@codyswann/lisa 3.13.1 → 3.13.2

package/scripts/check-conflict-markers.mjs

@@ -0,0 +1,312 @@
+#!/usr/bin/env node
+/**
+ * Deterministic gate against leftover merge-conflict markers in tracked files
+ * (issue #2552).
+ *
+ * PR #2548 committed literal `<<<<<<< HEAD` conflict blocks into six generated
+ * parity `SKILL.md` files and passed every gate on the way in:
+ *
+ *   - the parity push gate greps for the pin *value*, which was present inside
+ *     the conflict block, so it read as current;
+ *   - the test suite parses skill frontmatter, never the body;
+ *   - `🧩 Plugin artifacts match source` compares the generated copies against
+ *     `plugins/src`, and both sides were broken the *same* way, so they matched.
+ *
+ * Nothing in the loop read the bytes. This script does, and only that.
+ *
+ * Determinism guarantees (so the unit test is reproducible and CI is stable):
+ *   - zero third-party dependencies (Node built-ins only),
+ *   - no network access,
+ *   - no `Date` / `Math.random`,
+ *   - the file list comes from `git ls-files`, so the gate sees exactly what a
+ *     push would carry — an untracked scratch file can never block a push.
+ *
+ * Detection deliberately requires the COMPLETE ordered marker triple
+ * (`<<<<<<<` … `=======` … `>>>>>>>`), which is what git actually writes.
+ * Content between the start and the separator is ignored, so the diff3 base
+ * marker (`|||||||`) is accepted. A lone `<<<<<<<` line is NOT reported:
+ * documentation that quotes one side of a conflict is legitimate content, and a
+ * gate that fires on files it should not read is its own outage.
+ *
+ * CLI:
+ *   node scripts/check-conflict-markers.mjs [--root <dir>] [--json]
+ *
+ * Exit codes (mirroring the sibling parity scripts):
+ *   0 — no tracked file carries a conflict block.
+ *   1 — ≥1 tracked file carries a conflict block.
+ *   2 — operational/usage error: unknown flag, a flag missing its value,
+ *       `--root` absent or not a git repository, or git being unavailable.
+ *
+ * @module scripts/check-conflict-markers
+ */
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const REPO_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  ".."
+);
+
+/** `<<<<<<<` alone, or followed by whitespace and a label (`<<<<<<< HEAD`). */
+const START_RE = /^<{7}(?:[ \t].*)?$/;
+
+/** The separator git writes between the two sides: exactly seven `=`. */
+const SEPARATOR_RE = /^={7}$/;
+
+/** `>>>>>>>` alone, or followed by whitespace and a label. */
+const END_RE = /^>{7}(?:[ \t].*)?$/;
+
+/** Files larger than this are skipped — no source file is this big. */
+const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+/** Leading bytes probed for a NUL, which marks the file as binary. */
+const BINARY_PROBE_BYTES = 8000;
+
+/** Max bytes of `git ls-files` output (7k+ tracked paths is ~0.3 MB today). */
+const MAX_GIT_OUTPUT_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Usage error — thrown by `parseArgs` / `listTrackedFiles` for an invalid
+ * invocation so `main` can distinguish it (exit 2) from a finding (exit 1).
+ */
+export class UsageError extends Error {}
+
+/**
+ * Find every complete conflict block in `content`.
+ *
+ * A block is a `<<<<<<<` line, then a `=======` line, then a `>>>>>>>` line, in
+ * that order. A second `<<<<<<<` abandons any partial block and starts a new
+ * one, matching how git nests nothing and always re-opens.
+ *
+ * @param {string} content - full text of a file.
+ * @returns {{ startLine: number, separatorLine: number, endLine: number }[]}
+ *   one entry per complete block, with 1-based line numbers.
+ */
+export function findConflictBlocks(content) {
+  const lines = String(content).split(/\r?\n/);
+  const blocks = [];
+  let startLine = -1;
+  let separatorLine = -1;
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index];
+    if (START_RE.test(line)) {
+      startLine = index + 1;
+      separatorLine = -1;
+      continue;
+    }
+    if (startLine === -1) {
+      continue;
+    }
+    if (SEPARATOR_RE.test(line)) {
+      if (separatorLine === -1) {
+        separatorLine = index + 1;
+      }
+      continue;
+    }
+    if (END_RE.test(line)) {
+      if (separatorLine !== -1) {
+        blocks.push({ endLine: index + 1, separatorLine, startLine });
+      }
+      startLine = -1;
+      separatorLine = -1;
+    }
+  }
+  return blocks;
+}
+
+/**
+ * True iff `buffer` looks binary (a NUL byte in its leading bytes) — the same
+ * heuristic git uses to decide a blob is not text.
+ *
+ * @param {Buffer} buffer - the file contents.
+ * @returns {boolean} whether the file should be skipped as binary.
+ */
+function isBinary(buffer) {
+  return (
+    buffer.indexOf(0, 0) !== -1 && buffer.indexOf(0, 0) < BINARY_PROBE_BYTES
+  );
+}
+
+/**
+ * List every tracked file in `root`, relative to it. Throws `UsageError` when
+ * git is unavailable or `root` is not a repository.
+ *
+ * @param {string} root - the repository root.
+ * @returns {string[]} tracked paths, relative to `root`.
+ */
+function listTrackedFiles(root) {
+  let stdout;
+  try {
+    stdout = execFileSync("git", ["-C", root, "ls-files", "-z"], {
+      encoding: "utf8",
+      maxBuffer: MAX_GIT_OUTPUT_BYTES,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+  } catch (error) {
+    throw new UsageError(
+      `could not list tracked files in ${root}: ${error.message}`
+    );
+  }
+  return stdout.split("\0").filter(entry => entry !== "");
+}
+
+/**
+ * Scan one tracked file. Missing (staged-deleted), oversized, and binary files
+ * are skipped rather than reported.
+ *
+ * @param {string} root - the repository root.
+ * @param {string} file - a tracked path relative to `root`.
+ * @returns {{ file: string, blocks: ReadonlyArray<Record<string, number>> } | null}
+ *   the finding, or `null` when the file is clean or skipped.
+ */
+function scanFile(root, file) {
+  const absolute = path.join(root, file);
+  let stat;
+  try {
+    stat = fs.statSync(absolute);
+  } catch {
+    return null;
+  }
+  if (!stat.isFile() || stat.size > MAX_FILE_BYTES) {
+    return null;
+  }
+  let buffer;
+  try {
+    buffer = fs.readFileSync(absolute);
+  } catch {
+    return null;
+  }
+  if (isBinary(buffer)) {
+    return null;
+  }
+  const blocks = findConflictBlocks(buffer.toString("utf8"));
+  return blocks.length === 0 ? null : { blocks, file };
+}
+
+/**
+ * Assemble the machine-readable report.
+ *
+ * @param {ReadonlyArray<{ file: string, blocks: ReadonlyArray<Record<string, number>> }>} results
+ *   the conflicted files, sorted by path.
+ * @param {{ root: string, scanned: number }} opts - resolved options + scan size.
+ * @returns {Record<string, unknown>} the report object.
+ */
+export function buildReport(results, opts) {
+  return {
+    results,
+    root: opts.root,
+    schemaVersion: 1,
+    summary: {
+      clean: opts.scanned - results.length,
+      conflicted: results.length,
+      scanned: opts.scanned,
+    },
+  };
+}
+
+/**
+ * Render the human-readable report.
+ *
+ * @param {{ results: ReadonlyArray<{ file: string, blocks: ReadonlyArray<Record<string, number>> }>, summary: { scanned: number, conflicted: number } }} report
+ *   the report object.
+ * @returns {string} the rendered report.
+ */
+function humanReport(report) {
+  if (report.summary.conflicted === 0) {
+    return `✓ no leftover conflict markers in ${report.summary.scanned} tracked files`;
+  }
+  const lines = report.results.flatMap(result => [
+    `✗ ${result.file}`,
+    ...result.blocks.map(
+      block =>
+        `    - conflict block opens at line ${block.startLine}, separator at line ${block.separatorLine}, closes at line ${block.endLine}`
+    ),
+  ]);
+  return [
+    ...lines,
+    "",
+    `${report.summary.conflicted} of ${report.summary.scanned} tracked files carry leftover conflict markers`,
+  ].join("\n");
+}
+
+/**
+ * Parse argv into resolved options. Throws `UsageError` on a bad invocation.
+ *
+ * @param {readonly string[]} argv - arguments (without node/script prefix).
+ * @returns {{ root: string, json: boolean }} options.
+ */
+export function parseArgs(argv) {
+  let root = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") {
+      json = true;
+    } else if (arg === "--root") {
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) {
+        throw new UsageError("--root requires a value");
+      }
+      root = next;
+      i += 1;
+    } else {
+      throw new UsageError(`unknown argument: ${arg}`);
+    }
+  }
+  return { json, root: path.resolve(root ?? REPO_ROOT) };
+}
+
+/**
+ * Run the gate. Returns the process exit code (does not call `exit`).
+ *
+ * @param {readonly string[]} argv - arguments (without node/script prefix).
+ * @param {{ stdout?: { write(s: string): void }, stderr?: { write(s: string): void } }} [io]
+ *   injectable streams (defaults to process streams).
+ * @returns {number} the exit code (0 clean, 1 markers found, 2 usage error).
+ */
+export function main(argv, io = {}) {
+  const out = io.stdout ?? process.stdout;
+  const err = io.stderr ?? process.stderr;
+  let opts;
+  let files;
+  try {
+    opts = parseArgs(argv);
+    if (!fs.existsSync(opts.root) || !fs.statSync(opts.root).isDirectory()) {
+      throw new UsageError(`--root is not a directory: ${opts.root}`);
+    }
+    files = listTrackedFiles(opts.root);
+  } catch (error) {
+    err.write(`error: ${error.message}\n`);
+    return 2;
+  }
+  let results;
+  try {
+    results = files
+      .map(file => scanFile(opts.root, file))
+      .filter(result => result !== null)
+      .sort((a, b) => a.file.localeCompare(b.file));
+  } catch (error) {
+    err.write(`error: failed to scan tracked files: ${error.message}\n`);
+    return 2;
+  }
+  const report = buildReport(results, {
+    root: opts.root,
+    scanned: files.length,
+  });
+  out.write(
+    (opts.json ? JSON.stringify(report, null, 2) : humanReport(report)) + "\n"
+  );
+  return results.length === 0 ? 0 : 1;
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  // exitCode (not process.exit): when stdout is a pipe, writes are async and
+  // process.exit() truncates the report mid-flush.
+  process.exitCode = main(process.argv.slice(2));
+}

