@graphorin/eslint-plugin 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# @graphorin/eslint-plugin
+
+## 0.1.0
+
+### Minor Changes
+
+- Initial scaffold for the Graphorin ESLint plugin. Ships an empty rule set
+  and a single no-op rule (`no-console-in-public-api`) used to verify that
+  the plugin loads correctly in a host project. The full ruleset lands in a
+  later release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oleksiy Stepurenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# @graphorin/eslint-plugin
+
+> ESLint rules for projects that build on **Graphorin**.
+
+- **Status:** v0.5.0 — final Phase 16 ruleset.
+- **License:** [MIT](./LICENSE) — © 2026 Oleksiy Stepurenko.
+- **Engines:** Node.js 22+ (ESM only).
+- **Peer dependency:** `eslint >= 9`.
+
+## Installation
+
+```bash
+pnpm add -D eslint @graphorin/eslint-plugin
+```
+
+## Usage (ESLint flat config — `eslint.config.js`)
+
+```js
+import graphorin from '@graphorin/eslint-plugin';
+
+export default [
+  {
+    plugins: { '@graphorin': graphorin },
+    rules: {
+      '@graphorin/tool-description-required': 'error',
+      '@graphorin/tool-examples-recommended': 'warn',
+      '@graphorin/tool-parameter-naming': 'warn',
+      '@graphorin/no-secret-unwrap': 'error',
+      '@graphorin/no-secret-in-deps': 'error',
+      '@graphorin/no-implicit-network-call': 'error',
+      '@graphorin/no-third-party-workflow-aliases': 'error',
+      '@graphorin/provider-middleware-order': 'error',
+      '@graphorin/no-bare-tool-exec': 'warn',
+    },
+  },
+];
+```
+
+The bundled config wires every active rule at the severities documented below.
+For ESLint 9+ flat config (`eslint.config.js`), spread `flat/recommended` — it
+maps the `@graphorin` namespace to the plugin object for you:
+
+```js
+import graphorin from '@graphorin/eslint-plugin';
+
+export default [
+  graphorin.configs['flat/recommended'],
+];
+```
+
+The legacy `.eslintrc` form is still exported as `configs.recommended`
+(`plugins: ['@graphorin']`) for ESLint 8 consumers.
+
+## Rules
+
+| Rule | Status |
+|---|---|
+| `tool-description-required` | Active. Flags `tool({...})` registrations whose `description` is missing, shorter than 20 characters, or a placeholder value (`'TODO'`, `'FIXME'`, `'tbd'`, `'description'`, `'placeholder'`). |
+| `tool-examples-recommended` | Active. Flags missing or empty `examples` arrays and rejects more than the documented upper bound (5). |
+| `tool-parameter-naming` | Active. Flags ambiguous single-word parameter names (`user`, `id`, `name`, `value`, `data`, `input`, `output`, `result`, `to`, `from`, `key`, `field`) and numeric-suffix names (`arg1`, `param2`) on `inputSchema: z.object({ ... })`. Per-tool opt-out via `tags: ['experimental']` or `tags: ['legacy']`. |
+| `no-secret-unwrap` | Active. Flags `.unwrap()` and `.reveal()` calls on `SecretValue`-shaped expressions. `.unwrap()` is reported as `'error'` regardless of comments (the method is `@deprecated`); `.reveal()` honours the `// graphorin-allow-secret-unwrap: <reason>` opt-out. |
+| `no-secret-in-deps` | Active. Flags `Agent.toTool({ inheritSecrets: [...] })` calls whose allowlist is non-empty and lacks an `// rb-24-justification: <reason>` comment. |
+| `provider-middleware-order` | Active. Lint-time enforcement of the canonical `withTracing → withRetry → withRateLimit → withCostLimit → withCostTracking → withFallback → withRedaction` ordering. |
+| `no-implicit-network-call` | Active. Flags bare `fetch(...)` / `axios.get(...)` / `https.request(...)` / `new XMLHttpRequest()` invocations in `@graphorin/*` framework code without the explicit `// graphorin-allow-network: <reason>` opt-out. |
+| `no-third-party-workflow-aliases` | Active. Flags identifiers that mirror third-party-library workflow primitives in the `@graphorin/workflow` package's source so the framework keeps its own naming. |
+| `no-bare-tool-exec` | Active. Flags `tool({ execute })` functions that do not reference `signal` so long-running tools always propagate the cancellation contract. |
+| `no-console-in-public-api` | Scaffold (no-op). Will flag `console.*` calls in code that is part of a package's public surface; activates after the v0.1 public-API freeze. |
+
+## Programmatic discovery (single source of truth)
+
+The three `tool-*` rules are also exposed as plain helpers so `graphorin tools lint` reuses the same logic without re-importing through the ESLint runtime:
+
+```ts
+import {
+  AMBIGUOUS_PARAMETER_NAMES,
+  discoverToolCallsInSource,
+  gradeTool,
+  PARAMETER_NAMING_OPT_OUT_TAGS,
+  PLACEHOLDER_DESCRIPTIONS,
+  runToolRules,
+} from '@graphorin/eslint-plugin';
+
+const source = await readFile('src/tools/send-email.ts', 'utf8');
+const tools = discoverToolCallsInSource('src/tools/send-email.ts', source);
+for (const tool of tools) {
+  const findings = runToolRules(tool);
+  const score = gradeTool(tool, findings);
+  console.log(`${tool.name}: ${score.score}/100`);
+}
+```
+
+## Versioning
+
+`@graphorin/eslint-plugin` follows the same lockstep release as the rest of the `@graphorin/*` packages while the framework is on the `0.x` line. Once Graphorin reaches `1.0`, the plugin will move to its own release cadence.
+
+---
+
+**Graphorin** · v0.5.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -0,0 +1,249 @@
+import * as eslint0 from "eslint";
+
+//#region src/tool-discovery.d.ts
+
+/**
+ * Static `tool({...})` discovery + per-tool grader. Used by both the
+ * three `tool-*` ESLint rules and by the `graphorin tools lint` CLI
+ * subcommand (Phase 15) so the rule logic has a single source of
+ * truth (per the working plan acceptance criteria for RB-49).
+ *
+ * The discovery is intentionally text-based — it scans a source
+ * string for `tool(` call expressions and extracts the immediate
+ * object literal that follows. The extractor handles the common
+ * formatting cases (single-line, multi-line, nested object/array
+ * literals, single + double-quoted strings, template literals) and
+ * gracefully skips invocations whose argument shape it cannot
+ * parse statically. The trade-off is documented: a project that
+ * hides its `tool({...})` calls behind a builder helper or a
+ * dynamic import will not be picked up by this lint surface; that
+ * is the documented contract for the v0.1 lint surface.
+ *
+ * **Per-tool grader rubric (RB-49 calibration):**
+ *
+ *   - **description axis (0..40 points):**
+ *     - 0 if missing / placeholder / shorter than 20 chars.
+ *     - 16 if length >= 20.
+ *     - 24 if length >= 30.
+ *     - 32 if length >= 50.
+ *     - 40 if length >= 80.
+ *   - **examples axis (0..30 points):**
+ *     - 0 if no examples or more than 5 (the documented upper bound).
+ *     - 12 base for 1 example, +6 per additional, capped at 30.
+ *     - -6 per PII finding (cap at 0).
+ *   - **parameter naming axis (0..30 points):**
+ *     - 30 base, deducted per finding.
+ *     - -30/N per ambiguous-name finding (full penalty per param).
+ *     - -10/N per numeric-suffix finding (partial penalty per param).
+ *     - 15 baseline when no parameters are discoverable.
+ *
+ *   Total: 0..100 points. Calibrated against the RB-49 fixture
+ *   catalog so `wellDescribedTool` scores 82, `placeholderDescriptionTool`
+ *   scores 20, and `examplesPiiTool` scores 61.
+ *
+ * @stable
+ */
+/**
+ * @stable
+ */
+interface DiscoveredTool {
+  /** Source file the call was found in. */
+  readonly file: string;
+  /** 1-indexed line of the `tool(` token. */
+  readonly line: number;
+  /** Tool name extracted from the `name:` property when present. */
+  readonly name: string;
+  /** Tool description (`description:` value) when extractable. */
+  readonly description?: string;
+  /** Number of examples declared in the `examples:` array. */
+  readonly examplesCount: number;
+  /** Whether `examples:` is a non-empty array literal. */
+  readonly hasExamples: boolean;
+  /** Snapshot of identifiers referenced from the `inputSchema` Zod chain. */
+  readonly parameterNames: ReadonlyArray<string>;
+  /** Tags declared on the call (best-effort). */
+  readonly tags: ReadonlyArray<string>;
+  /**
+   * Raw object-literal source. Useful for tests + as a context blob
+   * when the CLI needs to surface the original source in a report.
+   */
+  readonly source: string;
+}
+/**
+ * @stable
+ */
+type LintFindingKind = 'description-missing' | 'description-too-short' | 'description-placeholder' | 'examples-missing' | 'examples-too-many' | 'examples-pii-detected' | 'parameter-ambiguous' | 'parameter-numeric-suffix';
+/**
+ * @stable
+ */
+interface LintFinding {
+  readonly rule: 'graphorin/tool-description-required' | 'graphorin/tool-examples-recommended' | 'graphorin/tool-parameter-naming';
+  readonly kind: LintFindingKind;
+  readonly severity: 'error' | 'warn' | 'info';
+  readonly message: string;
+  readonly toolName: string;
+  readonly file: string;
+  readonly line: number;
+  readonly hint?: string;
+  /**
+   * Optional matched-pattern context. Populated by the
+   * `examples-pii-detected` finding so reports can highlight which
+   * example payload triggered the rule.
+   */
+  readonly matchedPattern?: string;
+}
+/**
+ * @stable
+ */
+interface ToolGraderScore {
+  readonly toolName: string;
+  readonly file: string;
+  readonly line: number;
+  readonly score: number;
+  readonly axes: {
+    readonly description: number;
+    readonly examples: number;
+    readonly parameterNaming: number;
+  };
+  readonly findings: ReadonlyArray<LintFinding>;
+}
+/**
+ * Generic identifiers the parameter-naming rule flags as ambiguous.
+ * Tools whose `inputSchema` references only specific identifiers
+ * (e.g. `userId`, `recipientEmail`, `apiKey`) get full credit on
+ * the naming axis.
+ *
+ * @stable
+ */
+declare const AMBIGUOUS_PARAMETER_NAMES: ReadonlyArray<string>;
+/**
+ * Tag values that, when present in a tool's `tags: [...]` literal,
+ * suppress the parameter-naming rule for that tool. The opt-out
+ * exists so operators can defer the rename for a long tail of
+ * pre-RB-49 tools while the framework migrates without breaking
+ * calling code.
+ *
+ * @stable
+ */
+declare const PARAMETER_NAMING_OPT_OUT_TAGS: ReadonlyArray<string>;
+/**
+ * Placeholder values the description-required rule treats as
+ * non-descriptions.
+ *
+ * @stable
+ */
+declare const PLACEHOLDER_DESCRIPTIONS: ReadonlyArray<string>;
+/**
+ * Discover every `tool({...})` invocation in a source string. The
+ * returned findings are stable + frozen so callers can pass them
+ * straight into a JSON report.
+ *
+ * @stable
+ */
+declare function discoverToolCallsInSource(file: string, source: string): DiscoveredTool[];
+/**
+ * Run the three RB-49 rules against a discovered tool and return the
+ * findings. The CLI grader maps these findings into per-axis scores;
+ * the ESLint rules forward them to `context.report(...)`.
+ *
+ * @stable
+ */
+declare function runToolRules(tool: DiscoveredTool, severityOverrides?: {
+  readonly toolDescription?: 'error' | 'warn' | 'off';
+  readonly toolExamples?: 'error' | 'warn' | 'off';
+  readonly toolParameterNaming?: 'error' | 'warn' | 'off';
+}): LintFinding[];
+/**
+ * Compute the per-tool grader score (0..100). Each axis is gated by
+ * the findings produced for that axis. The rubric is calibrated
+ * against the RB-49 fixture catalog (`wellDescribedTool` -> 82,
+ * `placeholderDescriptionTool` -> 20, `examplesPiiTool` -> 61).
+ *
+ * @stable
+ */
+declare function gradeTool(tool: DiscoveredTool, findings: ReadonlyArray<LintFinding>): ToolGraderScore;
+//#endregion
+//#region src/index.d.ts
+/**
+ * @graphorin/eslint-plugin — ESLint plugin for projects that build on
+ * the Graphorin framework.
+ *
+ * Phase 16 final ruleset:
+ *
+ *   - `no-secret-unwrap`                  — DEC-020 / ADR-026. Active.
+ *   - `no-secret-in-deps`                 — DEC-137. Active.
+ *   - `provider-middleware-order`         — DEC-145 / ADR-039. Active.
+ *   - `no-implicit-network-call`          — DEC-154 / ADR-041. Active.
+ *   - `no-third-party-workflow-aliases`   — DEC-019 / ADR-029. Active.
+ *   - `no-bare-tool-exec`                 — principle 3 / DEC-143. Active.
+ *   - `tool-description-required`         — Active.
+ *   - `tool-examples-recommended`         — Active.
+ *   - `tool-parameter-naming`             — Active.
+ *
+ * (The former `no-console-in-public-api` scaffold — a permanent no-op
+ * since Phase 01 — was removed in the v0.4 hygiene pass (PS-21) rather
+ * than shipped inert.)
+ *
+ * @packageDocumentation
+ */
+declare const VERSION = "0.5.0";
+declare const meta: {
+  readonly name: "@graphorin/eslint-plugin";
+  readonly version: "0.5.0";
+};
+declare const rules: {
+  readonly 'no-bare-tool-exec': eslint0.Rule.RuleModule;
+  readonly 'no-implicit-network-call': eslint0.Rule.RuleModule;
+  readonly 'no-secret-in-deps': eslint0.Rule.RuleModule;
+  readonly 'no-secret-unwrap': eslint0.Rule.RuleModule;
+  readonly 'no-third-party-workflow-aliases': eslint0.Rule.RuleModule;
+  readonly 'provider-middleware-order': eslint0.Rule.RuleModule;
+  readonly 'tool-description-required': eslint0.Rule.RuleModule;
+  readonly 'tool-examples-recommended': eslint0.Rule.RuleModule;
+  readonly 'tool-parameter-naming': eslint0.Rule.RuleModule;
+};
+/** Shared severity map for both the legacy and flat recommended presets. */
+declare const RECOMMENDED_RULES: {
+  readonly '@graphorin/no-bare-tool-exec': "warn";
+  readonly '@graphorin/no-implicit-network-call': "error";
+  readonly '@graphorin/no-secret-in-deps': "error";
+  readonly '@graphorin/no-secret-unwrap': "error";
+  readonly '@graphorin/no-third-party-workflow-aliases': "error";
+  readonly '@graphorin/provider-middleware-order': "error";
+  readonly '@graphorin/tool-description-required': "error";
+  readonly '@graphorin/tool-examples-recommended': "warn";
+  readonly '@graphorin/tool-parameter-naming': "warn";
+};
+/**
+ * PS-17: ship BOTH config shapes. `recommended` is the legacy `.eslintrc` form
+ * (`plugins: ['@graphorin']`); `flat/recommended` is the ESLint 9+ flat-config
+ * form that maps the namespace to the plugin object, so flat-config consumers
+ * can `...plugin.configs['flat/recommended']` instead of hand-wiring ten rules.
+ */
+declare const plugin: {
+  readonly meta: typeof meta;
+  readonly rules: typeof rules;
+  readonly configs: {
+    readonly recommended: {
+      readonly plugins: readonly string[];
+      readonly rules: typeof RECOMMENDED_RULES;
+    };
+    readonly 'flat/recommended': {
+      plugins: Record<string, unknown>;
+      readonly rules: typeof RECOMMENDED_RULES;
+    };
+  };
+};
+declare const configs: {
+  readonly recommended: {
+    readonly plugins: readonly string[];
+    readonly rules: typeof RECOMMENDED_RULES;
+  };
+  readonly 'flat/recommended': {
+    plugins: Record<string, unknown>;
+    readonly rules: typeof RECOMMENDED_RULES;
+  };
+};
+//#endregion
+export { AMBIGUOUS_PARAMETER_NAMES, type DiscoveredTool, type LintFinding, type LintFindingKind, PARAMETER_NAMING_OPT_OUT_TAGS, PLACEHOLDER_DESCRIPTIONS, type ToolGraderScore, VERSION, configs, plugin as default, discoverToolCallsInSource, gradeTool, meta, rules, runToolRules };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/tool-discovery.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AA6CA;AA2BA;AAaA;AAuBA;AAqBA;AAwBA;AAWA;AAkBA;AAgCA;AAkIA;;;;;;;;;ACvTA;AAEA;AAKA;;;;;;;;;;;AAUW;AAaD;;;;;;;AAiCV;;AAhBe,UDnCE,cAAA,CCmCF;EACc;EAAiB,SAAA,IAAA,EAAA,MAAA;;;;;;;;;;;;2BDtBnB;;iBAEV;;;;;;;;;;KAWL,eAAA;;;;UAaK,WAAA;;iBAKA;;;;;;;;;;;;;;;;;UAkBA,eAAA;;;;;;;;;;qBAUI,cAAc;;;;;;;;;;cAWtB,2BAA2B;;;;;;;;;;cAwB3B,+BAA+B;;;;;;;cAW/B,0BAA0B;;;;;;;;iBAkBvB,yBAAA,gCAAyD;;;;;;;;iBAgCzD,YAAA,OACR;;;;IAML;;;;;;;;;iBA2Ha,SAAA,OACR,0BACI,cAAc,eACvB;;;;;;AA9SH;AA2BA;AAaA;AAuBA;AAqBA;AAwBA;AAWA;AAkBA;AAgCA;AAkIA;;;;;;;;;ACvTA;AAEa,cAFA,OAAA,GAKH,OAAA;AAEG,cALA,IAeH,EAAA;;;;cAVG;;;;;;;EAaP,SAAA,2BAUI,yBAAA;EAQJ,SAsBL,2BAAA,yBAAA;EArBuB,SAAA,uBAAA,yBAAA;CACC;;cApBnB,iBA2BS,EAAA;EACc,SAAA,8BAAA,EAAA,MAAA;EAAiB,SAAA,qCAAA,EAAA,OAAA;EAejC,SAAA,8BAAwB,EAAA,OAAA;EAnBR,SAAA,6BAAA,EAAA,OAAA;EAGd,SAAA,4CAAA,EAAA,OAAA;EACc,SAAA,sCAAA,EAAA,OAAA;EAAiB,SAAA,sCAAA,EAAA,OAAA;;;;;;;;;;cAVxC;wBACkB;yBACC;;;;6BAII;;;eAGd;6BACc;;;;cAehB;;;2BAnBgB;;;aAGd;2BACc"}