qfai 1.4.36 → 1.4.38

package/assets/init/.qfai/contracts/ui/README.md

@@ -31,6 +31,14 @@ The contract must describe both screen structure and minimum mockable behavior.
   3. `.qfai/evidence/prototyping.json` (`uiFidelity` snapshot)
 - If label text is intentionally hidden (icon-only, aria-only), add stable `data-qfai` markers and document mapping in the contract comments.
 
+### `data-qfai` marker convention
+
+- Recommended marker value: `CONTRACT_ID:ELEMENT_ID` (example: `data-qfai="CON-UI-0001:search_input"`).
+- Use `elements[].id` (stable ID) for the marker suffix, not `elements[].label`.
+- Even when label text is not visible in the UI, markers ensure fidelity coverage.
+- autogen generates expected markers from `elements[].id` automatically.
+- Legacy format (`CONTRACT_ID:ELEMENT_LABEL`) is accepted for backward compatibility but new implementations should use the id-based format.
+
 ## Mockable prototype minimum (L2)
 
 Add `prototype` at the top level.

package/dist/cli/index.cjs

@@ -1589,8 +1589,8 @@ var import_promises7 = require("fs/promises");
 var import_node_path8 = __toESM(require("path"), 1);
 var import_node_url2 = require("url");
 async function resolveToolVersion() {
-  if ("1.4.36".length > 0) {
-    return "1.4.36";
+  if ("1.4.38".length > 0) {
+    return "1.4.38";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -3541,6 +3541,7 @@ async function crawlRoutesAndCollectFoundLabels(baseUrl, routes) {
         status: "failed",
         httpStatus: null,
         labels: [],
+        markers: [],
         error: `invalid baseUrl or route: baseUrl=${baseUrl}, route=${route}`
       });
       continue;
@@ -3556,11 +3557,13 @@ async function crawlRoutesAndCollectFoundLabels(baseUrl, routes) {
         clearTimeout(timeoutId);
         const html = await response.text();
         const labels = extractDomLabels(html);
+        const markers = extractDomMarkers(html);
         results.push({
           route,
           status: response.ok ? "ok" : "failed",
           httpStatus: response.status,
           labels,
+          markers,
           ...response.ok ? {} : { error: `http status ${response.status} for ${targetUrl}` }
         });
       } finally {
@@ -3572,6 +3575,7 @@ async function crawlRoutesAndCollectFoundLabels(baseUrl, routes) {
         status: "failed",
         httpStatus: null,
         labels: [],
+        markers: [],
         error: formatError4(error2)
       });
     }
@@ -3644,19 +3648,46 @@ function buildUiFidelityScreens(expectedScreens, crawledRoutes, mockPathResults)
     const hasPass = mockPath?.entries.some(
       (entry) => entry.status.toLowerCase() === "pass"
     ) ?? false;
+    const expectedMarkers = screen.elementIds.map(
+      (id) => `${screen.uiContractId}:${id}`
+    );
+    const crawledMarkersSet = new Set(crawl?.markers ?? []);
+    const labelToIdMarker = /* @__PURE__ */ new Map();
+    for (const pair of screen.elementPairs) {
+      const labelMarker = `${screen.uiContractId}:${pair.label}`;
+      const idMarker = `${screen.uiContractId}:${pair.id}`;
+      if (labelMarker !== idMarker) {
+        labelToIdMarker.set(labelMarker, idMarker);
+      }
+    }
+    const foundMarkers = expectedMarkers.filter((marker) => {
+      if (crawledMarkersSet.has(marker)) return true;
+      for (const [labelMarker, idMarker] of labelToIdMarker) {
+        if (idMarker === marker && crawledMarkersSet.has(labelMarker)) {
+          return true;
+        }
+      }
+      return false;
+    });
+    const missingMarkers = expectedMarkers.filter(
+      (marker) => !foundMarkers.includes(marker)
+    );
     return {
       route: screen.route,
       uiContractId: screen.uiContractId,
       expected: {
         elements: screen.elementCount,
         actions: screen.actionIds.length,
-        labels: screen.labels
+        labels: screen.labels,
+        ids: screen.elementIds
       },
       found: {
-        labels: coverage.found
+        labels: coverage.found,
+        markers: foundMarkers
       },
       missing: {
-        labels: coverage.missing
+        labels: coverage.missing,
+        markers: missingMarkers
       },
       coverage: coverage.coverage,
       observed: {
@@ -3768,6 +3799,8 @@ function collectContractScreens(contractId, doc, mockPathIds) {
       route,
       uiContractId: contractId,
       expectedLabels: elements.labels,
+      elementIds: elements.ids,
+      elementPairs: elements.pairs,
       elementCount: elements.count,
       actionIds,
       mockPathIds,
@@ -3779,8 +3812,15 @@ function collectContractScreens(contractId, doc, mockPathIds) {
 function collectElements(value) {
   const entries = Array.isArray(value) ? value : [];
   const validEntries = entries.map((entry) => readRecord(entry)).filter((entry) => Boolean(entry));
+  const ids = validEntries.map((entry) => readText(entry.id)).filter((id) => id.length > 0);
   const labels = validEntries.map((entry) => readText(entry.label)).filter((label) => label.length > 0);
-  return { labels: dedupeLabels(labels), count: validEntries.length };
+  const pairs = validEntries.map((entry) => ({ id: readText(entry.id), label: readText(entry.label) })).filter((pair) => pair.id.length > 0 && pair.label.length > 0);
+  return {
+    ids: Array.from(new Set(ids)).sort((a, b) => a.localeCompare(b)),
+    labels: dedupeLabels(labels),
+    pairs,
+    count: validEntries.length
+  };
 }
 function collectActionIds(value) {
   const entries = Array.isArray(value) ? value : [];
@@ -3826,6 +3866,10 @@ function dedupeExpectedScreens(screens) {
         route: screen.route,
         uiContractId: screen.uiContractId,
         labels: dedupeLabels(screen.expectedLabels),
+        elementIds: Array.from(new Set(screen.elementIds)).sort(
+          (a, b) => a.localeCompare(b)
+        ),
+        elementPairs: [...screen.elementPairs],
         elementCount: screen.elementCount,
         actionIds: Array.from(new Set(screen.actionIds)).sort(
           (a, b) => a.localeCompare(b)
@@ -3843,6 +3887,16 @@ function dedupeExpectedScreens(screens) {
       ...current.labels,
       ...screen.expectedLabels
     ]);
+    current.elementIds = Array.from(
+      /* @__PURE__ */ new Set([...current.elementIds, ...screen.elementIds])
+    ).sort((a, b) => a.localeCompare(b));
+    const existingIds = new Set(current.elementPairs.map((p) => p.id));
+    for (const pair of screen.elementPairs) {
+      if (!existingIds.has(pair.id)) {
+        current.elementPairs.push(pair);
+        existingIds.add(pair.id);
+      }
+    }
     current.elementCount += screen.elementCount;
     current.actionIds = Array.from(
       /* @__PURE__ */ new Set([...current.actionIds, ...screen.actionIds])
@@ -3899,16 +3953,31 @@ function extractDomLabels(html) {
       }
     }
   }
-  const rawBodyText = document.body?.textContent ?? "";
-  const bodyTokens = rawBodyText.split(/\s{2,}|\n+/);
-  for (const token of bodyTokens) {
-    const trimmed = normalizeDomLabel(token);
-    if (trimmed) {
-      labels.push(trimmed);
+  if (process.env.QFAI_AUTOGEN_BODY_TOKENS === "1") {
+    const rawBodyText = document.body?.textContent ?? "";
+    const bodyTokens = rawBodyText.split(/\s{2,}|\n+/);
+    for (const token of bodyTokens) {
+      const trimmed = normalizeDomLabel(token);
+      if (trimmed) {
+        labels.push(trimmed);
+      }
     }
   }
   return dedupeLabels(labels);
 }
+function extractDomMarkers(html) {
+  const dom = new import_jsdom.JSDOM(html);
+  const document = dom.window.document;
+  const markers = [];
+  for (const element of document.querySelectorAll("[data-qfai]")) {
+    const value = element.getAttribute("data-qfai") ?? "";
+    const trimmed = value.trim();
+    if (trimmed.length > 0) {
+      markers.push(trimmed);
+    }
+  }
+  return Array.from(new Set(markers)).sort((a, b) => a.localeCompare(b));
+}
 function normalizeDomLabel(value) {
   const normalized = value.replace(/\s+/g, " ").trim();
   if (normalized.length === 0) {
@@ -3926,7 +3995,7 @@ function hasLabelMatch(foundLabels, expectedLabel) {
   }
   return foundLabels.some((label) => {
     const normalizedFound = normalizeComparableText(label);
-    return normalizedFound === normalizedExpected || normalizedFound.includes(normalizedExpected) || normalizedExpected.includes(normalizedFound);
+    return normalizedFound === normalizedExpected;
   });
 }
 function normalizeComparableText(value) {
@@ -3992,9 +4061,35 @@ var DEFAULT_EVIDENCE_PATH = ".qfai/evidence/prototyping.json";
 async function runPrototyping(options) {
   const autogenEnabled = options.autogenUiFidelity || process.env[ENV_AUTOGEN] === "1";
   if (!autogenEnabled) {
+    if (options.autogenOnly) {
+      error(
+        `prototyping: --autogen-only \u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u3059\u304C --autogen-ui-fidelity / ${ENV_AUTOGEN}=1 \u304C\u3042\u308A\u307E\u305B\u3093\u3002`
+      );
+      return 2;
+    }
     info(
       `prototyping: --autogen-ui-fidelity or ${ENV_AUTOGEN}=1 \u304C\u6307\u5B9A\u3055\u308C\u3066\u3044\u307E\u305B\u3093\u3002\u4F55\u3082\u5B9F\u884C\u3057\u307E\u305B\u3093\u3002`
     );
+    const evidencePath2 = resolveEvidencePath(options.root, options.evidenceOut);
+    const toolVersion2 = await resolveToolVersion();
+    let existingEvidence2 = {};
+    try {
+      const raw = await (0, import_promises14.readFile)(evidencePath2, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        existingEvidence2 = parsed;
+      }
+    } catch {
+    }
+    const skippedEvidence = emitUiFidelity({
+      evidence: existingEvidence2,
+      toolVersion: toolVersion2,
+      command: "qfai prototyping",
+      baseUrl: "",
+      status: "skipped",
+      reason: "autogen not enabled (--autogen-ui-fidelity or env not set)"
+    });
+    await writeEvidence(evidencePath2, skippedEvidence);
     return 0;
   }
   const baseUrl = resolveBaseUrl(options);
@@ -4017,9 +4112,15 @@ async function runPrototyping(options) {
     }
   } catch {
   }
+  const routeHints = extractRouteHintsFromEvidence(existingEvidence);
   let result;
   try {
-    result = await autogenerateUiFidelity(options.root, config, baseUrl, []);
+    result = await autogenerateUiFidelity(
+      options.root,
+      config,
+      baseUrl,
+      routeHints
+    );
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     warn(`prototyping: autogen failed - ${reason}`);
@@ -4098,6 +4199,45 @@ async function writeEvidence(filePath, evidence) {
   await (0, import_promises14.mkdir)(import_node_path17.default.dirname(filePath), { recursive: true });
   await (0, import_promises14.writeFile)(filePath, JSON.stringify(evidence, null, 2) + "\n", "utf-8");
 }
+function extractRouteHintsFromEvidence(evidence) {
+  const routes = /* @__PURE__ */ new Set();
+  const runtimeGate = evidence.runtimeGate;
+  if (runtimeGate && typeof runtimeGate === "object" && !Array.isArray(runtimeGate)) {
+    const gate = runtimeGate;
+    const uiRows = gate.ui;
+    if (Array.isArray(uiRows)) {
+      for (const row of uiRows) {
+        if (row && typeof row === "object" && !Array.isArray(row)) {
+          const r = row;
+          if (typeof r.route === "string" && r.route.trim().length > 0) {
+            routes.add(r.route.trim());
+          }
+        }
+      }
+    }
+  }
+  const specs = evidence.specs;
+  if (Array.isArray(specs)) {
+    for (const spec of specs) {
+      if (spec && typeof spec === "object" && !Array.isArray(spec)) {
+        const s = spec;
+        const missing = s.missing;
+        if (missing && typeof missing === "object" && !Array.isArray(missing)) {
+          const m = missing;
+          const uiRoutes = m.uiRoutes;
+          if (Array.isArray(uiRoutes)) {
+            for (const route of uiRoutes) {
+              if (typeof route === "string" && route.trim().length > 0) {
+                routes.add(route.trim());
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  return Array.from(routes).sort((a, b) => a.localeCompare(b));
+}
 
 // src/cli/commands/report.ts
 var import_promises42 = require("fs/promises");
@@ -11577,6 +11717,83 @@ async function validateUiFidelity(root, config, evidenceJsonPath, evidence) {
       )
     );
   }
+  const screensWithMissingLabels = uiFidelity.screens.filter(
+    (screen) => screen.expected.labels && screen.expected.labels.length > 0 && screen.missing?.labels && screen.missing.labels.length > 0
+  );
+  if (screensWithMissingLabels.length > 0) {
+    const details = screensWithMissingLabels.map((screen) => {
+      const missing = screen.missing?.labels ?? [];
+      return `${screen.route}:${screen.uiContractId}(missing_labels=${missing.join("|")})`;
+    }).sort((a, b) => a.localeCompare(b));
+    const refs = collectLabelMismatchRefs(screensWithMissingLabels);
+    issues.push(
+      issue(
+        "QFAI-PROT-241",
+        `QFAI-PROT-241: uiFidelity screens have missing labels. ${details.join("; ")}`,
+        "error",
+        evidenceJsonPath,
+        "prototypingEvidence.uiFidelityMissingLabels",
+        refs,
+        "change",
+        [
+          "contracts/ui \u306E elements[].label \u3092\u753B\u9762\u306B\u3059\u3079\u3066\u63CF\u753B\u3057\u3066\u304F\u3060\u3055\u3044\u3002",
+          "\u63CF\u753B\u304C\u96E3\u3057\u3044\u8981\u7D20\u306F data-qfai \u30DE\u30FC\u30AB\u30FC\u3067\u4EE3\u66FF\u3057\u3001autogen \u3092\u518D\u5B9F\u884C\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+        ].join("\n")
+      )
+    );
+  }
+  const screensWithMissingMarkers = uiFidelity.screens.filter(
+    (screen) => screen.expected.elements > 0 && screen.missing?.markers && screen.missing.markers.length > 0
+  );
+  if (screensWithMissingMarkers.length > 0) {
+    const details = screensWithMissingMarkers.map((screen) => {
+      const missing = screen.missing?.markers ?? [];
+      return `${screen.route}:${screen.uiContractId}(missing_markers=${missing.join("|")})`;
+    }).sort((a, b) => a.localeCompare(b));
+    const refs = collectMarkerMismatchRefs(screensWithMissingMarkers);
+    issues.push(
+      issue(
+        "QFAI-PROT-242",
+        `QFAI-PROT-242: uiFidelity screens have missing markers. ${details.join("; ")}`,
+        "error",
+        evidenceJsonPath,
+        "prototypingEvidence.uiFidelityMissingMarkers",
+        refs,
+        "change",
+        [
+          '\u753B\u9762\u306E\u5404\u8981\u7D20\u306B data-qfai="CONTRACT_ID:ELEMENT_ID" \u30DE\u30FC\u30AB\u30FC\u3092\u8FFD\u52A0\u3057\u3066\u304F\u3060\u3055\u3044\u3002',
+          '\u30DE\u30FC\u30AB\u30FC\u306E\u5024\u306F contracts/ui \u306E elements[].id \u3092\u4F7F\u3044\u307E\u3059\uFF08\u4F8B: data-qfai="CON-UI-0001:search_input"\uFF09\u3002',
+          "autogen \u3092\u518D\u5B9F\u884C\u3057\u3001missing.markers \u304C\u7A7A\u306B\u306A\u308B\u3053\u3068\u3092\u78BA\u8A8D\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+        ].join("\n")
+      )
+    );
+  }
+  const placeholderScreens = uiFidelity.screens.filter((screen) => {
+    if (!screen.found?.labels) return false;
+    const expectedElements = screen.expected.elements;
+    const observedElements = screen.observed.elementsPlaced;
+    const foundLabels = screen.found.labels.length;
+    return expectedElements > 2 && observedElements <= 1 && foundLabels <= 1;
+  });
+  if (placeholderScreens.length > 0) {
+    const details = placeholderScreens.map(
+      (screen) => `${screen.route}:${screen.uiContractId}(expected=${screen.expected.elements},observed=${screen.observed.elementsPlaced})`
+    ).sort((a, b) => a.localeCompare(b));
+    issues.push(
+      issue(
+        "QFAI-PROT-243",
+        `QFAI-PROT-243: placeholder/single-text pages detected. ${details.join("; ")}`,
+        "warning",
+        evidenceJsonPath,
+        "prototypingEvidence.placeholderPages",
+        placeholderScreens.map(
+          (screen) => `${screen.uiContractId}|${screen.route}`
+        ),
+        "change",
+        "\u30D7\u30EC\u30FC\u30B9\u30DB\u30EB\u30C0\u30FC\u30DA\u30FC\u30B8\u3092\u691C\u51FA\u3057\u307E\u3057\u305F\u3002contracts/ui \u306E\u5168\u8981\u7D20\u3092\u753B\u9762\u306B\u914D\u7F6E\u3057\u3066\u304F\u3060\u3055\u3044\u3002"
+      )
+    );
+  }
   const hasMockPaths = uiFidelity.screens.some(
     (screen) => screen.mockPaths.length > 0
   );
@@ -11647,6 +11864,40 @@ function collectUiFidelityMismatchRefs(mismatches) {
   }
   return Array.from(refs).sort((left, right) => left.localeCompare(right));
 }
+function collectLabelMismatchRefs(screens) {
+  const refs = /* @__PURE__ */ new Set();
+  for (const screen of screens) {
+    refs.add(`contract_id=${screen.uiContractId}`);
+    refs.add(`route=${screen.route}`);
+    refs.add(`contract_route=${screen.uiContractId}|${screen.route}`);
+    const missingLabels = screen.missing?.labels ?? [];
+    if (missingLabels.length > 0) {
+      const labels = missingLabels.sort((a, b) => a.localeCompare(b)).join("|");
+      refs.add(`missing_labels=${labels}`);
+      refs.add(
+        `missing_labels_by_contract_route=${screen.uiContractId}|${screen.route}:${labels}`
+      );
+    }
+  }
+  return Array.from(refs).sort((l, r) => l.localeCompare(r));
+}
+function collectMarkerMismatchRefs(screens) {
+  const refs = /* @__PURE__ */ new Set();
+  for (const screen of screens) {
+    refs.add(`contract_id=${screen.uiContractId}`);
+    refs.add(`route=${screen.route}`);
+    refs.add(`contract_route=${screen.uiContractId}|${screen.route}`);
+    const missingMarkers = screen.missing?.markers ?? [];
+    if (missingMarkers.length > 0) {
+      const markers = missingMarkers.sort((a, b) => a.localeCompare(b)).join("|");
+      refs.add(`missing_markers=${markers}`);
+      refs.add(
+        `missing_markers_by_contract_route=${screen.uiContractId}|${screen.route}:${markers}`
+      );
+    }
+  }
+  return Array.from(refs).sort((l, r) => l.localeCompare(r));
+}
 async function collectUiContractScreens(contractIndex) {
   const result = /* @__PURE__ */ new Map();
   for (const [contractId, fileSet] of contractIndex.idToFiles.entries()) {
@@ -11799,6 +12050,9 @@ function normalizeUiFidelityScreen(value) {
       route: value.route.trim(),
       uiContractId: value.uiContractId.trim().toUpperCase(),
       expected: expected.value,
+      ...normalizeOptionalFoundBlock(value.found),
+      ...normalizeOptionalMissingBlock(value.missing),
+      ...typeof value.coverage === "number" ? { coverage: value.coverage } : {},
       observed: observed.value,
       mockPaths: mockPaths.value
     }
@@ -11817,11 +12071,15 @@ function normalizeUiFidelityExpected(value) {
       reason: "`uiFidelity.screens[].expected` requires non-negative integers for elements/actions"
     };
   }
+  const labels = toOptionalStringArray(value.labels);
+  const ids = toOptionalStringArray(value.ids);
   return {
     ok: true,
     value: {
       elements: value.elements,
-      actions: value.actions
+      actions: value.actions,
+      ...labels ? { labels } : {},
+      ...ids ? { ids } : {}
     }
   };
 }
@@ -11979,6 +12237,47 @@ function toStringArray2(value) {
   }
   return value.map((item) => item.trim()).filter((item) => item.length > 0);
 }
+function toOptionalStringArray(value) {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    return void 0;
+  }
+  return value.map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function normalizeOptionalFoundBlock(value) {
+  if (!isRecord5(value)) {
+    return {};
+  }
+  const labels = toOptionalStringArray(value.labels);
+  const markers = toOptionalStringArray(value.markers);
+  if (!labels && !markers) {
+    return {};
+  }
+  return {
+    found: {
+      ...labels ? { labels } : {},
+      ...markers ? { markers } : {}
+    }
+  };
+}
+function normalizeOptionalMissingBlock(value) {
+  if (!isRecord5(value)) {
+    return {};
+  }
+  const labels = toOptionalStringArray(value.labels);
+  const markers = toOptionalStringArray(value.markers);
+  if (!labels && !markers) {
+    return {};
+  }
+  return {
+    missing: {
+      ...labels ? { labels } : {},
+      ...markers ? { markers } : {}
+    }
+  };
+}
 function isRecord5(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
@@ -14728,7 +15027,10 @@ var ISSUE_EXPECTED_BY_CODE = {
   "QFAI-PROT-114": "Per-spec DB checks satisfy declared object counts and leave no unresolved DB objects.",
   "QFAI-PROT-231": "Interactive prototyping evidence includes uiFidelity with required screen-level fields.",
   "QFAI-PROT-232": "uiFidelity screen observations satisfy referenced UI contract elements/actions coverage.",
-  "QFAI-PROT-233": "Interactive uiFidelity records at least one mockPaths status=pass entry (warning in v1.4.36).",
+  "QFAI-PROT-233": "Interactive uiFidelity records at least one mockPaths status=pass entry (warning in v1.4.37).",
+  "QFAI-PROT-241": "uiFidelity screens must have no missing labels when expected.labels is present.",
+  "QFAI-PROT-242": "uiFidelity screens must have no missing markers when expected.elements > 0 and markers are tracked.",
+  "QFAI-PROT-243": "Placeholder/single-text pages are detected when expected elements > 2, observed <= 1, and found.labels <= 1 (warning in v1.4.37).",
   "QFAI-CONTRACT-030": "Contract index references must match declared contract IDs in .qfai/contracts/**."
 };
 function resolveIssueTarget(issue2) {