@timidan/rite 0.1.0

package/src/instrument/auto-adapter.js

@@ -0,0 +1,237 @@
+/**
+ * src/instrument/auto-adapter.js — Auto-adapter generator.
+ *
+ * Given a JS/TS module that exports named functions, wraps each target entry
+ * and sink with lightweight instrumentation — no code modification needed.
+ *
+ * How it works:
+ *   1. Dynamically imports the target module.
+ *   2. Wraps named entry functions to capture call arguments.
+ *   3. Wraps the named sink function to record every invocation.
+ *   4. Exposes runCase(caseSpec) using the same adapter contract as rite.adapter.mjs.
+ *
+ * Limitations:
+ *   - Works for ES modules and CJS modules with named exports.
+ *   - The sink must be exported OR accessible via a state object returned by a factory.
+ *   - Does not handle async generator patterns or prototype-chain dispatch.
+ *   - Does not instrument code behind dynamic require() or conditional imports.
+ *   - For complex services (dependency injection, class hierarchies), a manual
+ *     adapter is still recommended.
+ *
+ * Usage (programmatic):
+ *   import { generateAdapter } from './auto-adapter.js';
+ *   const adapter = await generateAdapter({
+ *     modulePath: './src/service.js',
+ *     factoryFn: 'createService',   // optional: if module exports a factory
+ *     factoryArgs: [{ orders: [...] }],
+ *     entries: ['customerRefund', 'supportRefund'],
+ *     sink: 'issueRefund',          // name to detect in call stack / exports
+ *     snapshotFn: 'snapshot',       // optional: for before/after state
+ *   });
+ *   const report = await verify(config, adapter);
+ *
+ * Usage (CLI):
+ *   rite instrument --module ./src/service.js \
+ *                   --factory createService \
+ *                   --entries customerRefund,supportRefund \
+ *                   --sink issueRefund \
+ *                   --snapshot snapshot \
+ *                   --out examples/generated/rite.adapter.mjs
+ */
+
+import { pathToFileURL } from 'node:url';
+import { writeFileSync } from 'node:fs';
+
+// ------------------------------------------------------------------ //
+// Effect schema registry                                               //
+// ------------------------------------------------------------------ //
+// Registered sink schemas validate that effects match before comparison.
+// See src/instrument/effect-schema.js for the full registry.
+
+/**
+ * @typedef {{
+ *   modulePath: string,
+ *   factoryFn?: string,
+ *   factoryArgs?: unknown[],
+ *   entries: string[],
+ *   sink: string,
+ *   snapshotFn?: string,
+ *   seedBuilder?: (caseSpec: object) => object[],
+ * }} InstrumentOptions
+ */
+
+/**
+ * Generate a live adapter object (not a file) by wrapping a loaded module.
+ * @param {InstrumentOptions} opts
+ * @returns {Promise<{ runCase: (caseSpec: object) => Promise<object> }>}
+ */
+export async function generateAdapter(opts) {
+  const { modulePath, factoryFn, factoryArgs = [], entries, sink, snapshotFn, seedBuilder } = opts;
+
+  const mod = await import(pathToFileURL(modulePath).href);
+
+  return {
+    /**
+     * runCase — conforms to the rite adapter contract.
+     */
+    async runCase(caseSpec) {
+      const { path: entryName, actor, input } = caseSpec;
+
+      if (!entries.includes(entryName)) {
+        throw new Error(`Entry "${entryName}" not in instrumented entries: ${entries.join(', ')}`);
+      }
+
+      // Build fixture args — use seedBuilder if provided, else empty
+      const seeds = seedBuilder ? seedBuilder(caseSpec) : [];
+
+      // Create a fresh service instance per case
+      let instance;
+      const capturedSinkCalls = [];
+
+      if (factoryFn) {
+        const factory = mod[factoryFn];
+        if (typeof factory !== 'function')
+          throw new Error(`Factory "${factoryFn}" not found in module`);
+        instance = factory(...(seeds.length ? [{ orders: seeds }, ...factoryArgs.slice(1)] : factoryArgs));
+      } else {
+        // Module-level exports: wrap directly
+        instance = mod;
+      }
+
+      // Wrap the sink to capture calls
+      const originalSink = instance[sink];
+      if (typeof originalSink === 'function') {
+        instance[sink] = function (...args) {
+          const result = originalSink.apply(this, args);
+          capturedSinkCalls.push({ args, result });
+          return result;
+        };
+      }
+      // Note: if sink is a private closure (most common case), use snapshotFn to infer effects.
+
+      const entryFn = instance[entryName];
+      if (typeof entryFn !== 'function')
+        throw new Error(`Entry "${entryName}" not found on instance`);
+
+      // Snapshot before
+      const snapshotBefore = snapshotFn && typeof instance[snapshotFn] === 'function'
+        ? instance[snapshotFn]()
+        : null;
+      const eventsBefore = snapshotBefore?.events?.length ?? 0;
+
+      // Call entry
+      const result = entryFn.call(instance, input, { actorId: actor });
+
+      // Snapshot after
+      const snapshotAfter = snapshotFn && typeof instance[snapshotFn] === 'function'
+        ? instance[snapshotFn]()
+        : null;
+      const eventsAfter = snapshotAfter?.events?.length ?? 0;
+
+      // Derive effects from snapshot delta (works for private sinks)
+      const newEvents = snapshotAfter?.events
+        ? snapshotAfter.events.slice(eventsBefore)
+        : capturedSinkCalls.map(c => c.args[0] ?? c.args);
+
+      const effects = newEvents.map(({ refundId: _rid, ...rest }) => rest);
+
+      const orderId = input?.orderId;
+      const stateBefore = snapshotBefore?.orders?.find(o => o.id === orderId) ?? null;
+      const stateAfter  = snapshotAfter?.orders?.find(o => o.id === orderId) ?? null;
+      const stateChanged = JSON.stringify(stateBefore) !== JSON.stringify(stateAfter);
+
+      return {
+        decision: result?.ok === true ? 'allow' : 'deny',
+        effects,
+        stateBefore,
+        stateAfter,
+        stateChanged,
+      };
+    },
+  };
+}
+
+// ------------------------------------------------------------------ //
+// File generator — write a static adapter file                        //
+// ------------------------------------------------------------------ //
+
+/**
+ * Generate and write a rite.adapter.mjs file for a given module.
+ * The generated file is a fully self-contained adapter that can be committed.
+ * @param {InstrumentOptions & { outPath: string, relativeModulePath: string }} opts
+ */
+export function writeAdapterFile(opts) {
+  const { entries, sink, snapshotFn, factoryFn, outPath, relativeModulePath } = opts;
+
+  const importLine = factoryFn
+    ? `import { ${factoryFn} } from '${relativeModulePath}';`
+    : `import * as mod from '${relativeModulePath}';`;
+
+  const instanceExpr = factoryFn
+    ? `${factoryFn}({ orders: seedsForCase(input.orderId) })`
+    : `mod`;
+
+  const snapshotBefore = snapshotFn
+    ? `const snapBefore = instance.${snapshotFn}();`
+    : `const snapBefore = { events: [], orders: [] };`;
+
+  const snapshotAfter = snapshotFn
+    ? `const snapAfter = instance.${snapshotFn}();`
+    : `const snapAfter = { events: [], orders: [] };`;
+
+  const entryDispatch = entries.map(e =>
+    `  if (entryName === '${e}') result = instance.${e}(input, { actorId: actor });`
+  ).join('\n');
+
+  const content = `/**
+ * rite.adapter.mjs — Auto-generated by \`rite instrument\`.
+ * Edit seed definitions and the SEEDS map to match your fixtures.
+ * Generated: ${new Date().toISOString()}
+ */
+
+${importLine}
+
+// TODO: populate SEEDS with your fixture data.
+const SEEDS = {
+  'example-id': {
+    id: 'example-id',
+    ownerId: 'actor-owner',
+    paymentStatus: 'paid',
+    amountCents: 1000,
+    currency: 'USD',
+    refunded: false,
+  },
+};
+
+function seedsForCase(resourceId) {
+  const seed = SEEDS[resourceId];
+  if (!seed) throw new Error(\`No seed for: \${resourceId}\`);
+  return [{ ...seed }];
+}
+
+export async function runCase(caseSpec) {
+  const { path: entryName, actor, input } = caseSpec;
+  const instance = ${instanceExpr};
+  ${snapshotBefore}
+  let result;
+${entryDispatch}
+  else throw new Error(\`Unknown entry: \${entryName}\`);
+  ${snapshotAfter}
+  const newEvents = snapAfter.events.slice(snapBefore.events.length);
+  const effects = newEvents.map(({ refundId: _rid, ...rest }) => rest);
+  const orderId = input?.orderId ?? input?.resourceId;
+  const stateBefore = snapBefore.orders?.find(o => o.id === orderId) ?? null;
+  const stateAfter  = snapAfter.orders?.find(o => o.id === orderId) ?? null;
+  const stateChanged = JSON.stringify(stateBefore) !== JSON.stringify(stateAfter);
+  return {
+    decision: result?.ok === true ? 'allow' : 'deny',
+    effects,
+    stateBefore,
+    stateAfter,
+    stateChanged,
+  };
+}
+`;
+
+  writeFileSync(outPath, content, 'utf-8');
+}

