carveout 0.1.0 → 0.1.2

package/dist/src/project/build.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The local toolchain every carved-out project declares. Fixed per tool
+ * version so two cuts of one slice are byte-identical.
+ */
+export interface Toolchain {
+    /** `.nvmrc` content. */
+    readonly node: string;
+    /** `engines.node`. */
+    readonly nodeRange: string;
+    readonly npm: string;
+    readonly typescript: string;
+    readonly testRunner: "node:test";
+    readonly supportedPlatforms: readonly ("darwin" | "linux" | "win32")[];
+}
+export declare const SANDBOX_TOOLCHAIN: Toolchain;
+/** The commands a contributor runs, with or without the extension. */
+export declare const SANDBOX_COMMANDS: {
+    readonly install: "npm ci";
+    readonly dev: "npm run dev";
+    readonly build: "npm run build";
+    readonly test: "npm test";
+};
+export type SandboxCommand = keyof typeof SANDBOX_COMMANDS;

package/dist/src/project/catalog.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Version catalogs: a pin of `catalog:` or `catalog:<name>` names a version
+ * the workspace defines once, in pnpm's `pnpm-workspace.yaml` (`catalog:`
+ * and `catalogs:`) or in the root `package.json` (Bun's and pnpm's
+ * `workspaces.catalog(s)`, or top-level `catalog(s)`). npm knows no such
+ * protocol, so a slice's `package.json` takes the version the catalog
+ * gives, and its lockfile resolves (E8g: n8n's `catalog:typescript` stopped
+ * the install).
+ */
+type Catalogs = Map<string, Map<string, string>>;
+/**
+ * The `catalog:` and `catalogs:` maps of a `pnpm-workspace.yaml`: the
+ * block-style YAML pnpm writes, read line by line by indentation. Flow
+ * maps and anchors are not read; a catalog written so resolves nothing.
+ */
+export declare function parseWorkspaceCatalogs(text: string): Catalogs;
+/** The repository's catalogs, from every place a package manager keeps one. */
+export declare function workspaceCatalogs(repo: string): Catalogs;
+/**
+ * Resolves a pin through the catalogs: `catalog:` is the default catalog,
+ * `catalog:<name>` a named one. Any other pin, and a catalog entry that is
+ * not there, comes back as given (and a non-registry pin stays a blocker).
+ */
+export declare function catalogResolver(repo: string): (name: string, version: string) => string;
+export {};

package/dist/src/project/project.d.ts

