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

package/src/rules/source/stores.ts

@@ -0,0 +1,310 @@
+/** Warden-private store/factory pattern helpers. */
+
+import {
+  extractBindingName,
+  findConfigProperty,
+  getPropertyName,
+  identifierName,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+
+export interface StoreTableDefinition {
+  /** Table name declared inside store({ ... }). */
+  readonly name: string;
+  /**
+   * Local binding name of the enclosing `store(...)` declaration, if the
+   * `store(...)` call is bound to a `const`/`let`/`var` (e.g. `db` in
+   * `const db = store({ ... })`). Null for anonymous stores.
+   */
+  readonly storeBinding: string | null;
+  /**
+   * Stable composite key for this table in the form `${storeBinding}:${name}`,
+   * falling back to the bare `name` when the store is anonymous. Use this for
+   * compose-rule / compose-file keying so two stores with the same table name
+   * never collide.
+   */
+  readonly key: string;
+  /** Start offset of the table property declaration. */
+  readonly start: number;
+  /** Whether the authored table opts into version tracking. */
+  readonly versioned: boolean;
+}
+
+/**
+ * Build a composite key for a store table: `${storeBinding}:${tableName}`,
+ * falling back to the bare `tableName` when the enclosing store has no local
+ * binding. Centralized so rule keying stays stable.
+ *
+ * @remarks
+ * The key is intentionally file-local (no module path prefix). Compose-file
+ * aggregation in `ProjectContext` merges keys from all files, so two files
+ * with `const db = store({ notes: ... })` both produce `db:notes` — this is
+ * the desired behavior because the warden checks for *pattern completeness*
+ * across the project and matching keys signals that the same logical table
+ * is covered. If two genuinely different tables share a binding and name,
+ * that is a code-level naming collision the developer should resolve.
+ */
+export const makeStoreTableKey = (
+  storeBinding: string | null,
+  tableName: string
+): string => (storeBinding ? `${storeBinding}:${tableName}` : tableName);
+
+const isBooleanLiteral = (node: AstNode | undefined): boolean =>
+  Boolean(
+    node &&
+    ((node.type === 'BooleanLiteral' &&
+      (node as unknown as { value?: unknown }).value === true) ||
+      (node.type === 'Literal' &&
+        (node as unknown as { value?: unknown }).value === true))
+  );
+
+/**
+ * Check if a node is a `CallExpression` to the identifier `name`.
+ *
+ * e.g. `isNamedCall(node, 'store')` matches `store({...})` but not
+ * `someObj.store()` or `storeAlt()`.
+ */
+export const isNamedCall = (node: AstNode | undefined, name: string): boolean =>
+  !!node &&
+  node.type === 'CallExpression' &&
+  identifierName((node as unknown as { callee?: AstNode }).callee) === name;
+
+/**
+ * Narrow a member-expression node (`a.b` or `a['b']`) to its `object` /
+ * `property` pair, returning `null` for anything else.
+ */
+export const getMemberExpression = (
+  node: AstNode | undefined
+): { readonly object?: AstNode; readonly property?: AstNode } | null => {
+  if (
+    !node ||
+    (node.type !== 'MemberExpression' && node.type !== 'StaticMemberExpression')
+  ) {
+    return null;
+  }
+
+  return node as unknown as {
+    readonly object?: AstNode;
+    readonly property?: AstNode;
+  };
+};
+
+/**
+ * Resolve a `<store>.tables.<name>` member expression to its store binding
+ * and table name.
+ *
+ * Returns `null` for anything that isn't a two-level member access ending in
+ * `.tables.<name>`. The store binding is the identifier of the object owning
+ * `.tables` — typically the local binding from `const db = store(...)`.
+ */
+export const extractStoreTableFromMember = (
+  node: AstNode | undefined
+): {
+  readonly storeBinding: string | null;
+  readonly tableName: string;
+} | null => {
+  const member = getMemberExpression(node);
+  const tableName = member ? getPropertyName(member.property) : null;
+  const tablesMember = member ? getMemberExpression(member.object) : null;
+  if (!tableName || !tablesMember) {
+    return null;
+  }
+
+  if (getPropertyName(tablesMember.property) !== 'tables') {
+    return null;
+  }
+
+  const storeBinding = identifierName(tablesMember.object) ?? null;
+  return { storeBinding, tableName };
+};
+
+/**
+ * Collect `const foo = <store>.tables.<name>` bindings from a parsed file,
+ * keyed by the local binding name. Values are the composite table key
+ * (`${storeBinding}:${tableName}`) so callers can dedupe across stores that
+ * share a table name.
+ */
+export const collectNamedStoreTableIds = (
+  ast: AstNode
+): ReadonlyMap<string, string> => {
+  const ids = new Map<string, string>();
+
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    const name = extractBindingName(id);
+    const table = extractStoreTableFromMember(init);
+    if (name && table) {
+      ids.set(name, makeStoreTableKey(table.storeBinding, table.tableName));
+    }
+  });
+
+  return ids;
+};
+
+/**
+ * Resolve an argument node to a composite store-table key
+ * (`${storeBinding}:${tableName}` or bare `tableName` when anonymous).
+ *
+ * Handles the two authoring patterns:
+ *   - direct member access: `db.tables.notes`
+ *   - identifier reference: `const notesTable = db.tables.notes; crud(notesTable, …)`
+ */
+export const deriveStoreTableId = (
+  node: AstNode | undefined,
+  namedStoreTableIds: ReadonlyMap<string, string>
+): string | null => {
+  if (!node) {
+    return null;
+  }
+
+  if (node.type === 'Identifier') {
+    const name = identifierName(node);
+    return name ? (namedStoreTableIds.get(name) ?? null) : null;
+  }
+
+  const member = extractStoreTableFromMember(node);
+  return member
+    ? makeStoreTableKey(member.storeBinding, member.tableName)
+    : null;
+};
+
+const extractStoreTableDefinitions = (
+  node: AstNode,
+  storeBinding: string | null
+): readonly StoreTableDefinition[] => {
+  if (!isNamedCall(node, 'store')) {
+    return [];
+  }
+
+  const [tablesArg] = ((node as unknown as { arguments?: readonly AstNode[] })
+    .arguments ?? []) as readonly AstNode[];
+  if (!tablesArg || tablesArg.type !== 'ObjectExpression') {
+    return [];
+  }
+
+  const properties = tablesArg['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return [];
+  }
+
+  return properties.flatMap((property) => {
+    if (property.type !== 'Property') {
+      return [];
+    }
+
+    const name = getPropertyName(property.key);
+    const value = property.value as AstNode | undefined;
+    if (!name || value?.type !== 'ObjectExpression') {
+      return [];
+    }
+
+    const versionedProp = findConfigProperty(value, 'versioned');
+    return [
+      {
+        key: makeStoreTableKey(storeBinding, name),
+        name,
+        start: property.start,
+        storeBinding,
+        versioned: isBooleanLiteral(
+          versionedProp?.value as AstNode | undefined
+        ),
+      },
+    ];
+  });
+};
+
+export const findStoreTableDefinitions = (
+  ast: AstNode
+): readonly StoreTableDefinition[] => {
+  const definitions: StoreTableDefinition[] = [];
+  const seenStoreCalls = new WeakSet<AstNode>();
+
+  // First pass: bound stores (walk VariableDeclarators so we know the binding).
+  walk(ast, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const { id, init } = node as unknown as {
+      readonly id?: AstNode;
+      readonly init?: AstNode;
+    };
+    if (!init || !isNamedCall(init, 'store')) {
+      return;
+    }
+
+    seenStoreCalls.add(init);
+    const storeBinding = extractBindingName(id);
+    definitions.push(...extractStoreTableDefinitions(init, storeBinding));
+  });
+
+  // Second pass: anonymous `store({...})` calls not bound to a variable
+  // (e.g. an inline default export). Use the bare table name as the key.
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'store') || seenStoreCalls.has(node)) {
+      return;
+    }
+    definitions.push(...extractStoreTableDefinitions(node, null));
+  });
+
+  return definitions;
+};
+
+export const collectCrudTableIds = (ast: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  const namedStoreTableIds = collectNamedStoreTableIds(ast);
+
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'crud')) {
+      return;
+    }
+
+    const [tableArg] = ((node as unknown as { arguments?: readonly AstNode[] })
+      .arguments ?? []) as readonly AstNode[];
+    const tableId = deriveStoreTableId(tableArg, namedStoreTableIds);
+    if (tableId) {
+      ids.add(tableId);
+    }
+  });
+
+  return ids;
+};
+
+export const collectReconcileTableIds = (ast: AstNode): ReadonlySet<string> => {
+  const ids = new Set<string>();
+  const namedStoreTableIds = collectNamedStoreTableIds(ast);
+
+  walk(ast, (node) => {
+    if (!isNamedCall(node, 'reconcile')) {
+      return;
+    }
+
+    const [configArg] = ((
+      node as unknown as {
+        arguments?: readonly AstNode[];
+      }
+    ).arguments ?? []) as readonly AstNode[];
+    if (!configArg || configArg.type !== 'ObjectExpression') {
+      return;
+    }
+
+    const tableProp = findConfigProperty(configArg, 'table');
+    const tableId = deriveStoreTableId(
+      tableProp?.value as AstNode | undefined,
+      namedStoreTableIds
+    );
+    if (tableId) {
+      ids.add(tableId);
+    }
+  });
+
+  return ids;
+};

