agent-harness-kit 0.6.0 → 0.8.0

package/src/templates/_adapter-rust/harness/structural-check.mjs.hbs

@@ -2,7 +2,7 @@
 //
 // Reads harness.config.json. For each domain, walks every .rs file under
 // the domain root (excluding target/, .git/, vendor/) and asserts no
-// import goes "backward" through the layer order.
+// `use` statement imports a layer that comes BEFORE the source layer.
 //
 // Two layouts are supported:
 //
@@ -18,13 +18,20 @@
 //     `use unibot_types::`). Both default to `{layer}` and preserve the
 //     legacy single-crate behavior.
 //
-// Why Node + regex (not a Cargo binary):
-//   - Avoids polluting the user's Cargo workspace with a check crate.
-//   - Node is already required to install the kit (npx).
-//   - Regex over `use <crate>::<X>` is sufficient — we never need full
-//     parse trees because the layer rule is a syntactic property.
-//   - `super::` and `self::` are scoped to the current module, which is
-//     by definition the same layer, so we ignore them.
+// Approach (changed in v0.7): a proper Rust lexer-lite. The v0.5 / v0.6
+// implementation ran regex over each line after stripping line comments
+// and double-quoted strings on a per-line basis, which produced false
+// positives on:
+//   - multi-line block comments containing `use crate::X`
+//   - raw strings (r"...", r#"..."#)
+//   - char literals confused with lifetimes
+// and produced false negatives on:
+//   - braced use lists: `use crate::{types, service}` (only first ident matched)
+//   - nested braces: `use crate::{a::{b, c}, d}`
+// The new approach: first pass blanks out every non-code character
+// (preserving newlines for line numbers); second pass walks the code-only
+// string from each `use`/`pub use` and recursively extracts every
+// candidate-layer identifier through brace expansions.
 //
 // Exit codes:
 //   0 — clean (or only baselined violations; or first-run baseline write)
@@ -77,13 +84,224 @@ function* walkRustFiles(root) {
   }
 }
 
