@ontrails/warden 1.0.0-beta.2 → 1.0.0-beta.22

package/src/rules/missing-reconcile.ts

@@ -0,0 +1,98 @@
+import {
+  collectCrudTableIds,
+  collectReconcileTableIds,
+  findStoreTableDefinitions,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const buildMissingReconcileDiagnostic = (
+  tableId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Versioned store table "${tableId}" is used with CRUD factories but has no reconcile trail. Add reconcile(...) to complete the versioned store pattern.`,
+  rule: 'missing-reconcile',
+  severity: 'warn',
+});
+
+const checkMissingReconcile = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  crudTableIds: ReadonlySet<string>,
+  reconcileTableIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const definition of findStoreTableDefinitions(ast)) {
+    if (
+      !definition.versioned ||
+      !crudTableIds.has(definition.key) ||
+      reconcileTableIds.has(definition.key)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildMissingReconcileDiagnostic(
+        definition.name,
+        filePath,
+        offsetToLine(sourceCode, definition.start)
+      )
+    );
+  }
+
+  return diagnostics;
+};
+
+export const missingReconcile: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkMissingReconcile(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectCrudTableIds(ast) : new Set<string>(),
+      ast ? collectReconcileTableIds(ast) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localCrudTableIds = ast
+      ? collectCrudTableIds(ast)
+      : new Set<string>();
+    const localReconcileTableIds = ast
+      ? collectReconcileTableIds(ast)
+      : new Set<string>();
+
+    return checkMissingReconcile(
+      ast,
+      sourceCode,
+      filePath,
+      context.crudTableIds ?? localCrudTableIds,
+      context.reconcileTableIds ?? localReconcileTableIds
+    );
+  },
+  description:
+    'Warn when a versioned store table participates in CRUD factory generation without a matching reconcile trail.',
+  name: 'missing-reconcile',
+  severity: 'warn',
+};

package/src/rules/missing-visibility.ts

@@ -0,0 +1,110 @@
+import { collectComposeTargetTrailIds, parse } from './ast.js';
+import { isTestFile } from './scan.js';
+import {
+  findTrailLikeSpecs,
+  parseStringLiteral,
+  parseZodObjectShape,
+} from './specs.js';
+import type { TrailLikeSpec } from './specs.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+/** Check legacy `meta: { internal: true }` convention (mirrors runtime effectiveVisibility). */
+const hasLegacyMetaInternal = (spec: TrailLikeSpec): boolean => {
+  const meta = spec.properties.get('meta')?.value ?? '';
+  return /(?:^|[{,])\s*internal\s*:\s*true/.test(meta);
+};
+
+const trailVisibility = (spec: TrailLikeSpec): 'internal' | 'public' => {
+  if (
+    parseStringLiteral(spec.properties.get('visibility')?.value ?? '') ===
+    'internal'
+  ) {
+    return 'internal';
+  }
+  return hasLegacyMetaInternal(spec) ? 'internal' : 'public';
+};
+
+const hasRequiredComposeInput = (spec: TrailLikeSpec): boolean => {
+  const composeInput = spec.properties.get('composeInput');
+  if (!composeInput) {
+    return false;
+  }
+
+  const fields = parseZodObjectShape(composeInput.value);
+  return [...fields.values()].some((field) => field.required);
+};
+
+const buildMissingVisibilityDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" is composed elsewhere and declares required composeInput fields, but it is still public. Consider visibility: 'internal' so surfaces do not expose a trail that only works through ctx.compose().`,
+  rule: 'missing-visibility',
+  severity: 'warn',
+});
+
+const checkMissingVisibility = (
+  sourceCode: string,
+  filePath: string,
+  composedTrailIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const spec of findTrailLikeSpecs(sourceCode)) {
+    if (
+      spec.kind !== 'trail' ||
+      trailVisibility(spec) === 'internal' ||
+      !composedTrailIds.has(spec.id) ||
+      !hasRequiredComposeInput(spec)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildMissingVisibilityDiagnostic(spec.id, filePath, spec.line)
+    );
+  }
+
+  return diagnostics;
+};
+
+export const missingVisibility: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkMissingVisibility(
+      sourceCode,
+      filePath,
+      ast ? collectComposeTargetTrailIds(ast, sourceCode) : new Set<string>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localComposeTargetTrailIds = ast
+      ? collectComposeTargetTrailIds(ast, sourceCode)
+      : new Set<string>();
+    return checkMissingVisibility(
+      sourceCode,
+      filePath,
+      context.composeTargetTrailIds ?? localComposeTargetTrailIds
+    );
+  },
+  description:
+    'Coach when a composed trail still looks composition-only because it declares required composeInput but remains public.',
+  name: 'missing-visibility',
+  severity: 'warn',
+};

package/src/rules/no-destructured-compose.ts

