@sun-asterisk/sungen 3.2.16-beta.1 → 3.2.16-beta.10

package/src/cli/commands/delivery.ts

@@ -31,6 +31,7 @@ import {
   loadMatrixModel,
   approveMatrix,
   writeMatrixDeliverables,
+  MatrixFormat,
   hasErrors,
   hasReview,
 } from '../../exporters/matrix/export';
@@ -621,6 +622,7 @@ function matrixPathsFor(cwd: string, target: DeliveryTarget): MatrixTargetPaths
     featureFile: path.join(base, 'features', `${target.featureBaseName}.feature`),
     testDataFile: resolveTestDataPathForTarget(cwd, target),
     specFile: path.join(genBase, `${target.featureBaseName}.spec.ts`),
+    specMdFile: path.join(base, 'requirements', 'spec.md'),
     resultsPath: resolveResultsPath(cwd, target),
     mapFile: mapFilePath(base, target.featureBaseName),
   };
@@ -650,7 +652,7 @@ interface MatrixRunSummary {
 async function exportMatrixTarget(
   cwd: string,
   target: DeliveryTarget,
-  opts: { check?: boolean; preview?: boolean },
+  opts: { check?: boolean; preview?: boolean; format?: MatrixFormat },
 ): Promise<MatrixRunSummary | null> {
   const paths = matrixPathsFor(cwd, target);
   const { model, mapMissing, mapErrors } = loadMatrixModel(paths);
@@ -688,24 +690,38 @@ async function exportMatrixTarget(
     return null;
   }
 
-  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model);
+  const { csvPath, xlsxPath } = await writeMatrixDeliverables(paths, model, opts.format ?? 'xlsx');
   const passed = model.items.reduce((a, i) => a + i.resultCounts.passed, 0);
   const failed = model.items.reduce((a, i) => a + i.resultCounts.failed, 0);
-  log(`  ${COLOR.green}→ ${path.relative(cwd, xlsxPath)}${COLOR.reset} ${COLOR.gray}(+ ${path.relative(cwd, csvPath)})${COLOR.reset}`);
+  const written = [xlsxPath, csvPath].filter((p): p is string => !!p).map((p) => path.relative(cwd, p));
+  for (const rel of written) log(`  ${COLOR.green}→ ${rel}${COLOR.reset}`);
   return {
     label: paths.label,
     items: model.manifest.itemCount,
     variants: model.manifest.variantCount,
     passed,
     failed,
-    file: path.relative(cwd, xlsxPath),
+    file: written.join(' + '),
   };
 }
 
