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

package/src/rules/resource-exists.ts

@@ -0,0 +1,181 @@
+import { isDraftId } from '@ontrails/core';
+
+import {
+  collectNamedResourceIds,
+  collectResourceDefinitionIds,
+} from './source/resources.js';
+import {
+  extractFirstStringArg,
+  findConfigProperty,
+  findTrailDefinitions,
+  getNodeCallee,
+  getStringValue,
+  identifierName,
+  isStringLiteral,
+  offsetToLine,
+  parse,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type {
+  ProjectAwareWardenRule,
+  ProjectContext,
+  WardenDiagnostic,
+} from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName(getNodeCallee(node)) === 'resource';
+
+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 ?? [];
+};
+
+const extractDeclaredResourceId = (
+  element: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): string | null => {
+  if (element.type === 'Identifier') {
+    const name = identifierName(element);
+    return name ? (resourceIdsByName.get(name) ?? null) : null;
+  }
+
+  if (isStringLiteral(element)) {
+    return getStringValue(element);
+  }
+
+  return isResourceCall(element) ? extractFirstStringArg(element) : null;
+};
+
+const extractDeclaredResourceIds = (
+  config: AstNode,
+  resourceIdsByName: ReadonlyMap<string, string>
+): readonly string[] => [
+  ...new Set(
+    getResourceElements(config).flatMap((element) => {
+      const id = extractDeclaredResourceId(element, resourceIdsByName);
+      return id ? [id] : [];
+    })
+  ),
+];
+
+const buildMissingResourceDiagnostic = (
+  trailId: string,
+  resourceId: string,
+  filePath: string,
+  line: number
+): WardenDiagnostic => ({
+  filePath,
+  line,
+  message: `Trail "${trailId}" declares resource "${resourceId}" which is not defined in the project. Define it with resource('${resourceId}', ...) and ensure that definition is included in the topo.`,
+  rule: 'resource-exists',
+  severity: 'error',
+});
+
+const reportMissingResources = (
+  def: { id: string; config: AstNode; start: number },
+  sourceCode: string,
+  resourceIdsByName: ReadonlyMap<string, string>,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>,
+  diagnostics: WardenDiagnostic[]
+): void => {
+  const line = offsetToLine(sourceCode, def.start);
+  for (const resourceId of extractDeclaredResourceIds(
+    def.config,
+    resourceIdsByName
+  )) {
+    if (!knownResourceIds.has(resourceId) && !isDraftId(resourceId)) {
+      diagnostics.push(
+        buildMissingResourceDiagnostic(def.id, resourceId, filePath, line)
+      );
+    }
+  }
+};
+
+const buildResourceDiagnostics = (
+  ast: AstNode,
+  sourceCode: string,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  const diagnostics: WardenDiagnostic[] = [];
+  const resourceIdsByName = collectNamedResourceIds(ast);
+  for (const def of findTrailDefinitions(ast)) {
+    reportMissingResources(
+      def,
+      sourceCode,
+      resourceIdsByName,
+      filePath,
+      knownResourceIds,
+      diagnostics
+    );
+  }
+  return diagnostics;
+};
+
+const checkResourcesExist = (
+  sourceCode: string,
+  filePath: string,
+  knownResourceIds: ReadonlySet<string>
+): readonly WardenDiagnostic[] => {
+  if (isTestFile(filePath)) {
+    return [];
+  }
+
+  const ast = parse(filePath, sourceCode);
+  if (!ast) {
+    return [];
+  }
+
+  return buildResourceDiagnostics(ast, sourceCode, filePath, knownResourceIds);
+};
+
+/**
+ * Checks that all declared resources resolve to known resource definitions.
+ */
+export const resourceExists: ProjectAwareWardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+    return checkResourcesExist(
+      sourceCode,
+      filePath,
+      collectResourceDefinitionIds(ast)
+    );
+  },
+  checkWithContext(
+    sourceCode: string,
+    filePath: string,
+    context: ProjectContext
+  ): readonly WardenDiagnostic[] {
+    const ast = parse(filePath, sourceCode);
+    const localResourceIds = ast
+      ? collectResourceDefinitionIds(ast)
+      : new Set<string>();
+    return checkResourcesExist(
+      sourceCode,
+      filePath,
+      context.knownResourceIds ?? localResourceIds
+    );
+  },
+  description:
+    '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,
+  getNodeCallee,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName(getNodeCallee(node)) === '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/resource-mock-coverage.ts

