mandrel 1.57.0

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -0,0 +1,130 @@
+/**
+ * lib/audit-to-stories/build-story-body.js
+ *
+ * Render the canonical Story body for the standalone grouping mode. The
+ * body follows the contract spelled out in Story #2583 acceptance
+ * criteria #8: Title (caller), Summary, Acceptance Criteria, Agent
+ * Prompts, Context block, fingerprint footer.
+ *
+ * Pure: returns { title, body, labels }. Labels include every
+ * `audit::<dimension>` represented in the merge plus the standard
+ * `type::story`, `agent::ready`, and (when any finding is Critical)
+ * `risk::high`.
+ *
+ * The body is serialized via the canonical story-body serializer
+ * (`.agents/scripts/lib/story-body/story-body.js`) so the output is
+ * parseable by `parse()` and round-trippable. Audit-specific content
+ * (agent prompts, context links, fingerprint footer) is appended after
+ * the canonical sections as extended markdown.
+ */
+
+import { serialize } from '../story-body/story-body.js';
+import { renderFingerprintFooter } from './finding-adapter.js';
+
+const STATIC_LABELS = Object.freeze(['type::story', 'agent::ready']);
+
+function uniq(items) {
+  return [...new Set(items)];
+}
+
+function summaryFromGroup(group) {
+  const lines = group.findings.map((f, idx) => {
+    const sev = f.severity ? `[${f.severity.toUpperCase()}]` : '[—]';
+    const dim = f.dimension ? `(${f.dimension})` : '';
+    return `${idx + 1}. ${sev} ${dim} **${f.title}** — ${
+      f.currentState || '_(no current-state captured)_'
+    }`;
+  });
+  return lines.join('\n');
+}
+
+function goalFromGroup(group) {
+  // Derive a concise goal statement from the group title + finding summary.
+  const summary = summaryFromGroup(group);
+  return `${group.title}\n\n${summary}`;
+}
+
+function acceptanceCriteriaFromGroup(group) {
+  return group.findings.map((f) => {
+    const rec = f.recommendation || '_(no recommendation captured)_';
+    return `${f.title} — ${rec}`;
+  });
+}
+
+function agentPromptsSection(group) {
+  const blocks = group.findings
+    .filter(
+      (f) => typeof f.agentPrompt === 'string' && f.agentPrompt.length > 0,
+    )
+    .map((f) => `**${f.title}**\n\n\`\`\`\n${f.agentPrompt}\n\`\`\``);
+  return blocks.join('\n\n') || '_(no copy-pasteable prompts captured)_';
+}
+
+function contextLinksFromGroup(group) {
+  const reports = uniq(
+    group.findings
+      .map((f) => f.sourceReport)
+      .filter((s) => typeof s === 'string'),
+  );
+  if (reports.length === 0) return '_(no source audit reports captured)_';
+  return reports.map((r) => `- [\`${r}\`](${r})`).join('\n');
+}
+
+function labelsForGroup(group) {
+  const auditLabels = uniq(
+    (group.dimensions ?? []).map((d) => `audit::${d.replace(/\s+/g, '-')}`),
+  );
+  const labels = [...STATIC_LABELS, ...auditLabels];
+  const hasCritical = (group.findings ?? []).some(
+    (f) => f.severity === 'critical',
+  );
+  if (hasCritical) labels.push('risk::high');
+  return uniq(labels);
+}
+
+/**
+ * @param {object} params
+ * @param {object} params.group — output of `groupFindings` (one entry).
+ * @returns {{ title: string, body: string, labels: string[] }}
+ */
+export function buildStoryBody({ group }) {
+  if (!group || !Array.isArray(group.findings)) {
+    throw new Error('buildStoryBody: group with findings[] is required');
+  }
+  const title = group.title;
+
+  // Build the canonical StoryBody object from the audit group data.
+  const storyBody = {
+    goal: goalFromGroup(group),
+    changes: [],
+    acceptance: acceptanceCriteriaFromGroup(group),
+    verify: [],
+    references: [],
+    wide: null,
+    depends_on: [],
+    estimated_test_files: null,
+  };
+
+  // Serialize via the canonical serializer.
+  const canonicalSections = serialize(storyBody);
+
+  // Append audit-specific extended sections (agent prompts, context links,
+  // fingerprint footer) that are not part of the canonical shape.
+  const body = [
+    canonicalSections,
+    '',
+    '## Agent Prompts',
+    '',
+    agentPromptsSection(group),
+    '',
+    '## Context',
+    '',
+    'This Story was opened by `/audit-to-stories` from the following audit reports:',
+    '',
+    contextLinksFromGroup(group),
+    '',
+    renderFingerprintFooter(group.findings),
+  ].join('\n');
+
+  return { title, body, labels: labelsForGroup(group) };
+}

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -0,0 +1,114 @@
+/**
+ * lib/audit-to-stories/dedupe-against-github.js
+ *
+ * Idempotency gate: classify each proposed group as either eligible-to-create,
+ * already-open (skip), or re-occurring (skip, but flag).
+ *
+ * This module owns **no** fingerprint or dedup logic. It routes every
+ * finding through the shared `lib/findings/route-finding.js` helper — the
+ * single dedup/route implementation, shared verbatim with `qa-explore` — and
+ * folds the per-finding `routeFinding` decisions up to a group action:
+ *
+ *   - any finding routes to `update-existing` / `duplicate` → `skip-open`
+ *   - else any finding routes to `regression-of-closed`     → `skip-reoccurring`
+ *   - else (every finding is `new`)                          → `create`
+ *
+ * The GitHub lookup is delegated to a `provider` port the caller injects,
+ * exposing `findIssuesByFingerprint(sha)` → `{ number, state, body }[]`. The
+ * port is adapted into the `searchIssues` shape the shared helper expects.
+ *
+ * Pure orchestration: this module performs no network I/O itself.
+ */
+
+import { routeFinding } from '../findings/route-finding.js';
+import { toCanonicalFinding } from './finding-adapter.js';
+
+/**
+ * @typedef {object} GroupClassification
+ * @property {object} group — the original Group object.
+ * @property {'create'|'skip-open'|'skip-reoccurring'} action
+ * @property {{ number: number, state: string }[]} matchedIssues
+ * @property {string[]} matchedFingerprints — full sha1 list that triggered the match.
+ */
+
+/**
+ * @param {object} params
+ * @param {Array<object>} params.groups — output of `groupFindings`.
+ * @param {{ findIssuesByFingerprint: (sha: string) => Promise<Array<{ number: number, state: string, body?: string }>> }} params.provider
+ * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number } }>}
+ */
+export async function classifyGroupsAgainstGitHub({ groups, provider }) {
+  if (!Array.isArray(groups)) {
+    throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
+  }
+  if (!provider || typeof provider.findIssuesByFingerprint !== 'function') {
+    throw new Error(
+      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required',
+    );
+  }
+
+  // Adapt the provider port into the `searchIssues` shape routeFinding wants.
+  // routeFinding hands the port the sha it computed off the canonical
+  // projection, which equals the sha the group already carries (both come
+  // from the same `toCanonicalFinding` projection).
+  const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
+
+  const classifications = [];
+  const summary = { create: 0, skipOpen: 0, skipReoccurring: 0 };
+
+  for (const group of groups) {
+    const findings = group.findings ?? [];
+
+    const matchedIssues = [];
+    const matchedFingerprints = [];
+    let sawOpen = false;
+    let sawClosed = false;
+
+    for (const finding of findings) {
+      const sha = finding?.fingerprint?.full;
+      if (typeof sha !== 'string' || sha.length !== 40) continue;
+
+      const { decision, matchedIssue, fingerprint } = await routeFinding(
+        toCanonicalFinding(finding),
+        { searchIssues },
+      );
+
+      if (decision === 'new') continue;
+
+      if (matchedIssue) {
+        matchedIssues.push({
+          number: matchedIssue.number,
+          state: matchedIssue.state,
+        });
+      }
+      if (!matchedFingerprints.includes(fingerprint)) {
+        matchedFingerprints.push(fingerprint);
+      }
+      if (decision === 'update-existing' || decision === 'duplicate') {
+        sawOpen = true;
+      } else if (decision === 'regression-of-closed') {
+        sawClosed = true;
+      }
+    }
+
+    let action = 'create';
+    if (sawOpen) {
+      action = 'skip-open';
+      summary.skipOpen += 1;
+    } else if (sawClosed) {
+      action = 'skip-reoccurring';
+      summary.skipReoccurring += 1;
+    } else {
+      summary.create += 1;
+    }
+
+    classifications.push({
+      group,
+      action,
+      matchedIssues,
+      matchedFingerprints,
+    });
+  }
+
+  return { classifications, summary };
+}

