Skip to content

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

TypeScript

chore(knowledge): validate path-applicability blocks and fail unreached current records (#7795)

Cindy Zhang7bda21ec219b
diff --git a/docs/README.md b/docs/README.md
index a4ef917d58..abd06da414 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -111,6 +111,18 @@ base authority commit is its `origin/main` merge base, includes only
`authority: current` records, and returns only the matched claims; draft records
and nonmatching routes are omitted.
+An optional `path-applicability:v1` JSON block lists the repository paths a
+record governs when no placement, path field, name, or inherited link reaches
+them: `{"paths": ["apps/docsite/**"]}`. Patterns are repository-relative globs:
+`**` is a whole segment spanning any depth, `*` matches within one segment, and
+`?` matches one character. Like `review-applicability:v1`, it is an
+independently versioned overlay, so opting in does not migrate a record kind.
+A pattern must start with a literal path segment. Validation rejects
+malformed, unsafe, repeated, whole-repository, and no-match patterns. A match only locates the record for a path; claim scope and
+precedence are unchanged. `pnpm check:knowledge` also fails when a current record
+is reached from no tracked path that is not itself a record
+(`architecture:knowledge-contracts` INV25 and INV26).
+
New record kinds should prefer one typed relationship list over parallel fields.
If `system-spec` receives a future schema revision, replace its legacy
`affects_*` fields with one typed `affects` list containing ids such as
diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjs
index 0289467da8..659348f57e 100644
--- a/scripts/check-knowledge.mjs
+++ b/scripts/check-knowledge.mjs
@@ -132,6 +132,8 @@ export function parseKnowledgeDocument(content, filePath = '<document>') {
}
const REVIEW_APPLICABILITY_MARKER = 'review-applicability:v1';
+const PATH_APPLICABILITY_MARKER = 'path-applicability:v1';
+const PATH_PATTERN_CHARACTERS = /^[A-Za-z0-9_.@*?/-]+$/;
export const GLOBAL_REVIEW_TRIGGERS = new Set([
'accessibility',
'behavior',
@@ -205,19 +207,17 @@ export function extractKnowledgeClaims(content) {
return claims;
}
-export function parseReviewApplicabilityBlock(
- content,
- filePath = '<knowledge record>',
-) {
- const marker = /<!--\s*review-applicability:v1\s*-->/g;
+function parseOverlayBlock(content, markerName, filePath) {
+ const marker = new RegExp(
+ `<!--\\s*${markerName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*-->`,
+ 'g',
+ );
const markers = [...content.matchAll(marker)];
if (markers.length === 0) return {config: null, problems: []};
if (markers.length > 1) {
return {
config: null,
- problems: [
- `${filePath}: duplicate ${REVIEW_APPLICABILITY_MARKER} blocks.`,
- ],
+ problems: [`${filePath}: duplicate ${markerName} blocks.`],
};
}
@@ -227,7 +227,7 @@ export function parseReviewApplicabilityBlock(
return {
config: null,
problems: [
- `${filePath}: ${REVIEW_APPLICABILITY_MARKER} must be followed by one JSON code block.`,
+ `${filePath}: ${markerName} must be followed by one JSON code block.`,
],
};
}
@@ -242,7 +242,7 @@ export function parseReviewApplicabilityBlock(
return {
config: null,
problems: [
- `${filePath}: ${REVIEW_APPLICABILITY_MARKER} repeats JSON field ${JSON.stringify(duplicates[0])}.`,
+ `${filePath}: ${markerName} repeats JSON field ${JSON.stringify(duplicates[0])}.`,
],
};
}
@@ -253,12 +253,19 @@ export function parseReviewApplicabilityBlock(
return {
config: null,
problems: [
- `${filePath}: ${REVIEW_APPLICABILITY_MARKER} is not valid JSON (${error.message}).`,
+ `${filePath}: ${markerName} is not valid JSON (${error.message}).`,
],
};
}
}
+export function parseReviewApplicabilityBlock(
+ content,
+ filePath = '<knowledge record>',
+) {
+ return parseOverlayBlock(content, REVIEW_APPLICABILITY_MARKER, filePath);
+}
+
export function validateReviewApplicability(
config,
content,
@@ -327,6 +334,146 @@ export function validateReviewApplicability(
return problems;
}
+function pathPatternExpression(pattern) {
+ let expression = '';
+ const segments = pattern.split('/');
+ segments.forEach((segment, index) => {
+ const last = index === segments.length - 1;
+ if (segment === '**') {
+ expression += last ? '.*' : '(?:[^/]+/)*';
+ return;
+ }
+ expression += segment
+ .split('')
+ .map(character => {
+ if (character === '*') return '[^/]*';
+ if (character === '?') return '[^/]';
+ return character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+ })
+ .join('');
+ if (!last) expression += '/';
+ });
+ return new RegExp(`^${expression}$`);
+}
+
+/**
+ * True when a repository-relative path matches a path-applicability pattern.
+ * `**` spans any number of whole segments, `*` any run within one segment,
+ * and `?` one character within a segment. Matching is case-sensitive.
+ */
+const pathPatternCache = new Map();
+
+export function matchesPathPattern(pattern, filePath) {
+ let expression = pathPatternCache.get(pattern);
+ if (!expression) {
+ expression = pathPatternExpression(pattern);
+ pathPatternCache.set(pattern, expression);
+ }
+ return expression.test(filePath);
+}
+
+export function parsePathApplicabilityBlock(
+ content,
+ filePath = '<knowledge record>',
+) {
+ return parseOverlayBlock(content, PATH_APPLICABILITY_MARKER, filePath);
+}
+
+/**
+ * Validate a `path-applicability:v1` block. When `repositoryFiles` is given,
+ * every pattern must match at least one of them, so a pattern cannot go stale
+ * silently after a move or rename.
+ */
+export function validatePathApplicability(
+ config,
+ filePath = '<knowledge record>',
+ repositoryFiles = null,
+) {
+ if (config == null) return [];
+ const where = `${filePath}: ${PATH_APPLICABILITY_MARKER}`;
+ if (!exactKeys(config, ['paths'])) {
+ return [`${where} requires exactly paths.`];
+ }
+ if (!Array.isArray(config.paths) || config.paths.length === 0) {
+ return [`${where} requires a non-empty paths list.`];
+ }
+ const problems = [];
+ const seen = new Set();
+ for (const pattern of config.paths) {
+ if (typeof pattern !== 'string' || pattern.length === 0) {
+ problems.push(`${where} has a non-string or empty pattern.`);
+ continue;
+ }
+ const label = `${where} pattern ${JSON.stringify(pattern)}`;
+ if (seen.has(pattern)) {
+ problems.push(`${label} is repeated.`);
+ continue;
+ }
+ seen.add(pattern);
+ if (!PATH_PATTERN_CHARACTERS.test(pattern)) {
+ problems.push(
+ `${label} may use only letters, digits, _ . @ - / and the wildcards * ** ?.`,
+ );
+ continue;
+ }
+ const segments = pattern.split('/');
+ if (
+ pattern.startsWith('/') ||
+ segments.some(
+ segment => segment === '' || segment === '.' || segment === '..',
+ )
+ ) {
+ problems.push(
+ `${label} must be repository-relative with no empty, "." or ".." segments.`,
+ );
+ continue;
+ }
+ if (segments.some(segment => segment.includes('**') && segment !== '**')) {
+ problems.push(`${label} may use ** only as a whole segment.`);
+ continue;
+ }
+ if (pattern === '**') {
+ problems.push(`${label} covers the whole repository; name the paths.`);
+ continue;
+ }
+ if (/[*?]/.test(segments[0])) {
+ problems.push(
+ `${label} must start with a literal path segment; a leading wildcard covers the whole repository.`,
+ );
+ continue;
+ }
+ if (
+ repositoryFiles &&
+ repositoryFiles.length > 1 &&
+ repositoryFiles.every(candidate => matchesPathPattern(pattern, candidate))
+ ) {
+ problems.push(`${label} matches every repository file; name the paths.`);
+ continue;
+ }
+ if (
+ repositoryFiles &&
+ !repositoryFiles.some(candidate => matchesPathPattern(pattern, candidate))
+ ) {
+ problems.push(`${label} matches no repository file.`);
+ }
+ }
+ return problems;
+}
+
+function repositoryFileList(root) {
+ try {
+ return execFileSync('git', ['-C', root, 'ls-files', '-z'], {
+ encoding: 'utf8',
+ maxBuffer: 256 * 1024 * 1024,
+ stdio: ['ignore', 'pipe', 'ignore'],
+ })
+ .split('\0')
+ .filter(Boolean);
+ } catch {
+ return null;
+ }
+}
+
function isKnowledgeRecordPath(filePath) {
if (/^docs\/(?:architecture|design|families)\/[^/]+\.md$/.test(filePath)) {
return !filePath.endsWith('/README.md');
@@ -1626,6 +1773,7 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {
const ids = new Map();
const records = [];
const delegations = [];
+ const repositoryFiles = repositoryFileList(root);
for (const [kind, kindSchema] of Object.entries(schema.kinds)) {
const kindVersion = latestKindVersions.get(kind);
@@ -1684,6 +1832,15 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {
const filePath = path.relative(root, absolutePath);
const content = fs.readFileSync(absolutePath, 'utf8');
const document = parseKnowledgeDocument(content, filePath);
+ const pathApplicability = parsePathApplicabilityBlock(content, filePath);
+ problems.push(
+ ...pathApplicability.problems,
+ ...validatePathApplicability(
+ pathApplicability.config,
+ filePath,
+ repositoryFiles,
+ ),
+ );
const reviewApplicability = parseReviewApplicabilityBlock(
content,
filePath,
@@ -1827,10 +1984,28 @@ export async function validateKnowledgeRoot(root = DEFAULT_ROOT) {
}
}
+ if (repositoryFiles) {
+ const {loadKnowledgeIndex, findUnreachedRecords} =
+ await import('./specs-for-file.mjs');
+ for (const record of findUnreachedRecords(
+ loadKnowledgeIndex(root),
+ repositoryFiles,
+ )) {
+ problems.push(
+ `${record.path}: current record ${record.id} is not reached from any repository path that is not itself a record (INV25). Link it through placement, applies_to, verified_by, a membership or consumer-doc id, a cited spec number, or a path-applicability:v1 block.`,
+ );
+ }
+ }
+
return problems;
}
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
+async function main() {
+ if (!repositoryFileList(DEFAULT_ROOT)) {
+ console.warn(
+ 'Skipped the INV25 reachability and path-pattern match checks: `git ls-files` is unavailable here.',
+ );
+ }
const problems = await validateKnowledgeRoot();
const baseIndex = process.argv.indexOf('--base');
if (baseIndex !== -1) {
@@ -1850,3 +2025,12 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
}
console.log('Knowledge templates and records are aligned.');
}
+
+// Not a top-level await: validation imports scripts/specs-for-file.mjs, which
+// imports this module back, and that import must find it fully evaluated.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+ main().catch(error => {
+ console.error(error);
+ process.exit(1);
+ });
+}
diff --git a/scripts/check-knowledge.test.mjs b/scripts/check-knowledge.test.mjs
index e235c7a8de..c04cc1d047 100644
--- a/scripts/check-knowledge.test.mjs
+++ b/scripts/check-knowledge.test.mjs
@@ -10,15 +10,18 @@ import {
collectGlobalReviewMatches,
discoverKnowledgeRecords,
extractKnowledgeClaims,
+ matchesPathPattern,
parseAnatomyThemingBlock,
parseDesignDecisionsBlock,
parseKnowledgeDocument,
+ parsePathApplicabilityBlock,
parseReviewApplicabilityBlock,
routeGlobalReviewBaselinesAtRevision,
validateAnatomyThemingMap,
validateDesignDecisionsBlock,
validateDelegations,
validateKnowledgeRoot,
+ validatePathApplicability,
validateReviewApplicability,
validateSchemaEvolution,
} from './check-knowledge.mjs';
@@ -2226,3 +2229,154 @@ describe('knowledge validation', () => {
);
});
});
+
+describe('path-applicability:v1', () => {
+ it('matches ** across whole segments, * and ? within one segment', () => {
+ const cases = [
+ ['apps/docsite/**', 'apps/docsite/src/a.ts', true],
+ ['apps/docsite/**', 'apps/docsite', false],
+ ['apps/docsite/**', 'apps/docsite-old/a.ts', false],
+ [
+ 'packages/**/*.doc.mjs',
+ 'packages/core/src/Button/Button.doc.mjs',
+ true,
+ ],
+ ['packages/**/*.doc.mjs', 'packages/Button.doc.mjs', true],
+ [
+ 'packages/**/*.doc.mjs',
+ 'packages/core/src/Button/Button.doc.zh.mjs',
+ false,
+ ],
+ ['packages/*/src/index.ts', 'packages/core/src/index.ts', true],
+ ['packages/*/src/index.ts', 'packages/core/nested/src/index.ts', false],
+ ['scripts/check-?.mjs', 'scripts/check-a.mjs', true],
+ ['scripts/check-?.mjs', 'scripts/check-ab.mjs', false],
+ ['docs/a.b.md', 'docs/aXb.md', false],
+ ['README.md', 'README.md', true],
+ ['README.md', 'packages/core/README.md', false],
+ ];
+ for (const [pattern, filePath, expected] of cases) {
+ expect([
+ pattern,
+ filePath,
+ matchesPathPattern(pattern, filePath),
+ ]).toEqual([pattern, filePath, expected]);
+ }
+ });
+
+ it('accepts a valid block and rejects malformed, unsafe, repeated, or stale patterns', () => {
+ const files = ['apps/docsite/src/a.ts', 'README.md'];
+ const content = [
+ '# Record',
+ '',
+ '<!-- path-applicability:v1 -->',
+ '',
+ '```json',
+ '{"paths": ["apps/docsite/**", "README.md"]}',
+ '```',
+ ].join('\n');
+ const parsed = parsePathApplicabilityBlock(content, 'r.md');
+ expect(parsed.problems).toEqual([]);
+ expect(validatePathApplicability(parsed.config, 'r.md', files)).toEqual([]);
+
+ const problems = config => validatePathApplicability(config, 'r.md', files);
+ expect(problems({paths: []})).toEqual([
+ 'r.md: path-applicability:v1 requires a non-empty paths list.',
+ ]);
+ expect(problems({paths: ['README.md'], scope: 'global'})).toEqual([
+ 'r.md: path-applicability:v1 requires exactly paths.',
+ ]);
+ expect(
+ problems({
+ paths: [
+ 'README.md',
+ 'README.md',
+ '/abs/**',
+ 'a/../b',
+ 'a/b**',
+ '**',
+ 'docs/{a,b}.md',
+ 'apps/missing/**',
+ '**/*',
+ '**/**',
+ '**/?*',
+ '*/src/a.ts',
+ ],
+ }),
+ ).toEqual([
+ 'r.md: path-applicability:v1 pattern "README.md" is repeated.',
+ 'r.md: path-applicability:v1 pattern "/abs/**" must be repository-relative with no empty, "." or ".." segments.',
+ 'r.md: path-applicability:v1 pattern "a/../b" must be repository-relative with no empty, "." or ".." segments.',
+ 'r.md: path-applicability:v1 pattern "a/b**" may use ** only as a whole segment.',
+ 'r.md: path-applicability:v1 pattern "**" covers the whole repository; name the paths.',
+ 'r.md: path-applicability:v1 pattern "docs/{a,b}.md" may use only letters, digits, _ . @ - / and the wildcards * ** ?.',
+ 'r.md: path-applicability:v1 pattern "apps/missing/**" matches no repository file.',
+ 'r.md: path-applicability:v1 pattern "**/*" must start with a literal path segment; a leading wildcard covers the whole repository.',
+ 'r.md: path-applicability:v1 pattern "**/**" must start with a literal path segment; a leading wildcard covers the whole repository.',
+ 'r.md: path-applicability:v1 pattern "**/?*" must start with a literal path segment; a leading wildcard covers the whole repository.',
+ 'r.md: path-applicability:v1 pattern "*/src/a.ts" must start with a literal path segment; a leading wildcard covers the whole repository.',
+ ]);
+ expect(
+ validatePathApplicability({paths: ['apps/**']}, 'r.md', [
+ 'apps/a.ts',
+ 'apps/b/c.ts',
+ ]),
+ ).toEqual([
+ 'r.md: path-applicability:v1 pattern "apps/**" matches every repository file; name the paths.',
+ ]);
+ expect(
+ validatePathApplicability({paths: ['apps/missing/**']}, 'r.md', null),
+ ).toEqual([]);
+ });
+
+ it('reports duplicate blocks through the shared overlay parser', () => {
+ const block =
+ '<!-- path-applicability:v1 -->\n```json\n{"paths": ["README.md"]}\n```\n';
+ expect(
+ parsePathApplicabilityBlock(`${block}\n${block}`, 'r.md').problems,
+ ).toEqual(['r.md: duplicate path-applicability:v1 blocks.']);
+ });
+});
+
+describe('INV25 record reachability', () => {
+ function gitFixture(root) {
+ execFileSync('git', ['init', '-q'], {cwd: root});
+ execFileSync('git', ['add', '-A'], {cwd: root});
+ }
+
+ it('fails a current record no tracked non-record path reaches, and passes once a pattern reaches it', async () => {
+ const root = fixtureRoot();
+ writeSystemSpec(root, 'AST-900', systemSpecRecord());
+ fs.mkdirSync(path.join(root, 'apps/site'), {recursive: true});
+ fs.writeFileSync(path.join(root, 'apps/site/index.md'), '# Site\n');
+ gitFixture(root);
+ expect(await validateKnowledgeRoot(root)).toEqual([
+ 'docs/specs/AST-900/spec.md: current record spec:AST-900 is not reached from any repository path that is not itself a record (INV25). Link it through placement, applies_to, verified_by, a membership or consumer-doc id, a cited spec number, or a path-applicability:v1 block.',
+ ]);
+
+ fs.writeFileSync(
+ path.join(root, 'docs/specs/AST-900/spec.md'),
+ systemSpecRecord().replace(
+ '# Fixture system spec\n',
+ '# Fixture system spec\n\n<!-- path-applicability:v1 -->\n\n```json\n{"paths": ["apps/site/**"]}\n```\n',
+ ),
+ );
+ gitFixture(root);
+ expect(await validateKnowledgeRoot(root)).toEqual([]);
+ });
+
+ it('skips reachability when the root has no tracked file list', async () => {
+ const root = fixtureRoot();
+ writeSystemSpec(root, 'AST-900', systemSpecRecord());
+ expect(await validateKnowledgeRoot(root)).toEqual([]);
+ });
+
+ it('runs from the command line without deadlocking on its own import', () => {
+ const output = execFileSync(
+ process.execPath,
+ [path.join(repoRoot, 'scripts/check-knowledge.mjs')],
+ {cwd: repoRoot, encoding: 'utf8'},
+ );
+ expect(output).toContain('Knowledge templates and records are aligned.');
+ });
+});
diff --git a/scripts/specs-for-file.mjs b/scripts/specs-for-file.mjs
index 2ddb645692..34c4536e64 100644
--- a/scripts/specs-for-file.mjs
+++ b/scripts/specs-for-file.mjs
@@ -22,7 +22,9 @@ import {
collectGlobalReviewMatches,
discoverKnowledgeRecords,
consumerDocPublicNames,
+ matchesPathPattern,
parseKnowledgeDocument,
+ parsePathApplicabilityBlock,
} from './check-knowledge.mjs';
const require = createRequire(import.meta.url);
@@ -142,6 +144,9 @@ export function loadKnowledgeIndex(root = DEFAULT_ROOT) {
authority: frontmatter.get('authority'),
frontmatter,
classified: classifyComponentKnowledgePath(filePath),
+ pathPatterns: asList(
+ parsePathApplicabilityBlock(content, filePath).config?.paths,
+ ).filter(pattern => typeof pattern === 'string'),
});
}
const byId = new Map(records.map(record => [record.id, record]));
@@ -331,10 +336,16 @@ function placementMatches(index, filePath, location) {
return matches;
}
-/** Records that declare a path entry covering `filePath`. */
+/** Records that declare a path entry or pattern covering `filePath`. */
function declaredPathMatches(index, filePath) {
const matches = [];
for (const record of index.records) {
+ const pattern = record.pathPatterns.find(candidate =>
+ matchesPathPattern(candidate, filePath),
+ );
+ if (pattern) {
+ matches.push({record, via: 'path-applicability', detail: pattern});
+ }
for (const field of ['applies_to', 'verified_by']) {
for (const entry of asList(record.frontmatter.get(field))) {
if (pathEntryCovers(index.root, entry, filePath)) {
diff --git a/scripts/specs-for-file.test.mjs b/scripts/specs-for-file.test.mjs
index 68d7dcb021..ff321716e5 100644
--- a/scripts/specs-for-file.test.mjs
+++ b/scripts/specs-for-file.test.mjs
@@ -621,6 +621,36 @@ describe('resolveSpecsForFile', () => {
expect(ids(result.records)).not.toContain('spec:AST-020');
});
+ it("routes a path matched by a record's path-applicability pattern", () => {
+ const root = popoverFixture();
+ writeRecord(
+ root,
+ 'docs/specs/AST-033/spec.md',
+ {
+ kind: 'system-spec',
+ id: 'spec:AST-033',
+ affects_architecture: [],
+ affects_families: [],
+ affects_consumer_docs: [],
+ },
+ '\n<!-- path-applicability:v1 -->\n\n```json\n{"paths": ["apps/docsite/**"]}\n```\n',
+ );
+ const index = loadKnowledgeIndex(root);
+ const result = resolveSpecsForFile(
+ index,
+ 'apps/docsite/src/content/blog/posts/release.md',
+ );
+ expect(result.records).toEqual([
+ expect.objectContaining({
+ id: 'spec:AST-033',
+ routes: [{via: 'path-applicability', detail: 'apps/docsite/**'}],
+ }),
+ ]);
+ expect(
+ resolveSpecsForFile(index, 'apps/docsite-legacy/index.md').records,
+ ).toEqual([]);
+ });
+
it('reports a path no record reaches instead of guessing', () => {
const index = loadKnowledgeIndex(popoverFixture());
const result = resolveSpecsForFile(