@ontrails/warden 1.0.0-beta.39 → 1.0.0-beta.41

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

@@ -1,10 +1,16 @@
-import { deriveTopoGraph } from '@ontrails/topographer';
-import type { TopoGraph, TopoGraphEntry } from '@ontrails/topographer';
+import { deriveTopoGraph } from '@ontrails/topography';
+import type { TopoGraph, TopoGraphEntry } from '@ontrails/topography';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
 
 const RULE_NAME = 'duplicate-public-contract';
 const TOPO_FILE = '<topo>';
+const INVERSE_OPERATION_PAIRS = new Map([
+  ['archive', 'restore'],
+  ['disable', 'enable'],
+  ['pause', 'resume'],
+  ['star', 'unstar'],
+]);
 
 const resolveGraph = (
   topo: Parameters<TopoAwareWardenRule['checkTopo']>[0],
@@ -30,9 +36,9 @@ const contractFingerprint = (entry: TopoGraphEntry): string =>
   JSON.stringify(
     canonicalize({
       composes: entry.composes,
-      contours: entry.contours,
       detours: entry.detours,
       dryRunCapable: entry.dryRunCapable,
+      entities: entry.entities,
       fires: entry.fires,
       idempotent: entry.idempotent,
       input: entry.input,
@@ -60,10 +66,46 @@ const renderTrailIds = (trailIds: readonly string[]): string =>
     .map((trailId) => `"${trailId}"`)
     .join(', ');
 
+const splitOperation = (
+  trailId: string
+): { readonly scope: string; readonly operation: string } | undefined => {
+  const separatorIndex = trailId.lastIndexOf('.');
+
+  if (separatorIndex <= 0 || separatorIndex === trailId.length - 1) {
+    return undefined;
+  }
+
+  return {
+    operation: trailId.slice(separatorIndex + 1),
+    scope: trailId.slice(0, separatorIndex),
+  };
+};
+
+const areInverseOperations = (left: string, right: string): boolean =>
+  INVERSE_OPERATION_PAIRS.get(left) === right ||
+  INVERSE_OPERATION_PAIRS.get(right) === left;
+
+const isAcceptedInverseOperationPair = (
+  trailIds: readonly string[]
+): boolean => {
+  if (trailIds.length !== 2) {
+    return false;
+  }
+
+  const [left, right] = trailIds.map(splitOperation);
+
+  return Boolean(
+    left &&
+    right &&
+    left.scope === right.scope &&
+    areInverseOperations(left.operation, right.operation)
+  );
+};
+
 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, contours, composes, signals, and detours. Keep one contract with aliases/input mappings, compose a distinct wrapper, or document why these public contracts are separate.`,
+  message: `Likely duplicate public trail contracts ${renderTrailIds(trailIds)} share the same input, output, intent, permits, resources, entities, 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',
 });
@@ -82,7 +124,10 @@ export const duplicatePublicContract: TopoAwareWardenRule = {
     }
 
     return [...groups.values()]
-      .filter((trailIds) => trailIds.length > 1)
+      .filter(
+        (trailIds) =>
+          trailIds.length > 1 && !isAcceptedInverseOperationPair(trailIds)
+      )
       .map(buildDiagnostic);
   },
   description:

package/src/rules/{contour-exists.ts → entity-exists.ts}

@@ -1,9 +1,12 @@
 import {
   buildUserNamespaceContext,
-  collectContourDefinitionIds,
+  collectEntityDefinitionIds,
   collectImportAliasMap,
-  collectNamedContourIds,
-  deriveContourIdentifierName,
+  collectNamedEntityIds,
+  deriveEntityIdentifierName,
+  isUserNamespaceReceiverAllowed,
+} from './source/entities.js';
+import {
   extractFirstStringArg,
   findConfigProperty,
   findTrailDefinitions,
@@ -12,12 +15,12 @@ import {
   getNodeProperty,
   identifierName,
   isMemberAccessNonComputed,
-  isUserNamespaceReceiverAllowed,
   offsetToLine,
   parse,
-} from './ast.js';
-import type { AstNode, TrailDefinition, UserNamespaceContext } from './ast.js';
-import { mergeKnownContourIds } from './contour-ids.js';
+} from '@ontrails/source';
+import type { AstNode, TrailDefinition } from '@ontrails/source';
+import type { UserNamespaceContext } from './source/entities.js';
+import { mergeKnownEntityIds } from './entity-ids.js';
 import { isTestFile } from './scan.js';
 import type {
   ProjectAwareWardenRule,
@@ -25,17 +28,17 @@ import type {
   WardenDiagnostic,
 } from './types.js';
 
-const isContourCall = (node: AstNode): boolean =>
+const isEntityCall = (node: AstNode): boolean =>
   node.type === 'CallExpression' &&
-  identifierName(getNodeCallee(node)) === 'contour';
+  identifierName(getNodeCallee(node)) === 'entity';
 
-const getContourElements = (config: AstNode): readonly AstNode[] => {
-  const contoursProp = findConfigProperty(config, 'contours');
-  if (!contoursProp) {
+const getEntityElements = (config: AstNode): readonly AstNode[] => {
+  const entitiesProp = findConfigProperty(config, 'entities');
+  if (!entitiesProp) {
     return [];
   }
 
-  const arrayNode = contoursProp.value;
+  const arrayNode = entitiesProp.value;
   if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
     return [];
   }
@@ -47,13 +50,13 @@ const getContourElements = (config: AstNode): readonly AstNode[] => {
 };
 
 /**
- * Resolve `contours.user` to its contour name. When `userNamespace` carries a
+ * Resolve `entities.user` to its entity name. When `userNamespace` carries a
  * scope-aware `safeMemberStarts` set, the member access must appear in it —
- * rejecting cases where `contours` is shadowed by a local binding such as a
- * function parameter or `const contours = ...`. Without the set, falls back
+ * rejecting cases where `entities` is shadowed by a local binding such as a
+ * function parameter or `const entities = ...`. Without the set, falls back
  * to the bare name check for backward compatibility.
  */
-const resolveNamespaceMemberContourName = (
+const resolveNamespaceMemberEntityName = (
   element: AstNode,
   userNamespace: UserNamespaceContext
 ): string | null => {
@@ -72,27 +75,27 @@ const resolveNamespaceMemberContourName = (
   return property ? identifierName(property) : null;
 };
 
-const resolveDeclaredContourName = (
+const resolveDeclaredEntityName = (
   element: AstNode,
-  contourIdsByName: ReadonlyMap<string, string>,
-  knownContourIds?: ReadonlySet<string>,
+  entityIdsByName: ReadonlyMap<string, string>,
+  knownEntityIds?: ReadonlySet<string>,
   importAliases?: ReadonlyMap<string, string>,
   userNamespace?: UserNamespaceContext
 ): string | null => {
   if (element.type === 'Identifier') {
     const name = identifierName(element);
     return name
-      ? deriveContourIdentifierName(
+      ? deriveEntityIdentifierName(
           name,
-          contourIdsByName,
-          knownContourIds,
+          entityIdsByName,
+          knownEntityIds,
           importAliases
         )
       : null;
   }
 
   if (userNamespace && userNamespace.bindings.size > 0) {
-    const namespaceTarget = resolveNamespaceMemberContourName(
+    const namespaceTarget = resolveNamespaceMemberEntityName(
       element,
       userNamespace
     );
@@ -101,40 +104,40 @@ const resolveDeclaredContourName = (
     }
   }
 
-  return isContourCall(element) ? extractFirstStringArg(element) : null;
+  return isEntityCall(element) ? extractFirstStringArg(element) : null;
 };
 
-const extractDeclaredContourNames = (
+const extractDeclaredEntityNames = (
   config: AstNode,
-  contourIdsByName: ReadonlyMap<string, string>,
-  knownContourIds?: ReadonlySet<string>,
+  entityIdsByName: ReadonlyMap<string, string>,
+  knownEntityIds?: ReadonlySet<string>,
   importAliases?: ReadonlyMap<string, string>,
   userNamespace?: UserNamespaceContext
 ): readonly string[] => [
   ...new Set(
-    getContourElements(config).flatMap((element) => {
-      const contourName = resolveDeclaredContourName(
+    getEntityElements(config).flatMap((element) => {
+      const entityName = resolveDeclaredEntityName(
         element,
-        contourIdsByName,
-        knownContourIds,
+        entityIdsByName,
+        knownEntityIds,
         importAliases,
         userNamespace
       );
-      return contourName ? [contourName] : [];
+      return entityName ? [entityName] : [];
     })
   ),
 ];
 
-const buildMissingContourDiagnostic = (
+const buildMissingEntityDiagnostic = (
   trailId: string,
-  contourName: string,
+  entityName: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}" declares contour "${contourName}" which is not defined in the project. Define it with contour('${contourName}', ...) and include it in the topo, or fix the contours entry if this is a typo.`,
-  rule: 'contour-exists',
+  message: `Trail "${trailId}" declares entity "${entityName}" which is not defined in the project. Define it with entity('${entityName}', ...) and include it in the topo, or fix the entities entry if this is a typo.`,
+  rule: 'entity-exists',
   severity: 'error',
 });
 
@@ -142,8 +145,8 @@ const buildDiagnosticsForDefinition = (
   definition: TrailDefinition,
   sourceCode: string,
   filePath: string,
-  knownContourIds: ReadonlySet<string>,
-  contourIdsByName: ReadonlyMap<string, string>,
+  knownEntityIds: ReadonlySet<string>,
+  entityIdsByName: ReadonlyMap<string, string>,
   importAliases: ReadonlyMap<string, string>,
   userNamespace: UserNamespaceContext
 ): readonly WardenDiagnostic[] => {
@@ -152,19 +155,19 @@ const buildDiagnosticsForDefinition = (
   }
 
   const line = offsetToLine(sourceCode, definition.start);
-  return extractDeclaredContourNames(
+  return extractDeclaredEntityNames(
     definition.config,
-    contourIdsByName,
-    knownContourIds,
+    entityIdsByName,
+    knownEntityIds,
     importAliases,
     userNamespace
-  ).flatMap((contourName) =>
-    knownContourIds.has(contourName)
+  ).flatMap((entityName) =>
+    knownEntityIds.has(entityName)
       ? []
       : [
-          buildMissingContourDiagnostic(
+          buildMissingEntityDiagnostic(
             definition.id,
-            contourName,
+            entityName,
             filePath,
             line
           ),
@@ -172,13 +175,13 @@ const buildDiagnosticsForDefinition = (
   );
 };
 
-const buildContourDiagnostics = (
+const buildEntityDiagnostics = (
   ast: AstNode,
   sourceCode: string,
   filePath: string,
-  knownContourIds: ReadonlySet<string>
+  knownEntityIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] => {
-  const contourIdsByName = collectNamedContourIds(ast);
+  const entityIdsByName = collectNamedEntityIds(ast);
   const importAliases = collectImportAliasMap(ast);
   const userNamespace = buildUserNamespaceContext(ast);
 
@@ -187,43 +190,43 @@ const buildContourDiagnostics = (
       definition,
       sourceCode,
       filePath,
-      knownContourIds,
-      contourIdsByName,
+      knownEntityIds,
+      entityIdsByName,
       importAliases,
       userNamespace
     )
   );
 };
 
-const checkContourDeclarations = (
+const checkEntityDeclarations = (
   ast: AstNode,
   sourceCode: string,
   filePath: string,
-  knownContourIds: ReadonlySet<string>
+  knownEntityIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] => {
   if (isTestFile(filePath)) {
     return [];
   }
 
-  return buildContourDiagnostics(ast, sourceCode, filePath, knownContourIds);
+  return buildEntityDiagnostics(ast, sourceCode, filePath, knownEntityIds);
 };
 
 /**
- * Checks that every contour declared in a trail `contours` array resolves to a
- * known contour definition.
+ * Checks that every entity declared in a trail `entities` array resolves to a
+ * known entity definition.
  */
-export const contourExists: ProjectAwareWardenRule = {
+export const entityExists: ProjectAwareWardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
       return [];
     }
 
-    return checkContourDeclarations(
+    return checkEntityDeclarations(
       ast,
       sourceCode,
       filePath,
-      collectContourDefinitionIds(ast)
+      collectEntityDefinitionIds(ast)
     );
   },
   checkWithContext(
@@ -236,16 +239,16 @@ export const contourExists: ProjectAwareWardenRule = {
       return [];
     }
 
-    const localContourIds = collectContourDefinitionIds(ast);
-    return checkContourDeclarations(
+    const localEntityIds = collectEntityDefinitionIds(ast);
+    return checkEntityDeclarations(
       ast,
       sourceCode,
       filePath,
-      mergeKnownContourIds(localContourIds, context.knownContourIds)
+      mergeKnownEntityIds(localEntityIds, context.knownEntityIds)
     );
   },
   description:
-    'Ensure every contour declared on a trail resolves to a known contour definition.',
-  name: 'contour-exists',
+    'Ensure every entity declared on a trail resolves to a known entity definition.',
+  name: 'entity-exists',
   severity: 'error',
 };

package/src/rules/entity-ids.ts

@@ -0,0 +1,15 @@
+/**
+ * Merge a file's locally-defined entity IDs with the project-wide set.
+ *
+ * Rules that run with a `ProjectContext` need to treat both local and
+ * project-wide entity definitions as "known" so that declarations and
+ * references resolve correctly. When no project context is available — e.g.
+ * single-file lint runs via `check` — the local set is returned as-is.
+ */
+export const mergeKnownEntityIds = (
+  localEntityIds: ReadonlySet<string>,
+  projectEntityIds?: ReadonlySet<string>
+): ReadonlySet<string> =>
+  projectEntityIds
+    ? new Set([...projectEntityIds, ...localEntityIds])
+    : localEntityIds;

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

@@ -18,8 +18,8 @@ import {
   offsetToLine,
   parse,
   walk,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';