Skip to content

0.10.0.md

Latest commit

 

History

History
63 lines (39 loc) · 5.85 KB

0.10.0.md

File metadata and controls

63 lines (39 loc) · 5.85 KB
Raw

[0.10.0] — 2026-04-25 · Lite / Detailed MD modes

Headline feature: every generated Markdown doc now has a Lite version (paste-into-wiki summary for stakeholders) alongside the existing Detailed version (full reference for engineers). The Docs tab gains a Lite/Detailed toggle next to the Rendered/Raw one. 262 tests, bundle 296 KB.

Added

  • Lite / Detailed mode infrastructure. Every generator function (generateMarkdown, generateMeasuresMd, generateSourcesMd, etc.) accepts a third arg mode: "lite" | "detailed" defaulting to "detailed" for back-compat. The CLI bakes both modes into the dashboard payload; the dashboard's Docs-tab toolbar gains a Lite | Detailed button group that flips between them on the fly. Filenames in the Download button gain a -lite infix in Lite mode so users archiving both don't overwrite each other.

  • Per-doc Lite shapes:

    • Model.md — drops Conventions / Terminology, §3.2 Parameters, §4 Data Dictionary Summary, Appendix A. ~150 lines.
    • Data Dictionary.md — skipped entirely. Stakeholders don't column-shop.
    • Sources.md — keeps connection buckets + Physical-source index. Drops Native queries / M-step breakdown / Raw M expressions. ~170 lines (was ~600).
    • Measures.md — replaces per-measure detail with a flat A–Z summary table (Name · Table · Status · Format · Description). 80 lines (was 1,800).
    • Pages.md — keeps the visible-page index, drops per-page binding tables + hidden-page appendix. 32 lines (was 260).
    • Functions / Calc Groups — skipped when empty in both modes (F5).
    • Improvements.md — identical in both modes; the audit is already paced for stakeholder reading.
    • Index.md — skipped entirely. Glossary is reference-territory; Cmd-F serves it better.

  • Lite mode totals on the H&S fixture: 47 KB across all docs vs 230 KB for Detailed. Lite is 21% the size of Detailed.

  • MdMode and ImprovementsMdMode exported types from md-generator.ts and improvements.ts for callers wiring the toggle.

  • Dashboard tab visibility. Tabs whose corresponding MD payload is empty in the current mode are hidden automatically. Switching modes refreshes visibility — Data Dictionary + Index disappear in Lite; Functions / Calc Groups disappear in either mode when their entity list is empty.

Changed (Detailed-mode refinements from /sc:analyze audit)

  • F5 — Empty docs no longer ship placeholders. Functions / Calc Groups generators now return empty when their underlying entity list is empty, rather than emitting an 11-line _This model defines no UDFs_ placeholder. Three placeholder docs vanishing from real outputs.

  • F7 — Measures.md no longer carries the front-matter External-proxy table. The same proxy info was duplicated inline (each proxy's A–Z entry has the EXTERNAL badge + cluster callout) — readers were scrolling past the same measure twice. Inline badge stays; the duplicate front-matter table is removed.

  • F8 — Model.md §4 Data Dictionary Summary trimmed. Was a 53-row table duplicating §2.2 (Tables by role, already shown above). Replaced with a 1-line pointer to the Data Dictionary Reference + a "Largest user tables" top-10 mini-list for navigation context.

  • F9 — Model.md §3.3 Per-table sources removed. Sources.md owns per-table source detail (with bucket grouping, the Physical-source index, and consumer counts — all richer than the flat table this section emitted). Replaced with a 1-line pointer.

  • F10 — Index.md letter sections collapse to <details>. Each letter heading stays as a markdown ## A (anchors still work) — the contents wrap in a closed <details> block. Glossary is reference-territory; readers Cmd-F or click the jump-bar, they don't browse top-to-bottom.

Changed

  • CI bundle-size cap bumped 300 KB → 400 KB. The bake-both approach doubles per-doc MD payload — worth it to land both modes without the architectural carve to lazy client-side generation. Current bundle ~296 KB; cap leaves ~30% headroom.

  • generateHTML signature gains an optional liteMarkdowns object as the 15th parameter. Existing 14-arg callers continue to work (lite payload defaults to {} → empty Lite globals → toggle gracefully falls back to Detailed).

  • __loadBrowserData markdown shape gains lite-mode siblings (mdLite, measuresMdLite, functionsMdLite, …). Older callers without these still load — fields default to "" and the Lite toggle just hides empty tabs.

Deferred

Two refinements from the audit deferred to a follow-up PR:

  • F6 — Source-alias pattern. In composite-model fixtures the same AS URL appears 60+ times across docs. A per-doc alias ([AS-1], [AS-2]) on first mention with subsequent references would dedupe materially. Out of scope here — would require careful regex work in §3.2 Parameters and §2 connection buckets.
  • F13 — Strategic cross-links across 5 docs. A shared xref(kind, name) helper that emits canonical anchors for any entity in any doc. Substantial design (5 docs × 2-3 link points each); deferred to keep this PR focused on landing the mode infrastructure cleanly.

Verification

  • npm run typecheck — clean
  • npm test — 262/262 green (+13 new mode-specific tests)
  • npm run build:browser — bundle 296 KB (under 400 KB cap, was 289 KB on 0.9.x)
  • Smoke H&S fixture — Lite 47 KB / Detailed 230 KB; Functions + Calc Groups skip cleanly when empty; erDiagram + Mermaid lineage blocks unchanged from PR #83's ADO-friendly form

Migration

  • CLI users see no change (Detailed is the default and matches current behaviour exactly).
  • Dashboard users see a new [Lite] [Detailed] button group in the Docs tab toolbar — Detailed is selected by default.
  • Anyone paste-publishing to ADO Wiki now has a sensible "stakeholder-friendly" alternative for the read-once-and-share pages.