agent-harness-kit 0.6.0 → 0.8.0

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

@@ -0,0 +1,286 @@
+// harness/structural-check.mjs — forward-only layer enforcement for Kotlin.
+//
+// Reads harness.config.json. For each domain, walks every .kt/.kts file
+// under the domain root (excluding build/, .gradle/, out/, .git/) and
+// asserts no `import` statement pulls in a layer that comes BEFORE the
+// source layer.
+//
+// Kotlin's layer-from-import is read via `useIdentPattern` in
+// harness.config.json. Typical convention: `com.example.{layer}` so
+// `import com.example.types.Foo` resolves to layer "types". Default
+// pattern is `{layer}`, suitable for projects using top-level packages
+// matched to layer names.
+//
+// Skip-zones handled by stripNonCode():
+//   - line comment `// ... \n`
+//   - block comment `/* ... */` (Kotlin allows nesting)
+//   - regular string `"..."` (with `\"` and `\\` escapes)
+//   - raw / triple-quoted string `"""..."""`
+//
+// Exit codes:
+//   0 — clean (or only baselined violations; or first-run baseline write)
+//   2 — new violations found
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+} from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const repoRoot = process.cwd();
+const SKIP_DIRS = new Set([
+  ".git",
+  "build",
+  ".gradle",
+  "out",
+  ".idea",
+  "node_modules",
+  ".harness",
+]);
+
+function readConfig() {
+  return JSON.parse(readFileSync(join(repoRoot, "harness.config.json"), "utf8"));
+}
+function readBaseline() {
+  const path = join(repoRoot, ".harness/structural-baseline.json");
+  if (!existsSync(path)) return { exists: false, set: new Set() };
+  try {
+    const arr = JSON.parse(readFileSync(path, "utf8"));
+    return { exists: true, set: new Set(Array.isArray(arr) ? arr : []) };
+  } catch {
+    return { exists: true, set: new Set() };
+  }
+}
+
+function* walkKotlinFiles(root) {
+  if (!existsSync(root)) return;
+  for (const ent of readdirSync(root, { withFileTypes: true })) {
+    if (SKIP_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+    const full = join(root, ent.name);
+    if (ent.isDirectory()) yield* walkKotlinFiles(full);
+    else if (ent.isFile() && (ent.name.endsWith(".kt") || ent.name.endsWith(".kts"))) {
+      yield full;
+    }
+  }
+}
+
+// stripNonCode — blank out comments + strings, preserve newlines.
+// Block comments nest in Kotlin. Triple-quoted strings span lines and
+// don't process escapes (raw strings).
+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];
+    if (c === "/" && next === "/") {
+      while (i < n && src[i] !== "\n") {
+        out[i] = src[i] === "\n" ? "\n" : " ";
+        i++;
+      }
+      continue;
+    }
+    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;
+    }
+    // Triple-quoted raw string
+    if (c === '"' && next === '"' && src[i + 2] === '"') {
+      out[i] = out[i + 1] = out[i + 2] = " ";
+      let m = i + 3;
+      while (m < n) {
+        if (src[m] === '"' && src[m + 1] === '"' && src[m + 2] === '"') {
+          out[m] = out[m + 1] = out[m + 2] = " ";
+          m += 3;
+          break;
+        }
+        out[m] = src[m] === "\n" ? "\n" : " ";
+        m++;
+      }
+      i = m;
+      continue;
+    }
+    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;
+    }
+    out[i] = c;
+    i++;
+  }
+  return out.join("");
+}
+
+function layerOf(relPath, cfg) {
+  for (const d of cfg.domains) {
+    const altPrefix = d.root + "/";
+    const sepPrefix = d.root + sep;
+    let stripped;
+    if (relPath.startsWith(altPrefix)) stripped = relPath.slice(altPrefix.length);
+    else if (relPath.startsWith(sepPrefix)) stripped = relPath.slice(sepPrefix.length);
+    else continue;
+    const first = stripped.split(/[\/\\]/)[0];
+    const pattern = d.layerDirPattern || "{layer}";
+    const layer = resolveFromPattern(first, pattern, d.layers);
+    if (layer) return { layer, domain: d };
+  }
+  return null;
+}
+
+function resolveFromPattern(ident, pattern, layers) {
+  if (pattern === "{layer}") return layers.includes(ident) ? ident : 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 = ident.match(re);
+  if (m && layers.includes(m[1])) return m[1];
+  return null;
+}
+
+// `import com.example.layer.Foo` — extract the full dotted path (incl. `.*`),
+// then run resolveFromPattern on each segment.
+const IMPORT_RE = /\bimport\s+([A-Za-z_][\w.]*?)(?:\.\*)?\s*(?:as\s+\w+)?\s*[;\n\r]/g;
+
+function findImportLayers(code, domain) {
+  const out = [];
+  const ident = domain.useIdentPattern || "{layer}";
+  IMPORT_RE.lastIndex = 0;
+  let m;
+  while ((m = IMPORT_RE.exec(code)) !== null) {
+    const path = m[1];
+    const segments = path.split(".");
+    // Try matching from the most-specific (full path) down to single segments
+    // — useful when the pattern is e.g. `com.example.{layer}` and we need
+    // to match against the prefix-stripped segment.
+    let layer = null;
+    if (ident.includes("{layer}")) {
+      // Walk prefix lengths: try full match against pattern across the full
+      // dotted path, then progressively shorter.
+      // For pattern `com.example.{layer}`, candidates: full path "com.example.types",
+      // then "com.example", "com", and segments themselves.
+      const candidates = [];
+      for (let i = 1; i <= segments.length; i++) {
+        candidates.push(segments.slice(0, i).join("."));
+      }
+      for (const c of candidates) {
+        const found = resolveFromPattern(c, ident, domain.layers);
+        if (found) {
+          layer = found;
+          break;
+        }
+      }
+      // Fall back: per-segment match
+      if (!layer) {
+        for (const s of segments) {
+          const found = resolveFromPattern(s, "{layer}", domain.layers);
+          if (found) {
+            layer = found;
+            break;
+          }
+        }
+      }
+    }
+    if (layer) {
+      const line = code.slice(0, m.index).split("\n").length;
+      out.push({ layer, line });
+    }
+  }
+  return out;
+}
+
+function main() {
+  const cfg = readConfig();
+  const { exists: baselineExists, set: baselineSet } = readBaseline();
+  const violations = [];
+  for (const d of cfg.domains) {
+    const rootDir = join(repoRoot, d.root);
+    for (const file of walkKotlinFiles(rootDir)) {
+      const relPath = relative(repoRoot, file);
+      const src = layerOf(relPath, cfg);
+      if (!src) continue;
+      const srcIdx = src.domain.layers.indexOf(src.layer);
+      const content = readFileSync(file, "utf8");
+      const code = stripNonCode(content);
+      for (const { layer: tgtLayer, line } of findImportLayers(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,
+          });
+        }
+      }
+    }
+  }
+  if (!baselineExists && violations.length > 0) {
+    mkdirSync(join(repoRoot, ".harness"), { recursive: true });
+    const keys = [...new Set(violations.map((v) => v.key))].sort();
+    writeFileSync(
+      join(repoRoot, ".harness/structural-baseline.json"),
+      JSON.stringify(keys, null, 2) + "\n",
+    );
+    console.log(`✓ structural test: baselined ${keys.length} existing violation(s).`);
+    process.exit(0);
+  }
+  if (violations.length === 0) {
+    console.log("✓ structural test passed");
+    process.exit(0);
+  }
+  for (const v of violations) {
+    console.error(`✖ ${v.file}:${v.line}  layer=${v.from} → ${v.to}  (must be forward-only)`);
+  }
+  console.error(`\n${violations.length} new layer violation(s). Fix the import direction.`);
+  if (cfg.domains.length > 0) {
+    console.error(`Layer order for domain "${cfg.domains[0].name}": ${cfg.domains[0].layers.join(" → ")}`);
+  }
+  process.exit(2);
+}
+
+const isMain = import.meta.url === `file://${process.argv[1]}`;
+if (isMain) main();