package/scripts/plugin-routing-validate.mjs

@@ -158,6 +158,14 @@ export function cacheMaxVersion(cacheRoot, name, marketplace) {
  * contract): a semver value must equal the cache max; `"unknown"` is valid only
  * when the cache has no semver anywhere.
  *
+ * A semver `upstreamVersion` with NO semver in the cache is deliberately not an
+ * error. It means THIS machine cannot see the plugin (fresh clone, CI runner,
+ * plugin uninstalled) — not that the artifact is wrong. `isVersionUnverifiable`
+ * reports that state separately so the caller can warn instead of blocking,
+ * mirroring how the drift detector treats `not-installed` (issue #2552). Every
+ * other gate — schema, routing, coverage, anti-patterns — still runs, so a
+ * cacheless machine validates strictly more than it used to.
+ *
  * @param {unknown} upstreamVersion - the artifact's `upstreamVersion`.
  * @param {string | null} cacheMax - resolved max semver, or null.
  * @returns {string[]} validation error messages (empty when valid).
@@ -174,9 +182,7 @@ function validateVersion(upstreamVersion, cacheMax) {
     ];
   }
   if (cacheMax === null) {
-    return [
-      `upstreamVersion ${upstreamVersion} but no semver in the cache to confirm`,
-    ];
+    return [];
   }
   if (compareSemver(upstreamVersion, cacheMax) !== 0) {
     return [`upstreamVersion ${upstreamVersion} != cache max ${cacheMax}`];
@@ -184,6 +190,19 @@ function validateVersion(upstreamVersion, cacheMax) {
   return [];
 }
 
+/**
+ * True iff the artifact pins a semver `upstreamVersion` that this machine has
+ * no cached copy to confirm against. A cache-visibility fact, not a contract
+ * violation — reported so the push gate can warn without blocking.
+ *
+ * @param {unknown} upstreamVersion - the artifact's `upstreamVersion`.
+ * @param {string | null} cacheMax - resolved max semver, or null.
+ * @returns {boolean} whether the version claim is unverifiable here.
+ */
+export function isVersionUnverifiable(upstreamVersion, cacheMax) {
+  return cacheMax === null && isValidSemver(upstreamVersion);
+}
+
 /**
  * Validate one component entry.
  *
@@ -430,14 +449,20 @@ function truncate(text) {
  * @param {string} routingDir - the routing directory.
  * @param {string} file - the artifact filename (`*.json`).
  * @param {string} cacheRoot - the installed-plugin cache root.
- * @returns {{ file: string, errors: string[] }} the per-file result.
+ * @returns {{ file: string, errors: string[], unverifiable: boolean }}
+ *   the per-file result. `unverifiable` means the version claim could not be
+ *   confirmed on this machine; it never blocks.
  */
 function validateFile(routingDir, file, cacheRoot) {
   let artifact;
   try {
     artifact = JSON.parse(fs.readFileSync(path.join(routingDir, file), "utf8"));
   } catch (error) {
-    return { errors: [`invalid JSON: ${error.message}`], file };
+    return {
+      errors: [`invalid JSON: ${error.message}`],
+      file,
+      unverifiable: false,
+    };
   }
   const hasIds =
     artifact !== null &&
@@ -455,13 +480,21 @@ function validateFile(routingDir, file, cacheRoot) {
     filename: file,
     mdExists,
   });
-  return { errors, file };
+  const upstreamVersion =
+    artifact !== null && typeof artifact === "object"
+      ? artifact.upstreamVersion
+      : undefined;
+  return {
+    errors,
+    file,
+    unverifiable: isVersionUnverifiable(upstreamVersion, cacheMax),
+  };
 }
 
 /**
  * Assemble the machine-readable report.
  *
- * @param {ReadonlyArray<{ file: string, errors: string[] }>} results - per-file results.
+ * @param {ReadonlyArray<{ file: string, errors: string[], unverifiable?: boolean }>} results - per-file results.
  * @param {{ cacheRoot: string, routingDir: string }} opts - resolved options.
  * @returns {Record<string, unknown>} the report object.
  */
