ambit-ts 0.1.0

package/dist/cli/diff.d.ts

@@ -0,0 +1,66 @@
+import type { ApprovalReview, AuthorityDiff, MalformedApprovalLine } from "../core/index.ts";
+/** What `ambit diff` compared, and what came out. */
+export interface DiffResult {
+    readonly diff: AuthorityDiff;
+    /**
+     * Which increases the approval ledger lets through, which it does not, and
+     * which lines granted nothing (DESIGN.md §6.3).
+     */
+    readonly review: ApprovalReview;
+    /** `-` lines in the head side's ledger that did not parse. Reported; they grant nothing. */
+    readonly malformedApprovals: readonly MalformedApprovalLine[];
+    /** The ledger that governed the head side, relative to the checked directory's repository. */
+    readonly approvalsFile?: string;
+    /** The ref as given, and the commit it resolved to — a branch name moves, a sha does not. */
+    readonly ref: string;
+    readonly baseCommit: string;
+    /** The directory that was compared, relative to the repository root. */
+    readonly subdir: string;
+    /** That same directory as the caller gave it — what a `location.file` is relative to. */
+    readonly dir: string;
+}
+/**
+ * Compare the working tree's authority against `ref`.
+ *
+ * The base side is a `git worktree` checkout under the OS temporary
+ * directory; both sides then run the same {@link analyze} over the same
+ * subdirectory, and the two dumps go to `diffAuthority`, which is pure. Git
+ * appears here and nowhere in the comparison.
+ *
+ * The worktree is removed in a `finally`, so a failed analysis leaves nothing
+ * behind either.
+ *
+ * @effects process, fs_read, fs_write
+ */
+export declare function runDiff(ref: string, dir: string): Promise<DiffResult>;
+/** Whether the comparison fails: an increase with no approval in force (DESIGN.md §6.3). */
+export declare function hasUnapprovedIncrease(result: DiffResult): boolean;
+/**
+ * The comparison, for a human reading a pull request.
+ *
+ * What increased comes first and is the only part rendered in full: each
+ * added authority gets the call path that brought it, so the reader sees the
+ * hop that introduced it without opening anything. What decreased, what was
+ * deleted and what stayed the same follow, named or counted but never
+ * expanded — the point of the command is that nobody has to read every
+ * contract to find the one that changed.
+ */
+export declare function formatDiffText(result: DiffResult): string;
+/**
+ * One GitHub Actions annotation per authority gained — per symbol *and*
+ * authority, since that is what a reviewer acts on: `priceOrder` gaining
+ * `network` and `fs_write` are two decisions, not one.
+ *
+ * Annotated at the symbol's own declaration, with the call path folded into
+ * the body, so the annotation lands on the function whose contract changed
+ * and carries the reason without the reader opening the job log — the same
+ * shape `check --format github` uses (DESIGN.md §5.1 / §6).
+ *
+ * An unapproved increase is an `error`, and carries the ledger line to add.
+ * An **approved** one is a `notice`, carrying the reason that was given: it
+ * does not fail the build, and it must still be visible on the diff, because
+ * an increase nobody sees is the thing the ledger exists to prevent (§6.3).
+ * A decrease and a deletion are reported by the text output and do not fail a
+ * build (§6), so an annotation on them would be noise on a diff.
+ */
+export declare function formatDiffGithub(result: DiffResult): string;

package/dist/cli/diff.js

