@coryrylan/tools 0.1.0

package/dist/eslint/rules/require-listener-cleanup.js

@@ -0,0 +1,202 @@
+import { normalize, walk } from "./utils.js";
+//#region src/eslint/rules/require-listener-cleanup.ts
+var DEFAULT_LIFECYCLE_PAIRS = [["connectedCallback", "disconnectedCallback"]];
+var rule = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Ensures addEventListener calls in a setup lifecycle method have a matching removeEventListener in the paired teardown method, and forbids addEventListener in the constructor.",
+			recommended: true
+		},
+		schema: [{
+			type: "object",
+			properties: { lifecyclePairs: {
+				type: "array",
+				items: {
+					type: "array",
+					items: [{ type: "string" }, { type: "string" }],
+					minItems: 2,
+					maxItems: 2
+				}
+			} },
+			additionalProperties: false
+		}],
+		messages: {
+			"missing-cleanup": "`addEventListener` on `{{target}}` for `{{event}}` is called in {{setup}}() but no matching `removeEventListener` is called in {{teardown}}(). Attach the listener via a class field and remove the same reference in {{teardown}}() to prevent a listener leak when {{setup}} runs again.",
+			"missing-teardown": "{{setup}}() attaches event listeners but the class has no {{teardown}}(). Add a {{teardown}}() that removes each listener with its original reference to prevent a leak when {{setup}} runs again.",
+			"listener-in-constructor": "`addEventListener` on `{{target}}` for `{{event}}` is called in the constructor. The constructor runs once per instance, so this listener cannot be paired with a teardown call and leaks if the instance is torn down and recreated. Move the call into a setup lifecycle method and pair it with a matching removeEventListener in the corresponding teardown method."
+		}
+	},
+	create(context) {
+		const pairs = getLifecyclePairs(context);
+		const handleClass = (node) => {
+			checkClass({
+				context,
+				classNode: node
+			}, pairs);
+		};
+		return {
+			ClassDeclaration: handleClass,
+			ClassExpression: handleClass
+		};
+	}
+};
+function checkClass(env, pairs) {
+	checkConstructor(env);
+	for (const pair of pairs) checkPair(env, pair);
+}
+function checkConstructor(env) {
+	const ctor = findConstructor(env.classNode);
+	if (!ctor) return;
+	for (const add of collectListenerCalls(env, ctor, "addEventListener")) env.context.report({
+		node: add.node,
+		messageId: "listener-in-constructor",
+		data: {
+			target: add.target,
+			event: add.event
+		}
+	});
+}
+function checkPair(env, pair) {
+	const [setupName, teardownName] = pair;
+	const setup = findMethod(env.classNode, setupName);
+	if (!setup) return;
+	const addCalls = collectListenerCalls(env, setup, "addEventListener").filter((add) => !isSelfCleaningListenerCall(add.node));
+	if (addCalls.length === 0) return;
+	const teardown = findMethod(env.classNode, teardownName);
+	if (!teardown) {
+		env.context.report({
+			node: setup,
+			messageId: "missing-teardown",
+			data: {
+				setup: setupName,
+				teardown: teardownName
+			}
+		});
+		return;
+	}
+	reportUnmatched(env, {
+		addCalls,
+		removeCalls: collectListenerCalls(env, teardown, "removeEventListener"),
+		setupName,
+		teardownName
+	});
+}
+/**
+* An `addEventListener` call whose options argument statically guarantees the
+* listener detaches itself needs no paired `removeEventListener`:
+* `{ once: true }` self-removes after the first invocation, and `{ signal }`
+* delegates teardown to whatever aborts that `AbortSignal` - which commonly
+* lives outside the setup/teardown pair this rule pairs up, e.g. a shared
+* `AbortController` aborted from a different lifecycle hook entirely.
+* https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener#options
+*
+* Only a statically-analyzable options object exempts the call: an options
+* value that isn't an object literal (a boolean, an identifier, a spread-only
+* object) can't be proven self-cleaning here, so it keeps requiring a paired
+* `removeEventListener` rather than risk a false negative.
+*/
+function isSelfCleaningListenerCall(node) {
+	const optionsArg = node.arguments[2];
+	if (!optionsArg || optionsArg.type !== "ObjectExpression") return false;
+	return optionsArg.properties.some((property) => isAbortSignalProperty(property) || isOnceTrueProperty(property));
+}
+function isAbortSignalProperty(property) {
+	return getStaticPropertyName(property) === "signal";
+}
+function isOnceTrueProperty(property) {
+	if (property.type !== "Property" || getStaticPropertyName(property) !== "once") return false;
+	return property.value.type === "Literal" && property.value.value === true;
+}
+function getStaticPropertyName(property) {
+	if (property.type !== "Property" || property.computed) return null;
+	if (property.key.type === "Identifier") return property.key.name;
+	return property.key.type === "Literal" && typeof property.key.value === "string" ? property.key.value : null;
+}
+function reportUnmatched(env, check) {
+	for (const add of check.addCalls) if (!check.removeCalls.some((remove) => remove.target === add.target && remove.event === add.event)) env.context.report({
+		node: add.node,
+		messageId: "missing-cleanup",
+		data: {
+			target: add.target,
+			event: add.event,
+			setup: check.setupName,
+			teardown: check.teardownName
+		}
+	});
+}
+function findConstructor(classNode) {
+	for (const member of classNode.body.body) if (member.type === "MethodDefinition" && member.kind === "constructor") return member;
+	return null;
+}
+function findMethod(classNode, name) {
+	for (const member of classNode.body.body) if (isNamedMethod(member, name)) return member;
+	return null;
+}
+function isNamedMethod(member, name) {
+	return member.type === "MethodDefinition" && !member.static && member.key.type === "Identifier" && member.key.name === name;
+}
+/**
+* Collects `methodName` calls in `methodNode`'s own body, plus (depth-1 only)
+* calls made from any private helper method that `methodNode` calls directly
+* - the common pattern of a lifecycle method delegating to `#setup()`/`#teardown()`.
+*/
+function collectListenerCalls(env, methodNode, methodName) {
+	const results = collectInBody(env.context, methodNode.value.body, methodName);
+	const visited = /* @__PURE__ */ new Set([methodNode]);
+	walk(methodNode.value.body, (node) => {
+		if (node.type !== "CallExpression") return;
+		const resolved = resolvePrivateMethodCall(node, env.classNode);
+		if (!resolved || visited.has(resolved)) return;
+		visited.add(resolved);
+		results.push(...collectInBody(env.context, resolved.value.body, methodName));
+	});
+	return results;
+}
+function collectInBody(context, body, methodName) {
+	const results = [];
+	walk(body, (node) => {
+		if (node.type !== "CallExpression") return;
+		const call = matchListenerCall(context, node, methodName);
+		if (call) results.push(call);
+	});
+	return results;
+}
+function matchListenerCall(context, node, methodName) {
+	const callee = node.callee;
+	if (callee.type !== "MemberExpression") return null;
+	const property = callee.property;
+	if (property.type !== "Identifier" || property.name !== methodName) return null;
+	const eventArg = node.arguments[0];
+	if (!eventArg) return null;
+	return {
+		node,
+		target: normalize(context.sourceCode.getText(callee.object)),
+		event: normalize(context.sourceCode.getText(eventArg))
+	};
+}
+function resolvePrivateMethodCall(callNode, classNode) {
+	const callee = callNode.callee;
+	if (callee.type !== "MemberExpression") return null;
+	if (callee.object.type !== "ThisExpression" || callee.property.type !== "PrivateIdentifier") return null;
+	const name = callee.property.name;
+	for (const member of classNode.body.body) if (isPrivateMethod(member, name)) return member;
+	return null;
+}
+function isPrivateMethod(member, name) {
+	return member.type === "MethodDefinition" && !member.static && member.kind === "method" && member.key.type === "PrivateIdentifier" && member.key.name === name;
+}
+function getLifecyclePairs(context) {
+	const raw = context.options[0];
+	if (!hasLifecyclePairsField(raw) || !Array.isArray(raw.lifecyclePairs)) return DEFAULT_LIFECYCLE_PAIRS;
+	const pairs = raw.lifecyclePairs.filter(isLifecyclePair);
+	return pairs.length > 0 ? pairs : DEFAULT_LIFECYCLE_PAIRS;
+}
+function hasLifecyclePairsField(value) {
+	return typeof value === "object" && value !== null;
+}
+function isLifecyclePair(value) {
+	return Array.isArray(value) && value.length === 2 && typeof value[0] === "string" && typeof value[1] === "string";
+}
+//#endregion
+export { rule as default };

