Audit tools/lib/xmls/ comments (#225 Phase 2) - #235
Merged
Conversation
Phase 2 for #225. Five XML-parser modules, 29 flagged comments. Section-divider block comments deleted (/* Raw XML types */, /* Public types */, /* Public API */) across loot-xml.ts, materials-xml.ts, and blocks-xml.ts — organizational cruft that editor outlines already provide. Declaration-level rationale converted to JSDoc: - rwgmixer-xml.ts: District.previewColor range and parseRwgmixerXml input shape / null-color behavior. En-dash range 0-1 replaced with [0, 1] to satisfy the no-dash rule. - prefab-xml.ts: @libs/xml single-child collapse quirk on the raw property field; RawPrefabPropertyClass recursion; ParsedPrefabProperty union; isPrefabPropertyValue narrowing purpose. - blocks-xml.ts: RawNestedProperty recursion; Blocks.#downgradeRelations inverse-index semantics with a concrete example. Fail-fast throw in toEntry kept as WHY: linking to the AGENTS.md tools/ fail-fast rule. EXCLUDED_PATHS shrinks from 76 to 71.
WHY: markers should not repeat the project-level rules that live in AGENTS.md; the reader can consult the rule directly. The single-clause "silently dropping unknown shapes would hide schema drift in the source XML" already carries the load-bearing rationale. Also removes the semicolon-elaboration pattern flagged as an anti-pattern.
The throw is the standard exhaustiveness default for a variant sum, and the AGENTS.md fail-fast rule applies to every throw in tools/ the same way. The WHY: was restating a project-level convention at one particular site, which invites the same restatement everywhere else without adding local information.
This was referenced Jul 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 2 for #225: audit
tools/lib/xmls/(5 files, 29 flagged comments). Drop all five fromEXCLUDED_PATHS.Per-comment disposition
Section dividers deleted (9 comments)
/* Raw XML types (encapsulated) */,/* Public types */,/* Public API */markers inloot-xml.ts,materials-xml.ts,blocks-xml.ts— organizational cruft that modern editors (fold, outline view) already provide.Converted to JSDoc (declaration-level)
rwgmixer-xml.tsDistrict.previewColorfield[0, 1]float range; en-dash range notation replaced with[0, 1]interval to satisfy the no-dash rulerwgmixer-xml.tsparseRwgmixerXmlfunctionprefab-xml.tsRawPrefabXml.propertyfield@libs/xmlsingle-child collapse quirkprefab-xml.tsRawPrefabPropertyClassinterfaceprefab-xml.tsParsedPrefabPropertytypeprefab-xml.tsisPrefabPropertyValuefunctionblocks-xml.tsRawNestedPropertyinterfaceblocks-xml.tsBlocks.#downgradeRelationsfieldKept as marker
prefab-xml.tsfail-fast throw (intoEntry)WHY:— silent drops would hide schema drift; AGENTS.md requires tools/ to throwTest plan
deno task ci:lintpassesdeno task ci:fmt-checkpassesdeno task ci:type-checkpassesdeno task test— 41 tests / 241 steps passProgress
EXCLUDED_PATHS: 76 → 71.