@wazir-dev/cli 1.0.0 → 1.2.0

package/tooling/src/reports/command.js

@@ -0,0 +1,103 @@
+import path from 'node:path';
+
+import { parseCommandOptions } from '../command-options.js';
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+import { collectPhaseMetrics, buildPhaseReport } from './phase-report.js';
+
+const USAGE = 'Usage: wazir report phase --run <run-id> --phase <phase> [--base <branch>] [--json]';
+
+function handlePhase(parsed, context = {}) {
+  const { options } = parseCommandOptions(parsed.args, {
+    boolean: ['json', 'help'],
+    string: ['run', 'phase', 'base', 'state-root'],
+  });
+
+  if (options.help) {
+    return {
+      exitCode: 0,
+      stdout: `${USAGE}\n\nGenerate a structured phase report with metrics from git, tests, and run state.\n`,
+    };
+  }
+
+  if (!options.run) {
+    return {
+      exitCode: 1,
+      stderr: `wazir report phase requires --run <id>\n${USAGE}\n`,
+    };
+  }
+
+  if (!options.phase) {
+    return {
+      exitCode: 1,
+      stderr: `wazir report phase requires --phase <phase>\n${USAGE}\n`,
+    };
+  }
+
+  const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+  const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+  const stateRoot = resolveStateRoot(projectRoot, manifest, {
+    cwd: context.cwd ?? process.cwd(),
+    override: options.stateRoot,
+  });
+
+  const metrics = collectPhaseMetrics({
+    projectRoot,
+    stateRoot,
+    runId: options.run,
+    phase: options.phase,
+    baseBranch: options.base ?? 'main',
+  });
+
+  const report = buildPhaseReport(metrics);
+
+  if (options.json) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify(report, null, 2)}\n`,
+    };
+  }
+
+  // Human-readable text output
+  const lines = [
+    `Phase Report: ${report.phase} (run ${report.run_id})`,
+    `Generated: ${report.generated_at}`,
+    '',
+    'Tests:',
+    `  total: ${report.metrics.tests.total}, passed: ${report.metrics.tests.passed}, failed: ${report.metrics.tests.failed}, skipped: ${report.metrics.tests.skipped}`,
+    '',
+    'Diff:',
+    `  files changed: ${report.metrics.diff.files_changed}, insertions: ${report.metrics.diff.insertions}, deletions: ${report.metrics.diff.deletions}`,
+    '',
+    'Files:',
+    `  added: ${report.metrics.files.added.length}, modified: ${report.metrics.files.modified.length}, deleted: ${report.metrics.files.deleted.length}`,
+    '',
+    `Artifacts: ${report.metrics.artifacts.length}`,
+    `Duration: ${report.metrics.duration_seconds !== null ? `${report.metrics.duration_seconds}s` : 'N/A'}`,
+  ];
+
+  return {
+    exitCode: 0,
+    stdout: `${lines.join('\n')}\n`,
+  };
+}
+
+export function runReportCommand(parsed, context = {}) {
+  try {
+    switch (parsed.subcommand) {
+      case 'phase':
+        return handlePhase(parsed, context);
+      default:
+        return {
+          exitCode: 1,
+          stderr: `${USAGE}\n`,
+        };
+    }
+  } catch (error) {
+    return {
+      exitCode: 1,
+      stderr: `${error.message}\n`,
+    };
+  }
+}

package/tooling/src/reports/phase-report.js

@@ -0,0 +1,323 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parse Node.js test runner output to extract pass/fail/skip counts.
+ * Handles the built-in `node --test` reporter format.
+ * @param {string} output - raw test runner stdout+stderr
+ * @returns {{ total: number, passed: number, failed: number, skipped: number }}
+ */
+export function parseTestOutput(output) {
+  const result = { total: 0, passed: 0, failed: 0, skipped: 0 };
+
+  if (!output) {
+    return result;
+  }
+
+  // Node built-in test runner summary lines:
+  //   # tests 12
+  //   # pass 10
+  //   # fail 1
+  //   # skipped 1
+  const totalMatch = output.match(/^# tests\s+(\d+)/m);
+  const passMatch = output.match(/^# pass\s+(\d+)/m);
+  const failMatch = output.match(/^# fail\s+(\d+)/m);
+  const skipMatch = output.match(/^# skipped\s+(\d+)/m);
+
+  if (totalMatch) {
+    result.total = Number.parseInt(totalMatch[1], 10);
+  }
+
+  if (passMatch) {
+    result.passed = Number.parseInt(passMatch[1], 10);
+  }
+
+  if (failMatch) {
+    result.failed = Number.parseInt(failMatch[1], 10);
+  }
+
+  if (skipMatch) {
+    result.skipped = Number.parseInt(skipMatch[1], 10);
+  }
+
+  // Fallback: if no summary lines found, try TAP-style counting
+  if (!totalMatch && !passMatch && !failMatch) {
+    const okLines = output.match(/^ok \d+/gm);
+    const notOkLines = output.match(/^not ok \d+/gm);
+    const skipLines = output.match(/^ok \d+ .+# skip/gim);
+
+    result.passed = (okLines?.length ?? 0) - (skipLines?.length ?? 0);
+    result.failed = notOkLines?.length ?? 0;
+    result.skipped = skipLines?.length ?? 0;
+    result.total = result.passed + result.failed + result.skipped;
+  }
+
+  return result;
+}
+
+/**
+ * Run tests and parse results, or return null on failure.
+ * @param {string} projectRoot
+ * @returns {{ total: number, passed: number, failed: number, skipped: number } | null}
+ */
+function collectTestResults(projectRoot) {
+  try {
+    const output = execFileSync(
+      'node',
+      ['--test', '--experimental-test-snapshots'],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 120_000 },
+    );
+
+    return parseTestOutput(output);
+  } catch (error) {
+    // Test command may exit non-zero if tests fail — still parse output
+    if (error.stdout || error.stderr) {
+      return parseTestOutput(`${error.stdout ?? ''}${error.stderr ?? ''}`);
+    }
+
+    return null;
+  }
+}
+
+/**
+ * Parse `git diff --stat` output for files changed, insertions, deletions.
+ * @param {string} statOutput - output of git diff --stat
+ * @returns {{ files_changed: number, insertions: number, deletions: number }}
+ */
+export function parseDiffStat(statOutput) {
+  const result = { files_changed: 0, insertions: 0, deletions: 0 };
+
+  if (!statOutput) {
+    return result;
+  }
+
+  // Summary line: " 5 files changed, 120 insertions(+), 30 deletions(-)"
+  const summaryMatch = statOutput.match(
+    /(\d+) files? changed(?:,\s*(\d+) insertions?\(\+\))?(?:,\s*(\d+) deletions?\(-\))?/,
+  );
+
+  if (summaryMatch) {
+    result.files_changed = Number.parseInt(summaryMatch[1], 10);
+    result.insertions = summaryMatch[2] ? Number.parseInt(summaryMatch[2], 10) : 0;
+    result.deletions = summaryMatch[3] ? Number.parseInt(summaryMatch[3], 10) : 0;
+  }
+
+  return result;
+}
+
+/**
+ * Parse `git diff --name-status` output into added/modified/deleted arrays.
+ * @param {string} nameStatusOutput
+ * @returns {{ added: string[], modified: string[], deleted: string[] }}
+ */
+export function parseNameStatus(nameStatusOutput) {
+  const result = { added: [], modified: [], deleted: [] };
+
+  if (!nameStatusOutput) {
+    return result;
+  }
+
+  for (const line of nameStatusOutput.split('\n')) {
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      continue;
+    }
+
+    const statusChar = trimmed[0];
+    const filePath = trimmed.slice(1).trim();
+
+    if (!filePath) {
+      continue;
+    }
+
+    switch (statusChar) {
+      case 'A':
+        result.added.push(filePath);
+        break;
+      case 'M':
+        result.modified.push(filePath);
+        break;
+      case 'D':
+        result.deleted.push(filePath);
+        break;
+      default:
+        // R (rename), C (copy), etc. — treat as modified
+        result.modified.push(filePath);
+        break;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Collect diff stats from git.
+ * @param {string} projectRoot
+ * @param {string} baseBranch
+ * @returns {{ files_changed: number, insertions: number, deletions: number } | null}
+ */
+function collectDiffStats(projectRoot, baseBranch) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['diff', '--stat', `${baseBranch}...HEAD`],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 15_000 },
+    );
+
+    return parseDiffStat(output);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect file change summary from git.
+ * @param {string} projectRoot
+ * @param {string} baseBranch
+ * @returns {{ added: string[], modified: string[], deleted: string[] } | null}
+ */
+function collectFileChanges(projectRoot, baseBranch) {
+  try {
+    const output = execFileSync(
+      'git',
+      ['diff', '--name-status', `${baseBranch}...HEAD`],
+      { cwd: projectRoot, encoding: 'utf8', timeout: 15_000 },
+    );
+
+    return parseNameStatus(output);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List artifact files in run directories.
+ * @param {string} stateRoot
+ * @param {string} runId
+ * @returns {string[]}
+ */
+function collectArtifacts(stateRoot, runId) {
+  const artifacts = [];
+  const clarifiedDir = path.join(stateRoot, 'runs', runId, 'clarified');
+  const artifactsDir = path.join(stateRoot, 'runs', runId, 'artifacts');
+
+  for (const dir of [clarifiedDir, artifactsDir]) {
+    if (fs.existsSync(dir)) {
+      try {
+        const entries = fs.readdirSync(dir);
+
+        for (const entry of entries) {
+          artifacts.push(path.join(dir, entry));
+        }
+      } catch {
+        // ignore read errors
+      }
+    }
+  }
+
+  return artifacts;
+}
+
+/**
+ * Compute phase duration from events.ndjson.
+ * Looks for phase_enter and phase_exit events matching the given phase.
+ * @param {string} stateRoot
+ * @param {string} runId
+ * @param {string} phase
+ * @returns {number | null} duration in seconds, or null if unavailable
+ */
+function collectDuration(stateRoot, runId, phase) {
+  const eventsPath = path.join(stateRoot, 'runs', runId, 'events.ndjson');
+
+  if (!fs.existsSync(eventsPath)) {
+    return null;
+  }
+
+  try {
+    const content = fs.readFileSync(eventsPath, 'utf8');
+    const lines = content.split('\n').filter(Boolean);
+
+    let enterTime = null;
+    let exitTime = null;
+
+    for (const line of lines) {
+      const event = JSON.parse(line);
+
+      if (event.phase !== phase) {
+        continue;
+      }
+
+      if (event.event === 'phase_enter' && event.created_at) {
+        enterTime = new Date(event.created_at).getTime();
+      }
+
+      if (event.event === 'phase_exit' && event.created_at) {
+        exitTime = new Date(event.created_at).getTime();
+      }
+    }
+
+    if (enterTime !== null && exitTime !== null && exitTime > enterTime) {
+      return Math.round((exitTime - enterTime) / 1000);
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Collect metrics for a phase report.
+ * @param {object} opts
+ * @param {string} opts.projectRoot - project root path
+ * @param {string} opts.stateRoot - state root path
+ * @param {string} opts.runId - current run ID
+ * @param {string} opts.phase - phase name (init|clarifier|executor|final_review)
+ * @param {string} [opts.baseBranch] - base branch for diff (default: 'main')
+ * @returns {object} structured metrics
+ */
+export function collectPhaseMetrics(opts) {
+  const { projectRoot, stateRoot, runId, phase } = opts;
+  const baseBranch = opts.baseBranch ?? 'main';
+
+  return {
+    run_id: runId,
+    phase,
+    generated_at: new Date().toISOString(),
+    tests: collectTestResults(projectRoot),
+    diff: collectDiffStats(projectRoot, baseBranch),
+    files: collectFileChanges(projectRoot, baseBranch),
+    artifacts: collectArtifacts(stateRoot, runId),
+    duration_seconds: collectDuration(stateRoot, runId, phase),
+  };
+}
+
+/**
+ * Build a complete phase report JSON.
+ * Deterministic fields from code, qualitative fields left as placeholders for agent.
+ * @param {object} metrics - output from collectPhaseMetrics
+ * @param {object} [qualitative] - agent-provided qualitative fields
+ * @returns {object} complete report
+ */
+export function buildPhaseReport(metrics, qualitative = {}) {
+  return {
+    run_id: metrics.run_id,
+    phase: metrics.phase,
+    generated_at: metrics.generated_at,
+    metrics: {
+      tests: metrics.tests ?? { total: 0, passed: 0, failed: 0, skipped: 0 },
+      diff: metrics.diff ?? { files_changed: 0, insertions: 0, deletions: 0 },
+      files: metrics.files ?? { added: [], modified: [], deleted: [] },
+      artifacts: metrics.artifacts ?? [],
+      duration_seconds: metrics.duration_seconds ?? null,
+    },
+    qualitative: {
+      summary: qualitative.summary ?? '',
+      drift_analysis: qualitative.drift_analysis ?? '',
+      decisions: qualitative.decisions ?? [],
+      risks: qualitative.risks ?? [],
+    },
+  };
+}

package/tooling/src/state/command.js

@@ -0,0 +1,160 @@
+import path from 'node:path';
+
+import { parseCommandOptions } from '../command-options.js';
+import { readYamlFile } from '../loaders.js';
+import { findProjectRoot } from '../project-root.js';
+import { resolveStateRoot } from '../state-root.js';
+import {
+  closeStateDb,
+  getAuditTrend,
+  getFindingsByRun,
+  getLearningsByScope,
+  getStateCounts,
+  getUsageSummary,
+  openStateDb,
+} from './db.js';
+
+function success(payload, options = {}) {
+  if (options.json) {
+    return {
+      exitCode: 0,
+      stdout: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+  }
+
+  return {
+    exitCode: 0,
+    stdout: `${options.formatText ? options.formatText(payload) : String(payload)}\n`,
+  };
+}
+
+function failure(message, exitCode = 1) {
+  return {
+    exitCode,
+    stderr: `${message}\n`,
+  };
+}
+
+function loadProjectContext(context, stateRootOverride) {
+  const projectRoot = findProjectRoot(context.cwd ?? process.cwd());
+  const manifest = readYamlFile(path.join(projectRoot, 'wazir.manifest.yaml'));
+  const stateRoot = resolveStateRoot(projectRoot, manifest, {
+    cwd: context.cwd ?? process.cwd(),
+    override: stateRootOverride,
+  });
+
+  return {
+    projectRoot,
+    manifest,
+    stateRoot,
+  };
+}
+
+export function runStateCommand(parsed, context = {}) {
+  try {
+    const { positional, options } = parseCommandOptions(parsed.args, {
+      boolean: ['json'],
+      string: ['state-root', 'limit'],
+    });
+    const { stateRoot } = loadProjectContext(context, options.stateRoot);
+
+    switch (parsed.subcommand) {
+      case 'stats': {
+        const db = openStateDb(stateRoot);
+
+        try {
+          const counts = getStateCounts(db);
+          const usage = getUsageSummary(db);
+
+          return success({ ...counts, usage }, {
+            json: options.json,
+            formatText: (value) => [
+              `Learnings: ${value.learning_count}`,
+              `Findings:  ${value.finding_count}`,
+              `Audits:    ${value.audit_count}`,
+              `Usage records: ${value.usage_count}`,
+            ].join('\n'),
+          });
+        } finally {
+          closeStateDb(db);
+        }
+      }
+
+      case 'learnings': {
+        const db = openStateDb(stateRoot);
+
+        try {
+          const limit = options.limit ? Number(options.limit) : undefined;
+          const learnings = getLearningsByScope(db, { limit });
+
+          return success(learnings, {
+            json: options.json,
+            formatText: (rows) => rows.length === 0
+              ? 'No learnings recorded.'
+              : rows.map((row) => {
+                const scope = [row.scope_roles, row.scope_stacks, row.scope_concerns]
+                  .filter(Boolean)
+                  .join(', ');
+                return `[${row.category}] ${row.content}${scope ? ` (${scope})` : ''} x${row.recurrence_count}`;
+              }).join('\n'),
+          });
+        } finally {
+          closeStateDb(db);
+        }
+      }
+
+      case 'findings': {
+        const runId = positional[0];
+
+        if (!runId) {
+          return failure('Usage: wazir state findings <run-id> [--state-root <path>] [--json]');
+        }
+
+        const db = openStateDb(stateRoot);
+
+        try {
+          const findings = getFindingsByRun(db, runId);
+
+          return success(findings, {
+            json: options.json,
+            formatText: (rows) => rows.length === 0
+              ? `No findings for run ${runId}.`
+              : rows.map((row) => {
+                const status = row.resolved ? 'RESOLVED' : 'OPEN';
+                return `[${row.severity}] [${status}] ${row.description} (${row.source}, ${row.phase})`;
+              }).join('\n'),
+          });
+        } finally {
+          closeStateDb(db);
+        }
+      }
+
+      case 'trend': {
+        const db = openStateDb(stateRoot);
+
+        try {
+          const limit = options.limit ? Number(options.limit) : 10;
+          const trend = getAuditTrend(db, limit);
+
+          return success(trend, {
+            json: options.json,
+            formatText: (rows) => rows.length === 0
+              ? 'No audit history.'
+              : rows.map((row) => {
+                const before = row.quality_score_before != null ? row.quality_score_before.toFixed(1) : '?';
+                const after = row.quality_score_after != null ? row.quality_score_after.toFixed(1) : '?';
+                return `${row.date} ${row.run_id} findings=${row.finding_count} fixed=${row.fix_count} manual=${row.manual_count} quality=${before}->${after}`;
+              }).join('\n'),
+          });
+        } finally {
+          closeStateDb(db);
+        }
+      }
+
+      default:
+        return failure('Usage: wazir state <stats|learnings|findings|trend> [options]');
+    }
+  } catch (error) {
+    return failure(error.message);
+  }
+}