carveout 0.1.1 → 0.2.0

package/dist/src/command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Runs a tool to completion and returns its stdout. `env` is added to a
+ * minimal base, so nothing of the caller's environment but PATH and HOME
+ * passes through; an abort kills the whole process group.
+ */
+export declare function command(executable: string, args: readonly string[], options: {
+    signal: AbortSignal;
+    cwd?: string;
+    env?: Record<string, string>;
+}): Promise<string>;

package/dist/src/core.d.ts

@@ -0,0 +1,11 @@
+/** The pure rules the extractor reads, from one place. */
+export * from "./slice/analysis.js";
+export * from "./slice/graph.js";
+export * from "./slice/reach.js";
+export * from "./slice/report.js";
+export * from "./slice/externals.js";
+export * from "./slice/manifest.js";
+export * from "./project/provenance.js";
+export * from "./project/secrets.js";
+export * from "./project/build.js";
+export * from "./project/project.js";

package/dist/src/cut.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The cut: from the checkout's import graph and its files, the files a
+ * slice needs and the shape of their boundary.
+ *
+ * Walks the graph with `reach`, reads the included files, extracts
+ * signatures for the cut modules and the public surface (TypeScript and
+ * JavaScript; other languages get names only), compiles the fixture with
+ * the stubs in place, and assembles the manifest and the contract. A pure
+ * function of the graph, the source bytes and the request, apart from the
+ * package types it may fetch.
+ */
+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, as opposed to a blocker it reports. */
+export declare class CutError extends Error {
+}
+/** Bytes of included source one slice may copy. */
+export declare const INCLUDED_BYTES_MAX: number;
+/** Everything a slice of one request is, before anything is written. */
+export interface SliceAnalysis {
+    readonly manifest: SliceManifest;
+    readonly contract: BoundaryContract;
+    readonly contractJson: string;
+    readonly stubs: readonly {
+        path: string;
+        module: string;
+        text: string;
+    }[];
+    /** The public surface's declarations and check; see `surfaceFiles`. */
+    readonly surface: readonly {
+        path: string;
+        text: string;
+    }[];
+    readonly ready: boolean;
+    /**
+     * Whether the slice compiles with the source's noImplicitAny, so the
+     * folder can hold its code to it; false when the source has it off.
+     */
+    readonly keepsImplicitAny: boolean;
+    /**
+     * The files where the stubs leave an implicit any, when the source holds
+     * its code to noImplicitAny: the folder relaxes it for them alone when
+     * nothing else in the slice imports them.
+     */
+    readonly implicitAnyFiles: readonly string[];
+    /** The walk the slice was cut from. */
+    readonly walk: ReachResult;
+}
+/**
+ * Slices one request: walks the graph, reads the included files, extracts
+ * the boundary, compiles the fixture and assembles the manifest. A pure
+ * function of the graph, the source bytes and the parameters; the slice
+ * tool writes its result, and the scope agent checks its proposals with it.
+ */
+export declare function analyseSlice(input: {
+    readonly sourceDir: string;
+    readonly graph: SliceGraph;
+    readonly params: SliceParams;
+    readonly source: {
+        readonly commitSha: string | null;
+        /** Whether an included file differs from that commit. */
+        readonly isDirty: (paths: readonly string[]) => boolean;
+    };
+    readonly signal: AbortSignal;
+    readonly log: (line: string) => void;
+    /**
+     * The externals of the included files when an index already has them
+     * all, as `detectExternals` would give them; null to read them here.
+     */
+    readonly externalsOf?: (included: readonly string[]) => SliceExternals | null;
+    /**
+     * Fetches the types of the public packages the slice reads; without it,
+     * or when it fails, every package is untyped.
+     */
+    readonly packageTypes?: PackageTypesFetcher;
+    /** See `extractTypeScriptBoundary`; true unless told otherwise. */
+    readonly widenLiterals?: boolean;
+}): Promise<SliceAnalysis>;

package/dist/src/cut.js