package/dist/eslint/rules/require-observer-cleanup.d.ts

@@ -0,0 +1,8 @@
+/**
+ * ESLint rule that flags observer instances (ResizeObserver, MutationObserver,
+ * IntersectionObserver, PerformanceObserver) whose reference is discarded,
+ * making disposal impossible.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/require-observer-cleanup.js

@@ -0,0 +1,69 @@
+import { findEnclosingClass } from "./utils.js";
+//#region src/eslint/rules/require-observer-cleanup.ts
+var OBSERVER_NAMES = /* @__PURE__ */ new Set([
+	"ResizeObserver",
+	"MutationObserver",
+	"IntersectionObserver",
+	"PerformanceObserver"
+]);
+var RETAINED_CONTAINER_TYPES = /* @__PURE__ */ new Set([
+	"ReturnStatement",
+	"ArrowFunctionExpression",
+	"ArrayExpression",
+	"SpreadElement"
+]);
+var rule = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Flags observer instances created without storing a reference, which prevents them from being disconnected.",
+			recommended: true
+		},
+		schema: [],
+		messages: { "inline-observer-leak": "The `{{kind}}` is created but its reference is discarded, so it can never be `.disconnect()`-ed. Assign it to a class field (e.g., `this.#observer = new {{kind}}(...)`) and call `this.#observer.disconnect()` in the teardown lifecycle method to prevent the callback from firing on a detached instance." }
+	},
+	create(context) {
+		return { NewExpression(node) {
+			if (node.callee.type !== "Identifier" || !OBSERVER_NAMES.has(node.callee.name)) return;
+			if (!findEnclosingClass(node)) return;
+			if (isReferenceRetained(node)) return;
+			context.report({
+				node,
+				messageId: "inline-observer-leak",
+				data: { kind: node.callee.name }
+			});
+		} };
+	}
+};
+function isReferenceRetained(node) {
+	const parent = node.parent;
+	if (isTransparentWrapper(parent, node)) return isReferenceRetained(parent);
+	if (RETAINED_CONTAINER_TYPES.has(parent.type)) return true;
+	if (isRetainedAssignmentTarget(parent, node)) return true;
+	return isRetainedCallArgument(parent, node);
+}
+/**
+* `?:` and `??`/`||` forward one operand through as their own result, so an
+* observer sitting in a forwarded branch is exactly as retained as the
+* wrapper expression - the caller re-runs the same retention check one level
+* up. A `ConditionalExpression` `test` is consumed for its boolean-ness, not
+* forwarded, so an observer there is still a discarded leak.
+*/
+function isTransparentWrapper(parent, node) {
+	if (parent.type === "ConditionalExpression") return parent.consequent === node || parent.alternate === node;
+	if (parent.type === "LogicalExpression") return parent.left === node || parent.right === node;
+	return false;
+}
+function isRetainedAssignmentTarget(parent, node) {
+	if (parent.type === "VariableDeclarator") return parent.init === node;
+	if (parent.type === "AssignmentExpression") return parent.right === node;
+	if (parent.type === "PropertyDefinition") return parent.value === node;
+	if (parent.type === "Property") return parent.value === node;
+	return false;
+}
+function isRetainedCallArgument(parent, node) {
+	if (parent.type === "CallExpression" || parent.type === "NewExpression") return parent.arguments.includes(node);
+	return false;
+}
+//#endregion
+export { rule as default };

