@ontrails/warden 1.0.0-beta.23 → 1.0.0-beta.29

package/src/rules/contour-exists.ts

@@ -3,15 +3,18 @@ import {
   collectContourDefinitionIds,
   collectImportAliasMap,
   collectNamedContourIds,
+  deriveContourIdentifierName,
   extractFirstStringArg,
   findConfigProperty,
   findTrailDefinitions,
+  getNodeCallee,
+  getNodeObject,
+  getNodeProperty,
   identifierName,
   isMemberAccessNonComputed,
   isUserNamespaceReceiverAllowed,
   offsetToLine,
   parse,
-  deriveContourIdentifierName,
 } from './ast.js';
 import type { AstNode, TrailDefinition, UserNamespaceContext } from './ast.js';
 import { mergeKnownContourIds } from './contour-ids.js';
@@ -24,8 +27,7 @@ import type {
 
 const isContourCall = (node: AstNode): boolean =>
   node.type === 'CallExpression' &&
-  identifierName((node as unknown as { callee?: AstNode }).callee) ===
-    'contour';
+  identifierName(getNodeCallee(node)) === 'contour';
 
 const getContourElements = (config: AstNode): readonly AstNode[] => {
   const contoursProp = findConfigProperty(config, 'contours');
@@ -58,10 +60,8 @@ const resolveNamespaceMemberContourName = (
   if (!isMemberAccessNonComputed(element)) {
     return null;
   }
-  const { object, property } = element as unknown as {
-    readonly object?: AstNode;
-    readonly property?: AstNode;
-  };
+  const object = getNodeObject(element);
+  const property = getNodeProperty(element);
   const receiver = object ? identifierName(object) : null;
   if (
     !receiver ||

package/src/rules/dead-internal-trail.ts

@@ -2,6 +2,7 @@ import {
   collectComposeTargetTrailIds,
   findConfigProperty,
   findTrailDefinitions,
+  getNodeValue,
   getStringValue,
   isStringLiteral,
   offsetToLine,
@@ -56,7 +57,7 @@ const hasLegacyMetaInternal = (config: AstNode): boolean => {
   const internalValue = internalProp?.value as AstNode | undefined;
   return (
     internalValue?.type === 'BooleanLiteral' &&
-    (internalValue as unknown as { value: boolean }).value === true
+    getNodeValue(internalValue) === true
   );
 };
 
@@ -79,7 +80,8 @@ const checkDeadInternalTrails = (
   ast: AstNode | null,
   sourceCode: string,
   filePath: string,
-  composedTrailIds: ReadonlySet<string>
+  composedTrailIds: ReadonlySet<string>,
+  topoTrailIds?: ReadonlySet<string> | undefined
 ): readonly WardenDiagnostic[] => {
   if (isTestFile(filePath) || !ast) {
     return [];
@@ -92,7 +94,11 @@ const checkDeadInternalTrails = (
       continue;
     }
 
-    if (hasOnActivation(def.config) || composedTrailIds.has(def.id)) {
+    if (
+      hasOnActivation(def.config) ||
+      composedTrailIds.has(def.id) ||
+      topoTrailIds?.has(def.id)
+    ) {
       continue;
     }
 
@@ -144,7 +150,8 @@ export const deadInternalTrail: ProjectAwareWardenRule = {
       ast,
       sourceCode,
       filePath,
-      composeTargetTrailIds
+      composeTargetTrailIds,
+      context.topoTrailIds
     );
   },
   description:

package/src/rules/dead-public-trail.ts

@@ -0,0 +1,258 @@
+import {
+  collectComposeTargetTrailIds,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeDeclaration,
+  getNodeDeclarations,
+  getNodeId,
+  getNodeInit,
+  getNodeLocal,
+  getNodeName,
+  getNodeSpecifiers,
+  getNodeValue,
+  getStringValue,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walkWithParents,
+} from './ast.js';
+import type { AstNode, AstParentContext } from './ast.js';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const RULE_NAME = 'dead-public-trail';
+
+const isNonEmptyActivationValue = (onValue: AstNode): boolean => {
+  if (onValue.type === 'Identifier') {
+    return true;
+  }
+  if (onValue.type !== 'ArrayExpression') {
+    return false;
+  }
+  const elements = onValue['elements'] as readonly AstNode[] | undefined;
+  return (elements?.length ?? 0) > 0;
+};
+
+const hasOnActivation = (config: AstNode): boolean => {
+  const onProp = findConfigProperty(config, 'on');
+  const onValue = onProp?.value as AstNode | undefined;
+  return onValue ? isNonEmptyActivationValue(onValue) : false;
+};
+
+const hasExplicitInternalVisibility = (config: AstNode): boolean => {
+  const visibilityProp = findConfigProperty(config, 'visibility');
+  const visibilityValue = visibilityProp?.value as AstNode | undefined;
+  return (
+    !!visibilityValue &&
+    isStringLiteral(visibilityValue) &&
+    getStringValue(visibilityValue) === 'internal'
+  );
+};
+
+const hasLegacyMetaInternal = (config: AstNode): boolean => {
+  const metaProp = findConfigProperty(config, 'meta');
+  const metaValue = metaProp?.value as AstNode | undefined;
+  if (!metaValue || metaValue.type !== 'ObjectExpression') {
+    return false;
+  }
+  const internalProp = findConfigProperty(metaValue, 'internal');
+  const internalValue = internalProp?.value as AstNode | undefined;
+  return (
+    internalValue?.type === 'BooleanLiteral' &&
+    getNodeValue(internalValue) === true
+  );
+};
+
+const isInternalTrail = (config: AstNode): boolean =>
+  hasExplicitInternalVisibility(config) || hasLegacyMetaInternal(config);
+
+const isExportDeclaration = (node: AstNode | null | undefined): boolean =>
+  node?.type === 'ExportNamedDeclaration' ||
+  node?.type === 'ExportDefaultDeclaration';
+
+const identifierName = (node: AstNode | undefined): string | null =>
+  node?.type === 'Identifier' ? (getNodeName(node) ?? null) : null;
+
+const trailBindingStarts = (ast: AstNode): ReadonlyMap<string, number> => {
+  const trailStarts = new Set(
+    findTrailDefinitions(ast)
+      .filter((definition) => definition.kind === 'trail')
+      .map((definition) => definition.start)
+  );
+  const bindings = new Map<string, number>();
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+    const id = getNodeId(node);
+    const init = getNodeInit(node);
+    const name = identifierName(id);
+    if (name && init && trailStarts.has(init.start)) {
+      bindings.set(name, init.start);
+    }
+  });
+
+  return bindings;
+};
+
+const addExportedSpecifierStarts = (
+  node: AstNode,
+  bindings: ReadonlyMap<string, number>,
+  exported: Set<number>
+): void => {
+  const specifiers = getNodeSpecifiers(node) ?? [];
+  for (const specifier of specifiers) {
+    const local = getNodeLocal(specifier);
+    const name = identifierName(local);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  }
+};
+
+const exportedTrailStarts = (ast: AstNode): ReadonlySet<number> => {
+  const exported = new Set<number>();
+  const bindings = trailBindingStarts(ast);
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'CallExpression') {
+      return;
+    }
+
+    // Catch `export default trail(...)`. Exported variable declarations are
+    // handled by the VariableDeclaration walk below.
+    if (isExportDeclaration(context.parent)) {
+      exported.add(node.start);
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode, context: AstParentContext) => {
+    if (node.type !== 'VariableDeclaration') {
+      return;
+    }
+    if (!isExportDeclaration(context.parent)) {
+      return;
+    }
+    const declarations = getNodeDeclarations(node) ?? [];
+    for (const declaration of declarations) {
+      const init = getNodeInit(declaration);
+      if (init?.type === 'CallExpression') {
+        exported.add(init.start);
+      }
+    }
+  });
+
+  walkWithParents(ast, (node: AstNode) => {
+    if (node.type === 'ExportNamedDeclaration') {
+      addExportedSpecifierStarts(node, bindings, exported);
+      return;
+    }
+
+    if (node.type !== 'ExportDefaultDeclaration') {
+      return;
+    }
+    const declaration = getNodeDeclaration(node);
+    const name = identifierName(declaration);
+    const start = name ? bindings.get(name) : undefined;
+    if (start !== undefined) {
+      exported.add(start);
+    }
+  });
+
+  return exported;
+};
+
+const buildDiagnostic = (
+  trailId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Exported public trail "${trailId}" is not registered in a configured app topo, composed by another trail, or activated by on:. Anchor the contract in a topo, compose it, mark it internal, or remove the public export.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+const unionComposeTargetIds = (
+  ast: AstNode | null,
+  sourceCode: string,
+  context: ProjectContext
+): ReadonlySet<string> => {
+  const local = ast
+    ? collectComposeTargetTrailIds(ast, sourceCode)
+    : new Set<string>();
+  return context.composeTargetTrailIds
+    ? new Set([...context.composeTargetTrailIds, ...local])
+    : local;
+};
+
+const checkDeadPublicTrails = (
+  ast: AstNode | null,
+  sourceCode: string,
+  filePath: string,
+  context: ProjectContext
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath) || !ast || !context.topoTrailIds) {
+    return [];
+  }
+
+  const exportedStarts = exportedTrailStarts(ast);
+  const composeTargetTrailIds = unionComposeTargetIds(ast, sourceCode, context);
+  const diagnostics: WardenDiagnostic[] = [];
+
+  for (const def of findTrailDefinitions(ast)) {
+    if (
+      def.kind !== 'trail' ||
+      isInternalTrail(def.config) ||
+      !exportedStarts.has(def.start)
+    ) {
+      continue;
+    }
+
+    if (
+      hasOnActivation(def.config) ||
+      composeTargetTrailIds.has(def.id) ||
+      context.topoTrailIds.has(def.id)
+    ) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildDiagnostic(def.id, filePath, offsetToLine(sourceCode, def.start))
+    );
+  }
+
+  return diagnostics;
+};
+
+export const deadPublicTrail: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    return checkDeadPublicTrails(ast, sourceCode, filePath, {
+      knownTrailIds: new Set<string>(),
+    });
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    return checkDeadPublicTrails(
+      parse(filePath, sourceCode),
+      sourceCode,
+      filePath,
+      context
+    );
+  },
+  description:
+    'Warn when an exported public trail is neither registered in configured app topos nor reachable through composition or activation.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/duplicate-public-contract.ts

