carveout 0.1.1 → 0.2.0

package/dist/src/sandbox.js

@@ -0,0 +1,154 @@
+/**
+ * Running code that came back from outside in a container.
+ *
+ * A folder that came back holds the contributor's code, and its tests run
+ * it. On the maintainer's machine that code would run as the maintainer,
+ * with their files (the closed repository, the receipts that map the
+ * folder's pseudonyms back to the repository's names, credentials) and
+ * their network. Here each step is its own `docker run --rm` that mounts one
+ * directory, the scratch copy, and nothing else: no HOME, no receipts, no
+ * checkout beyond the copy. Only the install step has a network, and it runs
+ * a package manager with lifecycle scripts off on the receipt's manifests,
+ * so none of the folder's code runs while the network is there. Every other
+ * step (the build, the tests, the owner's acceptance tests, a merge's
+ * verify command) runs with `--network none`, all capabilities dropped, a
+ * read-only root, and bounds on memory and processes.
+ *
+ * Docker by default; `CARVEOUT_CONTAINER` names another runtime that takes
+ * the same arguments (podman), and `CARVEOUT_SANDBOX_IMAGE` the image (a
+ * Node image at this process's major version unless given).
+ */
+import { execFileSync, spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { relative, resolve, sep } from "node:path";
+/** The runtime and image from the environment, or Docker and a Node image at this process's major version. */
+export function defaultSandbox(image) {
+    return {
+        runtime: process.env["CARVEOUT_CONTAINER"] ?? "docker",
+        image: image ?? process.env["CARVEOUT_SANDBOX_IMAGE"] ?? `node:${process.versions.node.split(".")[0] ?? "22"}`,
+    };
+}
+/**
+ * Why the sandbox cannot run, or null when it can: the runtime answers, its
+ * daemon runs Linux containers, and the image is there or can be pulled.
+ */
+export function sandboxUnavailable(spec) {
+    try {
+        const os = execFileSync(spec.runtime, ["info", "--format", "{{.OSType}}"], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 20_000,
+        })
+            .toString("utf8")
+            .trim();
+        if (os !== "" && os !== "linux")
+            return `${spec.runtime} runs ${os} containers; the sandbox needs Linux ones.`;
+    }
+    catch (error) {
+        return `${spec.runtime} does not answer (${firstLine(error)}): start it, or set CARVEOUT_CONTAINER to a runtime that takes Docker's arguments.`;
+    }
+    try {
+        execFileSync(spec.runtime, ["image", "inspect", spec.image], { stdio: "ignore", timeout: 20_000 });
+    }
+    catch {
+        try {
+            execFileSync(spec.runtime, ["pull", "--quiet", spec.image], { stdio: "ignore", timeout: 10 * 60_000 });
+        }
+        catch (error) {
+            return `${spec.runtime} has no image ${spec.image} and could not pull it (${firstLine(error)}): pull it, or name another with --sandbox-image or CARVEOUT_SANDBOX_IMAGE.`;
+        }
+    }
+    return null;
+}
+const firstLine = (error) => (error instanceof Error ? (error.stderr?.toString("utf8") || error.message) : String(error)).trim().split("\n")[0] ?? "";
+/** Where a directory under the mounted one is inside the container. */
+export const MOUNT = "/work";
+/**
+ * Runs one command in a fresh container that mounts `root` at `/work` and
+ * nothing else, in `cwd` (a directory under `root`). Host paths under
+ * `root` in the arguments are rewritten to the container's, and this Node's
+ * own path to `node`. Only the names in `env` are passed, with HOME and the
+ * npm cache in the container's own /tmp. With `network` false the container
+ * has none. At `limitMs` the container is killed.
+ */
+export function sandboxRun(spec, root, command, options) {
+    const base = resolve(root);
+    const inside = (path) => {
+        const at = relative(base, resolve(path));
+        if (at === "")
+            return MOUNT;
+        if (at.startsWith("..") || at.startsWith(sep))
+            throw new Error(`${path} is outside the sandbox's folder ${base}.`);
+        return `${MOUNT}/${at.split(sep).join("/")}`;
+    };
+    const mapArgument = (value) => {
+        if (value === process.execPath)
+            return "node";
+        return value.split(base).join(MOUNT);
+    };
+    const [executable = "true", ...args] = command;
+    const name = `carveout-${randomBytes(6).toString("hex")}`;
+    const env = {};
+    for (const [key, value] of Object.entries(options.env ?? {}))
+        if (key !== "PATH" && key !== "HOME" && key !== "SystemRoot" && !key.startsWith("npm_config_"))
+            env[key] = value;
+    const runArgs = [
+        "run",
+        "--rm",
+        "--name",
+        name,
+        "--init",
+        ...(options.network ? [] : ["--network", "none"]),
+        ...(typeof process.getuid === "function" && typeof process.getgid === "function" ? ["--user", `${process.getuid()}:${process.getgid()}`] : []),
+        "--cap-drop",
+        "ALL",
+        "--security-opt",
+        "no-new-privileges",
+        "--read-only",
+        "--tmpfs",
+        "/tmp:rw,exec,size=2g",
+        "--memory",
+        process.env["CARVEOUT_SANDBOX_MEMORY"] ?? "4g",
+        "--pids-limit",
+        "2048",
+        "--volume",
+        `${base}:${MOUNT}`,
+        "--workdir",
+        inside(options.cwd ?? base),
+        "--env",
+        "HOME=/tmp",
+        "--env",
+        "npm_config_cache=/tmp/.npm",
+        "--env",
+        "npm_config_update_notifier=false",
+        "--env",
+        "CI=1",
+        ...Object.entries(env).flatMap(([key, value]) => ["--env", `${key}=${mapArgument(value)}`]),
+        spec.image,
+        mapArgument(executable),
+        ...args.map(mapArgument),
+    ];
+    return new Promise((resolvePromise) => {
+        const child = spawn(spec.runtime, runArgs, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.setEncoding("utf8").on("data", (chunk) => (stdout += chunk));
+        child.stderr.setEncoding("utf8").on("data", (chunk) => (stderr += chunk));
+        const timer = setTimeout(() => {
+            try {
+                execFileSync(spec.runtime, ["kill", name], { stdio: "ignore", timeout: 30_000 });
+            }
+            catch {
+                // Already gone.
+            }
+            child.kill("SIGKILL");
+        }, options.limitMs ?? 10 * 60_000);
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            resolvePromise({ stdout, stderr: `${stderr}${error.message}`, status: null });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolvePromise({ stdout, stderr, status: code });
+        });
+    });
+}

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