@@ -0,0 +1,287 @@
+/**
+ * The standalone project a cut becomes, as a pure function of the slice,
+ * the copied source and the dependency resolution.
+ *
+ * Copied source keeps its repository structure. Everything generated lives
+ * apart from it under `carveout/` and is classified: declaration stubs
+ * beside runtime mocks for the modules the slice imports from outside,
+ * mock packages for the packages it does not install, the recording mock
+ * runtime and the ambient declarations the slice compiled against, an
+ * interface test for the surface outside code imports, and the
+ * configuration that makes `npm ci`, `npm run dev`, `npm run build` and
+ * `npm test` work on a clean machine with no credentials.
+ *
+ * An import the source makes through a compiler alias is rewritten to a
+ * relative path and recorded, so `carveout patch` can undo it; a bare
+ * specifier that neither a package nor a cut module explains is a blocker,
+ * never a guess. Bodies of copied source are never rewritten beyond those
+ * specifiers.
+ */
+import { type VitestSettings } from "./vitest-config.js";
+import type { BoundaryContract, BoundarySymbol, SliceManifest } from "../slice/manifest.js";
+import { type Toolchain } from "./build.js";
+import { type PathClass, type ResolvedDependency } from "./provenance.js";
+export declare const HARNESS_DIR = "carveout";
+export declare const MOCKS_DIR = "carveout/packages";
+/** Mocks of modules that are no package (`virtual:build-info`), with the loader's map of them. */
+export declare const VIRTUAL_DIR = "carveout/virtual";
+export declare const VIRTUAL_MAP_PATH = "carveout/virtual/map.json";
+export declare const TESTS_DIR = "carveout/tests";
+export declare const MOCK_RUNTIME_PATH = "carveout/mock.js";
+export declare const AMBIENT_PATH = "carveout/ambient.d.ts";
+export declare const RUN_PATH = "carveout/run.ts";
+export declare const TEST_RUNNER_PATH = "carveout/test.js";
+/** The public surface's declarations and their type check (`extract/surface.ts`). */
+export declare const SURFACE_DIR = "carveout/surface";
+export declare const SURFACE_CHECK_PATH = "carveout/surface/check.ts";
+export declare const SURFACE_CONFIG_PATH = "carveout/surface/tsconfig.json";
+/**
+ * The last test run, as TAP: node:test's, then a `not ok` line for each
+ * failing Vitest test and surface check, then `# carveout` lines with each
+ * runner's counts. What `check` reads the baseline and the counts from.
+ */
+export declare const LAST_RUN_PATH = "carveout/.last-run.tap";
+/**
+ * Folders a contributor's tools write at a folder's root: npm's cache kept
+ * in the folder (`npm ci --cache .npm-cache`), a coverage report, a build
+ * tool's cache. None is part of a change: a patch leaves them out, and
+ * nothing in them is built or run.
+ */
+export declare const TOOL_DIRS: readonly string[];
+/** The last run's counts, by runner, written by the runner after every test ran. */
+export declare const COUNTS_PATH = "carveout/.last-run.json";
+/** The last Vitest run's JSON report, which the runner reads into the TAP. */
+export declare const VITEST_REPORT_PATH = "carveout/.vitest.json";
+/** The tests that failed when the folder was first checked: they fail on the mocks. */
+export declare const BASELINE_PATH = "carveout/baseline.json";
+export declare const ENV_FILE = "carveout.env";
+export declare const ASSETS_LOADER_PATH = "carveout/assets.js";
+/**
+ * Files a script imports that are not code: copied with the slice, typed
+ * as untyped modules, and loaded at runtime as their own path.
+ */
+export declare const ASSET_EXTENSIONS: readonly string[];
+export declare function isAssetPath(path: string): boolean;
+/** Where a cut came from, as the README and package name say it. */
+export interface ProjectOrigin {
+    /** The repository folder's name; null for a public folder. */
+    readonly repository: string | null;
+    /** The project's package name. */
+    readonly name: string;
+}
+export interface ProjectSource {
+    /** The repository path. */
+    readonly originalPath: string;
+    /** The path in the project; the same as the repository's. */
+    readonly path: string;
+    readonly text: string;
+}
+export interface ProjectStub {
+    /** The cut module's repository path. */
+    readonly module: string;
+    /** The module's path in the project, with its source extension. */
+    readonly path: string;
+    /** The declaration stub's text. */
+    readonly text: string;
+}
+export interface ProjectInput {
+    readonly origin: ProjectOrigin;
+    readonly manifest: SliceManifest;
+    readonly contract: BoundaryContract;
+    readonly sources: readonly ProjectSource[];
+    readonly stubs: readonly ProjectStub[];
+    readonly dependencies: readonly ResolvedDependency[];
+    /** Bare specifiers that need no rewrite: Node's modules and packages. */
+    readonly knownSpecifiers: readonly string[];
+    /** A safe subset of the source's compiler options, if they were read. */
+    readonly compilerOptions?: Readonly<Record<string, unknown>>;
+    /** What the sources read of each package, declared as the slice's check declared it. */
+    readonly packageModules?: PackageModules;
+    readonly toolchain?: Toolchain;
+    /** The coverage the repository's package test holds its sources to. */
+    readonly coverage?: CoverageGate;
+    /** Keep the source's noImplicitAny: the slice compiled under it. */
+    readonly keepsImplicitAny?: boolean;
+    /** Where the stubs leave an implicit any; see `SliceAnalysis.implicitAnyFiles`. */
+    readonly implicitAnyFiles?: readonly string[];
+    /** The package's Vitest settings, for the folder's `vitest.config.mjs`; see `vitest-config.ts`. */
+    readonly vitest?: VitestSettings;
+    /** The runner the package's own tests run on, when it is Vitest: the folder is set up for it with no test of it carried. */
+    readonly testRunner?: "vitest";
+    /** The folder installs Node's own types instead of the fallback globals. */
+    readonly hasNodeTypes?: boolean;
+    /** Service packages kept real rather than mocked, sorted. */
+    readonly live?: readonly string[];
+    /**
+     * Of the environment the slice reads, the names the live packages'
+     * importers read: left out of `carveout.env`, so the shell's values or
+     * the code's own defaults apply.
+     */
+    readonly liveEnvironment?: readonly string[];
+    /** The public surface's declarations and type check, `carveout/surface/`. */
+    readonly surface?: readonly {
+        path: string;
+        text: string;
+    }[];
+}
+/**
+ * Coverage thresholds a package's `node --test` script sets, in percent,
+ * over the sources under `folder` (a package's root, "" for the root).
+ */
+export interface CoverageGate {
+    readonly folder: string;
+    readonly lines?: number;
+    readonly branches?: number;
+    readonly functions?: number;
+    /**
+     * The test sources the package's script runs, relative to `folder`
+     * (`test/*.test.ts` for `--test dist-test/test/*.test.js`): a test
+     * elsewhere never runs in the repository, and never covers anything.
+     */
+    readonly tests?: string;
+    /**
+     * The script also fails when a compiled source under `dir` (relative to
+     * `folder`, back at the sources) was loaded by no test, except the files
+     * named: `assert-all-covered <dir> <report> [exclude...]`.
+     */
+    readonly allCovered?: {
+        readonly dir: string;
+        readonly excluded: readonly string[];
+    };
+}
+/**
+ * The test sources a package's test script runs, relative to its folder,
+ * when it names them (`--test dist-test/test/*.test.js`, back at the
+ * sources: `test/*.test.ts`); undefined when it leaves them to the
+ * runner's defaults, which find a test anywhere.
+ */
+export declare function testsGlobOf(script: string): string | undefined;
+/** The thresholds a package's test script passes to `node --test`, if any. */
+export declare function coverageGateOf(folder: string, script: string): CoverageGate | null;
+export interface GeneratedFile {
+    readonly path: string;
+    readonly text: string;
+    readonly class: PathClass;
+    readonly public: boolean;
+}
+export interface ImportRewrite {
+    readonly file: string;
+    readonly from: string;
+    readonly to: string;
+}
+export interface ProjectBlocker {
+    readonly code: "import_unrewritable" | "language_unsupported" | "mock_unsupported" | "path_conflict" | "secret_found" | "test_runner_mocked" | "vocabulary_leaked";
+    readonly file: string | null;
+    readonly detail: string;
+}
+export interface GeneratedProject {
+    readonly files: readonly GeneratedFile[];
+    readonly importRewrites: readonly ImportRewrite[];
+    readonly tests: readonly string[];
+    readonly blockers: readonly ProjectBlocker[];
+}
+/**
+ * The runtime shape of a symbol. The extractor names most kinds; a
+ * re-export it could only follow by name arrives as `unknown`, and its
+ * declaration text says whether it is a type (`export type { X }`,
+ * `interface`, `type`) or a value. A symbol with neither a kind nor a
+ * declaration cannot be mocked.
+ */
+export declare function runtimeKindOf(symbol: BoundarySymbol): "value" | "type" | "enum" | "unknown";
+/**
+ * Whether `runtimeKindOf` read a symbol's kind off the import it is
+ * exported again from, which says nothing of what it is: a mock may export
+ * it (harmless for a type), a test must not assert it.
+ */
+export declare function guessedFromImport(symbol: BoundarySymbol): boolean;
+export declare function dirnameOf(path: string): string;
+/** `../lib/service.js` from `src/app.ts` to `lib/service.ts`. */
+export declare function relativeSpecifier(fromFile: string, toFile: string): string;
+/** The emitted JavaScript path of a TypeScript source path. */
+export declare function runtimePath(path: string): string;
+/** What `npm run dev` and `npm test` run once the project is built. */
+export declare const SANDBOX_RUN_ARGV: {
+    readonly dev: readonly ["node", "--env-file=carveout.env", "--import=./carveout/assets.js", string];
+    readonly test: readonly ["node", "--env-file=carveout.env", "--import=./carveout/assets.js", "--test", "carveout/tests/**/*.test.js"];
+};
+/** A carved-out project's `package.json` scripts. */
+export declare const SANDBOX_SCRIPTS: {
+    readonly build: "tsc -p tsconfig.json";
+    readonly dev: `npm run build && ${string}`;
+    readonly test: `npm run build && ${string}`;
+};
+/** `x.ts`, `x.tsx` and `x.js` → `x.d.ts`; `x.mts` → `x.d.mts`; `x.cts` → `x.d.cts`. */
+export declare function declarationPath(path: string): string;
+/** A TypeScript source the project compiles, as opposed to a declaration or an asset. */
+export declare function isScript(path: string): boolean;
+/** Members of a `declare enum` declaration, as `[name, value]` pairs. */
+export declare function enumMembers(declaration: string): {
+    name: string;
+    value: string | number;
+}[] | null;
+export declare const MOCK_RUNTIME_TYPES = "export interface RecordedCall {\n  readonly name: string;\n  readonly args: readonly unknown[];\n}\nexport function recordedCalls(): RecordedCall[];\nexport function resetMocks(): void;\nexport function mockImplementation(\n  path: string,\n  implementation: (...args: unknown[]) => unknown,\n): void;\nexport function fixture(\n  path: string,\n  implementation: (...args: any[]) => unknown,\n): void;\nexport function createMock(origin: string, name?: string): any;\n";
+/**
+ * Module declarations for the specifiers a slice reads names of, each
+ * exporting those names as values and types, as the worker writes them for
+ * the slice's own check. They take the place of the specifier's untyped
+ * shorthand, which only works as a value: `import type { X }` from it fails.
+ * An installed package's are patterns (`"zod*"`), so its own types win.
+ */
+export interface PackageModules {
+    readonly specifiers: readonly string[];
+    readonly text: string;
+}
+/**
+ * Node's own modules and globals, untyped: what `@types/node` gives code
+ * the ES libraries alone do not. The slice is type-checked against these
+ * and a generated project builds against them. Where the DOM library
+ * declares a global too, the library's declaration comes first and keeps
+ * its type; the clash is in a declaration file, which `skipLibCheck`
+ * leaves unchecked.
+ */
+export declare const NODE_GLOBAL_DECLARATIONS: readonly string[];
+export declare function ambientDeclarations(packages: readonly string[], modules?: PackageModules, installed?: ReadonlySet<string>, hasNodeTypes?: boolean): string;
+/**
+ * The compiler options a generated project builds with: the source's safe
+ * options carried over, the source's bundler resolution when it uses one,
+ * otherwise Node's ESM resolution, and no emitted declarations.
+ */
+export declare function projectCompilerOptions(options: Readonly<Record<string, unknown>> | undefined): Record<string, unknown>;
+/** `tsconfig.json` for a generated project. */
+export declare function tsconfigFor(options: Readonly<Record<string, unknown>> | undefined, types?: readonly string[], excluded?: readonly string[], 
+/** Module names TypeScript finds by path: the folder's virtual modules. */
+paths?: Readonly<Record<string, readonly string[]>>): string;
+/** The folder's build when the stubs leave implicit anys: tsc, with those not counted. */
+export declare const BUILD_SCRIPT_PATH = "carveout/build.js";
+/**
+ * `carveout/build.js`: runs the folder's tsc, holding the code to the
+ * repository's noImplicitAny but for the files where the cut found the
+ * stubs leave an implicit any (a callback passed to a mocked package has
+ * no parameter types to take): those errors are the stubs', and are not
+ * counted. Any other error, an implicit any elsewhere included, fails it.
+ */
+/**
+ * The implicit-any diagnostics, by code: TypeScript's 7xxx family but its
+ * other checks there (TS7027 unreachable code, TS7028 an unused label,
+ * TS7029 a switch case that falls through, TS7030 a path that returns
+ * nothing), which hold the code to the repository's rules and are never
+ * the stubs' doing. The source of a regular expression over the digits.
+ */
+export declare const IMPLICIT_ANY_CODE = "7(?!02[7-9]|030)\\d{3}";
+export declare function buildScript(waived: readonly string[]): string;
+export declare function scanNamedImports(sources: readonly ProjectSource[]): Map<string, Set<string>>;
+/**
+ * `npm test`: every test in the folder at the time it runs, so a test added
+ * after the cut runs too. Each goes to the runner it imports; Node runs the
+ * compiled `.js`, Vitest the source.
+ */
+export declare function testRunnerScript(coverage: CoverageGate | undefined, globals?: boolean, waived?: readonly string[], 
+/** The test files the package's Vitest runs (its config's include), as globs from the folder's root. */
+vitestInclude?: readonly string[], 
+/** The runner the package's own tests run on, when it is Vitest: a node:test file added runs nowhere there. */
+packageRunner?: "vitest"): string;
+/**
+ * Generates the project. Deterministic: the same inputs give the same
+ * files in the same order.
+ */
+export declare function generateProject(input: ProjectInput): GeneratedProject;