sinapse-ai 9.4.0 → 9.5.0

package/scripts/coverage-report-summary.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * coverage-report-summary — Story 10.25
+ *
+ * Reads coverage/coverage-summary.json (Jest `json-summary` reporter)
+ * and prints a Current vs Floor comparison table to stdout. When run
+ * inside GitHub Actions (GITHUB_STEP_SUMMARY env var set), also writes
+ * a Markdown table to the job summary file so reviewers see coverage
+ * in the PR Checks tab.
+ *
+ * Always exits 0 — coverage gating is enforced by Jest's
+ * coverageThreshold in jest.config.js, not by this script.
+ *
+ * Usage:
+ *   node scripts/coverage-report-summary.js
+ *   node scripts/coverage-report-summary.js --json   (JSON output)
+ *
+ * Reads ratchet floors from jest.config.js coverageThreshold.global.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+const SUMMARY_PATH = path.join(PROJECT_ROOT, 'coverage', 'coverage-summary.json');
+const JEST_CONFIG_PATH = path.join(PROJECT_ROOT, 'jest.config.js');
+
+function readCoverageSummary(summaryPath = SUMMARY_PATH) {
+  if (!fs.existsSync(summaryPath)) {
+    return null;
+  }
+  try {
+    const raw = fs.readFileSync(summaryPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function readRatchetFloors(jestConfigPath = JEST_CONFIG_PATH) {
+  // We don't require() jest.config.js because Jest itself loads it with
+  // its own resolver. Instead we parse it as text and extract the global
+  // floors. This avoids running jest at script load time.
+  if (!fs.existsSync(jestConfigPath)) {
+    return null;
+  }
+  const raw = fs.readFileSync(jestConfigPath, 'utf8');
+  const globalBlockMatch = raw.match(/global:\s*\{([^}]+)\}/);
+  if (!globalBlockMatch) return null;
+  const block = globalBlockMatch[1];
+  const floors = {};
+  for (const key of ['statements', 'branches', 'lines', 'functions']) {
+    const re = new RegExp(`${key}\\s*:\\s*(\\d+)`);
+    const m = block.match(re);
+    if (m) floors[key] = Number(m[1]);
+  }
+  return floors;
+}
+
+function buildRows(summary, floors) {
+  if (!summary || !summary.total || !floors) return [];
+  const total = summary.total;
+  const metrics = ['statements', 'branches', 'lines', 'functions'];
+  return metrics.map((m) => {
+    const actual = total[m] && typeof total[m].pct === 'number' ? total[m].pct : null;
+    const floor = typeof floors[m] === 'number' ? floors[m] : null;
+    let status = '?';
+    if (actual !== null && floor !== null) {
+      status = actual >= floor ? 'PASS' : 'FAIL';
+    }
+    return { metric: m, floor, actual, status };
+  });
+}
+
+function formatAsciiTable(rows) {
+  const header = ['Metric', 'Floor', 'Actual', 'Status'];
+  const widths = header.map((h) => h.length);
+  for (const r of rows) {
+    widths[0] = Math.max(widths[0], r.metric.length);
+    widths[1] = Math.max(widths[1], String(r.floor).length + 1); // +1 for %
+    widths[2] = Math.max(widths[2], String(r.actual).length + 1);
+    widths[3] = Math.max(widths[3], r.status.length);
+  }
+  const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+  const fmt = (cells) =>
+    '| '
+    + cells.map((c, i) => String(c).padEnd(widths[i])).join(' | ')
+    + ' |';
+  const lines = [sep, fmt(header), sep];
+  for (const r of rows) {
+    lines.push(
+      fmt([
+        r.metric,
+        r.floor === null ? '?' : `${r.floor}%`,
+        r.actual === null ? '?' : `${r.actual}%`,
+        r.status,
+      ]),
+    );
+  }
+  lines.push(sep);
+  return lines.join('\n');
+}
+
+function formatMarkdownTable(rows) {
+  const lines = [];
+  lines.push('### Coverage Report (Story 10.19 ratchet)');
+  lines.push('');
+  lines.push('| Metric | Floor | Actual | Status |');
+  lines.push('|--------|-------|--------|--------|');
+  for (const r of rows) {
+    const floorStr = r.floor === null ? '?' : `${r.floor}%`;
+    const actualStr = r.actual === null ? '?' : `${r.actual}%`;
+    const statusEmoji = r.status === 'PASS' ? '✅' : r.status === 'FAIL' ? '❌' : '❓';
+    lines.push(`| ${r.metric} | ${floorStr} | ${actualStr} | ${statusEmoji} |`);
+  }
+  return lines.join('\n');
+}
+
+function appendToGithubSummary(markdown) {
+  const target = process.env.GITHUB_STEP_SUMMARY;
+  if (!target) return false;
+  try {
+    fs.appendFileSync(target, markdown + '\n\n', 'utf8');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  const summary = readCoverageSummary();
+  if (!summary) {
+    console.log('=== coverage-report-summary ===');
+    console.log('No coverage/coverage-summary.json found — run `npm run test:coverage` first.');
+    return 0;
+  }
+  const floors = readRatchetFloors();
+  if (!floors) {
+    console.log('=== coverage-report-summary ===');
+    console.log('Could not parse jest.config.js coverageThreshold.global — skipping comparison.');
+    return 0;
+  }
+  const rows = buildRows(summary, floors);
+  if (args.has('--json')) {
+    console.log(JSON.stringify({ rows, floors }, null, 2));
+    return 0;
+  }
+  console.log('=== Coverage Report (Story 10.19 ratchet) ===');
+  console.log(formatAsciiTable(rows));
+  appendToGithubSummary(formatMarkdownTable(rows));
+  return 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main();
+}
+
+module.exports = {
+  readCoverageSummary,
+  readRatchetFloors,
+  buildRows,
+  formatAsciiTable,
+  formatMarkdownTable,
+  appendToGithubSummary,
+  main,
+};

package/scripts/generate-install-manifest.js

@@ -274,9 +274,13 @@ async function generateManifest() {
   fileEntries.sort((a, b) => a.path.localeCompare(b.path));
 
   // Build manifest object
+  // Story 10.27 — `generated_at` removed from the manifest body to keep
+  // the file deterministic across regenerations. Without removal, every
+  // post-commit hook regen produced a new timestamp -> new file content
+  // -> recurring "M install-manifest.yaml" churn in git status. Consumers
+  // (post-install-validator) treat the field as optional metadata.
   const manifest = {
     version: version,
-    generated_at: new Date().toISOString(),
     generator: 'scripts/generate-install-manifest.js',
     file_count: fileEntries.length,
     files: fileEntries,
@@ -318,7 +322,7 @@ async function writeManifest(manifest) {
   console.log(`\nManifest written to: ${manifestPath}`);
   console.log(`  Version: ${manifest.version}`);
   console.log(`  Files: ${manifest.file_count}`);
-  console.log(`  Generated: ${manifest.generated_at}`);
+  console.log(`  Generated: ${new Date().toISOString()}`);
 
   // Also compute and display manifest hash for integrity verification
   const manifestHash = hashString(yamlContent);

package/scripts/release-readiness.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * release-readiness — Story 10.29
+ *
+ * Aggregates every validator and quality gate built throughout Epic 10.0
+ * into one release-readiness report. Run before opening a release PR or
+ * tagging v10.0.0 to confirm the framework is shippable.
+ *
+ * Validators executed (in order):
+ *   1. lint              — npm run lint
+ *   2. typecheck         — npm run typecheck
+ *   3. agents            — npm run validate:agents
+ *   4. squad-orqx        — npm run validate:squad-orqx     (Story 10.28)
+ *   5. story-meta        — npm run validate:story-meta     (Story 10.19)
+ *   6. no-external-refs  — npm run validate:no-external-refs (Story 10.17)
+ *   7. parity            — npm run validate:parity         (Story 10.18)
+ *   8. manifest          — npm run validate:manifest
+ *   9. install-docs      — npm run validate:docs
+ *
+ * Each gate runs in its own subprocess. Failures are reported but do NOT
+ * short-circuit — the script always runs every gate so the operator sees
+ * the full picture in one pass.
+ *
+ * Exit codes:
+ *   0  every gate passed
+ *   1  one or more gates failed (per-gate detail in the summary table)
+ *
+ * Usage:
+ *   node scripts/release-readiness.js
+ *   node scripts/release-readiness.js --json
+ *   node scripts/release-readiness.js --quiet
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const PROJECT_ROOT = path.resolve(__dirname, '..');
+
+const GATES = [
+  { id: 'lint', name: 'ESLint', cmd: ['npm', 'run', 'lint', '--silent'] },
+  { id: 'typecheck', name: 'TypeScript', cmd: ['npm', 'run', 'typecheck', '--silent'] },
+  { id: 'agents', name: 'Core agents', cmd: ['npm', 'run', 'validate:agents', '--silent'] },
+  { id: 'squad-orqx', name: 'Squad orqx (10.28)', cmd: ['npm', 'run', 'validate:squad-orqx', '--silent'] },
+  { id: 'story-meta', name: 'Story meta (10.19)', cmd: ['npm', 'run', 'validate:story-meta', '--silent'] },
+  { id: 'no-external-refs', name: 'External refs (10.17)', cmd: ['npm', 'run', 'validate:no-external-refs', '--silent'] },
+  { id: 'parity', name: 'Cross-IDE parity (10.18)', cmd: ['npm', 'run', 'validate:parity', '--silent'] },
+  { id: 'manifest', name: 'Install manifest', cmd: ['npm', 'run', 'validate:manifest', '--silent'] },
+  { id: 'install-docs', name: 'Install docs', cmd: ['npm', 'run', 'validate:docs', '--silent'] },
+];
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = new Set(argv);
+  return {
+    json: args.has('--json'),
+    quiet: args.has('--quiet') || args.has('-q'),
+  };
+}
+
+function runGate(gate) {
+  const start = Date.now();
+  const result = spawnSync(gate.cmd[0], gate.cmd.slice(1), {
+    cwd: PROJECT_ROOT,
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  const elapsed = Date.now() - start;
+  return {
+    id: gate.id,
+    name: gate.name,
+    status: result.status === 0 ? 'PASS' : 'FAIL',
+    exitCode: result.status,
+    elapsedMs: elapsed,
+    stderr: result.stderr ? result.stderr.split('\n').slice(-5).join('\n') : '',
+  };
+}
+
+function runAllGates(gates = GATES) {
+  return gates.map((g) => runGate(g));
+}
+
+function summarize(results) {
+  return {
+    total: results.length,
+    pass: results.filter((r) => r.status === 'PASS').length,
+    fail: results.filter((r) => r.status === 'FAIL').length,
+    elapsedMs: results.reduce((sum, r) => sum + r.elapsedMs, 0),
+  };
+}
+
+function formatTable(results) {
+  const lines = [];
+  const widths = [22, 8, 8, 6];
+  const sep = '+' + widths.map((w) => '-'.repeat(w + 2)).join('+') + '+';
+  lines.push(sep);
+  lines.push(
+    '| '
+    + 'Gate'.padEnd(widths[0])
+    + ' | '
+    + 'Status'.padEnd(widths[1])
+    + ' | '
+    + 'Time'.padEnd(widths[2])
+    + ' | '
+    + 'Exit'.padEnd(widths[3])
+    + ' |',
+  );
+  lines.push(sep);
+  for (const r of results) {
+    lines.push(
+      '| '
+      + r.name.padEnd(widths[0])
+      + ' | '
+      + r.status.padEnd(widths[1])
+      + ' | '
+      + `${r.elapsedMs}ms`.padEnd(widths[2])
+      + ' | '
+      + String(r.exitCode).padEnd(widths[3])
+      + ' |',
+    );
+  }
+  lines.push(sep);
+  return lines.join('\n');
+}
+
+function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (!args.quiet && !args.json) {
+    console.log('=== release-readiness ===');
+    console.log('Running all release gates (this can take a few minutes)...');
+    console.log('');
+  }
+  const results = runAllGates();
+  const summary = summarize(results);
+
+  if (args.json) {
+    console.log(JSON.stringify({ results, summary }, null, 2));
+  } else if (!args.quiet) {
+    console.log(formatTable(results));
+    console.log('');
+    console.log(
+      `Summary: ${summary.total} gates — ${summary.pass} pass, ${summary.fail} fail (${summary.elapsedMs}ms total)`,
+    );
+    if (summary.fail > 0) {
+      console.log('');
+      console.log('Failed gates (last 5 lines of stderr):');
+      for (const r of results.filter((x) => x.status === 'FAIL')) {
+        console.log(`\n--- ${r.name} ---`);
+        console.log(r.stderr || '(no stderr)');
+      }
+    }
+  }
+
+  return summary.fail > 0 ? 1 : 0;
+}
+
+if (require.main === module) {
+  process.exitCode = main();
+}
+
+module.exports = {
+  parseArgs,
+  GATES,
+  runGate,
+  runAllGates,
+  summarize,
+  formatTable,
+  main,
+};

package/scripts/test-install-matrix-local.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Story A.5 - Local install matrix helper
+#
+# Best-effort local validation of the install matrix. You can only fully
+# validate the OS you are currently running on — the other 2 OSes are
+# covered by the GitHub Actions workflow `.github/workflows/install-matrix.yml`
+# on release PRs.
+#
+# Usage:
+#   bash scripts/test-install-matrix-local.sh              # runs all PMs x methods available locally
+#   bash scripts/test-install-matrix-local.sh --pm npm     # limit to one PM
+#   bash scripts/test-install-matrix-local.sh --method global
+#   bash scripts/test-install-matrix-local.sh --only npm:global,pnpm:local
+#
+# What it does:
+#   1. Packs the current repo with `npm pack` into a tarball
+#   2. For each selected (pm, method) combo, creates a scratch dir and runs
+#      the SAME combo runner used by CI: .github/workflows/install-matrix/run-combo.sh
+#   3. Prints a summary table of local results
+#
+# What it does NOT do:
+#   - Run on OSes other than the current one
+#   - Replace the CI workflow (the gate for rc -> latest promotion)
+
+set -u
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Defaults
+FILTER_PM=""
+FILTER_METHOD=""
+ONLY=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --pm)     FILTER_PM="$2"; shift 2 ;;
+    --method) FILTER_METHOD="$2"; shift 2 ;;
+    --only)   ONLY="$2"; shift 2 ;;
+    -h|--help)
+      sed -n '2,30p' "$0"
+      exit 0
+      ;;
+    *)
+      echo "Unknown arg: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+# Detect OS (for informational purposes only)
+OS_KIND="unknown"
+case "$(uname -s 2>/dev/null || echo Windows)" in
+  Linux*)  OS_KIND="linux" ;;
+  Darwin*) OS_KIND="macos" ;;
+  MINGW*|CYGWIN*|MSYS*|Windows*) OS_KIND="windows" ;;
+esac
+
+echo "=== Local install matrix helper ==="
+echo "OS:          $OS_KIND"
+echo "Repo:        $REPO_ROOT"
+echo "Node:        $(node --version 2>/dev/null || echo 'NOT FOUND')"
+echo "npm:         $(npm --version 2>/dev/null || echo 'NOT FOUND')"
+echo "pnpm:        $(pnpm --version 2>/dev/null || echo 'NOT INSTALLED (skipped)')"
+echo "yarn:        $(yarn --version 2>/dev/null || echo 'NOT INSTALLED (skipped)')"
+echo
+
+# Build tarball once
+echo "[1/3] Packing candidate tarball..."
+TARBALL_REL=$(npm pack --silent 2>/dev/null | tail -n1)
+if [ -z "$TARBALL_REL" ] || [ ! -f "$TARBALL_REL" ]; then
+  echo "ERROR: failed to pack candidate" >&2
+  exit 1
+fi
+TARBALL="$REPO_ROOT/$TARBALL_REL"
+echo "  tarball: $TARBALL"
+echo
+
+# Enumerate combos
+ALL_PMS="npm pnpm yarn"
+ALL_METHODS="global npx local"
+RESULTS=()
+
+should_run() {
+  local pm="$1" method="$2"
+  if [ -n "$FILTER_PM" ] && [ "$pm" != "$FILTER_PM" ]; then return 1; fi
+  if [ -n "$FILTER_METHOD" ] && [ "$method" != "$FILTER_METHOD" ]; then return 1; fi
+  if [ -n "$ONLY" ]; then
+    case ",$ONLY," in
+      *,"$pm:$method",*) return 0 ;;
+      *) return 1 ;;
+    esac
+  fi
+  return 0
+}
+
+has_pm() {
+  command -v "$1" >/dev/null 2>&1
+}
+
+echo "[2/3] Running combos..."
+TMP_BASE="$(mktemp -d 2>/dev/null || mktemp -d -t install-matrix)"
+trap 'rm -rf "$TMP_BASE"' EXIT
+
+for pm in $ALL_PMS; do
+  if ! has_pm "$pm"; then
+    echo "  skip $pm/* — $pm not installed locally"
+    continue
+  fi
+  for method in $ALL_METHODS; do
+    if ! should_run "$pm" "$method"; then continue; fi
+    echo "  -> $pm / $method"
+    SM_PM="$pm" \
+    SM_METHOD="$method" \
+    SM_TARBALL="$TARBALL" \
+    SM_TEST_DIR="$TMP_BASE/$pm-$method" \
+      bash "$REPO_ROOT/.github/workflows/install-matrix/run-combo.sh"
+    code=$?
+    if [ $code -eq 0 ]; then
+      RESULTS+=("PASS|$pm|$method")
+    else
+      RESULTS+=("FAIL|$pm|$method")
+    fi
+    echo
+  done
+done
+
+echo "[3/3] Local matrix summary ($OS_KIND):"
+printf "  %-6s %-6s %-8s %s\n" "STATUS" "PM" "METHOD" ""
+printf "  %-6s %-6s %-8s %s\n" "------" "----" "------" ""
+PASS_COUNT=0
+FAIL_COUNT=0
+for row in "${RESULTS[@]:-}"; do
+  IFS='|' read -r status pm method <<<"$row"
+  printf "  %-6s %-6s %-8s\n" "$status" "$pm" "$method"
+  case "$status" in
+    PASS) PASS_COUNT=$((PASS_COUNT+1)) ;;
+    FAIL) FAIL_COUNT=$((FAIL_COUNT+1)) ;;
+  esac
+done
+echo
+echo "  PASS: $PASS_COUNT   FAIL: $FAIL_COUNT"
+echo
+echo "NOTE: Local runs validate only $OS_KIND. The full 27-combo gate runs in CI"
+echo "      via .github/workflows/install-matrix.yml on release PRs."
+
+# Cleanup tarball
+rm -f "$TARBALL" 2>/dev/null || true
+
+if [ $FAIL_COUNT -gt 0 ]; then
+  exit 1
+fi
+exit 0