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

package/src/rules/index.ts

@@ -1,54 +1,255 @@
+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 { composesDeclarations } from './composes-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 { noDirectImplInRoute } from './no-direct-impl-in-route.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 { missingVisibility } from './missing-visibility.js';
+import { missingReconcile } from './missing-reconcile.js';
+import { noDevPermitInSource } from './no-dev-permit-in-source.js';
+import { noDestructuredCompose } from './no-destructured-compose.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 { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+import { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 import { noSyncResultAssumption } from './no-sync-result-assumption.js';
-import { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+import { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
 import { noThrowInImplementation } from './no-throw-in-implementation.js';
+import { noTopLevelSurface } from './no-top-level-surface.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 type { WardenRule } from './types.js';
+import { publicExportExampleCoverage } from './public-export-example-coverage.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 { resourceMockCoverage } from './resource-mock-coverage.js';
+import { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
+import { signalGraphCoaching } from './signal-graph-coaching.js';
+import { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+import { surfaceFacetCoherence } from './surface-facet-coherence.js';
+import {
+  forkWithoutPreservedBlaze,
+  markerSchemaUnsupported,
+  versionPinnedCompose,
+} from './trail-versioning-source.js';
+import {
+  deprecationWithoutGuidance,
+  pendingForce,
+  versionGap,
+  versionWithoutExamples,
+} from './trail-versioning-topo.js';
+import type { TopoAwareWardenRule, WardenRule } from './types.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 { validDetourRefs } from './valid-detour-refs.js';
+import { wardenExportSymmetry } from './warden-export-symmetry.js';
+import { wardenRulesUseAst } from './warden-rules-use-ast.js';
+import { webhookRouteCollision } from './webhook-route-collision.js';
 
 export type {
+  WardenFix,
+  WardenFixCapability,
+  WardenFixClass,
+  WardenFixEdit,
+  WardenFixSafety,
+  WardenGuidance,
+  WardenGuidanceLink,
+  WardenRuleLifecycle,
+  WardenRuleLifecycleState,
+  WardenRuleConcern,
+  WardenRuleMetadata,
+  WardenRuleScope,
   ProjectAwareWardenRule,
   ProjectContext,
+  TopoAwareWardenRule,
   WardenDiagnostic,
   WardenRule,
+  WardenRuleTier,
   WardenSeverity,
 } from './types.js';
 
+export {
+  builtinWardenRuleMetadata,
+  getWardenRuleMetadata,
+  listWardenRuleMetadata,
+  wardenFixClasses,
+  wardenFixSafeties,
+  wardenRuleConcerns,
+  wardenRuleLifecycleStates,
+  wardenRuleScopes,
+  wardenRuleTiers,
+} from './metadata.js';
+export type { BuiltinWardenRuleName } from './metadata.js';
+
+export { activationOrphan } from './activation-orphan.js';
 export { noThrowInImplementation } from './no-throw-in-implementation.js';
+export { circularRefs } from './circular-refs.js';
+export { contourExists } from './contour-exists.js';
 export { contextNoSurfaceTypes } from './context-no-surface-types.js';
-export { validDetourRefs } from './valid-detour-refs.js';
-export { noDirectImplInRoute } from './no-direct-impl-in-route.js';
+export { composesDeclarations } from './composes-declarations.js';
+export { deadInternalTrail } from './dead-internal-trail.js';
+export { draftFileMarking } from './draft-file-marking.js';
+export { draftVisibleDebt } from './draft-visible-debt.js';
+export { errorMappingCompleteness } from './error-mapping-completeness.js';
+export { exampleValid } from './example-valid.js';
+export { firesDeclarations } from './fires-declarations.js';
+export { incompleteAccessorForStandardOp } from './incomplete-accessor-for-standard-op.js';
+export { incompleteCrud } from './incomplete-crud.js';
+export { intentPropagation } from './intent-propagation.js';
+export { layerFieldNameDrift } from './layer-field-name-drift.js';
+export { missingVisibility } from './missing-visibility.js';
+export { missingReconcile } from './missing-reconcile.js';
+export { onReferencesExist } from './on-references-exist.js';
+export { noDevPermitInSource } from './no-dev-permit-in-source.js';
+export { noDestructuredCompose } from './no-destructured-compose.js';
+export { noLegacyLayerImports } from './no-legacy-layer-imports.js';
 export { noDirectImplementationCall } from './no-direct-implementation-call.js';
+export { noNativeErrorResult } from './no-native-error-result.js';
+export { noRedundantResultErrorWrap } from './no-redundant-result-error-wrap.js';
+export { noRetiredCrossVocabulary } from './no-retired-cross-vocabulary.js';
 export { noSyncResultAssumption } from './no-sync-result-assumption.js';
 export { implementationReturnsResult } from './implementation-returns-result.js';
-export { noThrowInDetourTarget } from './no-throw-in-detour-target.js';
+export { noThrowInDetourRecover } from './no-throw-in-detour-recover.js';
+export { noTopLevelSurface } from './no-top-level-surface.js';
+export { orphanedSignal } from './orphaned-signal.js';
+export { ownerProjectionParity } from './owner-projection-parity.js';
+export { permitGovernance } from './permit-governance.js';
 export { preferSchemaInference } from './prefer-schema-inference.js';
+export { publicInternalDeepImports } from './public-internal-deep-imports.js';
+export { publicOutputSchema } from './public-output-schema.js';
+export { publicUnionOutputDiscriminants } from './public-union-output-discriminants.js';
+export { readIntentFires } from './read-intent-fires.js';
+export { referenceExists } from './reference-exists.js';
+export { resolvedImportBoundary } from './resolved-import-boundary.js';
+export { resourceDeclarations } from './resource-declarations.js';
+export { resourceExists } from './resource-exists.js';
+export { resourceIdGrammar } from './resource-id-grammar.js';
+export { resourceMockCoverage } from './resource-mock-coverage.js';
+export { scheduledDestroyIntent } from './scheduled-destroy-intent.js';
+export { signalGraphCoaching } from './signal-graph-coaching.js';
+export { staticResourceAccessorPreference } from './static-resource-accessor-preference.js';
+export { surfaceFacetCoherence } from './surface-facet-coherence.js';
+export {
+  forkWithoutPreservedBlaze,
+  markerSchemaUnsupported,
+  versionPinnedCompose,
+} from './trail-versioning-source.js';
+export {
+  deprecationWithoutGuidance,
+  pendingForce,
+  versionGap,
+  versionWithoutExamples,
+} from './trail-versioning-topo.js';
+export { unmaterializedActivationSource } from './unmaterialized-activation-source.js';
+export { unreachableDetourShadowing } from './unreachable-detour-shadowing.js';
+export { validDetourContract } from './valid-detour-contract.js';
 export { validDescribeRefs } from './valid-describe-refs.js';
+export { webhookRouteCollision } from './webhook-route-collision.js';
 
-/**
- * All built-in warden rules, keyed by rule name.
- *
- * Rules that duplicate validateTopo checks (follows-trails-exist,
- * no-recursive-follows, event-origins-exist, examples-match-schema,
- * require-output-schema) and follows-matches-calls (now covered by
- * testExamples follows coverage) have been removed.
- */
+/** All built-in warden rules, keyed by rule name. */
 export const wardenRules: ReadonlyMap<string, WardenRule> = new Map<
   string,
   WardenRule
 >([
   [noThrowInImplementation.name, noThrowInImplementation],
+  [circularRefs.name, circularRefs],
+  [contourExists.name, contourExists],
   [contextNoSurfaceTypes.name, contextNoSurfaceTypes],
+  [composesDeclarations.name, composesDeclarations],
+  [deadInternalTrail.name, deadInternalTrail],
+  [draftFileMarking.name, draftFileMarking],
+  [draftVisibleDebt.name, draftVisibleDebt],
+  [errorMappingCompleteness.name, errorMappingCompleteness],
+  [exampleValid.name, exampleValid],
+  [firesDeclarations.name, firesDeclarations],
+  [incompleteCrud.name, incompleteCrud],
+  [intentPropagation.name, intentPropagation],
+  [layerFieldNameDrift.name, layerFieldNameDrift],
+  [missingVisibility.name, missingVisibility],
+  [missingReconcile.name, missingReconcile],
+  [onReferencesExist.name, onReferencesExist],
+  [orphanedSignal.name, orphanedSignal],
+  [ownerProjectionParity.name, ownerProjectionParity],
+  [publicExportExampleCoverage.name, publicExportExampleCoverage],
+  [publicInternalDeepImports.name, publicInternalDeepImports],
+  [resourceDeclarations.name, resourceDeclarations],
+  [readIntentFires.name, readIntentFires],
+  [referenceExists.name, referenceExists],
+  [resolvedImportBoundary.name, resolvedImportBoundary],
+  [resourceIdGrammar.name, resourceIdGrammar],
+  [resourceExists.name, resourceExists],
+  [resourceMockCoverage.name, resourceMockCoverage],
   [preferSchemaInference.name, preferSchemaInference],
+  [staticResourceAccessorPreference.name, staticResourceAccessorPreference],
+  [surfaceFacetCoherence.name, surfaceFacetCoherence],
   [validDescribeRefs.name, validDescribeRefs],
-  [validDetourRefs.name, validDetourRefs],
+  [noDevPermitInSource.name, noDevPermitInSource],
+  [noDestructuredCompose.name, noDestructuredCompose],
   [noDirectImplementationCall.name, noDirectImplementationCall],
+  [noLegacyLayerImports.name, noLegacyLayerImports],
+  [noNativeErrorResult.name, noNativeErrorResult],
+  [noRedundantResultErrorWrap.name, noRedundantResultErrorWrap],
+  [noRetiredCrossVocabulary.name, noRetiredCrossVocabulary],
   [noSyncResultAssumption.name, noSyncResultAssumption],
   [implementationReturnsResult.name, implementationReturnsResult],
-  [noThrowInDetourTarget.name, noThrowInDetourTarget],
-  [noDirectImplInRoute.name, noDirectImplInRoute],
+  [noThrowInDetourRecover.name, noThrowInDetourRecover],
+  [noTopLevelSurface.name, noTopLevelSurface],
+  [unreachableDetourShadowing.name, unreachableDetourShadowing],
+  [wardenExportSymmetry.name, wardenExportSymmetry],
+  [wardenRulesUseAst.name, wardenRulesUseAst],
+  [forkWithoutPreservedBlaze.name, forkWithoutPreservedBlaze],
+  [markerSchemaUnsupported.name, markerSchemaUnsupported],
+  [versionPinnedCompose.name, versionPinnedCompose],
 ]);
+
+/**
+ * Built-in topo-aware warden rules, keyed by rule name.
+ *
+ * These rules inspect the compiled runtime trail graph once per topo,
+ * rather than scanning source files. Kept in a separate registry because
+ * their dispatch shape differs from `WardenRule` / `ProjectAwareWardenRule`.
+ *
+ * @remarks
+ * Topo-aware rules only fire when the warden runtime is invoked with a
+ * resolved `Topo` (see `WardenOptions.topo`). Runs without a topo — e.g.
+ * pure source-directory lints — silently skip this registry. Rules
+ * registered here must tolerate non-execution when no topo is available.
+ */
+export const wardenTopoRules: ReadonlyMap<string, TopoAwareWardenRule> =
+  new Map<string, TopoAwareWardenRule>([
+    [activationOrphan.name, activationOrphan],
+    [incompleteAccessorForStandardOp.name, incompleteAccessorForStandardOp],
+    [permitGovernance.name, permitGovernance],
+    [publicOutputSchema.name, publicOutputSchema],
+    [publicUnionOutputDiscriminants.name, publicUnionOutputDiscriminants],
+    [scheduledDestroyIntent.name, scheduledDestroyIntent],
+    [signalGraphCoaching.name, signalGraphCoaching],
+    [unmaterializedActivationSource.name, unmaterializedActivationSource],
+    [validDetourContract.name, validDetourContract],
+    [deprecationWithoutGuidance.name, deprecationWithoutGuidance],
+    [pendingForce.name, pendingForce],
+    [versionGap.name, versionGap],
+    [versionWithoutExamples.name, versionWithoutExamples],
+    [webhookRouteCollision.name, webhookRouteCollision],
+  ]);

package/src/rules/intent-propagation.ts

@@ -0,0 +1,127 @@
+import type { Intent } from '@ontrails/core';
+import {
+  collectNamedTrailIds,
+  collectTrailIntentsById,
+  extractDefinitionComposeTargetIds,
+  findTrailDefinitions,
+  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 buildIntentPropagationDiagnostic = (
+  trailId: string,
+  targetTrailId: string,
+  targetIntent: Exclude<Intent, 'read'>,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares intent: 'read' but composes "${targetTrailId}" with intent: '${targetIntent}'. Read trails must not compose write or destroy side effects.`,
+  rule: 'intent-propagation',
+  severity: 'warn',
+});
+
+const buildDiagnosticsForComposeTargets = (
+  trailId: string,
+  targetTrailIds: readonly string[],
+  filePath: string,
+  line: number,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] =>
+  targetTrailIds.flatMap((targetTrailId) => {
+    const targetIntent = trailIntentsById.get(targetTrailId);
+    if (!targetIntent || targetIntent === 'read') {
+      return [];
+    }
+
+    return [
+      buildIntentPropagationDiagnostic(
+        trailId,
+        targetTrailId,
+        targetIntent,
+        filePath,
+        line
+      ),
+    ];
+  });
+
+const buildDiagnosticsForTrail = (
+  def: ReturnType<typeof findTrailDefinitions>[number],
+  sourceCode: string,
+  filePath: string,
+  namedTrailIds: ReadonlyMap<string, string>,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (def.kind !== 'trail' || trailIntentsById.get(def.id) !== 'read') {
+    return [];
+  }
+
+  return buildDiagnosticsForComposeTargets(
+    def.id,
+    extractDefinitionComposeTargetIds(def.config, sourceCode, namedTrailIds),
+    filePath,
+    offsetToLine(sourceCode, def.start),
+    trailIntentsById
+  );
+};
+
+const checkIntentPropagation = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  trailIntentsById: ReadonlyMap<string, Intent>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast) {
+    return [];
+  }
+
+  const namedTrailIds = collectNamedTrailIds(ast);
+  return findTrailDefinitions(ast).flatMap((def) =>
+    buildDiagnosticsForTrail(
+      def,
+      sourceCode,
+      filePath,
+      namedTrailIds,
+      trailIntentsById
+    )
+  );
+};
+
+export const intentPropagation: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkIntentPropagation(
+      ast,
+      sourceCode,
+      filePath,
+      ast ? collectTrailIntentsById(ast) : new Map<string, Intent>()
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localTrailIntentsById = ast
+      ? collectTrailIntentsById(ast)
+      : new Map<string, Intent>();
+    const trailIntentsById = new Map(localTrailIntentsById);
+    for (const [trailId, intent] of context.trailIntentsById ?? []) {
+      trailIntentsById.set(trailId, intent);
+    }
+    return checkIntentPropagation(ast, sourceCode, filePath, trailIntentsById);
+  },
+  description:
+    "Warn when a trail declaring intent: 'read' composes a trail whose normalized intent is write or destroy.",
+  name: 'intent-propagation',
+  severity: 'warn',
+};

package/src/rules/layer-field-name-drift.ts

@@ -0,0 +1,96 @@
+import { sep } from 'node:path';
+
+import { identifierName, offsetToLine, parse, walk } from './ast.js';
+import type { AstNode } from './ast.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const RULE_NAME = 'layer-field-name-drift';
+
+const LEGACY_RESERVED_SET_NAMES = new Set(['META_FLAG_CANDIDATES']);
+
+const normalizePath = (filePath: string): string =>
+  filePath.split(sep).join('/');
+
+const isSurfaceSourceFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return /(^|\/)packages\/(cli|http|mcp)\/src\//.test(normalized);
+};
+
+const isTestFile = (filePath: string): boolean => {
+  const normalized = normalizePath(filePath);
+  return (
+    normalized.includes('/__tests__/') || /\.test\.[cm]?tsx?$/.test(normalized)
+  );
+};
+
+const looksLikeLayerReservedNameSet = (name: string): boolean => {
+  const lower = name.toLowerCase();
+  return (
+    LEGACY_RESERVED_SET_NAMES.has(name) ||
+    (lower.includes('layer') &&
+      lower.includes('reserved') &&
+      (lower.includes('name') || lower.includes('flag')))
+  );
+};
+
+const isSetConstruction = (node: AstNode | undefined): boolean => {
+  if (node?.type !== 'NewExpression') {
+    return false;
+  }
+  const { callee } = node as unknown as { callee?: AstNode };
+  return identifierName(callee) === 'Set';
+};
+
+const isLocalReservedSetInitializer = (node: AstNode | undefined): boolean =>
+  node?.type === 'ArrayExpression' || isSetConstruction(node);
+
+const buildDiagnostic = (
+  sourceCode: string,
+  filePath: string,
+  node: AstNode,
+  name: string
+): WardenDiagnostic => ({
+  filePath,
+  line: offsetToLine(sourceCode, node.start),
+  message: `layer-field-name-drift: surface-local reserved name set "${name}" can make layer input fields project differently across surfaces. Import LAYER_FIELD_RESERVED_NAMES from @ontrails/core instead.`,
+  rule: RULE_NAME,
+  severity: 'error',
+});
+
+export const layerFieldNameDrift: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (!isSurfaceSourceFile(filePath) || isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (node.type !== 'VariableDeclarator') {
+        return;
+      }
+      const { id, init } = node as unknown as {
+        id?: AstNode;
+        init?: AstNode;
+      };
+      const name = identifierName(id);
+      if (
+        name &&
+        looksLikeLayerReservedNameSet(name) &&
+        isLocalReservedSetInitializer(init)
+      ) {
+        diagnostics.push(buildDiagnostic(sourceCode, filePath, node, name));
+      }
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Prevent surface-local reserved-name sets from drifting layer input field projection across surfaces.',
+  name: RULE_NAME,
+  severity: 'error',
+};