@coryrylan/tools 0.1.0

package/dist/eslint/plugin.js

@@ -0,0 +1,36 @@
+import rule from "./rules/no-dead-code.js";
+import rule$1 from "./rules/no-deep-class-inheritance.js";
+import rule$2 from "./rules/no-single-consumer-abstraction.js";
+import rule$3 from "./rules/no-unjustified-disable.js";
+import rule$4 from "./rules/no-reexport-barrels.js";
+import rule$5 from "./rules/consistent-error-messages.js";
+import rule$6 from "./rules/require-listener-cleanup.js";
+import rule$7 from "./rules/require-observer-cleanup.js";
+import rule$8 from "./rules/require-timer-cleanup.js";
+import rule$9 from "./rules/no-unpinned-dependency-ranges.js";
+/**
+* The `tools/*` rule registry, shared by every config in `./configs/*.ts`
+* under the `tools` namespace. Lives in its own module (rather than
+* `index.ts`, where it was previously declared empty) so the configs can
+* import it directly without a circular import back through `index.ts`.
+*/
+var plugin = {
+	meta: {
+		name: "@coryrylan/tools",
+		version: "0.1.0"
+	},
+	rules: {
+		"no-dead-code": rule,
+		"no-deep-class-inheritance": rule$1,
+		"no-single-consumer-abstraction": rule$2,
+		"no-unjustified-disable": rule$3,
+		"no-reexport-barrels": rule$4,
+		"consistent-error-messages": rule$5,
+		"require-listener-cleanup": rule$6,
+		"require-observer-cleanup": rule$7,
+		"require-timer-cleanup": rule$8,
+		"no-unpinned-dependency-ranges": rule$9
+	}
+};
+//#endregion
+export { plugin };

package/dist/eslint/rules/consistent-error-messages.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule that requires thrown/constructed `Error`s (and subclasses) to
+ * carry a non-empty, informative message. Agents routinely emit placeholder
+ * throw sites (`new Error('error')`, `new Error('')`) that make production
+ * debugging impossible; deterministic message hygiene catches this before
+ * review has to.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/consistent-error-messages.js

