create-principles-disciple 1.142.0 → 1.142.2

package/core/dist/runtime-v2/__tests__/architecture-regression.test.js

@@ -3083,6 +3083,150 @@ describe('PRI-416: barrel cap guards', () => {
         expect(exportLines.length).toBeLessThanOrEqual(BARREL_MAX_EXPORT_LINES);
     });
 });
+// ── PRI-775: Barrel Export Surface Freeze ─────────────────────────────────────
+//
+// The two public barrels (src/index.ts, src/runtime-v2/index.ts) are the first
+// surface every AI task and developer reads; ghost exports accumulate exactly
+// there (PRI-751 audit section 2). The export-name SET of each barrel is
+// frozen via snapshot fixtures: adding OR removing a name must update the
+// fixture with a PRI-tagged reason in the PR. Count-only caps are blind to
+// delete-one-add-one drift, which is how ghost families regrow.
+//
+// The extractor strips comments from captured tokens and validates that every
+// frozen entry is a real identifier — the snapshot must be a name SET, never
+// source-text fragments (review finding: 12/1719 comment-polluted entries).
+// Whitespace variants of the block form are captured, not missed. Wildcard
+// re-exports, default exports and non-identifier captures fail loud: the
+// guard refuses to freeze a surface it cannot prove.
+describe('PRI-775: barrel export surface freeze', () => {
+    const IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+    function extractExportNames(src) {
+        if (/^export\s+\*/m.test(src)) {
+            throw new Error('PRI-775: wildcard re-export (`export *`) detected. A name-set snapshot cannot prove '
+                + 'the surface of a star re-export, so the freeze refuses to guess: enumerate the '
+                + 'exports explicitly or extend this guard deliberately.');
+        }
+        if (/^export\s+default/m.test(src)) {
+            throw new Error('PRI-775: default export detected. A barrel default export is invisible to the '
+                + 'name-set snapshot, so the freeze refuses to guess: use a named export or '
+                + 'extend this guard deliberately.');
+        }
+        const names = new Set();
+        for (const block of src.match(/\bexport\s*(?:type\s*)?\{[^}]*\}/g) ?? []) {
+            // Strip comments BEFORE splitting on commas: a comment that itself
+            // contains a comma would otherwise be cut in half and glue comment
+            // text onto the following real symbol (hit on real barrel source).
+            const inner = block
+                .slice(block.indexOf('{') + 1, block.indexOf('}'))
+                .replace(/\/\*[\s\S]*?\*\//g, '')
+                .replace(/\/\/.*$/gm, '');
+            for (let token of inner.split(',')) {
+                token = token.trim();
+                if (!token)
+                    continue;
+                if (token.startsWith('type '))
+                    token = token.slice(5).trim();
+                const asIdx = token.indexOf(' as ');
+                if (asIdx !== -1)
+                    token = token.slice(asIdx + 4).trim();
+                if (!token)
+                    continue;
+                if (!IDENTIFIER_RE.test(token)) {
+                    throw new Error(`PRI-775: extractor captured a non-identifier export token ${JSON.stringify(token)}. `
+                        + 'This guard freezes identifier names only; fail loud instead of freezing '
+                        + 'source-text fragments. Fix the extractor or the barrel formatting.');
+                }
+                names.add(token);
+            }
+        }
+        for (const m of src.match(/^export (?:const|function|class|interface|enum|abstract class) [A-Za-z0-9_]+/gm) ?? []) {
+            const decl = m.split(/\s/).pop();
+            if (decl)
+                names.add(decl);
+        }
+        return [...names].sort();
+    }
+    async function readFixture(fixtureFile) {
+        const fsMod = await import('fs'); // eslint-disable-line @typescript-eslint/consistent-type-imports
+        const pathMod = await import('path'); // eslint-disable-line @typescript-eslint/consistent-type-imports
+        return JSON.parse(fsMod.readFileSync(pathMod.resolve(__dirname, 'fixtures', fixtureFile), 'utf-8'));
+    }
+    for (const fixtureFile of ['runtime-v2-barrel-surface.json', 'core-barrel-surface.json']) {
+        it(`${fixtureFile}: export surface matches the frozen snapshot`, async () => {
+            const fsMod = await import('fs'); // eslint-disable-line @typescript-eslint/consistent-type-imports
+            const pathMod = await import('path'); // eslint-disable-line @typescript-eslint/consistent-type-imports
+            const fixture = await readFixture(fixtureFile);
+            const src = fsMod.readFileSync(pathMod.resolve(__dirname, '..', '..', '..', fixture.barrel), 'utf-8');
+            const current = extractExportNames(src);
+            const added = current.filter((n) => !fixture.names.includes(n));
+            const removed = fixture.names.filter((n) => !current.includes(n));
+            const diffMessage = [
+                `${fixture.barrel} export surface drifted from the frozen snapshot (PRI-775):`,
+                ...(added.length > 0 ? [`  + added (${added.length}): ${added.join(', ')}`] : []),
+                ...(removed.length > 0 ? [`  - removed (${removed.length}): ${removed.join(', ')}`] : []),
+                'To change the surface intentionally: update __tests__/fixtures/' + fixtureFile,
+                '  and state the reason with a PRI tag in the PR description. Ghost exports',
+                '  without production consumers are how barrel entropy regrows (PRI-751 audit).',
+            ].join('\n');
+            expect(added.length + removed.length, diffMessage).toBe(0);
+        });
+    }
+    it('barrel surface snapshots are self-consistent', async () => {
+        for (const fixtureFile of ['runtime-v2-barrel-surface.json', 'core-barrel-surface.json']) {
+            const fixture = await readFixture(fixtureFile);
+            expect(fixture.names.length, `${fixtureFile}: "count" field is stale`).toBe(fixture.count);
+            expect([...fixture.names].sort(), `${fixtureFile}: names are not sorted/deduped`).toEqual(fixture.names);
+            expect(new Set(fixture.names).size, `${fixtureFile}: duplicate names`).toBe(fixture.names.length);
+            expect(fixture.names.every((n) => IDENTIFIER_RE.test(n)), `${fixtureFile}: snapshot contains non-identifier names (comment/text pollution)`).toBe(true);
+        }
+    });
+    it('extractor contract: comments, aliases, type-only blocks, and fail-loud traps', () => {
+        // Comments inside an export block must never leak into the frozen names.
+        expect(extractExportNames([
+            'export {',
+            '  /** @deprecated use Bar instead */',
+            '  Foo,',
+            '  Bar, // trailing note',
+            "} from './x.js';",
+        ].join('\n'))).toEqual(['Bar', 'Foo']);
+        // A comma inside a comment must not split the comment in half and glue
+        // comment text onto the next symbol (hit on real barrel source).
+        expect(extractExportNames([
+            'export {',
+            '  // re-exports Foo, not deep imports.',
+            '  Foo,',
+            '  /* block, comment */ Baz,',
+            "} from './x.js';",
+        ].join('\n'))).toEqual(['Baz', 'Foo']);
+        // Aliases freeze the exported (right-hand) name; inline `type` modifier is honored.
+        expect(extractExportNames([
+            'export {',
+            '  InternalFoo as Foo,',
+            '  type InternalBar as Bar,',
+            "} from './x.js';",
+        ].join('\n'))).toEqual(['Bar', 'Foo']);
+        // `export type { ... }` blocks and value declarations are all captured.
+        expect(extractExportNames([
+            'export type { Baz };',
+            'export const QUX = 1;',
+            'export function qux(): void {}',
+            'export class Qux {}',
+            'export interface IQux {}',
+            'export enum QuxKind { A }',
+            'export abstract class BaseQux {}',
+        ].join('\n'))).toEqual(['BaseQux', 'Baz', 'IQux', 'QUX', 'Qux', 'QuxKind', 'qux']);
+        // Wildcard re-exports cannot be proven by a name snapshot: refuse.
+        expect(() => extractExportNames("export * from './x.js';")).toThrow(/wildcard/);
+        // Text fragments that never reduce to an identifier fail loud, never freeze.
+        expect(() => extractExportNames('export { 123bad } from "./x.js";')).toThrow(/non-identifier/);
+        // Whitespace variants of the block form are captured, not missed
+        // (`export{Foo}` slipped past the old strict-space regex).
+        expect(extractExportNames("export{NoSpace} from './x.js';")).toEqual(['NoSpace']);
+        expect(extractExportNames("export type{NoSpaceType} from './x.js';")).toEqual(['NoSpaceType']);
+        // A barrel default export is invisible to the name set: refuse.
+        expect(() => extractExportNames("import Foo from './x.js';\nexport default Foo;\n")).toThrow(/default/);
+    });
+});
 // ── PRI-443: Pure module boundary guards ──────────────────────────────────────
 //
 // Phases 1-3 extracted pure types/codecs/schema out of I/O modules. These guards