diff --git a/Storybook/for_renderer_matrix_scope/when_deriving_renderer_matrix_scope.ts b/Storybook/for_renderer_matrix_scope/when_deriving_renderer_matrix_scope.ts index 645f4b55..21541c53 100644 --- a/Storybook/for_renderer_matrix_scope/when_deriving_renderer_matrix_scope.ts +++ b/Storybook/for_renderer_matrix_scope/when_deriving_renderer_matrix_scope.ts @@ -6,7 +6,7 @@ import os from 'node:os'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { expect } from 'chai'; -import { describe, it } from 'vitest'; +import { afterEach, beforeEach, describe, it } from 'vitest'; import expectedStorybook from '../scripts/storybook-inventory.json'; import { computeRendererMatrixScope, findSlotOwningModules } from '../scripts/lib/renderer-matrix-scope.mjs'; @@ -197,3 +197,70 @@ describe('when deriving renderer matrix scope', () => { } }); }); + +describe('when deriving renderer scope through cycles and missing imports', () => { + let root: string; + let result: ReturnType; + + beforeEach(() => { + const fixtureDirectory = path.join(repositoryRoot, '.ai-work/506-b6'); + mkdirSync(fixtureDirectory, { recursive: true }); + root = mkdtempSync(path.join(fixtureDirectory, 'renderer-scope-')); + const fixtureSourceRoot = path.join(root, 'Source'); + const fixtures = { + 'Slot.tsx': "unstable_useSlot('common.button');\n", + 'CycleA.tsx': "import './CycleB';\n", + 'CycleB.tsx': "import './CycleA';\nimport './Slot';\n", + 'ClosedA.tsx': "import './ClosedB';\n", + 'ClosedB.tsx': "import './ClosedA';\n", + 'Composite.tsx': "import 'external-package';\nimport './Missing';\nimport './nested';\n", + 'nested/index.ts': "export { Slot } from '../Slot';\n", + 'dist/Hidden.tsx': "unstable_useSlot('common.button');\n", + 'node_modules/Hidden.tsx': "unstable_useSlot('common.button');\n", + 'storybook-static/Hidden.tsx': "unstable_useSlot('common.button');\n", + 'for_example/Hidden.tsx': "unstable_useSlot('common.button');\n", + 'Example.stories.tsx': "unstable_useSlot('common.button');\n", + 'Example.stories.ts': "unstable_useSlot('common.button');\n", + 'notes.md': "unstable_useSlot('common.button');\n", + }; + for (const [name, contents] of Object.entries(fixtures)) { + const file = path.join(fixtureSourceRoot, name); + mkdirSync(path.dirname(file), { recursive: true }); + writeFileSync(file, contents); + } + const storyEntries = [ + storyEntry('cycle--first', 'CycleA.tsx'), + storyEntry('cycle--second', 'CycleB.tsx'), + storyEntry('closed--first', 'ClosedA.tsx'), + storyEntry('closed--second', 'ClosedB.tsx'), + storyEntry('composite--default', 'Composite.tsx'), + storyEntry('missing--default', 'Missing.tsx'), + storyEntry('cycle--repeated', 'CycleA.tsx'), + storyEntry('closed--repeated', 'ClosedA.tsx'), + ]; + result = computeRendererMatrixScope({ storyEntries, repositoryRoot: root, sourceRoot: fixtureSourceRoot }); + }); + + afterEach(() => rmSync(root, { recursive: true, force: true })); + + it('should include only production TypeScript slot owners', () => { + [...result.slotOwningModules].should.deep.equal([path.join(root, 'Source/Slot.tsx')]); + }); + + it('should resolve index modules and reachable cycles without crediting closed cycles or missing modules', () => { + [...result.matrixStoryIds].should.deep.equal([ + 'cycle--first', 'cycle--second', 'composite--default', 'cycle--repeated', + ]); + }); + + it('should retain both positive and negative component membership for repeated stories', () => { + [...result.componentMatrixMembership].should.deep.equal([ + ['./Source/CycleA.tsx', true], + ['./Source/CycleB.tsx', true], + ['./Source/ClosedA.tsx', false], + ['./Source/ClosedB.tsx', false], + ['./Source/Composite.tsx', true], + ['./Source/Missing.tsx', false], + ]); + }); +}); diff --git a/Storybook/scripts/lib/renderer-matrix-scope.mjs b/Storybook/scripts/lib/renderer-matrix-scope.mjs index 61d8d409..3c0419af 100644 --- a/Storybook/scripts/lib/renderer-matrix-scope.mjs +++ b/Storybook/scripts/lib/renderer-matrix-scope.mjs @@ -9,17 +9,15 @@ const IGNORED_DIRECTORY_NAMES = new Set(['dist', 'node_modules', 'storybook-stat const SOURCE_FILE_PATTERN = /\.tsx?$/u; const SLOT_HOOK_PATTERN = /\bunstable_useSlot\s*\(/u; -const collectFiles = (directory, predicate, results = []) => { - for (const entry of readdirSync(directory, { withFileTypes: true })) { - if (IGNORED_DIRECTORY_NAMES.has(entry.name)) continue; - const entryPath = path.join(directory, entry.name); - if (entry.isDirectory()) { - collectFiles(entryPath, predicate, results); - continue; - } - if (entry.isFile() && predicate(entryPath)) results.push(entryPath); - } - return results; +const collectFiles = (directory, predicate) => + readdirSync(directory, { withFileTypes: true }) + .filter(entry => !IGNORED_DIRECTORY_NAMES.has(entry.name)) + .flatMap(entry => collectEntryFiles(directory, entry, predicate)); + +const collectEntryFiles = (directory, entry, predicate) => { + const entryPath = path.join(directory, entry.name); + if (entry.isDirectory()) return collectFiles(entryPath, predicate); + return entry.isFile() && predicate(entryPath) ? [entryPath] : []; }; const isProductionModule = filePath => @@ -39,12 +37,8 @@ const isProductionModule = filePath => */ export const findSlotOwningModules = sourceRoot => { const candidates = collectFiles(sourceRoot, isProductionModule); - const owning = new Set(); - for (const filePath of candidates) { - const contents = readFileSync(filePath, 'utf8'); - if (SLOT_HOOK_PATTERN.test(contents)) owning.add(filePath); - } - return owning; + return new Set(candidates.filter(filePath => + SLOT_HOOK_PATTERN.test(readFileSync(filePath, 'utf8')))); }; const isTypeOnlyDeclaration = statement => @@ -90,15 +84,11 @@ const moduleReachesSlot = (file, slotOwningModules, memo, pending = new Set()) = } if (pending.has(file) || !existsSync(file)) return false; pending.add(file); - let reaches = false; const source = readFileSync(file, 'utf8'); - for (const specifier of extractSpecifiers(source, file)) { + const reaches = extractSpecifiers(source, file).some(specifier => { const resolved = resolveRelativeModule(file, specifier); - if (resolved && moduleReachesSlot(resolved, slotOwningModules, memo, pending)) { - reaches = true; - break; - } - } + return resolved !== undefined && moduleReachesSlot(resolved, slotOwningModules, memo, pending); + }); pending.delete(file); memo.set(file, reaches); return reaches; diff --git a/scripts/generate-compat-manifest.mjs b/scripts/generate-compat-manifest.mjs index 595e553b..98391163 100644 --- a/scripts/generate-compat-manifest.mjs +++ b/scripts/generate-compat-manifest.mjs @@ -148,6 +148,37 @@ export function validateCompatibilityManifest( manifest, { rootDirectory = repositoryDirectory, matrix } = {}, ) { + validatePublicationMetadata(manifest); + validatePublicPackageScope(manifest); + + validateRepositoryPackages(manifest.packages ?? []); + validateToolingCompatibility(manifest.toolingCompatibility ?? {}); + validateMaintenanceWindow(manifest.supportWindows?.components3); + validateCurrentWindow(manifest.supportWindows?.components4); + validateAdapterRanges(manifest.supportWindows?.components4); + validatePrivateEvidence(manifest.gaScope?.privateEvidence ?? [], rootDirectory); + + const activeMatrix = + matrix ?? + (rootDirectory + ? readJson( + path.join(rootDirectory, 'scripts/renderer-adapter-matrix.json'), + rootDirectory, + ) + : undefined); + if (activeMatrix) { + validateVerifiedPeers(manifest.packages ?? [], activeMatrix); + } + + if ( + manifest.publicationEnabled && + manifest.releaseStatus !== 'publication-authorized' + ) { + fail("Publication requires releaseStatus 'publication-authorized'."); + } +} + +function validatePublicationMetadata(manifest) { if (manifest.schemaVersion !== 2) fail('Unsupported compatibility manifest schema.'); if (typeof manifest.publicationEnabled !== 'boolean') { fail('publicationEnabled must be a boolean.'); @@ -157,7 +188,9 @@ export function validateCompatibilityManifest( "A non-publishing source manifest must have releaseStatus 'source-candidate'.", ); } +} +function validatePublicPackageScope(manifest) { const scopedPackages = manifest.gaScope?.publicPackages ?? []; if (JSON.stringify(scopedPackages) !== JSON.stringify(packageOrder)) { fail( @@ -167,81 +200,107 @@ export function validateCompatibilityManifest( if ((manifest.packages ?? []).length !== packageOrder.length) { fail(`Expected ${packageOrder.length} public package entries.`); } +} - const repositoryVersion = (manifest.packages ?? []).find( +function validateRepositoryPackages(packages) { + const repositoryVersion = packages.find( ({ name }) => name === '@cratis/components', )?.version; if (!repositoryVersion) fail('Core package version is missing.'); - for (const entry of manifest.packages ?? []) { - const policy = packagePolicies.get(entry.name); - if (!policy) fail(`Unexpected public package '${entry.name}'.`); - if (entry.role !== policy.role || entry.releaseMajorRange !== policy.range) { - fail(`${entry.name} has invalid role or release-major policy metadata.`); - } - if (semver.valid(entry.version) !== entry.version) { - fail(`${entry.name} must declare a valid exact current version.`); - } - if (!semver.satisfies(entry.version, policy.range)) { - fail( - `${entry.name}@${entry.version} is outside supported release range '${policy.range}'.`, - ); - } - if (entry.private || entry.packageAccess !== 'public') { - fail(`${entry.name} must remain explicitly public-intent.`); - } - if (entry.version !== repositoryVersion) { - fail( - `${entry.name}@${entry.version} must match the repository release version ${repositoryVersion}.`, - ); - } - if (entry.independentRelease !== false) { + for (const entry of packages) { + validatePublicPackage(entry, repositoryVersion); + } +} + +function validatePublicPackage(entry, repositoryVersion) { + const policy = packagePolicies.get(entry.name); + if (!policy) fail(`Unexpected public package '${entry.name}'.`); + if (entry.role !== policy.role || entry.releaseMajorRange !== policy.range) { + fail(`${entry.name} has invalid role or release-major policy metadata.`); + } + validatePackageVersion(entry, policy.range); + if (entry.private || entry.packageAccess !== 'public') { + fail(`${entry.name} must remain explicitly public-intent.`); + } + if (entry.version !== repositoryVersion) { + fail( + `${entry.name}@${entry.version} must match the repository release version ${repositoryVersion}.`, + ); + } + if (entry.independentRelease !== false) { + fail( + `${entry.name} must participate in repository-wide versioning and must not declare cratisIndependentVersion.`, + ); + } + validateUpstreamPeers(entry); +} + +function validatePackageVersion(entry, range) { + if (semver.valid(entry.version) !== entry.version) { + fail(`${entry.name} must declare a valid exact current version.`); + } + if (!semver.satisfies(entry.version, range)) { + fail( + `${entry.name}@${entry.version} is outside supported release range '${range}'.`, + ); + } +} + +function validateUpstreamPeers(entry) { + for (const [upstreamName, upstreamRange] of Object.entries(entry.upstream ?? {})) { + if (entry.peerDependencies?.[upstreamName] !== upstreamRange) { fail( - `${entry.name} must participate in repository-wide versioning and must not declare cratisIndependentVersion.`, + `${entry.name} upstream '${upstreamName}' must exactly match its peer range.`, ); } - for (const [upstreamName, upstreamRange] of Object.entries( - entry.upstream ?? {}, - )) { - if (entry.peerDependencies?.[upstreamName] !== upstreamRange) { - fail( - `${entry.name} upstream '${upstreamName}' must exactly match its peer range.`, - ); - } - } } +} - const tooling = manifest.toolingCompatibility ?? {}; - if ( - tooling.componentsCore !== '>=4 <5' || - tooling.eslint !== '>=4 <5' || - tooling.migrator !== '>=4 <5' - ) { +function validateToolingCompatibility(tooling) { + if (!hasProperties(tooling, { + componentsCore: '>=4 <5', + eslint: '>=4 <5', + migrator: '>=4 <5', + })) { fail('Core 4 tooling compatibility must remain bounded to >=4 <5.'); } +} - const components3 = manifest.supportWindows?.components3; - const components4 = manifest.supportWindows?.components4; +function validateMaintenanceWindow(components3) { if ( - components3?.components !== '>=3 <4' || - components3?.status !== 'maintenance-security-critical' || - components3?.migrationTarget !== '>=4 <5' || - components3?.tooling !== '>=4 <5' || + !hasProperties(components3, { + components: '>=3 <4', + status: 'maintenance-security-critical', + migrationTarget: '>=4 <5', + tooling: '>=4 <5', + }) || !components3.ownerDecisionPolicy?.includes('12 months after Components 4 GA') ) { fail('The Components 3 maintenance and migration support window is incomplete.'); } +} + +function validateCurrentWindow(components4) { if ( - components4?.components !== '>=4 <5' || - components4?.status !== 'current' || - components4?.rendererAbi !== 1 || - components4?.coreProfile !== 'core/v1' || - components4?.adapterProfile !== 'stable-presentation/v1' || - components4?.tooling?.eslint !== '>=4 <5' || - components4?.tooling?.migrator !== '>=4 <5' + !hasProperties(components4, { + components: '>=4 <5', + status: 'current', + rendererAbi: 1, + coreProfile: 'core/v1', + adapterProfile: 'stable-presentation/v1', + }) || + !hasProperties(components4?.tooling, { eslint: '>=4 <5', migrator: '>=4 <5' }) ) { fail('The Components 4 compatibility window is incomplete.'); } +} + +function hasProperties(value, expected) { + return Object.entries(expected).every(([key, required]) => value?.[key] === required); +} + +function validateAdapterRanges(components4) { const expectedAdapterRanges = Object.fromEntries( packageOrder .filter((name) => @@ -254,8 +313,9 @@ export function validateCompatibilityManifest( if (JSON.stringify(components4?.adapters) !== JSON.stringify(expectedAdapterRanges)) { fail('Components 4 must list the exact Conformance and adapter release ranges.'); } +} - const evidence = manifest.gaScope?.privateEvidence ?? []; +function validatePrivateEvidence(evidence, rootDirectory) { if ( JSON.stringify(evidence.map(({ id }) => id)) !== JSON.stringify(['plain', 'storybook']) @@ -266,48 +326,31 @@ export function validateCompatibilityManifest( if (!item.private || item.published) fail(`Private evidence '${item.id}' cannot be published.`); const source = privateEvidence.find(({ id }) => id === item.id); - if ( - rootDirectory && - source && - !fs.existsSync(path.join(rootDirectory, source.sourcePath)) - ) { - fail(`Private evidence '${item.id}' is missing from the source repository.`); + if (rootDirectory && source) { + validateEvidenceSource(rootDirectory, source, item.id); } } +} - const activeMatrix = - matrix ?? - (rootDirectory - ? readJson( - path.join(rootDirectory, 'scripts/renderer-adapter-matrix.json'), - rootDirectory, - ) - : undefined); - if (activeMatrix) { - for (const entry of manifest.packages ?? []) { - const adapterKey = adapterKeysByPackage.get(entry.name); - if (!adapterKey) continue; - const expected = { - minimum: sortObject( - createFixture(activeMatrix, adapterKey, 'minimum').peers, - ), - current: sortObject( - createFixture(activeMatrix, adapterKey, 'current').peers, - ), - }; - if (JSON.stringify(entry.verifiedPeers) !== JSON.stringify(expected)) { - fail( - `${entry.name} verified peers must be copied from renderer-adapter-matrix.json.`, - ); - } - } +function validateEvidenceSource(rootDirectory, source, id) { + if (!fs.existsSync(path.join(rootDirectory, source.sourcePath))) { + fail(`Private evidence '${id}' is missing from the source repository.`); } +} - if ( - manifest.publicationEnabled && - manifest.releaseStatus !== 'publication-authorized' - ) { - fail("Publication requires releaseStatus 'publication-authorized'."); +function validateVerifiedPeers(packages, matrix) { + for (const entry of packages) { + const adapterKey = adapterKeysByPackage.get(entry.name); + if (!adapterKey) continue; + const expected = { + minimum: sortObject(createFixture(matrix, adapterKey, 'minimum').peers), + current: sortObject(createFixture(matrix, adapterKey, 'current').peers), + }; + if (JSON.stringify(entry.verifiedPeers) !== JSON.stringify(expected)) { + fail( + `${entry.name} verified peers must be copied from renderer-adapter-matrix.json.`, + ); + } } } @@ -358,26 +401,19 @@ function validatePackageSet(packages) { export function discoverWorkspaceManifestPaths(workspaces, rootDirectory) { if (!Array.isArray(workspaces)) fail('Root package.json must declare a workspaces array.'); - const manifestPaths = []; - for (const workspace of workspaces) { - if (workspace.endsWith('/*')) { - const parent = path.join(rootDirectory, workspace.slice(0, -2)); - for (const entry of fs.readdirSync(parent, { withFileTypes: true })) { - if (!entry.isDirectory()) continue; - const relativeManifest = path.posix.join( - workspace.slice(0, -2), - entry.name, - 'package.json', - ); - if (fs.existsSync(path.join(rootDirectory, relativeManifest))) { - manifestPaths.push(relativeManifest); - } - } - } else { - manifestPaths.push(path.posix.join(workspace, 'package.json')); - } - } - return manifestPaths.sort(); + return workspaces.flatMap((workspace) => + workspace.endsWith('/*') + ? discoverChildManifestPaths(workspace.slice(0, -2), rootDirectory) + : [path.posix.join(workspace, 'package.json')], + ).sort(); +} + +function discoverChildManifestPaths(workspace, rootDirectory) { + const parent = path.join(rootDirectory, workspace); + return fs.readdirSync(parent, { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .map((entry) => path.posix.join(workspace, entry.name, 'package.json')) + .filter((manifestPath) => fs.existsSync(path.join(rootDirectory, manifestPath))); } function parseAbiMajor(value) { diff --git a/scripts/generate-compat-manifest.test.mjs b/scripts/generate-compat-manifest.test.mjs index 4fd0ce88..292cf1b0 100644 --- a/scripts/generate-compat-manifest.test.mjs +++ b/scripts/generate-compat-manifest.test.mjs @@ -10,6 +10,7 @@ import { fileURLToPath } from 'node:url'; import { checkCompatibilityManifest, createCompatibilityManifest, + discoverWorkspaceManifestPaths, serializeCompatibilityManifest, validateCompatibilityManifest, } from './generate-compat-manifest.mjs'; @@ -169,6 +170,137 @@ test('publication authorization is explicit and reversible', () => { ); }); +for (const { label, location, keys, message } of [ + { + label: 'tooling compatibility', + location: ['toolingCompatibility'], + keys: ['componentsCore', 'eslint', 'migrator'], + message: 'Core 4 tooling compatibility must remain bounded to >=4 <5.', + }, + { + label: 'maintenance support window', + location: ['supportWindows', 'components3'], + keys: ['components', 'status', 'migrationTarget', 'tooling', 'ownerDecisionPolicy'], + message: 'The Components 3 maintenance and migration support window is incomplete.', + }, + { + label: 'current support window', + location: ['supportWindows', 'components4'], + keys: ['components', 'status', 'rendererAbi', 'coreProfile', 'adapterProfile'], + message: 'The Components 4 compatibility window is incomplete.', + }, + { + label: 'current tooling support window', + location: ['supportWindows', 'components4', 'tooling'], + keys: ['eslint', 'migrator'], + message: 'The Components 4 compatibility window is incomplete.', + }, +]) { + for (const key of keys) { + test(`${label} rejects an invalid ${key} with its original message`, () => { + const manifest = createManifest(); + const target = location.reduce((value, key) => value[key], manifest); + target[key] = 'unsupported'; + assert.throws( + () => validateCompatibilityManifest(manifest, { rootDirectory: undefined }), + { message }, + ); + }); + } +} + +for (const [field, value, message] of [ + ['schemaVersion', 0, 'Unsupported compatibility manifest schema.'], + ['publicationEnabled', 'true', 'publicationEnabled must be a boolean.'], + ['releaseStatus', 'unsupported', "Publication requires releaseStatus 'publication-authorized'."], +]) { + test(`manifest metadata rejects an invalid ${field} with its original message`, () => { + const manifest = createManifest(); + manifest[field] = value; + assert.throws( + () => validateCompatibilityManifest(manifest, { rootDirectory: undefined }), + { message }, + ); + }); +} + +for (const [field, value, detail] of [ + ['role', 'unsupported', 'has invalid role or release-major policy metadata.'], + ['releaseMajorRange', '>=3 <4', 'has invalid role or release-major policy metadata.'], + ['version', 'not-a-version', 'must declare a valid exact current version.'], + ['private', true, 'must remain explicitly public-intent.'], + ['packageAccess', 'restricted', 'must remain explicitly public-intent.'], + ['independentRelease', true, 'must participate in repository-wide versioning and must not declare cratisIndependentVersion.'], +]) { + test(`package metadata rejects an invalid ${field} with its original message`, () => { + const manifest = createManifest(); + manifest.packages[0][field] = value; + assert.throws( + () => validateCompatibilityManifest(manifest, { rootDirectory: undefined }), + { message: `${manifest.packages[0].name} ${detail}` }, + ); + }); +} + +test('manifest validation reports earlier policy failures before later ones', () => { + const manifest = createManifest(); + manifest.toolingCompatibility = {}; + manifest.supportWindows = {}; + manifest.gaScope.privateEvidence = []; + assert.throws( + () => validateCompatibilityManifest(manifest, { rootDirectory: undefined }), + { message: 'Core 4 tooling compatibility must remain bounded to >=4 <5.' }, + ); +}); + +test('private evidence remains unpublished and present in the source repository', () => { + const manifest = createManifest(); + manifest.gaScope.privateEvidence[0].published = true; + assert.throws( + () => validateCompatibilityManifest(manifest), + { message: "Private evidence 'plain' cannot be published." }, + ); + manifest.gaScope.privateEvidence[0].published = false; + assert.throws( + () => validateCompatibilityManifest(manifest, { + rootDirectory: path.join(repositoryDirectory, 'package.json'), + }), + { message: "Private evidence 'plain' is missing from the source repository." }, + ); +}); + +test('upstream ranges must exactly match package peers', () => { + const manifest = createManifest(); + const adapter = manifest.packages.find(({ name }) => name === '@cratis/components.mui'); + adapter.peerDependencies['@mui/material'] = '*'; + assert.throws( + () => validateCompatibilityManifest(manifest), + { message: "@cratis/components.mui upstream '@mui/material' must exactly match its peer range." }, + ); +}); + +test('workspace discovery sorts direct and wildcard manifests and skips non-workspaces', () => { + const fixtureDirectory = path.join(repositoryDirectory, '.ai-work/506-b6'); + mkdirSync(fixtureDirectory, { recursive: true }); + const root = mkdtempSync(path.join(fixtureDirectory, 'workspace-discovery-')); + try { + for (const directory of ['Adapters/Zeta', 'Adapters/Alpha', 'Adapters/Empty']) { + mkdirSync(path.join(root, directory), { recursive: true }); + } + writeFileSync(path.join(root, 'Adapters/Zeta/package.json'), '{}'); + writeFileSync(path.join(root, 'Adapters/Alpha/package.json'), '{}'); + writeFileSync(path.join(root, 'Adapters/not-a-directory'), '{}'); + assert.deepEqual(discoverWorkspaceManifestPaths(['Source', 'Adapters/*', 'Missing'], root), [ + 'Adapters/Alpha/package.json', + 'Adapters/Zeta/package.json', + 'Missing/package.json', + 'Source/package.json', + ]); + } finally { + rmSync(root, { recursive: true, force: true }); + } +}); + test('adapter proof cannot drift from the renderer matrix', () => { const manifest = createManifest(); const mui = manifest.packages.find(({ name }) => name === '@cratis/components.mui');