@@ -0,0 +1,75 @@
+/**
+ * The request a cut is made from, and the JSON form every record is
+ * written in, so two cuts of the same bytes give the same files.
+ */
+export declare const SLICE_TOOL_VERSION = "carveout-slice@2";
+export interface SliceBudget {
+    /** Files inside the slice; the first file past it on any path is a cut. */
+    readonly maxFiles: number;
+    /** Edges from the nearest entry point; a file further away is a cut. */
+    readonly maxDepth: number;
+}
+export declare const SLICE_BUDGET_DEFAULTS: SliceBudget;
+export interface SliceParams {
+    /** Repository-relative file or directory paths, sorted and unique. */
+    readonly entryPoints: readonly string[];
+    readonly budget: SliceBudget;
+    /** Also bring along the tests outside the slice that import it. */
+    readonly tests: boolean;
+    /**
+     * The setup files the package's Vitest tests run before them (its
+     * config's `setupFiles`), walked from as the entry points are but no
+     * entry point: an edit to one is held as a test-runner setting's is.
+     */
+    readonly setupFiles?: readonly string[];
+    /**
+     * The runner the package's own tests run on, when it is Vitest: the
+     * folder installs it, pinned as the package pins it, for the tests the
+     * contributor writes, whether or not a test of the slice came along.
+     */
+    readonly testRunner?: "vitest";
+    /**
+     * Service packages kept real rather than mocked: installed and typed as
+     * the repository has them, with the environment their importers read
+     * left to the shell. Absent when none.
+     */
+    readonly live?: readonly string[];
+    /**
+     * Include every file of the entry points' package the walk reaches, at
+     * any depth: the cut falls at package and service boundaries only, so a
+     * sibling module is copied rather than stubbed. Absent when off.
+     */
+    readonly wholePackage?: boolean;
+    /**
+     * Follow an import of one of the repository's own packages into its
+     * source, as an import of a file is followed, rather than stubbing the
+     * package at the seam. Absent when off.
+     */
+    readonly followWorkspaces?: boolean;
+    /**
+     * Copy pure code the slice runs (validators, error classes, formatters)
+     * rather than mock it, past the depth; see `ReachOptions.pure`. Absent
+     * when off.
+     */
+    readonly copyPure?: boolean;
+    /**
+     * Files never copied, as paths or globs from the repository's root:
+     * wherever the walk reaches one it is cut and stubbed, with its literal
+     * values widened. Absent when none.
+     */
+    readonly private?: readonly string[];
+    /**
+     * Folders (or files) copied in whole beside the slice, as paths from the
+     * repository's root: what the code reads by a name the walk cannot
+     * follow, such as a migrations folder. A path read into one is no
+     * blocker. Absent when none.
+     */
+    readonly copy?: readonly string[];
+}
+/**
+ * Whether a repository path matches one of `patterns`: the path itself,
+ * anything under it as a folder, or a glob (`*` within one segment, `**`
+ * across segments). Pure, so a slice's record can say what was kept out.
+ */
+export declare function pathMatcher(patterns: readonly string[]): (path: string) => boolean;
+export declare function canonicalJson(value: unknown): string;

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

