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

package/src/rules/resource-declarations.ts

@@ -0,0 +1,697 @@
+/**
+ * Validates that resource access matches the declared `resources` array.
+ *
+ * Statically analyzes trail `implementation` functions to find `db.from(ctx)` and
+ * `ctx.resource('db.main')` calls and compares them against the declared
+ * `resources: [...]` array in the trail config. Reports errors for undeclared
+ * access and warnings for unused declarations.
+ */
+
+import { collectNamedResourceIds } from './source/resources.js';
+import {
+  extractFirstStringArg,
+  findConfigProperty,
+  findImplementationBodies,
+  findTrailDefinitions,
+  getNodeCallee,
+  getNodeId,
+  getNodeInit,
+  getNodeKey,
+  getNodeLeft,
+  getNodeObject,
+  getNodeProperty,
+  getNodeValueNode,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+  walkScope,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Resource declaration extraction
+// ---------------------------------------------------------------------------
+
+interface DeclaredResource {
+  readonly id: string | null;
+  readonly name: string | null;
+}
+
+interface CalledResources {
+  readonly fromNames: ReadonlySet<string>;
+  readonly lookupIds: ReadonlySet<string>;
+  readonly lookupNames: ReadonlySet<string>;
+}
+
+const MEMBER_TYPES = new Set(['StaticMemberExpression', 'MemberExpression']);
+
+/** Extract object and property Identifier names from a MemberExpression. */
+const extractMemberPair = (
+  callee: AstNode
+): { objName: string; propName: string } | null => {
+  if (!MEMBER_TYPES.has(callee.type)) {
+    return null;
+  }
+
+  const objName = identifierName(getNodeObject(callee));
+  const propName = identifierName(getNodeProperty(callee));
+
+  return objName && propName ? { objName, propName } : null;
+};
+
+/** Check if a node is an inline `resource('id', ...)` call. */
+const isInlineResourceCall = (node: AstNode): boolean => {
+  if (node.type !== 'CallExpression') {
+    return false;
+  }
+  return identifierName(getNodeCallee(node)) === 'resource';
+};
+
+/** Get `resources` array elements from a trail config. */
+const getResourceElements = (config: AstNode): readonly AstNode[] => {
+  const resourcesProp = findConfigProperty(config, 'resources');
+  if (!resourcesProp) {
+    return [];
+  }
+
+  const arrayNode = resourcesProp.value;
+  if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
+    return [];
+  }
+
+  const elements = (arrayNode as AstNode)['elements'] as
+    | readonly AstNode[]
+    | undefined;
+  return elements ?? [];
+};
+
+/** Extract one declared resource from a `resources` array element. */
+const extractDeclaredResource = (
+  element: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): DeclaredResource | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return {
+      id: name ? (resourceIdsByName.get(name) ?? null) : null,
+      name,
+    };
+  }
+
+  if (isStringLiteral(element)) {
+    return { id: getStringValue(element), name: null };
+  }
+
+  if (isInlineResourceCall(element)) {
+    return { id: extractFirstStringArg(element), name: null };
+  }
+
+  return null;
+};
+
+/** Extract declared resources from a trail config's `resources` array. */
+const extractDeclaredResources = (
+  config: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): readonly DeclaredResource[] =>
+  getResourceElements(config).flatMap((element) => {
+    const resource = extractDeclaredResource(element, resourceIdsByName);
+    return resource ? [resource] : [];
+  });
+
+// ---------------------------------------------------------------------------
+// Called resource extraction
+// ---------------------------------------------------------------------------
+
+/** Extract the raw second parameter node from a implementation function. */
+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;
+};
+
+/**
+ * Extract the second parameter name from a implementation function node.
+ *
+ * Returns null when the parameter is not a plain Identifier (e.g. when the
+ * author destructures `{ resource }` in the parameter list). Parameter-level
+ * destructuring is handled separately by `collectParamResourceAliases`.
+ *
+ * Also handles defaulted parameters like `(input, ctx = fallback) => ...`
+ * (AssignmentPattern whose `.left` is the Identifier). Without this, valid
+ * signatures would silently drop out of ctx-access analysis.
+ */
+const extractContextParamName = (
+  implementationBody: AstNode
+): string | null => {
+  const param = extractContextParamNode(implementationBody);
+  if (!param) {
+    return null;
+  }
+  if (param.type === 'AssignmentPattern') {
+    const left = getNodeLeft(param);
+    return identifierName(left);
+  }
+  return identifierName(param);
+};
+
+/** Extract the alias name from a Property node whose key is `resource`. */
+const extractResourceAlias = (property: AstNode): string | null => {
+  if (property.type !== 'Property') {
+    return null;
+  }
+  const keyName = identifierName(getNodeKey(property));
+  if (keyName !== 'resource') {
+    return null;
+  }
+  return identifierName(getNodeValueNode(property)) ?? keyName;
+};
+
+/**
+ * Collect `resource` aliases bound via parameter-level destructuring.
+ *
+ * Recognizes `(input, { resource }) => ...` and `(input, { resource: r }) => ...`.
+ * When the implementation author destructures in the parameter list, there is no
+ * enclosing `ctx` identifier to track — we seed the resource alias set directly
+ * from the ObjectPattern in `params[1]`.
+ */
+const collectParamResourceAliases = (body: AstNode): ReadonlySet<string> => {
+  const param = extractContextParamNode(body);
+  if (!param || param.type !== 'ObjectPattern') {
+    return new Set();
+  }
+  const aliases = new Set<string>();
+  const properties = param['properties'] as readonly AstNode[] | undefined;
+  for (const property of properties ?? []) {
+    const alias = extractResourceAlias(property);
+    if (alias) {
+      aliases.add(alias);
+    }
+  }
+  return aliases;
+};
+
+/**
+ * Build the set of context parameter names to match against.
+ *
+ * Returns ONLY the actual second-parameter name from the implementation signature.
+ * No seeded defaults: if the implementation has no second parameter, the returned set
+ * is empty and no `ctx.resource(...)` / `context.resource(...)` calls are
+ * tracked for that implementation. An unrelated closure-scoped `ctx` identifier is not
+ * the trail context and must not be treated as one.
+ *
+ * Mirrors `fires-declarations.ts` `buildCtxNames` for the same reason.
+ */
+const buildCtxNames = (body: AstNode): ReadonlySet<string> => {
+  const ctxNames = new Set<string>();
+  const paramName = extractContextParamName(body);
+  if (paramName) {
+    ctxNames.add(paramName);
+  }
+  return ctxNames;
+};
+
+/** Extract a CallExpression callee, or null. */
+const extractCallCallee = (node: AstNode): AstNode | null => {
+  if (node.type !== 'CallExpression') {
+    return null;
+  }
+  return (getNodeCallee(node) ?? null) as AstNode | null;
+};
+
+/** Extract the first identifier argument from a CallExpression. */
+const extractFirstIdentifierArg = (node: AstNode): string | null => {
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  const [firstArg] = args ?? [];
+  return identifierName(firstArg);
+};
+
+const extractCallInfo = (
+  node: AstNode
+): { callee: AstNode; firstArgName: string | null } | null => {
+  const callee = extractCallCallee(node);
+  return callee
+    ? {
+        callee,
+        firstArgName: extractFirstIdentifierArg(node),
+      }
+    : null;
+};
+
+/** Extract `db.from(ctx)` object names. */
+const extractFromCallName = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>
+): string | null => {
+  const call = extractCallInfo(node);
+  const pair = call ? extractMemberPair(call.callee) : null;
+
+  return pair &&
+    pair.propName === 'from' &&
+    call?.firstArgName &&
+    ctxNames.has(call.firstArgName)
+    ? pair.objName
+    : null;
+};
+
+/** Check if a callee is a member-style `ctx.resource(...)` call. */
+const isMemberResourceCall = (
+  callee: AstNode,
+  ctxNames: ReadonlySet<string>
+): boolean => {
+  const pair = extractMemberPair(callee);
+  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'resource';
+};
+
+/** Extract `ctx.resource(db)` and destructured `resource(db)` lookup names. */
+const extractLookupResourceName = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>,
+  resourceAliases: ReadonlySet<string>
+): string | null => {
+  const callee = extractCallCallee(node);
+  if (!callee) {
+    return null;
+  }
+
+  if (isMemberResourceCall(callee, ctxNames)) {
+    return extractFirstIdentifierArg(node);
+  }
+
+  if (resourceAliases.has(identifierName(callee) ?? '')) {
+    return extractFirstIdentifierArg(node);
+  }
+
+  return null;
+};
+
+/** Extract `ctx.resource('id')` and destructured `resource('id')` lookup IDs. */
+const extractLookupResourceId = (
+  node: AstNode,
+  ctxNames: ReadonlySet<string>,
+  resourceAliases: ReadonlySet<string>
+): string | null => {
+  const callee = extractCallCallee(node);
+  if (!callee) {
+    return null;
+  }
+
+  if (isMemberResourceCall(callee, ctxNames)) {
+    return extractFirstStringArg(node);
+  }
+
+  const calleeName = identifierName(callee);
+  const args = node['arguments'] as readonly AstNode[] | undefined;
+  if (calleeName && resourceAliases.has(calleeName) && args?.length === 1) {
+    return extractFirstStringArg(node);
+  }
+
+  return null;
+};
+
+/** Collect local aliases for the resource accessor (e.g. `const { resource } = ctx`). */
+const collectResourceAliases = (
+  body: AstNode,
+  ctxNames: ReadonlySet<string>
+): ReadonlySet<string> => {
+  const aliases = new Set<string>();
+
+  const extractAliasNames = (
+    pattern: AstNode | undefined
+  ): readonly string[] => {
+    if (pattern?.type !== 'ObjectPattern') {
+      return [];
+    }
+
+    const properties = pattern['properties'] as readonly AstNode[] | undefined;
+    return (properties ?? []).flatMap((property) => {
+      if (property.type !== 'Property') {
+        return [];
+      }
+
+      const keyName = identifierName(getNodeKey(property));
+      if (keyName !== 'resource') {
+        return [];
+      }
+
+      const alias = identifierName(getNodeValueNode(property)) ?? keyName;
+      return [alias];
+    });
+  };
+
+  walkScope(body, (node) => {
+    if (node.type !== 'VariableDeclarator') {
+      return;
+    }
+
+    const id = getNodeId(node);
+    const init = getNodeInit(node);
+    const initName = identifierName(init);
+    if (!initName || !ctxNames.has(initName)) {
+      return;
+    }
+
+    for (const alias of extractAliasNames(id)) {
+      aliases.add(alias);
+    }
+  });
+
+  return aliases;
+};
+
+/** Walk implementation bodies and collect resource access that can be resolved statically. */
+const extractCalledResources = (config: AstNode): CalledResources => {
+  const fromNames = new Set<string>();
+  const lookupIds = new Set<string>();
+  const lookupNames = new Set<string>();
+
+  for (const body of findImplementationBodies(config)) {
+    const ctxNames = buildCtxNames(body);
+    const paramAliases = collectParamResourceAliases(body);
+    const bodyAliases = collectResourceAliases(body, ctxNames);
+    const resourceAliases = new Set([...paramAliases, ...bodyAliases]);
+
+    walkScope(body, (node) => {
+      const fromName = extractFromCallName(node, ctxNames);
+      if (fromName) {
+        fromNames.add(fromName);
+      }
+
+      const lookupId = extractLookupResourceId(node, ctxNames, resourceAliases);
+      if (lookupId) {
+        lookupIds.add(lookupId);
+      }
+
+      const lookupName = extractLookupResourceName(
+        node,
+        ctxNames,
+        resourceAliases
+      );
+      if (lookupName) {
+        lookupNames.add(lookupName);
+      }
+    });
+  }
+
+  return { fromNames, lookupIds, lookupNames };
+};
+
+// ---------------------------------------------------------------------------
+// Diagnostics
+// ---------------------------------------------------------------------------
+
+const renderDeclaredResource = (resource: DeclaredResource): string =>
+  resource.name ?? resource.id ?? '<unknown>';
+
+const buildUndeclaredFromDiagnostic = (
+  trailId: string,
+  resourceName: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ${resourceName}.from(ctx) called but '${resourceName}' is not declared in resources. Add it to the trail resources array: resources: [${resourceName}].`,
+  rule: 'resource-declarations',
+  severity: 'error',
+});
+
+const buildUndeclaredLookupDiagnostic = (
+  trailId: string,
+  resourceId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ctx.resource('${resourceId}') called but '${resourceId}' is not declared in resources. Add it to the trail resources array: resources: ['${resourceId}'], or prefer the resource definition's .from(ctx) helper when it is statically in scope.`,
+  rule: 'resource-declarations',
+  severity: 'error',
+});
+
+const buildUndeclaredLookupNameDiagnostic = (
+  trailId: string,
+  resourceName: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": ctx.resource(${resourceName}) called but '${resourceName}' is not declared in resources. Add it to the trail resources array: resources: [${resourceName}].`,
+  rule: 'resource-declarations',
+  severity: 'error',
+});
+
+const buildUnusedDiagnostic = (
+  trailId: string,
+  declaredResource: DeclaredResource,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}": '${renderDeclaredResource(declaredResource)}' declared in resources but never used. Remove it from resources, or access it through the resource's static .from(ctx) helper if the trail really depends on it.`,
+  rule: 'resource-declarations',
+  severity: 'warn',
+});
+
+// ---------------------------------------------------------------------------
+// Comparison
+// ---------------------------------------------------------------------------
+
+const resourceWasUsed = (
+  declaredResource: DeclaredResource,
+  calledResources: CalledResources
+): boolean => {
+  if (
+    declaredResource.name &&
+    (calledResources.fromNames.has(declaredResource.name) ||
+      calledResources.lookupNames.has(declaredResource.name))
+  ) {
+    return true;
+  }
+
+  if (
+    declaredResource.id &&
+    calledResources.lookupIds.has(declaredResource.id)
+  ) {
+    return true;
+  }
+
+  return false;
+};
+
+const buildDeclaredNames = (
+  declaredResources: readonly DeclaredResource[]
+): ReadonlySet<string> =>
+  new Set(
+    declaredResources.flatMap((resource) =>
+      resource.name ? [resource.name] : []
+    )
+  );
+
+const buildDeclaredIds = (
+  declaredResources: readonly DeclaredResource[]
+): ReadonlySet<string> =>
+  new Set(
+    declaredResources.flatMap((resource) => (resource.id ? [resource.id] : []))
+  );
+
+const reportUndeclaredFromCalls = (
+  trailId: string,
+  filePath: string,
+  line: number,
+  calledResources: CalledResources,
+  declaredNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const resourceName of calledResources.fromNames) {
+    if (!declaredNames.has(resourceName)) {
+      diagnostics.push(
+        buildUndeclaredFromDiagnostic(trailId, resourceName, filePath, line)
+      );
+    }
+  }
+};
+
+const reportUndeclaredLookupCalls = (
+  trailId: string,
+  filePath: string,
+  line: number,
+  calledResources: CalledResources,
+  declaredIds: ReadonlySet<string>,
+  declaredNames: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const resourceName of calledResources.lookupNames) {
+    // Name-based lookup checks remain reliable even when an imported resource ID
+    // cannot be resolved locally.
+    if (!declaredNames.has(resourceName)) {
+      diagnostics.push(
+        buildUndeclaredLookupNameDiagnostic(
+          trailId,
+          resourceName,
+          filePath,
+          line
+        )
+      );
+    }
+  }
+
+  for (const resourceId of calledResources.lookupIds) {
+    if (!declaredIds.has(resourceId)) {
+      diagnostics.push(
+        buildUndeclaredLookupDiagnostic(trailId, resourceId, filePath, line)
+      );
+    }
+  }
+};
+
+const reportUnusedDeclarations = (
+  trailId: string,
+  filePath: string,
+  line: number,
+  declaredResources: readonly DeclaredResource[],
+  calledResources: CalledResources,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  for (const declaredResource of declaredResources) {
+    if (resourceWasUsed(declaredResource, calledResources)) {
+      continue;
+    }
+
+    if (declaredResource.name && declaredResource.id === null) {
+      continue;
+    }
+
+    diagnostics.push(
+      buildUnusedDiagnostic(trailId, declaredResource, filePath, line)
+    );
+  }
+};
+
+const hasNoResourceActivity = (
+  declaredResources: readonly DeclaredResource[],
+  calledResources: CalledResources
+): boolean =>
+  declaredResources.length === 0 &&
+  calledResources.fromNames.size === 0 &&
+  calledResources.lookupIds.size === 0 &&
+  calledResources.lookupNames.size === 0;
+
+const analyzeTrailServices = (
+  def: { config: AstNode; start: number },
+  sourceCode: string,
+  resourceIdsByName: ReadonlyMap<string, string>
+): {
+  readonly calledResources: CalledResources;
+  readonly declaredIds: ReadonlySet<string>;
+  readonly declaredNames: ReadonlySet<string>;
+  readonly declaredResources: readonly DeclaredResource[];
+  readonly line: number;
+} => {
+  const declaredResources = extractDeclaredResources(
+    def.config,
+    resourceIdsByName
+  );
+  return {
+    calledResources: extractCalledResources(def.config),
+    declaredIds: buildDeclaredIds(declaredResources),
+    declaredNames: buildDeclaredNames(declaredResources),
+    declaredResources,
+    line: offsetToLine(sourceCode, def.start),
+  };
+};
+
+const checkTrailDefinition = (
+  def: { id: string; config: AstNode; start: number },
+  filePath: string,
+  sourceCode: string,
+  resourceIdsByName: ReadonlyMap<string, string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const {
+    calledResources,
+    declaredIds,
+    declaredNames,
+    declaredResources,
+    line,
+  } = analyzeTrailServices(def, sourceCode, resourceIdsByName);
+
+  if (hasNoResourceActivity(declaredResources, calledResources)) {
+    return;
+  }
+
+  reportUndeclaredFromCalls(
+    def.id,
+    filePath,
+    line,
+    calledResources,
+    declaredNames,
+    diagnostics
+  );
+  reportUndeclaredLookupCalls(
+    def.id,
+    filePath,
+    line,
+    calledResources,
+    declaredIds,
+    declaredNames,
+    diagnostics
+  );
+  reportUnusedDeclarations(
+    def.id,
+    filePath,
+    line,
+    declaredResources,
+    calledResources,
+    diagnostics
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Rule
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates that resource access aligns with declared `resources` arrays.
+ */
+export const resourceDeclarations: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isTestFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    const resourceIdsByName = collectNamedResourceIds(ast);
+
+    for (const def of findTrailDefinitions(ast)) {
+      checkTrailDefinition(
+        def,
+        filePath,
+        sourceCode,
+        resourceIdsByName,
+        diagnostics
+      );
+    }
+
+    return diagnostics;
+  },
+  description:
+    'Ensure resource.from(ctx) and ctx.resource() calls match the declared resources array in trail definitions.',
+  name: 'resource-declarations',
+  severity: 'error',
+};