package/dist/eslint/rules/require-timer-cleanup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * ESLint rule that flags timer leaks in class bodies: an unstored
+ * `setInterval` (which can never be cleared), a `setInterval` handle stored in
+ * a local variable that is never cleared or handed off, and stored
+ * `setInterval`/`setTimeout` handles that are never passed to a matching
+ * `clearInterval`/`clearTimeout` anywhere in the class.
+ */
+import type { Rule } from 'eslint';
+declare const rule: Rule.RuleModule;
+export default rule;

package/dist/eslint/rules/require-timer-cleanup.js

@@ -0,0 +1,142 @@
+import { findEnclosingClass, normalize, walk } from "./utils.js";
+//#region src/eslint/rules/require-timer-cleanup.ts
+var SET_FNS = /* @__PURE__ */ new Set(["setInterval", "setTimeout"]);
+var CLEAR_FNS = /* @__PURE__ */ new Set(["clearInterval", "clearTimeout"]);
+var rule = {
+	meta: {
+		type: "problem",
+		docs: {
+			description: "Flags setInterval without a stored handle, and stored setInterval/setTimeout calls whose handle is never cleared, in class bodies.",
+			recommended: true
+		},
+		schema: [],
+		messages: {
+			"unstoppable-interval": "`setInterval(...)` result is not stored, so the interval cannot be cleared. Assign it to a class field (e.g., `this.#intervalId = setInterval(...)`) and call `clearInterval(this.#intervalId)` in the teardown lifecycle method to stop the interval when the instance is torn down.",
+			"missing-timer-cleanup": "`{{fn}}(...)` result is stored on `{{target}}` but no matching `{{clear}}({{target}})` is called anywhere in the class. Clear the timer in the teardown lifecycle method so it does not fire after the instance is gone."
+		}
+	},
+	create(context) {
+		return { CallExpression(node) {
+			const fnName = getTimerFnName(node.callee);
+			if (!fnName) return;
+			const classNode = findEnclosingClass(node);
+			if (!classNode) return;
+			classifyAndReport(context, node, {
+				fnName,
+				classNode
+			});
+		} };
+	}
+};
+function getTimerFnName(callee) {
+	if (callee.type === "Identifier" && SET_FNS.has(callee.name)) return callee.name;
+	if (callee.type === "MemberExpression" && callee.property.type === "Identifier" && SET_FNS.has(callee.property.name)) return callee.property.name;
+	return null;
+}
+function classifyAndReport(context, callNode, info) {
+	const parent = callNode.parent;
+	const stored = getStoredMemberText(parent, callNode, context);
+	if (stored) {
+		reportIfNotCleared(context, callNode, {
+			...info,
+			stored
+		});
+		return;
+	}
+	if (info.fnName !== "setInterval") return;
+	if (parent.type === "ExpressionStatement") {
+		context.report({
+			node: callNode,
+			messageId: "unstoppable-interval"
+		});
+		return;
+	}
+	const localHandle = getLocalIntervalHandleDeclarator(parent, callNode);
+	if (localHandle && !localIntervalHandleIsClearedOrEscapes(context, localHandle)) context.report({
+		node: callNode,
+		messageId: "unstoppable-interval"
+	});
+}
+function reportIfNotCleared(context, callNode, info) {
+	const clearName = info.fnName === "setInterval" ? "clearInterval" : "clearTimeout";
+	if (classHasClearForTarget(info.classNode, {
+		clearName,
+		targetText: info.stored
+	}, context)) return;
+	context.report({
+		node: callNode,
+		messageId: "missing-timer-cleanup",
+		data: {
+			fn: info.fnName,
+			target: info.stored,
+			clear: clearName
+		}
+	});
+}
+function getStoredMemberText(parent, callNode, context) {
+	if (parent.type === "AssignmentExpression" && parent.right === callNode) return thisMemberText(parent.left, context);
+	if (parent.type === "PropertyDefinition" && parent.value === callNode) return propertyDefinitionAsThisMember(parent, context);
+	return null;
+}
+function thisMemberText(node, context) {
+	if (node.type !== "MemberExpression") return null;
+	if (node.object.type !== "ThisExpression") return null;
+	return normalize(context.sourceCode.getText(node));
+}
+function propertyDefinitionAsThisMember(node, context) {
+	if (node.static) return null;
+	const key = node.key;
+	if (key.type === "PrivateIdentifier") return `this.#${key.name}`;
+	if (key.type === "Identifier") return `this.${key.name}`;
+	return `this[${context.sourceCode.getText(key)}]`;
+}
+/**
+* Matches `const id = setInterval(...)` (any of `const`/`let`/`var`), where
+* the handle is bound to a plain identifier rather than destructured. A
+* destructuring pattern can't be resolved back to a single traceable binding
+* here, so it falls outside this rule's scope-analysis path.
+*/
+function getLocalIntervalHandleDeclarator(parent, callNode) {
+	if (parent.type !== "VariableDeclarator" || parent.init !== callNode || parent.id.type !== "Identifier") return null;
+	return parent;
+}
+/**
+* A local interval handle is safe to leave unstored-on-`this` when every use
+* of the binding shows the handle is either cleared or handed off before the
+* enclosing function returns: passed to any call (`clearInterval(id)`, or an
+* external owner like `registry.track(id)`), returned to the caller, or
+* assigned onward to a longer-lived reference (`this.#timer = id`). Uses scope
+* analysis (rather than walking the enclosing function's AST) so a reference
+* inside the interval's own callback - a closure over the binding - still
+* resolves back to the same variable.
+*/
+function localIntervalHandleIsClearedOrEscapes(context, declarator) {
+	const [handleVariable] = context.sourceCode.getDeclaredVariables(declarator);
+	if (!handleVariable) return true;
+	return handleVariable.references.some((reference) => referenceClearsOrReleasesHandle(reference));
+}
+function referenceClearsOrReleasesHandle(reference) {
+	const identifier = reference.identifier;
+	const parent = identifier.parent;
+	if (parent.type === "CallExpression") return parent.arguments.includes(identifier);
+	if (parent.type === "ReturnStatement") return parent.argument === identifier;
+	if (parent.type === "AssignmentExpression") return parent.right === identifier;
+	return false;
+}
+function classHasClearForTarget(classNode, search, context) {
+	let found = false;
+	walk(classNode.body, (node) => {
+		if (found || node.type !== "CallExpression") return;
+		if (getClearFnName(node.callee) !== search.clearName) return;
+		const firstArg = node.arguments[0];
+		if (firstArg && normalize(context.sourceCode.getText(firstArg)) === search.targetText) found = true;
+	});
+	return found;
+}
+function getClearFnName(callee) {
+	if (callee.type === "Identifier" && CLEAR_FNS.has(callee.name)) return callee.name;
+	if (callee.type === "MemberExpression" && callee.property.type === "Identifier" && CLEAR_FNS.has(callee.property.name)) return callee.property.name;
+	return null;
+}
+//#endregion
+export { rule as default };

