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

package/src/rules/{service-declarations.ts → provision-declarations.ts}

@@ -1,17 +1,17 @@
 /**
- * Validates that service access matches the declared `services` array.
+ * Validates that provision access matches the declared `provisions` array.
  *
- * Statically analyzes trail run functions to find `db.from(ctx)` and
- * `ctx.service('db.main')` calls and compares them against the declared
- * `services: [...]` array in the trail config. Reports errors for undeclared
+ * Statically analyzes trail `blaze` functions to find `db.from(ctx)` and
+ * `ctx.provision('db.main')` calls and compares them against the declared
+ * `provisions: [...]` array in the trail config. Reports errors for undeclared
  * access and warnings for unused declarations.
  */
 
 import {
-  collectNamedServiceIds,
+  collectNamedProvisionIds,
   extractFirstStringArg,
   findConfigProperty,
-  findRunBodies,
+  findBlazeBodies,
   findTrailDefinitions,
   getStringValue,
   identifierName,
@@ -25,15 +25,15 @@ import { isTestFile } from './scan.js';
 import type { WardenDiagnostic, WardenRule } from './types.js';
 
 // ---------------------------------------------------------------------------
-// Service declaration extraction
+// Provision declaration extraction
 // ---------------------------------------------------------------------------
 
-interface DeclaredService {
+interface DeclaredProvision {
   readonly id: string | null;
   readonly name: string | null;
 }
 
-interface CalledServices {
+interface CalledProvisions {
   readonly fromNames: ReadonlySet<string>;
   readonly lookupIds: ReadonlySet<string>;
   readonly lookupNames: ReadonlySet<string>;
@@ -59,25 +59,25 @@ const extractMemberPair = (
   return objName && propName ? { objName, propName } : null;
 };
 
-/** Check if a node is an inline `service('id', ...)` call. */
-const isInlineServiceCall = (node: AstNode): boolean => {
+/** Check if a node is an inline `provision('id', ...)` call. */
+const isInlineProvisionCall = (node: AstNode): boolean => {
   if (node.type !== 'CallExpression') {
     return false;
   }
   return (
     identifierName((node as unknown as { callee?: AstNode }).callee) ===
-    'service'
+    'provision'
   );
 };
 
-/** Get `services` array elements from a trail config. */
-const getServiceElements = (config: AstNode): readonly AstNode[] => {
-  const servicesProp = findConfigProperty(config, 'services');
-  if (!servicesProp) {
+/** Get `provisions` array elements from a trail config. */
+const getProvisionElements = (config: AstNode): readonly AstNode[] => {
+  const provisionsProp = findConfigProperty(config, 'provisions');
+  if (!provisionsProp) {
     return [];
   }
 
-  const arrayNode = servicesProp.value;
+  const arrayNode = provisionsProp.value;
   if (!arrayNode || (arrayNode as AstNode).type !== 'ArrayExpression') {
     return [];
   }
@@ -88,15 +88,15 @@ const getServiceElements = (config: AstNode): readonly AstNode[] => {
   return elements ?? [];
 };
 
-/** Extract one declared service from a `services` array element. */
-const extractDeclaredService = (
+/** Extract one declared provision from a `provisions` array element. */
+const extractDeclaredProvision = (
   element: AstNode,
-  serviceIdsByName: ReadonlyMap<string, string>
-): DeclaredService | null => {
+  provisionIdsByName: ReadonlyMap<string, string>
+): DeclaredProvision | null => {
   if (element.type === 'Identifier') {
     const name = identifierName(element);
     return {
-      id: name ? (serviceIdsByName.get(name) ?? null) : null,
+      id: name ? (provisionIdsByName.get(name) ?? null) : null,
       name,
     };
   }
@@ -105,30 +105,30 @@ const extractDeclaredService = (
     return { id: getStringValue(element), name: null };
   }
 
-  if (isInlineServiceCall(element)) {
+  if (isInlineProvisionCall(element)) {
     return { id: extractFirstStringArg(element), name: null };
   }
 
   return null;
 };
 
-/** Extract declared services from a trail config's `services` array. */
-const extractDeclaredServices = (
+/** Extract declared provisions from a trail config's `provisions` array. */
+const extractDeclaredProvisions = (
   config: AstNode,
-  serviceIdsByName: ReadonlyMap<string, string>
-): readonly DeclaredService[] =>
-  getServiceElements(config).flatMap((element) => {
-    const service = extractDeclaredService(element, serviceIdsByName);
-    return service ? [service] : [];
+  provisionIdsByName: ReadonlyMap<string, string>
+): readonly DeclaredProvision[] =>
+  getProvisionElements(config).flatMap((element) => {
+    const provision = extractDeclaredProvision(element, provisionIdsByName);
+    return provision ? [provision] : [];
   });
 
 // ---------------------------------------------------------------------------
 // Called service extraction
 // ---------------------------------------------------------------------------
 
-/** Extract the second parameter name from a run function node. */
-const extractContextParamName = (runBody: AstNode): string | null => {
-  const params = runBody['params'] as readonly AstNode[] | undefined;
+/** Extract the second parameter name from a blaze function node. */
+const extractContextParamName = (blazeBody: AstNode): string | null => {
+  const params = blazeBody['params'] as readonly AstNode[] | undefined;
   if (!params || params.length < 2) {
     return null;
   }
@@ -189,63 +189,63 @@ const extractFromCallName = (
     : null;
 };
 
-/** Check if a callee is a member-style `ctx.service(...)` call. */
-const isMemberServiceCall = (
+/** Check if a callee is a member-style `ctx.provision(...)` call. */
+const isMemberProvisionCall = (
   callee: AstNode,
   ctxNames: ReadonlySet<string>
 ): boolean => {
   const pair = extractMemberPair(callee);
-  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'service';
+  return !!pair && ctxNames.has(pair.objName) && pair.propName === 'provision';
 };
 
-/** Extract `ctx.service(db)` and destructured `service(db)` lookup names. */
-const extractLookupServiceName = (
+/** Extract `ctx.provision(db)` and destructured `provision(db)` lookup names. */
+const extractLookupProvisionName = (
   node: AstNode,
   ctxNames: ReadonlySet<string>,
-  serviceAliases: ReadonlySet<string>
+  provisionAliases: ReadonlySet<string>
 ): string | null => {
   const callee = extractCallCallee(node);
   if (!callee) {
     return null;
   }
 
-  if (isMemberServiceCall(callee, ctxNames)) {
+  if (isMemberProvisionCall(callee, ctxNames)) {
     return extractFirstIdentifierArg(node);
   }
 
-  if (serviceAliases.has(identifierName(callee) ?? '')) {
+  if (provisionAliases.has(identifierName(callee) ?? '')) {
     return extractFirstIdentifierArg(node);
   }
 
   return null;
 };
 
-/** Extract `ctx.service('id')` and destructured `service('id')` lookup IDs. */
-const extractLookupServiceId = (
+/** Extract `ctx.provision('id')` and destructured `provision('id')` lookup IDs. */
+const extractLookupProvisionId = (
   node: AstNode,
   ctxNames: ReadonlySet<string>,
-  serviceAliases: ReadonlySet<string>
+  provisionAliases: ReadonlySet<string>
 ): string | null => {
   const callee = extractCallCallee(node);
   if (!callee) {
     return null;
   }
 
-  if (isMemberServiceCall(callee, ctxNames)) {
+  if (isMemberProvisionCall(callee, ctxNames)) {
     return extractFirstStringArg(node);
   }
 
   const calleeName = identifierName(callee);
   const args = node['arguments'] as readonly AstNode[] | undefined;
-  if (calleeName && serviceAliases.has(calleeName) && args?.length === 1) {
+  if (calleeName && provisionAliases.has(calleeName) && args?.length === 1) {
     return extractFirstStringArg(node);
   }
 
   return null;
 };
 
-/** Collect local aliases for the service accessor (e.g. `const { service } = ctx`). */
-const collectServiceAliases = (
+/** Collect local aliases for the provision accessor (e.g. `const { provision } = ctx`). */
+const collectProvisionAliases = (
   body: AstNode,
   ctxNames: ReadonlySet<string>
 ): ReadonlySet<string> => {
@@ -267,7 +267,7 @@ const collectServiceAliases = (
       const keyName = identifierName(
         (property as unknown as { key?: AstNode }).key
       );
-      if (keyName !== 'service') {
+      if (keyName !== 'provision') {
         return [];
       }
 
@@ -300,15 +300,15 @@ const collectServiceAliases = (
   return aliases;
 };
 
-/** Walk run bodies and collect service access that can be resolved statically. */
-const extractCalledServices = (config: AstNode): CalledServices => {
+/** Walk blaze bodies and collect provision access that can be resolved statically. */
+const extractCalledProvisions = (config: AstNode): CalledProvisions => {
   const fromNames = new Set<string>();
   const lookupIds = new Set<string>();
   const lookupNames = new Set<string>();
 
-  for (const body of findRunBodies(config)) {
+  for (const body of findBlazeBodies(config)) {
     const ctxNames = buildCtxNames(body);
-    const serviceAliases = collectServiceAliases(body, ctxNames);
+    const provisionAliases = collectProvisionAliases(body, ctxNames);
 
     walkScope(body, (node) => {
       const fromName = extractFromCallName(node, ctxNames);
@@ -316,15 +316,19 @@ const extractCalledServices = (config: AstNode): CalledServices => {
         fromNames.add(fromName);
       }
 
-      const lookupId = extractLookupServiceId(node, ctxNames, serviceAliases);
+      const lookupId = extractLookupProvisionId(
+        node,
+        ctxNames,
+        provisionAliases
+      );
       if (lookupId) {
         lookupIds.add(lookupId);
       }
 
-      const lookupName = extractLookupServiceName(
+      const lookupName = extractLookupProvisionName(
         node,
         ctxNames,
-        serviceAliases
+        provisionAliases
       );
       if (lookupName) {
         lookupNames.add(lookupName);
@@ -339,58 +343,58 @@ const extractCalledServices = (config: AstNode): CalledServices => {
 // Diagnostics
 // ---------------------------------------------------------------------------
 
-const renderDeclaredService = (service: DeclaredService): string =>
-  service.name ?? service.id ?? '<unknown>';
+const renderDeclaredProvision = (provision: DeclaredProvision): string =>
+  provision.name ?? provision.id ?? '<unknown>';
 
 const buildUndeclaredFromDiagnostic = (
   trailId: string,
-  serviceName: string,
+  provisionName: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": ${serviceName}.from(ctx) called but '${serviceName}' is not declared in services`,
-  rule: 'service-declarations',
+  message: `Trail "${trailId}": ${provisionName}.from(ctx) called but '${provisionName}' is not declared in provisions`,
+  rule: 'provision-declarations',
   severity: 'error',
 });
 
 const buildUndeclaredLookupDiagnostic = (
   trailId: string,
-  serviceId: string,
+  provisionId: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": ctx.service('${serviceId}') called but '${serviceId}' is not declared in services`,
-  rule: 'service-declarations',
+  message: `Trail "${trailId}": ctx.provision('${provisionId}') called but '${provisionId}' is not declared in provisions`,
+  rule: 'provision-declarations',
   severity: 'error',
 });
 
 const buildUndeclaredLookupNameDiagnostic = (
   trailId: string,
-  serviceName: string,
+  provisionName: string,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": ctx.service(${serviceName}) called but '${serviceName}' is not declared in services`,
-  rule: 'service-declarations',
+  message: `Trail "${trailId}": ctx.provision(${provisionName}) called but '${provisionName}' is not declared in provisions`,
+  rule: 'provision-declarations',
   severity: 'error',
 });
 
 const buildUnusedDiagnostic = (
   trailId: string,
-  declaredService: DeclaredService,
+  declaredProvision: DeclaredProvision,
   filePath: string,
   line: number
 ): WardenDiagnostic => ({
   filePath,
   line,
-  message: `Trail "${trailId}": '${renderDeclaredService(declaredService)}' declared in services but never used`,
-  rule: 'service-declarations',
+  message: `Trail "${trailId}": '${renderDeclaredProvision(declaredProvision)}' declared in provisions but never used`,
+  rule: 'provision-declarations',
   severity: 'warn',
 });
 
@@ -398,19 +402,22 @@ const buildUnusedDiagnostic = (
 // Comparison
 // ---------------------------------------------------------------------------
 
-const serviceWasUsed = (
-  declaredService: DeclaredService,
-  calledServices: CalledServices
+const provisionWasUsed = (
+  declaredProvision: DeclaredProvision,
+  calledProvisions: CalledProvisions
 ): boolean => {
   if (
-    declaredService.name &&
-    (calledServices.fromNames.has(declaredService.name) ||
-      calledServices.lookupNames.has(declaredService.name))
+    declaredProvision.name &&
+    (calledProvisions.fromNames.has(declaredProvision.name) ||
+      calledProvisions.lookupNames.has(declaredProvision.name))
   ) {
     return true;
   }
 
-  if (declaredService.id && calledServices.lookupIds.has(declaredService.id)) {
+  if (
+    declaredProvision.id &&
+    calledProvisions.lookupIds.has(declaredProvision.id)
+  ) {
     return true;
   }
 
@@ -418,31 +425,35 @@ const serviceWasUsed = (
 };
 
 const buildDeclaredNames = (
-  declaredServices: readonly DeclaredService[]
+  declaredProvisions: readonly DeclaredProvision[]
 ): ReadonlySet<string> =>
   new Set(
-    declaredServices.flatMap((service) => (service.name ? [service.name] : []))
+    declaredProvisions.flatMap((provision) =>
+      provision.name ? [provision.name] : []
+    )
   );
 
 const buildDeclaredIds = (
-  declaredServices: readonly DeclaredService[]
+  declaredProvisions: readonly DeclaredProvision[]
 ): ReadonlySet<string> =>
   new Set(
-    declaredServices.flatMap((service) => (service.id ? [service.id] : []))
+    declaredProvisions.flatMap((provision) =>
+      provision.id ? [provision.id] : []
+    )
   );
 
 const reportUndeclaredFromCalls = (
   trailId: string,
   filePath: string,
   line: number,
-  calledServices: CalledServices,
+  calledProvisions: CalledProvisions,
   declaredNames: ReadonlySet<string>,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  for (const serviceName of calledServices.fromNames) {
-    if (!declaredNames.has(serviceName)) {
+  for (const provisionName of calledProvisions.fromNames) {
+    if (!declaredNames.has(provisionName)) {
       diagnostics.push(
-        buildUndeclaredFromDiagnostic(trailId, serviceName, filePath, line)
+        buildUndeclaredFromDiagnostic(trailId, provisionName, filePath, line)
       );
     }
   }
@@ -452,19 +463,19 @@ const reportUndeclaredLookupCalls = (
   trailId: string,
   filePath: string,
   line: number,
-  calledServices: CalledServices,
+  calledProvisions: CalledProvisions,
   declaredIds: ReadonlySet<string>,
   declaredNames: ReadonlySet<string>,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  for (const serviceName of calledServices.lookupNames) {
-    // Name-based lookup checks remain reliable even when an imported service ID
+  for (const provisionName of calledProvisions.lookupNames) {
+    // Name-based lookup checks remain reliable even when an imported provision ID
     // cannot be resolved locally.
-    if (!declaredNames.has(serviceName)) {
+    if (!declaredNames.has(provisionName)) {
       diagnostics.push(
         buildUndeclaredLookupNameDiagnostic(
           trailId,
-          serviceName,
+          provisionName,
           filePath,
           line
         )
@@ -472,10 +483,10 @@ const reportUndeclaredLookupCalls = (
     }
   }
 
-  for (const serviceId of calledServices.lookupIds) {
-    if (!declaredIds.has(serviceId)) {
+  for (const provisionId of calledProvisions.lookupIds) {
+    if (!declaredIds.has(provisionId)) {
       diagnostics.push(
-        buildUndeclaredLookupDiagnostic(trailId, serviceId, filePath, line)
+        buildUndeclaredLookupDiagnostic(trailId, provisionId, filePath, line)
       );
     }
   }
@@ -485,54 +496,54 @@ const reportUnusedDeclarations = (
   trailId: string,
   filePath: string,
   line: number,
-  declaredServices: readonly DeclaredService[],
-  calledServices: CalledServices,
+  declaredProvisions: readonly DeclaredProvision[],
+  calledProvisions: CalledProvisions,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  for (const declaredService of declaredServices) {
-    if (serviceWasUsed(declaredService, calledServices)) {
+  for (const declaredProvision of declaredProvisions) {
+    if (provisionWasUsed(declaredProvision, calledProvisions)) {
       continue;
     }
 
-    if (declaredService.name && declaredService.id === null) {
+    if (declaredProvision.name && declaredProvision.id === null) {
       continue;
     }
 
     diagnostics.push(
-      buildUnusedDiagnostic(trailId, declaredService, filePath, line)
+      buildUnusedDiagnostic(trailId, declaredProvision, filePath, line)
     );
   }
 };
 
-const hasNoServiceActivity = (
-  declaredServices: readonly DeclaredService[],
-  calledServices: CalledServices
+const hasNoProvisionActivity = (
+  declaredProvisions: readonly DeclaredProvision[],
+  calledProvisions: CalledProvisions
 ): boolean =>
-  declaredServices.length === 0 &&
-  calledServices.fromNames.size === 0 &&
-  calledServices.lookupIds.size === 0 &&
-  calledServices.lookupNames.size === 0;
+  declaredProvisions.length === 0 &&
+  calledProvisions.fromNames.size === 0 &&
+  calledProvisions.lookupIds.size === 0 &&
+  calledProvisions.lookupNames.size === 0;
 
 const analyzeTrailServices = (
   def: { config: AstNode; start: number },
   sourceCode: string,
-  serviceIdsByName: ReadonlyMap<string, string>
+  provisionIdsByName: ReadonlyMap<string, string>
 ): {
-  readonly calledServices: CalledServices;
+  readonly calledProvisions: CalledProvisions;
   readonly declaredIds: ReadonlySet<string>;
   readonly declaredNames: ReadonlySet<string>;
-  readonly declaredServices: readonly DeclaredService[];
+  readonly declaredProvisions: readonly DeclaredProvision[];
   readonly line: number;
 } => {
-  const declaredServices = extractDeclaredServices(
+  const declaredProvisions = extractDeclaredProvisions(
     def.config,
-    serviceIdsByName
+    provisionIdsByName
   );
   return {
-    calledServices: extractCalledServices(def.config),
-    declaredIds: buildDeclaredIds(declaredServices),
-    declaredNames: buildDeclaredNames(declaredServices),
-    declaredServices,
+    calledProvisions: extractCalledProvisions(def.config),
+    declaredIds: buildDeclaredIds(declaredProvisions),
+    declaredNames: buildDeclaredNames(declaredProvisions),
+    declaredProvisions,
     line: offsetToLine(sourceCode, def.start),
   };
 };
@@ -541,13 +552,18 @@ const checkTrailDefinition = (
   def: { id: string; config: AstNode; start: number },
   filePath: string,
   sourceCode: string,
-  serviceIdsByName: ReadonlyMap<string, string>,
+  provisionIdsByName: ReadonlyMap<string, string>,
   diagnostics: WardenDiagnostic[]
 ): void => {
-  const { calledServices, declaredIds, declaredNames, declaredServices, line } =
-    analyzeTrailServices(def, sourceCode, serviceIdsByName);
+  const {
+    calledProvisions,
+    declaredIds,
+    declaredNames,
+    declaredProvisions,
+    line,
+  } = analyzeTrailServices(def, sourceCode, provisionIdsByName);
 
-  if (hasNoServiceActivity(declaredServices, calledServices)) {
+  if (hasNoProvisionActivity(declaredProvisions, calledProvisions)) {
     return;
   }
 
@@ -555,7 +571,7 @@ const checkTrailDefinition = (
     def.id,
     filePath,
     line,
-    calledServices,
+    calledProvisions,
     declaredNames,
     diagnostics
   );
@@ -563,7 +579,7 @@ const checkTrailDefinition = (
     def.id,
     filePath,
     line,
-    calledServices,
+    calledProvisions,
     declaredIds,
     declaredNames,
     diagnostics
@@ -572,8 +588,8 @@ const checkTrailDefinition = (
     def.id,
     filePath,
     line,
-    declaredServices,
-    calledServices,
+    declaredProvisions,
+    calledProvisions,
     diagnostics
   );
 };
@@ -583,9 +599,9 @@ const checkTrailDefinition = (
 // ---------------------------------------------------------------------------
 
 /**
- * Validates that service access aligns with declared `services` arrays.
+ * Validates that provision access aligns with declared `provisions` arrays.
  */
-export const serviceDeclarations: WardenRule = {
+export const provisionDeclarations: WardenRule = {
   check(sourceCode: string, filePath: string): readonly WardenDiagnostic[] {
     if (isTestFile(filePath)) {
       return [];
@@ -597,14 +613,14 @@ export const serviceDeclarations: WardenRule = {
     }
 
     const diagnostics: WardenDiagnostic[] = [];
-    const serviceIdsByName = collectNamedServiceIds(ast);
+    const provisionIdsByName = collectNamedProvisionIds(ast);
 
     for (const def of findTrailDefinitions(ast)) {
       checkTrailDefinition(
         def,
         filePath,
         sourceCode,
-        serviceIdsByName,
+        provisionIdsByName,
         diagnostics
       );
     }
@@ -612,7 +628,7 @@ export const serviceDeclarations: WardenRule = {
     return diagnostics;
   },
   description:
-    'Ensure service.from(ctx) and ctx.service() calls match the declared services array in trail definitions.',
-  name: 'service-declarations',
+    'Ensure provision.from(ctx) and ctx.provision() calls match the declared provisions array in trail definitions.',
+  name: 'provision-declarations',
   severity: 'error',
 };