@ontrails/warden 1.0.0-beta.5 → 1.0.0-beta.50

package/src/trails/public-internal-deep-imports.trail.ts

@@ -0,0 +1,94 @@
+import { publicInternalDeepImports } from '../rules/public-internal-deep-imports.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const publicInternalDeepImportsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'packages/store/src/trails/example.ts',
+        importResolutionsByFile: {
+          'packages/store/src/trails/example.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '@ontrails/core/trails',
+              importerPath: 'packages/store/src/trails/example.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              packageRoot: 'packages/core',
+              resolvedPath: 'packages/core/src/trails/index.ts',
+              usesPublicExport: true,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        publicWorkspaces: {
+          '@ontrails/core': {
+            hasExports: true,
+            name: '@ontrails/core',
+            packageJsonPath: 'packages/core/package.json',
+            rootDir: 'packages/core',
+          },
+          '@ontrails/store': {
+            hasExports: true,
+            name: '@ontrails/store',
+            packageJsonPath: 'packages/store/package.json',
+            rootDir: 'packages/store',
+          },
+        },
+        sourceCode: `import { deriveTrail } from '@ontrails/core/trails';\n`,
+      },
+      name: 'Allows exported package subpaths',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/store/src/trails/example.ts',
+            line: 1,
+            message:
+              '@ontrails specifier "@ontrails/core/src/internal/hidden" is not exported by @ontrails/core. Use the package root or an exported subpath; if the API is missing, add an owner export follow-up instead of importing internals.',
+            rule: 'public-internal-deep-imports',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/store/src/trails/example.ts',
+        importResolutionsByFile: {
+          'packages/store/src/trails/example.ts': [
+            {
+              crossesPackageBoundary: true,
+              errorKind: 'package-path-not-exported',
+              importSource: '@ontrails/core/src/internal/hidden',
+              importerPath: 'packages/store/src/trails/example.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@ontrails/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        publicWorkspaces: {
+          '@ontrails/core': {
+            hasExports: true,
+            name: '@ontrails/core',
+            packageJsonPath: 'packages/core/package.json',
+            rootDir: 'packages/core',
+          },
+          '@ontrails/store': {
+            hasExports: true,
+            name: '@ontrails/store',
+            packageJsonPath: 'packages/store/package.json',
+            rootDir: 'packages/store',
+          },
+        },
+        sourceCode: `import { hidden } from '@ontrails/core/src/internal/hidden';\n`,
+      },
+      name: 'Flags compose-package imports into owner internals',
+    },
+  ],
+  rule: publicInternalDeepImports,
+});

package/src/trails/public-output-schema.trail.ts

@@ -0,0 +1,55 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { publicOutputSchema } from '../rules/public-output-schema.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const cleanTrail = trail('report.read', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({}),
+  output: z.object({ ok: z.boolean() }),
+});
+
+const cleanTopo = topo('public-output-schema-clean', {
+  cleanTrail,
+});
+
+const missingOutputTrail = trail('report.missing', {
+  implementation: () => Result.ok({ ok: true }),
+  input: z.object({}),
+});
+
+const missingOutputTopo = topo('public-output-schema-missing', {
+  missingOutputTrail,
+});
+
+export const publicOutputSchemaTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: cleanTopo,
+      },
+      name: 'Public surface trails declare output schemas',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: '<topo>',
+            line: 1,
+            message:
+              'Trail "report.missing" is visible to public MCP/HTTP surface rendering but does not declare an output schema. Add an explicit output schema, or mark the trail visibility as internal if it is composition-only.',
+            rule: 'public-output-schema',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        topo: missingOutputTopo,
+      },
+      name: 'Public surface trails without output schemas are flagged',
+    },
+  ],
+  rule: publicOutputSchema,
+});

package/src/trails/public-union-output-discriminants.trail.ts

@@ -0,0 +1,33 @@
+import { Result, topo, trail } from '@ontrails/core';
+import { z } from 'zod';
+
+import { publicUnionOutputDiscriminants } from '../rules/public-union-output-discriminants.js';
+import { wrapTopoRule } from './wrap-rule.js';
+
+const cleanOutput = z.discriminatedUnion('kind', [
+  z.object({ kind: z.literal('message'), message: z.string() }),
+  z.object({ count: z.number(), kind: z.literal('count') }),
+]);
+
+const cleanTrail = trail('report.read', {
+  implementation: () => Result.ok({ kind: 'message' as const, message: 'ok' }),
+  input: z.object({}),
+  output: cleanOutput,
+});
+
+const cleanTopo = topo('public-union-output-discriminants-clean', {
+  cleanTrail,
+});
+
+export const publicUnionOutputDiscriminantsTrail = wrapTopoRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        topo: cleanTopo,
+      },
+      name: 'Public output object unions expose a literal discriminator',
+    },
+  ],
+  rule: publicUnionOutputDiscriminants,
+});