@@ -0,0 +1,91 @@
+import { deriveTopoGraph } from '@ontrails/topographer';
+import type { TopoGraph, TopoGraphEntry } from '@ontrails/topographer';
+
+import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
+
+const RULE_NAME = 'duplicate-public-contract';
+const TOPO_FILE = '<topo>';
+
+const resolveGraph = (
+  topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
+  graph: TopoGraph | undefined
+): TopoGraph => graph ?? deriveTopoGraph(topo);
+
+const canonicalize = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .toSorted(([left], [right]) => left.localeCompare(right))
+        .map(([key, entryValue]) => [key, canonicalize(entryValue)])
+    );
+  }
+  return value;
+};
+
+const contractFingerprint = (entry: TopoGraphEntry): string =>
+  JSON.stringify(
+    canonicalize({
+      composes: entry.composes,
+      detours: entry.detours,
+      dryRunCapable: entry.dryRunCapable,
+      fires: entry.fires,
+      idempotent: entry.idempotent,
+      input: entry.input,
+      intent: entry.intent,
+      meta: entry.meta,
+      on: entry.on,
+      output: entry.output,
+      permit: entry.permit,
+      resources: entry.resources,
+    })
+  );
+
+const isCandidate = (entry: TopoGraphEntry): boolean =>
+  entry.kind === 'trail' &&
+  !entry.id.startsWith('warden.rule.') &&
+  entry.deprecated !== true &&
+  entry.meta?.['internal'] !== true &&
+  entry.input !== undefined &&
+  entry.output !== undefined &&
+  Boolean(entry.cli || entry.surfaces.length > 0);
+
+const renderTrailIds = (trailIds: readonly string[]): string =>
+  trailIds
+    .toSorted((left, right) => left.localeCompare(right))
+    .map((trailId) => `"${trailId}"`)
+    .join(', ');
+
+const buildDiagnostic = (trailIds: readonly string[]): WardenDiagnostic => ({
+  filePath: TOPO_FILE,
+  line: 1,
+  message: `Likely duplicate public trail contracts ${renderTrailIds(trailIds)} share the same input, output, intent, permits, resources, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.`,
+  rule: RULE_NAME,
+  severity: 'warn',
+});
+
+export const duplicatePublicContract: TopoAwareWardenRule = {
+  checkTopo(topo, context) {
+    const graph = resolveGraph(topo, context?.graph);
+    const groups = new Map<string, string[]>();
+
+    for (const entry of graph.entries) {
+      if (!isCandidate(entry)) {
+        continue;
+      }
+      const key = contractFingerprint(entry);
+      groups.set(key, [...(groups.get(key) ?? []), entry.id]);
+    }
+
+    return [...groups.values()]
+      .filter((trailIds) => trailIds.length > 1)
+      .map(buildDiagnostic);
+  },
+  description:
+    'Warn when public surface trails expose the same normalized contract facts.',
+  name: RULE_NAME,
+  severity: 'warn',
+};

