@mnci/az-durable 0.1.1 → 0.1.3

package/dist/eslint-plugin.cjs.js

@@ -0,0 +1,369 @@
+'use strict';
+
+/**
+ * Minimal ESLint rule shapes, declared locally.
+ *
+ * @remarks
+ * Declared here rather than imported from `@types/eslint` or
+ * `@typescript-eslint/utils` because this package ships **zero runtime
+ * dependencies**, and a type-only dependency is still a dependency a consumer
+ * must be able to resolve. These cover exactly what the three rules use.
+ */
+/**
+ * Whether a call expression registers an orchestration.
+ *
+ * @remarks
+ * Matches both `defineOrchestration(...)` and the raw
+ * `df.app.orchestration(...)`, since an orchestration written either way has
+ * the same determinism constraints.
+ *
+ * **Heuristic, by construction.** These rules match on call-site SHAPE, so an
+ * orchestration body extracted into a helper function is not caught. That is a
+ * documented limit rather than a defect: following the value would require type
+ * information the rule deliberately does not depend on.
+ *
+ * @param node - A `CallExpression` node.
+ * @returns `true` when the call registers an orchestration.
+ * @throws Never - pure inspection.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function isOrchestrationRegistration(node) {
+  const callee = node.callee;
+  if (callee === undefined) {
+    return false;
+  }
+  if (callee.type === 'Identifier' && callee.name === 'defineOrchestration') {
+    return true;
+  }
+  // df.app.orchestration(...) — match on the trailing property, so any local
+  // alias for the namespace still matches.
+  if (callee.type === 'MemberExpression') {
+    const property = callee.property;
+    return property?.type === 'Identifier' && property.name === 'orchestration';
+  }
+  return false;
+}
+/**
+ * The name a callee refers to, if it is a plain identifier or member access.
+ *
+ * @remarks
+ * For a member expression this returns the TRAILING property, so `df.now()`
+ * and `context.df.now()` both read as `now`. Callers that must distinguish a
+ * bare call from a member call check `node.type` themselves - `require-yield-star`
+ * does exactly that, because `yield c.df.callActivity(...)` is the correct raw
+ * SDK call and must not be flagged.
+ *
+ * @param node - A callee node.
+ * @returns The identifier or property name, or `undefined`.
+ * @throws Never - pure inspection.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function calleeName(node) {
+  if (node === undefined) {
+    return undefined;
+  }
+  if (node.type === 'Identifier') {
+    return node.name;
+  }
+  if (node.type === 'MemberExpression') {
+    const property = node.property;
+    if (property?.type === 'Identifier') {
+      return property.name;
+    }
+  }
+  return undefined;
+}
+
+/** Global reads that differ on every replay, with the replacement to suggest. */
+const FORBIDDEN_CALLS = {
+  'Date.now': 'now(context).getTime()',
+  'Math.random': 'context.df.newGuid(...) or an activity',
+  'crypto.randomUUID': 'context.df.newGuid(...)',
+  fetch: 'an activity — network calls must not run in an orchestrator',
+  axios: 'an activity — network calls must not run in an orchestrator'
+};
+/**
+ * Flags non-deterministic operations inside an orchestration body.
+ *
+ * @remarks
+ * The highest-value rule in the package. Each of these returns a DIFFERENT
+ * value on every replay, and the failure is silent: the orchestration still
+ * completes, it just produces output that disagrees with its own history.
+ * Nothing in the runtime reports it.
+ *
+ * Every message names the replacement, because "this is non-deterministic" is
+ * only half of what a reader needs.
+ *
+ * Heuristic by design — see {@link isOrchestrationRegistration}.
+ */
+const noNondeterministicOrchestrator = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow non-deterministic operations inside an orchestration.'
+    },
+    schema: [],
+    messages: {
+      forbidden: '{{what}} is non-deterministic on replay. Use {{fix}} instead.',
+      newDate: 'new Date() is non-deterministic on replay. Use now(context) instead.',
+      processEnv: 'process.env is read at replay time and may differ between deploys. ' + 'Read it in an activity, or pass it as orchestration input.'
+    }
+  },
+  create(context) {
+    let depth = 0;
+    const enter = node => {
+      if (isOrchestrationRegistration(node)) {
+        depth += 1;
+      }
+    };
+    const exit = node => {
+      if (isOrchestrationRegistration(node)) {
+        depth -= 1;
+      }
+    };
+    return {
+      CallExpression: node => {
+        enter(node);
+        if (depth === 0) {
+          return;
+        }
+        const callee = node.callee;
+        const object = callee?.object;
+        const full = object?.type === 'Identifier' ? `${String(object.name)}.${String(calleeName(callee))}` : calleeName(callee) ?? '';
+        const fix = FORBIDDEN_CALLS[full];
+        if (fix !== undefined) {
+          context.report({
+            node,
+            messageId: 'forbidden',
+            data: {
+              what: full,
+              fix
+            }
+          });
+        }
+      },
+      'CallExpression:exit': exit,
+      NewExpression: node => {
+        if (depth === 0) {
+          return;
+        }
+        const callee = node.callee;
+        const args = node.arguments;
+        // `new Date(someInstant)` is fine and common — only the argument-less
+        // form reads the wall clock.
+        if (callee?.type === 'Identifier' && callee.name === 'Date' && (args?.length ?? 0) === 0) {
+          context.report({
+            node,
+            messageId: 'newDate'
+          });
+        }
+      },
+      MemberExpression: node => {
+        if (depth === 0) {
+          return;
+        }
+        const object = node.object;
+        const property = node.property;
+        if (object?.type === 'Identifier' && object.name === 'process' && property?.type === 'Identifier' && property.name === 'env') {
+          context.report({
+            node,
+            messageId: 'processEnv'
+          });
+        }
+      }
+    };
+  }
+};
+
+/** SDK handler aliases that erase a handler's real signature. */
+const ERASING_TYPES = new Set(['ActivityHandler', 'OrchestrationHandler', 'FunctionHandler']);
+/**
+ * The annotation's type name, if it is a bare type reference.
+ *
+ * @param annotation - A node carrying a `typeAnnotation`, or `undefined`.
+ * @returns The referenced type's name, or `undefined` when it is not a bare reference.
+ * @throws Never - pure inspection.
+ * @typeParam None - this function has no generic type parameters.
+ */
+function referencedName(annotation) {
+  const typeAnnotation = annotation?.typeAnnotation;
+  if (typeAnnotation?.type !== 'TSTypeReference') {
+    return undefined;
+  }
+  const typeName = typeAnnotation.typeName;
+  return typeName?.type === 'Identifier' ? typeName.name : undefined;
+}
+/**
+ * Flags annotations that collapse a typed handler back to `any`.
+ *
+ * @remarks
+ * **The rule that actually earns its keep**, because TypeScript cannot catch
+ * this: the annotation is legal, so nothing errors — the types simply stop
+ * meaning anything.
+ *
+ * `ActivityHandler` is an alias for `FunctionHandler`, which the SDK declares as
+ * `(triggerInput: any, context: InvocationContext) => FunctionResult<any>`. So
+ * annotating a handler with it discards the very signature `defineActivity`
+ * exists to capture, and the activity silently becomes `any` in, `any` out. The
+ * package then appears to work — every call compiles — while checking nothing.
+ *
+ * The second, nastier form is a middleware wrapper typed
+ * `(h: ActivityHandler) => ActivityHandler`. That collapses EVERY handler it
+ * wraps, so one `injectLogger` helper can quietly disable type safety across a
+ * whole Function App. The fix is to make the wrapper generic:
+ *
+ * ```ts
+ * const withLogging = <I, O>(h: (i: I, c: InvocationContext) => O) =>
+ *   (i: I, c: InvocationContext): O => { c.log('...'); return h(i, c) }
+ * ```
+ */
+const noUntypedActivityHandler = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Disallow handler annotations that erase inferred types.'
+    },
+    schema: [],
+    messages: {
+      erased: "Annotating with '{{name}}' erases the handler's real signature — it is an alias for " + '(triggerInput: any, context) => any, so the activity becomes `any` in and `any` out. ' + 'Drop the annotation and let defineActivity infer it.',
+      erasedWrapper: "A wrapper typed '{{name}}' collapses every handler it wraps to `any`. " + 'Make it generic: <I, O>(h: (i: I, c: InvocationContext) => O) => (i: I, c: InvocationContext): O.'
+    }
+  },
+  create(context) {
+    return {
+      // const handler: ActivityHandler = ...
+      Identifier: node => {
+        const name = referencedName(node.typeAnnotation);
+        if (name === undefined || !ERASING_TYPES.has(name)) {
+          return;
+        }
+        // A function PARAMETER annotated this way is the middleware form, which
+        // is worse: it erases every handler passed through it, not just one.
+        const isParameter = node.parent?.type?.startsWith('TS') === false && node.parent?.params?.includes(node) === true;
+        context.report({
+          node,
+          messageId: isParameter ? 'erasedWrapper' : 'erased',
+          data: {
+            name
+          }
+        });
+      }
+    };
+  }
+};
+
+/** The wrapper calls that must be delegated to, not yielded. */
+const DELEGATED = new Set(['callActivity', 'callSubOrchestration', 'all', 'any', 'waitForEvent', 'sleepFor', 'sleepUntil']);
+/**
+ * Flags `yield callActivity(...)` where `yield *` is meant.
+ *
+ * @remarks
+ * **A convenience, not a safety net — and the build plan was wrong about this.**
+ * The plan described bare `yield` as compiling silently to `any`, "the
+ * difference between the package working and appearing to work". Measured
+ * against the real typings, it is a COMPILE ERROR in both registration paths:
+ * `TS2345` through `defineOrchestration` and `TS2322` through the SDK's own
+ * `OrchestrationHandler`, because these helpers return a `Generator` and
+ * yielding one where a `Task` is expected does not typecheck.
+ *
+ * The genuinely silent case is the RAW SDK — `yield context.df.callActivity(...)`
+ * returns `any` and compiles — which is the baseline this package replaces.
+ *
+ * So this rule earns its place only by reporting a clearer message than
+ * `TS2345` does. It is in `recommended` for that reason, not because anything
+ * depends on it.
+ */
+const requireYieldStar = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Require `yield *` when calling a delegating helper.'
+    },
+    schema: [],
+    messages: {
+      useYieldStar: "Use 'yield *' rather than 'yield' with {{name}}(). Delegation is what carries the " + 'result type; a bare yield does not typecheck, but the compiler error is obscure.'
+    }
+  },
+  create(context) {
+    return {
+      YieldExpression: node => {
+        if (node.delegate === true) {
+          return;
+        }
+        const argument = node.argument;
+        if (argument?.type !== 'CallExpression') {
+          return;
+        }
+        // A BARE IDENTIFIER only. `c.df.callActivity(...)` is the raw SDK call,
+        // which is correct code and must not be flagged — matching the trailing
+        // property of a member expression would flag it, which a negative
+        // fixture caught.
+        const callee = argument.callee;
+        if (callee?.type !== 'Identifier') {
+          return;
+        }
+        const name = callee.name;
+        if (DELEGATED.has(name)) {
+          context.report({
+            node,
+            messageId: 'useYieldStar',
+            data: {
+              name
+            }
+          });
+        }
+      }
+    };
+  }
+};
+
+/**
+ * Every rule this plugin ships, by name.
+ *
+ * @remarks
+ * The keys are the names a config writes after the `az-durable/` prefix, so
+ * renaming one is a breaking change for any consumer's config.
+ */
+const rules = {
+  'no-nondeterministic-orchestrator': noNondeterministicOrchestrator,
+  'no-untyped-activity-handler': noUntypedActivityHandler,
+  'require-yield-star': requireYieldStar
+};
+/**
+ * The plugin object, for a flat config's `plugins` map.
+ *
+ * @remarks
+ * Shipped from a separate entry point so lint rules are never a runtime import
+ * of the wrapper itself.
+ */
+const plugin = {
+  rules
+};
+/**
+ * The recommended rule set.
+ *
+ * @remarks
+ * Two errors and one warning, and the split is deliberate.
+ * `no-nondeterministic-orchestrator` and `no-untyped-activity-handler` catch
+ * failures nothing else does — silent replay corruption, and a type collapse
+ * TypeScript accepts as legal. `require-yield-star` is a warning because the
+ * compiler already rejects the code it flags; it only improves the message.
+ */
+const recommended = {
+  plugins: {
+    'az-durable': plugin
+  },
+  rules: {
+    'az-durable/no-nondeterministic-orchestrator': 'error',
+    'az-durable/no-untyped-activity-handler': 'error',
+    'az-durable/require-yield-star': 'warn'
+  }
+};
+
+exports.noNondeterministicOrchestrator = noNondeterministicOrchestrator;
+exports.noUntypedActivityHandler = noUntypedActivityHandler;
+exports.plugin = plugin;
+exports.recommended = recommended;
+exports.requireYieldStar = requireYieldStar;
+exports.rules = rules;
+//# sourceMappingURL=eslint-plugin.cjs.js.map