@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/__tests__/valid-describe-refs.test.ts

@@ -57,4 +57,187 @@ trail("entity.show", {
 
     expect(diagnostics).toHaveLength(0);
   });
+
+  test('ignores @see tags embedded in unrelated string literals', () => {
+    const code = `
+const docs = "see also @see entity.ghost in the other doc";
+
+trail("entity.show", {
+  input: z.object({ query: z.string() }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('ignores @see tags inside template-literal payloads that mimic describe calls', () => {
+    const code = `
+const example = \`
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe("@see entity.ghost"),
+  }),
+})\`;
+`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('flags @see tags inside template-literal describe arguments', () => {
+    const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`Search query. @see entity.ghost\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.message).toContain('entity.ghost');
+  });
+
+  describe('template literals with expressions', () => {
+    test('detects @see refs with a leading interpolation', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`search for \${query}. @see entity.ghost\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0]?.message).toContain('entity.ghost');
+    });
+
+    test('detects @see refs across quasis separated by an interpolation', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`\${prefix} @see missing.trail\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0]?.message).toContain('missing.trail');
+    });
+
+    test('still detects @see refs across quasis containing escape sequences', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`path\\\\to\\\\docs. @see missing.trail\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0]?.message).toContain('missing.trail');
+    });
+
+    test('does not emit a phantom @see match when interpolation splits the marker', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`@s\${x}ee missing\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test('does not emit a phantom @see match across multiple interpolations', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`@s\${x}ee \${y} missing\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(0);
+    });
+
+    test('still matches @see when the marker is fully inside a single quasi', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`@see missing.trail \${x}\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(1);
+      expect(diagnostics[0]?.message).toContain('missing.trail');
+    });
+
+    test('does not diagnose when quasis contain no @see token', () => {
+      const code = `
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe(\`\${prefix}\${suffix}\`),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+      const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+      expect(diagnostics).toHaveLength(0);
+    });
+  });
+
+  test('ignores describe calls whose argument is not a string literal', () => {
+    const code = `
+const mapFn = (x) => x;
+stream.describe(() => mapFn);
+
+trail("entity.show", {
+  input: z.object({ query: z.string() }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(0);
+  });
+
+  test('does not treat legacy event declarations as valid trail refs', () => {
+    const code = `
+event("entity.updated", {
+  payload: z.object({ id: z.string() }),
+})
+
+trail("entity.show", {
+  input: z.object({
+    query: z.string().describe("Search query. @see entity.updated"),
+  }),
+  blaze: (input) => Result.ok(input),
+})`;
+
+    const diagnostics = validDescribeRefs.check(code, 'src/entity.ts');
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('valid-describe-refs');
+    expect(diagnostics[0]?.message).toContain('entity.updated');
+  });
 });

package/src/__tests__/valid-detour-contract.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, test } from 'bun:test';
+
+import { ConflictError, Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { validDetourContract } from '../rules/valid-detour-contract.js';
+
+const validTrail = trail('entity.save', {
+  blaze: () => Result.ok({ ok: true }),
+  detours: [
+    {
+      on: ConflictError,
+      recover: () => Result.ok({ ok: true }),
+    },
+  ],
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+describe('valid-detour-contract', () => {
+  test('passes for detours with an error constructor and callable recover', () => {
+    const diagnostics = validDetourContract.checkTopo(
+      topo('valid-detour-contract', { validTrail })
+    );
+
+    expect(diagnostics).toEqual([]);
+  });
+
+  test('flags detours with a non-constructor on value', () => {
+    const malformed = {
+      ...validTrail,
+      detours: [
+        {
+          on: 'ConflictError',
+          recover: () => Result.ok({ ok: true }),
+        },
+      ],
+    } as typeof validTrail;
+
+    const diagnostics = validDetourContract.checkTopo(
+      topo('invalid-on', { malformed } as Record<string, unknown>)
+    );
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('valid-detour-contract');
+    expect(diagnostics[0]?.message).toContain('error constructor');
+  });
+
+  test('flags detours with a non-callable recover value', () => {
+    const malformed = {
+      ...validTrail,
+      detours: [
+        {
+          on: ConflictError,
+          recover: 'not callable',
+        },
+      ],
+    } as typeof validTrail;
+
+    const diagnostics = validDetourContract.checkTopo(
+      topo('invalid-recover', { malformed } as Record<string, unknown>)
+    );
+
+    expect(diagnostics).toHaveLength(1);
+    expect(diagnostics[0]?.rule).toBe('valid-detour-contract');
+    expect(diagnostics[0]?.message).toContain('callable recover');
+  });
+
+  test('reports both issues when on and recover are malformed', () => {
+    const malformed = {
+      ...validTrail,
+      detours: [
+        {
+          on: 'ConflictError',
+          recover: 'not callable',
+        },
+      ],
+    } as typeof validTrail;
+
+    const diagnostics = validDetourContract.checkTopo(
+      topo('invalid-contract', { malformed } as Record<string, unknown>)
+    );
+
+    expect(diagnostics).toHaveLength(2);
+  });
+});

package/src/__tests__/warden-export-symmetry.test.ts

@@ -0,0 +1,251 @@
+import { resolve } from 'node:path';
+import { describe, expect, test } from 'bun:test';
+
+import { wardenRules, wardenTopoRules } from '../rules/index.js';
+import { registeredRuleNames } from '../rules/registry-names.js';
+import { wardenExportSymmetry } from '../rules/warden-export-symmetry.js';
+
+const SELF_RULE_NAME = 'warden-export-symmetry';
+
+// The rule anchors to this package's own on-disk `src/index.ts`. Tests must
+// use the same resolved path so the rule actually engages.
+const TARGET_FILE = resolve(
+  Bun.fileURLToPath(new URL('../index.ts', import.meta.url))
+);
+const UNRELATED_FILE = resolve(
+  Bun.fileURLToPath(new URL('../cli.ts', import.meta.url))
+);
+
+const kebabToCamel = (value: string): string =>
+  value.replaceAll(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+
+const allRuleNames = [...wardenRules.keys(), ...wardenTopoRules.keys()];
+
+const expectedTrailExports = allRuleNames
+  .map((name) => `${kebabToCamel(name)}Trail`)
+  .toSorted();
+
+const [sampleTrailExport = 'missingTrailExportSentinel'] = expectedTrailExports;
+const [sampleRuleName = 'missing-rule-sentinel'] = allRuleNames;
+const sampleRawRuleCamel = kebabToCamel(sampleRuleName);
+
+const buildIndexSource = (extraExports = '', skip: readonly string[] = []) => {
+  const skipSet = new Set(skip);
+  const rendered = expectedTrailExports
+    .filter((name) => !skipSet.has(name))
+    .map((name) => `  ${name},`)
+    .join('\n');
+  return `export {
+${rendered}
+} from './trails/index.js';
+${extraExports}
+`;
+};
+
+describe('warden-export-symmetry', () => {
+  describe('scope', () => {
+    test("only targets this package's own src/index.ts", () => {
+      const source = buildIndexSource();
+      const diagnostics = wardenExportSymmetry.check(source, UNRELATED_FILE);
+      expect(diagnostics).toEqual([]);
+    });
+
+    test('ignores a foreign packages/warden/src/index.ts in another repo', () => {
+      // Simulate a consumer repo that happens to have the same folder
+      // structure. A path suffix match would incorrectly engage the rule here
+      // and flood the consumer with bogus diagnostics. The rule reads source
+      // from its argument, not from disk, so no fs setup is needed — only the
+      // path-anchoring check runs against `foreignBarrel`.
+      const foreignBarrel = resolve(
+        '/tmp/warden-foreign-sim/packages/warden/src/index.ts'
+      );
+      const diagnostics = wardenExportSymmetry.check(
+        `export { ${sampleRawRuleCamel} } from './rules/index.js';\nexport * from './trails/index.js';\nexport default {};\n`,
+        foreignBarrel
+      );
+      expect(diagnostics).toEqual([]);
+    });
+
+    test('baseline: current warden barrel emits zero diagnostics', async () => {
+      const realPath = Bun.fileURLToPath(
+        new URL('../index.ts', import.meta.url)
+      );
+      const source = await Bun.file(realPath).text();
+      const diagnostics = wardenExportSymmetry.check(source, realPath);
+      expect(diagnostics).toEqual([]);
+    });
+
+    test('registry-names snapshot matches the live registry', () => {
+      const live = new Set([...wardenRules.keys(), ...wardenTopoRules.keys()]);
+      const snapshot = new Set([...registeredRuleNames, SELF_RULE_NAME]);
+      const missingFromSnapshot = [...live].filter((n) => !snapshot.has(n));
+      const extraInSnapshot = [...snapshot].filter((n) => !live.has(n));
+      expect(missingFromSnapshot).toEqual([]);
+      expect(extraInSnapshot).toEqual([]);
+    });
+  });
+
+  describe('symmetry diagnostics', () => {
+    test('fires when a registry entry has no matching trail export', () => {
+      const source = buildIndexSource('', [sampleTrailExport]);
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const missing = diagnostics.filter((d) =>
+        d.message.includes(`missing trail export "${sampleTrailExport}"`)
+      );
+      expect(missing.length).toBe(1);
+      expect(missing[0]?.severity).toBe('error');
+    });
+
+    test('fires when a *Trail export has no matching registry entry', () => {
+      const source = buildIndexSource(
+        `export { fictitiousGhostTrail } from './trails/index.js';\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const orphans = diagnostics.filter((d) =>
+        d.message.includes('fictitiousGhostTrail')
+      );
+      expect(orphans.length).toBe(1);
+      expect(orphans[0]?.severity).toBe('error');
+    });
+
+    test('fires on orphan *Trail declared via `export const`', () => {
+      const source = buildIndexSource(
+        `export const fictitiousGhostTrail = {} as unknown;\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const orphans = diagnostics.filter((d) =>
+        d.message.includes('fictitiousGhostTrail')
+      );
+      expect(orphans.length).toBe(1);
+      expect(orphans[0]?.severity).toBe('error');
+    });
+
+    test('fires on orphan *Trail declared via destructured object pattern', () => {
+      // Regression: `sitesForDeclaration` previously only handled Identifier
+      // declarator ids. A destructured `export const { ... } = ...` silently
+      // bypassed the orphan-trail check.
+      const source = buildIndexSource(
+        `export const { fictitiousGhostTrail } = {} as { fictitiousGhostTrail: unknown };\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const orphans = diagnostics.filter((d) =>
+        d.message.includes('fictitiousGhostTrail')
+      );
+      expect(orphans.length).toBe(1);
+      expect(orphans[0]?.severity).toBe('error');
+    });
+
+    test('fires on orphan *Trail declared via destructured array pattern', () => {
+      const source = buildIndexSource(
+        `export const [fictitiousGhostTrail] = [] as unknown as [unknown];\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const orphans = diagnostics.filter((d) =>
+        d.message.includes('fictitiousGhostTrail')
+      );
+      expect(orphans.length).toBe(1);
+      expect(orphans[0]?.severity).toBe('error');
+    });
+  });
+
+  describe('raw-rule leaks', () => {
+    test('fires when a raw rule object is re-exported on the barrel', () => {
+      const source = buildIndexSource(
+        `export { ${sampleRawRuleCamel} } from './rules/index.js';\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const rawLeaks = diagnostics.filter((d) =>
+        d.message.includes(`raw rule export "${sampleRawRuleCamel}"`)
+      );
+      expect(rawLeaks.length).toBe(1);
+      expect(rawLeaks[0]?.severity).toBe('error');
+    });
+
+    test('fires on aliased raw-rule re-exports using the local binding name', () => {
+      const source = buildIndexSource(
+        `export { ${sampleRawRuleCamel} as disguisedRule } from './rules/index.js';\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const rawLeaks = diagnostics.filter((d) =>
+        d.message.includes(`raw rule export "${sampleRawRuleCamel}"`)
+      );
+      expect(rawLeaks.length).toBe(1);
+      expect(rawLeaks[0]?.severity).toBe('error');
+    });
+
+    test('fires on raw-rule leak via destructured object pattern', () => {
+      // Regression: destructuring was a silent bypass for raw-rule leaks —
+      // `export const { wardenExportSymmetry } = rulesModule` exposed the raw
+      // rule object without tripping the check.
+      const source = buildIndexSource(
+        `export const { ${sampleRawRuleCamel} } = {} as Record<string, unknown>;\n`
+      );
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const rawLeaks = diagnostics.filter((d) =>
+        d.message.includes(`raw rule export "${sampleRawRuleCamel}"`)
+      );
+      expect(rawLeaks.length).toBe(1);
+      expect(rawLeaks[0]?.severity).toBe('error');
+    });
+  });
+
+  describe('forbidden barrel shapes', () => {
+    test('fires on namespace re-exports (export * from ...)', () => {
+      const source = `${buildIndexSource()}export * from './trails/index.js';\n`;
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const nsReexports = diagnostics.filter((d) =>
+        d.message.includes('namespace re-export')
+      );
+      expect(nsReexports.length).toBe(1);
+      expect(nsReexports[0]?.severity).toBe('error');
+      // Regression guard: plain `export *` must not mention an ` as ` alias.
+      expect(nsReexports[0]?.message).not.toContain(' as ');
+      expect(nsReexports[0]?.message).toContain(
+        "export * from './trails/index.js'"
+      );
+    });
+
+    test('fires on aliased namespace re-exports and preserves the alias', () => {
+      const source = `${buildIndexSource()}export * as trailsNs from './trails/index.js';\n`;
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const nsReexports = diagnostics.filter((d) =>
+        d.message.includes('namespace re-export')
+      );
+      expect(nsReexports.length).toBe(1);
+      expect(nsReexports[0]?.severity).toBe('error');
+      expect(nsReexports[0]?.message).toContain(
+        "export * as trailsNs from './trails/index.js'"
+      );
+    });
+
+    test('rejects `export default` on the warden barrel', () => {
+      const source = `${buildIndexSource()}export default {};\n`;
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const defaults = diagnostics.filter((d) =>
+        d.message.includes('default export')
+      );
+      expect(defaults.length).toBe(1);
+      expect(defaults[0]?.severity).toBe('error');
+    });
+  });
+
+  describe('type-only namespace re-exports', () => {
+    test('allows `export type * from ...`', () => {
+      const source = `${buildIndexSource()}export type * from './rules/types.js';\n`;
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const nsReexports = diagnostics.filter((d) =>
+        d.message.includes('namespace re-export')
+      );
+      expect(nsReexports).toEqual([]);
+    });
+
+    test('allows `export type * as ns from ...`', () => {
+      const source = `${buildIndexSource()}export type * as types from './rules/types.js';\n`;
+      const diagnostics = wardenExportSymmetry.check(source, TARGET_FILE);
+      const nsReexports = diagnostics.filter((d) =>
+        d.message.includes('namespace re-export')
+      );
+      expect(nsReexports).toEqual([]);
+    });
+  });
+});