mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/findings/semantic-issue-search.js

@@ -1,38 +1,17 @@
 /**
- * lib/findings/semantic-issue-search.js — Semantic candidate search for findings.
- *
- * Dedup has two stages. This module owns the **first** stage: a meaning-first
- * candidate search that surfaces issues likely to describe the same problem as
- * a finding, *before* the exact fingerprint confirmation in
- * `route-finding.js` runs. The fingerprint is precise but brittle — a reworded
- * title or a moved file produces a fresh sha even when the underlying problem
- * is the same. The semantic pass casts a wider net so the confirmation stage
- * has the right candidates to inspect.
- *
- * The search scans BOTH open and closed issues, and explicitly includes the
- * sub-issues of any in-scope Epic (a regression that was closed under a prior
- * Epic, or a still-open sibling Story, must be reachable). Epic sub-issues are
- * fetched through the same injected port so a closed-then-reopened problem is
- * never missed.
- *
- * Pure orchestration: no network I/O lives here. The `search` port — and the
- * optional `listEpicSubIssues` port — are injected by the caller (production
- * wires them to the GitHub provider; tests pass in-memory stubs). The unit
- * test for this module performs no network calls.
+ * lib/findings/semantic-issue-search.js — meaning-first candidate search that
+ * widens the pool `route-finding.js` confirms, catching drifted fingerprints.
+ * Ports are injected.
  */
 
 const DEFAULT_LIMIT = 25;
 
 /**
- * Character budget for the query {@link buildQuery} emits. Default 200 leaves
- * headroom under GitHub Search's 256-char limit for the `repo:` / `type:`
- * qualifiers `searchIssues` appends (Story #4678).
+ * Headroom under GitHub Search's 256-char limit for appended qualifiers.
  */
 const DEFAULT_QUERY_BUDGET = 200;
 
 /**
- * Normalise a free-text string for token comparison: lowercased, trimmed,
- * punctuation collapsed to spaces.
  * @param {unknown} value
  * @returns {string}
  */
@@ -45,8 +24,6 @@ function normaliseText(value) {
 }
 
 /**
- * Tokenise normalised text into a Set of words, dropping very short noise
- * tokens that carry no discriminating signal.
  * @param {string} text
  * @returns {Set<string>}
  */
@@ -59,8 +36,7 @@ function tokenize(text) {
 }
 
 /**
- * Jaccard similarity between two token sets. Returns 0 when either set is
- * empty so an empty query never spuriously matches.
+ * 0 when either set is empty, so an empty query never matches.
  * @param {Set<string>} a
  * @param {Set<string>} b
  * @returns {number} similarity in [0, 1]
@@ -76,10 +52,7 @@ function jaccard(a, b) {
 }
 
 /**
- * The trailing path segment of a slash-or-backslash-delimited path. A deep
- * `primaryFile` like `src/very/deep/module.js` contributes only `module.js`
- * to the query — the basename carries the discriminating signal while the
- * mangled path spends the character budget for nothing (Story #4678).
+ * Only the basename carries signal; the full path would waste query budget.
  * @param {unknown} value
  * @returns {string}
  */
@@ -90,12 +63,8 @@ function basename(value) {
 }
 
 /**
- * Build the search query text for a finding. The title carries the strongest
- * signal; area and the primaryFile **basename** sharpen it. This is the text
- * both the (production) full-text search port and the local relevance scorer
- * key on. The result is filled highest-signal-first (title, then area, then
- * basename) up to `budget` characters on a whole-token boundary so a long title
- * over a deep path never blows GitHub Search's length limit (Story #4678).
+ * Title, area, file basename — highest signal first, cut to `budget` on a
+ * token boundary.
  * @param {object} finding
  * @param {object} [options]
  * @param {number} [options.budget] — max query length in characters.
@@ -121,9 +90,7 @@ export function buildQuery(finding, { budget = DEFAULT_QUERY_BUDGET } = {}) {
 }
 
 /**
- * Score a candidate issue against the finding's query tokens. Title overlap
- * dominates; body overlap is a weaker secondary signal so a verbose body
- * cannot drown out a precise title match.
+ * Title overlap dominates so a verbose body cannot drown a precise title.
  * @param {Set<string>} queryTokens
  * @param {{ title?: string, body?: string }} issue
  * @returns {number} relevance score in [0, 1]
@@ -135,7 +102,6 @@ function scoreIssue(queryTokens, issue) {
 }
 
 /**
- * De-duplicate issue records by `number`, keeping the first occurrence.
  * @param {Array<{ number?: number }>} issues
  * @returns {Array<object>}
  */