package/src/instrument/effect-schema.js

@@ -0,0 +1,168 @@
+/**
+ * src/instrument/effect-schema.js — Typed effect registry.
+ *
+ * Defines named sink event schemas. The engine validates adapter-reported
+ * effects against the registered schema before structural comparison.
+ * This prevents two adapters describing the same event differently from
+ * both passing silently.
+ *
+ * Schema format:
+ *   { field: 'type' | ['type', required?] }
+ * Types: 'string' | 'number' | 'boolean' | 'object' | 'any'
+ *
+ * Register your schema in rite.config.json under "effectSchema":
+ *   "effectSchema": "refund-event"
+ *
+ * Or inline in config:
+ *   "effectSchema": {
+ *     "orderId":    "string",
+ *     "actorId":    "string",
+ *     "amountCents": "number",
+ *     "currency":   "string"
+ *   }
+ */
+
+// ------------------------------------------------------------------ //
+// Built-in schemas                                                     //
+// ------------------------------------------------------------------ //
+
+/** @type {Record<string, Record<string, string | [string, boolean]>>} */
+const BUILT_IN_SCHEMAS = {
+  'refund-event': {
+    orderId:     'string',
+    actorId:     'string',
+    amountCents: 'number',
+    currency:    'string',
+  },
+  'transfer-event': {
+    fromAccountId: 'string',
+    toAccountId:   'string',
+    amountCents:   'number',
+    currency:      'string',
+  },
+  'permission-grant': {
+    subjectId:   'string',
+    resourceId:  'string',
+    permission:  'string',
+    grantedBy:   'string',
+  },
+};
+
+// ------------------------------------------------------------------ //
+// Validator                                                            //
+// ------------------------------------------------------------------ //
+
+/**
+ * Resolve a schema from either a registered name or an inline object.
+ * @param {string | Record<string,string> | undefined} schemaRef
+ * @returns {Record<string,string> | null}
+ */
+export function resolveSchema(schemaRef) {
+  if (!schemaRef) return null;
+  if (typeof schemaRef === 'string') return BUILT_IN_SCHEMAS[schemaRef] ?? null;
+  if (typeof schemaRef === 'object') return schemaRef;
+  return null;
+}
+
+/**
+ * Validate one effect object against a schema.
+ * Returns an array of violation strings (empty = valid).
+ * @param {object} effect
+ * @param {Record<string,string>} schema
+ * @param {string} context — for error messages
+ * @returns {string[]}
+ */
+export function validateEffect(effect, schema, context = 'effect') {
+  const violations = [];
+  for (const [field, typeSpec] of Object.entries(schema)) {
+    const [expectedType, required = true] = Array.isArray(typeSpec) ? typeSpec : [typeSpec, true];
+    const value = /** @type {Record<string,unknown>} */ (effect)[field];
+    if (value === undefined || value === null) {
+      if (required) violations.push(`${context}.${field}: required field missing`);
+      continue;
+    }
+    if (expectedType === 'any') continue;
+    const actualType = typeof value;
+    if (actualType !== expectedType)
+      violations.push(`${context}.${field}: expected ${expectedType}; got ${actualType} (${JSON.stringify(value)})`);
+  }
+  // Reject unknown fields — adapters must not smuggle extra data
+  for (const key of Object.keys(effect)) {
+    if (!(key in schema))
+      violations.push(`${context}.${key}: unexpected field not in schema`);
+  }
+  return violations;
+}
+
+/**
+ * Validate all effects in a case result against the config schema.
+ * Returns all violations across all effects.
+ * @param {object[]} effects
+ * @param {string | Record<string,string> | undefined} schemaRef
+ * @returns {string[]}
+ */
+export function validateEffects(effects, schemaRef) {
+  const schema = resolveSchema(schemaRef);
+  if (!schema || !Array.isArray(effects)) return [];
+  const violations = [];
+  for (let i = 0; i < effects.length; i++) {
+    violations.push(...validateEffect(effects[i], schema, `effects[${i}]`));
+  }
+  return violations;
+}
+
+/** @returns {string[]} Names of all built-in schemas */
+export function listSchemas() {
+  return Object.keys(BUILT_IN_SCHEMAS);
+}
+
+// ------------------------------------------------------------------ //
+// Unified effect comparison                                            //
+// ------------------------------------------------------------------ //
+
+/**
+ * Compare observed effects against expected effects and an optional schema.
+ * This is the single authoritative comparison used by both the engine and
+ * the browser runner — neither re-implements this logic.
+ *
+ * Checks (in order):
+ *   1. Count mismatch — a denial that produces effects always FAIL
+ *   2. Per-field structural match against expected values
+ *   3. Schema validation (if schemaRef provided)
+ *
+ * @param {object[]} observed
+ * @param {object[]} expected
+ * @param {string | Record<string,string> | undefined} [schemaRef]
+ * @returns {string[]} failure strings (empty = pass)
+ */
+export function compareEffects(observed, expected, schemaRef) {
+  const failures = [];
+  const obs = Array.isArray(observed) ? observed : [];
+  const exp = Array.isArray(expected) ? expected : [];
+
+  // 1. Count
+  if (obs.length !== exp.length) {
+    failures.push(
+      `effects count: expected ${exp.length}; observed ${obs.length}` +
+      (obs.length > 0 ? ` (first: ${JSON.stringify(obs[0])})` : '')
+    );
+  }
+
+  // 2. Per-field structural match
+  for (let i = 0; i < exp.length; i++) {
+    const eEff = exp[i];
+    const oEff = obs[i];
+    if (!oEff) break; // already caught by count check
+    for (const key of Object.keys(eEff)) {
+      if (eEff[key] !== oEff[key])
+        failures.push(`effects[${i}].${key}: expected ${JSON.stringify(eEff[key])}; observed ${JSON.stringify(oEff[key])}`);
+    }
+  }
+
+  // 3. Schema validation
+  if (schemaRef && obs.length > 0) {
+    failures.push(...validateEffects(obs, schemaRef));
+  }
+
+  return failures;
+}

