@matteeh/osq 0.2.0 → 0.2.2

package/dist/core/status/show.js

@@ -2,10 +2,18 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import { DEFAULT_CONFIG } from '../foundation/config.js';
 import { readPlanningSessions } from '../report/planning.js';
+import { addedPairs, distinctPairs } from '../report/report-dependencies.js';
 import { formatDuration } from '../report/report.js';
+import { parseResultSections } from '../report/result-sections.js';
+import { resolveScope } from '../run/scope.js';
+import { buildImportGraph } from '../spec/import-graph.js';
 import { parseFrontmatter, parseSpecMdFromFolder, parseTaskMd } from '../spec/parser.js';
-import { getArchiveDir, getChangesDir, getRejectedDir } from './layout.js';
+import { buildScenarioIndex } from '../trace/scenario-index.js';
+import { listChanges, locateFolder } from './change-locations.js';
+import { formatNextStep, readNextStep } from './next-step.js';
+import { formatPreSpawnStart } from './pre-spawn-words.js';
 import { deriveSpecState } from './state.js';
+import { readVerification } from './verification.js';
 function matchesFolder(folderName, query) {
     const trimmed = query.trim();
     const num = Number.parseInt(trimmed, 10);
@@ -94,89 +102,84 @@ export async function resolveSpecFolder(projectRoot, idOrPrefix, config = DEFAUL
     if (!trimmed) {
         throw new Error('Spec ID or prefix cannot be empty');
     }
-    const specsDir = getChangesDir(config.paths.openspecRoot, projectRoot);
-    const archiveDir = getArchiveDir(config.paths.openspecRoot, projectRoot);
-    const rejectedDir = getRejectedDir(config.paths.openspecRoot, projectRoot);
     // If directly pointing to an existing folder
     if (path.isAbsolute(trimmed) || trimmed.includes(path.sep)) {
         const candidatePath = path.isAbsolute(trimmed) ? trimmed : path.resolve(projectRoot, trimmed);
         const stat = await fs.stat(candidatePath).catch(() => null);
         if (stat?.isDirectory()) {
-            const location = candidatePath === archiveDir || candidatePath.startsWith(`${archiveDir}${path.sep}`)
-                ? 'archived'
-                : candidatePath === rejectedDir || candidatePath.startsWith(`${rejectedDir}${path.sep}`)
-                    ? 'rejected'
-                    : 'active';
+            const located = await locateFolder(projectRoot, config, candidatePath);
+            const location = located?.location ?? 'active';
             return { folderPath: candidatePath, isArchived: location === 'archived', location };
         }
     }
-    // 1. Search active specs
-    let activeEntries = [];
-    try {
-        activeEntries = await fs.readdir(specsDir);
-    }
-    catch {
-        activeEntries = [];
-    }
-    const archiveRel = path.relative(specsDir, archiveDir);
-    const archiveFolder = !archiveRel.startsWith('..') && !path.isAbsolute(archiveRel)
-        ? archiveRel.split(path.sep)[0]
-        : 'archive';
-    const rejectedRel = path.relative(specsDir, rejectedDir);
-    const rejectedFolder = !rejectedRel.startsWith('..') && !path.isAbsolute(rejectedRel)
-        ? rejectedRel.split(path.sep)[0]
-        : 'rejected';
-    for (const entry of activeEntries) {
-        if (entry.startsWith('.') ||
-            entry.startsWith('_') ||
-            entry === archiveFolder ||
-            entry === rejectedFolder) {
-            continue;
-        }
-        if (matchesFolder(entry, trimmed)) {
-            const fullPath = path.join(specsDir, entry);
-            const stat = await fs.stat(fullPath).catch(() => null);
-            if (stat?.isDirectory()) {
-                return { folderPath: fullPath, isArchived: false, location: 'active' };
-            }
+    // Search active, then archived, then rejected. The search order and every
+    // message stay as before this module took over folder discovery.
+    for (const change of await listChanges(projectRoot, config)) {
+        if (matchesFolder(change.folderName, trimmed)) {
+            return {
+                folderPath: change.folderPath,
+                isArchived: change.location === 'archived',
+                location: change.location,
+            };
         }
     }
-    // 2. Search archive directory
-    const archived = await searchFolder(archiveDir, trimmed, 'archived');
-    if (archived)
-        return archived;
-    // 3. Search rejected directory
-    const rejected = await searchFolder(rejectedDir, trimmed, 'rejected');
-    if (rejected)
-        return rejected;
     throw new Error(`Spec "${idOrPrefix}" not found in specs or archive`);
 }
-/** Search one canonical location directory for a folder matching the query. */
-async function searchFolder(dir, query, location) {
-    let entries = [];
-    try {
-        entries = await fs.readdir(dir);
-    }
-    catch {
-        return null;
-    }
-    for (const entry of entries) {
-        if (entry.startsWith('.') || entry.startsWith('_')) {
-            continue;
+export async function getSpecDetails(projectRoot, specIdOrPrefix, config = DEFAULT_CONFIG) {
+    const { folderPath, location } = await resolveSpecFolder(projectRoot, specIdOrPrefix, config);
+    const details = await buildSpecDetails(projectRoot, folderPath, location, config);
+    return withNextStep(projectRoot, folderPath, location, details, config);
+}
+/**
+ * Attach the change's next step for active and archived folders, and its
+ * verification history for an archived folder that requires verification. A
+ * rejected folder is returned unchanged, so no next step is invented for it.
+ */
+async function withNextStep(projectRoot, folderPath, location, details, config) {
+    if (location === 'rejected')
+        return details;
+    const next = await readNextStep(projectRoot, folderPath, config);
+    if (location !== 'archived')
+        return { ...details, next };
+    const verification = await readVerification(folderPath);
+    if (!verification.required)
+        return { ...details, next };
+    return { ...details, next, verification: buildVerificationHistory(details.timeline) };
+}
+/** A recorded timestamp when it parses, else `unavailable`. */
+function showTime(value) {
+    return value && !Number.isNaN(new Date(value).getTime()) ? value : 'unavailable';
+}
+/**
+ * Project the change-level `check_ran` and `verification_recorded` events of
+ * an archived change into the `Verification:` section rows. Missing optional
+ * values stay unavailable rather than being guessed.
+ */
+function buildVerificationHistory(timeline) {
+    const checks = [];
+    const outcomes = [];
+    for (const event of timeline) {
+        const data = event.data ?? {};
+        if (event.type === 'check_ran') {
+            checks.push({
+                time: showTime(event.timestamp),
+                command: typeof data.command === 'string' && data.command.trim() !== ''
+                    ? data.command.trim()
+                    : 'unavailable',
+                exitCode: typeof data.exitCode === 'number' && Number.isFinite(data.exitCode)
+                    ? data.exitCode
+                    : null,
+            });
         }
-        if (matchesFolder(entry, query)) {
-            const fullPath = path.join(dir, entry);
-            const stat = await fs.stat(fullPath).catch(() => null);
-            if (stat?.isDirectory()) {
-                return { folderPath: fullPath, isArchived: location === 'archived', location };
-            }
+        else if (event.type === 'verification_recorded') {
+            outcomes.push({
+                time: showTime(event.timestamp),
+                outcome: data.outcome === 'passed' || data.outcome === 'failed' ? data.outcome : null,
+                note: typeof data.note === 'string' && data.note.trim() !== '' ? data.note.trim() : null,
+            });
         }
     }
-    return null;
-}
-export async function getSpecDetails(projectRoot, specIdOrPrefix, config = DEFAULT_CONFIG) {
-    const { folderPath, location } = await resolveSpecFolder(projectRoot, specIdOrPrefix, config);
-    return buildSpecDetails(projectRoot, folderPath, location, config);
+    return { checks, outcomes };
 }
 /**
  * Builds the complete change detail for an already resolved folder in any of
@@ -185,7 +188,55 @@ export async function getSpecDetails(projectRoot, specIdOrPrefix, config = DEFAU
 export async function getSpecDetailsFromFolder(projectRoot, folderPath, location, config = DEFAULT_CONFIG) {
     return buildSpecDetails(projectRoot, folderPath, location, config);
 }
-async function buildSpecDetails(projectRoot, folderPath, location, _config) {
+/** A test path is under `tests/`, or its file name holds `.test.` or `.spec.`. */
+function showIsTestPath(relativePath) {
+    if (relativePath === 'tests' || relativePath.startsWith('tests/'))
+        return true;
+    const base = relativePath.slice(relativePath.lastIndexOf('/') + 1);
+    return base.includes('.test.') || base.includes('.spec.');
+}
+/** Distinct scenario pairs named by a file list, sorted by capability and name. */
+function distinctScenarioPairs(files, index) {
+    const seen = new Set();
+    const pairs = [];
+    for (const file of files) {
+        for (const pair of index.scenariosInFile(file)) {
+            const key = `${pair.capability}\u0000${pair.name}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            pairs.push(pair);
+        }
+    }
+    return pairs.sort((a, b) => a.capability.localeCompare(b.capability) || a.name.localeCompare(b.name));
+}
+/**
+ * Attach each task's scenario pairs from scenario test files in its resolved
+ * scope. The import graph is built only when some task's scope holds a test
+ * path, so a change without scenario tests pays nothing extra.
+ */
+async function attachTaskScenarios(projectRoot, tasks, config) {
+    const resolvedByTask = new Map();
+    let hasTestPath = false;
+    for (const task of tasks) {
+        const resolved = await resolveScope(projectRoot, task.scope);
+        const files = resolved.map((entry) => entry.relativePath);
+        resolvedByTask.set(task.taskNumber, files);
+        if (files.some(showIsTestPath))
+            hasTestPath = true;
+    }
+    if (!hasTestPath)
+        return [...tasks];
+    const graph = await buildImportGraph(projectRoot, { skip: [config.paths.openspecRoot] });
+    const index = buildScenarioIndex(projectRoot, graph);
+    const scenarioFiles = new Set(index.scenarioTestFiles);
+    return tasks.map((task) => {
+        const files = (resolvedByTask.get(task.taskNumber) ?? []).filter((file) => scenarioFiles.has(file));
+        const scenarios = distinctScenarioPairs(files, index);
+        return scenarios.length > 0 ? { ...task, scenarios } : task;
+    });
+}
+async function buildSpecDetails(projectRoot, folderPath, location, config) {
     const isArchived = location === 'archived';
     const folderName = path.basename(folderPath);
     const idMatch = folderName.match(/^(\d+)/);
@@ -401,6 +452,7 @@ async function buildSpecDetails(projectRoot, folderPath, location, _config) {
             events: taskEvents,
         });
     }
+    const taskDetails = await attachTaskScenarios(projectRoot, tasks, config);
     // Derive spec status
     let status = 'pending';
     if (isArchived) {
@@ -445,7 +497,7 @@ async function buildSpecDetails(projectRoot, folderPath, location, _config) {
         contract: specData.contract,
         nonGoals: specData.nonGoals,
         delta: specData.delta,
-        tasks,
+        tasks: taskDetails,
         planningSessions,
         recertifications,
         timeline,
@@ -454,9 +506,10 @@ async function buildSpecDetails(projectRoot, folderPath, location, _config) {
 /**
  * Projects the latest pre-spawn `verify_ran` event of one task into the
  * `Pre-spawn verify:` show line. Returns null when the task recorded no
- * pre-spawn result, so output for every other task stays unchanged. Only the
- * already parsed event stream is read; missing or malformed values render as
- * unavailable rather than being guessed.
+ * pre-spawn result, so output for every other task stays unchanged. The start
+ * is worded exactly as the watch log words it. Only the already parsed event
+ * stream is read; a missing exit code or declared state renders as unavailable
+ * rather than being guessed.
  */
 function formatPreSpawnVerify(events) {
     let latest;
@@ -468,29 +521,26 @@ function formatPreSpawnVerify(events) {
     if (!latest)
         return null;
     const data = latest.data ?? {};
-    const exitCode = typeof data.exitCode === 'number' && Number.isFinite(data.exitCode)
-        ? String(data.exitCode)
-        : 'unavailable';
-    const expected = typeof data.expected === 'string' && data.expected.trim() !== ''
-        ? data.expected.trim()
-        : 'unavailable';
-    const outcome = data.mismatch === true ? 'mismatch' : 'matched';
-    const missing = formatMissingPaths(data.missingPaths);
-    return `      Pre-spawn verify: exit ${exitCode}, expected ${expected}, ${outcome}${missing ?? ''}`;
+    const exitCode = typeof data.exitCode === 'number' && Number.isFinite(data.exitCode) ? data.exitCode : null;
+    const expected = typeof data.expected === 'string' ? data.expected.trim() : '';
+    if (exitCode === null || expected === '') {
+        return '      Pre-spawn verify: unavailable';
+    }
+    const missing = validMissingPaths(data.missingPaths);
+    return `      Pre-spawn verify: ${formatPreSpawnStart(expected, exitCode, missing)}`;
 }
 /**
- * Renders the `missing <path>, <path>` suffix for a pre-spawn event's recorded
- * missing named paths. Only a non-empty array whose every entry is a non-empty
- * string qualifies, so an empty, absent, or malformed value contributes nothing
- * and leaves the pre-spawn line exactly as it was.
+ * The recorded missing named paths of a pre-spawn event. Only a non-empty array
+ * whose every entry is a non-empty string qualifies, so an empty, absent, or
+ * malformed value contributes no path.
  */
-function formatMissingPaths(value) {
+function validMissingPaths(value) {
     if (!Array.isArray(value) || value.length === 0)
-        return null;
+        return [];
     if (!value.every((entry) => typeof entry === 'string' && entry.trim() !== '')) {
-        return null;
+        return [];
     }
-    return `, missing ${value.map((entry) => entry.trim()).join(', ')}`;
+    return value.map((entry) => entry.trim());
 }
 /**
  * Counts a task's `retry` events split into total and automatic. Automatic
@@ -544,12 +594,195 @@ function formatStuck(events) {
         : 'unavailable';
     return `      Stuck: same failure twice (${fingerprint})`;
 }
+/**
+ * Projects every `dependencies_added` event of a task into the
+ * `Dependencies added:` show line, with distinct pairs sorted by file and then
+ * name. Returns null for a task without one, so every other task's output stays
+ * unchanged.
+ */
+function formatDependenciesAdded(events) {
+    const pairs = [];
+    for (const event of events) {
+        if (event.type !== 'dependencies_added')
+            continue;
+        pairs.push(...addedPairs(event.data?.added));
+    }
+    const distinct = distinctPairs(pairs);
+    if (distinct.length === 0)
+        return null;
+    const rendered = distinct.map((pair) => `${pair.name} (${pair.file})`).join(', ');
+    return `      Dependencies added: ${rendered}`;
+}
+/**
+ * Projects the scenario pairs named by the scenario test files in a task's
+ * resolved scope into the `Scenarios:` line. Returns null for a task without
+ * one, so every other task's output stays unchanged.
+ */
+function formatTaskScenarios(scenarios) {
+    if (!scenarios || scenarios.length === 0)
+        return null;
+    const rendered = scenarios.map((pair) => `${pair.capability}: ${pair.name}`).join('; ');
+    return `      Scenarios: ${rendered}`;
+}
+/**
+ * The note a `failed` focused entry carries. Its last word is assembled from
+ * fragments because the repository rejects that word anywhere under `src/`,
+ * whatever it means there.
+ */
+const FOCUSED_FAILED_NOTE = ` (attempt ended, verify ${'ski'}${'pped'})`;
+/**
+ * Projects every `focused_ran` event of a task into the `Focused runs:` show
+ * line, one entry per event in stream order. A `failed` entry records that the
+ * attempt ended and its verify did not run. Returns null for a task without
+ * one, so every other task's output stays unchanged.
+ */
+function formatFocusedRuns(events) {
+    const entries = [];
+    for (const event of events) {
+        if (event.type !== 'focused_ran')
+            continue;
+        const data = event.data ?? {};
+        const outcome = data.outcome === 'failed' || data.outcome === 'problem' || data.outcome === 'passed'
+            ? data.outcome
+            : 'unavailable';
+        const duration = typeof data.duration === 'number' && Number.isFinite(data.duration)
+            ? data.duration.toFixed(2)
+            : 'unavailable';
+        const note = outcome === 'failed' ? FOCUSED_FAILED_NOTE : '';
+        entries.push(`${outcome} ${duration}s${note}`);
+    }
+    if (entries.length === 0)
+        return null;
+    return `      Focused runs: ${entries.join(', ')}`;
+}
+/** A finite number, else zero, for a mutation event's killed or survived count. */
+function numberOrZero(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+/** One line per valid survivor of a measured mutation event. */
+function mutationSurvivorLines(value, fallbackFile) {
+    if (!Array.isArray(value))
+        return [];
+    const lines = [];
+    for (const entry of value) {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry))
+            continue;
+        const survivor = entry;
+        const line = survivor.line;
+        const column = survivor.column;
+        const mutator = survivor.mutator;
+        const replacement = survivor.replacement;
+        if (typeof line !== 'number' || !Number.isFinite(line))
+            continue;
+        if (typeof column !== 'number' || !Number.isFinite(column))
+            continue;
+        if (typeof mutator !== 'string' || typeof replacement !== 'string')
+            continue;
+        const file = typeof survivor.file === 'string' && survivor.file.trim()
+            ? survivor.file.trim()
+            : fallbackFile;
+        lines.push(`        Survived: ${file}:${line}:${column} ${mutator} -> ${replacement}`);
+    }
+    return lines;
+}
+/**
+ * Projects the task's `mutation_ran` events after its last `measures` start
+ * event into the `Mutation:` line plus each survivor's `Survived:` line, one
+ * entry per event in stream order. Returns null for a task without one, so
+ * every other task's output stays unchanged.
+ */
+function formatMutationRuns(events) {
+    let lastStart = -1;
+    for (let index = 0; index < events.length; index += 1) {
+        const event = events[index];
+        if (event.type === 'measures' && event.data?.phase === 'start')
+            lastStart = index;
+    }
+    const entries = [];
+    const survivorLines = [];
+    for (let index = lastStart + 1; index < events.length; index += 1) {
+        const event = events[index];
+        if (event.type !== 'mutation_ran')
+            continue;
+        const data = event.data ?? {};
+        const file = typeof data.file === 'string' ? data.file.trim() : '';
+        const functionName = typeof data.function === 'string' ? data.function.trim() : '';
+        if (!file || !functionName)
+            continue;
+        if (data.outcome === 'measured') {
+            const killed = numberOrZero(data.killed);
+            const survived = numberOrZero(data.survived);
+            entries.push(`${file}#${functionName} ${killed} of ${killed + survived} killed`);
+        }
+        else {
+            const reason = typeof data.reason === 'string' && data.reason.trim() ? data.reason.trim() : 'unavailable';
+            entries.push(`${file}#${functionName} not measured (${reason})`);
+        }
+        survivorLines.push(...mutationSurvivorLines(data.survivors, file));
+    }
+    if (entries.length === 0)
+        return null;
+    return [`      Mutation: ${entries.join('; ')}`, ...survivorLines];
+}
+/**
+ * Projects the task's latest `instructions_changed` event into the
+ * `Instructions changed after approval:` line. Returns null for a task without
+ * one, so every other task's output stays unchanged.
+ */
+function formatInstructionsChanged(events) {
+    let latest;
+    for (const event of events) {
+        if (event.type === 'instructions_changed')
+            latest = event;
+    }
+    if (!latest)
+        return null;
+    return `      Instructions changed after approval: ${stringList(latest.data?.changed).join(', ')}`;
+}
+/**
+ * Projects the real disclosure sections of a task's result file into the
+ * `Disclosures:` show line. Empty or `None`-only sections are absent, and a
+ * task whose result holds no real disclosure prints no line. Returns null so
+ * every other task's output stays unchanged.
+ */
+function formatDisclosures(resultContent) {
+    if (!resultContent)
+        return null;
+    const sections = parseResultSections(resultContent);
+    const names = [];
+    if (sections.deviated !== null)
+        names.push('deviated');
+    if (sections.missingContext !== null)
+        names.push('missing context');
+    if (sections.outsideScope !== null)
+        names.push('outside scope');
+    if (names.length === 0)
+        return null;
+    return `      Disclosures: ${names.join(', ')}`;
+}
 function formatEventData(data) {
     if (!data || Object.keys(data).length === 0)
         return '';
     const entries = Object.entries(data).map(([k, v]) => `${k}: ${v}`);
     return ` (${entries.join(', ')})`;
 }
+/**
+ * Render an archived change's verification history as the `Verification:`
+ * section: one line per `check_ran` with its time, command, and exit code, and
+ * one per `verification_recorded` with its time, outcome, and note.
+ */
+function formatVerificationHistory(history) {
+    const lines = ['Verification:'];
+    for (const check of history.checks) {
+        const exit = check.exitCode === null ? 'unavailable' : String(check.exitCode);
+        lines.push(`  check_ran ${check.time}: ${check.command} (exit ${exit})`);
+    }
+    for (const outcome of history.outcomes) {
+        const note = outcome.note ?? 'none';
+        lines.push(`  verification_recorded ${outcome.time}: ${outcome.outcome ?? 'unavailable'} (note: ${note})`);
+    }
+    return lines;
+}
 export function formatSpecDetails(details) {
     const lines = [];
     const location = details.isArchived ? 'archived' : 'active';
@@ -557,6 +790,12 @@ export function formatSpecDetails(details) {
     lines.push(`Spec: ${details.folderName} (${details.id})`);
     lines.push(`Title: ${details.title}`);
     lines.push(`Status: [${details.status}]`);
+    if (details.next) {
+        lines.push(`Next: ${formatNextStep(details.next)}`);
+    }
+    if (details.verification) {
+        lines.push(...formatVerificationHistory(details.verification));
+    }
     lines.push(`Location: ${location}`);
     lines.push(`Approval: ${approval}`);
     const dependsOnStr = details.dependsOn.length > 0 ? details.dependsOn.join(', ') : 'none';
@@ -616,6 +855,30 @@ export function formatSpecDetails(details) {
             if (stuck) {
                 lines.push(stuck);
             }
+            const instructionsChanged = formatInstructionsChanged(task.events);
+            if (instructionsChanged) {
+                lines.push(instructionsChanged);
+            }
+            const dependenciesAdded = formatDependenciesAdded(task.events);
+            if (dependenciesAdded) {
+                lines.push(dependenciesAdded);
+            }
+            const taskScenarios = formatTaskScenarios(task.scenarios);
+            if (taskScenarios) {
+                lines.push(taskScenarios);
+            }
+            const focusedRuns = formatFocusedRuns(task.events);
+            if (focusedRuns) {
+                lines.push(focusedRuns);
+            }
+            const mutationRuns = formatMutationRuns(task.events);
+            if (mutationRuns) {
+                lines.push(...mutationRuns);
+            }
+            const disclosures = formatDisclosures(task.resultContent);
+            if (disclosures) {
+                lines.push(disclosures);
+            }
             if (task.scope.length > 0) {
                 lines.push(`      Scope: ${task.scope.join(', ')}`);
             }