@proteinjs/reflection-build 1.5.0 → 2.0.0

package/src/codegen/writeGeneratedIndex.ts

@@ -77,10 +77,10 @@ async function sourceRepositoryLoader(
 
   // Allow multiple roots (e.g., ['test','src']) to keep ancestry intact.
   const roots = Array.isArray(sourceRootsRel) ? sourceRootsRel : [sourceRootsRel];
-  const sourceGraph: Graph = await createSourceGraph(packageDir, [], roots);
+  const sourceGraph: Graph = await createEmittedSourceGraph(packageDir, roots);
 
-  code += generateSourceGraph(sourceGraph, packageJson.name);
-  code += generateSourceLinks(sourceGraph, packageJson, generatedIndexPath);
+  code += generateSourceGraph(sourceGraph);
+  code += generateSourceLinks(sourceGraph, packageJson, packageDir, generatedIndexPath);
   code += mergeSourceGraph();
   return code;
 }
@@ -138,19 +138,39 @@ function loadDependencySourceGraphs(packageDir: string, packageJson: any): strin
  * and correct for workspace symlinks (the symlinked package root carries its own dist).
  */
 export function dependencyHasSourceGraph(packageDir: string, packageName: string): boolean {
+  return !!findDependencySourceGraph(packageDir, packageName);
+}
+
+/**
+ * Full path to the dependency's source-graph artifact, or undefined when the dependency is
+ * not installed or not reflection-built. Same walk as `dependencyHasSourceGraph`; exposed for
+ * static graph harvesting (reflection-doctor).
+ */
+export function findDependencySourceGraph(packageDir: string, packageName: string): string | undefined {
+  const dependencyDir = findDependencyDir(packageDir, packageName);
+  if (!dependencyDir) {
+    return undefined;
+  }
+
+  const artifactPath = path.join(dependencyDir, 'dist', 'generated', 'index.js');
+  return fs.existsSync(artifactPath) ? artifactPath : undefined;
+}
+
+/**
+ * The installed location of a dependency, resolved by walking `node_modules` up from the
+ * consuming package — npm-layout resolution: the nearest installed copy shadows hoisted ones.
+ */
+export function findDependencyDir(packageDir: string, packageName: string): string | undefined {
   let currentDir = packageDir;
-  // Upward fs walk; exits are internal (found / package root / fs root).
+  // Upward fs walk; exits are internal (found / fs root).
   for (;;) {
     const candidate = path.join(currentDir, 'node_modules', packageName);
-    if (fs.existsSync(path.join(candidate, 'dist', 'generated', 'index.js'))) {
-      return true;
-    }
     if (fs.existsSync(candidate)) {
-      return false;
+      return candidate;
     }
     const parent = path.dirname(currentDir);
     if (parent === currentDir) {
-      return false;
+      return undefined;
     }
     currentDir = parent;
   }
@@ -210,8 +230,19 @@ function getDependencyImportSpecifier(packageDir: string, packageName: string):
   }
 }
 
