@graphorin/eslint-plugin 0.6.1 → 0.7.0

package/src/rules/_comment-utils.ts

@@ -0,0 +1,37 @@
+/**
+ * Comment-scanning helpers shared by the rule modules. We use raw
+ * `getAllComments` + line-distance heuristics instead of `getComments
+ * Before / Inside / After` because ESLint's per-node comment attachment
+ * leaves orphan comments at the program top-level when the node
+ * itself is nested inside an expression statement.
+ */
+
+import type { Rule } from 'eslint';
+import type { Comment, Node } from 'estree';
+
+/**
+ * Returns `true` when the source contains a comment whose `value`
+ * matches `tag` and which is positioned within `1` line of `node`'s
+ * start, or anywhere inside `node`'s span.
+ *
+ * @internal
+ */
+export function nodeHasNearbyComment(
+  context: Rule.RuleContext,
+  node: Node,
+  tagPattern: RegExp,
+  maxGap: number = 1,
+): boolean {
+  const startLine = node.loc?.start.line ?? 0;
+  const endLine = node.loc?.end.line ?? Number.POSITIVE_INFINITY;
+  const allComments = context.sourceCode.getAllComments() as Comment[];
+  for (const c of allComments) {
+    if (!tagPattern.test(c.value)) continue;
+    const cStart = c.loc?.start.line ?? 0;
+    const cEnd = c.loc?.end.line ?? 0;
+    if (cEnd <= startLine && startLine - cEnd <= maxGap) return true;
+    if (cStart >= startLine && cStart <= endLine) return true;
+    if (cStart >= endLine && cStart - endLine <= maxGap) return true;
+  }
+  return false;
+}

package/src/rules/no-bare-tool-exec.ts

