mandrel 1.57.0

package/.agents/scripts/lib/audit-to-stories/parse-audit-md.js

@@ -0,0 +1,246 @@
+/**
+ * lib/audit-to-stories/parse-audit-md.js — Parse `audit-*-results.md` reports.
+ *
+ * Extracts the `## Detailed Findings` section of an audit report and turns
+ * every `### <title>` block into a normalised finding record. The 12 audit
+ * workflows use slightly different field names — `Severity` vs `Impact`,
+ * `Dimension` vs `Category` — so the parser captures every key/value pair
+ * the block carries and normalises the two axes the downstream pipeline
+ * relies on (severity + dimension).
+ *
+ * Pure: no filesystem I/O. The caller supplies the report text and source
+ * path; the parser returns plain objects.
+ */
+
+import path from 'node:path';
+
+const SEVERITY_ALIASES = Object.freeze({
+  critical: 'critical',
+  high: 'high',
+  medium: 'medium',
+  mod: 'medium',
+  moderate: 'medium',
+  low: 'low',
+});
+
+const KEY_LINE = /^\s*-\s*\*\*([^:*]+):\*\*\s*(.*)$/;
+const HEADING_FINDING = /^###\s+(.+?)\s*$/;
+const HEADING_SECTION = /^##\s+(.+?)\s*$/;
+const PATH_HINT =
+  /(?<![\w/])([A-Za-z0-9_./\\@-]+\.(?:js|ts|tsx|jsx|mjs|cjs|md|json|yaml|yml|css|scss|html|py|go|rs|java|kt|rb|sh|ps1|tf|env))(?![\w])/g;
+
+function unwrapInlineCode(value) {
+  if (typeof value !== 'string') return '';
+  const trimmed = value.trim();
+  if (trimmed.startsWith('`') && trimmed.endsWith('`') && trimmed.length >= 2) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function normaliseSeverity(token) {
+  if (typeof token !== 'string') return null;
+  const cleaned = token
+    .toLowerCase()
+    .replace(/\[|\]|\(|\)/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  if (!cleaned) return null;
+  for (const word of cleaned.split(/[\s|/,]+/)) {
+    const hit = SEVERITY_ALIASES[word];
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function deriveDimension(fields, fallbackDimension) {
+  for (const key of ['dimension', 'category', 'area']) {
+    const raw = fields[key];
+    if (typeof raw === 'string' && raw.trim().length > 0) {
+      return raw
+        .replace(/\[|\]/g, '')
+        .trim()
+        .split(/\s*\|\s*/)[0];
+    }
+  }
+  return fallbackDimension;
+}
+
+function deriveSeverity(fields) {
+  for (const key of ['severity', 'impact', 'risk']) {
+    const sev = normaliseSeverity(fields[key]);
+    if (sev) return sev;
+  }
+  return null;
+}
+
+function normaliseTitle(title) {
+  return title
+    .toLowerCase()
+    .replace(/[`*_]/g, '')
+    .replace(/\s+/g, ' ')
+    .replace(/[^a-z0-9 -]/g, '')
+    .trim();
+}
+
+function extractFilePaths(text) {
+  if (typeof text !== 'string') return [];
+  const seen = new Set();
+  for (const match of text.matchAll(PATH_HINT)) {
+    const candidate = match[1].replace(/^[`'"]+|[`'"]+$/g, '');
+    if (candidate.includes('/') || candidate.includes('\\')) {
+      seen.add(candidate);
+    }
+  }
+  return [...seen];
+}
+
+function inferDimensionFromReportName(sourceReport) {
+  if (typeof sourceReport !== 'string' || sourceReport.length === 0)
+    return 'unknown';
+  const base = path.basename(sourceReport, path.extname(sourceReport));
+  const match = base.match(/^audit-(.+?)(?:-results)?$/);
+  return match ? match[1] : base;
+}
+
+function splitFindingBlocks(reportText) {
+  const lines = reportText.split(/\r?\n/);
+  let inDetailed = false;
+  const blocks = [];
+  let current = null;
+
+  for (const line of lines) {
+    const sectionMatch = HEADING_SECTION.exec(line);
+    if (sectionMatch) {
+      if (current) {
+        blocks.push(current);
+        current = null;
+      }
+      const sectionTitle = sectionMatch[1].toLowerCase();
+      inDetailed = sectionTitle.includes('detailed findings');
+      continue;
+    }
+
+    if (!inDetailed) continue;
+
+    const findingMatch = HEADING_FINDING.exec(line);
+    if (findingMatch) {
+      if (current) blocks.push(current);
+      current = { title: findingMatch[1].trim(), bodyLines: [] };
+      continue;
+    }
+
+    if (current) current.bodyLines.push(line);
+  }
+
+  if (current) blocks.push(current);
+  return blocks;
+}
+
+function parseBlockFields(bodyLines) {
+  const fields = {};
+  let activeKey = null;
+  for (const line of bodyLines) {
+    const m = KEY_LINE.exec(line);
+    if (m) {
+      activeKey = m[1].trim().toLowerCase();
+      fields[activeKey] = unwrapInlineCode(m[2]);
+      continue;
+    }
+    if (activeKey && line.trim().length > 0) {
+      const continuation = unwrapInlineCode(line.replace(/^\s+/, ''));
+      if (continuation) {
+        fields[activeKey] = fields[activeKey]
+          ? `${fields[activeKey]} ${continuation}`
+          : continuation;
+      }
+    }
+  }
+  return fields;
+}
+
+/**
+ * Parse a single audit report's markdown text into a list of normalised
+ * findings.
+ *
+ * @param {object} params
+ * @param {string} params.markdown — full report text.
+ * @param {string} params.sourceReport — path used for `sourceReport` field
+ *   and dimension inference when the report omits a `Dimension:` line.
+ * @returns {Array<{
+ *   dimension: string,
+ *   severity: 'critical'|'high'|'medium'|'low'|null,
+ *   title: string,
+ *   normalisedTitle: string,
+ *   files: string[],
+ *   currentState: string,
+ *   recommendation: string,
+ *   agentPrompt: string,
+ *   rawFields: Record<string,string>,
+ *   sourceReport: string,
+ * }>}
+ */
+export function parseAuditReport({ markdown, sourceReport }) {
+  if (typeof markdown !== 'string') {
+    throw new Error('parseAuditReport: markdown must be a string');
+  }
+  if (typeof sourceReport !== 'string' || sourceReport.length === 0) {
+    throw new Error('parseAuditReport: sourceReport path is required');
+  }
+
+  const fallbackDimension = inferDimensionFromReportName(sourceReport);
+  const blocks = splitFindingBlocks(markdown);
+
+  return blocks.map((block) => {
+    const fields = parseBlockFields(block.bodyLines);
+    const dimension = deriveDimension(fields, fallbackDimension);
+    const severity = deriveSeverity(fields);
+    const currentState = fields['current state'] ?? '';
+    const recommendation =
+      fields['recommendation & rationale'] ?? fields.recommendation ?? '';
+    const agentPrompt = fields['agent prompt'] ?? '';
+    const fileSet = new Set([
+      ...extractFilePaths(currentState),
+      ...extractFilePaths(recommendation),
+      ...extractFilePaths(agentPrompt),
+    ]);
+
+    return {
+      dimension: dimension.toLowerCase(),
+      severity,
+      title: block.title,
+      normalisedTitle: normaliseTitle(block.title),
+      files: [...fileSet],
+      currentState,
+      recommendation,
+      agentPrompt,
+      rawFields: fields,
+      sourceReport,
+    };
+  });
+}
+
+/**
+ * Parse N audit reports and return a flat findings array. Reports without a
+ * `## Detailed Findings` section yield zero entries rather than throwing —
+ * an audit can legitimately come back empty.
+ *
+ * @param {Array<{ markdown: string, sourceReport: string }>} reports
+ * @returns {Array<ReturnType<typeof parseAuditReport>[number]>}
+ */
+export function parseAuditReports(reports) {
+  if (!Array.isArray(reports)) {
+    throw new Error('parseAuditReports: reports must be an array');
+  }
+  const out = [];
+  for (const report of reports) {
+    out.push(...parseAuditReport(report));
+  }
+  return out;
+}
+
+export const __testing = {
+  normaliseSeverity,
+  extractFilePaths,
+  normaliseTitle,
+};

package/.agents/scripts/lib/audit-to-stories/seed-epic-from-findings.js

@@ -0,0 +1,160 @@
+/**
+ * lib/audit-to-stories/seed-epic-from-findings.js
+ *
+ * Build the `--idea`-shaped seed markdown that `/epic-plan` Phase 1
+ * consumes when the operator picks the Single-Epic grouping mode.
+ *
+ * The seed renders the canonical one-pager sections so the idea-refinement
+ * skill can sharpen it without having to invent context:
+ *   - Problem Statement (aggregated severity profile)
+ *   - Recommended Direction (rollup of recommendations by dimension)
+ *   - Key Assumptions (carries the source-report links forward)
+ *   - MVP Scope (the proposed Stories, one bullet per group)
+ *   - Key Files (explicit file paths so /epic-plan Phase 7 decompose
+ *     has concrete anchors)
+ *   - Not Doing (out-of-scope items by convention)
+ *
+ * Pure: returns a string. The caller decides where to persist it.
+ */
+
+const DIMENSION_LABEL = {
+  security: 'Security',
+  privacy: 'Privacy',
+  quality: 'Quality',
+  'clean-code': 'Clean code',
+  dependencies: 'Dependencies',
+  devops: 'DevOps',
+  lighthouse: 'Lighthouse',
+  performance: 'Performance',
+  seo: 'SEO',
+  sre: 'SRE',
+  'ux-ui': 'UX / UI',
+  architecture: 'Architecture',
+};
+
+const SEVERITY_ORDER = ['critical', 'high', 'medium', 'low'];
+
+function tallySeverities(findings) {
+  const tally = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) {
+    if (Object.hasOwn(tally, f.severity)) tally[f.severity] += 1;
+  }
+  return tally;
+}
+
+function tallyDimensions(findings) {
+  const tally = new Map();
+  for (const f of findings) {
+    tally.set(f.dimension, (tally.get(f.dimension) ?? 0) + 1);
+  }
+  return tally;
+}
+
+function formatProblemStatement(findings) {
+  const sev = tallySeverities(findings);
+  const dimensions = tallyDimensions(findings);
+  const tallyParts = SEVERITY_ORDER.filter((k) => sev[k] > 0)
+    .map((k) => `${sev[k]} ${k.charAt(0).toUpperCase() + k.slice(1)}`)
+    .join(', ');
+  const topDims = [...dimensions.entries()]
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 3)
+    .map(([d]) => DIMENSION_LABEL[d] ?? d);
+  const dimsPhrase = topDims.length > 0 ? topDims.join(', ') : 'multiple areas';
+  return `An audit sweep surfaced ${findings.length} findings (${tallyParts}) concentrated in ${dimsPhrase}. These require remediation to restore release posture.`;
+}
+
+function formatRecommendedDirection(findings) {
+  const byDim = new Map();
+  for (const f of findings) {
+    if (!byDim.has(f.dimension)) byDim.set(f.dimension, []);
+    if (f.recommendation) byDim.get(f.dimension).push(f.recommendation);
+  }
+  const lines = [];
+  for (const [dim, recs] of [...byDim.entries()].sort()) {
+    const label = DIMENSION_LABEL[dim] ?? dim;
+    const head = recs.slice(0, 2).join(' ');
+    lines.push(`- **${label}** — ${head || 'See linked findings.'}`);
+  }
+  return lines.join('\n');
+}
+
+function formatMVPScope(groups) {
+  return groups
+    .map((g, idx) => {
+      const dims = g.dimensions.join(' / ');
+      const file = g.files[0] ? ` (\`${g.files[0]}\`)` : '';
+      return `${idx + 1}. **${g.title}** — ${dims}${file}`;
+    })
+    .join('\n');
+}
+
+function formatKeyFiles(groups) {
+  const files = new Set();
+  for (const g of groups) for (const f of g.files) files.add(f);
+  if (files.size === 0) return '_(no concrete file paths surfaced)_';
+  return [...files]
+    .sort()
+    .map((f) => `- \`${f}\``)
+    .join('\n');
+}
+
+function formatKeyAssumptions(sourceReports) {
+  const unique = [...new Set(sourceReports)].sort();
+  if (unique.length === 0) return '- _(no source audit reports)_';
+  return unique.map((r) => `- Findings sourced from \`${r}\``).join('\n');
+}
+
+/**
+ * @param {object} params
+ * @param {Array<object>} params.groups — output of `groupFindings`, after dedupe filter.
+ * @param {Array<object>} params.findings — full filtered finding list.
+ * @param {string[]} params.sourceReports — list of source report paths.
+ * @returns {string}
+ */
+export function buildEpicSeedMarkdown({ groups, findings, sourceReports }) {
+  if (
+    !Array.isArray(groups) ||
+    !Array.isArray(findings) ||
+    !Array.isArray(sourceReports)
+  ) {
+    throw new Error(
+      'buildEpicSeedMarkdown: groups, findings, sourceReports must all be arrays',
+    );
+  }
+  const problem = formatProblemStatement(findings);
+  const direction = formatRecommendedDirection(findings);
+  const scope = formatMVPScope(groups);
+  const files = formatKeyFiles(groups);
+  const assumptions = formatKeyAssumptions(sourceReports);
+
+  return [
+    '# Idea Seed: Audit Remediation',
+    '',
+    '## Problem Statement',
+    '',
+    problem,
+    '',
+    '## Recommended Direction',
+    '',
+    direction || '_(no recommendations captured)_',
+    '',
+    '## Key Assumptions',
+    '',
+    assumptions,
+    '',
+    '## MVP Scope',
+    '',
+    scope || '_(no proposed stories)_',
+    '',
+    '## Key Files',
+    '',
+    files,
+    '',
+    '## Not Doing',
+    '',
+    '- Findings with severity below the operator-selected threshold.',
+    '- Re-occurring findings already tracked in closed issues (re-open manually if needed).',
+    '',
+  ].join('\n');
+}