skillrepo 4.9.2 → 4.10.0

package/src/test/lib/foreign-content.test.mjs

@@ -0,0 +1,522 @@
+/**
+ * Unit tests for src/lib/foreign-content.mjs (#2361).
+ *
+ * The sync-time governance scan: directories inside managed placement
+ * roots that the `.last-sync` manifest has no record of are FOREIGN and
+ * get surfaced (never touched). Also covers the privacy seam H7's
+ * receipts will consume (counts/category only, never names) and the
+ * gitignored-declaration probe (D6).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir, platform } from "node:os";
+import { execFileSync } from "node:child_process";
+
+import {
+  scanForeignContent,
+  formatForeignWarnings,
+  receiptViolationSummary,
+  checkDeclarationGitignored,
+  formatDeclarationIgnoredWarning,
+  readGovernanceSeen,
+  writeGovernanceSeen,
+  commitGovernanceSeen,
+  selectNewFindings,
+  normalizeStateKey,
+  UNMANAGED_CONTENT_CATEGORY,
+} from "../../lib/foreign-content.mjs";
+import { SKILLSET_DECLARATION_FILE } from "../../lib/constants.mjs";
+
+let originalCwd;
+let tempDir;
+
+beforeEach(() => {
+  originalCwd = process.cwd;
+  tempDir = mkdtempSync(join(tmpdir(), "cli-foreign-"));
+  process.cwd = () => tempDir;
+});
+
+afterEach(() => {
+  process.cwd = originalCwd;
+  rmSync(tempDir, { recursive: true, force: true });
+});
+
+/** Seed a skill-shaped directory under a project root. */
+function seedDir(root, name) {
+  const dir = join(tempDir, root, name);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, "SKILL.md"), `---\nname: ${name}\n---\n`);
+}
+
+const MANAGED = {
+  "alice/managed-one": { version: "1.0.0" },
+  "alice/managed-two": { version: "2.0.0" },
+};
+
+describe("scanForeignContent — classification", () => {
+  it("returns empty results when roots do not exist", () => {
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 0);
+    assert.equal(scan.roots.length, 1);
+    assert.deepEqual(scan.roots[0].foreignDirs, []);
+  });
+
+  it("classifies a manifest-less directory as foreign", () => {
+    seedDir(".claude/skills", "hand-rolled");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 1);
+    assert.deepEqual(scan.roots[0].foreignDirs, ["hand-rolled"]);
+  });
+
+  it("does NOT classify manifest-listed directories as foreign", () => {
+    seedDir(".claude/skills", "managed-one");
+    seedDir(".claude/skills", "managed-two");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 0);
+  });
+
+  it("mixed root — only the unmanaged dirs are foreign, sorted", () => {
+    seedDir(".claude/skills", "managed-one");
+    seedDir(".claude/skills", "zeta");
+    seedDir(".claude/skills", "alpha");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.deepEqual(scan.roots[0].foreignDirs, ["alpha", "zeta"]);
+    assert.equal(scan.foreignCount, 2);
+  });
+
+  it("skips .tmp/.old crashed-write artifacts and loose files", () => {
+    seedDir(".claude/skills", "ghost.tmp");
+    seedDir(".claude/skills", "ghost.old");
+    writeFileSync(join(tempDir, ".claude", "skills", "stray.md"), "x");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 0);
+  });
+
+  it("skips symlinked directories", { skip: platform() === "win32" }, () => {
+    seedDir(".claude/skills", "managed-one");
+    symlinkSync(
+      join(tempDir, ".claude", "skills", "managed-one"),
+      join(tempDir, ".claude", "skills", "linked"),
+      "dir",
+    );
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 0);
+  });
+
+  it("scans each unique target root once across cohort vendors", () => {
+    seedDir(".agents/skills", "rogue");
+    const scan = scanForeignContent({
+      vendors: ["cursor", "gemini", "codex"],
+      managedSkills: MANAGED,
+    });
+    // Three cohort vendors share agentsProject — one root, one finding.
+    assert.equal(scan.roots.length, 1);
+    assert.equal(scan.foreignCount, 1);
+    assert.deepEqual(scan.roots[0].foreignDirs, ["rogue"]);
+  });
+
+  it("scans both roots for claude + cohort vendor sets", () => {
+    seedDir(".claude/skills", "rogue-claude");
+    seedDir(".agents/skills", "rogue-agents");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode", "cursor"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.roots.length, 2);
+    assert.equal(scan.foreignCount, 2);
+  });
+
+  it("treats an empty/absent manifest as everything-foreign (nothing is CLI-written)", () => {
+    seedDir(".claude/skills", "anything");
+    for (const managedSkills of [null, undefined, {}]) {
+      const scan = scanForeignContent({ vendors: ["claudeCode"], managedSkills });
+      assert.equal(scan.foreignCount, 1, `managedSkills=${managedSkills}`);
+    }
+  });
+
+  it("declines to scan on an invalid vendor set instead of throwing", () => {
+    const scan = scanForeignContent({
+      vendors: ["not-a-vendor"],
+      managedSkills: MANAGED,
+    });
+    assert.equal(scan.foreignCount, 0);
+    assert.deepEqual(scan.roots, []);
+  });
+
+  it("ignores malformed manifest keys without crashing", () => {
+    seedDir(".claude/skills", "no-slash-name");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: { "no-slash-name": { version: "1.0.0" } },
+    });
+    // A key with no `/` cannot claim a dir — the dir stays foreign.
+    assert.equal(scan.foreignCount, 1);
+  });
+});
+
+describe("formatForeignWarnings", () => {
+  it("emits one sentence-case line per foreign dir naming the path", () => {
+    seedDir(".claude/skills", "hand-rolled");
+    seedDir(".claude/skills", "second");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    const lines = formatForeignWarnings(scan);
+    assert.equal(lines.length, 2);
+    assert.match(lines[0], /\.claude\/skills\/hand-rolled\//);
+    assert.match(lines[1], /\.claude\/skills\/second\//);
+    for (const line of lines) {
+      assert.ok(!line.includes("!"), "copy rules: no exclamation marks");
+      assert.match(line, /^ {2}warning: /);
+    }
+  });
+
+  it("emits nothing for a clean scan", () => {
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    assert.deepEqual(formatForeignWarnings(scan), []);
+  });
+});
+
+describe("receiptViolationSummary — the H7/#2111 privacy seam", () => {
+  it("carries category and count ONLY — never names", () => {
+    seedDir(".claude/skills", "secret-internal-tool");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    const summary = receiptViolationSummary(scan);
+    assert.deepEqual(summary, {
+      category: UNMANAGED_CONTENT_CATEGORY,
+      count: 1,
+    });
+    // Load-bearing privacy assertion: serializing the upstream shape
+    // must not leak the foreign dir's name.
+    assert.ok(!JSON.stringify(summary).includes("secret-internal-tool"));
+  });
+
+  it("tolerates a null scan", () => {
+    assert.deepEqual(receiptViolationSummary(null), {
+      category: UNMANAGED_CONTENT_CATEGORY,
+      count: 0,
+    });
+  });
+});
+
+describe("checkDeclarationGitignored — D6 out-of-band declaration probe", () => {
+  function git(args, cwd) {
+    execFileSync("git", args, { cwd, stdio: "ignore" });
+  }
+
+  it("reports absent when no declaration file exists", () => {
+    const result = checkDeclarationGitignored({ cwd: tempDir });
+    assert.deepEqual(result, { present: false, ignored: false });
+  });
+
+  it("reports present + not ignored outside a git work tree", () => {
+    writeFileSync(join(tempDir, SKILLSET_DECLARATION_FILE), "{}\n");
+    const result = checkDeclarationGitignored({ cwd: tempDir });
+    assert.equal(result.present, true);
+    assert.equal(result.ignored, false);
+  });
+
+  it("reports ignored when the declaration is gitignored in a real repo", () => {
+    git(["init", "-q"], tempDir);
+    writeFileSync(join(tempDir, SKILLSET_DECLARATION_FILE), "{}\n");
+    writeFileSync(join(tempDir, ".gitignore"), `${SKILLSET_DECLARATION_FILE}\n`);
+    const result = checkDeclarationGitignored({ cwd: tempDir });
+    assert.deepEqual(result, { present: true, ignored: true });
+  });
+
+  it("reports not ignored for a committed-style declaration in a real repo", () => {
+    git(["init", "-q"], tempDir);
+    writeFileSync(join(tempDir, SKILLSET_DECLARATION_FILE), "{}\n");
+    const result = checkDeclarationGitignored({ cwd: tempDir });
+    assert.deepEqual(result, { present: true, ignored: false });
+  });
+
+  it("warning line is sentence case, names the file, no exclamation marks", () => {
+    const line = formatDeclarationIgnoredWarning();
+    assert.match(line, new RegExp(SKILLSET_DECLARATION_FILE.replace(".", "\\.")));
+    assert.ok(!line.includes("!"));
+    assert.match(line, /^ {2}warning: /);
+  });
+});
+
+describe("warn-on-new state (#2361 owner directive)", () => {
+  it("warning copy carries the remediation (why + what to do)", () => {
+    seedDir(".claude/skills", "hand-rolled");
+    const scan = scanForeignContent({
+      vendors: ["claudeCode"],
+      managedSkills: MANAGED,
+    });
+    const [line] = formatForeignWarnings(scan);
+    assert.match(line, /not from your library/);
+    assert.match(line, /skillrepo push \.claude\/skills\/hand-rolled/);
+    assert.match(line, /or remove the directory/);
+  });
+
+it("selectNewFindings returns only unseen dirs (pure selection)", () => {
+    const scan = {
+      roots: [
+        { target: "claudeProject", root: "/abs/p/.claude/skills", displayRoot: ".claude/skills/", foreignDirs: ["a", "b"] },
+      ],
+      foreignCount: 2,
+    };
+    const seen = { schemaVersion: 1, roots: { "/abs/p/.claude/skills": ["a"] }, declarations: {} };
+    const newScan = selectNewFindings(scan, seen);
+    assert.deepEqual(newScan.roots[0].foreignDirs, ["b"]);
+    assert.equal(newScan.foreignCount, 1);
+  });
+});
+
+describe("readGovernanceSeen / writeGovernanceSeen", () => {
+  let homeSnapshot;
+
+  beforeEach(async () => {
+    const { captureHome, setSandboxHome } = await import("../helpers/sandbox-home.mjs");
+    homeSnapshot = captureHome();
+    setSandboxHome(tempDir);
+  });
+
+  afterEach(async () => {
+    const { restoreHome } = await import("../helpers/sandbox-home.mjs");
+    restoreHome(homeSnapshot);
+  });
+
+  it("round-trips state", () => {
+    const state = {
+      schemaVersion: 1,
+      roots: { "/p/.claude/skills": ["a"] },
+      declarations: { "/p": true },
+    };
+    writeGovernanceSeen(state);
+    assert.deepEqual(readGovernanceSeen(), state);
+  });
+
+  it("missing file reads as empty state", () => {
+    assert.deepEqual(readGovernanceSeen(), {
+      schemaVersion: 1,
+      roots: {},
+      declarations: {},
+    });
+  });
+
+  it("corrupt file reads as empty state (warn-everything is the safe direction)", async () => {
+    const { globalGovernanceSeenPath } = await import("../../lib/paths.mjs");
+    mkdirSync(join(tempDir, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(globalGovernanceSeenPath(), "{not json");
+    assert.deepEqual(readGovernanceSeen(), {
+      schemaVersion: 1,
+      roots: {},
+      declarations: {},
+    });
+  });
+
+  it("unknown schemaVersion reads as empty state", async () => {
+    const { globalGovernanceSeenPath } = await import("../../lib/paths.mjs");
+    mkdirSync(join(tempDir, ".claude", "skillrepo"), { recursive: true });
+    writeFileSync(
+      globalGovernanceSeenPath(),
+      JSON.stringify({ schemaVersion: 99, roots: { x: ["y"] } }),
+    );
+    assert.deepEqual(readGovernanceSeen().roots, {});
+  });
+});
+
+
+describe("warning output safety (#2361 prod-readiness)", () => {
+  it(
+    "escapes control characters in on-disk directory names",
+    { skip: platform() === "win32" },
+    () => {
+      // A cloned repo can carry any byte except NUL and "/" in a dir
+      // name - including ESC, the opener of terminal escape sequences.
+      const evil = "evil\u001b]0;pwned\u0007";
+      seedDir(".claude/skills", evil);
+      const scan = scanForeignContent({
+        vendors: ["claudeCode"],
+        managedSkills: MANAGED,
+      });
+      assert.equal(scan.foreignCount, 1);
+      const [line] = formatForeignWarnings(scan);
+      assert.ok(!line.includes("\u001b"), "raw ESC must never reach the terminal");
+      assert.ok(!line.includes("\u0007"), "raw BEL must never reach the terminal");
+      assert.ok(
+        line.includes("\\u001b"),
+        "control chars render as visible escapes",
+      );
+    },
+  );
+
+  it("global-scope findings print a runnable absolute push path (no tilde)", async () => {
+    const { captureHome, setSandboxHome, restoreHome } = await import(
+      "../helpers/sandbox-home.mjs"
+    );
+    const snapshot = captureHome();
+    setSandboxHome(tempDir);
+    try {
+      const dir = join(tempDir, ".claude", "skills", "rogue-global");
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(join(dir, "SKILL.md"), "---\nname: rogue-global\n---\n");
+      const scan = scanForeignContent({
+        vendors: ["claudeCode"],
+        global: true,
+        managedSkills: MANAGED,
+      });
+      assert.equal(scan.foreignCount, 1);
+      const [line] = formatForeignWarnings(scan);
+      // Human-readable sentence keeps the tilde display path...
+      assert.match(line, /~\/\.claude\/skills\/rogue-global\//);
+      // ...but the copy-pasteable command must be absolute: quotes stop
+      // shell tilde expansion and Windows cmd never expands "~".
+      assert.ok(
+        !/push ~/.test(line),
+        "the push command must not contain a tilde path",
+      );
+      // The command path is the NORMALIZED (realpath) root — on macOS
+      // the tmpdir's /var symlink resolves to /private/var, and a
+      // realpath'd absolute path is exactly as runnable.
+      assert.ok(
+        line.includes(
+          `push ${join(normalizeStateKey(join(tempDir, ".claude", "skills")), "rogue-global")}`,
+        ),
+        "the push command uses the absolute (normalized) path",
+      );
+    } finally {
+      restoreHome(snapshot);
+    }
+  });
+});
+
+describe("commitGovernanceSeen — narrow merge (prod-readiness High fix)", () => {
+  let homeSnapshot;
+
+  beforeEach(async () => {
+    const { captureHome, setSandboxHome } = await import("../helpers/sandbox-home.mjs");
+    homeSnapshot = captureHome();
+    setSandboxHome(tempDir);
+  });
+
+  afterEach(async () => {
+    const { restoreHome } = await import("../helpers/sandbox-home.mjs");
+    restoreHome(homeSnapshot);
+  });
+
+  const ROOT = "/repo/.claude/skills";
+  function scanWith(dirs, root = ROOT) {
+    return {
+      roots: [{ target: "claudeProject", root, displayRoot: ".claude/skills/", foreignDirs: dirs }],
+      foreignCount: dirs.length,
+    };
+  }
+
+  it("replaces (not merges) the scanned root, pruning removed dirs", () => {
+    commitGovernanceSeen({ scan: scanWith(["gone", "stays"]), repoKey: "/repo", declarationIgnored: false });
+    commitGovernanceSeen({ scan: scanWith(["stays"]), repoKey: "/repo", declarationIgnored: false });
+    assert.deepEqual(readGovernanceSeen().roots[ROOT], ["stays"]);
+    // Reappearance is a fresh finding again.
+    const newScan = selectNewFindings(scanWith(["gone", "stays"]), readGovernanceSeen());
+    assert.deepEqual(newScan.roots[0].foreignDirs, ["gone"]);
+  });
+
+  it("a clean root deletes its key", () => {
+    commitGovernanceSeen({ scan: scanWith(["x"]), repoKey: "/repo", declarationIgnored: false });
+    commitGovernanceSeen({ scan: scanWith([]), repoKey: "/repo", declarationIgnored: false });
+    assert.ok(!(ROOT in readGovernanceSeen().roots));
+  });
+
+  it("preserves a CONCURRENT writer's keys instead of restoring a stale snapshot", () => {
+    // This sync's scan happened; before its commit, ANOTHER process
+    // commits its own repo's state. The narrow merge must keep that
+    // other-repo entry — a full-object overwrite from this sync's
+    // earlier snapshot would silently drop it (the architect-traced
+    // suppressed-re-warn bug).
+    const otherRoot = "/other/.claude/skills";
+    writeGovernanceSeen({
+      schemaVersion: 1,
+      roots: { [otherRoot]: ["their-finding"] },
+      declarations: { "/other": true },
+    });
+    commitGovernanceSeen({ scan: scanWith(["mine"]), repoKey: "/repo", declarationIgnored: true });
+    const state = readGovernanceSeen();
+    assert.deepEqual(state.roots[otherRoot], ["their-finding"], "other repo's roots survive");
+    assert.equal(state.declarations["/other"], true, "other repo's declaration flag survives");
+    assert.deepEqual(state.roots[ROOT], ["mine"]);
+    assert.equal(state.declarations["/repo"], true);
+  });
+
+  it("clears this repo's declaration flag when no longer gitignored", () => {
+    commitGovernanceSeen({ scan: scanWith([]), repoKey: "/repo", declarationIgnored: true });
+    assert.equal(readGovernanceSeen().declarations["/repo"], true);
+    commitGovernanceSeen({ scan: scanWith([]), repoKey: "/repo", declarationIgnored: false });
+    assert.ok(!("/repo" in readGovernanceSeen().declarations));
+  });
+});
+
+describe("normalizeStateKey", () => {
+  it(
+    "two spellings of one directory (via symlink) share a key",
+    { skip: platform() === "win32" },
+    () => {
+      const real = join(tempDir, "real-repo");
+      mkdirSync(real, { recursive: true });
+      symlinkSync(real, join(tempDir, "linked-repo"), "dir");
+      assert.equal(
+        normalizeStateKey(join(tempDir, "linked-repo")),
+        normalizeStateKey(real),
+      );
+    },
+  );
+
+  it("case-folds on win32 (platform-stubbed — real Windows CI exercises the fs)", () => {
+    const desc = Object.getOwnPropertyDescriptor(process, "platform");
+    Object.defineProperty(process, "platform", { value: "win32", configurable: true });
+    try {
+      assert.equal(
+        normalizeStateKey("C:\\Users\\Dev\\Repo-Does-Not-Exist"),
+        "c:\\users\\dev\\repo-does-not-exist",
+      );
+    } finally {
+      Object.defineProperty(process, "platform", desc);
+    }
+  });
+
+  it("falls back to the raw path when the target does not exist", () => {
+    const ghost = join(tempDir, "does-not-exist");
+    assert.equal(
+      normalizeStateKey(ghost),
+      process.platform === "win32" ? ghost.toLowerCase() : ghost,
+    );
+  });
+});