@logtape/lint 2.2.0-dev.0

package/dist/deno/plugin.cjs

@@ -0,0 +1,332 @@
+const require_ast = require('../core/ast.cjs');
+
+//#region src/deno/plugin.ts
+function extractIdentifiers(node, names) {
+	if (!node) return;
+	if (node.type === "Identifier") names.add(node.name);
+	else if (node.type === "ObjectPattern") {
+		for (const prop of node.properties ?? []) if (prop.type === "Property") extractIdentifiers(prop.value, names);
+		else if (prop.type === "RestElement") extractIdentifiers(prop.argument, names);
+	} else if (node.type === "ArrayPattern") for (const elem of node.elements ?? []) extractIdentifiers(elem, names);
+	else if (node.type === "AssignmentPattern") extractIdentifiers(node.left, names);
+	else if (node.type === "RestElement") extractIdentifiers(node.argument, names);
+	else if (node.type === "TSParameterProperty") extractIdentifiers(node.parameter, names);
+}
+/**
+* Creates a scope tracker for LogTape logger variable bindings.
+*
+* The Deno Lint plugin API does not expose a scope manager, so this hand-rolls
+* one with a scope stack (Map<name, isLogger>) to correctly handle:
+* - Function parameters that shadow logger names (tracked as false)
+* - Local variables that re-declare logger names with non-logger values
+* - Block scoping via BlockStatement enter/exit
+*
+* Returns a `visitors` object to spread into a rule's visitor map, plus the
+* scope-aware predicates the rule's `CallExpression` handler needs.
+*/
+function makeLoggerScope() {
+	const getterNames = /* @__PURE__ */ new Set();
+	const lazyNames = /* @__PURE__ */ new Set();
+	const scopeStack = [/* @__PURE__ */ new Map()];
+	const shadowedGetterStack = [/* @__PURE__ */ new Set()];
+	const shadowedLazyStack = [/* @__PURE__ */ new Set()];
+	const asyncFnStack = [/* @__PURE__ */ new Map()];
+	function pushScope() {
+		scopeStack.push(/* @__PURE__ */ new Map());
+		shadowedGetterStack.push(/* @__PURE__ */ new Set());
+		shadowedLazyStack.push(/* @__PURE__ */ new Set());
+		asyncFnStack.push(/* @__PURE__ */ new Map());
+	}
+	function popScope() {
+		if (scopeStack.length > 1) scopeStack.pop();
+		if (shadowedGetterStack.length > 1) shadowedGetterStack.pop();
+		if (shadowedLazyStack.length > 1) shadowedLazyStack.pop();
+		if (asyncFnStack.length > 1) asyncFnStack.pop();
+	}
+	function isLoggerName(name) {
+		for (let i = scopeStack.length - 1; i >= 0; i--) if (scopeStack[i].has(name)) return scopeStack[i].get(name);
+		return false;
+	}
+	function isAsyncFunctionName(name) {
+		for (let i = asyncFnStack.length - 1; i >= 0; i--) if (asyncFnStack[i].has(name)) return asyncFnStack[i].get(name);
+		return false;
+	}
+	function isGetterShadowed(name) {
+		for (let i = shadowedGetterStack.length - 1; i >= 0; i--) if (shadowedGetterStack[i].has(name)) return true;
+		return false;
+	}
+	function isLazyShadowed(name) {
+		for (let i = shadowedLazyStack.length - 1; i >= 0; i--) if (shadowedLazyStack[i].has(name)) return true;
+		return false;
+	}
+	function recordImportShadow(name) {
+		shadowedGetterStack[shadowedGetterStack.length - 1].add(name);
+		shadowedLazyStack[shadowedLazyStack.length - 1].add(name);
+	}
+	function effectiveLazyNames() {
+		if (lazyNames.size === 0) return lazyNames;
+		const result = /* @__PURE__ */ new Set();
+		for (const name of lazyNames) if (!isLazyShadowed(name)) result.add(name);
+		return result;
+	}
+	function handleFunctionEnter(node) {
+		if (node.type === "FunctionDeclaration" && node.id?.type === "Identifier") {
+			recordImportShadow(node.id.name);
+			scopeStack[scopeStack.length - 1].set(node.id.name, false);
+			asyncFnStack[asyncFnStack.length - 1].set(node.id.name, node.async === true || require_ast.isPromiseReturningCallback(node));
+		}
+		pushScope();
+		const names = /* @__PURE__ */ new Set();
+		if (node.type === "FunctionExpression" && node.id?.type === "Identifier") names.add(node.id.name);
+		for (const param of node.params ?? []) extractIdentifiers(param, names);
+		for (const name of names) {
+			scopeStack[scopeStack.length - 1].set(name, false);
+			recordImportShadow(name);
+			asyncFnStack[asyncFnStack.length - 1].set(name, false);
+		}
+	}
+	function handleBlockEnter(node) {
+		pushScope();
+		for (const stmt of node.body ?? []) if (stmt?.type === "FunctionDeclaration" && stmt.id?.type === "Identifier") {
+			recordImportShadow(stmt.id.name);
+			scopeStack[scopeStack.length - 1].set(stmt.id.name, false);
+			asyncFnStack[asyncFnStack.length - 1].set(stmt.id.name, stmt.async === true || require_ast.isPromiseReturningCallback(stmt));
+		}
+	}
+	function handleCatchEnter(node) {
+		pushScope();
+		if (!node.param) return;
+		const names = /* @__PURE__ */ new Set();
+		extractIdentifiers(node.param, names);
+		for (const name of names) {
+			scopeStack[scopeStack.length - 1].set(name, false);
+			recordImportShadow(name);
+			asyncFnStack[asyncFnStack.length - 1].set(name, false);
+		}
+	}
+	function isLoggerExpr(node, depth = 0) {
+		if (depth > 16 || !node) return false;
+		if (node.type === "CallExpression" && node.callee?.type === "Identifier" && getterNames.has(node.callee.name) && !isGetterShadowed(node.callee.name)) return true;
+		if (node.type === "CallExpression" && node.callee?.type === "MemberExpression" && !node.callee.computed && node.callee.property?.type === "Identifier" && (node.callee.property.name === "with" || node.callee.property.name === "getChild")) return isLoggerExpr(node.callee.object, depth + 1);
+		if (node.type === "Identifier") return isLoggerName(node.name);
+		return false;
+	}
+	function isLogtapeCallee(callee) {
+		if (!callee || callee.type !== "MemberExpression") return false;
+		return isLoggerExpr(callee.object);
+	}
+	return {
+		visitors: {
+			ImportDeclaration(node) {
+				if (!require_ast.isLogtapeImportSource(node.source?.value)) return;
+				for (const spec of node.specifiers ?? []) {
+					if (spec.type !== "ImportSpecifier") continue;
+					if (spec.imported?.name === "getLogger") getterNames.add(spec.local?.name);
+					else if (spec.imported?.name === "lazy") lazyNames.add(spec.local?.name);
+				}
+			},
+			VariableDeclarator(node) {
+				if (node.id?.type === "Identifier") {
+					const name = node.id.name;
+					const init = node.init;
+					const isLogger = isLoggerExpr(init);
+					if (isLogger) scopeStack[scopeStack.length - 1].set(name, true);
+					else if (isLoggerName(name)) scopeStack[scopeStack.length - 1].set(name, false);
+					recordImportShadow(name);
+					asyncFnStack[asyncFnStack.length - 1].set(name, require_ast.isAsyncFunctionExpr(init) || require_ast.isPromiseReturningCallback(init));
+				} else {
+					const names = /* @__PURE__ */ new Set();
+					extractIdentifiers(node.id, names);
+					for (const name of names) {
+						if (isLoggerName(name)) scopeStack[scopeStack.length - 1].set(name, false);
+						recordImportShadow(name);
+						asyncFnStack[asyncFnStack.length - 1].set(name, false);
+					}
+				}
+			},
+			FunctionDeclaration: handleFunctionEnter,
+			"FunctionDeclaration:exit": popScope,
+			FunctionExpression: handleFunctionEnter,
+			"FunctionExpression:exit": popScope,
+			ArrowFunctionExpression: handleFunctionEnter,
+			"ArrowFunctionExpression:exit": popScope,
+			Program: handleBlockEnter,
+			"Program:exit": popScope,
+			BlockStatement: handleBlockEnter,
+			"BlockStatement:exit": popScope,
+			TSModuleBlock: handleBlockEnter,
+			"TSModuleBlock:exit": popScope,
+			ForStatement: pushScope,
+			"ForStatement:exit": popScope,
+			ForInStatement: pushScope,
+			"ForInStatement:exit": popScope,
+			ForOfStatement: pushScope,
+			"ForOfStatement:exit": popScope,
+			SwitchStatement: pushScope,
+			"SwitchStatement:exit": popScope,
+			CatchClause: handleCatchEnter,
+			"CatchClause:exit": popScope
+		},
+		isLogtapeCallee,
+		isAsyncFunctionName,
+		lazyNames,
+		effectiveLazyNames
+	};
+}
+/**
+* Deno Lint plugin providing LogTape lint rules.
+*
+* > [!WARNING]
+* > The Deno Lint plugin API is experimental.  This plugin may break between
+* > Deno releases while the API is stabilised.
+*/
+const logtapePlugin = {
+	name: "logtape",
+	rules: {
+		"no-message-interpolation": { create(ctx) {
+			const scope = makeLoggerScope();
+			return {
+				...scope.visitors,
+				CallExpression(node) {
+					if (!scope.isLogtapeCallee(node.callee)) return;
+					const methodName = require_ast.logMethodName(node.callee);
+					if (!methodName || !require_ast.LOG_METHODS.has(methodName)) return;
+					const firstArg = require_ast.unwrapTypeAssertion(node.arguments?.[0]);
+					if (!firstArg || firstArg.type !== "TemplateLiteral") return;
+					if (!firstArg.expressions?.length) return;
+					ctx.report({
+						node: firstArg,
+						message: "Avoid using template literal interpolation in log messages. Use a message template string with structured properties instead: logger.info(\"User {userId} logged in.\", { userId })."
+					});
+				}
+			};
+		} },
+		"prefer-lazy-evaluation": { create(ctx) {
+			const scope = makeLoggerScope();
+			return {
+				...scope.visitors,
+				CallExpression(node) {
+					if (!scope.isLogtapeCallee(node.callee)) return;
+					const methodName = require_ast.logMethodName(node.callee);
+					if (!methodName || !require_ast.LOG_METHODS.has(methodName)) return;
+					const selected = require_ast.selectLazyPropsObject(node.arguments);
+					if (!selected) return;
+					const { propsObject, fixTarget, propertiesOnly } = selected;
+					if (!require_ast.propsHaveEagerCall(propsObject, scope.effectiveLazyNames())) return;
+					const hasAsyncSyntax = require_ast.containsAwaitOrYield(propsObject);
+					ctx.report({
+						node: propsObject,
+						message: "Wrap the properties object in a lazy callback to avoid unnecessary computation: logger.debug(\"msg\", () => ({ ... })).",
+						fix: hasAsyncSyntax ? void 0 : (fixer) => {
+							const sourceCode = ctx.sourceCode ?? ctx.getSourceCode?.();
+							const text = typeof sourceCode === "string" && fixTarget.range ? sourceCode.slice(fixTarget.range[0], fixTarget.range[1]) : sourceCode?.getText?.(fixTarget);
+							if (!text) return null;
+							return fixer.replaceText(fixTarget, propertiesOnly ? `"{*}", () => (${text})` : `() => (${text})`);
+						}
+					});
+				}
+			};
+		} },
+		"no-unawaited-log": { create(ctx) {
+			const scope = makeLoggerScope();
+			return {
+				...scope.visitors,
+				CallExpression(node) {
+					if (!scope.isLogtapeCallee(node.callee)) return;
+					const methodName = require_ast.logMethodName(node.callee);
+					if (!methodName || !require_ast.LOG_METHODS.has(methodName)) return;
+					const secondArg = require_ast.unwrapTypeAssertion(node.arguments?.[1]);
+					if (!secondArg) return;
+					const isAsyncCallback = require_ast.isAsyncFunctionExpr(secondArg) || require_ast.isPromiseReturningCallback(secondArg) || secondArg.type === "Identifier" && scope.isAsyncFunctionName(secondArg.name);
+					if (!isAsyncCallback) return;
+					if (require_ast.isLogPromiseHandled(node)) return;
+					ctx.report({
+						node,
+						message: "Async lazy callbacks must be awaited to ensure the log is flushed: await logger.debug(\"msg\", async () => ({ ... })).",
+						fix: require_ast.canInsertAwait(node) ? (fixer) => fixer.insertTextBefore(node, "await ") : void 0
+					});
+				}
+			};
+		} },
+		"require-meta-sink": { create(ctx) {
+			const configFns = /* @__PURE__ */ new Set();
+			const shadowedConfigScopes = [/* @__PURE__ */ new Set()];
+			function pushConfigScope() {
+				shadowedConfigScopes.push(/* @__PURE__ */ new Set());
+			}
+			function popConfigScope() {
+				if (shadowedConfigScopes.length > 1) shadowedConfigScopes.pop();
+			}
+			function isConfigShadowed(name) {
+				for (let i = shadowedConfigScopes.length - 1; i >= 0; i--) if (shadowedConfigScopes[i].has(name)) return true;
+				return false;
+			}
+			function handleFnEnter(node) {
+				if (node.type === "FunctionDeclaration" && node.id?.type === "Identifier" && configFns.has(node.id.name)) shadowedConfigScopes[shadowedConfigScopes.length - 1].add(node.id.name);
+				pushConfigScope();
+				const names = /* @__PURE__ */ new Set();
+				if (node.type === "FunctionExpression" && node.id?.type === "Identifier") names.add(node.id.name);
+				for (const param of node.params ?? []) extractIdentifiers(param, names);
+				for (const name of names) if (configFns.has(name)) shadowedConfigScopes[shadowedConfigScopes.length - 1].add(name);
+			}
+			function handleBlockEnter(node) {
+				pushConfigScope();
+				for (const stmt of node.body ?? []) if (stmt?.type === "FunctionDeclaration" && stmt.id?.type === "Identifier") shadowedConfigScopes[shadowedConfigScopes.length - 1].add(stmt.id.name);
+			}
+			function handleCatchEnter(node) {
+				pushConfigScope();
+				if (!node.param) return;
+				const names = /* @__PURE__ */ new Set();
+				extractIdentifiers(node.param, names);
+				for (const name of names) if (configFns.has(name)) shadowedConfigScopes[shadowedConfigScopes.length - 1].add(name);
+			}
+			return {
+				ImportDeclaration(node) {
+					if (!require_ast.isLogtapeImportSource(node.source?.value)) return;
+					for (const specifier of node.specifiers ?? []) {
+						if (specifier.type !== "ImportSpecifier") continue;
+						const imported = specifier.imported?.name;
+						if (imported === "configure" || imported === "configureSync") configFns.add(specifier.local?.name);
+					}
+				},
+				FunctionDeclaration: handleFnEnter,
+				"FunctionDeclaration:exit": popConfigScope,
+				FunctionExpression: handleFnEnter,
+				"FunctionExpression:exit": popConfigScope,
+				ArrowFunctionExpression: handleFnEnter,
+				"ArrowFunctionExpression:exit": popConfigScope,
+				Program: handleBlockEnter,
+				"Program:exit": popConfigScope,
+				BlockStatement: handleBlockEnter,
+				"BlockStatement:exit": popConfigScope,
+				TSModuleBlock: handleBlockEnter,
+				"TSModuleBlock:exit": popConfigScope,
+				SwitchStatement: pushConfigScope,
+				"SwitchStatement:exit": popConfigScope,
+				CatchClause: handleCatchEnter,
+				"CatchClause:exit": popConfigScope,
+				VariableDeclarator(node) {
+					const names = /* @__PURE__ */ new Set();
+					extractIdentifiers(node.id, names);
+					for (const name of names) if (configFns.has(name)) shadowedConfigScopes[shadowedConfigScopes.length - 1].add(name);
+				},
+				CallExpression(node) {
+					if (configFns.size === 0) return;
+					const { callee } = node;
+					const calleeName = callee.type === "Identifier" ? callee.name : null;
+					if (!calleeName || !configFns.has(calleeName)) return;
+					if (isConfigShadowed(calleeName)) return;
+					const configArg = require_ast.unwrapTypeAssertion(node.arguments?.[0]);
+					if (require_ast.configNeedsMetaSink(configArg)) ctx.report({
+						node,
+						message: "Add a dedicated sink for the meta logger (category: [\"logtape\"] or [\"logtape\", \"meta\"]) to handle LogTape's own diagnostic messages."
+					});
+				}
+			};
+		} }
+	}
+};
+var plugin_default = logtapePlugin;
+
+//#endregion
+module.exports = plugin_default;

