ambit-ts 0.1.0

package/dist/checker/summarize.js

@@ -0,0 +1,411 @@
+import { budgetFrom, capabilitySetsEqual, DEFAULT_ON_EXCEED, effectSetOf, effectSetsEqual, emptyEffectSet, formatBudget, formatCapability, isKnownEffect, KNOWN_EFFECTS, parseBudgetTag, parseCapabilitiesTag, parseCapability, } from "../core/index.js";
+import { isConstructorKey, isKnownPureConstructor, lookupConstructorEffect, } from "../stubs/constructors.js";
+import { lookupClientEffects } from "../stubs/data-clients.js";
+import { lookupHttpCapability } from "../stubs/http-capabilities.js";
+import { lookupStubEffect } from "../stubs/node-builtins.js";
+import { isKnownPureBuiltin } from "../stubs/pure-builtins.js";
+/**
+ * Turn a backend's raw extraction into Ambit's own analysis representation
+ * (DESIGN.md §3.4 layer 2), independent of which backend produced it.
+ */
+export function summarizeExtractedFiles(files, config) {
+    const aliases = config?.effectAliases;
+    const summaries = [];
+    for (const file of files) {
+        const specs = specContracts(file.runtimeWrappers);
+        for (const fn of file.functions) {
+            const jsDoc = {
+                declared: parseDeclaredEffects(fn.jsDoc, aliases),
+                capabilities: parseDeclaredCapabilities(fn.jsDoc),
+                budget: parseDeclaredBudget(fn.jsDoc),
+                boundary: parseDeclaredBoundary(fn.jsDoc),
+                entrypoint: fn.jsDoc?.tags.has("entrypoint") ?? false,
+            };
+            const declaredContract = config?.contractFor(fn.id);
+            const merged = mergeContract(jsDoc, declaredContract, specs.get(fn.id), aliases);
+            summaries.push({
+                id: fn.id,
+                location: fn.location,
+                tagLocations: fn.jsDoc?.tagLocations ?? new Map(),
+                declarationStart: fn.declarationStart,
+                ...(fn.jsDocRange ? { jsDocRange: fn.jsDocRange } : {}),
+                ...(fn.implicitConstructor ? { implicitConstructor: true } : {}),
+                ...(fn.configOnly ? { configOnly: true } : {}),
+                ...merged,
+                calls: fn.calls.map(toCall),
+            });
+        }
+    }
+    return summaries;
+}
+/**
+ * The declarations the registrations in one file make about the handlers they
+ * name (DESIGN.md §4.4).
+ *
+ * Only a registration whose `handler` is a declaration in this same file says
+ * anything here — one naming a handler from elsewhere has no summary to attach
+ * to, and stays `AMB-W004`'s business. A half the source does not fix as a
+ * literal is left out, so it is `AMB-W004` too rather than a declaration
+ * invented from a value nobody can read.
+ *
+ * The first registration naming a handler is the one that declares for it.
+ * A second one is not merged: whatever it says is compared against this one's
+ * declaration like any other spec, so a pair that disagrees is `AMB-E010` /
+ * `AMB-E011` rather than a silent last-write-wins.
+ */
+function specContracts(wrappers) {
+    const contracts = new Map();
+    for (const wrapper of wrappers) {
+        const handler = wrapper.handler;
+        if (handler === undefined || contracts.has(handler))
+            continue;
+        const capabilities = wrapper.capabilities ? capabilitySetOf(wrapper.capabilities) : undefined;
+        const budget = wrapper.budget?.kind === "literal" ? budgetFrom(wrapper.budget) : undefined;
+        contracts.set(handler, {
+            ...(capabilities ? { capabilities } : {}),
+            ...(budget ? { budget } : {}),
+        });
+    }
+    return contracts;
+}
+/**
+ * Combine a JSDoc contract with the one `ambit.config.ts` declares for the
+ * same symbol and the one the registration beside it fixes (DESIGN.md §4.1,
+ * §4.4).
+ *
+ * JSDoc wins per tag — a tag JSDoc declares is the one that propagates, and the
+ * other sides fill only the tags JSDoc left out, so `@effects` in the code plus
+ * `capabilities` in the spec is one complete contract rather than a conflict.
+ * Where JSDoc and config declare the *same* tag and the two parse to different
+ * values, the difference is recorded as a {@link ContractDivergence} and
+ * reported (`AMB-W005`) rather than resolved silently.
+ *
+ * A spec is the last side consulted, and needs no divergence record of its own:
+ * `diagnoseRuntimeWrappers` compares every literal spec against whatever this
+ * merge settled on, so a spec disagreeing with a JSDoc *or* a config
+ * declaration is still `AMB-E010` / `AMB-E011` — an error, not a warning. Only
+ * the case where no other side declared anything is silent, and there the two
+ * being compared are the same declaration.
+ *
+ * A JSDoc tag that failed to parse still counts as "JSDoc declared this":
+ * neither config nor a spec must quietly stand in for a tag the author wrote
+ * and misspelled, or `AMB-E002` would be reported against a contract that is
+ * not the one in force.
+ */
+function mergeContract(jsDoc, config, spec, aliases) {
+    const divergences = [];
+    const configEffects = config?.effects ? expandConfigEffects(config.effects, aliases) : undefined;
+    const configCapabilities = config?.capabilities
+        ? capabilitySetOf(config.capabilities)
+        : undefined;
+    const configBudget = config?.budget
+        ? { ...config.budget, onExceed: config.budget.onExceed ?? DEFAULT_ON_EXCEED }
+        : undefined;
+    let declared = jsDoc.declared;
+    let effectsBy = jsDoc.declared.kind === "declared" ? "jsdoc" : undefined;
+    if (configEffects) {
+        if (jsDoc.declared.kind === "none") {
+            declared = { kind: "declared", effects: configEffects };
+            effectsBy = "config";
+        }
+        else if (jsDoc.declared.kind === "declared" &&
+            !effectSetsEqual(jsDoc.declared.effects, configEffects)) {
+            divergences.push({
+                tag: "effects",
+                jsDoc: formatEffects(jsDoc.declared.effects.effects),
+                config: formatEffects(configEffects.effects),
+            });
+        }
+    }
+    let capabilities = jsDoc.capabilities;
+    let capabilitiesBy = jsDoc.capabilities.kind === "declared" ? "jsdoc" : undefined;
+    if (configCapabilities) {
+        if (jsDoc.capabilities.kind === "none") {
+            capabilities = { kind: "declared", capabilities: configCapabilities };
+            capabilitiesBy = "config";
+        }
+        else if (jsDoc.capabilities.kind === "declared" &&
+            !capabilitySetsEqual(jsDoc.capabilities.capabilities, configCapabilities)) {
+            divergences.push({
+                tag: "capabilities",
+                jsDoc: formatCapabilities(jsDoc.capabilities.capabilities),
+                config: formatCapabilities(configCapabilities),
+            });
+        }
+    }
+    if (spec?.capabilities && capabilities.kind === "none") {
+        capabilities = { kind: "declared", capabilities: spec.capabilities };
+        capabilitiesBy = "spec";
+    }
+    let budget = jsDoc.budget;
+    let budgetBy = jsDoc.budget.kind === "declared" ? "jsdoc" : undefined;
+    if (configBudget) {
+        if (jsDoc.budget.kind === "none") {
+            budget = { kind: "declared", budget: configBudget };
+            budgetBy = "config";
+        }
+        else if (jsDoc.budget.kind === "declared" &&
+            formatBudget(jsDoc.budget.budget) !== formatBudget(configBudget)) {
+            divergences.push({
+                tag: "budget",
+                jsDoc: formatBudget(jsDoc.budget.budget),
+                config: formatBudget(configBudget),
+            });
+        }
+    }
+    if (spec?.budget && budget.kind === "none") {
+        budget = { kind: "declared", budget: spec.budget };
+        budgetBy = "spec";
+    }
+    const declaredBy = {
+        ...(effectsBy ? { effects: effectsBy } : {}),
+        ...(capabilitiesBy ? { capabilities: capabilitiesBy } : {}),
+        ...(budgetBy ? { budget: budgetBy } : {}),
+    };
+    let boundary = jsDoc.boundary;
+    if (config?.boundary !== undefined) {
+        if (jsDoc.boundary.kind === "none") {
+            boundary = { kind: "declared", reason: config.boundary };
+        }
+        else if (jsDoc.boundary.kind === "declared" && jsDoc.boundary.reason !== config.boundary) {
+            divergences.push({
+                tag: "boundary",
+                jsDoc: jsDoc.boundary.reason,
+                config: config.boundary,
+            });
+        }
+    }
+    // No `@entrypoint` is not a declaration that the function is *not* one, so
+    // only an explicit `entrypoint: false` beside the tag is a disagreement.
+    let entrypoint = jsDoc.entrypoint;
+    if (config?.entrypoint !== undefined) {
+        if (!jsDoc.entrypoint && config.entrypoint)
+            entrypoint = true;
+        else if (jsDoc.entrypoint && !config.entrypoint) {
+            divergences.push({ tag: "entrypoint", jsDoc: "true", config: "false" });
+        }
+    }
+    return {
+        declared,
+        capabilities,
+        budget,
+        boundary,
+        entrypoint,
+        ...(Object.keys(declaredBy).length > 0 ? { declaredBy } : {}),
+        ...(divergences.length > 0 ? { divergences } : {}),
+    };
+}
+/**
+ * A config `effects` list turned into an {@link EffectSet}. Every name is
+ * either a standard effect or a user-defined one, which `validateConfig`
+ * already guaranteed — a user-defined name expands to the standard effects it
+ * stands for, and nothing but standard effects ever leaves this function
+ * (DESIGN.md §4.1 (d)).
+ */
+function expandConfigEffects(names, aliases) {
+    const effects = [];
+    for (const name of names) {
+        if (isKnownEffect(name))
+            effects.push(name);
+        else
+            effects.push(...(aliases?.get(name) ?? []));
+    }
+    return effectSetOf(...effects);
+}
+/**
+ * A list of capability strings — a config `capabilities` list, or a spec's
+ * literal array — turned into a {@link CapabilitySet}.
+ *
+ * A token that does not parse is dropped rather than guessed at. It is not
+ * lost: `validateConfig` rejects a malformed config token, and a malformed
+ * spec token leaves the set narrower than the text the spec wrote, which
+ * `diagnoseRuntimeWrappers` then reports as `AMB-E010` against that text.
+ */
+function capabilitySetOf(tokens) {
+    const capabilities = tokens
+        .map(parseCapability)
+        .filter((capability) => capability !== undefined);
+    return { capabilities, unknown: false };
+}
+function formatEffects(effects) {
+    const ordered = KNOWN_EFFECTS.filter((effect) => effects.has(effect));
+    return ordered.length === 0 ? "pure" : ordered.join(", ");
+}
+function formatCapabilities(set) {
+    return set.capabilities.map(formatCapability).join(", ");
+}
+function parseDeclaredEffects(jsDoc, aliases) {
+    const tagText = jsDoc?.tags.get("effects");
+    if (tagText === undefined)
+        return { kind: "none" };
+    const effects = parseEffectsTag(tagText, aliases);
+    if (effects === undefined)
+        return { kind: "invalid", raw: tagText };
+    return { kind: "declared", effects };
+}
+function parseDeclaredCapabilities(jsDoc) {
+    const tagText = jsDoc?.tags.get("capabilities");
+    if (tagText === undefined)
+        return { kind: "none" };
+    const capabilities = parseCapabilitiesTag(tagText);
+    if (capabilities === undefined)
+        return { kind: "invalid", raw: tagText };
+    return { kind: "declared", capabilities };
+}
+function parseDeclaredBudget(jsDoc) {
+    const tagText = jsDoc?.tags.get("budget");
+    if (tagText === undefined)
+        return { kind: "none" };
+    const budget = parseBudgetTag(tagText);
+    if (budget === undefined)
+        return { kind: "invalid", raw: tagText };
+    return { kind: "declared", budget };
+}
+/**
+ * `@boundary reason="..."`. DESIGN.md §4.6 makes `reason` mandatory, so a tag
+ * without one does not declare a boundary — it declares an unexplained hole,
+ * which is exactly what the tag exists to prevent. Both quoted and bare
+ * `reason=` forms are accepted; anything else is `"invalid"`.
+ */
+export function parseBoundaryTag(text) {
+    const match = /^reason\s*=\s*(?:"([^"]*)"|'([^']*)'|(\S+))\s*$/.exec(text.trim());
+    const reason = match?.[1] ?? match?.[2] ?? match?.[3];
+    return reason !== undefined && reason.trim().length > 0 ? reason.trim() : undefined;
+}
+function parseDeclaredBoundary(jsDoc) {
+    const tagText = jsDoc?.tags.get("boundary");
+    if (tagText === undefined)
+        return { kind: "none" };
+    const reason = parseBoundaryTag(tagText);
+    if (reason === undefined)
+        return { kind: "invalid", raw: tagText };
+    return { kind: "declared", reason };
+}
+/**
+ * `pure` is the literal spelling for the empty set (DESIGN.md §4.2 rule 2).
+ * Returns `undefined` when a token is neither `pure` nor a known effect (a
+ * typo, e.g. `@effects netwrok`) — such a declaration must not silently
+ * collapse to an empty (`pure`) contract. The caller reports this as
+ * `AMB-E002` (`diagnose.ts`) instead of the tag's real, but broken, contract.
+ */
+export function parseEffectsTag(text, aliases) {
+    const trimmed = text.trim();
+    if (trimmed === "pure")
+        return emptyEffectSet();
+    const tokens = trimmed.split(",").map((token) => token.trim());
+    const effects = [];
+    for (const token of tokens) {
+        if (isKnownEffect(token)) {
+            effects.push(token);
+            continue;
+        }
+        // A user-defined name is usable from `@effects` too, not only from
+        // config (DESIGN.md §4.2: "User-defined effects can be declared in
+        // `ambit.config.ts` as combinations of standard effects"). It expands here, so
+        // nothing downstream ever sees a name that is not a standard effect
+        // (§4.1 (d)).
+        const expansion = aliases?.get(token);
+        if (expansion === undefined)
+            return undefined;
+        effects.push(...expansion);
+    }
+    return effectSetOf(...effects);
+}
+function toCall(site) {
+    if (site.mutation) {
+        return {
+            kind: "mutation",
+            location: site.location,
+            escaping: site.mutation.escaping,
+            ...(site.mutation.qualifiedName ? { qualifiedName: site.mutation.qualifiedName } : {}),
+            ...(site.mutation.unknownCallback ? { unknownCallback: true } : {}),
+        };
+    }
+    if (site.resolvedCallee) {
+        return { kind: "resolved", location: site.location, callee: site.resolvedCallee };
+    }
+    if (site.calleeQualifiedName) {
+        // A construction is keyed in its own namespace (`src/stubs/
+        // constructors.ts`) — `new URL(...)` and `URL(...)` are different
+        // operations and must never share a table entry.
+        if (isConstructorKey(site.calleeQualifiedName)) {
+            return toConstructorCall(site, site.calleeQualifiedName);
+        }
+        const effects = stubEffectsFor(site.calleeQualifiedName, site.literalArguments);
+        if (effects) {
+            const required = lookupHttpCapability(site.calleeQualifiedName, site.literalArguments);
+            return {
+                kind: "stub",
+                location: site.location,
+                effects,
+                qualifiedName: site.calleeQualifiedName,
+                ...(required?.capability ? { requiredCapability: required.capability } : {}),
+                ...(required?.targetUnknown ? { capabilityTargetUnknown: true } : {}),
+            };
+        }
+        // A named call that didn't resolve to a project function and doesn't
+        // match a known stub (e.g. a third-party library call): unresolved, not
+        // "no effect" (DESIGN.md §3.4 — never turn an unanalyzed call into
+        // "violation-free"). The connector layer may already know a more
+        // specific reason than the residual "unresolved-symbol" (see
+        // `CallSite.unresolvedReason`'s doc comment).
+        return {
+            kind: "unresolved",
+            location: site.location,
+            reason: site.unresolvedReason ?? "unresolved-symbol",
+            qualifiedName: site.calleeQualifiedName,
+        };
+    }
+    if (site.pureBuiltinName) {
+        // A callback passed by reference is never walked, so it can't be
+        // trusted as pure even when the method name itself is allowlisted
+        // (CallSite.callbackByReference's doc comment).
+        if (isKnownPureBuiltin(site.pureBuiltinName) && !site.callbackByReference) {
+            return { kind: "known-pure", location: site.location, qualifiedName: site.pureBuiltinName };
+        }
+        return {
+            kind: "unresolved",
+            location: site.location,
+            reason: site.unresolvedReason ?? "unresolved-symbol",
+            qualifiedName: site.pureBuiltinName,
+        };
+    }
+    return {
+        kind: "unresolved",
+        location: site.location,
+        reason: site.unresolvedReason ?? "unresolved-symbol",
+    };
+}
+/**
+ * The bundled effect tables, in one lookup: the fixed table for globals and
+ * Node.js builtins (`src/stubs/node-builtins.ts`), then the database/LLM
+ * client table (`src/stubs/data-clients.ts`), whose answer can depend on the
+ * call's own literal arguments. The two key spaces do not overlap — a builtin
+ * key never has a client class in it — so the order only decides which lookup
+ * runs first, not which answer wins.
+ */
+function stubEffectsFor(qualifiedName, literalArguments) {
+    const builtin = lookupStubEffect(qualifiedName);
+    if (builtin)
+        return [builtin];
+    return lookupClientEffects(qualifiedName, literalArguments);
+}
+function toConstructorCall(site, qualifiedName) {
+    const withoutArguments = site.constructedWithoutArguments === true;
+    const effect = lookupConstructorEffect(qualifiedName, withoutArguments);
+    if (effect) {
+        return { kind: "stub", location: site.location, effects: [effect], qualifiedName };
+    }
+    // A callback passed by reference is never walked, so an allowlisted
+    // constructor that runs one (`new Promise(namedExecutor)`) cannot be
+    // trusted as effect-free (DESIGN.md §4.2 rule 4).
+    if (isKnownPureConstructor(qualifiedName, withoutArguments) && !site.callbackByReference) {
+        return { kind: "known-pure", location: site.location, qualifiedName };
+    }
+    return {
+        kind: "unresolved",
+        location: site.location,
+        reason: site.unresolvedReason ?? "unresolved-symbol",
+        qualifiedName,
+    };
+}