package/dist/eslint/rules/utils.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared helpers for rules that need to reason about AST shape generically
+ * (walking a subtree, matching normalized text), about lexical scope (which
+ * class a node lives in), or about the filesystem (listing a package's source
+ * files, reading them safely). Extracted so that logic stays consistent
+ * across the `tools/*` rules that build on top of them.
+ */
+import type { Rule } from 'eslint';
+/**
+ * Recursively visits every node reachable from `node`, in no particular
+ * guaranteed order beyond depth-first. Skips the `parent` back-pointer (every
+ * node points back to its parent, so following it would recurse forever) and
+ * descends into arrays of children and into single child nodes.
+ */
+export declare function walk(node: unknown, visit: (node: Rule.Node) => void): void;
+/** Collapses internal whitespace so multi-line source text matches regardless of formatting. */
+export declare function normalize(text: string): string;
+type ClassNode = Extract<Rule.Node, {
+    type: 'ClassDeclaration' | 'ClassExpression';
+}>;
+/**
+ * Walks up `.parent` looking for the nearest enclosing class. Returns `null`
+ * when `node` lives at module scope (or otherwise outside any class body).
+ */
+export declare function findEnclosingClass(node: Rule.Node): ClassNode | null;
+/** Directories skipped by every recursive package-file listing, regardless of rule config. */
+export declare const IMPLICIT_EXCLUDED_DIRS: readonly string[];
+/**
+ * Milliseconds a package's recursive file listing stays cached before
+ * {@link getPackageFiles} recomputes it. Long enough to amortize repeated
+ * lookups across every candidate class linted within one file and across one
+ * lint pass; short enough that a long-lived ESLint process (IDE language
+ * server, `eslint_d`, watch mode) reflects a file added or removed on disk
+ * within about one save-and-relint cycle instead of requiring a restart.
+ */
+export declare const FILE_CACHE_TTL_MS = 5000;
+/** Every file under `root`, recursively, excluding {@link IMPLICIT_EXCLUDED_DIRS}. Cached per root. */
+export declare function getPackageFiles(root: string): readonly string[];
+/** Reads `file` as UTF-8, or `null` when it doesn't exist or isn't readable. */
+export declare function readFileSafe(file: string): string | null;
+/** Parses `text` as JSON, or `null` when it isn't valid JSON. */
+export declare function tryParseJson(text: string): unknown;
+/** Converts a `file://` URL or OS-native path to a forward-slash path for cross-platform text matching. */
+export declare function normalizePath(filepath: string): string;
+export {};