@@ -0,0 +1,192 @@
+import {
+  findBlazeBodies,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  isShadowed,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walkWithScopes,
+} from './ast.js';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-destructured-compose';
+
+const diagnosticMessage = (trailId: string): string =>
+  `Trail "${trailId}" destructures compose from the blaze context. Use ctx.compose(...) directly so composition stays visible and Warden can recognize composed Result values.`;
+
+const propertyKeyName = (property: AstNode): string | null => {
+  if ((property as unknown as { computed?: boolean }).computed === true) {
+    return null;
+  }
+
+  const key = property.key as AstNode | undefined;
+  if (!key) {
+    return null;
+  }
+
+  return (
+    identifierName(key) ?? (isStringLiteral(key) ? getStringValue(key) : null)
+  );
+};
+
+const findComposeBinding = (pattern: AstNode | undefined): AstNode | null => {
+  if (pattern?.type !== 'ObjectPattern') {
+    return null;
+  }
+
+  const properties =
+    (pattern as unknown as { properties?: readonly AstNode[] }).properties ??
+    [];
+
+  for (const property of properties) {
+    if (
+      property.type === 'Property' &&
+      propertyKeyName(property) === 'compose'
+    ) {
+      return property;
+    }
+  }
+
+  return null;
+};
+
+const blazeParams = (blaze: AstNode): readonly AstNode[] =>
+  (blaze as unknown as { params?: readonly AstNode[] }).params ?? [];
+
+const destructuredComposeFromVariableDeclarator = (
+  node: AstNode,
+  contextName: string
+): AstNode | null => {
+  if (node.type !== 'VariableDeclarator') {
+    return null;
+  }
+
+  const { id, init } = node as unknown as {
+    readonly id?: AstNode;
+    readonly init?: AstNode;
+  };
+
+  if (identifierName(init) !== contextName) {
+    return null;
+  }
+
+  return findComposeBinding(id);
+};
+
+const destructuredComposeFromAssignment = (
+  node: AstNode,
+  contextName: string
+): AstNode | null => {
+  if (node.type !== 'AssignmentExpression') {
+    return null;
+  }
+
+  const { left, operator, right } = node as unknown as {
+    readonly left?: AstNode;
+    readonly operator?: string;
+    readonly right?: AstNode;
+  };
+
+  if (operator !== '=' || identifierName(right) !== contextName) {
+    return null;
+  }
+
+  return findComposeBinding(left);
+};
+
+const checkBodyDestructuring = (
+  sourceCode: string,
+  filePath: string,
+  trailId: string,
+  blaze: AstNode,
+  contextName: string
+): WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+
+  walkWithScopes(
+    blaze,
+    (node, scopes) => {
+      if (isShadowed(contextName, scopes)) {
+        return;
+      }
+
+      const composeBinding =
+        destructuredComposeFromVariableDeclarator(node, contextName) ??
+        destructuredComposeFromAssignment(node, contextName);
+      if (!composeBinding) {
+        return;
+      }
+
+      diagnostics.push({
+        filePath,
+        line: offsetToLine(sourceCode, composeBinding.start),
+        message: diagnosticMessage(trailId),
+        rule: RULE_NAME,
+        severity: 'warn',
+      });
+    },
+    { stopAtNestedFunctions: true }
+  );
+
+  return diagnostics;
+};
+
+export const noDestructuredCompose: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath) || isFrameworkInternalFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const definition of findTrailDefinitions(ast)) {
+      if (definition.kind !== 'trail') {
+        continue;
+      }
+
+      for (const blaze of findBlazeBodies(definition.config)) {
+        const params = blazeParams(blaze);
+        const [, contextParam] = params;
+        const paramComposeBinding = findComposeBinding(contextParam);
+
+        if (paramComposeBinding) {
+          diagnostics.push({
+            filePath,
+            line: offsetToLine(sourceCode, paramComposeBinding.start),
+            message: diagnosticMessage(definition.id),
+            rule: RULE_NAME,
+            severity: 'warn',
+          });
+        }
+
+        const contextName = identifierName(contextParam);
+        if (contextName) {
+          diagnostics.push(
+            ...checkBodyDestructuring(
+              sourceCode,
+              filePath,
+              definition.id,
+              blaze,
+              contextName
+            )
+          );
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Coach trail blazes to compose with ctx.compose(...) directly instead of destructuring compose from the context.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/no-dev-permit-in-source.ts

@@ -0,0 +1,99 @@
+/**
+ * Flags occurrences of the `--dev-permit` CLI flag string in source code.
+ *
+ * `--dev-permit` is a local-development ergonomic that injects a synthetic
+ * full-access permit into the CLI execution pipeline (see TRL-410). It must
+ * never appear in committed scripts, CI configs, or library source — its
+ * presence in checked-in code defeats permit governance.
+ *
+ * The rule scans source text for the literal token `--dev-permit` (string
+ * literal, comment, or code). It is intentionally text-based rather than
+ * AST-based: the failure modes the rule targets (a developer pasting a CLI
+ * invocation into a script or doc, or wiring it into a `package.json`-like
+ * manifest) appear in places the AST cannot reason about.
+ *
+ * Allow-list: the CLI flag/build modules and the Warden rule surfaces that
+ * define this rule's own metadata are exempt. The Warden runner invokes this
+ * rule across TypeScript source plus committed script/config surfaces such as
+ * shell scripts, CI YAML, and `package.json`. Unlike most Warden source rules,
+ * test TypeScript files are still scanned for this literal because checked-in
+ * tests can become copied scripts or examples.
+ */
+import { resolve, sep } from 'node:path';
+
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'no-dev-permit-in-source';
+
+/** Literal CLI flag string the rule searches for. */
+const DEV_PERMIT_LITERAL = '--dev-permit';
+
+/**
+ * Path suffixes (in POSIX form) for source files that legitimately contain
+ * the literal `--dev-permit` string. Other files are flagged.
+ *
+ * Each entry is matched against the normalized (forward-slash) absolute
+ * path with a trailing-segment match, so the rule stays correct regardless
+ * of the consumer's repository root.
+ */
+const ALLOWED_PATH_SUFFIXES: readonly string[] = [
+  // The CLI flag preset module authors `--dev-permit` as the canonical name.
+  '/packages/cli/src/flags.ts',
+  // The build module spells the kebab-case form when reading the parsed flag.
+  '/packages/cli/src/build.ts',
+  // The rule's own implementation file references the literal it searches for.
+  '/packages/warden/src/rules/no-dev-permit-in-source.ts',
+  // Rule metadata and trail wrapper document the same literal for users.
+  '/packages/warden/src/rules/metadata.ts',
+  '/packages/warden/src/trails/no-dev-permit-in-source.trail.ts',
+];
+
+const normalizePath = (filePath: string): string =>
+  resolve(filePath).split(sep).join('/');
+
+const isAllowedFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return ALLOWED_PATH_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+};
+
+const findLineOfFirstMatch = (sourceCode: string): number => {
+  const idx = sourceCode.indexOf(DEV_PERMIT_LITERAL);
+  if (idx === -1) {
+    return 1;
+  }
+  let line = 1;
+  for (let i = 0; i < idx; i += 1) {
+    if (sourceCode.codePointAt(i) === 10) {
+      line += 1;
+    }
+  }
+  return line;
+};
+
+/**
+ * Flags occurrences of the `--dev-permit` flag string in committed source.
+ */
+export const noDevPermitInSource: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isAllowedFile(filePath)) {
+      return [];
+    }
+    if (!sourceCode.includes(DEV_PERMIT_LITERAL)) {
+      return [];
+    }
+    return [
+      {
+        filePath,
+        line: findLineOfFirstMatch(sourceCode),
+        message:
+          '`--dev-permit` is a local-development flag and must not appear in committed source. Use `--token` or `--permit` for CI and scripted invocations.',
+        rule: RULE_NAME,
+        severity: 'error',
+      },
+    ];
+  },
+  description:
+    'Disallow the `--dev-permit` CLI flag string in committed source code.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/no-direct-implementation-call.ts