+/**
+ * One place that accounts for every target the run did NOT write, so a sweep is
+ * never silently partial: scaffolds skipped by preflight and units whose gates /
+ * missing map stopped the export.
+ */
+function printSkipSummary(skipped: string[], notExported: string[]): void {
+  if (skipped.length === 0 && notExported.length === 0) return;
+  log(`${COLOR.gray}Not exported (${skipped.length + notExported.length}):${COLOR.reset}`);
+  for (const s of skipped) log(`  ${COLOR.gray}· ${s}${COLOR.reset}`);
+  for (const n of notExported) log(`  ${COLOR.gray}· ${n} (see the message above)${COLOR.reset}`);
+  log('');
+}
+
 function printMatrixSummaryTable(summaries: MatrixRunSummary[]): void {
   log(`\n${COLOR.bold}Delivery matrix export complete${COLOR.reset}\n`);
   const colWidth = Math.max(20, ...summaries.map((s) => s.label.length)) + 1;
-  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File`);
+  log(`  ${'Feature'.padEnd(colWidth)}Items  Variants  Passed  Failed  File(s)`);
   log('  ' + '-'.repeat(colWidth + 50));
   for (const s of summaries) {
     log(
@@ -795,9 +811,11 @@ export function registerDeliveryCommand(program: Command): void {
     .option('--check', 'Matrix gates only — validate the delivery map, write nothing')
     .option('--approve [ids]', 'Approve proposed groups (all, or a comma-separated id list) + stamp fingerprints')
     .option('--preview', 'Render the matrix despite review-required findings (DRAFT watermark)')
+    .option('--format <format>', 'Matrix output format: xlsx (default) | csv | both', 'xlsx')
     .action(async (names: string[], options: {
       skipPreflight?: boolean; continueOnMissing?: boolean; env?: string;
       legacy?: boolean; full?: boolean; check?: boolean; approve?: boolean | string; preview?: boolean;
+      format?: string;
     }) => {
       try {
         // Same effect as running with SUNGEN_ENV=<env> — result-file resolution,
@@ -805,11 +823,19 @@ export function registerDeliveryCommand(program: Command): void {
         if (options.env) process.env.SUNGEN_ENV = options.env;
         const cwd = process.cwd();
 
+        // Matrix output format — one artifact by default (xlsx); csv/both on request.
+        const format = (options.format ?? 'xlsx').toLowerCase();
+        if (!['xlsx', 'csv', 'both'].includes(format)) {
+          console.error(`${COLOR.red}Invalid --format "${options.format}"${COLOR.reset} — use xlsx | csv | both`);
+          process.exit(1);
+        }
+
         // 1. Scope detection — each positional name expands into one target
         //    per `.feature` file inside that screen/flow. Passing a specific
         //    feature basename (e.g. `home-modal`) narrows to that one file.
         let targets: DeliveryTarget[];
-        if (names && names.length > 0) {
+        const explicitScope = !!(names && names.length > 0);
+        if (explicitScope) {
           targets = names.flatMap((n) => resolveTargetsFromArg(cwd, n));
         } else {
           targets = listAllTargets(cwd);
@@ -822,8 +848,13 @@ export function registerDeliveryCommand(program: Command): void {
         const labels = targets.map((t) => t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName);
         log(`${COLOR.bold}sungen delivery${COLOR.reset} — exporting ${targets.length} feature(s): ${labels.join(', ')}\n`);
 
-        // 2. Pre-flight
+        // 2. Pre-flight — strictness follows the SCOPE. Naming a unit means "I want
+        //    this one" (fail loudly); a no-argument sweep means "export everything
+        //    that is ready", so scaffolded units (added but not yet authored) are
+        //    skipped with a note instead of aborting the whole run — otherwise one
+        //    untouched scaffold in a work-in-progress project produces zero files.
         let toExport: DeliveryTarget[];
+        const skipped: string[] = [];
         if (options.skipPreflight) {
           toExport = targets;
         } else {
@@ -832,22 +863,22 @@ export function registerDeliveryCommand(program: Command): void {
 
           const blockers = checks.filter(hasBlockingMissing);
           if (blockers.length > 0) {
-            if (options.continueOnMissing) {
-              const passedScreens = new Set(
-                checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
-              );
-              toExport = targets.filter((t) => {
-                const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
-                return passedScreens.has(label);
-              });
-              log(`${COLOR.yellow}Continuing with ${toExport.length} ready target(s).${COLOR.reset}\n`);
-            } else {
+            if (explicitScope && !options.continueOnMissing) {
               console.error(
-                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} target(s) have blocking issues.\n` +
+                `${COLOR.red}Aborted:${COLOR.reset} ${blockers.length} named target(s) have blocking issues.\n` +
                 `Run the suggested commands above, or use ${COLOR.cyan}--continue-on-missing${COLOR.reset} to skip them.`
               );
               process.exit(1);
             }
+            const readyLabels = new Set(
+              checks.filter((c) => !hasBlockingMissing(c)).map((c) => c.screen)
+            );
+            toExport = targets.filter((t) => {
+              const label = t.isFlow ? `flow/${t.featureBaseName}` : t.featureBaseName;
+              return readyLabels.has(label);
+            });
+            for (const b of blockers) skipped.push(`${b.screen} (not authored yet — run /sungen:create-test)`);
+            log(`${COLOR.yellow}Skipping ${blockers.length} target(s) that have no test cases yet; continuing with ${toExport.length}.${COLOR.reset}\n`);
           } else {
             toExport = targets;
           }
@@ -883,14 +914,25 @@ export function registerDeliveryCommand(program: Command): void {
           }
 
           const matrixSummaries: MatrixRunSummary[] = [];
