ambit-ts 0.1.0

package/dist/cli/main.js

@@ -0,0 +1,385 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { displayName, isEffectsContract } from "../core/index.js";
+import { analyze } from "./analyze.js";
+import { formatDiffGithub, formatDiffText, hasUnapprovedIncrease, runDiff } from "./diff.js";
+import { githubAnnotation, workspacePath } from "./github.js";
+/**
+ * Exit codes (plan step 9): distinguish "checked, no error-level violation"
+ * from "the check itself could not run" (DESIGN.md §3.4 — never turn an
+ * analysis failure into "no violations").
+ */
+const USAGE = `Usage: ambit check <dir> [--format json|github] [--coverage] [--strict]
+       ambit init  <dir> [--format json] [--config]   propose @effects for undeclared functions
+       ambit diff  <ref> [dir] [--format github]      report authority the working tree gained over <ref>
+`;
+const EXIT_OK = 0;
+const EXIT_VIOLATIONS = 1;
+const EXIT_ANALYSIS_FAILED = 2;
+/**
+ * `diff` shells out to git and writes a worktree, so the entry point's own
+ * contract is wider than `check`'s alone (DESIGN.md §6).
+ *
+ * @effects fs_read, fs_write, process
+ */
+export async function main(argv) {
+    const args = parseArgs(argv);
+    if (args.error) {
+        process.stderr.write(`ambit: ${args.error}\n${USAGE}`);
+        return EXIT_ANALYSIS_FAILED;
+    }
+    if (args.command === "diff")
+        return await diffCommand(args);
+    if (args.command !== "check" && args.command !== "init") {
+        process.stderr.write(`Unknown command: ${args.command}\n${USAGE}`);
+        return EXIT_ANALYSIS_FAILED;
+    }
+    let analysis;
+    try {
+        analysis = await analyze(args.dir, {
+            propose: args.command === "init",
+            proposeConfig: args.config,
+            strict: args.strict,
+        });
+    }
+    catch (error) {
+        process.stderr.write(`ambit: analysis failed: ${errorMessage(error)}\n`);
+        return EXIT_ANALYSIS_FAILED;
+    }
+    const { diagnostics, authority, coverage } = analysis;
+    for (const diagnostic of diagnostics) {
+        process.stdout.write(formatDiagnostic(diagnostic, args));
+    }
+    // The per-function authority records (DESIGN.md §5.1). Emitted after the
+    // diagnostics and before the trailing `summary` line, so a consumer that
+    // reads the last record as the summary keeps working, and only for `check`:
+    // `init` reports proposals about contracts that do not exist yet.
+    if (args.format === "json" && args.command === "check") {
+        for (const record of authority) {
+            process.stdout.write(`${JSON.stringify(record)}\n`);
+        }
+    }
+    // Always report what was analyzed — a silent, empty result must never
+    // read the same as "checked and found nothing" (DESIGN.md §3.4). The
+    // detailed unresolved-reason/name breakdown is opt-in via --coverage.
+    process.stdout.write(args.format === "json" ? formatSummaryJson(coverage) : formatSummaryText(coverage));
+    if (args.coverage) {
+        process.stdout.write(args.format === "json" ? formatCoverageJson(coverage) : formatCoverageText(coverage));
+    }
+    // `init` reports proposals, not violations: a codebase with contracts left
+    // to write has not failed a check, so it must not exit non-zero.
+    if (args.command === "init")
+        return EXIT_OK;
+    const hasError = diagnostics.some((d) => d.severity === "error");
+    return hasError ? EXIT_VIOLATIONS : EXIT_OK;
+}
+/**
+ * `ambit diff <ref>`: what authority the working tree gained over `ref`
+ * (DESIGN.md §6).
+ *
+ * @effects process, fs_read, fs_write
+ */
+async function diffCommand(args) {
+    let result;
+    try {
+        result = await runDiff(args.ref, args.dir);
+    }
+    catch (error) {
+        // Either side failing to analyze is exit 2, never 0: a comparison that
+        // could not be made must not read as "nothing increased" (DESIGN.md §3.4).
+        process.stderr.write(`ambit: diff failed: ${errorMessage(error)}\n`);
+        return EXIT_ANALYSIS_FAILED;
+    }
+    process.stdout.write(args.format === "github" ? formatDiffGithub(result) : formatDiffText(result));
+    // An increase with no approval in force fails (DESIGN.md §6.3). An increase
+    // carrying an approval added in this same comparison is reported and passes;
+    // so are a decrease and a deletion, because taking authority away is not the
+    // thing this command watches for, and failing on it would give an author a
+    // reason to leave a contract alone.
+    return hasUnapprovedIncrease(result) ? EXIT_VIOLATIONS : EXIT_OK;
+}
+const KNOWN_FLAGS = new Set(["--format", "--coverage", "--strict", "--config"]);
+function parseArgs(argv) {
+    const [command = "check", ...rest] = argv;
+    let dir = ".";
+    // `diff` takes the base ref first and the directory second; every other
+    // command's first positional is the directory.
+    let ref = "";
+    const positionals = [];
+    let format = "text";
+    let coverage = false;
+    let strict = false;
+    let config = false;
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === "--format") {
+            const value = rest[i + 1];
+            if (!isOutputFormat(value)) {
+                return {
+                    command,
+                    dir,
+                    ref,
+                    format,
+                    coverage,
+                    strict,
+                    config,
+                    error: `--format expects ${OUTPUT_FORMATS.map((f) => JSON.stringify(f)).join(", ")}, got ${value === undefined ? "nothing" : JSON.stringify(value)}`,
+                };
+            }
+            format = value;
+            i++;
+        }
+        else if (arg === "--coverage") {
+            coverage = true;
+        }
+        else if (arg === "--strict") {
+            strict = true;
+        }
+        else if (arg === "--config") {
+            config = true;
+        }
+        else if (arg?.startsWith("--")) {
+            if (!KNOWN_FLAGS.has(arg)) {
+                return {
+                    command,
+                    dir,
+                    ref,
+                    format,
+                    coverage,
+                    strict,
+                    config,
+                    error: `unknown option: ${arg}`,
+                };
+            }
+        }
+        else if (arg) {
+            positionals.push(arg);
+        }
+    }
+    if (command === "diff") {
+        const [first, second] = positionals;
+        if (first === undefined) {
+            return { command, dir, ref, format, coverage, strict, config, error: "diff expects a ref" };
+        }
+        ref = first;
+        if (second !== undefined)
+            dir = second;
+        // A flag `diff` does not act on is an error, not something to drop
+        // quietly: an author who wrote `--strict` and got a green diff would
+        // read it as "strict found nothing" (DESIGN.md §3.4, the same reason an
+        // unknown option exits 2 rather than running).
+        const inert = [
+            ...(coverage ? ["--coverage"] : []),
+            ...(strict ? ["--strict"] : []),
+            ...(config ? ["--config"] : []),
+            ...(format === "json" ? ['--format "json"'] : []),
+        ];
+        if (inert.length > 0) {
+            return {
+                command,
+                dir,
+                ref,
+                format,
+                coverage,
+                strict,
+                config,
+                error: `diff does not support ${inert.join(", ")} (diff takes --format text or github)`,
+            };
+        }
+    }
+    else {
+        const [first] = positionals;
+        if (first !== undefined)
+            dir = first;
+    }
+    return { command, dir, ref, format, coverage, strict, config };
+}
+/**
+ * `--format` values. `text` is for a human at a terminal, `json` is the NDJSON
+ * of DESIGN.md §5.1 for agents and tools, and `github` renders the same
+ * structured diagnostic as GitHub Actions workflow commands so a CI run
+ * annotates the offending lines — §6: "CI integrates via the exit code and
+ * the structured output. A dedicated CI plugin is not required".
+ */
+const OUTPUT_FORMATS = ["text", "json", "github"];
+function isOutputFormat(value) {
+    return OUTPUT_FORMATS.some((format) => format === value);
+}
+function formatDiagnostic(diagnostic, args) {
+    if (args.format === "json")
+        return formatJson(diagnostic);
+    if (args.format === "github")
+        return formatGithub(diagnostic, args.dir);
+    return formatText(diagnostic);
+}
+const GITHUB_COMMAND = {
+    error: "error",
+    warning: "warning",
+    info: "notice",
+};
+/**
+ * One GitHub Actions workflow command per diagnostic
+ * (`::error file=...,line=...::message`), which is what makes a failing check
+ * annotate the offending line in a pull request without installing anything —
+ * DESIGN.md §6's "A dedicated CI plugin is not required".
+ *
+ * The call path and the operation site are folded into the message with `%0A`
+ * so the annotation is self-sufficient: a reader on the diff sees every hop
+ * without opening the job log.
+ *
+ * `location.file` is relative to the directory that was checked, while an
+ * annotation is resolved from the workspace root, so the path is re-expressed
+ * relative to the working directory.
+ */
+function formatGithub(diagnostic, rootDir) {
+    const { location } = diagnostic;
+    return githubAnnotation({
+        severity: GITHUB_COMMAND[diagnostic.severity],
+        file: workspacePath(rootDir, location.file),
+        line: location.line,
+        col: location.col,
+        title: diagnostic.id,
+        body: [diagnostic.message, ...viaPath(diagnostic)],
+    });
+}
+function formatJson(diagnostic) {
+    return `${JSON.stringify(diagnostic)}\n`;
+}
+/**
+ * Human-readable form, rendered from the structured diagnostic (DESIGN.md §5:
+ * "Human-facing display is implemented as a rendering of the structured
+ * diagnostics").
+ *
+ * The header line reports the function that declared the contract, at its own
+ * `file:line`. `contract.via` — the call path from there to the function that
+ * carries what was observed — follows as one indented line per hop, each with
+ * its own `file:line`, so the middle of the path is readable without
+ * re-running the check with `--format json`.
+ */
+function formatText(diagnostic) {
+    const { severity, message, location } = diagnostic;
+    const header = `${severity}: ${message} (${location.file}:${location.line})\n`;
+    return (header +
+        viaPath(diagnostic)
+            .map((hop) => `  ${hop}\n`)
+            .join(""));
+}
+/**
+ * One entry per hop in `contract.via`, as `-> name (file:line)`.
+ *
+ * Empty when the diagnostic has no hops: the effect is performed in the
+ * reported function's own body, so there is no call path, and a path that does
+ * not exist is not synthesized (DESIGN.md §5.3 — the same rule that forbids
+ * fabricating a fix candidate).
+ */
+function viaPath(diagnostic) {
+    const contract = diagnostic.contract;
+    const via = contract?.via ?? [];
+    // The operation site is not a hop — it is where, inside the last function of
+    // the path, the effect is performed — so it is labelled rather than arrowed,
+    // and it appears for a direct diagnostic that has no path at all.
+    const operation = contract && isEffectsContract(contract) ? contract.operation : undefined;
+    return [
+        ...via.map((hop) => `-> ${displayName(hop.symbol)} (${hop.file}:${hop.line})`),
+        ...(operation
+            ? [`operation: ${operation.qualifiedName} (${operation.file}:${operation.line})`]
+            : []),
+    ];
+}
+function formatSummaryText(coverage) {
+    return `files=${coverage.filesAnalyzed} functions=${coverage.functionsExtracted} declared=${coverage.functionsDeclared}\n`;
+}
+function formatSummaryJson(coverage) {
+    return `${JSON.stringify({
+        kind: "summary",
+        filesAnalyzed: coverage.filesAnalyzed,
+        functionsExtracted: coverage.functionsExtracted,
+        functionsDeclared: coverage.functionsDeclared,
+    })}\n`;
+}
+function formatCoverageText(coverage) {
+    const unknownPct = (coverage.functionUnknownRate * 100).toFixed(1);
+    // Reported beside the unknown rate on purpose: a boundary leaves the
+    // unknown numerator without the body ever being checked, so reading one
+    // number without the other would show declaring boundaries as progress.
+    const boundaryPct = (coverage.functionBoundaryRate * 100).toFixed(1);
+    const lines = [
+        `declared-by: jsdoc=${coverage.functionsDeclaredByJsDoc} config=${coverage.functionsDeclaredByConfig}`,
+        `unknown-rate=${unknownPct}% (${Math.round(coverage.functionUnknownRate * coverage.functionsExtracted)}/${coverage.functionsExtracted} functions) boundary-rate=${boundaryPct}% (${coverage.functionsBoundary}/${coverage.functionsExtracted} functions)`,
+        `entrypoints=${coverage.functionsEntrypoint} (without-capabilities=${coverage.entrypointsWithoutCapabilities})`,
+        `skipped=${coverage.functionsSkipped} (${mapEntries(coverage.skippedByKind)})`,
+        `call-sites: total=${coverage.callSitesTotal} resolved=${coverage.callSitesResolved} stub=${coverage.callSitesStub} pure=${coverage.callSitesPure} mutation=${coverage.callSitesMutation} unresolved=${coverage.callSitesUnresolved}`,
+        `unresolved-by-reason: ${mapEntries(coverage.unresolvedByReason)}`,
+    ];
+    if (coverage.topUnresolvedNames.length > 0) {
+        lines.push(`top-unresolved-names: ${coverage.topUnresolvedNames.map((n) => `${n.name}=${n.count}`).join(", ")}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatCoverageJson(coverage) {
+    return `${JSON.stringify({
+        kind: "coverage",
+        functionsDeclaredByJsDoc: coverage.functionsDeclaredByJsDoc,
+        functionsDeclaredByConfig: coverage.functionsDeclaredByConfig,
+        functionUnknownRate: coverage.functionUnknownRate,
+        functionBoundaryRate: coverage.functionBoundaryRate,
+        functionsBoundary: coverage.functionsBoundary,
+        functionsEntrypoint: coverage.functionsEntrypoint,
+        entrypointsWithoutCapabilities: coverage.entrypointsWithoutCapabilities,
+        functionsSkipped: coverage.functionsSkipped,
+        skippedByKind: Object.fromEntries(coverage.skippedByKind),
+        callSitesTotal: coverage.callSitesTotal,
+        callSitesResolved: coverage.callSitesResolved,
+        callSitesStub: coverage.callSitesStub,
+        callSitesPure: coverage.callSitesPure,
+        callSitesMutation: coverage.callSitesMutation,
+        callSitesUnresolved: coverage.callSitesUnresolved,
+        unresolvedByReason: Object.fromEntries(coverage.unresolvedByReason),
+        topUnresolvedNames: coverage.topUnresolvedNames,
+    })}\n`;
+}
+function mapEntries(map) {
+    if (map.size === 0)
+        return "none";
+    return [...map.entries()].map(([k, v]) => `${k}=${v}`).join(", ");
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * True when this file is the process entry point (`node src/cli/main.ts ...`,
+ * or the installed `ambit` bin), false when a test or another module imports
+ * it.
+ *
+ * npm installs `bin` as a symlink (`node_modules/.bin/ambit ->
+ * ../ambit-ts/dist/cli/main.js`), and `process.argv[1]` is then the *symlink*
+ * path while `import.meta.url` is the resolved target — so comparing the two
+ * directly makes the installed CLI silently do nothing and exit 0, which reads
+ * exactly like "checked, no violations" (DESIGN.md §3.4 forbids that). The
+ * symlink is resolved before comparing. `pathToFileURL` (rather than a plain
+ * `file://` template) also handles a path containing spaces.
+ */
+function isProcessEntryPoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    let resolved;
+    try {
+        resolved = realpathSync(entry);
+    }
+    catch {
+        resolved = entry;
+    }
+    return import.meta.url === pathToFileURL(resolved).href;
+}
+if (isProcessEntryPoint()) {
+    main(process.argv.slice(2))
+        .then((code) => {
+        process.exitCode = code;
+    })
+        .catch((error) => {
+        process.stderr.write(`ambit: unexpected failure: ${errorMessage(error)}\n`);
+        process.exitCode = EXIT_ANALYSIS_FAILED;
+    });
+}

package/dist/cli/worktree.d.ts

@@ -0,0 +1,75 @@
+/** A base revision checked out on disk, plus the working tree it was taken from. */
+export interface BaseWorktree {
+    /** The temporary checkout's root. */
+    readonly root: string;
+    /** The repository root the ref was resolved against. */
+    readonly repoRoot: string;
+}
+/**
+ * Run `git` in `cwd` and return its stdout, trimmed.
+ *
+ * @effects process
+ */
+export declare function git(cwd: string, ...args: readonly string[]): Promise<string>;
+/**
+ * The same, untrimmed — for `-z` output, where the separator is a NUL and a
+ * trailing byte of a path is data rather than whitespace to be tidied away.
+ *
+ * @effects process
+ */
+export declare function gitRaw(cwd: string, ...args: readonly string[]): Promise<string>;
+/**
+ * The root of the repository containing `dir`.
+ *
+ * @effects process
+ */
+export declare function repositoryRoot(dir: string): Promise<string>;
+/**
+ * Check `ref` out into a temporary `git worktree` and hand the caller its
+ * root. The caller must call {@link removeWorktree}, whether or not its own
+ * work succeeded (DESIGN.md §6's `diff` entry).
+ *
+ * The checkout goes under the OS temporary directory, never inside the
+ * repository, so a run that is killed outright leaves nothing in the tree
+ * being analyzed.
+ *
+ * `node_modules` is symlinked in from the working tree when the working tree
+ * has one. Measured on this repository: without it the base side resolves 19
+ * more calls as unresolved and reports an `any-typed` reason the head side
+ * does not have, so the two sides would differ by their environment rather
+ * than by their contracts. A symlink is enough — nothing writes to it — and
+ * `git worktree` never tracks it.
+ *
+ * @effects process, fs_read, fs_write
+ */
+export declare function addWorktree(repoRoot: string, ref: string): Promise<BaseWorktree>;
+/**
+ * Remove a worktree {@link addWorktree} created, and the directory under it.
+ *
+ * Never throws: it runs in a `finally`, where an error would replace the
+ * failure the caller is already reporting. A `git worktree remove` that fails
+ * still leaves the administrative entry, so `prune` follows unconditionally
+ * and the directory is removed directly as the last resort.
+ *
+ * @effects process, fs_write
+ */
+export declare function removeWorktree(worktree: BaseWorktree): Promise<void>;
+/**
+ * The files git reports as renamed between `ref` and the working tree, base
+ * path to head path, each relative to `subdir` and separated by `"/"`.
+ *
+ * This is the only identity evidence `ambit diff` uses to carry a symbol
+ * across a move (DESIGN.md §6.3). Two properties of `git diff` shape what it
+ * can see, and both were measured rather than assumed:
+ *
+ * - The `-- <subdir>` pathspec restricts renames to the checked directory, and
+ *   a file renamed *into* it from outside comes out as an addition, not a
+ *   rename. That is the wanted reading: the checked directory did gain a
+ *   symbol, whatever the rest of the repository did.
+ * - Only tracked paths are compared, so a move whose destination has not been
+ *   `git add`ed reads as a deletion plus an untracked file — no rename. CI
+ *   always has a tracked tree; a local run may not.
+ *
+ * @effects process
+ */
+export declare function renamedFiles(repoRoot: string, ref: string, subdir: string): Promise<ReadonlyMap<string, string>>;

package/dist/cli/worktree.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { mkdtemp, rm, symlink } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+/**
+ * Run `git` in `cwd` and return its stdout, trimmed.
+ *
+ * @effects process
+ */
+export async function git(cwd, ...args) {
+    return (await gitRaw(cwd, ...args)).trim();
+}
+/**
+ * The same, untrimmed — for `-z` output, where the separator is a NUL and a
+ * trailing byte of a path is data rather than whitespace to be tidied away.
+ *
+ * @effects process
+ */
+export async function gitRaw(cwd, ...args) {
+    const { stdout } = await execFileAsync("git", [...args], { cwd, maxBuffer: 64 * 1024 * 1024 });
+    return stdout;
+}
+/**
+ * The root of the repository containing `dir`.
+ *
+ * @effects process
+ */
+export async function repositoryRoot(dir) {
+    return await git(dir, "rev-parse", "--show-toplevel");
+}
+/**
+ * Check `ref` out into a temporary `git worktree` and hand the caller its
+ * root. The caller must call {@link removeWorktree}, whether or not its own
+ * work succeeded (DESIGN.md §6's `diff` entry).
+ *
+ * The checkout goes under the OS temporary directory, never inside the
+ * repository, so a run that is killed outright leaves nothing in the tree
+ * being analyzed.
+ *
+ * `node_modules` is symlinked in from the working tree when the working tree
+ * has one. Measured on this repository: without it the base side resolves 19
+ * more calls as unresolved and reports an `any-typed` reason the head side
+ * does not have, so the two sides would differ by their environment rather
+ * than by their contracts. A symlink is enough — nothing writes to it — and
+ * `git worktree` never tracks it.
+ *
+ * @effects process, fs_read, fs_write
+ */
+export async function addWorktree(repoRoot, ref) {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ambit-diff-"));
+    try {
+        await git(repoRoot, "worktree", "add", "--detach", root, ref);
+    }
+    catch (error) {
+        // The checkout never happened, so there is no worktree to remove — only
+        // the empty temporary directory this function made.
+        await rm(root, { recursive: true, force: true });
+        throw error;
+    }
+    const installed = path.join(repoRoot, "node_modules");
+    if (existsSync(installed)) {
+        await symlink(installed, path.join(root, "node_modules"), "dir");
+    }
+    return { root, repoRoot };
+}
+/**
+ * Remove a worktree {@link addWorktree} created, and the directory under it.
+ *
+ * Never throws: it runs in a `finally`, where an error would replace the
+ * failure the caller is already reporting. A `git worktree remove` that fails
+ * still leaves the administrative entry, so `prune` follows unconditionally
+ * and the directory is removed directly as the last resort.
+ *
+ * @effects process, fs_write
+ */
+export async function removeWorktree(worktree) {
+    try {
+        await git(worktree.repoRoot, "worktree", "remove", "--force", worktree.root);
+    }
+    catch {
+        // fall through to the direct removal below
+    }
+    await rm(worktree.root, { recursive: true, force: true });
+    try {
+        await git(worktree.repoRoot, "worktree", "prune");
+    }
+    catch {
+        // Nothing left to do: the caller's own result is what matters here.
+    }
+}
+/**
+ * The files git reports as renamed between `ref` and the working tree, base
+ * path to head path, each relative to `subdir` and separated by `"/"`.
+ *
+ * This is the only identity evidence `ambit diff` uses to carry a symbol
+ * across a move (DESIGN.md §6.3). Two properties of `git diff` shape what it
+ * can see, and both were measured rather than assumed:
+ *
+ * - The `-- <subdir>` pathspec restricts renames to the checked directory, and
+ *   a file renamed *into* it from outside comes out as an addition, not a
+ *   rename. That is the wanted reading: the checked directory did gain a
+ *   symbol, whatever the rest of the repository did.
+ * - Only tracked paths are compared, so a move whose destination has not been
+ *   `git add`ed reads as a deletion plus an untracked file — no rename. CI
+ *   always has a tracked tree; a local run may not.
+ *
+ * @effects process
+ */
+export async function renamedFiles(repoRoot, ref, subdir) {
+    // `-z` rather than the default: a path is emitted raw between NULs, so a
+    // path containing a quote, a tab or a non-ASCII byte survives instead of
+    // arriving C-quoted.
+    const raw = await gitRaw(repoRoot, "diff", "--find-renames", "--name-status", "-z", ref, "--", subdir === "" ? "." : subdir);
+    const fields = raw.split("\0").filter((field) => field.length > 0);
+    const renames = new Map();
+    for (let i = 0; i < fields.length;) {
+        const status = fields[i] ?? "";
+        // A rename or copy record spans three fields (`R100`, old, new); every
+        // other status spans two.
+        if (status.startsWith("R") || status.startsWith("C")) {
+            const from = fields[i + 1];
+            const to = fields[i + 2];
+            if (from !== undefined && to !== undefined) {
+                const fromRelative = relativeToSubdir(from, subdir);
+                const toRelative = relativeToSubdir(to, subdir);
+                // Both ends inside the checked directory, or the pair says nothing
+                // about the comparison being made.
+                if (fromRelative !== undefined && toRelative !== undefined) {
+                    renames.set(fromRelative, toRelative);
+                }
+            }
+            i += 3;
+        }
+        else {
+            i += 2;
+        }
+    }
+    return renames;
+}
+/**
+ * A repository-relative path re-expressed relative to the checked directory —
+ * the form a symbol id carries (DESIGN.md §5.3) — or `undefined` when it is
+ * outside that directory.
+ */
+function relativeToSubdir(repoPath, subdir) {
+    if (subdir === "")
+        return repoPath;
+    if (!repoPath.startsWith(`${subdir}/`))
+        return undefined;
+    return repoPath.slice(subdir.length + 1);
+}

package/dist/config.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `ambit-ts/config` — the entry point a consumer's `ambit.config.ts` imports
+ * (DESIGN.md §4.1, "Out-of-code declarations").
+ *
+ * Deliberately separate from `ambit` (the diagnostic types) and from
+ * `ambit-ts/runtime`: a config file is loaded by the CLI at check time, and
+ * importing it must not drag the contract model, the runtime, or the checker
+ * into the consumer's build.
+ */
+export type { BudgetInput, OnExceed } from "./core/budget.ts";
+export type { AmbitConfig, ConfigContract } from "./core/config.ts";
+export { defineConfig } from "./core/config.ts";

package/dist/config.js

@@ -0,0 +1,10 @@
+/**
+ * `ambit-ts/config` — the entry point a consumer's `ambit.config.ts` imports
+ * (DESIGN.md §4.1, "Out-of-code declarations").
+ *
+ * Deliberately separate from `ambit` (the diagnostic types) and from
+ * `ambit-ts/runtime`: a config file is loaded by the CLI at check time, and
+ * importing it must not drag the contract model, the runtime, or the checker
+ * into the consumer's build.
+ */
+export { defineConfig } from "./core/config.js";