@sun-asterisk/sungen 3.2.28 → 3.2.30

package/src/harness/data-driven-lint.ts

@@ -3,8 +3,25 @@
  *
  * Advisory (warn, never block) — surfaced after `sungen generate`. Catches the silent
  * footguns: a `{{var}}` in a @cases scenario that is neither a row column nor a top-level
- * key, a name collision that shadows a top-level value, inconsistent dataset rows, and a
- * @query whose param has no value / whose name doesn't resolve.
+ * key, a name collision that shadows a top-level value, inconsistent dataset rows, a
+ * @query whose param has no value / whose name doesn't resolve, and a top-level test-data
+ * key nothing binds (dead data).
+ *
+ * "Referenced" is what the COMPILER and the RUNTIME actually read, not just `{{key}}` in a step:
+ *   - `{{key…}}` in any step, or in the comments of a `@manual` scenario (its tester procedure is
+ *     the only body it has — the delivery exports those refs, so they are not dead);
+ *   - a `@cases:<key>` dataset;
+ *   - an override value `…={{key…}}` on an @api/@query annotation;
+ *   - a @query or @api param bound IMPLICITLY by name — `params: [user_email]` with no override
+ *     reads `testData.raw("user_email")` at run time (driver-db / driver-api), so the key is live
+ *     even though no `{{user_email}}` appears anywhere;
+ *   - `{{key}}` in the unit's selectors (locale-aware names) or mock catalog (mock bodies).
+ * Keys that start with `_` are Data Factory metadata (`_generated_by`, `_fingerprint`), never
+ * scenario data — the factory itself skips them by the same rule.
+ * The FORWARD direction is checked here too: a `{{x}}` in a plain scenario whose head is neither a
+ * test-data key nor bound at run time compiles to the literal text `'${x}'` — the step types the
+ * placeholder into the field and the scenario runs green having tested nothing. The compiler emits
+ * no diagnostic for that fallback, so this lint names it.
  */
 import * as fs from 'fs';
 import * as path from 'path';
