Skip to content

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.cjs
index 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.mjs
index 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.cjs
new file mode 100644
index 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.mjs
new file mode 100644
index 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.mjs
index 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.mjs
index 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.yml
index 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 0
fi
- 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; then
git diff --name-status "$MERGE_BASE"...HEAD \
| node "$CLASSIFIER" --github-output
else
diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml
index 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 0
fi
- 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; then
git diff --name-status "$MERGE_BASE"...HEAD \
| node "$CLASSIFIER" --github-output
else
diff --git a/AGENTS.md b/AGENTS.md
index 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.md
index 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.md
index 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 the
cross-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:
```text
changed 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 contrast
methodology stays in design; shared measurement implementation stays in
architecture/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 applicable
decision 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 record
of 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 runs
normal CI.
- **INV8 — Private operations stay private.** Public records never name or link
@@ -110,9 +115,10 @@ Every record is either:
### When current records disagree
1. 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 by
recency, 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 that
verify 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 new
decision and receives approval.
@@ -171,7 +177,7 @@ canonical decision.
Record the durable outcome, not the review transcript. A ruling belongs in a
canonical 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 or
an 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's
canonical 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.json
new file mode 100644
index 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.md
index 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: 4
kind: component
id: component:<Name>
authority: draft
@@ -11,6 +11,7 @@ approved_at: null
owners: [<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 map
diff --git a/docs/templates/knowledge/module-spec.md b/docs/templates/knowledge/module-spec.md
new file mode 100644
index 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.json
index 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 1
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: component:Icon
@@ -11,6 +11,7 @@ approved_at: 2026-08-30
owners: [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.md
index 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: 3
template_version: 3
kind: component
id: component:Kbd
@@ -11,6 +11,7 @@ approved_at: null
owners: [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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.md
index 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: 3
template_version: 3
kind: component
id: 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.mjs
index 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.mjs
index 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/,
);
});