@graphorin/eslint-plugin 0.6.1 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @graphorin/eslint-plugin
 
+## 0.7.0
+
+### Minor Changes
+
+- [#154](https://github.com/o-stepper/graphorin/pull/154) [`fe98522`](https://github.com/o-stepper/graphorin/commit/fe98522ce2477c9a7dc09029f9dcfdb1f7c9aa04) Thanks [@o-stepper](https://github.com/o-stepper)! - W-072: every export map's `import` condition becomes `default`, and the Node floor rises to `>=22.12.0`.
+
+  CJS consumers previously hit a bewildering `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of a clear ESM-only signal. With the `default` condition, plain `require('@graphorin/core')` works via Node's stable `require(esm)` - which shipped in 22.12, hence the engines bump across every workspace manifest (packages, examples, benchmarks, docs; enforced by the widened mvp-readiness sweep). No dual-instance hazard: there is no CJS build, `require()` returns the same ESM module instance. ESM consumers are unaffected (`default` serves both paths; `types` stays first). The pack gate now runs attw under the full `node16` profile (was `esm-only`) and adds a runtime `require(esm)` smoke against the packed tarballs. Installs on Node 22.0-22.11 with `engine-strict` will refuse - upgrade Node (see the migration guide).
+
+- [#162](https://github.com/o-stepper/graphorin/pull/162) [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3) Thanks [@o-stepper](https://github.com/o-stepper)! - `no-implicit-network-call` now activates in two stages: the linted file path must match `packages/*/src` AND the nearest `package.json` name must start with a prefix from the new `packagePrefixes` option (default `['@graphorin/']`). Downstream pnpm monorepos with the standard layout stop getting errors on their own `fetch()` calls just for adopting `flat/recommended`; a consumer that wants the rule to police their own scope passes `['error', { packagePrefixes: ['@myorg/'] }]`. When no package.json resolves above the file (virtual paths, programmatic Linter runs) the rule fails OPEN to the old path-only activation, so resolution hiccups can only over-flag, never silently disable the guard. The rule is now also dogfooded against the framework's own source in tests (sharing the check-no-network ALLOW_LIST as the single source of exemptions), and a lockstep contract test pins both matchers' verdicts over a shared corpus - closing the known axios asymmetry (the CI script now flags `axios(...)`/`axios.get(...)` call sites, not just imports).
+
+- [#158](https://github.com/o-stepper/graphorin/pull/158) [`32bbd03`](https://github.com/o-stepper/graphorin/commit/32bbd03b588136a355e4b5ad6ac5e19b36b4d8ab) Thanks [@o-stepper](https://github.com/o-stepper)! - Tool discovery and grading are comment-aware (W-044). Discovery and every grading path run over a comment-blanked view of the source (newlines preserved, offsets stable; string/template and - conservatively - regex literals untouched): a commented-out `tool({...})` no longer appears in `graphorin tools lint` reports or the three ESLint tool rules, a commented-out property inside a live literal is never extracted, a commented email inside a live `examples:` block no longer penalizes the axis, and a `tool(` inside a string never matches. `DiscoveredTool` gains `gradingSource` (the blanked slice all graders consume) while `source` keeps the original text for reports. The description axis gets a deterministic anti-degenerate guard: 80+ chars of repeated filler (under 4 unique words, or one word over half the text) caps at 16 instead of scoring 40 - RB-49 calibration fixtures are unchanged; degenerate descriptions may now fall below `--threshold` gates. The false-positive contract (any callee lexically ending in `tool(`, renamed/wrapped calls invisible) is now documented in the module header and README.
+
+### Patch Changes
+
+- [#162](https://github.com/o-stepper/graphorin/pull/162) [`73b19ca`](https://github.com/o-stepper/graphorin/commit/73b19caeda388bda628a48138cb7d70b1db839a3) Thanks [@o-stepper](https://github.com/o-stepper)! - `no-secret-unwrap` gains an opt-in `allowReceiverPattern` option for the documented collision with Zod's `.unwrap()` (ZodOptional/ZodNullable/ZodDefault) and Rust-style result libraries: when the source text of the receiver expression matches the pattern, both `unwrap` and `reveal` reports are skipped, so `['error', { allowReceiverPattern: 'Schema$' }]` lets schema-introspection code lint clean while `secret.unwrap()` keeps erroring. Default behaviour is byte-identical (no pattern, sharp deprecation cliff), and there is deliberately no built-in "looks like Zod" heuristic - an explicit narrow pattern or a file-glob override beats a nondeterministic guess. README documents both recipes.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Tarballs now ship `src/` so the published `dist/**/*.d.ts.map` files actually work (W-136): the maps referenced `../src/*.ts` that the `files` whitelist excluded, so go-to-definition fell back into `.d.ts` and the shipped maps were dead weight. The pack gate gains a `map-integrity` leg: every source referenced by a shipped map must resolve inside the tarball (or be embedded via `sourcesContent`), with an anti-vacuous guard - a package whose tsdown config emits declaration maps must contain a non-zero number of `.d.ts.map` files, so a cache-restored dist that silently dropped maps fails the gate instead of passing vacuously. `mvp-readiness` now requires `src` in every publishable `files` array.
+
+- [#164](https://github.com/o-stepper/graphorin/pull/164) [`764239b`](https://github.com/o-stepper/graphorin/commit/764239b97e0e0202442e91272583f13adeb12d00) Thanks [@o-stepper](https://github.com/o-stepper)! - Every published package now declares its tree-shaking contract via `sideEffects` (W-137): 18 packages audited to a pure module scope get `false`, the CLI declares its bin entry (`["./dist/bin/*"]`), and `@graphorin/security` gets an explicit `true` - its secrets subsystem registers built-in resolvers and the SecretValue caller-context provider at import time, so marking it pure would let bundlers drop those registrations. `mvp-readiness` now fails any publishable manifest without a declared `sideEffects`, closing the drift for future packages.
+
 ## 0.6.1
 
 ### Patch Changes

package/README.md

@@ -2,7 +2,7 @@
 
 > ESLint rules for projects that build on **Graphorin**.
 
-- **Status:** v0.6.1 - final Phase 16 ruleset.
+- **Status:** v0.7.0 - final Phase 16 ruleset.
 - **License:** [MIT](./LICENSE) - © 2026 Oleksiy Stepurenko.
 - **Engines:** Node.js 22+ (ESM only).
 - **Peer dependency:** `eslint >= 9`.
@@ -58,10 +58,10 @@ The legacy `.eslintrc` form is still exported as `configs.recommended`
 | `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-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. Known collision: Zod's `ZodOptional`/`ZodNullable`/`ZodDefault` `.unwrap()` (and Rust-style result libraries) false-positive - either turn the rule off for introspection files (`{ files: ['**/schema-introspection/**'], rules: { '@graphorin/no-secret-unwrap': 'off' } }`) or set the carve-out option `['error', { allowReceiverPattern: 'Schema$' }]`, which skips receivers whose source text matches. Pick a NARROW suffix pattern (a broad regex would silence real `SecretValue.unwrap` calls); prefer the file-glob override when the collision is confined to a directory. |
 | `no-secret-in-deps` | Active. Flags `withChildToolSecretsContext({ secretsAllowed: [...] })` grants whose allowlist is non-empty and lacks an `// rb-24-justification: <reason>` comment (DEC-137). |
 | `provider-middleware-order` | Active. Lint-time enforcement of the canonical `withTracing → withRetry → withRateLimit → withCostLimit → withCostTracking → withFallback → withRedaction` ordering. |
-| `no-implicit-network-call` | Active. Flags network primitives in `@graphorin/*` framework code without the explicit `// graphorin-allow-network: <reason>` opt-out: `fetch(...)` / `axios.*` / `undici.*` / `got.*` / `http(s).request` / raw `net`·`tls`·`dgram` sockets / `new WebSocket` / `new EventSource` / `new XMLHttpRequest`, plus static, dynamic, and `require()` imports of HTTP clients (`node-fetch`, `undici`, `got`, `axios`, `ky`, `ws`). Kept in lockstep with `scripts/check-no-network.mjs`. |
+| `no-implicit-network-call` | Active. Flags network primitives in framework code without the explicit `// graphorin-allow-network: <reason>` opt-out: `fetch(...)` / `axios.*` / `undici.*` / `got.*` / `http(s).request` / raw `net`·`tls`·`dgram` sockets / `new WebSocket` / `new EventSource` / `new XMLHttpRequest`, plus static, dynamic, and `require()` imports of HTTP clients (`node-fetch`, `undici`, `got`, `axios`, `ky`, `ws`). Activation is two-stage (W-039): the file path must match `packages/*/src` AND the nearest `package.json` name must start with a prefix from `packagePrefixes` (default `['@graphorin/']`), so a downstream monorepo with the standard layout is not flagged; when no package.json resolves (virtual paths), the rule FAILS OPEN to path-only activation. Polices your own scope via `'@graphorin/no-implicit-network-call': ['error', { packagePrefixes: ['@myorg/'] }]`. Kept in lockstep with `scripts/check-no-network.mjs` (contract-tested). |
 | `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. |
 
@@ -88,10 +88,18 @@ for (const tool of tools) {
 }
 ```
 
+### Discovery contract (W-044)
+
+The discovery is **text-based by design** (one implementation serves both the CLI and the ESLint rules). Its contract:
+
+- **Comment-aware.** Discovery and grading run over a comment-blanked view of the source: a commented-out `tool({...})` is never discovered, a commented-out property inside a live literal is never extracted, and a commented email inside a live `examples:` block never penalizes the axis. `DiscoveredTool.source` keeps the original text for reports; grading consumes `DiscoveredTool.gradingSource`. String, template, and (conservatively) regex literals are left untouched, and a `tool(` inside a string never matches.
+- **False positives.** Any callee whose last lexical token is `tool(` matches - including method calls like `.tool(` and same-named local helpers. Renamed or wrapped invocations (`const t = tool; t({...})`) are NOT seen. This is the accepted cost of the text-based surface.
+- **Anti-degenerate description guard.** A description of 80+ chars scores the top tier only if it looks like prose: under 4 unique words, or one word carrying more than half the text, caps the axis at 16.
+
 ## 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.6.1 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>
+**Graphorin** · v0.7.0 · MIT License · © 2026 Oleksiy Stepurenko · <https://github.com/o-stepper/graphorin>

package/dist/index.d.ts

@@ -19,6 +19,24 @@ import * as eslint0 from "eslint";
  * dynamic import will not be picked up by this lint surface; that
  * is the documented contract for the v0.1 lint surface.
  *
+ * **Comment-awareness (W-044).** Discovery AND grading run over a
+ * comment-blanked view of the source: line-comment and block-comment
+ * content is replaced with spaces (newlines preserved, so line numbers
+ * and offsets never shift) while string/template literals - and,
+ * conservatively, regex literals - are left untouched. A
+ * commented-out `tool({...})` is therefore never discovered, and a
+ * commented-out property (or a commented email inside a live
+ * `examples:` block) never feeds the grader. The ORIGINAL slice stays
+ * available as {@link DiscoveredTool.source} for reports; grading
+ * paths consume {@link DiscoveredTool.gradingSource}.
+ *
+ * **False-positive contract.** The scanner matches ANY callee whose
+ * last lexical token is `tool(` - including method calls like
+ * `.tool(` and locally-defined helpers that happen to share the name.
+ * Renamed or wrapped invocations (`const t = tool; t({...})`) are NOT
+ * seen. This is the accepted cost of the text-based surface that lets
+ * the CLI and the ESLint rules share one implementation (RB-49).
+ *
  * **Per-tool grader rubric (RB-49 calibration):**
  *
  *   - **description axis (0..40 points):**
@@ -64,10 +82,18 @@ interface DiscoveredTool {
   /** 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.
+   * Raw object-literal source (ORIGINAL text, comments included).
+   * Useful for tests + as a context blob when the CLI needs to
+   * surface the original source in a report.
    */
   readonly source: string;
+  /**
+   * W-044: the same slice with comments blanked - what discovery
+   * parsed and what every grading path (examples PII scan,
+   * description/parameter scoring) consumes. Same length and line
+   * structure as `source`.
+   */
+  readonly gradingSource: string;
 }
 /**
  * @stable

package/dist/index.d.ts.map

@@ -1 +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;;;;;;;;;ACtTA;AAEA;AAKA;;;;;;;;;;;AAUW;AAaD;;;;;;;AAiCV;;AAhBe,UDpCE,cAAA,CCoCF;EACc;EAAiB,SAAA,IAAA,EAAA,MAAA;;;;;;;;;;;;2BDvBnB;;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;;;;;;;;;ACtTA;AAEa,cAFA,OAKH,EAAA,MAAA;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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/tool-discovery.ts","../src/index.ts"],"sourcesContent":[],"mappings":";;;;;;;AA+DA;AAmCA;AAaA;AAuBA;AAqBA;AAwBA;AAWA;AAkBA;AAoKA;AAoIA;;;;;;;;;ACtdA;AAEA;AAKA;;;;;;;;;;;AAUW;AAaD;;;;;;;AAiCV;;;;;;;;;;;;;;;;;;;;UDlCiB,cAAA;;;;;;;;;;;;;;2BAcU;;iBAEV;;;;;;;;;;;;;;;;;;KAmBL,eAAA;;;;UAaK,WAAA;;iBAKA;;;;;;;;;;;;;;;;;UAkBA,eAAA;;;;;;;;;;qBAUI,cAAc;;;;;;;;;;cAWtB,2BAA2B;;;;;;;;;;cAwB3B,+BAA+B;;;;;;;cAW/B,0BAA0B;;;;;;;;iBAkBvB,yBAAA,gCAAyD;;;;;;;;iBAoKzD,YAAA,OACR;;;;IAML;;;;;;;;;iBA6Ha,SAAA,OACR,0BACI,cAAc,eACvB;;;;;;AA5bH;AAmCA;AAaA;AAuBA;AAqBA;AAwBA;AAWA;AAkBA;AAoKA;AAoIA;;;;;;;;;ACtdA;AAEa,cAFA,OAKH,EAAA,MAAA;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"}

package/dist/index.js

@@ -1,5 +1,8 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
 //#region package.json
-var version = "0.6.1";
+var version = "0.7.0";
 
 //#endregion
 //#region src/rules/_comment-utils.ts
@@ -97,8 +100,72 @@ var no_bare_tool_exec_default = rule$8;
 
 //#endregion
 //#region src/rules/no-implicit-network-call.ts
+/**
+* Rule: `@graphorin/no-implicit-network-call` (DEC-154 / ADR-041).
+* Flags any direct network primitive in code under a `@graphorin/*`
+* package's `src/` directory unless the call site carries an opt-out
+* comment whose text contains `'graphorin-allow-network'`:
+*
+* - calls: `fetch(...)`, `http(s).request/get(...)`, `axios(...)` /
+*   `axios.<verb>(...)`, `undici.<verb>(...)` / `got.<verb>(...)`,
+*   `net.createConnection/connect(...)`, `tls.connect(...)`,
+*   `dgram.createSocket(...)`
+* - constructors: `new XMLHttpRequest()`, `new WebSocket(...)`,
+*   `new EventSource(...)`
+* - imports of HTTP clients: `node-fetch`, `undici`, `got`, `axios`,
+*   `ky`, `ws` (static, dynamic `import(...)`, and `require(...)`)
+*
+* Companion to the `pnpm run check-no-network` static analysis script;
+* the two matchers are kept in lockstep (this rule mirrors the EB-10
+* hardening that taught the script about undici/got, raw sockets,
+* WebSocket/EventSource, and HTTP-client import specifiers). The lint
+* surface catches the pattern at author time so reviewers do not need
+* to wait for CI to flag a missed network gate.
+*
+* The rule is intentionally limited to the framework's own code paths
+* - consumer applications can call `fetch` freely. Activation is
+* two-stage (W-039): the linted file path must match
+* `/packages/<pkg>/src/` AND the nearest package.json's `name` must
+* start with one of `options[0].packagePrefixes` (default
+* `['@graphorin/']`), so a downstream pnpm monorepo with the standard
+* `packages/*\/src` layout no longer gets errors on its own `fetch()`
+* calls just for adopting `flat/recommended`.
+*
+* FAIL-OPEN fallback: when no package.json resolves above the file
+* (virtual paths in editor buffers or programmatic `Linter` runs), the
+* rule activates on the path match alone - exactly the pre-W-039
+* behaviour, so a resolution hiccup can only over-flag framework-shaped
+* paths, never silently disable the guard.
+*
+* @packageDocumentation
+*/
 const ALLOW_TAG$2 = /graphorin-allow-network/;
 const FRAMEWORK_PATH_RE = /\bpackages\/[a-z0-9_-]+\/src\b/;
+/**
+* Directory -> nearest package.json `name` (or null when none
+* resolves). Module-level so one walk serves every file of a package
+* within a lint run.
+*/
+const packageNameCache = /* @__PURE__ */ new Map();
+/** Walk up from `fileDir` to the nearest package.json name (cached). */
+function nearestPackageName(fileDir) {
+	const cached = packageNameCache.get(fileDir);
+	if (cached !== void 0) return cached;
+	let name = null;
+	let dir = fileDir;
+	for (;;) try {
+		const raw = readFileSync(join(dir, "package.json"), "utf8");
+		const parsed = JSON.parse(raw);
+		name = typeof parsed.name === "string" ? parsed.name : null;
+		break;
+	} catch {
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	packageNameCache.set(fileDir, name);
+	return name;
+}
 const NETWORK_CALLEES = new Set(["fetch", "XMLHttpRequest"]);
 const HTTP_VERBS = new Set([
 	"get",
@@ -137,14 +204,25 @@ const rule$7 = {
 			description: "Disallow direct network primitives (`fetch`, `axios`/`undici`/`got`, `http.request`, raw `net`/`tls`/`dgram` sockets, `WebSocket`/`EventSource`/`XMLHttpRequest`, HTTP-client imports) in `@graphorin/*` framework code without an explicit opt-out comment (DEC-154).",
 			recommended: true
 		},
-		schema: [],
+		schema: [{
+			type: "object",
+			properties: { packagePrefixes: {
+				type: "array",
+				items: { type: "string" }
+			} },
+			additionalProperties: false
+		}],
 		messages: {
 			forbidden: "direct network call '{{callee}}' in framework code; user actions must initiate network I/O. Add `// graphorin-allow-network: <reason>` to opt out.",
 			forbiddenImport: "HTTP-client import '{{specifier}}' in framework code; user actions must initiate network I/O. Add `// graphorin-allow-network: <reason>` to opt out."
 		}
 	},
 	create(context) {
-		if (!FRAMEWORK_PATH_RE.test(context.filename.replace(/\\/g, "/"))) return {};
+		const filename = context.filename.replace(/\\/g, "/");
+		if (!FRAMEWORK_PATH_RE.test(filename)) return {};
+		const prefixes = (context.options?.[0] ?? {}).packagePrefixes ?? ["@graphorin/"];
+		const packageName = nearestPackageName(dirname(context.filename));
+		if (packageName !== null && !prefixes.some((p) => packageName.startsWith(p))) return {};
 		return {
 			CallExpression(node) {
 				const specifier = requiredClientSpecifier(node);
@@ -309,13 +387,19 @@ const rule$5 = {
 			description: "Disallow `.unwrap()` / `.reveal()` calls on `SecretValue` instances. Prefer `.use(fn)` (scoped) or attach a `// graphorin-allow-secret-unwrap: <reason>` opt-out comment for `.reveal()`.",
 			recommended: true
 		},
-		schema: [],
+		schema: [{
+			type: "object",
+			properties: { allowReceiverPattern: { type: "string" } },
+			additionalProperties: false
+		}],
 		messages: {
 			avoidReveal: "`.reveal()` returns the unwrapped secret as a V8 string. Prefer `.use(fn)` so the value is scoped to a single callback. Add `// graphorin-allow-secret-unwrap: <reason>` to opt out.",
 			avoidUnwrap: "`.unwrap()` is deprecated - call `.reveal()` (audited) or `.use(fn)` (scoped). The opt-out comment is intentionally NOT honoured for `.unwrap()` so the deprecation stays sharp."
 		}
 	},
 	create(context) {
+		const options = context.options?.[0] ?? {};
+		const allowReceiver = options.allowReceiverPattern !== void 0 ? new RegExp(options.allowReceiverPattern) : null;
 		return { CallExpression(node) {
 			const callee = node.callee;
 			if (callee.type !== "MemberExpression") return;
@@ -323,6 +407,8 @@ const rule$5 = {
 			if (me.computed) return;
 			if (me.property.type !== "Identifier") return;
 			const propName = me.property.name;
+			if (propName !== "unwrap" && propName !== "reveal") return;
+			if (allowReceiver?.test(context.sourceCode.getText(me.object)) === true) return;
 			if (propName === "unwrap") {
 				context.report({
 					node,
@@ -548,21 +634,138 @@ const MAX_EXAMPLES$1 = 5;
 */
 function discoverToolCallsInSource(file, source) {
 	const out = [];
+	const blanked = blankComments(source);
+	const searchable = blankStringContents(blanked);
 	const regex = /\btool\s*\(\s*\{/g;
-	let match = regex.exec(source);
+	let match = regex.exec(searchable);
 	while (match !== null) {
 		const objectStart = match.index + match[0].length - 1;
-		const objectEnd = matchBrace(source, objectStart);
+		const objectEnd = matchBrace(blanked, objectStart);
 		if (objectEnd > 0) {
 			const literal = source.slice(objectStart, objectEnd + 1);
-			const tool = parseToolLiteral(file, countLines(source, match.index), literal);
+			const gradingLiteral = blanked.slice(objectStart, objectEnd + 1);
+			const tool = parseToolLiteral(file, countLines(source, match.index), literal, gradingLiteral);
 			if (tool !== null) out.push(tool);
 		}
 		regex.lastIndex = objectEnd + 1;
-		match = regex.exec(source);
+		match = regex.exec(searchable);
 	}
 	return out;
 }
+/**
+* W-044: blank the CONTENTS of string/template literals (quotes kept,
+* newlines preserved) so the discovery regex cannot match `tool(`
+* inside prose. Used only for SEARCHING - parsing reads the
+* strings-intact view.
+*/
+function blankStringContents(source) {
+	const out = source.split("");
+	let inString = null;
+	let i = 0;
+	while (i < source.length) {
+		const ch = source[i];
+		if (inString !== null) {
+			if (ch === "\\") {
+				out[i] = " ";
+				if (i + 1 < source.length && source[i + 1] !== "\n") out[i + 1] = " ";
+				i += 2;
+				continue;
+			}
+			if (ch === inString) {
+				inString = null;
+				i += 1;
+				continue;
+			}
+			if (ch !== "\n") out[i] = " ";
+			i += 1;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") inString = ch;
+		i += 1;
+	}
+	return out.join("");
+}
+/**
+* W-044: replace line-comment and block-comment CONTENT with spaces
+* while preserving every newline (offsets and 1-indexed lines never
+* shift).
+* String and template literals pass through untouched; regex literals
+* are tracked with the classic prev-significant-token heuristic so a
+* `/` inside one is never mistaken for a comment opener - when in
+* doubt the scanner does NOT blank.
+*
+* @stable
+*/
+function blankComments(source) {
+	const out = source.split("");
+	let inString = null;
+	let prevSignificant = "";
+	let i = 0;
+	const isRegexStartContext = () => prevSignificant === "" || "([{=,:;!&|?+-*%<>~^".includes(prevSignificant);
+	while (i < source.length) {
+		const ch = source[i];
+		if (inString !== null) {
+			if (ch === "\\") {
+				i += 2;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			i += 1;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			prevSignificant = ch;
+			i += 1;
+			continue;
+		}
+		if (ch === "/" && source[i + 1] === "/") {
+			while (i < source.length && source[i] !== "\n") {
+				out[i] = " ";
+				i += 1;
+			}
+			continue;
+		}
+		if (ch === "/" && source[i + 1] === "*") {
+			out[i] = " ";
+			out[i + 1] = " ";
+			i += 2;
+			while (i < source.length && !(source[i] === "*" && source[i + 1] === "/")) {
+				if (source[i] !== "\n") out[i] = " ";
+				i += 1;
+			}
+			if (i < source.length) {
+				out[i] = " ";
+				out[i + 1] = " ";
+				i += 2;
+			}
+			continue;
+		}
+		if (ch === "/" && isRegexStartContext()) {
+			let j = i + 1;
+			let inClass = false;
+			while (j < source.length && source[j] !== "\n") {
+				const cj = source[j];
+				if (cj === "\\") {
+					j += 2;
+					continue;
+				}
+				if (cj === "[") inClass = true;
+				else if (cj === "]") inClass = false;
+				else if (cj === "/" && !inClass) break;
+				j += 1;
+			}
+			if (j < source.length && source[j] === "/") {
+				prevSignificant = "/";
+				i = j + 1;
+				continue;
+			}
+		}
+		if (!/\s/.test(ch)) prevSignificant = ch;
+		i += 1;
+	}
+	return out.join("");
+}
 /** Email PII pattern used by the examples-pii sub-check. */
 const EMAIL_PATTERN = /[\w.+%-]+@[\w.-]+\.[A-Za-z]{2,}/;
 /** Numeric-suffix pattern used by the parameter-naming sub-check. */
@@ -587,7 +790,7 @@ function runToolRules(tool, severityOverrides) {
 	if (examplesSeverity !== "off") {
 		if (!tool.hasExamples || tool.examplesCount === 0) findings.push(finding("graphorin/tool-examples-recommended", "examples-missing", examplesSeverity, tool, `tool '${tool.name}' has no examples; add 1-5 worked examples per Anthropic 2026 guidance.`));
 		else if (tool.examplesCount > MAX_EXAMPLES$1) findings.push(finding("graphorin/tool-examples-recommended", "examples-too-many", "error", tool, `tool '${tool.name}' declares ${tool.examplesCount} examples; the upper bound is ${MAX_EXAMPLES$1}.`));
-		const emailMatch = EMAIL_PATTERN.exec(extractExamplesBlock(tool.source));
+		const emailMatch = EMAIL_PATTERN.exec(extractExamplesBlock(tool.gradingSource));
 		if (emailMatch !== null) {
 			const matched = emailMatch[0];
 			findings.push(finding("graphorin/tool-examples-recommended", "examples-pii-detected", "error", tool, `tool '${tool.name}' example contains a real-looking email '${matched}'; replace with synthetic data (e.g. 'user@example.com').`, {
@@ -635,11 +838,20 @@ function gradeTool(tool, findings) {
 function scoreDescription(tool, findings) {
 	if (findings.length > 0) return 0;
 	const desc = tool.description?.trim() ?? "";
-	if (desc.length >= 80) return 40;
-	if (desc.length >= 50) return 32;
-	if (desc.length >= 30) return 24;
-	if (desc.length >= MIN_DESCRIPTION_LENGTH$1) return 16;
-	return 0;
+	let lengthScore = 0;
+	if (desc.length >= 80) lengthScore = 40;
+	else if (desc.length >= 50) lengthScore = 32;
+	else if (desc.length >= 30) lengthScore = 24;
+	else if (desc.length >= MIN_DESCRIPTION_LENGTH$1) lengthScore = 16;
+	if (lengthScore > 16 && desc.length > 0) {
+		const words = desc.toLowerCase().split(/\s+/).filter((w) => w.length > 0);
+		const counts = /* @__PURE__ */ new Map();
+		for (const w of words) counts.set(w, (counts.get(w) ?? 0) + 1);
+		const unique = counts.size;
+		const topShare = words.length === 0 ? 0 : Math.max(...counts.values()) / words.length;
+		if (unique < 4 || topShare > .5) return 16;
+	}
+	return lengthScore;
 }
 function scoreExamples(tool, findings) {
 	if (tool.examplesCount === 0) return 0;
@@ -781,14 +993,14 @@ function extractParameterNames(literal) {
 	}
 	return names;
 }
-function parseToolLiteral(file, line, literal) {
-	const name = readStringProp(literal, "name") ?? "<anonymous>";
-	const description = readStringProp(literal, "description");
-	const examples = countArrayProp(literal, "examples");
-	const tagsArr = countArrayProp(literal, "tags");
+function parseToolLiteral(file, line, literal, gradingLiteral) {
+	const name = readStringProp(gradingLiteral, "name") ?? "<anonymous>";
+	const description = readStringProp(gradingLiteral, "description");
+	const examples = countArrayProp(gradingLiteral, "examples");
+	const tagsArr = countArrayProp(gradingLiteral, "tags");
 	const tags = [];
 	if (tagsArr.present && tagsArr.count > 0) {
-		const m = /tags\s*:\s*\[([^\]]*)\]/.exec(literal);
+		const m = /tags\s*:\s*\[([^\]]*)\]/.exec(gradingLiteral);
 		if (m !== null) {
 			const inner = m[1] ?? "";
 			const tagRegex = /['"`]([^'"`]+)['"`]/g;
@@ -799,7 +1011,7 @@ function parseToolLiteral(file, line, literal) {
 			}
 		}
 	}
-	const parameterNames = extractParameterNames(literal);
+	const parameterNames = extractParameterNames(gradingLiteral);
 	return Object.freeze({
 		file,
 		line,
@@ -809,7 +1021,8 @@ function parseToolLiteral(file, line, literal) {
 		hasExamples: examples.present,
 		parameterNames: Object.freeze(parameterNames),
 		tags: Object.freeze(tags),
-		source: literal
+		source: literal,
+		gradingSource: gradingLiteral
 	});
 }
 function countLines(source, index) {