@h-rig/plugin-testkit 0.0.6-alpha.79

package/README.md

@@ -0,0 +1 @@
+# @h-rig/plugin-testkit

package/dist/src/behavior.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Behavior-level test helpers — invoke a plugin's executable channels
+ * (validators, task-source factories, typed hooks) with mock inputs and
+ * assert the results have the contract shape, modeling the assertions in
+ * @rig/core's plugin-host.test.ts.
+ *
+ * Unlike `pluginContractTests` these are runner-agnostic: they throw plain
+ * Errors instead of using vitest assertions, so they work the same under
+ * vitest and `bun test`.
+ */
+import type { HookContext, HookResult, RegisteredTaskSource, TaskSourceConfig } from "@rig/contracts";
+import type { RigPluginWithRuntime, ValidatorContext, ValidatorResult } from "@rig/core";
+/**
+ * Invoke the plugin's executable validator `id` with a mock
+ * ValidatorContext (missing fields filled with testkit defaults), assert
+ * the result shape (id/passed/summary present, id matches), and return it.
+ */
+export declare function testValidatorContext(plugin: RigPluginWithRuntime, id: string, mockCtx?: Partial<ValidatorContext>): Promise<ValidatorResult>;
+/**
+ * Assert the plugin ships an executable task-source factory for `kind`,
+ * instantiate it (with `config` or a minimal `{ kind }`), assert the
+ * returned RegisteredTaskSource carries the required surface (kind, id,
+ * list()), and return it for further assertions.
+ */
+export declare function expectTaskSourceRuntime(plugin: RigPluginWithRuntime, kind: string, config?: TaskSourceConfig): RegisteredTaskSource;
+/**
+ * Invoke the plugin's typed hook implementation `id` with a mock
+ * HookContext (missing fields filled with testkit defaults; the event
+ * defaults to the hook's metadata registration), assert the HookResult
+ * shape, and return it.
+ */
+export declare function testHook(plugin: RigPluginWithRuntime, id: string, mockInput?: Partial<HookContext>): Promise<HookResult>;

package/dist/src/behavior.js

@@ -0,0 +1,81 @@
+// @bun
+// packages/plugin-testkit/src/behavior.ts
+function fail(plugin, message) {
+  throw new Error(`plugin "${plugin.name}": ${message}`);
+}
+var DEFAULT_VALIDATOR_CONTEXT = {
+  taskId: "testkit-task",
+  workspaceRoot: "/tmp/testkit-workspace",
+  scope: []
+};
+async function testValidatorContext(plugin, id, mockCtx = {}) {
+  const validator = plugin.__runtime?.validators?.find((v) => v.id === id);
+  if (!validator) {
+    fail(plugin, `no executable validator "${id}" in the runtime channel`);
+  }
+  const result = await validator.run({ ...DEFAULT_VALIDATOR_CONTEXT, ...mockCtx });
+  if (typeof result?.id !== "string" || result.id !== id) {
+    fail(plugin, `validator "${id}" returned id "${result?.id}" \u2014 must echo its own id`);
+  }
+  if (typeof result.passed !== "boolean") {
+    fail(plugin, `validator "${id}" result is missing a boolean "passed"`);
+  }
+  if (typeof result.summary !== "string") {
+    fail(plugin, `validator "${id}" result is missing a string "summary"`);
+  }
+  return result;
+}
+function expectTaskSourceRuntime(plugin, kind, config) {
+  const entry = plugin.__runtime?.taskSources?.find((s) => s.kind === kind);
+  if (!entry) {
+    fail(plugin, `no executable task-source factory for kind "${kind}" in the runtime channel`);
+  }
+  const source = entry.factory(config ?? { kind });
+  if (!source || typeof source !== "object") {
+    fail(plugin, `task-source factory for kind "${kind}" did not return an object`);
+  }
+  if (source.kind !== kind) {
+    fail(plugin, `task source for kind "${kind}" reports kind "${source.kind}"`);
+  }
+  if (typeof source.id !== "string" || source.id.length === 0) {
+    fail(plugin, `task source for kind "${kind}" is missing a non-empty id`);
+  }
+  if (typeof source.list !== "function") {
+    fail(plugin, `task source for kind "${kind}" is missing the required list() method`);
+  }
+  return source;
+}
+async function testHook(plugin, id, mockInput = {}) {
+  const implementation = plugin.__runtime?.hooks?.[id];
+  if (!implementation) {
+    fail(plugin, `no typed hook implementation "${id}" in the runtime channel`);
+  }
+  const registration = (plugin.contributes?.hooks ?? []).find((h) => h.id === id);
+  if (!registration) {
+    fail(plugin, `typed hook "${id}" has no metadata entry in contributes.hooks`);
+  }
+  const input = {
+    event: registration.event,
+    toolInput: {},
+    filePaths: [],
+    projectRoot: "/tmp/testkit-project",
+    taskId: "testkit-task",
+    ...mockInput
+  };
+  const result = await implementation(input);
+  if (result?.decision !== "allow" && result?.decision !== "block") {
+    fail(plugin, `typed hook "${id}" returned decision "${result?.decision}" \u2014 must be "allow" or "block"`);
+  }
+  if (result.reason !== undefined && typeof result.reason !== "string") {
+    fail(plugin, `typed hook "${id}" returned a non-string "reason"`);
+  }
+  if (result.systemMessage !== undefined && typeof result.systemMessage !== "string") {
+    fail(plugin, `typed hook "${id}" returned a non-string "systemMessage"`);
+  }
+  return result;
+}
+export {
+  testValidatorContext,
+  testHook,
+  expectTaskSourceRuntime
+};

