@krapwoo/ds-viewer 0.14.2 → 0.16.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
@@ -409,6 +530,146 @@ function checkMissingComposition(pages, components) {
     }
     return issues;
 }
+/** #66: a page is a family or group (it has `members`) — presence, so a page whose `members` could
+ *  not be read is still never treated as a plain page. */
+function hasMembers(page) {
+    return page.hasMembers === true || Boolean(page.members && page.members.length > 0);
+}
+/** #66: a token page — a `tokenDefinition`, a token gallery, or token sections, by presence. */
+function isTokenPage(page) {
+    return page.hasTokenDefinition === true || page.tokenDefinition !== undefined || page.tokenGallery === true
+        || page.hasExplicitTokenGallery === true || page.hasExplicitTokenSections === true || Boolean(page.tokenSectionTitles?.length);
+}
+/** #66: a non-blank `standalone` reason opts a page out of `part-own-page` and `nothing-to-show`. */
+function hasStandaloneReason(page) {
+    return page.standalone !== undefined && page.standalone.trim() !== '';
+}
+/** #66: the pages the two structure rules consider — readable, plain (no members, not a token page),
+ *  browse-listed, and without a recorded `standalone` reason. */
+function isStructureCandidate(page) {
+    return page.checkable && !hasMembers(page) && !isTokenPage(page) && page.navigation !== 'reference' && !hasStandaloneReason(page);
+}
+/** #66: the default `patternGroups` — the starter kit's own group for example screens. */
+export const DEFAULT_PATTERN_GROUPS = ['Patterns'];
+/** #66: whether a page sits in a pattern group (case-insensitive). A pattern page uses components; it
+ *  is never the whole they are parts of. */
+function isPatternPage(page, patternGroups) {
+    const group = page.group?.trim().toLowerCase();
+    return group !== undefined && patternGroups.some((name) => name.trim().toLowerCase() === group);
+}
+/** #66 `standalone-reason-empty`: a `standalone` that is blank or whitespace records no reason, so it
+ *  is not an opt-out. */
+function checkStandaloneReason(pages) {
+    return pages
+        .filter((page) => page.standalone !== undefined && page.standalone.trim() === '')
+        .map((page) => issue({
+        id: 'standalone-reason-empty', severity: 'warning', ...pageRef(page),
+        message: '`standalone` is empty, so it does not opt this page out of the structure checks.',
+        fix: "Write the reason, e.g. standalone: 'Not a part of GitFileCard; it draws its own counts.', or remove the field.",
+    }));
+}
+/** #66: every page that uses one of `names`, excluding `self`, deduplicated by host page (a page
+ *  counts once however many of its entries name the component). A built-in entry anywhere on the
+ *  host wins over a non-built-in one. */
+function usesOf(pages, self, names) {
+    const byHost = new Map();
+    for (const host of pages) {
+        if (host === self)
+            continue;
+        const entries = [...(host.composedOf ?? []), ...(host.members ?? []).flatMap((member) => member.composedOf ?? [])];
+        for (const entry of entries) {
+            if (!names.has(entry.component))
+                continue;
+            const known = byHost.get(host);
+            if (!known || (known.relationship !== 'built-in' && entry.relationship === 'built-in'))
+                byHost.set(host, { host, relationship: entry.relationship });
+        }
+    }
+    return [...byHost.values()];
+}
+/** #66: the names a page answers to — its id and its component. */
+function pageNames(page) {
+    return new Set([resolvePageId(page, page.file), ...(page.component ? [page.component] : [])]);
+}
+/** #66: whether some other page has composition this reader couldn't read — a page-level or
+ *  member-level `composedOf`, or a `members` list that wasn't read at all — so "only" and "nothing
+ *  uses it" can't be claimed outright. */
+function hasUnreadableComposition(pages, self) {
+    return pages.some((other) => other !== self && ((other.hasComposedOf === true && other.composedOf === undefined)
+        || (other.hasMembers === true && other.members === undefined)
+        || Boolean(other.members?.some((member) => member.hasComposedOf === true && member.composedOf === undefined))));
+}
+const pageList = (pages) => [...new Set(pages.map((p) => `\`${resolvePageId(p, p.file)}\``))].join(', ');
+/** #66 `part-own-page`: a candidate page whose component is declared `{ relationship: 'built-in' }`
+ *  (at page or member level) by exactly one other non-pattern page, which doesn't already list it
+ *  as a member (by member id, component or alias). Two or more users can't give it one owner, so it
+ *  is exempt; `slot`/`related`/missing/non-literal relationships never count. Reports; never infers
+ *  an owner or a relationship. */
+function checkPartOwnPage(pages, patternGroups) {
+    const issues = [];
+    for (const page of pages) {
+        if (!isStructureCandidate(page))
+            continue;
+        const names = pageNames(page);
+        const owners = usesOf(pages, page, names)
+            .filter((use) => use.relationship === 'built-in' && !isPatternPage(use.host, patternGroups))
+            .map((use) => use.host);
+        if (owners.length !== 1)
+            continue;
+        const owner = owners[0];
+        if (owner.members?.some((member) => names.has(member.id) || (member.component !== undefined && names.has(member.component))
+            || member.aliases?.some((alias) => names.has(alias))))
+            continue;
+        const ownerId = resolvePageId(owner, owner.file);
+        const id = resolvePageId(page, page.file);
+        const caveat = hasUnreadableComposition(pages, page) ? ' (Some pages\' `composedOf` could not be read, so another user may exist.)' : '';
+        issues.push(issue({
+            id: 'part-own-page', severity: 'warning', ...pageRef(page),
+            message: `\`${id}\` is a built-in part of \`${ownerId}\` only, but has its own page.${caveat}`,
+            fix: `List it as a part in ${ownerId}'s family (\`members\`/\`sections\`), or set \`standalone: '<reason>'\` if it is not really part of ${ownerId}.`,
+        }));
+    }
+    return issues;
+}
+/** #66 `nothing-to-show`: a candidate page with no variants, states, comparison or `render`. A page
+ *  this reader could not fully read is never a candidate (`checkable`), so "nothing" is only claimed
+ *  about a page that was read in full. `previewWidths` alone is not content: it only sizes `render`. */
+function checkNothingToShow(pages, patternGroups) {
+    const issues = [];
+    for (const page of pages) {
+        if (!isStructureCandidate(page))
+            continue;
+        const hasSpecimens = Boolean(page.comparison) || Boolean(page.variantsItems?.length) || Boolean(page.statesItems?.length) || page.hasRender === true;
+        if (hasSpecimens)
+            continue;
+        const id = resolvePageId(page, page.file);
+        const hosts = usesOf(pages, page, pageNames(page)).map((use) => use.host);
+        const users = hosts.filter((host) => !isPatternPage(host, patternGroups));
+        const patternUsers = hosts.filter((host) => isPatternPage(host, patternGroups));
+        const unreadable = hasUnreadableComposition(pages, page);
+        const base = { id: 'nothing-to-show', severity: 'warning', ...pageRef(page) };
+        const otherFix = "Add a specimen, set `navigation: 'reference'`, or `standalone: '<reason>'`.";
+        if (users.length > 0) {
+            const alsoPatterns = patternUsers.length > 0 ? ` Pattern pages also use it (${pageList(patternUsers)}).` : '';
+            issues.push(issue({ ...base,
+                message: `\`${id}\` shows no specimens. It is used by ${pageList(users)}.${alsoPatterns}`,
+                fix: "List it on that page as a documentation-only part, or set `navigation: 'reference'` to keep it reachable through Source reference search without a browse entry, or `standalone: '<reason>'`.",
+            }));
+        }
+        else if (patternUsers.length > 0) {
+            issues.push(issue({ ...base, message: `\`${id}\` shows no specimens. Only pattern pages use it (${pageList(patternUsers)}).`, fix: otherFix }));
+        }
+        else {
+            issues.push(issue({ ...base,
+                message: unreadable
+                    ? `\`${id}\` shows no specimens, and no page whose \`composedOf\` doctor could read uses it.`
+                    : `\`${id}\` shows no specimens and no other page uses it.`,
+                fix: otherFix,
+            }));
+        }
+    }
+    return issues;
+}
 /** The viewer exports that frame an example as a phone (or another bounded document), so an
  *  overlay that portals to the document body opens inside it instead of over the catalog. */
 const DEVICE_FRAME_EXPORTS = ['PhoneFrame', 'OverlayDemo', 'PhoneScreen', 'BoundedOverlayViewport'];
