@sun-asterisk/sungen 3.2.20 → 3.2.21-beta.2

package/src/exporters/matrix/build.ts

@@ -5,7 +5,8 @@
  * is structural: there is no independent parent result input).
  */
 
-import { FeatureMetadata, PlaywrightResult } from '../types';
+import { ApiCatalogEntry, FeatureMetadata, PlaywrightResult } from '../types';
+import { formatApiCallLines, parseApiCalls } from '../api-testcase-formatter';
 import { bucketTexts } from './step-buckets';
 import { MergedScenario } from '../scenario-merger';
 import {
@@ -31,6 +32,8 @@ import {
   MAX_VARIANTS_PER_ITEM,
 } from './types';
 import { runGates } from './gates';
+import { capabilityRegistry } from '../../capabilities/registry';
+import { discoverAndRegisterCapabilities } from '../../capabilities/discover';
 
 // ---------------------------------------------------------------------------
 // Variant derivation
@@ -41,6 +44,27 @@ function normalizeShape(text: string): string {
   return text.replace(/\{\{[^}]*\}\}/g, '{{*}}').replace(/\s+/g, ' ').trim();
 }
 
+/**
+ * Is this scenario verified against MOCKED responses, and against which named deps? (#580)
+ * The mock capability owns its grammar: prefer the registry's `annotations` + `detectsStep`
+ * (driver-mock exports isMockStep — install AND call-count forms); fall back to literal
+ * twins of that grammar when the driver is not installed on this machine.
+ */
+export function detectMocked(tags: string[], stepTexts: string[]): { mocked: boolean; mockDeps: string[] } {
+  discoverAndRegisterCapabilities();
+  const cap = capabilityRegistry.get('mock');
+  const tagForms = cap?.annotations ?? ['@mock', '@network'];
+  const tagged = tags.some((t) => tagForms.some((a) => t === a || t.startsWith(`${a}:`)));
+  const isMockStep = cap?.detectsStep ?? ((t: string) =>
+    /\[[^\]]+\]\s+mock\s+is\s+active\b/i.test(t) ||
+    /\[[^\]]+\]\s+mock\s+called\s+(?:\{\{[^}]+\}\}|\d+)\s+times?\b/i.test(t));
+  const mockDeps = Array.from(new Set(stepTexts
+    .filter((t) => isMockStep(t))
+    .map((t) => (t.match(/\[([^\]]+)\]\s+mock\b/i) || [])[1])
+    .filter((x): x is string => Boolean(x))));
+  return { mocked: tagged || mockDeps.length > 0, mockDeps };
+}
+
 function deriveLayers(tags: string[]): MatrixLayer[] {
   const layers = new Set<MatrixLayer>(['ui']);
   if (tags.some((t) => t === '@api' || t.startsWith('@api:') || t === '@requires:api')) layers.add('api');
@@ -95,6 +119,8 @@ export interface BuildInputs {
   transformerVersion: string;
   /** requirements/spec.md content — source of the requirement-id inventory (FR/TR/NFR). */
   specText?: string;
+  /** apis.yaml endpoint catalog (api units) — renders `@api:` calls as request blocks. */
+  apiCatalog?: Record<string, ApiCatalogEntry>;
 }
 
 /**
@@ -102,11 +128,12 @@ export interface BuildInputs {
  * `@cases` dataset row). Exported separately so the gates + the map-proposal
  * support tooling see the same universe the builder does.
  */
-export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results'>): CoverageVariant[] {
+export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' | 'testData' | 'results' | 'apiCatalog'>): CoverageVariant[] {
   const { merged, results } = inputs;
   // Test-data values may cross-reference other keys (email_padded: " {{valid_email}} ") —
   // resolve one level so display cells never leak a template token (review B-04).
   const testData = resolveCrossRefs(inputs.testData);
+  const apiCatalog = inputs.apiCatalog ?? {};
   const variants: CoverageVariant[] = [];
 
   for (const m of merged) {
@@ -141,11 +168,27 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       tags,
     );
 
+    // `@api:<name>(args)` invocations — the runtime's precondition codegen (driver-api):
+    // each call sends its catalog request BEFORE the scenario's own steps and binds
+    // {{<name>.*}}. Cell placement follows what the tester actually does:
+    //  - pure api scenario (no When steps): the calls ARE the procedure → trigger,
+    //    rendered as Method/API/Header/Body blocks (the legacy Steps-cell language) —
+    //    the page-load fallback would misdescribe an HTTP request;
+    //  - hybrid (@api + own When steps): the calls are setup → precondition.
+    // Blocks keep raw `{{var}}` tokens here; renderCells' sub resolves them per data
+    // context (so @cases rows render their own arg values).
+    const apiCalls = parseApiCalls(tags);
+    const apiCallsAreTrigger = apiCalls.length > 0 && rawTrigger.length === 0;
+    const apiRequestLines = apiCalls.length > 0 ? formatApiCallLines(apiCalls, apiCatalog, (s) => s) : [];
+    // Shape entry per call: endpoint identity + arg KEYS (values are data, not shape).
+    const apiCallShapes = apiCalls.map((c) => `api:${c.name}(${Object.keys(c.args).join(',')})`);
+
     const preconditionProfile = [
       authRole ?? '-',
       m.feature.extendsName ?? '-',
       ...bucketTexts(m.feature.orderedSteps, 'given').map(normalizeShape),
       ...(manual?.preconditions ?? []).map(normalizeShape),
+      ...(apiCallsAreTrigger ? [] : apiCallShapes),
     ].join(' | ');
     // Display precondition = auth state + Background Given (shared start state) +
     // the scenario's own Given steps + manual Setup lines — deduplicated (a manual
@@ -155,18 +198,36 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
       ...bucketTexts(inputs.feature.backgroundOrderedSteps, 'given').map(renderPrecondition),
       ...bucketTexts(m.feature.orderedSteps, 'given').map(renderPrecondition),
       ...(manual?.preconditions ?? []).map((t) => renderSetupInstruction(t)),
+      ...(apiCallsAreTrigger ? [] : apiRequestLines),
     ]));
 
