@ts-kizuna/cli 1.49.5

package/dist/lint-deprecations-Dx9WRFQa.mjs

@@ -0,0 +1,669 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import ts from "typescript";
+import { AUTHORING_NAMES, CONTRACT_EXPORT_NAMES } from "@ts-kizuna/core/authoring-names";
+import { contractFingerprint, serializeDeprecationMap } from "@ts-kizuna/core/generator";
+import { createJiti } from "jiti";
+//#region src/schema-exports.ts
+/**
+* Maps every exported schema reachable from `entryPath` to the verbatim JSDoc
+* block on each of its fields, keyed by the exported const name (and, for
+* aliased re-exports, by the original declared name too).
+*
+* Walks the whole reachable graph, both the entry's re-exports and every file
+* it imports, so a schema defined in its own module and used via `import`
+* (rather than re-exported from the contract entry) is still collected.
+*
+* Used to patch emitted `.d.ts` files, where a `z.ZodObject<{...}>` shape is
+* keyed by the `declare const` name rather than a route or schema `meta.id`.
+*/
+const collectExportedSchemaDocs = (entryPath) => {
+	const { resolve, cache } = makeResolverWithCache(entryPath);
+	const result = /* @__PURE__ */ new Map();
+	const visited = /* @__PURE__ */ new Set();
+	const record = (name, expression) => {
+		const fields = /* @__PURE__ */ new Map();
+		collectFieldDocs(expression, "", fields, resolve);
+		if (fields.size > 0) result.set(name, fields);
+	};
+	const collectFromFile = (filePath) => {
+		if (visited.has(filePath)) return;
+		visited.add(filePath);
+		const sourceFile = ts.createSourceFile(filePath, fs.readFileSync(filePath, "utf8"), ts.ScriptTarget.Latest, true);
+		for (const statement of sourceFile.statements) {
+			if (ts.isVariableStatement(statement)) {
+				if (!(statement.modifiers ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+				for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name) && declaration.initializer) record(declaration.name.text, declaration.initializer);
+				continue;
+			}
+			if (!ts.isExportDeclaration(statement) || !statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+			const specifier = statement.moduleSpecifier.text;
+			if (!specifier.startsWith(".")) continue;
+			const target = resolveImportPath(path.dirname(filePath), specifier);
+			if (!target) continue;
+			const exportClause = statement.exportClause;
+			if (!exportClause) {
+				collectFromFile(target);
+				continue;
+			}
+			if (!ts.isNamedExports(exportClause)) continue;
+			const targetScope = buildFileScope(target, cache);
+			for (const element of exportClause.elements) {
+				const localName = (element.propertyName ?? element.name).text;
+				const exposedName = element.name.text;
+				const expression = targetScope.get(localName);
+				if (!expression) continue;
+				record(exposedName, expression);
+				if (localName !== exposedName) record(localName, expression);
+			}
+		}
+	};
+	collectFromFile(entryPath);
+	for (const filePath of [...cache.keys()]) collectFromFile(filePath);
+	return result;
+};
+//#endregion
+//#region src/dts-jsdoc.ts
+/**
+* Zod wrapper types whose inner type is the first type argument. Navigating a
+* field path unwraps these until it reaches a `ZodObject`. Mirrors the runtime
+* wrapper set in `zod-internals.ts`.
+*/
+const ELEMENT_WRAPPERS = new Set([
+	"ZodArray",
+	"ZodOptional",
+	"ZodNullable",
+	"ZodDefault",
+	"ZodReadonly",
+	"ZodNonOptional",
+	"ZodCatch",
+	"ZodPrefault"
+]);
+const entityNameRight = (name) => ts.isQualifiedName(name) ? name.right.text : name.text;
+/**
+* The right-most type name, ignoring the qualifier, so `ZodObject`,
+* `z.ZodObject`, and `import("zod").ZodObject` all read as `ZodObject`.
+*/
+const rightmostTypeName = (node) => {
+	if (ts.isTypeReferenceNode(node)) return entityNameRight(node.typeName);
+	if (ts.isImportTypeNode(node)) return node.qualifier ? entityNameRight(node.qualifier) : void 0;
+};
+const typeArgumentsOf = (node) => {
+	if (ts.isTypeReferenceNode(node)) return node.typeArguments ?? [];
+	if (ts.isImportTypeNode(node)) return node.typeArguments ?? [];
+	return [];
+};
+const propertySignatureName = (node) => {
+	if (ts.isIdentifier(node)) return node.text;
+	if (ts.isStringLiteral(node)) return node.text;
+	if (ts.isNumericLiteral(node)) return node.text;
+};
+/**
+* Walks a dotted field path through a Zod schema type to the leaf property
+* signature. Unwraps element wrappers (`ZodArray`, `ZodOptional`, …) and reads
+* each `ZodObject`'s shape from its first type argument. Returns undefined and
+* never throws when the path can't be navigated (e.g. the shape was emitted as
+* a named reference rather than a literal).
+*/
+const findPropertySignature = (typeNode, segments) => {
+	let current = typeNode;
+	for (let index = 0; index < segments.length; index += 1) {
+		let guard = 0;
+		let name = rightmostTypeName(current);
+		while (name !== void 0 && ELEMENT_WRAPPERS.has(name)) {
+			const args = typeArgumentsOf(current);
+			if (args.length === 0) return void 0;
+			current = args[0];
+			name = rightmostTypeName(current);
+			guard += 1;
+			if (guard > 32) return void 0;
+		}
+		if (name !== "ZodObject") return void 0;
+		const shape = typeArgumentsOf(current)[0];
+		if (!shape || !ts.isTypeLiteralNode(shape)) return void 0;
+		const member = shape.members.find((candidate) => ts.isPropertySignature(candidate) && propertySignatureName(candidate.name) === segments[index]);
+		if (!member) return void 0;
+		if (index === segments.length - 1) return member;
+		if (!member.type) return void 0;
+		current = member.type;
+	}
+};
+const hasLeadingJsDoc = (member, fullText) => {
+	return (ts.getLeadingCommentRanges(fullText, member.getFullStart()) ?? []).some((range) => fullText.slice(range.pos, range.pos + 3) === "/**");
+};
+/**
+* Re-indents a captured JSDoc block to `indent`: the opening `/**` keeps the
+* property's own indentation (already present before the splice point), and each
+* continuation line is re-prefixed so the `*` column lines up.
+*/
+const reindentJsDoc = (block, indent) => block.split("\n").map((line, index) => index === 0 ? line.trim() : `${indent} ${line.trim()}`).join("\n");
+const indentAt = (text, offset) => {
+	const lineStart = text.lastIndexOf("\n", offset - 1) + 1;
+	return text.slice(lineStart, offset).match(/^[ \t]*/)?.[0] ?? "";
+};
+/**
+* Maps each locally declared name to the names it's re-exported under in the
+* same file, e.g. `export { i as UserSchema }` from a bundled chunk where the
+* `declare const` is named `i`.
+*/
+const localExportAliases = (sourceFile) => {
+	const aliases = /* @__PURE__ */ new Map();
+	for (const statement of sourceFile.statements) {
+		if (!ts.isExportDeclaration(statement) || statement.moduleSpecifier) continue;
+		if (!statement.exportClause || !ts.isNamedExports(statement.exportClause)) continue;
+		for (const element of statement.exportClause.elements) {
+			const localName = (element.propertyName ?? element.name).text;
+			const list = aliases.get(localName) ?? [];
+			list.push(element.name.text);
+			aliases.set(localName, list);
+		}
+	}
+	return aliases;
+};
+const patchFile = (filePath, exportFieldMap) => {
+	const text = fs.readFileSync(filePath, "utf8");
+	const sourceFile = ts.createSourceFile(filePath, text, ts.ScriptTarget.Latest, true);
+	const aliases = localExportAliases(sourceFile);
+	const insertions = [];
+	for (const statement of sourceFile.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name) || !declaration.type) continue;
+			const fields = [declaration.name.text, ...aliases.get(declaration.name.text) ?? []].map((name) => exportFieldMap.get(name)).find(Boolean);
+			if (!fields) continue;
+			for (const [fieldPath, block] of fields) {
+				const member = findPropertySignature(declaration.type, fieldPath.split("."));
+				if (!member || hasLeadingJsDoc(member, text)) continue;
+				const offset = member.getStart(sourceFile);
+				const indent = indentAt(text, offset);
+				insertions.push({
+					offset,
+					text: `${reindentJsDoc(block, indent)}\n${indent}`
+				});
+			}
+		}
+	}
+	if (insertions.length === 0) return 0;
+	insertions.sort((left, right) => right.offset - left.offset);
+	let output = text;
+	for (const insertion of insertions) output = output.slice(0, insertion.offset) + insertion.text + output.slice(insertion.offset);
+	fs.writeFileSync(filePath, output, "utf8");
+	return insertions.length;
+};
+const DECLARATION_SUFFIXES = [
+	".d.ts",
+	".d.mts",
+	".d.cts"
+];
+const walkDeclarationFiles = (dir, into) => {
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const full = path.join(dir, entry.name);
+		if (entry.isDirectory()) walkDeclarationFiles(full, into);
+		else if (entry.isFile() && DECLARATION_SUFFIXES.some((suffix) => entry.name.endsWith(suffix))) into.push(full);
+	}
+};
+/**
+* Re-injects the JSDoc blocks from {@link collectExportedSchemaDocs} onto Zod
+* schema shape properties in the `.d.ts` files under `distDir`. Declaration emit
+* drops the comments an author wrote on schema fields; this restores them, full
+* descriptions, `@deprecated`, `@example`, etc., so they reach `z.infer`
+* consumers in other repos. Skips properties that already have JSDoc. Idempotent.
+*/
+const patchDeclarationDocs = (distDir, exportFieldMap) => {
+	const files = [];
+	walkDeclarationFiles(distDir, files);
+	let filesChanged = 0;
+	let injections = 0;
+	for (const file of files) {
+		const count = patchFile(file, exportFieldMap);
+		if (count > 0) {
+			filesChanged += 1;
+			injections += count;
+		}
+	}
+	return {
+		filesScanned: files.length,
+		filesChanged,
+		injections
+	};
+};
+//#endregion
+//#region src/deprecation-parser.ts
+const SCHEMA_KEYS = new Set([
+	"body",
+	"query",
+	"headers"
+]);
+const readDeprecatedMessage = (node) => {
+	const tag = ts.getJSDocTags(node).find((candidate) => candidate.tagName.text === "deprecated");
+	if (!tag) return void 0;
+	return ts.getTextOfJSDocComment(tag.comment) ?? "";
+};
+const propertyName = (node) => {
+	if (ts.isIdentifier(node)) return node.text;
+	if (ts.isStringLiteral(node)) return node.text;
+	if (ts.isNumericLiteral(node)) return node.text;
+};
+const resolveImportPath = (dir, specifier) => {
+	const base = specifier.replace(/\.js$/, "");
+	for (const candidate of [
+		`${base}.ts`,
+		`${base}/index.ts`,
+		base
+	]) {
+		const full = path.resolve(dir, candidate);
+		if (fs.existsSync(full)) return full;
+	}
+};
+const buildFileScope = (filePath, cache) => {
+	if (cache.has(filePath)) return cache.get(filePath);
+	const scope = /* @__PURE__ */ new Map();
+	cache.set(filePath, scope);
+	const source = fs.readFileSync(filePath, "utf8");
+	const sourceFile = ts.createSourceFile(filePath, source, ts.ScriptTarget.Latest, true);
+	for (const statement of sourceFile.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		for (const decl of statement.declarationList.declarations) if (ts.isIdentifier(decl.name) && decl.initializer) scope.set(decl.name.text, decl.initializer);
+	}
+	for (const statement of sourceFile.statements) {
+		if (!ts.isImportDeclaration(statement)) continue;
+		if (!ts.isStringLiteral(statement.moduleSpecifier)) continue;
+		const specifier = statement.moduleSpecifier.text;
+		if (!specifier.startsWith(".")) continue;
+		const importedPath = resolveImportPath(path.dirname(filePath), specifier);
+		if (!importedPath) continue;
+		const importedScope = buildFileScope(importedPath, cache);
+		const namedBindings = statement.importClause?.namedBindings;
+		if (!namedBindings || !ts.isNamedImports(namedBindings)) continue;
+		for (const element of namedBindings.elements) {
+			const exportedName = (element.propertyName ?? element.name).text;
+			const localName = element.name.text;
+			const expr = importedScope.get(exportedName);
+			if (expr) scope.set(localName, expr);
+		}
+	}
+	return scope;
+};
+const makeResolverWithCache = (contractPath) => {
+	const cache = /* @__PURE__ */ new Map();
+	buildFileScope(contractPath, cache);
+	const resolve = (node) => {
+		const filePath = node.getSourceFile().fileName;
+		return (cache.get(filePath) ?? buildFileScope(filePath, cache)).get(node.text);
+	};
+	return {
+		resolve,
+		cache
+	};
+};
+const readObjectStringProperty = (object, name) => {
+	for (const property of object.properties) {
+		if (!ts.isPropertyAssignment(property)) continue;
+		if (!ts.isIdentifier(property.name) || property.name.text !== name) continue;
+		if (ts.isStringLiteral(property.initializer)) return property.initializer.text;
+	}
+};
+const readAstMetaId = (expr) => {
+	if (!ts.isCallExpression(expr)) return void 0;
+	const firstArg = expr.arguments[0];
+	if (isModelCall(expr)) {
+		if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return void 0;
+		return readObjectStringProperty(firstArg, "title");
+	}
+	if (ts.isPropertyAccessExpression(expr.expression) && expr.expression.name.text === "meta") {
+		if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return void 0;
+		return readObjectStringProperty(firstArg, "id") ?? readAstMetaId(expr.expression.expression);
+	}
+};
+const firstObjectLiteralIn = (node, resolve, visited) => {
+	if (ts.isObjectLiteralExpression(node)) return node;
+	if (ts.isIdentifier(node)) {
+		const name = node.text;
+		if (visited.has(name)) return void 0;
+		const referenced = resolve(node);
+		if (!referenced) return void 0;
+		if (ts.isArrowFunction(referenced) || ts.isFunctionExpression(referenced)) return void 0;
+		visited.add(name);
+		return firstObjectLiteralIn(referenced, resolve, visited);
+	}
+	if (ts.isCallExpression(node)) {
+		if (isContractChainCall(node) || isRoutesChainCall(node)) {
+			const routesArg = routesArgFrom(node);
+			if (routesArg) return firstObjectLiteralIn(routesArg, resolve, visited);
+			return;
+		}
+		if (isModelCall(node)) {
+			const modelSchema = extractCreateModelSchema(node);
+			return modelSchema ? firstObjectLiteralIn(modelSchema, resolve, visited) : void 0;
+		}
+	}
+	let found;
+	ts.forEachChild(node, (child) => {
+		if (found) return;
+		found = firstObjectLiteralIn(child, resolve, visited);
+	});
+	return found;
+};
+const findExtendBase = (node) => {
+	if (!ts.isCallExpression(node) || !ts.isPropertyAccessExpression(node.expression)) return void 0;
+	if (node.expression.name.text === "extend") return node.expression.expression;
+	return findExtendBase(node.expression.expression);
+};
+const getFunctionBody = (func) => {
+	const { body } = func;
+	if (!ts.isBlock(body)) return body;
+	let result;
+	ts.forEachChild(body, (stmt) => {
+		if (!result && ts.isReturnStatement(stmt) && stmt.expression) result = stmt.expression;
+	});
+	return result ?? body;
+};
+const makeScopedResolver = (func, args, parent) => {
+	const substitutions = /* @__PURE__ */ new Map();
+	func.parameters.forEach((param, index) => {
+		const arg = args[index];
+		if (arg && ts.isIdentifier(param.name)) substitutions.set(param.name.text, arg);
+	});
+	return (node) => substitutions.get(node.text) ?? parent(node);
+};
+const extractCreateModelSchema = (node) => {
+	if (!ts.isCallExpression(node) || !isModelCall(node)) return void 0;
+	const firstArg = node.arguments[0];
+	if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return void 0;
+	for (const property of firstArg.properties) {
+		if (!ts.isPropertyAssignment(property)) continue;
+		if (propertyName(property.name) === "schema") return property.initializer;
+	}
+};
+/**
+* Walks a schema expression's fields, calling `visit` with each field's dot-path
+* and its property node. Resolves identifiers, `Kizuna.model`, generic wrapper
+* functions (e.g. `Pagination(Item)`), and `.extend()`; recurses into nested
+* objects.
+*/
+const walkSchemaFields = (schemaNode, prefix, resolve, visit) => {
+	const resolved = ts.isIdentifier(schemaNode) ? resolve(schemaNode) ?? schemaNode : schemaNode;
+	const modelSchema = extractCreateModelSchema(resolved);
+	if (modelSchema) {
+		walkSchemaFields(modelSchema, prefix, resolve, visit);
+		return;
+	}
+	if (ts.isCallExpression(resolved) && ts.isIdentifier(resolved.expression)) {
+		const funcExpr = resolve(resolved.expression);
+		if (funcExpr && (ts.isArrowFunction(funcExpr) || ts.isFunctionExpression(funcExpr))) {
+			walkSchemaFields(getFunctionBody(funcExpr), prefix, makeScopedResolver(funcExpr, resolved.arguments, resolve), visit);
+			return;
+		}
+	}
+	const extendBase = findExtendBase(resolved);
+	if (extendBase) walkSchemaFields(extendBase, prefix, resolve, visit);
+	const objectLiteral = firstObjectLiteralIn(schemaNode, resolve, /* @__PURE__ */ new Set());
+	if (!objectLiteral) return;
+	for (const property of objectLiteral.properties) {
+		if (ts.isShorthandPropertyAssignment(property)) {
+			visit(prefix === "" ? property.name.text : `${prefix}.${property.name.text}`, property);
+			continue;
+		}
+		if (!ts.isPropertyAssignment(property)) continue;
+		const fieldName = propertyName(property.name);
+		if (fieldName === void 0) continue;
+		const fieldPath = prefix === "" ? fieldName : `${prefix}.${fieldName}`;
+		visit(fieldPath, property);
+		walkSchemaFields(property.initializer, fieldPath, resolve, visit);
+	}
+};
+const collectFieldDeprecations = (schemaNode, prefix, into, resolve) => {
+	walkSchemaFields(schemaNode, prefix, resolve, (fieldPath, property) => {
+		const message = readDeprecatedMessage(property);
+		if (message !== void 0) into.set(fieldPath, message);
+	});
+};
+/**
+* Returns the verbatim leading JSDoc block (`/** … *\/`) on a node, or undefined
+* when it has none.
+*/
+const readJsDocBlock = (node) => {
+	const sourceFile = node.getSourceFile();
+	const jsDoc = (ts.getLeadingCommentRanges(sourceFile.text, node.getFullStart()) ?? []).filter((range) => sourceFile.text.slice(range.pos, range.pos + 3) === "/**").at(-1);
+	return jsDoc ? sourceFile.text.slice(jsDoc.pos, jsDoc.end) : void 0;
+};
+const collectFieldDocs = (schemaNode, prefix, into, resolve) => {
+	walkSchemaFields(schemaNode, prefix, resolve, (fieldPath, property) => {
+		const block = readJsDocBlock(property);
+		if (block !== void 0) into.set(fieldPath, block);
+	});
+};
+const isRouteLike = (obj) => obj.properties.some((prop) => {
+	const name = ts.isPropertyAssignment(prop) ? propertyName(prop.name) : ts.isShorthandPropertyAssignment(prop) ? prop.name.text : void 0;
+	return name === "method" || name === "path" || name === "responses";
+});
+const routePropertyName = (prop) => {
+	if (ts.isPropertyAssignment(prop)) return propertyName(prop.name);
+	if (ts.isShorthandPropertyAssignment(prop)) return prop.name.text;
+};
+const routePropertyInitializer = (prop) => ts.isPropertyAssignment(prop) ? prop.initializer : prop.name;
+const buildMapFromRoutesLiteral = (routesLiteral, resolve, prefix = "") => {
+	const routes = /* @__PURE__ */ new Map();
+	const fields = /* @__PURE__ */ new Map();
+	for (const routeProperty of routesLiteral.properties) {
+		if (!ts.isPropertyAssignment(routeProperty) && !ts.isShorthandPropertyAssignment(routeProperty)) continue;
+		const routeName = routePropertyName(routeProperty);
+		if (routeName === void 0) continue;
+		const fullKey = prefix === "" ? routeName : `${prefix}.${routeName}`;
+		const routeMessage = readDeprecatedMessage(routeProperty);
+		if (routeMessage !== void 0) routes.set(fullKey, routeMessage);
+		const initializer = routePropertyInitializer(routeProperty);
+		const resolvedLiteral = ts.isObjectLiteralExpression(initializer) ? initializer : firstObjectLiteralIn(initializer, resolve, /* @__PURE__ */ new Set());
+		if (!resolvedLiteral) continue;
+		if (!isRouteLike(resolvedLiteral)) {
+			const sub = buildMapFromRoutesLiteral(resolvedLiteral, resolve, fullKey);
+			for (const [key, value] of sub.routes) routes.set(key, value);
+			for (const [key, value] of sub.fields) fields.set(key, value);
+			continue;
+		}
+		const deprecated = /* @__PURE__ */ new Map();
+		for (const subProperty of resolvedLiteral.properties) {
+			if (!ts.isPropertyAssignment(subProperty)) continue;
+			const subKey = propertyName(subProperty.name);
+			if (subKey === void 0) continue;
+			if (SCHEMA_KEYS.has(subKey)) {
+				collectFieldDeprecations(subProperty.initializer, subKey, deprecated, resolve);
+				continue;
+			}
+			if (subKey === "responses" && ts.isObjectLiteralExpression(subProperty.initializer)) for (const responseEntry of subProperty.initializer.properties) {
+				if (!ts.isPropertyAssignment(responseEntry)) continue;
+				const status = propertyName(responseEntry.name);
+				if (status === void 0) continue;
+				collectFieldDeprecations(responseEntry.initializer, `responses.${status}`, deprecated, resolve);
+			}
+		}
+		if (deprecated.size > 0) fields.set(fullKey, deprecated);
+	}
+	return {
+		routes,
+		fields
+	};
+};
+const findRouterCallInNode = (node) => {
+	if (ts.isCallExpression(node)) {
+		if (isMemberCall(node, AUTHORING_NAMES.router)) return node;
+		if (isContractChainCall(node) || isRoutesChainCall(node)) return node;
+	}
+	let found;
+	ts.forEachChild(node, (child) => {
+		if (found) return;
+		found = findRouterCallInNode(child);
+	});
+	return found;
+};
+/**
+* True when `node` calls `member` on any receiver, e.g. `k.routes(...)`.
+*/
+const isMemberCall = (node, member) => ts.isPropertyAccessExpression(node.expression) && ts.isIdentifier(node.expression.name) && node.expression.name.text === member;
+const isRoutesChainCall = (node) => isMemberCall(node, AUTHORING_NAMES.routes);
+const isContractChainCall = (node) => isMemberCall(node, AUTHORING_NAMES.contract);
+const isModelCall = (node) => isMemberCall(node, AUTHORING_NAMES.model);
+const isContractExportName = (name) => CONTRACT_EXPORT_NAMES.includes(name);
+const routesArgFrom = (call) => {
+	if (isRoutesChainCall(call)) return call.arguments[call.arguments.length - 1];
+	if (isContractChainCall(call)) {
+		const arg = call.arguments[0];
+		if (arg && ts.isObjectLiteralExpression(arg)) for (const prop of arg.properties) {
+			if (ts.isPropertyAssignment(prop) && propertyName(prop.name) === "routes") return prop.initializer;
+			if (ts.isShorthandPropertyAssignment(prop) && prop.name.text === "routes") return prop.name;
+		}
+		return arg;
+	}
+	const firstArg = call.arguments[0];
+	if (!firstArg) return void 0;
+	if (call.arguments.length === 2) return call.arguments[1];
+	return firstArg;
+};
+const collectExportedRoutesLiterals = (sourceFile, resolve, into) => {
+	for (const statement of sourceFile.statements) {
+		if (!ts.isVariableStatement(statement)) continue;
+		if (!(statement.modifiers ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue;
+		for (const declaration of statement.declarationList.declarations) {
+			if (!ts.isIdentifier(declaration.name)) continue;
+			const exportName = declaration.name.text;
+			if (!isContractExportName(exportName)) continue;
+			if (!declaration.initializer) continue;
+			let initializer = declaration.initializer;
+			if (ts.isIdentifier(initializer)) {
+				const resolved = resolve(initializer);
+				if (resolved) initializer = resolved;
+			}
+			if (!ts.isCallExpression(initializer)) continue;
+			initializer.expression;
+			if (isContractChainCall(initializer)) {
+				const routesArg = routesArgFrom(initializer);
+				const lit = routesArg ? firstObjectLiteralIn(routesArg, resolve, /* @__PURE__ */ new Set()) : void 0;
+				if (lit) into.push(lit);
+			}
+		}
+	}
+	for (const statement of sourceFile.statements) {
+		if (!ts.isExportDeclaration(statement)) continue;
+		if (!statement.moduleSpecifier || !ts.isStringLiteral(statement.moduleSpecifier)) continue;
+		const specifier = statement.moduleSpecifier.text;
+		if (!specifier.startsWith(".")) continue;
+		const exportClause = statement.exportClause;
+		if (!exportClause || !ts.isNamedExports(exportClause)) continue;
+		if (!exportClause.elements.some((element) => {
+			const exportedName = element.name.text;
+			return isContractExportName(exportedName);
+		})) continue;
+		const importedPath = resolveImportPath(path.dirname(sourceFile.fileName), specifier);
+		if (!importedPath) continue;
+		collectExportedRoutesLiterals(ts.createSourceFile(importedPath, fs.readFileSync(importedPath, "utf8"), ts.ScriptTarget.Latest, true), resolve, into);
+	}
+};
+const findAllRouteObjectLiterals = (sourceFile, resolve) => {
+	const results = [];
+	collectExportedRoutesLiterals(sourceFile, resolve, results);
+	if (results.length > 0) return results;
+	const routerCall = findRouterCallInNode(sourceFile);
+	if (!routerCall) return [];
+	const routesArg = routesArgFrom(routerCall);
+	const lit = routesArg ? firstObjectLiteralIn(routesArg, resolve, /* @__PURE__ */ new Set()) : void 0;
+	return lit ? [lit] : [];
+};
+const parseFromSource = (contractPath) => {
+	const source = fs.readFileSync(contractPath, "utf8");
+	const sourceFile = ts.createSourceFile(contractPath, source, ts.ScriptTarget.Latest, true);
+	const { resolve, cache } = makeResolverWithCache(contractPath);
+	const routeLiterals = findAllRouteObjectLiterals(sourceFile, resolve);
+	const routes = /* @__PURE__ */ new Map();
+	const fields = /* @__PURE__ */ new Map();
+	for (const literal of routeLiterals) {
+		const partial = buildMapFromRoutesLiteral(literal, resolve);
+		for (const [key, value] of partial.routes) routes.set(key, value);
+		for (const [key, value] of partial.fields) fields.set(key, value);
+	}
+	const schemas = /* @__PURE__ */ new Map();
+	for (const fileScope of cache.values()) for (const expr of fileScope.values()) {
+		const id = readAstMetaId(expr);
+		if (!id) continue;
+		const fieldDeprecations = /* @__PURE__ */ new Map();
+		collectFieldDeprecations(expr, "", fieldDeprecations, resolve);
+		if (fieldDeprecations.size > 0) schemas.set(id, fieldDeprecations);
+	}
+	return {
+		routes,
+		fields,
+		schemas
+	};
+};
+/**
+* Parses a contract's `@deprecated` JSDoc tags into a {@link DeprecationMap}.
+*/
+const createDeprecationMap = (contractPath) => parseFromSource(contractPath);
+/**
+* Parses each contract's `@deprecated` tags and writes them to
+* `<outDir>/deprecations.json`, keyed by contract fingerprint. Generators read
+* the entry matching the contract they generate. Returns the written path.
+*/
+const writeKizunaDeprecations = (contracts, outDir) => {
+	const entries = {};
+	for (const { contract, contractPath } of contracts) entries[contractFingerprint(contract)] = serializeDeprecationMap(createDeprecationMap(contractPath));
+	const outputPath = path.join(outDir, "deprecations.json");
+	fs.mkdirSync(outDir, { recursive: true });
+	fs.writeFileSync(outputPath, JSON.stringify(entries, null, 2), "utf8");
+	return outputPath;
+};
+//#endregion
+//#region src/load-contract.ts
+/**
+* Imports a contract module with jiti (so a `.ts` entry works without a build
+* step) and returns the named export (default `contract`) or the default export.
+* Returns undefined when neither is present.
+*/
+const loadContract = async (contractPath, exportName = "contract") => {
+	const loaded = await createJiti(import.meta.url, { interopDefault: true }).import(contractPath);
+	return loaded[exportName] ?? loaded.default;
+};
+//#endregion
+//#region src/lint-deprecations.ts
+const editDistance = (a, b) => {
+	const rows = Array.from({ length: a.length + 1 }, (_, index) => [index, ...new Array(b.length).fill(0)]);
+	for (let column = 0; column <= b.length; column += 1) rows[0][column] = column;
+	for (let row = 1; row <= a.length; row += 1) for (let column = 1; column <= b.length; column += 1) {
+		const cost = a[row - 1] === b[column - 1] ? 0 : 1;
+		rows[row][column] = Math.min(rows[row - 1][column] + 1, rows[row][column - 1] + 1, rows[row - 1][column - 1] + cost);
+	}
+	return rows[a.length][b.length];
+};
+const lineOf = (text, index) => text.slice(0, index).split("\n").length;
+/**
+* Warns about JSDoc that would silently disable a deprecation, a misspelled
+* `@deprecated` tag, or more than one on the same comment. Scans the contract
+* source and the files it imports.
+*/
+const lintDeprecations = (entryPath) => {
+	const { cache } = makeResolverWithCache(entryPath);
+	const warnings = [];
+	for (const filePath of cache.keys()) {
+		const text = fs.readFileSync(filePath, "utf8");
+		for (const block of text.matchAll(/\/\*\*[\s\S]*?\*\//g)) {
+			const blockStart = block.index;
+			const tags = [...block[0].matchAll(/@(\w+)/g)];
+			const deprecatedTags = tags.filter((tag) => tag[1] === "deprecated");
+			if (deprecatedTags.length > 1) warnings.push({
+				file: filePath,
+				line: lineOf(text, blockStart + deprecatedTags[1].index),
+				message: "Duplicate `@deprecated` tag in one comment, only the first message is used."
+			});
+			for (const tag of tags) {
+				const name = tag[1].toLowerCase();
+				if (name !== "deprecated" && name.startsWith("dep") && editDistance(name, "deprecated") <= 2) warnings.push({
+					file: filePath,
+					line: lineOf(text, blockStart + tag.index),
+					message: `\`@${tag[1]}\` looks like a typo of \`@deprecated\`, it will be ignored.`
+				});
+			}
+		}
+	}
+	return warnings;
+};
+//#endregion
+export { patchDeclarationDocs as a, writeKizunaDeprecations as i, loadContract as n, collectExportedSchemaDocs as o, createDeprecationMap as r, lintDeprecations as t };