package/src/trails/read-intent-fires.trail.ts

@@ -0,0 +1,20 @@
+import { readIntentFires } from '../rules/read-intent-fires.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const readIntentFiresTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const entityLoaded = signal('entity.loaded', { payload: z.object({}) });
+trail('entity.read', {
+  intent: 'read',
+  implementation: async () => Result.ok({}),
+});`,
+      },
+      name: 'Read trails without fires stay quiet',
+    },
+  ],
+  rule: readIntentFires,
+});

package/src/trails/reference-exists.trail.ts

@@ -0,0 +1,25 @@
+import { referenceExists } from '../rules/reference-exists.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const referenceExistsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'entities.ts',
+        knownEntityIds: ['gist', 'user'],
+        knownTrailIds: [],
+        sourceCode: `const user = entity("user", {
+  id: z.string().uuid(),
+}, { identity: "id" });
+
+const gist = entity("gist", {
+  id: z.string().uuid(),
+  ownerId: user.id(),
+}, { identity: "id" });`,
+      },
+      name: 'Entity references resolve to known project entities',
+    },
+  ],
+  rule: referenceExists,
+});

package/src/trails/resolved-import-boundary.trail.ts

@@ -0,0 +1,109 @@
+import { resolvedImportBoundary } from '../rules/resolved-import-boundary.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resolvedImportBoundaryTrail = wrapRule({
+  examples: [
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Import "@fixture/core/internal/secret" is not exported by @fixture/core. Import the package root or an exported subpath instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              errorKind: 'package-path-not-exported',
+              importSource: '@fixture/core/internal/secret',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode: "import { secret } from '@fixture/core/internal/secret';\n",
+      },
+      name: 'Compose-package imports must use exported package subpaths',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Local import "../../core/src/public" composes into @fixture/core. Import the target package public surface instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '../../core/src/public',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: false,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode: "import { pub } from '../../core/src/public';\n",
+      },
+      name: 'Relative imports must not compose package boundaries',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'packages/app/src/index.ts',
+            line: 1,
+            message:
+              'Import "../../core/src/internal/secret" targets internal/private files in @fixture/core. Import the target package public surface instead.',
+            rule: 'resolved-import-boundary',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'packages/app/src/index.ts',
+        importResolutionsByFile: {
+          'packages/app/src/index.ts': [
+            {
+              crossesPackageBoundary: true,
+              importSource: '../../core/src/internal/secret',
+              importerPath: 'packages/app/src/index.ts',
+              isInternalTarget: true,
+              line: 1,
+              packageName: '@fixture/core',
+              usesPublicExport: false,
+            },
+          ],
+        },
+        knownTrailIds: [],
+        sourceCode:
+          "import { secret } from '../../core/src/internal/secret';\n",
+      },
+      name: 'Compose-package imports must not target internals',
+    },
+  ],
+  rule: resolvedImportBoundary,
+});

package/src/trails/resource-declarations.trail.ts

@@ -0,0 +1,25 @@
+import { resourceDeclarations } from '../rules/resource-declarations.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceDeclarationsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({ source: "factory" }),
+});
+
+trail("entity.show", {
+  resources: [db],
+  implementation: async (_input, ctx) => {
+    return Result.ok(db.from(ctx));
+  }
+})`,
+      },
+      name: 'Matched resource declarations and usage',
+    },
+  ],
+  rule: resourceDeclarations,
+});

package/src/trails/resource-exists.trail.ts

