@syv-ai/rulecast 0.1.0

package/dist/index.js

@@ -0,0 +1,327 @@
+import {
+  ADAPTERS,
+  CONFIG_FILE,
+  LlmUnavailableError,
+  MANIFEST_FILE,
+  MODEL_ALIASES,
+  VERSION,
+  adapterByName,
+  builtinDetectors,
+  cacheHome,
+  cachedRepos,
+  checkDetectors,
+  checkableKinds,
+  claudeCodeAdapter,
+  compile,
+  compileManifest,
+  createRegistry,
+  defaultDetectorSettings,
+  emptyDelivery,
+  fetchingRepos,
+  fixedRepo,
+  memoryCache,
+  perRule,
+  projectStateDir,
+  providerByName,
+  readSourceFile,
+  renderAgentText,
+  resolveModel,
+  runPipeline
+} from "./chunk-POEWJTZ2.js";
+
+// src/testing/adapter-contract.ts
+import assert from "assert/strict";
+var FORMAT_OPTIONS = { maxMatchesPerRule: 3 };
+var NONSENSE = [null, void 0, 0, "", "not json", [], {}, { hook_event_name: "NoSuchEvent" }];
+function adapterContract(adapter, fixture) {
+  const cases = [
+    {
+      name: "describes itself",
+      async run() {
+        assert.ok(adapter.name.length > 0, "name must not be empty");
+        assert.ok(adapter.label.length > 0, "label must not be empty");
+        assert.ok(
+          adapter.maxContextChars === null || adapter.maxContextChars > 0,
+          "maxContextChars must be null or positive"
+        );
+        assert.ok(Number.isInteger(adapter.restoredFiles) && adapter.restoredFiles >= 0, "restoredFiles must be >= 0");
+      }
+    },
+    {
+      name: "returns null for input it does not handle, and never throws",
+      async run() {
+        for (const input of NONSENSE) {
+          const parsed = adapter.parse(input);
+          assert.equal(parsed, null, `parse(${JSON.stringify(input)}) must be null`);
+        }
+      }
+    },
+    {
+      name: "parses each recorded payload to its event",
+      async run() {
+        assert.ok(fixture.payloads.length > 0, "an adapter fixture needs at least one recorded payload");
+        for (const { name, input, expected } of fixture.payloads) {
+          assert.deepEqual(adapter.parse(input), expected, `payload ${name}`);
+        }
+      }
+    },
+    {
+      name: "parsing is pure: the same payload parses the same twice",
+      async run() {
+        for (const { name, input } of fixture.payloads) {
+          assert.deepEqual(adapter.parse(input), adapter.parse(input), `payload ${name}`);
+        }
+      }
+    },
+    {
+      name: "every parsed event is well formed",
+      async run() {
+        for (const { name, input } of fixture.payloads) {
+          const event = adapter.parse(input)?.event;
+          if (!event) continue;
+          assert.ok(event.cwd.length > 0, `${name}: event.cwd must not be empty`);
+          for (const file of event.files) assert.equal(typeof file, "string", `${name}: files must be strings`);
+          if (event.kind === "prompt" || event.kind === "reset") {
+            assert.deepEqual(event.files, [], `${name}: ${event.kind} carries no files`);
+          }
+        }
+      }
+    },
+    {
+      name: "formats each delivery deterministically, with an exit code of 0 or 1",
+      async run() {
+        for (const { name, delivery, event } of fixture.deliveries) {
+          const first = adapter.format(delivery, event, FORMAT_OPTIONS);
+          const second = adapter.format(delivery, event, FORMAT_OPTIONS);
+          assert.deepEqual(first, second, `${name}: formatting must be deterministic`);
+          assert.equal(typeof first.stdout, "string", `${name}: stdout must be a string`);
+          assert.ok([0, 1].includes(first.exitCode), `${name}: exit code must be 0 or 1, got ${first.exitCode}`);
+        }
+      }
+    },
+    {
+      name: "an empty delivery exits 0",
+      async run() {
+        const event = fixture.deliveries[0]?.event ?? { kind: "edit", files: [], cwd: "/project" };
+        const result = adapter.format(emptyDelivery(), event, FORMAT_OPTIONS);
+        assert.equal(result.exitCode, 0, "nothing to report must not be a failure");
+      }
+    }
+  ];
+  const install = adapter.install;
+  if (install) {
+    cases.push(
+      {
+        name: "install declares markers, scopes and a command",
+        async run() {
+          assert.ok(install.markers.length > 0, "markers must not be empty");
+          assert.ok(install.scopes.length > 0, "scopes must not be empty");
+          for (const { file } of install.scopes) assert.ok(file.length > 0, "a scope needs a settings file");
+          assert.notEqual(install.command(true), install.command(false), "a local install runs a different command");
+        }
+      },
+      {
+        name: "merge is idempotent and remove undoes it",
+        async run() {
+          const command = install.command(false);
+          for (const settings of fixture.settings ?? [{}]) {
+            const original = structuredClone(settings);
+            const once = install.merge(structuredClone(original), command, 5e3);
+            assert.ok(once.added.length > 0, "merging into fresh settings must add hooks");
+            const twice = install.merge(structuredClone(once.settings), command, 5e3);
+            assert.deepEqual(twice.settings, once.settings, "merging twice must change nothing");
+            assert.deepEqual(twice.added, [], "merging twice must add nothing");
+            const removed = install.remove(structuredClone(once.settings));
+            assert.deepEqual(removed.settings, original, "remove must return the settings merge was given");
+            assert.deepEqual([...removed.removed].sort(), [...once.added].sort(), "remove must name what merge added");
+          }
+        }
+      }
+    );
+  }
+  return cases;
+}
+
+// src/testing/detector-contract.ts
+import assert2 from "assert/strict";
+
+// src/testing/contract.ts
+import { mkdir, mkdtemp, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import path from "path";
+async function contractProject(files) {
+  const root = await mkdtemp(path.join(tmpdir(), "rulecast-contract-"));
+  for (const [file, content] of Object.entries(files)) {
+    const full = path.join(root, file);
+    await mkdir(path.dirname(full), { recursive: true });
+    await writeFile(full, content);
+  }
+  return root;
+}
+
+// src/testing/detector-contract.ts
+var EVENTS = ["edit", "verify"];
+async function configOf(detector, value, where) {
+  const parsed = await detector.schema.safeParseAsync(value);
+  assert2.ok(parsed.success, `${where} config must pass the detector's own schema`);
+  return parsed.data;
+}
+function run(detector, rules, cwd, signal) {
+  return detector.run({
+    event: "edit",
+    // biome-ignore lint/suspicious/noExplicitAny: the registry erases each detector's config type.
+    rules,
+    changes: /* @__PURE__ */ new Map(),
+    read: (file) => readSourceFile(cwd, file),
+    cache: memoryCache(),
+    settings: defaultDetectorSettings(),
+    cwd,
+    signal
+  });
+}
+function assertResultShape(result, ids) {
+  assert2.ok(Array.isArray(result.findings), "result.findings must be an array");
+  assert2.ok(Array.isArray(result.errors), "result.errors must be an array");
+  for (const finding of result.findings) {
+    assert2.ok(ids.includes(finding.rule), `finding names rule "${finding.rule}", which was not in the run`);
+    const { match } = finding;
+    assert2.equal(typeof match.file, "string", "match.file must be a string");
+    for (const key of ["line", "endLine", "column"]) {
+      assert2.ok(Number.isInteger(match[key]) && match[key] >= 1, `match.${key} must be a 1-based integer`);
+    }
+    assert2.ok(match.endLine >= match.line, "match.endLine must not precede match.line");
+    assert2.equal(typeof match.text, "string", "match.text must be a string");
+  }
+  for (const error of result.errors) {
+    assert2.ok(error.rule === null || ids.includes(error.rule), `error names rule "${error.rule}", not in the run`);
+    assert2.equal(typeof error.message, "string", "error.message must be a string");
+  }
+}
+function detectorContract(detector, fixture) {
+  const project = async () => {
+    const root = await contractProject(fixture.files);
+    await fixture.prepare?.(root);
+    return root;
+  };
+  const rule = (id, config, files) => ({ id, config, files, context: [] });
+  const open = () => new AbortController().signal;
+  const cases = [
+    {
+      name: "declares a kind, captures and events",
+      async run() {
+        assert2.ok(detector.kind.length > 0, "kind must not be empty");
+        const config = await configOf(detector, fixture.config, "the fixture's");
+        const captures = detector.captures(config);
+        assert2.ok(Array.isArray(captures), "captures(config) must return an array");
+        for (const name of captures) assert2.equal(typeof name, "string", "a capture name must be a string");
+        const events = detector.events(config);
+        assert2.ok(events.length > 0, "events(config) must name at least one event");
+        for (const event of events) assert2.ok(EVENTS.includes(event), `unknown event "${event}"`);
+      }
+    },
+    {
+      name: "no rules is an empty result",
+      async run() {
+        const result = await run(detector, [], await project(), open());
+        assert2.deepEqual(result, { findings: [], errors: [] });
+      }
+    },
+    {
+      name: "every match carries exactly the declared captures, as strings",
+      async run() {
+        const config = await configOf(detector, fixture.config, "the fixture's");
+        const declared = [...detector.captures(config)].sort();
+        const result = await run(detector, [rule("a", config, fixture.matching)], await project(), open());
+        assert2.deepEqual(result.errors, [], "the fixture's matching config must not error");
+        assert2.ok(result.findings.length > 0, "the fixture's matching config must produce at least one finding");
+        assertResultShape(result, ["a"]);
+        for (const finding of result.findings) {
+          const present = Object.keys(finding.match.captures).sort();
+          assert2.deepEqual(present, declared, "captures must be exactly the declared names");
+          for (const value of Object.values(finding.match.captures)) {
+            assert2.equal(typeof value, "string", "every capture must be a string");
+          }
+        }
+      }
+    },
+    {
+      name: "batching attributes the same work to every rule that asked for it",
+      async run() {
+        const config = await configOf(detector, fixture.config, "the fixture's");
+        const rules = [rule("a", config, fixture.matching), rule("b", config, fixture.matching)];
+        const result = await run(detector, rules, await project(), open());
+        assert2.deepEqual(result.errors, [], "two identical rules must not error");
+        assertResultShape(result, ["a", "b"]);
+        const forRule = (id) => result.findings.filter((finding) => finding.rule === id);
+        assert2.ok(forRule("a").length > 0, "rule a must get findings");
+        assert2.equal(forRule("b").length, forRule("a").length, "identical rules must get the same findings");
+      }
+    },
+    {
+      name: "an aborted run produces nothing",
+      async run() {
+        const config = await configOf(detector, fixture.config, "the fixture's");
+        const controller = new AbortController();
+        controller.abort();
+        const rules = [rule("a", config, fixture.matching)];
+        const result = await run(detector, rules, await project(), controller.signal).catch(() => null);
+        if (result !== null) assert2.deepEqual(result.findings, [], "an aborted run must not report findings");
+      }
+    }
+  ];
+  if (fixture.failing) {
+    const failing = fixture.failing;
+    cases.push({
+      name: "a rule that fails does not take the others with it",
+      async run() {
+        const good = await configOf(detector, fixture.config, "the fixture's");
+        const bad = await configOf(detector, failing.config, "the fixture's failing");
+        const rules = [rule("bad", bad, failing.matching ?? fixture.matching), rule("good", good, fixture.matching)];
+        const result = await run(detector, rules, await project(), open());
+        assertResultShape(result, ["bad", "good"]);
+        assert2.ok(
+          result.errors.some((error) => error.rule === "bad"),
+          "the failing rule must produce an error naming it"
+        );
+        assert2.ok(
+          !result.errors.some((error) => error.rule === null),
+          "one rule's failure must not be reported as a whole-run error"
+        );
+        assert2.ok(
+          result.findings.some((finding) => finding.rule === "good"),
+          "the healthy rule must still report its findings"
+        );
+      }
+    });
+  }
+  return cases;
+}
+export {
+  ADAPTERS,
+  CONFIG_FILE,
+  LlmUnavailableError,
+  MANIFEST_FILE,
+  MODEL_ALIASES,
+  VERSION,
+  adapterByName,
+  adapterContract,
+  builtinDetectors,
+  cacheHome,
+  cachedRepos,
+  checkDetectors,
+  checkableKinds,
+  claudeCodeAdapter,
+  compile,
+  compileManifest,
+  createRegistry,
+  detectorContract,
+  emptyDelivery,
+  fetchingRepos,
+  fixedRepo,
+  perRule,
+  projectStateDir,
+  providerByName,
+  renderAgentText,
+  resolveModel,
+  runPipeline
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@syv-ai/rulecast",
+  "version": "0.1.0",
+  "description": "Deliver project conventions to coding agents at the moment they matter.",
+  "keywords": [
+    "claude-code",
+    "coding-agent",
+    "coding-agents",
+    "conventions",
+    "lint",
+    "hooks",
+    "ast-grep",
+    "agents"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/syv-ai/rulecast#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/syv-ai/rulecast.git",
+    "directory": "packages/rulecast"
+  },
+  "bugs": "https://github.com/syv-ai/rulecast/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=20.12"
+  },
+  "bin": {
+    "rulecast": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ast-grep/lang-python": "^0.0.6",
+    "@ast-grep/napi": "^0.45.3",
+    "@clack/prompts": "^1.8.1",
+    "diff": "^8.0.4",
+    "yaml": "^2.9.1",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "oxlint": "^1.83.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7"
+  },
+  "scripts": {
+    "binary": "tsx scripts/build-binary.ts",
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --clean",
+    "manifest": "tsx scripts/generate-manifest.ts",
+    "perf": "tsx scripts/perf.ts",
+    "readme": "tsx scripts/readme.ts",
+    "release-notes": "tsx scripts/release-notes.ts",
+    "sync-version": "tsx scripts/sync-version.ts",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}