balladeer 1.0.14 → 1.0.16

package/dist/risk/index.js

@@ -0,0 +1,20 @@
+/**
+ * The risk ranking of agentic testing: which agreed promises a change could put
+ * at risk, and why, worked out on this machine with no model and no network.
+ * `balladeer risk` is the command over it; see `README.md` beside this file.
+ */
+export * from "./contract.js";
+export { BEHAVIOR_MAP_DIRECTORY, BEHAVIOR_MAP_SCHEMA_VERSION, mapFiles, parseBehaviorMap, } from "../behavior-map-schema.js";
+export { describeReason } from "./describe.js";
+export { parseUnifiedDiff, unquotePath, } from "./diff.js";
+export { analyzeFileChange, extractChange, readCommitIntent, sqlLineContexts, } from "./extract.js";
+export { commitMessages, GitReadError, listTree, mergeBase, readBlobs, resolveCommit, tryGit, } from "./git.js";
+export { buildImportGraph, forwardClosure, parseLooseJson, reverseClosure, workingTreeReader, } from "./import-graph.js";
+export { isTestPath, languageOf } from "./paths.js";
+export { assessChange, buildGraphAt, readBehaviorMaps, watchedResources, } from "./pipeline.js";
+export { churnPriors, priorBreaksFromJudgeLog, readPriors } from "./priors.js";
+export { mentionsResource, normalizeRoute, parseResourceRef, resourceKey, resourcesInLine, resourcesMatch, routeFromPath, } from "./resources.js";
+export { BAND_THRESHOLDS, bandFor, byRisk, directness, forwardDecay, mapSeeds, reverseDecay, scoreChange, seededShuffle, WEIGHTS, } from "./score.js";
+export { declaredSymbols, loadTypeScript } from "./symbols.js";
+export { buildIdf, cosine, identifierTokens, STOP_WORDS, words } from "./text.js";
+export { parseChangeExtraction, parseRiskReport } from "./validate.js";

package/dist/risk/paths.d.ts

@@ -0,0 +1,16 @@
+import type { Language } from "./contract.js";
+export declare function extensionOf(path: string): string;
+export declare function basenameOf(path: string): string;
+export declare function dirnameOf(path: string): string;
+/** The contract's language for a path, by extension. */
+export declare function languageOf(path: string): Language;
+/** The TypeScript compiler reads these: the ts, tsx and js languages. */
+export declare function isScriptPath(path: string): boolean;
+/**
+ * Whether a path is a test: under a test directory, or named the way the common
+ * runners find tests (`*.test.*`, `*.spec.*`, `*_test.py`, `test_*.py`,
+ * `*_test.go`, `*_spec.rb`).
+ */
+export declare function isTestPath(path: string): boolean;
+/** Joins and normalizes repository-relative segments; undefined when it escapes the root. */
+export declare function joinRepositoryPath(directory: string, relative: string): string | undefined;

package/dist/risk/paths.js

@@ -0,0 +1,73 @@
+const LANGUAGE_BY_EXTENSION = {
+    ts: "ts",
+    mts: "ts",
+    cts: "ts",
+    tsx: "tsx",
+    js: "js",
+    mjs: "js",
+    cjs: "js",
+    jsx: "js",
+    py: "py",
+    go: "go",
+    rb: "rb",
+    java: "java",
+    kt: "kt",
+    kts: "kt",
+    rs: "rs",
+};
+export function extensionOf(path) {
+    const base = path.slice(path.lastIndexOf("/") + 1);
+    const dot = base.lastIndexOf(".");
+    return dot <= 0 ? "" : base.slice(dot + 1).toLowerCase();
+}
+export function basenameOf(path) {
+    return path.slice(path.lastIndexOf("/") + 1);
+}
+export function dirnameOf(path) {
+    const slash = path.lastIndexOf("/");
+    return slash < 0 ? "" : path.slice(0, slash);
+}
+/** The contract's language for a path, by extension. */
+export function languageOf(path) {
+    return LANGUAGE_BY_EXTENSION[extensionOf(path)] ?? "other";
+}
+/** The TypeScript compiler reads these: the ts, tsx and js languages. */
+export function isScriptPath(path) {
+    const language = languageOf(path);
+    return language === "ts" || language === "tsx" || language === "js";
+}
+const TEST_DIRECTORIES = new Set(["test", "tests", "__tests__", "spec", "specs"]);
+/**
+ * Whether a path is a test: under a test directory, or named the way the common
+ * runners find tests (`*.test.*`, `*.spec.*`, `*_test.py`, `test_*.py`,
+ * `*_test.go`, `*_spec.rb`).
+ */
+export function isTestPath(path) {
+    const segments = path.split("/");
+    const base = segments[segments.length - 1] ?? "";
+    if (segments.slice(0, -1).some((segment) => TEST_DIRECTORIES.has(segment)))
+        return true;
+    if (/\.(?:test|spec)\.[^.]+$/.test(base))
+        return true;
+    if (/^test_.+\.py$/.test(base) || /_test\.py$/.test(base))
+        return true;
+    if (/_test\.go$/.test(base) || /_spec\.rb$/.test(base))
+        return true;
+    return false;
+}
+/** Joins and normalizes repository-relative segments; undefined when it escapes the root. */
+export function joinRepositoryPath(directory, relative) {
+    const parts = directory === "" ? [] : directory.split("/");
+    for (const segment of relative.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === "..") {
+            if (parts.length === 0)
+                return undefined;
+            parts.pop();
+        }
+        else
+            parts.push(segment);
+    }
+    return parts.join("/");
+}