package/dist/cli/analyze.d.ts

@@ -0,0 +1,33 @@
+import type { CoverageReport } from "../checker/coverage.ts";
+import type { AuthorityRecord, Diagnostic } from "../core/index.ts";
+/** One run of the analysis over one directory. */
+export interface Analysis {
+    readonly diagnostics: readonly Diagnostic[];
+    /** Per-function authority (DESIGN.md §5.1), the input `ambit diff` compares. */
+    readonly authority: readonly AuthorityRecord[];
+    readonly coverage: CoverageReport;
+}
+export interface AnalyzeOptions {
+    /** `init`: report contract proposals instead of violations. */
+    readonly propose?: boolean;
+    /** `init --config`: also propose `ambit.config.ts` entries (DESIGN.md §4.1 (a)). */
+    readonly proposeConfig?: boolean;
+    /** `--strict`: promote the `unknown` warnings to errors (DESIGN.md §4.2 rule 3). */
+    readonly strict?: boolean;
+}
+/**
+ * Load the config, extract, summarize, propagate, diagnose and count — the
+ * whole single-directory pipeline, in one place.
+ *
+ * Extracted from `main` because `ambit diff` runs it twice, once per tree,
+ * and the two runs must be the same run: a base side that analyzed a
+ * directory even slightly differently would report the difference as a change
+ * in authority.
+ *
+ * Throws on any failure. A caller turns that into exit 2 — an analysis that
+ * could not run must never be reported as "checked, nothing wrong"
+ * (DESIGN.md §3.4).
+ *
+ * @effects fs_read
+ */
+export declare function analyze(dir: string, options?: AnalyzeOptions): Promise<Analysis>;

