Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

ci: one list of record paths for check:knowledge, change classification and the spec-owner gate (#9469)

Cindy Zhang326614a7be99
diff --git a/.github/scripts/change-scope.cjs b/.github/scripts/change-scope.cjs
index 26440243d6..e3f302320c 100644
--- a/.github/scripts/change-scope.cjs
+++ b/.github/scripts/change-scope.cjs
@@ -6,8 +6,7 @@
// eslint-disable-next-line @typescript-eslint/no-require-imports
const {
isComponentSpecRecordPath,
- isLegacyComponentSpecPath,
- isPackageArchitectureRecordPath,
+ isOwnerGatedPath,
isPlatformComponentSpecPath,
} = require('./knowledge-paths.cjs');
@@ -105,18 +104,6 @@ function isSharedInfraPath(filePath) {
);
}
-const THEME_DOC_CANDIDATE = /^docs\/themes\/(?!README\.md$)[^/]+\.md$/;
-const THEME_PACKAGE_CANDIDATE =
- /^packages\/themes\/[^/]+\/(?:.*\/)?[^/]+\.spec\.md$/;
-
-const KNOWLEDGE_RECORD_PATTERNS = [
- ...SPEC_RECORD_PATTERNS,
- THEME_DOC_CANDIDATE,
- THEME_PACKAGE_CANDIDATE,
- /^docs\/architecture\/(?!README\.md$)[^/]+\.md$/,
- /^docs\/design\/assets\//,
-];
-
function isSpecRecordPath(filePath) {
return (
isComponentSpecRecordPath(filePath) ||
@@ -143,15 +130,13 @@ function isPackageReleasePath(filePath) {
return true;
}
+/**
+ * A path the spec-owner gate decides (knowledge-paths.cjs's owner-gated
+ * paths): every record, every Markdown file in a record location, and the
+ * normative design assets.
+ */
function isKnowledgeRecordPath(filePath) {
- return (
- isSpecRecordPath(filePath) ||
- // Not a record and never spec-only, but the owner gate must still see it.
- isLegacyComponentSpecPath(filePath) ||
- // A package's architecture record, owner-gated like docs/architecture/.
- isPackageArchitectureRecordPath(filePath) ||
- KNOWLEDGE_RECORD_PATTERNS.some(pattern => pattern.test(filePath))
- );
+ return isOwnerGatedPath(filePath);
}
function isNodeToolingPath(filePath) {
@@ -307,25 +292,55 @@ function parseNameStatus(input) {
});
}
+/**
+ * Each path's record classes, for a caller outside this workflow: whether it
+ * counts toward a spec-only change (`specRecord`) and whether its change needs
+ * a spec owner's approval (`ownerGatedRecord`). Reads the paths alone.
+ *
+ * @param {string[]} paths
+ * @returns {Record<string, {specRecord: boolean, ownerGatedRecord: boolean}>}
+ */
+function classifyPaths(paths) {
+ return Object.fromEntries(
+ paths.map(filePath => [
+ filePath,
+ {
+ specRecord: isSpecRecordPath(filePath),
+ ownerGatedRecord: isOwnerGatedPath(filePath),
+ },
+ ]),
+ );
+}
+
if (require.main === module) {
// eslint-disable-next-line @typescript-eslint/no-require-imports
const fs = require('node:fs');
- const result = classifyChanges(parseNameStatus(fs.readFileSync(0, 'utf8')));
- if (result.specChangesetConflict) {
- console.error(
- 'Pure spec-record changes must not add a Changeset; they do not release packages.',
- );
- process.exitCode = 1;
- } else if (process.argv.includes('--github-output')) {
- const outputPath = process.env.GITHUB_OUTPUT;
- if (!outputPath)
- throw new Error('GITHUB_OUTPUT is required with --github-output.');
- fs.appendFileSync(
- outputPath,
- `spec_only=${result.specOnly}\ndocsite_only=${result.docsiteOnly}\ntooling_only=${result.toolingOnly}\nlab_only=${result.labOnly}\nfull_suite=${result.fullSuite}\n`,
- );
+ // `--classify-paths`: newline-separated paths on stdin, JSON on stdout.
+ if (process.argv.includes('--classify-paths')) {
+ const paths = fs
+ .readFileSync(0, 'utf8')
+ .split(/\r?\n/)
+ .map(line => line.trim())
+ .filter(Boolean);
+ process.stdout.write(`${JSON.stringify(classifyPaths(paths))}\n`);
} else {
- process.stdout.write(`${JSON.stringify(result)}\n`);
+ const result = classifyChanges(parseNameStatus(fs.readFileSync(0, 'utf8')));
+ if (result.specChangesetConflict) {
+ console.error(
+ 'Pure spec-record changes must not add a Changeset; they do not release packages.',
+ );
+ process.exitCode = 1;
+ } else if (process.argv.includes('--github-output')) {
+ const outputPath = process.env.GITHUB_OUTPUT;
+ if (!outputPath)
+ throw new Error('GITHUB_OUTPUT is required with --github-output.');
+ fs.appendFileSync(
+ outputPath,
+ `spec_only=${result.specOnly}\ndocsite_only=${result.docsiteOnly}\ntooling_only=${result.toolingOnly}\nlab_only=${result.labOnly}\nfull_suite=${result.fullSuite}\n`,
+ );
+ } else {
+ process.stdout.write(`${JSON.stringify(result)}\n`);
+ }
}
}
@@ -334,6 +349,7 @@ module.exports = {
NODE_TOOLING_PATHS,
SURFACES,
classifyChanges,
+ classifyPaths,
isKnowledgeRecordPath,
isNodeToolingPath,
isPackageReleasePath,
diff --git a/.github/scripts/change-scope.test.mjs b/.github/scripts/change-scope.test.mjs
index 36e888d2b6..d1cb036530 100644
--- a/.github/scripts/change-scope.test.mjs
+++ b/.github/scripts/change-scope.test.mjs
@@ -71,10 +71,13 @@ describe('spec-only change scope', () => {
]);
expect(result.touchesKnowledgeRecords).toBe(true);
expect(result.specOnly).toBe(false);
- expect(
- classifyChanges([{filename: 'packages/native/specs/README.md'}])
- .touchesKnowledgeRecords,
- ).toBe(false);
+ // Every Markdown file under a package's specs/ is owner-gated, a README
+ // too, though only records count toward a spec-only change.
+ const readme = classifyChanges([
+ {filename: 'packages/native/specs/README.md'},
+ ]);
+ expect(readme.touchesKnowledgeRecords).toBe(true);
+ expect(readme.specOnly).toBe(false);
});
it('owner-gates architecture records without granting the spec-only fast path', () => {
diff --git a/.github/scripts/knowledge-paths.cjs b/.github/scripts/knowledge-paths.cjs
index 5b37061f85..902904ebed 100644
--- a/.github/scripts/knowledge-paths.cjs
+++ b/.github/scripts/knowledge-paths.cjs
@@ -378,6 +378,86 @@ function componentSpecPathForSource(packageName, relativePath) {
return `${COMPONENT_SPEC_ROOT}/${segments.join('/')}`;
}
+/**
+ * A knowledge record `check:knowledge` discovers and validates: a system spec
+ * or plan, a family, architecture or design record, a theme record, a
+ * package's own architecture record, or a component or module record.
+ * `scripts/check-knowledge.mjs` reads records through this predicate, and its
+ * test pins it to the tool's discovery.
+ */
+function isKnowledgeRecordPath(filePath) {
+ const normalized = normalizePath(filePath);
+ if (/^docs\/(?:architecture|design|families)\/[^/]+\.md$/.test(normalized)) {
+ return !normalized.endsWith('/README.md');
+ }
+ if (/^docs\/specs\/[^/]+\/(?:spec|plan)\.md$/.test(normalized)) {
+ return true;
+ }
+ const themeMatch = /^packages\/themes\/([^/]+)\/([^/]+)\.spec\.md$/.exec(
+ normalized,
+ );
+ if (themeMatch) return themeMatch[1] === themeMatch[2];
+ if (classifyPackageArchitectureRecordPath(normalized)) return true;
+ return isComponentSpecRecordPath(normalized);
+}
+
+/**
+ * A file `check:knowledge` validates as a record of its own: a knowledge
+ * record or a platform component record. Its front matter states its
+ * authority.
+ */
+function isValidatedRecordPath(filePath) {
+ return (
+ isKnowledgeRecordPath(filePath) || isPlatformComponentSpecPath(filePath)
+ );
+}
+
+/**
+ * A path whose change needs a spec owner's approval: every validated record;
+ * every Markdown file in a record location, whether a record or not (a
+ * generated table beside a spec, a draft or README under a package's
+ * `specs/`); theme record candidates `check:knowledge` rejects as misplaced;
+ * a component spec at a legacy location; and the normative design assets.
+ * Ignored locations (isIgnoredKnowledgeLocation) stay ignored.
+ */
+const OWNER_GATED_PATTERNS = Object.freeze([
+ /^docs\/specs\/.+\.md$/,
+ /^docs\/(?:architecture|design|families)\/(?!README\.md$)[^/]+\.md$/,
+ /^docs\/design\/assets\//,
+ /^docs\/themes\/(?!README\.md$)[^/]+\.md$/,
+ /^packages\/themes\/[^/]+\/(?:.*\/)?[^/]+\.spec\.md$/,
+ /^packages\/[^/]+\/specs\/.+\.md$/,
+ /^packages\/[^/]+\/docs\/architecture\/.+\.md$/,
+]);
+
+/**
+ * A hidden, fixture, test, generated, build-output, coverage or dependency
+ * path, or a `*.generated.spec.md`: discovery and pull-request routing ignore
+ * it everywhere (`architecture:knowledge-contracts`).
+ */
+function isIgnoredKnowledgeLocation(filePath) {
+ const segments = normalizePath(filePath).split('/');
+ const fileName = segments.pop();
+ return (
+ fileName.startsWith('.') ||
+ fileName.endsWith('.generated.spec.md') ||
+ segments.some(
+ segment =>
+ segment.startsWith('.') || isIgnoredComponentKnowledgeSegment(segment),
+ )
+ );
+}
+
+function isOwnerGatedPath(filePath) {
+ const normalized = normalizePath(filePath);
+ return (
+ isValidatedRecordPath(normalized) ||
+ isLegacyComponentSpecPath(normalized) ||
+ (!isIgnoredKnowledgeLocation(normalized) &&
+ OWNER_GATED_PATTERNS.some(pattern => pattern.test(normalized)))
+ );
+}
+
module.exports = {
COMPONENT_PACKAGE_NAMES,
COMPONENT_SPEC_ROOT,
@@ -390,9 +470,12 @@ module.exports = {
componentSpecPathForSource,
isComponentSpecRecordPath,
isIgnoredComponentKnowledgeSegment,
+ isKnowledgeRecordPath,
isLegacyComponentSpecPath,
+ isOwnerGatedPath,
isPackageArchitectureRecordPath,
isPlatformComponentSpecPath,
+ isValidatedRecordPath,
locateComponentKnowledgePath,
locatePlatformComponentSource,
resolveComponentPackage,
diff --git a/.github/scripts/knowledge-paths.test.mjs b/.github/scripts/knowledge-paths.test.mjs
index a9cc948d34..c0cc32c628 100644
--- a/.github/scripts/knowledge-paths.test.mjs
+++ b/.github/scripts/knowledge-paths.test.mjs
@@ -281,3 +281,150 @@ describe('component record location', () => {
).toBeNull();
});
});
+
+describe('record paths: one list for check:knowledge, change classification and the owner gate', () => {
+ const {
+ isKnowledgeRecordPath,
+ isOwnerGatedPath,
+ } = require('./knowledge-paths.cjs');
+ const {
+ classifyPaths,
+ isKnowledgeRecordPath: gatedByScope,
+ } = require('./change-scope.cjs');
+ const root = path.resolve(import.meta.dirname, '../..');
+ const tracked = require('node:child_process')
+ .execFileSync('git', ['ls-files', '-z'], {
+ cwd: root,
+ encoding: 'utf8',
+ maxBuffer: 256 * 1024 * 1024,
+ })
+ .split('\0')
+ .filter(Boolean);
+ const relative = files =>
+ files.map(file => path.relative(root, file).split(path.sep).join('/'));
+
+ it('names exactly the records check:knowledge discovers, and gates every one', async () => {
+ const {discoverKnowledgeRecords, discoverPlatformComponentRecords} =
+ await import('../../scripts/check-knowledge.mjs');
+ const discovered = relative(discoverKnowledgeRecords(root)).sort();
+ expect(tracked.filter(file => isKnowledgeRecordPath(file)).sort()).toEqual(
+ discovered,
+ );
+ const platform = relative(discoverPlatformComponentRecords(root)).sort();
+ expect(
+ tracked.filter(file => isPlatformComponentSpecPath(file)).sort(),
+ ).toEqual(platform);
+ for (const record of [...discovered, ...platform]) {
+ expect(isOwnerGatedPath(record), record).toBe(true);
+ }
+ });
+
+ it('the spec-owner gate decides exactly the owner-gated paths', () => {
+ for (const file of tracked) {
+ expect(gatedByScope(file), file).toBe(isOwnerGatedPath(file));
+ }
+ });
+
+ it.each([
+ // A generated record table beside a spec, with the code that writes it.
+ [
+ 'a generated table beside a spec',
+ [
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',
+ 'package.json',
+ 'packages/core/src/motion/roles.test.ts',
+ 'scripts/generate-motion-roles.mjs',
+ 'scripts/motion-roles-table.d.mts',
+ 'scripts/motion-roles-table.mjs',
+ ],
+ {
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md': {
+ specRecord: false,
+ ownerGatedRecord: true,
+ },
+ },
+ ],
+ // A platform record with its Swift view and tests.
+ [
+ 'a platform record',
+ [
+ 'docs/specs/components/Avatar/Avatar.swift.spec.md',
+ 'packages/native/apple/Sources/Astryx/Avatar/Avatar.swift',
+ 'packages/native/apple/Tests/AstryxTests/AvatarTests.swift',
+ ],
+ {
+ 'docs/specs/components/Avatar/Avatar.swift.spec.md': {
+ specRecord: true,
+ ownerGatedRecord: true,
+ },
+ },
+ ],
+ ])('%s needs a spec owner, and its code does not', (_, files, records) => {
+ const classified = classifyPaths(files);
+ for (const file of files) {
+ expect(classified[file], file).toEqual(
+ records[file] ?? {specRecord: false, ownerGatedRecord: false},
+ );
+ }
+ });
+
+ it.each([
+ 'docs/specs/AST-030/spec.md',
+ 'docs/specs/AST-030/plan.md',
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',
+ 'docs/specs/README.md',
+ 'docs/specs/components/Button/Button.spec.md',
+ 'docs/specs/components/Button/notes.md',
+ 'docs/families/action-groups.md',
+ 'docs/design/motion.md',
+ 'docs/design/assets/selector/alignment.png',
+ 'docs/architecture/knowledge-contracts.md',
+ 'docs/themes/neutral.md',
+ 'packages/themes/neutral/neutral.spec.md',
+ 'packages/themes/neutral/subdir/neutral.spec.md',
+ 'packages/native/specs/README.md',
+ 'packages/native/specs/TEMPLATE.md',
+ 'packages/native/specs/swift/library/accessibility.md',
+ 'packages/native/specs/swift/library/tooltip.spec.md',
+ 'packages/core/docs/architecture/runtime.md',
+ 'packages/core/src/Selector/Selector.spec.md',
+ ])('gates %s', file => {
+ expect(isOwnerGatedPath(file)).toBe(true);
+ });
+
+ it.each([
+ 'docs/architecture/README.md',
+ 'docs/families/README.md',
+ 'docs/design/README.md',
+ 'docs/themes/README.md',
+ 'docs/specs/components/__tests__/TopLevel.spec.md',
+ 'docs/specs/components/Selector/__fixtures__/fixture.spec.md',
+ 'docs/specs/components/Selector/.hidden/Hidden.spec.md',
+ 'docs/specs/components/Selector/generated/fake.spec.md',
+ 'docs/specs/components/Selector/plugins/fake.generated.spec.md',
+ 'docs/contributing/spec-writing.md',
+ 'docs/schemas/knowledge/component.schema.json',
+ 'packages/core/src/Button/Button.tsx',
+ ])('leaves %s ungated', file => {
+ expect(isOwnerGatedPath(file)).toBe(false);
+ });
+
+ it('classifies paths from the command line for callers outside the workflow', () => {
+ const output = require('node:child_process').execFileSync(
+ process.execPath,
+ [path.join(root, '.github/scripts/change-scope.cjs'), '--classify-paths'],
+ {
+ input:
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md\npackage.json\n',
+ encoding: 'utf8',
+ },
+ );
+ expect(JSON.parse(output)).toEqual({
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md': {
+ specRecord: false,
+ ownerGatedRecord: true,
+ },
+ 'package.json': {specRecord: false, ownerGatedRecord: false},
+ });
+ });
+});
diff --git a/.github/scripts/spec-owner-decision.cjs b/.github/scripts/spec-owner-decision.cjs
index dac446a798..2334f136a9 100644
--- a/.github/scripts/spec-owner-decision.cjs
+++ b/.github/scripts/spec-owner-decision.cjs
@@ -242,6 +242,89 @@ function approvalGroupFor(content, filePath) {
return 'spec';
}
+/**
+ * The `authority` the file's leading fields state, or null: the front-matter
+ * block when there is one, else the `key: value` lines it opens with. A
+ * README may show a front-matter example in its body; that never counts.
+ */
+function leadingAuthority(content) {
+ if (content == null) return null;
+ const block = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+ let lines;
+ if (block) {
+ lines = block[1].split(/\r?\n/);
+ } else {
+ const all = content.split(/\r?\n/);
+ const end = all.findIndex(line => !/^[a-z_]+:\s/.test(line));
+ lines = end === -1 ? all : all.slice(0, end);
+ }
+ for (const line of lines) {
+ const match = /^authority:\s*['"]?([a-z-]+)['"]?\s*$/.exec(line);
+ if (match) return match[1];
+ }
+ return null;
+}
+
+/**
+ * The owner groups one changed record or owner-gated file needs: a set of
+ * `spec`, `design` and `theme`, empty when none (a draft record, a design
+ * asset whose group comes from the change's own flag).
+ */
+function recordApprovalGroups(record) {
+ const groups = new Set();
+ const versions = [
+ {content: record.baseContent, path: record.previousPath ?? record.path},
+ {content: record.headContent, path: record.path},
+ ];
+ // An owner-gated Markdown file with no authority of its own (a generated
+ // table beside a spec, a README or draft note in a record location) has
+ // nothing for the gate to read, so an engineering owner decides it.
+ if (
+ versions.some(
+ version =>
+ typeof version.path === 'string' &&
+ version.path.endsWith('.md') &&
+ !version.path.startsWith('docs/design/assets/'),
+ ) &&
+ versions.every(version => leadingAuthority(version.content) == null) &&
+ versions.some(version => version.content != null)
+ ) {
+ groups.add('spec');
+ return groups;
+ }
+ const currentVersions = versions.filter(
+ version => parseAuthority(version.content, version.path) === 'current',
+ );
+ if (currentVersions.length === 0) return groups;
+
+ const touchesComponentOrModule = versions.some(version => {
+ const kind = parseKind(version.content, version.path);
+ return kind === 'component' || kind === 'module';
+ });
+ if (touchesComponentOrModule) {
+ const change = classifyDesignDecisionChange({
+ basePath: record.previousPath ?? record.path,
+ headPath: record.path,
+ baseContent: record.baseContent,
+ headContent: record.headContent,
+ });
+ if (change.classification === 'dd-only') {
+ groups.add('design');
+ } else if (change.classification === 'mixed') {
+ groups.add('spec');
+ groups.add('design');
+ } else {
+ groups.add('spec');
+ }
+ return groups;
+ }
+
+ for (const version of currentVersions) {
+ groups.add(approvalGroupFor(version.content, version.path));
+ }
+ return groups;
+}
+
function requiredApprovalGroups(
records,
{complete = true, touchesDesignAssets = false} = {},
@@ -249,40 +332,7 @@ function requiredApprovalGroups(
if (!complete) return {spec: true, design: true, theme: true};
const groups = {spec: false, design: touchesDesignAssets, theme: false};
for (const record of records) {
- const versions = [
- {content: record.baseContent, path: record.previousPath ?? record.path},
- {content: record.headContent, path: record.path},
- ];
- const currentVersions = versions.filter(
- version => parseAuthority(version.content, version.path) === 'current',
- );
- if (currentVersions.length === 0) continue;
-
- const touchesComponentOrModule = versions.some(version => {
- const kind = parseKind(version.content, version.path);
- return kind === 'component' || kind === 'module';
- });
- if (touchesComponentOrModule) {
- const change = classifyDesignDecisionChange({
- basePath: record.previousPath ?? record.path,
- headPath: record.path,
- baseContent: record.baseContent,
- headContent: record.headContent,
- });
- if (change.classification === 'dd-only') {
- groups.design = true;
- } else if (change.classification === 'mixed') {
- groups.spec = true;
- groups.design = true;
- } else {
- groups.spec = true;
- }
- continue;
- }
-
- for (const version of currentVersions) {
- groups[approvalGroupFor(version.content, version.path)] = true;
- }
+ for (const group of recordApprovalGroups(record)) groups[group] = true;
}
return groups;
}
@@ -400,6 +450,8 @@ module.exports = {
parseOwnerCommandIntent,
parseOwnerCommandTarget,
parseOwnerFile,
+ leadingAuthority,
+ recordApprovalGroups,
requiredApprovalGroups,
requiresOwnerApproval,
resolveOwnerDecision,
diff --git a/.github/scripts/spec-owner-decision.test.mjs b/.github/scripts/spec-owner-decision.test.mjs
index 410fe2805a..d8b9ae1cab 100644
--- a/.github/scripts/spec-owner-decision.test.mjs
+++ b/.github/scripts/spec-owner-decision.test.mjs
@@ -87,6 +87,79 @@ describe('spec owner decision', () => {
expect(requiresOwnerApproval([], {complete: false})).toBe(true);
});
+ it('requires an engineering owner for an owner-gated file with no authority of its own', () => {
+ const {
+ requiredApprovalGroups: groupsFor,
+ } = require('./spec-owner-decision.cjs');
+ // A generated table beside a spec: no front matter, so an engineering
+ // owner decides it.
+ expect(
+ groupsFor([
+ {
+ path: 'docs/specs/AST-094-touch-presentations/motion-roles.md',
+ previousPath:
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',
+ baseContent: '# Motion roles\n',
+ headContent: '# Motion roles\n\n| role |\n',
+ },
+ ]),
+ ).toEqual({spec: true, design: false, theme: false});
+ // A README whose body shows a front-matter example still has no
+ // authority of its own, even with two example lines.
+ const example = [
+ '# Native specs',
+ '',
+ '```md',
+ '---',
+ 'authority: draft',
+ '---',
+ '```',
+ '',
+ '```md',
+ '---',
+ 'authority: current',
+ '---',
+ '```',
+ '',
+ ].join('\n');
+ expect(
+ groupsFor([
+ {
+ path: 'packages/native/specs/README.md',
+ previousPath: 'packages/native/specs/README.md',
+ baseContent: example,
+ headContent: `${example}More.\n`,
+ },
+ ]),
+ ).toEqual({spec: true, design: false, theme: false});
+ // Added, too.
+ expect(
+ groupsFor([
+ {
+ path: 'packages/native/specs/swift/library/notes.md',
+ baseContent: null,
+ headContent: '# Notes\n',
+ },
+ ]).spec,
+ ).toBe(true);
+ // A draft record still needs no approval, and a design asset goes to the
+ // design group through its own flag.
+ expect(
+ groupsFor([
+ {
+ path: 'docs/specs/AST-999/spec.md',
+ baseContent: null,
+ headContent: 'authority: draft\n',
+ },
+ {
+ path: 'docs/design/assets/x.png',
+ baseContent: null,
+ headContent: null,
+ },
+ ]),
+ ).toEqual({spec: false, design: false, theme: false});
+ });
+
it('requires an engineering owner when a platform record becomes current', () => {
const swiftRecord = authority =>
[
diff --git a/.github/scripts/spec-owner-reconcile.cjs b/.github/scripts/spec-owner-reconcile.cjs
index bf2fcf7edf..787f75a52a 100644
--- a/.github/scripts/spec-owner-reconcile.cjs
+++ b/.github/scripts/spec-owner-reconcile.cjs
@@ -17,8 +17,8 @@ const {
describeOwnerCommandProblem,
newestGateRun,
parseOwnerCommandIntent,
- parseAuthority,
- parseKind,
+ leadingAuthority,
+ recordApprovalGroups,
parseOwnerFile,
requiredApprovalGroups,
resolveOwnerDecision,
@@ -455,31 +455,23 @@ async function reconcileWithinBudget({
commandProblem,
}) {
if (typeof core.summary?.addRaw !== 'function') return;
+ // The same per-record rule the decision uses, so the two never disagree.
const groupFor = record => {
- const current =
- parseAuthority(record.headContent, record.path) === 'current' ||
- parseAuthority(record.baseContent, record.previousPath) === 'current';
- if (!current) return 'none (draft)';
- const kind = parseKind(
- record.headContent ?? record.baseContent,
- record.path,
- );
- return kind === 'design' || kind === 'theme'
- ? 'design or eng owner'
- : 'eng owner';
+ const groups = recordApprovalGroups(record);
+ if (groups.size === 0) return 'none (draft)';
+ return groups.has('spec') ? 'eng owner' : 'design or eng owner';
};
+ const authorityOf = content => leadingAuthority(content) ?? 'no authority';
const rows = changedRecords.map(record => {
const text = record.headContent ?? record.baseContent ?? '';
const id = text.match(/^id:\s*(.+)$/m)?.[1]?.trim() ?? record.path;
const title = text.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? '';
const before =
- record.baseContent == null
- ? 'new'
- : (parseAuthority(record.baseContent, record.previousPath) ?? '?');
+ record.baseContent == null ? 'new' : authorityOf(record.baseContent);
const after =
record.headContent == null
? 'removed'
- : (parseAuthority(record.headContent, record.path) ?? '?');
+ : authorityOf(record.headContent);
const change = before === after ? after : `${before} → ${after}`;
return `| \`${id}\` | ${title} | ${change} | ${groupFor(record)} |`;
});
diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjs
index 93dce03125..7c7f910126 100644
--- a/.github/scripts/spec-owner-reconcile.test.mjs
+++ b/.github/scripts/spec-owner-reconcile.test.mjs
@@ -378,6 +378,53 @@ function createDesignHarness(options = {}) {
}
describe('spec owner workflow reconciliation', () => {
+ it.each([
+ [
+ 'a generated table beside a spec',
+ 'docs/specs/AST-094-touch-presentations/motion-roles.md',
+ '<!-- Generated. Do not edit. -->\n\n# Motion roles\n\n| role |\n',
+ ],
+ [
+ 'a README that shows front-matter examples',
+ 'packages/native/specs/README.md',
+ [
+ '# Native specs',
+ '',
+ '```md',
+ '---',
+ 'authority: draft',
+ '---',
+ '```',
+ '',
+ '```md',
+ '---',
+ 'authority: current',
+ '---',
+ '```',
+ '',
+ ].join('\n'),
+ ],
+ ])(
+ 'waits for an engineering owner on %s, and its details say so',
+ async (_, filename, headContent) => {
+ const harness = createHarness({
+ changedFile: {filename, status: 'modified'},
+ baseContent: '# Before\n',
+ headContent,
+ });
+
+ await run(harness, context({runId: 100n, action: 'synchronize'}));
+
+ expect(latestGateStatus(harness.state)).toMatchObject({
+ state: 'pending',
+ description: 'Mirrors review-required · spec waiting (eng)',
+ });
+ expect(harness.state.summary).toContain('| eng owner |');
+ expect(harness.state.summary).toContain('no authority');
+ expect(harness.state.summary).not.toContain('none (draft)');
+ },
+ );
+
it('skips the owner reads and the label call for a pull request that changes no records', async () => {
const harness = createHarness({
changedFile: {filename: 'README.md', status: 'modified'},
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 270ac01abd..71a1994b57 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -864,14 +864,25 @@ this flow passes the historical review benchmark and is enforced on pull request
component/module changes as no DD change, DD-only, or mixed from trusted base
and head bytes. DD-only requires unchanged path, kind, authority, and every byte
outside a valid optional block.
-- `.github/scripts/change-scope.cjs` identifies pure spec-record changes.
+- `.github/scripts/knowledge-paths.cjs` holds the one list of record paths.
+ It names the records `check:knowledge` discovers and the owner-gated paths:
+ every record; every Markdown file under `docs/specs/` or a package's
+ `specs/` or `docs/architecture/`, READMEs included; every Markdown file in
+ the family, design, architecture and theme-docs folders except each
+ folder's `README.md` index; every `*.spec.md` in a theme package; and the
+ normative design assets. Ignored locations stay ignored.
+- `.github/scripts/change-scope.cjs` identifies pure spec-record changes and
+ the owner-gated paths a change touches, and classifies paths for callers
+ outside the workflow (`--classify-paths`).
- `.github/workflows/review-signal.yml` publishes the one review gate,
`review-required`, which carries spec-owner approval too (DEC-14). One owner approval covers every knowledge-record change in the pull
request and binds the approved spec content, not a commit. Approval for every
record kind derives from `.github/ENGOWNERS`; current design and theme records,
normative design assets, and DD-only current component/module changes
additionally accept `.github/DESIGNOWNERS`. A mixed DD plus other
- component/module edit requires both groups. Record metadata never
+ component/module edit requires both groups. An owner-gated Markdown file with
+ no authority of its own, such as a generated table beside a spec, requires an
+ engineering owner. Record metadata never
self-authorizes. The gate decides approval only; it never enables auto-merge.
- `.github/workflows/review-signal.yml` lets a DESIGNOWNER author bypass the
engineering gate only when trusted-base code verifies every changed Core line
@@ -1146,12 +1157,12 @@ checks, the owner gate, and path routing.
A spec owner reviews a pull request's knowledge-record changes together and
approves or reworks them as a whole. The approval binds the **spec content**:
-one fingerprint over every changed knowledge-record and normative design-asset
-path, each read at a commit. In Markdown records the fingerprint omits the
-front-matter `authority`, `approved_by`, and `approved_at` values, so recording
-an approval and moving a record from `draft` to `current` never change it. The
-workflow computes every fingerprint from the pull request's files; no comment,
-label, or status supplies it.
+one fingerprint over every changed owner-gated path, each read at a commit. In
+Markdown records the fingerprint omits the front-matter `authority`,
+`approved_by`, and `approved_at` values, so recording an approval and moving a
+record from `draft` to `current` never change it. The workflow computes every
+fingerprint from the pull request's files; no comment, label, or status
+supplies it.
- **Approving acts.** Each of these, by an eligible owner, approves the content
of the commit it names, and counts while that commit's fingerprint equals the
@@ -1253,22 +1264,22 @@ because the reader never sees the hook wired.
## Verification
-| Invariant | Evidence | Failure signal |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |
-| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |
-| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |
-| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |
-| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |
-| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |
-| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |
-| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |
-| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |
-| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |
-| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |
-| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |
-| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/spec-owner-workflow.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; or an evaluation leaves its head without a terminal state |
-| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |
+| Invariant | Evidence | Failure signal |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |
+| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |
+| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |
+| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |
+| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |
+| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |
+| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |
+| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |
+| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |
+| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |
+| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |
+| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |
+| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |
+| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |
| Invariant | Evidence | Failure signal |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjs
index 427e509297..d486d78f7f 100644
--- a/scripts/check-knowledge.mjs
+++ b/scripts/check-knowledge.mjs
@@ -37,6 +37,7 @@ const {
componentSpecPathForSource,
isComponentSpecRecordPath,
isIgnoredComponentKnowledgeSegment,
+ isKnowledgeRecordPath,
isPlatformComponentSpecPath,
locateComponentKnowledgePath,
} = require('../.github/scripts/knowledge-paths.cjs');
@@ -528,21 +529,6 @@ function repositoryFileList(root) {
}
}
-function isKnowledgeRecordPath(filePath) {
- if (/^docs\/(?:architecture|design|families)\/[^/]+\.md$/.test(filePath)) {
- return !filePath.endsWith('/README.md');
- }
- if (/^docs\/specs\/[^/]+\/(?:spec|plan)\.md$/.test(filePath)) {
- return true;
- }
- const themeMatch = /^packages\/themes\/([^/]+)\/([^/]+)\.spec\.md$/.exec(
- filePath,
- );
- if (themeMatch) return themeMatch[1] === themeMatch[2];
- if (classifyPackageArchitectureRecordPath(filePath)) return true;
- return isComponentSpecRecordPath(filePath);
-}
-
const REVIEW_CONCERN_NAME_PATTERN = REVIEW_TRIGGER_PATTERN;
const IDENTIFIER_PATTERN = /^[A-Za-z_$][\w$]*$/;