package/src/mcp/server.js

@@ -0,0 +1,185 @@
+/**
+ * src/mcp/server.js — Local MCP stdio server for Rite.
+ *
+ * Tools:
+ *   rite_analyze  — Read configured rule and path scope from a config file
+ *   rite_verify   — Run verification using the same core engine as the CLI
+ *   rite_report   — Read and render a saved report file
+ *
+ * Stdout carries MCP protocol messages only. Logs go to stderr.
+ * Workspace and file path arguments are validated; no generic shell execution.
+ *
+ * Start: node src/cli/rite.js mcp  (or rite mcp)
+ * Test:  npx @modelcontextprotocol/inspector node src/cli/rite.js mcp
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { validateConfig, verify, ENGINE_VERSION } from '../core/engine.js';
+import { loadAdapterFromConfig } from '../core/loader.js';
+
+// ------------------------------------------------------------------ //
+// Helpers shared with CLI                                              //
+// ------------------------------------------------------------------ //
+
+function safeJson(filePath) {
+  try {
+    return { ok: true, data: JSON.parse(readFileSync(filePath, 'utf-8')) };
+  } catch (e) {
+    return { ok: false, error: e.message };
+  }
+}
+
+function renderReportText(report) {
+  const lines = [];
+  lines.push(`Rite v${ENGINE_VERSION} — ${report.ruleId}`);
+  lines.push(`Rule: ${report.rule}`);
+  lines.push(`Status: ${report.status}  Generated: ${report.generatedAt}`);
+  lines.push('');
+  for (const r of report.results) {
+    const icon = r.status === 'PASS' ? '✓' : r.status === 'FAIL' ? '✗' : '!';
+    lines.push(`${icon} ${r.status.padEnd(5)} [${r.path}] ${r.id}`);
+    if (r.failures?.length) {
+      for (const f of r.failures) lines.push(`    ${f}`);
+    }
+    if (r.error) lines.push(`    ERROR: ${r.error.split('\n')[0]}`);
+  }
+  const total  = report.results.length;
+  const passed = report.results.filter(r => r.status === 'PASS').length;
+  lines.push('');
+  lines.push(`${report.status}: ${passed}/${total} passed`);
+  return lines.join('\n');
+}
+
+// ------------------------------------------------------------------ //
+// Server                                                               //
+// ------------------------------------------------------------------ //
+
+export async function startMcpServer() {
+  const server = new McpServer({
+    name: 'rite',
+    version: ENGINE_VERSION,
+  });
+
+  // ---- rite_analyze ------------------------------------------------ //
+  server.tool(
+    'rite_analyze',
+    'Read a Rite config file and return its rule, configured entry paths, and case summary.',
+    {
+      config: z.string().describe('Absolute or relative path to rite.config.json'),
+    },
+    async ({ config: configArg }) => {
+      const configPath = resolve(configArg);
+      if (!existsSync(configPath)) {
+        return { content: [{ type: 'text', text: `Config not found: ${configPath}` }], isError: true };
+      }
+      const parsed = safeJson(configPath);
+      if (!parsed.ok) {
+        return { content: [{ type: 'text', text: `Failed to parse config: ${parsed.error}` }], isError: true };
+      }
+      const errs = validateConfig(parsed.data);
+      if (errs.length) {
+        return { content: [{ type: 'text', text: `Config invalid:\n${errs.join('\n')}` }], isError: true };
+      }
+      const cfg = parsed.data;
+      const summary = [
+        `ruleId: ${cfg.ruleId}`,
+        `rule: ${cfg.rule}`,
+        '',
+        'Configured paths:',
+        ...cfg.paths.map(p => `  ${p.entry} → ${p.sink}  (${p.source})`),
+        '',
+        `Cases (${cfg.cases.length}):`,
+        ...cfg.cases.map(c => `  ${c.id}  [${c.path}]  actor=${c.actor}  expected=${c.expected.decision}`),
+      ].join('\n');
+      return { content: [{ type: 'text', text: summary }] };
+    }
+  );
+
+  // ---- rite_verify ------------------------------------------------- //
+  server.tool(
+    'rite_verify',
+    'Run Rite verification using the same core engine as the CLI. Returns the full report as JSON.',
+    {
+      config: z.string().describe('Absolute or relative path to rite.config.json'),
+      out: z.string().optional().describe('Optional path to write the JSON report'),
+    },
+    async ({ config: configArg, out: outArg }) => {
+      const configPath = resolve(configArg);
+      if (!existsSync(configPath)) {
+        return { content: [{ type: 'text', text: `Config not found: ${configPath}` }], isError: true };
+      }
+      const parsed = safeJson(configPath);
+      if (!parsed.ok) {
+        return { content: [{ type: 'text', text: `Failed to parse config: ${parsed.error}` }], isError: true };
+      }
+      const errs = validateConfig(parsed.data);
+      if (errs.length) {
+        return { content: [{ type: 'text', text: `Config invalid:\n${errs.join('\n')}` }], isError: true };
+      }
+
+      const cfg = parsed.data;
+      const loaded = await loadAdapterFromConfig(cfg, configPath);
+      if (!loaded.ok) {
+        return { content: [{ type: 'text', text: loaded.error }], isError: true };
+      }
+      const { adapter } = loaded;
+
+      let report;
+      try {
+        report = await verify(cfg, adapter, { configPath });
+      } catch (e) {
+        return { content: [{ type: 'text', text: `Engine error: ${e.message}` }], isError: true };
+      }
+
+      if (outArg) {
+        try {
+          writeFileSync(resolve(outArg), JSON.stringify(report, null, 2), 'utf-8');
+        } catch (e) {
+          process.stderr.write(`rite-mcp: could not write report: ${e.message}\n`);
+        }
+      }
+
+      const text = renderReportText(report);
+      const json = JSON.stringify(report, null, 2);
+      return {
+        content: [
+          { type: 'text', text },
+          { type: 'text', text: '\n--- JSON ---\n' + json },
+        ],
+      };
+    }
+  );
+
+  // ---- rite_report ------------------------------------------------- //
+  server.tool(
+    'rite_report',
+    'Read and render a saved Rite report JSON file.',
+    {
+      file: z.string().describe('Absolute or relative path to a Rite report JSON file'),
+    },
+    async ({ file }) => {
+      const filePath = resolve(file);
+      if (!existsSync(filePath)) {
+        return { content: [{ type: 'text', text: `Report not found: ${filePath}` }], isError: true };
+      }
+      const parsed = safeJson(filePath);
+      if (!parsed.ok) {
+        return { content: [{ type: 'text', text: `Failed to parse report: ${parsed.error}` }], isError: true };
+      }
+      const report = parsed.data;
+      if (!report.results || !report.status) {
+        return { content: [{ type: 'text', text: 'File does not look like a Rite report.' }], isError: true };
+      }
+      return { content: [{ type: 'text', text: renderReportText(report) }] };
+    }
+  );
+
+  // Start transport
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write(`rite-mcp: server started (Rite v${ENGINE_VERSION})\n`);
+}