agent-harness-kit 0.5.1 → 0.7.0

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

@@ -2,19 +2,36 @@
 //
 // Reads harness.config.json. For each domain, walks every .rs file under
 // the domain root (excluding target/, .git/, vendor/) and asserts no
-// `use crate::<layer>::...` import goes "backward" through the layer order.
+// `use` statement imports a layer that comes BEFORE the source layer.
 //
-// Layer assignment: a file's layer = first path segment after `<root>/`.
-// E.g. `src/repo/store.rs` belongs to the `repo` layer when
-// `domains[0].root == "src"`.
+// Two layouts are supported:
 //
-// 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.
+//   * Single-crate (default): a file's layer is the first path segment
+//     after `<root>/`. Intra-crate dependencies are written as
+//     `use crate::<layer>::...`.
+//
+//   * Workspace mode (`layerDirPattern` + `useIdentPattern` in
+//     `harness.config.json`): each layer is its own crate. The directory
+//     pattern maps layer name → folder (e.g. `unibot-{layer}` →
+//     `unibot-types/`), and the use-ident pattern maps layer name → the
+//     crate identifier in `use` statements (e.g. `unibot_{layer}` →
+//     `use unibot_types::`). Both default to `{layer}` and preserve the
+//     legacy single-crate behavior.
+//
+// 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)
@@ -67,7 +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.
+//
+// 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 + "/";
@@ -78,45 +312,84 @@ function layerOf(relPath, cfg) {
       stripped = relPath.slice(sepPrefix.length);
     else continue;
     const first = stripped.split(/[\/\\]/)[0];
-    if (d.layers.includes(first)) return { layer: first, domain: d };
+    const pattern = d.layerDirPattern || "{layer}";
+    const layer = resolveLayerFromDir(first, pattern, d.layers);
+    if (layer) return { layer, domain: d };
   }
   return null;
 }
 
-// Capture the first identifier after `use crate::` (or `pub use crate::`).
-const USE_CRATE_RE = /\b(?:pub\s+)?use\s+crate::([a-zA-Z_][a-zA-Z0-9_]*)/g;
+function resolveLayerFromDir(dirName, pattern, layers) {
+  if (pattern === "{layer}") {
+    return layers.includes(dirName) ? dirName : null;
+  }
+  const [prefix, suffix] = pattern.split("{layer}");
+  const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${pre}(.+?)${suf}$`);
+  const m = dirName.match(re);
+  if (m && layers.includes(m[1])) return m[1];
+  return null;
+}
 
-function parseUseCrate(line) {
-  return [...line.matchAll(USE_CRATE_RE)].map((m) => m[1]);
+function resolveLayerFromUseIdent(ident, useIdentPattern, layers) {
+  if (useIdentPattern === "{layer}") {
+    return layers.includes(ident) ? ident : null;
+  }
+  const [prefix, suffix] = useIdentPattern.split("{layer}");
+  const pre = (prefix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const suf = (suffix || "").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`^${pre}(.+?)${suf}$`);
+  const m = ident.match(re);
+  if (m && layers.includes(m[1])) return m[1];
+  return null;
 }
 
-// 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;
+// 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;
+
+// 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() {
@@ -133,31 +406,27 @@ function main() {
       const srcIdx = src.domain.layers.indexOf(src.layer);
 
       const content = readFileSync(file, "utf8");
-      const lines = content.split("\n");
-      for (let i = 0; i < lines.length; i++) {
-        const codeOnly = stripCommentsAndStrings(lines[i]);
-        const targets = 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();
@@ -195,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();
+}