@ontrails/warden 1.0.0-beta.14 → 1.0.0-beta.16

package/src/rules/public-union-output-discriminants.ts

@@ -0,0 +1,150 @@
+import { filterSurfaceTrails, zodToJsonSchema } from '@ontrails/core';
+import type { AnyTrail, Topo } from '@ontrails/core';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'public-union-output-discriminants';
+
+type JsonSchema = Readonly<Record<string, unknown>>;
+
+interface ObjectBranch {
+  readonly properties: Readonly<Record<string, JsonSchema>>;
+  readonly required: ReadonlySet<string>;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+const isJsonSchema = (value: unknown): value is JsonSchema => isRecord(value);
+
+const schemaForTrailOutput = (trail: AnyTrail): JsonSchema | undefined => {
+  if (!trail.output) {
+    return undefined;
+  }
+  try {
+    return zodToJsonSchema(trail.output);
+  } catch {
+    return undefined;
+  }
+};
+
+const readProperties = (
+  schema: JsonSchema
+): Readonly<Record<string, JsonSchema>> | undefined => {
+  const { properties } = schema;
+  if (!isRecord(properties)) {
+    return undefined;
+  }
+  const entries = Object.entries(properties);
+  if (!entries.every(([, value]) => isJsonSchema(value))) {
+    return undefined;
+  }
+  return properties as Readonly<Record<string, JsonSchema>>;
+};
+
+const readRequired = (schema: JsonSchema): ReadonlySet<string> => {
+  const { required } = schema;
+  if (!Array.isArray(required)) {
+    return new Set();
+  }
+  return new Set(
+    required.filter((entry): entry is string => typeof entry === 'string')
+  );
+};
+
+const objectBranchFromSchema = (schema: unknown): ObjectBranch | undefined => {
+  if (!isJsonSchema(schema) || schema['type'] !== 'object') {
+    return undefined;
+  }
+  const properties = readProperties(schema);
+  if (!properties) {
+    return undefined;
+  }
+  return { properties, required: readRequired(schema) };
+};
+
+const objectBranchesFromAnyOf = (
+  schema: JsonSchema
+): readonly ObjectBranch[] | undefined => {
+  const { anyOf } = schema;
+  if (!Array.isArray(anyOf) || anyOf.length < 2) {
+    return undefined;
+  }
+  const branches = anyOf.flatMap((branch) => {
+    const objectBranch = objectBranchFromSchema(branch);
+    return objectBranch ? [objectBranch] : [];
+  });
+  return branches.length >= 2 ? branches : undefined;
+};
+
+const hasConst = (schema: JsonSchema): boolean =>
+  Object.hasOwn(schema, 'const');
+
+const constValue = (schema: JsonSchema): unknown => schema['const'];
+
+const constKey = (value: unknown): string => JSON.stringify(value);
+
+const branchLiteralForKey = (
+  branch: ObjectBranch,
+  key: string
+): unknown | undefined => {
+  if (!branch.required.has(key)) {
+    return undefined;
+  }
+  const property = branch.properties[key];
+  return property && hasConst(property) ? constValue(property) : undefined;
+};
+
+const hasRequiredLiteralDiscriminant = (
+  branches: readonly ObjectBranch[]
+): boolean => {
+  const [first] = branches;
+  if (!first) {
+    return false;
+  }
+
+  return Object.keys(first.properties).some((key) => {
+    const values = branches.map((branch) => branchLiteralForKey(branch, key));
+    return (
+      values.every((value) => value !== undefined) &&
+      new Set(values.map(constKey)).size === branches.length
+    );
+  });
+};
+
+const diagnosticForTrail = (trail: AnyTrail): WardenDiagnostic => ({
+  filePath: '<topo>',
+  line: 1,
+  message:
+    `Trail "${trail.id}" exposes a public output anyOf with object variants but no required literal discriminator. ` +
+    'Add a shared z.literal(...) field or z.discriminatedUnion(...) so surfaces and agents can select the output branch.',
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+const diagnoseTrail = (trail: AnyTrail): WardenDiagnostic | undefined => {
+  const schema = schemaForTrailOutput(trail);
+  if (!schema) {
+    return undefined;
+  }
+  const objectBranches = objectBranchesFromAnyOf(schema);
+  if (!objectBranches) {
+    return undefined;
+  }
+  return hasRequiredLiteralDiscriminant(objectBranches)
+    ? undefined
+    : diagnosticForTrail(trail);
+};
+
+export const publicUnionOutputDiscriminants: TopoAwareWardenRule = {
+  checkTopo(topo: Topo): readonly WardenDiagnostic[] {
+    return filterSurfaceTrails(topo.list()).flatMap((trail) => {
+      const diagnostic = diagnoseTrail(trail);
+      return diagnostic ? [diagnostic] : [];
+    });
+  },
+  description:
+    'Require public trail output object unions to expose a required literal discriminator.',
+  name: RULE_NAME,
+  severity: 'error',
+};

package/src/rules/read-intent-fires.ts

@@ -0,0 +1,187 @@
+import {
+  buildSignalIdentifierResolver,
+  deriveConstString,
+  extractStringLiteral,
+  findConfigProperty,
+  findTrailDefinitions,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode, SignalIdentifierResolver } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+interface DeclaredFireSummary {
+  readonly count: number;
+  readonly ids: readonly string[];
+  readonly line: number;
+}
+
+const isReadIntent = (config: AstNode): boolean => {
+  const intentProp = findConfigProperty(config, 'intent');
+  const intentValue = intentProp?.value as AstNode | undefined;
+  return isStringLiteral(intentValue) && getStringValue(intentValue) === 'read';
+};
+
+const collectArrayBindings = (ast: AstNode): ReadonlyMap<string, AstNode> => {
+  const bindings = new Map<string, AstNode>();
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    const name = identifierName(id);
+    if (name && init?.type === 'ArrayExpression') {
+      bindings.set(name, init);
+    }
+  });
+  return bindings;
+};
+
+const getFiresArray = (
+  config: AstNode,
+  arrayBindings: ReadonlyMap<string, AstNode>
+): AstNode | null => {
+  const firesProp = findConfigProperty(config, 'fires');
+  const value = firesProp?.value as AstNode | undefined;
+  if (value?.type === 'ArrayExpression') {
+    return value;
+  }
+
+  const name = identifierName(value);
+  return name ? (arrayBindings.get(name) ?? null) : null;
+};
+
+const getFiresElements = (
+  config: AstNode,
+  arrayBindings: ReadonlyMap<string, AstNode>
+): readonly AstNode[] => {
+  const array = getFiresArray(config, arrayBindings);
+  if (!array) {
+    return [];
+  }
+
+  return (
+    (array as unknown as { readonly elements?: readonly (AstNode | null)[] })
+      .elements ?? []
+  ).filter((element): element is AstNode => element !== null);
+};
+
+const resolveFireElementId = (
+  element: AstNode,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): string | null => {
+  const literalValue = extractStringLiteral(element);
+  if (literalValue !== null) {
+    return literalValue;
+  }
+
+  if (element.type !== 'Identifier') {
+    return null;
+  }
+
+  const resolved = signalIds.resolve(element);
+  if (resolved.kind === 'signal' || resolved.kind === 'string') {
+    return resolved.id;
+  }
+
+  const name = identifierName(element);
+  return name ? deriveConstString(name, sourceCode) : null;
+};
+
+const summarizeDeclaredFires = (
+  config: AstNode,
+  arrayBindings: ReadonlyMap<string, AstNode>,
+  sourceCode: string,
+  signalIds: SignalIdentifierResolver
+): DeclaredFireSummary | null => {
+  const firesProp = findConfigProperty(config, 'fires');
+  const elements = getFiresElements(config, arrayBindings);
+  if (elements.length === 0) {
+    return null;
+  }
+
+  const ids: string[] = [];
+  for (const element of elements) {
+    const resolved = resolveFireElementId(element, sourceCode, signalIds);
+    if (resolved) {
+      ids.push(resolved);
+    }
+  }
+
+  const [firstElement] = elements;
+  const lineNode = firesProp ?? firstElement;
+  return {
+    count: elements.length,
+    ids,
+    line: lineNode ? offsetToLine(sourceCode, lineNode.start) : 1,
+  };
+};
+
+const formatSignalList = (summary: DeclaredFireSummary): string => {
+  const named = summary.ids.map((id) => `"${id}"`);
+  const unresolvedCount = summary.count - summary.ids.length;
+  const unresolved =
+    unresolvedCount > 0
+      ? [
+          unresolvedCount === 1
+            ? '1 unresolved signal reference'
+            : `${unresolvedCount} unresolved signal references`,
+        ]
+      : [];
+  return [...named, ...unresolved].join(', ');
+};
+
+const buildDiagnostic = (
+  trailId: string,
+  summary: DeclaredFireSummary,
+  filePath: string
+): WardenDiagnostic => ({
+  filePath,
+  line: summary.line,
+  message: `Trail "${trailId}" declares intent: 'read' but also declares fires: [${formatSignalList(summary)}]. Read trails should remain side-effect-free; change the trail intent or move ctx.fire behavior to an appropriate write trail.`,
+  rule: 'read-intent-fires',
+  severity: 'warn',
+});
+
+export const readIntentFires: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const signalIds = buildSignalIdentifierResolver(ast);
+    const arrayBindings = collectArrayBindings(ast);
+    return findTrailDefinitions(ast).flatMap((def) => {
+      if (def.kind !== 'trail' || !isReadIntent(def.config)) {
+        return [];
+      }
+
+      const summary = summarizeDeclaredFires(
+        def.config,
+        arrayBindings,
+        sourceCode,
+        signalIds
+      );
+      return summary ? [buildDiagnostic(def.id, summary, filePath)] : [];
+    });
+  },
+  description:
+    'Warn when read-intent trails declare signal fires side effects.',
+  name: 'read-intent-fires',
+  severity: 'warn',
+};