package/dist/risk/pipeline.d.ts

@@ -0,0 +1,47 @@
+import { type ImportGraph } from "./import-graph.js";
+import { type ResourceRef } from "./resources.js";
+import type { BehaviorMap, ChangeExtraction, Delta, Intent, RiskReport } from "./contract.js";
+import { type Prior, type Weights } from "./score.js";
+export type MapProblem = Readonly<{
+    file: string;
+    message: string;
+}>;
+/**
+ * Every `*.json` in a directory read as a behavior map. A file that does not
+ * parse is reported, not thrown: one bad map must not hide the others.
+ */
+export declare function readBehaviorMaps(directory: string): {
+    maps: BehaviorMap[];
+    problems: MapProblem[];
+};
+/** Every resource the maps name, including sink resources, for the extraction to look for directly. */
+export declare function watchedResources(maps: readonly BehaviorMap[]): ResourceRef[];
+/** The import graph of the tree at a commit, read from git rather than the working tree. */
+export declare function buildGraphAt(root: string, rev: string): ImportGraph;
+export type AssessOptions = Readonly<{
+    root: string;
+    base: string;
+    head: string;
+    maps: readonly BehaviorMap[];
+    /** Promises that should be listed even without a map. */
+    promiseIds?: readonly string[];
+    weights?: Weights;
+    /** Read churn and judge-log priors from the repository. On unless false. */
+    priors?: boolean | Readonly<Record<string, Prior>>;
+    /** Behavioral deltas a model wrote for this change, when one ran. */
+    deltas?: readonly Delta[];
+    /** The change's intent from its description or a model; else it is read from the commits. */
+    intent?: Intent;
+}>;
+export type Assessment = Readonly<{
+    report: RiskReport;
+    extraction: ChangeExtraction;
+    graph: ImportGraph;
+}>;
+/**
+ * The whole pipeline for one change: extract it (looking for every resource
+ * the maps name), take its intent from the commit messages unless a description
+ * or a model supplied one, add a model's deltas when there are any, build the
+ * import graph at head, read the priors, score. Nothing here calls a model.
+ */
+export declare function assessChange(options: AssessOptions): Promise<Assessment>;

package/dist/risk/pipeline.js