@@ -12,7 +12,7 @@
 import { constants, readFileSync } from "node:fs";
 import { open, readFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { BOUNDARY_CONTRACT_SCHEMA_VERSION, OPERATION_POLICY, SLICE_MANIFEST_SCHEMA_VERSION, SLICE_TOOL_VERSION, canonicalJson, detectExternals, isRegistryVersion, isSecretPath, pathMatcher, purityRules, reach, sliceReadiness, } from "./core.js";
+import { BOUNDARY_CONTRACT_SCHEMA_VERSION, IMPLICIT_ANY_CODE, OPERATION_POLICY, SLICE_MANIFEST_SCHEMA_VERSION, SLICE_TOOL_VERSION, canonicalJson, detectExternals, isPackageName, isRegistryVersion, isSecretPath, pathMatcher, purityRules, reach, sliceReadiness, } from "./core.js";
 import { catalogResolver } from "./project/catalog.js";
 import { testRunnerResolver } from "./project/runner.js";
 import { workspaceModuleResolver, workspacePackages, } from "./extract/compiler-config.js";
@@ -214,6 +214,7 @@ export async function analyseSlice(input) {
         : pathMatcher(params.private);
     const reached = reach(graph, params.entryPoints, params.budget, {
         tests: params.tests,
+        ...(params.setupFiles === undefined || params.setupFiles.length === 0 ? {} : { roots: params.setupFiles }),
         packageOf: packageFolder(input.sourceDir),
         runnerOf: testRunnerResolver(input.sourceDir, packageFolder(input.sourceDir)),
         ...(params.wholePackage === true ? { wholePackage: true } : {}),
@@ -293,7 +294,9 @@ export async function analyseSlice(input) {
             continue;
         if (dependency.status === "dynamic" && carriedTests.has(dependency.file))
             continue;
-        if (dependency.status !== "dynamic" && isBare(dependency.specifier)) {
+        // A path read is a repository path, never a package, however it is
+        // spelled (`apps/worker/python/extract.py` is no package named `apps`).
+        if (dependency.status !== "dynamic" && dependency.status !== "path" && isBare(dependency.specifier)) {
             if (isNodeBuiltin(dependency.specifier))
                 continue;
             if (scripted && workspaceModule(dependency.specifier) !== null)
@@ -314,7 +317,7 @@ export async function analyseSlice(input) {
                 detail: dependency.status === "dynamic"
                     ? "A dynamic import of a computed name cannot be resolved."
                     : dependency.status === "path"
-                        ? `${dependency.specifier ?? ""} is read by path, and is a folder or a kind of file a slice does not copy.`
+                        ? `${dependency.specifier ?? ""} is read by path, and is a folder or a kind of file a slice does not copy: cut again with --copy ${dependency.specifier ?? "<path>"} to bring it.`
                         : `${dependency.specifier ?? ""} does not resolve to a repository file.`,
             });
     }
@@ -326,6 +329,15 @@ export async function analyseSlice(input) {
             files.add(test);
         packageFiles.set("vitest", files);
     }
+    // So does a package whose tests run on Vitest when no test of the slice
+    // came along: the tests the contributor writes run on it, as the
+    // repository's do. Pinned as the entry points' package pins it.
+    if (params.tests && params.testRunner === "vitest") {
+        const files = packageFiles.get("vitest") ?? new Set();
+        for (const entry of walk.entries)
+            files.add(entry);
+        packageFiles.set("vitest", files);
+    }
     // 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))
@@ -343,6 +355,7 @@ export async function analyseSlice(input) {
     let surface = [];
     let configs = [];
     let keepsImplicitAny = false;
+    let implicitAnyFiles = [];
     let compilation = {
         attempted: false,
         ok: false,
@@ -397,7 +410,9 @@ export async function analyseSlice(input) {
                 ...pinned,
                 ...(registry === null ? {} : { registry }),
             });
-            if (pinned.version === null)
+            // A module that is no package (`virtual:build-info`) is mocked by its
+            // name and installed by none: no pin to look for.
+            if (pinned.version === null && isPackageName(name))
                 unpinned.push({
                     code: "missing_build_input",
                     file: from === "" ? null : from,
@@ -588,11 +603,13 @@ export async function analyseSlice(input) {
         const sourceImplicitAny = options["noImplicitAny"] === true ||
             (options["noImplicitAny"] === undefined && options["strict"] === true);
         if (sourceImplicitAny && compilation.ok) {
-            // TS7xxx: the implicit-any family.
-            const implicit = compile(fixture, stubModules, false).diagnostics.filter(({ code }) => /^(TS)?7\d{3}$/.test(String(code)));
+            // The implicit-any family (TS7xxx but the checks that share it).
+            const implicitCode = new RegExp(`^(TS)?${IMPLICIT_ANY_CODE}$`);
+            const implicit = compile(fixture, stubModules, false).diagnostics.filter(({ code }) => implicitCode.test(String(code)));
             keepsImplicitAny = implicit.length === 0;
+            implicitAnyFiles = [...new Set(implicit.flatMap((d) => (d.file === undefined || d.file === null ? [] : [String(d.file)])))].sort();
             if (!keepsImplicitAny)
-                input.log(`noImplicitAny is relaxed in the folder: ${implicit.length} implicit any with the stubs (${implicit
+                input.log(`The folder keeps noImplicitAny; its build does not count the ${implicit.length} implicit any(s) the stubs leave (${implicit
                     .slice(0, 3)
                     .map((d) => `${d.file ?? ""}:${d.line ?? ""} ${d.code}`)
                     .join(", ")}).`);
@@ -726,6 +743,7 @@ export async function analyseSlice(input) {
         surface,
         ready: readiness.ready,
         keepsImplicitAny,
+        implicitAnyFiles,
         walk,
     };
 }

package/dist/src/extract/compiler-config.d.ts

@@ -0,0 +1,49 @@
+import ts from "typescript";
+export interface LoadedConfig {
+    readonly path: string | null;
+    readonly options: ts.CompilerOptions;
+    readonly rawOptions: Record<string, unknown> | undefined;
+    readonly errors: readonly string[];
+}
+/**
+ * The `packages:` list of a `pnpm-workspace.yaml`, block or flow style.
+ * Read by line: the file is a list of globs, and the worker has no YAML
+ * parser to spare.
+ */
+export declare function pnpmWorkspacePatterns(text: string): string[];
+/**
+ * The repository's own workspace packages, by name, to their directories.
+ * A shared base (`@scope/tsconfig/react.json`) is usually one of them, and a
+ * snapshot has no node_modules to find it in; and an import of one is the
+ * repository's own code, which the slice must never fetch by its name.
+ * Every directory a workspace glob names (`workspacePatterns`) that holds a
+ * named `package.json`, less those a `!` glob excludes.
+ */
+export declare function workspacePackages(root: string): Map<string, string>;
+/**
+ * The nearest `tsconfig.json` above a file, read without following `extends`
+ * outside the root. A base in an installed package resolves when the
+ * package is one of the repository's own workspaces.
+ */
+export declare function loadConfig(root: string, file: string, 
+/**
+ * For a caller loading many files' configurations: the workspaces read
+ * once, and each tsconfig loaded once, for that run.
+ */
+shared?: {
+    readonly packages?: () => ReadonlyMap<string, string>;
+    readonly loaded?: Map<string, LoadedConfig>;
+}): LoadedConfig;
+/** The target an `exports` map gives a package subpath, or null. */
+export declare function exportTarget(exports: unknown, subpath: string): string | null;
+/**
+ * The repository source a bare specifier of one of the repository's own
+ * packages stands for, by path, or null for any other specifier. The
+ * package's `exports` (or `types`, `module`, `main`) name what it ships,
+ * which is usually a build output the snapshot does not have; a target
+ * under the package's `outDir` is read back under its `rootDir`, as the
+ * build wrote it from there, and a script target that is not an output is
+ * the source itself. Memoized; the resolver never leaves the root.
+ */
+export declare function workspaceModuleResolver(root: string, packages: () => ReadonlyMap<string, string>): (specifier: string) => string | null;
+export declare function nearestCompilerOptions(root: string, file: string): Record<string, unknown> | undefined;

package/dist/src/extract/fixture.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The isolated compile that tells whether a slice closes.
+ *
+ * The included files and the generated stubs are type-checked together in
+ * memory, at the paths they hold in the repository, with the source's own
+ * compiler settings. Nothing else of the repository is visible, so an
+ * import the stubs do not cover is an error here rather than a surprise in
+ * the sandbox. Packages are declared as `any` for this check, since the
+ * worker installs nothing; the sandbox phase installs the pinned versions.
+ * Each name the slice reads of a package is declared as a type as well as
+ * a value, so a package's types used in the slice do not fail the check:
+ * only what the slice itself leaves unresolved does.
+ */
+import ts from "typescript";
+import type { CompilationResult } from "../core.js";
+export declare const DIAGNOSTICS_MAX = 100;
+export declare const SHIM_PATH = "__slice__/packages.d.ts";
+export interface FixtureInput {
+    readonly root: string;
+    /** Repository-relative path to text: included files, stubs and shims. */
+    readonly files: ReadonlyMap<string, string>;
+    readonly compilerOptions: ts.CompilerOptions;
+    readonly shimmedPackages: readonly string[];
+    /** Diagnostic codes not to report: see `UNTYPED_PACKAGE_CODES`. */
+    readonly ignoredCodes?: readonly number[];
+    /**
+     * Bare specifiers of the repository's own packages, to the path in
+     * `files` each stands for: no node_modules holds them here.
+     */
+    readonly modules?: ReadonlyMap<string, string>;
+    /** Diagnostics reported at most; defaults to `DIAGNOSTICS_MAX`. */
+    readonly limit?: number;
+    /**
+     * A directory whose node_modules holds fetched package types, read from
+     * disk; a package that resolves there is typed, and its shim yields.
+     */
+    readonly packageTypes?: string | null;
+}
+/**
+ * Settings for a compile whose packages are shimmed as `any`. A callback
+ * passed to an untyped function has no parameter types to take, which
+ * `noImplicitAny` reports though the package's own types would give them.
+ */
+export declare const UNTYPED_PACKAGE_OPTIONS: ts.CompilerOptions;
+/**
+ * Errors only a shimmed package raises: TS2347, a type argument given to
+ * an untyped call (`useState<string>()`).
+ */
+export declare const UNTYPED_PACKAGE_CODES: readonly number[];
+/**
+ * What the slice reads of one package specifier: the names it imports, and
+ * under each the members it reads off it (`React.ComponentProps`,
+ * `z.infer`), as deep as it reads them. A default import is `default`.
+ */
+export interface PackageUse {
+    readonly members: Map<string, PackageUse>;
+}
+export interface PackageUses {
+    /** By specifier, as imported. */
+    readonly modules: ReadonlyMap<string, PackageUse>;
+    /** By global name: `React`. */
+    readonly globals: ReadonlyMap<string, PackageUse>;
+}
+/**
+ * What the files read of each specifier that `shimmed` says is a package,
+ * and of the globals such a package declares (`PACKAGE_GLOBALS`),
+ * by the packages' names (`react` covers `react/jsx-runtime`). Read from the
+ * syntax alone: a name shadowed in a nested scope may be counted, which
+ * only declares one more `any`.
+ */
+export declare function packageUses(files: ReadonlyMap<string, string>, shimmed: (specifier: string) => boolean): PackageUses;
+/**
+ * Ambient declarations that make the listed packages resolve as `any`, with
+ * Node's own modules and globals as the generated project declares them.
+ * A specifier in `uses` gets a module of its own that exports each name the
+ * slice reads as both a value and a type, so `import type { X }` and
+ * `React.ComponentProps<"button">` check as they would with the package's
+ * types; any other is untyped, which only works as a value. A global in
+ * `uses` is a namespace of the types read off it. A `typed` package, whose
+ * fetched types the compile reads, is declared by patterns that yield to
+ * them.
+ */
+export declare function packageShim(packages: readonly string[], { modules: uses, globals }?: PackageUses, typed?: (name: string) => boolean): string;
+/**
+ * The part of `packageShim` that declares what the slice reads: a module
+ * for each specifier in `uses` and a namespace for each global. A sliced
+ * project declares its packages with these too, so it builds against what
+ * the slice was checked against; one it `installed` by a pattern, which
+ * yields to the package's own types.
+ */
+export declare function packageModules({ modules: uses, globals }: PackageUses, installed?: (specifier: string) => boolean): {
+    specifiers: string[];
+    text: string;
+};
+/**
+ * A compiler message with the checkout's path taken out. Messages name
+ * files by absolute path (TS6059 names the project's `rootDir`), and they
+ * are written into the folder's record, which may leave the machine: a
+ * path under the repository becomes repository-relative, and one under the
+ * fetched package types becomes `<package types>/...`.
+ */
+export declare function withoutRoots(message: string, root: string, types?: string | null): string;
+export declare function compileFixture(input: FixtureInput): CompilationResult;

package/dist/src/extract/hash.d.ts

@@ -0,0 +1,6 @@
+import type { Stats } from "node:fs";
+/** Git's blob id for these bytes: what `git hash-object` would print. */
+export declare function gitBlobId(bytes: Uint8Array): string;
+export declare function sha256(bytes: Uint8Array | string): string;
+/** The two modes Git records for a regular file. */
+export declare function gitFileMode(stats: Pick<Stats, "mode">): string;

package/dist/src/extract/package-registry.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Where a repository says the packages it imports are fetched from: the
+ * URLs its lockfiles resolved them at, and the registries its npm, Yarn
+ * and pnpm configuration send their scopes to. These are the facts
+ * `resolveScope` in core decides by: a package is installed by its name
+ * only when they show it comes from the public registry, since a private
+ * registry's package name is anyone's to publish on the public one.
+ *
+ * Only the repository's own files are read, never a registry: the root
+ * `package-lock.json` or `npm-shrinkwrap.json`, `yarn.lock` (classic and
+ * Berry), `pnpm-lock.yaml`, `.npmrc`, `.yarnrc`, `.yarnrc.yml`, and the
+ * `publishConfig` of the root and workspace manifests. Lockfiles in YAML
+ * are read by line, as far as their entries' names and resolutions.
+ */
+import type { PackageRegistry } from "../core.js";
+/** Whether a registry or tarball URL is the public registry's. */
+export declare function isPublicRegistry(url: string): boolean;
+/**
+ * What the repository at `root` says of each package's registry, as a
+ * function of its name: `private` when any of its configuration sends the
+ * package's scope, or every package, to another registry, or a lockfile
+ * resolved it elsewhere; `public` when a lockfile resolved it from the
+ * public registry, or pinned it from a registry that the configuration
+ * its own package manager reads names as the public one; null when
+ * nothing says.
+ *
+ * One file naming another registry is enough, whichever manager reads it:
+ * Berry ignores `.npmrc` and npm ignores `.yarnrc.yml`, so a public
+ * registry in one never outweighs a private one in another.
+ */
+export declare function packageRegistries(root: string): (name: string) => PackageRegistry | null;
+/**
+ * The integrity each `pnpm-lock.yaml` entry with no tarball URL records,
+ * by package name and version. Such an entry came from whatever registry
+ * the developer's configuration named, so on its own it shows nothing;
+ * its `sha512-` integrity, equal to the one the public registry publishes
+ * for the same version, shows it is the public package byte for byte (see
+ * `publicByIntegrity`).
+ */
+export declare function lockIntegrities(root: string): Map<string, Map<string, string>>;
+/**
+ * Whether every version of `name` the lockfile records has the integrity
+ * the public registry publishes for it: then the repository installs the
+ * public package, whatever registry served it. One mismatch, or a version
+ * the registry does not have, and it shows nothing.
+ */
+export declare function publicByIntegrity(name: string, versions: ReadonlyMap<string, string>, signal: AbortSignal): Promise<boolean>;

package/dist/src/extract/package-types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The declared types of the public packages a slice reads, for the
+ * extractor and the fixture compile.
+ *
+ * A snapshot has no node_modules, so without these every package is
+ * untyped: a value whose type the source infers from one (a zod schema)
+ * becomes `any` in its stub, and the sandbox, which installs the package,
+ * no longer compiles what the source does. Only packages the repository
+ * shows come from the public registry are fetched, at the version its
+ * lockfile installed (or the range its package.json pins), with install
+ * scripts off; the compiler reads their declaration files and nothing of
+ * them runs.
+ */
+export interface PackageTypesRequest {
+    readonly name: string;
+    /** What npm installs it by: a version, a range or an `npm:` alias. */
+    readonly spec: string;
+}
+export interface PackageTypes {
+    /** A directory whose `node_modules` holds the packages. */
+    readonly directory: string;
+    /** What was installed under each requested name. */
+    readonly packages: readonly {
+        name: string;
+        version: string;
+    }[];
+}
+/** The types, or why there are none: the slice then goes on untyped. */
+export type PackageTypesFetcher = (requests: readonly PackageTypesRequest[], signal: AbortSignal) => Promise<PackageTypes | {
+    readonly failed: string;
+}>;
+export declare const PUBLIC_REGISTRY = "https://registry.npmjs.org/";
+/** How long one fetch may take before the slice goes on without types. */
+export declare const PACKAGE_TYPES_TIMEOUT_MS = 120000;
+/**
+ * What the repository's npm lockfile installed under `name` at its root,
+ * as npm would install it again: `1.2.3`, or `npm:other@1.2.3` for an
+ * alias. Null when no npm lockfile says.
+ */
+export declare function lockedSpec(root: string, name: string): string | null;
+/** `@types/x` for `x`, `@types/scope__x` for `@scope/x`. */
+export declare function typesPackageOf(name: string): string;
+/**
+ * Fetches with npm into `root`, one directory per set of requests, kept
+ * for the next slice that reads the same packages. Nothing of the worker's
+ * npm configuration applies: the registry is the public one, the user
+ * config an empty file, and no credential is in the environment.
+ */
+export declare function npmPackageTypes(options: {
+    readonly root: string;
+    readonly timeoutMs?: number;
+}): PackageTypesFetcher;

package/dist/src/extract/surface.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The public surface's types, held where the slice can check them.
+ *
+ * The interface test asserts that each export outside code imports is
+ * still there; it cannot see a changed signature, and a slice whose
+ * importers live in other packages passes a change that breaks them. So
+ * the cut writes, under `carveout/surface/`, the declarations the slice's
+ * own modules had when it was cut (a mirror of their paths, each import
+ * pointing at the mirror, the folder's stub or the package it named), and
+ * `check.ts`, which holds every export outside code uses to that type:
+ *
+ * - a value must still be assignable to its old type, so every call and
+ *   read outside code makes still compiles;
+ * - an interface or type alias must be assignable both ways, since
+ *   outside code both reads and builds it.
+ *
+ * `npm test` type-checks `check.ts` with the folder's own compiler (see
+ * `carveout/test.js`) and reports each error as the export whose type
+ * changed. Enums, and classes with private or protected members, are
+ * nominal: an identical copy of one is not assignable to the original, so
+ * they are not checked. A check that fails before any edit (a type that
+ * holds such a class) fails at the slice's baseline and is not counted.
+ */
+import ts from "typescript";
+export interface SurfaceInput {
+    readonly program: ts.Program;
+    /** Included modules outside code imports, with the names it takes. */
+    readonly surface: ReadonlyMap<string, ReadonlySet<string> | "*">;
+    readonly included: ReadonlySet<string>;
+    /** Cut modules whose stub the folder holds at their declaration path. */
+    readonly stubbed: ReadonlySet<string>;
+    /** A specifier's module in the repository, or null for a package. */
+    readonly resolve: (specifier: string, from: string) => string | null;
+    readonly abs: (path: string) => string;
+}
+export interface SurfaceFile {
+    readonly path: string;
+    readonly text: string;
+}
+/**
+ * The mirror and the check for a slice's public surface; empty when there
+ * is nothing to check or a module's declarations cannot be emitted.
+ */
+export declare function surfaceFiles(input: SurfaceInput): SurfaceFile[];