package/src/rules/error-mapping-completeness.ts

@@ -10,6 +10,8 @@ import { codesByCategory, errorClasses } from '@ontrails/core';
 import type { ErrorCategory } from '@ontrails/core';
 
 import {
+  getNodeKey,
+  getNodeValueNode,
   getStringValue,
   identifierName,
   isStringLiteral,
@@ -82,9 +84,9 @@ const findObjectPropertyValue = (
       continue;
     }
 
-    const key = getPropertyName((property as unknown as { key?: AstNode }).key);
+    const key = getPropertyName(getNodeKey(property));
     if (key === propertyName) {
-      return (property as unknown as { value?: AstNode }).value ?? null;
+      return getNodeValueNode(property) ?? null;
     }
   }
 
@@ -157,7 +159,7 @@ const addMappedCategory = (
     return true;
   }
 
-  const key = getPropertyName((property as unknown as { key?: AstNode }).key);
+  const key = getPropertyName(getNodeKey(property));
   if (key) {
     categories.add(key);
   }

package/src/rules/example-valid.ts

@@ -5,6 +5,9 @@ import {
   extractStringLiteral,
   findConfigProperty,
   findContourDefinitions,
+  getNodeExpression,
+  getNodeObject,
+  getNodeProperty,
   getStringValue,
   identifierName,
   offsetToLine,
@@ -115,11 +118,7 @@ const evaluateIdentifierExpression: ContourNodeEvaluator = (
 const evaluateWrappedExpression: ContourNodeEvaluator = (
   node: AstNode,
   env: ContourEvaluationEnvironment
-): unknown =>
-  evaluateNode(
-    requireNode((node as unknown as { expression?: AstNode }).expression),
-    env
-  );
+): unknown => evaluateNode(requireNode(getNodeExpression(node)), env);
 
 const evaluateNullExpression: ContourNodeEvaluator = (): null => null;
 
@@ -215,13 +214,8 @@ const evaluateMemberCall = (
   args: readonly unknown[],
   env: ContourEvaluationEnvironment
 ): unknown => {
-  const receiver = evaluateNode(
-    requireNode((callee as unknown as { object?: AstNode }).object),
-    env
-  );
-  const propertyName = getPropertyName(
-    (callee as unknown as { property?: AstNode }).property
-  );
+  const receiver = evaluateNode(requireNode(getNodeObject(callee)), env);
+  const propertyName = getPropertyName(getNodeProperty(callee));
   if (!propertyName) {
     throw new UnsupportedContourEvaluationError(
       'Unsupported member property in contour evaluation.'