balladeer 1.0.14 → 1.0.16

package/dist/risk/score.js

@@ -0,0 +1,543 @@
+import { mapFiles } from "../behavior-map-schema.js";
+import { forwardClosure, reverseClosure } from "./import-graph.js";
+import { parseResourceRef, resourceKey, resourcesMatch } from "./resources.js";
+import { RISK_REPORT_SCHEMA_VERSION, } from "./contract.js";
+import { buildIdf, cosine, REVERSAL_CUE, words } from "./text.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 const WEIGHTS = {
+    linked_test_changed: 0.9,
+    symbol_hit: 0.9,
+    sink_reach: 0.75,
+    resource: 0.65,
+    graph_forward: 0.55,
+    intent_clash: 0.5,
+    delta_similarity: 0.45,
+    graph_reverse: 0.3,
+    prior_break: 0.08,
+    churn: 0.04,
+};
+/** Forward distance d counts 1/(1+d): the mapped file itself 1, a direct import one half. */
+export const forwardDecay = (distance) => 1 / (1 + distance);
+/** Reverse distance decays faster, and a mapped file is not its own dependent. */
+export const reverseDecay = (distance) => distance < 1 ? 0 : 1 / ((1 + distance) * (1 + distance));
+export const BAND_THRESHOLDS = { high: 0.6, medium: 0.3 };
+export function bandFor(score) {
+    if (score >= BAND_THRESHOLDS.high)
+        return "high";
+    if (score >= BAND_THRESHOLDS.medium)
+        return "medium";
+    if (score > 0)
+        return "low";
+    return "none";
+}
+const evidenceOf = (fields) => ({
+    file: fields.file ?? "",
+    symbol: fields.symbol ?? "",
+    resource: fields.resource ?? "",
+    delta: fields.delta ?? "",
+    ...(fields.caseId === undefined ? {} : { caseId: fields.caseId }),
+    ...(fields.detail === undefined ? {} : { detail: fields.detail }),
+});
+function offer(place, signal, value, evidence) {
+    if (!(value > 0))
+        return;
+    if ((place.values[signal] ?? 0) >= value)
+        return;
+    place.values[signal] = Math.min(1, value);
+    place.evidence[signal] = evidenceOf(evidence);
+}
+/**
+ * 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 function directness(features) {
+    if (features.symbol_hit >= 0.75 ||
+        features.linked_test_changed > 0 ||
+        features.graph_forward_distance === 0)
+        return 3;
+    if (features.sink_reach > 0 ||
+        features.resource_overlap > 0 ||
+        features.symbol_hit > 0 ||
+        features.intent_clash >= 0.5)
+        return 2;
+    if (features.graph_forward_distance !== null ||
+        features.graph_reverse_distance !== null ||
+        features.delta_similarity > 0 ||
+        features.intent_clash > 0)
+        return 1;
+    return 0;
+}
+/**
+ * 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 function byRisk(a, b) {
+    const evidence = (p) => p.reasons.reduce((sum, reason) => sum + reason.weight, 0);
+    return (directness(b.features) - directness(a.features) ||
+        b.score - a.score ||
+        evidence(b) - evidence(a) ||
+        a.promiseId.localeCompare(b.promiseId));
+}
+/** Independent signals combined so that none can push past 1 and more never lowers it. */
+function combine(place, weights) {
+    let miss = 1;
+    for (const [signal, value] of Object.entries(place.values)) {
+        miss *= 1 - Math.min(1, weights[signal] * value);
+    }
+    return 1 - miss;
+}
+/** The files the promise's behavior runs through, where the import closures start. Tests excluded. */
+export function mapSeeds(map) {
+    return [
+        ...new Set([
+            ...map.entryPoints.map((entry) => entry.file),
+            ...map.symbols.map((symbol) => symbol.file),
+        ]),
+    ];
+}
+function symbolNamesMatch(mapped, changed) {
+    return mapped === changed || changed.endsWith(`.${mapped}`) || mapped.endsWith(`.${changed}`);
+}
+function promiseText(map) {
+    const failingText = new Map();
+    for (const example of map.meaning?.failingExamples ?? [])
+        failingText.set(example.id, example.text);
+    for (const sink of map.sinks)
+        failingText.set(sink.caseId, `${failingText.get(sink.caseId) ?? ""} ${sink.effect}`.trim());
+    return {
+        failing: [...failingText].map(([caseId, text]) => ({ caseId, words: words(text) })),
+        nonGoals: (map.meaning?.nonGoals ?? []).map((text) => ({ text, words: words(text) })),
+        outcome: words(`${map.meaning?.title ?? ""} ${map.meaning?.observableOutcome ?? ""}`),
+    };
+}
+function corpusDocument(text) {
+    const all = new Set(text.outcome);
+    for (const failing of text.failing)
+        for (const word of failing.words)
+            all.add(word);
+    for (const nonGoal of text.nonGoals)
+        for (const word of nonGoal.words)
+            all.add(word);
+    return all;
+}
+/** Lexical signals for one place: sources against failing cases and non-goals. */
+function offerText(place, sources, text, idf, file) {
+    for (const source of sources) {
+        if (source.words.size === 0)
+            continue;
+        for (const failing of text.failing) {
+            offer(place, "delta_similarity", cosine(source.words, failing.words, idf), {
+                file,
+                delta: source.text.slice(0, 300),
+                caseId: failing.caseId,
+            });
+        }
+        // Only stated intent can clash: identifiers state nothing.
+        if (!source.stated)
+            continue;
+        for (const nonGoal of text.nonGoals) {
+            offer(place, "intent_clash", cosine(source.words, nonGoal.words, idf), {
+                file,
+                delta: source.text.slice(0, 300),
+                detail: `non_goal: ${nonGoal.text.slice(0, 200)}`,
+            });
+        }
+        if (REVERSAL_CUE.test(source.text)) {
+            offer(place, "intent_clash", cosine(source.words, text.outcome, idf), {
+                file,
+                delta: source.text.slice(0, 300),
+                detail: "reverses_outcome",
+            });
+        }
+    }
+}
+function intentLines(summary) {
+    return summary
+        .split("\n")
+        .map((line) => line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, "").trim())
+        .filter((line) => line.length > 0);
+}
+/** A seeded shuffle, so the random baseline is the same list every time for the same change. */
+export function seededShuffle(items, seed) {
+    let hash = 0x811c9dc5;
+    for (const char of seed) {
+        hash ^= char.charCodeAt(0);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    let state = hash || 1;
+    const next = () => {
+        state = (state + 0x6d2b79f5) >>> 0;
+        let t = state;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    const shuffled = [...items];
+    for (let i = shuffled.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(next() * (i + 1));
+        [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+    }
+    return shuffled;
+}
+function surfaceMatches(surface, path) {
+    const clean = surface.replace(/^\.\//, "").replace(/^\/+/, "");
+    if (clean.length === 0)
+        return true;
+    if (clean.includes("*")) {
+        const pattern = clean
+            .split("**")
+            .map((part) => part
+            .split("*")
+            .map((piece) => piece.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+            .join("[^/]*"))
+            .join(".*");
+        return new RegExp(`^${pattern}`).test(path);
+    }
+    if (clean.endsWith("/"))
+        return path.startsWith(clean);
+    return path === clean || path.startsWith(`${clean}/`);
+}
+const round = (value) => Math.round(value * 10_000) / 10_000;
+const SIGNAL_ORDER = [
+    "linked_test_changed",
+    "symbol_hit",
+    "sink_reach",
+    "resource",
+    "graph_forward",
+    "intent_clash",
+    "delta_similarity",
+    "graph_reverse",
+    "prior_break",
+    "churn",
+];
+function emptyFeatures() {
+    return {
+        symbol_hit: 0,
+        graph_forward_distance: null,
+        graph_reverse_distance: null,
+        resource_overlap: 0,
+        linked_test_changed: 0,
+        sink_reach: 0,
+        delta_similarity: 0,
+        intent_clash: 0,
+        prior_break: 0,
+        churn: 0,
+    };
+}
+/**
+ * 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 function scoreChange(options) {
+    const weights = options.weights ?? WEIGHTS;
+    const { extraction, graph } = options;
+    const maxDistance = options.maxDistance ?? 8;
+    const maps = [...new Map(options.maps.map((map) => [map.promiseId, map])).values()];
+    const texts = new Map(maps.map((map) => [map.promiseId, promiseText(map)]));
+    const idf = buildIdf([...texts.values()].map(corpusDocument));
+    const deltas = extraction.deltas ?? [];
+    const changedPaths = new Set();
+    for (const file of extraction.files) {
+        changedPaths.add(file.path);
+        if (file.oldPath !== null)
+            changedPaths.add(file.oldPath);
+    }
+    const deltaFor = (file) => deltas.filter((delta) => delta.files.some((path) => path === file.path || (file.oldPath !== null && path === file.oldPath)));
+    const unattributed = deltas.filter((delta) => !delta.files.some((path) => changedPaths.has(path)));
+    const intentSources = [
+        ...intentLines(extraction.intent?.summary ?? "").map((line) => ({
+            text: line,
+            words: words(line),
+            stated: true,
+        })),
+        ...unattributed.map((delta) => ({ text: delta.text, words: words(delta.text), stated: true })),
+    ];
+    const scored = [];
+    const importClosure = [];
+    const scopeOnly = [];
+    for (const map of maps) {
+        const text = texts.get(map.promiseId);
+        const seeds = mapSeeds(map);
+        const forward = graph === undefined
+            ? new Map(seeds.map((seed) => [seed, 0]))
+            : forwardClosure(graph, seeds, maxDistance);
+        const reverse = graph === undefined
+            ? new Map(seeds.map((seed) => [seed, 0]))
+            : reverseClosure(graph, seeds, maxDistance);
+        const mappedSymbols = [
+            ...map.symbols.map((symbol) => ({ file: symbol.file, name: symbol.name, role: symbol.role })),
+            ...map.entryPoints.map((entry) => ({
+                file: entry.file,
+                name: entry.symbol,
+                role: "core",
+            })),
+            ...map.sinks.flatMap((sink) => sink.symbols.flatMap((reference) => {
+                const hash = reference.lastIndexOf("#");
+                return hash > 0
+                    ? [
+                        {
+                            file: reference.slice(0, hash),
+                            name: reference.slice(hash + 1),
+                            role: "core",
+                        },
+                    ]
+                    : [];
+            })),
+        ];
+        // Each signal has one source: the path's resources feed `resource`, and the
+        // failing cases' sinks feed `sink_reach` alone, so neither counts the other.
+        const promiseResources = map.resources.map((resource) => ({
+            kind: resource.kind,
+            name: resource.name,
+        }));
+        const sinkResources = map.sinks.flatMap((sink) => sink.resources.flatMap((ref) => {
+            const parsed = parseResourceRef(ref);
+            return parsed === undefined ? [] : [{ caseId: sink.caseId, ref: parsed }];
+        }));
+        const places = [];
+        const features = emptyFeatures();
+        let closestForward;
+        for (const file of extraction.files) {
+            const place = { values: {}, evidence: {} };
+            const paths = file.oldPath === null ? [file.path] : [file.path, file.oldPath];
+            const here = (path) => paths.includes(path);
+            // A mapped symbol changed, or a changed line names one.
+            const named = new Set([...file.identifiersAdded, ...file.identifiersRemoved]);
+            const linkedTestHere = map.linkedTests.some((test) => here(test.file));
+            for (const mapped of mappedSymbols) {
+                if (here(mapped.file)) {
+                    for (const changed of file.symbolsChanged) {
+                        if (!symbolNamesMatch(mapped.name, changed.name))
+                            continue;
+                        offer(place, "symbol_hit", mapped.role === "core" ? 1 : 0.75, {
+                            file: file.path,
+                            symbol: changed.name,
+                            detail: changed.change,
+                        });
+                    }
+                }
+                else if (!linkedTestHere) {
+                    // A line naming the symbol elsewhere is a call site. The promise's own
+                    // linked tests call it by construction, and have their own signal.
+                    const bare = mapped.name.slice(mapped.name.lastIndexOf(".") + 1);
+                    if (bare.length >= 5 && named.has(bare)) {
+                        offer(place, "symbol_hit", 0.5, { file: file.path, symbol: bare, detail: "call_site" });
+                    }
+                }
+            }
+            // A linked test deleted, stripped of an assertion, or edited.
+            for (const test of map.linkedTests) {
+                if (!here(test.file))
+                    continue;
+                const [value, detail] = file.status === "deleted"
+                    ? [1, "deleted"]
+                    : file.guardDeletions.length > 0
+                        ? [1, "assertion_removed"]
+                        : file.hunks.length === 0
+                            ? [0.3, "renamed"]
+                            : [0.6, "modified"];
+                offer(place, "linked_test_changed", value, {
+                    file: file.path,
+                    symbol: test.name,
+                    detail,
+                });
+            }
+            // New reach to a sink: the file names a sink resource it did not name before.
+            for (const sink of sinkResources) {
+                for (const changed of file.resources) {
+                    if (changed.change !== "added" || !resourcesMatch(sink.ref, changed))
+                        continue;
+                    offer(place, "sink_reach", 1, {
+                        file: file.path,
+                        resource: resourceKey(sink.ref),
+                        caseId: sink.caseId,
+                        detail: "new_reach",
+                    });
+                }
+            }
+            // A resource the promise depends on, named by the change.
+            for (const mapped of promiseResources) {
+                for (const changed of file.resources) {
+                    if (!resourcesMatch(mapped, changed))
+                        continue;
+                    offer(place, "resource", 1, {
+                        file: file.path,
+                        resource: resourceKey(mapped),
+                        detail: changed.change,
+                    });
+                }
+            }
+            // Import distance, both ways.
+            const forwardDistance = Math.min(...paths.map((path) => forward.get(path) ?? Infinity));
+            if (Number.isFinite(forwardDistance)) {
+                offer(place, "graph_forward", forwardDecay(forwardDistance), {
+                    file: file.path,
+                    detail: `distance:${forwardDistance}`,
+                });
+                closestForward = Math.min(closestForward ?? Infinity, forwardDistance);
+                features.graph_forward_distance = Math.min(features.graph_forward_distance ?? Infinity, forwardDistance);
+            }
+            const reverseDistance = Math.min(...paths.map((path) => reverse.get(path) ?? Infinity));
+            if (Number.isFinite(reverseDistance)) {
+                offer(place, "graph_reverse", reverseDecay(reverseDistance), {
+                    file: file.path,
+                    detail: `distance:${reverseDistance}`,
+                });
+                features.graph_reverse_distance = Math.min(features.graph_reverse_distance ?? Infinity, reverseDistance);
+            }
+            // What the change says it does, against the failing cases and non-goals.
+            const fileDeltas = deltaFor(file);
+            const sources = deltas.length > 0
+                ? fileDeltas.map((delta) => ({
+                    text: delta.text,
+                    words: words(delta.text),
+                    stated: true,
+                }))
+                : [
+                    {
+                        text: [...named].slice(0, 12).join(" "),
+                        words: words([...named].join(" ")),
+                        stated: false,
+                    },
+                ];
+            offerText(place, sources, text, idf, file.path);
+            places.push(place);
+        }
+        const intentPlace = { values: {}, evidence: {} };
+        offerText(intentPlace, intentSources, text, idf, "");
+        places.push(intentPlace);
+        // The highest place, never a sum.
+        let best = 0;
+        for (const place of places)
+            best = Math.max(best, combine(place, weights));
+        // Features and reasons: each signal's strongest place.
+        const strongest = new Map();
+        for (const place of places) {
+            for (const [signal, value] of Object.entries(place.values)) {
+                const contribution = weights[signal] * value;
+                const current = strongest.get(signal);
+                if (current !== undefined && current.contribution >= contribution)
+                    continue;
+                strongest.set(signal, {
+                    contribution,
+                    value,
+                    evidence: place.evidence[signal],
+                });
+            }
+        }
+        features.symbol_hit = round(strongest.get("symbol_hit")?.value ?? 0);
+        features.resource_overlap = round(strongest.get("resource")?.value ?? 0);
+        features.linked_test_changed = round(strongest.get("linked_test_changed")?.value ?? 0);
+        features.sink_reach = round(strongest.get("sink_reach")?.value ?? 0);
+        features.delta_similarity = round(strongest.get("delta_similarity")?.value ?? 0);
+        features.intent_clash = round(strongest.get("intent_clash")?.value ?? 0);
+        const prior = options.priors?.[map.promiseId];
+        features.prior_break = Math.max(0, prior?.priorBreak ?? 0);
+        features.churn = round(Math.min(1, Math.max(0, prior?.churn ?? 0)));
+        let score = best;
+        if (best > 0) {
+            const breakValue = Math.min(1, features.prior_break);
+            if (breakValue > 0) {
+                score += weights.prior_break * breakValue;
+                strongest.set("prior_break", {
+                    contribution: weights.prior_break * breakValue,
+                    value: breakValue,
+                    evidence: evidenceOf({ detail: `broken_before:${features.prior_break}` }),
+                });
+            }
+            if (features.churn > 0) {
+                score += weights.churn * features.churn;
+                strongest.set("churn", {
+                    contribution: weights.churn * features.churn,
+                    value: features.churn,
+                    evidence: evidenceOf({ detail: `churn:${features.churn}` }),
+                });
+            }
+        }
+        score = round(Math.min(1, score));
+        const reasons = [...strongest.entries()]
+            .filter(([, entry]) => entry.contribution > 0)
+            .sort((a, b) => b[1].contribution - a[1].contribution ||
+            SIGNAL_ORDER.indexOf(a[0]) - SIGNAL_ORDER.indexOf(b[0]))
+            .map(([signal, entry]) => ({
+            signal,
+            weight: round(Math.min(1, entry.contribution)),
+            evidence: entry.evidence,
+        }));
+        scored.push({
+            promiseId: map.promiseId,
+            ...(map.meaning?.title === undefined ? {} : { title: map.meaning.title }),
+            score,
+            band: bandFor(score),
+            reasons,
+            features,
+        });
+        if (closestForward !== undefined)
+            importClosure.push({ promiseId: map.promiseId, distance: closestForward });
+        const surfaces = map.meaning?.surfaces ?? [];
+        const inScope = surfaces.length > 0
+            ? [...changedPaths].some((path) => surfaces.some((surface) => surfaceMatches(surface, path)))
+            : mapFiles(map).some((path) => changedPaths.has(path));
+        if (inScope)
+            scopeOnly.push(map.promiseId);
+    }
+    const mappedIds = new Set(maps.map((map) => map.promiseId));
+    const unmapped = [...new Set(options.promiseIds ?? [])]
+        .filter((id) => !mappedIds.has(id))
+        .sort()
+        .map((promiseId) => ({
+        promiseId,
+        score: 0,
+        band: "unmapped",
+        reasons: [],
+        features: emptyFeatures(),
+    }));
+    const ordered = [...scored.sort(byRisk), ...unmapped];
+    const all = [...mappedIds].sort();
+    return {
+        schemaVersion: RISK_REPORT_SCHEMA_VERSION,
+        base: extraction.base,
+        head: extraction.head,
+        promises: ordered,
+        baselines: {
+            scope_only: scopeOnly.sort(),
+            import_closure: importClosure
+                .sort((a, b) => a.distance - b.distance || a.promiseId.localeCompare(b.promiseId))
+                .map((entry) => entry.promiseId),
+            all,
+            random: seededShuffle(all, options.seed ?? extraction.head),
+        },
+    };
+}

package/dist/risk/symbols.d.ts

@@ -0,0 +1,35 @@
+import type ts from "typescript";
+import type { SymbolExtractor, SymbolKind } from "./contract.js";
+/**
+ * Where each named thing in a file starts and ends, by line.
+ *
+ * TypeScript and JavaScript are parsed with the repository's own TypeScript
+ * compiler when it has one, one file at a time with no program, so it is a
+ * syntax read and never a type check.
+ * Python is read by indentation after `def` and `class`. Every other language
+ * gets a declaration regex and a symbol runs until the next declaration.
+ */
+export type DeclaredSymbol = Readonly<{
+    name: string;
+    kind: SymbolKind;
+    /** 1-based, inclusive. */
+    startLine: number;
+    endLine: number;
+}>;
+type TypeScriptModule = typeof ts;
+/**
+ * The TypeScript compiler of the repository being read, resolved from its root
+ * the way its own tools resolve it. The published command ships no compiler and
+ * never imports one: a TypeScript repository nearly always has its own, and one
+ * without it has its script files read by the declaration pattern instead.
+ * Looked up once per repository.
+ */
+export declare function loadTypeScript(root: string | undefined): TypeScriptModule | undefined;
+/** Every symbol declared in a file, with its line range, and which reader found them. */
+export declare function declaredSymbols(path: string, text: string, root?: string): {
+    symbols: DeclaredSymbol[];
+    extractor: SymbolExtractor;
+};
+/** The symbols whose range contains any of the given lines. */
+export declare function symbolsAtLines(symbols: readonly DeclaredSymbol[], lines: ReadonlySet<number>): DeclaredSymbol[];
+export {};