@@ -20,15 +37,113 @@ export interface DataDrivenWarning {
 
 const ROW_META = new Set(['case', 'name', 'label', '__label']);
 
-/** Collect the inner text of every `{{…}}` reference in a scenario's steps. */
-function collectRefs(sc: ParsedScenario): string[] {
+/**
+ * Collect the inner text of every `{{…}}` reference in a scenario's steps — and, for a `@manual`
+ * scenario, in its comments: the `# Tester verifies: …` procedure is its only body and the delivery
+ * exporter reads those refs. Other scenarios' comments are NOT scanned: a ref mentioned only in
+ * prose would otherwise hide a genuinely dead key.
+ */
+function collectRefs(sc: ParsedScenario, manual: boolean = isManualScenario(sc)): string[] {
   const refs = new Set<string>();
-  for (const st of sc.steps || []) {
-    for (const m of (st.text || '').matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) refs.add(m[1]);
+  const texts = (sc.steps || []).map((st) => st.text || '');
+  if (manual) texts.push(...(sc.comments || []));
+  for (const text of texts) {
+    for (const m of text.matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) refs.add(m[1]);
   }
   return [...refs];
 }
 
+function isManualScenario(sc: ParsedScenario): boolean {
+  return (sc.tags || []).some((t) => t === '@manual' || t.startsWith('@manual:'));
+}
+
+/** Variable heads a scenario binds at RUN time: `@api:<name>`/`@query:<name>` responses and `remember … as {{v}}` captures. */
+function runtimeBoundHeads(sc: ParsedScenario): Set<string> {
+  const out = new Set<string>();
+  for (const t of sc.tags || []) {
+    const m = t.match(/^@(?:api|query):([A-Za-z_]\w*)/);
+    if (m) out.add(m[1]);
+  }
+  for (const st of sc.steps || []) {
+    for (const m of (st.text || '').matchAll(/\bas\s+\{\{\s*([^}.[\s]+)/g)) out.add(m[1]);
+  }
+  return out;
+}
+
+/**
+ * The unit id the catalogs are resolved by — the path under `qa/`, with the `screens/` prefix
+ * dropped: `qa/screens/login` → `login`, `qa/flows/checkout` → `flows/checkout`, `qa/api/pet` →
+ * `api/pet`, `qa/api/flows/signup` → `api/flows/signup`. `generate` hands every unit kind to this
+ * lint; a bare basename sent an api unit's `@query` to `qa/screens/<area>/database/` and reported
+ * every query as "not found".
+ */
+function unitIdOf(unitDir: string): string {
+  const parts = path.resolve(unitDir).split(path.sep);
+  const qa = parts.lastIndexOf('qa', parts.length - 2); // a unit itself named `qa` is not the qa/ root
+  if (qa < 0) {
+    const base = path.basename(unitDir);
+    return path.basename(path.dirname(unitDir)) === 'flows' ? `flows/${base}` : base;
+  }
+  const rel = parts.slice(qa + 1);
+  return (rel[0] === 'screens' ? rel.slice(1) : rel).join('/');
+}
+
+/**
+ * `{{key}}` refs the unit's OTHER authored files carry — a locale-aware selector (`name: '{{lbl_submit}}'`,
+ * resolved from test-data by the selector resolver) and a mock body (`body: "{{mock_search_body}}"`,
+ * bound by the mock driver at compile time). A key used only there is live, not dead.
+ */
+function refsInUnitFiles(unitDir: string): Set<string> {
+  const out = new Set<string>();
+  for (const sub of ['selectors', 'mock']) {
+    const dir = path.join(unitDir, sub);
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (!/\.ya?ml$/.test(f)) continue;
+      const text = fs.readFileSync(path.join(dir, f), 'utf8');
+      for (const m of text.matchAll(/\{\{\s*([^}$][^}]*?)\s*\}\}/g)) out.add(m[1].split(/[.[]/)[0]);
+    }
+  }
+  return out;
+}
+
+/**
+ * Param names of the `@api:<name>` entries a unit can reference — declared `params:`, else the
+ * `:name` placeholders in path/body/headers (the same derivation the API driver applies). Read
+ * straight from the catalog files: a param not overridden in the annotation is bound at run time by
+ * NAME from test-data (`testData.raw("petId")`), so that key is live even with no `{{petId}}` anywhere.
+ * Best-effort — a missing or unparseable catalog contributes nothing (the api driver's own sensor
+ * reports those).
+ */
+function apiParamsByName(unitId: string, cwd: string): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const unitCatalog = unitId.startsWith('api/') || unitId.startsWith('flows/')
+    ? path.join(cwd, 'qa', unitId, 'api', 'apis.yaml')
+    : path.join(cwd, 'qa', 'screens', unitId, 'api', 'apis.yaml');
+  for (const file of [unitCatalog, path.join(cwd, 'qa', 'api', 'apis.yaml')]) {
+    if (!fs.existsSync(file)) continue;
+    let raw: any;
+    try { raw = parseYaml(fs.readFileSync(file, 'utf8')) || {}; } catch { continue; }
+    const root = raw && typeof raw === 'object' && raw.apis && typeof raw.apis === 'object' ? raw.apis : raw;
+    for (const [name, v] of Object.entries(root as Record<string, any>)) {
+      if (!v || typeof v !== 'object' || typeof v.method !== 'string' || typeof v.path !== 'string') continue;
+      if (out.has(name)) continue; // unit catalog wins over the shared one
+      // Same rule as the driver's apiParamNames: declared `params` when non-empty, else the `:name`
+      // placeholders of path/body/headers/files/bodyFile — except an XML string body, whose `:` are
+      // namespaces, where only declared params count.
+      const declared = Array.isArray(v.params) && v.params.length ? v.params.map(String) : null;
+      const refs = new Set<string>();
+      const xmlBody = v.encoding === 'xml' && typeof v.body === 'string';
+      const texts = [v.path, xmlBody ? '' : JSON.stringify(v.body ?? ''), JSON.stringify(v.headers ?? ''), JSON.stringify(v.files ?? ''), JSON.stringify(v.bodyFile ?? '')];
+      for (const text of texts) {
+        for (const m of String(text).matchAll(/:([A-Za-z_][A-Za-z0-9_]*)/g)) refs.add(m[1]);
+      }
+      out.set(name, declared ?? (xmlBody ? [] : [...refs]));
+    }
+  }
+  return out;
+}
+
 /** Keys overridden in a `@query:name(a=…,b=…)` annotation. */
 function overrideKeys(raw?: string): Set<string> {
   const out = new Set<string>();
@@ -43,29 +158,69 @@ function overrideKeys(raw?: string): Set<string> {
 /** Lint the @cases/@query usage of one screen/flow directory. Returns advisory warnings. */
 export function lintDataDriven(screenDir: string, cwd: string = process.cwd()): DataDrivenWarning[] {
   const base = path.basename(screenDir);
-  const isFlow = path.basename(path.dirname(screenDir)) === 'flows';
-  const screenName = isFlow ? `flows/${base}` : base;
+  const screenName = unitIdOf(screenDir);
   // Every `.feature` of the unit — `add --feature` sub-features lint too. A file that
   // fails to parse contributes nothing rather than voiding the whole unit's lint.
-  const scenarios: ParsedScenario[] = featureFilesFor(screenDir, base)
-    .filter((p) => fs.existsSync(p))
-    .flatMap((p) => {
-      try {
-        return new GherkinParser().parseFeatureFile(p).scenarios || [];
-      } catch {
-        return [];
-      }
-    });
+  const scenarios: ParsedScenario[] = [];
+  const featureTags: string[] = [];
+  for (const p of featureFilesFor(screenDir, base).filter((f) => fs.existsSync(f))) {
+    try {
+      const feature = new GherkinParser().parseFeatureFile(p);
+      scenarios.push(...(feature.scenarios || []));
+      featureTags.push(...(feature.tags || []));
+    } catch {
+      /* a file that fails to parse contributes nothing */
+    }
+  }
   if (scenarios.length === 0) return [];
 
   const tdPath = path.join(screenDir, 'test-data', `${base}.yaml`);
   const td: Record<string, any> = tdPath && fs.existsSync(tdPath) ? parseYaml(fs.readFileSync(tdPath, 'utf8')) || {} : {};
   const topKeys = new Set(Object.keys(td));
   const warns: DataDrivenWarning[] = [];
+  // Bindings a `@beforeAll` hook's `@api:`/`@query:` preconditions make are readable from EVERY
+  // scenario of the feature (the compiler registers them feature-wide). A `remember … as` inside the
+  // hook is NOT — it stays hook-local — so only the tag-bound names are exempted here.
+  const featureBound = new Set<string>();
+  for (const sc of scenarios) {
+    if (sc.hookType !== 'beforeAll') continue;
+    for (const t of sc.tags || []) { const m = t.match(/^@(?:api|query):([A-Za-z_]\w*)/); if (m) featureBound.add(m[1]); }
+  }
+  // H3: an `@extend:<base>` scenario runs the base's steps first — the base's captures bind for it.
+  const stepsBase = new Map<string, ParsedScenario>();
+  for (const sc of scenarios) if (sc.stepsName) stepsBase.set(sc.stepsName, sc);
+  // `{{key}}` refs carried by the unit's selectors (i18n) and mock catalog are live too.
+  const fileRefs = refsInUnitFiles(screenDir);
+  // A feature-level `@manual` makes every scenario manual (the whole file is skipped by the compiler).
+  const featureManual = featureTags.some((t) => t === '@manual' || t.startsWith('@manual:'));
+
+  // What the scenarios bind, collected up front — the @query pass below adds the params it binds by name.
+  const usedHeads = new Set<string>();
+  const usedDatasets = new Set<string>();
+  const apiParams = apiParamsByName(screenName, cwd);
+  for (const h of fileRefs) usedHeads.add(h);
+  for (const sc of scenarios) {
+    for (const r of collectRefs(sc, featureManual || isManualScenario(sc))) usedHeads.add(r.split(/[.[]/)[0]);
+    for (const t of sc.tags || []) {
+      const cm = t.match(/^@cases:(.+)$/);
+      if (cm) usedDatasets.add(cm[1].trim());
+      const om = t.match(/^@(?:api|query):[A-Za-z_]\w*\((.*)\)$/);
+      if (om) for (const ref of om[1].matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) usedHeads.add(ref[1].split(/[.[]/)[0].trim());
+      // `@api:<name>` params not overridden in the annotation are read from test-data BY NAME at run time.
+      const am = t.match(/^@api:([A-Za-z_]\w*)(?:\((.*)\))?$/);
+      if (am) {
+        const overrides = overrideKeys(am[2]);
+        for (const p of apiParams.get(am[1]) ?? []) if (!overrides.has(p)) usedHeads.add(p);
+      }
+    }
+  }
 
   for (const sc of scenarios) {
     const tags: string[] = sc.tags || [];
-    const refs = collectRefs(sc);
+    const manual = featureManual || isManualScenario(sc);
+    const refs = collectRefs(sc, manual);
+    const bound = runtimeBoundHeads(sc);
+    if (sc.extendsName && stepsBase.has(sc.extendsName)) for (const h of runtimeBoundHeads(stepsBase.get(sc.extendsName)!)) bound.add(h);
 
     // --- @cases -----------------------------------------------------------
     const casesTag = tags.find((t) => t.startsWith('@cases:'));
@@ -85,6 +240,9 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
         }
         for (const r of refs) {
           const head = r.split(/[.[]/)[0];
+          // `{{$uuid}}` is resolved at run time; `{{login.status}}` / `{{captured}}` are bound by the
+          // scenario's own @api/@query call or `remember … as` — none of them is test-data.
+          if (head.startsWith('$') || bound.has(head)) continue;
           if (!allCols.has(head) && !topKeys.has(head)) {
             warns.push({ scenario: sc.name, message: `@cases:${ds} → {{${r}}} is neither a dataset column nor a top-level test-data key.` });
           }
@@ -92,6 +250,16 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
       }
     }
 
+    // --- forward: a ref in a PLAIN scenario that nothing provides ----------------------------
+    //     (@cases scenarios are covered above with their row columns; hooks bind their own refs)
+    if (!casesTag && !manual) { // a @manual scenario is never compiled — nothing to say about literals
+      for (const r of refs) {
+        const head = r.split(/[.[]/)[0];
+        if (head.startsWith('$') || bound.has(head) || featureBound.has(head) || topKeys.has(head)) continue;
+        warns.push({ scenario: sc.name, message: `{{${r}}} is not a test-data key and nothing binds it at run time — it compiles to the literal text '\${${r}}' (add the key to test-data, or fix the ref).` });
+      }
+    }
+
     // --- @query -----------------------------------------------------------
     for (const t of tags) {
       const m = t.match(/^@query:([A-Za-z_][A-Za-z0-9_]*)(?:\((.*)\))?$/);
@@ -106,7 +274,10 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
         continue;
       }
       for (const p of entry.params || []) {
-        if (!overrides.has(p) && !topKeys.has(p)) {
+        if (overrides.has(p)) continue;
+        // Not overridden → the runtime reads `testData.raw("<p>")`: the key IS referenced, by name.
+        usedHeads.add(p);
+        if (!topKeys.has(p)) {
           warns.push({ scenario: sc.name, message: `@query:${name} → param "${p}" has no value: not in the annotation and not a top-level test-data key.` });
         }
       }
@@ -114,20 +285,9 @@ export function lintDataDriven(screenDir: string, cwd: string = process.cwd()):
   }
 
   // --- orphan test-data: a top-level key never referenced (dead data — generated but not
-  //     materialized into a scenario). Referenced = a `{{key…}}` in any step, a `@cases:<key>`
-  //     dataset, or an override value `…={{key…}}` on an @api/@query annotation.
-  const usedHeads = new Set<string>();
-  const usedDatasets = new Set<string>();
-  for (const sc of scenarios) {
-    for (const r of collectRefs(sc)) usedHeads.add(r.split(/[.[]/)[0]);
-    for (const t of sc.tags || []) {
-      const cm = t.match(/^@cases:(.+)$/);
-      if (cm) usedDatasets.add(cm[1].trim());
-      const om = t.match(/^@(?:api|query):[A-Za-z_]\w*\((.*)\)$/);
-      if (om) for (const ref of om[1].matchAll(/\{\{\s*([^}]+?)\s*\}\}/g)) usedHeads.add(ref[1].split(/[.[]/)[0].trim());
-    }
-  }
+  //     materialized into a scenario). See the header for what counts as referenced.
   for (const k of topKeys) {
+    if (k.startsWith('_')) continue; // Data Factory metadata, not scenario data
     if (!usedHeads.has(k) && !usedDatasets.has(k)) {
       warns.push({ message: `test-data key "${k}" is defined but never referenced ({{${k}}}, a @cases dataset, or an override) — dead data: bind it into a scenario or remove it.` });
     }

package/src/harness/parse.ts

@@ -41,6 +41,12 @@ export interface ScenarioInfo {
   ownedByFlow?: string;       // @owned-by:<flow> — the flow that owns this deferred scenario (H6)
   /** Ordered steps with their resolved bucket (And/But inherit) — flow handoff analysis (#569). */
   steps?: Array<{ bucket: 'given' | 'when' | 'then'; text: string }>;
+  /**
+   * The `.feature` this scenario was read from. A unit may hold several (`add --feature`), and
+   * `scenarioIdReuse` scopes its uniqueness check to ONE file — so the sensor needs to know
+   * which. Set by `loadScenarios`; absent on hand-built fixtures, which then count as one file.
+   */
+  sourceFile?: string;
 }
 
 /** Format-tolerant: is this token an ID (project's scheme), not a prose word?
@@ -270,7 +276,7 @@ export function loadScenarios(featurePath: string): ScenarioInfo[] {
   const feature = parser.parseFeatureFile(featurePath);
   return (feature.scenarios || [])
     .filter((s) => !s.stepsName && !s.hookType) // skip @steps/@hook blocks
-    .map((s) => classifyScenario(withBackground(s, feature.background)));
+    .map((s) => ({ ...classifyScenario(withBackground(s, feature.background)), sourceFile: featurePath }));
 }
 
 /**

package/src/harness/repair.ts

@@ -10,6 +10,7 @@ import * as path from 'path';
 import { capabilityRegistry } from '../capabilities/registry';
 import { discoverAndRegisterCapabilities } from '../capabilities/discover';
 import { scoringCapabilityFor } from './audit';
+import { readCapabilities } from './capability';
 
 export interface RepairProposal { source: 'audit' | 'runtime'; signal: string; ruleId: string; fix: string }
 export interface RepairPlan {
@@ -50,7 +51,13 @@ function failuresFromResult(file: string): string[] {
  */
 export function planRepair(unitId: string, reportName: string, cwd: string, generatedDir?: string): RepairPlan {
   discoverAndRegisterCapabilities();
-  const capId = scoringCapabilityFor(unitId, capabilityRegistry.defaultCapabilityId());
+  // The ACTIVE PLATFORM is part of capability resolution, and leaving it out silently sent every
+  // mobile unit to the web catalog: `scoringCapabilityFor`'s third parameter is what lets `mobile`
+  // beat the default `ui`, `runAudit` passes it, and this call did not. A bare screen on a
+  // `platform: mobile` project therefore resolved to `ui` — whose repair rules are the WEB ones —
+  // so registering a mobile catalog would have changed nothing here. `cwd` is the project root
+  // (the CLI passes `process.cwd()`), which is where `qa/capabilities.yaml` lives.
+  const capId = scoringCapabilityFor(unitId, capabilityRegistry.defaultCapabilityId(), readCapabilities(cwd).platform);
   const rules = (capId ? capabilityRegistry.get(capId)?.repair?.rules : undefined) ?? [];
 
   const signals: { source: 'audit' | 'runtime'; text: string }[] = [];

package/src/harness/script-check.ts

@@ -38,7 +38,7 @@ export interface ScriptCheckResult {
   findings: string[];
 }
 
-/** Split a spec into test() blocks (title + body) via brace counting. */
+/** Split a spec into test() / it() blocks (title + body) via brace counting. */
 export function extractTestBlocks(specSrc: string): { title: string; body: string[] }[] {
   const lines = specSrc.split('\n');
   const blocks: { title: string; body: string[] }[] = [];
@@ -46,7 +46,11 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
     // Same escape-aware title match as extractTestTitles — with `[^'"`]+` a
     // quote-bearing title extracted truncated (or not at all), missed the
     // automatedTitles lookup, and silently dropped out of the BYPASS scan.
-    const m = lines[i].match(/\btest(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/);
+    // The `test|it` alternation matches extractTestTitles (#429): mobile/Appium specs
+    // are mocha and declare `it(`, so a `test(`-only splitter returned ZERO blocks for
+    // them and check C — the whole anti-bypass scan — silently examined nothing on
+    // every mobile unit (#707). Only extractTestTitles got the alternation in #429.
+    const m = lines[i].match(/\b(?:test|it)(?:\.(?:only|skip|fixme))?\(\s*(['"`])((?:\\.|(?!\1).)+)\1/);
     if (!m) continue;
     let depth = 0, started = false;
     const body: string[] = [];
@@ -66,38 +70,180 @@ export function extractTestBlocks(specSrc: string): { title: string; body: strin
 // reading as hollow: a sync void call after its step comment matched none of the
 // original alternatives (no await/expect/testData, `page` only as a bare argument,
 // no `=`), so @mock:passthrough scenarios were flagged BYPASS (field report) — on
-// sungen's own mock-route golden fixture, no less. Comment lines are step markers
-// (never inside a scanned region), so `identifier(` cannot false-match non-code.
+// sungen's own mock-route golden fixture, no less. Comment lines are excluded by the
+// caller before this test runs (#673 — a step's region legitimately contains template
+// comments), so `identifier(` cannot false-match a commented-out call.
 const CODE_LINE = /\b(await|expect|testData|page\.)\b|=\s*[^=]|[\w$]\s*\(/;
 
+// A line that proves something — the oracle vocabulary of BOTH adapters. Written as one
+// pattern because the alternatives differ only in spelling, not in kind:
+//   expect( / expectPage( / expectCheckedState(   playwright + its generated helpers
+//   __assertVisible( / __assertCheckedState(      appium helpers
+//   db.assertRow( / assertNoUnmocked( / …         data-driver and mock oracles
+//   throw new Error(`[sungen] Expected …`)        appium value/text assertion, emitted inline
+// Deliberately generous: a missed assertion costs a FALSE BYPASS, and this file's own
+// convention is that a false BYPASS — the finding that makes a QA deliverable look
+// untrustworthy — is the costlier error. See #707.
+const ASSERTION_LINE = /\bexpect\w*\s*\(|\b(?:db\.)?assert\w*\s*\(|\b__assert\w*\s*\(|\[sungen\] Expected /;
+
+// The compiler's own step-comment convention: an assertion step is emitted as `// Assert …`.
+// It is the second, adapter-neutral oracle signal, and it is what keeps this check honest
+// without chasing template internals: several Appium assertions compile to a bespoke polling
+// loop closed by a `throw` (`Then User see device log contains …`), matching no call shape at
+// all. Measured across the 55 committed goldens: 103 test blocks carry BOTH signals, 19 carry
+// only a call (the api/db steps word their comments differently), 1 carries only the comment
+// — so neither signal alone is sufficient and the union is what the check needs.
+// A `// Assert` step that emitted nothing is NOT silently excused by this: an empty step
+// region is precisely what the hollow-step scan below reports.
+const ASSERTION_STEP_COMMENT = /^\s*\/\/\s*Assert\b/;
+
+// A step the compiler deliberately compiles to NOTHING, and says so in the emitted comment.
+// `appium/templates/steps/navigation/navigation.hbs` is the only comment-only step template
+// on that adapter: an Appium session opens the app from the wdio capabilities, so
+// `Given User is on [Home] page` has no navigation left to perform. It is not a hollow step —
+// there is no code the adapter failed to emit. Without this, un-blinding check C on mobile
+// reported a BYPASS on EVERY mobile unit that opens with a page step, i.e. all of them (#707).
+// Anchored to the start of a comment line: the phrase is emitted by exactly one template today,
+// but as a bare substring it would also exempt a genuinely hollow step whose test-data or step
+// text happened to contain it.
+const NOOP_STEP_MARKER = /^\s*\/\/\s*App launched via wdio capabilities/;
+
+/** A spec comment line reduced to its text, for comparison against a compiler step comment. */
+const commentText = (line: string): string => line.trim().replace(/^\/\/\s?/, '').trim();
+
+/**
+ * Which `//` lines of a test body are STEP markers (#673).
+ *
+ * Structural (preferred) — the compiler records the step comments it emitted per scenario
+ * (`CodeGenerator.stepTrace`), so a comment line is a step marker only when it IS one, matched
+ * in order. Template bodies, `// [from @steps:…]` section headers and a step's own trailing
+ * explanation lines are then region content rather than phantom steps.
+ *
+ * Heuristic fallback (no trace — a hand-rolled spec, or regeneration failed) — a RUN of
+ * consecutive comment lines counts as ONE marker, anchored at its first line. Attributing every
+ * comment line separately gave each one an empty region, so a step followed by so much as one
+ * explanation comment reported "emitted no code": 30+ false BYPASS findings on shipped templates.
+ */
+function stepMarkers(body: string[], trace?: string[]): { markers: number[]; structural: boolean } {
+  const commentIdx: number[] = [];
+  for (let k = 1; k < body.length; k++) if (body[k].trim().startsWith('//')) commentIdx.push(k);
+  // First line of each run of adjacent comments — the step comment precedes its template body.
+  const runs = { markers: commentIdx.filter((k, i) => i === 0 || commentIdx[i - 1] !== k - 1), structural: false };
+  if (!trace?.length) return runs;
+  const markers: number[] = [];
+  let from = 0;
+  for (const want of trace) {
+    const hit = commentIdx.findIndex((k, i) => i >= from && commentText(body[k]) === want.trim());
+    if (hit < 0) return runs; // the trace does not describe THIS block (stale/edited spec) → heuristic
+    markers.push(commentIdx[hit]);
+    from = hit + 1;
+  }
+  return { markers, structural: true };
+}
+
 /**
  * Faithfulness / anti-bypass: a non-@manual test that performs actions but proves
  * nothing (0 assertions), or a step-comment that emitted no executable code (hollow
  * — the testcase step is not run). Structural 1:1 can't see these.
  */
-export function analyzeFaithfulness(specSrc: string, automatedTitles: Set<string>) {
+export function analyzeFaithfulness(
+  specSrc: string,
+  automatedTitles: Set<string>,
+  stepTrace?: Map<string, string[]>,
+) {
   const assertionlessTests: string[] = [];
   const hollowSteps: { test: string; step: string }[] = [];
   for (const blk of extractTestBlocks(specSrc)) {
-    if (!automatedTitles.has(blk.title)) continue; // only non-@manual scenarios
+    // Compare on the canonical scenario name, exactly as check A does: a mobile title carries
+    // its tags (`… [@high]`) and a @cases title its row-label suffix, so a raw comparison
+    // matched NOTHING on those units and check C skipped every one of them (#707).
+    const title = canonSpecTitle(blk.title);
+    if (!automatedTitles.has(title)) continue; // only non-@manual scenarios
     // TQ-11 — a capability-pending @requires scenario compiles to a `test.skip(true, …)` stub:
     // it intentionally proves nothing here (it runs once the driver is added), so it is not a bypass.
     if (blk.body.some((l) => /\btest\.skip\(\s*true\b/.test(l))) continue;
+    // Same category on the appium adapter (#707): a web-only step compiles to a loud refusal
+    // (`throw new Error('[sungen] step … is web-only — the appium adapter cannot express it')`).
+    // It carries no assertion by design and can never pass silently — it always throws — so it
+    // is a refusal, not a bypass. Flagging it would report the adapter doing its job as a defect.
+    if (blk.body.some((l) => /web-only — the appium adapter cannot express it/.test(l))) continue;
     const body = blk.body;
-    // An assertion is a Playwright `expect(...)` OR a Data Driver DB assertion
-    // (`db.assertRow/assertNoRow/assertCount/...`) — a DB check is a real oracle, so a
-    // DB-only scenario (no UI expect) is NOT a bypass.
-    if (!body.some((l) => /expect\(|\bdb\.assert\w*\s*\(/.test(l))) assertionlessTests.push(blk.title);
+    // Step boundaries come first — the assertionless check below needs them to tell an
+    // `// Assert …` step that emitted code from one that emitted nothing.
+    // stepTrace is keyed by the RAW scenario name (code-generator.ts), so it too must be
+    // looked up by the canonical title — on mobile the tagged spec title never hit it and
+    // check C silently fell back to its heuristic attribution.
+    const { markers, structural } = stepMarkers(body, stepTrace?.get(title));
+    const isComment = (l: string): boolean => l.trim().startsWith('//');
+    /** The lines a step owns: from its marker to the next marker (or the end of the block). */
+    const regionOf = (s: number): string[] =>
+      body.slice(markers[s] + 1, s + 1 < markers.length ? markers[s + 1] : body.length);
+    // What counts as an assertion, across both adapters:
+    //   - Playwright `expect(...)`, and its generated helpers `expectPage(...)` /
+    //     `expectCheckedState(...)` — `expect\(` alone missed these, since the literal
+    //     `(` never follows `expect` in a helper name;
+    //   - the appium helpers `__assertVisible(...)` / `__assertCheckedState(...)`, which is
+    //     how the mobile adapter expresses EVERY visibility and checked-state assertion;
+    //   - a Data Driver DB assertion (`db.assertRow/assertNoRow/assertCount/...`) or a
+    //     mock assertion (`assertNoUnmocked(...)`) — a DB check is a real oracle, so a
+    //     DB-only scenario (no UI expect) is NOT a bypass;
+    //   - the appium value/text assertions, which compile to an inline comparison closed by
+    //     `throw new Error('[sungen] Expected …')` rather than a helper call.
+    // Under the Playwright-literal detector that preceded this, un-blinding the mobile splitter
+    // reported 13 of 18 mobile-parity tests as assertionless — every one of them a false BYPASS.
+    //
+    // Both signals are read from CODE, never from a comment:
+    //   - a comment is not an oracle. `alert-text-assertion.hbs` ships a commented-out
+    //     `// expect(await dialogPromise1).toContain(…)` placeholder for the author to
+    //     uncomment; scanning raw lines let that dead literal satisfy the check and silence
+    //     a genuinely assertionless dialog test.
+    //   - an `// Assert …` step counts only when the step actually EMITTED something. An
+    //     assertion step that compiled to nothing is not an assertion, and it must stay
+    //     visible here: the hollow-step scan below excuses an ambiguous LAST step on the
+    //     heuristic path, so leaning on it as the sole backstop let a hollow trailing
+    //     `// Assert …` escape both signals whenever the regenerate failed.
+    //
+    // On the heuristic path the `// Assert …` line is not always the marker: stepMarkers
+    // collapses a run of adjacent comments to its FIRST line, so a step whose comment sits
+    // under a header — an `@extend` `// [from @steps:…]` section header, a @cases row label —
+    // has its real step comment one line INTO the region. Reading only the marker there
+    // reported a genuinely-asserting polling test as assertionless. Scan the rest of the
+    // collapsed run, and only there: with structural attribution the markers ARE the compiler's
+    // step comments, nothing was collapsed, and a region's later comments are template body
+    // text that must not be mistaken for the step's own label.
+    const assertLabeled = (s: number): boolean => {
+      if (ASSERTION_STEP_COMMENT.test(body[markers[s]])) return true;
+      if (structural) return false;
+      for (const l of regionOf(s)) {
+        if (!isComment(l)) return false; // past the collapsed run
+        if (ASSERTION_STEP_COMMENT.test(l)) return true;
+      }
+      return false;
+    };
+    const hasOracle =
+      body.some((l) => !isComment(l) && ASSERTION_LINE.test(l)) ||
+      markers.some((_m, s) => assertLabeled(s)
+        && regionOf(s).some((l) => !isComment(l) && CODE_LINE.test(l)));
+    if (!hasOracle) assertionlessTests.push(title);
     // hollow step: a `// step` whose region (until the NEXT step-comment / block end)
     // contains no executable code. The region — not just the next line — is checked,
     // so block-style steps (`// Assert all … { … expect … }`) are correctly counted.
-    const stepIdx: number[] = [];
-    for (let k = 1; k < body.length; k++) if (body[k].trim().startsWith('//')) stepIdx.push(k);
-    for (let s = 0; s < stepIdx.length; s++) {
-      const start = stepIdx[s] + 1;
-      const end = s + 1 < stepIdx.length ? stepIdx[s + 1] : body.length;
-      const hasCode = body.slice(start, end).some((l) => CODE_LINE.test(l));
-      if (!hasCode) hollowSteps.push({ test: blk.title, step: body[stepIdx[s]].trim().slice(0, 70) });
+    // Heuristic path only: the block's LAST comment run is ambiguous — a genuinely hollow final
+    // step and a step's own trailing explanation (`alert-text-assertion.hbs` emits two such lines)
+    // have an identical shape, and only the compiler knows which it is. A false BYPASS is the
+    // costlier error — it is the finding that makes a QA deliverable look untrustworthy — so stay
+    // silent there and let the 0-assertion check carry a truly empty test.
+    const tailAmbiguous = !structural;
+    for (let s = 0; s < markers.length; s++) {
+      // Comment-only lines are never the step's code: with structural attribution a step's region
+      // legitimately holds its template's comments (`user-login-todo.hbs` emits six).
+      const region = regionOf(s);
+      const hasCode = region.some((l) => !isComment(l) && CODE_LINE.test(l));
+      // A documented no-op emits its explanation INTO the step's region, so read the region
+      // (not just the marker line) for it — see NOOP_STEP_MARKER.
+      if (hasCode || region.some((l) => NOOP_STEP_MARKER.test(l))) continue;
+      if (tailAmbiguous && s === markers.length - 1) continue;
+      hollowSteps.push({ test: title, step: body[markers[s]].trim().slice(0, 70) });
     }
   }
   return { assertionlessTests, hollowSteps };
@@ -119,6 +265,22 @@ function extractTestTitles(specSrc: string): string[] {
   return titles;
 }
 
+/**
+ * Reduce a title as it appears IN THE SPEC to the bare scenario name from the .feature,
+ * so both compare on the same footing. Two codegen shapes add a suffix:
+ *   - mobile/mocha appends the pass-through tags (`… [@high @spec:FR-01]`) because mocha
+ *     has no per-test tag option;
+ *   - a @cases scenario emits `'<name> — ' + __row.__label` (or the legacy
+ *     `<name> — ${__row.__label}`), extracted as the literal `<name> —`.
+ * Shared by check A (structural 1:1) and check C (faithfulness) — check C used to compare
+ * raw and so skipped every mobile and every @cases block it was handed (#707).
+ */
+function canonSpecTitle(t: string): string {
+  return t
+    .replace(/\s*\[@[^\]]*\]$/, '')
+    .replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
+}
+
 /** Undo the compiler's escapeQuotes escaping (\' \\ \n \r \t) so extracted titles
  *  compare against the raw scenario names from the .feature. */
 function unescapeJsLiteral(s: string): string {
@@ -200,9 +362,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   // (and plain titles) compare on the same footing. Mobile/mocha specs append the
   // tags to the title (`it('<name> [@high @spec:FR-01]')` — mocha has no tag option),
   // so strip that suffix too or every mobile scenario reads MISSING + EXTRA (#429).
-  const canonSpecTitle = (t: string) => t
-    .replace(/\s*\[@[^\]]*\]$/, '')
-    .replace(/\s*—(\s*\$\{__row\.__label\})?$/, '');
+  // canonSpecTitle now lives at module scope — check C needs the identical reduction.
   const specTitleSet = new Set(specTitles.map(canonSpecTitle));
   const expectedSet = new Set(automated.map((s) => s.name));
   const missingInSpec = automated.filter((s) => !specTitleSet.has(s.name)).map((s) => s.name);
@@ -217,6 +377,10 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
   // B. Drift — regenerate to temp and diff
   let drift: ScriptCheckResult['drift'] = committedSpec ? 'in-sync' : 'no-spec';
   const driftHunks: string[] = [];
+  // #673 — the regenerate below also yields the compiler's step-boundary trace, which check C
+  // needs to tell a step comment from a template body comment. Hoisted out of the try so a
+  // failed regenerate degrades check C to its heuristic instead of crashing it.
+  let stepTrace: Map<string, string[]> | undefined;
   if (committedSpec) {
     try {
       const { CodeGenerator } = require('../generators/test-generator/code-generator');
@@ -232,6 +396,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
         ? new CodeGenerator({ framework, runtimeData: true })
         : new CodeGenerator({ framework, screenName, runtimeData: true, flowMode: kind === 'flow' });
       await gen.generateAllTests(qaSourceDir, tmp, featureFiles);
+      stepTrace = gen.stepTrace;
       // Pair each committed spec with its regenerated twin by filename — one `.feature`
       // compiles to one `.spec.ts`, so a multi-feature unit has several of each.
       const freshByName = new Map(findSpecs(tmp, screenName, kind).map((p) => [path.basename(p), p]));
@@ -265,7 +430,7 @@ export async function runScriptCheck(screenDir: string, screenName: string, kind
 
   // C. Anti-bypass / faithfulness
   const { assertionlessTests, hollowSteps } = committedSpec
-    ? analyzeFaithfulness(specSrc, expectedSet)
+    ? analyzeFaithfulness(specSrc, expectedSet, stepTrace)
     : { assertionlessTests: [], hollowSteps: [] };
   for (const t of assertionlessTests) {
     findings.push(`BYPASS: test "${t}" has 0 assertions (action-only — proves nothing). The testcase is not really automated.`);