@askrjs/cli 0.0.12 → 0.0.14

package/README.md

@@ -49,6 +49,7 @@ unless you opt out with `--no-skills`.
 - `askr skills install [--cwd <dir>] [--force]`
 - `askr skills sync [--cwd <dir>]`
 - `askr ssg --config <path> --output <dir> [--incremental]`
+- `askr verify-hydration [--output ./dist] [--route <path>]...`
 - `askr openapi [--entry ./src/api.ts] [--output ./openapi.yml] [--check]`
 - `askr outdated [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
 - `askr update [packages...] [--workspace <glob>] [--tag <tag>] [--json]`
@@ -140,6 +141,24 @@ owned files so stale chunks and previous output paths are removed. Full and
 incremental builds publish through a sibling staging directory, so route output,
 metadata, assets, and sitemap artifacts change together or not at all.
 
+## Hydration verification
+
+`askr verify-hydration` builds SSG output, serves the generated route set, and
+loads every successful metadata route in a real headless browser both with and
+without JavaScript. It compares normalized tag-and-child topology under `#app`
+after hydration, so text, classes, and mutable ARIA state do not create noise
+while nodes migrating into the wrong sibling container fail with an actionable
+static-versus-hydrated path diff.
+
+```bash
+askr verify-hydration
+askr verify-hydration --route / --route /docs
+askr verify-hydration --no-build --output ./dist
+```
+
+See the [hydration verification reference](./docs/verify-hydration.md) for
+browser installation, timeout, route, and root-selector options.
+
 ## OpenAPI artifacts
 
 `askr openapi` loads a TypeScript module whose default export exposes

package/dist/analyze.js

@@ -71,7 +71,7 @@ async function runAnalyzeCli(args = process.argv.slice(2), io = console, runtime
 			io.log(helpText.trimEnd());
 			return 0;
 		}
