android2harmony 0.1.6 → 0.1.8

package/skills/a2h-spec-implement/scripts/state_propagation_check.mjs

@@ -0,0 +1,676 @@
+// L0 state-propagation checker — the four ArkUI state pitfalls that compile clean, pass
+// codelinter, and still fail on device as "value stored, screen never changes".
+//
+// Report shape is codelinter-compatible on purpose, so the L0 gate consumes it exactly like
+// lint-report.json:  [{ filePath, messages: [{ line, column, severity, message, rule }] }]
+//   severity=error → blocking (structural pattern, high precision)
+//   severity=warn  → suspect  (needs one human judgement call)
+//
+//   P1 builder-value-param     @Builder taking state by value never re-renders its body
+//   P2 controller-vs-callback  on*Change overwrites what a controller setter just set
+//   P3 async-only-state        a state member is written only in callback / post-await paths
+//   P5 foreach-key-omits-state keyGenerator misses the state that changes the item. Counts state
+//                              reached through a helper the item body calls, and blocks (error)
+//                              when the key is identity-only AND the omitted state is written.
+//
+// Usage: node state_propagation_check.mjs --dir <project-or-dir> [--out <report.json>]
+//                                        [--files a.ets,b.ets] [--all-error]
+// Exit 0 = no blocking finding, 1 = blocking finding, 2 = bad invocation. Zero deps.
+//
+// Criteria and the fix for each pattern:
+//   ../rules/arkts/ui/state-management.md  § State written but never rendered
+import fs from "node:fs";
+import path from "node:path";
+import { emit } from "./_lib/common.mjs";
+
+const STATE_DECORATORS = new Set([
+  "State", "StorageLink", "StorageProp", "Prop", "Link", "Local", "Param",
+  "Provide", "Consume", "ObjectLink", "Computed",
+]);
+const PRIMITIVE = /^(string|number|boolean|Resource)$/;
+const KEYWORD = new Set([
+  "if", "for", "while", "switch", "catch", "return", "typeof", "new", "await", "function",
+  "constructor", "super", "else", "do", "try", "case", "delete", "void", "in", "of",
+]);
+
+// --- blank comments and string bodies (length + newlines preserved) so scans never match
+// inside them. Template `${...}` expressions stay live code — P5 must read them.
+function blankNonCode(s) {
+  const out = s.split("");
+  const stack = [];
+  let i = 0, mode = "code", quote = "";
+  const blank = (k) => { if (out[k] !== "\n" && out[k] !== "\r") out[k] = " "; };
+  while (i < s.length) {
+    const c = s[i], d = s[i + 1];
+    if (mode === "code") {
+      if (c === "/" && d === "/") { blank(i); blank(i + 1); mode = "line"; i += 2; continue; }
+      if (c === "/" && d === "*") { blank(i); blank(i + 1); mode = "block"; i += 2; continue; }
+      if (c === "'" || c === '"') { quote = c; mode = "str"; i++; continue; }
+      if (c === "`") { stack.push("t"); mode = "tmpl"; i++; continue; }
+      if (c === "}" && stack.length && stack[stack.length - 1] === "e") { stack.pop(); mode = "tmpl"; i++; continue; }
+      i++; continue;
+    }
+    if (mode === "line") { if (c === "\n") { mode = "code"; i++; continue; } blank(i); i++; continue; }
+    if (mode === "block") {
+      if (c === "*" && d === "/") { blank(i); blank(i + 1); mode = "code"; i += 2; continue; }
+      blank(i); i++; continue;
+    }
+    if (mode === "str") {
+      if (c === "\\") { blank(i); blank(i + 1); i += 2; continue; }
+      if (c === quote) { mode = "code"; i++; continue; }
+      blank(i); i++; continue;
+    }
+    // tmpl
+    if (c === "\\") { blank(i); blank(i + 1); i += 2; continue; }
+    if (c === "$" && d === "{") { stack.push("e"); mode = "code"; i += 2; continue; }
+    if (c === "`") { stack.pop(); mode = "code"; i++; continue; }
+    blank(i); i++;
+  }
+  return out.join("");
+}
+
+function lineStarts(src) {
+  const a = [0];
+  for (let i = 0; i < src.length; i++) if (src[i] === "\n") a.push(i + 1);
+  return a;
+}
+function posOf(starts, idx) {
+  let lo = 0, hi = starts.length - 1;
+  while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= idx) lo = mid; else hi = mid - 1; }
+  return { line: lo + 1, column: idx - starts[lo] + 1 };
+}
+function matchPair(code, i, open, close) {
+  let depth = 0;
+  for (let k = i; k < code.length; k++) {
+    if (code[k] === open) depth++;
+    else if (code[k] === close) { depth--; if (depth === 0) return k; }
+  }
+  return -1;
+}
+function splitArgs(text) {
+  const args = []; let depth = 0, cur = "";
+  for (const ch of text) {
+    if ("([{".includes(ch)) depth++;
+    else if (")]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) { args.push(cur.trim()); cur = ""; continue; }
+    cur += ch;
+  }
+  if (cur.trim()) args.push(cur.trim());
+  return args;
+}
+
+function findStructs(code) {
+  const out = [];
+  const re = /\bstruct\s+(\w+)[^{]*\{/g;
+  let m;
+  while ((m = re.exec(code))) {
+    const open = code.indexOf("{", m.index);
+    const end = matchPair(code, open, "{", "}");
+    if (end < 0) continue;
+    out.push({ name: m[1], start: open + 1, end });
+    re.lastIndex = open + 1;
+  }
+  return out;
+}
+
+function findMembers(code, start, end) {
+  const body = code.slice(start, end);
+  const members = new Map();
+  const re = /@(\w+)\s*(?:\([^)]*\))?\s*(?:(?:private|public|protected|readonly)\s+)*(\w+)\s*[?!]?\s*(?:=|:\s*([\w.<>\[\]|]+))/g;
+  let m;
+  while ((m = re.exec(body))) {
+    if (!STATE_DECORATORS.has(m[1])) continue;
+    if (!members.has(m[2])) members.set(m[2], { decorator: m[1], type: m[3] || "", idx: start + m.index });
+  }
+  return members;
+}
+
+// Method bodies inside a struct, each tagged with whether @Builder precedes it.
+function findMethods(code, start, end) {
+  const out = [];
+  const re = /(?:^|[\s;}])((?:private|public|protected|static|async)\s+)*(\w+)\s*\(/g;
+  re.lastIndex = start;
+  let m;
+  while ((m = re.exec(code)) && m.index < end) {
+    const name = m[2];
+    const paren = code.indexOf("(", m.index + (m[1] ? m[1].length : 0));
+    if (KEYWORD.has(name) || paren < 0 || paren > end) { continue; }
+    const pClose = matchPair(code, paren, "(", ")");
+    if (pClose < 0) continue;
+    let k = pClose + 1;
+    while (k < end && /\s/.test(code[k])) k++;
+    if (code[k] === ":") {                       // skip a return-type annotation
+      const brace = code.indexOf("{", k);
+      const semi = code.indexOf(";", k);
+      if (brace < 0 || (semi >= 0 && semi < brace)) continue;
+      k = brace;
+    }
+    if (code[k] !== "{") continue;
+    const bClose = matchPair(code, k, "{", "}");
+    if (bClose < 0) continue;
+    const before = code.slice(Math.max(start, m.index - 300), m.index);
+    out.push({
+      name,
+      isBuilder: /@Builder\s*$/.test(before),
+      params: splitArgs(code.slice(paren + 1, pClose)),
+      bodyStart: k + 1, bodyEnd: bClose, idx: m.index,
+    });
+    re.lastIndex = bClose;
+  }
+  return out;
+}
+
+// Regions that are callback bodies. `kind` distinguishes the two families, which matter for
+// different checks:
+//   ui     — ArkUI attribute callbacks (.onClick/.onChange/.onTextSelectionChange). A user tap
+//            always arrives, so these are NOT a liveness risk (P3 ignores them), but they DO
+//            overwrite state on the next frame (P2 needs exactly these).
+//   engine — an engine/service subscription: `.on('stateChange', …)` with a string event name,
+//            or `.then/.catch`. These may never fire, which is the P3 defect.
+function callbackRegions(code, start, end) {
+  const regions = [];
+  const re = /\.\s*(on\w*|then|catch|finally)\s*\(/g;
+  re.lastIndex = start;
+  let m;
+  while ((m = re.exec(code)) && m.index < end) {
+    const paren = code.indexOf("(", m.index);
+    const close = matchPair(code, paren, "(", ")");
+    if (close < 0) { re.lastIndex = paren + 1; continue; }
+    const name = m[1];
+    // `.on('event', cb)` — a string first argument means an engine/service subscription,
+    // not an ArkUI attribute callback.
+    const subscribes = name === "on" || /^(then|catch|finally)$/.test(name)
+      || /^\s*['"]/.test(code.slice(paren + 1, paren + 3));
+    regions.push({ a: paren, b: close, kind: name, family: subscribes ? "engine" : "ui" });
+    re.lastIndex = paren + 1;
+  }
+  return regions;
+}
+const inRegions = (rs, i) => rs.some((r) => i > r.a && i < r.b);
+
+// Callback bodies in `text` between `from` and `to`, covering BOTH spellings. `callbackRegions`
+// only sees dot-calls (`.onClick(() => …)`); a handler handed to a child component is written as
+// an object-literal property instead (`onTap: () => { … }`), which is not a dot-call at all. Both
+// must be excluded wherever "is this value read during render, or only on interaction?" is the
+// question — a field read inside a handler runs on tap, against the then-current value.
+function allCallbackRegions(text, from, to) {
+  const cbs = callbackRegions(text, from, to);
+  const arrowRe = /(\w+)\s*:\s*(?:async\s+)?\(([^)]*)\)\s*=>\s*/g;
+  arrowRe.lastIndex = from;
+  let a;
+  while ((a = arrowRe.exec(text)) && a.index < to) {
+    const after = arrowRe.lastIndex;
+    const brace = text.indexOf("{", after);
+    let bodyEnd;
+    if (brace >= 0 && brace <= after + 1) {
+      bodyEnd = matchPair(text, brace, "{", "}");
+    } else {
+      // Expression-bodied arrow: runs to the next top-level comma or the enclosing close.
+      let d = 0;
+      let i = after;
+      for (; i < to; i++) {
+        const ch = text[i];
+        if ("([{".includes(ch)) d++;
+        else if (")]}".includes(ch)) d--;
+        else if (ch === "," && d === 0) break;
+      }
+      bodyEnd = i;
+    }
+    if (bodyEnd > after) cbs.push({ a: after, b: bodyEnd, kind: a[1], family: "ui" });
+  }
+  return cbs;
+}
+
+// A method named on<Something> that nothing inside the struct ever calls as `this.onX(` is an
+// externally-invoked callback (registered with an engine / service). Writes inside it are as
+// deferred as writes inside an inline `.on(...)` closure — P3 must count them the same way.
+function externalCallbackMethods(code, start, end, methods) {
+  const out = [];
+  for (const m of methods) {
+    if (!/^on[A-Z]/.test(m.name)) continue;
+    const selfCall = new RegExp(`this\\.${m.name}\\s*\\(`, "g");
+    selfCall.lastIndex = start;
+    let called = false, c;
+    while ((c = selfCall.exec(code)) && c.index < end) {
+      if (c.index < m.bodyStart || c.index > m.bodyEnd) { called = true; break; }  // ignore recursion
+    }
+    if (!called) out.push({ a: m.bodyStart - 1, b: m.bodyEnd, kind: m.name });
+  }
+  return out;
+}
+
+// `TextArea({ text: this.body, controller: this.ctrl })` + `.onChange(v => this.body = v)` is the
+// framework's own content-sync idiom, not the P2 defect. Detect the member sitting in an object
+// literal that also carries `controller:`, and exempt it.
+function controllerBoundMembers(code, start, end) {
+  const bound = new Set();
+  const re = /\{[^{}]*\bcontroller\s*:[^{}]*\}/g;
+  re.lastIndex = start;
+  let m;
+  while ((m = re.exec(code)) && m.index < end) {
+    const rr = /this\.(\w+)/g;
+    let r;
+    while ((r = rr.exec(m[0]))) bound.add(r[1]);
+  }
+  return bound;
+}
+
+function checkFile(raw) {
+  const code = blankNonCode(raw);
+  const starts = lineStarts(raw);
+  const msgs = [];
+  const push = (idx, severity, rule, message) => {
+    const p = posOf(starts, idx);
+    msgs.push({ line: p.line, column: p.column, severity, message, rule: `state-propagation/${rule}` });
+  };
+
+  for (const st of findStructs(code)) {
+    // ---- P7: a `get` accessor declared directly in an @Component / @Entry struct.
+    //
+    // The ArkUI struct transform does not carry get accessors through. The declaration compiles
+    // and lints clean, then `this.thing` reads `undefined` at runtime: a Text renders empty, an
+    // `if (this.flag)` never takes its branch. Verified on shipped HAPs — decompiling ets/modules.abc
+    // shows @State accessor pairs (#keepSorted / #keepSorted^1), plain methods (#tagNameById) and
+    // static class methods all present in the function table, while every `private get` is absent
+    // and its name survives only in the property-name pool. In one archived build the string
+    // 'No due date', reachable only through such a getter, appears zero times in the whole binary
+    // while its sibling literal rendered from build() appears once.
+    //
+    // This check must run before the `members.size` guard below: a struct can declare a getter and
+    // no state at all. Precision is high — across ten real ArkUI trees exactly one struct getter
+    // exists, and it is the known defect the harness itself patches out via scaffold-info-bar.patch.
+    {
+      const getRe = /(?:^|[\s;{}])(?:(?:private|protected|public|readonly)\s+)*get\s+(\w+)\s*\(\s*\)/g;
+      getRe.lastIndex = st.start;
+      let g;
+      while ((g = getRe.exec(code)) && g.index < st.end) {
+        const name = g[1];
+        if (KEYWORD.has(name)) continue;
+        // Only a direct member of the struct body — not a getter inside a nested class or object.
+        let depth = 0;
+        for (let i = st.start; i < g.index; i++) {
+          const ch = code[i];
+          if (ch === "{") depth++;
+          else if (ch === "}") depth--;
+        }
+        if (depth !== 0) continue;
+        // Is it actually read? An unread getter is dead code, not a rendering defect.
+        const readRe = new RegExp(`this\\.${name}\\b(?!\\s*\\()`, "g");
+        const body = code.slice(st.start, st.end);
+        const isRead = readRe.test(body);
+        push(g.index, isRead ? "error" : "warn", "P7-struct-getter-erased",
+          `'get ${name}()' is declared in struct '${st.name}'. The ArkUI struct transform drops get ` +
+          `accessors, so ` + (isRead
+            ? `every \`this.${name}\` read resolves to undefined at runtime — text renders empty and ` +
+              `conditions never take their branch, with no compile or lint error. Convert it to a plain ` +
+              `method (\`private ${name}(): T { … }\` called as \`this.${name}()\`), or inline the ` +
+              `expression at the point of use.`
+            : `it would resolve to undefined if read. Convert it to a plain method or delete it.`));
+      }
+    }
+
+    // ---- P8: a CustomDialogController built as a FIELD INITIALISER, capturing state by value.
+    //
+    // A property initialiser runs once, when the struct is constructed. Any `this.<state>` in the
+    // builder's argument object is therefore evaluated at that instant and frozen — usually while
+    // the field still holds its declared default. Every later `open()` shows the dialog built from
+    // that stale snapshot, no matter how many times the state has changed since:
+    //
+    //   private tagDialog: CustomDialogController = new CustomDialogController({
+    //     builder: TagPicker({ initialSelectedIds: this.selectedTagIds })   // captured empty, forever
+    //   });
+    //
+    // Assigning inside a method instead (`this.tagDialog = new CustomDialogController({…})` right
+    // before `open()`) re-reads the state each time. Writes are exempt: a callback that sets
+    // `this.x = …` runs on interaction, not at construction, so only reads are a defect.
+    //
+    // Severity is warn, not error: the archived trees carry no CustomDialogController at all, so
+    // there is no false-positive measurement behind this shape — unlike P7, where nine clean trees
+    // plus one known defect justified blocking. Revisit once a run exercises it.
+    {
+      const ctlRe = /(\w+)\s*:\s*CustomDialogController\s*=\s*new\s+CustomDialogController\s*\(/g;
+      ctlRe.lastIndex = st.start;
+      let c;
+      while ((c = ctlRe.exec(code)) && c.index < st.end) {
+        const paren = code.indexOf("(", c.index + c[1].length);
+        const close = matchPair(code, paren, "(", ")");
+        if (close < 0) { ctlRe.lastIndex = paren + 1; continue; }
+        ctlRe.lastIndex = paren + 1;
+        const cbs = allCallbackRegions(code, paren, close);
+        const captured = new Set();
+        const rr = /this\.(\w+)\b(?!\s*\()/g;
+        rr.lastIndex = paren;
+        let r;
+        while ((r = rr.exec(code)) && r.index < close) {
+          if (inRegions(cbs, r.index)) continue;                 // runs on interaction, not now
+          // A write (`this.x = …`) is not a capture; only reads freeze a value.
+          const tail = code.slice(r.index + r[0].length, r.index + r[0].length + 3);
+          if (/^\s*=[^=]/.test(tail)) continue;
+          captured.add(r[1]);
+        }
+        if (!captured.size) continue;
+        push(c.index, "warn", "P8-dialog-controller-captures-state",
+          `'${c[1]}' is a CustomDialogController built in a field initialiser, and its builder reads ` +
+          `[${[...captured].map((n) => `this.${n}`).join(", ")}] as construction argument(s). A property ` +
+          `initialiser runs once, at struct construction, so those values are frozen at their declared ` +
+          `defaults — every open() re-shows the dialog built from that first snapshot, however often the ` +
+          `state has changed since. Build the controller in a method immediately before open() ` +
+          `(\`this.${c[1]} = new CustomDialogController({…}); this.${c[1]}.open();\`) so the current ` +
+          `values are read each time.`);
+      }
+    }
+
+    const members = findMembers(code, st.start, st.end);
+    if (!members.size) continue;
+    const methods = findMethods(code, st.start, st.end);
+    const cbRegions = callbackRegions(code, st.start, st.end);
+    const extCbRegions = externalCallbackMethods(code, st.start, st.end, methods);
+    // P3 liveness risk = engine subscriptions + engine-invoked named handlers. A UI attribute
+    // callback (.onClick) is excluded: a user tap always arrives, so state written there is not
+    // at risk of never being written.
+    const engineRegions = cbRegions.filter((r) => r.family === "engine").concat(extCbRegions);
+    const ctrlBound = controllerBoundMembers(code, st.start, st.end);
+
+    // State a method renders *transitively*. A ForEach item body is very often just
+    // `this.SomeBuilder(item)`, and the state that decides what the row looks like sits one or
+    // two calls deeper (`TagRow` → `isSelected()` → `this.selectedIds`). Scanning only the item
+    // body therefore misses the whole class where the key is an id and the changing value is
+    // reached through a helper — the defect P5 exists to catch.
+    const byName = new Map(methods.map((m) => [m.name, m]));
+    const transitiveState = (methodName, seen = new Set()) => {
+      const found = new Set();
+      if (seen.has(methodName)) return found;         // recursion guard
+      seen.add(methodName);
+      const mth = byName.get(methodName);
+      if (!mth) return found;
+      const body = code.slice(mth.bodyStart, mth.bodyEnd);
+      // Reads inside this method's own event handlers are not rendered values (same rule the
+      // direct scan below applies), so skip them.
+      const hRegions = callbackRegions(code, mth.bodyStart, mth.bodyEnd);
+      const rr = /this\.(\w+)\b/g;
+      let r;
+      while ((r = rr.exec(body))) {
+        const name = r[1];
+        const abs = mth.bodyStart + r.index;
+        if (inRegions(hRegions, abs)) continue;
+        if (members.has(name)) { if (!/^on[A-Z]/.test(name)) found.add(name); continue; }
+        // not a state field — if it is a method of this struct, follow it
+        if (byName.has(name)) for (const n of transitiveState(name, seen)) found.add(n);
+      }
+      return found;
+    };
+
+    // a bare `this.x` read of a state member ($$ / $ prefixed forms are the correct binding)
+    const stateRead = (expr) => {
+      const t = expr.trim();
+      if (/^\$/.test(t)) return null;
+      const m = /^this\.(\w+)$/.exec(t);
+      return m && members.has(m[1]) ? m[1] : null;
+    };
+
+    // ---- P1: @Builder receiving state by value
+    for (const mth of methods) {
+      if (!mth.isBuilder) continue;
+      const primIdx = mth.params
+        .map((p, i) => { const t = /:\s*([\w.<>\[\]]+)/.exec(p); return t && PRIMITIVE.test(t[1]) ? i : -1; })
+        .filter((i) => i >= 0);
+      if (!primIdx.length) continue;
+      const callRe = new RegExp(`this\\.${mth.name}\\s*\\(`, "g");
+      callRe.lastIndex = st.start;
+      let c;
+      while ((c = callRe.exec(code)) && c.index < st.end) {
+        const paren = code.indexOf("(", c.index);
+        const close = matchPair(code, paren, "(", ")");
+        if (close < 0) break;
+        const args = splitArgs(code.slice(paren + 1, close));
+        for (const i of primIdx) {
+          const name = args[i] ? stateRead(args[i]) : null;
+          if (!name) continue;
+          push(c.index, "error", "P1-builder-value-param",
+            `@Builder '${mth.name}' receives state '${name}' (@${members.get(name).decorator}) by value as arg ${i + 1}. ` +
+            `A by-value @Builder parameter does not subscribe, so the builder body never re-renders when '${name}' changes ` +
+            `— the value is stored but the screen keeps the old text. Pass $$this.${name}, read this.${name} inside the ` +
+            `builder, or split the row into @Component + @Prop/@Link.`);
+        }
+        callRe.lastIndex = close;
+      }
+    }
+
+    // ---- P2: controller setter vs on*Change writing the same member
+    const cbWrites = new Map();
+    for (const r of cbRegions) {
+      if (!/^on/.test(r.kind)) continue;
+      const seg = code.slice(r.a, r.b);
+      const wr = /this\.(\w+)\s*=(?!=)/g;
+      let w;
+      while ((w = wr.exec(seg))) if (members.has(w[1]) && !cbWrites.has(w[1])) cbWrites.set(w[1], r.a + w.index);
+    }
+    const CTRL = /this\.\w*[Cc]ontroller\s*\.\s*\w+\s*\(/;
+    for (const mth of methods) {
+      const seg = code.slice(mth.bodyStart, mth.bodyEnd);
+      if (!CTRL.test(seg)) continue;
+      const wr = /this\.(\w+)\s*=(?!=)/g;
+      let w;
+      while ((w = wr.exec(seg))) {
+        const abs = mth.bodyStart + w.index;
+        if (!members.has(w[1]) || inRegions(cbRegions, abs) || !cbWrites.has(w[1])) continue;
+        // `Comp({ text: this.body, controller: this.ctrl })` + `.onChange(v => this.body = v)`
+        // is the framework's own content-sync idiom, not the overwrite defect.
+        if (ctrlBound.has(w[1])) continue;
+        push(abs, "error", "P2-controller-vs-callback",
+          `'${w[1]}' is assigned here alongside a controller setter in '${mth.name}', and is also written by a framework ` +
+          `on*Change callback (line ${posOf(starts, cbWrites.get(w[1])).line}). The callback fires afterwards and overwrites ` +
+          `this value, so the next action reads the framework's offset, not yours. Typical symptom: the forward action passes ` +
+          `and the inverse action fails. Guard with a suppression flag, or hold a semantic anchor (line index / item id) ` +
+          `instead of a raw offset.`);
+      }
+    }
+
+    // ---- P3: a BOOLEAN control state written ONLY from engine event callbacks.
+    // Two deliberate narrowings, both learned from false positives on real code:
+    //   * post-await writes are NOT counted — "load then render" resolves on its own.
+    //   * only boolean members are considered — a data field (title, elapsed, list) legitimately
+    //     arrives from the engine; a control's on/off state must never depend on an event that
+    //     may never fire, because every test that drives that control dies at step 1.
+    for (const [name, info] of members) {
+      if (info.type !== "boolean") continue;
+      const wr = new RegExp(`this\\.${name}\\s*=(?!=)`, "g");
+      wr.lastIndex = st.start;
+      let w, total = 0, viaCallback = 0;
+      while ((w = wr.exec(code)) && w.index < st.end) {
+        total++;
+        if (inRegions(engineRegions, w.index)) viaCallback++;
+      }
+      if (total > 0 && viaCallback === total) {
+        push(info.idx, "warn", "P3-async-only-state",
+          `Boolean control state '${name}' (@${info.decorator}) is written only from engine event callbacks ` +
+          `(${total} site(s), no synchronous write). If the event never arrives — a player that never reaches ` +
+          `'playing', a session that never calls back — the control renders its initial value forever, and every ` +
+          `test that must first drive this control fails at step 1. Add a synchronous write path (optimistic ` +
+          `update + rollback on failure) and a timeout fallback state.`);
+      }
+    }
+
+    // ---- P5: ForEach keyGenerator omits the state its item renders
+    const feRe = /\b(Lazy)?ForEach\s*\(/g;
+    feRe.lastIndex = st.start;
+    let f;
+    while ((f = feRe.exec(code)) && f.index < st.end) {
+      const paren = code.indexOf("(", f.index);
+      const close = matchPair(code, paren, "(", ")");
+      if (close < 0) break;
+      feRe.lastIndex = paren + 1;
+      const args = splitArgs(code.slice(paren + 1, close));
+      const kind = f[1] ? "LazyForEach" : "ForEach";
+      const item = args[1] || "";
+      // Only state that flows into RENDERED content counts. A `this.x` read inside an event
+      // handler (`.onClick(() => this.x = '')`) or a gesture closure is not a per-item rendered
+      // value, and the key is under no obligation to include it — counting those was the single
+      // largest source of false positives on real code.
+      const itemAbs = code.indexOf(item, paren);
+      const handlerRegions = itemAbs >= 0 ? callbackRegions(code, itemAbs, itemAbs + item.length) : [];
+      const used = new Set();
+      const viaHelper = new Set();
+      const rr = /this\.(\w+)\b/g;
+      let r;
+      while ((r = rr.exec(item))) {
+        const name = r[1];
+        if (itemAbs >= 0 && inRegions(handlerRegions, itemAbs + r.index)) continue;
+        if (members.has(name)) {
+          if (/^on[A-Z]/.test(name)) continue;       // handlers are not rendered values
+          used.add(name);
+          continue;
+        }
+        // `this.SomeBuilder(item)` — follow the call and collect the state it renders.
+        if (byName.has(name)) {
+          for (const n of transitiveState(name)) { used.add(n); viaHelper.add(n); }
+        }
+      }
+      // ---- P6: a MUTABLE FIELD OF THE ITEM is handed to a child component as a construction
+      // argument while the key carries only the item's identity.
+      //
+      // This is P5's blind spot, and it is the more common shape. P5 follows `this.<state>`; here
+      // the changing value is `habit.todayValue` — a field of the loop variable, not struct state —
+      // so P5 never mentions it, and this check must run even when P5 found nothing:
+      //
+      //   ForEach(this.habits, (habit: HabitData) => {
+      //     NumberPanel({ todayValue: habit.todayValue })   // @Prop copy, taken once
+      //   }, (habit: HabitData) => `${habit.id}`)           // key cannot change when the field does
+      //
+      // Reassigning the array re-runs the loop, but a key that still matches lets ArkUI reuse the
+      // node, and a reused child does not re-evaluate its @Prop initialisers — the row keeps
+      // rendering the old value. Fixing only the *child's* inner key does not help: the parent row
+      // is reused first. Verified against an archived run where the candidate did exactly that
+      // (inner key rebuilt with the rendered value, P5 satisfied and silent) and the device test
+      // still read the stale seeded number.
+      if (args[2]) {
+        const itemParam = /^\s*\(?\s*([A-Za-z_$][\w$]*)/.exec(item);
+        const v = itemParam ? itemParam[1] : null;
+        const keyFields = v ? (args[2].match(new RegExp(`\\b${v}\\.(\\w+)`, "g")) || [])
+          .map((s) => s.split(".")[1]) : [];
+        // Identity-only key: it mentions the item, and every field it reads is an id.
+        const identityOnly = keyFields.length > 0 && keyFields.every((fd) => /^(id|key|uuid|guid)$/i.test(fd));
+        if (v && !KEYWORD.has(v) && identityOnly) {
+          const ctorRe = /\b([A-Z][\w$]*)\s*\(\s*\{/g;
+          const seen = new Set();
+          let c;
+          while ((c = ctorRe.exec(item))) {
+            const open = item.indexOf("{", c.index);
+            const shut = matchPair(item, open, "{", "}");
+            if (shut < 0) continue;
+            ctorRe.lastIndex = open + 1;
+            const argObj = item.slice(open + 1, shut);
+            // Fields read inside a callback are fine — a handler runs on tap, against the
+            // then-current item. Two spellings must both be excluded: an attribute callback
+            // (`.onClick(() => …)`, found by callbackRegions) and an object-literal property
+            // holding an arrow function (`onTap: () => { … }`), which is how handlers are passed
+            // into a child component and is NOT a dot-call, so callbackRegions cannot see it.
+            const cbs = allCallbackRegions(item, open, shut);
+            const passed = new Set();
+            const fr = new RegExp(`\\b${v}\\.(\\w+)`, "g");
+            let p;
+            while ((p = fr.exec(argObj))) {
+              if (inRegions(cbs, open + 1 + p.index)) continue;
+              if (/^(id|key|uuid|guid)$/i.test(p[1])) continue;        // identity is already in the key
+              passed.add(p[1]);
+            }
+            if (!passed.size) continue;
+            const sig = `${c[1]}:${[...passed].join(",")}`;
+            if (seen.has(sig)) continue;
+            seen.add(sig);
+            push(f.index, "warn", "P6-foreach-item-field-to-child",
+              `${kind} passes mutable item field(s) [${[...passed].map((x) => `${v}.${x}`).join(", ")}] into ` +
+              `'${c[1]}' as construction arguments, but its keyGenerator ` +
+              `\`${args[2].replace(/\s+/g, " ").slice(0, 54)}\` carries only the item's identity. When those fields ` +
+              `change, the key still matches, ArkUI reuses the row, and '${c[1]}' keeps the @Prop copy it was built ` +
+              `with — the old value stays on screen. Add the changing field (or a render version) to the key; ` +
+              `rebuilding a key *inside* '${c[1]}' does not help, because the row above it is reused first.`);
+          }
+        }
+      }
+
+      if (!used.size) continue;
+      // Severity stays `warn` deliberately. An identity-only key over state the struct writes
+      // looks like a certain defect, but measured against 20 archived runs it is not: the exact
+      // same shape ("selection indicator keyed by id") appears on specs that scored 100% —
+      // mihon-more-tab omits `currentTab` keyed by `tab.id`, readyou-accounts omits `accent`
+      // keyed by `s.id`, markor_002 omits `selectedNames` keyed by `entry.path` — and on specs
+      // that failed for exactly this reason (uhabits CheckmarkPanel omits `todayValue` keyed by
+      // `${dayIndex}`). Whether a reused node actually renders stale depends on how the value
+      // reaches the child (constructor argument vs read inline) and on whether anything drives
+      // the change, neither of which this scan can see. Promoting on the shape alone would have
+      // blocked 8 findings across 5 fully-passing specs. Use --all-error to force blocking.
+      if (!args[2]) {
+        push(f.index, "warn", "P5-foreach-key-omits-state",
+          `${kind} has no keyGenerator, but its item body renders state [${[...used].join(", ")}]. Without a key that ` +
+          `includes the changing value, items are not rebuilt when it changes.`);
+        continue;
+      }
+      const key = args[2];
+      const missing = [...used].filter((n) => !new RegExp(`\\b${n}\\b`).test(key));
+      if (missing.length === used.size) {
+        const indirect = missing.filter((n) => viaHelper.has(n));
+        const how = indirect.length
+          ? ` The value is reached indirectly — the item body calls a helper of this struct that reads ` +
+            `[${indirect.join(", ")}] — so the key looks complete at the call site while the row still depends on ` +
+            `changing state.`
+          : "";
+        push(f.index, "warn", "P5-foreach-key-omits-state",
+          `${kind} keyGenerator \`${key.replace(/\s+/g, " ").slice(0, 70)}\` omits every state value its item renders ` +
+          `[${missing.join(", ")}], so changing them does not rebuild the item.${how} Include the rendered value in the ` +
+          `key, or hold it as @State in the child and update it locally on the interaction (an @Prop copy is not ` +
+          `re-evaluated for a reused node).`);
+      }
+    }
+  }
+  return msgs;
+}
+
+// ---- cli
+function argOf(argv, flag) { const i = argv.indexOf(flag); return i >= 0 && argv[i + 1] ? argv[i + 1] : null; }
+const SKIP_DIR = new Set(["node_modules", "oh_modules", "build", ".git", ".idea", "dist"]);
+function walk(dir, acc = []) {
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (SKIP_DIR.has(e.name)) continue;
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) walk(p, acc);
+    else if (e.name.endsWith(".ets")) acc.push(p);
+  }
+  return acc;
+}
+
+const argv = process.argv.slice(2);
+const dirArg = argOf(argv, "--dir");
+const filesArg = argOf(argv, "--files");
+const outArg = argOf(argv, "--out");
+const allError = argv.includes("--all-error");
+
+let files = [];
+if (filesArg) files = filesArg.split(",").map((s) => s.trim()).filter(Boolean);
+else if (dirArg && fs.existsSync(dirArg)) files = fs.statSync(dirArg).isDirectory() ? walk(dirArg) : [dirArg];
+else if (!dirArg) { emit({ ok: false, error: "need --dir <project-or-dir> or --files a.ets,b.ets" }); process.exit(2); }
+
+const report = [];
+const byRule = {};
+let nError = 0, nWarn = 0;
+for (const f of files) {
+  let raw;
+  try { raw = fs.readFileSync(f, "utf8"); } catch { continue; }
+  const messages = checkFile(raw);
+  if (!messages.length) continue;
+  for (const m of messages) {
+    if (allError) m.severity = "error";
+    byRule[m.rule] = (byRule[m.rule] || 0) + 1;
+    if (m.severity === "error") nError++; else nWarn++;
+  }
+  report.push({ filePath: f, messages });
+}
+if (outArg) {
+  fs.mkdirSync(path.dirname(path.resolve(outArg)), { recursive: true });
+  fs.writeFileSync(outArg, JSON.stringify(report, null, 2), "utf8");
+}
+emit({
+  ok: nError === 0, files_scanned: files.length, files_with_findings: report.length,
+  error: nError, warn: nWarn, by_rule: byRule, report: outArg || null,
+});
+process.exit(nError > 0 ? 1 : 0);