package/dist/cli/analyze.js

@@ -0,0 +1,98 @@
+import { buildAuthorityRecords, computeCoverage, diagnose, diagnoseContractDivergence, diagnoseRuntimeWrappers, diagnoseUncarriedContracts, diagnoseUnmatchedConfigKeys, legacyTsBackend, loadConfig, propagate, proposeContracts, resolveConfig, summarizeExtractedFiles, } from "../checker/index.js";
+/**
+ * Load the config, extract, summarize, propagate, diagnose and count — the
+ * whole single-directory pipeline, in one place.
+ *
+ * Extracted from `main` because `ambit diff` runs it twice, once per tree,
+ * and the two runs must be the same run: a base side that analyzed a
+ * directory even slightly differently would report the difference as a change
+ * in authority.
+ *
+ * Throws on any failure. A caller turns that into exit 2 — an analysis that
+ * could not run must never be reported as "checked, nothing wrong"
+ * (DESIGN.md §3.4).
+ *
+ * @effects fs_read
+ */
+export async function analyze(dir, options = {}) {
+    // Loaded before extraction so a broken config stops the run before any
+    // work is reported (DESIGN.md §3.4): a config that could not be read must
+    // never come out as "checked, no violations".
+    const loaded = await loadConfig(dir);
+    const config = loaded ? resolveConfig(loaded, dir) : undefined;
+    const project = await legacyTsBackend.extractProject(dir);
+    // No extracted function anywhere means "nothing analyzable was found"
+    // (zero .ts files, or every function-like node was skipped) — that must
+    // not read the same as "checked, no violations" (DESIGN.md §3.4). Counted
+    // over functions rather than over `files`, because a file can now be
+    // pushed for its `withAmbit` wrappers alone.
+    const functionsFound = project.files.reduce((total, file) => total + file.functions.length, 0);
+    if (functionsFound === 0) {
+        throw new Error(`no analyzable functions found under ${dir}`);
+    }
+    const summaries = summarizeExtractedFiles(project.files, config);
+    const state = propagate(summaries);
+    const engine = { name: legacyTsBackend.name, version: legacyTsBackend.version };
+    const diagnostics = options.propose
+        ? proposeContracts(state, engine, options.proposeConfig ? configTarget(config, dir) : undefined)
+        : applyStrict([
+            ...diagnose(state, engine),
+            ...diagnoseUncarriedContracts(project.uncarriedContracts, engine),
+            ...diagnoseRuntimeWrappers(project.files.flatMap((file) => file.runtimeWrappers), state, engine),
+            ...(config ? diagnoseContractDivergence(state, config.displayPath, engine) : []),
+            ...(config
+                ? diagnoseUnmatchedConfigKeys(config.unmatchedExactKeys(), config.displayPath, config.sourceText, engine)
+                : []),
+        ], options.strict ?? false, config);
+    return {
+        diagnostics,
+        authority: buildAuthorityRecords(state),
+        coverage: computeCoverage({
+            filesAnalyzed: project.files.length,
+            skippedFunctions: project.skippedFunctions,
+            summaries,
+            state,
+        }),
+    };
+}
+/**
+ * The diagnostics `--strict` promotes to errors: the two that say "analysis
+ * reached something it could not resolve" (DESIGN.md §4.2 rule 3 — "Ambit's
+ * `strict: true` can promote it to an error"). Deliberately not every warning:
+ * `--strict` means "an unverified path is not acceptable here", which is a
+ * different claim from promoting, say, an entrypoint's missing capability set.
+ */
+const STRICT_PROMOTED_IDS = new Set(["AMB-W001", "AMB-W003"]);
+/**
+ * `--strict` promotes everywhere; `strict` in `ambit.config.ts` promotes only
+ * inside the globs it lists (DESIGN.md §4.3: "`strict` can be set per
+ * directory in `ambit.config.ts`. Tighten new code while leaving legacy code
+ * at warnings"). The two are a union, so `--strict` on the command line is never
+ * narrowed by a config that lists fewer directories.
+ *
+ * Matched on the diagnostic's own file, which is why the config-level
+ * diagnostics (AMB-W005/W006) are unaffected in practice: theirs is the
+ * config file, which no `strict` glob names.
+ */
+function applyStrict(diagnostics, strict, config) {
+    if (!strict && config === undefined)
+        return diagnostics;
+    return diagnostics.map((diagnostic) => STRICT_PROMOTED_IDS.has(diagnostic.id) &&
+        (strict || config?.isStrictFile(diagnostic.location.file) === true)
+        ? { ...diagnostic, severity: "error" }
+        : diagnostic);
+}
+/**
+ * Where `ambit init --config` should write, and what is already there — the
+ * config file's path and text.
+ *
+ * `undefined` when no config file was found: §4.1's patch is an *append* to a
+ * `contracts` block, and inventing a whole file (with a `defineConfig` import
+ * whose specifier depends on how the consumer installed Ambit) is not a patch
+ * this command can generate safely (§5.3).
+ */
+function configTarget(config, rootDir) {
+    if (!config)
+        return undefined;
+    return { path: config.displayPath, source: config.sourceText, rootDir };
+}