-		const report = await (runtime.analyze ?? (await import("./runner-BRjjPhZY.js")).runAnalysis)({
+		const report = await (runtime.analyze ?? (await import("./runner-BSs9Ow3t.js")).runAnalysis)({
 			cwd: parsed.cwd,
 			workspacePatterns: parsed.workspacePatterns,
 			check: parsed.check

package/dist/cli.js

@@ -41,6 +41,7 @@ function printHelp(io = console) {
 	io.log("  openapi    Generate or check an OpenAPI YAML artifact");
 	io.log("  skills     Install or sync Askr agent skills");
 	io.log("  ssg        Run static-site generation");
+	io.log("  verify-hydration  Verify SSG DOM structure in a real browser");
 	io.log("  outdated   List available dependency updates");
 	io.log("  repair     Apply safe fixes and identify remaining semantic work");
 	io.log("  update     Apply safe dependency updates");
@@ -63,6 +64,7 @@ function printHelp(io = console) {
 	io.log("  askr openapi --check");
 	io.log("  askr skills review foundation --cwd ./candidate-app");
 	io.log("  askr ssg --config ./ssg.config.ts --output ./dist/static");
+	io.log("  askr verify-hydration --output ./dist --route /");
 	io.log("  askr outdated");
 	io.log("  askr update");
 	io.log("  askr upgrade");
@@ -90,7 +92,7 @@ async function runCli(args = process.argv.slice(2), io = console) {
 		return runAnalyzeCli(args.slice(1), io);
 	}
 	if (command === "check" || command === "doctor" || command === "repair") {
-		const { runGuardrailCli } = await import("./guardrails-GPM9PJqO.js");
+		const { runGuardrailCli } = await import("./guardrails-D6KCKS-H.js");
 		return runGuardrailCli(command, args.slice(1), io);
 	}
 	if (command === "generate") {
@@ -101,6 +103,10 @@ async function runCli(args = process.argv.slice(2), io = console) {
 		const { runSsgCli } = await import("./ssg.js");
 		return runSsgCli(args.slice(1), void 0, io);
 	}
+	if (command === "verify-hydration") {
+		const { runVerifyHydrationCli } = await import("./verify-hydration.js");
+		return runVerifyHydrationCli(args.slice(1), void 0, io);
+	}
 	if (command === "openapi") {
 		const { runOpenApiCli } = await import("./openapi.js");
 		return runOpenApiCli(args.slice(1), io);

package/dist/{guardrails-GPM9PJqO.js → guardrails-D6KCKS-H.js}

@@ -98,7 +98,7 @@ async function runGuardrailCli(command, args = process.argv.slice(2), io = conso
 			cwd: parsed.cwd,
 			workspacePatterns: parsed.workspacePatterns
 		};
-		const { runCheck, runDoctor, runRepair } = await import("./runner-Ca43qqzG.js");
+		const { runCheck, runDoctor, runRepair } = await import("./runner-DetGSvGf.js");
 		const report = command === "doctor" ? await runDoctor(options, runtime) : command === "repair" ? await runRepair(options) : await runCheck(options, runtime);
 		if (parsed.json) io.log(JSON.stringify(report));
 		else if (report.command === "doctor") printDoctor(report, io);

package/dist/{runner-BRjjPhZY.js → runner-BSs9Ow3t.js}

@@ -11,6 +11,7 @@ const DEFAULT_ANALYZE_EXCLUDES = [
 	"**/build/**",
 	"**/coverage/**",
 	"**/.git/**",
+	"**/.askr/**",
 	"**/.next/**",
 	"**/.output/**",
 	"**/.turbo/**",
@@ -237,6 +238,273 @@ const RENDER_SCOPED_CONCEPTS = /* @__PURE__ */ new Set([
 const POSITIONAL_DATA_CONCEPTS = /* @__PURE__ */ new Set(["createQuery", "createMutation"]);
 const ASKR_MODULE_PATTERN = /^@askrjs\/askr(?:\/|$)/;
 //#endregion
+//#region src/analyze/call-graph.ts
+const CALL_GRAPH_CACHE = /* @__PURE__ */ new WeakMap();
+function isLocalFunction(node) {
+	return Boolean(node && ts.isFunctionLike(node) && "body" in node && node.body);
+}
+function containingLocalFunction(node) {
+	for (let current = node.parent; current; current = current.parent) if (isLocalFunction(current)) return current;
+	return null;
+}
+function declarationFunction(declaration) {
+	if (!declaration) return null;
+	if (isLocalFunction(declaration)) return declaration;
+	if (ts.isVariableDeclaration(declaration) && declaration.initializer && isLocalFunction(declaration.initializer)) return declaration.initializer;
+	if (ts.isPropertyAssignment(declaration) && isLocalFunction(declaration.initializer)) return declaration.initializer;
+	return null;
+}
+function symbolForExpression(checker, expression) {
+	const location = ts.isPropertyAccessExpression(expression) ? expression.name : expression;
+	let symbol = checker.getSymbolAtLocation(location) ?? checker.getSymbolAtLocation(expression);
+	if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = checker.getAliasedSymbol(symbol);
+	return symbol;
+}
+function resolveLocalFunction(checker, sourceFiles, expression) {
+	const symbol = symbolForExpression(checker, expression);
+	const declarations = [symbol?.valueDeclaration, ...symbol?.declarations ?? []];
+	for (const declaration of declarations) {
+		const fn = declarationFunction(declaration);
+		if (fn && sourceFiles.has(fn.getSourceFile())) return fn;
+	}
+	return null;
+}
+function localNamedFunction(sourceFile, name) {
+	for (const statement of sourceFile.statements) {
+		if (ts.isFunctionDeclaration(statement) && statement.name?.text === name) return isLocalFunction(statement) ? statement : null;
+		if (!ts.isVariableStatement(statement)) continue;
+		for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.name.text === name && declaration.initializer && isLocalFunction(declaration.initializer)) return declaration.initializer;
+	}
+	return null;
+}
+function localCallGraph(context) {
+	const cached = CALL_GRAPH_CACHE.get(context.program);
+	if (cached) return cached;
+	const sourceFiles = new Set(context.sourceFiles);
+	const sourceByPath = new Map(context.sourceFiles.map((sourceFile) => [path.resolve(sourceFile.fileName), sourceFile]));
+	const moduleCache = /* @__PURE__ */ new Map();
+	const resolveModule = (containingFile, specifier) => {
+		if (!specifier.startsWith(".")) return null;
+		const cacheKey = `${containingFile.fileName}\0${specifier}`;
+		if (moduleCache.has(cacheKey)) return moduleCache.get(cacheKey) ?? null;
+		const base = path.resolve(path.dirname(containingFile.fileName), specifier);
+		const withoutJsExtension = base.replace(/\.(?:c|m)?js$/, "");
+		const candidates = [
+			base,
+			`${base}.ts`,
+			`${base}.tsx`,
+			`${base}.mts`,
+			`${base}.cts`,
+			`${base}.js`,
+			`${base}.jsx`,
+			`${withoutJsExtension}.ts`,
+			`${withoutJsExtension}.tsx`,
+			path.join(base, "index.ts"),
+			path.join(base, "index.tsx"),
+			path.join(base, "index.js")
+		];
+		for (const candidate of candidates) {
+			const resolved = sourceByPath.get(candidate);
+			if (resolved) {
+				moduleCache.set(cacheKey, resolved);
+				return resolved;
+			}
+		}
+		moduleCache.set(cacheKey, null);
+		return null;
+	};
+	const exportCache = /* @__PURE__ */ new Map();
+	const exportedFunction = (sourceFile, name, seen = /* @__PURE__ */ new Set()) => {
+		const key = `${sourceFile.fileName}\0${name}`;
+		if (exportCache.has(key)) return exportCache.get(key) ?? null;
+		if (seen.has(key)) return null;
+		seen.add(key);
+		const direct = localNamedFunction(sourceFile, name);
+		if (direct) {
+			exportCache.set(key, direct);
+			return direct;
+		}
+		exportCache.set(key, null);
+		for (const statement of sourceFile.statements) {
+			if (name === "default" && ts.isFunctionDeclaration(statement) && statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword) && isLocalFunction(statement)) {
+				exportCache.set(key, statement);
+				return statement;
+			}
+			if (!ts.isExportDeclaration(statement)) continue;
+			const target = statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) ? resolveModule(sourceFile, statement.moduleSpecifier.text) : sourceFile;
+			if (!target) continue;
+			if (!statement.exportClause) {
+				const resolved = exportedFunction(target, name, seen);
+				if (resolved) {
+					exportCache.set(key, resolved);
+					return resolved;
+				}
+				continue;
+			}
+			if (!ts.isNamedExports(statement.exportClause)) continue;
+			const element = statement.exportClause.elements.find((candidate) => candidate.name.text === name);
+			if (!element) continue;
+			const imported = element.propertyName?.text ?? element.name.text;
+			const resolved = target === sourceFile ? localNamedFunction(sourceFile, imported) : exportedFunction(target, imported, seen);
+			exportCache.set(key, resolved);
+			return resolved;
+		}
+		return null;
+	};
+	const importBindings = /* @__PURE__ */ new Map();
+	for (const sourceFile of context.sourceFiles) {
+		const named = /* @__PURE__ */ new Map();
+		const namespaces = /* @__PURE__ */ new Map();
+		for (const statement of sourceFile.statements) {
+			if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+			const target = resolveModule(sourceFile, statement.moduleSpecifier.text);
+			if (!target) continue;
+			const clause = statement.importClause;
+			if (clause?.name) named.set(clause.name.text, {
+				source: target,
+				imported: "default"
+			});
+			const bindings = clause?.namedBindings;
+			if (bindings && ts.isNamedImports(bindings)) for (const element of bindings.elements) named.set(element.name.text, {
+				source: target,
+				imported: element.propertyName?.text ?? element.name.text
+			});
+			else if (bindings && ts.isNamespaceImport(bindings)) namespaces.set(bindings.name.text, target);
+		}
+		importBindings.set(sourceFile, {
+			named,
+			namespaces
+		});
+	}
+	const resolveImportedFunction = (expression) => {
+		const imports = importBindings.get(expression.getSourceFile());
+		if (!imports) return null;
+		if (ts.isIdentifier(expression)) {
+			const imported = imports.named.get(expression.text);
+			return imported ? exportedFunction(imported.source, imported.imported) : null;
+		}
+		if (ts.isPropertyAccessExpression(expression) && ts.isIdentifier(expression.expression)) {
+			const source = imports.namespaces.get(expression.expression.text);
+			return source ? exportedFunction(source, expression.name.text) : null;
+		}
+		return null;
+	};
+	const targetByExpression = /* @__PURE__ */ new WeakMap();
+	const resolveFunctionExpression = (expression) => {
+		if (targetByExpression.has(expression)) return targetByExpression.get(expression) ?? null;
+		const target = resolveLocalFunction(context.checker, sourceFiles, expression) ?? resolveImportedFunction(expression);
+		targetByExpression.set(expression, target);
+		return target;
+	};
+	const functions = /* @__PURE__ */ new Set();
+	const callNodes = [];
+	const constructionNodes = [];
+	const walk = (node) => {
+		if (isLocalFunction(node)) functions.add(node);
+		if (ts.isCallExpression(node)) callNodes.push(node);
+		if (ts.isNewExpression(node)) constructionNodes.push(node);
+		ts.forEachChild(node, walk);
+	};
+	for (const sourceFile of context.sourceFiles) walk(sourceFile);
+	const targetByCall = /* @__PURE__ */ new Map();
+	const graph = {
+		calls: callNodes.map((node) => {
+			const target = resolveFunctionExpression(node.expression);
+			targetByCall.set(node, target);
+			return {
+				node,
+				owner: containingLocalFunction(node),
+				target
+			};
+		}),
+		constructions: constructionNodes.map((node) => ({
+			node,
+			owner: containingLocalFunction(node)
+		})),
+		functions,
+		functionForCall(call) {
+			return targetByCall.get(call) ?? null;
+		},
+		functionForExpression(expression) {
+			return resolveFunctionExpression(expression);
+		}
+	};
+	CALL_GRAPH_CACHE.set(context.program, graph);
+	return graph;
+}
+function addAll(target, source) {
+	let changed = false;
+	for (const value of source) {
+		if (target.has(value)) continue;
+		target.add(value);
+		changed = true;
+	}
+	return changed;
+}
+function summarizeTransitiveCalls(context, classifyDirectOperation, callIsUnstable) {
+	const graph = localCallGraph(context);
+	const mutable = /* @__PURE__ */ new Map();
+	const reverseEdges = /* @__PURE__ */ new Map();
+	const ensure = (fn) => {
+		const existing = mutable.get(fn);
+		if (existing) return existing;
+		const created = {
+			values: /* @__PURE__ */ new Set(),
+			unstableValues: /* @__PURE__ */ new Set()
+		};
+		mutable.set(fn, created);
+		return created;
+	};
+	for (const fn of graph.functions) ensure(fn);
+	for (const site of graph.calls) {
+		if (!site.owner) continue;
+		const direct = classifyDirectOperation(site.node);
+		if (direct) {
+			const summary = ensure(site.owner);
+			summary.values.add(direct.value);
+			if (direct.unstable) summary.unstableValues.add(direct.value);
+		}
+		if (!site.target) continue;
+		const incoming = reverseEdges.get(site.target) ?? [];
+		incoming.push({
+			owner: site.owner,
+			unstable: callIsUnstable(site.node, site.owner)
+		});
+		reverseEdges.set(site.target, incoming);
+	}
+	for (const site of graph.constructions) {
+		if (!site.owner) continue;
+		const direct = classifyDirectOperation(site.node);
+		if (!direct) continue;
+		const summary = ensure(site.owner);
+		summary.values.add(direct.value);
+		if (direct.unstable) summary.unstableValues.add(direct.value);
+	}
+	const queue = [...graph.functions];
+	const queued = new Set(queue);
+	for (let index = 0; index < queue.length; index += 1) {
+		const callee = queue[index];
+		queued.delete(callee);
+		const calleeSummary = ensure(callee);
+		for (const edge of reverseEdges.get(callee) ?? []) {
+			const ownerSummary = ensure(edge.owner);
+			let changed = addAll(ownerSummary.values, calleeSummary.values);
+			changed = addAll(ownerSummary.unstableValues, edge.unstable ? calleeSummary.values : calleeSummary.unstableValues) || changed;
+			if (changed && !queued.has(edge.owner)) {
+				queue.push(edge.owner);
+				queued.add(edge.owner);
+			}
+		}
+	}
+	return {
+		byFunction: mutable,
+		forCall(call) {
+			const target = graph.functionForCall(call);
+			return target ? mutable.get(target) ?? null : null;
+		}
+	};
+}
+//#endregion
 //#region src/analyze/rules.ts
 const SOURCE_BINDING_CACHE = /* @__PURE__ */ new WeakMap();
 const SOURCE_FACT_CACHE = /* @__PURE__ */ new WeakMap();
@@ -341,8 +609,34 @@ function containingFunction(node) {
 }
 function isControlFlowAncestor(node, boundary) {
 	for (let current = node.parent; current && current !== boundary; current = current.parent) {
-		if (ts.isIfStatement(current) || ts.isConditionalExpression(current) || ts.isSwitchStatement(current) || ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current) || ts.isTryStatement(current)) return true;
-		if (ts.isBinaryExpression(current) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken].includes(current.operatorToken.kind)) return true;
+		if (ts.isIfStatement(current) && !isConstantCondition(current.expression)) return true;
+		if (ts.isConditionalExpression(current) && !isConstantCondition(current.condition) || ts.isSwitchStatement(current) || ts.isForStatement(current) || ts.isForInStatement(current) || ts.isForOfStatement(current) || ts.isWhileStatement(current) || ts.isDoStatement(current) || ts.isTryStatement(current)) return true;
+		if (ts.isBinaryExpression(current) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken].includes(current.operatorToken.kind) && !isConstantCondition(current.left)) return true;
+	}
+	return hasConditionalEarlyExitBefore(node, boundary);
+}
+function containsFunctionExit(node) {
+	let found = false;
+	const walk = (candidate) => {
+		if (found || candidate !== node && ts.isFunctionLike(candidate)) return;
+		if (ts.isReturnStatement(candidate) || ts.isThrowStatement(candidate)) {
+			found = true;
+			return;
+		}
+		ts.forEachChild(candidate, walk);
+	};
+	walk(node);
+	return found;
+}
+function hasConditionalEarlyExitBefore(node, boundary) {
+	let child = node;
+	for (let current = node.parent; current && current !== boundary; current = current.parent) {
+		if (ts.isBlock(current)) {
+			const statement = current.statements.find((candidate) => candidate === child || candidate.pos <= child.pos && child.end <= candidate.end);
+			const index = statement ? current.statements.indexOf(statement) : -1;
+			if (index > 0 && current.statements.slice(0, index).some((candidate) => ts.isIfStatement(candidate) && !isConstantCondition(candidate.expression) && containsFunctionExit(candidate))) return true;
+		}
+		child = current;
 	}
 	return false;
 }
@@ -385,12 +679,31 @@ const stableRenderRule = {
 	description: "Render-scoped Askr primitives must have stable top-level call order.",
 	analyze(context) {
 		const diagnostics = [];
+		const wrapperSummary = summarizeTransitiveCalls(context, (call) => {
+			if (!ts.isCallExpression(call)) return null;
+			const name = canonicalCallName(call.expression, sourceBindings(call.getSourceFile()));
+			return name && (RENDER_SCOPED_CONCEPTS.has(name) || POSITIONAL_DATA_CONCEPTS.has(name)) ? {
+				value: name,
+				unstable: Boolean(containingFunction(call) && isControlFlowAncestor(call, containingFunction(call)))
+			} : null;
+		}, isControlFlowAncestor);
 		for (const sourceFile of context.sourceFiles) {
 			const bindings = sourceBindings(sourceFile);
 			visit(sourceFile, (node) => {
 				if (!ts.isCallExpression(node)) return;
 				const name = canonicalCallName(node.expression, bindings);
-				if (!name || !RENDER_SCOPED_CONCEPTS.has(name) && !POSITIONAL_DATA_CONCEPTS.has(name)) return;
+				if (!name || !RENDER_SCOPED_CONCEPTS.has(name) && !POSITIONAL_DATA_CONCEPTS.has(name)) {
+					const summary = wrapperSummary.forCall(node);
+					const owner = containingFunction(node);
+					if (!summary || summary.values.size === 0 || !owner || !/^[A-Z]/.test(functionName(owner) ?? "") && !containsJsx(owner) || !isControlFlowAncestor(node, owner) && summary.unstableValues.size === 0) return;
+					const conditionalCallSite = isControlFlowAncestor(node, owner);
+					const conditionalWrapperInternals = summary.unstableValues.size > 0;
+					const concepts = [...conditionalWrapperInternals ? summary.unstableValues : summary.values].sort().join(", ");
+					const message = conditionalCallSite && conditionalWrapperInternals ? `${node.expression.getText()}() is called conditionally and transitively contains conditionally executed render-owned Askr APIs (${concepts}).` : conditionalCallSite ? `${node.expression.getText()}() is called conditionally and transitively calls render-owned Askr APIs (${concepts}).` : `${node.expression.getText()}() transitively contains conditionally executed render-owned Askr APIs (${concepts}).`;
+					const remediation = conditionalCallSite ? "Call the wrapper unconditionally at the top level and branch on its result or inputs." : "Make the render-owned call unconditional inside the wrapper and branch on its result or inputs.";
+					diagnostics.push(diagnostic(context, node.expression, this, message, remediation));
+					return;
+				}
 				const owner = containingFunction(node);
 				if (!owner) {
 					if (POSITIONAL_DATA_CONCEPTS.has(name)) return;
@@ -403,14 +716,194 @@ const stableRenderRule = {
 				if (!ts.isJsxOpeningElement(node) && !ts.isJsxSelfClosingElement(node)) return;
 				const name = canonicalJsxName(node.tagName, bindings);
 				if (!name || !EAGER_CONTROL_CONCEPTS.has(name)) return;
-				if (!unstableControlConditional(node, bindings)) return;
-				const remediation = name === "Show" ? "Mount <Show> unconditionally and move the condition into its when prop." : "Replace the ternary or logical expression with a <Show> boundary.";
-				diagnostics.push(diagnostic(context, node.tagName, this, `<${name}> is mounted behind a changing conditional, so its render position is unstable.`, remediation));
+				const conditional = unstableControlConditional(node, bindings);
+				const owner = containingFunction(node);
+				const followsEarlyReturn = Boolean(owner && hasConditionalEarlyExitBefore(node, owner));
+				if (!conditional && !followsEarlyReturn) return;
+				const remediation = followsEarlyReturn ? name === "For" ? "Keep <For> mounted and represent the unavailable case with an empty each source." : name === "Show" ? "Keep <Show> mounted and move the condition into its when prop." : "Keep <Case> mounted and express the condition in its branches." : name === "Show" ? "Mount <Show> unconditionally and move the condition into its when prop." : "Replace the ternary or logical expression with a <Show> boundary.";
+				diagnostics.push(diagnostic(context, node.tagName, this, followsEarlyReturn ? `<${name}> is reached after a conditional early return, so its render position is unstable.` : `<${name}> is mounted behind a changing conditional, so its render position is unstable.`, remediation));
 			});
 		}
 		return diagnostics;
 	}
 };
+const TIMER_STARTS = /* @__PURE__ */ new Set([
+	"requestAnimationFrame",
+	"setInterval",
+	"setTimeout"
+]);
+const OBSERVER_CONSTRUCTORS = /* @__PURE__ */ new Set([
+	"IntersectionObserver",
+	"MutationObserver",
+	"ResizeObserver"
+]);
+const SUBSCRIPTION_CONSTRUCTORS = /* @__PURE__ */ new Set([
+	"BroadcastChannel",
+	"EventSource",
+	"WebSocket"
+]);
+const PLATFORM_EVENT_TARGET_TYPES = /^(?:AbortSignal|Document|EventTarget|HTMLElement|MediaQueryList|Window)(?:<.*>)?$/;
+const PROJECT_SOURCE_FILES = /* @__PURE__ */ new WeakMap();
+const CLEANUP_CALLS = /* @__PURE__ */ new WeakMap();
+function projectDeclaredIdentifier(identifier, context) {
+	let symbol = context.checker.getSymbolAtLocation(identifier);
+	if (symbol && (symbol.flags & ts.SymbolFlags.Alias) !== 0) symbol = context.checker.getAliasedSymbol(symbol);
+	let sourceFiles = PROJECT_SOURCE_FILES.get(context.program);
+	if (!sourceFiles) {
+		sourceFiles = new Set(context.sourceFiles);
+		PROJECT_SOURCE_FILES.set(context.program, sourceFiles);
+	}
+	return symbol?.declarations?.some((declaration) => sourceFiles.has(declaration.getSourceFile())) ?? false;
+}
+function knownGlobalObject(expression, context) {
+	return ts.isIdentifier(expression) && [
+		"document",
+		"globalThis",
+		"window"
+	].includes(expression.text) && !projectDeclaredIdentifier(expression, context);
+}
+function typedPlatformEventTarget(expression, context) {
+	if (knownGlobalObject(expression, context)) return true;
+	if (!ts.isIdentifier(expression)) return false;
+	const symbol = context.checker.getSymbolAtLocation(expression);
+	return Boolean(symbol?.declarations?.some((declaration) => {
+		if (!ts.isVariableDeclaration(declaration) && !ts.isParameter(declaration) && !ts.isPropertyDeclaration(declaration)) return false;
+		return Boolean(declaration.type && PLATFORM_EVENT_TARGET_TYPES.test(declaration.type.getText()));
+	}));
+}
+function directGlobalCall(call, names, context) {
+	if (ts.isIdentifier(call.expression) && names.has(call.expression.text) && !projectDeclaredIdentifier(call.expression, context)) return call.expression.text;
+	if (ts.isPropertyAccessExpression(call.expression) && names.has(call.expression.name.text) && knownGlobalObject(call.expression.expression, context)) return call.expression.name.text;
+	return null;
+}
+function platformConstructorName(expression, context) {
+	if (ts.isIdentifier(expression) && !projectDeclaredIdentifier(expression, context)) return expression.text;
+	if (ts.isPropertyAccessExpression(expression) && knownGlobalObject(expression.expression, context)) return expression.name.text;
+	return null;
+}
+function renderSideEffect(node, context) {
+	if (ts.isNewExpression(node)) {
+		const name = platformConstructorName(node.expression, context);
+		if (name && OBSERVER_CONSTRUCTORS.has(name)) return "observer";
+		if (name && SUBSCRIPTION_CONSTRUCTORS.has(name)) return "subscription";
+		return null;
+	}
+	if (directGlobalCall(node, TIMER_STARTS, context)) return "timer";
+	if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "addEventListener" && typedPlatformEventTarget(node.expression.expression, context)) return "listener";
+	if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.text === "watchPosition" && ts.isPropertyAccessExpression(node.expression.expression) && node.expression.expression.name.text === "geolocation" && ts.isIdentifier(node.expression.expression.expression) && node.expression.expression.expression.text === "navigator" && !projectDeclaredIdentifier(node.expression.expression.expression, context)) return "subscription";
+	return null;
+}
+function terminalCleanupFunction(callback, context) {
+	if (!("body" in callback) || !callback.body) return null;
+	let returned;
+	if (ts.isArrowFunction(callback) && !ts.isBlock(callback.body)) returned = callback.body;
+	else if (ts.isBlock(callback.body)) {
+		const last = callback.body.statements.at(-1);
+		if (last && ts.isReturnStatement(last)) returned = last.expression;
+	}
+	return resolvedFunction(returned, context);
+}
+function cleanupCalls(callback, context) {
+	const cached = CLEANUP_CALLS.get(callback);
+	if (cached) return cached;
+	const cleanup = terminalCleanupFunction(callback, context);
+	if (!cleanup) {
+		CLEANUP_CALLS.set(callback, []);
+		return [];
+	}
+	const calls = [];
+	const walk = (node) => {
+		if (node !== cleanup && ts.isFunctionLike(node)) return;
+		if (ts.isCallExpression(node)) calls.push(node);
+		ts.forEachChild(node, walk);
+	};
+	walk(cleanup);
+	CLEANUP_CALLS.set(callback, calls);
+	return calls;
+}
+function assignedEffectReference(node) {
+	const parent = node.parent;
+	if (ts.isVariableDeclaration(parent) && parent.initializer === node) return ts.isIdentifier(parent.name) ? parent.name : null;
+	if (ts.isBinaryExpression(parent) && parent.right === node && parent.operatorToken.kind === ts.SyntaxKind.EqualsToken) return parent.left;
+	return null;
+}
+function sameReference(left, right, context) {
+	if (!left || !right) return false;
+	let leftSymbol = context.checker.getSymbolAtLocation(left);
+	let rightSymbol = context.checker.getSymbolAtLocation(right);
+	if (leftSymbol && (leftSymbol.flags & ts.SymbolFlags.Alias) !== 0) leftSymbol = context.checker.getAliasedSymbol(leftSymbol);
+	if (rightSymbol && (rightSymbol.flags & ts.SymbolFlags.Alias) !== 0) rightSymbol = context.checker.getAliasedSymbol(rightSymbol);
+	return leftSymbol && rightSymbol ? leftSymbol === rightSymbol : left.getText() === right.getText();
+}
+function taskCleansDirectEffect(callback, node, effect, context) {
+	const cleanup = cleanupCalls(callback, context);
+	if (effect === "listener" && ts.isCallExpression(node)) {
+		if (!ts.isPropertyAccessExpression(node.expression) || node.expression.name.text !== "addEventListener") return false;
+		const startExpression = node.expression;
+		return cleanup.some((call) => ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === "removeEventListener" && sameReference(call.expression.expression, startExpression.expression, context) && sameReference(call.arguments[0], node.arguments[0], context) && sameReference(call.arguments[1], node.arguments[1], context) && (node.arguments[2] === void 0 || sameReference(call.arguments[2], node.arguments[2], context)));
+	}
+	const handle = assignedEffectReference(node);
+	if (!handle) return false;
+	if (effect === "timer" && ts.isCallExpression(node)) {
+		const start = directGlobalCall(node, TIMER_STARTS, context);
+		const expected = start === "setInterval" ? "clearInterval" : start === "setTimeout" ? "clearTimeout" : start === "requestAnimationFrame" ? "cancelAnimationFrame" : null;
+		const expectedSet = expected ? /* @__PURE__ */ new Set([expected]) : /* @__PURE__ */ new Set();
+		return cleanup.some((call) => Boolean(directGlobalCall(call, expectedSet, context)) && sameReference(call.arguments[0], handle, context));
+	}
+	if (effect === "observer") return cleanup.some((call) => ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === "disconnect" && sameReference(call.expression.expression, handle, context));
+	if (effect === "subscription") return cleanup.some((call) => {
+		if (ts.isPropertyAccessExpression(call.expression) && (call.expression.name.text === "close" || call.expression.name.text === "unsubscribe") && sameReference(call.expression.expression, handle, context)) return true;
+		return ts.isCallExpression(node) && ts.isPropertyAccessExpression(call.expression) && call.expression.name.text === "clearWatch" && ts.isPropertyAccessExpression(call.expression.expression) && call.expression.expression.name.text === "geolocation" && ts.isIdentifier(call.expression.expression.expression) && call.expression.expression.expression.text === "navigator" && !projectDeclaredIdentifier(call.expression.expression.expression, context) && sameReference(call.arguments[0], handle, context);
+	});
+	return false;
+}
+function isRenderFunction(owner) {
+	return /^[A-Z]/.test(functionName(owner) ?? "") || containsJsx(owner);
+}
+const renderSideEffectRule = {
+	id: "askr/render-side-effect",
+	category: "correctness",
+	severity: "error",
+	description: "Platform side effects started during render require lifecycle-owned cleanup.",
+	analyze(context) {
+		const diagnostics = [];
+		const graph = localCallGraph(context);
+		const summary = summarizeTransitiveCalls(context, (node) => {
+			const effect = renderSideEffect(node, context);
+			return effect ? { value: effect } : null;
+		}, () => false);
+		const lifecycleCallbacks = /* @__PURE__ */ new Set();
+		for (const site of graph.calls) {
+			if (canonicalCallName(site.node.expression, sourceBindings(site.node.getSourceFile())) !== "task") continue;
+			const argument = site.node.arguments[0];
+			const callback = resolvedFunction(argument, context) ?? (argument ? graph.functionForExpression(argument) : null);
+			if (callback) lifecycleCallbacks.add(callback);
+		}
+		const report = (node, effects, direct = false) => {
+			const owner = containingFunction(node);
+			if (!owner) return;
+			const managed = lifecycleCallbacks.has(owner);
+			if (managed && direct && [...effects].every((effect) => taskCleansDirectEffect(owner, node, effect, context))) return;
+			if (!managed && !isRenderFunction(owner)) return;
+			const effectNames = [...effects].sort().join(", ");
+			diagnostics.push(diagnostic(context, node.expression, this, managed ? `This task starts ${effectNames} side effects without returning matching cleanup.` : `${node.expression.getText()} starts unmanaged ${effectNames} side effects during render.`, "Start the effect in task() and return cleanup that clears, disconnects, removes, closes, or unsubscribes it."));
+		};
+		for (const site of graph.calls) {
+			const direct = renderSideEffect(site.node, context);
+			if (direct) {
+				report(site.node, /* @__PURE__ */ new Set([direct]), true);
+				continue;
+			}
+			const wrapper = summary.forCall(site.node);
+			if (wrapper && wrapper.values.size > 0) report(site.node, wrapper.values);
+		}
+		for (const site of graph.constructions) {
+			const direct = renderSideEffect(site.node, context);
+			if (direct) report(site.node, /* @__PURE__ */ new Set([direct]), true);
+		}
+		return diagnostics;
+	}
+};
 function collectStateBindings(sourceFile, bindings) {
 	const getters = /* @__PURE__ */ new Set();
 	const setters = /* @__PURE__ */ new Set();
@@ -660,7 +1153,10 @@ const preferForRule = {
 		return diagnostics;
 	}
 };
+const CONTAINS_JSX = /* @__PURE__ */ new WeakMap();
 function containsJsx(node) {
+	const cached = CONTAINS_JSX.get(node);
+	if (cached !== void 0) return cached;
 	let found = false;
 	const walk = (candidate) => {
 		if (found) return;
@@ -671,6 +1167,7 @@ function containsJsx(node) {
 		ts.forEachChild(candidate, walk);
 	};
 	walk(node);
+	CONTAINS_JSX.set(node, found);
 	return found;
 }
 function isAsyncFunction(node) {
@@ -1269,6 +1766,7 @@ const ANALYZE_RULES = [
 		}
 	},
 	stableRenderRule,
+	renderSideEffectRule,
 	stateAccessRule,
 	stateRenderWriteRule,
 	resourceCancellationRule,

package/dist/{runner-Ca43qqzG.js → runner-DetGSvGf.js}

@@ -1,6 +1,6 @@
 import { t as inspectBundledSkills } from "./skills-CSGdAZHN.js";
 import { discoverWorkspaceProject } from "./discovery-DUDrZCIC.js";
-import { analysisHasBlockingFindings, runAnalysis } from "./runner-BRjjPhZY.js";
+import { analysisHasBlockingFindings, runAnalysis } from "./runner-BSs9Ow3t.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { spawn } from "node:child_process";