apiforge-analyzer 1.3.2 → 1.3.5

package/dist/esm/frameworks/fastify.js

@@ -0,0 +1,1076 @@
+import { Project, SyntaxKind } from "ts-morph";
+import * as fs from "fs";
+function loadJsonCatalog(filePath) {
+    if (!filePath)
+        return {};
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn(`⚠️  APIForge: could not load catalog at ${filePath}`, err);
+        return {};
+    }
+}
+let tsProject = null;
+function getProject() {
+    if (!tsProject) {
+        tsProject = new Project();
+        tsProject.addSourceFilesAtPaths([
+            "**/*.{js,ts,mjs,cjs}",
+            "!node_modules/**",
+            "!dist/**",
+        ]);
+    }
+    return tsProject;
+}
+function normalize(s) {
+    return s.replace(/\s+/g, " ").trim();
+}
+function findHandlerNode(handlerName) {
+    const project = getProject();
+    for (const sourceFile of project.getSourceFiles()) {
+        // Pehle jaisa top-level check rakho (fast path)
+        const topLevelFn = sourceFile.getFunction(handlerName);
+        if (topLevelFn)
+            return { node: topLevelFn, sourceFile };
+        // NAYA: nested function declarations bhi dhoondo (kisi bhi depth pe)
+        const nestedFns = sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration);
+        for (const fn of nestedFns) {
+            if (fn.getName() === handlerName) {
+                return { node: fn, sourceFile };
+            }
+        }
+        const props = sourceFile.getDescendantsOfKind(SyntaxKind.PropertyAssignment);
+        for (const prop of props) {
+            if (prop.getName() === handlerName) {
+                const initializer = prop.getInitializer();
+                if (initializer &&
+                    (initializer.getKind() === SyntaxKind.ArrowFunction ||
+                        initializer.getKind() === SyntaxKind.FunctionExpression)) {
+                    return { node: prop, sourceFile };
+                }
+            }
+        }
+    }
+    return null;
+}
+function findNodeBySource(handlerFn) {
+    const rawSrc = normalize(handlerFn.toString());
+    const project = getProject();
+    for (const sourceFile of project.getSourceFiles()) {
+        const candidates = [
+            ...sourceFile.getDescendantsOfKind(SyntaxKind.ArrowFunction),
+            ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionExpression),
+            ...sourceFile.getDescendantsOfKind(SyntaxKind.FunctionDeclaration),
+        ];
+        for (const cand of candidates) {
+            if (normalize(cand.getText()) === rawSrc) {
+                return { node: cand, sourceFile };
+            }
+        }
+    }
+    return null;
+}
+function findCurriedFactoryHandler(handlerFn) {
+    const rawSrc = normalize(handlerFn.toString());
+    const project = getProject();
+    for (const sourceFile of project.getSourceFiles()) {
+        const varDecls = sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+        for (const decl of varDecls) {
+            const outerInit = decl.getInitializer();
+            if (!outerInit || outerInit.getKind() !== SyntaxKind.ArrowFunction)
+                continue;
+            const outerBody = outerInit.getBody();
+            if (!outerBody)
+                continue;
+            const isInnerFn = outerBody.getKind() === SyntaxKind.ArrowFunction ||
+                outerBody.getKind() === SyntaxKind.FunctionExpression;
+            if (!isInnerFn)
+                continue;
+            const factoryName = decl.getName();
+            for (const callSiteFile of project.getSourceFiles()) {
+                const calls = callSiteFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+                for (const call of calls) {
+                    if (call.getExpression().getText() !== factoryName)
+                        continue;
+                    const candidateText = normalize(outerBody.getText());
+                    if (candidateText === rawSrc) {
+                        return { node: outerBody, sourceFile };
+                    }
+                }
+            }
+        }
+    }
+    return null;
+}
+function resolveDelegateParamName(node) {
+    if (typeof node.getParameters !== "function")
+        return null;
+    const params = node.getParameters().map((p) => p.getName());
+    if (params.length < 2)
+        return null;
+    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const expr = call.getExpression();
+        if (expr.getKind() !== SyntaxKind.Identifier)
+            continue;
+        const args = call.getArguments().map((a) => a.getText());
+        if (args.length >= 2 && args[0] === params[0] && args[1] === params[1]) {
+            return expr.getText();
+        }
+    }
+    return null;
+}
+function resolveViaCallSite(node, delegateParamName, rawMethod, rawUrl) {
+    const enclosing = node.getFirstAncestor((a) => a.getKind() === SyntaxKind.FunctionDeclaration);
+    if (!enclosing)
+        return null;
+    const paramNames = enclosing.getParameters().map((p) => p.getName());
+    const handlerIndex = paramNames.indexOf(delegateParamName);
+    const methodIndex = paramNames.indexOf("method");
+    const suffixIndex = paramNames.indexOf("suffix");
+    if (handlerIndex === -1)
+        return null;
+    const enclosingName = enclosing.getName();
+    if (!enclosingName)
+        return null;
+    const stripQuotes = (s) => s.replace(/^['"`]|['"`]$/g, "");
+    const project = getProject();
+    const candidates = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const call of calls) {
+            if (call.getExpression().getText() !== enclosingName)
+                continue;
+            const args = call.getArguments();
+            const handlerArg = args[handlerIndex];
+            if (!handlerArg || handlerArg.getKind() !== SyntaxKind.Identifier)
+                continue;
+            if (methodIndex !== -1 && args[methodIndex]) {
+                const methodArg = stripQuotes(args[methodIndex].getText()).toLowerCase();
+                if (methodArg !== rawMethod.toLowerCase())
+                    continue;
+            }
+            const suffix = suffixIndex !== -1 && args[suffixIndex]
+                ? stripQuotes(args[suffixIndex].getText())
+                : "";
+            candidates.push({ handlerName: handlerArg.getText(), suffix });
+        }
+    }
+    candidates.sort((a, b) => b.suffix.length - a.suffix.length);
+    for (const c of candidates) {
+        if (rawUrl.endsWith(c.suffix))
+            return c.handlerName;
+    }
+    return null;
+}
+function matchAll(src, re) {
+    return [...src.matchAll(re)].map((m) => m[1]).filter(Boolean);
+}
+function unique(items) {
+    return Array.from(new Set(items.filter(Boolean)));
+}
+function parseZodChain(initializer) {
+    const info = { type: "unknown" };
+    let current = initializer;
+    const calls = [];
+    while (current && current.getKind() === SyntaxKind.CallExpression) {
+        const expr = current.getExpression();
+        if (expr.getKind() === SyntaxKind.PropertyAccessExpression) {
+            const methodName = expr.getName();
+            const args = current.getArguments().map((a) => a.getText());
+            calls.unshift({ name: methodName, args });
+            current = expr.getExpression();
+        }
+        else if (expr.getKind() === SyntaxKind.Identifier &&
+            expr.getText() === "z") {
+            break;
+        }
+        else {
+            current = null;
+        }
+    }
+    for (const call of calls) {
+        switch (call.name) {
+            case "string":
+                info.type = "string";
+                break;
+            case "number":
+                info.type = "number";
+                break;
+            case "boolean":
+                info.type = "boolean";
+                break;
+            case "enum":
+                info.type = "enum";
+                info.enum = call.args[0]
+                    ?.replace(/[\[\]'"]/g, "")
+                    .split(",")
+                    .map((s) => s.trim());
+                break;
+            case "min":
+                info.min = Number(call.args[0]);
+                break;
+            case "max":
+                info.max = Number(call.args[0]);
+                break;
+            case "length": {
+                const len = Number(call.args[0]);
+                info.min = len;
+                info.max = len;
+                break;
+            }
+            case "default": {
+                const raw = call.args[0]?.replace(/['"]/g, "");
+                info.default = info.type === "number" ? Number(raw) : raw;
+                info.required = false;
+                break;
+            }
+            case "optional":
+                info.required = false;
+                break;
+        }
+    }
+    if (info.required === undefined)
+        info.required = true;
+    return info;
+}
+/** Convert an internal zod field descriptor into a JSON-Schema-shaped fragment. */
+function zodFieldToJsonSchema(field) {
+    const schema = {
+        type: field.type === "enum" ? "string" : field.type,
+    };
+    if (field.enum)
+        schema.enum = field.enum;
+    if (field.min !== undefined) {
+        if (schema.type === "string")
+            schema.minLength = field.min;
+        else
+            schema.minimum = field.min;
+    }
+    if (field.max !== undefined) {
+        if (schema.type === "string")
+            schema.maxLength = field.max;
+        else
+            schema.maximum = field.max;
+    }
+    if (field.default !== undefined)
+        schema.default = field.default;
+    return schema;
+}
+function unwrapToObjectCall(init) {
+    let current = init;
+    while (current && current.getKind() === SyntaxKind.CallExpression) {
+        const expr = current.getExpression();
+        if (expr.getKind() !== SyntaxKind.PropertyAccessExpression)
+            return null;
+        const methodName = expr.getName();
+        const target = expr.getExpression();
+        if (methodName === "object" &&
+            target.getKind() === SyntaxKind.Identifier &&
+            target.getText() === "z") {
+            return current;
+        }
+        current = target;
+    }
+    return null;
+}
+function extractZodFields(schemaVarName) {
+    const project = getProject();
+    for (const sourceFile of project.getSourceFiles()) {
+        const varDecls = sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+        for (const decl of varDecls) {
+            if (decl.getName() !== schemaVarName)
+                continue;
+            const init = decl.getInitializer();
+            if (!init || init.getKind() !== SyntaxKind.CallExpression)
+                continue;
+            const objectCall = unwrapToObjectCall(init);
+            if (!objectCall)
+                continue;
+            const objArg = objectCall.getArguments()[0];
+            if (!objArg || objArg.getKind() !== SyntaxKind.ObjectLiteralExpression)
+                continue;
+            const fields = [];
+            for (const prop of objArg.getProperties()) {
+                if (prop.getKind() !== SyntaxKind.PropertyAssignment)
+                    continue;
+                const name = prop.getName();
+                const fieldInit = prop.getInitializer();
+                const parsed = parseZodChain(fieldInit);
+                fields.push({ name, ...parsed });
+            }
+            return fields;
+        }
+    }
+    return [];
+}
+function extractZodUsage(src, target) {
+    // Native zod method call: schemaVar.parse(request.query)
+    const methodStyle = new RegExp(`(\\w+)\\.parse\\s*\\(\\s*req(?:uest)?\\.${target}\\s*\\)`);
+    const methodMatch = src.match(methodStyle);
+    if (methodMatch)
+        return methodMatch[1];
+    // Wrapper-function call: parse(schemaVar, request.query) — schema passed as
+    // an argument rather than the receiver. Idiomatic in codebases that centralize
+    // parsing (e.g. to attach a shared error formatter) instead of calling zod directly.
+    const wrapperStyle = new RegExp(`\\bparse\\s*\\(\\s*(\\w+)\\s*,\\s*req(?:uest)?\\.${target}\\s*\\)`);
+    const wrapperMatch = src.match(wrapperStyle);
+    return wrapperMatch ? wrapperMatch[1] : null;
+}
+function getLeadingJsDoc(node) {
+    if (typeof node.getFullText !== "function")
+        return undefined;
+    const fullText = node.getFullText();
+    const nodeText = node.getText();
+    const leading = fullText.slice(0, fullText.length - nodeText.length);
+    const match = leading.match(/\/\*\*([\s\S]*?)\*\//);
+    if (!match)
+        return undefined;
+    return (match[1]
+        .split("\n")
+        .map((l) => l.replace(/^\s*\*\s?/, "").trim())
+        .filter(Boolean)
+        .join(" ") || undefined);
+}
+const GUARD_FUNCTION_NAMES = ["requireScope", "requireOperator"];
+function resolveGuardAliases(sourceFile, guardNames) {
+    const aliases = [];
+    const decls = sourceFile.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+    for (const decl of decls) {
+        const init = decl.getInitializer();
+        if (init &&
+            init.getKind() === SyntaxKind.Identifier &&
+            guardNames.includes(init.getText())) {
+            aliases.push(decl.getName());
+        }
+    }
+    return aliases;
+}
+function resolveScopeArgExpression(enclosingNode, argExpr) {
+    if (!argExpr)
+        return {};
+    if (argExpr.getKind() === SyntaxKind.StringLiteral) {
+        return { scope: argExpr.getLiteralText() };
+    }
+    if (argExpr.getKind() === SyntaxKind.ConditionalExpression) {
+        const whenTrue = argExpr.getWhenTrue();
+        const whenFalse = argExpr.getWhenFalse();
+        if (whenTrue.getKind() === SyntaxKind.StringLiteral &&
+            whenFalse.getKind() === SyntaxKind.StringLiteral) {
+            return {
+                scopes: [whenTrue.getLiteralText(), whenFalse.getLiteralText()],
+                scopeCondition: argExpr.getCondition().getText(),
+            };
+        }
+        return { scopeUnresolved: true, scopeExpression: argExpr.getText() };
+    }
+    if (argExpr.getKind() === SyntaxKind.Identifier) {
+        const varName = argExpr.getText();
+        const decls = enclosingNode.getDescendantsOfKind(SyntaxKind.VariableDeclaration);
+        for (const decl of decls) {
+            if (decl.getName() === varName) {
+                const init = decl.getInitializer();
+                if (init)
+                    return resolveScopeArgExpression(enclosingNode, init);
+            }
+        }
+        return { scopeUnresolved: true, scopeExpression: varName };
+    }
+    return { scopeUnresolved: true, scopeExpression: argExpr.getText() };
+}
+function extractScopeInfoAst(node) {
+    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const expr = call.getExpression();
+        if (expr.getKind() !== SyntaxKind.Identifier)
+            continue;
+        if (expr.getText() !== "requireScope")
+            continue;
+        const args = call.getArguments();
+        if (args.length < 2)
+            continue;
+        const line = typeof call.getStartLineNumber === "function"
+            ? call.getStartLineNumber()
+            : undefined;
+        return { ...resolveScopeArgExpression(node, args[1]), scopeLine: line };
+    }
+    return {};
+}
+// ---- NEW: dynamic status code resolution (same pattern as scope resolution) ----
+function resolveStatusArgExpression(argExpr) {
+    if (!argExpr)
+        return {};
+    if (argExpr.getKind() === SyntaxKind.NumericLiteral) {
+        return { literal: Number(argExpr.getText()) };
+    }
+    if (argExpr.getKind() === SyntaxKind.ConditionalExpression) {
+        const whenTrue = argExpr.getWhenTrue();
+        const whenFalse = argExpr.getWhenFalse();
+        if (whenTrue.getKind() === SyntaxKind.NumericLiteral &&
+            whenFalse.getKind() === SyntaxKind.NumericLiteral) {
+            return {
+                options: [Number(whenTrue.getText()), Number(whenFalse.getText())],
+                condition: argExpr.getCondition().getText(),
+            };
+        }
+        // ternary exists but branches aren't plain numbers (nested calls, vars) —
+        // don't guess, report the full expression as unresolved.
+        return { unresolved: true, expression: argExpr.getText() };
+    }
+    // identifier, member access, function call, etc. — can't resolve statically
+    return { unresolved: true, expression: argExpr.getText() };
+}
+function extractStatusInfoAst(node) {
+    const responseStatuses = [];
+    const dynamicStatuses = [];
+    const statusSources = [];
+    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const expr = call.getExpression();
+        if (expr.getKind() !== SyntaxKind.PropertyAccessExpression)
+            continue;
+        const methodName = expr.getName();
+        if (methodName !== "status" && methodName !== "code")
+            continue;
+        const args = call.getArguments();
+        if (args.length < 1)
+            continue;
+        const line = typeof call.getStartLineNumber === "function"
+            ? call.getStartLineNumber()
+            : undefined;
+        const result = resolveStatusArgExpression(args[0]);
+        if (result.literal !== undefined) {
+            responseStatuses.push(result.literal);
+            statusSources.push({ status: result.literal, line });
+        }
+        else if (result.options) {
+            responseStatuses.push(...result.options);
+            dynamicStatuses.push({
+                options: result.options,
+                condition: result.condition,
+                line,
+            });
+        }
+        else if (result.unresolved) {
+            dynamicStatuses.push({
+                unresolved: true,
+                expression: result.expression,
+                line,
+            });
+        }
+    }
+    return {
+        responseStatuses: unique(responseStatuses),
+        dynamicStatuses,
+        statusSources,
+    };
+}
+// ---- END NEW ----
+function detectStreaming(node) {
+    const calls = node.getDescendantsOfKind(SyntaxKind.CallExpression);
+    for (const call of calls) {
+        const expr = call.getExpression();
+        if (expr.getKind() !== SyntaxKind.PropertyAccessExpression)
+            continue;
+        const methodName = expr.getName();
+        const target = expr.getExpression();
+        const targetText = target.getText();
+        // reply.raw.writeHead(...) / reply.raw.write(...)
+        if ((methodName === "writeHead" || methodName === "write") &&
+            /\.raw$/.test(targetText)) {
+            return true;
+        }
+        // reply.hijack()
+        if (methodName === "hijack") {
+            return true;
+        }
+    }
+    return false;
+}
+function collectContentTypeParsers() {
+    const project = getProject();
+    const parsers = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const call of calls) {
+            const expr = call.getExpression();
+            if (expr.getKind() !== SyntaxKind.PropertyAccessExpression)
+                continue;
+            const methodName = expr.getName();
+            const isAdd = methodName === "addContentTypeParser";
+            const isRemove = methodName === "removeContentTypeParser";
+            if (!isAdd && !isRemove)
+                continue;
+            const args = call.getArguments();
+            if (args.length < 1)
+                continue;
+            // First arg can be a string literal or an array of string literals
+            const firstArg = args[0];
+            const contentTypes = [];
+            if (firstArg.getKind() === SyntaxKind.StringLiteral) {
+                contentTypes.push(firstArg.getLiteralText());
+            }
+            else if (firstArg.getKind() === SyntaxKind.ArrayLiteralExpression) {
+                for (const el of firstArg.getElements()) {
+                    if (el.getKind() === SyntaxKind.StringLiteral) {
+                        contentTypes.push(el.getLiteralText());
+                    }
+                }
+            }
+            else {
+                // dynamic content-type expression — can't resolve statically,
+                // record the raw expression text instead of a real content type
+                contentTypes.push(`unresolved:${firstArg.getText()}`);
+            }
+            const prefixes = findEnclosingRegisterPrefixes(call);
+            const prefix = prefixes.length > 0 ? prefixes.join("") : undefined;
+            for (const ct of contentTypes) {
+                parsers.push({
+                    action: isAdd ? "add" : "remove",
+                    contentType: ct,
+                    scope: prefix ? "scoped" : "global",
+                    prefix,
+                    file: sourceFile.getFilePath(),
+                    line: typeof call.getStartLineNumber === "function"
+                        ? call.getStartLineNumber()
+                        : undefined,
+                });
+            }
+        }
+    }
+    return parsers;
+}
+function applicableContentTypeParsersForPath(path, allParsers) {
+    return allParsers.filter((p) => p.scope === "global" || (p.prefix && path.startsWith(p.prefix)));
+}
+function findEnclosingRegisterPrefixes(node) {
+    const prefixes = [];
+    let current = node;
+    while (current) {
+        const fnAncestor = current.getFirstAncestor((a) => a.getKind() === SyntaxKind.ArrowFunction ||
+            a.getKind() === SyntaxKind.FunctionExpression);
+        if (!fnAncestor)
+            break;
+        const callExpr = fnAncestor.getParent();
+        if (callExpr && callExpr.getKind() === SyntaxKind.CallExpression) {
+            const callee = callExpr.getExpression();
+            if (callee.getKind() === SyntaxKind.PropertyAccessExpression &&
+                callee.getName() === "register") {
+                const args = callExpr.getArguments();
+                const optsArg = args[1];
+                if (optsArg &&
+                    optsArg.getKind() === SyntaxKind.ObjectLiteralExpression) {
+                    const prefixProp = optsArg
+                        .getProperties()
+                        .find((p) => p.getKind() === SyntaxKind.PropertyAssignment &&
+                        p.getName() === "prefix");
+                    if (prefixProp) {
+                        const init = prefixProp.getInitializer();
+                        if (init && init.getKind() === SyntaxKind.StringLiteral) {
+                            prefixes.unshift(init.getLiteralText());
+                        }
+                    }
+                }
+            }
+        }
+        current = fnAncestor;
+    }
+    return prefixes;
+}
+const IGNORED_HOOK_TYPES = new Set([
+    "onRoute",
+    "onRegister",
+    "onReady",
+    "onClose",
+    "onListen",
+]);
+function collectGlobalHooks() {
+    const project = getProject();
+    const hooks = [];
+    for (const sourceFile of project.getSourceFiles()) {
+        const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const call of calls) {
+            const expr = call.getExpression();
+            if (expr.getKind() !== SyntaxKind.PropertyAccessExpression)
+                continue;
+            if (expr.getName() !== "addHook")
+                continue;
+            const args = call.getArguments();
+            if (args.length < 1 || args[0].getKind() !== SyntaxKind.StringLiteral)
+                continue;
+            const hookType = args[0].getLiteralText();
+            if (IGNORED_HOOK_TYPES.has(hookType))
+                continue;
+            const prefixes = findEnclosingRegisterPrefixes(call);
+            const prefix = prefixes.length > 0 ? prefixes.join("") : undefined;
+            hooks.push({
+                type: hookType,
+                scope: prefix ? "scoped" : "global",
+                prefix,
+                file: sourceFile.getFilePath(),
+                line: typeof call.getStartLineNumber === "function"
+                    ? call.getStartLineNumber()
+                    : undefined,
+            });
+        }
+    }
+    return hooks;
+}
+function applicableHooksForPath(path, allHooks) {
+    return allHooks.filter((h) => h.scope === "global" || (h.prefix && path.startsWith(h.prefix)));
+}
+function extractHeaderInfoAst(node) {
+    const results = [];
+    const elementAccesses = node.getDescendantsOfKind(SyntaxKind.ElementAccessExpression);
+    for (const el of elementAccesses) {
+        const target = el.getExpression();
+        if (!/req(?:uest)?\.headers$/.test(target.getText()))
+            continue;
+        const argExpr = el.getArgumentExpression();
+        if (!argExpr || argExpr.getKind() !== SyntaxKind.StringLiteral)
+            continue;
+        results.push({
+            name: argExpr.getLiteralText(),
+            line: typeof el.getStartLineNumber === "function"
+                ? el.getStartLineNumber()
+                : undefined,
+        });
+    }
+    return results;
+}
+function extractFromNode(node, sourceFile) {
+    const src = node.getText();
+    let queryParams = unique(matchAll(src, /req(?:uest)?\.query\.([a-zA-Z0-9_$]+)/g));
+    let requestBodyFields = unique(matchAll(src, /req(?:uest)?\.body\.([a-zA-Z0-9_$]+)/g));
+    let queryParamsSchema = [];
+    let requestBodySchema = [];
+    const queryZodVar = extractZodUsage(src, "query");
+    if (queryZodVar) {
+        queryParamsSchema = extractZodFields(queryZodVar);
+        queryParams = queryParamsSchema.map((f) => f.name);
+    }
+    const bodyZodVar = extractZodUsage(src, "body");
+    if (bodyZodVar) {
+        requestBodySchema = extractZodFields(bodyZodVar);
+        requestBodyFields = requestBodySchema.map((f) => f.name);
+    }
+    const headerInfoAst = extractHeaderInfoAst(node);
+    return {
+        queryParams,
+        requestBodyFields,
+        queryParamsSchema,
+        requestBodySchema,
+        headerParams: unique(headerInfoAst.map((h) => h.name)),
+        headerSources: headerInfoAst,
+        hasAuth: (() => {
+            const aliases = sourceFile
+                ? resolveGuardAliases(sourceFile, GUARD_FUNCTION_NAMES)
+                : [];
+            const names = [...GUARD_FUNCTION_NAMES, ...aliases]
+                .map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+                .join("|");
+            const re = new RegExp(`\\b(${names})\\s*\\(|auth\\.(either|client|machine)`);
+            return re.test(src);
+        })(),
+        ...extractStatusInfoAst(node),
+        ...extractScopeInfoAst(node),
+        streaming: detectStreaming(node),
+    };
+}
+function resolveHandlerInfo(handlerFn, raw) {
+    const empty = {
+        queryParams: [],
+        requestBodyFields: [],
+        queryParamsSchema: [],
+        requestBodySchema: [],
+        headerParams: [],
+        responseStatuses: [],
+        dynamicStatuses: [],
+        hasAuth: false,
+        resolved: false,
+        deprecated: false,
+        scope: undefined,
+        scopeUnresolved: undefined,
+        scopeExpression: undefined,
+        scopeLine: undefined,
+        statusSources: [],
+        headerSources: [],
+        streaming: false,
+    };
+    if (!handlerFn || typeof handlerFn !== "function")
+        return empty;
+    try {
+        const handlerName = handlerFn.name;
+        let found = handlerName ? findHandlerNode(handlerName) : null;
+        if (!found)
+            found = findNodeBySource(handlerFn);
+        if (!found)
+            found = findCurriedFactoryHandler(handlerFn);
+        if (!found)
+            return empty;
+        let { node, sourceFile } = found;
+        const wrapperSrc = node.getText();
+        const deprecated = /reply\.header\s*\(\s*['"]deprecation['"]/.test(wrapperSrc);
+        const delegateParamName = resolveDelegateParamName(node);
+        if (delegateParamName) {
+            const direct = findHandlerNode(delegateParamName);
+            if (direct) {
+                node = direct.node;
+                sourceFile = direct.sourceFile;
+            }
+            else {
+                const targetName = resolveViaCallSite(node, delegateParamName, raw.method, raw.url);
+                if (targetName) {
+                    const targetFound = findHandlerNode(targetName);
+                    if (targetFound) {
+                        node = targetFound.node;
+                        sourceFile = targetFound.sourceFile;
+                    }
+                }
+            }
+        }
+        const jsDoc = getLeadingJsDoc(node);
+        const extracted = extractFromNode(node, sourceFile);
+        return {
+            file: sourceFile.getFilePath(),
+            line: typeof node.getStartLineNumber === "function"
+                ? node.getStartLineNumber()
+                : undefined,
+            description: jsDoc,
+            ...extracted,
+            resolved: true,
+            deprecated,
+        };
+    }
+    catch (err) {
+        console.warn("⚠️  APIForge: handler resolution error", err);
+        return empty;
+    }
+}
+export async function analyzeFastify(app, options) {
+    const scopeCatalog = loadJsonCatalog(options?.scopeCatalogPath);
+    const errorCatalog = loadJsonCatalog(options?.errorCatalogPath);
+    const envelopes = options?.envelopes || {};
+    const sidecarAnnotations = loadJsonCatalog(options?.annotationsPath);
+    const rawRoutes = [];
+    app.addHook("onRoute", (routeOptions) => {
+        rawRoutes.push({
+            method: routeOptions.method,
+            url: routeOptions.url,
+            handlerFn: routeOptions.handler,
+            config: routeOptions.config,
+            schema: routeOptions.schema,
+            onRequest: routeOptions.onRequest,
+            preHandler: routeOptions.preHandler,
+        });
+    });
+    await app.ready();
+    const globalHooks = collectGlobalHooks();
+    const contentTypeParsers = collectContentTypeParsers();
+    const filtered = rawRoutes.filter((r) => r.method !== "HEAD");
+    const routes = filtered.map((r) => buildRoute(r, scopeCatalog, errorCatalog, envelopes, globalHooks, contentTypeParsers, sidecarAnnotations));
+    // Stale annotation warning: any sidecar entry that doesn't match a
+    // discovered runtime route is pointing at something that no longer exists.
+    const discoveredKeys = new Set(filtered.map((r) => `${r.method} ${r.url}`));
+    for (const key of Object.keys(sidecarAnnotations)) {
+        if (!discoveredKeys.has(key)) {
+            console.warn(`⚠️  Stale APIForge annotation: ${key}`);
+        }
+    }
+    console.log(`📦 Fastify: captured ${routes.length} routes`);
+    return routes;
+}
+function mergeAnnotation(inferred, annotation, errorCatalog = {}, routeKey) {
+    if (!annotation || typeof annotation !== "object")
+        return inferred;
+    // An annotation can name error codes that never showed up as a resolved
+    // response status (e.g. thrown from a shared error middleware, not a
+    // literal `reply.status(...)` in the handler) — look those up too instead
+    // of only ever joining on inferred.responseStatuses.
+    const errors = Array.isArray(annotation.errors)
+        ? annotation.errors.map((code) => {
+            if (!(code in errorCatalog)) {
+                console.warn(`⚠️  APIForge: annotation on ${routeKey || "a route"} names error code "${code}", which is not in the error catalog — reported without status/retry/message`);
+            }
+            return { code, ...(errorCatalog[code] || {}) };
+        })
+        : inferred.errors;
+    return {
+        ...inferred,
+        summary: typeof annotation.summary === "string"
+            ? annotation.summary
+            : inferred.summary,
+        description: typeof annotation.description === "string"
+            ? annotation.description
+            : inferred.description,
+        tags: Array.isArray(annotation.tags) ? annotation.tags : inferred.tags,
+        deprecated: typeof annotation.deprecated === "boolean"
+            ? annotation.deprecated
+            : inferred.deprecated,
+        errors,
+    };
+}
+const AUTH_HOOK_NAME_PATTERN = /auth|jwt|verify|require|guard|protect|session/i;
+const AUTH_HOOK_BODY_PATTERN = /jwtVerify|verifyJwt|jwt\.verify|\.verify\(|Authorization|Bearer|req(?:uest)?\.headers\[?['"]?authorization['"]?\]?|unauthorized|401/i;
+function inspectRouteLevelAuth(raw) {
+    const collect = (val) => {
+        if (!val)
+            return [];
+        return Array.isArray(val) ? val : [val];
+    };
+    const hooks = [...collect(raw.onRequest), ...collect(raw.preHandler)];
+    const allHookNames = hooks
+        .map((fn) => typeof fn === "function" ? fn.name || "(anonymous)" : String(fn))
+        .filter(Boolean);
+    const matchedAuthHookNames = hooks
+        .filter((fn) => {
+        if (typeof fn !== "function")
+            return false;
+        // Pehle naam se try karo (fast path)
+        if (fn.name && AUTH_HOOK_NAME_PATTERN.test(fn.name))
+            return true;
+        // Naam anonymous ho toh function ka source body check karo
+        try {
+            const src = fn.toString();
+            return AUTH_HOOK_BODY_PATTERN.test(src);
+        }
+        catch {
+            return false;
+        }
+    })
+        .map((fn) => fn.name || "(anonymous, matched via body pattern)");
+    return {
+        hasRouteLevelHooks: hooks.length > 0,
+        matchedAuthHookNames,
+        allHookNames,
+    };
+}
+function buildRoute(raw, scopeCatalog = {}, errorCatalog = {}, envelopes = {}, globalHooks = [], contentTypeParsers = [], sidecarAnnotations = {}) {
+    const method = raw.method;
+    const path = raw.url;
+    const pathParams = [...path.matchAll(/:(\w+)/g)].map((m) => m[1]);
+    const inferredTag = path
+        .split("/")
+        .filter(Boolean)
+        .find((s) => !s.startsWith(":") && !/^v\d+$/.test(s)) ||
+        "general";
+    const operationId = `${method.toLowerCase()}_${path
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_|_$/, "")}`;
+    const handlerInfo = resolveHandlerInfo(raw.handlerFn, raw);
+    const routeLevelAuth = inspectRouteLevelAuth(raw);
+    let hasAuthFinal;
+    let authSource;
+    if (routeLevelAuth.matchedAuthHookNames.length > 0) {
+        // Route-level decorator jaise server.authenticate — sabse reliable signal
+        hasAuthFinal = true;
+        authSource = `route-level hook: ${routeLevelAuth.matchedAuthHookNames.join(", ")}`;
+    }
+    else if (handlerInfo.resolved && handlerInfo.hasAuth) {
+        // Handler ke andar requireScope/requireOperator/auth.either pattern mila
+        hasAuthFinal = true;
+        authSource = "handler-level guard call";
+    }
+    else if (routeLevelAuth.hasRouteLevelHooks) {
+        // Koi onRequest/preHandler hook hai, lekin naam se auth confirm nahi ho paya —
+        // "false" bolna galat hoga (spec requirement #34), isliye "unknown"
+        hasAuthFinal = "unknown";
+        authSource = `unresolved route-level hook(s): ${routeLevelAuth.allHookNames.join(", ")} — inspect manually`;
+    }
+    else if (!handlerInfo.resolved) {
+        // Handler khud resolve nahi hua, toh confidently "no auth" nahi bol sakte
+        hasAuthFinal = "unknown";
+        authSource = "handler could not be resolved";
+    }
+    else {
+        // Handler resolve ho gaya AND koi route-level hook nahi AND koi guard call nahi
+        hasAuthFinal = false;
+    }
+    const sourceFor = (line) => handlerInfo.file && line ? `${handlerInfo.file}:${line}` : undefined;
+    let scopeInfo = undefined;
+    if (handlerInfo.scope) {
+        scopeInfo = {
+            name: handlerInfo.scope,
+            ...(scopeCatalog[handlerInfo.scope] || {}),
+            source: sourceFor(handlerInfo.scopeLine),
+        };
+    }
+    else if (handlerInfo.scopes) {
+        scopeInfo = {
+            options: handlerInfo.scopes.map((s) => ({
+                name: s,
+                ...(scopeCatalog[s] || {}),
+            })),
+            condition: handlerInfo.scopeCondition,
+            source: sourceFor(handlerInfo.scopeLine),
+        };
+    }
+    else if (handlerInfo.scopeUnresolved) {
+        scopeInfo = {
+            unresolved: true,
+            expression: handlerInfo.scopeExpression,
+            source: sourceFor(handlerInfo.scopeLine),
+        };
+    }
+    const errorEntries = Object.entries(errorCatalog).filter(([, v]) => handlerInfo.responseStatuses?.includes(v.status));
+    const errors = errorEntries.map(([code, v]) => ({
+        code,
+        ...v,
+    }));
+    const prefixMatch = path.match(/^\/(v\d+)(\/|$)/);
+    const routePrefix = prefixMatch ? `/${prefixMatch[1]}` : undefined;
+    let responseEnvelope = undefined;
+    if (routePrefix && envelopes[routePrefix]) {
+        const envConfig = envelopes[routePrefix];
+        if (!("bare" in envConfig && envConfig.bare)) {
+            const isExcluded = envConfig.excluded?.includes(path);
+            if (!isExcluded) {
+                responseEnvelope = {
+                    wrapper: envConfig.wrapper,
+                    dataField: envConfig.dataField,
+                };
+            }
+        }
+    }
+    else if (routePrefix && Object.keys(envelopes).length > 0) {
+        // The caller declared envelope shapes for some prefixes but not this one.
+        // Silently defaulting to "bare" here is exactly the bug this feature exists
+        // to prevent — a new prefix must be declared (wrapped or explicitly `bare`),
+        // not inherit a guess. Surface it instead.
+        console.warn(`⚠️  APIForge: no envelope config declared for prefix "${routePrefix}" (route ${method} ${path}) — add an entry to \`envelopes\` (wrapped, or { bare: true }) so the response shape is reported correctly`);
+    }
+    // Only build an envelope-aware `responses` object when the caller actually
+    // configured envelopes — otherwise leave `responses` unset so the generic
+    // fallback in export.ts's buildResponses() behaves exactly as before.
+    let responses = undefined;
+    if (Object.keys(envelopes).length > 0) {
+        const upperMethod = method.toUpperCase();
+        const primaryStatus = handlerInfo.responseStatuses?.find((s) => s >= 200 && s < 300) ??
+            (upperMethod === "POST" ? 201 : upperMethod === "DELETE" ? 204 : 200);
+        if (primaryStatus !== 204) {
+            const bareSchema = {
+                type: "object",
+                properties: {
+                    success: { type: "boolean", example: true },
+                    endpoint: { type: "string", example: `${upperMethod} ${path}` },
+                    resource: { type: "string", example: inferredTag.toLowerCase() },
+                },
+            };
+            const schema = responseEnvelope
+                ? {
+                    type: "object",
+                    description: responseEnvelope.wrapper,
+                    properties: { [responseEnvelope.dataField]: bareSchema },
+                }
+                : bareSchema;
+            responses = {
+                [String(primaryStatus)]: {
+                    description: "Successful response",
+                    content: { "application/json": { schema } },
+                },
+            };
+        }
+    }
+    // Zod-derived field info has real types (enum members, min/max, defaults) —
+    // surface it via the standard Route.parameters / Route.requestBody shape,
+    // not just the bare field-name arrays, or uploadRoutes()/exportToJSON() (which
+    // only ever look at `parameters`/`requestBody`) silently discard it and fall
+    // back to generic `{ type: 'string' }` placeholders.
+    const zodParameters = (handlerInfo.queryParamsSchema || []).map((f) => ({
+        name: f.name,
+        in: "query",
+        required: f.required !== false,
+        type: f.type,
+        schema: zodFieldToJsonSchema(f),
+        description: `Query parameter: ${f.name}.`,
+    }));
+    let requestBody = undefined;
+    if (handlerInfo.requestBodySchema && handlerInfo.requestBodySchema.length > 0) {
+        const properties = {};
+        const required = [];
+        for (const f of handlerInfo.requestBodySchema) {
+            properties[f.name] = zodFieldToJsonSchema(f);
+            if (f.required !== false)
+                required.push(f.name);
+        }
+        requestBody = {
+            required: required.length > 0,
+            content: {
+                "application/json": {
+                    schema: { type: "object", required, properties },
+                },
+            },
+        };
+    }
+    const inferred = {
+        method,
+        path,
+        tag: inferredTag,
+        tags: [inferredTag],
+        operationId,
+        summary: `${method} ${path}`,
+        description: handlerInfo.resolved
+            ? handlerInfo.deprecated
+                ? `[Deprecated] ${handlerInfo.description || ""}`.trim()
+                : handlerInfo.description
+            : "⚠️ Handler could not be resolved (wrapper/delegated handler) — auth, params, and schema may be incomplete",
+        middleware: [],
+        authRequired: hasAuthFinal,
+        pathParams,
+        queryParams: handlerInfo.queryParams,
+        requestBodyFields: handlerInfo.requestBodyFields,
+        queryParamsSchema: handlerInfo.queryParamsSchema,
+        requestBodySchema: handlerInfo.requestBodySchema,
+        parameters: zodParameters.length > 0 ? zodParameters : undefined,
+        requestBody,
+        responses,
+        headerParams: handlerInfo.headerParams,
+        responseStatuses: handlerInfo.responseStatuses,
+        dynamicStatuses: (handlerInfo.dynamicStatuses || []).map((d) => ({
+            ...d,
+            line: undefined,
+            source: sourceFor(d.line),
+        })),
+        hooks: applicableHooksForPath(path, globalHooks).map((h) => ({
+            type: h.type,
+            scope: h.scope,
+            ...(h.prefix ? { prefix: h.prefix } : {}),
+        })),
+        streaming: handlerInfo.streaming || false,
+        contentTypeParsers: applicableContentTypeParsersForPath(path, contentTypeParsers).map((p) => ({
+            action: p.action,
+            contentType: p.contentType,
+            scope: p.scope,
+            ...(p.prefix ? { prefix: p.prefix } : {}),
+        })),
+        statusSources: (handlerInfo.statusSources || []).map((s) => ({
+            status: s.status,
+            source: sourceFor(s.line),
+        })),
+        headerSources: (handlerInfo.headerSources || []).map((h) => ({
+            name: h.name,
+            source: sourceFor(h.line),
+        })),
+        errors,
+        responseEnvelope,
+        scope: scopeInfo,
+        linkedPaths: [],
+        hasAuth: hasAuthFinal,
+        authSource,
+        framework: "fastify",
+        deprecated: handlerInfo.deprecated,
+    };
+    const routeKey = `${method} ${path}`;
+    const sidecarAnnotation = sidecarAnnotations[routeKey];
+    const inlineAnnotation = raw.config?.apiforge;
+    let merged = mergeAnnotation(inferred, sidecarAnnotation, errorCatalog, routeKey);
+    merged = mergeAnnotation(merged, inlineAnnotation, errorCatalog, routeKey);
+    if (sidecarAnnotation ||
+        (inlineAnnotation && typeof inlineAnnotation === "object")) {
+        merged.annotated = true;
+    }
+    return merged;
+}