-// Returns { layer, domain } or null.
+// stripNonCode — blank out every byte that's inside a comment, string, raw
+// string, or char literal. Newlines are preserved so line numbers stay
+// accurate; everything else inside a skip-zone becomes a single space.
+// This is the layer that catches false positives like
+//   /* use crate::service */    or   r#"use crate::service"#
+// which the prior per-line regex missed.
+export function stripNonCode(src) {
+  const n = src.length;
+  const out = new Array(n);
+  let i = 0;
+  while (i < n) {
+    const c = src[i];
+    const next = src[i + 1];
+    // Line comment
+    if (c === "/" && next === "/") {
+      while (i < n && src[i] !== "\n") {
+        out[i] = src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      continue;
+    }
+    // Block comment (Rust allows nesting)
+    if (c === "/" && next === "*") {
+      let depth = 1;
+      out[i] = " ";
+      out[i + 1] = " ";
+      i += 2;
+      while (i < n && depth > 0) {
+        if (src[i] === "/" && src[i + 1] === "*") {
+          depth++;
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+        } else if (src[i] === "*" && src[i + 1] === "/") {
+          depth--;
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+        } else {
+          out[i] = src[i] === "\n" ? "\n" : " ";
+          i++;
+        }
+      }
+      continue;
+    }
+    // Raw string: r"..." or r#..#"..."#..#  (also br"..." / br#"..."#)
+    if ((c === "r" || (c === "b" && next === "r")) && (i === 0 || !/[a-zA-Z0-9_]/.test(src[i - 1]))) {
+      let j = i;
+      if (src[j] === "b") {
+        out[j] = " ";
+        j++;
+      }
+      if (src[j] === "r") {
+        let k = j + 1;
+        let hashes = 0;
+        while (src[k] === "#") {
+          hashes++;
+          k++;
+        }
+        if (src[k] === '"') {
+          // Confirmed raw string. Blot from i to closing "#####"
+          out[j] = " ";
+          for (let q = j + 1; q <= k; q++) out[q] = " ";
+          let m = k + 1;
+          const closeStr = '"' + "#".repeat(hashes);
+          while (m < n) {
+            if (src.slice(m, m + closeStr.length) === closeStr) {
+              for (let q = m; q < m + closeStr.length; q++) out[q] = " ";
+              m += closeStr.length;
+              break;
+            }
+            out[m] = src[m] === "\n" ? "\n" : " ";
+            m++;
+          }
+          i = m;
+          continue;
+        }
+        // Not a raw string — `r` was just an identifier letter. Fall through.
+      }
+    }
+    // Regular string: "..." (handles \", \\, and embedded newlines)
+    if (c === '"') {
+      out[i] = " ";
+      i++;
+      while (i < n) {
+        if (src[i] === "\\" && i + 1 < n) {
+          out[i] = " ";
+          out[i + 1] = " ";
+          i += 2;
+          continue;
+        }
+        if (src[i] === '"') {
+          out[i] = " ";
+          i++;
+          break;
+        }
+        out[i] = src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      continue;
+    }
+    // Char literal vs lifetime. 'X' or '\X...' is a char; 'name (no closer)
+    // is a lifetime. Heuristic: find the closing `'` within the next 6
+    // chars; if present AND the body looks like a single char or short
+    // escape, treat as char. Otherwise leave as lifetime (raw identifier).
+    if (c === "'") {
+      // Look for closing '
+      let closeAt = -1;
+      for (let k = i + 1; k < Math.min(n, i + 8); k++) {
+        if (src[k] === "'") {
+          closeAt = k;
+          break;
+        }
+        if (src[k] === "\n") break; // lifetime can't span lines
+      }
+      const body = closeAt > -1 ? src.slice(i + 1, closeAt) : "";
+      // Char if body is length 1 (X) OR starts with `\` and is short.
+      const isChar =
+        closeAt > -1 &&
+        (body.length === 1 ||
+          (body.startsWith("\\") && body.length <= 6) ||
+          /^u\{[0-9a-fA-F]+\}$/.test(body));
+      if (isChar) {
+        for (let k = i; k <= closeAt; k++) out[k] = src[k] === "\n" ? "\n" : " ";
+        i = closeAt + 1;
+        continue;
+      }
+      // Lifetime: pass through as-is.
+      out[i] = c;
+      i++;
+      continue;
+    }
+    // Default: pass character through.
+    out[i] = c;
+    i++;
+  }
+  return out.join("");
+}
+
+// extractUseTargets — given the code-only text and the start index right
+// after `crate::` (single-crate mode) or after `use ` (workspace mode),
+// return every candidate layer identifier reachable through nested braces.
+// Stops at `;` at top level.
 //
-// Resolution:
-//   1. Strip the domain root prefix from the path.
-//   2. The first segment is the candidate layer directory.
-//   3. Match it against `layerDirPattern` (default `{layer}`) — if the
-//      pattern resolves a layer name, use it.
+// Examples (single-crate, called with start = position after "crate::"):
+//   "service;"                       → ["service"]
+//   "service::Foo;"                  → ["service"]
+//   "{a, b, c};"                     → ["a", "b", "c"]
+//   "{a::Foo, b::{x, y}};"           → ["a", "b"]
+//   "*;"                             → []
+//   "service::Foo as Bar;"           → ["service"]
+export function extractUseTargets(src, start) {
+  let i = start;
+  function skipWs() {
+    while (i < src.length && /\s/.test(src[i])) i++;
+  }
+  function readIdent() {
+    skipWs();
+    const m = src.slice(i).match(/^[a-zA-Z_][a-zA-Z0-9_]*/);
+    if (!m) return null;
+    i += m[0].length;
+    return m[0];
+  }
+  // Parse one "use path item" starting at i, return list of first-ident layers.
+  function parseItem() {
+    skipWs();
+    if (src[i] === "{") {
+      i++; // {
+      const layers = [];
+      while (i < src.length) {
+        skipWs();
+        if (src[i] === "}") {
+          i++;
+          break;
+        }
+        // Could be `self`, `super`, `crate`, an ident, or `*`.
+        const inner = parseItem();
+        layers.push(...inner);
+        // Skip ahead to next `,` or `}` at depth 0.
+        let depth = 0;
+        while (i < src.length) {
+          const c = src[i];
+          if (c === "{") depth++;
+          else if (c === "}") {
+            if (depth === 0) break;
+            depth--;
+          } else if (c === "," && depth === 0) {
+            i++;
+            break;
+          }
+          i++;
+        }
+      }
+      return layers;
+    }
+    if (src[i] === "*") {
+      i++;
+      return [];
+    }
+    const id = readIdent();
+    if (!id) return [];
+    // `self`, `super`, `crate` aren't layers; they may precede `::layer::...`.
+    if (id === "self" || id === "super" || id === "crate") {
+      skipWs();
+      if (src[i] === ":" && src[i + 1] === ":") {
+        i += 2;
+        return parseItem();
+      }
+      return [];
+    }
+    return [id];
+  }
+  return parseItem();
+}
+
+// Returns { layer, domain } or null. Resolves the source file's layer
+// (which dir bucket it lives in) by stripping the domain root prefix and
+// applying the `layerDirPattern`.
 function layerOf(relPath, cfg) {
   for (const d of cfg.domains) {
     const altPrefix = d.root + "/";
@@ -101,14 +319,10 @@ function layerOf(relPath, cfg) {
   return null;
 }
 
-// Given a directory name and a pattern like `unibot-{layer}`, return the
-// matching layer name from `layers` (or null). Handles the legacy
-// `{layer}` pattern as the identity case.
 function resolveLayerFromDir(dirName, pattern, layers) {
   if (pattern === "{layer}") {
     return layers.includes(dirName) ? dirName : null;
   }
-  // Escape regex specials in the surrounding pattern fragments.
   const [prefix, suffix] = pattern.split("{layer}");
   const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -118,35 +332,7 @@ function resolveLayerFromDir(dirName, pattern, layers) {
   return null;
 }
 
-// Capture the first identifier after `use ` (or `pub use ...`). The trailing
-// `::` is optional — `use demo_service;` is legal Rust even though most
-// real usage is `use demo_service::foo`.
-const USE_RE = /\b(?:pub\s+)?use\s+([a-zA-Z_][a-zA-Z0-9_]*)/g;
-
-function parseUseTargets(line, domain) {
-  const useIdent = domain.useIdentPattern || "crate";
-  const matches = [...line.matchAll(USE_RE)];
-  const layers = [];
-  for (const m of matches) {
-    const ident = m[1];
-    const layer = resolveLayerFromUseIdent(ident, useIdent, domain.layers);
-    if (layer) layers.push(layer);
-  }
-  return layers;
-}
-
-// Map a `use <ident>` to a layer. For single-crate mode this is
-// `use crate::<layer>::...` — `ident == "crate"` and the layer is the
-// SECOND segment. For workspace mode it is `use <crate>::...` where the
-// crate name itself encodes the layer.
 function resolveLayerFromUseIdent(ident, useIdentPattern, layers) {
-  if (useIdentPattern === "crate") {
-    // Legacy single-crate mode: only `use crate::...` matters; the layer
-    // is read from the captured ident only when ident === "crate" but
-    // the actual layer name is the segment AFTER `crate::` — see the
-    // separate `USE_CRATE_RE` path used by the caller for compatibility.
-    return null;
-  }
   if (useIdentPattern === "{layer}") {
     return layers.includes(ident) ? ident : null;
   }
@@ -159,40 +345,51 @@ function resolveLayerFromUseIdent(ident, useIdentPattern, layers) {
   return null;
 }
 
-// Backwards-compat: also keep the original single-crate matcher.
-const USE_CRATE_RE = /\b(?:pub\s+)?use\s+crate::([a-zA-Z_][a-zA-Z0-9_]*)/g;
-
-function parseUseCrate(line) {
-  return [...line.matchAll(USE_CRATE_RE)].map((m) => m[1]);
-}
+// USE_RE — matches `use ` and `pub use ` at any position. We scan the
+// code-only string for these tokens, then hand off to extractUseTargets
+// from the position right after the matching prefix.
+const USE_HEAD_RE = /\b(?:pub\s+)?use\s+/g;
 
-// Return only the code portion of a line — strip line comments (//) and
-// double-quoted string contents so the regex can't match `use crate::X`
-// inside text like `"use crate::service"` or `// use crate::service`.
-// Block comments and char literals (single quotes — also Rust lifetimes)
-// are not handled; collisions are rare and would only cause noise, not
-// missed real violations.
-function stripCommentsAndStrings(line) {
-  let result = "";
-  let inStr = false;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (inStr) {
-      if (c === "\\" && i + 1 < line.length) {
-        i++;
-        continue;
+// findUseLayers — top-level scanner. For each `use ... ;` in the code-only
+// string, return [{layer, line}].
+function findUseLayers(codeOnly, domain) {
+  const out = [];
+  const workspaceMode = !!domain.useIdentPattern;
+  USE_HEAD_RE.lastIndex = 0;
+  let m;
+  while ((m = USE_HEAD_RE.exec(codeOnly)) !== null) {
+    const after = m.index + m[0].length;
+    if (workspaceMode) {
+      // First ident after `use ` IS the crate; decode layer from it.
+      const id = codeOnly.slice(after).match(/^[a-zA-Z_][a-zA-Z0-9_]*/);
+      if (!id) continue;
+      const layer = resolveLayerFromUseIdent(id[0], domain.useIdentPattern, domain.layers);
+      if (layer) {
+        const line = codeOnly.slice(0, m.index).split("\n").length;
+        out.push({ layer, line });
       }
-      if (c === '"') inStr = false;
       continue;
     }
-    if (c === '"') {
-      inStr = true;
-      continue;
+    // Single-crate: skip optional `crate::` prefix.
+    let cursor = after;
+    while (cursor < codeOnly.length && /\s/.test(codeOnly[cursor])) cursor++;
+    const head = codeOnly.slice(cursor).match(/^[a-zA-Z_][a-zA-Z0-9_]*/);
+    if (!head) continue;
+    if (head[0] !== "crate") continue; // external crates aren't layer imports
+    cursor += head[0].length;
+    while (cursor < codeOnly.length && /\s/.test(codeOnly[cursor])) cursor++;
+    if (codeOnly[cursor] !== ":" || codeOnly[cursor + 1] !== ":") continue;
+    cursor += 2;
+    // Now cursor sits at the position right after `crate::`.
+    const layers = extractUseTargets(codeOnly, cursor);
+    const line = codeOnly.slice(0, m.index).split("\n").length;
+    for (const layer of layers) {
+      if (domain.layers.includes(layer)) {
+        out.push({ layer, line });
+      }
     }
-    if (c === "/" && i + 1 < line.length && line[i + 1] === "/") break;
-    result += c;
   }
-  return result;
+  return out;
 }
 
 function main() {
@@ -209,36 +406,27 @@ function main() {
       const srcIdx = src.domain.layers.indexOf(src.layer);
 
       const content = readFileSync(file, "utf8");
-      const lines = content.split("\n");
-      // Workspace mode uses `useIdentPattern` (e.g. "unibot_{layer}");
-      // single-crate mode keeps the historical `use crate::<layer>::` form.
-      const workspaceMode = !!src.domain.useIdentPattern;
-      for (let i = 0; i < lines.length; i++) {
-        const codeOnly = stripCommentsAndStrings(lines[i]);
-        const targets = workspaceMode
-          ? parseUseTargets(codeOnly, src.domain)
-          : parseUseCrate(codeOnly);
-        for (const tgtLayer of targets) {
-          if (!src.domain.layers.includes(tgtLayer)) continue;
-          const tgtIdx = src.domain.layers.indexOf(tgtLayer);
-          if (srcIdx < tgtIdx) {
-            const key = `${relPath}::${tgtLayer}`;
-            if (baselineSet.has(key)) continue;
-            violations.push({
-              file: relPath,
-              line: i + 1,
-              from: src.layer,
-              to: tgtLayer,
-              domain: src.domain.name,
-              key,
-            });
-          }
+      const code = stripNonCode(content);
+      for (const { layer: tgtLayer, line } of findUseLayers(code, src.domain)) {
+        const tgtIdx = src.domain.layers.indexOf(tgtLayer);
+        if (tgtIdx === -1) continue;
+        if (srcIdx < tgtIdx) {
+          const key = `${relPath}::${tgtLayer}`;
+          if (baselineSet.has(key)) continue;
+          violations.push({
+            file: relPath,
+            line,
+            from: src.layer,
+            to: tgtLayer,
+            domain: src.domain.name,
+            key,
+          });
         }
       }
     }
   }
 
-  // First-run baseline: no baseline file + violations → record + exit 0.
+  // First-run baseline.
   if (!baselineExists && violations.length > 0) {
     mkdirSync(join(repoRoot, ".harness"), { recursive: true });
     const keys = [...new Set(violations.map((v) => v.key))].sort();
@@ -276,4 +464,8 @@ function main() {
   process.exit(2);
 }
 
-main();
+// Only run when invoked directly; allow unit tests to import the helpers.
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) {
+  main();
+}