@sun-asterisk/sungen 3.2.32 → 3.2.34-beta.1

package/src/cli/commands/audit.ts

@@ -4,14 +4,26 @@ import * as fs from 'fs';
 import { runAudit, AuditReport, catalogIdFromScreenDir } from '../../harness/audit';
 import { reportSlug } from '../../harness/unit-paths';
 import { acceptViewpointBaseline } from '../../harness/viewpoint-baseline';
+import { removeDraftLineFromFile, viewpointFileIsAiDraft } from '../../harness/viewpoint-draft-header';
 import { findUnitDir } from '../resolve-unit';
 
 
-function bar(ratio: number, width = 20): string {
-  const n = Math.round(ratio * width);
+export function bar(ratio: number, width = 20): string {
+  // A display helper must not be able to take the CLI down whatever the model hands it: an
+  // out-of-range ratio made `String.repeat` throw `Invalid count value: -5`, which killed the
+  // run mid-scorecard so the gate, the findings and the next-step hint never printed (#762).
+  const n = Math.max(0, Math.min(width, Math.round((Number.isFinite(ratio) ? ratio : 0) * width)));
   return '█'.repeat(n) + '░'.repeat(width - n);
 }
 
+/** The ⑥ headline. No viewpoint ID read → nothing was matched, so `0%` would read as a measured
+ *  failure; say `n/a` and why instead (#832). Same with no scenario yet (#852). */
+export function traceabilityHeadline(trace: AuditReport['trace']): string {
+  if (trace.overviewIds === 0) return '  ⑥ Traceability — n/a (no viewpoint ID found in test-viewpoint.md)';
+  if (trace.total === 0) return '  ⑥ Traceability — n/a (no scenarios yet)';
+  return `  ⑥ Traceability — ${(trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`;
+}
+
 function render(r: AuditReport): void {
   const L = console.log;
   L('');
@@ -47,6 +59,11 @@ function render(r: AuditReport): void {
   L(`  ① Viewpoint Gate — page-type: ${r.gate.pageType ?? 'unknown'} — themes ${r.gate.themesCovered}/${r.gate.themesTotal} covered`);
   if (r.gate.gaps.length) for (const g of r.gate.gaps) L(`      ✗ ${g.status === 'shallow' ? 'SHALLOW' : 'MISSING'}: ${g.theme}`);
   else L('      ✓ all critical themes covered (with data assertions)');
+  // Name the scenario behind each covered theme (#776). A bare count gives a reviewer nothing to
+  // check, so a keyword matching something absurd stays invisible; the evidence line makes it
+  // obvious. Second line of defence — it holds even if the matcher is wrong again.
+  for (const c of r.gate.coveredBy ?? [])
+    L(`      ✓ ${c.theme} ← [${c.keyword}] ${c.by.length > 88 ? `${c.by.slice(0, 88)}…` : c.by}`);
   L('');
   if (r.flowQuality?.hasContract) {
     const fq = r.flowQuality;
@@ -74,7 +91,7 @@ function render(r: AuditReport): void {
   if (r.depth.shallowBusinessCritical.length > 8) L(`      … +${r.depth.shallowBusinessCritical.length - 8} more`);
   L('');
   L(`  ③ Claim-Proof — ${r.claim.proven}/${r.claim.withClaims} titled claims proven by steps  [${r.claim.verdict.toUpperCase()}]`);
-  if (r.claim.unproven.length === 0) L('      ✓ every claim (all/only/single/correct/changes/hidden) is backed by an assertion');
+  if (r.claim.unproven.length === 0) L('      ✓ every claim (all/only/single/correct/changes/hidden/order/limit) is backed by an assertion');
   for (const u of r.claim.unproven.slice(0, 8)) L(`      ${u.severity === 'fail' ? '✗' : '⚠'} [${u.claim}] ${u.name} → needs ${u.need}`);
   if (r.claim.unproven.length > 8) L(`      … +${r.claim.unproven.length - 8} more`);
   L('');
@@ -102,7 +119,7 @@ function render(r: AuditReport): void {
     }
   }
   L('');
-  L(`  ⑥ Traceability — ${(r.trace.mappedRatio * 100).toFixed(0)}% scenarios linked to viewpoint-overview`);
+  L(traceabilityHeadline(r.trace));
   L(`      ${r.trace.note}`);
   L('');
   if (r.spec.hasSpec && (r.spec.frTotal > 0 || r.spec.triggerGaps.length > 0 || r.spec.verdict !== 'pass')) {
@@ -127,7 +144,7 @@ function render(r: AuditReport): void {
       const held = new Set(r.score.axes.filter((x) => x.withheld).map((x) => x.key));
       const absent = na.filter((k) => !held.has(k));
       if (absent.length) L(`      not scored (no evidence in this unit): ${absent.join(', ')}`);
-      if (held.size) L(`      measured but held (viewpoint baseline changed — review, then --accept-viewpoint): ${[...held].join(', ')}`);
+      if (held.size) L(`      measured but held (viewpoint not accepted yet — changed, adopted after the suite, or an AI draft; review, then --accept-viewpoint): ${[...held].join(', ')}`);
     }
     L(`      weakest: ${r.calibration.weakest.axis} ${(r.calibration.weakest.value * 100).toFixed(0)}%${r.calibration.inflated ? '  ⚠ SCORE-INFLATED-BY-BREADTH' : ''}`);
     if (r.calibration.cappedAt !== undefined) {
@@ -157,14 +174,18 @@ export function registerAuditCommand(program: Command): void {
     .option('--area <name>', 'Alias of --api — an API-first area (qa/api/<name>)')
     .option('--json', 'Output the raw JSON report')
     .option('--accept-viewpoint', 'Accept the current test-viewpoint.md as the baseline the suite is measured against')
+    .option('--no-baseline', 'Measure without writing .sungen/viewpoint-baseline.json (audit a drafted viewpoint before generating)')
     .action((options) => {
       try {
         const name = options.screen || options.api || options.area;
         if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        // Commander's `--no-*`: `baseline` is true unless the flag is passed.
+        const recordBaseline = options.baseline !== false;
+        if (!recordBaseline && options.acceptViewpoint) throw new Error('--no-baseline and --accept-viewpoint cannot be combined');
         const dir = findUnitDir(name);
         if (!dir) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
 
-        const report = runAudit(dir, name);
+        let report = runAudit(dir, name);
 
         // The baseline is only ever written HERE, never by the measurement itself:
         // a first sighting has nothing to compare against, and any later change is
@@ -179,18 +200,43 @@ export function registerAuditCommand(program: Command): void {
         const unitId = catalogIdFromScreenDir(dir);
         const vb = report.viewpointBaseline;
         const postHoc = vb.status === 'new' && report.scenarioCount > 0;
+        // `drafted-by: ai` — a viewpoint the AI wrote is never accepted by the audit that measures it,
+        // with scenarios or without: only `--accept-viewpoint` does, and that removes the line.
+        const vpPath = path.join(dir, 'requirements', 'test-viewpoint.md');
+        const hasDraftMarker = viewpointFileIsAiDraft(vpPath);
+        // A draft with no VP id has nothing to accept — only VIEWPOINT-MISSING speaks for it. Fail
+        // here, before any write, so the file stays as it is and the QA is told why.
+        if (options.acceptViewpoint && vb.status === 'absent' && hasDraftMarker) {
+          throw new Error('the draft declares no VP ids — nothing to accept. Add the viewpoint ids (VP-… in the Priority Viewpoints table or checks), then run --accept-viewpoint again.');
+        }
+        const aiDraft = vb.status !== 'absent' && hasDraftMarker;
         // A re-parsed baseline is a CACHE migration, not an acceptance: the comparison already
         // resolved to `unchanged`, and rewriting the record only lets the NEXT real edit be
         // detected. Left unwritten it would re-migrate — and re-announce — on every run.
-        if (vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
-        if ((vb.status === 'new' && !postHoc) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc))) {
+        //
+        // `--no-baseline` skips every write here, the migration included: a draft audited before its
+        // scenarios exist is `new` and not post-hoc, and a plain audit would record it as the yardstick.
+        if (recordBaseline && !aiDraft && vb.reparsed) acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
+        if (recordBaseline && ((vb.status === 'new' && !postHoc && !aiDraft) || (options.acceptViewpoint && (vb.status === 'changed' || postHoc || aiDraft)))) {
           acceptViewpointBaseline(process.cwd(), unitId, { hash: vb.hash, ids: vb.ids, fileHash: vb.fileHash });
-          if (options.acceptViewpoint && !options.json) {
-            console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
-            console.log('    Re-run the audit to score atomicLedger + traceability against it.\n');
+          if (options.acceptViewpoint) {
+            // The baseline is recorded first: if the line cannot be removed the draft stays flagged
+            // (held, finding, decide step) and the accept can simply be run again.
+            const lineRemoved = aiDraft && removeDraftLineFromFile(vpPath);
+            // Measure again against what was just accepted: the report printed and saved below (the
+            // one `sungen next` reads) must not be the pre-accept one, still holding the axes (#867).
+            report = runAudit(dir, name);
+            if (!options.json) {
+              console.log(`\n  ✓ test-viewpoint.md accepted as the baseline for ${name} (${vb.ids.length} viewpoint id(s)).`);
+              if (lineRemoved) console.log('    Removed the `drafted-by: ai` line from test-viewpoint.md — it is QA-reviewed from here on.');
+              console.log('    The report below is measured against it.\n');
+            }
           }
         } else if (options.acceptViewpoint && !options.json) {
-          console.log(`\n  ○ nothing to accept for ${name} — the viewpoint baseline is ${vb.status}.\n`);
+          // `absent` covers a file with no readable viewpoint id too — say which (#832).
+          console.log(vb.status === 'absent'
+            ? `\n  ○ nothing to accept for ${name} — no viewpoint ID found in requirements/test-viewpoint.md (missing file, or no section declares one).\n`
+            : `\n  ○ nothing to accept for ${name} — the viewpoint baseline is ${vb.status}.\n`);
         }
 
         // Persist report under .sungen/reports/ (flat slug: api flow `flows/x` → `flows-x-audit.json`).
@@ -204,6 +250,7 @@ export function registerAuditCommand(program: Command): void {
         } else {
           render(report);
           console.log(`  Report: ${path.relative(process.cwd(), outPath)}`);
+          if (!recordBaseline) console.log('  ○ baseline not recorded (--no-baseline)');
           console.log('');
         }
         // Non-zero exit when the gate fails — usable in CI / repair loop. Set exitCode (not

package/src/cli/commands/capability.ts

@@ -4,7 +4,8 @@ import { createRequire } from 'module';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
-  readCapabilities, writeCapabilities, loadDriverCatalog, driverMeta,
+  readCapabilities, writeCapabilities, loadDriverCatalog, driverMeta, capabilitiesPath,
+  type CapabilityProfile,
 } from '../../harness/capability';
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
@@ -12,26 +13,37 @@ import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobil
 import { emitAppiumEnvironment, runAppiumEnvironmentSetup } from '../../orchestrator/appium-environment-setup';
 import { coreVersion, resolveDriverVersion } from '../../orchestrator/lockstep-version';
 import { findUnitDir, resolveUnit } from '../resolve-unit';
+import { readTextFile } from '../../harness/read-text';
 
 /**
- * Add `test:mobile` to the project's package.json scripts (if absent).
- * Idempotent — skips if the script is already set.
- * Returns true if the script was added, false if already present or no package.json.
+ * Add `test:mobile` to the project's package.json scripts (if absent). Idempotent.
+ *
+ * Four outcomes, not two. The old boolean collapsed "already present", "no package.json" and
+ * "could not parse it" into a single `false`, and the caller rendered that as
+ * `– skipped  package.json scripts[test:mobile] (already exists)` — which, on a malformed
+ * package.json, states the exact opposite of the truth: the script is absent, the command promised
+ * it, and the next thing the user sees is `npm error Missing script: "test:mobile"`.
  */
-function addMobileScript(cwd: string): boolean {
+type MobileScriptOutcome =
+  | { state: 'added' }
+  | { state: 'already-present' }
+  | { state: 'no-package-json' }
+  | { state: 'unreadable'; error: string };
+
+function addMobileScript(cwd: string): MobileScriptOutcome {
   const pkgPath = path.join(cwd, 'package.json');
-  if (!fs.existsSync(pkgPath)) return false;
+  if (!fs.existsSync(pkgPath)) return { state: 'no-package-json' };
   let pkg: Record<string, any>;
   try {
-    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
-  } catch {
-    return false;
+    pkg = JSON.parse(readTextFile(pkgPath));   // BOM-tolerant: npm reads such a file fine, so must we
+  } catch (e) {
+    return { state: 'unreadable', error: (e as Error).message.split('\n')[0] };
   }
   if (!pkg.scripts || typeof pkg.scripts !== 'object') pkg.scripts = {};
-  if (pkg.scripts['test:mobile']) return false;
+  if (pkg.scripts['test:mobile']) return { state: 'already-present' };
   pkg.scripts['test:mobile'] = 'wdio run wdio.conf.ts';
   fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
-  return true;
+  return { state: 'added' };
 }
 
 /**
@@ -221,9 +233,13 @@ export function registerCapabilityCommand(program: Command): void {
         }
 
         const profile = readCapabilities(cwd);
+        assertProfileWritable(profile, cwd);
         const enabled = Array.from(new Set([...profile.enabled, driver]));
         const platform = meta.kind === 'platform' ? driver : profile.platform;
-        writeCapabilities(cwd, { platform, enabled });
+        // Carry `verification` through. It is the recorded TEST TYPE, not a derived value: dropping
+        // it here silently re-derives the scope from `enabled`, handing an E2E-only project the
+        // @api/@query verification it had explicitly narrowed away.
+        writeCapabilities(cwd, { platform, enabled, verification: profile.verification });
         console.log(`✓ capability "${driver}" enabled${meta.kind === 'platform' ? ` (platform=${driver})` : ''}.`);
 
         // Emit the mobile runtime harness when the mobile platform driver is added.
@@ -236,11 +252,11 @@ export function registerCapabilityCommand(program: Command): void {
           for (const f of result.skipped) console.log(`  – skipped  ${f} (already exists)`);
 
           // Add test:mobile script to package.json (idempotent)
-          if (addMobileScript(cwd)) {
-            console.log('  ✓ created  package.json scripts[test:mobile]');
-          } else {
-            console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
-          }
+          const script = addMobileScript(cwd);
+          if (script.state === 'added') console.log('  ✓ created  package.json scripts[test:mobile]');
+          else if (script.state === 'already-present') console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
+          else if (script.state === 'no-package-json') console.log('  ✗ NOT added  package.json scripts[test:mobile] — no package.json here; run `npm init -y` first, then add: "test:mobile": "wdio run wdio.conf.ts"');
+          else console.log(`  ✗ NOT added  package.json scripts[test:mobile] — package.json is not valid JSON (${script.error}); fix it, then add: "test:mobile": "wdio run wdio.conf.ts"`);
 
           // appium-environment/ provisioning bundle (idempotent per file) — emitted before the driver
           // install, run after it so its Appium step finds the project-local CLI.
@@ -249,7 +265,9 @@ export function registerCapabilityCommand(program: Command): void {
           else console.log('  – skipped  appium-environment/ (already exists)');
 
           // Best-effort driver install — non-fatal so capability add still succeeds offline.
-          installMobileDriver(cwd);
+          // --skip-install promises no npm install; the driver + wdio/appium runtime is ~290 MB.
+          if (o.skipInstall) console.log('  – skipped  mobile driver install (--skip-install) — later: sungen capability add mobile');
+          else installMobileDriver(cwd);
 
           // --skip-install means "record only" — then provisioning the machine is not wanted either.
           runAppiumEnvironmentSetup(cwd, { skip: !!(o.skipEnvSetup || o.skipInstall) });
@@ -262,6 +280,22 @@ export function registerCapabilityCommand(program: Command): void {
       }
     });
 
+/**
+ * Every path that WRITES qa/capabilities.yaml first reads it, edits one field, and writes the whole
+ * file back. That round-trip is only safe when the read succeeded: an unreadable profile reads as
+ * "no platform, no drivers", so the write-back would replace the user's declaration with just the
+ * one driver being added — and `remove` would replace it with nothing at all. Refuse instead.
+ */
+function assertProfileWritable(profile: CapabilityProfile, cwd: string): void {
+  if (profile.source !== 'unreadable') return;
+  console.error(
+    `✗ ${path.relative(cwd, capabilitiesPath(cwd))} exists but could not be parsed.\n` +
+    `  Refusing to rewrite it: this command replaces the whole file, so it would discard the\n` +
+    `  platform, drivers and verification scope you declared. Fix the YAML and re-run.`,
+  );
+  process.exit(1);
+}
+
   // ── remove ─────────────────────────────────────────────────────────────
   cap
     .command('remove <driver>')
@@ -271,9 +305,10 @@ export function registerCapabilityCommand(program: Command): void {
       try {
         const cwd = process.cwd();
         const profile = readCapabilities(cwd);
+        assertProfileWritable(profile, cwd);
         const enabled = profile.enabled.filter((d) => d !== driver);
         const platform = profile.platform === driver ? undefined : profile.platform;
-        writeCapabilities(cwd, { platform, enabled });
+        writeCapabilities(cwd, { platform, enabled, verification: profile.verification });
         const meta = driverMeta(driver);
         if (o.uninstall && meta && !adapterRegistry.hasAdapter(meta.adapter || meta.id)) {
           spawnSync('npm', ['uninstall', meta.package], { stdio: 'inherit', shell: true });

package/src/cli/commands/changed.ts

@@ -12,6 +12,7 @@
 import { Command } from 'commander';
 import { buildRunManifest, readRunManifest, writeRunManifest, selectChanged } from '../../harness/run-manifest';
 import { findUnitDir } from '../resolve-unit';
+import { titlesToGrep } from '../../harness/select-by-ids';
 import { execFileSync } from 'child_process';
 import * as path from 'path';
 
@@ -40,9 +41,6 @@ function gitChangedFiles(unitDir: string): string[] {
   }
 }
 
-/** Escape a scenario title for a `-g` / `--mochaOpts.grep` regex. */
-const toGrep = (titles: string[]): string =>
-  titles.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
 
 export function registerChangedCommand(program: Command): void {
   program
@@ -75,7 +73,7 @@ export function registerChangedCommand(program: Command): void {
         if (options.grep) {
           // Empty output is meaningful: nothing to run. A caller must treat "" as "skip the run",
           // never as "match everything" — an empty grep would run the whole suite.
-          console.log(toGrep(selection.scenarios));
+          console.log(titlesToGrep(selection.scenarios));
           return;
         }
         if (options.json) { console.log(JSON.stringify(selection, null, 2)); return; }

package/src/cli/commands/dashboard.ts

@@ -11,8 +11,7 @@ import { Command } from 'commander';
 import * as path from 'path';
 import * as fs from 'fs';
 import { execSync } from 'child_process';
-import { EnvironmentInfo } from '../../exporters/types';
-import { resolveWebBaseUrl } from '../../exporters/env-qa';
+import { getEnvironment } from '../../exporters/run-environment';
 import {
   buildDashboardSnapshot,
   DashboardTarget,
@@ -37,30 +36,6 @@ const COLOR = {
 
 function log(msg: string): void { console.log(msg); }
 
-function getEnvironment(cwd: string): EnvironmentInfo {
-  let baseURL = '';
-  let projectName = 'chromium';
-  const configPath = path.join(cwd, 'playwright.config.ts');
-  if (fs.existsSync(configPath)) {
-    const c = fs.readFileSync(configPath, 'utf-8');
-    // Both config shapes: legacy literal and env-aware resolveBaseUrl('x') wrapper.
-    const baseMatch = c.match(/baseURL:\s*(?:resolveBaseUrl\(\s*)?['"]([^'"]+)['"]/);
-    if (baseMatch) baseURL = baseMatch[1];
-    const projMatch = c.match(/name:\s*['"]([^'"]+)['"]/);
-    if (projMatch) projectName = projMatch[1];
-  }
-  // Same SUNGEN_BASE_URL override as delivery — the two surfaces must agree.
-  baseURL = resolveWebBaseUrl(cwd, baseURL);
-
-  let executor = process.env.CI_USER || process.env.USER || '';
-  try {
-    const gitUser = execSync('git config user.name', { cwd, encoding: 'utf-8' }).trim();
-    if (gitUser) executor = gitUser;
-  } catch { /* ignore */ }
-
-  return { baseURL, projectName, executor };
-}
-
 interface DashboardOptions {
   noHistory?: boolean;
   open?: boolean;

package/src/cli/commands/defect.ts

@@ -0,0 +1,49 @@
+import { Command } from 'commander';
+import { resolveUnit } from '../resolve-unit';
+import { draftDefects } from '../../harness/defect-draft';
+import { readDefects } from '../../harness/defects';
+
+/**
+ * `sungen defect draft|list` — defect records under qa/defects/ (see harness/defects.ts).
+ * `draft` writes one record per product-candidate row of the unit's last `sungen triage`.
+ */
+export function registerDefectCommand(program: Command): void {
+  const defect = program.command('defect').description('Draft and list defect records (qa/defects/DEF-NNN-*.md) from red scenarios');
+
+  defect
+    .command('draft')
+    .description('Draft a defect record for each product-candidate row of the last `sungen triage`')
+    .option('-s, --screen <name>', 'Screen or flow name')
+    .option('--api <name>', 'API-first area or api flow (qa/api/<name>)')
+    .option('--scenario <title|id>', 'Only the scenario whose title contains this text, or that carries this VP id')
+    .option('--json', 'Output raw JSON')
+    .action((o: { screen?: string; api?: string; scenario?: string; json?: boolean }) => {
+      try {
+        const name = o.screen || o.api;
+        if (!name) throw new Error('Provide --screen <name> (or --api <area>)');
+        const unit = resolveUnit(name, process.cwd());
+        if (!unit) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+        const r = draftDefects(process.cwd(), unit, { scenario: o.scenario });
+        if (o.json) { console.log(JSON.stringify(r, null, 2)); return; }
+        if (r.missingTriage) { console.log(`\n  ${name}: no triage yet — run \`sungen triage --screen ${name}\` after the tests.\n`); return; }
+        for (const f of r.written) console.log(`  ✎ ${f}`);
+        for (const s of r.skipped) console.log(`  ○ already recorded as ${s.id}: ${s.scenario}`);
+        if (!r.written.length && !r.skipped.length) console.log(`  ✓ ${name}: no product-candidate rows to draft.`);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exitCode = 1;
+      }
+    });
+
+  defect
+    .command('list')
+    .description('List defect records (id, severity, status, units, scenario count)')
+    .option('--status <status>', 'Only records with this status (open, fixed, verified, closed, wont-fix)')
+    .option('--json', 'Output raw JSON')
+    .action((o: { status?: string; json?: boolean }) => {
+      const rows = readDefects(process.cwd()).filter((r) => !o.status || r.status === o.status);
+      if (o.json) { console.log(JSON.stringify(rows, null, 2)); return; }
+      if (!rows.length) { console.log('  (no defect records)'); return; }
+      for (const r of rows) console.log(`  ${r.id}  ${r.severity.padEnd(8)} ${r.status.padEnd(9)} ${r.units.join(',')}  ${r.scenarios.length} scenario(s)  ${r.title}`);
+    });
+}