package/dist/eslint/rules/utils.js

@@ -0,0 +1,109 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/eslint/rules/utils.ts
+/**
+* Shared helpers for rules that need to reason about AST shape generically
+* (walking a subtree, matching normalized text), about lexical scope (which
+* class a node lives in), or about the filesystem (listing a package's source
+* files, reading them safely). Extracted so that logic stays consistent
+* across the `tools/*` rules that build on top of them.
+*/
+/** Narrows an unknown value to `AstNode` without asserting anything about it. */
+function isAstNode(value) {
+	return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+/**
+* Recursively visits every node reachable from `node`, in no particular
+* guaranteed order beyond depth-first. Skips the `parent` back-pointer (every
+* node points back to its parent, so following it would recurse forever) and
+* descends into arrays of children and into single child nodes.
+*/
+function walk(node, visit) {
+	if (!isAstNode(node)) return;
+	visit(node);
+	for (const key of Object.keys(node)) {
+		if (key === "parent") continue;
+		const child = node[key];
+		if (Array.isArray(child)) for (const item of child) walk(item, visit);
+		else if (isAstNode(child)) walk(child, visit);
+	}
+}
+/** Collapses internal whitespace so multi-line source text matches regardless of formatting. */
+function normalize(text) {
+	return text.replace(/\s+/g, " ").trim();
+}
+/**
+* Walks up `.parent` looking for the nearest enclosing class. Returns `null`
+* when `node` lives at module scope (or otherwise outside any class body).
+*/
+function findEnclosingClass(node) {
+	let current = node.parent;
+	while (current) {
+		if (current.type === "ClassDeclaration" || current.type === "ClassExpression") return current;
+		current = current.parent;
+	}
+	return null;
+}
+/** Directories skipped by every recursive package-file listing, regardless of rule config. */
+var IMPLICIT_EXCLUDED_DIRS = ["node_modules", "dist"];
+/**
+* Milliseconds a package's recursive file listing stays cached before
+* {@link getPackageFiles} recomputes it. Long enough to amortize repeated
+* lookups across every candidate class linted within one file and across one
+* lint pass; short enough that a long-lived ESLint process (IDE language
+* server, `eslint_d`, watch mode) reflects a file added or removed on disk
+* within about one save-and-relint cycle instead of requiring a restart.
+*/
+var FILE_CACHE_TTL_MS = 5e3;
+/** Recursive file listing per package root, cached for {@link FILE_CACHE_TTL_MS}. */
+var FILE_CACHE = /* @__PURE__ */ new Map();
+/** Every file under `root`, recursively, excluding {@link IMPLICIT_EXCLUDED_DIRS}. Cached per root. */
+function getPackageFiles(root) {
+	const key = normalizePath(root);
+	const cached = FILE_CACHE.get(key);
+	const now = Date.now();
+	if (cached !== void 0 && now - cached.cachedAtMs < 5e3) return cached.files;
+	const files = collectFilesSafe(key).map(normalizePath);
+	FILE_CACHE.set(key, {
+		files,
+		cachedAtMs: now
+	});
+	return files;
+}
+function collectFilesSafe(dir) {
+	return readDirSafe(dir).flatMap((entry) => collectEntry(dir, entry));
+}
+function collectEntry(dir, entry) {
+	if (entry.isDirectory()) return IMPLICIT_EXCLUDED_DIRS.includes(entry.name) ? [] : collectFilesSafe(join(dir, entry.name));
+	return entry.isFile() ? [join(dir, entry.name)] : [];
+}
+function readDirSafe(dir) {
+	try {
+		return readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+}
+/** Reads `file` as UTF-8, or `null` when it doesn't exist or isn't readable. */
+function readFileSafe(file) {
+	try {
+		return readFileSync(file, "utf8");
+	} catch {
+		return null;
+	}
+}
+/** Parses `text` as JSON, or `null` when it isn't valid JSON. */
+function tryParseJson(text) {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return null;
+	}
+}
+/** Converts a `file://` URL or OS-native path to a forward-slash path for cross-platform text matching. */
+function normalizePath(filepath) {
+	return (filepath.startsWith("file://") ? fileURLToPath(filepath) : filepath).replaceAll(sep, "/");
+}
+//#endregion
+export { FILE_CACHE_TTL_MS, IMPLICIT_EXCLUDED_DIRS, findEnclosingClass, getPackageFiles, normalize, normalizePath, readFileSafe, tryParseJson, walk };

package/dist/prettier/index.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from 'prettier';
+/**
+ * Personal Prettier preferences, shared across projects so formatting stops
+ * being a per-repo decision. Point `package.json`'s `"prettier"` field at
+ * `"@coryrylan/tools/prettier"` to consume it directly, or import this
+ * default export and spread it into a local `prettier.config.js` to layer
+ * project-specific overrides on top.
+ *
+ * `embeddedLanguageFormatting: 'off'` is deliberate: embedded template
+ * literals (Lit `html`/`css` tagged templates) are hand-formatted rather
+ * than reflowed by Prettier's embedded-language support, which tends to
+ * mangle multi-line markup readability.
+ */
+declare const config: Config;
+export default config;

package/dist/prettier/index.js

@@ -0,0 +1,26 @@
+//#region src/prettier/index.ts
+/**
+* Personal Prettier preferences, shared across projects so formatting stops
+* being a per-repo decision. Point `package.json`'s `"prettier"` field at
+* `"@coryrylan/tools/prettier"` to consume it directly, or import this
+* default export and spread it into a local `prettier.config.js` to layer
+* project-specific overrides on top.
+*
+* `embeddedLanguageFormatting: 'off'` is deliberate: embedded template
+* literals (Lit `html`/`css` tagged templates) are hand-formatted rather
+* than reflowed by Prettier's embedded-language support, which tends to
+* mangle multi-line markup readability.
+*/
+var config = {
+	trailingComma: "none",
+	tabWidth: 2,
+	printWidth: 120,
+	semi: true,
+	singleQuote: true,
+	arrowParens: "avoid",
+	bracketSameLine: true,
+	embeddedLanguageFormatting: "off",
+	singleAttributePerLine: false
+};
+//#endregion
+export { config as default };

package/dist/stylelint/index.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from 'stylelint';
+/**
+ * Personal Stylelint preferences layered on `stylelint-config-standard`.
+ * Point a `stylelint.config.js` at it with
+ * `export { default } from '@coryrylan/tools/stylelint';`, or import the
+ * default export and add `rules`/`overrides` on top for project-specific
+ * exceptions.
+ */
+declare const config: Config;
+export default config;