package/src/rules/reference-exists.ts

@@ -0,0 +1,98 @@
+import {
+  collectContourDefinitionIds,
+  collectContourReferenceSites,
+  offsetToLine,
+  parse,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { mergeKnownContourIds } from './contour-ids.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const buildMissingReferenceDiagnostic = (
+  sourceContour: string,
+  field: string,
+  targetContour: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Contour "${sourceContour}" field "${field}" references contour "${targetContour}" which is not defined in the project.`,
+  rule: 'reference-exists',
+  severity: 'error',
+});
+
+const checkContourReferences = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownContourIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return collectContourReferenceSites(ast, knownContourIds).flatMap(
+    (reference) => {
+      if (knownContourIds.has(reference.target)) {
+        return [];
+      }
+
+      return [
+        buildMissingReferenceDiagnostic(
+          reference.source,
+          reference.field,
+          reference.target,
+          filePath,
+          offsetToLine(sourceCode, reference.start)
+        ),
+      ];
+    }
+  );
+};
+
+/**
+ * Checks that every contour `.id()` reference resolves to a known contour.
+ */
+export const referenceExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return checkContourReferences(
+      ast,
+      sourceCode,
+      filePath,
+      collectContourDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localContourIds = collectContourDefinitionIds(ast);
+    return checkContourReferences(
+      ast,
+      sourceCode,
+      filePath,
+      mergeKnownContourIds(localContourIds, context.knownContourIds)
+    );
+  },
+  description:
+    'Ensure every contour field declared via .id() resolves to a known contour.',
+  name: 'reference-exists',
+  severity: 'error',
+};

package/src/rules/registry-names.ts

@@ -0,0 +1,113 @@
+/**
+ * Registry name snapshot used by `warden-export-symmetry`.
+ *
+ * Imports each rule module directly to avoid a dependency cycle with
+ * `./index.ts`, which itself imports `warden-export-symmetry`. Keep this
+ * list in lockstep with `wardenRules` / `wardenTopoRules` in `./index.ts` —
+ * the `warden-export-symmetry` rule will fail the build if they drift.
+ */
+import { activationOrphan } from './activation-orphan.js';
+import { circularRefs } from './circular-refs.js';
+import { contourExists } from './contour-exists.js';
+import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { crossDeclarations } from './cross-declarations.js';
+import { deadInternalTrail } from './dead-internal-trail.js';
+import { draftFileMarking } from './draft-file-marking.js';
+import { draftVisibleDebt } from './draft-visible-debt.js';
+import { errorMappingCompleteness } from './error-mapping-completeness.js';
+import { exampleValid } from './example-valid.js';
+import { firesDeclarations } from './fires-declarations.js';
+import { implementationReturnsResult } from './implementation-returns-result.js';
+import { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+import { incompleteCrud } from './incomplete-crud.js';
+import { intentPropagation } from './intent-propagation.js';
+import { layerFieldNameDrift } from './layer-field-name-drift.js';
+import { missingReconcile } from './missing-reconcile.js';
+import { missingVisibility } from './missing-visibility.js';
+import { noDevPermitInSource } from './no-dev-permit-in-source.js';
+import { noLegacyLayerImports } from './no-legacy-layer-imports.js';
+import { noDirectImplementationCall } from './no-direct-implementation-call.js';
+import { noNativeErrorResult } from './no-native-error-result.js';
+import { noSyncResultAssumption } from './no-sync-result-assumption.js';
+import { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
+import { noThrowInImplementation } from './no-throw-in-implementation.js';
+import { onReferencesExist } from './on-references-exist.js';
+import { orphanedSignal } from './orphaned-signal.js';
+import { ownerProjectionParity } from './owner-projection-parity.js';
+import { permitGovernance } from './permit-governance.js';
+import { preferSchemaInference } from './prefer-schema-inference.js';
+import { publicInternalDeepImports } from './public-internal-deep-imports.js';
+import { publicOutputSchema } from './public-output-schema.js';
+import { publicUnionOutputDiscriminants } from './public-union-output-discriminants.js';
+import { readIntentFires } from './read-intent-fires.js';
+import { referenceExists } from './reference-exists.js';
+import { resolvedImportBoundary } from './resolved-import-boundary.js';
+import { resourceDeclarations } from './resource-declarations.js';
+import { resourceExists } from './resource-exists.js';
+import { resourceIdGrammar } from './resource-id-grammar.js';
+import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
+import { signalGraphCoaching } from './signal-graph-coaching.js';
+import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+import { unmaterializedActivationSource } from './unmaterialized-activation-source.js';
+import { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+import { validDetourContract } from './valid-detour-contract.js';
+import { validDescribeRefs } from './valid-describe-refs.js';
+import { wardenRulesUseAst } from './warden-rules-use-ast.js';
+import { webhookRouteCollision } from './webhook-route-collision.js';
+
+/**
+ * All non-`warden-export-symmetry` rule identifiers registered in
+ * `wardenRules` / `wardenTopoRules`. Excludes the symmetry rule itself to
+ * avoid a self-referential check; the symmetry rule adds its own name back in
+ * when comparing against the public barrel.
+ */
+export const registeredRuleNames: readonly string[] = [
+  activationOrphan.name,
+  circularRefs.name,
+  contextNoSurfaceTypes.name,
+  contourExists.name,
+  crossDeclarations.name,
+  deadInternalTrail.name,
+  draftFileMarking.name,
+  draftVisibleDebt.name,
+  errorMappingCompleteness.name,
+  exampleValid.name,
+  firesDeclarations.name,
+  implementationReturnsResult.name,
+  incompleteAccessorForStandardOp.name,
+  incompleteCrud.name,
+  intentPropagation.name,
+  layerFieldNameDrift.name,
+  missingReconcile.name,
+  missingVisibility.name,
+  noDevPermitInSource.name,
+  noLegacyLayerImports.name,
+  noDirectImplementationCall.name,
+  noNativeErrorResult.name,
+  noSyncResultAssumption.name,
+  noThrowInDetourRecover.name,
+  noThrowInImplementation.name,
+  onReferencesExist.name,
+  orphanedSignal.name,
+  ownerProjectionParity.name,
+  permitGovernance.name,
+  preferSchemaInference.name,
+  publicInternalDeepImports.name,
+  publicOutputSchema.name,
+  publicUnionOutputDiscriminants.name,
+  readIntentFires.name,
+  referenceExists.name,
+  resolvedImportBoundary.name,
+  resourceDeclarations.name,
+  resourceExists.name,
+  resourceIdGrammar.name,
+  scheduledDestroyIntent.name,
+  signalGraphCoaching.name,
+  staticResourceAccessorPreference.name,
+  unmaterializedActivationSource.name,
+  unreachableDetourShadowing.name,
+  validDetourContract.name,
+  validDescribeRefs.name,
+  wardenRulesUseAst.name,
+  webhookRouteCollision.name,
+];

package/src/rules/resolved-import-boundary.ts

@@ -0,0 +1,146 @@
+import { hasIgnoreCommentOnLine, splitSourceLines } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenImportResolution } from '../resolve.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'resolved-import-boundary';
+
+const normalizePath = (path: string): string => path.replaceAll('\\', '/');
+
+const isLocalPathImport = (importSource: string): boolean =>
+  importSource.startsWith('.') || importSource.startsWith('/');
+
+const isFixtureOrMigrationFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return /(?:^|\/)(?:__fixtures__|fixtures?|migrations?)(?:\/|$)/.test(
+    normalized
+  );
+};
+
+const isAllowlistedFile = (filePath: string): boolean =>
+  isTestFile(filePath) || isFixtureOrMigrationFile(filePath);
+
+const resolutionLabel = (resolution: {
+  readonly importSource: string;
+  readonly packageName?: string | undefined;
+}): string => resolution.packageName ?? resolution.importSource;
+
+const publicSurfaceMessage = (resolution: {
+  readonly importSource: string;
+  readonly packageName?: string | undefined;
+}): string =>
+  `Import "${resolution.importSource}" is not exported by ${resolutionLabel(
+    resolution
+  )}. Import the package root or an exported subpath instead.`;
+
+const localPathBoundaryMessage = (resolution: {
+  readonly importSource: string;
+  readonly packageName?: string | undefined;
+}): string =>
+  `Local import "${resolution.importSource}" crosses into ${resolutionLabel(
+    resolution
+  )}. Import the target package public surface instead.`;
+
+const internalTargetMessage = (resolution: {
+  readonly importSource: string;
+  readonly packageName?: string | undefined;
+}): string =>
+  `Import "${resolution.importSource}" targets internal/private files in ${resolutionLabel(
+    resolution
+  )}. Import the target package public surface instead.`;
+
+const diagnosticForResolution = (
+  filePath: string,
+  resolution: WardenImportResolution
+): WardenDiagnostic | null => {
+  if (!resolution.crossesPackageBoundary) {
+    return null;
+  }
+
+  if (resolution.isInternalTarget) {
+    return {
+      filePath,
+      line: resolution.line,
+      message: internalTargetMessage(resolution),
+      rule: RULE_NAME,
+      severity: 'error',
+    };
+  }
+
+  if (isLocalPathImport(resolution.importSource)) {
+    return {
+      filePath,
+      line: resolution.line,
+      message: localPathBoundaryMessage(resolution),
+      rule: RULE_NAME,
+      severity: 'error',
+    };
+  }
+
+  if (resolution.errorKind === 'package-path-not-exported') {
+    return {
+      filePath,
+      line: resolution.line,
+      message: publicSurfaceMessage(resolution),
+      rule: RULE_NAME,
+      severity: 'error',
+    };
+  }
+
+  if (
+    resolution.errorKind &&
+    resolution.errorKind !== 'builtin' &&
+    resolution.errorKind !== 'ignored'
+  ) {
+    return {
+      filePath,
+      line: resolution.line,
+      message: publicSurfaceMessage(resolution),
+      rule: RULE_NAME,
+      severity: 'error',
+    };
+  }
+
+  return null;
+};
+
+const importResolutionsForFile = (context: ProjectContext, filePath: string) =>
+  context.importResolutionsByFile?.get(filePath) ?? [];
+
+export const resolvedImportBoundary: ProjectAwareWardenRule = {
+  check(): readonly WardenDiagnostic[] {
+    return [];
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    if (isAllowlistedFile(filePath)) {
+      return [];
+    }
+
+    const lines = splitSourceLines(sourceCode);
+    const diagnostics: WardenDiagnostic[] = [];
+
+    for (const resolution of importResolutionsForFile(context, filePath)) {
+      if (hasIgnoreCommentOnLine(lines, resolution.line)) {
+        continue;
+      }
+      const diagnostic = diagnosticForResolution(filePath, resolution);
+      if (diagnostic) {
+        diagnostics.push(diagnostic);
+      }
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Ensure cross-package imports resolve through package-owned public exports.',
+  name: RULE_NAME,
+  severity: 'error',
+};