balladeer 1.0.14 → 1.0.16

package/dist/risk/resources.js

@@ -0,0 +1,374 @@
+import { basenameOf, extensionOf } from "./paths.js";
+export function resourceKey(ref) {
+    return `${ref.kind}:${ref.name}`;
+}
+/** `outbound:stripe.charges.create` → { kind: outbound, name: stripe.charges.create }. */
+export function parseResourceRef(text) {
+    const colon = text.indexOf(":");
+    if (colon <= 0)
+        return undefined;
+    const kind = text.slice(0, colon);
+    const name = text.slice(colon + 1).trim();
+    if (!RESOURCE_KIND_SET.has(kind) || name.length === 0)
+        return undefined;
+    return { kind, name };
+}
+const RESOURCE_KIND_SET = new Set([
+    "table",
+    "column",
+    "route",
+    "flag",
+    "env",
+    "queue",
+    "event",
+    "outbound",
+    "file",
+    "config",
+]);
+const SQL_WORDS = new Set([
+    "select",
+    "where",
+    "set",
+    "values",
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "not",
+    "exists",
+    "if",
+    "on",
+    "as",
+    "only",
+    "lateral",
+    "unnest",
+    "table",
+    "into",
+    "from",
+    "join",
+    "update",
+    "using",
+    "with",
+    "public",
+    "returning",
+    "default",
+]);
+const FILE_EXTENSIONS = "json|jsonl|ya?ml|toml|ini|env|txt|md|csv|tsv|db|sqlite|sqlite3|lock|log|conf|cfg|xml|properties|pem|key|plist";
+/** Whether the file is SQL, where keywords are read in any case. */
+export function isSqlPath(path) {
+    return extensionOf(path) === "sql";
+}
+function cleanTableName(raw) {
+    const name = raw.replace(/["`[\]]/g, "").replace(/;$/, "");
+    if (name.length < 2)
+        return undefined;
+    if (!/^[A-Za-z_][\w.]*$/.test(name))
+        return undefined;
+    const last = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
+    if (SQL_WORDS.has(last))
+        return undefined;
+    return name.toLowerCase();
+}
+/** Normalizes a route so `/orders/:id`, `/orders/{id}` and `/orders/[id]` meet. */
+export function normalizeRoute(route) {
+    const path = route.split(/[?#]/)[0] ?? route;
+    const normalized = path
+        .split("/")
+        .map((segment) => /^(?::\w+|\{[^}]*\}|\[[^\]]*\]|<[^>]*>|\$\{[^}]*\})$/.test(segment) ? ":param" : segment)
+        .join("/")
+        .replace(/\/+$/, "");
+    return (normalized.startsWith("/") ? normalized : `/${normalized}`).toLowerCase();
+}
+function looksLikeRoute(literal) {
+    if (!/^\/[A-Za-z0-9_:{[<$-]/.test(literal))
+        return false;
+    if (/\s/.test(literal))
+        return false;
+    // A file on disk rather than a route: an extension at the end.
+    if (new RegExp(`\\.(?:${FILE_EXTENSIONS}|js|ts|mjs|cjs|py|html|css|png|svg|sh)$`, "i").test(literal))
+        return false;
+    if (/^\/(?:usr|etc|tmp|var|bin|dev|proc|home|Users|opt)\b/.test(literal))
+        return false;
+    return true;
+}
+function looksLikeFile(literal) {
+    if (/\s/.test(literal) || literal.length > 300)
+        return false;
+    if (/^[a-z]+:\/\//i.test(literal))
+        return false;
+    return new RegExp(`(?:^|/)[\\w.@-]+\\.(?:${FILE_EXTENSIONS})$`, "i").test(literal);
+}
+const STRING_LITERAL = /(["'`])((?:\\.|(?!\1)[^\\\n])*)\1/g;
+/** Every resource this one line names. */
+export function resourcesInLine(line, context) {
+    const found = new Map();
+    const add = (kind, name) => {
+        if (name === undefined)
+            return;
+        const trimmed = name.trim();
+        if (trimmed.length === 0 || trimmed.length > 600)
+            return;
+        found.set(`${kind}:${trimmed}`, { kind, name: trimmed });
+    };
+    const sql = isSqlPath(context.path);
+    const trimmed = line.trim();
+    const isImportLine = /^(?:import|export)\b.*\bfrom\b/.test(trimmed) ||
+        /^from\s+[\w.]+\s+import\b/.test(trimmed) ||
+        /^import\s+[\w.]+/.test(trimmed);
+    // SQL tables. In SQL files any case; elsewhere only upper-case keywords, which
+    // is how SQL embedded in code is conventionally written and what keeps "from
+    // the queue" in a comment from naming a table called "the".
+    if (!isImportLine) {
+        const keyword = sql
+            ? /\b(?:from|join|into|update|references|(?:create|alter|drop|truncate)\s+table(?:\s+if\s+(?:not\s+)?exists)?)\s+(?:only\s+)?([`"[]?[A-Za-z_][\w.]*[`"\]]?)/gi
+            : /\b(?:FROM|JOIN|INTO|UPDATE|REFERENCES|(?:CREATE|ALTER|DROP|TRUNCATE)\s+TABLE(?:\s+IF\s+(?:NOT\s+)?EXISTS)?)\s+(?:ONLY\s+)?([`"[]?[A-Za-z_][\w.]*[`"\]]?)/g;
+        for (const match of line.matchAll(keyword))
+            add("table", cleanTableName(match[1] ?? ""));
+        // Query builders: supabase `.from("orders")`, knex `.table("orders")`, `.into("orders")`.
+        for (const match of line.matchAll(/\.(?:from|table|into|insertInto|selectFrom|updateTable|deleteFrom)\(\s*["'`]([A-Za-z_][\w.]*)["'`]/g))
+            add("table", cleanTableName(match[1] ?? ""));
+    }
+    if (sql) {
+        const columnPatterns = [
+            /\b(?:add|drop|alter|rename)\s+column\s+(?:if\s+(?:not\s+)?exists\s+)?["`]?([A-Za-z_]\w*)["`]?/gi,
+            /\brename\s+column\s+["`]?[A-Za-z_]\w*["`]?\s+to\s+["`]?([A-Za-z_]\w*)["`]?/gi,
+            /\badd\s+(?!column\b|constraint\b|index\b|primary\b|foreign\b|unique\b|check\b)["`]?([A-Za-z_]\w*)["`]?\s+[A-Za-z]/gi,
+        ];
+        for (const pattern of columnPatterns) {
+            for (const match of line.matchAll(pattern)) {
+                const column = (match[1] ?? "").toLowerCase();
+                if (column.length === 0)
+                    continue;
+                add("column", context.currentTable ? `${context.currentTable}.${column}` : column);
+            }
+        }
+        // `ALTER TABLE orders ADD COLUMN x` on one line names its own table.
+        const inline = /\balter\s+table\s+(?:if\s+exists\s+)?(?:only\s+)?([`"]?[A-Za-z_][\w.]*[`"]?)/i.exec(line);
+        if (inline) {
+            const table = cleanTableName(inline[1] ?? "");
+            for (const pattern of columnPatterns) {
+                for (const match of line.matchAll(pattern)) {
+                    const column = (match[1] ?? "").toLowerCase();
+                    if (table && column.length > 0)
+                        add("column", `${table}.${column}`);
+                }
+            }
+        }
+        if (context.inCreateTable) {
+            const column = /^\s*["`]?([A-Za-z_]\w*)["`]?\s+[A-Za-z]/.exec(line);
+            const name = column?.[1]?.toLowerCase();
+            if (name !== undefined &&
+                !/^(?:constraint|primary|foreign|unique|check|create|like|exclude)$/.test(name))
+                add("column", context.currentTable ? `${context.currentTable}.${name}` : name);
+        }
+    }
+    // Migrations written in code: alembic `op.drop_column("orders", "status")`,
+    // Rails `remove_column :orders, :status`, knex `table.dropColumn("status")`.
+    for (const match of line.matchAll(/\bop\.(?:add|drop|alter)_column\(\s*["'](\w+)["']\s*,\s*(?:sa\.Column\(\s*)?["'](\w+)["']/g)) {
+        add("table", cleanTableName(match[1] ?? ""));
+        add("column", `${(match[1] ?? "").toLowerCase()}.${(match[2] ?? "").toLowerCase()}`);
+    }
+    for (const match of line.matchAll(/\b(?:add|remove|rename|change)_column\s*\(?\s*:(\w+)\s*,\s*:(\w+)/g)) {
+        add("table", cleanTableName(match[1] ?? ""));
+        add("column", `${(match[1] ?? "").toLowerCase()}.${(match[2] ?? "").toLowerCase()}`);
+    }
+    for (const match of line.matchAll(/\.(?:dropColumn|renameColumn)\(\s*["'](\w+)["']/g))
+        add("column", (match[1] ?? "").toLowerCase());
+    // Environment keys.
+    for (const pattern of [
+        /\bprocess\.env\.([A-Za-z_]\w*)/g,
+        /\bprocess\.env\[\s*["'`]([A-Za-z_]\w*)["'`]\s*\]/g,
+        /\bimport\.meta\.env\.([A-Za-z_]\w*)/g,
+        /\bos\.environ\[\s*["']([A-Za-z_]\w*)["']\s*\]/g,
+        /\bos\.environ\.get\(\s*["']([A-Za-z_]\w*)["']/g,
+        /\bos\.getenv\(\s*["']([A-Za-z_]\w*)["']/g,
+        /\bos\.Getenv\(\s*"([A-Za-z_]\w*)"/g,
+        /\bENV\[\s*["']([A-Za-z_]\w*)["']\s*\]/g,
+        /\bENV\.fetch\(\s*["']([A-Za-z_]\w*)["']/g,
+        /\bSystem\.getenv\(\s*"([A-Za-z_]\w*)"/g,
+        /\benv::var\(\s*"([A-Za-z_]\w*)"/g,
+        /\bDeno\.env\.get\(\s*["']([A-Za-z_]\w*)["']/g,
+    ]) {
+        for (const match of line.matchAll(pattern))
+            add("env", match[1]);
+    }
+    // Feature flags.
+    for (const match of line.matchAll(/\b(?:flag|isEnabled|isFeatureEnabled|isFeatureFlagEnabled|featureEnabled|feature_enabled|is_enabled|useFlag|getFlag|useFeatureFlag|getFeatureFlag|variation|boolVariation|isOn|flipper)\(\s*["'`]([\w.:/-]+)["'`]/g))
+        add("flag", match[1]);
+    for (const match of line.matchAll(/\b(?:features|featureFlags|feature_flags|flags)\.([A-Za-z_]\w*)/g))
+        add("flag", match[1]);
+    // Queues and events.
+    for (const match of line.matchAll(/\b(?:emit|on|once|off|addEventListener|removeEventListener|trigger|dispatchEvent|listen)\(\s*["'`]([\w.:/-]+)["'`]/g))
+        add("event", match[1]);
+    for (const match of line.matchAll(/\b(?:publish|subscribe|enqueue|send_task|sendToQueue|assertQueue|consume|Queue|queue|topic|channel)\(\s*["'`]([\w.:/-]+)["'`]/g))
+        add("queue", match[1]);
+    // Configuration keys.
+    for (const match of line.matchAll(/\b(?:config|conf|cfg|settings|options)\s*(?:\.get\(\s*|\[\s*)["'`]([\w.:-]+)["'`]/g))
+        add("config", match[1]);
+    for (const match of line.matchAll(/\b(?:getConfig|readConfig|configValue)\(\s*["'`]([\w.:-]+)["'`]/g))
+        add("config", match[1]);
+    // Route decorators without a leading slash: NestJS `@Get("orders")`.
+    for (const match of line.matchAll(/@(?:Get|Post|Put|Patch|Delete|All|Head|Options)\(\s*["'`]([^"'`]*)["'`]/g))
+        add("route", normalizeRoute(match[1] ?? ""));
+    // String literals: routes, outbound hosts, files.
+    for (const match of line.matchAll(STRING_LITERAL)) {
+        const literal = match[2] ?? "";
+        for (const url of literal.matchAll(/\b[a-z][a-z0-9+.-]*:\/\/([A-Za-z0-9.-]+)(?::\d+)?(\/[^\s"'`]*)?/gi)) {
+            const host = (url[1] ?? "").toLowerCase();
+            if (host.length > 0 && !/^(?:localhost|127\.0\.0\.1|0\.0\.0\.0)$/.test(host))
+                add("outbound", host);
+        }
+        if (looksLikeRoute(literal))
+            add("route", normalizeRoute(literal));
+        if (looksLikeFile(literal))
+            add("file", literal.replace(/^\.\//, ""));
+    }
+    return [...found.values()];
+}
+/** Next.js and similar file-system routers: the route a file serves, from its path. */
+export function routeFromPath(path) {
+    const app = /(?:^|\/)app\/(.*)\/route\.[jt]sx?$/.exec(path);
+    if (app)
+        return normalizeRoute(`/${(app[1] ?? "").replace(/\([^)]*\)\/?/g, "")}`);
+    const pages = /(?:^|\/)pages\/(api\/.*?)(?:\/index)?\.[jt]sx?$/.exec(path);
+    if (pages)
+        return normalizeRoute(`/${pages[1] ?? ""}`);
+    return undefined;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const compiled = new Map();
+/** The needle as a whole word, compiled once per needle. */
+function wordPattern(needle, flags) {
+    const key = `${flags}\u0000${needle}`;
+    const cached = compiled.get(key);
+    if (cached !== undefined)
+        return cached;
+    const before = /^\w/.test(needle) ? "(?<![\\w$])" : "";
+    const after = /\w$/.test(needle) ? "(?![\\w$])" : "";
+    const pattern = new RegExp(`${before}${escapeRegExp(needle)}${after}`, flags);
+    if (compiled.size > 10_000)
+        compiled.clear();
+    compiled.set(key, pattern);
+    return pattern;
+}
+/** The contents of every string literal on a line. */
+export function stringLiterals(line) {
+    return [...line.matchAll(STRING_LITERAL)].map((match) => match[2] ?? "");
+}
+const lastSegment = (name) => name.slice(name.lastIndexOf(".") + 1);
+/**
+ * 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 function mentionsResource(line, ref, context) {
+    const sql = isSqlPath(context.path);
+    let needle;
+    switch (ref.kind) {
+        case "route":
+            return false;
+        case "file":
+            needle = basenameOf(ref.name);
+            break;
+        case "table":
+        case "column":
+            needle = lastSegment(ref.name);
+            break;
+        case "config": {
+            // `settings.json#hooks.PreToolUse` names the key after the file, and code
+            // spells a nested key one segment at a time, so the last segment is what
+            // a line carries.
+            const key = ref.name.includes("#") ? ref.name.slice(ref.name.indexOf("#") + 1) : ref.name;
+            needle = lastSegment(key);
+            break;
+        }
+        default:
+            needle = ref.name;
+    }
+    if (needle.length < 4)
+        return false;
+    const caseless = ref.kind === "table" || ref.kind === "column";
+    const pattern = wordPattern(needle, caseless ? "i" : "");
+    const literalOnly = (ref.kind === "table" || ref.kind === "column" || ref.kind === "file") && !sql;
+    const places = literalOnly ? stringLiterals(line) : [line];
+    for (const place of places) {
+        if (!pattern.test(place))
+            continue;
+        if (ref.kind === "column" && ref.name.includes(".")) {
+            // A bare column name is an ordinary word; it counts when its table is in sight.
+            const table = lastSegment(ref.name.slice(0, ref.name.lastIndexOf(".")));
+            const tableNamed = wordPattern(table, "i").test(place);
+            const tableInContext = context.currentTable !== undefined && lastSegment(context.currentTable) === table;
+            if (!tableNamed && !tableInContext)
+                continue;
+        }
+        return true;
+    }
+    return false;
+}
+/**
+ * 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 function resourcesMatch(mapped, changed) {
+    const a = mapped.name.toLowerCase();
+    const b = changed.name.toLowerCase();
+    const last = (name) => name.slice(name.lastIndexOf(".") + 1);
+    switch (mapped.kind) {
+        case "table":
+            if (changed.kind === "table")
+                return a === b || last(a) === last(b);
+            if (changed.kind === "column")
+                return b.startsWith(`${a}.`) || b.startsWith(`${last(a)}.`);
+            return false;
+        case "column": {
+            if (changed.kind !== "column")
+                return false;
+            if (a === b)
+                return true;
+            if (!a.includes(".") || !b.includes("."))
+                return last(a) === last(b);
+            const [tableA, columnA] = [a.slice(0, a.lastIndexOf(".")), last(a)];
+            const [tableB, columnB] = [b.slice(0, b.lastIndexOf(".")), last(b)];
+            return columnA === columnB && last(tableA) === last(tableB);
+        }
+        case "route": {
+            if (changed.kind !== "route")
+                return false;
+            const x = normalizeRoute(a);
+            const y = normalizeRoute(b);
+            return x === y || y.startsWith(`${x}/`) || x.startsWith(`${y}/`);
+        }
+        case "file":
+            if (changed.kind !== "file")
+                return false;
+            return (a === b || a.endsWith(`/${b}`) || b.endsWith(`/${a}`) || basenameOf(a) === basenameOf(b));
+        case "outbound":
+            if (changed.kind !== "outbound")
+                return false;
+            return a === b || a.endsWith(`.${b}`) || b.endsWith(`.${a}`) || a.startsWith(`${b}/`);
+        case "config": {
+            if (changed.kind !== "config")
+                return false;
+            const keyOf = (name) => name.includes("#") ? name.slice(name.indexOf("#") + 1) : name;
+            const x = keyOf(a);
+            const y = keyOf(b);
+            return x === y || x.endsWith(`.${y}`) || y.endsWith(`.${x}`);
+        }
+        default:
+            return mapped.kind === changed.kind && a === b;
+    }
+}

package/dist/risk/score.d.ts

@@ -0,0 +1,85 @@
+import { type ImportGraph } from "./import-graph.js";
+import { type Band, type BehaviorMap, type ChangeExtraction, type PromiseRisk, type RiskReport, type Signal } from "./contract.js";
+/**
+ * How much each signal counts, in the contract's order: a changed linked test
+ * and a direct hit on a mapped symbol highest, then new reach to a sink, a
+ * shared resource, forward import distance, intent clash, delta similarity,
+ * reverse import distance, and the two priors as small additions.
+ *
+ * One exported table so the evaluation can sweep it. `scoreChange` accepts a
+ * replacement.
+ */
+export declare const WEIGHTS: Readonly<Record<Signal, number>>;
+export type Weights = Readonly<Record<Signal, number>>;
+/** Forward distance d counts 1/(1+d): the mapped file itself 1, a direct import one half. */
+export declare const forwardDecay: (distance: number) => number;
+/** Reverse distance decays faster, and a mapped file is not its own dependent. */
+export declare const reverseDecay: (distance: number) => number;
+export declare const BAND_THRESHOLDS: {
+    readonly high: 0.6;
+    readonly medium: 0.3;
+};
+export declare function bandFor(score: number): Exclude<Band, "unmapped">;
+export type Prior = Readonly<{
+    /** Verified breaks of this promise recorded before; any positive count counts fully. */
+    priorBreak?: number;
+    /** Share of recent commits that touched the promise's mapped files, in [0, 1]. */
+    churn?: number;
+}>;
+export type ScoreOptions = Readonly<{
+    extraction: ChangeExtraction;
+    maps: readonly BehaviorMap[];
+    /** The import graph at head. Without it the graph signals and the closure baseline see only the mapped files themselves. */
+    graph?: ImportGraph;
+    priors?: Readonly<Record<string, Prior>>;
+    /** Every promise that should appear. Those without a map are listed as `unmapped`. */
+    promiseIds?: readonly string[];
+    weights?: Weights;
+    /** Seed for the random baseline; the head sha when absent. */
+    seed?: string;
+    /** How far the import closures reach. */
+    maxDistance?: number;
+}>;
+/**
+ * How directly a change reaches a promise, read off the features the report already carries.
+ *
+ * 3: the change edits the promise's own code or its tests: a mapped symbol changed, a linked test
+ *    changed, or a mapped file itself is among the changed files.
+ * 2: the change reaches what the promise depends on without editing its code: a sink, a resource, a
+ *    changed line elsewhere naming one of its symbols, or a stated intent that reads as its reversal.
+ * 1: anything weaker: a neighbour in the import graph, or words that resemble a failing case.
+ * 0: nothing.
+ */
+export declare function directness(features: PromiseRisk["features"]): 0 | 1 | 2 | 3;
+/**
+ * The order promises are listed in: how directly the change reaches each, then the score, then the
+ * total evidence, then the id.
+ *
+ * The score alone is not an order. Signals combine so that none can push past 1, so strong
+ * evidence saturates: in the first live evaluation (29 September 2026, 17 real regressions) four
+ * promises whose code one change had edited all scored exactly 1, and the alphabet decided which
+ * was listed first. The total evidence behind each now decides that. The same arithmetic lets
+ * several weak signals reach 0.99 as easily as one strong one; that was not seen live, where every
+ * promise listed above the broken one had its own code edited by the same change, but a change
+ * that edits a promise's code is a different kind of evidence from one that resembles it, so it
+ * is a tier and not a larger number. Scores and bands are unchanged.
+ */
+export declare function byRisk(a: PromiseRisk, b: PromiseRisk): number;
+/** The files the promise's behavior runs through, where the import closures start. Tests excluded. */
+export declare function mapSeeds(map: BehaviorMap): string[];
+/** A seeded shuffle, so the random baseline is the same list every time for the same change. */
+export declare function seededShuffle<T>(items: readonly T[], seed: string): T[];
+/**
+ * Scores one change against every behavior map.
+ *
+ * Every signal is computed per place: each changed file, and the change's
+ * stated intent as one more place. A place's signals combine as independent
+ * chances; the promise's score is the highest place's, never a sum over the
+ * change, so a fifty-file change is not riskier for being wide. Priors are then
+ * added, small, to a promise that already has some signal.
+ *
+ * `features` in the report are each signal's own maximum across places
+ * (distances their minimum), for reading. The score is not recomputable from
+ * them, because two signals from different files are never combined.
+ */
+export declare function scoreChange(options: ScoreOptions): RiskReport;