carveout 0.1.1 → 0.1.2

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

@@ -0,0 +1,180 @@
+import { type SurfaceFile } from "./surface.js";
+export { declarationPath as declarationPathFor, packageNameOf, } from "../core.js";
+export { loadConfig } from "./compiler-config.js";
+import type { BoundaryModule, CutEdge, SliceBlocker } from "../core.js";
+import ts from "typescript";
+export declare const TYPESCRIPT_EXTRACTOR_VERSION: string;
+export declare const ALL = "*";
+export type RequestedNames = ReadonlySet<string> | typeof ALL;
+export declare const STUB_CLOSURE_MAX = 500;
+/**
+ * Repository files one extraction may parse. The compiler runs on the
+ * event loop; a program the size of a monorepo would hold it past the
+ * heartbeat and lose the lease, so the slice stops with a blocker instead.
+ */
+export declare const PROGRAM_FILES_MAX = 2000;
+/** Modules Node provides; never a package the sandbox must install. */
+export declare const NODE_BUILTINS: readonly string[];
+export declare function isScriptPath(path: string): boolean;
+/**
+ * Files a script imports as data (`import data from "./data.json"`) or
+ * reads by path (a query, a schema, a template). They ride along in a
+ * TypeScript slice; code in any other language does not.
+ */
+export declare function isDataPath(path: string): boolean;
+export declare function isNodeBuiltin(specifier: string): boolean;
+/** The stub's artifact path for a module: `stubs/<path>.d.ts`. */
+export declare function stubPathFor(module: string): string;
+export interface ImportFact {
+    readonly specifier: string;
+    readonly names: RequestedNames;
+    readonly line: number;
+}
+/**
+ * The names read off a namespace binding (`ns.a`, `ns.T` in a type), or
+ * `ALL` once it escapes: passed or returned as a value, re-exported, read
+ * with a computed key, taken as `typeof ns`, or shadowed by another
+ * binding of the same name. Only a namespace that never escapes can be
+ * stubbed with less than the whole module.
+ */
+export declare function namespaceUses(nodes: readonly ts.Node[], name: string, binding: ts.Node): RequestedNames;
+/** Every import a file makes, with the names it takes, from the syntax. */
+export declare function importsOf(source: ts.SourceFile): ImportFact[];
+/** Where a snapshot's bare specifiers resolve, having no node_modules. */
+export interface ModuleFallbacks {
+    /** The repository path of one of its own packages; see `workspaceModuleResolver`. */
+    readonly workspaceModule?: (specifier: string) => string | null;
+    /** A directory whose node_modules holds fetched package types. */
+    readonly packageTypes?: string | null;
+}
+/**
+ * Resolves imports as the compiler does, then a bare specifier it cannot
+ * resolve as one of the repository's own packages, then from the fetched
+ * package types, as if imported beside their node_modules.
+ */
+export declare function resolveModulesWith(host: ts.CompilerHost, root: string, options: ts.CompilerOptions, fallbacks: ModuleFallbacks): void;
+/**
+ * A declaration file with the module specifiers `to` maps replaced, in
+ * imports, re-exports and `import("...")` types; the rest is left as is.
+ */
+export declare function rewriteModuleSpecifiers(text: string, to: (specifier: string) => string | null): string;
+/**
+ * A compiler host that reads only the source tree, the compiler's libs
+ * and the fetched package types.
+ */
+export declare function boundedHost(root: string, options: ts.CompilerOptions, fallbacks?: ModuleFallbacks): ts.CompilerHost;
+/** Options for declaration emit: the source's, with output settings forced. */
+export declare function extractionOptions(base: ts.CompilerOptions): ts.CompilerOptions;
+/**
+ * Options for a stub's declaration emit. A stub leaves the repository, so
+ * it carries no comments; the context builders, which stay private, keep
+ * them through `extractionOptions`. `@internal` declarations are emitted
+ * like any other, without their comments: the compiler's `stripInternal`
+ * would drop one the slice's code imports or a kept declaration names
+ * across the cut, and the stub would not declare what that code compiles
+ * against. `filterDeclaration` keeps only what is asked for and what that
+ * needs, so one nothing reaches is left out all the same.
+ */
+export declare function stubExtractionOptions(base: ts.CompilerOptions): ts.CompilerOptions;
+/**
+ * An emitted declaration file as a stub may show it. The emitter writes a
+ * literal constant's value (`declare const KEY = "sk_live_..."`, `static
+ * readonly KEY = "..."`), the literal types an `as const` value or an
+ * annotation spells it with, every comment it was not told to drop and
+ * each private member's name. A stub keeps each value's type with its
+ * literals widened to `string`, `number`, `bigint` or `boolean`, no
+ * comments, and private members only as one nameless brand, since no code
+ * outside the class can use them.
+ *
+ * A constant the file reads as a type (`(typeof PROVIDERS)[number]`, `kind:
+ * typeof KIND`) keeps its name-like string literals (`"github"`, `"draft"`):
+ * they are that type's members, and widened, the type would be `string` and
+ * the slice would stop checking the code that relies on it (a guard taken
+ * out compiles). Its other literals (numbers, URLs, keys, sentences) widen
+ * as any value's do.
+ *
+ * A string enum member's value becomes its own name: it stays a string
+ * enum, each member its own type, without the text it stood for. Numeric
+ * members keep their values, which an ambient enum needs for its members
+ * to be constant, and a number names nothing.
+ */
+export declare function sanitizeDeclaration(text: string, options?: {
+    readonly widenLiterals?: boolean;
+}): string;
+export interface FilteredDeclaration {
+    readonly text: string;
+    /** Requested names that no kept statement exports and no `export *` could. */
+    readonly missing: readonly string[];
+    /** Names forwarded to `export *` targets because nothing local declared them. */
+    readonly forwarded: readonly {
+        specifier: string;
+        names: RequestedNames;
+    }[];
+    /** Modules the kept declarations import from, with the names taken. */
+    readonly imports: readonly {
+        specifier: string;
+        names: RequestedNames;
+    }[];
+    readonly symbols: readonly {
+        name: string;
+        kind: string;
+        declaration: string;
+    }[];
+}
+/**
+ * Narrows an emitted declaration file to the requested exports and what
+ * they need. `ALL` keeps the file whole.
+ */
+export declare function filterDeclaration(text: string, requested: RequestedNames): FilteredDeclaration;
+export interface TypeScriptBoundary {
+    readonly extractorVersion: string;
+    readonly outbound: readonly BoundaryModule[];
+    readonly inbound: readonly BoundaryModule[];
+    /** Declaration files standing in for cut modules, by artifact path. */
+    readonly stubs: readonly {
+        path: string;
+        module: string;
+        text: string;
+    }[];
+    readonly blockers: readonly SliceBlocker[];
+    /** Configuration files the included files are read with, sorted. */
+    readonly configs: readonly string[];
+    /** Package specifiers imported by included files or kept stubs, with the files. */
+    readonly packages: ReadonlyMap<string, ReadonlySet<string>>;
+    /** The options the fixture compiles with. */
+    readonly compilerOptions: ts.CompilerOptions;
+    /**
+     * Imports of the repository's own packages, which resolve to their
+     * source: the cuts and internal imports they add, with specifiers, and
+     * each specifier's module.
+     */
+    readonly workspace: {
+        readonly outbound: readonly CutEdge[];
+        readonly internal: readonly CutEdge[];
+        readonly modules: ReadonlyMap<string, string>;
+    };
+    /**
+     * The public surface's declarations and the check `npm test` holds them
+     * to (`carveout/surface/`); empty when there is nothing to check.
+     */
+    readonly surface: readonly SurfaceFile[];
+}
+export interface TypeScriptBoundaryInput {
+    readonly root: string;
+    readonly included: readonly string[];
+    readonly outbound: readonly CutEdge[];
+    readonly inbound: readonly CutEdge[];
+    readonly texts: ReadonlyMap<string, string>;
+    /** Defaults to `PROGRAM_FILES_MAX`. */
+    readonly maxProgramFiles?: number;
+    /** The source of a repository package's specifier; see `workspaceModuleResolver`. */
+    readonly workspaceModule?: (specifier: string) => string | null;
+    /** A directory whose node_modules holds fetched package types. */
+    readonly packageTypes?: string | null;
+    /**
+     * Whether stubs widen literal values to their types, so no constant's
+     * value leaves the repository. Defaults to true.
+     */
+    readonly widenLiterals?: boolean;
+}
+export declare function extractTypeScriptBoundary(input: TypeScriptBoundaryInput): TypeScriptBoundary;