@@ -0,0 +1,120 @@
+/**
+ * Rule: `@graphorin/no-bare-tool-exec`. Flags any `tool({...})`
+ * invocation whose `execute` function does not reference
+ * `ctx.signal`. The intent is principle 3 (streaming-first) +
+ * DEC-143 (cancellation contract): every long-running tool MUST
+ * propagate the abort signal to the underlying I/O so cancellation
+ * actually frees resources.
+ *
+ * The check is intentionally lexical - it scans the function body for
+ * the literal string `signal` (matching `ctx.signal`,
+ * `request.signal`, `args.signal`, etc.). False positives are
+ * acceptable because the fix is one comment line; false negatives are
+ * not, because they hide cancellation bugs in production.
+ *
+ * Per-call opt-out: `// graphorin-allow-bare-exec: <reason>` on the
+ * line above the `execute` function or anywhere inside the tool
+ * builder call.
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+import type {
+  ArrowFunctionExpression,
+  CallExpression,
+  FunctionExpression,
+  Identifier,
+  ObjectExpression,
+  Property,
+} from 'estree';
+
+import { nodeHasNearbyComment } from './_comment-utils.js';
+
+const ALLOW_TAG = /graphorin-allow-bare-exec/;
+const SIGNAL_REFERENCE_RE = /\bsignal\b/;
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require every `tool({...})` `execute` function to reference `ctx.signal` so cancellation propagates to the underlying I/O (principle 3, DEC-143).',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      missingSignal:
+        "tool '{{name}}' `execute` function does not reference `ctx.signal`; long-running tools MUST propagate the abort signal. Add `// graphorin-allow-bare-exec: <reason>` to opt out.",
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      CallExpression(node: CallExpression): void {
+        if (!isToolBuilderCall(node)) return;
+        const arg = node.arguments[0];
+        if (arg === undefined || arg.type !== 'ObjectExpression') return;
+        const exec = findExecuteProperty(arg as ObjectExpression);
+        if (exec === null) return;
+        if (!isFunctionLike(exec)) return;
+        const fn = exec as ArrowFunctionExpression | FunctionExpression;
+        if (!fn.body) return;
+        const fnSource = context.sourceCode.getText(fn.body);
+        if (SIGNAL_REFERENCE_RE.test(fnSource)) return;
+        if (hasAllowComment(context, node)) return;
+        const name = extractToolName(arg as ObjectExpression) ?? '<unknown>';
+        context.report({
+          node: fn,
+          messageId: 'missingSignal',
+          data: { name },
+        });
+      },
+    };
+  },
+};
+
+function isToolBuilderCall(node: CallExpression): boolean {
+  if (node.callee.type !== 'Identifier') return false;
+  return (node.callee as Identifier).name === 'tool';
+}
+
+function findExecuteProperty(obj: ObjectExpression): Property['value'] | null {
+  for (const prop of obj.properties) {
+    if (prop.type !== 'Property') continue;
+    const property = prop as Property;
+    if (property.computed) continue;
+    const key = property.key;
+    if (key.type === 'Identifier' && key.name === 'execute') return property.value;
+    if (key.type === 'Literal' && key.value === 'execute') return property.value;
+  }
+  return null;
+}
+
+function isFunctionLike(
+  value: Property['value'],
+): value is ArrowFunctionExpression | FunctionExpression {
+  return value.type === 'ArrowFunctionExpression' || value.type === 'FunctionExpression';
+}
+
+function extractToolName(obj: ObjectExpression): string | null {
+  for (const prop of obj.properties) {
+    if (prop.type !== 'Property') continue;
+    const property = prop as Property;
+    if (property.computed) continue;
+    const key = property.key;
+    const isName =
+      (key.type === 'Identifier' && key.name === 'name') ||
+      (key.type === 'Literal' && key.value === 'name');
+    if (!isName) continue;
+    if (property.value.type === 'Literal' && typeof property.value.value === 'string') {
+      return property.value.value;
+    }
+  }
+  return null;
+}
+
+function hasAllowComment(context: Rule.RuleContext, node: CallExpression): boolean {
+  return nodeHasNearbyComment(context, node, ALLOW_TAG, 1);
+}
+
+export default rule;

package/src/rules/no-implicit-network-call.ts

@@ -0,0 +1,236 @@
+/**
+ * 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
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import type { Rule } from 'eslint';
+import type {
+  CallExpression,
+  Identifier,
+  ImportDeclaration,
+  MemberExpression,
+  NewExpression,
+} from 'estree';
+
+import { nodeHasNearbyComment } from './_comment-utils.js';
+
+const ALLOW_TAG = /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 = new Map<string, string | null>();
+
+/** Walk up from `fileDir` to the nearest package.json name (cached). */
+function nearestPackageName(fileDir: string): string | null {
+  const cached = packageNameCache.get(fileDir);
+  if (cached !== undefined) return cached;
+  let name: string | null = null;
+  let dir = fileDir;
+  for (;;) {
+    try {
+      const raw = readFileSync(join(dir, 'package.json'), 'utf8');
+      const parsed = JSON.parse(raw) as { name?: unknown };
+      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', 'post', 'put', 'patch', 'delete', 'head', 'options', 'request']);
+const CLIENT_NAMESPACE_VERBS = new Set(['request', 'stream', 'fetch', 'get', 'post']);
+const NETWORK_CONSTRUCTORS = new Set(['XMLHttpRequest', 'WebSocket', 'EventSource']);
+const HTTP_CLIENT_SPECIFIERS = new Set(['node-fetch', 'undici', 'got', 'axios', 'ky', 'ws']);
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      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: [
+      {
+        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: Rule.RuleContext): Rule.RuleListener {
+    const filename = context.filename.replace(/\\/g, '/');
+    if (!FRAMEWORK_PATH_RE.test(filename)) {
+      return {};
+    }
+    // W-039 second stage: only packages whose manifest name matches a
+    // configured prefix are "framework code". No resolvable manifest ->
+    // fail open (path-only activation, the historical behaviour).
+    const options = (context.options?.[0] ?? {}) as { packagePrefixes?: readonly string[] };
+    const prefixes = options.packagePrefixes ?? ['@graphorin/'];
+    const packageName = nearestPackageName(dirname(context.filename));
+    if (packageName !== null && !prefixes.some((p) => packageName.startsWith(p))) {
+      return {};
+    }
+    return {
+      CallExpression(node: CallExpression): void {
+        const specifier = requiredClientSpecifier(node);
+        if (specifier !== null) {
+          if (hasAllowComment(context, node)) return;
+          context.report({
+            node,
+            messageId: 'forbiddenImport',
+            data: { specifier },
+          });
+          return;
+        }
+        const name = describeCallee(node);
+        if (name === null) return;
+        if (hasAllowComment(context, node)) return;
+        context.report({
+          node,
+          messageId: 'forbidden',
+          data: { callee: name },
+        });
+      },
+      NewExpression(node: NewExpression): void {
+        if (node.callee.type !== 'Identifier') return;
+        const callee = node.callee as Identifier;
+        if (!NETWORK_CONSTRUCTORS.has(callee.name)) return;
+        if (hasAllowComment(context, node)) return;
+        context.report({
+          node,
+          messageId: 'forbidden',
+          data: { callee: `new ${callee.name}` },
+        });
+      },
+      ImportDeclaration(node: ImportDeclaration): void {
+        const source = node.source.value;
+        if (typeof source !== 'string' || !HTTP_CLIENT_SPECIFIERS.has(source)) return;
+        if (nodeHasNearbyComment(context, node, ALLOW_TAG, 1)) return;
+        context.report({
+          node,
+          messageId: 'forbiddenImport',
+          data: { specifier: source },
+        });
+      },
+      ImportExpression(node: Rule.Node): void {
+        const source = (node as { source?: { type?: string; value?: unknown } }).source;
+        if (source?.type !== 'Literal' || typeof source.value !== 'string') return;
+        if (!HTTP_CLIENT_SPECIFIERS.has(source.value)) return;
+        if (nodeHasNearbyComment(context, node as never, ALLOW_TAG, 1)) return;
+        context.report({
+          node: node as never,
+          messageId: 'forbiddenImport',
+          data: { specifier: source.value },
+        });
+      },
+    };
+  },
+};
+
+/** `require('<http client>')` - import-shaped despite being a call. */
+function requiredClientSpecifier(node: CallExpression): string | null {
+  if (node.callee.type !== 'Identifier') return null;
+  if ((node.callee as Identifier).name !== 'require') return null;
+  const arg = node.arguments[0];
+  if (arg === undefined || arg.type !== 'Literal') return null;
+  const value = (arg as { value?: unknown }).value;
+  if (typeof value !== 'string' || !HTTP_CLIENT_SPECIFIERS.has(value)) return null;
+  return value;
+}
+
+function describeCallee(node: CallExpression): string | null {
+  if (node.callee.type === 'Identifier') {
+    const name = (node.callee as Identifier).name;
+    if (NETWORK_CALLEES.has(name) || name === 'axios') return name;
+    return null;
+  }
+  if (node.callee.type === 'MemberExpression') {
+    const me = node.callee as MemberExpression;
+    if (me.computed) return null;
+    const objName = me.object.type === 'Identifier' ? (me.object as Identifier).name : null;
+    if (objName === null) return null;
+    const propName = me.property.type === 'Identifier' ? (me.property as Identifier).name : null;
+    if (propName === null) return null;
+    if (
+      (objName === 'http' || objName === 'https') &&
+      (propName === 'request' || propName === 'get')
+    )
+      return `${objName}.${propName}`;
+    if (objName === 'axios' && HTTP_VERBS.has(propName)) return `axios.${propName}`;
+    if ((objName === 'undici' || objName === 'got') && CLIENT_NAMESPACE_VERBS.has(propName))
+      return `${objName}.${propName}`;
+    if (objName === 'net' && (propName === 'createConnection' || propName === 'connect'))
+      return `net.${propName}`;
+    if (objName === 'tls' && propName === 'connect') return 'tls.connect';
+    if (objName === 'dgram' && propName === 'createSocket') return 'dgram.createSocket';
+    return null;
+  }
+  return null;
+}
+
+function hasAllowComment(context: Rule.RuleContext, node: CallExpression | NewExpression): boolean {
+  return nodeHasNearbyComment(context, node, ALLOW_TAG, 1);
+}
+
+export default rule;

package/src/rules/no-secret-in-deps.ts

@@ -0,0 +1,113 @@
+/**
+ * Rule: `@graphorin/no-secret-in-deps` (RB-24 / DEC-137). Flags any
+ * call shaped like `withChildToolSecretsContext({ secretsAllowed:
+ * [...] }, fn)` where the `secretsAllowed` array is non-empty and the
+ * surrounding call site does not include a comment whose text starts
+ * with `'rb-24-justification:'` (case-insensitive).
+ *
+ * The rule enforces the principle-of-least-authority discipline from
+ * DEC-137: granting a child tool scope access to parent secrets is
+ * opt-in, and the opt-in MUST be explained in code so security
+ * reviewers can audit the inheritance graph without guessing.
+ *
+ * History: this rule originally matched `Agent.toTool({
+ * inheritSecrets: [...] })`, a pre-0.5 API shape that no longer
+ * exists - `AgentToToolOptions` deliberately has no secret-inheritance
+ * mechanism at that boundary. The DEC-137 grant point today is the
+ * explicit child ACL scope opened via `withChildToolSecretsContext`
+ * from `@graphorin/security` (whose `secretsAllowed` is intersected
+ * with the parent allowlist), so that is what the rule matches now.
+ *
+ * The rule is intentionally syntactic - it operates on the literal
+ * call site without trying to resolve the value of the array. This
+ * keeps the rule cheap and avoids false negatives from spread /
+ * function-call expressions that hide the inheritance shape.
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+import type {
+  ArrayExpression,
+  CallExpression,
+  Identifier,
+  MemberExpression,
+  ObjectExpression,
+  Property,
+} from 'estree';
+
+import { nodeHasNearbyComment } from './_comment-utils.js';
+
+const JUSTIFICATION_TAG = /\brb-24-justification\s*:/i;
+const GRANT_CALLEE = 'withChildToolSecretsContext';
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Require an `// rb-24-justification:` comment when `withChildToolSecretsContext({ secretsAllowed: [...] })` grants a non-empty allowlist to a child tool scope (DEC-137).',
+      recommended: true,
+    },
+    schema: [],
+    messages: {
+      missingJustification:
+        '`secretsAllowed` is non-empty but the call site lacks an `// rb-24-justification: <reason>` comment. Document why this child tool scope inherits parent secrets per DEC-137.',
+    },
+  },
+  create(context: Rule.RuleContext): Rule.RuleListener {
+    return {
+      CallExpression(node: CallExpression): void {
+        if (!isGrantCall(node)) return;
+        const arg = node.arguments[0];
+        if (arg === undefined || arg.type !== 'ObjectExpression') return;
+        const objectArg = arg as ObjectExpression;
+        const secretsAllowed = findSecretsAllowedProperty(objectArg);
+        if (secretsAllowed === null) return;
+        if (!isNonEmptyArray(secretsAllowed)) return;
+        if (hasJustificationComment(context, node)) return;
+        context.report({
+          node: secretsAllowed,
+          messageId: 'missingJustification',
+        });
+      },
+    };
+  },
+};
+
+function isGrantCall(node: CallExpression): boolean {
+  if (node.callee.type === 'Identifier') {
+    return (node.callee as Identifier).name === GRANT_CALLEE;
+  }
+  if (node.callee.type === 'MemberExpression') {
+    const callee = node.callee as MemberExpression;
+    if (callee.computed) return false;
+    if (callee.property.type !== 'Identifier') return false;
+    return callee.property.name === GRANT_CALLEE;
+  }
+  return false;
+}
+
+function findSecretsAllowedProperty(obj: ObjectExpression): Property['value'] | null {
+  for (const prop of obj.properties) {
+    if (prop.type !== 'Property') continue;
+    const property = prop as Property;
+    const key = property.key;
+    if (property.computed) continue;
+    if (key.type === 'Identifier' && key.name === 'secretsAllowed') return property.value;
+    if (key.type === 'Literal' && key.value === 'secretsAllowed') return property.value;
+  }
+  return null;
+}
+
+function isNonEmptyArray(value: Property['value']): boolean {
+  if (value.type !== 'ArrayExpression') return false;
+  const arr = value as ArrayExpression;
+  return arr.elements.some((e) => e !== null);
+}
+
+function hasJustificationComment(context: Rule.RuleContext, node: CallExpression): boolean {
+  return nodeHasNearbyComment(context, node, JUSTIFICATION_TAG, 1);
+}
+
+export default rule;

package/src/rules/no-secret-unwrap.ts

@@ -0,0 +1,118 @@
+/**
+ * Rule: `@graphorin/no-secret-unwrap` (DEC-020 / ADR-026 / Phase 16).
+ *
+ * Flags member expressions that look like an unprotected unwrap of a
+ * `SecretValue` instance - `<expr>.unwrap()` and `<expr>.reveal()` -
+ * outside an allow-listed context. The framework convention is:
+ *
+ *   - Prefer `value.use(fn)` / `value.useBuffer(fn)` for scoped reads;
+ *     they limit the lifetime of the derived V8 string to a single
+ *     callback invocation.
+ *   - Use `value.reveal()` only as a one-shot escape hatch with an
+ *     adjacent justification. The audit log records the call.
+ *   - Never use `value.unwrap()` - it is `@deprecated` and is an alias
+ *     for `.reveal()` retained only for the v0.x compatibility window.
+ *     The rule reports `unwrap()` as `'error'` even when an
+ *     opt-out comment is present so the deprecation cliff stays sharp.
+ *
+ * Per-call opt-out: `// graphorin-allow-secret-unwrap: <reason>` on
+ * the line above the call site or anywhere inside the enclosing
+ * expression-statement source span. The opt-out is honoured for
+ * `reveal()` but **not** for `unwrap()` (the deprecation supersedes
+ * any local justification).
+ *
+ * The rule is intentionally lexical - it matches `.unwrap()` /
+ * `.reveal()` on any `MemberExpression` regardless of the receiver
+ * type. False positives are tolerated because (a) the receiver is
+ * almost always a `SecretValue` in this codebase and (b) the
+ * one-line opt-out is cheap.
+ *
+ * Known collision (W-043): Zod's `ZodOptional`/`ZodNullable`/
+ * `ZodDefault` expose `.unwrap()`, and Rust-style result libraries use
+ * it too - schema-introspection code trips the rule. The
+ * `allowReceiverPattern` option carves those receivers out: when the
+ * SOURCE TEXT of the receiver expression matches the pattern, both
+ * `unwrap` and `reveal` reports are skipped. The default stays
+ * undefined (byte-identical historical behaviour - the deprecation
+ * cliff keeps its edge), and there is deliberately NO built-in
+ * "looks like Zod" auto-heuristic: a nondeterministic guess is worse
+ * than an explicit, narrow setting (pick a suffix pattern like
+ * `'Schema$'`, or prefer a file-glob rule override).
+ *
+ * @packageDocumentation
+ */
+
+import type { Rule } from 'eslint';
+import type { CallExpression, Identifier, MemberExpression } from 'estree';
+
+import { nodeHasNearbyComment } from './_comment-utils.js';
+
+const ALLOW_TAG = /graphorin-allow-secret-unwrap/;
+
+const rule: Rule.RuleModule = {
+  meta: {
+    type: 'problem',
+    docs: {
+      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: [
+      {
+        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: Rule.RuleContext): Rule.RuleListener {
+    const options = (context.options?.[0] ?? {}) as { allowReceiverPattern?: string };
+    const allowReceiver =
+      options.allowReceiverPattern !== undefined ? new RegExp(options.allowReceiverPattern) : null;
+    return {
+      CallExpression(node: CallExpression): void {
+        const callee = node.callee;
+        if (callee.type !== 'MemberExpression') return;
+        const me = callee as MemberExpression;
+        if (me.computed) return;
+        if (me.property.type !== 'Identifier') return;
+        const propName = (me.property as Identifier).name;
+        if (propName !== 'unwrap' && propName !== 'reveal') return;
+        // W-043 carve-out: a receiver whose source text matches the
+        // configured pattern is not a SecretValue (Zod schemas,
+        // Rust-style results) - skip both report paths.
+        if (allowReceiver?.test(context.sourceCode.getText(me.object)) === true) {
+          return;
+        }
+        if (propName === 'unwrap') {
+          context.report({
+            node,
+            messageId: 'avoidUnwrap',
+          });
+          return;
+        }
+        if (propName === 'reveal') {
+          if (hasAllowComment(context, node)) return;
+          context.report({
+            node,
+            messageId: 'avoidReveal',
+          });
+        }
+      },
+    };
+  },
+};
+
+function hasAllowComment(context: Rule.RuleContext, node: CallExpression): boolean {
+  return nodeHasNearbyComment(context, node, ALLOW_TAG, 1);
+}
+
+export default rule;