+    // Mocked-run detection (#580): a pass against a scripted response must never read as a
+    // pass against the real dependency. The GRAMMAR authority is the mock capability itself
+    // (driver-mock declares `annotations` and exports `detectsStep`) — consult it instead of
+    // re-writing its regexes here, so new tag/step forms are picked up automatically. The
+    // literal fallback keeps delivery honest on machines WITHOUT the driver installed
+    // (delivery reads only feature text + results, it never compiles). Background steps are
+    // scanned too — a Background install mocks every scenario in the feature, and the
+    // driver's own spec warns that per-scenario tracking misses them.
+    const scenarioStepTexts = [
+      ...inputs.feature.backgroundOrderedSteps.map((st) => st.text),
+      ...m.feature.orderedSteps.map((st) => st.text),
+    ];
+    const { mocked, mockDeps } = detectMocked(tags, scenarioStepTexts);
+
     const base = {
       vpId,
       vpCategory,
       priority: extractPriority(tags),
       mode: mode as 'auto' | 'manual',
       manualReason: manualReason(tags),
+      mocked,
+      ...(mockDeps.length ? { mockDeps } : {}),
       layers: deriveLayers(tags),
       traces: tags.filter((t) => t.startsWith('@spec:')).map((t) => t.slice('@spec:'.length)),
       runtimeVars: [...runtimeVars],
-      triggerShape: rawTrigger.map(normalizeShape),
+      apiCalls: apiCalls.length,
+      triggerShape: [...rawTrigger.map(normalizeShape), ...(apiCallsAreTrigger ? apiCallShapes : [])],
       oracleShape: rawOracle.map(normalizeShape),
       preconditionProfile,
       precondition,
@@ -196,7 +257,11 @@ export function deriveVariants(inputs: Pick<BuildInputs, 'feature' | 'merged' |
         });
         return { trigger, oracle, precondition: preconditionOut, verification: verificationOut };
       }