@@ -475,6 +508,7 @@ export function buildReport(results, opts) {
     summary: {
       invalid,
       scanned: results.length,
+      unverifiable: results.filter(r => r.unverifiable === true).length,
       valid: results.length - invalid,
     },
   };
@@ -483,20 +517,27 @@ export function buildReport(results, opts) {
 /**
  * Render the human-readable report.
  *
- * @param {{ results: ReadonlyArray<{ file: string, errors: string[] }>, summary: { scanned: number, valid: number, invalid: number } }} report - report object.
+ * @param {{ results: ReadonlyArray<{ file: string, errors: string[], unverifiable?: boolean }>, summary: { scanned: number, valid: number, invalid: number, unverifiable: number } }} report - report object.
  * @returns {string} the rendered report.
  */
 function humanReport(report) {
-  const lines = report.results.map(r =>
-    r.errors.length === 0
-      ? `✓ ${r.file}`
-      : `✗ ${r.file}\n${r.errors.map(e => `    - ${e}`).join("\n")}`
-  );
+  const lines = report.results.map(r => {
+    if (r.errors.length > 0) {
+      return `✗ ${r.file}\n${r.errors.map(e => `    - ${e}`).join("\n")}`;
+    }
+    return r.unverifiable === true
+      ? `⚠ ${r.file} (version unverifiable: plugin not in this machine's cache)`
+      : `✓ ${r.file}`;
+  });
   const s = report.summary;
+  const unverifiable =
+    s.unverifiable > 0
+      ? `, ${s.unverifiable} unverifiable on this machine`
+      : "";
   return [
     ...lines,
     "",
-    `${s.valid}/${s.scanned} routing artifacts valid, ${s.invalid} invalid`,
+    `${s.valid}/${s.scanned} routing artifacts valid, ${s.invalid} invalid${unverifiable}`,
   ].join("\n");
 }