package/dist/deno/plugin.d.cts

@@ -0,0 +1,46 @@
+//#region src/deno/plugin.d.ts
+/**
+ * Deno Lint plugin for LogTape lint rules.
+ *
+ * > [!NOTE]
+ * > The Deno Lint plugin API is currently experimental (unstable).
+ * > This plugin requires Deno 2.2.0 or later with the `--unstable-lint` flag
+ * > or the `"unstable": ["lint"]` option in your `deno.json`.
+ *
+ * Add this plugin to your `deno.json`:
+ * ```json
+ * {
+ *   "lint": {
+ *     "plugins": ["jsr:@logtape/lint/deno"],
+ *     "rules": {
+ *       "include": [
+ *         "logtape/no-message-interpolation",
+ *         "logtape/prefer-lazy-evaluation",
+ *         "logtape/no-unawaited-log",
+ *         "logtape/require-meta-sink"
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The rule detection logic is shared with the ESLint rules via `../core/ast.ts`;
+ * only the scope tracking (which the Deno Lint API does not provide a manager
+ * for) and the report/fix wiring are implemented here.
+ *
+ * @module
+ */
+/**
+ * Deno Lint plugin providing LogTape lint rules.
+ *
+ * > [!WARNING]
+ * > The Deno Lint plugin API is experimental.  This plugin may break between
+ * > Deno releases while the API is stabilised.
+ */
+declare const logtapePlugin: {
+  name: string;
+  rules: Record<string, unknown>;
+};
+//#endregion
+export { logtapePlugin as default };
+//# sourceMappingURL=plugin.d.cts.map