@@ -0,0 +1,127 @@
+//#region src/eslint/rules/consistent-error-messages.ts
+var DEFAULT_DENYLIST = [
+	"error",
+	"err",
+	"failed",
+	"failure",
+	"oops",
+	"something went wrong",
+	"unknown error",
+	"invalid",
+	"bad"
+];
+function readOptions(context) {
+	const provided = context.options[0];
+	return {
+		disallow: provided?.disallow ?? DEFAULT_DENYLIST,
+		allowLowercase: provided?.allowLowercase ?? false
+	};
+}
+/**
+* Error-constructor-shaped identifier names this rule cares about (built-ins
+* and custom `*Error` classes), excluding `AggregateError`. Requires a PascalCase
+* (uppercase-first) name so ordinary helpers whose name merely ends in `Error`
+* - `reportError`, `logError`, `handleError`, `onError` - are not mistaken for
+* constructors; every built-in and conventional custom error class is PascalCase.
+*/
+function isErrorConstructorName(name) {
+	return name !== "AggregateError" && /^[A-Z]/.test(name) && /Error$/.test(name);
+}
+/** Extracts the callee's identifier name, or `null` if the callee isn't a plain identifier. */
+function calleeName(node) {
+	return node.callee.type === "Identifier" ? node.callee.name : null;
+}
+/** Shared trim/noise/lowercase analysis for a message's literal text, used for both string literals and template-literal leading quasis. */
+function analyzeText(text, options) {
+	const trimmed = text.trim();
+	if (trimmed === "") return { messageId: "emptyMessage" };
+	const lower = trimmed.toLowerCase();
+	if (options.disallow.some((entry) => entry.toLowerCase() === lower)) return {
+		messageId: "noiseMessage",
+		text: trimmed
+	};
+	if (!options.allowLowercase && /^[a-z]/.test(trimmed)) return { messageId: "lowercaseMessage" };
+	return null;
+}
+/**
+* A template literal starting with `${` (empty leading quasi plus at least
+* one expression) is always treated as informative. Typed against the plain
+* `estree` shape (not `Rule.Node`) because this is a call argument, not a
+* traversed node, so it doesn't carry a `.parent` back-pointer.
+*/
+function analyzeTemplateLiteral(node, options) {
+	const cooked = node.quasis[0]?.value.cooked ?? "";
+	if (node.expressions.length > 0 && cooked === "") return null;
+	return analyzeText(cooked, options);
+}
+/** Analyzes the first argument to a flagged Error constructor/call, or `null` if it's not a message-shaped literal worth checking. */
+function analyzeFirstArgument(firstArgument, options) {
+	if (firstArgument.type === "Literal" && typeof firstArgument.value === "string") return analyzeText(firstArgument.value, options);
+	if (firstArgument.type === "TemplateLiteral") return analyzeTemplateLiteral(firstArgument, options);
+	return null;
+}
+function checkNode(context, node, options) {
+	const name = calleeName(node);
+	if (name === null || !isErrorConstructorName(name)) return;
+	const [firstArgument] = node.arguments;
+	if (!firstArgument) {
+		context.report({
+			node,
+			messageId: "missingMessage"
+		});
+		return;
+	}
+	const verdict = analyzeFirstArgument(firstArgument, options);
+	if (!verdict) return;
+	if (verdict.messageId === "noiseMessage") {
+		context.report({
+			node,
+			messageId: "noiseMessage",
+			data: { text: verdict.text ?? "" }
+		});
+		return;
+	}
+	context.report({
+		node,
+		messageId: verdict.messageId
+	});
+}
+var rule = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Require Error (and subclass) constructor/call sites to carry a non-empty, informative message.",
+			recommended: true
+		},
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				disallow: {
+					type: "array",
+					items: { type: "string" }
+				},
+				allowLowercase: { type: "boolean" }
+			}
+		}],
+		messages: {
+			missingMessage: "Construct errors with a message",
+			emptyMessage: "Error message must not be empty",
+			lowercaseMessage: "Error message should start with a capital letter or interpolated identifier",
+			noiseMessage: "Error message '{{text}}' is low-information noise; describe what failed and why"
+		}
+	},
+	create(context) {
+		const options = readOptions(context);
+		return {
+			NewExpression(node) {
+				checkNode(context, node, options);
+			},
+			CallExpression(node) {
+				checkNode(context, node, options);
+			}
+		};
+	}
+};
+//#endregion
+export { rule as default };

package/dist/eslint/rules/no-dead-code.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Removing dead/commented-out code keeps an agent's context free of zombie
+ * snippets that look load-bearing but aren't. Version control already
+ * remembers deleted code, so a comment that only exists to preserve an old
+ * implementation is pure noise for the next agent that reads the file.
+ *
+ * @see https://kentcdodds.com/blog/please-dont-commit-commented-out-code
+ */
+import type { Rule } from 'eslint';
+/** Options for the `no-dead-code` rule. */
+export interface NoDeadCodeOptions {
+    /** Regex source strings; a comment whose text matches any of these is never flagged. */
+    readonly allowPatterns: readonly string[];
+}
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/no-dead-code.js