package/dist/src/gate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `carveout gate`: the hand-off policy on a change made in the repository
+ * itself, by an agent or anyone else, rather than on a folder that came
+ * back from outside.
+ *
+ * It reads the change from Git (the base commit against the working tree,
+ * untracked files included) and names what a change to code should not
+ * slip in unread: protected paths (CI, hooks, manifests, lockfiles,
+ * environment), deleted tests, tests whose assertions were removed or
+ * rewritten or that were skipped or focused with `.only`, edits to the
+ * configuration a check reads (tsconfig, linter, test runner), and new
+ * check suppressions (`@ts-ignore`, `eslint-disable`, coverage ignores).
+ * With `scope`, a file outside the paths the change was meant to touch is
+ * named too. A refusal is a question for a reviewer, not a verdict: a
+ * change asked to alter a behaviour rewrites the assertion that held it.
+ *
+ * Reads only: it runs no code of the repository.
+ */
+import { type Refusal } from "./policy.js";
+export type ChangeKind = "added" | "changed" | "deleted";
+export interface RepositoryChange {
+    readonly path: string;
+    readonly change: ChangeKind;
+}
+export interface Gate {
+    /** The checkout's root; every path is relative to it. */
+    readonly repo: string;
+    /** The base as given, and the commit it names. */
+    readonly base: string;
+    readonly baseCommit: string;
+    readonly changes: readonly RepositoryChange[];
+    readonly refused: readonly Refusal[];
+}
+/** The root of the Git checkout holding `dir`. */
+export declare function checkoutRoot(dir: string): string;
+/** The commit `base` names in `root`, or an error that says so. */
+export declare function baseCommitOf(root: string, base: string): string;
+/**
+ * What changed from `baseCommit` to the working tree: tracked files by
+ * `git diff` (a rename is a deletion and an addition), and untracked files
+ * Git does not ignore as added. Sorted by path.
+ */
+export declare function changesSince(root: string, baseCommit: string): RepositoryChange[];
+/** A file's text at `commit`, or null when it has none there. */
+export declare function textAt(root: string, commit: string, path: string): string | null;
+/** A file's text in the working tree, or null when it is not a file. */
+export declare function textNow(root: string, path: string): string | null;
+/** Judges the change from `base` (default `HEAD`) to the working tree. */
+export declare function gateRepository(options: {
+    readonly repo: string;
+    readonly base?: string;
+    readonly allow?: readonly string[];
+    /** Paths or globs the change was meant to stay within. */
+    readonly scope?: readonly string[];
+}): Gate;

