@ontrails/warden 1.0.0-beta.0

package/dist/rules/valid-detour-refs.js

@@ -0,0 +1,116 @@
+import { collectTrailIds } from './specs.js';
+const trackBraces = (line, state) => {
+    for (const ch of line) {
+        if (ch === '{') {
+            state.depth += 1;
+            state.found = true;
+        }
+        if (ch === '}') {
+            state.depth -= 1;
+        }
+    }
+};
+const collectArrayText = (lines, start) => {
+    let text = '';
+    for (let k = start; k < lines.length && k < start + 20; k += 1) {
+        const line = lines[k];
+        if (!line) {
+            continue;
+        }
+        text += `${line}\n`;
+        if (text.includes(']')) {
+            break;
+        }
+    }
+    return text;
+};
+const findMissingDetourTargets = (text, knownIds) => {
+    const missing = [];
+    for (const m of text.matchAll(/target\s*:\s*["'`]([^"'`]+)["'`]/g)) {
+        const [, id] = m;
+        if (id && !knownIds.has(id)) {
+            missing.push(id);
+        }
+    }
+    return missing;
+};
+const findMissingPlainDetours = (text, knownIds) => {
+    const missing = [];
+    const cleaned = text.replaceAll(/target\s*:\s*["'`][^"'`]+["'`]/g, '');
+    for (const m of cleaned.matchAll(/["'`]([^"'`]+)["'`]/g)) {
+        const [, id] = m;
+        if (id && id.includes('.') && !knownIds.has(id)) {
+            missing.push(id);
+        }
+    }
+    return missing;
+};
+const findAllMissingDetours = (text, knownIds) => [
+    ...findMissingDetourTargets(text, knownIds),
+    ...findMissingPlainDetours(text, knownIds),
+];
+const addMissingDetourDiagnostics = (specLine, j, lines, trailId, lineNum, filePath, knownIds, diagnostics) => {
+    if (!/\bdetours\s*:/.test(specLine)) {
+        return;
+    }
+    for (const targetId of findAllMissingDetours(collectArrayText(lines, j), knownIds)) {
+        diagnostics.push({
+            filePath,
+            line: lineNum,
+            message: `Trail "${trailId}" has detour targeting "${targetId}" which is not defined.`,
+            rule: 'valid-detour-refs',
+            severity: 'error',
+        });
+    }
+};
+const scanTrailDetours = (lines, startIndex, trailId, filePath, knownIds, diagnostics) => {
+    const braceState = { depth: 0, found: false };
+    for (let j = startIndex; j < lines.length && j < startIndex + 200; j += 1) {
+        const specLine = lines[j];
+        if (!specLine) {
+            continue;
+        }
+        trackBraces(specLine, braceState);
+        addMissingDetourDiagnostics(specLine, j, lines, trailId, startIndex + 1, filePath, knownIds, diagnostics);
+        if (braceState.found && braceState.depth <= 0) {
+            break;
+        }
+    }
+};
+const processLine = (line, i, lines, filePath, knownIds, diagnostics) => {
+    const trailMatch = line.match(/\btrail\s*\(\s*["'`]([^"'`]+)["'`]/);
+    if (!trailMatch) {
+        return;
+    }
+    const [, trailId] = trailMatch;
+    if (!trailId) {
+        return;
+    }
+    scanTrailDetours(lines, i, trailId, filePath, knownIds, diagnostics);
+};
+const checkDetourRefs = (sourceCode, filePath, knownIds) => {
+    const diagnostics = [];
+    const lines = sourceCode.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i];
+        if (line) {
+            processLine(line, i, lines, filePath, knownIds, diagnostics);
+        }
+    }
+    return diagnostics;
+};
+/**
+ * Checks that all trail IDs referenced in `detours` declarations exist.
+ */
+export const validDetourRefs = {
+    check(sourceCode, filePath) {
+        return checkDetourRefs(sourceCode, filePath, collectTrailIds(sourceCode));
+    },
+    checkWithContext(sourceCode, filePath, context) {
+        return checkDetourRefs(sourceCode, filePath, context.knownTrailIds);
+    },
+    description: 'Ensure all detour target trail IDs reference defined trails.',
+    name: 'valid-detour-refs',
+    severity: 'error',
+};
+//# sourceMappingURL=valid-detour-refs.js.map

package/dist/rules/valid-detour-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"valid-detour-refs.js","sourceRoot":"","sources":["../../src/rules/valid-detour-refs.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@ontrails/warden",
+  "version": "1.0.0-beta.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint ./src",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "devDependencies": {
+    "@oxc-project/types": "^0.122.0",
+    "oxc-parser": "^0.121.0",
+    "zod": "catalog:"
+  },
+  "peerDependencies": {
+    "@ontrails/core": "workspace:*",
+    "@ontrails/schema": "workspace:*"
+  }
+}

package/src/__tests__/cli.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { formatWardenReport, runWarden } from '../cli.js';
+
+const makeTempDir = (): string => {
+  const dir = join(
+    tmpdir(),
+    `warden-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  );
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+describe('runWarden', () => {
+  test('produces a report with diagnostics for bad code', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'bad.ts'),
+        `trail("entity.show", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      expect(report.errorCount).toBeGreaterThan(0);
+      expect(report.passed).toBe(false);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('passes for clean code', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'good.ts'),
+        `trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      expect(report.errorCount).toBe(0);
+      expect(report.passed).toBe(true);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('lintOnly skips drift check', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(join(dir, 'empty.ts'), 'export {}');
+      const report = await runWarden({ lintOnly: true, rootDir: dir });
+      expect(report.drift).toBeNull();
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('driftOnly skips lint', async () => {
+    const dir = makeTempDir();
+    try {
+      // Even with bad code, driftOnly should produce 0 diagnostics
+      writeFileSync(
+        join(dir, 'bad.ts'),
+        `trail("x", { implementation: async () => { throw new Error("x"); } })`
+      );
+      const report = await runWarden({ driftOnly: true, rootDir: dir });
+      expect(report.diagnostics.length).toBe(0);
+      expect(report.drift).not.toBeNull();
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('uses project context for detour references across files', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'show.ts'),
+        `trail("entity.show", {
+  detours: { NotFoundError: ["entity.search"] },
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`
+      );
+      writeFileSync(
+        join(dir, 'search.ts'),
+        `trail("entity.search", {
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      const detourRefErrors = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'valid-detour-refs'
+      );
+
+      expect(detourRefErrors).toHaveLength(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('flags throws in detour targets declared in another file', async () => {
+    const dir = makeTempDir();
+    try {
+      writeFileSync(
+        join(dir, 'show.ts'),
+        `trail("entity.show", {
+  detours: { NotFoundError: ["entity.search"] },
+  implementation: async (input, ctx) => {
+    return Result.ok(data);
+  }
+})`
+      );
+      writeFileSync(
+        join(dir, 'search.ts'),
+        `trail("entity.search", {
+  implementation: async (input, ctx) => {
+    throw new Error("boom");
+  }
+})`
+      );
+
+      const report = await runWarden({ rootDir: dir });
+      const detourThrowRules = report.diagnostics.filter(
+        (diagnostic) => diagnostic.rule === 'no-throw-in-detour-target'
+      );
+
+      expect(detourThrowRules).toHaveLength(1);
+      expect(detourThrowRules[0]?.message).toContain('entity.search');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});
+
+describe('formatWardenReport', () => {
+  test('formats a clean report', () => {
+    const output = formatWardenReport({
+      diagnostics: [],
+      drift: { committedHash: null, currentHash: 'stub', stale: false },
+      errorCount: 0,
+      passed: true,
+      warnCount: 0,
+    });
+    expect(output).toContain('Warden Report');
+    expect(output).toContain('Lint: clean');
+    expect(output).toContain('Drift: clean');
+    expect(output).toContain('Result: PASS');
+  });
+
+  test('formats a report with errors', () => {
+    const output = formatWardenReport({
+      diagnostics: [
+        {
+          filePath: 'src/trails/entity.ts',
+          line: 3,
+          message: 'Do not throw inside implementation.',
+          rule: 'no-throw-in-implementation',
+          severity: 'error',
+        },
+      ],
+      drift: { committedHash: null, currentHash: 'stub', stale: false },
+      errorCount: 1,
+      passed: false,
+      warnCount: 0,
+    });
+    expect(output).toContain('1 errors');
+    expect(output).toContain('Result: FAIL');
+    expect(output).toContain('entity.ts:3');
+  });
+
+  test('formats a report with stale drift', () => {
+    const output = formatWardenReport({
+      diagnostics: [],
+      drift: { committedHash: 'abc', currentHash: 'def', stale: true },
+      errorCount: 0,
+      passed: false,
+      warnCount: 0,
+    });
+    expect(output).toContain('surface.lock is stale');
+    expect(output).toContain('Result: FAIL');
+  });
+});

package/src/__tests__/drift.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { trail, topo, Result } from '@ontrails/core';
+import { hashSurfaceMap, generateSurfaceMap } from '@ontrails/schema';
+import { z } from 'zod';
+
+import { checkDrift } from '../drift.js';
+
+const makeTopo = () => {
+  const t = trail('test.hello', {
+    implementation: () => Result.ok({ greeting: 'hi' }),
+    input: z.object({ name: z.string() }),
+    output: z.object({ greeting: z.string() }),
+  });
+  return topo('test-app', { t });
+};
+
+const createTempDir = (): string => {
+  const dir = join(tmpdir(), `drift-test-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+  return dir;
+};
+
+describe('checkDrift', () => {
+  test('returns stale: false when no topo is provided', async () => {
+    const result = await checkDrift('/tmp');
+    expect(result.stale).toBe(false);
+    expect(result.currentHash).toBe('unknown');
+  });
+
+  test('returns stale: false when no lock file exists', async () => {
+    const dir = createTempDir();
+    try {
+      const result = await checkDrift(dir, makeTopo());
+      expect(result.stale).toBe(false);
+      expect(result.committedHash).toBeNull();
+      expect(result.currentHash.length).toBeGreaterThan(0);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('returns stale: false when lock matches current hash', async () => {
+    const dir = createTempDir();
+    try {
+      const tp = makeTopo();
+      const hash = hashSurfaceMap(generateSurfaceMap(tp));
+      writeFileSync(join(dir, 'surface.lock'), `${hash}\n`);
+
+      const result = await checkDrift(dir, tp);
+      expect(result.stale).toBe(false);
+      expect(result.committedHash).toBe(hash);
+      expect(result.currentHash).toBe(hash);
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+
+  test('returns stale: true when lock does not match', async () => {
+    const dir = createTempDir();
+    try {
+      writeFileSync(join(dir, 'surface.lock'), 'outdated-hash\n');
+
+      const result = await checkDrift(dir, makeTopo());
+      expect(result.stale).toBe(true);
+      expect(result.committedHash).toBe('outdated-hash');
+    } finally {
+      rmSync(dir, { force: true, recursive: true });
+    }
+  });
+});

package/src/__tests__/formatters.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { WardenReport } from '../cli.js';
+import {
+  formatGitHubAnnotations,
+  formatJson,
+  formatSummary,
+} from '../formatters.js';
+
+const cleanReport: WardenReport = {
+  diagnostics: [],
+  drift: { committedHash: 'abc', currentHash: 'abc', stale: false },
+  errorCount: 0,
+  passed: true,
+  warnCount: 0,
+};
+
+const reportWithDiagnostics: WardenReport = {
+  diagnostics: [
+    {
+      filePath: 'packages/core/src/result.ts',
+      line: 42,
+      message: 'Throw statement found in trail implementation',
+      rule: 'no-throw-in-implementation',
+      severity: 'error',
+    },
+    {
+      filePath: 'packages/core/src/trails.ts',
+      line: 15,
+      message: 'Trail "entity.show" has no output schema',
+      rule: 'require-output-schema',
+      severity: 'warn',
+    },
+  ],
+  drift: null,
+  errorCount: 1,
+  passed: false,
+  warnCount: 1,
+};
+
+const reportWithDrift: WardenReport = {
+  diagnostics: [],
+  drift: { committedHash: 'abc', currentHash: 'def', stale: true },
+  errorCount: 0,
+  passed: false,
+  warnCount: 0,
+};
+
+describe('formatGitHubAnnotations', () => {
+  test('produces empty string for clean report', () => {
+    expect(formatGitHubAnnotations(cleanReport)).toBe('');
+  });
+
+  test('maps error severity to ::error', () => {
+    const output = formatGitHubAnnotations(reportWithDiagnostics);
+    expect(output).toContain(
+      '::error file=packages/core/src/result.ts,line=42::no-throw-in-implementation:'
+    );
+  });
+
+  test('maps warn severity to ::warning', () => {
+    const output = formatGitHubAnnotations(reportWithDiagnostics);
+    expect(output).toContain(
+      '::warning file=packages/core/src/trails.ts,line=15::require-output-schema:'
+    );
+  });
+
+  test('emits drift as a single ::error annotation', () => {
+    const output = formatGitHubAnnotations(reportWithDrift);
+    expect(output).toContain('::error::drift: surface.lock is stale');
+  });
+
+  test('produces one line per diagnostic', () => {
+    const lines = formatGitHubAnnotations(reportWithDiagnostics)
+      .split('\n')
+      .filter(Boolean);
+    expect(lines).toHaveLength(2);
+  });
+});
+
+describe('formatJson', () => {
+  test('produces valid JSON', () => {
+    const parsed = JSON.parse(formatJson(cleanReport));
+    expect(parsed).toBeDefined();
+  });
+
+  test('includes passed status', () => {
+    const parsed = JSON.parse(formatJson(cleanReport));
+    expect(parsed.passed).toBe(true);
+  });
+
+  test('includes summary counts', () => {
+    const parsed = JSON.parse(formatJson(reportWithDiagnostics));
+    expect(parsed.summary).toEqual({
+      errors: 1,
+      suggestions: 0,
+      warnings: 1,
+    });
+  });
+
+  test('includes diagnostics array', () => {
+    const parsed = JSON.parse(formatJson(reportWithDiagnostics));
+    expect(parsed.diagnostics).toHaveLength(2);
+    expect(parsed.diagnostics[0].rule).toBe('no-throw-in-implementation');
+  });
+
+  test('includes null drift when absent', () => {
+    const parsed = JSON.parse(formatJson(reportWithDiagnostics));
+    expect(parsed.drift).toBeNull();
+  });
+
+  test('includes drift result when present', () => {
+    const parsed = JSON.parse(formatJson(reportWithDrift));
+    expect(parsed.drift.stale).toBe(true);
+  });
+});
+
+describe('formatSummary', () => {
+  test('includes markdown heading', () => {
+    expect(formatSummary(cleanReport)).toContain('## Warden Report');
+  });
+
+  test('shows PASS for clean report', () => {
+    expect(formatSummary(cleanReport)).toContain('**Result: PASS**');
+  });
+
+  test('shows FAIL for failing report', () => {
+    expect(formatSummary(reportWithDiagnostics)).toContain('**Result: FAIL**');
+  });
+
+  test('groups errors under ### Errors heading', () => {
+    const output = formatSummary(reportWithDiagnostics);
+    expect(output).toContain('### Errors');
+    expect(output).toContain('no-throw-in-implementation');
+  });
+
+  test('groups warnings under ### Warnings heading', () => {
+    const output = formatSummary(reportWithDiagnostics);
+    expect(output).toContain('### Warnings');
+    expect(output).toContain('require-output-schema');
+  });
+
+  test('includes file:line in backticks', () => {
+    const output = formatSummary(reportWithDiagnostics);
+    expect(output).toContain('`packages/core/src/result.ts:42`');
+  });
+
+  test('includes drift section when stale', () => {
+    const output = formatSummary(reportWithDrift);
+    expect(output).toContain('### Drift');
+    expect(output).toContain('surface.lock is stale');
+  });
+
+  test('omits drift section when clean', () => {
+    expect(formatSummary(cleanReport)).not.toContain('### Drift');
+  });
+});

package/src/__tests__/implementation-returns-result.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+
+import { implementationReturnsResult } from '../rules/implementation-returns-result.js';
+
+const TEST_FILE = 'test.ts';
+
+describe('implementation-returns-result', () => {
+  test('flags raw object return in trail implementation', () => {
+    const code = `
+trail("entity.show", {
+  implementation: async (input, ctx) => {
+    return { name: "foo" };
+  }
+})`;
+
+    const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.rule).toBe('implementation-returns-result');
+    expect(diagnostics[0]?.severity).toBe('error');
+  });
+
+  test('allows Result.ok() and returning ctx.follow() results', () => {
+    const code = `
+hike("entity.onboard", {
+  implementation: async (input, ctx) => {
+    const result = await ctx.follow("entity.create", input);
+    return result;
+  }
+})
+
+trail("entity.create", {
+  implementation: async (input, ctx) => Result.ok({ id: "123" })
+})`;
+
+    const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(0);
+  });
+
+  test('flags concise raw implementation bodies', () => {
+    const code = `
+trail("entity.create", {
+  implementation: async (input, ctx) => ({ id: "123" })
+})`;
+
+    const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(1);
+    expect(diagnostics[0]?.message).toContain('entity.create');
+  });
+
+  test('allows returning explicitly Result-typed local helpers', () => {
+    const code = `
+const buildDetail = (trailId: string): Result<object, Error> =>
+  Result.ok({ trailId });
+
+const buildDiff = async (): Promise<Result<object, Error>> =>
+  Result.ok({ breaking: [] });
+
+trail("survey", {
+  implementation: async (input, ctx) => {
+    if (input.diff) {
+      return await buildDiff();
+    }
+
+    return buildDetail(input.trailId);
+  }
+})`;
+
+    const diagnostics = implementationReturnsResult.check(code, TEST_FILE);
+
+    expect(diagnostics.length).toBe(0);
+  });
+});