@proteinjs/reflection-build 1.4.12 → 2.0.0

package/src/codegen/writeGeneratedIndex.ts

@@ -1,3 +1,4 @@
+import * as fs from 'fs';
 import * as path from 'path';
 import { promisifiedFs } from '@proteinjs/util-node';
 import { graphSerializer, isInstanceOf } from '@proteinjs/util';
@@ -76,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;
 }
@@ -103,12 +104,19 @@ function loadDependencySourceGraphs(packageDir: string, packageJson: any): strin
 
   if (packageJson.dependencies) {
     for (const packageName in packageJson.dependencies) {
-      // Skip any packages listed in SKIP_REFLECTION_LOAD
+      // Skip any packages listed in SKIP_REFLECTION_LOAD (deliberate opt-out for deps that
+      // DO carry a graph but should not load in this package's context)
       if (skipList.includes(packageName)) {
         continue;
       }
 
-      if (packageName.startsWith('@material-ui')) {
+      // Only reflection-built dependencies belong here: the import exists solely to run the
+      // dependency's generated index (SourceRepository.merge of its source graph). A dep is
+      // reflection-built iff it ships the artifact this same codegen emits —
+      // dist/generated/index.js. Everything else (icon sets, ui libs, utilities) contributed
+      // nothing at runtime while pinning its entire dependency root into every consumer's
+      // bundle (observed: ~19 duplicate FontAwesome set copies across the app bundle).
+      if (!dependencyHasSourceGraph(packageDir, packageName)) {
         continue;
       }
 
@@ -123,6 +131,51 @@ function loadDependencySourceGraphs(packageDir: string, packageJson: any): strin
   return code;
 }
 
+/**
+ * True iff the dependency ships a reflection source graph (`dist/generated/index.js`, the
+ * artifact `writeGeneratedIndex` itself emits). Located by walking `node_modules` up from the
+ * consuming package — the npm layout lookup, immune to `exports`-map resolution restrictions
+ * 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 / fs root).
+  for (;;) {
+    const candidate = path.join(currentDir, 'node_modules', packageName);
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = path.dirname(currentDir);
+    if (parent === currentDir) {
+      return undefined;
+    }
+    currentDir = parent;
+  }
+}
+
 /**
  * Determine an import specifier for a dependency that respects its package.json exports or main/module fields.
  */
@@ -177,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
@@ -255,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()) {
@@ -276,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/DependencySourceGraphGate.test.ts

@@ -0,0 +1,61 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { dependencyHasSourceGraph } from '../src/codegen/writeGeneratedIndex';
+
+/**
+ * The dependency-import gate (MOBILE_SUPPORT S11 bundle diet): generated indexes import a
+ * dependency iff it ships `dist/generated/index.js` — the artifact writeGeneratedIndex
+ * itself emits. Outcome tests over a real on-disk npm layout, including the hoisted case.
+ */
+describe('dependencyHasSourceGraph', () => {
+  let root: string;
+
+  const mkpkg = (base: string, name: string, withGraph: boolean) => {
+    const dir = path.join(base, 'node_modules', name);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name, version: '1.0.0' }));
+    if (withGraph) {
+      const gen = path.join(dir, 'dist', 'generated');
+      fs.mkdirSync(gen, { recursive: true });
+      fs.writeFileSync(path.join(gen, 'index.js'), '// sourceGraph artifact');
+    }
+  };
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-gate-'));
+  });
+
+  afterEach(() => {
+    fs.rmdirSync(root, { recursive: true });
+  });
+
+  it('accepts a dependency that ships dist/generated/index.js', () => {
+    mkpkg(root, '@scope/reflected-dep', true);
+    expect(dependencyHasSourceGraph(root, '@scope/reflected-dep')).toBe(true);
+  });
+
+  it('rejects a resolvable dependency without the artifact (icon sets, ui libs)', () => {
+    mkpkg(root, '@fortawesome/pro-solid-svg-icons', false);
+    expect(dependencyHasSourceGraph(root, '@fortawesome/pro-solid-svg-icons')).toBe(false);
+  });
+
+  it('finds the artifact through hoisted node_modules (walks up like npm resolution)', () => {
+    const consumer = path.join(root, 'node_modules', '@scope', 'consumer');
+    fs.mkdirSync(consumer, { recursive: true });
+    mkpkg(root, '@scope/hoisted-reflected', true);
+    expect(dependencyHasSourceGraph(consumer, '@scope/hoisted-reflected')).toBe(true);
+  });
+
+  it('stops at the nearest resolved copy: a local artifact-less copy shadows a hoisted one', () => {
+    const consumer = path.join(root, 'pkg');
+    fs.mkdirSync(consumer, { recursive: true });
+    mkpkg(consumer, 'dep', false);
+    mkpkg(root, 'dep', true);
+    expect(dependencyHasSourceGraph(consumer, 'dep')).toBe(false);
+  });
+
+  it('rejects an unresolvable dependency', () => {
+    expect(dependencyHasSourceGraph(root, 'not-installed-anywhere')).toBe(false);
+  });
+});

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');
+    });
+  });
+});