@@ -1,16 +1,16 @@
 /**
- * Flags direct `.implementation()` calls in application code.
+ * Flags direct `.blaze()` calls in application code.
  *
- * Uses AST parsing to find `.implementation()` call expressions,
+ * Uses AST parsing to find `.blaze()` call expressions,
  * ignoring occurrences in strings and comments.
  */
 
-import { isImplementationCall, offsetToLine, parse, walk } from './ast.js';
+import { isBlazeCall, offsetToLine, parse, walk } from './ast.js';
 import { isFrameworkInternalFile, isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 /**
- * Flags direct `.implementation()` calls in application code.
+ * Flags direct `.blaze()` calls in application code.
  */
 export const noDirectImplementationCall: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
@@ -26,12 +26,12 @@ export const noDirectImplementationCall: WardenRule = {
     const diagnostics: WardenDiagnostic[] = [];
 
     walk(ast, (node) => {
-      if (isImplementationCall(node)) {
+      if (isBlazeCall(node)) {
         diagnostics.push({
           filePath,
           line: offsetToLine(sourceCode, node.start),
           message:
-            'Use ctx.follow("trailId", input) instead of direct .implementation() calls. Direct implementation access bypasses validation, tracing, and layers.',
+            'Use ctx.compose("trailId", input) instead of direct .blaze() calls. Direct implementation access bypasses validation, tracing, and layers.',
           rule: 'no-direct-implementation-call',
           severity: 'warn',
         });
@@ -41,7 +41,7 @@ export const noDirectImplementationCall: WardenRule = {
     return diagnostics;
   },
   description:
-    'Disallow direct .implementation() calls in application code. Use ctx.follow() instead.',
+    'Disallow direct .blaze() calls in application code. Use ctx.compose() instead.',
   name: 'no-direct-implementation-call',
   severity: 'warn',
 };