@@ -0,0 +1,235 @@
+import path from "node:path";
+import { authorityDecreases, deletedSymbols, diffAuthority, displayName, formatApprovalLine, movedSymbols, pathFor, reviewIncreases, unchangedSymbols, unknownGained, } from "../core/index.js";
+import { analyze } from "./analyze.js";
+import { loadApprovals } from "./approvals.js";
+import { githubAnnotation, workspacePath } from "./github.js";
+import { addWorktree, git, removeWorktree, renamedFiles, repositoryRoot } from "./worktree.js";
+/**
+ * Compare the working tree's authority against `ref`.
+ *
+ * The base side is a `git worktree` checkout under the OS temporary
+ * directory; both sides then run the same {@link analyze} over the same
+ * subdirectory, and the two dumps go to `diffAuthority`, which is pure. Git
+ * appears here and nowhere in the comparison.
+ *
+ * The worktree is removed in a `finally`, so a failed analysis leaves nothing
+ * behind either.
+ *
+ * @effects process, fs_read, fs_write
+ */
+export async function runDiff(ref, dir) {
+    const repoRoot = await repositoryRoot(dir);
+    // Resolved before the checkout so a bad ref fails with git's own message
+    // rather than as a half-made worktree.
+    const baseCommit = await git(repoRoot, "rev-parse", ref);
+    const subdir = path.relative(repoRoot, path.resolve(dir));
+    // Asked of the working tree, before the base checkout exists: `git diff`
+    // compares the index and the working tree against `baseCommit`, and the
+    // temporary worktree is neither.
+    const renames = await renamedFiles(repoRoot, baseCommit, subdir);
+    const worktree = await addWorktree(repoRoot, baseCommit);
+    try {
+        // The same subpath on both sides: a symbol id is relative to the
+        // directory that was checked (DESIGN.md §5.3), so comparing `src` against
+        // a whole repository would make every id look new.
+        const baseDir = path.join(worktree.root, subdir);
+        const headDir = path.resolve(dir);
+        const base = await analyze(baseDir);
+        const head = await analyze(headDir);
+        // The ledger is read on both sides, because an approval counts only in
+        // the comparison that adds it (DESIGN.md §6.3).
+        const baseApprovals = loadApprovals(baseDir);
+        const headApprovals = loadApprovals(headDir);
+        const diff = diffAuthority(base.authority, head.authority, renames);
+        return {
+            diff,
+            review: reviewIncreases(diff, baseApprovals.parsed.approvals, headApprovals.parsed.approvals),
+            malformedApprovals: headApprovals.parsed.malformed,
+            ...(headApprovals.filePath
+                ? { approvalsFile: path.relative(repoRoot, headApprovals.filePath) }
+                : {}),
+            ref,
+            baseCommit,
+            subdir,
+            dir: headDir,
+        };
+    }
+    finally {
+        await removeWorktree(worktree);
+    }
+}
+/** Whether the comparison fails: an increase with no approval in force (DESIGN.md §6.3). */
+export function hasUnapprovedIncrease(result) {
+    return result.review.unapproved.length > 0;
+}
+/**
+ * The comparison, for a human reading a pull request.
+ *
+ * What increased comes first and is the only part rendered in full: each
+ * added authority gets the call path that brought it, so the reader sees the
+ * hop that introduced it without opening anything. What decreased, what was
+ * deleted and what stayed the same follow, named or counted but never
+ * expanded — the point of the command is that nobody has to read every
+ * contract to find the one that changed.
+ */
+export function formatDiffText(result) {
+    const { diff, review } = result;
+    const decreases = authorityDecreases(diff);
+    const deleted = deletedSymbols(diff);
+    const moved = movedSymbols(diff);
+    const unknown = unknownGained(diff);
+    const where = result.subdir === "" ? "the repository root" : result.subdir;
+    const lines = [
+        `base ${result.ref} (${result.baseCommit.slice(0, 7)}) vs the working tree, over ${where}`,
+        "",
+    ];
+    if (review.unapproved.length === 0 && review.approved.length === 0) {
+        lines.push("No authority increased.", "");
+    }
+    if (review.unapproved.length > 0) {
+        lines.push(`${count(review.unapproved.length, "authority")} increased without approval:`, "", ...review.unapproved.flatMap((item) => renderIncrease(item)), `Add each line above to ${result.approvalsFile ?? APPROVALS_HINT}, with the reason, and`, "commit it in the same change (DESIGN.md §6.3). An approval already in the base", "grants nothing.", "");
+    }
+    // Approved increases are still printed in full. The point of the ledger is
+    // that an increase is visible to whoever reads the pull request, and a
+    // section that collapses to a count would undo exactly that.
+    if (review.approved.length > 0) {
+        lines.push(`${count(review.approved.length, "authority")} increased, approved in this change:`, "", ...review.approved.flatMap((item) => [
+            ...renderIncrease(item, { suggestApproval: false }),
+            `      approved: ${item.approval.reason} (${result.approvalsFile ?? APPROVALS_HINT}:${item.approval.line})`,
+            "",
+        ]));
+    }
+    if (review.unused.length > 0) {
+        lines.push(`${count(review.unused.length, "approval")} added here matched no increase and granted nothing:`, ...review.unused.map((approval) => `  ${result.approvalsFile ?? APPROVALS_HINT}:${approval.line}  ${approval.symbol} ${approval.authority.kind}:${approval.authority.name}`), "");
+    }
+    if (result.malformedApprovals.length > 0) {
+        lines.push(`${count(result.malformedApprovals.length, "line")} in ${result.approvalsFile ?? APPROVALS_HINT} did not parse as an approval and granted nothing:`, ...result.malformedApprovals.map((entry) => `  line ${entry.line}: ${entry.text}`), "");
+    }
+    if (moved.length > 0) {
+        lines.push(`${count(moved.length, "symbol")} moved with a renamed file and was compared against its old path:`, ...moved.map((entry) => `  ${entry.movedFrom} -> ${entry.symbol}`), "");
+    }
+    // Not an increase — `unknown` is not authority (DESIGN.md §4.3) — but never
+    // silent either: a range that stopped being analyzable is exactly what must
+    // not be reported as "nothing increased here".
+    if (unknown.length > 0) {
+        lines.push(`Analysis reached something it could not resolve in ${count(unknown.length, "symbol")} where it previously did not.`, "This is not authority and is not counted as an increase; those symbols' effects may be incomplete:", ...unknown.map((entry) => `  ${entry.symbol}`), "");
+    }
+    if (decreases.length > 0) {
+        lines.push(`Authority decreased in ${count(decreases.length, "symbol")}:`);
+        for (const entry of decreases) {
+            lines.push(`  ${entry.symbol}`, ...entry.removed.map((ref) => `    - ${refText(ref)}`));
+        }
+        lines.push("");
+    }
+    if (deleted.length > 0) {
+        lines.push(`${count(deleted.length, "symbol")} no longer present:`, ...deleted.map((entry) => `  ${entry.symbol}`), "");
+    }
+    lines.push(`${count(unchangedSymbols(diff).length, "symbol")} unchanged, out of ${count(diff.symbols.length, "symbol")} compared.`, "");
+    return lines.join("\n");
+}
+/** Where to write an approval when the repository has no ledger yet (DESIGN.md §6.3). */
+const APPROVALS_HINT = "ambit.approvals.md";
+/**
+ * One authority one symbol gained: the symbol at its own position, the
+ * authority, and the path that carries it.
+ *
+ * A path is shown only where the record has one. An authority a function
+ * declares but does not reach has no path, and none is invented
+ * (DESIGN.md §5.3).
+ *
+ * For an increase with nothing approving it, the ledger line to add follows,
+ * ready to copy — the grammar of §6.3 is a thing to paste, not to recall.
+ */
+function renderIncrease(item, options = {}) {
+    const { entry, ref } = item;
+    const at = entry.head ? ` (${entry.head.location.file}:${entry.head.location.line})` : "";
+    const what = entry.status === "new" ? "  [new symbol]" : entry.status === "moved" ? "  [moved]" : "";
+    const lines = [`  ${entry.symbol}${at}${what}`, `    + ${refText(ref)}`];
+    const path = pathFor(entry.head, ref);
+    for (const hop of path?.via ?? []) {
+        lines.push(`      -> ${displayName(hop.symbol)} (${hop.file}:${hop.line})`);
+    }
+    if (path?.operation) {
+        lines.push(`      operation: ${path.operation.qualifiedName} (${path.operation.file}:${path.operation.line})`);
+    }
+    if (options.suggestApproval !== false) {
+        lines.push(`    ${formatApprovalLine(entry.symbol, ref)}`, "");
+    }
+    return lines;
+}
+/**
+ * An authority as a reader recognizes it: an effect by its bare name, a
+ * capability prefixed so the two lattices never read as one namespace.
+ */
+function refText(ref) {
+    return ref.kind === "effect" ? ref.name : `capability ${ref.name}`;
+}
+/**
+ * `1 symbol` / `2 symbols`, with the plural spelled out where appending an
+ * `s` gets it wrong — "2 authoritys" is the sort of thing a reader stops on.
+ */
+const PLURALS = { authority: "authorities" };
+function count(n, noun) {
+    if (n === 1)
+        return `${n} ${noun}`;
+    return `${n} ${PLURALS[noun] ?? `${noun}s`}`;
+}
+/**
+ * One GitHub Actions annotation per authority gained — per symbol *and*
+ * authority, since that is what a reviewer acts on: `priceOrder` gaining
+ * `network` and `fs_write` are two decisions, not one.
+ *
+ * Annotated at the symbol's own declaration, with the call path folded into
+ * the body, so the annotation lands on the function whose contract changed
+ * and carries the reason without the reader opening the job log — the same
+ * shape `check --format github` uses (DESIGN.md §5.1 / §6).
+ *
+ * An unapproved increase is an `error`, and carries the ledger line to add.
+ * An **approved** one is a `notice`, carrying the reason that was given: it
+ * does not fail the build, and it must still be visible on the diff, because
+ * an increase nobody sees is the thing the ledger exists to prevent (§6.3).
+ * A decrease and a deletion are reported by the text output and do not fail a
+ * build (§6), so an annotation on them would be noise on a diff.
+ */
+export function formatDiffGithub(result) {
+    let out = "";
+    for (const item of result.review.unapproved) {
+        out += increaseAnnotation(result, item, "error", [
+            `add to ${result.approvalsFile ?? APPROVALS_HINT}: ${formatApprovalLine(item.entry.symbol, item.ref)}`,
+        ]);
+    }
+    for (const item of result.review.approved) {
+        out += increaseAnnotation(result, item, "notice", [
+            `approved in this change: ${item.approval.reason}`,
+        ]);
+    }
+    return out;
+}
+function increaseAnnotation(result, item, severity, trailer) {
+    const head = item.entry.head;
+    if (!head)
+        return "";
+    const path = pathFor(head, item.ref);
+    const what = item.entry.status === "new"
+        ? "new symbol"
+        : item.entry.status === "moved"
+            ? "moved, and widened"
+            : "authority increased";
+    return githubAnnotation({
+        severity,
+        file: workspacePath(result.dir, head.location.file),
+        line: head.location.line,
+        col: head.location.col,
+        title: "ambit diff",
+        body: [
+            `${displayName(head.symbol)} gained ${refText(item.ref)} since ${result.ref} (${what})`,
+            ...(path?.via ?? []).map((hop) => `-> ${displayName(hop.symbol)} (${hop.file}:${hop.line})`),
+            ...(path?.operation
+                ? [
+                    `operation: ${path.operation.qualifiedName} (${path.operation.file}:${path.operation.line})`,
+                ]
+                : []),
+            ...trailer,
+        ],
+    });
+}