@@ -0,0 +1,51 @@
+/**
+ * What a slice reaches outside the repository: the service SDKs and HTTP
+ * clients its files import, and the environment variables they read. Listed
+ * by name so the sandbox phase knows what to mock; values are never read.
+ *
+ * A fixed table over import specifiers plus a regex pass over the text, so
+ * the result is the same for the same bytes. The regexes are deliberately
+ * simple: a false positive costs one spurious line in a list a person reads;
+ * a parser per language would cost a dependency per language.
+ */
+export interface ExternalServiceRule {
+    /** A neutral name for the service family: `aws`, `postgres`, `http`. */
+    readonly service: string;
+    /** Exact specifiers, or a scope prefix ending in `/*`. */
+    readonly specifiers: readonly string[];
+}
+export declare const EXTERNAL_SERVICE_RULES: readonly ExternalServiceRule[];
+export interface ExternalPackage {
+    readonly specifier: string;
+    readonly service: string;
+    /** Included files importing it, sorted. */
+    readonly files: readonly string[];
+}
+export interface EnvironmentRead {
+    readonly name: string;
+    readonly files: readonly string[];
+}
+export interface SliceExternals {
+    readonly packages: readonly ExternalPackage[];
+    readonly environment: readonly EnvironmentRead[];
+}
+export interface ExternalsInput {
+    readonly path: string;
+    readonly text: string;
+}
+/** The service a specifier belongs to, or null when the table has none. */
+export declare function serviceOf(specifier: string): string | null;
+export declare function detectExternals(files: readonly ExternalsInput[]): SliceExternals;
+/** Node's modules pure code may import: no disk, network or process. */
+export declare const PURE_NODE_MODULES: ReadonlySet<string>;
+/**
+ * What makes a module pure for `ReachOptions.pure`: it imports no service
+ * package and none of Node's modules that reach the disk, the network or
+ * the process, and its own text reads no environment and calls no
+ * network. Read from the text, so a false "impure" costs only a mock, as
+ * before; `read` gives a file's text, or null when it cannot be read.
+ */
+export declare function purityRules(read: (file: string) => string | null, isBuiltin: (specifier: string) => boolean): {
+    readonly package: (specifier: string) => boolean;
+    readonly sideEffects: (file: string) => boolean;
+};

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

