carveout 0.1.1 → 0.2.0

package/dist/src/slice/reach.d.ts

@@ -0,0 +1,204 @@
+/**
+ * The bounded walk that proposes a slice.
+ *
+ * Starting from the entry points, the walk follows what a file's own code
+ * imports, breadth first, until the budget is spent: `maxDepth` imports
+ * from the nearest entry point, `maxFiles` files in all. Everything reached
+ * inside the budget is _included_; every link that leaves the included set
+ * is a _cut_, outbound where the slice needs something outside and inbound
+ * where outside code needs the slice.
+ *
+ * It follows names, not whole files. An import of `a` from a barrel
+ * includes the barrel and, through its re-exports, only the module that
+ * declares `a`, at the barrel's depth: a re-export is not an import of the
+ * barrel's own code. An import of types only (`import type`, or names the
+ * target declares as interfaces or type aliases) is erased at runtime, so
+ * its module is cut and stubbed, never copied. A module named to a test
+ * runner (`vi.mock`) is never followed either; a file read by path is.
+ *
+ * Two options move the cut from the hop count to the package: with
+ * `wholePackage`, every file of the entry points' package the walk reaches
+ * comes along at any depth, so a sibling module is copied, never stubbed;
+ * and a test brought along by `tests` brings its own helpers (the fakes and
+ * builders it imports from its package, or from a test folder anywhere),
+ * since a stub in a fake's place fails the test before any change is made
+ * (E6c: 44% of the tests failing on a fresh cut reached such a stub). A
+ * file the owner marks `private` is never entered, wherever it is reached:
+ * it is cut and stubbed like a module past the budget.
+ *
+ * Pure and deterministic: states are visited in path order within a level,
+ * so the same graph, entry points and budget give the same slice however
+ * the graph ordered its arrays. The budget bounds the proposal; it does not
+ * prove the slice closed. Imports the compiler could not resolve and
+ * dynamic imports are reported as dependencies for the caller to turn into
+ * blockers, never dropped.
+ */
+import type { SliceBudget } from "./analysis.js";
+import type { SliceGraph, SliceRelation } from "./graph.js";
+/** One link between two repository files. */
+export interface CutEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly relation: SliceRelation;
+    readonly specifier: string | null;
+    readonly location: string | null;
+    /** Erased at runtime: the stub alone serves it. */
+    readonly typeOnly: boolean;
+}
+/** An import from an included file that resolves to no repository file. */
+export interface SliceDependency {
+    readonly file: string;
+    /** The import text; for a path read, the path from the repository's
+     * root; null for a dynamic import of a computed name. */
+    readonly specifier: string | null;
+    /** `path`: a literal path read at runtime that names no file a slice
+     * can copy (a folder, a file of another kind). */
+    readonly status: "external" | "unresolved" | "dynamic" | "path";
+    readonly location: string | null;
+}
+export interface ReachResult {
+    /** Entry points resolved to files, sorted. */
+    readonly entries: readonly string[];
+    /** Entry points naming nothing in the graph, in the order given. */
+    readonly unknownEntryPoints: readonly string[];
+    /** Files inside the budget, sorted by path. */
+    readonly included: readonly string[];
+    /** Imports from the nearest entry point, per included file. */
+    readonly depthOf: Readonly<Record<string, number>>;
+    /**
+     * Files the walk reached within the depth that did not fit the file
+     * budget, sorted. They are cut like any module past the budget.
+     */
+    readonly dropped: readonly string[];
+    readonly cuts: {
+        readonly outbound: readonly CutEdge[];
+        /** Imports of the slice from outside it; never a `references` or
+         * `reads` link. */
+        readonly inbound: readonly CutEdge[];
+    };
+    /**
+     * Links between included files that carry the specifier the source
+     * wrote, sorted. A generated project resolves its imports with these and
+     * the outbound cuts, so a path alias or a moved file can be rewritten
+     * without the source's compiler configuration.
+     */
+    readonly internal: readonly CutEdge[];
+    readonly dependencies: readonly SliceDependency[];
+    /** Of the included files, the tests brought along, sorted. */
+    readonly tests: readonly string[];
+    /**
+     * Of the included files, the helpers the tests brought along: what a
+     * test imports at runtime from its own package, or from a test folder,
+     * that the slice did not already hold. Sorted.
+     */
+    readonly helpers: readonly string[];
+    /** Files the walk reached and kept out as private, sorted; each is a cut. */
+    readonly privateFiles: readonly string[];
+    /** Of the included files, the pure code copied rather than mocked, sorted. */
+    readonly pure: readonly string[];
+    /**
+     * Tests of the slice left behind, sorted: they run on neither `node:test`
+     * nor Vitest, or make an import no slice can carry (a computed dynamic
+     * import, one that resolves to nothing, a path read of no file).
+     */
+    readonly untestable: readonly string[];
+    /**
+     * Every test that runs the slice's code, directly or through a chain of
+     * barrels, that the folder does not hold, with the reason; sorted. A
+     * change these tests would catch passes in the folder unseen.
+     */
+    readonly testsLeft: readonly SliceTestLeft[];
+    /** Of the tests, those on Vitest's globals, which import no runner. */
+    readonly globalsTests: readonly string[];
+    /** Barrels outside the slice that forward names from it, sorted. */
+    readonly barrels: readonly string[];
+    /** Why each included file is in the slice. */
+    readonly originOf: Readonly<Record<string, SliceOrigin>>;
+}
+/**
+ * Why a file is in the slice: an entry point, reached within the depth,
+ * brought by `wholePackage`, a test, a barrel a test imports through, a
+ * test's helper, code of the package the tests run (`wholePackage` after
+ * the tests), or pure code copied rather than mocked.
+ */
+export type SliceOrigin = "entry" | "walk" | "package" | "test" | "barrel" | "helper" | "test-code" | "pure";
+/**
+ * A test that runs the slice's code and is not in the folder: it was not
+ * asked for (`tests` off), it tests another package, it runs on no runner
+ * a slice runs (Jest, say), it reads what no slice carries, or the budget
+ * ran out.
+ */
+export interface SliceTestLeft {
+    readonly file: string;
+    readonly reason: "not-asked" | "other-package" | "runner" | "unreadable" | "budget";
+    /**
+     * The slice's files it imports itself, which it tests: named so a
+     * contributor knows what a change only it would catch is in. Empty when
+     * it reaches the slice only through a barrel outside it.
+     */
+    readonly imports?: readonly string[];
+}
+export interface ReachOptions {
+    /**
+     * Files walked from as the entry points are, which are no entry point:
+     * the setup files a package's Vitest tests run before them. They come
+     * along with what they import, as the tests' helpers; the entry points,
+     * their package and their demands are the caller's alone.
+     */
+    readonly roots?: readonly string[];
+    /**
+     * Also include each test file outside the slice that imports it, directly
+     * or through a barrel that re-exports from it, and runs on `node:test` or
+     * Vitest. Such a barrel comes along too, its other re-exports cut. Tests
+     * and barrels count against the file budget.
+     */
+    readonly tests?: boolean;
+    /**
+     * The package folder a file belongs to (`""` for the root), for
+     * `wholePackage` and for a test's helpers. Every file is in one package
+     * without it.
+     */
+    readonly packageOf?: (file: string) => string;
+    /**
+     * Follow the entry points' package past the depth: every file of it the
+     * included files import at runtime (or read by path) comes along, tests
+     * apart, while the file budget lasts. Imports into other packages still
+     * stop at the depth.
+     */
+    readonly wholePackage?: boolean;
+    /** Files never entered: cut and stubbed wherever the walk reaches them. */
+    readonly isPrivate?: (file: string) => boolean;
+    /**
+     * The runner of a test file, from its path and the bare specifiers it
+     * imports; `testRunnerOf` without it, which knows only a runner imported.
+     */
+    readonly runnerOf?: (file: string, specifiers: readonly string[]) => TestRunner | null;
+    /**
+     * Copy pure code rather than mock it: a module the slice imports at
+     * runtime from outside comes along, past the depth, when every module
+     * its runtime imports reach outside the slice is pure. A mock of a
+     * validator, an error class or a formatter answers with more mocks, and
+     * the slice's tests fail on it before any change (a red baseline); the
+     * real code runs the same in the folder as in the repository.
+     */
+    readonly pure?: {
+        /** A package a pure module may import: no service, no I/O. */
+        readonly package: (specifier: string) => boolean;
+        /** Whether the file's own code reads the environment, the disk or the network. */
+        readonly sideEffects: (file: string) => boolean;
+    };
+}
+/** `x.test.ts`, `x.spec.tsx`, or anything under `__tests__/`. */
+export declare const TEST_PATH_PATTERN: RegExp;
+export declare function isTestPath(path: string): boolean;
+/** A file in a folder of test support: fakes, fixtures, builders. */
+export declare const TEST_SUPPORT_PATH_PATTERN: RegExp;
+export declare function isTestSupportPath(path: string): boolean;
+/**
+ * A runner a slice runs tests on: `node:test`, Vitest imported, or Vitest
+ * with its globals (`describe`, `it`, `expect` unimported).
+ */
+export type TestRunner = "node" | "vitest" | "vitest-globals";
+/** The test runner a test file imports, when carveout can run it. */
+export declare function testRunnerOf(specifiers: readonly string[]): "node" | "vitest" | null;
+export declare function reach(graph: SliceGraph, entryPoints: readonly string[], budget: SliceBudget, options?: ReachOptions): ReachResult;