package/dist/cli/approvals.d.ts

@@ -0,0 +1,28 @@
+import { type ParsedApprovals } from "../core/index.ts";
+/** The ledger that governs `dir`, and what it said. */
+export interface LoadedApprovals {
+    /** Absolute path to the ledger, or `undefined` when there is none. */
+    readonly filePath?: string;
+    readonly parsed: ParsedApprovals;
+}
+/**
+ * Walk up from `startDir` looking for the ledger, stopping after the first
+ * directory that holds a `package.json` or `.git`.
+ *
+ * The same walk `ambit.config.ts` uses (DESIGN.md §4.1 (c)), so the two files
+ * agree on where the project starts — a ledger picked up from outside the
+ * project would approve increases in a tree nobody reviewed.
+ */
+export declare function findApprovalsFile(startDir: string): string | undefined;
+/**
+ * Load the ledger governing `dir`. No file is not an error: a repository with
+ * no increases to approve never needs one, and the base side of the very
+ * comparison that introduces the mechanism has none by definition.
+ *
+ * A file that exists and cannot be read *is* an error. Treating it as an empty
+ * ledger would silently withdraw every approval in it, which reads as "these
+ * increases were never approved" (DESIGN.md §3.4).
+ *
+ * @effects fs_read
+ */
+export declare function loadApprovals(dir: string): LoadedApprovals;

