@proteinjs/reflection-build 1.5.0 → 2.0.1

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/parser/types/createClassDeclaration.ts

@@ -9,14 +9,14 @@ export async function createClassDeclaration(
   packageNameFinder: PackageNameFinder,
   filePath: string
 ): Promise<ClassDeclaration> {
-  let isAbstract = false;
+  // Class-level truth, recorded by the parser from the class node's own `abstract` modifier.
+  // Never derive this from members: an abstract class need not declare any abstract member
+  // (the 2026-08 MachineAccount mis-stamp — abstract properties, concrete accessors — was
+  // emitted `isAbstract: false` by an accessor scan, and the runtime instantiated it).
+  const isAbstract = parserClassDeclaration.isAbstract;
   let isStatic = false;
   let visibility: Visibility = 'public';
   for (const accessor of parserClassDeclaration.accessors) {
-    if (accessor.isAbstract) {
-      isAbstract = true;
-    }
-
     if (accessor.isStatic) {
       isStatic = true;
     }

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/AbstractClassDeclaration.test.ts

@@ -0,0 +1,97 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { createSourceGraph } from '../src/parser/createSourceGraph';
+
+/**
+ * The parser must stamp `isAbstract: true` on a class declared `abstract` — the runtime's
+ * only defense against instantiating an abstract class (`objects()` filters on it) is this flag.
+ *
+ * The real-world mis-stamp (2026-08-21): `MachineAccount`, an `export abstract class` with
+ * generics implementing an interface, was emitted with `isAbstract: false` into a generated
+ * source graph. Root cause: `createClassDeclaration` derived class abstractness by scanning the
+ * class's get/set ACCESSORS for the `abstract` modifier — the vendored typescript-parser never
+ * recorded the class-level `abstract` keyword at all. Any abstract class without an abstract
+ * accessor member (i.e. nearly all of them, MachineAccount included: abstract PROPERTIES plus
+ * concrete getters) was stamped concrete.
+ */
+
+const PACKAGE_NAME = '@test/machine-account-shape';
+
+// Mirrors the real MachineAccount shape: export abstract class, generic interface implemented,
+// abstract properties, concrete get accessors — and NO abstract accessors.
+const MACHINE_ACCOUNT_SHAPE = `
+import { SourceRecordLoader } from '@proteinjs/db';
+import { User } from './User';
+
+export abstract class MachineAccount implements SourceRecordLoader<User> {
+  abstract id: string;
+  abstract email: string;
+  abstract accountName: string;
+  abstract roles: string[];
+  abstract secretName: string;
+
+  get table(): string {
+    return 'user';
+  }
+
+  get record(): SourceRecordLoader<User>['record'] {
+    return {} as SourceRecordLoader<User>['record'];
+  }
+}
+
+export class ConcreteMachineAccount extends MachineAccount {
+  id = '1';
+  email = 'machine@example.com';
+  accountName = 'machine';
+  roles: string[] = [];
+  secretName = 'machine-secret';
+}
+`;
+
+const OTHER_ABSTRACT_SHAPES = `
+export abstract class PlainAbstract {
+  abstract run(): void;
+}
+
+abstract class UnexportedAbstract {
+  abstract run(): void;
+}
+export { UnexportedAbstract };
+`;
+
+describe('parser stamps class-level isAbstract', () => {
+  let dir: string;
+  let graph: any;
+
+  beforeAll(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'abstract-class-declaration-'));
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: PACKAGE_NAME }));
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(path.join(dir, 'src', 'MachineAccount.ts'), MACHINE_ACCOUNT_SHAPE);
+    fs.writeFileSync(path.join(dir, 'src', 'OtherAbstractShapes.ts'), OTHER_ABSTRACT_SHAPES);
+    graph = await createSourceGraph(dir);
+  });
+
+  afterAll(() => {
+    fs.rmdirSync(dir, { recursive: true });
+  });
+
+  test('abstract class with generics implementing an interface (the MachineAccount shape) is stamped isAbstract: true', () => {
+    const machineAccount = graph.node(`${PACKAGE_NAME}/MachineAccount`);
+    expect(machineAccount).toBeTruthy();
+    expect(machineAccount.isAbstract).toBe(true);
+  });
+
+  test('plain export abstract class is stamped isAbstract: true', () => {
+    const plainAbstract = graph.node(`${PACKAGE_NAME}/PlainAbstract`);
+    expect(plainAbstract).toBeTruthy();
+    expect(plainAbstract.isAbstract).toBe(true);
+  });
+
+  test('concrete subclass is stamped isAbstract: false', () => {
+    const concrete = graph.node(`${PACKAGE_NAME}/ConcreteMachineAccount`);
+    expect(concrete).toBeTruthy();
+    expect(concrete.isAbstract).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');
+    });
+  });
+});