@@ -719,8 +980,165 @@ 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) {
+export function collectIssues(pages, components, options = {}) {
+    const patternGroups = options.patternGroups ?? DEFAULT_PATTERN_GROUPS;
     return [
         ...checkParseErrors(pages),
         ...checkNotCheckable(pages),
@@ -732,12 +1150,19 @@ export function collectIssues(pages, components) {
         ...checkDegenerateGridAxis(pages),
         ...checkComponentPages(pages, components),
         ...checkMissingComposition(pages, components),
+        ...checkStandaloneReason(pages),
+        ...checkPartOwnPage(pages, patternGroups),
+        ...checkNothingToShow(pages, patternGroups),
         ...checkMissingWorkingPreview(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
@@ -874,7 +1299,7 @@ export function runDoctor(config) {
         ? { '*': [path.join(config.projectRoot, 'node_modules', '@types', '*'), path.join(config.projectRoot, 'node_modules', '*')] }
         : undefined;
     let issues = [
-        ...collectIssues(pages, components),
+        ...collectIssues(pages, components, { patternGroups: config.patternGroups }),
         ...checkPageTypeErrors(pages, { fallbackPaths, hostRoot: config.projectRoot }),
         ...checkOverlaysFramed(pages, components, config.projectRoot),
         ...collectGlobalIssues({ syncWarnings: syncResult.warnings, tokenFileCount }),
@@ -893,6 +1318,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 +1358,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);