@proteinjs/reflection-build 2.0.2 → 2.1.0

package/src/parser/createGraphBuilder.ts

@@ -1,4 +1,3 @@
-import * as path from 'path';
 import * as graphlib from '@dagrejs/graphlib';
 import {
   VariableDeclaration as ParserVariableDeclaration,
@@ -14,14 +13,30 @@ import { PackageNameFinder } from './types/PackageNameFinder';
 import { createTypeAliasDeclaration } from './types/createTypeAliasDeclaration';
 import { createClassDeclaration } from './types/createClassDeclaration';
 import { createInterfaceDeclaration } from './types/createInterfaceDeclaration';
+import { PackageSourceFiles } from './PackageSourceFiles';
+import { SharedQualifiedNames } from './SharedQualifiedNames';
 
-export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, packageJsonDir: string) {
+/**
+ * @param sharedNames  records the file of every declaration set on the graph: the graph keeps one
+ *                     node per qualified name, so it cannot show a name two files declare
+ */
+export function createGraphBuilder(
+  graph: graphlib.Graph,
+  packageJson: any,
+  packageJsonDir: string,
+  sharedNames: SharedQualifiedNames
+) {
   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);
+    // Package-relative with `/` separators: the graph is a serialized, shipped artifact —
+    // absolute build-machine paths (CI runner paths, local checkout paths) and the platform's
+    // separator must never enter it. Build-time consumers that need a real location
+    // (sourceLink imports) join this with the package dir.
+    const filePath = PackageSourceFiles.relativePath(packageJsonDir, parsedFile.filePath);
+    const setDeclaration = (qualifiedName: string, value: object) => {
+      graph.setNode(qualifiedName, value);
+      sharedNames.record(qualifiedName, filePath);
+    };
     for (const declaration of parsedFile.declarations) {
       if (!(declaration as any)['isExported']) {
         continue;
@@ -38,7 +53,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
           packageNameFinder,
           filePath
         );
-        graph.setNode(
+        setDeclaration(
           variableDeclaration.qualifiedName,
           Object.assign(variableDeclaration, { sourceType: SourceType.variable })
         );
@@ -54,7 +69,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
           packageNameFinder,
           filePath
         );
-        graph.setNode(
+        setDeclaration(
           typeAliasDeclaration.qualifiedName,
           Object.assign(typeAliasDeclaration, { sourceType: SourceType.typeAlias })
         );
@@ -70,7 +85,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
           packageNameFinder,
           filePath
         );
-        graph.setNode(
+        setDeclaration(
           classDeclaration.qualifiedName,
           Object.assign(classDeclaration, { sourceType: SourceType.class })
         );
@@ -107,7 +122,7 @@ export function createGraphBuilder(graph: graphlib.Graph, packageJson: any, pack
           packageNameFinder,
           filePath
         );
-        graph.setNode(
+        setDeclaration(
           interfaceDeclaration.qualifiedName,
           Object.assign(interfaceDeclaration, { sourceType: SourceType.interface })
         );

package/src/parser/createSourceGraph.ts

@@ -1,14 +1,20 @@
 import * as graphlib from '@dagrejs/graphlib';
-import globby from 'globby';
 import * as path from 'path';
 import { TypescriptParser } from '../../modules/typescript-parser';
 import { promisifiedFs } from '@proteinjs/util-node';
 import { createGraphBuilder } from './createGraphBuilder';
+import { PackageSourceFiles } from './PackageSourceFiles';
+import { SharedQualifiedNames } from './SharedQualifiedNames';
 
+/**
+ * @param sharedNames  receives the file of every declaration the graph holds a node for; the
+ *                     build reads the names two files declare from it after the prune
+ */
 export async function createSourceGraph(
   dir: string,
   excludedDirs: string[] = [],
-  sourceRootsRel: string | string[] = 'src'
+  sourceRootsRel: string | string[] = 'src',
+  sharedNames: SharedQualifiedNames = new SharedQualifiedNames()
 ) {
   const packageJsonPath = path.join(dir, 'package.json');
   if (!(await promisifiedFs.exists(packageJsonPath))) {
@@ -17,24 +23,16 @@ export async function createSourceGraph(
 
   const packageJson = require(packageJsonPath);
   const roots = Array.isArray(sourceRootsRel) ? sourceRootsRel : [sourceRootsRel];
-
-  const patterns: string[] = [];
-  for (const rel of roots) {
-    const root = path.join(dir, rel);
-    patterns.push(path.join(root, '**/*.ts'));
-    patterns.push(path.join(root, '**/*.tsx'));
-  }
-
-  const excludePatterns = ['!**/node_modules/**', '!**/generated/**', ...excludedDirs.map((d) => `!${d}`)];
-
-  const sourceFilePaths = await globby([...patterns, ...excludePatterns]);
-  const uniqueFilePaths = Array.from(new Set(sourceFilePaths));
+  const sourceFilePaths = await new PackageSourceFiles(dir, roots, excludedDirs).list();
 
   const graph = new graphlib.Graph();
-  const addSourceFile = createGraphBuilder(graph, packageJson, dir);
+  const addSourceFile = createGraphBuilder(graph, packageJson, dir, sharedNames);
   const parser = new TypescriptParser();
 
-  for (const sourceFilePath of uniqueFilePaths) {
+  // Sequential, in PackageSourceFiles order: the parse order is part of the graph's content (a
+  // name exported by two files holds the declaration parsed last — the build refuses such a name
+  // when it survives the prune) and the order `sharedNames` lists the declaring files in.
+  for (const sourceFilePath of sourceFilePaths) {
     const sourceFile = await parser.parseFile(sourceFilePath, path.dirname(sourceFilePath));
     await addSourceFile(sourceFile);
   }

package/test/Class.test.ts

@@ -60,7 +60,7 @@ test('do not load non-loadable classes', async () => {
   ).toBeUndefined();
   expect(
     sourceRepository.flattenedSourceGraph.classes[
-      '@proteinjs/reflection-build-test-a/ImplementsExtendsLocalNotLoadableInterface'
+      '@proteinjs/reflection-build-test-a/ImplementsExtendsNotLoadableForeignInterface'
     ]
   ).toBeUndefined();
   expect(

package/test/ExamplePackageFixture.ts

@@ -0,0 +1,142 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { execFileSync } from 'child_process';
+import { build } from '../src/build';
+
+/**
+ * Disposable copies of an example package under `test/examples`, each at its own absolute
+ * location, built the way the `reflection-build` bin builds a package (the package dir arrives
+ * as INIT_CWD), compiled with tsc and packed with `npm pack` — so a test can compare what two
+ * builds of the same sources ship, or what one build refuses.
+ */
+export class ExamplePackageFixture {
+  private static readonly NODE_MODULES = path.join(__dirname, '..', 'node_modules');
+  private readonly sources: string;
+  private readonly tmpRoot: string;
+  private readonly links: string[] = [];
+
+  /**
+   * @param example      the example's directory under `test/examples`
+   * @param packageName  the name its copies are built under (a fixture name, never a published package's)
+   */
+  constructor(
+    example: string,
+    readonly packageName: string
+  ) {
+    this.sources = path.join(__dirname, 'examples', example);
+    this.tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), `refl-${example}-`));
+  }
+
+  /** `packageName/name`: the qualified name this package declares `name` under. */
+  qualified(name: string): string {
+    return `${this.packageName}/${name}`;
+  }
+
+  /** Copies the example package to `<tmp>/<location>` and returns its absolute path. */
+  materialize(location: string): string {
+    const packageDir = path.join(this.tmpRoot, location);
+    fs.mkdirSync(path.dirname(packageDir), { recursive: true });
+    this.copyTree(this.sources, packageDir);
+    fs.writeFileSync(path.join(packageDir, 'package.json'), JSON.stringify(this.packageJson(), null, 2));
+    fs.writeFileSync(path.join(packageDir, 'tsconfig.json'), JSON.stringify(this.tsconfig(), null, 2));
+    const link = path.join(packageDir, 'node_modules');
+    fs.symlinkSync(ExamplePackageFixture.NODE_MODULES, link, 'dir');
+    this.links.push(link);
+    return packageDir;
+  }
+
+  /** Runs reflection-build in `packageDir`; returns the generated index it wrote (rejects when the build refuses). */
+  async generate(packageDir: string): Promise<string> {
+    const initCwd = process.env.INIT_CWD;
+    process.env.INIT_CWD = packageDir;
+    try {
+      await build();
+    } finally {
+      if (initCwd === undefined) {
+        delete process.env.INIT_CWD;
+      } else {
+        process.env.INIT_CWD = initCwd;
+      }
+    }
+    return fs.readFileSync(path.join(packageDir, 'generated', 'index.ts'), 'utf-8');
+  }
+
+  /** tsc over the package (its tsconfig includes the generated index). */
+  compile(packageDir: string): void {
+    execFileSync(process.execPath, [require.resolve('typescript/bin/tsc'), '-p', packageDir], { stdio: 'pipe' });
+  }
+
+  /** `npm pack` of the package; returns the tarball's sha256. */
+  packSha256(packageDir: string): string {
+    const destination = fs.mkdtempSync(path.join(this.tmpRoot, 'pack-'));
+    execFileSync('npm', ['pack', '--pack-destination', destination], { cwd: packageDir, stdio: 'pipe' });
+    const [tarball] = fs.readdirSync(destination);
+    return this.sha256(fs.readFileSync(path.join(destination, tarball)));
+  }
+
+  sha256(bytes: Buffer | string): string {
+    return crypto.createHash('sha256').update(bytes).digest('hex');
+  }
+
+  /** The source graph a generated index embeds, read the way the runtime reads it. */
+  graphOf(generatedIndex: string): { nodes: { v: string; value?: any }[]; edges: { v: string; w: string }[] } {
+    const literal = generatedIndex.match(/const sourceGraph = (".*");/);
+    if (!literal) {
+      throw new Error('no serialized sourceGraph in the generated index');
+    }
+    return JSON.parse(JSON.parse(literal[1]).replace(/\\'/g, "'"));
+  }
+
+  /** Removes the copies; each linked node_modules is unlinked first, never descended into. */
+  dispose(): void {
+    for (const link of this.links) {
+      fs.unlinkSync(link);
+    }
+    execFileSync('rm', ['-rf', this.tmpRoot]);
+  }
+
+  private packageJson(): object {
+    return {
+      name: this.packageName,
+      version: '0.0.1',
+      private: true,
+      main: './dist/generated/index.js',
+      types: './dist/generated/index.d.ts',
+      files: ['dist/**'],
+      dependencies: { '@proteinjs/reflection': '^1.2.1' },
+    };
+  }
+
+  private tsconfig(): object {
+    return {
+      compilerOptions: {
+        noEmitOnError: true,
+        target: 'es5',
+        module: 'commonjs',
+        declaration: true,
+        sourceMap: true,
+        outDir: './dist/',
+        strict: true,
+        esModuleInterop: true,
+        skipLibCheck: true,
+        types: [],
+      },
+      include: ['./index.ts', './generated/index.ts'],
+    };
+  }
+
+  private copyTree(from: string, to: string): void {
+    fs.mkdirSync(to, { recursive: true });
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+      const source = path.join(from, entry.name);
+      const target = path.join(to, entry.name);
+      if (entry.isDirectory()) {
+        this.copyTree(source, target);
+      } else {
+        fs.copyFileSync(source, target);
+      }
+    }
+  }
+}

package/test/GraphEmitRelativePaths.test.ts

@@ -78,7 +78,7 @@ describe('graph emit: package-relative filePaths', () => {
     }
     // 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);
+    expect(checked.every((p) => p.startsWith('src/') || p.startsWith('index.'))).toBe(true);
   });
 
   it('sourceLink imports still resolve to the linked source files (outcome: links survive)', () => {

package/test/PackageSourceFiles.test.ts

@@ -0,0 +1,42 @@
+import * as path from 'path';
+import { PackageSourceFiles } from '../src/parser/PackageSourceFiles';
+
+/**
+ * The two machine-specific inputs `PackageSourceFiles` closes where they enter the generated
+ * index: the platform's path separator and the machine's collation. The Windows half cannot run
+ * on the machine that runs this suite, so the class is loaded once more against `path.win32` in
+ * an isolated module registry — the same code, Windows paths in.
+ */
+describe('PackageSourceFiles', () => {
+  test('relativePath writes / separators and no leading ./ from Windows paths', () => {
+    jest.isolateModules(() => {
+      jest.doMock('path', () => path.win32);
+      const { PackageSourceFiles: OnWindows } = require('../src/parser/PackageSourceFiles');
+      expect(OnWindows.relativePath('C:\\work\\pkg', 'C:\\work\\pkg\\src\\beta\\deep\\Gamma.ts')).toBe(
+        'src/beta/deep/Gamma.ts'
+      );
+      expect(OnWindows.relativePath('C:\\work\\pkg\\generated', 'C:\\work\\pkg\\src\\alpha\\Alpha.ts')).toBe(
+        '../src/alpha/Alpha.ts'
+      );
+      expect(OnWindows.relativePath('C:\\work\\pkg\\generated', 'C:\\work\\pkg')).toBe('..');
+    });
+  });
+
+  test('relativePath writes the same form from POSIX paths', () => {
+    expect(PackageSourceFiles.relativePath('/work/pkg', '/work/pkg/src/beta/deep/Gamma.ts')).toBe(
+      'src/beta/deep/Gamma.ts'
+    );
+    expect(PackageSourceFiles.relativePath('/work/pkg/generated', '/work/pkg/src/alpha/Alpha.ts')).toBe(
+      '../src/alpha/Alpha.ts'
+    );
+  });
+
+  test('compare orders by code unit, so upper case sorts before lower case on every machine', () => {
+    // 'Z' is 0x5a, 'd' is 0x64: code-unit order puts ZetaPlugin first; a locale collation would not.
+    expect(PackageSourceFiles.compare('src/zeta/ZetaPlugin.ts', 'src/zeta/defaults.ts')).toBeLessThan(0);
+    expect(PackageSourceFiles.compare('src/zeta/defaults.ts', 'src/zeta/ZetaPlugin.ts')).toBeGreaterThan(0);
+    expect(PackageSourceFiles.compare('src/a.ts', 'src/a.ts')).toBe(0);
+    // A shorter path sorts before its extension: 'SourceRecord.ts' before 'SourceRecordLoader.ts' ('.' is 0x2e, 'L' is 0x4c).
+    expect(PackageSourceFiles.compare('src/SourceRecord.ts', 'src/SourceRecordLoader.ts')).toBeLessThan(0);
+  });
+});

package/test/ReflectionDoctor.test.ts

@@ -16,6 +16,18 @@ import { writeGeneratedIndex } from '../src/codegen/writeGeneratedIndex';
 describe('ReflectionDoctor', () => {
   const fixtureA = path.join(__dirname, 'examples', 'source-repository', 'a');
 
+  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'));
+  };
+
   describe('inventory + healthy fixture (fixture a)', () => {
     it('reports dependency graphs, own graph size, and no orphans', async () => {
       const doctor = new ReflectionDoctor(fixtureA);
@@ -61,18 +73,6 @@ describe('ReflectionDoctor', () => {
   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(
@@ -190,4 +190,42 @@ describe('ReflectionDoctor', () => {
       expect(explanation.verdict).toContain('rebuild');
     });
   });
+
+  describe('a name two files declare (crafted fixture)', () => {
+    let pkgDir: string;
+
+    beforeEach(() => {
+      pkgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-doctor-shared-'));
+      fs.writeFileSync(
+        path.join(pkgDir, 'package.json'),
+        JSON.stringify({ name: '@test/doctor-shared-name', version: '1.0.0', dependencies: {} }, null, 2)
+      );
+      fs.mkdirSync(path.join(pkgDir, 'src', 'alpha'), { recursive: true });
+      fs.writeFileSync(path.join(pkgDir, 'src', 'index.ts'), `export * from './alpha/Widget';\n`);
+      fs.writeFileSync(
+        path.join(pkgDir, 'src', 'alpha', 'Widget.ts'),
+        `import { Loadable } from '@proteinjs/reflection';\n\nexport interface Widget extends Loadable {}\n`
+      );
+    });
+
+    afterEach(() => {
+      fs.rmdirSync(pkgDir, { recursive: true });
+    });
+
+    it('reports a name that reaches the graph from two files, with every declaring file, as the build would refuse it', async () => {
+      // Built while one file declared the name; a second file declares it since.
+      await emitFixture(pkgDir);
+      fs.mkdirSync(path.join(pkgDir, 'src', 'beta'));
+      fs.writeFileSync(path.join(pkgDir, 'src', 'beta', 'Widget.ts'), `export class Widget {}\n`);
+
+      const report = await new ReflectionDoctor(pkgDir).diagnose();
+      expect(report.sharedNames).toEqual([
+        { qualifiedName: '@test/doctor-shared-name/Widget', filePaths: ['src/alpha/Widget.ts', 'src/beta/Widget.ts'] },
+      ]);
+      expect(report.healthy).toBe(false);
+      expect(report.text).toContain(
+        '  @test/doctor-shared-name/Widget\n    declared in src/alpha/Widget.ts\n    declared in src/beta/Widget.ts'
+      );
+    });
+  });
 });

package/test/ReproducibleGeneratedIndex.test.ts

@@ -0,0 +1,114 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ExamplePackageFixture } from './ExamplePackageFixture';
+
+/**
+ * The same sources build to the same bytes: the generated index, the compiled dist and the
+ * packed tarball do not depend on where the package is checked out, nor on the order the
+ * filesystem hands the source files back (which varies by filesystem and from run to run).
+ *
+ * The enumeration is stubbed at the glob the build reads its sources through: the real glob's
+ * result in a fixed base order (code-unit sorted — the glob's own order varies from copy to copy,
+ * so a reversal of it would not be the same reversal twice), reordered by `mockEnumerationOrder`.
+ */
+let mockEnumerationOrder: (paths: string[]) => string[] = (paths) => paths;
+jest.mock('globby', () => {
+  const actual = jest.requireActual('globby');
+  const reordered = async (...args: any[]) => mockEnumerationOrder([...(await actual(...args))].sort());
+  return Object.assign(reordered, actual);
+});
+
+const BUILD_TIMEOUT_MS = 120 * 1000;
+
+describe('reproducible generated index', () => {
+  const fixture = new ExamplePackageFixture('reproducible', '@proteinjs/reflection-build-test-reproducible');
+
+  afterEach(() => {
+    mockEnumerationOrder = (paths) => paths;
+  });
+
+  afterAll(() => fixture.dispose());
+
+  test(
+    'two checkouts at different absolute paths ship byte-identical dist/generated/index.js and tarballs',
+    async () => {
+      const shipped = [];
+      for (const location of ['one/pkg', 'two/a/much/deeper/checkout/elsewhere']) {
+        const packageDir = fixture.materialize(location);
+        await fixture.generate(packageDir);
+        fixture.compile(packageDir);
+        const generatedJs = fs.readFileSync(path.join(packageDir, 'dist', 'generated', 'index.js'));
+        expect(generatedJs.toString()).not.toContain(packageDir);
+        shipped.push({ generatedJs: fixture.sha256(generatedJs), tarball: fixture.packSha256(packageDir) });
+      }
+
+      expect(shipped[1]).toEqual(shipped[0]);
+    },
+    BUILD_TIMEOUT_MS
+  );
+
+  test(
+    'the generated index does not depend on the order the source files are enumerated',
+    async () => {
+      const orders: { [name: string]: (paths: string[]) => string[] } = {
+        asEnumerated: (paths) => paths,
+        reversed: (paths) => [...paths].reverse(),
+        rotated: (paths) => [...paths.slice(3), ...paths.slice(0, 3)],
+      };
+      const generated: { [name: string]: string } = {};
+      for (const name of Object.keys(orders)) {
+        mockEnumerationOrder = orders[name];
+        generated[name] = await fixture.generate(fixture.materialize(`order-${name}/pkg`));
+      }
+
+      expect(generated.reversed).toBe(generated.asEnumerated);
+      expect(generated.rotated).toBe(generated.asEnumerated);
+    },
+    BUILD_TIMEOUT_MS
+  );
+
+  test(
+    'node filePaths are package-relative, with / separators and no leading ./',
+    async () => {
+      const graph = fixture.graphOf(await fixture.generate(fixture.materialize('relative/pkg')));
+      const gamma = graph.nodes.find((node) => node.v === fixture.qualified('GammaPlugin'));
+      expect(gamma?.value?.filePath).toBe('src/beta/deep/Gamma.ts');
+
+      const filePaths = graph.nodes.map((node) => node.value?.filePath).filter((filePath) => !!filePath);
+      expect(filePaths.length).toBeGreaterThan(0);
+      expect(filePaths.filter((filePath) => !/^src\/[A-Za-z]+(\/[A-Za-z]+)*\.ts$/.test(filePath))).toEqual([]);
+    },
+    BUILD_TIMEOUT_MS
+  );
+
+  test(
+    'nodes are emitted by file then qualified name, edges by child then parent, source links in node order',
+    async () => {
+      const generated = await fixture.generate(fixture.materialize('canonical/pkg'));
+      const graph = fixture.graphOf(generated);
+      const byCodeUnit = (keys: string[][]) =>
+        [...keys].sort((a, b) => {
+          const left = a.join('\0');
+          const right = b.join('\0');
+          return left < right ? -1 : left > right ? 1 : 0;
+        });
+
+      const nodeKeys = graph.nodes.map((node) => [node.value?.filePath || '', node.v]);
+      expect(nodeKeys).toEqual(byCodeUnit(nodeKeys));
+      expect(nodeKeys.slice(0, 2)).toEqual([
+        ['', '@proteinjs/reflection/Loadable'],
+        ['src/alpha/Alpha.ts', fixture.qualified('AardvarkPlugin')],
+      ]);
+
+      const edgeKeys = graph.edges.map((edge) => [edge.v, edge.w]);
+      expect(edgeKeys).toEqual(byCodeUnit(edgeKeys));
+
+      const linkedNames = (generated.match(/^\t'[^']+'/gm) || []).map((line) => line.slice(2, -1));
+      const linkableNodeNames = graph.nodes
+        .filter((node) => node.value && (node.value.sourceType === 0 || node.value.sourceType === 2))
+        .map((node) => node.v);
+      expect(linkedNames).toEqual(linkableNodeNames);
+    },
+    BUILD_TIMEOUT_MS
+  );
+});

package/test/SharedQualifiedNames.test.ts

@@ -0,0 +1,89 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { ExamplePackageFixture } from './ExamplePackageFixture';
+
+/**
+ * One qualified name, one declaring file, for every name that reaches the generated index. The
+ * index holds one declaration per qualified name, so a name exported by two files would keep only
+ * the file parsed last and drop the other without a trace; the build refuses it instead. The rule
+ * applies after the prune: a name whose declarations are all pruned (types, consts, interfaces that
+ * are not Loadable) never reaches the index and is ordinary TypeScript.
+ *
+ * The enumeration is stubbed at the glob, as in the reproducible suite: the real glob's result in a
+ * fixed base order (code-unit sorted), reordered by `mockEnumerationOrder`.
+ */
+let mockEnumerationOrder: (paths: string[]) => string[] = (paths) => paths;
+jest.mock('globby', () => {
+  const actual = jest.requireActual('globby');
+  const reordered = async (...args: any[]) => mockEnumerationOrder([...(await actual(...args))].sort());
+  return Object.assign(reordered, actual);
+});
+
+const BUILD_TIMEOUT_MS = 120 * 1000;
+
+/** What one build did: the refusal's message, or the file whose declaration `name` holds in the index it wrote. */
+const outcomeOf = (fixture: ExamplePackageFixture, packageDir: string, name: string) =>
+  fixture.generate(packageDir).then(
+    (generated) => ({
+      built:
+        fixture.graphOf(generated).nodes.find((node) => node.v === fixture.qualified(name))?.value?.filePath || null,
+    }),
+    (error: Error) => ({ refused: error.message })
+  );
+
+describe('a name exported by two files', () => {
+  const sharedName = new ExamplePackageFixture('shared-name', '@proteinjs/reflection-build-test-shared-name');
+  const prunedPair = new ExamplePackageFixture(
+    'shared-name-pruned',
+    '@proteinjs/reflection-build-test-shared-name-pruned'
+  );
+  // Widget is declared by two files. Gear (src/gamma/Gear.ts) is declared twice by ONE file, an
+  // interface and a const, and reaches the index too: it is not a shared name, so it is not named.
+  const refusal = [
+    'reflection-build refused @proteinjs/reflection-build-test-shared-name: a name that reaches the generated index is declared in more than one file.',
+    'The index holds one declaration per qualified name, so the file parsed last would replace the others without a trace.',
+    'Give each declaration its own name (no index was written):',
+    '  @proteinjs/reflection-build-test-shared-name/Widget: src/alpha/Widget.ts, src/beta/Widget.ts',
+  ].join('\n');
+
+  afterEach(() => {
+    mockEnumerationOrder = (paths) => paths;
+  });
+
+  afterAll(() => {
+    sharedName.dispose();
+    prunedPair.dispose();
+  });
+
+  test(
+    'reaching the index (an interface that extends Loadable, a class): the build refuses, naming the package, the name and both files, and writes no index',
+    async () => {
+      const packageDir = sharedName.materialize('refused/pkg');
+      expect(await outcomeOf(sharedName, packageDir, 'Widget')).toEqual({ refused: refusal });
+      expect(fs.existsSync(path.join(packageDir, 'generated', 'index.ts'))).toBe(false);
+    },
+    BUILD_TIMEOUT_MS
+  );
+
+  test(
+    'the refusal names the files in package-relative path order, whatever order they are enumerated in',
+    async () => {
+      mockEnumerationOrder = (paths) => [...paths].reverse();
+      expect(await outcomeOf(sharedName, sharedName.materialize('reversed/pkg'), 'Widget')).toEqual({
+        refused: refusal,
+      });
+    },
+    BUILD_TIMEOUT_MS
+  );
+
+  test(
+    'pruned before the index (a type and an interface; two consts): the build writes the index, without the names',
+    async () => {
+      const packageDir = prunedPair.materialize('built/pkg');
+      expect(await outcomeOf(prunedPair, packageDir, 'Shape')).toEqual({ built: null });
+      expect(await outcomeOf(prunedPair, packageDir, 'LIMITS')).toEqual({ built: null });
+      expect(await outcomeOf(prunedPair, packageDir, 'SquareTile')).toEqual({ built: 'src/alpha/Tile.ts' });
+    },
+    BUILD_TIMEOUT_MS
+  );
+});

package/test/examples/reproducible/index.ts

@@ -0,0 +1,4 @@
+export * from './src/alpha/Alpha';
+export * from './src/beta/Beta';
+export * from './src/beta/deep/Gamma';
+export * from './src/zeta/Zeta';

package/test/examples/reproducible/src/alpha/Alpha.ts

@@ -0,0 +1,13 @@
+import { Loadable } from '@proteinjs/reflection';
+
+export interface Plugin extends Loadable {
+  id: string;
+}
+
+export class AlphaPlugin implements Plugin {
+  id = 'alpha';
+}
+
+export class AardvarkPlugin implements Plugin {
+  id = 'aardvark';
+}

package/test/examples/reproducible/src/alpha/Defaults.ts

@@ -0,0 +1,4 @@
+import { Plugin } from './Alpha';
+
+// The same file name as src/zeta/Defaults.ts, a different exported name: one declaration per qualified name.
+export const defaults: Plugin = { id: 'alpha-defaults' };

package/test/examples/reproducible/src/beta/Beta.ts

@@ -0,0 +1,7 @@
+import { Plugin } from '../alpha/Alpha';
+
+export class BetaPlugin implements Plugin {
+  id = 'beta';
+}
+
+export const betaSetting: Plugin = { id: 'beta-setting' };

package/test/examples/reproducible/src/beta/deep/Gamma.ts

@@ -0,0 +1,5 @@
+import { Plugin } from '../../alpha/Alpha';
+
+export class GammaPlugin implements Plugin {
+  id = 'gamma';
+}