skillrepo 4.9.2 → 4.11.0

package/src/test/lib/skillset-declaration.test.mjs

@@ -0,0 +1,514 @@
+/**
+ * Unit tests for src/lib/skillset-declaration.mjs (#2362).
+ *
+ * The repo skillset-declaration resolver: walk-up discovery (cwd →
+ * `.git` boundary or fs root), the v1 single-file rule (nesting fails
+ * closed), imperative sub-schema validation per the D6 note, the D3
+ * `@` reservation, and the pre-H8 dark-shipping error. Every
+ * fail-closed outcome carries EXIT_UNRESOLVABLE (6).
+ *
+ * Sandboxes create their own `.git` boundary so walks never escape
+ * into the real filesystem. `realpathSync` on the sandbox keeps path
+ * assertions stable on macOS (`/tmp` → `/private/tmp`).
+ */
+
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import {
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  rmSync,
+  chmodSync,
+  realpathSync,
+  symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+import { tmpdir, platform } from "node:os";
+
+import {
+  findDeclarationFiles,
+  resolveDeclaration,
+  declarationUnavailableError,
+  DECLARATION_KEY,
+  DECLARATION_SCHEMA_VERSION,
+} from "../../lib/skillset-declaration.mjs";
+import { SKILLSET_DECLARATION_FILE } from "../../lib/constants.mjs";
+import { CliError, EXIT_UNRESOLVABLE } from "../../lib/errors.mjs";
+
+let sandbox;
+
+beforeEach(() => {
+  sandbox = realpathSync(mkdtempSync(join(tmpdir(), "cli-skillset-decl-")));
+});
+
+afterEach(() => {
+  rmSync(sandbox, { recursive: true, force: true });
+});
+
+/** Create a directory tree under the sandbox and return its abs path. */
+function dir(...segments) {
+  const p = join(sandbox, ...segments);
+  mkdirSync(p, { recursive: true });
+  return p;
+}
+
+/** Write a declaration file (raw string or object) into `where`. */
+function writeDecl(where, content) {
+  const body = typeof content === "string" ? content : JSON.stringify(content, null, 2);
+  writeFileSync(join(where, SKILLSET_DECLARATION_FILE), body);
+}
+
+const VALID_BLOCK = {
+  version: 1,
+  name: "checkout-service",
+  use: "acme/backend-core",
+};
+
+/** A well-formed declaration file body. */
+function validDecl(overrides = {}) {
+  return { [DECLARATION_KEY]: { ...VALID_BLOCK, ...overrides } };
+}
+
+/** Assert an "invalid" resolution with the typed exit code. */
+function assertInvalid(resolution, messagePattern) {
+  assert.equal(resolution.status, "invalid");
+  assert.ok(resolution.error instanceof CliError, "error must be a CliError");
+  assert.equal(resolution.error.exitCode, EXIT_UNRESOLVABLE);
+  if (messagePattern) assert.match(resolution.error.message, messagePattern);
+}
+
+// ── findDeclarationFiles — walk-up discovery ───────────────────────────
+
+describe("findDeclarationFiles — walk-up discovery", () => {
+  it("returns [] when no file exists between cwd and the repo boundary", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    const cwd = dir("repo", "src", "deep");
+    assert.deepEqual(findDeclarationFiles({ cwd }), []);
+  });
+
+  it("finds the file at cwd itself (repo root case)", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    assert.deepEqual(findDeclarationFiles({ cwd: root }), [
+      join(root, SKILLSET_DECLARATION_FILE),
+    ]);
+  });
+
+  it("finds the repo-root file from a nested subdirectory", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const cwd = dir("repo", "packages", "app", "src");
+    assert.deepEqual(findDeclarationFiles({ cwd }), [
+      join(root, SKILLSET_DECLARATION_FILE),
+    ]);
+  });
+
+  it("stops at the .git boundary — a file ABOVE the repo is never consulted", () => {
+    writeDecl(sandbox, validDecl()); // outside the repo
+    const root = dir("outer", "repo");
+    mkdirSync(join(root, ".git"));
+    const cwd = dir("outer", "repo", "src");
+    assert.deepEqual(findDeclarationFiles({ cwd }), []);
+  });
+
+  it("treats a .git FILE (worktree/submodule pointer) as the boundary", () => {
+    writeDecl(sandbox, validDecl()); // outside — must not be reached
+    const root = dir("wt");
+    writeFileSync(join(root, ".git"), "gitdir: /elsewhere/.git/worktrees/wt\n");
+    writeDecl(root, validDecl());
+    const cwd = dir("wt", "lib");
+    assert.deepEqual(findDeclarationFiles({ cwd }), [
+      join(root, SKILLSET_DECLARATION_FILE),
+    ]);
+  });
+
+  it("outside any git repo, ancestors up the tree are found (ancestor-config semantics)", () => {
+    // No .git anywhere in the sandbox: the walk ascends past the
+    // sandbox toward the fs root. The sandbox-level file must be
+    // found; we only assert on entries inside the sandbox so a
+    // hypothetical stray file on the host cannot flake the test.
+    writeDecl(sandbox, validDecl());
+    const cwd = dir("plain", "nested");
+    const found = findDeclarationFiles({ cwd }).filter((p) => p.startsWith(sandbox));
+    assert.deepEqual(found, [join(sandbox, SKILLSET_DECLARATION_FILE)]);
+  });
+
+  it("returns nearest-first when multiple files exist on the path", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const sub = dir("repo", "sub");
+    writeDecl(sub, validDecl());
+    assert.deepEqual(findDeclarationFiles({ cwd: sub }), [
+      join(sub, SKILLSET_DECLARATION_FILE),
+      join(root, SKILLSET_DECLARATION_FILE),
+    ]);
+  });
+
+  it("skips a DIRECTORY named skillrepo.json", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    mkdirSync(join(root, SKILLSET_DECLARATION_FILE));
+    assert.deepEqual(findDeclarationFiles({ cwd: root }), []);
+  });
+});
+
+// ── resolveDeclaration — statuses ──────────────────────────────────────
+
+describe("resolveDeclaration — absent / config-only / declared", () => {
+  it("absent when no file exists", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    assert.deepEqual(resolveDeclaration({ cwd: root }), { status: "absent" });
+  });
+
+  it("config-only when the file has no skillset key — carries rootDir for the probe anchor", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, { someFutureFeature: true });
+    const res = resolveDeclaration({ cwd: dir("repo", "src") });
+    assert.equal(res.status, "config-only");
+    assert.equal(res.rootDir, root);
+    assert.equal(res.filePath, join(root, SKILLSET_DECLARATION_FILE));
+  });
+
+  it("declared for a well-formed declaration; extra defaults to []", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const res = resolveDeclaration({ cwd: root });
+    assert.equal(res.status, "declared");
+    assert.equal(res.rootDir, root);
+    assert.deepEqual(res.declaration, {
+      version: 1,
+      name: "checkout-service",
+      use: "acme/backend-core",
+      extra: [],
+    });
+  });
+
+  it("declared with extras — the array is copied, not aliased", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl({ extra: ["acme/db-migrations", "acme/testing"] }));
+    const res = resolveDeclaration({ cwd: root });
+    assert.equal(res.status, "declared");
+    assert.deepEqual(res.declaration.extra, ["acme/db-migrations", "acme/testing"]);
+  });
+
+  it("declared from a subdirectory — rootDir is the detected root, not cwd", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const cwd = dir("repo", "a", "b");
+    const res = resolveDeclaration({ cwd });
+    assert.equal(res.status, "declared");
+    assert.equal(res.rootDir, root);
+  });
+
+  it("empty extra array is valid and stays empty", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl({ extra: [] }));
+    const res = resolveDeclaration({ cwd: root });
+    assert.equal(res.status, "declared");
+    assert.deepEqual(res.declaration.extra, []);
+  });
+
+  it("tolerates a UTF-8 BOM (Windows editors)", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(
+      join(root, SKILLSET_DECLARATION_FILE),
+      "" + JSON.stringify(validDecl()),
+    );
+    assert.equal(resolveDeclaration({ cwd: root }).status, "declared");
+  });
+
+  it("tolerates unknown TOP-LEVEL keys (future skillrepo.json features)", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, { ...validDecl(), telemetry: { enabled: false } });
+    assert.equal(resolveDeclaration({ cwd: root }).status, "declared");
+  });
+});
+
+// ── resolveDeclaration — fail-closed outcomes ──────────────────────────
+
+describe("resolveDeclaration — nesting fails closed", () => {
+  it("two files on the walk path → invalid, names both, says not yet supported", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const sub = dir("repo", "service");
+    writeDecl(sub, validDecl({ name: "service" }));
+    const res = resolveDeclaration({ cwd: sub });
+    assertInvalid(res, /not yet supported/);
+    assert.match(res.error.message, /2 skillrepo\.json files/);
+    assert.match(res.error.hint, /repository root/);
+  });
+
+  it("a config-only file nested below a declared root still fails closed (presence, not content)", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    const sub = dir("repo", "tool");
+    writeDecl(sub, { unrelated: true });
+    assertInvalid(resolveDeclaration({ cwd: sub }), /not yet supported/);
+  });
+});
+
+describe("resolveDeclaration — symlinked declaration files", () => {
+  /** Try to create a symlink; returns false where unsupported (win32 without privilege). */
+  function trySymlink(target, linkPath) {
+    try {
+      symlinkSync(target, linkPath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  it("DANGLING symlink fails closed, never reads as absent (fail-open regression guard)", (t) => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    if (!trySymlink("./does-not-exist.json", join(root, SKILLSET_DECLARATION_FILE))) {
+      t.skip("symlinks unsupported on this platform/privilege level");
+      return;
+    }
+    const res = resolveDeclaration({ cwd: root });
+    // existsSync FOLLOWS symlinks and reports a dangling one as false,
+    // which classified the repo as undeclared and delivered the whole
+    // library (2026-08-07 prod-readiness QA). lstat-based discovery
+    // must route this into the fail-closed cannot-read branch.
+    assertInvalid(res, /cannot read/);
+  });
+
+  it("WORKING symlink to a valid declaration file resolves as declared", (t) => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, "governance.json"), JSON.stringify(validDecl()));
+    if (!trySymlink("./governance.json", join(root, SKILLSET_DECLARATION_FILE))) {
+      t.skip("symlinks unsupported on this platform/privilege level");
+      return;
+    }
+    const res = resolveDeclaration({ cwd: root });
+    assert.equal(res.status, "declared");
+    assert.equal(res.declaration.use, "acme/backend-core");
+  });
+});
+
+describe("resolveDeclaration — unreadable and unparseable files", () => {
+  it("invalid JSON → EXIT_UNRESOLVABLE with fix-or-remove guidance", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, SKILLSET_DECLARATION_FILE), "{ not json");
+    const res = resolveDeclaration({ cwd: root });
+    assertInvalid(res, /not valid JSON/);
+    assert.match(res.error.hint, /remove the file/);
+  });
+
+  it("top-level JSON array → invalid", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, SKILLSET_DECLARATION_FILE), "[1, 2]");
+    assertInvalid(resolveDeclaration({ cwd: root }), /JSON object at the top level/);
+  });
+
+  it("top-level null → invalid", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, SKILLSET_DECLARATION_FILE), "null");
+    assertInvalid(resolveDeclaration({ cwd: root }), /found null/);
+  });
+
+  it("unreadable file → invalid (cannot rule out a declaration)", (t) => {
+    if (platform() === "win32" || process.getuid?.() === 0) {
+      t.skip("chmod-based unreadability is not enforceable here");
+      return;
+    }
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    chmodSync(join(root, SKILLSET_DECLARATION_FILE), 0o000);
+    try {
+      assertInvalid(resolveDeclaration({ cwd: root }), /cannot read/);
+    } finally {
+      chmodSync(join(root, SKILLSET_DECLARATION_FILE), 0o644);
+    }
+  });
+});
+
+describe("resolveDeclaration — sub-schema validation", () => {
+  /** Resolve a declaration whose block is `block`, from a fresh repo. */
+  function resolveBlock(block) {
+    const root = dir(`repo-${Math.random().toString(36).slice(2, 8)}`);
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, { [DECLARATION_KEY]: block });
+    return resolveDeclaration({ cwd: root });
+  }
+
+  it("skillset value must be an object — string rejected", () => {
+    assertInvalid(resolveBlock("acme/backend-core"), /must be an object/);
+  });
+
+  it("skillset value must be an object — array rejected", () => {
+    assertInvalid(resolveBlock(["acme/backend-core"]), /must be an object/);
+  });
+
+  it("skillset value must be an object — null rejected", () => {
+    assertInvalid(resolveBlock(null), /must be an object/);
+  });
+
+  it("unknown field inside the block is a typo guard, names the field", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, extras: ["acme/x"] });
+    assertInvalid(res, /unknown field "extras"/);
+    assert.match(res.error.hint, /typos/);
+  });
+
+  it("multiple unknown fields are all named", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, extras: [], skillset: "x" });
+    assertInvalid(res, /unknown fields "extras", "skillset"/);
+  });
+
+  it("missing version → invalid with found-nothing copy", () => {
+    const { version, ...rest } = VALID_BLOCK;
+    assertInvalid(resolveBlock(rest), /integer "version" field \(found nothing\)/);
+  });
+
+  it("string version → invalid", () => {
+    assertInvalid(resolveBlock({ ...VALID_BLOCK, version: "1" }), /found a string/);
+  });
+
+  it("future schema version → not-supported copy pointing at a CLI update", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, version: 2 });
+    assertInvalid(res, /schema version 2 is not supported/);
+    assert.match(res.error.hint, /latest skillrepo CLI/);
+    assert.equal(DECLARATION_SCHEMA_VERSION, 1);
+  });
+
+  it("missing name → invalid", () => {
+    const { name, ...rest } = VALID_BLOCK;
+    assertInvalid(resolveBlock(rest), /"name" field/);
+  });
+
+  it("whitespace-only name → invalid", () => {
+    assertInvalid(resolveBlock({ ...VALID_BLOCK, name: "   " }), /non-empty string "name"/);
+  });
+
+  it("non-string name → invalid", () => {
+    assertInvalid(resolveBlock({ ...VALID_BLOCK, name: 7 }), /found a number/);
+  });
+
+  it("missing use → invalid", () => {
+    const { use, ...rest } = VALID_BLOCK;
+    assertInvalid(resolveBlock(rest), /"use" field must be a non-empty "owner\/name" string/);
+  });
+
+  for (const bad of ["acme", "acme/", "/core", "a/b/c", "  "]) {
+    it(`use ${JSON.stringify(bad)} fails the owner/name shape`, () => {
+      assertInvalid(resolveBlock({ ...VALID_BLOCK, use: bad }), /"use"/);
+    });
+  }
+
+  it("use with @ version syntax hits the D3 reservation, not the shape error", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, use: "acme/backend-core@2" });
+    assertInvalid(res, /"@" version syntax, which is not yet supported/);
+    assert.match(res.error.message, /library pins/);
+  });
+
+  it("extra must be an array — object rejected", () => {
+    assertInvalid(resolveBlock({ ...VALID_BLOCK, extra: {} }), /"extra" field must be an array/);
+  });
+
+  it("non-string extra entry → invalid, names the index", () => {
+    assertInvalid(resolveBlock({ ...VALID_BLOCK, extra: [42] }), /"extra\[0\]"/);
+  });
+
+  it("bad-shape extra entry → invalid at its index", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, extra: ["acme/ok", "just-a-name"] });
+    assertInvalid(res, /"extra\[1\]"/);
+  });
+
+  it("extra entry with @ hits the D3 reservation", () => {
+    assertInvalid(
+      resolveBlock({ ...VALID_BLOCK, extra: ["acme/db@1.2"] }),
+      /not yet supported/,
+    );
+  });
+
+  it("control characters in echoed content are escaped, never raw", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, use: "acme/bad\u0007name" });
+    assert.equal(res.status, "invalid");
+    assert.ok(!res.error.message.includes(String.fromCharCode(7)), "raw control char must not pass through");
+    assert.match(res.error.message, /\\u0007/);
+  });
+
+  it("C1 control characters are rejected too (canonical file-write class, not a narrower copy)", () => {
+    // › is CSI in 8-bit terminals — the C1 range a hand-rolled
+    // C0-only regex would miss (code-review round-1 finding).
+    const res = resolveBlock({ ...VALID_BLOCK, name: "svc\u009bname" });
+    assertInvalid(res, /control characters/);
+    assert.match(res.error.message, /\\u009b/);
+  });
+
+  it("control characters in unknown field names are escaped", () => {
+    const res = resolveBlock({ ...VALID_BLOCK, ["bad\u001bkey"]: 1 });
+    assert.equal(res.status, "invalid");
+    assert.ok(!res.error.message.includes(String.fromCharCode(27)));
+    assert.match(res.error.message, /\\u001b/);
+  });
+});
+
+describe("resolveDeclaration — error copy paths", () => {
+  it("names the bare filename when the file is at cwd", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, SKILLSET_DECLARATION_FILE), "{bad");
+    const res = resolveDeclaration({ cwd: root });
+    assert.match(res.error.message, /^skillrepo\.json is not valid JSON/);
+  });
+
+  it("names the absolute path when the file is above cwd", () => {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeFileSync(join(root, SKILLSET_DECLARATION_FILE), "{bad");
+    const cwd = dir("repo", "sub");
+    const res = resolveDeclaration({ cwd });
+    assert.ok(
+      res.error.message.startsWith(join(root, SKILLSET_DECLARATION_FILE)),
+      `expected absolute path prefix, got: ${res.error.message}`,
+    );
+  });
+});
+
+// ── declarationUnavailableError — the dark-shipping copy ───────────────
+
+describe("declarationUnavailableError", () => {
+  function declaredResolution() {
+    const root = dir("repo");
+    mkdirSync(join(root, ".git"));
+    writeDecl(root, validDecl());
+    return resolveDeclaration({ cwd: root });
+  }
+
+  it("carries EXIT_UNRESOLVABLE and the not-yet-available copy", () => {
+    const err = declarationUnavailableError(declaredResolution());
+    assert.ok(err instanceof CliError);
+    assert.equal(err.exitCode, EXIT_UNRESOLVABLE);
+    assert.match(err.message, /skillset "acme\/backend-core"/);
+    assert.match(err.message, /not yet available/);
+    assert.match(err.message, /never the whole library/);
+  });
+
+  it("never implies the user's file is wrong; hint offers keep-or-remove", () => {
+    const err = declarationUnavailableError(declaredResolution());
+    assert.ok(!/invalid|malformed|wrong|fix/i.test(err.message));
+    assert.match(err.hint, /Keep the declaration/);
+    assert.match(err.hint, /remove/);
+  });
+});