@@ -0,0 +1,121 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { extractChange, readCommitIntent } from "./extract.js";
+import { listTree, readBlobs, resolveCommit } from "./git.js";
+import { buildImportGraph } from "./import-graph.js";
+import { extensionOf } from "./paths.js";
+import { readPriors } from "./priors.js";
+import { parseResourceRef, resourceKey } from "./resources.js";
+import { parseBehaviorMap } from "../behavior-map-schema.js";
+import { scoreChange } from "./score.js";
+/**
+ * Every `*.json` in a directory read as a behavior map. A file that does not
+ * parse is reported, not thrown: one bad map must not hide the others.
+ */
+export function readBehaviorMaps(directory) {
+    let entries;
+    try {
+        entries = readdirSync(directory)
+            .filter((entry) => entry.endsWith(".json"))
+            .sort();
+    }
+    catch {
+        return { maps: [], problems: [] };
+    }
+    const maps = [];
+    const problems = [];
+    for (const entry of entries) {
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(join(directory, entry), "utf8"));
+        }
+        catch (error) {
+            problems.push({
+                file: entry,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            continue;
+        }
+        const parsed = parseBehaviorMap(raw);
+        if (!parsed.ok) {
+            problems.push({ file: entry, message: parsed.errors[0] ?? "not a behavior map" });
+            continue;
+        }
+        maps.push(parsed.value);
+    }
+    return { maps, problems };
+}
+/** Every resource the maps name, including sink resources, for the extraction to look for directly. */
+export function watchedResources(maps) {
+    const refs = new Map();
+    for (const map of maps) {
+        for (const resource of map.resources) {
+            const ref = { kind: resource.kind, name: resource.name };
+            refs.set(resourceKey(ref), ref);
+        }
+        for (const sink of map.sinks) {
+            for (const text of sink.resources) {
+                const ref = parseResourceRef(text);
+                if (ref !== undefined)
+                    refs.set(resourceKey(ref), ref);
+            }
+        }
+    }
+    return [...refs.values()];
+}
+const GRAPH_EXTENSIONS = new Set(["ts", "tsx", "mts", "cts", "js", "jsx", "mjs", "cjs", "py"]);
+const MAX_GRAPH_FILE_BYTES = 1_000_000;
+/** The import graph of the tree at a commit, read from git rather than the working tree. */
+export function buildGraphAt(root, rev) {
+    const entries = listTree(root, rev).filter((entry) => {
+        if (entry.size > MAX_GRAPH_FILE_BYTES)
+            return false;
+        if (/(?:^|\/)(?:node_modules|vendor|dist|build|\.next|coverage)\//.test(entry.path))
+            return false;
+        const base = entry.path.slice(entry.path.lastIndexOf("/") + 1);
+        return (GRAPH_EXTENSIONS.has(extensionOf(entry.path)) ||
+            base === "package.json" ||
+            base === "tsconfig.json" ||
+            base === "jsconfig.json" ||
+            /^tsconfig\..*json$/.test(base));
+    });
+    const paths = entries.map((entry) => entry.path);
+    const blobs = readBlobs(root, rev, paths);
+    return buildImportGraph(root, paths, (path) => blobs.get(path));
+}
+/**
+ * The whole pipeline for one change: extract it (looking for every resource
+ * the maps name), take its intent from the commit messages unless a description
+ * or a model supplied one, add a model's deltas when there are any, build the
+ * import graph at head, read the priors, score. Nothing here calls a model.
+ */
+export async function assessChange(options) {
+    const head = resolveCommit(options.root, options.head);
+    const extraction = await extractChange({
+        root: options.root,
+        base: options.base,
+        head,
+        watch: watchedResources(options.maps),
+    });
+    const intent = options.intent ?? readCommitIntent({ root: options.root, base: extraction.base, head });
+    const withIntent = {
+        ...extraction,
+        ...(options.deltas === undefined ? {} : { deltas: [...options.deltas] }),
+        ...(intent === undefined ? {} : { intent }),
+    };
+    const graph = buildGraphAt(options.root, head);
+    const priors = options.priors === false
+        ? undefined
+        : typeof options.priors === "object"
+            ? options.priors
+            : readPriors(options.root, head, options.maps);
+    const report = scoreChange({
+        extraction: withIntent,
+        maps: options.maps,
+        graph,
+        ...(priors === undefined ? {} : { priors }),
+        ...(options.promiseIds === undefined ? {} : { promiseIds: options.promiseIds }),
+        ...(options.weights === undefined ? {} : { weights: options.weights }),
+    });
+    return { report, extraction: withIntent, graph };
+}

package/dist/risk/priors.d.ts

@@ -0,0 +1,18 @@
+import type { Prior } from "./score.js";
+import type { BehaviorMap } from "./contract.js";
+/**
+ * The two priors, read from what the repository already holds: how often the
+ * promise's mapped files change (git history), and how often a judge has
+ * recorded a verified break of it (the local judge log). Both are small
+ * additions to a promise that already has some signal, never a signal alone.
+ */
+/** Share of the last `window` commits before head that touched any file a map names. */
+export declare function churnPriors(root: string, head: string, maps: readonly BehaviorMap[], window?: number): Record<string, number>;
+/**
+ * Verified breaks per promise from `.continuity/judge-log/*.jsonl`: verdicts of
+ * `broken` whose reproduction the runner did not reject. A missing or
+ * unreadable log is no history, not an error.
+ */
+export declare function priorBreaksFromJudgeLog(root: string): Record<string, number>;
+/** Both priors, keyed by promise. */
+export declare function readPriors(root: string, head: string, maps: readonly BehaviorMap[]): Record<string, Prior>;

package/dist/risk/priors.js

@@ -0,0 +1,86 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tryGit } from "./git.js";
+import { mapFiles } from "../behavior-map-schema.js";
+/**
+ * The two priors, read from what the repository already holds: how often the
+ * promise's mapped files change (git history), and how often a judge has
+ * recorded a verified break of it (the local judge log). Both are small
+ * additions to a promise that already has some signal, never a signal alone.
+ */
+/** Share of the last `window` commits before head that touched any file a map names. */
+export function churnPriors(root, head, maps, window = 200) {
+    const out = tryGit(root, ["log", "-n", String(window), "--format=%x00", "--name-only", head]);
+    if (out === undefined)
+        return {};
+    const commits = out
+        .split("\0")
+        .map((block) => new Set(block
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)))
+        .filter((files) => files.size > 0);
+    if (commits.length === 0)
+        return {};
+    const churn = {};
+    for (const map of maps) {
+        const files = mapFiles(map);
+        const touching = commits.filter((changed) => files.some((file) => changed.has(file))).length;
+        churn[map.promiseId] = touching / commits.length;
+    }
+    return churn;
+}
+/**
+ * Verified breaks per promise from `.continuity/judge-log/*.jsonl`: verdicts of
+ * `broken` whose reproduction the runner did not reject. A missing or
+ * unreadable log is no history, not an error.
+ */
+export function priorBreaksFromJudgeLog(root) {
+    const directory = join(root, ".continuity", "judge-log");
+    let entries;
+    try {
+        entries = readdirSync(directory).filter((entry) => entry.endsWith(".jsonl"));
+    }
+    catch {
+        return {};
+    }
+    const breaks = {};
+    for (const entry of entries) {
+        let text;
+        try {
+            text = readFileSync(join(directory, entry), "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split("\n")) {
+            if (line.trim().length === 0)
+                continue;
+            try {
+                const verdict = JSON.parse(line);
+                if (verdict.verdict !== "broken" || verdict.reproductionRejected)
+                    continue;
+                if (typeof verdict.promiseId !== "string")
+                    continue;
+                breaks[verdict.promiseId] = (breaks[verdict.promiseId] ?? 0) + 1;
+            }
+            catch {
+                // A torn line is skipped, not fatal.
+            }
+        }
+    }
+    return breaks;
+}
+/** Both priors, keyed by promise. */
+export function readPriors(root, head, maps) {
+    const churn = churnPriors(root, head, maps);
+    const breaks = priorBreaksFromJudgeLog(root);
+    const priors = {};
+    for (const map of maps) {
+        priors[map.promiseId] = {
+            churn: churn[map.promiseId] ?? 0,
+            priorBreak: breaks[map.promiseId] ?? 0,
+        };
+    }
+    return priors;
+}

package/dist/risk/resources.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceKind } from "./contract.js";
+/**
+ * Resources a line of code names, found by regular expression across languages:
+ * tables and columns in SQL, route literals, environment keys, feature flags,
+ * queue and event names, outbound hosts, file paths and configuration keys.
+ *
+ * This reads text, not programs. It will name a table in a comment and miss one
+ * assembled at run time. What it buys is the couplings an import graph cannot
+ * see: two files that never import each other and meet at a table name, a
+ * route string or a file on disk.
+ */
+export type ResourceRef = Readonly<{
+    kind: ResourceKind;
+    name: string;
+}>;
+export declare function resourceKey(ref: ResourceRef): string;
+/** `outbound:stripe.charges.create` → { kind: outbound, name: stripe.charges.create }. */
+export declare function parseResourceRef(text: string): ResourceRef | undefined;
+/** Whether the file is SQL, where keywords are read in any case. */
+export declare function isSqlPath(path: string): boolean;
+/** Normalizes a route so `/orders/:id`, `/orders/{id}` and `/orders/[id]` meet. */
+export declare function normalizeRoute(route: string): string;
+export type LineContext = Readonly<{
+    path: string;
+    /** For SQL files: the table the statement around this line alters or creates. */
+    currentTable?: string | undefined;
+    /** Whether this line sits inside a CREATE TABLE body, so a leading identifier is a column. */
+    inCreateTable?: boolean;
+}>;
+/** Every resource this one line names. */
+export declare function resourcesInLine(line: string, context: LineContext): ResourceRef[];
+/** Next.js and similar file-system routers: the route a file serves, from its path. */
+export declare function routeFromPath(path: string): string | undefined;
+/** The contents of every string literal on a line. */
+export declare function stringLiterals(line: string): string[];
+/**
+ * Whether one line names a resource a behavior map lists, read directly.
+ *
+ * The extraction runs this for every resource the maps list, so a resource the
+ * expressions above cannot recognize (a call chain such as
+ * `stripe.charges.create`, a configuration key) is still found where it is
+ * written. Tables, columns and files are looked for inside string literals
+ * only, outside SQL files, because their names are ordinary words in code.
+ * Routes are left to the route literals above, which normalize parameters.
+ * Names shorter than four characters are too common to look for.
+ */
+export declare function mentionsResource(line: string, ref: ResourceRef, context: LineContext): boolean;
+/**
+ * Whether a resource the change names is the resource a map names.
+ *
+ * Names meet case-insensitively. Tables meet on their last segment as well
+ * (`public.orders` and `orders`), columns with or without their table, routes
+ * by prefix after parameters are normalized, files by base name, hosts by
+ * suffix, and configuration keys by their final segments.
+ */
+export declare function resourcesMatch(mapped: ResourceRef, changed: ResourceRef): boolean;