package/dist/src/slice/reach.js

@@ -206,6 +206,7 @@ export function reach(graph, entryPoints, budget, options = {}) {
         for (const file of resolved)
             entries.add(file);
     }
+    const roots = new Set((options.roots ?? []).flatMap((root) => resolveEntry(root, byId, files)).filter((file) => !entries.has(file)));
     const maxFiles = Math.max(0, Math.floor(budget.maxFiles));
     const maxDepth = Math.max(0, Math.floor(budget.maxDepth));
     const packageOf = options.packageOf ?? (() => "");
@@ -226,7 +227,7 @@ export function reach(graph, entryPoints, budget, options = {}) {
     const dropped = new Set();
     const seen = new Set();
     const byState = (a, b) => compare(a[0], b[0]) || compare(a[1], b[1]);
-    let level = [...entries].map((file) => [file, EVERYTHING]);
+    let level = [...entries, ...roots].map((file) => [file, EVERYTHING]);
     let depth = 0;
     while (level.length > 0 && depth <= maxDepth && dropped.size === 0) {
         const work = level.sort(byState);
@@ -242,7 +243,7 @@ export function reach(graph, entryPoints, budget, options = {}) {
                 return false;
             }
             depthOf.set(file, depth);
-            originOf.set(file, entries.has(file) ? "entry" : "walk");
+            originOf.set(file, entries.has(file) ? "entry" : roots.has(file) ? "helper" : "walk");
             return true;
         };
         // A re-export forwards a name at the barrel's depth; an import of the
@@ -366,7 +367,7 @@ export function reach(graph, entryPoints, budget, options = {}) {
             demand.set(file, set);
             return grew;
         };
-        for (const file of entries)
+        for (const file of [...entries, ...roots])
             if (depthOf.has(file))
                 add(file, EVERYTHING);
         for (let changed = true; changed;) {
@@ -568,10 +569,11 @@ export function reach(graph, entryPoints, budget, options = {}) {
             if (link.relation !== "imports" || link.typeOnly)
                 continue;
             const through = barrels.get(edge.to);
-            const entry = exercising.get(file) ?? { through: new Set(), own: false };
+            const entry = exercising.get(file) ?? { through: new Set(), own: false, imports: new Set() };
             if (code.has(edge.to)) {
                 if (packageOf(edge.to) === mine)
                     entry.own = true;
+                entry.imports.add(edge.to);
                 exercising.set(file, entry);
             }
             else if (through !== undefined &&
@@ -583,6 +585,8 @@ export function reach(graph, entryPoints, budget, options = {}) {
                     entry.own = true;
                     entry.through.add(edge.to);
                 }
+                // Named only if the slice holds the barrel itself.
+                entry.imports.add(edge.to);
                 exercising.set(file, entry);
             }
         }
@@ -720,11 +724,13 @@ export function reach(graph, entryPoints, budget, options = {}) {
     }
     /** The tests of the slice's code the folder does not carry, and why. */
     const testsLeft = [];
-    for (const [file, { own }] of [...exercising].sort(([a], [b]) => compare(a, b))) {
+    for (const [file, { own, imports }] of [...exercising].sort(([a], [b]) => compare(a, b))) {
         if (depthOf.has(file))
             continue;
+        const named = [...imports].filter((path) => depthOf.has(path)).sort(compare);
         testsLeft.push({
             file,
+            ...(named.length === 0 ? {} : { imports: named }),
             reason: !own
                 ? "other-package"
                 : options.tests !== true

package/dist/src/slice/report.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What a slice shows and what it tests, in words a maintainer and a
+ * contributor read before trusting a pass in the folder.
+ *
+ * Exposure counts the files and lines a cut copies, by why each is there,
+ * so the cost of `--whole-package`, `--with-tests` and `--copy-pure` in code
+ * shown is a number before anything is handed out. The tests account names
+ * every test that runs the slice's code and stays in the repository: a
+ * change one of them would catch passes in the folder unseen.
+ */
+import { type ReachResult, type SliceOrigin, type SliceTestLeft } from "./reach.js";
+export interface SliceExposure {
+    readonly files: number;
+    readonly lines: number;
+    /** By origin, in `ORIGIN_ORDER`, origins with no file left out. */
+    readonly byOrigin: readonly {
+        readonly origin: SliceOrigin;
+        readonly files: number;
+        readonly lines: number;
+    }[];
+    /**
+     * The source the folder copies from outside the entry points, tests left
+     * out, by folder, most lines first: what the contributor reads beyond
+     * the part handed to them, and what `--private` would keep out. Absent
+     * from a record written before it was counted.
+     */
+    readonly outside?: readonly {
+        readonly folder: string;
+        readonly files: number;
+        readonly lines: number;
+    }[];
+}
+/** Lines and files the walk's included files hold, by origin. */
+export declare function exposureOf(walk: Pick<ReachResult, "included" | "originOf">, read: (path: string) => string | null): SliceExposure;
+/** One line: `24 files, 3,410 lines: 1 entry point (180), ...`. */
+export declare function renderExposure(exposure: SliceExposure): string;
+/**
+ * The source copied from outside the entry points, by folder, as lines for
+ * `plan` and `cut`; nothing when there is none.
+ */
+export declare function renderOutside(exposure: SliceExposure): string[];
+export declare const TEST_LEFT_REASON: Readonly<Record<SliceTestLeft["reason"], string>>;
+/** What a pass in the folder says, given the tests it holds and leaves. */
+export declare function testsVerdict(walk: Pick<ReachResult, "tests" | "testsLeft">): string;
+/**
+ * The tests section of BOUNDARY.md. `name` writes a path outside the slice
+ * as the folder may show it (a public cut names only its package).
+ */
+export declare function renderTestsMarkdown(walk: Pick<ReachResult, "tests" | "testsLeft">, name: (path: string) => string): string[];

package/dist/src/slice/report.js

@@ -120,8 +120,11 @@ export function renderTestsMarkdown(walk, name) {
     if (walk.testsLeft.length > 0) {
         lines.push("Left in the repository, which runs them on the change after the merge:", "");
         const grouped = new Map();
-        for (const { file, reason } of walk.testsLeft) {
-            const key = `\`${name(file)}\`: ${TEST_LEFT_REASON[reason]}`;
+        for (const { file, reason, imports } of walk.testsLeft) {
+            // What it tests, by the slice's files it imports: a change to one of
+            // those is what only it would catch.
+            const tests = imports === undefined || imports.length === 0 ? "" : `; it imports ${imports.map((path) => `\`${path}\``).join(", ")}`;
+            const key = `\`${name(file)}\`: ${TEST_LEFT_REASON[reason]}${tests}`;
             grouped.set(key, (grouped.get(key) ?? 0) + 1);
         }
         for (const [key, count] of grouped)

package/dist/src/specifiers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The module specifiers a source writes, read from its syntax tree rather
+ * than by pattern: imports and re-exports, `require` and `import()`,
+ * `import("x").T` in a type, `import x = require("y")`, and the calls that
+ * name a module to a test runner or a resolver (`vi.mock`,
+ * `jest.requireActual`, `require.resolve`, `import.meta.resolve`).
+ *
+ * A regex over the text (the former `IMPORT_LITERAL`) misread an import
+ * quoted in a comment, a string that said `from`, or a clause spanning
+ * lines, and each misreading was a false `import_unrewritable` blocker or
+ * a specifier left unrewritten (E6c: 23 such blockers, 3 green templates
+ * marked not ready). The tree has none of those: a specifier is a string
+ * literal in one of the positions below, and nothing else is one.
+ */
+import ts from "typescript";
+/** Where a specifier sits in the source. */
+export interface SpecifierLiteral {
+    /** The text between the quotes. */
+    readonly specifier: string;
+    /** Offsets of that text in the source. */
+    readonly start: number;
+    readonly end: number;
+    /**
+     * `import`: an import, re-export or `import()`; `require`: a `require`
+     * call; `type`: `import("x")` in a type; `reference`: a call that names a
+     * module without loading it (`vi.mock`, `require.resolve`).
+     */
+    readonly kind: "import" | "require" | "type" | "reference";
+    /** Whether only types are imported (`import type`, `export type`). */
+    readonly typeOnly: boolean;
+}
+/** Calls that name a module to a test runner or a resolver. */
+export declare const MODULE_REFERENCE_CALLS: readonly string[];
+/** The parse of `text` as the file at `path` would be parsed. */
+export declare function parseSource(path: string, text: string): ts.SourceFile;
+/**
+ * Every module specifier in `text`, in source order. The same literal is
+ * never reported twice.
+ */
+export declare function moduleSpecifiers(path: string, text: string, source?: ts.SourceFile): SpecifierLiteral[];
+/** The distinct specifiers of `text`, in source order. */
+export declare function specifiersIn(path: string, text: string): string[];
+/**
+ * `text` with each specifier replaced by what `replace` returns for it, or
+ * left as written when it returns null. Positions come from one parse, so
+ * a replacement never shifts another's.
+ */
+export declare function rewriteSpecifiers(path: string, text: string, replace: (literal: SpecifierLiteral) => string | null): string;

package/dist/src/status.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `carveout status`: whether a cut folder still matches its repository.
+ *
+ * The cut is made again in memory, with the request `carveout.json`
+ * records, against the repository as it stands (HEAD and the working
+ * tree), and every file it would write is compared with what the folder's
+ * record says was written. The folder is current when no file would differ;
+ * otherwise each difference is named with its cause: a slice file that
+ * changed, a cut module whose declarations changed (by symbol), a file the
+ * walk now reaches or no longer reaches, or generated configuration. A
+ * change to a cut module's bodies alone leaves its stub, and so the
+ * folder, as it was. The lockfile the cut resolved from the registry is not
+ * compared: it is the registry's answer, not the repository's.
+ *
+ * Nothing is written; the package types a cut reads come from the cache
+ * when the set is the same.
+ */
+export type StaleCause = "source_changed" | "source_added" | "source_removed" | "stub_changed" | "stub_added" | "stub_removed" | "surface_changed" | "generated_changed" | "cut_failed";
+export interface StaleItem {
+    readonly cause: StaleCause;
+    readonly path: string | null;
+    readonly detail: string;
+}
+export interface Status {
+    readonly current: boolean;
+    readonly stale: readonly StaleItem[];
+    /** Resolution inputs that changed, whatever they did to the cut. */
+    readonly inputsChanged: readonly string[];
+    /** Files outside the slice that import it now and did not, or the reverse. */
+    readonly importers: {
+        readonly added: readonly string[];
+        readonly removed: readonly string[];
+    };
+    readonly commit: string | null;
+}
+/** Each exported name a declaration file declares, with its text. */
+export declare function declaredSymbols(text: string): Map<string, string>;
+/** Symbols added, removed and changed between two versions of a stub. */
+export declare function symbolDiff(before: string, after: string): string;
+export declare function statusProject(dir: string, options?: {
+    readonly repo?: string;
+    /** The cut's receipt file; else the one `CARVEOUT_HOME` keeps for its id. */
+    readonly receipt?: string;
+    /** No receipt: the folder's own record is all there is. */
+    readonly noReceipt?: boolean;
+}): Promise<Status>;

package/dist/src/status.js

@@ -19,7 +19,8 @@ import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import ts from "typescript";
-import { computeCut, readRecord } from "./carve.js";
+import { computeCut } from "./carve.js";
+import { trustedCut } from "./receipt.js";
 import { trustedRepo } from "./policy.js";
 const compare = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
 const sha256 = (data) => createHash("sha256").update(data).digest("hex");
@@ -78,7 +79,7 @@ export function symbolDiff(before, after) {
 const stubOf = (path) => path.replace(/\.d\.([cm]?)ts$/, ".$1js");
 export async function statusProject(dir, options = {}) {
     const root = resolve(dir);
-    const record = readRecord(root);
+    const record = trustedCut(root, options.receipt, options.noReceipt === true ? { noReceipt: true } : {}).record;
     const repo = trustedRepo(record, options.repo);
     const request = record.request;
     let fresh;

package/dist/src/test-integrity.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Whether an edit to a test weakens it: read from the syntax of the test
+ * as it was and as it is, never run.
+ *
+ * A test may grow. Its assertions, the statements they rest on (the data
+ * passed in, the value compared with, the setup, a fake's method), and
+ * the tests it skips or focuses are what it held the code to, and an edit
+ * that removes, rewrites, guards or outruns one of them is held for the
+ * maintainer: an expected value changed may be the change that was asked
+ * for, or a test bent to pass. Statements are compared as TypeScript prints
+ * them, so formatting is no change and a string's own characters are.
+ */
+import ts from "typescript";
+/** Calls whose function arguments hold a test or its hooks. */
+export declare const TEST_STRUCTURE: ReadonlySet<string>;
+/** The script kind TypeScript should parse a path as. */
+export declare const scriptKindOf: (path: string) => ts.ScriptKind.TS | ts.ScriptKind.TSX;
+/**
+ * A node as TypeScript prints it, its strings in one quoting: the same
+ * code, however it is laid out, quoted or semicoloned, prints the same,
+ * and a string's own characters are kept. A trailing comma is layout.
+ */
+export declare function canonical(node: ts.Node, source: ts.SourceFile): string;
+/**
+ * The names a test file's assertions go by: `assert` and `expect`, every
+ * name imported from an assertion module (`strictEqual` from `node:assert`),
+ * and from a runner's module only its asserting names (`expect` from
+ * `vitest`, never `describe`), whether imported or required.
+ */
+export declare function assertionRoots(source: ts.SourceFile): Set<string>;
+/** The identifier a call or member chain starts at, or null. */
+export declare function chainRoot(node: ts.Expression): string | null;
+/**
+ * Whether an expression is a constant the code can read without running
+ * it: `true`, `false`, `0`, `1`, `""`, `null`, `undefined`, `!x` of one, or
+ * one in parentheses. Null for anything else.
+ */
+export declare function constantOf(node: ts.Expression): boolean | null;
+/** What `before` holds that `after` does not, counted as multisets. */
+export declare function removedFrom(before: readonly string[], after: readonly string[]): string[];
+/** Whether a module specifier names the code's own module: a path, or a path alias. */
+export declare function ownSpecifier(specifier: string): boolean;
+/**
+ * Why a change to a test weakens it, or null: an assertion removed,
+ * rewritten or put where it may not run; a test skipped or focused; a
+ * statement the assertions rest on rewritten or removed; a mock, spy or
+ * member write of the code's own module added, which can stand in for the
+ * code under test; or a statement added that changes what a kept assertion
+ * reads (one that declares a name the test already reads, a hook in a
+ * scope that holds tests, top-level code, or a statement before a kept
+ * assertion in its body). A new test, a new import, a new helper with a
+ * name of its own and statements after the last assertion pass.
+ */
+export declare function weakenedTest(path: string, before: string, after: string, noun?: string): string | null;