package/dist/deno/plugin.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.cts","names":[],"sources":["../../src/deno/plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4YM;;SAAsC"}

package/dist/deno/plugin.d.ts

@@ -0,0 +1,46 @@
+//#region src/deno/plugin.d.ts
+/**
+ * Deno Lint plugin for LogTape lint rules.
+ *
+ * > [!NOTE]
+ * > The Deno Lint plugin API is currently experimental (unstable).
+ * > This plugin requires Deno 2.2.0 or later with the `--unstable-lint` flag
+ * > or the `"unstable": ["lint"]` option in your `deno.json`.
+ *
+ * Add this plugin to your `deno.json`:
+ * ```json
+ * {
+ *   "lint": {
+ *     "plugins": ["jsr:@logtape/lint/deno"],
+ *     "rules": {
+ *       "include": [
+ *         "logtape/no-message-interpolation",
+ *         "logtape/prefer-lazy-evaluation",
+ *         "logtape/no-unawaited-log",
+ *         "logtape/require-meta-sink"
+ *       ]
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * The rule detection logic is shared with the ESLint rules via `../core/ast.ts`;
+ * only the scope tracking (which the Deno Lint API does not provide a manager
+ * for) and the report/fix wiring are implemented here.
+ *
+ * @module
+ */
+/**
+ * Deno Lint plugin providing LogTape lint rules.
+ *
+ * > [!WARNING]
+ * > The Deno Lint plugin API is experimental.  This plugin may break between
+ * > Deno releases while the API is stabilised.
+ */
+declare const logtapePlugin: {
+  name: string;
+  rules: Record<string, unknown>;
+};
+//#endregion
+export { logtapePlugin as default };
+//# sourceMappingURL=plugin.d.ts.map

package/dist/deno/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../src/deno/plugin.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA4YM;;SAAsC"}