@ontrails/warden 1.0.0-beta.4 → 1.0.0-beta.42

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

@@ -0,0 +1,188 @@
+import { buildSignalIdentifierResolver } from './source/signals.js';
+import {
+  deriveConstString,
+  extractStringLiteral,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeElements,
+  getNodeId,
+  getNodeInit,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import type { SignalIdentifierResolver } from './source/signals.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 = getNodeId(node);
+    const init = getNodeInit(node);
+    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 getNodeElements(array).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,97 @@
+import {
+  collectEntityDefinitionIds,
+  collectEntityReferenceSites,
+} from './source/entities.js';
+import { offsetToLine, parse } from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { mergeKnownEntityIds } from './entity-ids.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const buildMissingReferenceDiagnostic = (
+  sourceEntity: string,
+  field: string,
+  targetEntity: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Entity "${sourceEntity}" field "${field}" references entity "${targetEntity}" which is not defined in the project. Define it with entity('${targetEntity}', ...) and include it in the topo, or fix the field reference if this is a typo.`,
+  rule: 'reference-exists',
+  severity: 'error',
+});
+
+const checkEntityReferences = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownEntityIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  return collectEntityReferenceSites(ast, knownEntityIds).flatMap(
+    (reference) => {
+      if (knownEntityIds.has(reference.target)) {
+        return [];
+      }
+
+      return [
+        buildMissingReferenceDiagnostic(
+          reference.source,
+          reference.field,
+          reference.target,
+          filePath,
+          offsetToLine(sourceCode, reference.start)
+        ),
+      ];
+    }
+  );
+};
+
+/**
+ * Checks that every entity `.id()` reference resolves to a known entity.
+ */
+export const referenceExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    return checkEntityReferences(
+      ast,
+      sourceCode,
+      filePath,
+      collectEntityDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const localEntityIds = collectEntityDefinitionIds(ast);
+    return checkEntityReferences(
+      ast,
+      sourceCode,
+      filePath,
+      mergeKnownEntityIds(localEntityIds, context.knownEntityIds)
+    );
+  },
+  description:
+    'Ensure every entity field declared via .id() resolves to a known entity.',
+  name: 'reference-exists',
+  severity: 'error',
+};

package/src/rules/registry-names.ts

@@ -0,0 +1,167 @@
+/**
+ * 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 { capturedKernel } from './captured-kernel.js';
+import { cliCommandRouteCoherence } from './cli-command-route-coherence.js';
+import { circularRefs } from './circular-refs.js';
+import { entityExists } from './entity-exists.js';
+import { contextNoSurfaceTypes } from './context-no-surface-types.js';
+import { composesDeclarations } from './composes-declarations.js';
+import { deadInternalTrail } from './dead-internal-trail.js';
+import { deadPublicTrail } from './dead-public-trail.js';
+import { draftFileMarking } from './draft-file-marking.js';
+import { draftVisibleDebt } from './draft-visible-debt.js';
+import { duplicateExportedSymbol } from './duplicate-exported-symbol.js';
+import { duplicatePublicContract } from './duplicate-public-contract.js';
+import { errorMappingCompleteness } from './error-mapping-completeness.js';
+import { exampleValid } from './example-valid.js';
+import { firesDeclarations } from './fires-declarations.js';
+import { governedSymbolResidue } from './governed-symbol-residue.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 { libraryProjectionCoherence } from './library-projection-coherence.js';
+import { missingReconcile } from './missing-reconcile.js';
+import { missingVisibility } from './missing-visibility.js';
+import { noDevPermitInSource } from './no-dev-permit-in-source.js';
+import { noDestructuredCompose } from './no-destructured-compose.js';
+import { noLegacyCliAliasExport } from './no-legacy-cli-alias-export.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 { 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 { 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 { surfaceOverlayCoherence } from './surface-overlay-coherence.js';
+import { surfaceTrailheadCoherence } from './surface-trailhead-coherence.js';
+import { trailForkCoaching } from './trail-fork-coaching.js';
+import { trailheadOverrideDivergence } from './trailhead-override-divergence.js';
+import {
+  forkWithoutPreservedImplementation,
+  markerSchemaUnsupported,
+  versionPinnedCompose,
+} from './trail-versioning-source.js';
+import {
+  deprecationWithoutGuidance,
+  pendingForce,
+  versionGap,
+  versionWithoutExamples,
+} from './trail-versioning-topo.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,
+  capturedKernel.name,
+  cliCommandRouteCoherence.name,
+  circularRefs.name,
+  contextNoSurfaceTypes.name,
+  entityExists.name,
+  composesDeclarations.name,
+  deadInternalTrail.name,
+  deadPublicTrail.name,
+  deprecationWithoutGuidance.name,
+  duplicateExportedSymbol.name,
+  duplicatePublicContract.name,
+  draftFileMarking.name,
+  draftVisibleDebt.name,
+  errorMappingCompleteness.name,
+  exampleValid.name,
+  firesDeclarations.name,
+  governedSymbolResidue.name,
+  forkWithoutPreservedImplementation.name,
+  implementationReturnsResult.name,
+  incompleteAccessorForStandardOp.name,
+  incompleteCrud.name,
+  intentPropagation.name,
+  layerFieldNameDrift.name,
+  libraryProjectionCoherence.name,
+  markerSchemaUnsupported.name,
+  missingReconcile.name,
+  missingVisibility.name,
+  noDevPermitInSource.name,
+  noDestructuredCompose.name,
+  noLegacyCliAliasExport.name,
+  noLegacyLayerImports.name,
+  noDirectImplementationCall.name,
+  noNativeErrorResult.name,
+  noRedundantResultErrorWrap.name,
+  noRetiredCrossVocabulary.name,
+  noSyncResultAssumption.name,
+  noThrowInDetourRecover.name,
+  noThrowInImplementation.name,
+  noTopLevelSurface.name,
+  onReferencesExist.name,
+  orphanedSignal.name,
+  ownerProjectionParity.name,
+  pendingForce.name,
+  permitGovernance.name,
+  preferSchemaInference.name,
+  publicExportExampleCoverage.name,
+  publicInternalDeepImports.name,
+  publicOutputSchema.name,
+  publicUnionOutputDiscriminants.name,
+  readIntentFires.name,
+  referenceExists.name,
+  resolvedImportBoundary.name,
+  resourceDeclarations.name,
+  resourceExists.name,
+  resourceIdGrammar.name,
+  resourceMockCoverage.name,
+  scheduledDestroyIntent.name,
+  signalGraphCoaching.name,
+  staticResourceAccessorPreference.name,
+  surfaceOverlayCoherence.name,
+  surfaceTrailheadCoherence.name,
+  trailForkCoaching.name,
+  trailheadOverrideDivergence.name,
+  unmaterializedActivationSource.name,
+  unreachableDetourShadowing.name,
+  validDetourContract.name,
+  validDescribeRefs.name,
+  versionGap.name,
+  versionPinnedCompose.name,
+  versionWithoutExamples.name,
+  wardenRulesUseAst.name,
+  webhookRouteCollision.name,
+];

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

@@ -0,0 +1,146 @@
+import { hasIgnoreCommentOnLine, splitSourceLines } from './source/pragmas.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}" composes 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 compose-package imports resolve through package-owned public exports.',
+  name: RULE_NAME,
+  severity: 'error',
+};