package/dist/src/index.d.ts

@@ -0,0 +1,17 @@
+import type { RigPlugin } from "@rig/contracts";
+export { expectTaskSourceRuntime, testHook, testValidatorContext, } from "./behavior";
+/**
+ * Run a standard contract-test suite against a plugin instance.
+ * Plugin authors use this to verify their plugin is well-formed before publishing.
+ *
+ * Usage in plugin author's test file:
+ *   import { pluginContractTests } from "@rig/plugin-testkit";
+ *   import myPlugin from "../src";
+ *   pluginContractTests(myPlugin());
+ */
+export declare function pluginContractTests(plugin: RigPlugin): void;
+/**
+ * Assert that a plugin contributes at least one item of the named kind.
+ * Useful inside additional test suites.
+ */
+export declare function expectContribution(plugin: RigPlugin, kind: keyof NonNullable<RigPlugin["contributes"]>): void;

package/dist/src/index.js

@@ -0,0 +1,153 @@
+// @bun
+// packages/plugin-testkit/src/index.ts
+import { describe, expect, it } from "vitest";
+import { Schema } from "effect";
+import { RigPlugin as RigPluginSchema } from "@rig/contracts";
+
+// packages/plugin-testkit/src/behavior.ts
+function fail(plugin, message) {
+  throw new Error(`plugin "${plugin.name}": ${message}`);
+}
+var DEFAULT_VALIDATOR_CONTEXT = {
+  taskId: "testkit-task",
+  workspaceRoot: "/tmp/testkit-workspace",
+  scope: []
+};
+async function testValidatorContext(plugin, id, mockCtx = {}) {
+  const validator = plugin.__runtime?.validators?.find((v) => v.id === id);
+  if (!validator) {
+    fail(plugin, `no executable validator "${id}" in the runtime channel`);
+  }
+  const result = await validator.run({ ...DEFAULT_VALIDATOR_CONTEXT, ...mockCtx });
+  if (typeof result?.id !== "string" || result.id !== id) {
+    fail(plugin, `validator "${id}" returned id "${result?.id}" \u2014 must echo its own id`);
+  }
+  if (typeof result.passed !== "boolean") {
+    fail(plugin, `validator "${id}" result is missing a boolean "passed"`);
+  }
+  if (typeof result.summary !== "string") {
+    fail(plugin, `validator "${id}" result is missing a string "summary"`);
+  }
+  return result;
+}
+function expectTaskSourceRuntime(plugin, kind, config) {
+  const entry = plugin.__runtime?.taskSources?.find((s) => s.kind === kind);
+  if (!entry) {
+    fail(plugin, `no executable task-source factory for kind "${kind}" in the runtime channel`);
+  }
+  const source = entry.factory(config ?? { kind });
+  if (!source || typeof source !== "object") {
+    fail(plugin, `task-source factory for kind "${kind}" did not return an object`);
+  }
+  if (source.kind !== kind) {
+    fail(plugin, `task source for kind "${kind}" reports kind "${source.kind}"`);
+  }
+  if (typeof source.id !== "string" || source.id.length === 0) {
+    fail(plugin, `task source for kind "${kind}" is missing a non-empty id`);
+  }
+  if (typeof source.list !== "function") {
+    fail(plugin, `task source for kind "${kind}" is missing the required list() method`);
+  }
+  return source;
+}
+async function testHook(plugin, id, mockInput = {}) {
+  const implementation = plugin.__runtime?.hooks?.[id];
+  if (!implementation) {
+    fail(plugin, `no typed hook implementation "${id}" in the runtime channel`);
+  }
+  const registration = (plugin.contributes?.hooks ?? []).find((h) => h.id === id);
+  if (!registration) {
+    fail(plugin, `typed hook "${id}" has no metadata entry in contributes.hooks`);
+  }
+  const input = {
+    event: registration.event,
+    toolInput: {},
+    filePaths: [],
+    projectRoot: "/tmp/testkit-project",
+    taskId: "testkit-task",
+    ...mockInput
+  };
+  const result = await implementation(input);
+  if (result?.decision !== "allow" && result?.decision !== "block") {
+    fail(plugin, `typed hook "${id}" returned decision "${result?.decision}" \u2014 must be "allow" or "block"`);
+  }
+  if (result.reason !== undefined && typeof result.reason !== "string") {
+    fail(plugin, `typed hook "${id}" returned a non-string "reason"`);
+  }
+  if (result.systemMessage !== undefined && typeof result.systemMessage !== "string") {
+    fail(plugin, `typed hook "${id}" returned a non-string "systemMessage"`);
+  }
+  return result;
+}
+
+// packages/plugin-testkit/src/index.ts
+function pluginContractTests(plugin) {
+  describe(`plugin contract: ${plugin.name}@${plugin.version}`, () => {
+    it("conforms to the RigPlugin schema", () => {
+      expect(() => Schema.decodeUnknownSync(RigPluginSchema)(plugin)).not.toThrow();
+    });
+    it("declares a non-empty name", () => {
+      expect(plugin.name).toBeTruthy();
+      expect(plugin.name.length).toBeGreaterThan(0);
+    });
+    it("declares a semver-ish version", () => {
+      expect(plugin.version).toMatch(/^\d+\.\d+\.\d+/);
+    });
+    it("registration ids are unique within each contribution type", () => {
+      const c = plugin.contributes;
+      if (!c)
+        return;
+      const types = [
+        ["validators", c.validators],
+        ["hooks", c.hooks],
+        ["skills", c.skills],
+        ["repoSources", c.repoSources],
+        ["agentRoles", c.agentRoles],
+        ["taskFieldSchemas", c.taskFieldSchemas],
+        ["taskSources", c.taskSources],
+        ["cliCommands", c.cliCommands]
+      ];
+      for (const [name, items] of types) {
+        if (!items)
+          continue;
+        const ids = items.map((i) => i.id);
+        const unique = new Set(ids);
+        expect(unique.size, `${name} had duplicate ids`).toBe(ids.length);
+      }
+    });
+    it("registration ids are namespaced (contain a ':' separator)", () => {
+      const c = plugin.contributes;
+      if (!c)
+        return;
+      const allIds = [
+        ...c.validators ?? [],
+        ...c.hooks ?? [],
+        ...c.skills ?? [],
+        ...c.repoSources ?? [],
+        ...c.agentRoles ?? [],
+        ...c.taskFieldSchemas ?? [],
+        ...c.taskSources ?? [],
+        ...c.cliCommands ?? []
+      ].map((i) => i.id);
+      for (const id of allIds) {
+        expect(id, `id "${id}" should be namespaced like "plugin-name:local-id"`).toMatch(/^[a-z][a-z0-9-]*:[a-z0-9][a-z0-9-:]*$/i);
+      }
+    });
+  });
+}
+function expectContribution(plugin, kind) {
+  const c = plugin.contributes;
+  if (!c)
+    throw new Error(`plugin "${plugin.name}" has no contributes block`);
+  const arr = c[kind];
+  if (!arr || arr.length === 0) {
+    throw new Error(`plugin "${plugin.name}" contributes no ${String(kind)}`);
+  }
+}
+export {
+  testValidatorContext,
+  testHook,
+  pluginContractTests,
+  expectTaskSourceRuntime,
+  expectContribution
+};

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@h-rig/plugin-testkit",
+  "version": "0.0.6-alpha.79",
+  "type": "module",
+  "description": "Rig package",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "main": "./dist/src/index.js",
+  "module": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "dependencies": {
+    "@rig/contracts": "npm:@h-rig/contracts@0.0.6-alpha.79",
+    "@rig/core": "npm:@h-rig/core@0.0.6-alpha.79",
+    "effect": "4.0.0-beta.78",
+    "vitest": "^4.0.0"
+  }
+}