An open source design system that's fully customizable and agent ready
TypeScript
build(knowledge): add component module contracts (#5833)
Cindy Zhang8bf4b513637e
diff --git a/.github/scripts/change-scope.cjs b/.github/scripts/change-scope.cjsindex 53abb1b47b..1c09247fe8 100644--- a/.github/scripts/change-scope.cjs+++ b/.github/scripts/change-scope.cjs@@ -3,6 +3,9 @@'use strict';/* global console, module, process, require */+// eslint-disable-next-line @typescript-eslint/no-require-imports+const {isComponentSpecRecordPath} = require('./knowledge-paths.cjs');+/*** Classifies changed paths without reading PR-controlled content.*@@ -16,7 +19,6 @@ const SPEC_RECORD_PATTERNS = [/^docs\/families\/(?!README\.md$)[^/]+\.md$/,/^docs\/design\/(?!README\.md$)(?!assets\/)[^/]+\.md$/,/^packages\/themes\/([^/]+)\/\1\.spec\.md$/,- /^packages\/(?:core|lab)\/src\/[^/]+\/[^/]+\.spec\.md$/,];const CHANGESET_PATTERN = /^\.changeset\/(?!README\.md$)[^/]+\.md$/;@@ -34,7 +36,10 @@ const KNOWLEDGE_RECORD_PATTERNS = [];function isSpecRecordPath(filePath) {- return SPEC_RECORD_PATTERNS.some(pattern => pattern.test(filePath));+ return (+ isComponentSpecRecordPath(filePath) ||+ SPEC_RECORD_PATTERNS.some(pattern => pattern.test(filePath))+ );}function isPackageReleasePath(filePath) {@@ -54,7 +59,10 @@ function isPackageReleasePath(filePath) {}function isKnowledgeRecordPath(filePath) {- return KNOWLEDGE_RECORD_PATTERNS.some(pattern => pattern.test(filePath));+ return (+ isSpecRecordPath(filePath) ||+ KNOWLEDGE_RECORD_PATTERNS.some(pattern => pattern.test(filePath))+ );}function normalizeChange(change) {diff --git a/.github/scripts/change-scope.test.mjs b/.github/scripts/change-scope.test.mjsindex 1aa39d87d1..9fae95f040 100644--- a/.github/scripts/change-scope.test.mjs+++ b/.github/scripts/change-scope.test.mjs@@ -15,6 +15,10 @@ describe('spec-only change scope', () => {{filename: 'docs/design/selection-inputs.md'},{filename: 'packages/themes/neutral/neutral.spec.md'},{filename: 'packages/core/src/Selector/Selector.spec.md'},+ {+ filename:+ 'packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md',+ },{filename: 'packages/lab/src/FutureInput/FutureInput.spec.md'},]);expect(result.specOnly).toBe(true);@@ -85,6 +89,9 @@ describe('spec-only change scope', () => {it.each(['packages/core/src/Selector/Selector.tsx','packages/core/src/Selector/Selector.audit.json',+ 'packages/core/src/Table/__fixtures__/fake.spec.md',+ 'packages/core/src/Table/generated/fake.spec.md',+ 'packages/core/src/Table/plugins/fake.generated.spec.md','docs/architecture/layers.md','docs/templates/knowledge/component-spec.md','docs/templates/knowledge/theme-spec.md',@@ -109,6 +116,19 @@ describe('spec-only change scope', () => {expect(result.specOnly).toBe(false);});+ it.each([+ 'packages/core/src/__tests__/TopLevel.spec.md',+ 'packages/core/src/Selector/__fixtures__/fixture.spec.md',+ 'packages/core/src/Selector/.hidden/Hidden.spec.md',+ 'packages/core/src/Selector/.Hidden.spec.md',+ 'packages/core/src/Selector/generated/fake.spec.md',+ 'packages/core/src/Selector/plugins/fake.generated.spec.md',+ ])('ignores non-record component spec path %s consistently', filename => {+ const result = classifyChanges([{filename}]);+ expect(result.specOnly).toBe(false);+ expect(result.touchesKnowledgeRecords).toBe(false);+ });+it('fails closed for an empty change set', () => {expect(classifyChanges([]).specOnly).toBe(false);});diff --git a/.github/scripts/knowledge-paths.cjs b/.github/scripts/knowledge-paths.cjsnew file mode 100644index 0000000000..72431115e7--- /dev/null+++ b/.github/scripts/knowledge-paths.cjs@@ -0,0 +1,82 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use strict';+/* global module */++/**+ * One dependency-free path contract for component-local knowledge records.+ * Validation, change classification, and the spec-owner gate all consume this+ * helper so ignored paths cannot become records on only one surface.+ */++const IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS = new Set([+ '__fixtures__',+ '__generated__',+ '__snapshots__',+ '__tests__',+ 'build',+ 'coverage',+ 'dist',+ 'fixtures',+ 'generated',+ 'node_modules',+ 'test',+ 'test-utils',+ 'tests',+]);++function normalizePath(filePath) {+ return String(filePath).replaceAll('\\', '/').replace(/^\.\//, '');+}++function isIgnoredComponentKnowledgeSegment(segment) {+ return (+ segment.startsWith('.') || IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS.has(segment)+ );+}++/**+ * Classify a canonical component-local knowledge candidate by path alone.+ * Direct children are component-record candidates; module records must be+ * nested at least one directory beneath the component root. Semantic kind,+ * filename/id agreement, and parent ownership are validated after parsing.+ */+function classifyComponentKnowledgePath(filePath) {+ const normalized = normalizePath(filePath);+ const match = /^packages\/(core|lab)\/src\/([^/]+)\/(.+\.spec\.md)$/.exec(+ normalized,+ );+ if (!match) return null;++ const packageName = match[1];+ const componentRoot = match[2];+ const relativePath = match[3];+ const segments = [componentRoot, ...relativePath.split('/')];+ if (segments.some(isIgnoredComponentKnowledgeSegment)) return null;++ const fileName = segments.at(-1);+ if (fileName.endsWith('.generated.spec.md')) return null;+ const publicName = fileName.slice(0, -'.spec.md'.length);+ if (!/^[A-Za-z][A-Za-z0-9]*$/.test(publicName)) return null;++ const nested = relativePath.includes('/');+ return {+ componentRoot,+ fileName,+ kind: nested ? 'module' : 'component',+ packageName,+ publicName,+ relativePath,+ };+}++function isComponentSpecRecordPath(filePath) {+ return classifyComponentKnowledgePath(filePath) !== null;+}++module.exports = {+ IGNORED_COMPONENT_KNOWLEDGE_SEGMENTS,+ classifyComponentKnowledgePath,+ isComponentSpecRecordPath,+ isIgnoredComponentKnowledgeSegment,+};diff --git a/.github/scripts/knowledge-paths.test.mjs b/.github/scripts/knowledge-paths.test.mjsnew file mode 100644index 0000000000..91d582cfae--- /dev/null+++ b/.github/scripts/knowledge-paths.test.mjs@@ -0,0 +1,60 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {createRequire} from 'node:module';+import {describe, expect, it} from 'vitest';++const require = createRequire(import.meta.url);+const {+ classifyComponentKnowledgePath,+ isComponentSpecRecordPath,+} = require('./knowledge-paths.cjs');++describe('component knowledge paths', () => {+ it.each([+ [+ 'flat component record',+ 'packages/core/src/Button/Button.spec.md',+ 'component',+ ],+ [+ 'flat public member record',+ 'packages/core/src/NavMenu/NavHeadingMenu.spec.md',+ 'component',+ ],+ [+ 'nested module record',+ 'packages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md',+ 'module',+ ],+ [+ 'nested Lab module record',+ 'packages/lab/src/Future/subsystems/model/createModel.spec.md',+ 'module',+ ],+ ])('classifies the %s', (_label, filePath, kind) => {+ expect(classifyComponentKnowledgePath(filePath)).toMatchObject({kind});+ expect(isComponentSpecRecordPath(filePath)).toBe(true);+ });++ it.each([+ 'packages/core/src/__tests__/TopLevel.spec.md',+ 'packages/core/src/Button/__fixtures__/Fixture.spec.md',+ 'packages/core/src/Button/.hidden/Hidden.spec.md',+ 'packages/core/src/Button/.Hidden.spec.md',+ 'packages/core/src/Button/generated/Generated.spec.md',+ 'packages/core/src/Button/plugins/Thing.generated.spec.md',+ 'packages/core/src/Button/node_modules/pkg/Dependency.spec.md',+ ])('ignores %s on every consumer', filePath => {+ expect(classifyComponentKnowledgePath(filePath)).toBeNull();+ expect(isComponentSpecRecordPath(filePath)).toBe(false);+ });++ it.each([+ 'packages/core/src/Button/Button.md',+ 'packages/core/src/Button/not-kebab.spec.md',+ 'packages/core/src/Button.spec.md',+ 'packages/charts/src/Chart/Chart.spec.md',+ ])('rejects non-record path %s', filePath => {+ expect(classifyComponentKnowledgePath(filePath)).toBeNull();+ });+});diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjsindex 7554f39111..234f950c1c 100644--- a/.github/scripts/spec-owner-reconcile.test.mjs+++ b/.github/scripts/spec-owner-reconcile.test.mjs@@ -350,6 +350,26 @@ describe('spec owner workflow reconciliation', () => {expect(harness.state.pr.auto_merge).toBe(null);});+ it.each([+ 'packages/core/src/__tests__/TopLevel.spec.md',+ 'packages/core/src/Button/.hidden/Hidden.spec.md',+ 'packages/core/src/Button/.Hidden.spec.md',+ 'packages/core/src/Button/generated/Generated.spec.md',+ ])('does not owner-gate ignored component spec path %s', async filename => {+ const harness = createHarness({+ changedFile: {filename, status: 'added'},+ headContent: 'kind: module\nauthority: current\n',+ });++ await run(harness, context({runId: 100n, action: 'synchronize'}));++ expect(latestGateStatus(harness.state)).toMatchObject({+ state: 'success',+ description: 'No knowledge records changed.',+ });+ expect(harness.state.calls).not.toContain('enable-auto-merge');+ });+it('requires a real ready transition and never auto-merges a draft PR', async () => {const readyDraft = createDesignHarness({draft: true});diff --git a/.github/scripts/spec-owner-workflow.test.mjs b/.github/scripts/spec-owner-workflow.test.mjsindex 238d185964..f91d6c4f99 100644--- a/.github/scripts/spec-owner-workflow.test.mjs+++ b/.github/scripts/spec-owner-workflow.test.mjs@@ -1,7 +1,9 @@// Copyright (c) Meta Platforms, Inc. and affiliates.import fs from 'node:fs';+import os from 'node:os';import path from 'node:path';+import {spawnSync} from 'node:child_process';import {describe, expect, it} from 'vitest';const root = path.resolve(import.meta.dirname, '../..');@@ -23,6 +25,65 @@ describe('spec-only workflow contract', () => {);});+ it('packages every dependency for trusted-base isolated classification', () => {+ for (const workflow of [+ '.github/workflows/ci.yml',+ '.github/workflows/lint.yml',+ ]) {+ const source = read(workflow);+ expect(source, workflow).toContain(+ 'git show "origin/${{ github.base_ref }}:.github/scripts/change-scope.cjs"',+ );+ expect(source, workflow).toContain(+ 'git show "origin/${{ github.base_ref }}:.github/scripts/knowledge-paths.cjs"',+ );+ expect(source, workflow).toContain(+ 'CLASSIFIER_DIR="$RUNNER_TEMP/change-scope"',+ );+ }++ const isolated = fs.mkdtempSync(+ path.join(os.tmpdir(), 'astryx-change-scope-'),+ );+ try {+ for (const file of ['change-scope.cjs', 'knowledge-paths.cjs']) {+ fs.copyFileSync(+ path.join(root, '.github/scripts', file),+ path.join(isolated, file),+ );+ }+ const output = path.join(isolated, 'github-output');+ const result = spawnSync(+ process.execPath,+ [path.join(isolated, 'change-scope.cjs'), '--github-output'],+ {+ encoding: 'utf8',+ env: {...process.env, GITHUB_OUTPUT: output},+ input:+ 'A\tpackages/core/src/Table/plugins/rowStatus/useTableRowStatus.spec.md\n',+ },+ );+ expect(result.status, result.stderr).toBe(0);+ expect(fs.readFileSync(output, 'utf8')).toBe(+ 'spec_only=true\ndocsite_only=false\n',+ );++ fs.rmSync(path.join(isolated, 'knowledge-paths.cjs'));+ const missingDependency = spawnSync(+ process.execPath,+ [path.join(isolated, 'change-scope.cjs')],+ {+ encoding: 'utf8',+ input: 'A\tpackages/core/src/Button/Button.spec.md\n',+ },+ );+ expect(missingDependency.status).not.toBe(0);+ expect(missingDependency.stderr).toContain('knowledge-paths.cjs');+ } finally {+ fs.rmSync(isolated, {recursive: true, force: true});+ }+ });+it('keeps required CI names green while skipping heavy work', () => {const ci = read('.github/workflows/ci.yml');expect(ci).toContain(diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 5f38e1efa3..a2ad46c07a 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -48,8 +48,12 @@ jobs:printf 'docsite_only=false\nspec_only=false\n' >> "$GITHUB_OUTPUT"exit 0fi- CLASSIFIER="$RUNNER_TEMP/change-scope.cjs"- if git show "origin/${{ github.base_ref }}:.github/scripts/change-scope.cjs" > "$CLASSIFIER" 2>/dev/null; then+ CLASSIFIER_DIR="$RUNNER_TEMP/change-scope"+ mkdir -p "$CLASSIFIER_DIR"+ CLASSIFIER="$CLASSIFIER_DIR/change-scope.cjs"+ MATCHER="$CLASSIFIER_DIR/knowledge-paths.cjs"+ if git show "origin/${{ github.base_ref }}:.github/scripts/change-scope.cjs" > "$CLASSIFIER" 2>/dev/null \+ && git show "origin/${{ github.base_ref }}:.github/scripts/knowledge-paths.cjs" > "$MATCHER" 2>/dev/null; thengit diff --name-status "$MERGE_BASE"...HEAD \| node "$CLASSIFIER" --github-outputelsediff --git a/.github/workflows/lint.yml b/.github/workflows/lint.ymlindex 5b83ec8652..24653372d7 100644--- a/.github/workflows/lint.yml+++ b/.github/workflows/lint.yml@@ -29,8 +29,12 @@ jobs:printf 'docsite_only=false\nspec_only=false\n' >> "$GITHUB_OUTPUT"exit 0fi- CLASSIFIER="$RUNNER_TEMP/change-scope.cjs"- if git show "origin/${{ github.base_ref }}:.github/scripts/change-scope.cjs" > "$CLASSIFIER" 2>/dev/null; then+ CLASSIFIER_DIR="$RUNNER_TEMP/change-scope"+ mkdir -p "$CLASSIFIER_DIR"+ CLASSIFIER="$CLASSIFIER_DIR/change-scope.cjs"+ MATCHER="$CLASSIFIER_DIR/knowledge-paths.cjs"+ if git show "origin/${{ github.base_ref }}:.github/scripts/change-scope.cjs" > "$CLASSIFIER" 2>/dev/null \+ && git show "origin/${{ github.base_ref }}:.github/scripts/knowledge-paths.cjs" > "$MATCHER" 2>/dev/null; thengit diff --name-status "$MERGE_BASE"...HEAD \| node "$CLASSIFIER" --github-outputelsediff --git a/AGENTS.md b/AGENTS.mdindex 9024fdb8d0..967974f1cb 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -11,7 +11,8 @@ Meta-only context.- Contributors: read `CONTRIBUTING.md` and the relevant guidance linked from`docs/README.md`.- Component work: read the component's `{Name}.spec.md` when one exists, then- its consumer docs, tests, and implementation.+ any `module:*` records it lists for the public module being changed, followed by+ consumer docs, tests, and implementation.- Cross-component work: read the relevant contract under `docs/families/`,applicable design spec under `docs/design/`, and current architecture under`docs/architecture/`.diff --git a/docs/README.md b/docs/README.mdindex ec341dbea7..fb1bff49cf 100644--- a/docs/README.md+++ b/docs/README.md@@ -15,9 +15,24 @@ it governs. Consumer documentation remains in component `.doc.mjs` files and- `templates/knowledge/`: authoring templates. Templates never live among records.- `schemas/knowledge/`: versioned structural requirements for templates and records.-Component-local contracts and audits live beside the component as-`<Name>.spec.md` and `<Name>.audit.json`. Theme contracts likewise live beside-the package as `packages/themes/<theme>/<theme>.spec.md`.+Component contracts are direct children of their Core or Lab component root and+use `<PublicName>.spec.md`. `<PublicName>` normally matches the root directory;+a public member such as `NavMenu/NavHeadingMenu.spec.md` is valid only when an+exact top-level or full inline consumer-doc entry in that root declares the same+public name. A flat filename and matching `component:` id alone are not enough.++Independently contractible public hooks, plugins, utilities, and subsystems use+`kind: module` records named `<PublicName>.spec.md` at least one directory below+the same component root. Their canonical id is+`module:<ParentComponent>/<PublicName>`; the module's `parent_component` and the+parent component's `modules` list must agree. Private transform helpers do not+require records.++Component-local discovery and PR routing ignore hidden path segments,+`*.generated.spec.md`, and fixture, test, generated, build-output, coverage, and+`node_modules` directories. Those files are not knowledge records or spec-only+changes. Theme contracts live beside the package as+`packages/themes/<theme>/<theme>.spec.md`.## Authority@@ -38,9 +53,11 @@ Every knowledge record declares `authority: draft | current | archived`.through GitHub review. When an approver is also the PR author, they comment`/approve-spec <full-head-sha>`. Any new commit invalidates that approval.- Only `current` documents guide implementation and review.-- Current records link only other current records. Draft relationships are listed- on the candidate record; promotion updates affected backlinks under owner- review.+- Current records rely only on other current records. `modules` and+ `parent_component` are structural ownership links, so they may connect active+ draft/current records without making draft behavior authoritative. Other draft+ relationships are listed on the candidate record; promotion updates affected+ backlinks under owner review.- `archived` documents declare `archive_reason` (`superseded`, `withdrawn`, or`historical`) and link `superseded_by` when a replacement exists.diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.mdindex 70dc525171..a4c0e1def5 100644--- a/docs/architecture/knowledge-contracts.md+++ b/docs/architecture/knowledge-contracts.md@@ -33,7 +33,10 @@ requests:Astryx keeps different facts in different places:-- Component contracts describe behavior one component promises.+- Component contracts describe aggregate behavior one component promises.+- Module contracts describe an independently contractible public hook, plugin,+ utility, or subsystem owned by one component. Private implementation helpers do+ not require records.- Family contracts describe behavior sibling components share.- Design specs record human-owned visual and interaction decisions, including thecross-theme accessibility and contrast methodology used to judge token/color@@ -45,12 +48,12 @@ Astryx keeps different facts in different places:- Consumer docs explain props, examples, and usage.- Audit records hold current evidence and findings.-The reviewer starts with the changed code and the nearest current component-contract. They follow only the links needed for the question:+The reviewer starts with the changed code and the nearest current component or+module contract. They follow only the links needed for the question:```textchanged code or theme source- → nearest current component or theme contract+ → nearest current component, module, or theme contract→ relevant family or design requirement→ architecture or system decision only when referenced→ mapped tests and audit evidence@@ -84,8 +87,10 @@ Every record is either:compiler behavior stay in architecture/system records; human contrastmethodology stays in design; shared measurement implementation stays inarchitecture/tooling; theme-specific mappings, states, exceptions, receipts,- and gaps stay in the package-local theme record; observable component behavior- stays in component/family records; consumer syntax stays in consumer docs.+ and gaps stay in the package-local theme record; aggregate observable component+ behavior stays in component/family records; independently contractible public+ component-module behavior stays in module records; consumer syntax stays in+ consumer docs.- **INV3 — Existing decisions are reusable.** A reviewer cites an applicabledecision and proceeds without asking the human again.- **INV4 — New judgment is explicit.** A reviewer asks a human when no current@@ -99,7 +104,7 @@ Every record is either:creates a later schema definition for that kind and migrates every active recordof that kind in the same pull request.- **INV7 — Only pure spec changes use lightweight CI.** Every changed file must- be a component, family, design, theme, or system spec. A change to code,+ be a component, module, family, design, theme, or system spec. A change to code,architecture, guidance, templates, schemas, audits, or any unknown path runsnormal CI.- **INV8 — Private operations stay private.** Public records never name or link@@ -110,9 +115,10 @@ Every record is either:### When current records disagree1. A draft is context only and cannot conflict with current policy.-2. Identify the canonical owner from the fact's scope: component behavior,- family behavior, design representation, one theme's semantics/mappings,- cross-theme architecture, consumer usage, or audit evidence.+2. Identify the canonical owner from the fact's scope: aggregate component+ behavior, independent public module behavior, family behavior, design+ representation, one theme's semantics/mappings, cross-theme architecture,+ consumer usage, or audit evidence.3. If two current records make different claims, review stops. Do not choose byrecency, path proximity, or specificity; record a `novel-human` gap.4. Resolve the gap by changing the canonical owner and removing the copied claim.@@ -125,8 +131,8 @@ Every record is either:A document does not stay current by convention alone.-Before any component, family, design, theme, or architecture record becomes `current`,-the repository must support this flow:+Before any component, module, family, design, theme, or architecture record becomes+`current`, the repository must support this flow:1. The record names the code surface that can affect it and the checks thatverify it.@@ -135,7 +141,7 @@ the repository must support this flow:- `preserves`: the change still satisfies the current contract;- `settled`: an existing human decision applies and is cited;- `novel-human`: the contract needs a new human decision;- - `out-of-scope`: another component, family, system, or product owns it.+ - `out-of-scope`: another component, module, family, system, or product owns it.4. `preserves` and `settled` proceed without asking the human again.5. `novel-human` remains blocked until the owning record contains the newdecision and receives approval.@@ -171,7 +177,7 @@ canonical decision.Record the durable outcome, not the review transcript. A ruling belongs in acanonical record when at least one is true:-- it changes or clarifies an owning component, family, or system boundary;+- it changes or clarifies an owning component, module, family, or system boundary;- it establishes a requirement or prohibition future work must preserve; or- it rejects an alternative that is consequential and likely to recur.@@ -200,13 +206,22 @@ Examples:A draft record cannot clear a review gap. Only a verified `current` contract oran applicable decision can produce `preserves` or `settled`.-The bootstrap does not mark any component or family record current until this-flow passes the historical review benchmark and is enforced on pull requests.+The bootstrap does not mark any component, module, or family record current until+this flow passes the historical review benchmark and is enforced on pull requests.## Owning code- `AGENTS.md` points reviewers to the narrowest relevant record.- `docs/templates/knowledge/` contains authoring forms.+- Component records are direct `<PublicName>.spec.md` children of a Core or Lab+ component root. The public name normally matches the root; a parent/member+ exception requires an exact top-level or full inline consumer-doc entry in+ that root. Public semantic module records are nested at least one directory+ beneath the same root as `<PublicName>.spec.md`; the parent component's+ `modules` list and the module's `parent_component` field must agree. Hidden,+ fixture, test, generated, build-output, coverage, dependency, and+ `*.generated.spec.md` paths are ignored consistently by discovery and PR+ routing.- `packages/themes/<theme>/<theme>.spec.md` contains that package theme'scanonical record; `docs/themes/README.md` is guidance and an index only.- `docs/schemas/knowledge/` defines required structure.diff --git a/docs/schemas/knowledge/v3.json b/docs/schemas/knowledge/v3.jsonnew file mode 100644index 0000000000..29728de26d--- /dev/null+++ b/docs/schemas/knowledge/v3.json@@ -0,0 +1,94 @@+{+ "schemaVersion": 3,+ "extends": 2,+ "kinds": {+ "component": {+ "template": "docs/templates/knowledge/component-spec.md",+ "requiredFrontmatter": [+ "schema_version",+ "template_version",+ "kind",+ "id",+ "authority",+ "archive_reason",+ "superseded_by",+ "approved_by",+ "approved_at",+ "owners",+ "review_triggers",+ "verified_by",+ "modules",+ "families",+ "design_specs",+ "architecture",+ "contributing",+ "system_specs"+ ],+ "requiredSections": [+ "Intent",+ "Compatibility and migration",+ "Ownership boundary",+ "Public concepts",+ "Behavioral and layout contract",+ "Accessibility contract",+ "Design relationships",+ "Family and system relationships",+ "Verification map",+ "Decision log",+ "Open questions",+ "Content boundary"+ ],+ "currentNonEmptyFields": ["owners", "review_triggers", "verified_by"],+ "listFields": [+ "owners",+ "review_triggers",+ "verified_by",+ "modules",+ "families",+ "design_specs",+ "architecture",+ "contributing",+ "system_specs"+ ],+ "idPattern": "^component:[A-Z][A-Za-z0-9]*$"+ },+ "module": {+ "template": "docs/templates/knowledge/module-spec.md",+ "requiredFrontmatter": [+ "schema_version",+ "template_version",+ "kind",+ "id",+ "authority",+ "archive_reason",+ "superseded_by",+ "approved_by",+ "approved_at",+ "owners",+ "review_triggers",+ "verified_by",+ "parent_component",+ "references"+ ],+ "requiredSections": [+ "Intent",+ "Compatibility and migration",+ "Ownership boundary",+ "Public API and concepts",+ "Behavioral contract",+ "Accessibility contract",+ "Design relationships",+ "Parent and system relationships",+ "Verification map",+ "Decision log",+ "Open questions",+ "Content boundary"+ ],+ "currentNonEmptyFields": ["owners", "review_triggers", "verified_by"],+ "requiredNonEmptyStringFields": ["parent_component"],+ "listFields": ["owners", "review_triggers", "verified_by", "references"],+ "referenceFields": ["references"],+ "idPattern": "^module:[A-Z][A-Za-z0-9]*/[A-Za-z][A-Za-z0-9]*$"+ }+ }+}diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.mdindex 94e56c5e9e..9bee2098ba 100644--- a/docs/templates/knowledge/component-spec.md+++ b/docs/templates/knowledge/component-spec.md@@ -1,6 +1,6 @@----schema_version: 1-template_version: 3+schema_version: 3+template_version: 4kind: componentid: component:<Name>authority: draft@@ -11,6 +11,7 @@ approved_at: nullowners: [<owner>]review_triggers: [public-api, behavior, layout, theming, accessibility]verified_by: [<test-or-check>]+modules: [module:<Name>/<PublicModule>]families: [family:<family-name>]design_specs: [design:<surface>]architecture: [architecture:<surface>]@@ -48,9 +49,10 @@ Consumer migration instructions belong in consumer docs and release notes.<!--Concepts, not a prop table. Consumer syntax/defaults remain in <Name>.doc.mjs.Record only component-local semantic concepts, additions, and exceptions; inherit-current family rules. For an explicitly co-owned public hook or utility, cover-semantic inputs/outputs and lifetime/resource behavior through concept rows and-linked local requirements. Follow spec:AST-002 without copying system rules.+current family rules. When a public hook, plugin, utility, or subsystem has an+independent contract, list its `module:<Name>/<PublicName>` record in `modules`+and keep its API, behavior, accessibility, precedence, and evidence there.+Follow spec:AST-002 without copying system rules.-->| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |@@ -132,10 +134,13 @@ current reachability never silently decides future themeability.## Family and system relationships-Frontmatter lists only `current` family, design, architecture, and system-relationships. Candidate records list proposed members on the candidate itself;-do not edit an existing component contract merely to backlink to a draft.+Frontmatter lists structural `modules` links plus only `current` family, design,+architecture, and system relationships. A module backlink may name an active+draft because it records ownership rather than adopting draft behavior. Candidate+family or design records list proposed members on the candidate itself; do not+edit an existing component contract merely to backlink to those drafts.+- `module:<Name>/<PublicName>` owns `<independent public module contract>`; this component owns aggregate module protocol, ordering, and composition.- `family:<family-name>` owns `<shared concept>`; this component `<adopts or deliberately differs>`.## Verification mapdiff --git a/docs/templates/knowledge/module-spec.md b/docs/templates/knowledge/module-spec.mdnew file mode 100644index 0000000000..09dd976d5e--- /dev/null+++ b/docs/templates/knowledge/module-spec.md@@ -0,0 +1,120 @@+---+schema_version: 3+template_version: 1+kind: module+id: module:<ParentComponent>/<PublicName>+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [<owner>]+review_triggers: [public-api, behavior, theming, accessibility]+verified_by: [<test-or-check>]+parent_component: component:<ParentComponent>+references: [architecture:<surface>, design:<surface>, spec:AST-000/DEC-0]+---++# <PublicName> module contract++## Intent++<!-- Why this public semantic module exists and the component-local job it owns. Private implementation helpers do not need records. Consumer usage belongs in the module's .doc.mjs. -->++## Compatibility and migration++- Released default preserved: `<yes, no, or not yet released>`+- Compatibility class: `<state the compatibility effect>`+- Migration decision: `<module DEC or system spec link>`++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- `<the module's public API, generated anatomy, accessibility, precedence, or evidence obligation>`++**Does not own / non-goals**++- Aggregate module protocol, ordering, and composition — owned by `component:<ParentComponent>`.+- `<other responsibility>` — owned by `<record or product callsite>`.++## Public API and concepts++<!-- Concepts, not a duplicated parameter table. Consumer signatures/defaults remain in the module's .doc.mjs. -->++| Concept | Closed values or states | Meaning | Default | Owner | Stability |+| ----------- | ----------------------- | ----------- | ----------- | --------------------------------------- | -------------------------- |+| `<concept>` | `<values>` | `<meaning>` | `<default>` | `module:<ParentComponent>/<PublicName>` | `<stable or experimental>` |++## Behavioral contract++| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------- | ----------------------------------------------------------------------------- | -------------------------------------- |+| FR1 | `<The module MUST …>` | `<existing DEC, documented promise, standard, current behavior, or proposal>` | `<settled, verify, or human decision>` |++### Transformation and precedence order++- **ORD1 — `<pipeline>`.** `<The required order and which explicit input wins.>`++### Performance and resources++- **PR1 — `<constraint>`.** `<Durable render, listener, observer, or initialization behavior.>`++## Accessibility contract++- **AR1 — `<obligation>`.** `<The module MUST …>`++## Design relationships++| Anatomy or state | Design requirement | Representation authority | Module contract |+| ---------------- | ---------------------- | -------------------------------------------- | ------------------- |+| `<role/state>` | `design:<surface>/DR1` | `<prescribed, human-selected, or unsettled>` | `<FR/AR reference>` |++### Theming anatomy++<!--+Optional during migration. When present, this block maps the exact public anatomy+and targets from this module's own consumer-doc entry. It never falls back to the+parent component's aggregate anatomy or target inventory. Use the same+anatomy-theming:v1 format documented by the component template.+-->++<!-- anatomy-theming:v1 -->++```json+{+ "<module part>": {"target": "<target>"}+}+```++## Parent and system relationships++- `component:<ParentComponent>` owns aggregate module protocol, ordering, and composition.+- This record owns only the independent public module contract stated above; link shared rules instead of copying them.++## Verification map++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | ---------------------------- | --------------------- | ----------------------------------------------- |+| FR1 | `<test or browser evidence>` | `<states>` | `<removing behavior makes this fail because …>` |++## Decision log++### DEC-1 — `<module-local decision>`++**Reference:** `module:<ParentComponent>/<PublicName>/DEC-1`+**Decider:** `<person>`, `<YYYY-MM-DD>`++`<Reason and user impact.>`++## Open questions++- **OQ1 — `<question>`** (`checkable | human-design | human-api`)++## Content boundary++This record does not duplicate consumer signatures/examples, parent aggregate+protocol or ordering, current audit results, implementation steps, or+family/design/system rules. It links to their canonical owners.diff --git a/docs/templates/knowledge/versions.json b/docs/templates/knowledge/versions.jsonindex aab9c9536b..55f7db5807 100644--- a/docs/templates/knowledge/versions.json+++ b/docs/templates/knowledge/versions.json@@ -1,9 +1,10 @@{"architecture": 1,- "component": 3,+ "component": 4,"design": 1,"family": 1,"implementation-plan": 1,+ "module": 1,"system-spec": 1,"theme": 1}diff --git a/packages/core/src/BottomSheet/BottomSheet.spec.md b/packages/core/src/BottomSheet/BottomSheet.spec.mdindex 8478109404..01390ea318 100644--- a/packages/core/src/BottomSheet/BottomSheet.spec.md+++ b/packages/core/src/BottomSheet/BottomSheet.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:BottomSheet@@ -16,6 +16,7 @@ verified_by:packages/core/src/BottomSheet/BottomSheetPanel.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/CheckboxList/CheckboxList.spec.md b/packages/core/src/CheckboxList/CheckboxList.spec.mdindex deb32cd222..cae69d4d7c 100644--- a/packages/core/src/CheckboxList/CheckboxList.spec.md+++ b/packages/core/src/CheckboxList/CheckboxList.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:CheckboxList@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/CommandPalette/CommandPalette.spec.md b/packages/core/src/CommandPalette/CommandPalette.spec.mdindex ca46f4db5b..3073331946 100644--- a/packages/core/src/CommandPalette/CommandPalette.spec.md+++ b/packages/core/src/CommandPalette/CommandPalette.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:CommandPalette@@ -21,6 +21,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/ComplexSelector/ComplexSelector.spec.md b/packages/core/src/ComplexSelector/ComplexSelector.spec.mdindex 0b9a3f6051..ce0ebcbdb4 100644--- a/packages/core/src/ComplexSelector/ComplexSelector.spec.md+++ b/packages/core/src/ComplexSelector/ComplexSelector.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:ComplexSelector@@ -17,6 +17,7 @@ verified_by:packages/core/src/Icon/Icon.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/ContextMenu/ContextMenu.spec.md b/packages/core/src/ContextMenu/ContextMenu.spec.mdindex 13f4c118f9..10ddaae962 100644--- a/packages/core/src/ContextMenu/ContextMenu.spec.md+++ b/packages/core/src/ContextMenu/ContextMenu.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:ContextMenu@@ -18,6 +18,7 @@ verified_by:packages/core/src/List/List.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/Divider/Divider.spec.md b/packages/core/src/Divider/Divider.spec.mdindex ccd6891c66..8a158b6a94 100644--- a/packages/core/src/Divider/Divider.spec.md+++ b/packages/core/src/Divider/Divider.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Divider@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/Divider/Divider.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/DropdownMenu/DropdownMenu.spec.md b/packages/core/src/DropdownMenu/DropdownMenu.spec.mdindex 507e387e27..7f70f25d2a 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.spec.md+++ b/packages/core/src/DropdownMenu/DropdownMenu.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:DropdownMenu@@ -21,6 +21,7 @@ verified_by:packages/core/src/Icon/Icon.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/FieldStatus/FieldStatus.spec.md b/packages/core/src/FieldStatus/FieldStatus.spec.mdindex e03e3d0df6..1677623e71 100644--- a/packages/core/src/FieldStatus/FieldStatus.spec.md+++ b/packages/core/src/FieldStatus/FieldStatus.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 1kind: componentid: component:FieldStatus@@ -15,6 +15,7 @@ verified_by:packages/core/src/FieldStatus/FieldStatus.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Grid/Grid.spec.md b/packages/core/src/Grid/Grid.spec.mdindex 113a46c46a..9b38d05482 100644--- a/packages/core/src/Grid/Grid.spec.md+++ b/packages/core/src/Grid/Grid.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Grid@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:layout-primitives]design_specs: []architecture:diff --git a/packages/core/src/Icon/Icon.spec.md b/packages/core/src/Icon/Icon.spec.mdindex 655493a664..189f1041c5 100644--- a/packages/core/src/Icon/Icon.spec.md+++ b/packages/core/src/Icon/Icon.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Icon@@ -11,6 +11,7 @@ approved_at: 2026-08-30owners: [cixzhang, imdreamrunner]review_triggers: [public-api, behavior, theming, accessibility]verified_by: [packages/core/src/Icon/Icon.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Kbd/Kbd.spec.md b/packages/core/src/Kbd/Kbd.spec.mdindex fd7692dd35..f2741b6521 100644--- a/packages/core/src/Kbd/Kbd.spec.md+++ b/packages/core/src/Kbd/Kbd.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Kbd@@ -11,6 +11,7 @@ approved_at: nullowners: [cixzhang]review_triggers: [theming]verified_by: [packages/core/src/Kbd/Kbd.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Layout/Layout.spec.md b/packages/core/src/Layout/Layout.spec.mdindex 9a50dc7b43..aa0baf6ed0 100644--- a/packages/core/src/Layout/Layout.spec.md+++ b/packages/core/src/Layout/Layout.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Layout@@ -19,6 +19,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:layout-regions]design_specs: []architecture:diff --git a/packages/core/src/Lightbox/Lightbox.spec.md b/packages/core/src/Lightbox/Lightbox.spec.mdindex ae4a60fffb..4be20e55ec 100644--- a/packages/core/src/Lightbox/Lightbox.spec.md+++ b/packages/core/src/Lightbox/Lightbox.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Lightbox@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.mdindex 586e54aeaa..b9ba3f7f95 100644--- a/packages/core/src/Markdown/Markdown.spec.md+++ b/packages/core/src/Markdown/Markdown.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Markdown@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:navigation-destinations]design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/MobileNav/MobileNav.spec.md b/packages/core/src/MobileNav/MobileNav.spec.mdindex 470b8167aa..ac73210c9f 100644--- a/packages/core/src/MobileNav/MobileNav.spec.md+++ b/packages/core/src/MobileNav/MobileNav.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:MobileNav@@ -18,6 +18,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/MoreMenu/MoreMenu.spec.md b/packages/core/src/MoreMenu/MoreMenu.spec.mdindex 3eb5c75250..54e38ac8cc 100644--- a/packages/core/src/MoreMenu/MoreMenu.spec.md+++ b/packages/core/src/MoreMenu/MoreMenu.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:MoreMenu@@ -19,6 +19,7 @@ verified_by:packages/core/src/List/List.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/MultiSelector/MultiSelector.spec.md b/packages/core/src/MultiSelector/MultiSelector.spec.mdindex 47bba00e9c..209141c002 100644--- a/packages/core/src/MultiSelector/MultiSelector.spec.md+++ b/packages/core/src/MultiSelector/MultiSelector.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:MultiSelector@@ -21,6 +21,7 @@ verified_by:packages/core/src/Text/Text.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/NavIcon/NavIcon.spec.md b/packages/core/src/NavIcon/NavIcon.spec.mdindex 962181a1b3..ebc1a411a4 100644--- a/packages/core/src/NavIcon/NavIcon.spec.md+++ b/packages/core/src/NavIcon/NavIcon.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:NavIcon@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/NavIcon/NavIcon.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/NavMenu/NavHeadingMenu.spec.md b/packages/core/src/NavMenu/NavHeadingMenu.spec.mdindex e37c422e85..1211da890c 100644--- a/packages/core/src/NavMenu/NavHeadingMenu.spec.md+++ b/packages/core/src/NavMenu/NavHeadingMenu.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:NavHeadingMenu@@ -18,6 +18,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:navigation-destinations]design_specs: []architecture:diff --git a/packages/core/src/Outline/Outline.spec.md b/packages/core/src/Outline/Outline.spec.mdindex 864e20fb3f..5c62542738 100644--- a/packages/core/src/Outline/Outline.spec.md+++ b/packages/core/src/Outline/Outline.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Outline@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/Outline/Outline.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/OverflowList/OverflowList.spec.md b/packages/core/src/OverflowList/OverflowList.spec.mdindex 196677d31e..d6a99ccce9 100644--- a/packages/core/src/OverflowList/OverflowList.spec.md+++ b/packages/core/src/OverflowList/OverflowList.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:OverflowList@@ -15,6 +15,7 @@ verified_by:packages/core/src/OverflowList/OverflowList.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Pagination/Pagination.spec.md b/packages/core/src/Pagination/Pagination.spec.mdindex dadcb42dac..0f36865723 100644--- a/packages/core/src/Pagination/Pagination.spec.md+++ b/packages/core/src/Pagination/Pagination.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Pagination@@ -20,6 +20,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Popover/Popover.spec.md b/packages/core/src/Popover/Popover.spec.mdindex e461ed1289..71b97b7fac 100644--- a/packages/core/src/Popover/Popover.spec.md+++ b/packages/core/src/Popover/Popover.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Popover@@ -20,6 +20,7 @@ verified_by:packages/cli/foundation/discovery/theming-targets.test.mjs,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/PowerSearch/PowerSearch.spec.md b/packages/core/src/PowerSearch/PowerSearch.spec.mdindex aa9cb70526..ee340bbb1e 100644--- a/packages/core/src/PowerSearch/PowerSearch.spec.md+++ b/packages/core/src/PowerSearch/PowerSearch.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:PowerSearch@@ -19,6 +19,7 @@ verified_by:packages/core/src/Layer/useLayer.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/ProgressBar/ProgressBar.spec.md b/packages/core/src/ProgressBar/ProgressBar.spec.mdindex c6eeacc5b8..9196221698 100644--- a/packages/core/src/ProgressBar/ProgressBar.spec.md+++ b/packages/core/src/ProgressBar/ProgressBar.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:ProgressBar@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Resizable/Resizable.spec.md b/packages/core/src/Resizable/Resizable.spec.mdindex 88c7aff9ad..b30fd753d3 100644--- a/packages/core/src/Resizable/Resizable.spec.md+++ b/packages/core/src/Resizable/Resizable.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Resizable@@ -17,6 +17,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Section/Section.spec.md b/packages/core/src/Section/Section.spec.mdindex d21f543a24..a331608fcc 100644--- a/packages/core/src/Section/Section.spec.md+++ b/packages/core/src/Section/Section.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Section@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/Section/Section.test.tsx, scripts/check-knowledge.mjs]+modules: []families: [family:layout-regions]design_specs: []architecture:diff --git a/packages/core/src/SegmentedControl/SegmentedControl.spec.md b/packages/core/src/SegmentedControl/SegmentedControl.spec.mdindex 0f23d0bc83..6a3a4c243f 100644--- a/packages/core/src/SegmentedControl/SegmentedControl.spec.md+++ b/packages/core/src/SegmentedControl/SegmentedControl.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:SegmentedControl@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Selector/Selector.spec.md b/packages/core/src/Selector/Selector.spec.mdindex 054f4e0ab5..294b46168e 100644--- a/packages/core/src/Selector/Selector.spec.md+++ b/packages/core/src/Selector/Selector.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Selector@@ -15,6 +15,7 @@ verified_by:packages/core/src/Selector/Selector.test.tsx,packages/core/src/Selector/Selector.source-build.test.mjs,]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Skeleton/Skeleton.spec.md b/packages/core/src/Skeleton/Skeleton.spec.mdindex 5091e3412e..7541a045f7 100644--- a/packages/core/src/Skeleton/Skeleton.spec.md+++ b/packages/core/src/Skeleton/Skeleton.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Skeleton@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/Skeleton/Skeleton.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Slider/Slider.spec.md b/packages/core/src/Slider/Slider.spec.mdindex b91a3b7abb..01b7b4400d 100644--- a/packages/core/src/Slider/Slider.spec.md+++ b/packages/core/src/Slider/Slider.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Slider@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Stack/Stack.spec.md b/packages/core/src/Stack/Stack.spec.mdindex 7106bdc6a7..36feb8cfcb 100644--- a/packages/core/src/Stack/Stack.spec.md+++ b/packages/core/src/Stack/Stack.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Stack@@ -17,6 +17,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:layout-primitives]design_specs: []architecture:diff --git a/packages/core/src/StatusDot/StatusDot.spec.md b/packages/core/src/StatusDot/StatusDot.spec.mdindex 2fedd84419..970a7b9a04 100644--- a/packages/core/src/StatusDot/StatusDot.spec.md+++ b/packages/core/src/StatusDot/StatusDot.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:StatusDot@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/StatusDot/StatusDot.test.tsx, scripts/check-knowledge.mjs]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Switch/Switch.spec.md b/packages/core/src/Switch/Switch.spec.mdindex dd8988655c..c734c2cf7c 100644--- a/packages/core/src/Switch/Switch.spec.md+++ b/packages/core/src/Switch/Switch.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Switch@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Table/Table.spec.md b/packages/core/src/Table/Table.spec.mdindex 95aeabe5c0..ad730786a3 100644--- a/packages/core/src/Table/Table.spec.md+++ b/packages/core/src/Table/Table.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Table@@ -21,6 +21,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture:diff --git a/packages/core/src/Text/Text.spec.md b/packages/core/src/Text/Text.spec.mdindex fc2431f753..48485c1547 100644--- a/packages/core/src/Text/Text.spec.md+++ b/packages/core/src/Text/Text.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Text@@ -17,6 +17,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/TextArea/TextArea.spec.md b/packages/core/src/TextArea/TextArea.spec.mdindex 06ac494f4b..093b2ed467 100644--- a/packages/core/src/TextArea/TextArea.spec.md+++ b/packages/core/src/TextArea/TextArea.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:TextArea@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: []design_specs: []architecture: [architecture:component-theming-surface]diff --git a/packages/core/src/Tokenizer/Tokenizer.spec.md b/packages/core/src/Tokenizer/Tokenizer.spec.mdindex 0adf6c6624..c650ad4236 100644--- a/packages/core/src/Tokenizer/Tokenizer.spec.md+++ b/packages/core/src/Tokenizer/Tokenizer.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Tokenizer@@ -17,6 +17,7 @@ verified_by:packages/core/src/Layer/useLayer.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/Toolbar/Toolbar.spec.md b/packages/core/src/Toolbar/Toolbar.spec.mdindex b1ce3ea04d..eeedcd1c58 100644--- a/packages/core/src/Toolbar/Toolbar.spec.md+++ b/packages/core/src/Toolbar/Toolbar.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Toolbar@@ -17,6 +17,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:layout-regions]design_specs: []architecture:diff --git a/packages/core/src/Tooltip/Tooltip.spec.md b/packages/core/src/Tooltip/Tooltip.spec.mdindex 48ea5bcf7d..22d5fab9eb 100644--- a/packages/core/src/Tooltip/Tooltip.spec.md+++ b/packages/core/src/Tooltip/Tooltip.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Tooltip@@ -12,6 +12,7 @@ owners: [cixzhang]review_triggers: [theming]verified_by:[packages/core/src/Tooltip/Tooltip.test.tsx, scripts/check-knowledge.mjs]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/packages/core/src/TreeList/TreeList.spec.md b/packages/core/src/TreeList/TreeList.spec.mdindex 877f364bff..11472b6d78 100644--- a/packages/core/src/TreeList/TreeList.spec.md+++ b/packages/core/src/TreeList/TreeList.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:TreeList@@ -16,6 +16,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,scripts/check-knowledge.mjs,]+modules: []families: [family:navigation-destinations]design_specs: []architecture:diff --git a/packages/core/src/Typeahead/Typeahead.spec.md b/packages/core/src/Typeahead/Typeahead.spec.mdindex 4bd39e4444..01f7bfe5fc 100644--- a/packages/core/src/Typeahead/Typeahead.spec.md+++ b/packages/core/src/Typeahead/Typeahead.spec.md@@ -1,5 +1,5 @@----schema_version: 1+schema_version: 3template_version: 3kind: componentid: component:Typeahead@@ -19,6 +19,7 @@ verified_by:packages/core/src/Icon/Icon.test.tsx,scripts/check-knowledge.mjs,]+modules: []families: [family:overlay-dismissal]design_specs: []architecture:diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjsindex 113540a5bc..32c81f45a8 100644--- a/scripts/check-knowledge.mjs+++ b/scripts/check-knowledge.mjs@@ -13,9 +13,16 @@ const {parseAuthority,parseOwnerFile,} = require('../.github/scripts/knowledge-frontmatter.cjs');+const {+ classifyComponentKnowledgePath,+ isComponentSpecRecordPath,+ isIgnoredComponentKnowledgeSegment,+} = require('../.github/scripts/knowledge-paths.cjs');const HERE = path.dirname(fileURLToPath(import.meta.url));const DEFAULT_ROOT = path.resolve(HERE, '..');+const MODULE_ID_PATTERN =+ /^module:([A-Z][A-Za-z0-9]*)\/([A-Za-z][A-Za-z0-9]*)$/;export function parseKnowledgeDocument(content, filePath = '<document>') {const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);@@ -110,7 +117,11 @@ function matchingFiles(directory, predicate) {.map(entry => path.join(directory, entry.name));}-function matchingFilesRecursively(directory, predicate) {+function matchingFilesRecursively(+ directory,+ predicate,+ {skipDirectory = () => false} = {},+) {if (!fs.existsSync(directory)) return [];const matches = [];const pending = [directory];@@ -118,8 +129,14 @@ function matchingFilesRecursively(directory, predicate) {const current = pending.pop();for (const entry of fs.readdirSync(current, {withFileTypes: true})) {const candidate = path.join(current, entry.name);- if (entry.isDirectory()) pending.push(candidate);- else if (entry.isFile() && predicate(entry.name)) matches.push(candidate);+ if (entry.isDirectory()) {+ if (skipDirectory(entry.name, candidate)) {+ continue;+ }+ pending.push(candidate);+ } else if (entry.isFile() && predicate(entry.name, candidate)) {+ matches.push(candidate);+ }}}return matches;@@ -189,16 +206,283 @@ export function discoverKnowledgeRecords(root = DEFAULT_ROOT) {records.push(...discoverThemeRecordCandidates(root).records);for (const packageName of ['core', 'lab']) {- for (const componentDirectory of immediateDirectories(- path.join(root, `packages/${packageName}/src`),- )) {- records.push(- ...matchingFiles(componentDirectory, name => name.endsWith('.spec.md')),+ const sourceRoot = path.join(root, `packages/${packageName}/src`);+ records.push(+ ...matchingFilesRecursively(+ sourceRoot,+ (_name, candidate) =>+ isComponentSpecRecordPath(+ path.relative(root, candidate).split(path.sep).join('/'),+ ),+ {skipDirectory: isIgnoredComponentKnowledgeSegment},+ ),+ );+ }++ return records.sort();+}++function componentRecordLocation(root, absolutePath) {+ const filePath = path.relative(root, absolutePath).split(path.sep).join('/');+ const classified = classifyComponentKnowledgePath(filePath);+ if (!classified) return null;+ return {+ ...classified,+ componentRootPath: path.join(+ root,+ 'packages',+ classified.packageName,+ 'src',+ classified.componentRoot,+ ),+ };+}++function isFullConsumerDocEntry(entry) {+ return (+ entry != null &&+ typeof entry === 'object' &&+ (typeof entry.description === 'string' ||+ Array.isArray(entry.props) ||+ Array.isArray(entry.params) ||+ Array.isArray(entry.returns) ||+ entry.usage != null)+ );+}++function componentRootDefinesPublicComponent(componentRootPath, publicName) {+ for (const docPath of matchingFilesRecursively(+ componentRootPath,+ name => name.endsWith('.doc.mjs'),+ {skipDirectory: isIgnoredComponentKnowledgeSegment},+ )) {+ let mod;+ try {+ mod = require(docPath);+ } catch {+ continue;+ }+ const doc = mod.docs ?? mod.default;+ if (!doc) continue;+ if (doc.name?.replace(/^XDS/, '') === publicName) return true;+ if (+ (doc.components ?? []).some(+ entry =>+ entry?.name?.replace(/^XDS/, '') === publicName &&+ isFullConsumerDocEntry(entry),+ )+ ) {+ return true;+ }+ }+ return false;+}++function activeRecord(record, activeAuthorities) {+ return activeAuthorities.includes(+ record.document.frontmatter.get('authority'),+ );+}++/**+ * Validate the explicit two-way ownership graph between component and module+ * records. This is structural metadata, not broad coverage enforcement: a+ * component with `modules: []` is valid, and private helpers need no record.+ */+export function validateComponentModuleRelationships(+ root,+ records,+ activeAuthorities = ['draft', 'current'],+) {+ const problems = [];+ const recordsById = new Map();++ for (const record of records) {+ const id = record.document.frontmatter.get('id');+ if (typeof id !== 'string') continue;+ const matches = recordsById.get(id) ?? [];+ matches.push(record);+ recordsById.set(id, matches);+ }++ for (const record of records) {+ const {frontmatter} = record.document;+ const kind = frontmatter.get('kind');+ if (kind !== 'component' && kind !== 'module') continue;++ const location = componentRecordLocation(root, record.absolutePath);+ if (!location) {+ problems.push(+ `${record.filePath}: ${kind} records must live under packages/{core,lab}/src/<component-root>/.`,+ );+ continue;+ }++ const publicName = location.publicName;+ if (kind === 'component') {+ if (location.kind !== 'component') {+ problems.push(+ `${record.filePath}: component records must be direct children of their component root; nested records use kind: module.`,+ );+ }+ const expectedId = `component:${publicName}`;+ if (frontmatter.get('id') !== expectedId) {+ problems.push(+ `${record.filePath}: component record id must be ${expectedId} to match its filename.`,+ );+ }+ if (+ publicName !== location.componentRoot &&+ !componentRootDefinesPublicComponent(+ location.componentRootPath,+ publicName,+ )+ ) {+ problems.push(+ `${record.filePath}: flat component record ${expectedId} must match component root ${JSON.stringify(location.componentRoot)} or an exact public component entry in that root's consumer docs.`,+ );+ }+ continue;+ }++ if (location.kind !== 'module') {+ problems.push(+ `${record.filePath}: module records must be nested beneath their component root; direct children are reserved for component records.`,+ );+ }+ const id = frontmatter.get('id');+ const idMatch = typeof id === 'string' ? MODULE_ID_PATTERN.exec(id) : null;+ if (!idMatch) continue;+ const expectedParent = `component:${idMatch[1]}`;+ if (frontmatter.get('parent_component') !== expectedParent) {+ problems.push(+ `${record.filePath}: parent_component must be ${expectedParent} to match module id ${id}.`,+ );+ }+ if (publicName !== idMatch[2]) {+ problems.push(+ `${record.filePath}: module filename must be ${idMatch[2]}.spec.md to match id ${id}.`,);}}- return records.sort();+ for (const record of records) {+ if (!activeRecord(record, activeAuthorities)) continue;+ const {frontmatter} = record.document;+ const kind = frontmatter.get('kind');+ const id = frontmatter.get('id');+ const location = componentRecordLocation(root, record.absolutePath);+ if (!location || typeof id !== 'string') continue;++ if (kind === 'component') {+ const modules = frontmatter.get('modules');+ if (!Array.isArray(modules)) continue;+ const seen = new Set();+ for (const moduleId of modules) {+ if (seen.has(moduleId)) {+ problems.push(+ `${record.filePath}: modules contains duplicate reference ${moduleId}.`,+ );+ continue;+ }+ seen.add(moduleId);++ const targets = recordsById.get(moduleId) ?? [];+ if (targets.length === 0) {+ problems.push(+ `${record.filePath}: modules reference ${moduleId} does not resolve to an active module record.`,+ );+ continue;+ }+ if (targets.length > 1) continue;+ const target = targets[0];+ if (target.document.frontmatter.get('kind') !== 'module') {+ problems.push(+ `${record.filePath}: modules reference ${moduleId} must resolve to a module record, not ${target.document.frontmatter.get('kind')}.`,+ );+ continue;+ }+ if (!activeRecord(target, activeAuthorities)) {+ problems.push(+ `${record.filePath}: modules reference ${moduleId} must resolve to an active module record.`,+ );+ continue;+ }+ if (target.document.frontmatter.get('parent_component') !== id) {+ problems.push(+ `${record.filePath}: modules reference ${moduleId}, but that module declares parent_component ${JSON.stringify(target.document.frontmatter.get('parent_component'))}.`,+ );+ }+ const targetLocation = componentRecordLocation(+ root,+ target.absolutePath,+ );+ if (+ targetLocation &&+ path.resolve(targetLocation.componentRootPath) !==+ path.resolve(location.componentRootPath)+ ) {+ problems.push(+ `${record.filePath}: module ${moduleId} must live in the same component root as its parent record (${target.filePath}).`,+ );+ }+ }+ continue;+ }++ if (kind !== 'module') continue;+ const parentId = frontmatter.get('parent_component');+ if (typeof parentId !== 'string') continue;+ const parents = recordsById.get(parentId) ?? [];+ if (parents.length === 0) {+ problems.push(+ `${record.filePath}: parent_component ${parentId} does not resolve to an active component record.`,+ );+ continue;+ }+ if (parents.length > 1) continue;+ const parent = parents[0];+ if (parent.document.frontmatter.get('kind') !== 'component') {+ problems.push(+ `${record.filePath}: parent_component ${parentId} must resolve to a component record, not ${parent.document.frontmatter.get('kind')}.`,+ );+ continue;+ }+ if (!activeRecord(parent, activeAuthorities)) {+ problems.push(+ `${record.filePath}: parent_component ${parentId} must resolve to an active component record.`,+ );+ continue;+ }++ const parentLocation = componentRecordLocation(root, parent.absolutePath);+ if (+ parentLocation &&+ path.resolve(parentLocation.componentRootPath) !==+ path.resolve(location.componentRootPath)+ ) {+ problems.push(+ `${record.filePath}: parent_component ${parentId} must be declared in the same component root (${parent.filePath}).`,+ );+ }++ const backlinks = Array.isArray(parent.document.frontmatter.get('modules'))+ ? parent.document.frontmatter+ .get('modules')+ .filter(moduleId => moduleId === id).length+ : 0;+ if (backlinks === 0) {+ problems.push(+ `${record.filePath}: module ${id} is orphaned; ${parent.filePath} must list it in modules.`,+ );+ } else if (backlinks > 1) {+ problems.push(+ `${record.filePath}: module ${id} is listed more than once by ${parent.filePath}.`,+ );+ }+ }++ return problems;}export function parseAnatomyThemingBlock(@@ -541,6 +825,71 @@ function loadComponentContract(root, specPath, componentName) {};}+function loadModuleContract(root, specPath, moduleName) {+ const location = componentRecordLocation(root, specPath);+ if (!location) {+ return {+ problem: `${path.relative(root, specPath)}: module record is outside a component root.`,+ };+ }++ const candidates = [];+ for (const docPath of matchingFilesRecursively(+ location.componentRootPath,+ name => name.endsWith('.doc.mjs'),+ {skipDirectory: isIgnoredComponentKnowledgeSegment},+ )) {+ let mod;+ try {+ mod = require(docPath);+ } catch (error) {+ return {+ problem: `${path.relative(root, docPath)}: could not load component doc (${error.message}).`,+ };+ }+ const doc = mod.docs ?? mod.default;+ if (!doc) continue;+ if (doc.name?.replace(/^XDS/, '') === moduleName) {+ candidates.push({docPath, doc});+ }+ for (const entry of doc.components ?? []) {+ if (+ entry?.name?.replace(/^XDS/, '') === moduleName &&+ isFullConsumerDocEntry(entry)+ ) {+ candidates.push({docPath, doc: entry});+ }+ }+ }++ if (candidates.length === 0) {+ return {+ problem: `${path.relative(root, specPath)}: no exact consumer doc entry for module ${moduleName}.`,+ };+ }+ if (candidates.length > 1) {+ return {+ problem: `${path.relative(root, specPath)}: module ${moduleName} has multiple consumer doc entries (${candidates.map(candidate => path.relative(root, candidate.docPath)).join(', ')}).`,+ };+ }++ const [{docPath, doc}] = candidates;+ if (!Array.isArray(doc.usage?.anatomy)) {+ return {+ problem: `${path.relative(root, docPath)}: ${moduleName} has no canonical English usage.anatomy; module records never inherit parent aggregate anatomy.`,+ };+ }+ const targets = (doc.theming?.targets ?? [])+ .filter(target => target.deprecatedFor == null)+ .map(target => target.className.replace(/^astryx-/, ''));+ return {+ contract: {+ anatomy: doc.usage.anatomy.map(part => part.name),+ targets,+ },+ };+}+function validateAgainstSchema(document,schema,@@ -926,17 +1275,21 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {`${filePath}: active ${kind} records must use latest schema_version ${latestKindVersion} for that kind.`,);}- if (document.frontmatter.get('kind') === 'component') {+ if (kind === 'component' || kind === 'module') {const parsed = parseAnatomyThemingBlock(content, filePath);problems.push(...parsed.problems);if (parsed.mapping != null) {if (isActiveRecord) {delegations.push(...collectDelegations(parsed.mapping, filePath));}- const componentName = String(document.frontmatter.get('id') ?? '')- .replace(/^component:/, '')- .replace(/\/.*$/, '');- const loaded = loadComponentContract(root, absolutePath, componentName);+ const recordName = String(document.frontmatter.get('id') ?? '')+ .replace(/^(?:component|module):/, '')+ .split('/')+ .at(-1);+ const loaded =+ kind === 'module'+ ? loadModuleContract(root, absolutePath, recordName)+ : loadComponentContract(root, absolutePath, recordName);if (loaded.problem) {problems.push(loaded.problem);} else {@@ -963,9 +1316,17 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {});}}- records.push({filePath, document});+ records.push({filePath, absolutePath, document});}+ problems.push(+ ...validateComponentModuleRelationships(+ root,+ records,+ schema.activeAuthorities,+ ),+ );+if (delegations.length > 0) {const activeFamilies = new Map();for (const {filePath, document} of records) {diff --git a/scripts/check-knowledge.test.mjs b/scripts/check-knowledge.test.mjsindex ca30a40249..311eabbea1 100644--- a/scripts/check-knowledge.test.mjs+++ b/scripts/check-knowledge.test.mjs@@ -28,7 +28,7 @@ function fixtureRoot() {path.join(root, 'docs/templates/knowledge'),{recursive: true},);- for (const version of ['v1.json', 'v2.json']) {+ for (const version of ['v1.json', 'v2.json', 'v3.json']) {fs.copyFileSync(path.join(repoRoot, `docs/schemas/knowledge/${version}`),path.join(root, `docs/schemas/knowledge/${version}`),@@ -73,7 +73,7 @@ function addSchemaVersion(root, version) {function componentRecord(overrides = {}) {const values = {- schema_version: '1',+ schema_version: '3',template_version: '1',kind: 'component',id: 'component:Button',@@ -85,6 +85,7 @@ function componentRecord(overrides = {}) {owners: '[owner]',review_triggers: '[behavior]',verified_by: '[Button.test.tsx]',+ modules: '[]',families: '[family:actions]',design_specs: '[design:actions]',architecture: '[architecture:components]',@@ -114,6 +115,46 @@ function componentRecord(overrides = {}) {return `---\n${frontmatter}\n---\n\n# Button component contract\n\n${sections}\n`;}+function moduleRecord(overrides = {}) {+ const values = {+ schema_version: '3',+ template_version: '1',+ kind: 'module',+ id: 'module:Button/useButtonThing',+ authority: 'draft',+ archive_reason: 'null',+ superseded_by: 'null',+ approved_by: 'null',+ approved_at: 'null',+ owners: '[owner]',+ review_triggers: '[public-api,behavior,accessibility]',+ verified_by: '[useButtonThing.test.ts]',+ parent_component: 'component:Button',+ references: '[]',+ ...overrides,+ };+ const frontmatter = Object.entries(values)+ .map(([key, value]) => `${key}: ${value}`)+ .join('\n');+ const sections = [+ 'Intent',+ 'Compatibility and migration',+ 'Ownership boundary',+ 'Public API and concepts',+ 'Behavioral contract',+ 'Accessibility contract',+ 'Design relationships',+ 'Parent and system relationships',+ 'Verification map',+ 'Decision log',+ 'Open questions',+ 'Content boundary',+ ]+ .map(section => `## ${section}\n\nBody.`)+ .join('\n\n');+ return `---\n${frontmatter}\n---\n\n# Button module contract\n\n${sections}\n`;+}+function themeRecord(overrides = {}) {const values = {schema_version: '2',@@ -753,6 +794,368 @@ describe('knowledge validation', () => {expect(await validateKnowledgeRoot(root)).toEqual([]);});+ it('accepts a flat public member record backed by the root consumer doc', async () => {+ const root = fixtureRoot();+ const directory = path.join(root, 'packages/core/src/NavMenu');+ fs.mkdirSync(directory);+ fs.writeFileSync(+ path.join(directory, 'NavMenu.doc.mjs'),+ "export const docs = {name: 'NavHeadingMenu'};\n",+ );+ fs.writeFileSync(+ path.join(directory, 'NavHeadingMenu.spec.md'),+ componentRecord({id: 'component:NavHeadingMenu'}),+ );++ expect(await validateKnowledgeRoot(root)).toEqual([]);+ });++ it('accepts a flat public member record backed by a full inline consumer entry', async () => {+ const root = fixtureRoot();+ const directory = path.join(root, 'packages/core/src/Table');+ fs.mkdirSync(directory);+ fs.writeFileSync(+ path.join(directory, 'Table.doc.mjs'),+ `export const docs = {+ name: 'Table',+ components: [{name: 'TableRow', description: 'A public row.', props: []}],+};\n`,+ );+ fs.writeFileSync(+ path.join(directory, 'TableRow.spec.md'),+ componentRecord({id: 'component:TableRow'}),+ );++ expect(await validateKnowledgeRoot(root)).toEqual([]);+ });++ it('rejects a flat component record unrelated to its component root', async () => {+ const root = fixtureRoot();+ const directory = path.join(root, 'packages/core/src/Button');+ fs.mkdirSync(directory);+ const parentDoc = writeButtonDoc(directory).replace(+ ' usage: {',+ " components: [{name: 'Wrong', projection: {anatomy: []}}],\n usage: {",+ );+ fs.writeFileSync(path.join(directory, 'Button.doc.mjs'), parentDoc);+ fs.writeFileSync(+ path.join(directory, 'Wrong.spec.md'),+ componentRecord({id: 'component:Wrong'}),+ );++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /flat component record component:Wrong must match component root "Button" or an exact public component entry/,+ );+ });++ it('discovers a nested module beside its flat parent and ignores non-record trees', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const modulePath = path.join(+ componentDirectory,+ 'plugins/thing/useButtonThing.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useButtonThing]'}),+ );+ fs.writeFileSync(modulePath, moduleRecord());++ const ignored = [+ '__fixtures__/fixture.spec.md',+ '__generated__/generated.spec.md',+ '__tests__/test.spec.md',+ '.hidden/hidden.spec.md',+ '.hidden.spec.md',+ 'fixtures/fixture.spec.md',+ 'generated/generated.spec.md',+ 'node_modules/dependency.spec.md',+ 'plugins/thing/snapshot.generated.spec.md',+ ];+ for (const relative of ignored) {+ const ignoredPath = path.join(componentDirectory, relative);+ fs.mkdirSync(path.dirname(ignoredPath), {recursive: true});+ fs.writeFileSync(ignoredPath, moduleRecord());+ }+ const topLevelIgnored = path.join(+ root,+ 'packages/core/src/__tests__/TopLevel.spec.md',+ );+ fs.mkdirSync(path.dirname(topLevelIgnored), {recursive: true});+ fs.writeFileSync(topLevelIgnored, moduleRecord());++ const discovered = discoverKnowledgeRecords(root).map(filePath =>+ path.relative(root, filePath).split(path.sep).join('/'),+ );+ expect(discovered).toContain('packages/core/src/Button/Button.spec.md');+ expect(discovered).toContain(+ 'packages/core/src/Button/plugins/thing/useButtonThing.spec.md',+ );+ for (const relative of ignored) {+ expect(discovered).not.toContain(`packages/core/src/Button/${relative}`);+ }+ expect(discovered).not.toContain(+ 'packages/core/src/__tests__/TopLevel.spec.md',+ );+ expect(await validateKnowledgeRoot(root)).toEqual([]);+ });++ it('rejects a nested component record instead of treating it as a module', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const nestedPath = path.join(componentDirectory, 'notes/Extra.spec.md');+ fs.mkdirSync(path.dirname(nestedPath), {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord(),+ );+ fs.writeFileSync(nestedPath, componentRecord({id: 'component:Extra'}));++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /nested records use kind: module/,+ );+ });++ it('rejects a direct-child module record', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ fs.mkdirSync(componentDirectory, {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useButtonThing]'}),+ );+ fs.writeFileSync(+ path.join(componentDirectory, 'useButtonThing.spec.md'),+ moduleRecord(),+ );++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /module records must be nested beneath their component root/,+ );+ });++ it('rejects missing parent links and orphan module records', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const modulePath = path.join(+ componentDirectory,+ 'plugins/orphan/useOrphan.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useMissing]'}),+ );+ fs.writeFileSync(+ modulePath,+ moduleRecord({+ id: 'module:Button/useOrphan',+ parent_component: 'component:Button',+ }),+ );++ const problems = (await validateKnowledgeRoot(root)).join('\n');+ expect(problems).toMatch(+ /modules reference module:Button\/useMissing does not resolve/,+ );+ expect(problems).toMatch(/module module:Button\/useOrphan is orphaned/);+ });++ it('rejects mismatched parent declarations and component roots', async () => {+ const root = fixtureRoot();+ const buttonDirectory = path.join(root, 'packages/core/src/Button');+ const otherDirectory = path.join(root, 'packages/core/src/Other');+ const modulePath = path.join(+ otherDirectory,+ 'plugins/thing/useButtonThing.spec.md',+ );+ fs.mkdirSync(buttonDirectory, {recursive: true});+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(+ path.join(buttonDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Other/useButtonThing]'}),+ );+ fs.writeFileSync(+ path.join(otherDirectory, 'Other.spec.md'),+ componentRecord({+ id: 'component:Other',+ modules: '[module:Other/useButtonThing]',+ }),+ );+ fs.writeFileSync(+ modulePath,+ moduleRecord({+ id: 'module:Other/useButtonThing',+ parent_component: 'component:Other',+ }),+ );++ const problems = (await validateKnowledgeRoot(root)).join('\n');+ expect(problems).toMatch(+ /Button\.spec\.md: modules reference module:Other\/useButtonThing, but that module declares parent_component "component:Other"/,+ );+ expect(problems).toMatch(/must live in the same component root/);+ });++ it('requires parent_component to resolve to a component record', async () => {+ const root = fixtureRoot();+ const familyTemplate = fs.readFileSync(+ path.join(root, 'docs/templates/knowledge/family-contract.md'),+ 'utf8',+ );+ fs.writeFileSync(+ path.join(root, 'docs/families/not-a-component.md'),+ familyTemplate.replace(+ 'id: family:<family-name>',+ 'id: component:Button',+ ),+ );+ const modulePath = path.join(+ root,+ 'packages/core/src/Button/plugins/thing/useButtonThing.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(modulePath, moduleRecord());++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /parent_component component:Button must resolve to a component record, not family/,+ );+ });++ it('requires parent module links to resolve to module records', async () => {+ const root = fixtureRoot();+ const familyTemplate = fs.readFileSync(+ path.join(root, 'docs/templates/knowledge/family-contract.md'),+ 'utf8',+ );+ fs.writeFileSync(+ path.join(root, 'docs/families/actions.md'),+ familyTemplate.replace('family:<family-name>', 'family:actions'),+ );+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ fs.mkdirSync(componentDirectory, {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[family:actions]'}),+ );++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /modules reference family:actions must resolve to a module record, not family/,+ );+ });++ it('rejects duplicate module links and duplicate module ids', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ fs.mkdirSync(componentDirectory, {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({+ modules: '[module:Button/useButtonThing,module:Button/useButtonThing]',+ }),+ );+ for (const owner of ['first', 'second']) {+ const modulePath = path.join(+ componentDirectory,+ `plugins/${owner}/useButtonThing.spec.md`,+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(modulePath, moduleRecord());+ }++ const problems = (await validateKnowledgeRoot(root)).join('\n');+ expect(problems).toMatch(/duplicate id module:Button\/useButtonThing/);+ expect(problems).toMatch(+ /modules contains duplicate reference module:Button\/useButtonThing/,+ );+ });++ it('requires module ids and filenames to encode the same public name', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const modulePath = path.join(+ componentDirectory,+ 'plugins/thing/WrongName.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useButtonThing]'}),+ );+ fs.writeFileSync(modulePath, moduleRecord());++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /module filename must be useButtonThing\.spec\.md/,+ );+ });++ it('validates module anatomy only against the module consumer doc', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const modulePath = path.join(+ componentDirectory,+ 'plugins/thing/useButtonThing.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useButtonThing]'}),+ );+ fs.writeFileSync(+ path.join(componentDirectory, 'useButtonThing.doc.mjs'),+ `export const docs = {+ name: 'useButtonThing',+ usage: {+ anatomy: [+ {name: 'Generated control', required: true, description: 'Generated UI.'},+ ],+ },+ theming: {+ targets: [{className: 'astryx-button-thing'}],+ },+};\n`,+ );+ fs.writeFileSync(+ modulePath,+ withAnatomyTheming(moduleRecord(), {+ 'Generated control': {target: 'button-thing'},+ }),+ );++ expect(await validateKnowledgeRoot(root)).toEqual([]);+ });++ it('never validates a module map against parent aggregate anatomy', async () => {+ const root = fixtureRoot();+ const componentDirectory = path.join(root, 'packages/core/src/Button');+ const modulePath = path.join(+ componentDirectory,+ 'plugins/thing/useButtonThing.spec.md',+ );+ fs.mkdirSync(path.dirname(modulePath), {recursive: true});+ const parentDoc = writeButtonDoc(componentDirectory).replace(+ ' usage: {',+ " components: [{name: 'useButtonThing'}],\n usage: {",+ );+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.doc.mjs'),+ parentDoc,+ );+ fs.writeFileSync(+ path.join(componentDirectory, 'Button.spec.md'),+ componentRecord({modules: '[module:Button/useButtonThing]'}),+ );+ fs.writeFileSync(+ modulePath,+ withAnatomyTheming(moduleRecord(), {Root: {target: 'button'}}),+ );++ expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(+ /no exact consumer doc entry for module useButtonThing/,+ );+ });+it('discovers only the exact canonical package-local theme record without placement errors', async () => {const root = fixtureRoot();fs.writeFileSync(@@ -1082,10 +1485,10 @@ describe('knowledge validation', () => {fs.mkdirSync(directory);fs.writeFileSync(path.join(directory, 'Button.spec.md'),- componentRecord({template_version: '4'}),+ componentRecord({template_version: '5'}),);expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(- /template_version 4 is newer than 3/,+ /template_version 5 is newer than 4/,);});@@ -1099,7 +1502,7 @@ describe('knowledge validation', () => {componentRecord({schema_version: '0'}),);expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(- /active component records must use latest schema_version 1 for that kind/,+ /active component records must use latest schema_version 3 for that kind/,);});