carveout 0.2.0 → 0.3.1

package/NOTICE.md

@@ -6,3 +6,47 @@ pseudonyms (`src/pseudonyms`: aliases, vocabulary, draft) are carved out of
 `packages/core/src/slice`, `packages/core/src/sandbox` and
 `apps/worker/src/tools/slice`. The import graph (`src/graph.ts`) replaces the
 graphify driver there with the TypeScript compiler alone.
+
+`src/pseudonyms/carry.ts` is the platform's `packages/core/src/sandbox/carry.ts`
+(commit f31d780), moved here verbatim but for a pluggable renaming
+(`aliases`). `src/pseudonyms/legacy/` holds that commit's `aliases.ts` and
+`vocabulary.ts` frozen, exported with a `V1` suffix (`legacy.ts`).
+
+## Where the forks differ from the platform
+
+carveout's behaviour is kept in each case; `carveout/extract` and
+`carveout/pseudonyms` export it.
+
+- `isDataPath`: also `.toml`, `.csv`, `.xml`, `.sql`, `.graphql`, `.gql`,
+  `.prisma`, and the images, fonts and media `isAssetPath` names.
+- `boundedHost`: never reads the checkout's own `node_modules`.
+- `sanitizeDeclaration` and `extractTypeScriptBoundary`: `widenLiterals`
+  (default true); with it, a constant read as a type (`typeof KIND`) keeps
+  its name-like string literals.
+- `filterDeclaration`: `export { a, b } from "./m"` keeps only the names
+  asked of it; a barrel lists the names passed through its `export *`.
+- `extractTypeScriptBoundary`: `CutEdge` carries `typeOnly`, not
+  `targetSymbol`, and an edge with no import asks for the whole module;
+  a copied asset is no module to stub; a workspace package's import asks
+  its source module; the result has `surface` (the surface check).
+- `compileFixture`: drops `rootDir`, `rootDirs` and `outDir`; messages name
+  files relative to the checkout (`withoutRoots`).
+- `packageUses`: reads `const { a } = await import("pkg")`.
+- `loadConfig`: an optional third argument shares workspaces and loaded
+  configurations across calls.
+- `package-registry.ts`: adds `lockIntegrities` and `publicByIntegrity`
+  (a pnpm entry with no URL, matched against the public registry).
+- `analyseSlice` (`src/cut.ts`): walks with carveout's own graph and
+  `reach`; blocks on a path read unless `pathReads: "omit"`; `CutError`
+  codes `no_files`, `too_large`, `unreadable` where the platform throws
+  `AnalysisError("tool_failed" | "too_large")`; adds `surface`,
+  `keepsImplicitAny`, `implicitAnyFiles`, `walk`; no graphify communities.
+- Alias rules: a path may hold any character but a NUL, a backslash, a
+  quote or a newline; a path rule matches after a `/` too; a rule's target
+  may occur where an earlier rule put it.
+- Vocabulary: a term's words do not join across `/`; `scanVocabulary`
+  drops a found one-word name `tooCommonAlone` and adds handle stems and
+  accent-free spellings.
+- Draft: made-up placeholders first, a tail word per extra word of a term
+  (`contoso-labs`), restyled to each spelling, and an earlier cut's
+  placeholders kept (`preferred`).

package/dist/src/api.d.ts

@@ -15,7 +15,16 @@
  * to throw.
  *
  * `walk` returns the walk `plan` and `cut` make, whole, for a platform
- * that generates its own stubs and project from it.
+ * that generates its own stubs and project from it. `analyse` goes on from
+ * the walk to what `cut` writes the folder from (manifest, contract, stubs,
+ * surface), and runs no process at all, Git included; `importGraph` builds
+ * the graph once for many analyses. `folderLayout` says where a cut folder
+ * keeps its harness, mocks, configuration and tests, and what a grader runs.
+ *
+ * The extractor and the fixture compile are `carveout/extract`
+ * (`extract.ts`); the alias table, the vocabulary scan, the draft, carry-back
+ * and the mock runtime's text, pure, are `carveout/pseudonyms`
+ * (`pseudonyms.ts`).
  *
  * Also exported: the policy's text checks (`integrityOf`,
  * `gainedIntegrity`, `weakenedTest`) and the slice and project modules
@@ -23,13 +32,16 @@
  */
 import type { ReachResult } from "./slice/reach.js";
 import { type CarveoutRecord, type Patch, type PlanSurface } from "./carve.js";