@@ -0,0 +1,69 @@
+/**
+ * The import graph of a checkout, as the slice walk reads it.
+ *
+ * Node ids: `file:<path>` for a file of the checkout, and
+ * `dependency:<path>:<specifier>` for an import from `<path>` that resolves
+ * to no file of it (a package, a path that misses, a computed name). A
+ * node's `sourceFile` is the repository path it was read from.
+ *
+ * Each link is one import, re-export or reference as the source wrote it,
+ * with the names it takes, so the walk can follow a barrel only to the
+ * modules that supply those names, and pass over an import of types.
+ */
+export type SliceNodeKind = "file" | "dependency";
+/** The names a file declares and exports itself, read from its syntax. */
+export interface FileExports {
+    /** Names that exist at runtime, `default` among them. */
+    readonly values: readonly string[];
+    /** Interfaces and type aliases, which the compiler erases. */
+    readonly types: readonly string[];
+}
+export interface SliceGraphNode {
+    readonly id: string;
+    readonly kind: SliceNodeKind;
+    readonly label: string;
+    /** Repository-relative path, `/`-separated. */
+    readonly sourceFile: string;
+    /** Only on `dependency` nodes: a package, an import nothing resolved, or
+     * a literal path read at runtime that is no file a slice can copy. */
+    readonly dependencyStatus: "external" | "unresolved" | "path" | null;
+    /** On a script's `file` node: its own exports; null when not known
+     * (`export =`, or a file that is not a script). */
+    readonly exports: FileExports | null;
+}
+/**
+ * - `imports`: an import, re-export, `require` or `import()` of a literal.
+ * - `references`: a module named to a test runner or a resolver
+ *   (`vi.mock`, `jest.requireActual`, `require.resolve`), which needs the
+ *   module to exist but never loads its code into the slice.
+ * - `reads`: a file read by a literal path at runtime
+ *   (`new URL("./x", import.meta.url)`, `join(__dirname, "x")`), which needs
+ *   the file itself at that path.
+ */
+export type SliceRelation = "imports" | "references" | "reads";
+export interface SliceGraphLink {
+    readonly source: string;
+    readonly target: string;
+    readonly relation: SliceRelation;
+    /** The text as written, for an import or a reference; null otherwise. */
+    readonly specifier: string | null;
+    /** `L<n>`, the line it is on. */
+    readonly location: string | null;
+    /** `import type`, `export type`, `import("x").T`: erased at runtime. */
+    readonly typeOnly: boolean;
+    /** The names it takes, or null for the whole module. */
+    readonly names: readonly string[] | null;
+    /**
+     * For `export ... from`, what it forwards as [name in the module, name
+     * exported]: `*` for `export *`, `["*", "ns"]` for `export * as ns`.
+     * Null for anything else.
+     */
+    readonly forwards: readonly (readonly [string, string])[] | "*" | null;
+}
+export interface SliceGraph {
+    readonly nodes: readonly SliceGraphNode[];
+    readonly links: readonly SliceGraphLink[];
+}
+export declare function nodeKind(id: string): SliceNodeKind | null;
+/** The file a node belongs to; a dependency placeholder belongs to none. */
+export declare function fileOf(node: SliceGraphNode): string | null;

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