@@ -152,28 +118,17 @@ function dedupeByNumber(issues) {
 }
 
 /**
- * Find semantically-similar candidate issues for a finding.
+ * Candidates scored locally by token overlap, best-first.
  *
- * The `search` port runs the host's issue search (production: GitHub
- * full-text search across open AND closed issues). When an `epicId` is in
- * scope and a `listEpicSubIssues` port is supplied, that Epic's sub-issues
- * are folded into the candidate pool so a regression closed under a prior
- * Epic — or an open sibling Story — is never missed. The pooled candidates
- * are scored locally by token overlap and returned best-first.
- *
- * @param {object} finding — canonical finding ({ title, area, primaryFile, ... }).
+ * @param {object} finding
  * @param {object} ports
  * @param {(query: string) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} ports.search
- *   Required. Queries both open and closed issues for the finding's query text.
  * @param {(epicId: number) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [ports.listEpicSubIssues]
- *   Optional. Lists the sub-issues of the in-scope Epic.
  * @param {object} [options]
- * @param {number|null} [options.epicId] — Epic whose sub-issues to include.
- * @param {number} [options.limit] — max candidates to return (default 25).
- * @param {number} [options.minScore] — drop candidates scoring below this
- *   (default 0; every scanned issue is a candidate).
+ * @param {number|null} [options.epicId]
+ * @param {number} [options.limit]
+ * @param {number} [options.minScore]
  * @returns {Promise<Array<{ number: number, state: string, title?: string, body?: string, score: number }>>}
- *   candidates sorted by descending relevance score.
  */
 export async function searchSemanticCandidates(
   finding,

package/.agents/scripts/lib/findings/severity.js

@@ -1,30 +1,10 @@
 /**
- * lib/findings/severity.js — Canonical severity vocabulary for the findings core.
- *
- * Single source of truth for finding severity (Story #3816). Three modules in
- * the shared findings core previously each declared their own severity list —
- * `classify-finding.js` (`[unknown, low, medium, high, critical]`),
- * `promote-finding.js` (`SEVERITY_RANK` over `[critical … info]`), and the
- * `qa-ledger` JSON schema (`[critical, high, medium, low, info]`). Because
- * `severity` is a `fingerprintFinding` identity field
- * (`route-finding.js`), the same finding could hash to different SHAs depending
- * on which path normalised its severity, silently weakening dedup. This module
- * collapses all three onto one enum + one normaliser so the fingerprint is
- * stable regardless of the code path that produced the severity.
- *
- * The canonical order is `critical | high | medium | low | info`, highest →
- * lowest, and it MUST match the `severity` enum in
- * `.agents/schemas/qa-ledger.schema.json`. Pure module: no I/O, no
- * module-level state beyond the frozen constants.
+ * lib/findings/severity.js — the one severity vocabulary. Severity is a
+ * fingerprint field, so every path must normalise it identically. Order MUST
+ * match the `severity` enum in `qa-ledger.schema.json`.
  */
 
-/**
- * The closed, canonical set of severity values, ordered highest → lowest.
- * This is the ONLY definition of the severity vocabulary in the findings core;
- * `classify-finding.js` and `promote-finding.js` re-export / import it rather
- * than re-declaring their own list. Mirrors the `severity` enum in
- * `qa-ledger.schema.json`.
- */
+/** Highest → lowest. */
 export const SEVERITIES = Object.freeze([
   'critical',
   'high',
@@ -33,34 +13,11 @@ export const SEVERITIES = Object.freeze([
   'info',
 ]);
 
-/**
- * The severity applied when a finding carries no recognisable severity. `info`
- * is the canonical floor (lowest level). The ledger/finding schemas REQUIRE a
- * severity drawn from {@link SEVERITIES}, so this fallback only fires on
- * malformed input — and because both the classify and promote paths share it,
- * malformed input still fingerprints identically across the two paths.
- */
 const DEFAULT_SEVERITY = 'info';
 
 const SEVERITY_SET = new Set(SEVERITIES);
 
-/**
- * Non-canonical spellings that resolve onto a canonical level (Story #4877).
- *
- * The vocabulary drifted because four modules each carried their own partial
- * copy of it: `audit-to-stories/parse-audit-md.js` recognised
- * `critical|high|medium|mod|moderate|low` and nothing else, `audit-to-stories.js`
- * ranked `critical|high|medium|low`, and `audit-to-stories/seed-from-findings.js`
- * ordered the same four. None of them knew `info` — the canonical floor — so an
- * `Info` / `Informational` finding parsed to `null`, tallied as `unknown`, and
- * was dropped by EVERY severity-filtered run (including `--severity low`).
- * Folding the alias table in here makes this module the only place the
- * vocabulary is written down.
- *
- * Keys are already lower-cased and trimmed by {@link normalizeSeverity}.
- *
- * @type {Readonly<Record<string, string>>}
- */
+/** @type {Readonly<Record<string, string>>} */
 const SEVERITY_ALIASES = Object.freeze({
   blocker: 'critical',
   major: 'high',
@@ -72,13 +29,7 @@ const SEVERITY_ALIASES = Object.freeze({
   trivial: 'info',
 });
 
-/**
- * Numeric rank for "highest severity wins" comparisons, derived from the
- * canonical order so the ranking has exactly one source. `critical` is the
- * highest rank (`SEVERITIES.length - 1`); `info` is `0`.
- *
- * @type {Readonly<Record<string, number>>}
- */
+/** @type {Readonly<Record<string, number>>} */
 export const SEVERITY_RANK = Object.freeze(
   Object.fromEntries(
     SEVERITIES.map((severity, index) => [
@@ -89,15 +40,11 @@ export const SEVERITY_RANK = Object.freeze(
 );
 
 /**
- * Normalise an arbitrary severity input to one of {@link SEVERITIES}. Case- and
- * whitespace-insensitive. A non-string, empty, or unrecognised value resolves
- * to `fallback` (default {@link DEFAULT_SEVERITY}) rather than throwing — the
- * findings pipeline treats severity as advisory signal, never a hard gate.
+ * Never throws — severity is advisory, never a gate.
  *
- * @param {unknown} value — the raw severity field off a finding/ledger item.
- * @param {string} [fallback=DEFAULT_SEVERITY] — canonical value to return when
- *   `value` is absent or unrecognised.
- * @returns {string} one of {@link SEVERITIES}.
+ * @param {unknown} value
+ * @param {string} [fallback=DEFAULT_SEVERITY]
+ * @returns {string}
  */
 export function normalizeSeverity(value, fallback = DEFAULT_SEVERITY) {
   if (typeof value !== 'string') return fallback;
@@ -107,33 +54,12 @@ export function normalizeSeverity(value, fallback = DEFAULT_SEVERITY) {
 }
 
 /**
- * The **identity projection** of a severity, for use inside a finding
- * fingerprint — and nowhere else (Story #4877).
- *
- * `severity` is a `fingerprintFinding` identity field
- * (`route-finding.js`), so whatever this returns is folded into the sha that
- * deduplicates findings against already-filed Issues. That makes the severity
- * pipeline and the severity *identity* two different jobs with two different
- * failure modes:
+ * Fingerprint-only projection: absent stays `''` and unknown passes through,
+ * so no filed fingerprint moves; aliases resolve, so the hash is invariant
+ * under normalisation.
  *
- * - {@link normalizeSeverity} resolves an absent or unrecognised severity to
- *   `info` so downstream filtering and tallies have a level to work with.
- * - This function must NOT. Folding `info` in where the previous
- *   implementation folded the empty string would re-mint the fingerprint of
- *   every finding that carries no severity, silently breaking dedup for all of
- *   them. An absent severity therefore stays the empty string, exactly as the
- *   raw `String(value).toLowerCase().trim()` it replaces produced.
- *
- * What it *does* change is alias resolution: `Informational` and `info` project
- * onto the same `info`, so the fingerprint is **invariant** under the
- * normalization this Story introduces — a finding hashes the same whether it is
- * fingerprinted before or after {@link normalizeSeverity} has run over it. An
- * unrecognised non-empty value is passed through verbatim rather than collapsed,
- * again so no already-filed fingerprint moves.
- *
- * @param {unknown} value — the raw severity field off a finding.
- * @returns {string} a canonical level, the empty string when absent, or the
- *   lower-cased raw value when it is neither canonical nor a known alias.
+ * @param {unknown} value
+ * @returns {string}
  */
 export function fingerprintSeverity(value) {
   if (typeof value !== 'string') return '';
@@ -143,13 +69,8 @@ export function fingerprintSeverity(value) {
 }
 
 /**
- * The highest-ranked severity across a list of raw severity values. Returns
- * {@link DEFAULT_SEVERITY} for an empty list. Each value is normalised through
- * {@link normalizeSeverity}, so the result is always one of {@link SEVERITIES}.
- *
- * @param {Iterable<unknown>} values — raw severity strings (or anything
- *   `normalizeSeverity` accepts).
- * @returns {string} one of {@link SEVERITIES}.
+ * @param {Iterable<unknown>} values
+ * @returns {string}
  */
 export function highestSeverity(values) {
   let best = DEFAULT_SEVERITY;
@@ -165,14 +86,7 @@ export function highestSeverity(values) {
   return best;
 }
 
-/**
- * Internals reached by the unit tests only. The floor and the alias table are
- * consumed exclusively by this module's own exported functions, so they are
- * not public API — but the alias table carries a structural invariant (no
- * alias shadows a canonical level, every target IS one) that cannot be proven
- * through `normalizeSeverity` alone, since that function returns a canonical
- * value by construction.
- */
+/** Test-only: the alias-table invariant is unobservable via the API. */
 export const __testing = {
   DEFAULT_SEVERITY,
   SEVERITY_ALIASES,

package/.agents/scripts/lib/format-generated-json.js

@@ -1,40 +1,19 @@
 /**
- * format-generated-json.js — run generated JSON through the project
- * formatter (Biome) so a generator's output matches what the repo's
- * commit-time formatting would have produced anyway.
- *
- * Why this exists. Generators serialize with `JSON.stringify`, which
- * expands every array across multiple lines. Biome collapses short ones
- * that fit inside `lineWidth` (`"allowedTools": ["Read", "Bash"]`), and
- * lint-staged runs `biome format --write` over staged JSON at commit
- * time — so the committed artifact is Biome-shaped while a fresh
- * generator run is not. The gap means regenerating on a clean tree
- * always leaves format drift, and a `<generate>` → `lint` sequence fails
- * on `biome ci` even when the generator's own `--check` reports the
- * artifact semantically fresh (Story #4546).
- *
- * Running the real formatter, rather than hand-matching its array
- * collapsing, keeps this correct by construction across future formatter
- * and `lineWidth` changes.
- *
- * Stdin mode is deliberate: Biome's configured `formatWrite` command is
- * whole-tree (`biome format --write .`), which is a far broader side
- * effect than a generator should have. `--stdin-file-path` makes this a
- * pure content transform with no filesystem writes.
+ * format-generated-json.js — run generated JSON through Biome so a fresh
+ * generator run matches the Biome-shaped committed artifact (lint-staged
+ * formats at commit; `JSON.stringify` does not collapse short arrays).
+ * Stdin mode keeps it a pure transform — the configured `formatWrite` is
+ * whole-tree.
  */
 
 import { spawnSync } from 'node:child_process';
 import process from 'node:process';
 import { Logger } from './Logger.js';
 
-/** Wall-clock ceiling for the formatter spawn, so a hung child cannot wedge a generator run. */
+/** A hung formatter must not wedge a generator run. */
 const FORMATTER_TIMEOUT_MS = 30_000;
 
-/**
- * Warn once about a fallback and return null for the caller to act on.
- * Owning the message here keeps every caller's write path a single
- * `formatGeneratedJson(...) ?? serialized` expression.
- */
+/** Callers write `formatGeneratedJson(...) ?? serialized`. */
 function fallback(filename) {
   Logger.warn(
     `project formatter (biome) unavailable — writing unformatted ${filename}; ` +
@@ -44,20 +23,10 @@ function fallback(filename) {
 }
 
 /**
- * Format `source` as JSON using the project formatter.
- *
- * Best-effort by design: `.agents/` is materialized into consumer
- * projects that need not have Biome installed, so an unavailable or
- * failing formatter warns and returns `null` for the caller to fall back
- * on its own serialization rather than failing the generator. That is
- * safe wherever the artifact's freshness check compares parsed objects
- * rather than bytes — formatting carries no semantic content.
- *
- * `--no` keeps npx from reaching the network to install a missing Biome.
- * `filename` is passed as a bare basename: Biome only needs it to infer
- * the language and match config overrides, and a basename cannot carry
- * the spaces that would break arg quoting under the Windows `shell:
- * true` spawn.
+ * Best-effort: consumers may lack Biome, so failure warns and returns `null`
+ * — safe where freshness compares parsed objects, not bytes. `--no` stops
+ * npx installing from the network; `filename` is a bare basename so it
+ * cannot carry spaces that break Windows shell quoting.
  *
  * @param {string} source Text to format.
  * @param {object} opts
@@ -79,8 +48,7 @@ export function formatGeneratedJson(
         cwd,
         input: source,
         encoding: 'utf8',
-        // npm/npx ship as `.cmd` shims on Windows, which Node refuses to
-        // spawn without a shell since CVE-2024-27980.
+        // `.cmd` shims need a shell on Windows since CVE-2024-27980.
         shell: process.platform === 'win32',
         timeout: FORMATTER_TIMEOUT_MS,
       },