-import { type CutEdge, type SliceExposure, type SliceExternals, type SliceOrigin, type SliceTestLeft, type TestRunner } from "./core.js";
+import { CutError, type CutErrorCode, type SliceAnalysis } from "./cut.js";
+import type { PackageTypesFetcher } from "./extract/package-types.js";
+import { type CutEdge, type SliceExposure, type SliceExternals, type SliceOrigin, type SliceGraph, type SliceTestLeft, type TestRunner } from "./core.js";
 import type { Readiness } from "./readiness.js";
 import type { Receipt } from "./receipt.js";
 export * from "./core.js";
 export { gainedIntegrity, integrityOf, weakenedTest, type Refusal } from "./policy.js";
 export type { CarveoutRecord, Patch, PlanSurface, Readiness, Receipt };
-export type { ReachResult };
+export type { ReachResult, PackageTypesFetcher };
+export { CutError, type CutErrorCode };
 /** The walk's bounds, as `carveout plan` and `cut` take them. */
 export interface WalkOptions {
     /** The repository's checkout root. */
@@ -160,3 +172,123 @@ export interface PatchInput {
  * own record; runs nothing from the folder.
  */
 export declare function patch(input: PatchInput): Promise<Patch>;
+/**
+ * The import graph of a whole checkout, read once, for many `analyse`
+ * calls on it (`AnalyseOptions.graph`). It does not depend on the entries;
+ * it does on whether imports of the repository's own packages are followed
+ * into their source, which `copyPure` and the repository's
+ * `carveout.config.json` decide, as they do for the analyses: build it with
+ * the same `copyPure` they take. Runs no process: the files are every file
+ * under the root outside the folders a graph ignores, or `files`.
+ */
+export declare function importGraph(root: string, options?: {
+    readonly copyPure?: boolean;
+    readonly files?: readonly string[];
+}): SliceGraph;
+export interface AnalyseOptions extends WalkOptions {
+    /** The commit the root is a checkout of, stamped into the manifest and the contract; Git is not asked. */
+    readonly commitSha: string | null;
+    /** Whether an included file differs from that commit; by default none does. */
+    readonly isDirty?: (paths: readonly string[]) => boolean;
+    /**
+     * Fetches the types of the public packages the slice reads (`npmPackageTypes`
+     * from `carveout/extract`, or the caller's own). Absent: every package is
+     * untyped and nothing is fetched or run.
+     */
+    readonly packageTypes?: PackageTypesFetcher;
+    /** Widen literal values in the stubs to their types; default true (the CLI's default is off but for `--public`). */
+    readonly widenLiterals?: boolean;
+    /** `omit`: a file read by path blocks nothing (see `analyseSlice`); default `block`, as the CLI. */
+    readonly pathReads?: "block" | "omit";
+    /** The externals of the included files when the caller has them all; null to read them here. */
+    readonly externalsOf?: (included: readonly string[]) => SliceExternals | null;
+    /** The checkout's files; by default every file under the root outside the folders a graph ignores. */
+    readonly files?: readonly string[];
+    /**
+     * A graph from `importGraph`, reused across analyses. Without it the graph
+     * is read lazily, as `cut` reads it, from the entries outward; the walk is
+     * the same, but the manifest's `graphSha256` is of the graph used.
+     */
+    readonly graph?: SliceGraph;
+    readonly signal?: AbortSignal;
+    /** The analysis's progress lines. */
+    readonly log?: (line: string) => void;
+}
+/**
+ * What `cut` writes a folder from: the manifest, the boundary contract (and
+ * its canonical JSON), the stubs, the public surface's check, whether it is
+ * ready, how it stands with noImplicitAny, and the walk.
+ */
+export type Analysis = SliceAnalysis;
+/**
+ * The analysis `cut` makes before it writes anything, on the same code
+ * path and with the same request after `carveout.config.json`, for a
+ * platform that writes its own folder: on the same checkout, its manifest
+ * and contract are the cut's, but for the commit and dirty fields, which
+ * are the caller's here. It runs no process (no Git, no npm unless the
+ * `packageTypes` given does) and writes nothing. Throws a `CutError` when
+ * no slice can be made at all.
+ */
+export declare function analyse(options: AnalyseOptions): Promise<Analysis>;
+/** One command a grader runs on the staged folder; none goes through `npm run`. */
+export interface LayoutCommand {
+    readonly name: "install" | "build" | "public-tests";
+    readonly argv: readonly string[];
+}
+/** How one test file runs on its own, with a TAP report on stdout. */
+export interface LayoutTestRun {
+    /** The command, before the file. */
+    readonly argv: readonly string[];
+    /** Whether the file is given as its emitted JavaScript (after the build) rather than its source. */
+    readonly emitted: boolean;
+}
+/**
+ * Where a folder handed to a contributor keeps what is not theirs to
+ * change, and how it is graded: a carveout folder's (`folderLayout`), or a
+ * platform's own written in the same terms.
+ */
+export interface FolderLayout {
+    /** The harness: generated code a submission never changes. */
+    readonly harnessDir: string;
+    /** The mock packages. */
+    readonly mocksDir: string;
+    /** The recording mock runtime, which task code never imports. */
+    readonly mockRuntimePath: string;
+    /** The placeholder environment every run reads (`--env-file`). */
+    readonly envFile: string;
+    /** Top-level folders a submission never writes into. */
+    readonly harnessRoots: readonly string[];
+    /** Root files that configure the run, each with why a change to it is refused. */
+    readonly configFiles: Readonly<Record<string, string>>;
+    /** What a grader runs, in order, on the staged folder. */
+    readonly commands: readonly LayoutCommand[];
+    readonly tests: {
+        /** The public suite's folder; null when tests sit beside the code they test. */
+        readonly publicDir: string | null;
+        /** Where hidden tests are staged; null when each goes at its own repository path. */
+        readonly privateDir: string | null;
+        /** The test files the folder holds. */
+        readonly files: readonly string[];
+        /** One hidden test on its own, by the runner it imports; null for a runner the folder does not install. */
+        readonly run: {
+            readonly "node:test": LayoutTestRun;
+            readonly vitest: LayoutTestRun | null;
+        };
+    };
+}
+/**
+ * Where a carveout folder keeps its harness (`carveout/`), its mock
+ * packages (`carveout/packages`), its mock runtime, its configuration and
+ * its tests, and the commands that install, build and test it as `carveout
+ * check` does (`npm test` is `node carveout/test.js` after the build), for
+ * a grader that takes the layout as a parameter. Hidden tests go at their
+ * repository paths, as `carveout check --accept` puts them, and run one at
+ * a time with `tests.run` (`layoutTestArgv`). Read from the folder's record.
+ */
+export declare function folderLayout(record: CarveoutRecord): FolderLayout;
+/**
+ * The command that runs one test file of a folder on its own, with a TAP
+ * report on stdout: `path` as the folder holds its source; null when the
+ * layout has no way to run that runner's tests.
+ */
+export declare function layoutTestArgv(layout: FolderLayout, path: string, runner?: "node:test" | "vitest"): readonly string[] | null;

package/dist/src/api.js

@@ -15,7 +15,16 @@
  * to throw.
  *
  * `walk` returns the walk `plan` and `cut` make, whole, for a platform
- * that generates its own stubs and project from it.
+ * that generates its own stubs and project from it. `analyse` goes on from
+ * the walk to what `cut` writes the folder from (manifest, contract, stubs,
+ * surface), and runs no process at all, Git included; `importGraph` builds
+ * the graph once for many analyses. `folderLayout` says where a cut folder
+ * keeps its harness, mocks, configuration and tests, and what a grader runs.
+ *
+ * The extractor and the fixture compile are `carveout/extract`
+ * (`extract.ts`); the alias table, the vocabulary scan, the draft, carry-back
+ * and the mock runtime's text, pure, are `carveout/pseudonyms`
+ * (`pseudonyms.ts`).
  *
  * Also exported: the policy's text checks (`integrityOf`,
  * `gainedIntegrity`, `weakenedTest`) and the slice and project modules
@@ -24,10 +33,14 @@
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { cutSlice, patchProject, planBlockers, planSlice, } from "./carve.js";
+import { RECORD_PATH, cutSlice, patchProject, planBlockers, planSlice, sliceInputOf, } from "./carve.js";
+import { CutError, analyseSlice } from "./cut.js";
+import { buildGraph, listFiles, walkGraph } from "./graph.js";
+import { ASSETS_LOADER_PATH, BUILD_SCRIPT_PATH, ENV_FILE, HARNESS_DIR, MOCKS_DIR, MOCK_RUNTIME_PATH, TESTS_DIR, TEST_RUNNER_PATH, runtimePath, } from "./project/project.js";
 import { SLICE_BUDGET_DEFAULTS, TEST_LEFT_REASON, testsVerdict, } from "./core.js";
 export * from "./core.js";
 export { gainedIntegrity, integrityOf, weakenedTest } from "./policy.js";
+export { CutError };
 const budgetOf = (options) => ({
     maxFiles: options.maxFiles ?? SLICE_BUDGET_DEFAULTS.maxFiles,
     maxDepth: options.depth ?? SLICE_BUDGET_DEFAULTS.maxDepth,
@@ -132,3 +145,132 @@ export function patch(input) {
         ...(input.allow === undefined ? {} : { allow: input.allow }),
     });
 }
+/**
+ * The import graph of a whole checkout, read once, for many `analyse`
+ * calls on it (`AnalyseOptions.graph`). It does not depend on the entries;
+ * it does on whether imports of the repository's own packages are followed
+ * into their source, which `copyPure` and the repository's
+ * `carveout.config.json` decide, as they do for the analyses: build it with
+ * the same `copyPure` they take. Runs no process: the files are every file
+ * under the root outside the folders a graph ignores, or `files`.
+ */
+export function importGraph(root, options = {}) {
+    const { repo, settled } = sliceInputOf({
+        repo: root,
+        entryPoints: [],
+        ...(options.copyPure === undefined ? {} : { copyPure: options.copyPure }),
+    });
+    return buildGraph(repo, options.files ?? listFiles(repo, { git: false }), {
+        followWorkspaces: settled.followWorkspaces,
+    }).graph;
+}
+/**
+ * The analysis `cut` makes before it writes anything, on the same code
+ * path and with the same request after `carveout.config.json`, for a
+ * platform that writes its own folder: on the same checkout, its manifest
+ * and contract are the cut's, but for the commit and dirty fields, which
+ * are the caller's here. It runs no process (no Git, no npm unless the
+ * `packageTypes` given does) and writes nothing. Throws a `CutError` when
+ * no slice can be made at all.
+ */
+export function analyse(options) {
+    const { repo, entryPoints, budget, walk: walkOptions, params } = sliceInputOf(requestOf(options));
+    const graph = options.graph ??
+        walkGraph(repo, entryPoints, budget, {
+            ...walkOptions,
+            files: options.files ?? listFiles(repo, { git: false }),
+        }).built.graph;
+    return analyseSlice({
+        sourceDir: repo,
+        graph,
+        params,
+        source: { commitSha: options.commitSha, isDirty: options.isDirty ?? (() => false) },
+        signal: options.signal ?? new AbortController().signal,
+        log: options.log ?? (() => { }),
+        widenLiterals: options.widenLiterals ?? true,
+        ...(options.packageTypes === undefined ? {} : { packageTypes: options.packageTypes }),
+        ...(options.pathReads === undefined ? {} : { pathReads: options.pathReads }),
+        ...(options.externalsOf === undefined ? {} : { externalsOf: options.externalsOf }),
+    });
+}
+/** Why a change to a carveout folder's root file is refused. */
+const CONFIG_REASONS = {
+    "package.json": "package.json is the folder's; scripts and dependencies are not the submission's to change.",
+    "package-lock.json": "The lockfile is the folder's.",
+    ".npmrc": ".npmrc is the folder's.",
+    ".nvmrc": ".nvmrc is the folder's.",
+    "tsconfig.json": "tsconfig.json is the folder's; the build's options are not the submission's to change.",
+    "vitest.config.mjs": "vitest.config.mjs is the folder's; how tests run is not the submission's to change.",
+    [ENV_FILE]: `${ENV_FILE} is the folder's placeholder environment.`,
+    [RECORD_PATH]: `${RECORD_PATH} is the folder's record of the cut.`,
+};
+/**
+ * Where a carveout folder keeps its harness (`carveout/`), its mock
+ * packages (`carveout/packages`), its mock runtime, its configuration and
+ * its tests, and the commands that install, build and test it as `carveout
+ * check` does (`npm test` is `node carveout/test.js` after the build), for
+ * a grader that takes the layout as a parameter. Hidden tests go at their
+ * repository paths, as `carveout check --accept` puts them, and run one at
+ * a time with `tests.run` (`layoutTestArgv`). Read from the folder's record.
+ */
+export function folderLayout(record) {
+    const generated = new Set(record.generated.map((file) => file.path));
+    const configFiles = {};
+    for (const path of [...generated, RECORD_PATH, ...(record.lockfile ? ["package-lock.json"] : [])].sort())
+        if (!path.includes("/") && !/\.(?:[cm]?[jt]sx?|d\.ts)$/.test(path) && !/\.md$/i.test(path))
+            configFiles[path] = CONFIG_REASONS[path] ?? `${path} is the folder's own; carveout wrote it.`;
+    const install = ["--ignore-scripts", "--no-audit", "--no-fund"];
+    return {
+        harnessDir: HARNESS_DIR,
+        mocksDir: MOCKS_DIR,
+        mockRuntimePath: MOCK_RUNTIME_PATH,
+        envFile: ENV_FILE,
+        harnessRoots: [HARNESS_DIR, "node_modules"],
+        configFiles,
+        commands: [
+            { name: "install", argv: record.lockfile ? ["npm", "ci", ...install] : ["npm", "install", ...install] },
+            {
+                name: "build",
+                argv: generated.has(BUILD_SCRIPT_PATH)
+                    ? ["node", BUILD_SCRIPT_PATH]
+                    : ["node", "node_modules/typescript/bin/tsc", "-p", "tsconfig.json"],
+            },
+            { name: "public-tests", argv: ["node", TEST_RUNNER_PATH] },
+        ],
+        tests: {
+            publicDir: null,
+            privateDir: null,
+            files: [
+                ...new Set([
+                    ...(record.tests?.carried ?? []),
+                    ...[...generated].filter((path) => path.startsWith(`${TESTS_DIR}/`) && /\.test\.[cm]?tsx?$/.test(path)),
+                ]),
+            ].sort(),
+            run: {
+                "node:test": {
+                    argv: [
+                        "node",
+                        `--env-file=${ENV_FILE}`,
+                        `--import=./${ASSETS_LOADER_PATH}`,
+                        "--test",
+                        "--test-reporter=tap",
+                        "--test-reporter-destination=stdout",
+                    ],
+                    emitted: true,
+                },
+                vitest: generated.has("vitest.config.mjs")
+                    ? { argv: ["node_modules/.bin/vitest", "run", "--config", "vitest.config.mjs", "--reporter=tap"], emitted: false }
+                    : null,
+            },
+        },
+    };
+}
+/**
+ * The command that runs one test file of a folder on its own, with a TAP
+ * report on stdout: `path` as the folder holds its source; null when the
+ * layout has no way to run that runner's tests.
+ */
+export function layoutTestArgv(layout, path, runner = "node:test") {
+    const run = layout.tests.run[runner];
+    return run === null ? null : [...run.argv, run.emitted ? runtimePath(path) : path];
+}

package/dist/src/carve.d.ts

@@ -8,13 +8,14 @@
  * scripts off, the public registry only) and resolves the folder's
  * lockfile with npm; `offline` skips both.
  */