package/dist/cli/github.d.ts

@@ -0,0 +1,33 @@
+/**
+ * GitHub Actions workflow-command escaping and path handling, shared by every
+ * command that emits annotations.
+ *
+ * One implementation, because `check` and `diff` annotate the same files in
+ * the same run: two escapings that drifted apart would show up as one command
+ * annotating a line the other could not.
+ */
+/** Workflow-command escaping for the message body. */
+export declare function githubData(value: string): string;
+/** Workflow-command escaping for a property value, where `:` and `,` also terminate. */
+export declare function githubProperty(value: string): string;
+/**
+ * A `location.file` — relative to the directory that was checked — re-expressed
+ * relative to the working directory, which is what an annotation is resolved
+ * against.
+ */
+export declare function workspacePath(rootDir: string, file: string): string;
+/**
+ * One workflow command: `::<severity> file=...,line=...,col=...,title=...::<body>`.
+ *
+ * The body is folded onto one line with `%0A`, so an annotation carrying a
+ * call path stays self-sufficient — a reader on the diff sees every hop
+ * without opening the job log (DESIGN.md §5.1).
+ */
+export declare function githubAnnotation(annotation: {
+    readonly severity: string;
+    readonly file: string;
+    readonly line: number;
+    readonly col: number;
+    readonly title: string;
+    readonly body: readonly string[];
+}): string;

