Audit src/lib/, src/types/, src/prefabs/main.ts (#225 Phase 2)#241
Merged
Conversation
Phase 2 for #225. Eighteen files, 121 flagged comments. Declaration-level rationale moved to JSDoc across the types module (all Prefab / HighlightedPrefab / mesh / district / glyph shapes), data lookup libraries (prefab-tooltip, prefab-hit-index, labels, footprint-color, utils, prefabs, prefab-added-versions), and UI helpers (url-state, prefab-link-tooltip, prefabs-filter-controls, glyph-sprite). In-body rationale kept as single-clause WHY: / INVARIANT: markers: - prefab-tooltip: popover top-layer contract, global Shift tracking. - prefab-hit-index: rotation-swap of world-aligned width and depth. - footprint-color: lattice-origin derivation from any tile. - utils: content-encoding length-check condition. - prefabs: malformed-position fail-fast. - storage: pipeTo close-once INVARIANT; NotFoundError idempotency. - throttled-invoker: pending-flag coalescing INVARIANT. - url-state: input+change dual dispatch rationales. - dom-utils, glyph-sprite: rotation-swap and scale rationale. - label-handler: synchronous initial-language commit. - oneshot-worker: preventDefault suppresses double-logging. Deleted where variable names or idiom already convey the intent: - dom-utils "in-game scale" / "center offset" section labels. - prefabs/main.ts "// init" above the IIFE. Style: single-clause sentences using because / so / since for causation, no ; / — / colon-elaboration per the #235-#236 memo. EXCLUDED_PATHS shrinks from 48 to 30.
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 all of
src/lib/,src/prefabs/main.ts, andsrc/types/7dtdmap.tsin one sweep (18 files, 121 flagged comments). Drops the corresponding 18 entries fromEXCLUDED_PATHS.Highlights
Declaration-level rationale moved to JSDoc, in-body rationale kept as single-clause markers, code-restating comments deleted.
Types & data shape (
src/types/7dtdmap.ts, 18 comments)All interface / field docs moved to JSDoc so they show on hover for consumers.
Data / lookup libraries
prefab-tooltip.ts(19) — CURSOR_OFFSET, TooltipHint, PrefabTooltip, PrefabTooltipController preambles → JSDoc; three in-bodyWHY:(popover top-layer contract, global Shift tracking, anchor evaluation ordering).prefab-hit-index.ts(12) — EXCLUDED_NAME_FRAGMENTS and PrefabHitIndex preambles → JSDoc; rotation-swap rationale →WHY:.labels.ts(10) — PRIMARY_SUBTAG_LANGUAGES and resolveChinese preambles → JSDoc.footprint-color.ts(8) — TileIndex, buildTileIndex, footprintColorRgb preambles → JSDoc; lattice-origin derivation →WHY:.utils.ts(8) — fetchCompleteBlob, escapeHtml preambles → JSDoc; content-encoding length-check rationale →WHY:.prefabs.ts(5) — loadPrefabsXml (DOMParser rationale) and decorationToPrefab preambles → JSDoc; malformed-position fail-fast →WHY:.prefab-added-versions.ts(5) — Version-comparison preamble → JSDoc onlatestAddedVersion.storage.ts(4) — pipeTo close-once contract →INVARIANT:; NotFoundError idempotency →WHY:.throttled-invoker.ts(2) — Pending-flag coalescing →INVARIANT:.UI helpers
url-state.ts(7) — UrlState preamble → JSDoc; two-event dispatch rationales →WHY:.dom-utils.ts(4) — Rotation-swap →WHY:; three in-body section labels deleted.prefab-link-tooltip.ts(4) — CURSOR_OFFSET and installPrefabLinkTooltip preambles → JSDoc.prefabs-filter-controls.ts(4) — bindPrefabsFilterControls preamble → JSDoc.glyph-sprite.ts(4) — buildGlyphSprite preamble → JSDoc; scale rationale →WHY:.label-handler.ts(4) — Synchronous initial-language commit →WHY:.oneshot-worker.ts(2) — preventDefault rationale →WHY:.prefabs/main.ts(1) —// initdeleted (self-invoking async IIFE is idiomatic).Style
All new markers are single-clause sentences using
because/so/sincefor causation. No;,—, or elaboration parentheticals in prose. JSDoc bodies use period-split for genuinely separate ideas.Test plan
deno task ci:lintpassesdeno task ci:fmt-checkpassesdeno task ci:type-checkpassesdeno task test— 41 tests / 241 steps passProgress
EXCLUDED_PATHS: 48 → 30. All ofsrc/lib/,src/types/, andsrc/prefabs/audited.