@@ -0,0 +1,115 @@
+/**
+ * Warns when a `resource('id', { ... })` definition declares neither a `mock`
+ * factory nor an explicit `unmockable` reason.
+ *
+ * Every resource should declare its test posture: a `mock` factory so
+ * `testAll(app)` runs without production-like configuration (common pitfall
+ * #10), or an explicit `unmockable: { reason }` escape hatch when it genuinely
+ * cannot be mocked. The `mock?`/`unmockable?` fields are both optional in
+ * `ResourceSpec`, so the compiler does not enforce the choice — this rule does.
+ *
+ * Conservative by design (zero false positives over completeness): only flags
+ * a `resource()` call whose second argument is an inline object literal with no
+ * spread. A referenced spec variable, a spread spec, or a non-object second
+ * argument cannot be verified statically, so they are skipped.
+ */
+
+import {
+  extractFirstStringArg,
+  findConfigProperty,
+  getNodeCallee,
+  identifierName,
+  offsetToLine,
+  parse,
+  walk,
+} from '@ontrails/source';
+import type { AstNode } from '@ontrails/source';
+import { isFrameworkInternalFile, isTestFile } from './scan.js';
+import type { WardenDiagnostic, WardenRule } from './types.js';
+
+const isResourceCall = (node: AstNode): boolean =>
+  node.type === 'CallExpression' &&
+  identifierName(getNodeCallee(node)) === 'resource';
+
+/**
+ * `.test-d.ts` type-fixture files are not matched by `isTestFile` (its pattern
+ * keys on `.test.`/`.spec.`), yet they hold type-inference probe resources that
+ * intentionally omit `mock`. Treat them as test fixtures here.
+ */
+const isTypeFixtureFile = (filePath: string): boolean =>
+  filePath.endsWith('.test-d.ts') || filePath.endsWith('.test-d.tsx');
+
+/**
+ * Framework-internal packages (`@ontrails/warden`, `@ontrails/testing`) define
+ * throwaway fixture resources to build example topos for other rules' tests
+ * (e.g. signal-graph-coaching's `invoiceStore`). Those scaffolding resources
+ * are not governed application resources, so skip them — consistent with how
+ * the rest of the framework treats `isFrameworkInternalFile` source.
+ */
+const isExcludedFile = (filePath: string): boolean =>
+  isTestFile(filePath) ||
+  isTypeFixtureFile(filePath) ||
+  isFrameworkInternalFile(filePath);
+
+/** A spec object literal we can analyze: an ObjectExpression with no spread. */
+const isStaticallyAnalyzableSpec = (spec: AstNode | undefined): boolean => {
+  if (!spec || spec.type !== 'ObjectExpression') {
+    return false;
+  }
+  const properties = spec['properties'] as readonly AstNode[] | undefined;
+  if (!properties) {
+    return false;
+  }
+  // A spread (`...base`) could contribute `mock`/`unmockable` from elsewhere;
+  // we cannot prove its absence, so do not flag.
+  return properties.every((prop) => prop.type === 'Property');
+};
+
+const declaresTestPosture = (spec: AstNode): boolean =>
+  findConfigProperty(spec, 'mock') !== null ||
+  findConfigProperty(spec, 'unmockable') !== null;
+
+export const resourceMockCoverage: WardenRule = {
+  check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
+    if (isExcludedFile(filePath)) {
+      return [];
+    }
+
+    const ast = parse(filePath, sourceCode);
+    if (!ast) {
+      return [];
+    }
+
+    const diagnostics: WardenDiagnostic[] = [];
+    walk(ast, (node) => {
+      if (!isResourceCall(node)) {
+        return;
+      }
+
+      const args = node['arguments'] as readonly AstNode[] | undefined;
+      const spec = args?.[1];
+      if (!isStaticallyAnalyzableSpec(spec) || !spec) {
+        return;
+      }
+      if (declaresTestPosture(spec)) {
+        return;
+      }
+
+      const resourceId = extractFirstStringArg(node);
+      const subject = resourceId ? `Resource "${resourceId}"` : 'Resource';
+      diagnostics.push({
+        filePath,
+        line: offsetToLine(sourceCode, node.start),
+        message: `${subject} declares no mock factory. Add a mock() so testAll(app) runs without configuration, or declare unmockable: { reason } if it intentionally cannot be mocked.`,
+        rule: 'resource-mock-coverage',
+        severity: 'warn',
+      });
+    });
+
+    return diagnostics;
+  },
+  description:
+    'Resource definitions declare a mock factory or an explicit unmockable reason.',
+  name: 'resource-mock-coverage',
+  severity: 'warn',
+};