package/dist/src/gate.js

@@ -98,6 +98,7 @@ export function gateRepository(options) {
     const changes = changesSince(root, baseCommit);
     const judge = handoffPolicy({
         checks: true,
+        integrity: true,
         testNoun: "a test",
         ...(options.allow === undefined ? {} : { allow: options.allow }),
     });

package/dist/src/graph.d.ts

@@ -0,0 +1,142 @@
+/**
+ * The import graph of a checkout, as the slice walk reads it.
+ *
+ * Every script file the checkout tracks becomes a `file:` node, with the
+ * names it exports itself. Each import, re-export and module reference the
+ * compiler resolves to a file in the checkout is a link to that file, with
+ * the names it takes and whether only types; each literal path a file reads
+ * at runtime is a `reads` link. Every other import (a package, a path that
+ * resolves to nothing, a dynamic import of a computed name) is a link to a
+ * `dependency:` node, which the walk reports rather than follows. Modules resolve with
+ * the nearest `tsconfig.json` (Node's resolution when there is none), and
+ * never through `node_modules`, so a workspace package is a bare specifier
+ * here, as it is in a snapshot without its installs. With
+ * `followWorkspaces`, an import of one of the repository's own packages is
+ * resolved to its source through the package's manifest and becomes a link
+ * to that file, so the walk copies or cuts it as it does any module.
+ *
+ * Nothing here runs repository code. The same files give the same graph.
+ */
+import ts from "typescript";
+import { type ReachOptions, type ReachResult, type SliceBudget, type SliceGraph, type SliceGraphLink, type SliceRelation } from "./core.js";
+/** Directories never read, whatever Git tracks. */
+export declare const IGNORED_DIRECTORIES: readonly string[];
+/** Files a graph reads before it stops; past it the checkout is too large. */
+export declare const GRAPH_FILES_MAX = 50000;
+/**
+ * The checkout's files, `/`-separated and sorted: what Git tracks plus
+ * untracked files it does not ignore, or every file outside Git.
+ */
+export declare function listFiles(root: string): string[];
+/**
+ * The checkout's files a Vite glob's patterns match, as the bundler reads
+ * them: relative to the importing file's folder, or to the root for a
+ * pattern starting with `/`; a `!` pattern excludes. Never node_modules.
+ */
+export declare function globMatches(root: string, directory: string, patterns: readonly string[]): string[];
+export interface BuiltGraph {
+    readonly graph: SliceGraph;
+    /** Script files read, sorted. */
+    readonly files: readonly string[];
+    /** Files whose `tsconfig.json` could not be read. */
+    readonly invalidConfigs: readonly string[];
+    /** Where the time went, in milliseconds: resolving is the compiler's
+     * configuration and module resolution, parsing the rest of the walk. */
+    readonly timings: {
+        readonly listMs: number;
+        readonly parseMs: number;
+        readonly resolveMs: number;
+    };
+}
+/** How the graph reads imports of the repository's own packages. */
+export interface GraphOptions {
+    /** Resolve a workspace package's import to its source file. */
+    readonly followWorkspaces?: boolean;
+    /** Files read as if the checkout had none (the owner's acceptance tests). */
+    readonly unseen?: readonly string[];
+}
+/** What `walkGraph` takes: the walk's options and the graph's. */
+export type WalkOptions = ReachOptions & GraphOptions;
+/** The graph of every script file of the checkout. */
+export declare function buildGraph(root: string, listed?: readonly string[], options?: GraphOptions): BuiltGraph;
+/**
+ * The graph a slice walk needs, read lazily: the entry points, every file
+ * the walk reaches, what those files name and what that re-exports (so a
+ * barrel and an import of types are judged from their targets), and every
+ * file that may import the slice. The walk on this graph gives what it
+ * gives on the whole checkout's graph, without parsing the rest of a large
+ * monorepo.
+ *
+ * Importers are found by text first and confirmed by the compiler: a file
+ * is read when it mentions an included file's name (its folder's, for an
+ * `index`), an alias with no wildcard that maps to it, `import.meta.glob`,
+ * or an import of folders alone (`.`, `..`, `../..`). A relative or wildcard-alias import spells
+ * the file's name or its folder's, and a workspace package's name is a
+ * package here, not a link, so no importer is missed for being unread.
+ */
+export declare function walkGraph(root: string, entryPoints: readonly string[], budget: SliceBudget, options?: WalkOptions): {
+    built: BuiltGraph;
+    walk: ReachResult;
+};
+/**
+ * The walk with the files that import the slice by a workspace package's
+ * name among its inbound cuts. Unfollowed, such an import is a package
+ * here, not a link, and the walk never sees it; but the package's other
+ * workspaces compile against the module its name resolves to, so a change
+ * to that module's exports breaks them. The public surface, the interface
+ * test and `status` read the inbound cuts, and must count them. The walk
+ * itself is unchanged: nothing is copied or cut for it.
+ */
+export declare function workspaceImportersOf(root: string): (walk: ReachResult, graph: SliceGraph) => ReachResult;
+/** A confirmed link from an importer to a file `importersOf` searched for. */
+export interface ImporterLink {
+    readonly from: string;
+    readonly to: string;
+    readonly specifier: string | null;
+    readonly relation: SliceRelation;
+    readonly typeOnly: boolean;
+    readonly forwards: SliceGraphLink["forwards"];
+}
+/**
+ * Every file that imports `targets`, directly or through other importers,
+ * up to `maxDepth` hops (unbounded by default): the reverse of the slice
+ * walk, read as lazily. Each hop finds candidates by text (a target's name,
+ * its folder's for an `index`, an exact alias, a workspace package's name,
+ * a folder-only import, `import.meta.glob`) and keeps those whose import
+ * the compiler resolves to a target. A target that no longer exists (a
+ * deleted module) is matched by resolving imports as if it still were.
+ * `references` (`vi.mock`) count: such a test runs against the module.
+ *
+ * It follows names, as the slice walk does: a barrel carries the change
+ * only through the names it forwards from a changed module, so a file that
+ * imports other names from the barrel is not reached. A file whose own code
+ * takes a name that carries the change is reached, and carries it on only
+ * through its exports whose declarations reach that name, by way of its
+ * other top-level declarations. Nothing here runs repository code.
+ */
+export declare function importersOf(root: string, targets: readonly string[], options?: {
+    readonly maxDepth?: number;
+    /** The names of each target that changed (`changedExports`); all by default. */
+    readonly seeds?: ReadonlyMap<string, ReadonlySet<string> | "*">;
+}): {
+    built: BuiltGraph;
+    /** Hops from the nearest target; the targets themselves at 0. */
+    depthOf: ReadonlyMap<string, number>;
+    links: readonly ImporterLink[];
+};
+/**
+ * The exports of a module whose declarations reach one of `locals`, through
+ * its other top-level declarations. Read by the identifiers each statement
+ * names, so a shadowing name counts too: it errs toward more.
+ */
+export declare function exportsReachingIn(source: ts.SourceFile, locals: ReadonlySet<string>): Set<string> | "*";
+/**
+ * The exports of a module that a change from `before` to `after` reaches:
+ * those whose own declaration changed, those that reach a changed
+ * declaration or import through the module's other declarations, and
+ * those added, removed or re-pointed by an export list or a re-export. A
+ * changed statement that declares nothing (code run at load, `export *`)
+ * reaches everything. Null `before` or `after`: an added or deleted module,
+ * all of it.
+ */
+export declare function changedExports(path: string, before: string | null, after: string | null): Set<string> | "*";

package/dist/src/graph.js

@@ -140,8 +140,9 @@ export function buildGraph(root, listed, options = {}) {
  */
 export function walkGraph(root, entryPoints, budget, options = {}) {
     const started = performance.now();
-    const files = listFiles(root);
-    const { followWorkspaces, ...rest } = options;
+    const { followWorkspaces, unseen, ...rest } = options;
+    const hidden = new Set(unseen ?? []);
+    const files = listFiles(root).filter((file) => !hidden.has(file));
     const graphOptions = followWorkspaces === undefined ? {} : { followWorkspaces };
     const builder = graphBuilder(root, files, performance.now() - started, graphOptions);
     const absoluteRoot = resolve(root);
@@ -150,7 +151,7 @@ export function walkGraph(root, entryPoints, budget, options = {}) {
         packageOf: rest.packageOf ?? packageFolder(absoluteRoot),
     };
     const scripts = files.filter((file) => SCRIPT.test(file));
-    const prefixes = entryPoints.map((entry) => entry.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, ""));
+    const prefixes = [...entryPoints, ...(options.roots ?? [])].map((entry) => entry.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, ""));
     builder.add(scripts.filter((file) => prefixes.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))));
     const aliases = exactAliases(absoluteRoot, files);
     // A workspace package is imported by its name, which spells neither the