@@ -0,0 +1,27 @@
+import { resourceExists } from '../rules/resource-exists.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceExistsTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        knownResourceIds: ['db.main'],
+        knownTrailIds: ['entity.show'],
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({ source: "factory" }),
+});
+
+trail("entity.show", {
+  resources: [db],
+  implementation: async (_input, ctx) => {
+    return Result.ok(db.from(ctx));
+  }
+})`,
+      },
+      name: 'Declared resources resolve to known project resources',
+    },
+  ],
+  rule: resourceExists,
+});

package/src/trails/resource-id-grammar.trail.ts

@@ -0,0 +1,39 @@
+import { resourceIdGrammar } from '../rules/resource-id-grammar.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceIdGrammarTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Resource ids stay free of the scope separator',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'invalid.ts',
+            line: 1,
+            message:
+              'Resource "billing:primary" is invalid because resource ids may not contain ":".',
+            rule: 'resource-id-grammar',
+            severity: 'error',
+          },
+        ],
+      },
+      input: {
+        filePath: 'invalid.ts',
+        sourceCode: `const db = resource("billing:primary", {
+  create: () => Result.ok({}),
+});`,
+      },
+      name: 'Colon-separated resource ids are rejected',
+    },
+  ],
+  rule: resourceIdGrammar,
+});

package/src/trails/resource-mock-coverage.trail.ts

@@ -0,0 +1,40 @@
+import { resourceMockCoverage } from '../rules/resource-mock-coverage.js';
+import { wrapRule } from './wrap-rule.js';
+
+export const resourceMockCoverageTrail = wrapRule({
+  examples: [
+    {
+      expected: { diagnostics: [] },
+      input: {
+        filePath: 'clean.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok(openDatabase()),
+  mock: () => createInMemoryDb(),
+});`,
+      },
+      name: 'Resource declaring a mock factory passes',
+    },
+    {
+      expected: {
+        diagnostics: [
+          {
+            filePath: 'missing-mock.ts',
+            line: 1,
+            message:
+              'Resource "db.main" declares no mock factory. Add a mock() so testAll(app) runs without configuration, or declare unmockable: { reason } if it intentionally cannot be mocked.',
+            rule: 'resource-mock-coverage',
+            severity: 'warn',
+          },
+        ],
+      },
+      input: {
+        filePath: 'missing-mock.ts',
+        sourceCode: `const db = resource("db.main", {
+  create: () => Result.ok(openDatabase()),
+});`,
+      },
+      name: 'Resource without a mock factory or unmockable reason is flagged',
+    },
+  ],
+  rule: resourceMockCoverage,
+});

package/src/trails/run.ts