-import { type BoundaryContract, type CoverageGate, type DependencyChoice, type GeneratedFile, type ImportRewrite, type ReachResult, type ResolvedDependency, type SliceBudget, type SliceManifest, type SliceExternals, type SliceExposure, type SliceTestLeft, type TestRunner } from "./core.js";
+import { type BoundaryContract, type CoverageGate, type DependencyChoice, type GeneratedFile, type ImportRewrite, type ReachResult, type ResolvedDependency, type SliceBudget, type SliceManifest, type SliceParams, type SliceExternals, type SliceExposure, type SliceTestLeft, type TestRunner } from "./core.js";
+import { type VitestSettings } from "./project/vitest-config.js";
 import { type Refusal } from "./policy.js";
 import { type SandboxSpec } from "./sandbox.js";
 import { type Readiness } from "./readiness.js";
 import { type AliasRule, type FolderPseudonyms } from "./pseudonyms/index.js";
 import { type Receipt } from "./receipt.js";
-export declare const CARVEOUT_VERSION = "0.2.0";
+export declare const CARVEOUT_VERSION = "0.3.1";
 export declare const RECORD_PATH = "carveout.json";
 export declare const RECORD_SCHEMA_VERSION = 1;
 export declare const BOUNDARY_PATH = "BOUNDARY.md";
