@graphorin/eslint-plugin 0.5.0

package/dist/index.js

@@ -0,0 +1,1011 @@
+//#region src/rules/_comment-utils.ts
+/**
+* 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
+*/
+function nodeHasNearbyComment(context, node, tagPattern, maxGap = 1) {
+	const startLine = node.loc?.start.line ?? 0;
+	const endLine = node.loc?.end.line ?? Number.POSITIVE_INFINITY;
+	const allComments = context.sourceCode.getAllComments();
+	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;
+}
+
+//#endregion
+//#region src/rules/no-bare-tool-exec.ts
+const ALLOW_TAG$3 = /graphorin-allow-bare-exec/;
+const SIGNAL_REFERENCE_RE = /\bsignal\b/;
+const rule$8 = {
+	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) {
+		return { CallExpression(node) {
+			if (!isToolBuilderCall(node)) return;
+			const arg = node.arguments[0];
+			if (arg === void 0 || arg.type !== "ObjectExpression") return;
+			const exec = findExecuteProperty(arg);
+			if (exec === null) return;
+			if (!isFunctionLike(exec)) return;
+			const fn = exec;
+			if (!fn.body) return;
+			const fnSource = context.sourceCode.getText(fn.body);
+			if (SIGNAL_REFERENCE_RE.test(fnSource)) return;
+			if (hasAllowComment$3(context, node)) return;
+			const name = extractToolName(arg) ?? "<unknown>";
+			context.report({
+				node: fn,
+				messageId: "missingSignal",
+				data: { name }
+			});
+		} };
+	}
+};
+function isToolBuilderCall(node) {
+	if (node.callee.type !== "Identifier") return false;
+	return node.callee.name === "tool";
+}
+function findExecuteProperty(obj) {
+	for (const prop of obj.properties) {
+		if (prop.type !== "Property") continue;
+		const property = prop;
+		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) {
+	return value.type === "ArrowFunctionExpression" || value.type === "FunctionExpression";
+}
+function extractToolName(obj) {
+	for (const prop of obj.properties) {
+		if (prop.type !== "Property") continue;
+		const property = prop;
+		if (property.computed) continue;
+		const key = property.key;
+		if (!(key.type === "Identifier" && key.name === "name" || key.type === "Literal" && key.value === "name")) continue;
+		if (property.value.type === "Literal" && typeof property.value.value === "string") return property.value.value;
+	}
+	return null;
+}
+function hasAllowComment$3(context, node) {
+	return nodeHasNearbyComment(context, node, ALLOW_TAG$3, 1);
+}
+var no_bare_tool_exec_default = rule$8;
+
+//#endregion
+//#region src/rules/no-implicit-network-call.ts
+const ALLOW_TAG$2 = /graphorin-allow-network/;
+const FRAMEWORK_PATH_RE = /\bpackages\/[a-z0-9_-]+\/src\b/;
+const NETWORK_CALLEES = new Set(["fetch", "XMLHttpRequest"]);
+const HTTP_VERBS = new Set([
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"head",
+	"options",
+	"request"
+]);
+const rule$7 = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Disallow direct network primitives (`fetch`, `axios`, `http.request`, `XMLHttpRequest`) in `@graphorin/*` framework code without an explicit opt-out comment (DEC-154).",
+			recommended: true
+		},
+		schema: [],
+		messages: { forbidden: "direct network call '{{callee}}' 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 {};
+		return {
+			CallExpression(node) {
+				const name = describeCallee(node);
+				if (name === null) return;
+				if (hasAllowComment$2(context, node)) return;
+				context.report({
+					node,
+					messageId: "forbidden",
+					data: { callee: name }
+				});
+			},
+			NewExpression(node) {
+				if (node.callee.type !== "Identifier") return;
+				if (node.callee.name !== "XMLHttpRequest") return;
+				if (hasAllowComment$2(context, node)) return;
+				context.report({
+					node,
+					messageId: "forbidden",
+					data: { callee: "new XMLHttpRequest" }
+				});
+			}
+		};
+	}
+};
+function describeCallee(node) {
+	if (node.callee.type === "Identifier") {
+		const name = node.callee.name;
+		if (NETWORK_CALLEES.has(name) || name === "axios") return name;
+		return null;
+	}
+	if (node.callee.type === "MemberExpression") {
+		const me = node.callee;
+		if (me.computed) return null;
+		const objName = me.object.type === "Identifier" ? me.object.name : null;
+		if (objName === null) return null;
+		const propName = me.property.type === "Identifier" ? me.property.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}`;
+		return null;
+	}
+	return null;
+}
+function hasAllowComment$2(context, node) {
+	return nodeHasNearbyComment(context, node, ALLOW_TAG$2, 1);
+}
+var no_implicit_network_call_default = rule$7;
+
+//#endregion
+//#region src/rules/no-secret-in-deps.ts
+const JUSTIFICATION_TAG = /\brb-24-justification\s*:/i;
+const rule$6 = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Require an `// rb-24-justification:` comment when `Agent.toTool({ inheritSecrets: [...] })` carries a non-empty allowlist (DEC-137).",
+			recommended: true
+		},
+		schema: [],
+		messages: { missingJustification: "`inheritSecrets` is non-empty but the call site lacks an `// rb-24-justification: <reason>` comment. Document why this sub-agent inherits parent secrets per DEC-137." }
+	},
+	create(context) {
+		return { CallExpression(node) {
+			if (!isToToolCall(node)) return;
+			const arg = node.arguments[0];
+			if (arg === void 0 || arg.type !== "ObjectExpression") return;
+			const inheritSecrets = findInheritSecretsProperty(arg);
+			if (inheritSecrets === null) return;
+			if (!isNonEmptyArray(inheritSecrets)) return;
+			if (hasJustificationComment(context, node)) return;
+			context.report({
+				node: inheritSecrets,
+				messageId: "missingJustification"
+			});
+		} };
+	}
+};
+function isToToolCall(node) {
+	if (node.callee.type !== "MemberExpression") return false;
+	const callee = node.callee;
+	if (callee.computed) return false;
+	if (callee.property.type !== "Identifier") return false;
+	return callee.property.name === "toTool";
+}
+function findInheritSecretsProperty(obj) {
+	for (const prop of obj.properties) {
+		if (prop.type !== "Property") continue;
+		const property = prop;
+		const key = property.key;
+		if (property.computed) continue;
+		if (key.type === "Identifier" && key.name === "inheritSecrets") return property.value;
+		if (key.type === "Literal" && key.value === "inheritSecrets") return property.value;
+	}
+	return null;
+}
+function isNonEmptyArray(value) {
+	if (value.type !== "ArrayExpression") return false;
+	return value.elements.some((e) => e !== null);
+}
+function hasJustificationComment(context, node) {
+	return nodeHasNearbyComment(context, node, JUSTIFICATION_TAG, 1);
+}
+var no_secret_in_deps_default = rule$6;
+
+//#endregion
+//#region src/rules/no-secret-unwrap.ts
+const ALLOW_TAG$1 = /graphorin-allow-secret-unwrap/;
+const rule$5 = {
+	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: [],
+		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) {
+		return { CallExpression(node) {
+			const callee = node.callee;
+			if (callee.type !== "MemberExpression") return;
+			const me = callee;
+			if (me.computed) return;
+			if (me.property.type !== "Identifier") return;
+			const propName = me.property.name;
+			if (propName === "unwrap") {
+				context.report({
+					node,
+					messageId: "avoidUnwrap"
+				});
+				return;
+			}
+			if (propName === "reveal") {
+				if (hasAllowComment$1(context, node)) return;
+				context.report({
+					node,
+					messageId: "avoidReveal"
+				});
+			}
+		} };
+	}
+};
+function hasAllowComment$1(context, node) {
+	return nodeHasNearbyComment(context, node, ALLOW_TAG$1, 1);
+}
+var no_secret_unwrap_default = rule$5;
+
+//#endregion
+//#region src/rules/no-third-party-workflow-aliases.ts
+const ALLOW_TAG = /graphorin-workflow-naming-allow/;
+const WORKFLOW_PATH_RE = /\bpackages\/workflow\/src\b/;
+const FORBIDDEN_NAMES = new Map([
+	["Send", "Dispatch"],
+	["Command", "Directive"],
+	["interrupt", "pause"],
+	["LastValue", "LatestValue"],
+	["BinaryOperatorAggregate", "Reducer"],
+	["BinaryAggregate", "Reducer"],
+	["Topic", "Stream"]
+]);
+const rule$4 = {
+	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) {
+		if (!WORKFLOW_PATH_RE.test(context.filename.replace(/\\/g, "/"))) return {};
+		return { Identifier(node) {
+			const replacement = FORBIDDEN_NAMES.get(node.name);
+			if (replacement === void 0) return;
+			if (isInImportSpecifier(node)) return;
+			if (hasAllowComment(context, node)) return;
+			context.report({
+				node,
+				messageId: "forbidden",
+				data: {
+					forbidden: node.name,
+					replacement
+				}
+			});
+		} };
+	}
+};
+function isInImportSpecifier(node) {
+	const parent = node.parent;
+	if (parent === void 0) return false;
+	switch (parent.type) {
+		case "ImportSpecifier":
+		case "ImportNamespaceSpecifier":
+		case "ImportDefaultSpecifier":
+		case "ExportSpecifier": return true;
+		default: return false;
+	}
+}
+function hasAllowComment(context, node) {
+	return nodeHasNearbyComment(context, node, ALLOW_TAG, 1);
+}
+var no_third_party_workflow_aliases_default = rule$4;
+
+//#endregion
+//#region src/rules/provider-middleware-order.ts
+const CANONICAL_ORDER = [
+	"withTracing",
+	"withRetry",
+	"withRateLimit",
+	"withCostLimit",
+	"withCostTracking",
+	"withFallback",
+	"withRedaction"
+];
+const CANONICAL_INDEX = new Map(CANONICAL_ORDER.map((name, idx) => [name, idx]));
+const rule$3 = {
+	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) {
+		return { CallExpression(node) {
+			if (!isComposeCall(node)) return;
+			const arg = node.arguments[0];
+			if (arg === void 0 || arg.type !== "ArrayExpression") return;
+			const factories = extractFactoryNames(arg);
+			const recognised = [];
+			for (const f of factories) {
+				const idx = CANONICAL_INDEX.get(f.name);
+				if (idx !== void 0) 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 !== void 0 && cur !== void 0 && 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) {
+	if (node.callee.type === "Identifier") return node.callee.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) {
+	const out = [];
+	for (const elt of arr.elements) {
+		if (elt === null) continue;
+		if (elt.type === "Identifier") {
+			out.push({
+				name: elt.name,
+				node: elt
+			});
+			continue;
+		}
+		if (elt.type === "CallExpression") {
+			const callee = elt.callee;
+			if (callee.type === "Identifier") out.push({
+				name: callee.name,
+				node: elt
+			});
+			else if (callee.type === "MemberExpression" && callee.property.type === "Identifier") out.push({
+				name: callee.property.name,
+				node: elt
+			});
+		}
+	}
+	return out;
+}
+var provider_middleware_order_default = rule$3;
+
+//#endregion
+//#region src/tool-discovery.ts
+/**
+* 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
+*/
+const AMBIGUOUS_PARAMETER_NAMES = Object.freeze([
+	"user",
+	"id",
+	"name",
+	"value",
+	"data",
+	"input",
+	"output",
+	"result",
+	"to",
+	"from",
+	"key",
+	"field"
+]);
+/**
+* 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
+*/
+const PARAMETER_NAMING_OPT_OUT_TAGS = Object.freeze(["experimental", "legacy"]);
+/**
+* Placeholder values the description-required rule treats as
+* non-descriptions.
+*
+* @stable
+*/
+const PLACEHOLDER_DESCRIPTIONS = Object.freeze([
+	"todo",
+	"fixme",
+	"tbd",
+	"description",
+	"placeholder"
+]);
+const MIN_DESCRIPTION_LENGTH$1 = 20;
+const MAX_EXAMPLES$1 = 5;
+/**
+* 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
+*/
+function discoverToolCallsInSource(file, source) {
+	const out = [];
+	const regex = /\btool\s*\(\s*\{/g;
+	let match = regex.exec(source);
+	while (match !== null) {
+		const objectStart = match.index + match[0].length - 1;
+		const objectEnd = matchBrace(source, objectStart);
+		if (objectEnd > 0) {
+			const literal = source.slice(objectStart, objectEnd + 1);
+			const tool = parseToolLiteral(file, countLines(source, match.index), literal);
+			if (tool !== null) out.push(tool);
+		}
+		regex.lastIndex = objectEnd + 1;
+		match = regex.exec(source);
+	}
+	return out;
+}
+/** 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. */
+const NUMERIC_SUFFIX_PATTERN$1 = /^[A-Za-z]+\d+$/;
+/**
+* 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
+*/
+function runToolRules(tool, severityOverrides) {
+	const findings = [];
+	const descSeverity = severityOverrides?.toolDescription ?? "error";
+	if (descSeverity !== "off") {
+		const desc = tool.description?.trim() ?? "";
+		if (desc.length === 0) findings.push(finding("graphorin/tool-description-required", "description-missing", descSeverity, tool, `tool '${tool.name}' has no description; add a description that explains what the tool does and when to use it.`));
+		else if (PLACEHOLDER_DESCRIPTIONS.includes(desc.toLowerCase())) findings.push(finding("graphorin/tool-description-required", "description-placeholder", descSeverity, tool, `tool '${tool.name}' description is a placeholder ('${tool.description}').`));
+		else if (desc.length < MIN_DESCRIPTION_LENGTH$1) findings.push(finding("graphorin/tool-description-required", "description-too-short", descSeverity, tool, `tool '${tool.name}' description is shorter than ${MIN_DESCRIPTION_LENGTH$1} characters.`));
+	}
+	const examplesSeverity = severityOverrides?.toolExamples ?? "warn";
+	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));
+		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').`, {
+				matchedPattern: matched,
+				hint: "RB-49: examples must use synthetic test data so the rendered tool catalogue does not leak PII into provider context."
+			}));
+		}
+	}
+	const namingSeverity = severityOverrides?.toolParameterNaming ?? "warn";
+	const namingOptedOut = tool.tags.some((t) => PARAMETER_NAMING_OPT_OUT_TAGS.includes(t));
+	if (namingSeverity !== "off" && !namingOptedOut) {
+		for (const param of tool.parameterNames) if (AMBIGUOUS_PARAMETER_NAMES.includes(param)) findings.push(finding("graphorin/tool-parameter-naming", "parameter-ambiguous", namingSeverity, tool, `tool '${tool.name}' uses ambiguous parameter name '${param}'; prefer a self-documenting name (e.g. '${param}Id', '${param}Email').`));
+		else if (NUMERIC_SUFFIX_PATTERN$1.test(param)) findings.push(finding("graphorin/tool-parameter-naming", "parameter-numeric-suffix", namingSeverity, tool, `tool '${tool.name}' uses numeric-suffix parameter name '${param}'; prefer a semantic name (e.g. 'queryText', 'userId').`));
+	}
+	return findings;
+}
+/**
+* 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
+*/
+function gradeTool(tool, findings) {
+	const descFindings = findings.filter((f) => f.rule === "graphorin/tool-description-required");
+	const exampleFindings = findings.filter((f) => f.rule === "graphorin/tool-examples-recommended");
+	const namingFindings = findings.filter((f) => f.rule === "graphorin/tool-parameter-naming");
+	const description = scoreDescription(tool, descFindings);
+	const examples = scoreExamples(tool, exampleFindings);
+	const parameterNaming = scoreParameterNaming(tool, namingFindings);
+	return Object.freeze({
+		toolName: tool.name,
+		file: tool.file,
+		line: tool.line,
+		score: description + examples + parameterNaming,
+		axes: Object.freeze({
+			description,
+			examples,
+			parameterNaming
+		}),
+		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;
+}
+function scoreExamples(tool, findings) {
+	if (tool.examplesCount === 0) return 0;
+	if (tool.examplesCount > MAX_EXAMPLES$1) return 0;
+	const base = Math.min(30, 12 + (tool.examplesCount - 1) * 6);
+	const piiCount = findings.filter((f) => f.kind === "examples-pii-detected").length;
+	return Math.max(0, base - piiCount * 6);
+}
+function scoreParameterNaming(tool, findings) {
+	if (tool.parameterNames.length === 0) return 15;
+	const total = tool.parameterNames.length;
+	const ambiguousCount = findings.filter((f) => f.kind === "parameter-ambiguous").length;
+	const numericCount = findings.filter((f) => f.kind === "parameter-numeric-suffix").length;
+	const score = 30 - 30 / total * ambiguousCount - 10 / total * numericCount;
+	return Math.max(0, Math.round(score));
+}
+function finding(rule$9, kind, severity, tool, message, extra = {}) {
+	return Object.freeze({
+		rule: rule$9,
+		kind,
+		severity,
+		message,
+		toolName: tool.name,
+		file: tool.file,
+		line: tool.line,
+		...extra.hint !== void 0 ? { hint: extra.hint } : {},
+		...extra.matchedPattern !== void 0 ? { matchedPattern: extra.matchedPattern } : {}
+	});
+}
+/**
+* Extract the substring inside the `examples: [...]` array literal so
+* the PII detector can scan only the example payloads (not the rest of
+* the tool body).
+*
+* @internal
+*/
+function extractExamplesBlock(literal) {
+	const m = /examples\s*:\s*\[/.exec(literal);
+	if (m === null) return "";
+	const start = m.index + m[0].length - 1;
+	const end = matchBracket(literal, start);
+	if (end < 0) return "";
+	return literal.slice(start + 1, end);
+}
+/**
+* Parse a string literal value from the immediate object literal.
+* Supports `'`, `"`, and template strings (without interpolation).
+*
+* @internal
+*/
+function readStringProp(literal, prop) {
+	const escapedProp = prop.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const m = new RegExp(`(?:^|[\\s,{])${escapedProp}\\s*:\\s*(['"\`])`, "m").exec(literal);
+	if (m === null) return void 0;
+	const quote = m[1];
+	let i = m.index + m[0].length;
+	let out = "";
+	while (i < literal.length) {
+		const ch = literal[i];
+		if (ch === "\\" && i + 1 < literal.length) {
+			out += literal[i + 1];
+			i += 2;
+			continue;
+		}
+		if (ch === quote) return out;
+		out += ch;
+		i += 1;
+	}
+}
+/**
+* Count entries in an array literal value of the form `prop: [...]`.
+*
+* @internal
+*/
+function countArrayProp(literal, prop) {
+	const escapedProp = prop.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const m = new RegExp(`(?:^|[\\s,{])${escapedProp}\\s*:\\s*\\[`, "m").exec(literal);
+	if (m === null) return {
+		count: 0,
+		present: false
+	};
+	const start = m.index + m[0].length - 1;
+	const end = matchBracket(literal, start);
+	if (end < 0) return {
+		count: 0,
+		present: true
+	};
+	const inner = literal.slice(start + 1, end).trim().replace(/,\s*$/, "");
+	if (inner.length === 0) return {
+		count: 0,
+		present: true
+	};
+	let depth = 0;
+	let inString = null;
+	let count = 1;
+	for (let i = 0; i < inner.length; i += 1) {
+		const ch = inner[i];
+		if (inString !== null) {
+			if (ch === "\\") {
+				i += 1;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			continue;
+		}
+		if (ch === "(" || ch === "[" || ch === "{") depth += 1;
+		else if (ch === ")" || ch === "]" || ch === "}") depth -= 1;
+		else if (ch === "," && depth === 0) count += 1;
+	}
+	return {
+		count,
+		present: true
+	};
+}
+/**
+* Extract identifiers passed into a `z.object({...})` schema as
+* top-level keys.
+*
+* @internal
+*/
+function extractParameterNames(literal) {
+	const m = /inputSchema\s*:\s*z\s*\.\s*object\s*\(\s*\{/.exec(literal);
+	if (m === null) return [];
+	const start = m.index + m[0].length - 1;
+	const end = matchBrace(literal, start);
+	if (end < 0) return [];
+	const inner = literal.slice(start + 1, end);
+	const names = [];
+	const idRegex = /(^|[\s,{])([A-Za-z_$][A-Za-z0-9_$]*)\s*:/g;
+	let id = idRegex.exec(inner);
+	while (id !== null) {
+		const name = id[2];
+		if (!names.includes(name)) names.push(name);
+		id = idRegex.exec(inner);
+	}
+	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");
+	const tags = [];
+	if (tagsArr.present && tagsArr.count > 0) {
+		const m = /tags\s*:\s*\[([^\]]*)\]/.exec(literal);
+		if (m !== null) {
+			const inner = m[1] ?? "";
+			const tagRegex = /['"`]([^'"`]+)['"`]/g;
+			let t = tagRegex.exec(inner);
+			while (t !== null) {
+				tags.push(t[1]);
+				t = tagRegex.exec(inner);
+			}
+		}
+	}
+	const parameterNames = extractParameterNames(literal);
+	return Object.freeze({
+		file,
+		line,
+		name,
+		...description !== void 0 ? { description } : {},
+		examplesCount: examples.count,
+		hasExamples: examples.present,
+		parameterNames: Object.freeze(parameterNames),
+		tags: Object.freeze(tags),
+		source: literal
+	});
+}
+function countLines(source, index) {
+	let n = 1;
+	for (let i = 0; i < index; i += 1) if (source[i] === "\n") n += 1;
+	return n;
+}
+function matchBrace(source, openIndex) {
+	return matchPair(source, openIndex, "{", "}");
+}
+function matchBracket(source, openIndex) {
+	return matchPair(source, openIndex, "[", "]");
+}
+function matchPair(source, openIndex, open, close) {
+	let depth = 0;
+	let inString = null;
+	for (let i = openIndex; i < source.length; i += 1) {
+		const ch = source[i];
+		if (inString !== null) {
+			if (ch === "\\") {
+				i += 1;
+				continue;
+			}
+			if (ch === inString) inString = null;
+			continue;
+		}
+		if (ch === "\"" || ch === "'" || ch === "`") {
+			inString = ch;
+			continue;
+		}
+		if (ch === open) depth += 1;
+		else if (ch === close) {
+			depth -= 1;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+
+//#endregion
+//#region src/rules/tool-description-required.ts
+const MIN_DESCRIPTION_LENGTH = 20;
+const rule$2 = {
+	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) {
+		return { "Program:exit"() {
+			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 === void 0 || 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
+					}
+				});
+			}
+		} };
+	}
+};
+var tool_description_required_default = rule$2;
+
+//#endregion
+//#region src/rules/tool-examples-recommended.ts
+const MAX_EXAMPLES = 5;
+const rule$1 = {
+	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) {
+		return { "Program:exit"() {
+			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)
+				}
+			});
+		} };
+	}
+};
+var tool_examples_recommended_default = rule$1;
+
+//#endregion
+//#region src/rules/tool-parameter-naming.ts
+const NUMERIC_SUFFIX_PATTERN = /^[A-Za-z]+\d+$/;
+const rule = {
+	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) {
+		return { "Program:exit"() {
+			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
+					}
+				});
+			}
+		} };
+	}
+};
+var tool_parameter_naming_default = rule;
+
+//#endregion
+//#region src/index.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
+*/
+const VERSION = "0.5.0";
+const meta = {
+	name: "@graphorin/eslint-plugin",
+	version: VERSION
+};
+const rules = {
+	"no-bare-tool-exec": no_bare_tool_exec_default,
+	"no-implicit-network-call": no_implicit_network_call_default,
+	"no-secret-in-deps": no_secret_in_deps_default,
+	"no-secret-unwrap": no_secret_unwrap_default,
+	"no-third-party-workflow-aliases": no_third_party_workflow_aliases_default,
+	"provider-middleware-order": provider_middleware_order_default,
+	"tool-description-required": tool_description_required_default,
+	"tool-examples-recommended": tool_examples_recommended_default,
+	"tool-parameter-naming": tool_parameter_naming_default
+};
+/** Shared severity map for both the legacy and flat recommended presets. */
+const RECOMMENDED_RULES = {
+	"@graphorin/no-bare-tool-exec": "warn",
+	"@graphorin/no-implicit-network-call": "error",
+	"@graphorin/no-secret-in-deps": "error",
+	"@graphorin/no-secret-unwrap": "error",
+	"@graphorin/no-third-party-workflow-aliases": "error",
+	"@graphorin/provider-middleware-order": "error",
+	"@graphorin/tool-description-required": "error",
+	"@graphorin/tool-examples-recommended": "warn",
+	"@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.
+*/
+const plugin = {
+	meta,
+	rules,
+	configs: {
+		recommended: {
+			plugins: ["@graphorin"],
+			rules: RECOMMENDED_RULES
+		},
+		"flat/recommended": {
+			plugins: {},
+			rules: RECOMMENDED_RULES
+		}
+	}
+};
+plugin.configs["flat/recommended"].plugins = { "@graphorin": plugin };
+const configs = plugin.configs;
+var src_default = plugin;
+
+//#endregion
+export { AMBIGUOUS_PARAMETER_NAMES, PARAMETER_NAMING_OPT_OUT_TAGS, PLACEHOLDER_DESCRIPTIONS, VERSION, configs, src_default as default, discoverToolCallsInSource, gradeTool, meta, rules, runToolRules };
+//# sourceMappingURL=index.js.map