@cad0p/pi-steering 0.1.0

package/src/compat.test.ts

@@ -0,0 +1,431 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * Tests for {@link fromJSON} — v1 JSON → v2 {@link SteeringConfig}
+ * import helper.
+ *
+ * Covers:
+ *   - Happy paths: top-level fields, rule fields, `when.cwd`.
+ *   - Golden conversions: the v1 JSON fixtures in
+ *     `../loader.test.ts`'s source pass through with the expected
+ *     output.
+ *   - Rejection paths: every v2-only construct (plugins, observers,
+ *     function predicates, custom `when` keys).
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FromJSONError, fromJSON } from "./compat.ts";
+
+describe("compat: fromJSON happy paths", () => {
+  it("empty object produces empty config", () => {
+    assert.deepEqual(fromJSON({}), {});
+  });
+
+  it("preserves `disable` list (renames to `disabledRules` in v2)", () => {
+    const out = fromJSON({ disable: ["rule-a", "rule-b"] });
+    assert.deepEqual(out.disabledRules, ["rule-a", "rule-b"]);
+  });
+
+  it("preserves `defaultNoOverride`", () => {
+    assert.equal(fromJSON({ defaultNoOverride: true }).defaultNoOverride, true);
+    assert.equal(
+      fromJSON({ defaultNoOverride: false }).defaultNoOverride,
+      false,
+    );
+  });
+
+  it("converts a minimal rule", () => {
+    const out = fromJSON({
+      rules: [
+        {
+          name: "no-foo",
+          tool: "bash",
+          field: "command",
+          pattern: "^foo",
+          reason: "foo forbidden",
+        },
+      ],
+    });
+    assert.deepEqual(out.rules, [
+      {
+        name: "no-foo",
+        tool: "bash",
+        field: "command",
+        pattern: "^foo",
+        reason: "foo forbidden",
+      },
+    ]);
+  });
+
+  it("carries forward `requires` / `unless` / `noOverride` / `when.cwd`", () => {
+    const out = fromJSON({
+      rules: [
+        {
+          name: "rich",
+          tool: "write",
+          field: "path",
+          pattern: "secret",
+          requires: "\\.env$",
+          unless: "\\.env\\.example$",
+          noOverride: true,
+          reason: "no secrets in tracked files",
+          when: { cwd: "^/workplace" },
+        },
+      ],
+    });
+    const rule = out.rules?.[0];
+    assert.ok(rule);
+    assert.equal(rule.requires, "\\.env$");
+    assert.equal(rule.unless, "\\.env\\.example$");
+    assert.equal(rule.noOverride, true);
+    assert.equal(rule.when?.cwd, "^/workplace");
+  });
+
+  it("golden: example fixture used by the v1 JSON loader tests round-trips", () => {
+    // Mirrors the shape of the fixture at
+    // `src/loader.test.ts` — using a
+    // generic name so this test doesn't grow an import dependency
+    // on the legacy fixture file.
+    const fixture = {
+      disable: ["noisy-rule"],
+      defaultNoOverride: true,
+      rules: [
+        {
+          name: "block-dangerous",
+          tool: "bash",
+          field: "command",
+          pattern: "^rm\\s+-rf",
+          reason: "rm -rf is catastrophic",
+          noOverride: true,
+        },
+        {
+          name: "warn-in-workplace",
+          tool: "bash",
+          field: "command",
+          pattern: "^git\\s+push",
+          reason: "don't push from workplace paths",
+          when: { cwd: "^/workplace" },
+        },
+      ],
+    };
+    const out = fromJSON(fixture);
+    assert.deepEqual(out.disabledRules, ["noisy-rule"]);
+    assert.equal(out.defaultNoOverride, true);
+    assert.equal(out.rules?.length, 2);
+    assert.equal(out.rules?.[0]?.noOverride, true);
+    assert.equal(out.rules?.[1]?.when?.cwd, "^/workplace");
+  });
+});
+
+describe("compat: fromJSON rejections", () => {
+  it("rejects non-object top-level", () => {
+    assert.throws(() => fromJSON(null), FromJSONError);
+    assert.throws(() => fromJSON(42), FromJSONError);
+    assert.throws(() => fromJSON("string"), FromJSONError);
+    assert.throws(() => fromJSON([]), FromJSONError);
+  });
+
+  it("rejects v2-only top-level keys with a clear error", () => {
+    for (const key of [
+      "plugins",
+      "observers",
+      "disablePlugins",
+      "disabledPlugins",
+      "disabledRules",
+      "disableDefaults",
+    ]) {
+      let caught: unknown;
+      try {
+        fromJSON({ [key]: [] });
+      } catch (e) {
+        caught = e;
+      }
+      assert.ok(
+        caught instanceof FromJSONError,
+        `expected FromJSONError for ${key}`,
+      );
+      assert.ok(
+        caught.message.includes(key),
+        `error should mention the forbidden key, got: ${caught.message}`,
+      );
+      assert.equal(caught.path, `<root>.${key}`);
+    }
+  });
+
+  it("rejects malformed `disable`", () => {
+    assert.throws(() => fromJSON({ disable: "not-an-array" }), FromJSONError);
+    assert.throws(() => fromJSON({ disable: [1, 2] }), FromJSONError);
+  });
+
+  it("rejects malformed `defaultNoOverride`", () => {
+    assert.throws(() => fromJSON({ defaultNoOverride: "true" }), FromJSONError);
+  });
+
+  it("rejects missing required rule fields", () => {
+    // missing name
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            { tool: "bash", field: "command", pattern: "p", reason: "r" },
+          ],
+        }),
+      FromJSONError,
+    );
+    // missing pattern
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [{ name: "n", tool: "bash", field: "command", reason: "r" }],
+        }),
+      FromJSONError,
+    );
+    // wrong tool value
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "shell", // not one of bash/write/edit
+              field: "command",
+              pattern: "p",
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects invalid (tool, field) combinations per the Rule union", () => {
+    // bash rules must use `field: "command"`; `path` / `content` are
+    // silently-wrong combos the discriminated TS Rule union now
+    // rejects. compat.ts mirrors the check at JSON parse time.
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "path",
+              pattern: "p",
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "content",
+              pattern: "p",
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+    // write / edit rules test `path` or `content`, never `command`.
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "write",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "edit",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects non-string `pattern`", () => {
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: 42,
+              reason: "r",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects function-shaped rule fields (they can't appear in JSON, but errors help hand-editing humans)", () => {
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+              requires: 42,
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects plugin-registered `when` keys", () => {
+    let caught: unknown;
+    try {
+      fromJSON({
+        rules: [
+          {
+            name: "n",
+            tool: "bash",
+            field: "command",
+            pattern: "p",
+            reason: "r",
+            when: { branch: "^main$" },
+          },
+        ],
+      });
+    } catch (e) {
+      caught = e;
+    }
+    assert.ok(caught instanceof FromJSONError);
+    assert.ok(caught.message.includes("when.branch"));
+    assert.ok(caught.path.endsWith("when.branch"));
+  });
+
+  it("rejects `when.not` / `when.condition` (v2-only)", () => {
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+              when: { not: {} },
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+              when: { condition: "noop" },
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects `observer` key on a rule", () => {
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+              observer: "some-name",
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+
+  it("rejects non-string `when.cwd`", () => {
+    assert.throws(
+      () =>
+        fromJSON({
+          rules: [
+            {
+              name: "n",
+              tool: "bash",
+              field: "command",
+              pattern: "p",
+              reason: "r",
+              when: { cwd: 42 },
+            },
+          ],
+        }),
+      FromJSONError,
+    );
+  });
+});
+
+describe("compat: FromJSONError", () => {
+  it("carries a path pointing at the offending location", () => {
+    try {
+      fromJSON({
+        rules: [
+          {
+            name: "ok",
+            tool: "bash",
+            field: "command",
+            pattern: "p",
+            reason: "r",
+          },
+          {
+            name: "bad",
+            tool: "bash",
+            field: "command",
+            pattern: 42,
+            reason: "r",
+          },
+        ],
+      });
+      assert.fail("expected throw");
+    } catch (err) {
+      assert.ok(err instanceof FromJSONError);
+      assert.equal(err.path, "<root>.rules[1].pattern");
+    }
+  });
+});