@@ -532,6 +533,58 @@ export interface ComputedCut {
     readonly record: Omit<CarveoutRecord, "generated" | "lockfile">;
     readonly contract: BoundaryContract;
 }
+/**
+ * What a request asks of `analyseSlice`, after the owner's configuration
+ * (`settle`): the walk's options, the test setup and the slice's params.
+ * `computeCut` and the library's `analyse` (`api.ts`) share it, so both
+ * cut the same slice of the same request.
+ */
+export declare function sliceInputOf(request: SliceRequest & {
+    readonly copy?: readonly string[];
+    readonly widenLiterals?: boolean;
+    readonly public?: boolean;
+    readonly live?: readonly string[];
+}): {
+    settled: SliceRequest & {
+        readonly copy?: readonly string[];
+        readonly widenLiterals?: boolean;
+        readonly public?: boolean;
+        readonly live?: readonly string[];
+    } & {
+        readonly wholePackage: boolean;
+        readonly followWorkspaces: boolean;
+        readonly copyPure: boolean;
+        readonly private: readonly string[];
+        readonly copy: readonly string[];
+        readonly widenLiterals: boolean;
+        readonly public: boolean;
+        readonly maxExposure: {
+            readonly lines?: number;
+            readonly percent?: number;
+        };
+    };
+    repo: string;
+    budget: SliceBudget;
+    entryPoints: string[];
+    setup: string[];
+    vitest: VitestSettings | null;
+    testRunner: "vitest" | "node:test" | null;
+    live: string[];
+    walk: {
+        unseen?: readonly string[] | undefined;
+        roots?: string[] | undefined;
+        isPrivate?: ((path: string) => boolean) | undefined;
+        pure?: {
+            readonly package: (specifier: string) => boolean;
+            readonly sideEffects: (file: string) => boolean;
+        } | undefined;
+        followWorkspaces?: boolean | undefined;
+        wholePackage?: boolean | undefined;
+        tests: boolean;
+        runnerOf: (file: string, specifiers: readonly string[]) => TestRunner | null;
+    };
+    params: SliceParams;
+};
 export declare function computeCut(request: Omit<CutRequest, "out">): Promise<ComputedCut>;
 /**
  * The packages whose classes the code tests with `instanceof`, by package

package/dist/src/carve.js

@@ -35,7 +35,7 @@ import { sandboxRun } from "./sandbox.js";
 import { configuredFolders, liveCandidates } from "./readiness.js";
 import { exactToFolder, fromFolder, specifierPackages, toFolder, keptNames, looseLeaks, maskKept, pseudonymize, vocabularyBlockers, vocabularyLeaks, workspaceNames, ownedNames, workspaceVocabulary, } from "./pseudonyms/index.js";
 import { RECEIPT_SCHEMA_VERSION, folderRecordFor, folderView, newCutId, receiptPathFor, trustedBaseline, trustedCut, trustedCutWith, writeReceipt, } from "./receipt.js";
-export const CARVEOUT_VERSION = "0.2.0";
+export const CARVEOUT_VERSION = "0.3.1";
 export const RECORD_PATH = "carveout.json";
 export const RECORD_SCHEMA_VERSION = 1;
 /** Blockers that stop a cut before it writes anything. */