package/dist/cli/github.js

@@ -0,0 +1,41 @@
+import path from "node:path";
+/**
+ * GitHub Actions workflow-command escaping and path handling, shared by every
+ * command that emits annotations.
+ *
+ * One implementation, because `check` and `diff` annotate the same files in
+ * the same run: two escapings that drifted apart would show up as one command
+ * annotating a line the other could not.
+ */
+/** Workflow-command escaping for the message body. */
+export function githubData(value) {
+    return value.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
+}
+/** Workflow-command escaping for a property value, where `:` and `,` also terminate. */
+export function githubProperty(value) {
+    return githubData(value).replaceAll(":", "%3A").replaceAll(",", "%2C");
+}
+/**
+ * A `location.file` — relative to the directory that was checked — re-expressed
+ * relative to the working directory, which is what an annotation is resolved
+ * against.
+ */
+export function workspacePath(rootDir, file) {
+    return path.relative(process.cwd(), path.resolve(rootDir, file)).split(path.sep).join("/");
+}
+/**
+ * One workflow command: `::<severity> file=...,line=...,col=...,title=...::<body>`.
+ *
+ * The body is folded onto one line with `%0A`, so an annotation carrying a
+ * call path stays self-sufficient — a reader on the diff sees every hop
+ * without opening the job log (DESIGN.md §5.1).
+ */
+export function githubAnnotation(annotation) {
+    const properties = [
+        `file=${githubProperty(annotation.file)}`,
+        `line=${annotation.line}`,
+        `col=${annotation.col}`,
+        `title=${githubProperty(annotation.title)}`,
+    ].join(",");
+    return `::${annotation.severity} ${properties}::${githubData(annotation.body.join("\n"))}\n`;
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `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 declare function main(argv: readonly string[]): Promise<number>;