@ontrails/warden 1.0.0-beta.13 → 1.0.0-beta.15

package/src/rules/{provision-exists.ts → resource-exists.ts}

@@ -1,6 +1,8 @@
+import { isDraftId } from '@ontrails/core';
+
 import {
-  collectNamedProvisionIds,
-  collectProvisionDefinitionIds,
+  collectNamedResourceIds,
+  collectResourceDefinitionIds,
   extractFirstStringArg,
   findConfigProperty,
   findTrailDefinitions,
@@ -18,18 +20,18 @@ import type {
   WardenDiagnostic,
 } from './types.js';
 
-const isProvisionCall = (node: AstNode): boolean =>
+const isResourceCall = (node: AstNode): boolean =>
   node.type === 'CallExpression' &&
   identifierName((node as unknown as { callee?: AstNode }).callee) ===
-    'provision';
+    'resource';
 
-const getProvisionElements = (config: AstNode): readonly AstNode[] => {
-  const provisionsProp = findConfigProperty(config, 'provisions');
-  if (!provisionsProp) {
+const getResourceElements = (config: AstNode): readonly AstNode[] => {
+  const resourcesProp = findConfigProperty(config, 'resources');
+  if (!resourcesProp) {
     return [];
   }
 
-  const arrayNode = provisionsProp.value;
+  const arrayNode = resourcesProp.value;
   if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
     return [];
   }
@@ -40,93 +42,93 @@ const getProvisionElements = (config: AstNode): readonly AstNode[] => {
   return elements ?? [];
 };
 
-const extractDeclaredProvisionId = (
+const extractDeclaredResourceId = (
   element: AstNode,
-  provisionIdsByName: ReadonlyMap<string, string>
+  resourceIdsByName: ReadonlyMap<string, string>
 ): string | null => {
   if (element.type === 'Identifier') {
     const name = identifierName(element);
-    return name ? (provisionIdsByName.get(name) ?? null) : null;
+    return name ? (resourceIdsByName.get(name) ?? null) : null;
   }
 
   if (isStringLiteral(element)) {
     return getStringValue(element);
   }
 
-  return isProvisionCall(element) ? extractFirstStringArg(element) : null;
+  return isResourceCall(element) ? extractFirstStringArg(element) : null;
 };
 
-const extractDeclaredProvisionIds = (
+const extractDeclaredResourceIds = (
   config: AstNode,
-  provisionIdsByName: ReadonlyMap<string, string>
+  resourceIdsByName: ReadonlyMap<string, string>
 ): readonly string[] => [
   ...new Set(
-    getProvisionElements(config).flatMap((element) => {
-      const id = extractDeclaredProvisionId(element, provisionIdsByName);
+    getResourceElements(config).flatMap((element) => {
+      const id = extractDeclaredResourceId(element, resourceIdsByName);
       return id ? [id] : [];
     })
   ),
 ];
 
-const buildMissingProvisionDiagnostic = (
+const buildMissingResourceDiagnostic = (
   trailId: string,
-  provisionId: string,
+  resourceId: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}" declares provision "${provisionId}" which is not defined in the project.`,
-  rule: 'provision-exists',
+  message: `Trail "${trailId}" declares resource "${resourceId}" which is not defined in the project.`,
+  rule: 'resource-exists',
   severity: 'error',
 });
 
-const reportMissingProvisions = (
+const reportMissingResources = (
   def: { id: string; config: AstNode; start: number },
   sourceCode: string,
-  provisionIdsByName: ReadonlyMap<string, string>,
+  resourceIdsByName: ReadonlyMap<string, string>,
   filePath: string,
-  knownProvisionIds: ReadonlySet<string>,
+  knownResourceIds: ReadonlySet<string>,
   diagnostics: WardenDiagnostic[]
 ): void => {
   const line = offsetToLine(sourceCode, def.start);
-  for (const provisionId of extractDeclaredProvisionIds(
+  for (const resourceId of extractDeclaredResourceIds(
     def.config,
-    provisionIdsByName
+    resourceIdsByName
   )) {
-    if (!knownProvisionIds.has(provisionId)) {
+    if (!knownResourceIds.has(resourceId) && !isDraftId(resourceId)) {
       diagnostics.push(
-        buildMissingProvisionDiagnostic(def.id, provisionId, filePath, line)
+        buildMissingResourceDiagnostic(def.id, resourceId, filePath, line)
       );
     }
   }
 };
 
-const buildProvisionDiagnostics = (
+const buildResourceDiagnostics = (
   ast: AstNode,
   sourceCode: string,
   filePath: string,
-  knownProvisionIds: ReadonlySet<string>
+  knownResourceIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] => {
   const diagnostics: WardenDiagnostic[] = [];
-  const provisionIdsByName = collectNamedProvisionIds(ast);
+  const resourceIdsByName = collectNamedResourceIds(ast);
   for (const def of findTrailDefinitions(ast)) {
-    reportMissingProvisions(
+    reportMissingResources(
       def,
       sourceCode,
-      provisionIdsByName,
+      resourceIdsByName,
       filePath,
-      knownProvisionIds,
+      knownResourceIds,
       diagnostics
     );
   }
   return diagnostics;
 };
 
-const checkProvisionsExist = (
+const checkResourcesExist = (
   sourceCode: string,
   filePath: string,
-  knownProvisionIds: ReadonlySet<string>
+  knownResourceIds: ReadonlySet<string>
 ): readonly WardenDiagnostic[] => {
   if (isTestFile(filePath)) {
     return [];
@@ -137,27 +139,22 @@ const checkProvisionsExist = (
     return [];
   }
 
-  return buildProvisionDiagnostics(
-    ast,
-    sourceCode,
-    filePath,
-    knownProvisionIds
-  );
+  return buildResourceDiagnostics(ast, sourceCode, filePath, knownResourceIds);
 };
 
 /**
- * Checks that all declared provisions resolve to known provision definitions.
+ * Checks that all declared resources resolve to known resource definitions.
  */
-export const provisionExists: ProjectAwareWardenRule = {
+export const resourceExists: ProjectAwareWardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
       return [];
     }
-    return checkProvisionsExist(
+    return checkResourcesExist(
       sourceCode,
       filePath,
-      collectProvisionDefinitionIds(ast)
+      collectResourceDefinitionIds(ast)
     );
   },
   checkWithContext(
@@ -166,17 +163,17 @@ export const provisionExists: ProjectAwareWardenRule = {
     context: ProjectContext
   ): readonly WardenDiagnostic[] {
     const ast = parse(filePath, sourceCode);
-    const localProvisionIds = ast
-      ? collectProvisionDefinitionIds(ast)
+    const localResourceIds = ast
+      ? collectResourceDefinitionIds(ast)
       : new Set<string>();
-    return checkProvisionsExist(
+    return checkResourcesExist(
       sourceCode,
       filePath,
-      context.knownProvisionIds ?? localProvisionIds
+      context.knownResourceIds ?? localResourceIds
     );
   },
   description:
-    'Ensure every provision declared on a trail resolves to a known provision definition.',
-  name: 'provision-exists',
+    'Ensure every resource declared on a trail resolves to a known resource definition.',
+  name: 'resource-exists',
   severity: 'error',
 };

package/src/rules/resource-id-grammar.ts

@@ -0,0 +1,65 @@
+import {
+  extractFirstStringArg,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from './ast.js';
+import type { AstNode } from './ast.js';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) ===
+    'resource';
+
+const buildDiagnostic = (
+  resourceId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Resource "${resourceId}" is invalid because resource ids may not contain ":".`,
+  rule: 'resource-id-grammar',
+  severity: 'error',
+});
+
+export const resourceIdGrammar: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (!isResourceCall(node)) {
+        return;
+      }
+
+      const resourceId = extractFirstStringArg(node);
+      if (!resourceId || !resourceId.includes(':')) {
+        return;
+      }
+
+      diagnostics.push(
+        buildDiagnostic(
+          resourceId,
+          filePath,
+          offsetToLine(sourceCode, node.start)
+        )
+      );
+    });
+
+    return diagnostics;
+  },
+  description: 'Ensure resource ids do not contain the ":" scope separator.',
+  name: 'resource-id-grammar',
+  severity: 'error',
+};

package/src/rules/specs.ts

@@ -31,7 +31,11 @@ export interface SchemaFieldInfo {
   readonly required: boolean;
 }
 
-const TRAIL_LIKE_PATTERN = /\b(trail|event)\s*\(/g;
+// Match `trail(...)` / `signal(...)` declaration sites, not method calls.
+// The negative lookbehind excludes `foo.signal(...)`, `foo?.signal(...)`, and
+// similar member-expression call sites (including optional chaining with
+// whitespace) where `signal` / `trail` is a property name, not a factory.
+const TRAIL_LIKE_PATTERN = /(?<![.?])\b(trail|signal)\s*\(/g;
 
 const PROPERTY_PATTERN =
   /^(?:readonly\s+)?(?:(["'`])([^"'`]+)\1|([A-Za-z_$][\w$]*))\s*:\s*([\s\S]+)$/;

package/src/rules/types.ts

@@ -1,3 +1,5 @@
+import type { Topo } from '@ontrails/core';
+
 /**
  * Severity level for warden diagnostics.
  */
@@ -43,12 +45,39 @@ export interface WardenRule {
  * Options for cross-file rules that need knowledge of all trail IDs in a project.
  */
 export interface ProjectContext {
+  /** All known contour names in the project. */
+  readonly knownContourIds?: ReadonlySet<string>;
+  /** Store table IDs used with the CRUD factory across the project. */
+  readonly crudTableIds?: ReadonlySet<string>;
   /** All known trail IDs in the project */
   readonly knownTrailIds: ReadonlySet<string>;
-  /** All known provision IDs in the project */
-  readonly knownProvisionIds?: ReadonlySet<string>;
-  /** All trail IDs referenced as detour targets across the project */
-  readonly detourTargetTrailIds?: ReadonlySet<string>;
+  /** Declared contour references keyed by source contour name. */
+  readonly contourReferencesByName?: ReadonlyMap<string, readonly string[]>;
+  /** All known resource IDs in the project */
+  readonly knownResourceIds?: ReadonlySet<string>;
+  /** All known signal IDs in the project */
+  readonly knownSignalIds?: ReadonlySet<string>;
+  /** All trail IDs referenced by declared crosses arrays across the project. */
+  readonly crossTargetTrailIds?: ReadonlySet<string>;
+  /** Signal IDs referenced by trail `on` arrays across the project. */
+  readonly onTargetSignalIds?: ReadonlySet<string>;
+  /** Store table IDs used with reconcile trails across the project. */
+  readonly reconcileTableIds?: ReadonlySet<string>;
+  /** Normalized trail intents by trail ID across the project. */
+  readonly trailIntentsById?: ReadonlyMap<string, 'destroy' | 'read' | 'write'>;
+  /**
+   * CRUD operation coverage per entity aggregated across the project.
+   *
+   * Keys are stable entity IDs (authored contour names, `imported:<local>`
+   * sentinels for contours imported from another module, or store-table IDs
+   * produced by `deriveStoreTableId`). Values are the set of CRUD operations
+   * (`create`, `read`, `update`, `delete`, `list`) observed for that entity.
+   *
+   * Enables cross-file completeness evaluation so one-file-per-operation
+   * layouts (e.g. separate `create.ts`, `read.ts`) do not trip file-scoped
+   * coverage warnings.
+   */
+  readonly crudCoverageByEntity?: ReadonlyMap<string, ReadonlySet<string>>;
 }
 
 /**
@@ -62,3 +91,27 @@ export interface ProjectAwareWardenRule extends WardenRule {
     context: ProjectContext
   ) => readonly WardenDiagnostic[];
 }
+
+/**
+ * A topo-aware warden rule inspects the compiled runtime trail graph —
+ * actual `Trail` objects with resolved types, accessor shapes, detour
+ * declarations, `pattern` field values, and other runtime-only data that
+ * is unavailable to AST-based rules.
+ *
+ * Unlike `WardenRule` and `ProjectAwareWardenRule`, which analyze source
+ * code on a per-file basis, a `TopoAwareWardenRule` runs once per topo
+ * and returns diagnostics spanning the whole graph. A rule file must
+ * implement exactly one of the three rule kinds.
+ */
+export interface TopoAwareWardenRule {
+  /** Unique rule identifier */
+  readonly name: string;
+  /** Default severity */
+  readonly severity: WardenSeverity;
+  /** Human-readable description of what the rule enforces */
+  readonly description: string;
+  /** Run the rule against the resolved topo and return any diagnostics */
+  readonly checkTopo: (
+    topo: Topo
+  ) => readonly WardenDiagnostic[] | Promise<readonly WardenDiagnostic[]>;
+}