@krapwoo/ds-viewer 0.14.2 → 0.15.0

package/dist/cli/doctor.js

@@ -7,7 +7,8 @@ import { importedNames, readStaticPages } from "./staticPage.js";
 import { resolveGlob } from "./glob.js";
 import { sync } from "./sync.js";
 import { gridColumnLimit } from "../native/catalog/comparison.js";
-import { validateComposedOf, validateFamily } from "../native/catalog/pageApi.js";
+import { resolveExternalPart, validateComposedOf, validateFamily, validateGroupIssues, } from "../native/catalog/pageApi.js";
+import { canonicalTokenTitle, findDuplicateIds, isTokenKind } from "../native/catalog/tokenDefinition.js";
 function issue(fields) {
     return fields;
 }
@@ -156,24 +157,22 @@ function checkFamilyMembers(pages, components) {
     }
     return issues;
 }
-/** Plan V3's `family-invalid`: reuses `native/catalog/pageApi.ts`'s own `validateFamily` —
- *  the exact same rule `pageApi.ts`'s `buildCatalogSections` runs at runtime — against every
- *  checkable family page, with the same catalog-wide "every other page/member id" contract that
- *  function already takes. N3: `StaticPage.sections` already carries each section's real
- *  `label`/`kind`, so `validateFamily`'s messages name the real section (never an empty label),
- *  and its N6 list-section rule can tell a `list` section from a `blocks` one. */
-function checkFamilyValidity(pages) {
-    // V2c item 6: `members.length > 0`, the same predicate the runtime uses — an empty array is not
-    // a family page.
-    const familyPages = pages.filter((p) => p.members && p.members.length > 0 && p.checkable);
-    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
-    const familyIdsByPageId = new Map();
+/** #64 B5: every id/alias one page itself registers — a family's member ids/aliases plus its own
+ *  page-level `aliases` (the existing universe `checkFamilyValidity` already built inline), now
+ *  also including a tokenDefinition page's own `aliases` and each of its sections' own `aliases`
+ *  (extending routing/uniqueness to tokenDefinition pages — #64 B5's own requirement). Keyed by
+ *  each page's own resolved id; a page contributing nothing is simply absent, same as before. */
+function idsRegisteredByPage(pages) {
+    const byId = new Map();
     // I-B (independent review, confirmation pass): built from every page with members, not only
     // checkable ones — the same precedent `checkMemberComposedOf` above already follows for
     // `knownNames` (no `checkable` filter). A non-checkable family page still contributes a working
     // link at runtime (`pageApi.ts`'s `otherMemberIds` has no `checkable` concept either), so
     // excluding it here turned a valid `relatedPages` entry into a false CI-failing error.
-    for (const page of pages.filter((p) => p.members && p.members.length > 0)) {
+    for (const page of pages) {
+        const hasMembers = Boolean(page.members && page.members.length > 0);
+        if (!hasMembers && !page.tokenDefinition)
+            continue;
         const id = resolvePageId(page, page.file);
         const ids = new Set();
         for (const member of page.members ?? []) {
@@ -183,9 +182,87 @@ function checkFamilyValidity(pages) {
         }
         for (const alias of page.aliases ?? [])
             ids.add(alias);
-        familyIdsByPageId.set(id, ids);
+        for (const section of page.tokenDefinition?.sections ?? [])
+            for (const alias of section.aliases ?? [])
+                ids.add(alias);
+        byId.set(id, ids);
+    }
+    return byId;
+}
+/** Review F9: a page authored with neither `whole` nor `sections` — by presence (`hasWhole` /
+ *  `hasSections`), never by value, so a family whose `whole`/`sections` isn't a literal (and is
+ *  therefore left unset, non-checkable) is never mistaken for a group page. A hand-built
+ *  `StaticPage` without the flags falls back to whether the value is set. */
+function isGroupShape(p) {
+    return !(p.hasWhole ?? p.whole !== undefined) && !(p.hasSections ?? p.sections !== undefined);
+}
+/** #63 A5/A6: the static-side equivalent of `buildCatalogSections`'s own external-part pre-pass —
+ *  built from `StaticPage[]` instead of the runtime catalog, but the same `resolveExternalPart`
+ *  rule (imported, never reimplemented). Returns, per family page id, the external part ids it
+ *  resolved (fed into `validateFamily`'s own `externalPartIds` exemption below) and every
+ *  resolution problem as its own `family-external-part` finding. */
+function collectExternalParts(pages) {
+    const memberLocations = new Map();
+    for (const p of pages) {
+        const pHasMembers = Boolean(p.members && p.members.length > 0);
+        const pIsGroup = pHasMembers && isGroupShape(p);
+        for (const member of p.members ?? []) {
+            memberLocations.set(member.id, [...(memberLocations.get(member.id) ?? []), { pageId: resolvePageId(p, p.file), isGroupPage: pIsGroup, parent: member.parent }]);
+        }
     }
+    const externalPartIdsByPage = new Map();
     const issues = [];
+    for (const page of pages) {
+        const hasMembers = Boolean(page.members && page.members.length > 0);
+        if (!hasMembers || page.whole === undefined || page.sections === undefined || !page.checkable)
+            continue; // not a valid family.
+        const id = resolvePageId(page, page.file);
+        const byIdThisPage = new Set(page.members.map((m) => m.id));
+        const external = new Set();
+        for (const section of page.sections) {
+            if (!section.inWhole)
+                continue;
+            for (const memberId of section.members) {
+                if (byIdThisPage.has(memberId) || external.has(memberId))
+                    continue;
+                const owners = memberLocations.get(memberId);
+                if (!owners)
+                    continue; // genuinely unknown — `family-invalid`'s own "not a member" already covers it.
+                const resolution = resolveExternalPart(memberId, owners, page.whole);
+                if ('issue' in resolution) {
+                    issues.push(issue({
+                        id: 'family-external-part', severity: 'error', ...pageRef(page),
+                        message: `Family "${id}": ${resolution.issue}`,
+                        fix: 'Make the id resolve to exactly one group page\'s member, with that member\'s own "parent" equal to this family\'s "whole".',
+                    }));
+                }
+                else {
+                    external.add(memberId);
+                }
+            }
+        }
+        if (external.size > 0)
+            externalPartIdsByPage.set(id, external);
+    }
+    return { externalPartIdsByPage, issues };
+}
+/** Plan V3's `family-invalid`: reuses `native/catalog/pageApi.ts`'s own `validateFamily` —
+ *  the exact same rule `pageApi.ts`'s `buildCatalogSections` runs at runtime — against every
+ *  checkable family page, with the same catalog-wide "every other page/member id" contract that
+ *  function already takes. N3: `StaticPage.sections` already carries each section's real
+ *  `label`/`kind`, so `validateFamily`'s messages name the real section (never an empty label),
+ *  and its N6 list-section rule can tell a `list` section from a `blocks` one. #63 A5: a page with
+ *  neither `whole` nor `sections` (a group) is still included in `familyPages` below, but
+ *  `validateFamily` is now a no-op for it (see its own doc comment) — `checkGroupValidity` is its
+ *  real validator. */
+function checkFamilyValidity(pages) {
+    // V2c item 6: `members.length > 0`, the same predicate the runtime uses — an empty array is not
+    // a family page.
+    const familyPages = pages.filter((p) => p.members && p.members.length > 0 && p.checkable);
+    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
+    const familyIdsByPageId = idsRegisteredByPage(pages);
+    const { externalPartIdsByPage, issues: externalIssues } = collectExternalParts(pages);
+    const issues = [...externalIssues];
     for (const page of familyPages) {
         const id = resolvePageId(page, page.file);
         const otherPageIds = new Set([...allPageIds].filter((pageId) => pageId !== id));
@@ -211,12 +288,56 @@ function checkFamilyValidity(pages) {
             // not only ever silently warned in a browser console (`npm run check:catalog`).
             relatedPages: page.relatedPages,
         };
-        for (const message of validateFamily(pageLike, otherPageIds, otherMemberIds)) {
+        const externalPartIds = externalPartIdsByPage.get(id) ?? new Set();
+        for (const message of validateFamily(pageLike, otherPageIds, otherMemberIds, externalPartIds)) {
             issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message, fix: 'Fix the family\'s members/whole/sections to satisfy the rule above.' }));
         }
     }
     return issues;
 }
+/** #63 A1/A3/A4/A6: the static-side equivalent of `buildCatalogSections`'s own `validateGroup`
+ *  call, against every checkable group page (`members` with no `whole`/`sections`). Reuses the
+ *  `family-invalid` rule id for every shape error (same class the family-shaped version already
+ *  reports under), and the new `group-anatomy-member` rule id only for an embedded anatomy
+ *  problem (A4) — per the controller's own decision. */
+function checkGroupValidity(pages) {
+    const groupPages = pages.filter((p) => p.members && p.members.length > 0 && isGroupShape(p) && p.checkable);
+    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
+    const familyIdsByPageId = idsRegisteredByPage(pages);
+    const issues = [];
+    for (const page of groupPages) {
+        const id = resolvePageId(page, page.file);
+        const otherPageIds = new Set([...allPageIds].filter((pageId) => pageId !== id));
+        const otherMemberIds = new Set();
+        for (const [pageId, ids] of familyIdsByPageId)
+            if (pageId !== id)
+                for (const memberId of ids)
+                    otherMemberIds.add(memberId);
+        const pageLike = {
+            id,
+            members: (page.members ?? []).map((m) => ({
+                id: m.id,
+                parent: m.parent,
+                aliases: m.aliases,
+                anatomy: m.anatomy ? { groups: [{ label: '', items: m.anatomy.memberIds.map((memberId) => ({ member: memberId, description: '' })) }] } : undefined,
+            })),
+            aliases: page.aliases,
+            anatomy: page.hasAnatomy ? {} : undefined,
+            relatedPages: page.relatedPages,
+        };
+        for (const { rule, message } of validateGroupIssues(pageLike, otherPageIds, otherMemberIds)) {
+            const isAnatomyRule = rule === 'group-anatomy-member';
+            issues.push(issue({
+                id: rule,
+                severity: 'error', ...pageRef(page), message,
+                fix: isAnatomyRule
+                    ? 'Name only this member\'s own descendants on this page, and set "anatomy" only on a top-level member.'
+                    : 'Fix the group\'s members/aliases/anatomy to satisfy the rule above.',
+            }));
+        }
+    }
+    return issues;
+}
 /** Deprecation (`relatedPages`): a family page still using one or more non-`inWhole` sections to
  *  document a merely-related component inline, instead of giving it its own page and naming it in
  *  the page's `relatedPages` list. One finding per page (never per section), naming every member
@@ -719,6 +840,162 @@ function checkComponentPages(pages, components) {
     }
     return issues;
 }
+/** #61: errors for an opted-in `tokenDefinition` that is provably malformed, conflicts with an
+ *  explicit legacy `render`/`tokenGallery`/`tokenSections`/`members` recipe on the same page, has a
+ *  duplicate section id or a duplicate entry id within one section, or has an explicit page `title`
+ *  that conflicts with its kind's canonical title (design R4's own severity list). A `tokenDefinition`
+ *  that isn't itself statically readable (non-literal `kind`/`sections`) already made the whole page
+ *  `checkable: false` in `cli/staticPage.ts` — `checkNotCheckable` reports that case as the established
+ *  `page-not-checkable` warning; this rule only ever runs against a definition that WAS readable. */
+/** Opted-in token pages whose sections take their entries from runtime imports — the intended
+ *  authoring path, since values come from the app's own token modules. Doctor never executes them,
+ *  so those sections are listed as not statically validated. Informational only, like the
+ *  "unbound examples" count: it never becomes an issue, never changes the exit code, and is not
+ *  promoted by `doctor.strict`. `undefined` when there are none, so legacy output is unchanged. */
+function runtimeOnlyTokenSections(pages) {
+    // #64 B1: a section counts as runtime-only when its own entries are opaque, OR its own `groups`
+    // couldn't be read, OR any one group's own entries are opaque — groups are read the same
+    // lenient way as a section's own entries (`cli/tokenDefinition.ts`'s own `readStaticTokenDefinition`).
+    const isOpaque = (section) => section.entriesOpaque || Boolean(section.groupsOpaque) || (section.groups ?? []).some((g) => g.entriesOpaque);
+    const found = pages.flatMap((page) => {
+        const sections = page.tokenDefinition?.sections.filter(isOpaque).map((section) => section.id) ?? [];
+        return sections.length > 0 ? [{ page: resolvePageId(page, page.file), sections }] : [];
+    });
+    return found.length > 0 ? found : undefined;
+}
+function checkTokenDefinition(pages) {
+    const issues = [];
+    for (const page of pages) {
+        if (!page.hasTokenDefinition || !page.tokenDefinition)
+            continue;
+        const ref = pageRef(page);
+        const def = page.tokenDefinition;
+        if (!isTokenKind(def.kind)) {
+            issues.push(issue({
+                id: 'token-definition-invalid-kind', severity: 'error', ...ref,
+                message: `tokenDefinition has an unknown kind "${def.kind}".`,
+                fix: 'Use one of: colors, typography, spacing, radius, dimensions, shadows, opacity, motion.',
+            }));
+            continue; // The canonical-title check below needs a valid kind to compare against.
+        }
+        if (page.hasRender) {
+            issues.push(issue({ id: 'token-definition-conflict', severity: 'error', ...ref, message: 'tokenDefinition conflicts with this page\'s own "render".', fix: 'Remove one of them.' }));
+        }
+        if (page.hasExplicitTokenGallery) {
+            issues.push(issue({ id: 'token-definition-conflict', severity: 'error', ...ref, message: 'tokenDefinition conflicts with this page\'s own "tokenGallery".', fix: 'Remove one of them.' }));
+        }
+        if (page.hasExplicitTokenSections) {
+            issues.push(issue({ id: 'token-definition-conflict', severity: 'error', ...ref, message: 'tokenDefinition conflicts with this page\'s own "tokenSections".', fix: 'Remove one of them.' }));
+        }
+        if (page.hasMembers) {
+            issues.push(issue({ id: 'token-definition-conflict', severity: 'error', ...ref, message: 'tokenDefinition conflicts with this page\'s own "members" (a family page).', fix: 'Remove one of them.' }));
+        }
+        if (page.title !== undefined && page.title !== canonicalTokenTitle(def.kind)) {
+            issues.push(issue({
+                id: 'token-definition-title-conflict', severity: 'error', ...ref,
+                message: `tokenDefinition: title "${page.title}" conflicts with kind "${def.kind}" (expected "${canonicalTokenTitle(def.kind)}").`,
+                fix: 'Omit "title" to use the kind\'s canonical title automatically, or change it to match.',
+            }));
+        }
+        for (const id of findDuplicateIds(def.sections.map((s) => s.id))) {
+            issues.push(issue({ id: 'token-definition-duplicate-id', severity: 'error', ...ref, message: `tokenDefinition has more than one section with id "${id}".`, fix: 'Give each section its own id.' }));
+        }
+        for (const section of def.sections) {
+            for (const id of findDuplicateIds(section.entryIds)) {
+                issues.push(issue({
+                    id: 'token-definition-duplicate-id', severity: 'error', ...ref,
+                    message: `tokenDefinition section "${section.id}" has more than one entry with id "${id}".`,
+                    fix: 'Give each entry within this section its own id (the same id may still be reused in a different section).',
+                }));
+            }
+            // #64 B1: a section's own groups — group ids unique within the section, entry ids unique
+            // within their own group (the same scoping `native/catalog/tokenDefinition.ts`'s own
+            // `validateTokenDefinition` enforces at runtime).
+            for (const id of findDuplicateIds((section.groups ?? []).map((g) => g.id))) {
+                issues.push(issue({
+                    id: 'token-definition-duplicate-id', severity: 'error', ...ref,
+                    message: `tokenDefinition section "${section.id}" has more than one group with id "${id}".`,
+                    fix: 'Give each group within this section its own id.',
+                }));
+            }
+            for (const group of section.groups ?? []) {
+                for (const id of findDuplicateIds(group.entryIds)) {
+                    issues.push(issue({
+                        id: 'token-definition-duplicate-id', severity: 'error', ...ref,
+                        message: `tokenDefinition section "${section.id}" group "${group.id}" has more than one entry with id "${id}".`,
+                        fix: 'Give each entry within this group its own id (the same id may still be reused in a different group or in the section\'s own entries).',
+                    }));
+                }
+            }
+        }
+    }
+    return issues;
+}
+/** #64 B4: a literal `tokenDefinition.kind` shared by two or more pages — one issue per page in
+ *  the group (every one of them is reported, each naming the other page(s)). A page with no
+ *  `tokenDefinition` at all is never involved. */
+function checkTokenDefinitionDuplicateKind(pages) {
+    const byKind = new Map();
+    for (const page of pages) {
+        if (!page.tokenDefinition)
+            continue;
+        const kind = page.tokenDefinition.kind;
+        byKind.set(kind, [...(byKind.get(kind) ?? []), page]);
+    }
+    const issues = [];
+    for (const [kind, group] of byKind) {
+        if (group.length < 2)
+            continue;
+        for (const page of group) {
+            const others = group.filter((p) => p !== page).map((p) => resolvePageId(p, p.file)).join(', ');
+            issues.push(issue({
+                id: 'token-definition-duplicate-kind', severity: 'error', ...pageRef(page),
+                message: `tokenDefinition kind "${kind}" is also used by ${others}.`,
+                fix: 'Give one of these pages its own kind, or merge them into one page.',
+            }));
+        }
+    }
+    return issues;
+}
+/** #64 B5: a tokenDefinition page's own page-level `aliases`, and each of its sections' own
+ *  `aliases`, join the exact same catalog-wide "one owner" pool `family-invalid` already checks
+ *  family ids/aliases against (`idsRegisteredByPage`) — reusing that rule id rather than adding a
+ *  second alias-collision rule. */
+function checkTokenDefinitionAliases(pages) {
+    const allPageIds = new Set(pages.map((p) => resolvePageId(p, p.file)));
+    const idsByPage = idsRegisteredByPage(pages);
+    const issues = [];
+    for (const page of pages) {
+        if (!page.tokenDefinition)
+            continue;
+        const id = resolvePageId(page, page.file);
+        const otherPageIds = new Set([...allPageIds].filter((pid) => pid !== id));
+        const otherIds = new Set();
+        for (const [pid, ids] of idsByPage)
+            if (pid !== id)
+                for (const x of ids)
+                    otherIds.add(x);
+        const seen = new Set();
+        const checkAlias = (alias) => {
+            if (seen.has(alias)) {
+                issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message: `Page "${id}": id "${alias}" is used more than once on this page.`, fix: 'Give each alias its own name.' }));
+            }
+            seen.add(alias);
+            if (otherPageIds.has(alias)) {
+                issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message: `Page "${id}": id "${alias}" collides with another page's id.`, fix: 'Choose a different alias.' }));
+            }
+            if (otherIds.has(alias)) {
+                issues.push(issue({ id: 'family-invalid', severity: 'error', ...pageRef(page), message: `Page "${id}": id "${alias}" collides with another member or alias elsewhere in the catalog.`, fix: 'Choose a different alias.' }));
+            }
+        };
+        for (const alias of page.aliases ?? [])
+            checkAlias(alias);
+        for (const section of page.tokenDefinition.sections)
+            for (const alias of section.aliases ?? [])
+                checkAlias(alias);
+    }
+    return issues;
+}
 /** Every page-scoped issue, from every rule above. */
 export function collectIssues(pages, components) {
     return [
@@ -736,8 +1013,12 @@ export function collectIssues(pages, components) {
         ...checkPreviewOnlyPages(pages),
         ...checkFamilyMembers(pages, components),
         ...checkFamilyValidity(pages),
+        ...checkGroupValidity(pages),
         ...checkMemberComposedOf(pages, components),
         ...checkDeprecatedRelatedSections(pages),
+        ...checkTokenDefinition(pages),
+        ...checkTokenDefinitionDuplicateKind(pages),
+        ...checkTokenDefinitionAliases(pages),
     ];
 }
 /** Issues that aren't tied to one page: `sync`'s own "Could not read" warnings, and a configured
@@ -893,6 +1174,9 @@ export function runDoctor(config) {
         withExamples: countWithExamples(pages, components),
         unboundExamples: countUnboundExamples(pages),
     };
+    const runtimeOnly = runtimeOnlyTokenSections(pages);
+    if (runtimeOnly)
+        summary.runtimeOnlyTokenSections = runtimeOnly;
     const pageFileById = new Map(pages.map((p) => [resolvePageId(p, p.file), path.relative(config.projectRoot, p.file)]));
     return { version: 1, summary, update: null, issues, exitCode: summary.errors > 0 ? 1 : 0, pageFiles: pageFileById };
 }
@@ -930,7 +1214,12 @@ export function formatHuman(result) {
             renderIssue(issue);
         lines.push('');
     }
-    const { errors, warnings, components, withExamples, unboundExamples } = result.summary;
+    const { errors, warnings, components, withExamples, unboundExamples, runtimeOnlyTokenSections: runtimeOnly } = result.summary;
+    if (runtimeOnly && runtimeOnly.length > 0) {
+        const count = runtimeOnly.reduce((sum, entry) => sum + entry.sections.length, 0);
+        const where = runtimeOnly.map((entry) => `${entry.page} (${entry.sections.join(', ')})`).join('; ');
+        lines.push(`${count} token section${count === 1 ? '' : 's'} with runtime-only entries (not statically validated): ${where}.`, '');
+    }
     lines.push(`${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} — ` +
         `${components} components (${withExamples} with examples), ${unboundExamples} unbound examples.`);
     return lines.join('\n');

package/dist/cli/explain.js

@@ -5,6 +5,7 @@ import { resolveGlob } from "./glob.js";
 import { axisItems, blockMinWidth, choosePlacement, gridColumnLimit, listGeometry, presentationBlocks, MATRIX_LAYOUT, } from "../native/catalog/comparison.js";
 import { CATALOG_LAYOUT } from "../native/catalog/tokens.js";
 import { sectionColumns } from "../native/catalog/tokenLayout.js";
+import { numberForGroupMember } from "../native/catalog/pageApi.js";
 function placeholderItem(item) {
     return {
         key: item.key, name: item.name, node: null, group: item.group,
@@ -152,6 +153,20 @@ export function explainPage(config, pageId, options = {}) {
     // to never drift from what the viewer actually renders.
     if (!page.checkable)
         return { pageId, notCheckable: true, blocks: [] };
+    // #63 A10: a group page (`members` with no `whole`/`sections`) — its real content lives entirely
+    // on its members, which `toSectionDef`/`presentationBlocks` below never read, so it gets its own
+    // outline instead of an (otherwise empty) block list.
+    if (page.members !== undefined && page.members.length > 0 && page.whole === undefined && page.sections === undefined) {
+        const members = page.members;
+        const byId = new Set(members.map((m) => m.id));
+        const topLevelMembers = members.filter((m) => m.parent === undefined || !byId.has(m.parent));
+        const topLevel = topLevelMembers.map((m) => ({
+            id: m.id,
+            qualifier: m.component ? m.component : 'documentation-only',
+            parts: [...numberForGroupMember(m.id, members).entries()].map(([id, entry]) => ({ number: entry.number, id })),
+        }));
+        return { pageId, blocks: [], group: { topLevel } };
+    }
     const def = toSectionDef(page);
     const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
     // Two blocks placed side by side get half the row each, which changes how many columns fit.
@@ -194,6 +209,17 @@ export function formatExplain(result) {
     if (result.notCheckable) {
         return `${result.pageId}\n\nPage not statically checkable — some of its layout data is not a literal doctor can read.`;
     }
+    // #63 A10: a group page prints its own outline — title, each top-level member with its
+    // qualifier, nested parts with numbers — instead of the block-based report below.
+    if (result.group) {
+        const lines = [result.pageId, ''];
+        for (const top of result.group.topLevel) {
+            lines.push(`${top.id} (${top.qualifier})`);
+            for (const part of top.parts)
+                lines.push(`  ${part.number}. ${part.id}`);
+        }
+        return lines.join('\n').replace(/\n+$/, '');
+    }
     const lines = [result.pageId, ''];
     for (const block of result.blocks) {
         lines.push(block.title);

package/dist/cli/staticPage.js

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import { readFileSync } from 'node:fs';
+import { readStaticTokenDefinition } from "./tokenDefinition.js";
 const TRANSPILE_OPTIONS = {
     compilerOptions: { jsx: ts.JsxEmit.ReactJSX, module: ts.ModuleKind.ESNext, target: ts.ScriptTarget.ES2022 },
     reportDiagnostics: true,
@@ -58,21 +59,26 @@ function readStaticPage(file) {
         return { file, checkable: false, viewerImports };
     const page = { file, checkable: true, viewerImports };
     const idProp = findProp(pageObject, 'id');
+    const titleProp = findProp(pageObject, 'title');
     const componentProp = findProp(pageObject, 'component');
     const groupProp = findProp(pageObject, 'group');
     const specimenSizeProp = findProp(pageObject, 'specimenSize');
     const tokenGalleryProp = findProp(pageObject, 'tokenGallery');
     if (idProp)
         page.id = stringLiteral(resolve(idProp.initializer, consts, new Set()));
+    if (titleProp)
+        page.title = stringLiteral(resolve(titleProp.initializer, consts, new Set()));
     if (componentProp)
         page.component = stringLiteral(resolve(componentProp.initializer, consts, new Set()));
     if (groupProp)
         page.group = stringLiteral(resolve(groupProp.initializer, consts, new Set()));
     if (specimenSizeProp)
         page.specimenSize = stringLiteral(resolve(specimenSizeProp.initializer, consts, new Set()));
+    page.hasExplicitTokenGallery = tokenGalleryProp !== undefined;
     if (tokenGalleryProp)
         page.tokenGallery = resolve(tokenGalleryProp.initializer, consts, new Set()).kind === ts.SyntaxKind.TrueKeyword;
     const tokenSectionsProp = findProp(pageObject, 'tokenSections');
+    page.hasExplicitTokenSections = tokenSectionsProp !== undefined;
     if (tokenSectionsProp) {
         const list = resolve(tokenSectionsProp.initializer, consts, new Set());
         const items = ts.isArrayLiteralExpression(list) ? list.elements.map((element) => resolve(element, consts, new Set())) : [list];
@@ -201,6 +207,7 @@ function readStaticPage(file) {
         }
     }
     const membersProp = findProp(pageObject, 'members');
+    page.hasMembers = membersProp !== undefined;
     if (membersProp) {
         const members = readFamilyMembers(membersProp.initializer, consts, gridNames, sourceFile);
         if (!members)
@@ -209,6 +216,7 @@ function readStaticPage(file) {
             page.members = members;
     }
     const wholeProp = findProp(pageObject, 'whole');
+    page.hasWhole = wholeProp !== undefined;
     if (wholeProp) {
         const whole = stringLiteral(resolve(wholeProp.initializer, consts, new Set()));
         if (whole === undefined)
@@ -217,6 +225,7 @@ function readStaticPage(file) {
             page.whole = whole;
     }
     const sectionsProp = findProp(pageObject, 'sections');
+    page.hasSections = sectionsProp !== undefined;
     if (sectionsProp) {
         const sectionsRead = readSections(sectionsProp.initializer, consts);
         if (!sectionsRead)
@@ -235,11 +244,43 @@ function readStaticPage(file) {
     const relatedPagesProp = findProp(pageObject, 'relatedPages');
     if (relatedPagesProp)
         page.relatedPages = readRelatedPages(relatedPagesProp.initializer, consts);
+    page.hasAnatomy = findProp(pageObject, 'anatomy') !== undefined;
+    const navigationProp = findProp(pageObject, 'navigation');
+    if (navigationProp) {
+        const resolved = resolve(navigationProp.initializer, consts, new Set());
+        if (ts.isStringLiteral(resolved) && (resolved.text === 'browse' || resolved.text === 'reference')) {
+            page.navigation = resolved.text;
+        }
+        else {
+            page.checkable = false;
+        }
+    }
+    const tokenDefinitionProp = findProp(pageObject, 'tokenDefinition');
+    page.hasTokenDefinition = tokenDefinitionProp !== undefined;
+    if (tokenDefinitionProp) {
+        const tokenDefinition = readStaticTokenDefinition(tokenDefinitionProp.initializer, consts);
+        if (!tokenDefinition)
+            page.checkable = false;
+        else {
+            page.tokenDefinition = tokenDefinition;
+            // #61 geometry parity (design R4): the same titles/wide flags `buildCatalogSections` derives
+            // at runtime from `tokenDefinition.sections` — only when no separate `tokenSections` already
+            // set them (an explicit conflict is reported on its own terms by `cli/doctor.ts`; whichever
+            // geometry already won here doesn't change that).
+            if (page.tokenSectionTitles === undefined) {
+                page.tokenSectionTitles = tokenDefinition.sections.map((section) => section.title);
+                page.tokenSectionWide = tokenDefinition.sections.map((section) => section.wide ?? false);
+                page.tokenGallery = true;
+            }
+        }
+    }
     return page;
 }
 /** A literal array of string literals (or same-file `const` references to one) — undefined for
- *  anything else, including an array containing even one non-literal element. */
-function readStringLiteralArray(node, consts) {
+ *  anything else, including an array containing even one non-literal element. Exported for
+ *  `cli/tokenDefinition.ts`'s own static read of a tokenDefinition section's `aliases` (#64 B5),
+ *  the same leniency every other string-literal-array field here already gets. */
+export function readStringLiteralArray(node, consts) {
     const resolved = resolve(node, consts, new Set());
     if (!ts.isArrayLiteralExpression(resolved))
         return undefined;
@@ -295,6 +336,8 @@ function readFamilyMembers(node, consts, gridNames, sourceFile) {
             if (!comparison)
                 return undefined;
         }
+        const anatomyProp = findProp(resolvedElement, 'anatomy');
+        const memberIds = anatomyProp ? readAnatomyMemberIds(anatomyProp.initializer, consts) : undefined;
         members.push({
             id,
             component,
@@ -304,6 +347,7 @@ function readFamilyMembers(node, consts, gridNames, sourceFile) {
             hasWhenToUse: findProp(resolvedElement, 'whenToUse') !== undefined,
             hasA11y: findProp(resolvedElement, 'a11y') !== undefined,
             hasExamples: Boolean(variants.items?.length) || Boolean(states.items?.length) || Boolean(comparison),
+            anatomy: memberIds ? { memberIds } : undefined,
         });
     }
     return members;
@@ -360,6 +404,46 @@ function readComposedOf(node, consts) {
     }
     return entries;
 }
+/** #63 A4/A10: `CatalogMember.anatomy`/`CatalogPageInput.anatomy`'s own `groups[].items[]`, read
+ *  down to just the literal `member` ids a `{ member: string }` item names — an `{ other: string }`
+ *  item is skipped (it never names a descendant), and `description`/`picture` are never read (design
+ *  parity with `readComposedOf`/`readRelatedPages`: `doctor`'s own rule never needs them). Undefined
+ *  — never a partial read — for anything that isn't itself a literal `{ groups: [...] }` object with
+ *  a literal `groups` array of literal `{ items: [...] }` objects whose own `items` array is itself
+ *  literal; an `other`/`description`-shaped item still reads fine even though its own `member` (if
+ *  any) is simply absent from the result. */
+function readAnatomyMemberIds(node, consts) {
+    const resolved = resolve(node, consts, new Set());
+    if (!ts.isObjectLiteralExpression(resolved))
+        return undefined;
+    const groupsProp = findProp(resolved, 'groups');
+    if (!groupsProp)
+        return undefined;
+    const groupsResolved = resolve(groupsProp.initializer, consts, new Set());
+    if (!ts.isArrayLiteralExpression(groupsResolved))
+        return undefined;
+    const memberIds = [];
+    for (const groupElement of groupsResolved.elements) {
+        const group = resolve(groupElement, consts, new Set());
+        if (!ts.isObjectLiteralExpression(group))
+            return undefined;
+        const itemsProp = findProp(group, 'items');
+        if (!itemsProp)
+            return undefined;
+        const itemsResolved = resolve(itemsProp.initializer, consts, new Set());
+        if (!ts.isArrayLiteralExpression(itemsResolved))
+            return undefined;
+        for (const itemElement of itemsResolved.elements) {
+            const item = resolve(itemElement, consts, new Set());
+            if (!ts.isObjectLiteralExpression(item))
+                return undefined;
+            const member = propertyStringLiteral(item, 'member', consts);
+            if (member !== undefined)
+                memberIds.push(member);
+        }
+    }
+    return memberIds;
+}
 /** A literal array of `RelatedPage`-shaped object literals, read down to just `page` (design
  *  parity with `readComposedOf`: `note` is authored prose `doctor` never needs). Undefined — not
  *  an empty array — for anything that isn't itself a literal array, or whose element isn't an
@@ -433,7 +517,7 @@ function topLevelConsts(sourceFile) {
  *  reference to its own initializer (same pattern as `cli/tokens.ts`'s `readExpression`) — returns
  *  the resolved expression node itself, not a value, so callers can pattern-match on its kind
  *  (array/object literal, call expression, …). `seen` guards a reference cycle. */
-function resolve(node, consts, seen) {
+export function resolve(node, consts, seen) {
     if (ts.isAsExpression(node) || ts.isParenthesizedExpression(node) || ts.isSatisfiesExpression(node)) {
         return resolve(node.expression, consts, seen);
     }
@@ -444,7 +528,7 @@ function resolve(node, consts, seen) {
     }
     return node;
 }
-function stringLiteral(node) {
+export function stringLiteral(node) {
     return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
 }
 /** `true`/`false` only from a known `true`/`false` literal; any other expression (a variable, a
@@ -464,11 +548,11 @@ function literalBooleanOrUnknown(node, consts) {
 function propertyName(name) {
     return ts.isIdentifier(name) || ts.isStringLiteral(name) ? name.text : name.getText();
 }
-function findProp(obj, name) {
+export function findProp(obj, name) {
     const prop = obj.properties.find((p) => ts.isPropertyAssignment(p) && propertyName(p.name) === name);
     return prop;
 }
-function propertyStringLiteral(obj, name, consts) {
+export function propertyStringLiteral(obj, name, consts) {
     const prop = findProp(obj, name);
     return prop ? stringLiteral(resolve(prop.initializer, consts, new Set())) : undefined;
 }