-      const trigger = rawTrigger.map((s) => renderAction(sub(s)));
+      // A pure api scenario's procedure is its request blocks (not renderAction —
+      // Method/API/Header/Body lines are already reader-facing, not step DSL).
+      const trigger = apiCallsAreTrigger
+        ? apiRequestLines.map(sub)
+        : rawTrigger.map((s) => renderAction(sub(s)));
       const oracle = rawOracle.map((s) => renderExpected(sub(s)));
       return {
         // A pure-render check (Given + Then only) is checked on page load — say so

package/src/exporters/matrix/export.ts

@@ -8,6 +8,7 @@
  */
 
 import * as fs from 'fs';
+import { loadApiCatalog } from '../api-catalog-loader';
 import { parseFeatureMetadata } from '../feature-parser';
 import { parseSpecFile } from '../spec-parser';
 import { loadTestData } from '../test-data-resolver';
@@ -16,17 +17,25 @@ import { mergeFeatureAndSpec } from '../scenario-merger';
 import { getPackageVersion } from '../package-info';
 import { writeCsv } from '../csv-exporter';
 import { writeXlsx } from '../xlsx-exporter';
+import { loadPerfConfig, perfVerdict } from '../../harness/perf';
 import { loadDeliveryMap, writeDeliveryMap } from './map-loader';
 import { mapContentFingerprint } from './fingerprint';
 import { buildMatrix, deriveVariants } from './build';
 import { renderMatrixXlsx } from './render-xlsx';
 import { renderMatrixCsv } from './render-csv';
 import { DeliveryMap, MatrixFinding, MatrixModel } from './types';
+import { ApiCatalogEntry } from '../types';
 
 export interface MatrixTargetPaths {
   cwd: string;
   /** Feature basename — names the deliverable files. */
   unit: string;
+  /** Unit kind — 'api' loads the endpoint catalog so cells render request blocks.
+   *  Optional for back-compat: absent means non-api (no catalog). */
+  kind?: 'screen' | 'flow' | 'api';
+  /** Area/screen directory name (differs from `unit` for sub-features) — keys the
+   *  unit-level apis.yaml path. Defaults to `unit`. */
+  area?: string;
   /** Display label (flow/… prefix for flows). */
   label: string;
   featureFile: string;
@@ -44,6 +53,11 @@ function readSpecText(paths: MatrixTargetPaths): string {
     : '';
 }
 
+/** apis.yaml endpoint catalog for an api unit ({} for screen/flow — loader no-ops). */
+function catalogFor(paths: MatrixTargetPaths): Record<string, ApiCatalogEntry> {
+  return loadApiCatalog(paths.cwd, paths.kind ?? 'screen', paths.area ?? paths.unit);
+}
+
 export interface MatrixLoadResult {
   model?: MatrixModel;
   map?: DeliveryMap;
@@ -74,7 +88,18 @@ export function loadMatrixModel(paths: MatrixTargetPaths): MatrixLoadResult {
     map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog: catalogFor(paths),
   });
+  // Perf verdict (#569): budgets are config (qa/perf.yaml), samples are the run's
+  // per-test durations. Advisory — reported here because delivery is where runs
+  // are read; the audit's score stays a pure function of the design artifacts.
+  const perfConfig = loadPerfConfig(paths.cwd);
+  if (perfConfig && results) {
+    const samples = [...results.values()]
+      .filter((r) => (r.status === 'passed' || r.status === 'failed' || r.status === 'timedOut') && typeof r.duration === 'number')
+      .map((r) => ({ title: r.testTitle, ms: r.duration as number }));
+    model.perf = perfVerdict(perfConfig, paths.unit, samples);
+  }
   return { model, map, mapErrors: [] };
 }
 
@@ -95,15 +120,17 @@ export function approveMatrix(paths: MatrixTargetPaths, groupIds?: string[]): {
   const merged = mergeFeatureAndSpec(feature, spec);
   const testData = fs.existsSync(paths.testDataFile) ? loadTestData(paths.testDataFile, process.env.SUNGEN_ENV ?? null) : null;
 
+  const apiCatalog = catalogFor(paths);
   const model = buildMatrix({
     unit: paths.unit, feature, merged, testData, results: null, map,
     transformerVersion: getPackageVersion(),
     specText: readSpecText(paths),
+    apiCatalog,
   });
   const blocking = model.findings.filter((f) => f.severity === 'error');
   if (blocking.length > 0) return { findings: blocking, approved: [] };
 
-  const variants = deriveVariants({ feature, merged, testData, results: null });
+  const variants = deriveVariants({ feature, merged, testData, results: null, apiCatalog });
   const byRef = new Map(variants.map((v) => [v.ref, v] as const));
   const byVp = new Map<string, typeof variants>();
   for (const v of variants) {

package/src/exporters/matrix/gates.ts

@@ -248,7 +248,13 @@ function gateDExecutability(ctx: GateContext, findings: MatrixFinding[]): void {
   for (const g of map.groups) {
     const vs = g.variants.flatMap((ref) => expandMapRef(ref, variantsByVp));
     for (const v of vs) {
-      const hasPrecondition = v.precondition.length > 0 || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0;
+      // An api-first variant (`@api:` calls, no UI steps) legitimately has no UI start
+      // state — the request blocks in its trigger (Method/API/Header/Body) carry
+      // everything a tester needs. Demanding a Background/Given here blocked 100% of
+      // api-first units (field report 3.2.19).
+      const hasPrecondition = v.precondition.length > 0
+        || bucketTexts(feature.backgroundOrderedSteps, 'given').length > 0
+        || v.apiCalls > 0;
       if (!hasPrecondition) {
         findings.push({
           gate: 'D', severity: 'error', ref: v.ref,

package/src/exporters/matrix/render-xlsx.ts

@@ -224,7 +224,7 @@ function addMatrixSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersion?
         // parent's steps + these read as one continuous procedure.
         numbered(item.triggerDeltas[v.ref] ?? [], item.trigger.length + 1),
         expectedWithVerification(v.oracle, v.verification),
-        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : 'Auto',
+        v.mode === 'manual' ? `Manual${v.manualReason ? ` (${v.manualReason})` : ''}` : (v.mocked ? 'Auto · Mocked' : 'Auto'),
         v.traces.join(', '),
         variantState(v),
         isoDate(v.result?.startTime),
@@ -315,6 +315,50 @@ function addCoverageSheet(wb: ExcelJS.Workbook, model: MatrixModel, sungenVersio
 
   let rowIdx = 7;
 
+  // --- Performance budget (#569) — advisory: config (qa/perf.yaml) vs measured runs.
+  if (model.perf) {
+    const p = model.perf;
+    dataCell(ws.getRow(rowIdx).getCell(2), 'Performance budget', { bold: true });
+    rowIdx++;
+    const r = ws.getRow(rowIdx);
+    dataCell(r.getCell(2), `p${p.percentile} ${p.metric.replace('_ms', ' time')}`);
+    dataCell(r.getCell(3), p.pass ? 'PASS' : 'OVER BUDGET', { bold: true });
+    dataCell(r.getCell(4), `measured ${p.measuredMs}ms`);
+    dataCell(r.getCell(5), `budget ${p.budgetMs}ms`);
+    dataCell(r.getCell(6), `${p.samples} runs`);
+    if (!p.pass && p.slowest.length) dataCell(r.getCell(8), `slowest: ${p.slowest.map((x) => `${x.ms}ms ${x.title.slice(0, 40)}`).join(' · ')}`);
+    rowIdx += 2;
+  }
+
+  // --- External Dependency Tracking (#580, ISTQB system-test practice): every case that
+  // ran against a MOCK is listed centrally. Its Result stays in the canonical vocabulary
+  // (the roll-up formulas depend on it); THIS table is where "Pass (Mocked) ≠ Pass (Real)"
+  // is visible — a case verified only against mocks is not Done until re-verified real.
+  {
+    const mockedVars = model.items.flatMap((it) => it.variants.filter((v) => v.mocked).map((v) => ({ it, v })));
+    if (mockedVars.length > 0) {
+      dataCell(ws.getRow(rowIdx).getCell(2), 'External Dependency Tracking — mock-verified cases (Pass here = Pass (Mocked), not Pass (Real))', { bold: true });
+      rowIdx++;
+      const hd = ws.getRow(rowIdx);
+      dataCell(hd.getCell(2), 'Variant');
+      dataCell(hd.getCell(3), 'Mocked dependency');
+      dataCell(hd.getCell(4), 'Delivery item');
+      dataCell(hd.getCell(5), 'Result');
+      dataCell(hd.getCell(8), 'Real-environment re-verify');
+      rowIdx++;
+      for (const { it, v } of mockedVars) {
+        const r = ws.getRow(rowIdx);
+        dataCell(r.getCell(2), v.ref);
+        dataCell(r.getCell(3), (v.mockDeps ?? []).join(', ') || '(scenario-level @mock)');
+        dataCell(r.getCell(4), it.id);
+        dataCell(r.getCell(5), variantState(v));
+        dataCell(r.getCell(8), '');
+        rowIdx++;
+      }
+      rowIdx++;
+    }
+  }
+
   // --- Requirement coverage (review §6): every requirement id gets ONE explicit status.
   if (model.requirements.length > 0) {
     dataCell(ws.getRow(rowIdx).getCell(2), 'Requirement coverage — every id has an explicit status', { bold: true });

package/src/exporters/matrix/types.ts

@@ -92,12 +92,23 @@ export interface CoverageVariant {
   /** 'auto' | 'manual'; manual keeps its @manual:Mx reason. */
   mode: 'auto' | 'manual';
   manualReason?: string;
+  /** The scenario runs against MOCKED network responses (@mock / `[x] mock is active`) —
+   *  a pass verifies the handling logic, not the real dependency (Pass (Mocked) ≠ Pass (Real),
+   *  #580: ISTQB external-dependency tracking). */
+  mocked?: boolean;
+  /** Named mocked dependencies (`[name] mock is active` refs), for the tracking table. */
+  mockDeps?: string[];
   layers: MatrixLayer[];
   /** @spec:* requirement traces. */
   traces: string[];
   /** Variables this scenario produces at RUN TIME (`remember … as {{v}}`, capability
    *  bindings) — they never exist in test-data, so Gate D must not demand them. */
   runtimeVars: string[];
+  /** Count of `@api:<name>` invocations. An api-first variant's start state lives in
+   *  its request blocks (Method/API/Header/Body), so Gate D's precondition demand is
+   *  waived when this is > 0 — requiring a Background/Given blocked EVERY api-first
+   *  unit (field report 3.2.19). */
+  apiCalls: number;
   /** Condition summary: differentiating dimension shown on the sub-row. */
   condition: string;
   /** Resolved data pairs (test-data values / dataset-row columns), `key: value` lines. */
@@ -220,6 +231,8 @@ export interface MatrixModel {
   requirements: RequirementCoverage[];
   findings: MatrixFinding[];
   manifest: MatrixManifest;
+  /** Perf verdict (#569) — present when qa/perf.yaml sets a budget AND the run produced durations. */
+  perf?: import('../../harness/perf').PerfVerdict | null;
 }
 
 /** Complexity warning threshold (rules draft Gate I; raised for compact grouping) — echoed in the manifest. */

package/src/exporters/playwright-report-parser.ts

@@ -54,6 +54,7 @@ interface PlaywrightSpec {
     projectId?: string;
     results?: Array<{
       status?: string;           // 'passed' | 'failed' | 'timedOut' | 'skipped' | 'interrupted'
+      duration?: number;         // ms — Playwright emits this on every result (#569 perf budgets)
       startTime?: string;
       error?: { message?: string; stack?: string };
       attachments?: Array<{ name?: string; path?: string; contentType?: string }>;
@@ -120,6 +121,7 @@ export function loadPlaywrightReport(reportPath: string): Map<string, Playwright
     result.set(stripped, {
       testTitle: stripped,
       status,
+      duration: typeof res?.duration === 'number' ? res.duration : undefined,
       startTime: res?.startTime,
       error: errorMsg,
       tracePath: trace,

package/src/exporters/types.ts

@@ -121,6 +121,8 @@ export interface SpecFileData {
 export interface PlaywrightResult {
   testTitle: string;
   status: 'passed' | 'failed' | 'skipped' | 'timedOut' | 'interrupted' | 'unknown';
+  /** Wall-clock run time in ms (from Playwright's results[].duration) — perf budgets (#569). */
+  duration?: number;
   startTime?: string;
   error?: string;
   tracePath?: string;

package/src/generators/test-generator/diagnostics.ts

@@ -35,12 +35,17 @@
  *             nothing for the query half to assert, so the step checks the PATH only. Not an
  *             error (the value may legitimately vary per environment), but the step asserts
  *             strictly less than it appears to
+ *   SG-W015 — `see [X] card/item with {{n}}` where the value is a bare number: this compiles
+ *             to a TEXT assertion (toHaveText('3')), NOT a count — an author reaching for
+ *             "3 cards are shown" gets an assertion that can only pass if the card's text
+ *             IS the digit. Count semantics exist on row/table ("see [T] table with {{n}}",
+ *             "see [Ref] row with {{n}}") and lists ("should have count") only
  *
  * Diagnostics never block generation by themselves; `sungen generate --strict`
  * turns any collected diagnostic into a non-zero exit.
  */
 
-export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014';
+export type DiagnosticCode = 'SG-W001' | 'SG-W002' | 'SG-W003' | 'SG-W005' | 'SG-W006' | 'SG-W007' | 'SG-W008' | 'SG-W009' | 'SG-W010' | 'SG-W011' | 'SG-W012' | 'SG-W013' | 'SG-W014' | 'SG-W015';
 
 export interface Diagnostic {
   code: DiagnosticCode;

package/src/generators/test-generator/patterns/index.ts

@@ -73,34 +73,40 @@ export class PatternRegistry {
    * Prefers resolver (returns template data) over generator (renders directly).
    */
   generateStep(step: ParsedStep, context: PatternContext): MappedStep | null {
-    const pattern = this.findPattern(step);
-    if (!pattern) {
-      return null;
-    }
-
-    // Prefer resolver (framework-agnostic) over generator (legacy)
-    if (pattern.resolver) {
-      const resolved = pattern.resolver(step, context);
-
-      // Auto-inject parent scoping if step has parentRef
-      // Skip for table-* patterns — they resolve the table name internally from step text
-      if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
-        resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
-          step.parentRef, step.parentType, context
-        );
+    // Matchers see only the STEP; some decisions need context (a resolver reading the
+    // test-data value, e.g. row-count's numeric check). A resolver may therefore return
+    // null to say "not mine after all" — the search continues with the next matching
+    // pattern in priority order instead of crashing or silently dropping the step.
+    const matchStep: ParsedStep = { ...step, text: maskRefsForMatching(step.text) };
+    for (const pattern of this.patterns) {
+      if (!this.matchesPattern(matchStep, pattern.matcher)) continue;
+
+      // Prefer resolver (framework-agnostic) over generator (legacy)
+      if (pattern.resolver) {
+        const resolved = pattern.resolver(step, context);
+        if (!resolved) continue; // resolver declined — fall through
+
+        // Auto-inject parent scoping if step has parentRef
+        // Skip for table-* patterns — they resolve the table name internally from step text
+        if (step.parentRef && step.parentType && !pattern.name.startsWith('table-')) {
+          resolved.data.parentLocator = PatternRegistry.resolveParentLocator(
+            step.parentRef, step.parentType, context
+          );
+        }
+
+        const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
+        return {
+          code,
+          comment: resolved.comment,
+        };
       }
 
-      const code = context.templateEngine.renderStep(resolved.templateName, resolved.data);
-      return {
-        code,
-        comment: resolved.comment,
-      };
-    }
+      if (pattern.generator) {
+        return pattern.generator(step, context);
+      }
 
-    if (pattern.generator) {
-      return pattern.generator(step, context);
+      return null;
     }
-
     return null;
   }
 

package/src/generators/test-generator/step-mapper.ts

@@ -175,6 +175,28 @@ export class StepMapper {
       this.lastPrimaryKeyword = keyword;
     }
 
+    // SG-W015 — `see [X] card with {{n}}` where n is a bare number compiles to a TEXT
+    // assertion (toHaveText('3')), not a count. An author reaching for "3 cards are shown"
+    // gets an assertion that can only pass if the card's TEXT is the digit — a wrong test
+    // with no error. Count semantics live on row/table ("see [T] table with {{n}}",
+    // "see [Ref] row with {{n}}") and lists ("should have count"); on the container types
+    // below, a bare-number text expectation is almost never what the author meant. A text
+    // element asserting a numeric readout ("[Row Quantity] text with 4") stays silent.
+    const COUNT_MISREAD_TYPES = new Set(['card', 'item', 'items', 'cards', 'option', 'options']);
+    if (this.diagnostics && step.dataRef && step.selectorRef &&
+        COUNT_MISREAD_TYPES.has((step.elementType || '').toLowerCase()) &&
+        /\bsees?\s+\[/.test(step.text) && /\bwith\b/.test(step.text)) {
+      // peekBaseValue reads the literal from test-data even in runtime-data mode,
+      // where resolveData returns an opaque marker (never numeric-looking).
+      let resolvedValue: string | undefined;
+      try { resolvedValue = this.dataResolver.peekBaseValue(step.dataRef, this.featureName); } catch { /* unresolved at compile time → cannot judge */ }
+      if (resolvedValue !== undefined && /^\d+$/.test(resolvedValue.trim())) {
+        this.diagnostics.add('SG-W015',
+          `\`see [${step.selectorRef}] ${step.elementType} with {{${step.dataRef}}}\` compiles to a TEXT assertion toHaveText('${resolvedValue.trim()}'), NOT a count of ${step.elementType}s. For a count use \`see [Ref] row with {{n}}\` / \`see [T] table with {{n}}\` (or a list "should have count"); if '${resolvedValue.trim()}' really is the ${step.elementType}'s text, assert it on a text/label element instead`,
+          { feature: this.featureName, step: step.text });
+      }
+    }
+
     // SG-W007 — a two-step-form browser-alert handler (`click [OK] alert`) written AFTER
     // an action step registers its page.once('dialog') listener too late: a dialog
     // triggered by the earlier action auto-dismisses with no error (issue #472).