package/src/rules/static-resource-accessor-preference.ts

@@ -6,11 +6,11 @@
  * Dynamic IDs and generic framework internals remain outside its scope.
  */
 
+import { collectNamedResourceIds } from './source/resources.js';
 import {
-  collectNamedResourceIds,
   extractFirstStringArg,
-  findBlazeBodies,
   findConfigProperty,
+  findImplementationBodies,
   findTrailDefinitions,
   getNodeCallee,
   getNodeId,
@@ -32,8 +32,8 @@ import {
   walk,
   walkScope,
   walkWithScopes,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import { isFrameworkInternalFile, isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
@@ -125,16 +125,20 @@ const extractDeclaredStaticResources = (
     return name ? [{ id: resourceIdsByName.get(name) ?? null, name }] : [];
   });
 
-const extractContextParamNode = (blazeBody: AstNode): AstNode | null => {
-  const params = blazeBody['params'] as readonly AstNode[] | undefined;
+const extractContextParamNode = (
+  implementationBody: AstNode
+): AstNode | null => {
+  const params = implementationBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
   return params[1] ?? null;
 };
 
-const extractContextParamName = (blazeBody: AstNode): string | null => {
-  const param = extractContextParamNode(blazeBody);
+const extractContextParamName = (
+  implementationBody: AstNode
+): string | null => {
+  const param = extractContextParamNode(implementationBody);
   if (!param) {
     return null;
   }
@@ -340,7 +344,7 @@ const collectResourceLookups = (
 ): readonly ResourceLookup[] => {
   const lookups: ResourceLookup[] = [];
 
-  for (const body of findBlazeBodies(config)) {
+  for (const body of findImplementationBodies(config)) {
     const ctxNames = buildCtxNames(body);
     const resourceAliases = new Set([
       ...collectParamResourceAliases(body),
@@ -465,7 +469,7 @@ const collectInlineDependencyConstructions = (
 ): readonly InlineDependencyConstruction[] => {
   const constructions: InlineDependencyConstruction[] = [];
 
-  for (const body of findBlazeBodies(config)) {
+  for (const body of findImplementationBodies(config)) {
     walkWithScopes(
       body,
       (node, scopes) => {
@@ -517,7 +521,7 @@ const buildInlineDependencyDiagnostic = (
   line: offsetToLine(sourceCode, construction.start),
   message:
     `Trail "${trailId}": ${construction.rendered} constructs an external dependency ` +
-    'inside blaze logic. Move the client behind a resource definition and declare it in resources.',
+    'inside implementation logic. Move the client behind a resource definition and declare it in resources.',
   rule: RULE_NAME,
   severity: 'warn',
 });

package/src/rules/surface-overlay-coherence.ts

@@ -27,7 +27,7 @@ import type {
   SurfaceOverlayBindings,
   Topo,
 } from '@ontrails/core';
-import type { TopoGraph } from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topography';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';
 

package/src/rules/surface-trailhead-coherence.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 type { WardenDiagnostic, WardenRule } from './types.js';
 
 const RULE_NAME = 'surface-trailhead-coherence';

package/src/rules/trail-fork-coaching.ts

@@ -1,7 +1,7 @@
 import {
   extractStringOrTemplateLiteral,
-  findBlazeBodies,
   findConfigProperty,
+  findImplementationBodies,
   findTrailDefinitions,
   getNodeArgument,
   getNodeArguments,
@@ -26,8 +26,8 @@ import {
   offsetToLine,
   parse,
   walkScope,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 const RULE_NAME = 'trail-fork-coaching';
@@ -49,7 +49,7 @@ interface SchemaBindingRecord {
 
 type SchemaBindings = ReadonlyMap<string, readonly SchemaBindingRecord[]>;
 
-interface BlazeInputBindings {
+interface ImplementationInputBindings {
   readonly aliases: ReadonlyMap<string, string>;
   readonly inputParamName: string | null;
 }
@@ -344,8 +344,8 @@ const findControlFields = (
   return fields;
 };
 
-const blazeParams = (blaze: AstNode): readonly AstNode[] =>
-  getNodeParams(blaze) ?? [];
+const implementationParams = (implementation: AstNode): readonly AstNode[] =>
+  getNodeParams(implementation) ?? [];
 
 const memberFieldName = (
   node: AstNode | undefined,
@@ -397,13 +397,13 @@ const collectDestructuredFieldAliasesFromPattern = (
 };
 
 const collectDestructuredFieldAliases = (
-  blaze: AstNode,
+  implementation: AstNode,
   inputParamName: string,
   fields: ReadonlySet<string>
 ): ReadonlyMap<string, string> => {
   const aliases = new Map<string, string>();
 
-  walkScope(blaze, (node) => {
+  walkScope(implementation, (node) => {
     if (node.type !== 'VariableDeclarator') {
       return;
     }
@@ -427,15 +427,19 @@ const collectDestructuredFieldAliases = (
   return aliases;
 };
 
-const collectBlazeInputBindings = (
-  blaze: AstNode,
+const collectImplementationInputBindings = (
+  implementation: AstNode,
   fields: ReadonlySet<string>
-): BlazeInputBindings | null => {
-  const [inputParam] = blazeParams(blaze);
+): ImplementationInputBindings | null => {
+  const [inputParam] = implementationParams(implementation);
   const inputParamName = identifierName(inputParam);
   if (inputParamName) {
     return {
-      aliases: collectDestructuredFieldAliases(blaze, inputParamName, fields),
+      aliases: collectDestructuredFieldAliases(
+        implementation,
+        inputParamName,
+        fields
+      ),
       inputParamName,
     };
   }
@@ -511,13 +515,13 @@ const comparisonBranchesOnField = (
 };
 
 const branchesOnField = (
-  blaze: AstNode,
+  implementation: AstNode,
   inputParamName: string | null,
   fieldName: string,
   aliases: ReadonlyMap<string, string>
 ): AstNode | null => {
   let found: AstNode | null = null;
-  walkScope(blaze, (node) => {
+  walkScope(implementation, (node) => {
     if (found) {
       return;
     }
@@ -579,15 +583,20 @@ export const trailForkCoaching: WardenRule = {
       }
       const fieldNames = new Set(fields.map((field) => field.name));
 
-      for (const blaze of findBlazeBodies(definition.config)) {
-        const inputBindings = collectBlazeInputBindings(blaze, fieldNames);
+      for (const implementation of findImplementationBodies(
+        definition.config
+      )) {
+        const inputBindings = collectImplementationInputBindings(
+          implementation,
+          fieldNames
+        );
         if (!inputBindings) {
           continue;
         }
 
         for (const field of fields) {
           const branchNode = branchesOnField(
-            blaze,
+            implementation,
             inputBindings.inputParamName,
             field.name,
             inputBindings.aliases

package/src/rules/trail-versioning-source.ts

@@ -1,6 +1,6 @@
 import {
-  findBlazeBodies,
   findConfigProperty,
+  findImplementationBodies,
   findTrailDefinitions,
   getNodeArgument,
   getNodeArguments,
@@ -23,12 +23,13 @@ import {
   parse,
   walk,
   walkScope,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 const VERSION_PINNED_COMPOSE = 'version-pinned-compose';
-const FORK_WITHOUT_PRESERVED_BLAZE = 'fork-without-preserved-blaze';
+const FORK_WITHOUT_PRESERVED_IMPLEMENTATION =
+  'fork-without-preserved-implementation';
 const MARKER_SCHEMA_UNSUPPORTED = 'marker-schema-unsupported';
 
 interface SchemaBindingRecord {
@@ -893,8 +894,8 @@ export const versionPinnedCompose: WardenRule = {
     }
 
     const diagnostics: WardenDiagnostic[] = [];
-    for (const blaze of findBlazeBodies(ast)) {
-      walk(blaze, (node) => {
+    for (const implementation of findImplementationBodies(ast)) {
+      walk(implementation, (node) => {
         if (!composeCallHasVersionPin(node)) {
           return;
         }
@@ -918,7 +919,7 @@ export const versionPinnedCompose: WardenRule = {
   severity: 'warn',
 };
 
-export const forkWithoutPreservedBlaze: WardenRule = {
+export const forkWithoutPreservedImplementation: WardenRule = {
   check(sourceCode, filePath) {
     const ast = parse(filePath, sourceCode);
     if (!ast) {
@@ -931,17 +932,20 @@ export const forkWithoutPreservedBlaze: WardenRule = {
         continue;
       }
       for (const entry of versionEntries(definition.config)) {
-        if (hasProperty(entry, 'transpose') || hasProperty(entry, 'blaze')) {
+        if (
+          hasProperty(entry, 'transpose') ||
+          hasProperty(entry, 'implementation')
+        ) {
           continue;
         }
         diagnostics.push(
           diagnostic(
-            FORK_WITHOUT_PRESERVED_BLAZE,
+            FORK_WITHOUT_PRESERVED_IMPLEMENTATION,
             'error',
             filePath,
             sourceCode,
             entry,
-            `Trail "${definition.id}" has a historical version entry without transpose or blaze. Add transpose for a revision entry, or preserve the historical blaze for a fork entry.`
+            `Trail "${definition.id}" has a historical version entry without transpose or implementation. Add transpose for a revision entry, or preserve the historical implementation for a fork entry.`
           )
         );
       }
@@ -949,8 +953,8 @@ export const forkWithoutPreservedBlaze: WardenRule = {
     return diagnostics;
   },
   description:
-    'Require historical fork version entries to preserve a blaze, while revision entries declare transpose.',
-  name: FORK_WITHOUT_PRESERVED_BLAZE,
+    'Require historical fork version entries to preserve an implementation, while revision entries declare transpose.',
+  name: FORK_WITHOUT_PRESERVED_IMPLEMENTATION,
   severity: 'error',
 };
 

package/src/rules/trail-versioning-topo.ts

@@ -1,10 +1,10 @@
-import { deriveTopoGraph } from '@ontrails/topographer';
+import { deriveTopoGraph } from '@ontrails/topography';
 import type {
   TopoGraph,
   TopoGraphEntry,
   TopoGraphForceEntry,
   TopoGraphVersionEntry,
-} from '@ontrails/topographer';
+} from '@ontrails/topography';
 import type { Topo } from '@ontrails/core';
 
 import type { TopoAwareWardenRule, WardenDiagnostic } from './types.js';

package/src/rules/trailhead-override-divergence.ts

@@ -39,8 +39,8 @@ import {
   offsetToLine,
   parse,
   walk,
-} from './ast.js';
-import type { AstNode } from './ast.js';
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
 import type {
   AuthoredMcpSurfaceBindingSet,
   ProjectAwareWardenRule,

package/src/rules/types.ts

@@ -6,7 +6,7 @@ import type {
   SurfaceBindings,
   Topo,
 } from '@ontrails/core';
-import type { TopoGraph } from '@ontrails/topographer';
+import type { TopoGraph } from '@ontrails/topography';
 
 import type { WardenDepth } from '../config.js';
 import type { WardenImportResolution } from '../resolve.js';
@@ -314,16 +314,16 @@ export interface ProjectContext {
   readonly authoredMcpSurfaceBindingSets?:
     | readonly AuthoredMcpSurfaceBindingSet[]
     | undefined;
-  /** All known contour names in the project. */
-  readonly knownContourIds?: ReadonlySet<string>;
+  /** All known entity names in the project. */
+  readonly knownEntityIds?: 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>;
   /** Trail IDs registered in configured app topo targets. */
   readonly topoTrailIds?: ReadonlySet<string>;
-  /** Declared contour references keyed by source contour name. */
-  readonly contourReferencesByName?: ReadonlyMap<string, readonly string[]>;
+  /** Declared entity references keyed by source entity name. */
+  readonly entityReferencesByName?: ReadonlyMap<string, readonly string[]>;
   /** All known resource IDs in the project */
   readonly knownResourceIds?: ReadonlySet<string>;
   /** All known signal IDs in the project */
@@ -356,8 +356,8 @@ export interface ProjectContext {
   /**
    * 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
+   * Keys are stable entity IDs (authored entity names, `imported:<local>`
+   * sentinels for entities 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.
    *

package/src/rules/unmaterialized-activation-source.ts

@@ -6,6 +6,7 @@ const RULE_NAME = 'unmaterialized-activation-source';
 const TOPO_FILE = '<topo>';
 
 const MATERIALIZED_SOURCE_KINDS = new Set<ActivationSourceKind>([
+  'queue',
   'schedule',
   'signal',
   'webhook',

package/src/rules/unreachable-detour-shadowing.ts

@@ -15,8 +15,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';