mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/observability/perf-report-readers.js

@@ -1,328 +0,0 @@
-/**
- * perf-report-readers.js — I/O readers + git-scrape helpers for the
- * structured perf-summary comments (Epic #1030 / Story #1123, split out
- * under Story #3350).
- *
- * Every export here touches the filesystem, the ticketing provider, or
- * `git log`. The pure renderers that format the report bodies live in the
- * sibling `perf-report-render.js`; the Story-/Epic-mode orchestrators in
- * `analyze-execution.js` wire these readers to those renderers.
- *
- * @see docs/data-dictionary.md §StoryPerfSummary, §EpicPerfReport
- */
-
-import fs from 'node:fs/promises';
-import { storyArtifactPath } from '../config/temp-paths.js';
-import { gitSpawn } from '../git-utils.js';
-import { Logger } from '../Logger.js';
-import { read as readSignals } from '../signals/read.js';
-import { concurrentMap } from '../util/concurrent-map.js';
-import { extractStoryPerfSummaryFromComment } from './perf-report-render.js';
-import { forEachLine } from './signals-writer.js';
-
-/**
- * Stream every lifecycle event under the Epic into an in-memory array
- * (Story #3025 / Task #3030). The perf-aggregator's wave-parallelism
- * reducer needs a single chronological iterable spanning wave-start /
- * wave-complete / state-transition events; the canonical reader walks
- * the epic-level signals.ndjson first, then each per-Story stream in
- * ascending Story-ID order, so that ordering matches the wave-tick
- * emit order at runtime.
- *
- * Returns `[]` on any reader failure so the analyzer keeps composing
- * its other report sections.
- */
-export async function readEpicLifecycleEvents(epicId, config, logger) {
-  const events = [];
-  try {
-    for await (const evt of readSignals({ epic: epicId, config })) {
-      if (evt && typeof evt === 'object') events.push(evt);
-    }
-  } catch (err) {
-    logger?.warn?.(
-      `[analyze-execution] readEpicLifecycleEvents(${epicId}) failed (non-fatal): ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-  }
-  return events;
-}
-
-/**
- * Read every NDJSON line from a Story's signals stream into an array.
- * Missing files resolve to `[]` so callers can treat absence as
- * "no signals yet" without a try/catch.
- */
-export async function readStorySignals(epicId, storyId, config) {
-  const events = [];
-  await forEachLine(
-    epicId,
-    storyId,
-    (parsed) => {
-      if (parsed && typeof parsed === 'object') events.push(parsed);
-    },
-    config,
-  );
-  return events;
-}
-
-/**
- * Best-effort read of the per-Story phase-timings JSON written by
- * `post-merge-close.js`. Returns `null` when the file is missing or
- * malformed — phaseTimingsMs in the StoryPerfSummary degrades to `{}`
- * rather than throwing.
- */
-export async function readPhaseTimings(epicId, storyId, config, overridePath) {
-  const target =
-    overridePath ??
-    storyArtifactPath(epicId, storyId, 'phase-timings.json', config);
-  try {
-    const buf = await fs.readFile(target, 'utf8');
-    const parsed = JSON.parse(buf);
-    if (parsed && typeof parsed === 'object') return parsed;
-    return null;
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    Logger.warn(
-      `[analyze-execution] could not parse phase-timings at ${target}: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return null;
-  }
-}
-
-/**
- * Throw-away ghSpawnCount reader (Story #1795 / Epic #1788). Looks for
- * the `temp/epic-<eid>/stories/story-<sid>/gh-spawn-count.json` file written by
- * `close-validation.emitGhSpawnCount` immediately before the perf-summary
- * phase spawns this analyzer. Returns the integer count when present and
- * well-formed; `null` when absent or unparseable. Callers treat `null` as
- * "no signal" — the structured comment simply omits `ghSpawnCount`.
- */
-export async function readGhSpawnCount(epicId, storyId, config) {
-  const target = storyArtifactPath(
-    epicId,
-    storyId,
-    'gh-spawn-count.json',
-    config,
-  );
-  try {
-    const buf = await fs.readFile(target, 'utf8');
-    const parsed = JSON.parse(buf);
-    const count = parsed?.ghSpawnCount;
-    if (Number.isInteger(count) && count >= 0) return count;
-    return null;
-  } catch (err) {
-    if (err && err.code === 'ENOENT') return null;
-    Logger.warn(
-      `[analyze-execution] could not parse gh-spawn-count at ${target}: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return null;
-  }
-}
-
-/**
- * Fetch every `story-perf-summary` structured comment from the Stories
- * under an Epic. We rely on `provider.getSubTickets(epicId)` for child
- * enumeration (Stories carry `parent: #<epicId>` either via the native
- * sub-issue link or the body marker — `getSubTickets` reconciles both).
- * Missing comments are skipped (the Story may have been recut and not
- * closed yet).
- */
-export async function collectStorySummaries(provider, epicId, logger) {
-  let stories;
-  try {
-    const children = await provider.getSubTickets(epicId);
-    stories = Array.isArray(children) ? children : [];
-  } catch (err) {
-    logger.warn?.(
-      `[analyze-execution] getSubTickets(${epicId}) failed: ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return [];
-  }
-  // Filter to Story tickets — descendants include Tasks too. We only
-  // want the per-Story summaries, so guard on `type::story`.
-  const storyTickets = stories.filter(
-    (t) =>
-      Array.isArray(t?.labels) &&
-      t.labels.some(
-        (l) => (typeof l === 'string' ? l : l?.name) === 'type::story',
-      ),
-  );
-
-  // Bounded-parallel comment fetch (Story #3990). Each Story's comment
-  // thread is an independent paginated REST read through a fresh `gh`
-  // spawn, so a serial loop pays N sequential round-trips. concurrentMap
-  // preserves input→output index, keeping summaries in Story order; the
-  // per-Story try/catch stays inside the mapper so one failed fetch
-  // degrades to warn-and-skip without aborting the batch (mirrors
-  // verifySingleResult in lib/orchestration/wave-record-io.js, #3024).
-  const perStory = await concurrentMap(
-    storyTickets,
-    async (ticket) => {
-      const id = Number(ticket.id ?? ticket.number);
-      if (!Number.isInteger(id) || id < 1) return null;
-      let comments;
-      try {
-        comments = (await provider.getTicketComments(id)) ?? [];
-      } catch (err) {
-        logger.warn?.(
-          `[analyze-execution] getTicketComments(${id}) failed: ${
-            err instanceof Error ? err.message : String(err)
-          }`,
-        );
-        return null;
-      }
-      for (const c of comments) {
-        const parsed = extractStoryPerfSummaryFromComment(c?.body);
-        if (parsed) return parsed;
-      }
-      return null;
-    },
-    { concurrency: 4 },
-  );
-  return perStory.filter((s) => s !== null);
-}
-
-/**
- * Default git-log gatherer for the baseline-refresh-rate reporter
- * (Story #1400 / Task #1427). Reads commits on `epic/<id>` over the
- * trailing window and shapes them into the record format the pure
- * reporter expects. Returns `[]` on any spawn failure so the retro
- * comment keeps composing — the reporter then prints "no Story merges
- * in window" and the operator can investigate offline.
- *
- * Injectable via `runEpicMode({ gatherEpicCommitsFn })` so the unit test
- * can pin behavior without a temp git repo.
- */
-export function gatherEpicCommitsFromGit({ epicId, windowDays, cwd, logger }) {
-  const ref = `epic/${epicId}`;
-  const since = `${windowDays} days ago`;
-  // Subject (%s) carries the Story-merge `(resolves #N)` and the
-  // `baseline-refresh:` prefix; ISO commit date (%cI) drives the window
-  // filter inside the reporter. Tab separator avoids subjects that
-  // contain pipes.
-  const res = gitSpawn(
-    cwd,
-    'log',
-    ref,
-    `--since=${since}`,
-    '--pretty=format:%H%x09%cI%x09%s',
-  );
-  if (res.status !== 0) {
-    logger.warn?.(
-      `[analyze-execution] git log ${ref} failed (non-fatal): ${res.stderr || res.stdout}`,
-    );
-    return [];
-  }
-  const lines = (res.stdout || '').split('\n').filter(Boolean);
-  return lines.map((line) => {
-    const [sha, isoDate, ...rest] = line.split('\t');
-    return {
-      sha,
-      isoDate,
-      subject: rest.join('\t'),
-      epicId,
-    };
-  });
-}
-
-/**
- * Default friction aggregator for the Quality-gate friction block
- * (Story #1400 / Task #1429). Walks each child Story's signals.ndjson
- * stream and returns counts of `baseline-refresh-regression` records
- * plus the top offenders by file (and method, when present in the
- * `regressedFiles` / `crapOverCap` payloads).
- *
- * Aggregation runs against the existing `signals.ndjson` stream — no new
- * file format. Two upstream record shapes are walked:
- *   - check-maintainability emits a flat `regressedFiles[]` of `{ file, current, baseline, drop }`.
- *   - auto-refresh-runner emits `miOverCap[]` / `crapOverCap[]` rows
- *     carrying `path`/`file` and (for crap) `method`.
- *
- * Injectable via `runEpicMode({ aggregateFrictionFn })` so the unit test
- * can pin behavior without seeding NDJSON files.
- */
-export async function aggregateBaselineFrictionFromSignals({
-  epicId,
-  storyIds,
-  config,
-  windowDays,
-  now,
-}) {
-  const cutoffMs = now().getTime() - windowDays * 24 * 60 * 60 * 1000;
-  const offenders = new Map(); // key → { file, method, occurrences }
-  const storiesAffected = new Set();
-  let totalRecords = 0;
-
-  for (const sid of storyIds) {
-    let touched = false;
-    await forEachLine(
-      epicId,
-      sid,
-      (record) => {
-        if (
-          !record ||
-          typeof record !== 'object' ||
-          record.kind !== 'friction' ||
-          record.category !== 'baseline-refresh-regression'
-        ) {
-          return;
-        }
-        const ts = Date.parse(record.ts);
-        if (Number.isFinite(ts) && ts < cutoffMs) return;
-
-        totalRecords += 1;
-        touched = true;
-
-        const flatFiles = Array.isArray(record.regressedFiles)
-          ? record.regressedFiles.map((r) => ({ file: r.file }))
-          : [];
-        const miFiles = Array.isArray(record.miOverCap)
-          ? record.miOverCap.map((r) => ({ file: r.path ?? r.file }))
-          : [];
-        const crapMethods = Array.isArray(record.crapOverCap)
-          ? record.crapOverCap.map((r) => ({
-              file: r.file,
-              method: r.method,
-            }))
-          : [];
-
-        for (const off of [...flatFiles, ...miFiles, ...crapMethods]) {
-          if (!off || typeof off.file !== 'string' || off.file.length === 0) {
-            continue;
-          }
-          const key = off.method ? `${off.file}::${off.method}` : off.file;
-          const prev = offenders.get(key);
-          if (prev) {
-            prev.occurrences += 1;
-          } else {
-            offenders.set(key, {
-              file: off.file,
-              method: off.method ?? null,
-              occurrences: 1,
-            });
-          }
-        }
-      },
-      config,
-    );
-    if (touched) storiesAffected.add(sid);
-  }
-
-  const topOffenders = [...offenders.values()]
-    .sort((a, b) => b.occurrences - a.occurrences)
-    .slice(0, 10);
-
-  return {
-    totalRecords,
-    storiesAffected: storiesAffected.size,
-    topOffenders,
-    windowDays,
-  };
-}

package/.agents/scripts/lib/observability/perf-report-render.js

@@ -1,182 +0,0 @@
-/**
- * perf-report-render.js — pure renderers + summary extraction for the
- * structured perf-summary comments (Epic #1030 / Story #1123, split out
- * under Story #3350).
- *
- * Every export here is a pure function: it depends only on its inputs and
- * performs no I/O. The Story-/Epic-mode orchestrators in
- * `analyze-execution.js` read NDJSON, phase-timings, and git-log records
- * via the sibling `perf-report-readers.js`, then hand the resulting plain
- * objects to these renderers. Keeping the render surface free of I/O makes
- * the report formatting unit-testable without fixtures.
- *
- * `extractStoryPerfSummaryFromComment` is the one mixed read/parse helper —
- * it parses a comment body that originated from `renderStoryBody`, so it
- * lives next to the renderer it mirrors. It delegates the fenced-JSON
- * extraction to `parseFencedJsonComment` (the shared structured-comment
- * parser) rather than open-coding the fence regex.
- *
- * @see docs/data-dictionary.md §StoryPerfSummary, §EpicPerfReport
- */
-
-import { parseFencedJsonComment } from '../orchestration/structured-comment-parser.js';
-
-export const STORY_PERF_TYPE = 'story-perf-summary';
-export const EPIC_PERF_TYPE = 'epic-perf-report';
-// Marker emitted by `upsertStructuredComment` for the story-perf-summary
-// type. Mirrors `structuredCommentMarker(STORY_PERF_TYPE)` so the Epic
-// rollup can detect summary comments without importing the renderer.
-export const STORY_PERF_MARKER = `<!-- ap:structured-comment type="${STORY_PERF_TYPE}" -->`;
-
-/**
- * Render a small operator-facing summary block that doubles as the
- * comment body. The fenced JSON payload is the canonical machine-
- * readable surface; the prose lines above it give a human a reason to
- * skim. The retro composer reads the fenced JSON, not the prose.
- */
-export function renderStoryBody(payload) {
-  const friction = Object.entries(payload.frictionByCategory ?? {})
-    .map(([k, v]) => `${k}=${v}`)
-    .join(', ');
-  const phaseRows = Object.entries(payload.phaseTimingsMs ?? {})
-    .map(([k, v]) => `- \`${k}\`: ${v}ms`)
-    .join('\n');
-  const lines = [
-    `### Story Perf Summary — Story #${payload.storyId} (Epic #${payload.epicId})`,
-    '',
-    `Closed at: \`${payload.closedAt}\``,
-    '',
-    friction.length > 0
-      ? `**Friction:** ${friction}`
-      : '**Friction:** none recorded',
-    '',
-    phaseRows.length > 0
-      ? `**Phase timings:**\n${phaseRows}`
-      : '**Phase timings:** none recorded',
-    '',
-    `**Rework:** ${payload.reworkScore.filesEditedBeyondThreshold} files beyond threshold`,
-    `**Retries:** ${payload.retryDensity.retries} across ${payload.retryDensity.uniqueCommands} unique command(s)`,
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-  ];
-  return lines.join('\n');
-}
-
-/**
- * Render the optional Quality-gate friction summary block (Story #1400 /
- * Task #1429). Aggregates `baseline-refresh-regression` friction records
- * from the Stories' signals.ndjson streams over the trailing window,
- * counts them, and lists the top offenders by file/method.
- *
- * Output contract:
- *   - `friction == null` → empty string (caller injected nothing).
- *   - `friction.totalRecords === 0` → `**Quality gate friction:** none`
- *   - otherwise → count line + bulleted top-offenders list
- *
- * The block reads the existing `signals.ndjson` stream — no new file
- * format. Aggregation is provided by `aggregateBaselineFrictionFromSignals`
- * which the unit test can stub via `runEpicMode({ aggregateFrictionFn })`.
- */
-export function renderQualityGateFrictionBlock(friction) {
-  if (!friction) return '';
-  const total = friction.totalRecords ?? 0;
-  if (total === 0) {
-    return ['', '**Quality gate friction:** none', ''].join('\n');
-  }
-  const offenders = (friction.topOffenders ?? [])
-    .map((o) => {
-      const where = o.method ? `${o.file} → ${o.method}` : o.file;
-      return `- \`${where}\` — ${o.occurrences} occurrence(s)`;
-    })
-    .join('\n');
-  return [
-    '',
-    `**Quality gate friction:** ${total} \`baseline-refresh-regression\` record(s) across ${friction.storiesAffected ?? 0} Story/Stories`,
-    offenders.length > 0 ? `\nTop offenders:\n${offenders}` : '',
-    '',
-  ].join('\n');
-}
-
-/**
- * Render the per-Epic baseline-refresh-rate row (Story #1400 / Task #1427).
- * Returns an empty string when `refresh` is null so the caller can
- * concatenate unconditionally.
- */
-export function renderBaselineRefreshRateRow(refresh) {
-  if (!refresh) return '';
-  const row = (refresh.perEpic ?? [])[0];
-  if (!row) {
-    return [
-      '',
-      `**Baseline refresh discipline (trailing ${refresh.windowDays}d):** no Story merges in window`,
-      '',
-    ].join('\n');
-  }
-  const pct = (row.cleanMergeRate * 100).toFixed(1);
-  const target = row.cleanMergeRate >= 0.9 ? '✅' : '⚠️';
-  return [
-    '',
-    `**Baseline refresh discipline (trailing ${refresh.windowDays}d):** ${target} ${pct}% clean-merge rate (${row.storyMerges - row.baselineRefreshes}/${row.storyMerges} Stories landed without follow-up refresh; ${row.baselineRefreshes} \`baseline-refresh:\` commit(s))`,
-    '',
-  ].join('\n');
-}
-
-export function renderEpicBody(payload, extras = {}) {
-  const counts = payload.signalCounts ?? {};
-  const countLine = Object.entries(counts)
-    .map(([k, v]) => `${k}=${v}`)
-    .join(', ');
-  const hotspots = (payload.topHotspots ?? [])
-    .map(
-      (h) =>
-        `- \`${h.phase}\` — ${h.occurrences} occurrence(s), avg ratio ${h.avgRatio.toFixed(2)}`,
-    )
-    .join('\n');
-  const friction = (payload.mostFrictionStories ?? [])
-    .map((s) => `- Story #${s.storyId}: ${s.frictionCount} friction signal(s)`)
-    .join('\n');
-  const lines = [
-    `### Epic Perf Report — Epic #${payload.epicId}`,
-    '',
-    `Generated at: \`${payload.generatedAt}\``,
-    '',
-    `**Signal counts:** ${countLine.length > 0 ? countLine : 'none'}`,
-    '',
-    hotspots.length > 0
-      ? `**Top hotspots:**\n${hotspots}`
-      : '**Top hotspots:** none recorded',
-    '',
-    friction.length > 0
-      ? `**Most-friction Stories:**\n${friction}`
-      : '**Most-friction Stories:** none recorded',
-    renderBaselineRefreshRateRow(extras.baselineRefreshRate),
-    renderQualityGateFrictionBlock(extras.qualityGateFriction),
-    '',
-    '```json',
-    JSON.stringify(payload, null, 2),
-    '```',
-  ];
-  return lines.join('\n');
-}
-
-/**
- * Extract a story-perf-summary payload from a comment body. The body
- * begins with the structured marker line, followed by markdown prose,
- * followed by a fenced ```json``` block carrying the canonical payload.
- * We delegate the fence extraction to `parseFencedJsonComment` so the
- * fenced-JSON regex lives in exactly one place.
- *
- * Returns `null` when the marker is missing, no fence is found, or the
- * fence does not parse — the caller treats absence as "no signal" and
- * keeps walking.
- */
-export function extractStoryPerfSummaryFromComment(body) {
-  if (typeof body !== 'string' || !body.includes(STORY_PERF_MARKER)) {
-    return null;
-  }
-  const parsed = parseFencedJsonComment({ body });
-  if (parsed && parsed.kind === 'story-perf-summary') return parsed;
-  return null;
-}