qfai 1.4.37 → 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.37".length > 0) {
-    return "1.4.37";
+  if ("1.4.38".length > 0) {
+    return "1.4.38";
   }
   try {
     const packagePath = resolvePackageJsonPath();
@@ -3648,15 +3648,29 @@ function buildUiFidelityScreens(expectedScreens, crawledRoutes, mockPathResults)
     const hasPass = mockPath?.entries.some(
       (entry) => entry.status.toLowerCase() === "pass"
     ) ?? false;
-    const expectedMarkers = screen.labels.map(
-      (label) => `${screen.uiContractId}:${label}`
-    );
-    const crawledMarkers = crawl?.markers ?? [];
-    const foundMarkers = expectedMarkers.filter(
-      (marker) => crawledMarkers.includes(marker)
-    );
+    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) => !crawledMarkers.includes(marker)
+      (marker) => !foundMarkers.includes(marker)
     );
     return {
       route: screen.route,
@@ -3664,7 +3678,8 @@ function buildUiFidelityScreens(expectedScreens, crawledRoutes, mockPathResults)
       expected: {
         elements: screen.elementCount,
         actions: screen.actionIds.length,
-        labels: screen.labels
+        labels: screen.labels,
+        ids: screen.elementIds
       },
       found: {
         labels: coverage.found,
@@ -3784,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,
@@ -3795,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 : [];
@@ -3842,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)
@@ -3859,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])
@@ -11723,7 +11761,8 @@ async function validateUiFidelity(root, config, evidenceJsonPath, evidence) {
         refs,
         "change",
         [
-          '\u753B\u9762\u306E\u5404\u8981\u7D20\u306B data-qfai="CONTRACT_ID:ELEMENT_LABEL" \u30DE\u30FC\u30AB\u30FC\u3092\u8FFD\u52A0\u3057\u3066\u304F\u3060\u3055\u3044\u3002',
+          '\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")
       )
@@ -12033,12 +12072,14 @@ function normalizeUiFidelityExpected(value) {
     };
   }
   const labels = toOptionalStringArray(value.labels);
+  const ids = toOptionalStringArray(value.ids);
   return {
     ok: true,
     value: {
       elements: value.elements,
       actions: value.actions,
-      ...labels ? { labels } : {}
+      ...labels ? { labels } : {},
+      ...ids ? { ids } : {}
     }
   };
 }