package/dist/src/impact.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `carveout impact`: what a change made in the repository reaches, for the
+ * agent or person who made it, before the repository's CI says so.
+ *
+ * From the change (Git's base commit against the working tree, or the
+ * files named) it finds:
+ *
+ * - every file that imports a changed module, directly or through others,
+ *   by the same lazy, compiler-confirmed search the slice walk uses;
+ * - the exports of each changed module whose type changed or that are
+ *   gone, read by the TypeScript checker at the base and now, and which of
+ *   those importers take each one (through barrels too);
+ * - the tests among the importers, with their runner, and the commands
+ *   that run just them, package by package.
+ *
+ * The search, the type comparison and the test selection run no code of
+ * the repository; `runImpactTests` runs the commands, in the repository,
+ * with the caller's environment, as its own test script would.
+ *
+ * A type is compared as the checker prints it, one level of members deep:
+ * a change inside a named type another module declares shows on that
+ * module's own exports when it changed too, not on this one.
+ */
+import { type ChangeKind } from "./gate.js";
+export type ImpactRunner = "node" | "vitest" | "jest";
+export interface ImpactExport {
+    readonly file: string;
+    readonly name: string;
+    readonly change: "removed" | "changed";
+    /** The type as the checker prints it, one level of members deep. */
+    readonly before: string;
+    readonly after: string | null;
+    /** Files outside the change that take this export, sorted. */
+    readonly usedBy: readonly string[];
+}
+export interface ImpactTest {
+    readonly file: string;
+    /** Hops from the nearest changed module; 0 for a test the change edits. */
+    readonly depth: number;
+    readonly package: string;
+    /** Null: no runner carveout knows (mocha, ava, a custom script). */
+    readonly runner: ImpactRunner | null;
+}
+export interface ImpactCommand {
+    /** The package folder to run it in, from the checkout's root ("" the root). */
+    readonly cwd: string;
+    readonly runner: ImpactRunner | null;
+    readonly argv: readonly string[];
+    readonly tests: readonly string[];
+    /** Runs the package's whole test script, not only these tests. */
+    readonly whole: boolean;
+}
+export interface Impact {
+    readonly repo: string;
+    /** The base as given and its commit; null when files were named. */
+    readonly base: string | null;
+    readonly baseCommit: string | null;
+    /** The script files the change touches, with how. */
+    readonly changed: readonly {
+        readonly path: string;
+        readonly change: ChangeKind;
+    }[];
+    /** Files that import a changed module, with their hops from it, sorted. */
+    readonly importers: readonly {
+        readonly file: string;
+        readonly depth: number;
+    }[];
+    readonly exports: readonly ImpactExport[];
+    readonly tests: readonly ImpactTest[];
+    readonly commands: readonly ImpactCommand[];
+    /** Changed modules whose types could not be compared, with why. */
+    readonly unchecked: readonly {
+        readonly file: string;
+        readonly reason: string;
+    }[];
+    readonly timings: {
+        readonly graphMs: number;
+        readonly typesMs: number;
+    };
+}
+/**
+ * A test file's runner: the one it imports (`node:test`, `vitest`,
+ * `@jest/globals`), else the one its package (or the root) depends on
+ * when the file calls a runner's globals.
+ */
+export declare function impactRunnerResolver(root: string, packageOf: (file: string) => string): (file: string, specifiers: readonly string[]) => ImpactRunner | null;
+/** The commands that run `tests`, one per package and runner. */
+export declare function impactCommands(tests: readonly ImpactTest[]): ImpactCommand[];
+/** What the change from `base` (or the files named) reaches. */
+export declare function impactOf(options: {
+    readonly repo: string;
+    readonly base?: string;
+    /** Files to start from instead of the change since `base`. */
+    readonly files?: readonly string[];
+    /** Hops of importers to follow; unbounded by default. */
+    readonly maxDepth?: number;
+}): Impact;
+export interface ImpactRun {
+    readonly command: ImpactCommand;
+    readonly ok: boolean;
+    readonly exitCode: number | null;
+    /** The last lines of what it printed. */
+    readonly output: string;
+}
+/**
+ * Runs each command at its package's folder, one at a time, with the
+ * caller's environment: these are the repository's own tests, run where
+ * its test script would run them. `timeoutMs` bounds each.
+ */
+export declare function runImpactTests(root: string, commands: readonly ImpactCommand[], options?: {
+    readonly timeoutMs?: number;
+    readonly log?: (line: string) => void;
+}): ImpactRun[];