@@ -0,0 +1,262 @@
+/**
+ * What a slice run writes, and the rules that read it.
+ *
+ * `slice-manifest.json` is the immutable record of a proposed slice: the
+ * source it was cut from, the copied files pinned by hash, the generated
+ * files kept apart from them, the cut edges, the externals and whatever
+ * blocks the slice from becoming a sandbox. `boundary-contract.json` is the
+ * machine-readable shape of the boundary: the symbols the slice imports from
+ * outside (stubs) and the symbols outside code imports from it (its public
+ * surface), with their declarations. The markdown views are rendered from
+ * the contract and never carry anything it does not.
+ */
+import type { SliceBudget, SliceParams } from "./analysis.js";
+import type { SliceExternals } from "./externals.js";
+import type { CutEdge } from "./reach.js";
+export declare const SLICE_MANIFEST_SCHEMA_VERSION = 1;
+export declare const BOUNDARY_CONTRACT_SCHEMA_VERSION = 1;
+/**
+ * How much of the boundary carries declarations. `full` means every cut
+ * and public symbol has one and the fixture compiled; it says nothing about
+ * runtime readiness. `partial` and `names-only` are diagnostic output.
+ */
+export type StubCoverage = "full" | "partial" | "names-only";
+export declare const SLICE_BLOCKER_CODES: readonly ["unknown_entry_point", "unresolved_import", "dynamic_dependency", "path_read", "missing_build_input", "no_extractor", "declaration_incomplete", "compile_error", "secret_file"];
+export type SliceBlockerCode = (typeof SLICE_BLOCKER_CODES)[number];
+/**
+ * The blockers a contributor meets in the code itself: an import that
+ * resolves to no file, a dynamic import of a computed name, a path read at
+ * runtime the folder will not have. Every other
+ * code is the slicer's own build falling short (a compile error in its
+ * fixture, a configuration it could not read, a language it cannot
+ * extract), which says how well the code was measured, not how hard the
+ * work is, and one cause can raise dozens of them.
+ */
+export declare const WORK_BLOCKER_CODES: readonly SliceBlockerCode[];
+export declare const isWorkBlocker: (blocker: Pick<SliceBlocker, "code">) => boolean;
+export interface SliceBlocker {
+    readonly code: SliceBlockerCode;
+    readonly file: string | null;
+    readonly location: string | null;
+    readonly detail: string;
+}
+export interface BoundarySymbol {
+    readonly name: string;
+    /** `function`, `class`, `interface`, `type`, `enum`, `variable`, `module`, `unknown`. */
+    readonly kind: string;
+    /** Declaration text, `.d.ts` style; null when the language has no extractor. */
+    readonly declaration: string | null;
+}
+export interface BoundaryModule {
+    /** Repository path of the module. */
+    readonly module: string;
+    readonly symbols: readonly BoundarySymbol[];
+    /** Files on the other side of the cut that import it, sorted. */
+    readonly importedBy: readonly string[];
+    /** For an outbound module: the generated stub's artifact path. */
+    readonly stubPath: string | null;
+}
+export interface CompilationResult {
+    readonly attempted: boolean;
+    readonly ok: boolean;
+    readonly diagnostics: readonly {
+        readonly file: string | null;
+        readonly line: number | null;
+        readonly code: string;
+        readonly message: string;
+    }[];
+    /** Package specifiers declared `any` so the fixture could type-check. */
+    readonly shimmedPackages: readonly string[];
+    /**
+     * Errors the source has too, checked the same way with its own code in
+     * place of the stubs: what declaring its packages untyped costs, not
+     * counted against the slice. Absent when nothing failed.
+     */
+    readonly untypedPackageErrors?: CompilationResult["diagnostics"];
+    /**
+     * Packages whose published types the check read, at the versions read,
+     * rather than declaring them untyped. Absent when none were fetched.
+     */
+    readonly typedPackages?: readonly {
+        readonly name: string;
+        readonly version: string;
+    }[];
+}
+export interface BoundaryContract {
+    readonly schemaVersion: typeof BOUNDARY_CONTRACT_SCHEMA_VERSION;
+    readonly toolVersion: string;
+    readonly extractorVersion: string | null;
+    /** The commit the source was read at; null outside Git. */
+    readonly sourceCommitSha: string | null;
+    readonly language: "typescript" | "none";
+    /** Slice → outside: what the slice needs, as stubs. */
+    readonly outbound: readonly BoundaryModule[];
+    /** Outside → slice: what the slice must keep offering. */
+    readonly inbound: readonly BoundaryModule[];
+    readonly stubCoverage: StubCoverage;
+    readonly compilation: CompilationResult;
+    readonly blockers: readonly SliceBlocker[];
+}
+export interface IncludedFile {
+    readonly path: string;
+    /** Git's blob id of the bytes read, so the sandbox can verify its copy. */
+    readonly blobId: string;
+    readonly sha256: string;
+    /** `100644` or `100755`, as Git records it. */
+    readonly mode: string;
+    readonly sizeBytes: number;
+    readonly operations: readonly "edit"[];
+}
+export interface SyntheticFile {
+    readonly path: string;
+    readonly kind: "stub" | "shim" | "config";
+    readonly generator: string;
+    readonly generatorVersion: string;
+    readonly sha256: string;
+    readonly sizeBytes: number;
+}
+export interface RequiredBuildInputs {
+    /** Compiler and package configuration the included files are read with. */
+    readonly configs: readonly string[];
+    /** Packages the included files import, with the version the source pins. */
+    readonly packages: readonly {
+        readonly name: string;
+        readonly version: string | null;
+        readonly declaredIn: string | null;
+        /**
+         * One of the repository's own workspace packages: its source lives
+         * here, not on the registry, so it is mocked and never installed.
+         */
+        readonly workspace?: true;
+        /**
+         * Where the repository says it is fetched from; absent when nothing
+         * it holds says. Only a package shown to come from the public
+         * registry is installed by its name.
+         */
+        readonly registry?: PackageRegistry;
+    }[];
+}
+/**
+ * What a repository's lockfiles and npm configuration say of a package's
+ * registry. `public` is a lockfile entry resolved from the public registry
+ * with no configuration mapping its scope elsewhere; `private` is any
+ * lockfile entry or configuration that names another registry.
+ */
+export interface PackageRegistry {
+    readonly source: "public" | "private";
+    /** The file that says so, such as `package-lock.json` or `.npmrc`. */
+    readonly evidence: string;
+}
+/** Every operation a contribution may make on the slice has a stated rule. */
+export interface OperationPolicy {
+    readonly edit: "included-source-only";
+    readonly add: "requires-approved-path-mapping";
+    readonly delete: "requires-explicit-allowance";
+    readonly rename: "requires-explicit-allowance";
+    readonly synthetic: "rejected";
+    readonly unknown: "refused";
+}
+export declare const OPERATION_POLICY: OperationPolicy;
+export interface SliceMeta {
+    readonly includedFiles: number;
+    readonly includedBytes: number;
+    readonly outboundCuts: number;
+    readonly inboundCuts: number;
+    readonly stubCoverage: StubCoverage;
+    readonly externals: number;
+    readonly blockers: number;
+    readonly ready: boolean;
+}
+export interface SliceManifest {
+    readonly schemaVersion: typeof SLICE_MANIFEST_SCHEMA_VERSION;
+    readonly toolVersion: string;
+    readonly extractorVersion: string | null;
+    /** The commit the source was read at; null outside Git. */
+    readonly sourceCommitSha: string | null;
+    /** Whether any included file differed from that commit. */
+    readonly sourceDirty: boolean;
+    /** The import graph walked, as `canonicalJson` writes it. */
+    readonly graphSha256: string;
+    readonly params: SliceParams;
+    readonly entryPoints: readonly string[];
+    readonly budget: SliceBudget;
+    readonly included: readonly IncludedFile[];
+    readonly synthetic: readonly SyntheticFile[];
+    readonly requiredBuildInputs: RequiredBuildInputs;
+    readonly cuts: {
+        readonly outbound: readonly CutEdge[];
+        readonly inbound: readonly CutEdge[];
+    };
+    /** Import edges between included files, with their specifiers; see `reach`. */
+    readonly internalImports: readonly CutEdge[];
+    readonly externals: SliceExternals;
+    readonly blockers: readonly SliceBlocker[];
+    readonly policy: OperationPolicy;
+    readonly boundaryContractSha256: string;
+    readonly meta: SliceMeta;
+}
+/**
+ * Whether a slice may advance past diagnosis. Only full declaration
+ * coverage with no blockers may; the sandbox phase then proves the runtime.
+ */
+export declare function sliceReadiness(input: {
+    readonly stubCoverage: StubCoverage;
+    readonly blockers: readonly SliceBlocker[];
+}): {
+    ready: boolean;
+    reasons: string[];
+};
+/** The bounded view of a boundary a console renders without the files. */
+export interface SliceBoundarySummary {
+    readonly schemaVersion: 1;
+    readonly language: BoundaryContract["language"];
+    readonly stubCoverage: StubCoverage;
+    readonly ready: boolean;
+    readonly counts: {
+        readonly includedFiles: number;
+        readonly includedBytes: number;
+        readonly outboundModules: number;
+        readonly inboundModules: number;
+        readonly stubs: number;
+        readonly publicSymbols: number;
+        readonly externals: number;
+        readonly blockers: number;
+    };
+    readonly included: readonly string[];
+    readonly outbound: readonly SummaryModule[];
+    readonly inbound: readonly SummaryModule[];
+    readonly externals: {
+        readonly packages: readonly {
+            specifier: string;
+            service: string;
+        }[];
+        readonly environment: readonly string[];
+    };
+    readonly blockers: readonly SliceBlocker[];
+    /** Whether any list above was cut short. */
+    readonly truncated: boolean;
+}
+export interface SummaryModule {
+    readonly module: string;
+    readonly symbols: readonly string[];
+    readonly importedBy: readonly string[];
+    readonly truncated: boolean;
+}
+export declare const SUMMARY_LIMITS: {
+    readonly files: 200;
+    readonly modules: 100;
+    readonly symbols: 50;
+    readonly importers: 10;
+    readonly blockers: 50;
+    readonly externalPackages: 100;
+    readonly environment: 100;
+};
+export declare function boundarySummary(contract: BoundaryContract, manifest: Pick<SliceManifest, "included" | "externals" | "meta">): SliceBoundarySummary;
+/**
+ * `BOUNDARY.md`: an index of the boundary, rendered from the contract. What
+ * the slice holds is in the README and `carveout.json`; what each stub
+ * declares is in the stub.
+ */
+export declare function renderBoundaryMarkdown(contract: BoundaryContract, manifest: Pick<SliceManifest, "included" | "entryPoints" | "budget" | "externals" | "meta">): string;
+/** `public-surface.md`: only what a contribution must keep. */
+export declare function renderPublicSurfaceMarkdown(contract: BoundaryContract): string;