@@ -918,40 +918,52 @@ function withoutOutsideImporters(contract, outsideName) {
         })),
     };
 }
-export async function computeCut(request) {
+/**
+ * What a request asks of `analyseSlice`, after the owner's configuration
+ * (`settle`): the walk's options, the test setup and the slice's params.
+ * `computeCut` and the library's `analyse` (`api.ts`) share it, so both
+ * cut the same slice of the same request.
+ */
+export function sliceInputOf(request) {
     const settled = settle(request);
     const repo = resolve(request.repo);
-    const log = request.log ?? (() => { });
     const budget = request.budget ?? SLICE_BUDGET_DEFAULTS;
     const entryPoints = entriesOf(request);
     const { setup, settings: vitest } = withTestSetup(repo, entryPoints, request.tests === true);
     const testRunner = request.tests === true ? packageTestRunner(repo, entryPoints) : null;
-    const { built } = walkGraph(repo, entryPoints, budget, {
+    const live = [...new Set(request.live ?? [])].sort(compare);
+    const walk = {
         ...walkOptions(settled, repo),
         ...(setup.length === 0 ? {} : { roots: setup }),
         ...(request.unseen === undefined || request.unseen.length === 0 ? {} : { unseen: request.unseen }),
-    });
+    };
+    const params = {
+        entryPoints,
+        budget,
+        tests: request.tests === true,
+        ...(setup.length === 0 ? {} : { setupFiles: setup }),
+        ...(testRunner === "vitest" ? { testRunner } : {}),
+        ...(live.length === 0 ? {} : { live }),
+        ...(settled.wholePackage ? { wholePackage: true } : {}),
+        ...(settled.followWorkspaces ? { followWorkspaces: true } : {}),
+        ...(settled.copyPure ? { copyPure: true } : {}),
+        ...(settled.private.length === 0 ? {} : { private: settled.private }),
+        ...(settled.copy.length === 0 ? {} : { copy: settled.copy }),
+    };
+    return { settled, repo, budget, entryPoints, setup, vitest, testRunner, live, walk, params };
+}
+export async function computeCut(request) {
+    const { settled, repo, budget, entryPoints, vitest, testRunner, live, walk, params } = sliceInputOf(request);
+    const log = request.log ?? (() => { });
+    const { built } = walkGraph(repo, entryPoints, budget, walk);
     log(`Read the imports of ${built.files.length} files.`);
     const commitSha = git(repo, ["rev-parse", "HEAD"]);
     const signal = AbortSignal.timeout(15 * 60_000);
-    const live = [...new Set(request.live ?? [])].sort(compare);
     const workspaces = workspacePackages(repo);
     const analysis = await analyseSlice({
         sourceDir: repo,
         graph: built.graph,
-        params: {
-            entryPoints,
-            budget,
-            tests: request.tests === true,
-            ...(setup.length === 0 ? {} : { setupFiles: setup }),
-            ...(testRunner === "vitest" ? { testRunner } : {}),
-            ...(live.length === 0 ? {} : { live }),
-            ...(settled.wholePackage ? { wholePackage: true } : {}),
-            ...(settled.followWorkspaces ? { followWorkspaces: true } : {}),
-            ...(settled.copyPure ? { copyPure: true } : {}),
-            ...(settled.private.length === 0 ? {} : { private: settled.private }),
-            ...(settled.copy.length === 0 ? {} : { copy: settled.copy }),
-        },
+        params,
         source: {
             commitSha,
             isDirty: (paths) => commitSha !== null &&

package/dist/src/cut.d.ts

@@ -11,8 +11,18 @@
  */
 import type { BoundaryContract, ReachResult, SliceExternals, SliceGraph, SliceManifest, SliceParams } from "./core.js";
 import { type PackageTypesFetcher } from "./extract/package-types.js";
+/** Why a cut could not be made at all. */
+export type CutErrorCode = 
+/** The entry points reach no file. */
+"no_files"
+/** The included source is past `INCLUDED_BYTES_MAX`. */
+ | "too_large"
+/** An included file is outside the checkout, a symbolic link or not a regular file. */
+ | "unreadable";
 /** Why a cut could not be made at all, as opposed to a blocker it reports. */
 export declare class CutError extends Error {
+    readonly code: CutErrorCode;
+    constructor(code: CutErrorCode, message: string);
 }
 /** Bytes of included source one slice may copy. */
 export declare const INCLUDED_BYTES_MAX: number;
@@ -75,4 +85,11 @@ export declare function analyseSlice(input: {
     readonly packageTypes?: PackageTypesFetcher;
     /** See `extractTypeScriptBoundary`; true unless told otherwise. */
     readonly widenLiterals?: boolean;
+    /**
+     * What a file read by path does to the slice: `block` (the default, the
+     * CLI's) makes a `path_read` blocker of a path the slice cannot copy and
+     * of a file read by path outside the slice; `omit` leaves both out, as
+     * sandbox-factory's slice tool did, which has no way to carry one.
+     */
+    readonly pathReads?: "block" | "omit";
 }): Promise<SliceAnalysis>;

package/dist/src/cut.js

@@ -25,6 +25,11 @@ import { lockedSpec, typesPackageOf, } from "./extract/package-types.js";
 import { declarationPathFor, extractTypeScriptBoundary, isNodeBuiltin, isDataPath, isScriptPath, packageNameOf, } from "./extract/typescript.js";
 /** Why a cut could not be made at all, as opposed to a blocker it reports. */
 export class CutError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
 }
 /** Bytes of included source one slice may copy. */
 export const INCLUDED_BYTES_MAX = 64 * 1024 * 1024;
@@ -140,22 +145,22 @@ async function readIncluded(sourceDir, files) {
         const absolute = resolve(sourceDir, path);
         const rel = relative(sourceDir, absolute);
         if (rel.startsWith("..") || isAbsolute(rel) || rel === "")
-            throw new CutError(`${path} is outside the repository.`);
+            throw new CutError("unreadable", `${path} is outside the repository.`);
         // One handle for the check and the read, so the file cannot be swapped
         // between them; a symlink fails to open, and a FIFO opens without
         // blocking and then fails the regular-file check.
         const handle = await open(absolute, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK).catch(() => null);
         if (handle === null)
-            throw new CutError(`${path} cannot be read (a symbolic link is not copied).`);
+            throw new CutError("unreadable", `${path} cannot be read (a symbolic link is not copied).`);
         let stats;
         let bytes;
         try {
             stats = await handle.stat();
             if (!stats.isFile())
-                throw new CutError(`${path} is not a regular file.`);
+                throw new CutError("unreadable", `${path} is not a regular file.`);
             total += stats.size;
             if (total > INCLUDED_BYTES_MAX)
-                throw new CutError(`The slice holds more than ${INCLUDED_BYTES_MAX / 1024 / 1024} MB of source; narrow the entry points or the budget.`);
+                throw new CutError("too_large", `The slice holds more than ${INCLUDED_BYTES_MAX / 1024 / 1024} MB of source; narrow the entry points or the budget.`);
             bytes = await handle.readFile();
         }
         finally {
@@ -259,7 +264,7 @@ export async function analyseSlice(input) {
             });
     if (walk.included.length === 0) {
         // Nothing to slice: say which entry points missed before failing.
-        throw new CutError(blockers.length === 0
+        throw new CutError("no_files", blockers.length === 0
             ? "The entry points reach no file."
             : blockers.map((blocker) => blocker.detail).join(" "));
     }
@@ -289,8 +294,9 @@ export async function analyseSlice(input) {
     // A test brought along may hold a computed import: what it names is the
     // baseline's business, not a blocker (see `reach`).
     const carriedTests = new Set(walk.tests);
+    const omitPathReads = input.pathReads === "omit";
     for (const dependency of walk.dependencies) {
-        if (dependency.status === "path" && copied(dependency.specifier ?? ""))
+        if (dependency.status === "path" && (omitPathReads || copied(dependency.specifier ?? "")))
             continue;
         if (dependency.status === "dynamic" && carriedTests.has(dependency.file))
             continue;
@@ -340,7 +346,7 @@ export async function analyseSlice(input) {
     }
     // A file read by path must be there itself; a stub at its path is not it.
     for (const edge of walk.cuts.outbound)
-        if (edge.relation === "reads" && !copied(edge.to))
+        if (edge.relation === "reads" && !omitPathReads && !copied(edge.to))
             blockers.push({
                 code: "path_read",
                 file: edge.from,

package/dist/src/extract.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `carveout/extract`: the stub extractor and the fixture compile a cut
+ * runs, for a platform that calls them itself (sandbox-factory's worker,
+ * whose `slice/*`, `compiler-config.ts` and `package-registry.ts` these
+ * were forked from; NOTICE.md lists where they differ now).
+ *
+ * - `extract/hash.ts`: `sha256`, `gitBlobId`, `gitFileMode`.
+ * - `extract/typescript.ts`: the boundary extractor and its parts
+ *   (`extractTypeScriptBoundary`, `boundedHost`, `extractionOptions`,
+ *   `filterDeclaration`, `sanitizeDeclaration`, `NODE_BUILTINS`,
+ *   `isNodeBuiltin`, `isScriptPath`, `isDataPath`, `declarationPathFor`).
+ * - `extract/fixture.ts`: `compileFixture`, `packageUses`,
+ *   `packageModules`, `packageShim`, `SHIM_PATH`, `UNTYPED_PACKAGE_OPTIONS`,
+ *   `UNTYPED_PACKAGE_CODES`, `DIAGNOSTICS_MAX`.
+ * - `extract/package-types.ts`: `npmPackageTypes` (npm, scripts off) and
+ *   the `PackageTypesFetcher` contract `analyse` takes.
+ * - `extract/compiler-config.ts`: `loadConfig`, `nearestCompilerOptions`,
+ *   `workspacePackages`, `workspaceModuleResolver`, `exportTarget`,
+ *   `pnpmWorkspacePatterns`.
+ * - `extract/package-registry.ts`: `packageRegistries`,
+ *   `isPublicRegistry`, `lockIntegrities`, `publicByIntegrity`.
+ *
+ * Only `npmPackageTypes` starts a process; `publicByIntegrity` reads the
+ * public registry over HTTPS.
+ */
+export * from "./extract/hash.js";
+export * from "./extract/typescript.js";
+export * from "./extract/fixture.js";
+export * from "./extract/package-types.js";
+export * from "./extract/compiler-config.js";
+export * from "./extract/package-registry.js";