package/dist/src/imports.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Imports as the repository writes them. The cut rewrites a slice's
+ * imports to paths Node resolves inside the folder, and records each
+ * rewrite; `patch` turns them back. An import the folder's own edits added
+ * has no record, so it is restored by what it resolves to: the specifier
+ * the slice already uses for that target, else one the target's other
+ * importers use, else a relative path in the package's own style.
+ */
+import { type ImportRewrite } from "./core.js";
+/**
+ * `text` with the folder's import rewrites put back as the source wrote
+ * them. Two specifiers the cut rewrote to one (`@/lib/format` and
+ * `../../lib/format` both to `../../lib/format.js`) are told apart by
+ * `original`, the file as the cut read it: they come back in the order it
+ * wrote them. Without it, the last recorded wins. `path` tells the parser
+ * what kind of file the text is (`.tsx` reads JSX); a `.ts` without it.
+ */
+export declare function undoRewrites(text: string, rewrites: readonly ImportRewrite[], original?: string | null, path?: string): string;
+/** Every specifier a source writes, in source order. */
+export declare function specifiersOf(text: string, path?: string): Set<string>;
+/** How a package spells a relative import's extension. */
+export type ExtensionStyle = "none" | "js" | "ts";
+/** What a cut knows about the slice's imports, for restoring new ones. */
+export interface ImportContext {
+    /** Import edges the cut resolved, by importer, target and specifier. */
+    readonly edges: readonly {
+        from: string;
+        to: string;
+        specifier: string;
+    }[];
+    /** The folder's source files, by repository path: slice and new files. */
+    readonly files: ReadonlySet<string>;
+    /** Cut modules by repository path; their stubs sit beside them. */
+    readonly stubs: ReadonlySet<string>;
+    /** The repository's package folder holding a path, "" for the root. */
+    readonly packageOf: (path: string) => string;
+    /**
+     * How a package writes the extension of a relative import: none, the
+     * emitted `.js`, or the source's own `.ts` (Node's type stripping,
+     * `allowImportingTsExtensions`).
+     */
+    readonly extensionStyle: (pkg: string) => ExtensionStyle;
+}
+/** The folder file or cut module a relative specifier in `file` names. */
+export declare function importTarget(file: string, specifier: string, context: Pick<ImportContext, "files" | "stubs">): string | null;
+export interface RestoredImports {
+    readonly text: string;
+    /** Specifiers restored relative across packages: no spelling was known. */
+    readonly crossPackage: readonly string[];
+}
+/**
+ * A slice file's text with its imports as the repository writes them.
+ * `original` is the file as the cut read it (null for a new file): the
+ * specifiers it wrote are kept as they are.
+ */
+export declare function restoreImports(file: string, text: string, original: string | null, rewrites: readonly ImportRewrite[], context: ImportContext): RestoredImports;
+/** The nearest folder above `path` with a package.json in `repo`, "" for none. */
+export declare function packageFolder(repo: string, cache?: Map<string, string>): (path: string) => string;
+/**
+ * How each package writes relative imports, by the imports the cut read
+ * there: without an extension, with the emitted `.js`, or with the
+ * source's `.ts`. The most common style wins; `.js` on a tie or none.
+ */
+export declare function extensionStyles(edges: readonly {
+    from: string;
+    specifier: string;
+}[], packageOf: (path: string) => string): (pkg: string) => ExtensionStyle;