package/.agents/scripts/lib/audit-to-stories/finding-adapter.js

@@ -0,0 +1,93 @@
+/**
+ * lib/audit-to-stories/finding-adapter.js — Project audit findings onto the
+ * shared findings identity.
+ *
+ * `/audit-to-stories` parses `audit-*-results.md` into findings shaped as
+ * `{ dimension, severity, title, normalisedTitle, files, ... }`. The shared
+ * dedup/route helper (`lib/findings/route-finding.js`) fingerprints over the
+ * canonical identity `{ title, area, primaryFile, severity, labels }`. This
+ * module is the thin, audit-specific adapter that maps the former onto the
+ * latter and reuses the shared helper's primitives — it contains **no**
+ * fingerprint or dedup logic of its own. The single dedup/route
+ * implementation lives in `lib/findings/route-finding.js`, shared verbatim
+ * with `qa-explore`.
+ */
+
+import {
+  fingerprintFinding,
+  fingerprintFooter,
+} from '../findings/route-finding.js';
+
+/**
+ * Map an audit finding onto the canonical identity the shared helper
+ * fingerprints over. The audit pipeline already lower-cases `dimension` and
+ * normalises the title; `files[0]` is the primary file the parser pulled
+ * from the finding body. `dimension` is the identity axis (carried as
+ * `area`) and also the sole label so two findings in the same dimension that
+ * are otherwise identical collide exactly as the legacy
+ * `(dimension, normalisedTitle, primaryFile)` key did.
+ *
+ * @param {{ dimension?: string, normalisedTitle?: string, files?: string[] }} finding
+ * @returns {{ title: string, area: string, primaryFile: string, severity: string, labels: string[] }}
+ */
+export function toCanonicalFinding(finding) {
+  const dimension = finding?.dimension ?? '';
+  const primaryFile =
+    Array.isArray(finding?.files) && finding.files.length > 0
+      ? finding.files[0]
+      : '';
+  return {
+    title: finding?.normalisedTitle ?? '',
+    area: dimension,
+    primaryFile,
+    severity: '',
+    labels: dimension ? [dimension] : [],
+  };
+}
+
+/**
+ * Compute the shared-helper fingerprint for a single audit finding.
+ *
+ * @param {object} finding
+ * @returns {{ short: string, full: string, components: object }}
+ */
+export function fingerprintAuditFinding(finding) {
+  return fingerprintFinding(toCanonicalFinding(finding));
+}
+
+/**
+ * Stamp every audit finding with its shared-helper fingerprint and return a
+ * new array. Mirrors the legacy `withFingerprints` contract so downstream
+ * grouping / story-body / dedupe consumers keep reading `finding.fingerprint`.
+ *
+ * @template T
+ * @param {Array<T>} findings
+ * @returns {Array<T & { fingerprint: { short: string, full: string } }>}
+ */
+export function withFingerprints(findings) {
+  if (!Array.isArray(findings)) {
+    throw new Error('withFingerprints: findings must be an array');
+  }
+  return findings.map((f) => ({
+    ...f,
+    fingerprint: fingerprintAuditFinding(f),
+  }));
+}
+
+/**
+ * Render the machine-readable fingerprint footer for a group of findings,
+ * via the shared helper's single footer renderer. Findings must already
+ * carry `fingerprint.full` (set by {@link withFingerprints}).
+ *
+ * @param {Array<{ fingerprint?: { full?: string } }>} findings
+ * @returns {string}
+ */
+export function renderFingerprintFooter(findings) {
+  if (!Array.isArray(findings)) {
+    throw new Error('renderFingerprintFooter: findings must be an array');
+  }
+  const shas = findings
+    .map((f) => f?.fingerprint?.full)
+    .filter((sha) => typeof sha === 'string' && sha.length > 0);
+  return fingerprintFooter(shas);
+}

