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.mdindex 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 recordsand 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 asdiff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjsindex 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.mjsindex 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.mjsindex 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.mjsindex 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(