@@ -0,0 +1,202 @@
+/**
+ * Run file-scoped warden rule trails against a single source file.
+ *
+ * Returns a flat array of diagnostics from every source-aware rule. Built-in
+ * topo-aware rules are dispatched separately via `runTopoAwareWardenTrails()`
+ * so callers that loop files do not duplicate graph-level findings.
+ */
+
+import type { Intent, Topo } from '@ontrails/core';
+import { run } from '@ontrails/core';
+
+import { wardenRules, wardenTopoRules } from '../rules/index.js';
+import type {
+  GovernedVocabularyHistoryEvidence,
+  GovernedVocabularyHistoryIssue,
+  ProjectAwareWardenRule,
+  WardenDiagnostic,
+  WardenRule,
+} from '../rules/types.js';
+import type { WardenImportResolution } from '../resolve.js';
+import type { WardenPublicWorkspace } from '../workspaces.js';
+import { projectAwareRuleInput } from './schema.js';
+import type { RuleOutput } from './schema.js';
+import { wardenTopo } from './topo.js';
+import { buildProjectContext } from './wrap-rule.js';
+
+/**
+ * Run all file-scoped warden rule trails for a given file and collect diagnostics.
+ *
+ * Each rule trail runs independently. Errors from individual trails are
+ * silently skipped so that one broken rule does not block the rest.
+ */
+const appendDiagnostics = (
+  target: WardenDiagnostic[],
+  diagnostics: readonly WardenDiagnostic[]
+): void => {
+  for (const diagnostic of diagnostics) {
+    target.push(diagnostic);
+  }
+};
+
+type TrailIntentMap = Readonly<Record<string, Intent>>;
+
+interface ProjectRuleOptions {
+  readonly governedVocabularyHistories?: readonly GovernedVocabularyHistoryEvidence[];
+  readonly governedVocabularyHistoryIssues?: readonly GovernedVocabularyHistoryIssue[];
+  readonly governedVocabularyHistoryRequired?: boolean;
+  readonly entityReferencesByName?: Readonly<Record<string, readonly string[]>>;
+  readonly composeTargetTrailIds?: readonly string[];
+  readonly crudTableIds?: readonly string[];
+  readonly crudCoverageByEntity?: Readonly<Record<string, readonly string[]>>;
+  readonly knownEntityIds?: readonly string[];
+  readonly importResolutionsByFile?: Readonly<
+    Record<string, readonly WardenImportResolution[]>
+  >;
+  readonly documentedImportResolutionsByFile?: Readonly<
+    Record<string, readonly WardenImportResolution[]>
+  >;
+  readonly knownResourceIds?: readonly string[];
+  readonly knownSignalIds?: readonly string[];
+  readonly knownTrailIds?: readonly string[];
+  readonly onTargetSignalIds?: readonly string[];
+  readonly publicWorkspaces?: Readonly<Record<string, WardenPublicWorkspace>>;
+  readonly reconcileTableIds?: readonly string[];
+  readonly trailIntentsById?: TrailIntentMap;
+}
+
+const PROJECT_OPTION_KEYS = [
+  'governedVocabularyHistories',
+  'governedVocabularyHistoryIssues',
+  'governedVocabularyHistoryRequired',
+  'entityReferencesByName',
+  'composeTargetTrailIds',
+  'crudTableIds',
+  'crudCoverageByEntity',
+  'knownEntityIds',
+  'importResolutionsByFile',
+  'documentedImportResolutionsByFile',
+  'knownResourceIds',
+  'knownSignalIds',
+  'knownTrailIds',
+  'onTargetSignalIds',
+  'publicWorkspaces',
+  'reconcileTableIds',
+  'trailIntentsById',
+] as const satisfies readonly (keyof ProjectRuleOptions)[];
+
+const hasProjectOptions = (options?: ProjectRuleOptions): boolean =>
+  Boolean(
+    options && PROJECT_OPTION_KEYS.some((key) => options[key] !== undefined)
+  );
+
+const collectProjectOptions = (
+  options?: ProjectRuleOptions
+): ProjectRuleOptions => {
+  if (!options) {
+    return {};
+  }
+
+  return Object.fromEntries(
+    PROJECT_OPTION_KEYS.flatMap((key) => {
+      const value = options[key];
+      return value === undefined ? [] : [[key, value] as const];
+    })
+  ) as ProjectRuleOptions;
+};
+
+const buildRuleInput = (
+  filePath: string,
+  sourceCode: string,
+  options?: ProjectRuleOptions
+): {
+  readonly filePath: string;
+  readonly sourceCode: string;
+} & ProjectRuleOptions => {
+  const base = { filePath, sourceCode };
+  if (!hasProjectOptions(options)) {
+    return base;
+  }
+
+  return { ...base, ...collectProjectOptions(options) };
+};
+
+const topoAwareTrailIds = new Set(
+  [...wardenTopoRules.keys()].map((ruleName) => `warden.rule.${ruleName}`)
+);
+
+export const runWardenTrails = async (
+  filePath: string,
+  sourceCode: string,
+  options?: ProjectRuleOptions
+): Promise<readonly WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+  const input = buildRuleInput(filePath, sourceCode, options);
+
+  for (const id of wardenTopo.ids()) {
+    if (topoAwareTrailIds.has(id)) {
+      continue;
+    }
+    const result = await run(wardenTopo, id, input);
+    if (result.isOk()) {
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
+    }
+  }
+
+  return allDiagnostics;
+};
+
+const isProjectAwareRule = (rule: WardenRule): rule is ProjectAwareWardenRule =>
+  'checkWithContext' in rule;
+
+/**
+ * Run project-wide built-in Warden diagnostics once for one project context.
+ *
+ * @example
+ * ```ts
+ * const diagnostics = runProjectWardenRules({
+ *   governedVocabularyHistories: histories,
+ * });
+ * ```
+ */
+export const runProjectWardenRules = (
+  options?: ProjectRuleOptions
+): readonly WardenDiagnostic[] => {
+  const context = buildProjectContext(
+    projectAwareRuleInput.parse(buildRuleInput('<project>', '', options))
+  );
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const rule of wardenRules.values()) {
+    if (isProjectAwareRule(rule) && rule.checkProject !== undefined) {
+      appendDiagnostics(diagnostics, rule.checkProject(context));
+    }
+  }
+  return diagnostics;
+};
+
+/**
+ * Run the built-in topo-aware warden rule trails once against a resolved topo.
+ *
+ * Unlike `runWardenTrails()`, which is file-scoped, topo-aware rules inspect
+ * the compiled graph and should only be dispatched once per topo.
+ */
+export const runTopoAwareWardenTrails = async (
+  topo: Topo
+): Promise<readonly WardenDiagnostic[]> => {
+  const allDiagnostics: WardenDiagnostic[] = [];
+
+  for (const id of topoAwareTrailIds) {
+    const result = await run(wardenTopo, id, { topo });
+    if (result.isOk()) {
+      appendDiagnostics(
+        allDiagnostics,
+        (result.value as RuleOutput).diagnostics
+      );
+    }
+  }
+
+  return allDiagnostics;
+};