@proteinjs/reflection-build 1.4.12 → 2.0.0

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

package/test/ValidateDontMutate.test.ts

@@ -0,0 +1,126 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { build } from '../src/build';
+
+/**
+ * Validate-don't-mutate (task #104 §3.3): the build computes the package-config contract and
+ * VALIDATES it instead of silently rewriting files.
+ *
+ * The founder's UX bar:
+ * - ABSENCE is not a mismatch — a fresh package missing main/types gets them SET (today's
+ *   behavior kept; the copy-a-package workflow survives).
+ * - The build errors ONLY on conflicting existing values, and the error is friendly: plain
+ *   words, why it matters, the exact lines to paste, `--fix` offered first.
+ * - `reflection-build --fix` writes the contract; a second run is a no-op.
+ *
+ * Red-before-green: against pre-change code the conflict tests fail because the mutating
+ * build succeeds and silently rewrites package.json.
+ */
+describe("validate-don't-mutate", () => {
+  let pkgDir: string;
+  const savedEnv: { [key: string]: string | undefined } = {};
+
+  const writeFixture = (packageJson: any) => {
+    pkgDir = fs.mkdtempSync(path.join(os.tmpdir(), 'refl-validate-'));
+    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`);
+    process.env.INIT_CWD = pkgDir;
+  };
+
+  const readPackageJson = () => JSON.parse(fs.readFileSync(path.join(pkgDir, 'package.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('fails the build on a conflicting main and leaves package.json untouched', async () => {
+    writeFixture({ name: '@test/validate-fixture', version: '1.0.0', main: './dist/custom-entry.js' });
+    // The conflicting value points at a REAL file — a deliberate setting, not boilerplate.
+    fs.mkdirSync(path.join(pkgDir, 'dist'));
+    fs.writeFileSync(path.join(pkgDir, 'dist', 'custom-entry.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('the conflict error is friendly: offers --fix first, then the exact lines to paste', async () => {
+    writeFixture({ name: '@test/validate-fixture', version: '1.0.0', main: './dist/custom-entry.js' });
+    fs.mkdirSync(path.join(pkgDir, 'dist'));
+    fs.writeFileSync(path.join(pkgDir, 'dist', 'custom-entry.js'), 'module.exports = {};\n');
+
+    let message = '';
+    try {
+      await build();
+    } catch (error: any) {
+      message = error.message;
+    }
+    expect(message).toContain('reflection-build --fix');
+    expect(message).toContain('"main": "./dist/generated/index.js"');
+    expect(message).toContain('"types": "./dist/generated/index.d.ts"');
+    // --fix is the first remedy offered, before the paste-able lines.
+    expect(message.indexOf('--fix')).toBeGreaterThan(-1);
+    expect(message.indexOf('--fix')).toBeLessThan(message.indexOf('"main": "./dist/generated/index.js"'));
+    // Plain words about why it matters, not just a diff.
+    expect(message.toLowerCase()).toContain('consumer');
+  });
+
+  it('sets absent main/types silently — the fresh/copied-package workflow survives', async () => {
+    writeFixture({ name: '@test/validate-fixture', version: '1.0.0' });
+    await build();
+    const packageJson = readPackageJson();
+    expect(packageJson.main).toBe('./dist/generated/index.js');
+    expect(packageJson.types).toBe('./dist/generated/index.d.ts');
+  });
+
+  it('treats npm-init boilerplate (main pointing at a file that does not exist) as absence', async () => {
+    writeFixture({ name: '@test/validate-fixture', version: '1.0.0', main: 'index.js' });
+    await build();
+    expect(readPackageJson().main).toBe('./dist/generated/index.js');
+  });
+
+  it('accepts a package already on contract without touching it', async () => {
+    writeFixture({
+      name: '@test/validate-fixture',
+      version: '1.0.0',
+      main: './dist/generated/index.js',
+      types: './dist/generated/index.d.ts',
+    });
+    await build();
+    const first = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    await build();
+    expect(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8')).toBe(first);
+  });
+
+  it('--fix rewrites conflicting values to the contract; a second run is a no-op', async () => {
+    writeFixture({ name: '@test/validate-fixture', version: '1.0.0', main: './dist/custom-entry.js' });
+    fs.mkdirSync(path.join(pkgDir, 'dist'));
+    fs.writeFileSync(path.join(pkgDir, 'dist', 'custom-entry.js'), 'module.exports = {};\n');
+
+    await build({ fix: true });
+    const packageJson = readPackageJson();
+    expect(packageJson.main).toBe('./dist/generated/index.js');
+    expect(packageJson.types).toBe('./dist/generated/index.d.ts');
+
+    const afterFix = fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8');
+    await build();
+    expect(fs.readFileSync(path.join(pkgDir, 'package.json'), 'utf-8')).toBe(afterFix);
+  });
+});

package/test/examples/source-repository/a/dist/BuildContract.d.ts

@@ -0,0 +1,69 @@
+export interface BuildContractOptions {
+    /** Root of the package being built (contains package.json) */
+    packageDir: string;
+    /** First REFLECTION_SOURCE_DIRS entry; 'src' for prod builds */
+    primaryRoot: string;
+    /** REFLECTION_DIST_DIR or 'dist' */
+    distDirRel: string;
+    /** Absolute path to the generated index .ts this invocation emits */
+    generatedIndexPath: string;
+    /** Write conflicting values to the contract instead of failing the build */
+    fix: boolean;
+}
+/**
+ * The package-config contract of a reflection build (task #104 §3.3, validate-don't-mutate).
+ *
+ * A build's artifact is only usable if the package's config points at it, so reflection-build
+ * owns that config as a contract instead of silently rewriting files on every build:
+ *
+ * - ABSENT config is completed in place (a fresh or copied package gets main/types, subpath
+ *   mappings, stubs — the zero-ceremony workflow survives).
+ * - EXISTING config that conflicts with the contract fails the build with a friendly error
+ *   (plain words, why it matters, the exact lines to paste, `--fix` offered first) and leaves
+ *   every file untouched.
+ * - `reflection-build --fix` writes the contract over conflicting values; it is idempotent.
+ *
+ * Prod builds (primary root 'src') own main/types + the tsconfig include. Subpath builds
+ * (primary root e.g. 'test') own the complete subpath contract — root <root>.js/<root>.d.ts
+ * stubs, exports/typesVersions mappings, files[] entries, tsconfig excludes (the d51556f0
+ * class, generalized): consumers must resolve the subpath to built dist in every install
+ * shape and resolution mode, never to sources.
+ */
+export declare class BuildContract {
+    private readonly options;
+    constructor(options: BuildContractOptions);
+    apply(): Promise<void>;
+    private applyPackageJson;
+    /** Prod builds: main/types point at the built reflection artifact. */
+    private settleEntryPoints;
+    /** Subpath builds: exports map "." and "./<root>" to the built artifacts. */
+    private settleSubpathExports;
+    /** Subpath builds: typesVersions carries the subpath's types for node10 resolution. */
+    private settleTypesVersions;
+    /** Subpath builds: an existing files allowlist must keep shipping the root stubs. */
+    private settleFilesAllowlist;
+    /**
+     * Subpath builds: root stubs that win the node10/paths-mapped file lookup, so every install
+     * shape resolves the subpath to built dist — never to sources (the TS6059/ts-jest class).
+     */
+    private applyStubs;
+    /**
+     * tsconfig: include the generated index; on subpath builds, exclude the root stubs from
+     * compilation. List membership only — nothing here can conflict.
+     */
+    private applyTsconfig;
+    /**
+     * Settle one string field: absent → set; equal → ok; a dangling value (points at a file
+     * that does not exist — npm init's boilerplate `"main": "index.js"`, a stale copy) → set;
+     * a value that points at a real, different file is a deliberate setting → conflict.
+     */
+    private settleString;
+    private formatConflicts;
+    private isProd;
+    private prodIndexJs;
+    private prodIndexDts;
+    private subpathIndexJs;
+    private subpathIndexDts;
+    private stubJsName;
+    private stubDtsName;
+}