@graphorin/eslint-plugin 0.6.1 → 0.7.0

package/src/rules/no-third-party-workflow-aliases.ts

@@ -0,0 +1,100 @@
+/**
+ * Rule: `@graphorin/no-third-party-workflow-aliases` (DEC-019 /
+ * ADR-029). Flags any identifier in `@graphorin/workflow` source whose
+ * name matches a known third-party workflow primitive (e.g. the
+ * library-specific names that Graphorin deliberately renamed). The
+ * intent is legal hygiene: the framework's primitives are
+ * `Directive`, `Dispatch`, `pause`, `LatestValue`, `Reducer`,
+ * `Stream`, `Barrier`, `Ephemeral`, `AnyValue` - we never reuse
+ * external library identifiers in the public API.
+ *
+ * The forbidden list is intentionally narrow - we only flag the
+ * canonical proper-noun primitives third-party workflow engines use.
+ * Rare false positives (e.g. an internal helper named `Send` for an
+ * unrelated reason) are mitigated by the per-occurrence opt-out
+ * comment `// graphorin-workflow-naming-allow: <reason>`.
+ *
+ * The rule activates only on files inside the
+ * `@graphorin/workflow` package source tree (path matcher
+ * `packages/workflow/src`).
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+import type { Identifier, Node } from 'estree';
+
+import { nodeHasNearbyComment } from './_comment-utils.js';
+
+const ALLOW_TAG = /graphorin-workflow-naming-allow/;
+const WORKFLOW_PATH_RE = /\bpackages\/workflow\/src\b/;
+
+const FORBIDDEN_NAMES: ReadonlyMap<string, string> = new Map([
+  ['Send', 'Dispatch'],
+  ['Command', 'Directive'],
+  ['interrupt', 'pause'],
+  ['LastValue', 'LatestValue'],
+  ['BinaryOperatorAggregate', 'Reducer'],
+  ['BinaryAggregate', 'Reducer'],
+  ['Topic', 'Stream'],
+]);
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Disallow third-party workflow primitive identifiers in `@graphorin/workflow` source. Graphorin owns its primitive names per DEC-019.',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      forbidden:
+        "identifier '{{forbidden}}' is reserved for the third-party workflow library it originates from; use '{{replacement}}' (DEC-019).",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    if (!WORKFLOW_PATH_RE.test(context.filename.replace(/\\/g, '/'))) {
+      return {};
+    }
+    return {
+      Identifier(node: Identifier): void {
+        const replacement = FORBIDDEN_NAMES.get(node.name);
+        if (replacement === undefined) return;
+        if (isInImportSpecifier(node)) return;
+        if (hasAllowComment(context, node)) return;
+        context.report({
+          node,
+          messageId: 'forbidden',
+          data: {
+            forbidden: node.name,
+            replacement,
+          },
+        });
+      },
+    };
+  },
+};
+
+function isInImportSpecifier(node: Identifier): boolean {
+  // Skip identifiers used as keys / property names - those are
+  // typically referencing external library exports the user is
+  // intentionally importing into a renamed local symbol.
+  const parent = (node as Identifier & { parent?: Node }).parent;
+  if (parent === undefined) return false;
+  switch (parent.type) {
+    case 'ImportSpecifier':
+    case 'ImportNamespaceSpecifier':
+    case 'ImportDefaultSpecifier':
+    case 'ExportSpecifier':
+      return true;
+    default:
+      return false;
+  }
+}
+
+function hasAllowComment(context: Rule.RuleContext, node: Identifier): boolean {
+  return nodeHasNearbyComment(context, node, ALLOW_TAG, 1);
+}
+
+export default rule;

package/src/rules/provider-middleware-order.ts

@@ -0,0 +1,113 @@
+/**
+ * Rule: `@graphorin/provider-middleware-order` (DEC-145 / ADR-039).
+ * Lint-time enforcement of the canonical middleware ordering for
+ * `composeProviderMiddleware([...])`. Catches the same class of error
+ * the runtime composer raises (`MiddlewareOrderingError`) without
+ * requiring the runtime to actually wire the chain.
+ *
+ * The canonical order, outermost → innermost, mirrors the runtime
+ * constant `CANONICAL_MIDDLEWARE_ORDER` exported by
+ * `@graphorin/provider/middleware`. Built-ins not in the canonical
+ * list are tolerated at any position.
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+import type { ArrayExpression, CallExpression, Identifier, Node } from 'estree';
+
+const CANONICAL_ORDER: ReadonlyArray<string> = [
+  'withTracing',
+  'withRetry',
+  'withRateLimit',
+  'withCostLimit',
+  'withCostTracking',
+  'withFallback',
+  'withRedaction',
+];
+
+const CANONICAL_INDEX: ReadonlyMap<string, number> = new Map(
+  CANONICAL_ORDER.map((name, idx) => [name, idx]),
+);
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Enforce the canonical provider-middleware ordering at lint time. Mirrors the runtime `MiddlewareOrderingError` from `@graphorin/provider/middleware`.',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      orderingViolation: "'{{outer}}' must appear before '{{inner}}' (canonical order: {{order}}).",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      CallExpression(node: CallExpression): void {
+        if (!isComposeCall(node)) return;
+        const arg = node.arguments[0];
+        if (arg === undefined || arg.type !== 'ArrayExpression') return;
+        const factories = extractFactoryNames(arg as ArrayExpression);
+        const recognised: { name: string; index: number; node: Node }[] = [];
+        for (const f of factories) {
+          const idx = CANONICAL_INDEX.get(f.name);
+          if (idx !== undefined) recognised.push({ name: f.name, index: idx, node: f.node });
+        }
+        for (let i = 1; i < recognised.length; i++) {
+          const prev = recognised[i - 1];
+          const cur = recognised[i];
+          if (prev !== undefined && cur !== undefined && prev.index > cur.index) {
+            context.report({
+              node: cur.node,
+              messageId: 'orderingViolation',
+              data: {
+                outer: cur.name,
+                inner: prev.name,
+                order: CANONICAL_ORDER.join(' → '),
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+function isComposeCall(node: CallExpression): boolean {
+  if (node.callee.type === 'Identifier') {
+    return (node.callee as Identifier).name === 'composeProviderMiddleware';
+  }
+  if (node.callee.type === 'MemberExpression') {
+    const prop = node.callee.property;
+    if (prop.type === 'Identifier' && prop.name === 'composeProviderMiddleware') return true;
+  }
+  return false;
+}
+
+function extractFactoryNames(arr: ArrayExpression): { name: string; node: Node }[] {
+  const out: { name: string; node: Node }[] = [];
+  for (const elt of arr.elements) {
+    if (elt === null) continue;
+    // Each element is one of:
+    //   - `withTracing()` / `withRetry({...})` - CallExpression with Identifier callee
+    //   - `withTracing` (factory ref) - Identifier
+    //   - `provider.withTracing()` - CallExpression with MemberExpression callee
+    if (elt.type === 'Identifier') {
+      out.push({ name: (elt as Identifier).name, node: elt });
+      continue;
+    }
+    if (elt.type === 'CallExpression') {
+      const callee = elt.callee;
+      if (callee.type === 'Identifier') {
+        out.push({ name: (callee as Identifier).name, node: elt });
+      } else if (callee.type === 'MemberExpression' && callee.property.type === 'Identifier') {
+        out.push({ name: callee.property.name, node: elt });
+      }
+    }
+  }
+  return out;
+}
+
+export default rule;

package/src/rules/tool-description-required.ts

@@ -0,0 +1,75 @@
+/**
+ * Rule: `@graphorin/tool-description-required` (RB-49 / suggested
+ * DEC-165). Flags `tool({...})` invocations whose `description`
+ * field is missing, too short (< 20 characters), or a placeholder
+ * value (`'TODO'` / `'FIXME'` / `'tbd'` / `'description'` /
+ * `'placeholder'`, case-insensitive).
+ *
+ * The rule shares its discovery + scoring code with the
+ * `graphorin tools lint` CLI subcommand (Phase 15) so the rule
+ * logic has a single source of truth.
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+
+import { discoverToolCallsInSource, PLACEHOLDER_DESCRIPTIONS } from '../tool-discovery.js';
+
+const MIN_DESCRIPTION_LENGTH = 20;
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'Require a meaningful `description` on every `tool({...})` registration. RB-49 (Anthropic 2026 advanced tool use guidance).',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      missing:
+        "tool '{{name}}' has no description; add a description that explains what the tool does and when to use it.",
+      tooShort:
+        "tool '{{name}}' description is shorter than {{min}} characters (currently {{len}}).",
+      placeholder: "tool '{{name}}' description is a placeholder ('{{value}}').",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      'Program:exit'(): void {
+        const filename = context.filename;
+        const source = context.sourceCode.text;
+        const tools = discoverToolCallsInSource(filename, source);
+        for (const tool of tools) {
+          const desc = tool.description?.trim();
+          if (desc === undefined || desc.length === 0) {
+            context.report({
+              loc: { line: tool.line, column: 0 },
+              messageId: 'missing',
+              data: { name: tool.name },
+            });
+          } else if (desc.length < MIN_DESCRIPTION_LENGTH) {
+            context.report({
+              loc: { line: tool.line, column: 0 },
+              messageId: 'tooShort',
+              data: {
+                name: tool.name,
+                min: String(MIN_DESCRIPTION_LENGTH),
+                len: String(desc.length),
+              },
+            });
+          } else if (PLACEHOLDER_DESCRIPTIONS.includes(desc.toLowerCase())) {
+            context.report({
+              loc: { line: tool.line, column: 0 },
+              messageId: 'placeholder',
+              data: { name: tool.name, value: desc },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/src/rules/tool-examples-recommended.ts

@@ -0,0 +1,61 @@
+/**
+ * Rule: `@graphorin/tool-examples-recommended` (RB-49). Flags
+ * `tool({...})` invocations whose `examples` field is missing,
+ * empty, or longer than the documented upper bound (5).
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+
+import { discoverToolCallsInSource } from '../tool-discovery.js';
+
+const MAX_EXAMPLES = 5;
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        "Recommend 1-5 `examples` entries on every `tool({...})` registration (Anthropic 2026 'Writing effective tools' guidance).",
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      missing:
+        "tool '{{name}}' has no examples; add 1-5 worked examples per Anthropic 2026 guidance.",
+      tooMany:
+        "tool '{{name}}' declares {{count}} examples; the documented upper bound is {{max}}.",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      'Program:exit'(): void {
+        const filename = context.filename;
+        const source = context.sourceCode.text;
+        const tools = discoverToolCallsInSource(filename, source);
+        for (const tool of tools) {
+          if (!tool.hasExamples || tool.examplesCount === 0) {
+            context.report({
+              loc: { line: tool.line, column: 0 },
+              messageId: 'missing',
+              data: { name: tool.name },
+            });
+          } else if (tool.examplesCount > MAX_EXAMPLES) {
+            context.report({
+              loc: { line: tool.line, column: 0 },
+              messageId: 'tooMany',
+              data: {
+                name: tool.name,
+                count: String(tool.examplesCount),
+                max: String(MAX_EXAMPLES),
+              },
+            });
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;

package/src/rules/tool-parameter-naming.ts

@@ -0,0 +1,75 @@
+/**
+ * Rule: `@graphorin/tool-parameter-naming` (RB-49). Inspects the
+ * `inputSchema: z.object({...})` declaration of every `tool({...})`
+ * invocation and flags two anti-patterns:
+ *
+ *   - **Ambiguous single-word identifiers** (`user`, `id`, `name`,
+ *     `value`, `data`, `input`, `output`, `result`, `to`, `from`,
+ *     `key`, `field`). Suggest a self-documenting alternative.
+ *   - **Numeric-suffix identifiers** (`arg1`, `arg2`, `param3`).
+ *     Suggest a semantic name.
+ *
+ * Per-tool opt-out: when the tool declares `tags: ['experimental']`
+ * or `tags: ['legacy']` the rule is suppressed for that registration.
+ * This lets operators defer the rename for a long tail of pre-RB-49
+ * tools while the framework migrates without breaking calling code.
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+
+import {
+  AMBIGUOUS_PARAMETER_NAMES,
+  discoverToolCallsInSource,
+  PARAMETER_NAMING_OPT_OUT_TAGS,
+} from '../tool-discovery.js';
+
+const NUMERIC_SUFFIX_PATTERN = /^[A-Za-z]+\d+$/;
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Flag ambiguous or numeric-suffix parameter names on `tool({...})` `inputSchema` declarations (RB-49 - write self-documenting parameter names).',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      ambiguous:
+        "tool '{{name}}' uses ambiguous parameter name '{{param}}'; prefer a self-documenting name (e.g. '{{param}}Id', '{{param}}Email').",
+      numericSuffix:
+        "tool '{{name}}' uses numeric-suffix parameter name '{{param}}'; prefer a semantic name (e.g. 'queryText', 'userId').",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      'Program:exit'(): void {
+        const filename = context.filename;
+        const source = context.sourceCode.text;
+        const tools = discoverToolCallsInSource(filename, source);
+        for (const tool of tools) {
+          if (tool.tags.some((t) => PARAMETER_NAMING_OPT_OUT_TAGS.includes(t))) continue;
+          for (const param of tool.parameterNames) {
+            if (AMBIGUOUS_PARAMETER_NAMES.includes(param)) {
+              context.report({
+                loc: { line: tool.line, column: 0 },
+                messageId: 'ambiguous',
+                data: { name: tool.name, param },
+              });
+            } else if (NUMERIC_SUFFIX_PATTERN.test(param)) {
+              context.report({
+                loc: { line: tool.line, column: 0 },
+                messageId: 'numericSuffix',
+                data: { name: tool.name, param },
+              });
+            }
+          }
+        }
+      },
+    };
+  },
+};
+
+export default rule;