@mifort-solutions/qmetrix 1.0.0

package/src/quality-dashboard.mjs

@@ -0,0 +1,291 @@
+#!/usr/bin/env node
+/**
+ * Code-quality dashboard generator (orchestrator) — COLLECT-ONLY.
+ *
+ * Walks the known artifact locations and renders a single, self-contained (offline,
+ * no CDN) HTML dashboard. It does NOT run linters, tests or audits; whatever a section
+ * needs must already exist on disk, and anything missing is clearly flagged with the
+ * command that generates it.
+ *
+ *   1. Tests, lint & types — coverage-summary.json + dist/reports/eslint.json + tsc.log
+ *   2. Security scanners   — Snyk / CodeQL / Checkmarx (local SARIF, else CI link)
+ *   3. Dependencies        — filterable table: prod/dev, what it is, why/when added,
+ *                            imported?, outdated?, vulnerable? (npm-audit.json / npm-outdated.json)
+ *   4. File graph          — internal import relationships (expandable folder tree + force graph)
+ *   5. Routing             — Next.js App Router tree (pages / API routes / layouts)
+ *   6. Component composition — app-rooted nested rectangles of feature widgets (props/state/events/API)
+ *   7. Data model          — ER-style entity boxes parsed from supabase/migrations/*.sql
+ *   8. Storybook           — link to the static Storybook built next to the dashboard
+ *   9. Codebase bundle     — the whole codebase as one browsable HTML file
+ *
+ * Read-only artifact inputs (generate them separately; the dashboard only reads them):
+ *   - dist/reports/coverage/<suite>/coverage-summary.json   (npm run coverage:unit / :all)
+ *   - dist/reports/eslint.json    (npm run lint -- -f json -o dist/reports/eslint.json)
+ *   - dist/reports/tsc.log        (npm run typecheck > dist/reports/tsc.log 2>&1)
+ *   - dist/reports/npm-audit.json (npm audit --json > dist/reports/npm-audit.json)
+ *   - dist/reports/npm-outdated.json (npm outdated --json > dist/reports/npm-outdated.json)
+ *   - dist/reports/*.sarif        (npm run security:scan)
+ *   - <outDir>/storybook/index.html (built by `npm run quality:dashboard`, or `npm run build-storybook`)
+ *
+ * The collection logic lives in dev/scripts/dashboard/collectors/*, shared helpers in
+ * dev/scripts/dashboard/utils/*, and the HTML rendering in dev/scripts/dashboard/render/*.
+ *
+ * The dependency "what it is / why / when" columns are populated automatically from
+ * each package's node_modules description and the git commit that introduced it in
+ * package.json. To curate them, create dev/scripts/dependency-notes.json:
+ *   { "<package>": { "description": "...", "reason": "...", "task": "PROJ-123", "added": "2026-06-05" } }
+ * Any field present there overrides the auto-detected value.
+ *
+ * Usage:
+ *   npm run quality:dashboard          # full deployable site: build Storybook + dashboard → dist/site/
+ *   node dev/scripts/quality-dashboard.mjs [options]   # fast report-only regen (no Storybook build)
+ *
+ * Options:
+ *   --out <file>   Output path (default: dist/site/index.html)
+ *   --no-bundle    Skip generating the codebase bundle (bundle-codebase.mjs)
+ *   --open         Open the dashboard when done
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+
+import { bundleCodebase } from './bundle-codebase.mjs';
+import { ROOT } from './dashboard/config.mjs';
+import { collectCode } from './dashboard/collectors/code.mjs';
+import { collectComposition } from './dashboard/collectors/composition.mjs';
+import { collectCoverage } from './dashboard/collectors/coverage.mjs';
+import { collectDeps } from './dashboard/collectors/deps.mjs';
+import { collectEntities } from './dashboard/collectors/entities.mjs';
+import { collectGraph } from './dashboard/collectors/graph.mjs';
+import { collectLint } from './dashboard/collectors/lint.mjs';
+import { collectRouting } from './dashboard/collectors/routing.mjs';
+import { collectSecurity } from './dashboard/collectors/security.mjs';
+import { collectStorybook } from './dashboard/collectors/storybook.mjs';
+import { render } from './dashboard/render/template.mjs';
+import { exec, log } from './dashboard/utils/exec.mjs';
+import { rel } from './dashboard/utils/fs.mjs';
+
+const argv = process.argv.slice(2);
+const flag = (name) => argv.includes(name);
+const opt = (name, fallback) => {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : fallback;
+};
+
+const OUT = path.resolve(ROOT, opt('--out', 'dist/site/index.html'));
+const RUN_BUNDLE = !flag('--no-bundle');
+
+/**
+ * Print a found/missing inventory of every collect-only artifact the dashboard reads,
+ * so the build log shows at a glance which reports were picked up and which are absent
+ * (with the command that generates each missing one). Source-derived sections (code,
+ * graph, routing, composition, entities) are always computed and aren't listed here.
+ */
+function printReportInventory({ coverage, lint, deps, security, storybook }) {
+  const rows = [];
+  const add = (section, name, found, detail) => rows.push({ section, name, found, detail });
+
+  // 1. Coverage — one row per suite (unit / e2e / storybook / global).
+  for (const s of coverage.suites) {
+    const hint = s.key === 'unit' ? 'npm run coverage:unit' : 'npm run coverage:all';
+    add(
+      'Coverage',
+      s.label,
+      s.available,
+      s.available ? `dist/reports/coverage/${s.key}/coverage-summary.json` : hint,
+    );
+  }
+
+  // 2. Lint & types.
+  add(
+    'Lint & types',
+    'ESLint',
+    !!lint.eslint?.available,
+    lint.eslint?.available
+      ? 'dist/reports/eslint.json'
+      : 'npm run lint -- -f json -o dist/reports/eslint.json',
+  );
+  add(
+    'Lint & types',
+    'TypeScript',
+    !!lint.tsc?.available,
+    lint.tsc?.available ? 'dist/reports/tsc.log' : 'npm run typecheck > dist/reports/tsc.log 2>&1',
+  );
+
+  // 3. Dependencies (audit + outdated).
+  add(
+    'Dependencies',
+    'npm audit',
+    !!deps.audit?.available,
+    deps.audit?.available
+      ? 'dist/reports/npm-audit.json'
+      : 'npm audit --json > dist/reports/npm-audit.json',
+  );
+  add(
+    'Dependencies',
+    'npm outdated',
+    !!deps.outdatedAvailable,
+    deps.outdatedAvailable
+      ? 'dist/reports/npm-outdated.json'
+      : 'npm outdated --json > dist/reports/npm-outdated.json',
+  );
+
+  // 4. Security scanners — local SARIF/JSON if present, otherwise a CI link only.
+  for (const tool of [security.snyk, security.codeql, security.checkmarx]) {
+    const n = tool.reports?.length || 0;
+    add(
+      'Security',
+      tool.name,
+      n > 0,
+      n > 0
+        ? `${n} local report${n > 1 ? 's' : ''}`
+        : 'no local SARIF (CI link only; Snyk: npm run security:scan)',
+    );
+  }
+
+  // 5. Storybook static build (built next to the dashboard).
+  add(
+    'Storybook',
+    'Static build',
+    !!storybook.built,
+    storybook.built
+      ? rel(path.join(path.dirname(OUT), 'storybook', 'index.html'))
+      : 'npm run quality:dashboard (or npm run build-storybook)',
+  );
+
+  const found = rows.filter((r) => r.found).length;
+  console.log(`\n📋  Report inventory — ${found}/${rows.length} artifacts found (collect-only):\n`);
+  const pad = Math.max(...rows.map((r) => r.name.length));
+  let section = '';
+  for (const r of rows) {
+    if (r.section !== section) {
+      section = r.section;
+      console.log(`   ${section}`);
+    }
+    const tail = r.found ? r.detail : `missing — ${r.detail}`;
+    console.log(`     ${r.found ? '✓' : '✗'}  ${r.name.padEnd(pad)}  ${tail}`);
+  }
+  console.log('');
+}
+
+function gitInfo() {
+  const remote = exec('git config --get remote.origin.url').stdout.trim();
+  const branch = exec('git rev-parse --abbrev-ref HEAD').stdout.trim() || 'unknown';
+  let repo = null;
+  const m = remote.match(/[:/]([^/]+)\/([^/]+?)(?:\.git)?$/);
+  if (m) {
+    repo = { owner: m[1], name: m[2] };
+  }
+  return { repo, branch };
+}
+
+async function main() {
+  console.log('\n📊  Building quality dashboard…\n');
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
+  } catch {}
+  const { repo, branch } = gitInfo();
+
+  log('Scanning source tree…');
+  const code = collectCode();
+  const graph = collectGraph();
+  const coverage = collectCoverage(path.dirname(OUT));
+  const lint = collectLint();
+  const deps = collectDeps(graph.importedExternals);
+  const security = collectSecurity(repo);
+  const routing = collectRouting();
+  const composition = collectComposition();
+  const entities = collectEntities();
+  const storybook = collectStorybook(path.dirname(OUT));
+
+  printReportInventory({ coverage, lint, deps, security, storybook });
+
+  // Codebase bundle — generated next to the dashboard so the relative link works.
+  let bundle = { available: false, note: 'Skipped (--no-bundle).' };
+  if (RUN_BUNDLE) {
+    log('Bundling codebase…');
+    try {
+      const b = await bundleCodebase(path.join(path.dirname(OUT), 'codebase-bundle.html'));
+      bundle = {
+        available: true,
+        file: path.basename(b.outFile),
+        fileCount: b.fileCount,
+        totalBytes: b.totalBytes,
+        htmlBytes: b.htmlBytes,
+      };
+    } catch (err) {
+      bundle = { available: false, note: `Bundle failed: ${err.message}` };
+    }
+  }
+
+  const meta = {
+    name: pkg.name || 'project',
+    version: pkg.version || '0.0.0',
+    generated: new Date().toISOString().replace('T', ' ').slice(0, 19) + ' UTC',
+    repo,
+    branch,
+  };
+
+  const html = render({
+    meta,
+    code,
+    coverage,
+    lint,
+    deps,
+    graph,
+    security,
+    routing,
+    composition,
+    entities,
+    storybook,
+    bundle,
+  });
+  mkdirSync(path.dirname(OUT), { recursive: true });
+  writeFileSync(OUT, html, 'utf8');
+
+  // Also dump the raw collected data for programmatic use / debugging.
+  const jsonOut = OUT.replace(/\.html?$/i, '') + '.json';
+  writeFileSync(
+    jsonOut,
+    JSON.stringify(
+      {
+        meta,
+        code,
+        coverage,
+        lint,
+        deps,
+        graph: { ...graph, graph: undefined, importedExternals: [...graph.importedExternals] },
+        security,
+        routing,
+        composition,
+        entities,
+        storybook,
+        bundle,
+      },
+      null,
+      2,
+    ),
+    'utf8',
+  );
+
+  console.log(`\n✅  Dashboard:  ${rel(OUT)}`);
+  console.log(`   Raw data:   ${rel(jsonOut)}\n`);
+
+  if (flag('--open')) {
+    // Arg-array spawn (no shell string) so quotes/&/spaces in the path survive.
+    const [cmd, args] =
+      process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', OUT]]
+        : process.platform === 'darwin'
+          ? ['open', [OUT]]
+          : ['xdg-open', [OUT]];
+    spawnSync(cmd, args, { stdio: 'ignore', windowsHide: true });
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/security-scan.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+/**
+ * Local security scanners → SARIF, ready for the Quality Dashboard.
+ *
+ *   • Snyk      — Open Source (SCA) + Snyk Code (SAST). Requires a free Snyk account
+ *                 (run `snyk auth`, or set SNYK_TOKEN). Skipped with guidance if absent.
+ *   • CodeQL    — GitHub's semantic SAST. Free, no account. Auto-downloads the official
+ *                 CodeQL CLI bundle into ./.codeql-bundle/ on first run, then builds a DB
+ *                 from ./src and analyses it with the security-and-quality suite.
+ *
+ * Outputs (under dist/reports/, git-ignored, all parsed by dev/scripts/quality-dashboard.mjs):
+ *   dist/reports/snyk-deps.sarif · dist/reports/snyk-code.sarif · dist/reports/codeql.sarif
+ *
+ * Usage:
+ *   node dev/scripts/security-scan.mjs [--snyk-only|--codeql-only] [--no-download]
+ *   npm run security:scan
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const ROOT = process.cwd();
+
+// All SARIF reports are collected here (alongside jest/playwright under dist/reports).
+const REPORTS_DIR = path.join(ROOT, 'dist', 'reports');
+mkdirSync(REPORTS_DIR, { recursive: true });
+const SARIF = {
+  snykDeps: path.join(REPORTS_DIR, 'snyk-deps.sarif'),
+  snykCode: path.join(REPORTS_DIR, 'snyk-code.sarif'),
+  codeql: path.join(REPORTS_DIR, 'codeql.sarif'),
+};
+
+const argv = process.argv.slice(2);
+const has = (f) => argv.includes(f);
+const SNYK_ONLY = has('--snyk-only');
+const CODEQL_ONLY = has('--codeql-only');
+const ANY_ONLY = SNYK_ONLY || CODEQL_ONLY;
+const NO_DOWNLOAD = has('--no-download');
+
+const results = [];
+
+/* ── helpers ── */
+function exec(cmd, { timeout = 1_800_000, stdio = 'pipe', cwd = ROOT } = {}) {
+  const r = spawnSync(cmd, {
+    cwd,
+    shell: true,
+    encoding: 'utf8',
+    timeout,
+    maxBuffer: 128 * 1024 * 1024,
+    windowsHide: true,
+    stdio: stdio === 'inherit' ? 'inherit' : 'pipe',
+  });
+  return {
+    code: r.status ?? (r.error ? 1 : 0),
+    stdout: r.stdout || '',
+    stderr: r.stderr || '',
+    error: r.error,
+  };
+}
+function which(cmd) {
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  return exec(probe).code === 0;
+}
+const hr = (t) => console.log(`\n${'─'.repeat(58)}\n  ${t}\n${'─'.repeat(58)}`);
+const sarifCount = (file) => {
+  try {
+    const doc = JSON.parse(readFileSync(file, 'utf8'));
+    return (doc.runs || []).reduce((n, run) => n + (run.results?.length || 0), 0);
+  } catch {
+    return null;
+  }
+};
+
+/* ─────────────────────────── Snyk ─────────────────────────── */
+function snykAuthed() {
+  if (process.env.SNYK_TOKEN) {
+    return true;
+  }
+  const cfgs = [
+    path.join(process.env.APPDATA || '', 'configstore', 'snyk.json'),
+    path.join(os.homedir(), '.config', 'configstore', 'snyk.json'),
+  ];
+  return cfgs.some((p) => p && existsSync(p));
+}
+
+function runSnyk() {
+  hr('Snyk — Open Source (SCA) + Snyk Code (SAST)');
+  if (!snykAuthed()) {
+    console.log('⚠  No Snyk credentials found (no SNYK_TOKEN, no stored auth).');
+    console.log('   Authenticate once, then re-run:');
+    console.log('     npm i -g snyk   &&   snyk auth        (free account)');
+    console.log('     — or set $env:SNYK_TOKEN=<token>');
+    console.log('   Skipping Snyk.');
+    results.push({ tool: 'Snyk', status: 'skipped (not authenticated)' });
+    return;
+  }
+  const snyk = which('snyk') ? 'snyk' : 'npx --yes snyk';
+  console.log(`Using: ${snyk}`);
+
+  console.log('→ snyk test (dependencies)…');
+  const dep = exec(
+    `${snyk} test --all-projects --severity-threshold=low --sarif-file-output="${SARIF.snykDeps}"`,
+  );
+  // Snyk exits non-zero when issues are found — that's success for us, the SARIF is what matters.
+  const depN = sarifCount(SARIF.snykDeps);
+  console.log(
+    depN == null
+      ? `  (no SARIF — ${(dep.stderr || dep.stdout).trim().split('\n')[0]})`
+      : `  ${depN} dependency findings`,
+  );
+
+  console.log('→ snyk code test (SAST)…');
+  const code = exec(
+    `${snyk} code test --severity-threshold=low --sarif-file-output="${SARIF.snykCode}"`,
+  );
+  const codeN = sarifCount(SARIF.snykCode);
+  console.log(
+    codeN == null
+      ? `  (no SARIF — ${(code.stderr || code.stdout).trim().split('\n')[0]})`
+      : `  ${codeN} code findings`,
+  );
+
+  results.push({
+    tool: 'Snyk',
+    status:
+      depN == null && codeN == null
+        ? 'no SARIF produced'
+        : `deps=${depN ?? '—'}, code=${codeN ?? '—'}`,
+  });
+}
+
+/* ────────────────────────── CodeQL ────────────────────────── */
+function codeqlPlatformAsset() {
+  if (process.platform === 'win32') {
+    return 'codeql-bundle-win64.tar.gz';
+  }
+  if (process.platform === 'darwin') {
+    return 'codeql-bundle-osx64.tar.gz';
+  }
+  return 'codeql-bundle-linux64.tar.gz';
+}
+
+function ensureCodeql() {
+  // 1) Explicit override, 2) on PATH, 3) local cached bundle, 4) download bundle.
+  if (process.env.CODEQL_DIST) {
+    const p = path.join(
+      process.env.CODEQL_DIST,
+      process.platform === 'win32' ? 'codeql.exe' : 'codeql',
+    );
+    if (existsSync(p)) {
+      return `"${p}"`;
+    }
+  }
+  if (which('codeql')) {
+    return 'codeql';
+  }
+
+  const cacheDir = path.join(ROOT, 'dist', '.codeql-bundle');
+  const bin = path.join(cacheDir, 'codeql', process.platform === 'win32' ? 'codeql.exe' : 'codeql');
+  if (existsSync(bin)) {
+    return `"${bin}"`;
+  }
+
+  if (NO_DOWNLOAD) {
+    console.log('⚠  CodeQL CLI not found and --no-download was passed. Skipping CodeQL.');
+    return null;
+  }
+
+  const asset = codeqlPlatformAsset();
+  const url = `https://github.com/github/codeql-action/releases/latest/download/${asset}`;
+  const tarball = path.join(cacheDir, asset);
+  mkdirSync(cacheDir, { recursive: true });
+
+  console.log(`→ Downloading CodeQL CLI bundle (~700 MB, one-time)…\n  ${url}`);
+  const dl = exec(`curl -L --fail --retry 3 -o "${tarball}" "${url}"`, { timeout: 1_800_000 });
+  if (dl.code !== 0 || !existsSync(tarball)) {
+    console.log(`✗ Download failed: ${(dl.stderr || dl.stdout).trim().split('\n').slice(-1)[0]}`);
+    return null;
+  }
+  console.log('→ Extracting…');
+  const ex = exec(`tar -xzf "${tarball}" -C "${cacheDir}"`, { timeout: 600_000 });
+  try {
+    rmSync(tarball);
+  } catch {}
+  if (ex.code !== 0 || !existsSync(bin)) {
+    console.log(`✗ Extraction failed: ${(ex.stderr || ex.stdout).trim()}`);
+    return null;
+  }
+  console.log('✓ CodeQL ready.');
+  return `"${bin}"`;
+}
+
+function runCodeQL() {
+  hr('CodeQL — semantic SAST (javascript-typescript)');
+  const codeql = ensureCodeql();
+  if (!codeql) {
+    results.push({ tool: 'CodeQL', status: 'skipped (CLI unavailable)' });
+    return;
+  }
+  const ver = exec(`${codeql} version --format=terse`).stdout.trim();
+  if (ver) {
+    console.log(`CodeQL ${ver}`);
+  }
+
+  const dbDir = path.join(ROOT, '.codeql-db');
+  try {
+    rmSync(dbDir, { recursive: true, force: true });
+  } catch {}
+
+  console.log('→ Building database from ./src …');
+  const create = exec(
+    `${codeql} database create "${dbDir}" --language=javascript-typescript --source-root="${path.join(ROOT, 'src')}" --overwrite`,
+    { timeout: 1_200_000 },
+  );
+  if (create.code !== 0 || !existsSync(dbDir)) {
+    console.log(
+      `✗ database create failed:\n${(create.stderr || create.stdout).trim().split('\n').slice(-8).join('\n')}`,
+    );
+    results.push({ tool: 'CodeQL', status: 'database create failed' });
+    return;
+  }
+
+  console.log('→ Analysing (security-and-quality)…');
+  const out = SARIF.codeql;
+  const analyzeWith = (suite) =>
+    exec(
+      `${codeql} database analyze "${dbDir}" ${suite} --format=sarif-latest --output="${out}" --sarif-category=codeql`,
+      { timeout: 1_200_000 },
+    );
+  let an = analyzeWith('javascript-security-and-quality.qls');
+  if (an.code !== 0 || !existsSync(out)) {
+    console.log('  (retrying with default query pack…)');
+    an = analyzeWith('codeql/javascript-queries');
+  }
+  const n = sarifCount(SARIF.codeql);
+  if (n == null) {
+    console.log(
+      `✗ analyze failed:\n${(an.stderr || an.stdout).trim().split('\n').slice(-8).join('\n')}`,
+    );
+    results.push({ tool: 'CodeQL', status: 'analyze failed' });
+  } else {
+    console.log(`✓ dist/reports/codeql.sarif — ${n} findings`);
+    results.push({ tool: 'CodeQL', status: `${n} findings` });
+  }
+  // Keep the DB out of the way but cheap to rebuild; remove to save disk.
+  try {
+    rmSync(dbDir, { recursive: true, force: true });
+  } catch {}
+}
+
+/* ─────────────────────────── main ─────────────────────────── */
+console.log('\n==  Local security scan  ==\n');
+if (!ANY_ONLY || SNYK_ONLY) {
+  runSnyk();
+}
+if (!ANY_ONLY || CODEQL_ONLY) {
+  runCodeQL();
+}
+
+hr('Summary');
+for (const r of results) {
+  console.log(`  ${r.tool.padEnd(8)} ${r.status}`);
+}
+console.log('\nNext:  npm run quality:dashboard   (re-renders the dashboard with these reports)\n');

package/src/test-outline.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * Print a high-level markdown outline of the Playwright suites without running them.
+ *
+ * Levels map onto the spec structure:
+ *   1. feature / widget  — the spec file (or the top-level describe for storybook)
+ *   2. functionality     — test.describe block
+ *   3. scenario / case   — test title
+ *
+ * Usage:
+ *   node dev/scripts/test-outline.mjs              # both e2e and storybook
+ *   node dev/scripts/test-outline.mjs e2e          # just the site e2e suite
+ *   node dev/scripts/test-outline.mjs storybook    # just the storybook suite
+ */
+import { execFileSync } from 'node:child_process';
+
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const rootDir = process.cwd();
+
+const SUITES = {
+  e2e: { title: 'E2E (site)', config: '.config/playwright.config.ts' },
+  storybook: { title: 'Storybook (widgets)', config: '.config/playwright.storybook.config.ts' },
+};
+
+function listTests(config) {
+  const out = execFileSync(
+    process.platform === 'win32' ? 'npx.cmd' : 'npx',
+    ['playwright', 'test', `--config=${config}`, '--list', '--reporter=json'],
+    {
+      cwd: rootDir,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+      shell: process.platform === 'win32',
+    },
+  );
+  // The json reporter is the only stdout writer under --list, but guard against
+  // stray npm/node noise before the JSON payload.
+  return JSON.parse(out.slice(out.indexOf('{')));
+}
+
+const prettify = (s) =>
+  s
+    .replace(/\.((e2e|storybook)\.)?spec\.ts$/, '')
+    .replace(/[-_]/g, ' ')
+    .replace(/^\w/, (c) => c.toUpperCase());
+
+/** Feature title from the co-located spec path: its basename, with an api/ prefix kept for API-route specs. */
+function featureTitle(file) {
+  const p = file.replace(/\\/g, '/');
+  const base = p.split('/').pop();
+  return prettify(p.includes('/api/') ? `api/${base}` : base);
+}
+
+/** Collect spec titles, deduplicating parameterized tests that expand per item. */
+function specTitles(suite) {
+  const titles = [];
+  for (const spec of suite.specs ?? []) {
+    if (!titles.includes(spec.title)) {
+      titles.push(spec.title);
+    }
+  }
+  return titles;
+}
+
+function printSuite(fileSuite) {
+  // Level 1: the spec file (api specs keep their api/ prefix for context)
+  console.log(`- **${featureTitle(fileSuite.title)}**`);
+  // Tests declared at file top level (outside any describe) land directly at level 2.
+  for (const title of specTitles(fileSuite)) {
+    console.log(`  - ${title}`);
+  }
+  for (const describe of fileSuite.suites ?? []) {
+    console.log(`  - ${describe.title}`);
+    for (const title of specTitles(describe)) {
+      console.log(`    - ${title}`);
+    }
+    // Flatten deeper describes into level 3 so the outline never exceeds three levels.
+    for (const nested of describe.suites ?? []) {
+      for (const title of specTitles(nested)) {
+        console.log(`    - ${nested.title} — ${title}`);
+      }
+    }
+  }
+}
+
+const wanted = process.argv[2] ? [process.argv[2]] : Object.keys(SUITES);
+for (const key of wanted) {
+  const suite = SUITES[key];
+  if (!suite) {
+    console.error(`Unknown suite "${key}". Use: ${Object.keys(SUITES).join(', ')}`);
+    process.exit(1);
+  }
+  const report = listTests(suite.config);
+  console.log(`\n# ${suite.title}\n`);
+  for (const fileSuite of report.suites ?? []) {
+    printSuite(fileSuite);
+  }
+}