-function generateSourceGraph(sourceGraph: Graph, buildTargetPackageName: string): string {
-  removeNonLoadables(sourceGraph, buildTargetPackageName);
+/**
+ * The graph exactly as a build emits it: parsed from the package's source roots, with
+ * build-time-non-loadable declarations pruned. Owned here so build emit and diagnostic
+ * tooling (reflection-doctor drift checks) share one pipeline.
+ */
+export async function createEmittedSourceGraph(packageDir: string, sourceRootsRel: string[]): Promise<Graph> {
+  const packageJson = await getPackageJson(packageDir);
+  const sourceGraph = await createSourceGraph(packageDir, [], sourceRootsRel);
+  removeNonLoadables(sourceGraph, packageJson.name);
+  return sourceGraph;
+}
+
+function generateSourceGraph(sourceGraph: Graph): string {
   let code = `\n\n/** Generate Source Graph */\n\n`;
   const serializedSourceGraph = graphSerializer.serialize(sourceGraph);
   const doubleEscapedSerializedSourceGraph = jsesc(serializedSourceGraph, { json: true }); // since we write to file, need to escape a second time
@@ -288,7 +319,12 @@ function removeNonLoadableNode(
   return shouldRemove;
 }
 
-function generateSourceLinks(sourceGraph: Graph, packageJson: any, generatedIndexPath: string): string {
+function generateSourceLinks(
+  sourceGraph: Graph,
+  packageJson: any,
+  packageDir: string,
+  generatedIndexPath: string
+): string {
   let code = `\n\n/** Generate Source Links */\n\n`;
   const linkableNodes: PackageScope[] = [];
   for (const nodeName of sourceGraph.nodes()) {
@@ -309,7 +345,9 @@ function generateSourceLinks(sourceGraph: Graph, packageJson: any, generatedInde
       continue;
     }
 
-    const relativeImportPath = path.relative(path.dirname(generatedIndexPath), node.filePath);
+    // node.filePath is package-relative (never serialized absolute); resolve against the
+    // package dir to compute the real import location for the generated index.
+    const relativeImportPath = path.relative(path.dirname(generatedIndexPath), path.join(packageDir, node.filePath));
     code += `import { ${node.name} } from '${relativeImportPath.replace(/\.[^/.]+$/, '')}';\n`;
     linkableNodes.push(node);
   }

package/src/parser/createGraphBuilder.ts

@@ -1,3 +1,4 @@
+import * as path from 'path';
 import * as graphlib from '@dagrejs/graphlib';
 import {
   VariableDeclaration as ParserVariableDeclaration,
@@ -17,6 +18,10 @@ import { createInterfaceDeclaration } from './types/createInterfaceDeclaration';
 export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, packageJsonDir: string) {
   const packageName = packageJson.name;
   return async (parsedFile: File): Promise<void> => {
+    // Package-relative: the graph is a serialized, shipped artifact — absolute build-machine
+    // paths (CI runner paths, local checkout paths) must never enter it. Build-time consumers
+    // that need a real location (sourceLink imports) join this with the package dir.
+    const filePath = path.relative(packageJsonDir, parsedFile.filePath);
     for (const declaration of parsedFile.declarations) {
       if (!(declaration as any)['isExported']) {
         continue;
@@ -31,7 +36,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
         const variableDeclaration = await createVariableDeclaration(
           declaration as ParserVariableDeclaration,
           packageNameFinder,
-          parsedFile.filePath
+          filePath
         );
         graph.setNode(
           variableDeclaration.qualifiedName,
@@ -47,7 +52,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
         const typeAliasDeclaration = await createTypeAliasDeclaration(
           declaration as ParserTypeAliasDeclaration,
           packageNameFinder,
-          parsedFile.filePath
+          filePath
         );
         graph.setNode(
           typeAliasDeclaration.qualifiedName,
@@ -63,7 +68,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
         const classDeclaration = await createClassDeclaration(
           declaration as ParserClassDeclaration,
           packageNameFinder,
-          parsedFile.filePath
+          filePath
         );
         graph.setNode(
           classDeclaration.qualifiedName,
@@ -100,7 +105,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
         const interfaceDeclaration = await createInterfaceDeclaration(
           declaration as ParserInterfaceDeclaration,
           packageNameFinder,
-          parsedFile.filePath
+          filePath
         );
         graph.setNode(
           interfaceDeclaration.qualifiedName,

package/src/runBuild.ts

@@ -3,5 +3,11 @@
 import { build } from './build';
 
 (async function () {
-  await build();
+  try {
+    await build({ fix: process.argv.includes('--fix') });
+  } catch (error: any) {
+    // Contract conflicts are a diagnosis for humans — print the message, not a stack trace.
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
 })();

package/src/runDoctor.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { ReflectionDoctor } from './ReflectionDoctor';
+
+(async function () {
+  try {
+    const packageDir = process.env.INIT_CWD || process.cwd();
+    const skipList = (process.env.SKIP_REFLECTION_LOAD || '')
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    const doctor = new ReflectionDoctor(packageDir, { skipList });
+
+    const explainIndex = process.argv.indexOf('--explain');
+    if (explainIndex !== -1) {
+      const target = process.argv[explainIndex + 1];
+      if (!target) {
+        console.error(`usage: reflection-doctor [--explain <name|qualifiedName>]`);
+        process.exit(1);
+      }
+      const explanation = await doctor.explain(target);
+      console.log(explanation.text);
+      return;
+    }
+
+    const report = await doctor.diagnose();
+    console.log(report.text);
+    // Diagnostic exit code: orphans/drift fail CI-style callers.
+    process.exit(report.healthy ? 0 : 1);
+  } catch (error: any) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  }
+})();

package/test/GraphEmitRelativePaths.test.ts

@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { writeGeneratedIndex } from '../src/codegen/writeGeneratedIndex';
+
+/**
+ * The emitted source graph must carry package-relative filePaths (task #104 §3.4 carve-out).
+ * Absolute paths from the build machine leak into every consumer bundle (CI runner paths in
+ * registry packages, local checkout paths in dev bundles) — a path disclosure with zero
+ * runtime value: nothing reads filePath at runtime; it is consumed only at build time to
+ * emit sourceLink imports, before serialization.
+ *
+ * Red-before-green: against pre-fix codegen the emitted graph embeds absolute paths and the
+ * assertions below fail.
+ */
+describe('graph emit: package-relative filePaths', () => {
+  const fixtureA = path.join(__dirname, 'examples', 'source-repository', 'a');
+  // A tmp copy of fixture a (sources only), emitted into its own ./generated — the real build
+  // layout, so path assertions cover exactly what a real build writes.
+  let pkgDir: string;
+  let tmpRoot: string;
+  let emitted: string;
+  let graph: any;
+
+  beforeAll(async () => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-relpaths-'));
+    pkgDir = path.join(tmpRoot, 'a');
+    fs.mkdirSync(pkgDir);
+    for (const entry of ['package.json', 'index.ts', 'src']) {
+      execSync(`cp -R ${path.join(fixtureA, entry)} ${path.join(pkgDir, entry)}`);
+    }
+    const outDir = path.join(pkgDir, 'generated');
+    fs.mkdirSync(outDir);
+    const generatedIndexPath = path.join(outDir, 'index.ts');
+    await writeGeneratedIndex(pkgDir, outDir, generatedIndexPath, ['src']);
+    emitted = fs.readFileSync(generatedIndexPath, 'utf-8');
+
+    // Extract the emitted graph exactly as the runtime would read it: the JSON string literal
+    // assigned to `const sourceGraph`, unescaped once (JSON.parse of the literal), then parsed.
+    const literalMatch = emitted.match(/const sourceGraph = (".*");/);
+    expect(literalMatch).toBeTruthy();
+    const serialized = JSON.parse(literalMatch![1]).replace(/\\'/g, "'");
+    graph = JSON.parse(serialized);
+  });
+
+  afterAll(() => {
+    fs.rmdirSync(tmpRoot, { recursive: true });
+  });
+
+  it('emits no absolute filePath on any graph node', () => {
+    const offenders: string[] = [];
+    for (const node of graph.nodes) {
+      const filePath = node.value?.filePath;
+      if (typeof filePath === 'string' && path.isAbsolute(filePath)) {
+        offenders.push(`${node.v}: ${filePath}`);
+      }
+    }
+    expect(offenders).toEqual([]);
+  });
+
+  it('emits no build-machine path anywhere in the serialized graph string', () => {
+    // The strongest form of the disclosure check: the package's own absolute location
+    // (worktree checkout path here; /home/runner/... in CI) never appears in the artifact.
+    expect(emitted).not.toContain(pkgDir);
+    expect(emitted).not.toContain(fixtureA);
+  });
+
+  it('node filePaths are package-relative and resolve to real source files', () => {
+    const checked: string[] = [];
+    for (const node of graph.nodes) {
+      const filePath = node.value?.filePath;
+      if (typeof filePath !== 'string' || filePath === '') {
+        continue;
+      }
+      expect(fs.existsSync(path.join(pkgDir, filePath))).toBe(true);
+      checked.push(filePath);
+    }
+    // Fixture a declares sources under src/ — the graph must actually carry them.
+    expect(checked.length).toBeGreaterThan(0);
+    expect(checked.every((p) => p.startsWith('src' + path.sep) || p.startsWith('index.'))).toBe(true);
+  });
+
+  it('sourceLink imports still resolve to the linked source files (outcome: links survive)', () => {
+    const importLines = emitted.match(/import \{ .+ \} from '.+';/g) || [];
+    const linkImports = importLines.filter((line) => !line.includes('@proteinjs/reflection'));
+    expect(linkImports.length).toBeGreaterThan(0);
+    for (const line of linkImports) {
+      const spec = line.match(/from '(.+)';/)![1];
+      const resolved = path.resolve(path.join(pkgDir, 'generated'), spec);
+      const exists = fs.existsSync(`${resolved}.ts`) || fs.existsSync(`${resolved}.tsx`);
+      expect(`${spec}: ${exists}`).toBe(`${spec}: true`);
+    }
+  });
+});

package/test/ReflectionDoctor.test.ts

@@ -0,0 +1,193 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { ReflectionDoctor } from '../src/ReflectionDoctor';
+import { writeGeneratedIndex } from '../src/codegen/writeGeneratedIndex';
+
+/**
+ * reflection-doctor (task #104 §3.1): purely analytical CLI — registered-inventory print,
+ * orphan detection (the undeclared-dep/typo class, today silently pruned at runtime), and
+ * --explain parent-edge traces naming the broken hop. Executes no dependency code: graphs
+ * are harvested statically from dist/generated artifacts.
+ *
+ * Red-before-green: written against the finished doctor api/trace format; fails before
+ * ReflectionDoctor exists.
+ */
+describe('ReflectionDoctor', () => {
+  const fixtureA = path.join(__dirname, 'examples', 'source-repository', 'a');
+
+  describe('inventory + healthy fixture (fixture a)', () => {
+    it('reports dependency graphs, own graph size, and no orphans', async () => {
+      const doctor = new ReflectionDoctor(fixtureA);
+      const report = await doctor.diagnose();
+
+      expect(report.dependencies.loaded).toContain('@proteinjs/reflection-build-test-b');
+      expect(report.dependencies.withoutGraph).toContain('@proteinjs/reflection');
+      expect(report.nodeCount).toBeGreaterThan(0);
+      expect(report.edgeCount).toBeGreaterThan(0);
+      expect(report.sourceLinkCount).toBeGreaterThan(0);
+      expect(report.orphans).toEqual([]);
+      expect(report.drift.missingFromDist).toEqual([]);
+      expect(report.drift.onlyInDist).toEqual([]);
+      expect(report.healthy).toBe(true);
+      expect(report.text).toContain('@proteinjs/reflection-build-test-b');
+    });
+
+    it('explains a Loadable chain through a foreign graph, naming each hop', async () => {
+      const doctor = new ReflectionDoctor(fixtureA);
+      const explanation = await doctor.explain('ImplementsLoadableForeignInterface');
+
+      expect(explanation.text).toContain('@proteinjs/reflection-build-test-a/ImplementsLoadableForeignInterface');
+      expect(explanation.text).toContain(
+        'implements interface @proteinjs/reflection-build-test-b/LoadableForeignInterface'
+      );
+      expect(explanation.text).toContain('[edge OK]');
+      expect(explanation.text).toContain('graph @proteinjs/reflection-build-test-b: LOADED');
+      expect(explanation.verdict).toContain('Loadable');
+      expect(explanation.verdict).toContain(`objects('@proteinjs/reflection-build-test-b/LoadableForeignInterface')`);
+    });
+
+    it('explains a deliberately non-Loadable type without inventing a defect', async () => {
+      const doctor = new ReflectionDoctor(fixtureA);
+      const explanation = await doctor.explain('ImplementsNotLoadableForeignInterface');
+
+      expect(explanation.verdict).toContain('NOT Loadable');
+      // The parent package's graph IS loaded; the parent just is not Loadable there.
+      expect(explanation.text).toContain('@proteinjs/reflection-build-test-b/NotLoadableForeignInterface');
+      expect(explanation.text).toContain('not Loadable');
+    });
+  });
+
+  describe('broken chains (crafted fixture)', () => {
+    let pkgDir: string;
+
+    const emitFixture = async (pkgDirToBuild: string) => {
+      const generatedDir = path.join(pkgDirToBuild, 'generated');
+      fs.mkdirSync(generatedDir, { recursive: true });
+      const generatedIndexPath = path.join(generatedDir, 'index.ts');
+      await writeGeneratedIndex(pkgDirToBuild, generatedDir, generatedIndexPath, ['src']);
+      // The doctor reads the built artifact; the sourceGraph/sourceLinks lines it parses are
+      // identical between generated/index.ts and its compiled dist twin.
+      const distGeneratedDir = path.join(pkgDirToBuild, 'dist', 'generated');
+      fs.mkdirSync(distGeneratedDir, { recursive: true });
+      fs.copyFileSync(generatedIndexPath, path.join(distGeneratedDir, 'index.js'));
+    };
+
+    beforeEach(() => {
+      pkgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-doctor-'));
+      fs.writeFileSync(
+        path.join(pkgDir, 'package.json'),
+        JSON.stringify({ name: '@test/doctor-fixture', version: '1.0.0', dependencies: {} }, null, 2)
+      );
+      fs.mkdirSync(path.join(pkgDir, 'src'));
+      fs.writeFileSync(path.join(pkgDir, 'src', 'index.ts'), `export * from './Orphan';\n`);
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'Orphan.ts'),
+        `import { ForeignBase } from '@undeclared/pkg';\n\nexport class Orphan implements ForeignBase {}\n`
+      );
+    });
+
+    afterEach(() => {
+      fs.rmdirSync(pkgDir, { recursive: true });
+    });
+
+    it('detects the orphan: a kept node whose foreign parent resolves in no loaded graph', async () => {
+      await emitFixture(pkgDir);
+      const doctor = new ReflectionDoctor(pkgDir);
+      const report = await doctor.diagnose();
+
+      expect(report.orphans).toHaveLength(1);
+      expect(report.orphans[0].qualifiedName).toBe('@test/doctor-fixture/Orphan');
+      expect(report.orphans[0].unresolvedParent).toBe('@undeclared/pkg/ForeignBase');
+      expect(report.orphans[0].cause).toContain('not a declared dependency');
+      expect(report.healthy).toBe(false);
+      expect(report.text).toContain('@undeclared/pkg/ForeignBase');
+    });
+
+    it('--explain names the broken hop and the cause', async () => {
+      await emitFixture(pkgDir);
+      const doctor = new ReflectionDoctor(pkgDir);
+      const explanation = await doctor.explain('Orphan');
+
+      expect(explanation.text).toContain('implements interface @undeclared/pkg/ForeignBase');
+      expect(explanation.text).toContain('graph @undeclared/pkg: NOT LOADED');
+      expect(explanation.verdict).toContain('NOT Loadable');
+      expect(explanation.verdict).toContain('@undeclared/pkg/ForeignBase');
+      expect(explanation.verdict).toContain('not a declared dependency');
+    });
+
+    it('classifies a declared-but-not-reflection-built dependency', async () => {
+      const packageJson = JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+      packageJson.dependencies['@undeclared/pkg'] = '1.0.0';
+      fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+      const depDir = path.join(pkgDir, 'node_modules', '@undeclared', 'pkg');
+      fs.mkdirSync(depDir, { recursive: true });
+      fs.writeFileSync(path.join(depDir, 'package.json'), JSON.stringify({ name: '@undeclared/pkg' }));
+
+      await emitFixture(pkgDir);
+      const doctor = new ReflectionDoctor(pkgDir);
+      const report = await doctor.diagnose();
+
+      expect(report.orphans).toHaveLength(1);
+      expect(report.orphans[0].cause).toContain('not reflection-built');
+      expect(report.dependencies.withoutGraph).toContain('@undeclared/pkg');
+    });
+
+    it('does not report inline type-expression parents as orphans (the ArrayMembershipOp class)', async () => {
+      // A union alias with a doc comment inside: the parser captures the raw expression as a
+      // parent name (leading '/'), dodging the '{'-name guard — a junk, never-resolvable
+      // parent edge. The doctor must classify it as inline-expression noise, not as an
+      // undeclared dependency.
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'Ops.ts'),
+        `export type MembershipOp =\n  /** Insert */\n  | { op: 'add'; id: string }\n  /** Remove */\n  | { op: 'remove'; id: string };\n`
+      );
+      await emitFixture(pkgDir);
+
+      const doctor = new ReflectionDoctor(pkgDir);
+      const report = await doctor.diagnose();
+      // Only the real orphan remains; the junk parent is excluded.
+      expect(report.orphans).toHaveLength(1);
+      expect(report.orphans[0].unresolvedParent).toBe('@undeclared/pkg/ForeignBase');
+    });
+
+    it('detects drift: sources added after the artifact was built', async () => {
+      await emitFixture(pkgDir);
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'Late.ts'),
+        `import { ForeignBase } from '@undeclared/pkg';\n\nexport class Late implements ForeignBase {}\n`
+      );
+
+      const doctor = new ReflectionDoctor(pkgDir);
+      const report = await doctor.diagnose();
+      expect(report.drift.missingFromDist).toContain('@test/doctor-fixture/Late');
+      expect(report.healthy).toBe(false);
+    });
+
+    it('--explain diagnoses a declaration that exists but is not exported', async () => {
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'Hidden.ts'),
+        `import { ForeignBase } from '@undeclared/pkg';\n\nclass Hidden implements ForeignBase {}\n`
+      );
+      await emitFixture(pkgDir);
+
+      const doctor = new ReflectionDoctor(pkgDir);
+      const explanation = await doctor.explain('Hidden');
+      expect(explanation.verdict).toContain('not exported');
+      expect(explanation.text).toContain('Hidden.ts');
+    });
+
+    it('--explain diagnoses a stale dist: declaration in sources but not in the artifact', async () => {
+      await emitFixture(pkgDir);
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'Late.ts'),
+        `import { ForeignBase } from '@undeclared/pkg';\n\nexport class Late implements ForeignBase {}\n`
+      );
+
+      const doctor = new ReflectionDoctor(pkgDir);
+      const explanation = await doctor.explain('Late');
+      expect(explanation.verdict.toLowerCase()).toContain('stale');
+      expect(explanation.verdict).toContain('rebuild');
+    });
+  });
+});

package/test/TestSubpathContract.test.ts

@@ -0,0 +1,148 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { build } from '../src/build';
+
+/**
+ * The ./test subpath contract (task #104 §3.2, the d51556f0 class): the test subpath is a
+ * reflection-build feature, so reflection-build owns the COMPLETE artifact contract for it —
+ * root stubs, exports/typesVersions mappings, files[] entries, tsconfig excludes — instead of
+ * every package hand-rolling the d51556f0 shims and drifting.
+ *
+ * Contract pieces, validated/emitted on every subpath build (primary root != 'src'):
+ * - root <root>.js / <root>.d.ts stubs re-exporting dist/generated/<root>/index — win the
+ *   node10/paths-mapped file lookup so consumers resolve built dist, never sources (TS6059)
+ * - exports: "." and "./<root>" mapped to the built artifacts (node16/modern resolution)
+ * - typesVersions: "<root>" mapped for node10 TYPES resolution
+ * - files[]: stub entries added when a files allowlist exists (published tarballs keep them)
+ * - tsconfig exclude: the stubs never become compiler inputs
+ *
+ * Red-before-green: against pre-change code nothing emits any of this — every assertion fails.
+ */
+describe('test-subpath contract', () => {
+  let pkgDir: string;
+  const savedEnv: { [key: string]: string | undefined } = {};
+
+  const writeFixture = (packageJson: any) => {
+    pkgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-subpath-'));
+    fs.writeFileSync(path.join(pkgDir, 'package.json'), JSON.stringify(packageJson, null, 2));
+    fs.mkdirSync(path.join(pkgDir, 'src'));
+    fs.writeFileSync(path.join(pkgDir, 'src', 'index.ts'), `export * from './Example';\n`);
+    fs.writeFileSync(path.join(pkgDir, 'src', 'Example.ts'), `export class Example {}\n`);
+    fs.mkdirSync(path.join(pkgDir, 'test'));
+    fs.writeFileSync(path.join(pkgDir, 'test', 'index.ts'), `export * from './TestHelper';\n`);
+    fs.writeFileSync(path.join(pkgDir, 'test', 'TestHelper.ts'), `export class TestHelper {}\n`);
+    process.env.INIT_CWD = pkgDir;
+    process.env.REFLECTION_SOURCE_DIRS = 'test,src';
+    process.env.REFLECTION_EXPORT_FROM = 'test/index.ts';
+  };
+
+  const readPackageJson = () => JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8'));
+  const readTsconfig = () => JSON.parse(fs.readFileSync(path.join(pkgDir, 'tsconfig.json'), 'utf-8'));
+
+  beforeEach(() => {
+    for (const key of ['INIT_CWD', 'REFLECTION_SOURCE_DIRS', 'REFLECTION_EXPORT_FROM', 'REFLECTION_DIST_DIR']) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(savedEnv)) {
+      if (typeof savedEnv[key] === 'undefined') {
+        delete process.env[key];
+      } else {
+        process.env[key] = savedEnv[key];
+      }
+    }
+    fs.rmdirSync(pkgDir, { recursive: true });
+  });
+
+  it('emits root stubs that resolve the subpath to built dist in every install shape', async () => {
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0' });
+    await build();
+
+    const stubJs = fs.readFileSync(path.join(pkgDir, 'test.js'), 'utf-8');
+    expect(stubJs).toContain(`require('./dist/generated/test/index.js')`);
+    const stubDts = fs.readFileSync(path.join(pkgDir, 'test.d.ts'), 'utf-8');
+    expect(stubDts).toContain(`export * from './dist/generated/test/index'`);
+  });
+
+  it('maps the subpath in exports and typesVersions', async () => {
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0' });
+    await build();
+
+    const packageJson = readPackageJson();
+    expect(packageJson.exports['.']).toEqual({
+      types: './dist/generated/index.d.ts',
+      default: './dist/generated/index.js',
+    });
+    expect(packageJson.exports['./test']).toEqual({
+      types: './dist/generated/test/index.d.ts',
+      default: './dist/generated/test/index.js',
+    });
+    expect(packageJson.typesVersions['*']['test']).toEqual(['dist/generated/test/index.d.ts']);
+  });
+
+  it('keeps extra exports subpaths a package added on its own', async () => {
+    writeFixture({
+      name: '@test/subpath-fixture',
+      version: '1.0.0',
+      exports: { './extra': './dist/extra.js' },
+    });
+    await build();
+
+    const packageJson = readPackageJson();
+    expect(packageJson.exports['./extra']).toBe('./dist/extra.js');
+    expect(packageJson.exports['./test']).toEqual({
+      types: './dist/generated/test/index.d.ts',
+      default: './dist/generated/test/index.js',
+    });
+  });
+
+  it('adds stub entries to an existing files allowlist, and leaves absent files[] absent', async () => {
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0', files: ['dist/**'] });
+    await build();
+    expect(readPackageJson().files).toEqual(expect.arrayContaining(['dist/**', 'test.js', 'test.d.ts']));
+
+    fs.rmdirSync(pkgDir, { recursive: true });
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0' });
+    await build();
+    expect(readPackageJson().files).toBeUndefined();
+  });
+
+  it('excludes the stubs from compilation in tsconfig without clobbering default excludes', async () => {
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0' });
+    await build();
+
+    const tsconfig = readTsconfig();
+    expect(tsconfig.exclude).toEqual(expect.arrayContaining(['node_modules', 'test.js', 'test.d.ts']));
+  });
+
+  it('fails friendly on a conflicting subpath mapping and leaves package.json untouched', async () => {
+    writeFixture({
+      name: '@test/subpath-fixture',
+      version: '1.0.0',
+      exports: { './test': './dist/somewhere-else.js' },
+    });
+    fs.mkdirSync(path.join(pkgDir, 'dist'));
+    fs.writeFileSync(path.join(pkgDir, 'dist', 'somewhere-else.js'), 'module.exports = {};\n');
+    const before = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+
+    await expect(build()).rejects.toThrow(/--fix/);
+    expect(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8')).toBe(before);
+  });
+
+  it('is idempotent: a second build changes nothing', async () => {
+    writeFixture({ name: '@test/subpath-fixture', version: '1.0.0', files: ['dist/**'] });
+    await build();
+    const packageJsonAfterFirst = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    const stubAfterFirst = fs.readFileSync(path.join(pkgDir, 'test.js'), 'utf-8');
+    const tsconfigAfterFirst = fs.readFileSync(path.join(pkgDir, 'tsconfig.json'), 'utf-8');
+
+    await build();
+    expect(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8')).toBe(packageJsonAfterFirst);
+    expect(fs.readFileSync(path.join(pkgDir, 'test.js'), 'utf-8')).toBe(stubAfterFirst);
+    expect(fs.readFileSync(path.join(pkgDir, 'tsconfig.json'), 'utf-8')).toBe(tsconfigAfterFirst);
+  });
+});