package/.agents/scripts/lib/audit-to-stories/group-findings.js

@@ -0,0 +1,265 @@
+/**
+ * lib/audit-to-stories/group-findings.js — Cluster findings into Stories.
+ *
+ * Grouping signals, in priority order (Story #2583):
+ *   1. **Same primary file** — two findings on the same file merge.
+ *   2. **Adjacent files in the same module directory** — when the
+ *      directory hash matches and there is no stronger signal.
+ *   3. **Root-cause keyword overlap** — shared topical n-gram across
+ *      Current State / Title.
+ *
+ * Cross-audit grouping is enabled by default: a `security` finding and a
+ * `clean-code` finding on the same file produce a single group with both
+ * dimensions captured (`group.dimensions` is an array — callers map this
+ * to multiple `audit::<dim>` labels).
+ *
+ * Dependency edges (Recommendation of A references the file Current
+ * State of B flags) are emitted as a separate `edges` array — they do
+ * NOT merge the groups. The CLI surfaces them in the preview so the
+ * operator can decide if a sequencing constraint is worth flagging.
+ *
+ * Pure: no I/O.
+ */
+
+const SEVERITY_RANK = { critical: 3, high: 2, medium: 1, low: 0, null: -1 };
+
+function dirOf(filePath) {
+  if (typeof filePath !== 'string' || filePath.length === 0) return '';
+  const norm = filePath.replace(/\\/g, '/');
+  const lastSlash = norm.lastIndexOf('/');
+  return lastSlash === -1 ? '' : norm.slice(0, lastSlash);
+}
+
+function pickPrimaryFile(finding) {
+  if (Array.isArray(finding?.files) && finding.files.length > 0) {
+    return finding.files[0];
+  }
+  return null;
+}
+
+function highestSeverity(findings) {
+  let best = null;
+  let bestRank = -2;
+  for (const f of findings) {
+    const r = SEVERITY_RANK[f.severity ?? 'null'] ?? -1;
+    if (r > bestRank) {
+      bestRank = r;
+      best = f.severity ?? null;
+    }
+  }
+  return best;
+}
+
+/**
+ * @typedef {object} Group
+ * @property {string} groupKey — stable identifier (file path / dir / synthesized).
+ * @property {string[]} dimensions — every audit dimension represented.
+ * @property {string|null} severity — highest severity in the merge.
+ * @property {string[]} files — every file path mentioned across the merge.
+ * @property {string} title — synthesized group title.
+ * @property {Array<object>} findings — the merged finding objects.
+ */
+
+/**
+ * @typedef {object} GroupingResult
+ * @property {Group[]} groups
+ * @property {Array<{ fromGroupKey: string, toGroupKey: string, via: string }>} edges
+ */
+
+function tokenisePhrase(text) {
+  if (typeof text !== 'string') return new Set();
+  return new Set(
+    text
+      .toLowerCase()
+      .replace(/[`*_]/g, '')
+      .replace(/[^a-z0-9 -]/g, ' ')
+      .split(/\s+/)
+      .filter((w) => w.length > 4),
+  );
+}
+
+function rootCauseSignature(finding) {
+  // Topical tokens drawn from title + current-state.
+  const title = tokenisePhrase(finding.normalisedTitle ?? finding.title ?? '');
+  const state = tokenisePhrase(finding.currentState ?? '');
+  return new Set([...title, ...state]);
+}
+
+function bestSignatureGroupKey(finding, sigBuckets) {
+  const sig = rootCauseSignature(finding);
+  let bestKey = null;
+  let bestScore = 0;
+  for (const [key, bucket] of sigBuckets.entries()) {
+    let overlap = 0;
+    for (const t of sig) if (bucket.has(t)) overlap += 1;
+    if (overlap > bestScore && overlap >= 3) {
+      bestScore = overlap;
+      bestKey = key;
+    }
+  }
+  return { key: bestKey, sig };
+}
+
+function makeGroup(key) {
+  return {
+    groupKey: key,
+    dimensions: new Set(),
+    severity: null,
+    files: new Set(),
+    title: '',
+    findings: [],
+    _signature: new Set(),
+  };
+}
+
+function attachFindingToGroup(group, finding) {
+  group.findings.push(finding);
+  if (finding.dimension) group.dimensions.add(finding.dimension);
+  for (const f of finding.files ?? []) group.files.add(f);
+}
+
+function synthesizeTitle(group) {
+  const findings = group.findings;
+  if (findings.length === 1) return findings[0].title;
+
+  const sharedFile = [...group.files][0];
+  const dims = [...group.dimensions].sort();
+  if (sharedFile) {
+    return `Remediate ${dims.join(' / ')} findings in ${sharedFile}`;
+  }
+  if (findings.length === 2) {
+    return `${findings[0].title} & ${findings[1].title}`;
+  }
+  return `${findings[0].title} (+${findings.length - 1} related)`;
+}
+
+function detectDependencyEdges(groups) {
+  // A dependency edge fires when group B's primary file is mentioned in
+  // group A's Recommendation text (i.e. fixing A requires B to land).
+  const fileToGroup = new Map();
+  for (const g of groups) {
+    const filesIter = Array.isArray(g.files) ? g.files : [...g.files];
+    for (const f of filesIter) {
+      if (!fileToGroup.has(f)) fileToGroup.set(f, g.groupKey);
+    }
+  }
+
+  const edges = [];
+  for (const g of groups) {
+    const ownFiles = new Set(Array.isArray(g.files) ? g.files : [...g.files]);
+    for (const finding of g.findings) {
+      const rec = finding.recommendation ?? '';
+      if (!rec) continue;
+      for (const [file, owningKey] of fileToGroup.entries()) {
+        if (owningKey === g.groupKey) continue;
+        if (!ownFiles.has(file) && rec.includes(file)) {
+          edges.push({
+            fromGroupKey: g.groupKey,
+            toGroupKey: owningKey,
+            via: file,
+          });
+        }
+      }
+    }
+  }
+
+  return edges;
+}
+
+/**
+ * Cluster findings into Stories.
+ *
+ * @param {Array<{
+ *   dimension: string,
+ *   severity: string|null,
+ *   title: string,
+ *   normalisedTitle: string,
+ *   files: string[],
+ *   currentState: string,
+ *   recommendation: string,
+ * }>} findings
+ * @returns {GroupingResult}
+ */
+export function groupFindings(findings) {
+  if (!Array.isArray(findings)) {
+    throw new Error('groupFindings: findings must be an array');
+  }
+
+  const groups = new Map();
+  const sigBuckets = new Map();
+
+  for (const finding of findings) {
+    const primary = pickPrimaryFile(finding);
+    let key;
+
+    if (primary) {
+      key = `file:${primary}`;
+    } else {
+      // No file → try signature-based merge with an existing group.
+      const { key: matchKey, sig } = bestSignatureGroupKey(finding, sigBuckets);
+      if (matchKey) {
+        key = matchKey;
+      } else {
+        key = `topic:${finding.dimension}:${finding.normalisedTitle.slice(0, 40)}`;
+        sigBuckets.set(key, sig);
+      }
+    }
+
+    if (!groups.has(key)) {
+      groups.set(key, makeGroup(key));
+      if (!sigBuckets.has(key))
+        sigBuckets.set(key, rootCauseSignature(finding));
+    } else {
+      const existing = sigBuckets.get(key) ?? new Set();
+      for (const t of rootCauseSignature(finding)) existing.add(t);
+      sigBuckets.set(key, existing);
+    }
+
+    attachFindingToGroup(groups.get(key), finding);
+  }
+
+  // Second pass: merge any single-finding groups whose primary directory
+  // matches another group's directory AND whose root-cause signatures
+  // overlap by ≥ 3 tokens. This implements signal #2.
+  const groupArray = [...groups.values()];
+  const merged = new Set();
+  for (let i = 0; i < groupArray.length; i += 1) {
+    if (merged.has(groupArray[i].groupKey)) continue;
+    if (groupArray[i].findings.length > 1) continue;
+    const targetDir = dirOf(pickPrimaryFile(groupArray[i].findings[0]) ?? '');
+    if (!targetDir) continue;
+    const targetSig = sigBuckets.get(groupArray[i].groupKey) ?? new Set();
+
+    for (let j = i + 1; j < groupArray.length; j += 1) {
+      if (merged.has(groupArray[j].groupKey)) continue;
+      const otherDir = dirOf(
+        pickPrimaryFile(groupArray[j].findings[0] ?? {}) ?? '',
+      );
+      if (otherDir !== targetDir) continue;
+      const otherSig = sigBuckets.get(groupArray[j].groupKey) ?? new Set();
+      let overlap = 0;
+      for (const t of targetSig) if (otherSig.has(t)) overlap += 1;
+      if (overlap < 3) continue;
+
+      for (const f of groupArray[j].findings) {
+        attachFindingToGroup(groupArray[i], f);
+      }
+      merged.add(groupArray[j].groupKey);
+    }
+  }
+
+  const finalGroups = groupArray
+    .filter((g) => !merged.has(g.groupKey))
+    .map((g) => {
+      g.severity = highestSeverity(g.findings);
+      g.dimensions = [...g.dimensions].sort();
+      g.files = [...g.files];
+      g.title = synthesizeTitle(g);
+      delete g._signature;
+      return g;
+    });
+
+  const edges = detectDependencyEdges(finalGroups);
+
+  return { groups: finalGroups, edges };
+}