-          let failedTargets = 0;
+          const notExported: string[] = [];
           for (const target of toExport) {
-            const s = await exportMatrixTarget(cwd, target, { check: options.check, preview: options.preview });
+            const s = await exportMatrixTarget(cwd, target, {
+              check: options.check, preview: options.preview, format: format as MatrixFormat,
+            });
             if (s) matrixSummaries.push(s);
-            else failedTargets++;
+            else notExported.push(target.isFlow ? `flow/${target.featureBaseName}` : target.featureBaseName);
           }
           if (matrixSummaries.length > 0 && !options.check) printMatrixSummaryTable(matrixSummaries);
-          if (failedTargets > 0) process.exit(1);
+          printSkipSummary(skipped, notExported);
+          // A named target that produced nothing is a failure. A sweep is a failure
+          // only when it produced nothing at all — units still waiting for a map or
+          // an approval are the normal state of a live project. Preflight skips are
+          // not counted here: reaching this point in an explicit scope means
+          // --continue-on-missing was passed, which IS the opt-in to tolerate them.
+          const failed = explicitScope
+            ? notExported.length > 0
+            : matrixSummaries.length === 0;
+          if (failed) process.exit(1);
           return;
         }
 
@@ -903,6 +945,10 @@ export function registerDeliveryCommand(program: Command): void {
 
         // 4. Summary
         printSummaryTable(summaries);
+        printSkipSummary(skipped, []);
+        // Same rule as the matrix path: every attempted target in an explicit scope
+        // must have produced a file; a sweep only fails when nothing was written.
+        if (explicitScope ? summaries.length < toExport.length : summaries.length === 0) process.exit(1);
       } catch (err) {
         console.error(`${COLOR.red}Fatal:${COLOR.reset} ${err instanceof Error ? err.message : err}`);
         process.exit(1);

package/src/exporters/feature-parser.ts

@@ -172,12 +172,28 @@ export function extractAuthRole(tags: string[]): string | null {
 }
 
 /**
- * Extract VP ID and human-readable name from scenario name like
+ * The leading viewpoint/requirement id of a scenario title.
+ *
+ * The `VP-` prefix is the scheme sungen suggests, NOT a requirement: real projects
+ * bring their own (`SEC-123`, `PER-345`, `MS-HP-001`, `VP0-001`), and the harness
+ * has always been format-tolerant about it. The exporters were not — a project
+ * using `SEC-123` got no id at all, which made every scenario "unaddressable" and
+ * blocked the whole delivery matrix at Gate A.
+ *
+ * Shape: uppercase segments joined by `-`, ending in a number (with an optional
+ * letter or sub-code suffix). Requiring the trailing number is what keeps an
+ * ordinary title word ("A11y check…") from being mistaken for an id.
+ */
+export const SCENARIO_ID = /^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)/;
+
+/**
+ * Extract the id and the human-readable name from a scenario title:
  * "VP-UI-001 Modal displays all required fields" →
  *   { vpId: "VP-UI-001", category1: "Modal displays all required fields" }
+ * "SEC-123 Login is protected" → { vpId: "SEC-123", category1: "Login is protected" }
  */
 export function splitVpAndName(scenarioName: string): { vpId?: string; category1: string } {
-  const match = scenarioName.match(/^(VP-[A-Z][A-Z0-9]*-\d+(?:[a-zA-Z]|-[A-Z0-9]+)?)\s+(.+)$/);
+  const match = scenarioName.match(new RegExp(SCENARIO_ID.source + '\\s+(.+)$'));
   if (match) {
     return { vpId: match[1], category1: match[2] };
   }
@@ -194,6 +210,9 @@ export function splitVpAndName(scenarioName: string): { vpId?: string; category1
  */
 export function mapVpToCategory2(vpId: string | undefined, scenarioName?: string): string {
   if (!vpId) return 'Function';
+  // Compare on the category segment so a project scheme without the `VP-` prefix
+  // (`SEC-123`) classifies the same as `VP-SEC-001`.
+  vpId = /^VP-/.test(vpId) ? vpId : `VP-${vpId}`;
   if (vpId.startsWith('VP-SEC-')) {
     if (scenarioName && /xss|injection/i.test(scenarioName)) return 'Function';
     return 'Accessing';