package/src/compat.ts

@@ -0,0 +1,282 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * `fromJSON` — convert the v1 JSON config shape to a v2
+ * {@link SteeringConfig}.
+ *
+ * Per the accepted ADR ("Design → File layout and loader behavior"):
+ * JSON is not a first-class config format in v2. `fromJSON` exists so
+ * `.pi/steering.json` files authored against the PoC shape can be
+ * loaded programmatically — either as a library call (this module)
+ * or via the `pi-steering import-json` CLI wrapping it.
+ *
+ * Scope:
+ *
+ *   - Top-level v1 fields: `disable`, `defaultNoOverride`, `rules`.
+ *   - Rule fields: `name`, `tool`, `field`, `pattern` (stays a string —
+ *     v2 accepts `string | RegExp`), `requires`, `unless`, `reason`,
+ *     `noOverride`, `when.cwd` (string pattern).
+ *
+ * Rejected (throws):
+ *
+ *   - Plugins (JSON can't express function-typed handlers).
+ *   - Observers (ditto — `onResult` is a function).
+ *   - Function-valued fields on rules (ditto).
+ *   - `when.<customKey>` — plugin-registered predicates have no
+ *     JSON-expressible binding.
+ *   - `when.not` or `when.condition` (also function-shaped or recursive).
+ *
+ * Callers that hit one of the rejection cases should author the
+ * offending rule / plugin directly in TypeScript; `fromJSON` is only
+ * for the trivial pattern-string path.
+ */
+
+import type { Rule, SteeringConfig, WhenClause } from "./schema.ts";
+
+/**
+ * Error thrown when the input JSON uses a feature the v1 → v2 helper
+ * can't represent. Carries a `path` pointing at the offending location
+ * (e.g. `rules[2].when.branch`) so callers can point the user at the
+ * rule to rewrite in TypeScript.
+ */
+export class FromJSONError extends Error {
+  readonly path: string;
+
+  constructor(message: string, path: string) {
+    super(`${message} (at ${path})`);
+    this.name = "FromJSONError";
+    this.path = path;
+  }
+}
+
+/** Narrow `unknown` to a plain (non-array) object. */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Convert v1 JSON into a v2 {@link SteeringConfig}.
+ *
+ * The input is typed `unknown` deliberately — this helper accepts
+ * whatever came out of `JSON.parse`, validates the shape, and throws
+ * {@link FromJSONError} on anything it can't represent.
+ */
+export function fromJSON(json: unknown): SteeringConfig {
+  if (!isPlainObject(json)) {
+    throw new FromJSONError(
+      "expected a JSON object at the top level",
+      "<root>",
+    );
+  }
+
+  // Pre-flight: loudly reject v2-only keys that shouldn't appear in
+  // v1 JSON. If a user lands here by mistake (e.g. calling fromJSON
+  // on an already-v2 object), we'd rather tell them than silently
+  // drop their plugins / observers.
+  for (const forbidden of [
+    "plugins",
+    "observers",
+    "disablePlugins",
+    "disabledPlugins",
+    "disabledRules",
+    "disableDefaults",
+  ] as const) {
+    if (forbidden in json) {
+      throw new FromJSONError(
+        `JSON config cannot express \`${forbidden}\`; ` +
+          `author that configuration directly in TypeScript instead`,
+        `<root>.${forbidden}`,
+      );
+    }
+  }
+
+  const out: SteeringConfig = {};
+
+  if ("disable" in json) {
+    const disable = json["disable"];
+    if (
+      !Array.isArray(disable) ||
+      !disable.every((x) => typeof x === "string")
+    ) {
+      throw new FromJSONError(
+        "`disable` must be a string array",
+        "<root>.disable",
+      );
+    }
+    // v1 JSON's `disable` → v2 TS `disabledRules`. The JSON key is
+    // preserved for legacy on-disk configs; the TS shape uses the
+    // past-participle form.
+    out.disabledRules = [...disable];
+  }
+
+  if ("defaultNoOverride" in json) {
+    const v = json["defaultNoOverride"];
+    if (typeof v !== "boolean") {
+      throw new FromJSONError(
+        "`defaultNoOverride` must be a boolean",
+        "<root>.defaultNoOverride",
+      );
+    }
+    out.defaultNoOverride = v;
+  }
+
+  if ("rules" in json) {
+    const rules = json["rules"];
+    if (!Array.isArray(rules)) {
+      throw new FromJSONError("`rules` must be an array", "<root>.rules");
+    }
+    out.rules = rules.map((rule, i) => convertRule(rule, `<root>.rules[${i}]`));
+  }
+
+  return out;
+}
+
+/** Convert a single v1 JSON rule, scoping errors with `path`. */
+function convertRule(raw: unknown, path: string): Rule {
+  if (!isPlainObject(raw)) {
+    throw new FromJSONError("rule must be an object", path);
+  }
+
+  // Required: name, tool, field, pattern, reason.
+  const name = raw["name"];
+  if (typeof name !== "string" || name.length === 0) {
+    throw new FromJSONError(
+      "`name` must be a non-empty string",
+      `${path}.name`,
+    );
+  }
+  const tool = raw["tool"];
+  if (tool !== "bash" && tool !== "write" && tool !== "edit") {
+    throw new FromJSONError(
+      "`tool` must be one of 'bash' | 'write' | 'edit'",
+      `${path}.tool`,
+    );
+  }
+  const field = raw["field"];
+  if (field !== "command" && field !== "path" && field !== "content") {
+    throw new FromJSONError(
+      "`field` must be one of 'command' | 'path' | 'content'",
+      `${path}.field`,
+    );
+  }
+  // Validate the (tool, field) combination per the discriminated
+  // Rule union: bash rules test against `command`; write / edit
+  // rules test against `path` or `content`.
+  if (tool === "bash" && field !== "command") {
+    throw new FromJSONError(
+      `bash rules must use \`field: "command"\` (got "${field}")`,
+      `${path}.field`,
+    );
+  }
+  if ((tool === "write" || tool === "edit") && field === "command") {
+    throw new FromJSONError(
+      `${tool} rules must use \`field: "path"\` or \`field: "content"\` ` +
+        `(got "command")`,
+      `${path}.field`,
+    );
+  }
+  const pattern = raw["pattern"];
+  if (typeof pattern !== "string") {
+    throw new FromJSONError(
+      "JSON rules must use a string `pattern` (v2 accepts RegExp in TS)",
+      `${path}.pattern`,
+    );
+  }
+  const reason = raw["reason"];
+  if (typeof reason !== "string") {
+    throw new FromJSONError("`reason` must be a string", `${path}.reason`);
+  }
+
+  const rule: Rule =
+    tool === "bash"
+      ? { name, tool, field: "command", pattern, reason }
+      : {
+          name,
+          tool,
+          // Narrowed by the (tool, field) check above.
+          field: field as "path" | "content",
+          pattern,
+          reason,
+        };
+
+  // Optional: requires / unless (string patterns only).
+  if ("requires" in raw) {
+    const v = raw["requires"];
+    if (typeof v !== "string") {
+      throw new FromJSONError(
+        "JSON rules must use string `requires` (functions aren't JSON-expressible)",
+        `${path}.requires`,
+      );
+    }
+    rule.requires = v;
+  }
+  if ("unless" in raw) {
+    const v = raw["unless"];
+    if (typeof v !== "string") {
+      throw new FromJSONError(
+        "JSON rules must use string `unless` (functions aren't JSON-expressible)",
+        `${path}.unless`,
+      );
+    }
+    rule.unless = v;
+  }
+
+  // Optional: noOverride.
+  if ("noOverride" in raw) {
+    const v = raw["noOverride"];
+    if (typeof v !== "boolean") {
+      throw new FromJSONError(
+        "`noOverride` must be a boolean",
+        `${path}.noOverride`,
+      );
+    }
+    rule.noOverride = v;
+  }
+
+  // Optional: when. V1 JSON supports only `when.cwd` (string pattern).
+  // Every other key under `when` is plugin-specific and can't be
+  // expressed in JSON.
+  if ("when" in raw) {
+    rule.when = convertWhen(raw["when"], `${path}.when`);
+  }
+
+  // V1 JSON has no `observer` field — observers are v2-only. But if
+  // someone hand-edits `observer: "name"` into their JSON, warn loudly.
+  if ("observer" in raw) {
+    throw new FromJSONError(
+      "JSON rules cannot reference observers; observers are v2-only (TS)",
+      `${path}.observer`,
+    );
+  }
+
+  return rule;
+}
+
+/** Convert the v1 `when` object into a v2 {@link WhenClause}. */
+function convertWhen(raw: unknown, path: string): WhenClause {
+  if (!isPlainObject(raw)) {
+    throw new FromJSONError("`when` must be an object", path);
+  }
+  const out: WhenClause = {};
+  for (const key of Object.keys(raw)) {
+    if (key !== "cwd") {
+      throw new FromJSONError(
+        `JSON config cannot express \`when.${key}\`; ` +
+          `plugin-registered predicates and \`when.not\` / \`when.condition\` are v2-only (TS)`,
+        `${path}.${key}`,
+      );
+    }
+  }
+  if ("cwd" in raw) {
+    const v = raw["cwd"];
+    if (typeof v !== "string") {
+      throw new FromJSONError(
+        "JSON `when.cwd` must be a string pattern",
+        `${path}.cwd`,
+      );
+    }
+    out.cwd = v;
+  }
+  return out;
+}