package/dist/src/slice/manifest.js

@@ -169,13 +169,14 @@ export function boundarySummary(contract, manifest) {
  * them; repeating them here cost a session an eighth of everything it read
  * (E6c: BOUNDARY.md opened in 60 of 60 slice runs).
  */
-function renderModules(modules, empty) {
+function renderModules(modules, empty, rest = "") {
     if (modules.length === 0)
         return [empty];
     return modules.map((module) => {
         const names = module.symbols.map((symbol) => symbol.name);
         const shown = names.slice(0, 12).map((name) => `\`${name}\``).join(", ");
-        const more = names.length > 12 ? `, +${names.length - 12} more` : "";
+        // Where every name of a long list is, rather than all of them here.
+        const more = names.length > 12 ? `, +${names.length - 12} more${rest}` : "";
         // The folder writes each stub beside the module's path, not where the
         // contract files it.
         const stub = module.stubPath === null
@@ -206,7 +207,7 @@ export function renderBoundaryMarkdown(contract, manifest) {
             lines.push(`- ${reason}`);
         lines.push("");
     }
-    lines.push("## Stubbed modules", "", "What the slice imports from outside, with the names it takes. Each stub's `.d.ts` declares them; the `.js` beside it is a recording mock.", "", ...renderModules(contract.outbound, "The slice imports nothing outside itself."), "", "## Public surface", "", "What outside code imports from the slice; a change must keep these exports to fit back.", "", ...renderModules(contract.inbound, "Nothing outside the slice imports it."), "", "## Externals to mock", "");
+    lines.push("## Stubbed modules", "", "What the slice imports from outside, with the names it takes. Each stub's `.d.ts` declares them; the `.js` beside it is a recording mock.", "", ...renderModules(contract.outbound, "The slice imports nothing outside itself.", " (the stub declares each)"), "", "## Public surface", "", "What outside code imports from the slice; a change must keep these exports to fit back.", "", ...renderModules(contract.inbound, "Nothing outside the slice imports it.", " (`carveout/surface/check.ts` holds each, a line apiece)"), "", "## Externals to mock", "");
     if (manifest.externals.packages.length === 0 &&
         manifest.externals.environment.length === 0)
         lines.push("No service SDKs or environment reads were detected.");