package/dist/cli/approvals.js

@@ -0,0 +1,55 @@
+/**
+ * Finding and reading the approval ledger `ambit.approvals.md`
+ * (DESIGN.md §6.3).
+ *
+ * The reading of it — what the lines mean, and which of them are in force —
+ * is `src/core/approvals.ts`, which touches no file. This module is only the
+ * two lines of filesystem that stand between them, and it runs once per side
+ * of a `diff`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { APPROVALS_FILENAME, parseApprovals } from "../core/index.js";
+const EMPTY = { approvals: [], malformed: [] };
+/**
+ * Walk up from `startDir` looking for the ledger, stopping after the first
+ * directory that holds a `package.json` or `.git`.
+ *
+ * The same walk `ambit.config.ts` uses (DESIGN.md §4.1 (c)), so the two files
+ * agree on where the project starts — a ledger picked up from outside the
+ * project would approve increases in a tree nobody reviewed.
+ */
+export function findApprovalsFile(startDir) {
+    let dir = path.resolve(startDir);
+    for (;;) {
+        const candidate = path.join(dir, APPROVALS_FILENAME);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile())
+            return candidate;
+        if (isProjectBoundary(dir))
+            return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function isProjectBoundary(dir) {
+    return fs.existsSync(path.join(dir, "package.json")) || fs.existsSync(path.join(dir, ".git"));
+}
+/**
+ * Load the ledger governing `dir`. No file is not an error: a repository with
+ * no increases to approve never needs one, and the base side of the very
+ * comparison that introduces the mechanism has none by definition.
+ *
+ * A file that exists and cannot be read *is* an error. Treating it as an empty
+ * ledger would silently withdraw every approval in it, which reads as "these
+ * increases were never approved" (DESIGN.md §3.4).
+ *
+ * @effects fs_read
+ */
+export function loadApprovals(dir) {
+    const filePath = findApprovalsFile(dir);
+    if (filePath === undefined)
+        return { parsed: EMPTY };
+    return { filePath, parsed: parseApprovals(fs.readFileSync(filePath, "utf8")) };
+}