@@ -0,0 +1,110 @@
+//#region src/eslint/rules/no-dead-code.ts
+var DEFAULT_ALLOW_PATTERNS = [];
+/**
+* Comments that exist to talk to tooling rather than to a reader - ESLint
+* directive comments, TypeScript pragma comments, Prettier's ignore marker,
+* and c8/istanbul coverage markers - are never dead code, no matter what
+* text follows the marker. Checked against the trimmed comment text.
+*/
+var DIRECTIVE_COMMENT_PATTERN = /^(?:eslint-disable|eslint-enable|eslint-env|globals?\b|exported\b|@ts-|prettier-ignore|c8\b|istanbul\b)/;
+/**
+* Heuristics for "this comment contains commented-out source code", ported
+* from the rule this replaces: each pattern targets one JS/TS construct that
+* shows up in real code but essentially never in prose (see inline comments
+* on patterns that need extra care to avoid false positives).
+*/
+var CODE_LIKE_PATTERNS = {
+	importStatement: /\s*import\s+.*from\s+['"].*['"];/,
+	exportStatement: /\s*export\s+.*from\s+['"].*['"];/,
+	functionKeyword: /\bfunction\b\s+(\w+)\s*\(/,
+	arrowFunction: /\([^()]*\)\s*=>|[(=]\s*\w+\s*=>|=>\s*[{(]/,
+	variableDeclaration: /(?:^|\s)(?:const|let|var)\s+(\w+|\[.*\])\s*(?:[=,;]|$)/,
+	controlFlowKeyword: /\b(?:if|else|try|catch|switch|while|for|do)\b\s*\(|^(?:if|else|try|catch|switch|while|for|do)$/,
+	returnStatement: /\breturn\b[^;]*;/,
+	consoleLog: /\bconsole\s*\.?\s*log\b\s*\(/,
+	debuggerStatement: /\bdebugger\b/,
+	describeBlock: /\bdescribe\(/,
+	itBlock: /\bit\(/
+};
+/** Whether `text` opens with a marker that tooling (not a human) reads. */
+function isDirectiveComment(text) {
+	return DIRECTIVE_COMMENT_PATTERN.test(text);
+}
+/**
+* Strips markdown-style inline code spans (`` `...` ``) before running the
+* commented-out-code heuristics. Prose and JSDoc routinely reference a
+* construct by name for illustration (`` `it(...)` ``, `` `export * from
+* './mod.js';` ``) and real dead code is never itself wrapped in backticks,
+* so anything that only "looks like code" inside a backtick span is a doc
+* reference, not a commented-out statement.
+*/
+function stripInlineCodeSpans(text) {
+	return text.replace(/`[^`]*`/g, "");
+}
+/** Whether `text` matches any of the commented-out-code heuristics. */
+function looksLikeCode(text) {
+	const withoutInlineCode = stripInlineCodeSpans(text);
+	return Object.values(CODE_LIKE_PATTERNS).some((pattern) => pattern.test(withoutInlineCode));
+}
+function matchesAnyPattern(text, patterns) {
+	return patterns.some((pattern) => pattern.test(text));
+}
+function readOptions(context) {
+	return { allowPatterns: context.options[0]?.allowPatterns ?? DEFAULT_ALLOW_PATTERNS };
+}
+/**
+* The JSON schema only validates `allowPatterns` entries as strings, so a
+* malformed regex source (e.g. `'[test'`) reaches here uncompiled. Skipping a
+* pattern that fails to compile - rather than letting `new RegExp` throw -
+* keeps one bad option entry from crashing the entire lint run.
+*/
+function tryCompile(source) {
+	try {
+		return new RegExp(source);
+	} catch {
+		return null;
+	}
+}
+function compileAllowPatterns(sources) {
+	const patterns = [];
+	for (const source of sources) {
+		const compiled = tryCompile(source);
+		if (compiled !== null) patterns.push(compiled);
+	}
+	return patterns;
+}
+function shouldSkipComment(text, allowPatterns) {
+	return text === "" || isDirectiveComment(text) || matchesAnyPattern(text, allowPatterns);
+}
+function checkComment(context, comment, allowPatterns) {
+	const text = comment.value.trim();
+	if (shouldSkipComment(text, allowPatterns) || !looksLikeCode(text)) return;
+	context.report({
+		node: comment,
+		messageId: "unexpected-dead-code",
+		data: { type: comment.type.toLowerCase() }
+	});
+}
+var rule = {
+	meta: {
+		type: "problem",
+		docs: { description: "Disallow dead code paths or dead source-code comment blocks." },
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: { allowPatterns: {
+				type: "array",
+				items: { type: "string" }
+			} }
+		}],
+		messages: { "unexpected-dead-code": "Remove dead/commented {{type}} to avoid incorrect context." }
+	},
+	create(context) {
+		const allowPatterns = compileAllowPatterns(readOptions(context).allowPatterns);
+		return { Program() {
+			for (const comment of context.sourceCode.getAllComments()) checkComment(context, comment, allowPatterns);
+		} };
+	}
+};
+//#endregion
+export { rule as default };

package/dist/eslint/rules/no-deep-class-inheritance.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Agents tend to solve "I need a slightly different X" by subclassing X
+ * instead of composing behavior, and the habit compounds: each new layer
+ * makes sense in isolation, but understanding any one class now requires
+ * reading the whole chain up to its root. This rule counts superclass hops
+ * and reports once a class's inheritance chain passes a configured maximum,
+ * so local wrappers around an allowed root stay possible without letting the
+ * hierarchy grow without bound.
+ */
+import type { Rule } from 'eslint';
+/** Options for the `no-deep-class-inheritance` rule. */
+export interface NoDeepClassInheritanceOptions {
+    /** Maximum number of superclass hops allowed before an allowed root is reached. */
+    readonly maxDepth: number;
+    /** Class names that end the depth count early once reached. */
+    readonly allowedRoots: readonly string[];
+}
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/no-deep-class-inheritance.js

@@ -0,0 +1,132 @@
+//#region src/eslint/rules/no-deep-class-inheritance.ts
+var DEFAULT_MAX_DEPTH = 2;
+var DEFAULT_ALLOWED_ROOTS = [];
+var ANONYMOUS_CLASS_NAME = "<anonymous>";
+function hasTypeAwareParserServices(services) {
+	if (typeof services !== "object" || services === null) return false;
+	const candidate = services;
+	return Boolean(candidate.program) && Boolean(candidate.esTreeNodeToTSNodeMap);
+}
+/** Returns `null` when the active parser doesn't provide type information (e.g. plain espree). */
+function getTypeAwareParserServices(context) {
+	const services = context.sourceCode.parserServices;
+	return hasTypeAwareParserServices(services) ? services : null;
+}
+function readOptions(context) {
+	const provided = context.options[0];
+	return {
+		maxDepth: provided?.maxDepth ?? DEFAULT_MAX_DEPTH,
+		allowedRoots: provided?.allowedRoots ?? DEFAULT_ALLOWED_ROOTS
+	};
+}
+function getClassName(node) {
+	return node.id?.name ?? ANONYMOUS_CLASS_NAME;
+}
+/** The `extends` heritage clause of a class-like declaration, if it has one (as opposed to `implements`). */
+function getExtendsExpression(classDeclaration) {
+	return (classDeclaration.heritageClauses?.find((clause) => clause.getText().startsWith("extends")))?.types[0]?.expression ?? null;
+}
+/**
+* Structural stand-in for `ts.isClassLike`, again to keep typescript out of the
+* runtime import graph. Declaration merging means this can also match an
+* interface with the same name; interfaces use `extends` heritage clauses too,
+* so chain walking still terminates correctly in that case.
+*/
+function isClassLikeDeclaration(declaration) {
+	const candidate = declaration;
+	return Array.isArray(candidate.members) && candidate.heritageClauses !== void 0;
+}
+/** The display name for one link in the inheritance chain: the resolved symbol's name, or the raw source text if it has none. */
+function resolveClassName(symbol, expression) {
+	return symbol?.getName() ?? expression.getText();
+}
+/**
+* The next superclass expression to follow from `symbol`'s declaration, or
+* `null` once there's no further (or already-visited) class-like declaration
+* to walk into. Marks the declaration visited as a side effect so `visited`
+* stays accurate for the caller's next iteration.
+*/
+function resolveNextExpression(symbol, visited) {
+	const declaration = symbol?.declarations?.find(isClassLikeDeclaration);
+	if (!declaration || visited.has(declaration)) return null;
+	visited.add(declaration);
+	return getExtendsExpression(declaration);
+}
+/**
+* Walks superclass hops starting from `superClass`, collecting each link's
+* display name, until it runs out of resolvable declarations or hits a name
+* in `allowedRoots`. `visited` guards against revisiting the same
+* declaration if a project's types ever formed a cycle.
+*/
+function getInheritanceChain(superClass, checker, allowedRoots) {
+	const chain = [];
+	const visited = /* @__PURE__ */ new Set();
+	let expression = superClass;
+	while (expression) {
+		const symbol = checker.getTypeAtLocation(expression).getSymbol();
+		const className = resolveClassName(symbol, expression);
+		chain.push(className);
+		if (allowedRoots.has(className)) break;
+		expression = resolveNextExpression(symbol, visited);
+	}
+	return chain;
+}
+function reportTooDeep(context, report) {
+	const className = getClassName(report.node);
+	context.report({
+		node: report.node,
+		messageId: "too-deep",
+		data: {
+			className,
+			depth: String(report.chain.length),
+			maxDepth: String(report.maxDepth),
+			chain: `${className} -> ${report.chain.join(" -> ")}`
+		}
+	});
+}
+function checkClassDeclaration(context, node, config) {
+	if (!node.superClass) return;
+	const services = getTypeAwareParserServices(context);
+	if (!services) return;
+	const chain = getInheritanceChain(services.esTreeNodeToTSNodeMap.get(node.superClass), services.program.getTypeChecker(), config.allowedRoots);
+	if (chain.length <= config.maxDepth) return;
+	reportTooDeep(context, {
+		node,
+		chain,
+		maxDepth: config.maxDepth
+	});
+}
+var rule = {
+	meta: {
+		type: "problem",
+		docs: { description: "Disallow class inheritance chains deeper than the configured maximum." },
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				maxDepth: {
+					type: "integer",
+					minimum: 1
+				},
+				allowedRoots: {
+					type: "array",
+					items: { type: "string" },
+					uniqueItems: true
+				}
+			}
+		}],
+		messages: { "too-deep": "`{{className}}` has inheritance depth {{depth}} (`{{chain}}`). Maximum allowed depth is {{maxDepth}}." }
+	},
+	create(context) {
+		const options = readOptions(context);
+		const config = {
+			maxDepth: options.maxDepth,
+			allowedRoots: new Set(options.allowedRoots)
+		};
+		return { ClassDeclaration(node) {
+			checkClassDeclaration(context, node, config);
+		} };
+	}
+};
+//#endregion
+export { rule as default };

package/dist/eslint/rules/no-reexport-barrels.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule that flags files re-exporting from more modules than
+ * `maxReexports` allows. Agents follow barrel files (`export * from './x'`)
+ * transitively - reading one barrel to find a symbol drags an entire
+ * dependency closure into context. Deep barrels also block tree-shaking and
+ * are a common source of import cycles.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/no-reexport-barrels.js

@@ -0,0 +1,55 @@
+//#region src/eslint/rules/no-reexport-barrels.ts
+var DEFAULT_MAX_REEXPORTS = 5;
+function readOptions(context) {
+	const provided = context.options[0];
+	return {
+		maxReexports: provided?.maxReexports ?? DEFAULT_MAX_REEXPORTS,
+		allowNamed: provided?.allowNamed ?? true
+	};
+}
+var rule = {
+	meta: {
+		type: "suggestion",
+		docs: {
+			description: "Disallow re-exporting from more than a configured number of modules (barrel files).",
+			recommended: true
+		},
+		schema: [{
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				maxReexports: {
+					type: "integer",
+					minimum: 0
+				},
+				allowNamed: { type: "boolean" }
+			}
+		}],
+		messages: { tooManyReexports: "This file re-exports from {{count}} modules (max {{max}}). Barrel files bloat agent context and break tree-shaking; import from concrete modules instead." }
+	},
+	create(context) {
+		const options = readOptions(context);
+		const reexports = [];
+		return {
+			ExportAllDeclaration(node) {
+				reexports.push(node);
+			},
+			ExportNamedDeclaration(node) {
+				if (!options.allowNamed && node.source) reexports.push(node);
+			},
+			"Program:exit"() {
+				if (reexports.length <= options.maxReexports) return;
+				for (const node of reexports) context.report({
+					node,
+					messageId: "tooManyReexports",
+					data: {
+						count: reexports.length,
+						max: options.maxReexports
+					}
+				});
+			}
+		};
+	}
+};
+//#endregion
+export { rule as default };

package/dist/eslint/rules/no-single-consumer-abstraction.d.ts

@@ -0,0 +1,3 @@
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;