autodocsync 1.0.0

package/bin/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import fs from "fs";
+import path from "path";
+import { Command } from "commander";
+import { scanProject } from "../src/scanners/index.js";
+import {
+  checkOllama,
+  printOllamaGuide,
+  printModelGuide,
+} from "../src/check-ollama.js";
+import {
+  describeEndpointWithMistral,
+  summarizeProjectWithMistral,
+} from "../src/llm.js";
+import { generateOpenAPI } from "../src/openapi-gen.js";
+
+const program = new Command();
+
+program
+  .name("docsync")
+  .description("Generate OpenAPI docs")
+  .version("1.0.0");
+
+program
+  .command("init")
+  .description("Initialize project")
+  .action(() => {
+    console.log("Init command running...");
+  });
+
+program
+  .command("generate")
+  .argument("[projectDir]", "Project root", ".")
+  .option("-o, --output <dir>", "Output folder", ".")
+  .action(async (projectDir, options) => {
+    const projectRoot = path.resolve(process.cwd(), projectDir);
+    console.log("[docSync] Scanning project...");
+
+    const ollama = await checkOllama();
+    let useLlm = false;
+
+    if (!ollama.running) {
+      printOllamaGuide();
+      console.warn(
+        "[docSync] Warning: Ollama is not running. AI features disabled.",
+      );
+    } else if (!ollama.hasModel) {
+      printModelGuide();
+      console.warn(
+        "[docSync] Warning: Mistral model is missing. AI features disabled.",
+      );
+    } else {
+      useLlm = true;
+    }
+
+    const scan = await scanProject(projectRoot);
+    console.log(
+      `[docSync] Found ${scan.routes.length} routes, ${scan.files.length} files, ${Object.keys(scan.models).length} models`,
+    );
+
+    if (useLlm) {
+      if (scan.hasReadme) {
+        console.log("[docSync] Summarizing project from README...");
+        const summary = await summarizeProjectWithMistral(scan.existingReadme);
+        if (summary) scan.projectDescription = summary;
+      }
+
+      console.log("[docSync] Enhancing endpoint descriptions with Mistral...");
+      const enhancedDescriptions = {};
+      for (const route of scan.routes) {
+        const endpoint = {
+          method: route.method,
+          url: route.path,
+        };
+        try {
+          const desc = await describeEndpointWithMistral(endpoint);
+          if (!enhancedDescriptions[route.path])
+            enhancedDescriptions[route.path] = {};
+          enhancedDescriptions[route.path][route.method] = desc;
+        } catch (err) {
+          console.error(
+            `[docSync] Failed for ${route.method} ${route.path}:`,
+            err.message,
+          );
+        }
+      }
+
+      console.log("[docSync] Generating openapi.json...");
+      const openApiSpec = generateOpenAPI(scan, enhancedDescriptions);
+
+      const outDir = path.resolve(process.cwd(), options.output);
+      fs.mkdirSync(outDir, { recursive: true });
+
+      fs.writeFileSync(
+        path.join(outDir, "openapi.json"),
+        JSON.stringify(openApiSpec, null, 2),
+        "utf-8",
+      );
+      console.log(
+        `[docSync] SUCCESS: openapi.json generated at ${path.join(outDir, "openapi.json")}`,
+      );
+    } else {
+      console.log(
+        "[docSync] Generating openapi.json (without AI enhancement)...",
+      );
+      const openApiSpec = generateOpenAPI(scan);
+
+      const outDir = path.resolve(process.cwd(), options.output);
+      fs.mkdirSync(outDir, { recursive: true });
+
+      fs.writeFileSync(
+        path.join(outDir, "openapi.json"),
+        JSON.stringify(openApiSpec, null, 2),
+        "utf-8",
+      );
+      console.log(
+        `[docSync] SUCCESS: openapi.json generated at ${path.join(outDir, "openapi.json")}`,
+      );
+    }
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "autodocsync",
+  "version": "1.0.0",
+  "description": "Combines TS code parsing and local LLMs to generate OpenAPI specs automatically",
+  "main": "src/openapi-gen.js",
+  "type": "module",
+  "bin": {
+    "autodocsync": "bin/index.js"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "autodoc",
+    "api",
+    "express"
+  ],
+  "author": "Arshdeep Anand",
+  "license": "MIT",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node bin/index.js"
+  },
+  "dependencies": {
+    "axios": "^1.14.0",
+    "commander": "^11.1.0",
+    "express": "^5.2.1",
+    "glob": "^10.3.10",
+    "ts-morph": "^21.0.1"
+  }
+}

package/src/check-ollama.js

@@ -0,0 +1,52 @@
+import axios from "axios";
+
+const OLLAMA_URL = "http://localhost:11434";
+
+export async function checkOllama() {
+  try {
+    const res = await axios.get(`${OLLAMA_URL}/api/tags`, {
+      timeout: 30000,
+    });
+    const data = res.data;
+
+    // Check if our model is already pulled
+    const models = data.models?.map((m) => m.name) ?? [];
+    const hasModel = models.some((m) => m.startsWith("mistral"));
+
+    return { running: true, hasModel };
+  } catch {
+    return { running: false, hasModel: false };
+  }
+}
+
+export function printOllamaGuide() {
+  console.log(`
+╔══════════════════════════════════════════════════╗
+║         autodocs-sync — setup required           ║
+╠══════════════════════════════════════════════════╣
+║  Ollama is not running on this machine.          ║
+║                                                  ║
+║  To enable AI-powered docs:                      ║
+║                                                  ║
+║  1. Install Ollama                               ║
+║     → https://ollama.com/download                ║
+║                                                  ║
+║  2. Pull the model (~4.4 GB, one time)           ║
+║     $ ollama pull mistral                        ║
+║                                                  ║
+║  3. Regenerate docs manually after setup         ║
+║     $ npx autodocs                               ║
+╚══════════════════════════════════════════════════╝
+  `);
+}
+
+export function printModelGuide() {
+  console.log(`
+[autodocs] Ollama is running but mistral is not pulled yet.
+Run: ollama pull mistral
+Then run: npx autodocs
+  `);
+}
+
+export const OLLAMA_MODEL = "mistral";
+export const OLLAMA_API = OLLAMA_URL;

package/src/llm.js

@@ -0,0 +1,56 @@
+import axios from "axios";
+
+export async function describeEndpointWithMistral(endpoint) {
+  const method = endpoint.method.toUpperCase();
+  const url = endpoint.url;
+  
+  // Extract the resource from the URL (e.g., /users, /posts, /comments)
+  const resourceMatch = url.match(/\/([a-zA-Z]+)(\?|$|\/{1})/);
+  const resource = resourceMatch ? resourceMatch[1] : 'resource';
+  
+  try {
+    // Try to use Ollama HTTP API
+    const prompt = `As a Senior API Architect, generate a highly professional, detailed description for this API endpoint. Explain its purpose and its role in the system. Use industry-standard terminology.\n\nMethod: ${method}\nURL: ${url}\n\nReturn only the description text.`;
+    
+    const response = await axios.post('http://localhost:11434/api/generate', {
+      model: 'mistral',
+      prompt: prompt,
+      stream: false
+    });
+
+    const data = response.data;
+    const description = data.response?.trim();
+    return description || generateDefaultDescription(method, resource, url);
+  } catch (error) {
+    // Fallback: Generate smart description based on URL and method
+    return generateDefaultDescription(method, resource, url);
+  }
+}
+
+export async function summarizeProjectWithMistral(readme) {
+  try {
+    const prompt = `Based on this README, generate a brief (1-2 sentences), professional description of this project for API documentation:\n\n${readme.slice(0, 3000)}`;
+    const response = await axios.post('http://localhost:11434/api/generate', {
+      model: 'mistral',
+      prompt: prompt,
+      stream: false
+    });
+
+    const data = response.data;
+    return data.response?.trim() || "Industry standard API documentation.";
+  } catch (error) {
+    console.error("[llm] Failed to summarize project:", error.message);
+    return "Industry standard API documentation.";
+  }
+}
+
+function generateDefaultDescription(method, resource, url) {
+  const descriptions = {
+    'GET': `Retrieves ${resource} data from the server.`,
+    'POST': `Creates a new ${resource.slice(0, -1) || 'resource'} and returns the created object.`,
+    'PUT': `Updates an existing ${resource.slice(0, -1) || 'resource'} with the provided data.`,
+    'DELETE': `Permanently deletes the specified ${resource.slice(0, -1) || 'resource'} from the server.`,
+    'PATCH': `Partially updates a ${resource.slice(0, -1) || 'resource'} with the provided changes.`
+  };
+  return descriptions[method] || `Performs a ${method} request to the ${resource} endpoint.`;
+}

package/src/openapi-gen.js

@@ -0,0 +1,345 @@
+import path from "path";
+const tagDescriptionMap = {
+  Auth: "Authentication algorithms, secure login, and session management",
+  User: "User profile management, account settings, and event registrations",
+  Admin:
+    "Administrative operations for system configuration and user management",
+  Manager:
+    "Management interface for high-level operations, certificates, and analytics",
+  OTP: "One-time password operations for verification and secure resets",
+  Event: "Event management, registration tracking, and results processing",
+  Certificate: "Certificate generation, previewing, and status tracking",
+  Analytics: "Data analytics, system reporting, and performance metrics",
+  General: "General system and resource operations",
+};
+
+/**
+ * Generates an OpenAPI 3.0.3 specification from scanned project data.
+ */
+export function generateOpenAPI(scan, enhancedDescriptions = {}) {
+  // 1. Determine common prefix (e.g., /api/v1)
+  const allPaths = scan.routes.map((r) => r.path);
+  const commonPrefix = getCommonPrefix(allPaths);
+  const serverPath = commonPrefix || "/api/v1";
+
+  const spec = {
+    openapi: "3.0.3",
+    info: {
+      title: (scan.projectName || "Backend Service")
+        .replace(/-/g, " ")
+        .replace(
+          /\w\S*/g,
+          (txt) => txt.charAt(0).toUpperCase() + txt.substr(1).toLowerCase(),
+        ),
+      description:
+        scan.projectDescription ||
+        "Industry standard API documentation for professional backend integration. Features secure authentication, comprehensive resource management, and detailed error handling.",
+      version: scan.projectVersion || "1.0.0",
+      contact: {
+        name: (scan.projectAuthor || "Engineering Team") + " Support",
+      },
+    },
+    servers: [
+      {
+        url: serverPath,
+        description: "Primary Production/Active version API server",
+      },
+    ],
+    tags: [],
+    paths: {},
+    components: {
+      securitySchemes: {
+        cookieAuth: {
+          type: "apiKey",
+          in: "cookie",
+          name: "accessToken",
+        },
+        bearerAuth: {
+          type: "http",
+          scheme: "bearer",
+          bearerFormat: "JWT",
+        },
+      },
+      schemas: {
+        ErrorResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: false },
+            message: {
+              type: "string",
+              example: "Detailed error message explaining the failure.",
+            },
+            error: { type: "object", nullable: true },
+          },
+          required: ["success", "message"],
+        },
+        SuccessResponse: {
+          type: "object",
+          properties: {
+            success: { type: "boolean", example: true },
+            message: {
+              type: "string",
+              example: "Operation completed successfully.",
+            },
+            data: { type: "object", nullable: true },
+          },
+          required: ["success", "message"],
+        },
+        ...scan.models,
+      },
+    },
+    security: [{ cookieAuth: [] }, { bearerAuth: [] }],
+  };
+
+  // PASS 1: Generate Grouped Tags
+  const usedTags = new Set();
+  scan.routes.forEach((r) => {
+    const tagName = inferTag(r, tagDescriptionMap);
+    usedTags.add(tagName);
+  });
+
+  spec.tags = Array.from(usedTags)
+    .map((name) => ({
+      name: name,
+      description:
+        tagDescriptionMap[name] || `${name} resource management and operations`,
+    }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  // Sort routes by path to ensure consistent openapi.json
+  const sortedRoutes = [...scan.routes].sort((a, b) =>
+    a.path.localeCompare(b.path),
+  );
+
+  // PASS 2: Generate Paths
+  for (const route of sortedRoutes) {
+    const relativePath =
+      commonPrefix && route.path.startsWith(commonPrefix)
+        ? route.path.replace(commonPrefix, "") || "/"
+        : route.path;
+
+    if (!spec.paths[relativePath]) spec.paths[relativePath] = {};
+
+    const methodLower = route.method.toLowerCase();
+    const tagName = inferTag(route, tagDescriptionMap);
+
+    // LLM or AI-enhanced description
+    let description =
+      enhancedDescriptions[route.path]?.[route.method] ||
+      `Performs a ${route.method} operation on the ${relativePath} resource.`;
+    if (!enhancedDescriptions[route.path]?.[route.method]) {
+      description += `\n\n**Implementation details:** This endpoint is handled by \`${route.handlerName}\`.`;
+    }
+
+    // Security detection
+    const isProtected = route.middlewares.some(
+      (m) =>
+        /auth|verify|jwt|protect|login/i.test(m) && !/login/i.test(route.path),
+    );
+
+    const operation = {
+      tags: [tagName],
+      summary: camelToTitle(
+        route.handlerName || `${route.method} ${relativePath}`,
+      ),
+      description: description,
+      responses: {},
+    };
+
+    if (!isProtected) operation.security = [];
+
+    // Request Body
+    if (["POST", "PUT", "PATCH"].includes(route.method)) {
+      operation.requestBody = {
+        required: true,
+        content: {
+          "application/json": {
+            schema: inferSchemaFromInputs(
+              route.inputs.body,
+              scan.models,
+              tagName,
+            ),
+          },
+        },
+      };
+    }
+
+    // Parameters (Path & Query)
+    if (route.inputs.params.length > 0 || route.inputs.query.length > 0) {
+      operation.parameters = [];
+      route.inputs.params.forEach((p) => {
+        operation.parameters.push({
+          name: p,
+          in: "path",
+          required: true,
+          schema: {
+            type: "string",
+            example: p.includes("id") ? "60d0fe4f5311236168a109ca" : "string",
+          },
+        });
+      });
+      route.inputs.query.forEach((p) => {
+        operation.parameters.push({
+          name: p,
+          in: "query",
+          required: false,
+          schema: { type: "string" },
+        });
+      });
+    }
+
+    // Responses
+    const distinctCodes = [
+      ...new Set(route.outputs.statusCodes.map((c) => c.replace(/['"]/g, ""))),
+    ];
+    distinctCodes.forEach((code) => {
+      operation.responses[code] = {
+        description: code.startsWith("2")
+          ? "Successful operation"
+          : "Action failed due to client or server error",
+        content: {
+          "application/json": {
+            schema: {
+              $ref: code.startsWith("2")
+                ? "#/components/schemas/SuccessResponse"
+                : "#/components/schemas/ErrorResponse",
+            },
+          },
+        },
+      };
+    });
+
+    if (Object.keys(operation.responses).length === 0) {
+      operation.responses["200"] = {
+        description: "Operation successful",
+        content: {
+          "application/json": {
+            schema: { $ref: "#/components/schemas/SuccessResponse" },
+          },
+        },
+      };
+    }
+
+    spec.paths[relativePath][methodLower] = operation;
+  }
+
+  return spec;
+}
+
+function inferTag(route, tagDescriptionMap = {}) {
+  const p = route.path.toLowerCase();
+  const h = (route.handlerName || "").toLowerCase();
+
+  // 1. Core Category Inferrer (Industry Standards)
+  if (p.includes("/admin") || h.includes("admin")) return "Admin";
+  if (p.includes("/manager") || h.includes("manager")) return "Manager";
+  if (
+    p.includes("/auth") ||
+    h.includes("login") ||
+    h.includes("logout") ||
+    h.includes("register") ||
+    h.includes("auth")
+  )
+    return "Auth";
+  if (p.includes("/user") || p.includes("/profile") || h.includes("user"))
+    return "User";
+  if (p.includes("/otp") || h.includes("otp") || p.includes("/email"))
+    return "OTP";
+  if (p.includes("/analytics") || h.includes("analytics")) return "Analytics";
+
+  // 2. Resource Inferrer (File-driven)
+  // Extracts 'Product' from 'product.routes.js'
+  if (route.file) {
+    const baseName = path.basename(route.file).split(".")[0].toLowerCase();
+    const cleanName = baseName.replace(/routes|router|controller/g, "").trim();
+    if (cleanName && !["app", "index", "server"].includes(cleanName)) {
+      return cleanName.charAt(0).toUpperCase() + cleanName.slice(1);
+    }
+  }
+
+  // 3. Structural Inferrer (Path-driven fallback)
+  const parts = p
+    .split("/")
+    .filter(Boolean)
+    .filter((s) => !["api", "v1", "v2", "v3", "public"].includes(s));
+  if (parts.length > 0) {
+    return parts[0].charAt(0).toUpperCase() + parts[0].slice(1);
+  }
+
+  return "General";
+}
+
+function getCommonPrefix(paths) {
+  if (paths.length < 2) return "";
+  const splitPaths = paths.map((p) => p.split("/").filter(Boolean));
+  const first = splitPaths[0];
+  const common = [];
+  for (let i = 0; i < first.length; i++) {
+    const segment = first[i];
+    // Majority matching (>= 80% to be safe)
+    const count = splitPaths.filter((p) => p[i] === segment).length;
+    if (count >= splitPaths.length * 0.8) {
+      common.push(segment);
+    } else {
+      break;
+    }
+  }
+  return common.length > 0 ? "/" + common.join("/") : "";
+}
+
+function camelToTitle(text) {
+  if (!text) return "";
+  const result = text
+    .replace(/Router|Controller/g, "")
+    .replace(/([A-Z])/g, " $1");
+  const titlized =
+    result.charAt(0).toUpperCase() + result.slice(1).toLowerCase().trim();
+  return titlized;
+}
+
+/**
+ * Heuristic to link field inputs to existing models or create an inline schema.
+ */
+function inferSchemaFromInputs(fields, models, tagName) {
+  const potentialModel = tagName.replace(/s$/, "");
+  const modelName = Object.keys(models).find(
+    (m) => m.toLowerCase() === potentialModel.toLowerCase(),
+  );
+
+  // If many fields, and it's a resource tag, likely it's a model reference
+  if (modelName && fields.length > 4) {
+    return { $ref: `#/components/schemas/${modelName}` };
+  }
+
+  if (fields.length === 0) return { type: "object", example: {} };
+
+  const properties = {};
+  fields.forEach((f) => {
+    const description =
+      f.toLowerCase().includes("identifier") ||
+      f.toLowerCase().includes("email")
+        ? "Email or Username of the user"
+        : undefined;
+    properties[f] = {
+      type: "string",
+      ...(description ? { description } : {}),
+      example: generateExampleForField(f),
+    };
+  });
+
+  return {
+    type: "object",
+    properties,
+  };
+}
+
+function generateExampleForField(f) {
+  const n = f.toLowerCase();
+  if (n.includes("email")) return "user@example.com";
+  if (n.includes("username")) return "john_doe";
+  if (n.includes("identifier")) return "user@example.com";
+  if (n.includes("password")) return "********";
+  if (n.includes("identifier")) return "user@example.com";
+  if (n.includes("id")) return "60d0fe4f5311236168a109ca";
+  return "string";
+}

package/src/scanners/expressScanner.js

@@ -0,0 +1,332 @@
+import path from "path";
+import { SyntaxKind } from "ts-morph";
+
+/**
+ * Scans an Express project to extract routes, nested routers, middlewares, and handler logic.
+ */
+export function scanExpressProject(project, root) {
+  const routes = [];
+  const filePrefixMap = new Map();
+
+  // PASS 1: Build a map of file paths to their URL prefixes by tracing .use() calls
+  for (let pass = 0; pass < 3; pass++) {
+    for (const sourceFile of project.getSourceFiles()) {
+      for (const call of sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression)) {
+        const exp = call.getExpression();
+        if (exp.getKind() !== SyntaxKind.PropertyAccessExpression || exp.getName() !== "use") continue;
+
+        const args = call.getArguments();
+        if (args.length < 1) continue;
+
+        let prefix = "";
+        const startIdx = args[0].getKind() === SyntaxKind.StringLiteral ? 1 : 0;
+        if (startIdx === 1) prefix = args[0].getLiteralText();
+
+        for (let i = startIdx; i < args.length; i++) {
+          const routerFile = resolveToSourceFile(args[i]);
+          if (routerFile && routerFile.getFilePath() !== sourceFile.getFilePath()) {
+            const basePrefix = filePrefixMap.get(sourceFile.getFilePath()) || "";
+            const fullPrefix = (basePrefix + prefix).replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+            filePrefixMap.set(routerFile.getFilePath(), fullPrefix);
+            // DO NOT BREAK: We must map the prefix to all potential routers/middlewares in the chain
+          }
+        }
+      }
+    }
+  }
+
+  const methods = ["get", "post", "put", "patch", "delete", "options", "all"];
+
+  // PASS 2: Extract actual route definitions
+  for (const sourceFile of project.getSourceFiles()) {
+    const routePrefix = filePrefixMap.get(sourceFile.getFilePath()) || "";
+    const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+
+    for (const callExpr of callExpressions) {
+      const expression = callExpr.getExpression();
+      if (expression.getKind() !== SyntaxKind.PropertyAccessExpression) continue;
+
+      const methodName = expression.getName();
+      if (!methods.includes(methodName)) continue;
+
+      const args = callExpr.getArguments();
+      let pathStr = "";
+      let handlerNode = null;
+      let middlewares = [];
+
+      // Pattern 1: router.get('/path', handler)
+      if (args.length >= 2 && args[0].getKind() === SyntaxKind.StringLiteral) {
+          pathStr = args[0].getLiteralText();
+          for (let i = 1; i < args.length - 1; i++) {
+              middlewares.push(args[i].getText());
+          }
+          handlerNode = args[args.length - 1];
+      } 
+      // Pattern 2: router.route('/path').get(handler)
+      else if (expression.getExpression().getKind() === SyntaxKind.CallExpression) {
+          const routeCall = expression.getExpression();
+          const routeExp = routeCall.getExpression();
+          if (routeExp.getKind() === SyntaxKind.PropertyAccessExpression && routeExp.getName() === "route") {
+              const routeArgs = routeCall.getArguments();
+              if (routeArgs.length > 0 && routeArgs[0].getKind() === SyntaxKind.StringLiteral) {
+                  pathStr = routeArgs[0].getLiteralText();
+                  for (let i = 0; i < args.length - 1; i++) {
+                      middlewares.push(args[i].getText());
+                  }
+                  handlerNode = args[args.length - 1];
+              }
+          }
+      }
+
+      if (!pathStr || !handlerNode) continue;
+
+      const fullPath = (routePrefix + pathStr).replace(/\/\//g, "/").replace(/\/$/, "") || "/";
+      const resolvedHandler = resolveHandler(handlerNode);
+      const analysis = analyzeHandler(resolvedHandler);
+
+      routes.push({
+        method: methodName.toUpperCase(),
+        path: fullPath,
+        file: path.relative(root, sourceFile.getFilePath()),
+        middlewares,
+        handlerName: handlerNode.getText(),
+        ...analysis,
+        handlerCode: resolvedHandler ? resolvedHandler.getText().slice(0, 500) : ""
+      });
+    }
+  }
+
+  return routes;
+}
+
+function resolveToSourceFile(node) {
+  if (!node) return null;
+  
+  const sourceFile = node.getSourceFile();
+
+  // 1. Try ESM Import resolution
+  if (node.getKind() === SyntaxKind.Identifier) {
+      const importDecls = sourceFile.getImportDeclarations();
+      for (const imp of importDecls) {
+          const namedImports = imp.getNamedImports();
+          const defaultImport = imp.getDefaultImport();
+          const namespaceImport = imp.getNamespaceImport();
+          
+          if (defaultImport?.getText() === node.getText() || 
+              namedImports.some(ni => ni.getName() === node.getText()) ||
+              namespaceImport?.getText() === node.getText()) {
+              return manualResolve(sourceFile, imp.getModuleSpecifierValue());
+          }
+      }
+  }
+
+  // 2. Try TS-based resolution
+  const symbol = node.getSymbol();
+  if (symbol) {
+    const decls = symbol.getDeclarations();
+    for (const d of decls) {
+        const sf = d.getSourceFile();
+        if (sf && sf.getFilePath() !== sourceFile.getFilePath()) return sf;
+    }
+  }
+
+  // 3. Fallback for CommonJS: check for require()
+  if (node.getKind() === SyntaxKind.Identifier) {
+      const decls = node.getSymbol()?.getDeclarations() || [];
+      for (const d of decls) {
+          if (d.getKind() === SyntaxKind.VariableDeclaration) {
+              const init = d.getInitializer();
+              if (init && init.getKind() === SyntaxKind.CallExpression && init.getExpression().getText() === "require") {
+                  const args = init.getArguments();
+                  if (args.length > 0 && args[0].getKind() === SyntaxKind.StringLiteral) {
+                      return manualResolve(sourceFile, args[0].getLiteralText());
+                  }
+              }
+          }
+      }
+  }
+  return null;
+}
+
+/**
+ * Manually resolves a require or import path to its SourceFile.
+ */
+function manualResolve(sourceFile, reqPath) {
+    if (!reqPath || typeof reqPath !== "string") return null;
+    const directory = path.dirname(sourceFile.getFilePath());
+    let normalizedPath = reqPath;
+    
+    // Remove .js extension for resolution if present (typical in ESM)
+    if (normalizedPath.endsWith(".js")) {
+        normalizedPath = normalizedPath.slice(0, -3);
+    }
+    
+    const absPath = path.resolve(directory, normalizedPath);
+    const project = sourceFile.getProject();
+    
+    // Standard attempts with common extensions
+    const variants = [
+        absPath + ".js",
+        absPath + ".ts",
+        absPath,
+        path.join(absPath, "index.js"),
+        path.join(absPath, "index.ts")
+    ];
+    
+    for (const v of variants) {
+        const sf = project.getSourceFile(v);
+        if (sf) return sf;
+    }
+    
+    // Fallback: Case-insensitive match or contains match for robust resolution
+    const vLower = absPath.toLowerCase().replace(/\\/g, "/");
+    const sfFallback = project.getSourceFiles().find(f => {
+        const fp = f.getFilePath().toLowerCase().replace(/\\/g, "/");
+        return fp === vLower || fp === vLower + ".js" || fp === vLower + ".ts" || fp.endsWith(vLower + ".js");
+    });
+    
+    return sfFallback;
+}
+
+function resolveHandler(node) {
+  if (!node) return null;
+
+  // Unwrap asyncHandler(func)
+  if (node.getKind() === SyntaxKind.CallExpression) {
+      const exp = node.getExpression();
+      if (exp.getText().includes("asyncHandler")) {
+          const args = node.getArguments();
+          if (args.length > 0) return resolveHandler(args[0]);
+      }
+  }
+
+  if (node.getKind() === SyntaxKind.PropertyAccessExpression) {
+      const obj = node.getExpression();
+      const prop = node.getName();
+      const objFile = resolveToSourceFile(obj);
+      if (objFile) {
+          // Look for 'exports.name = ...' or 'module.exports.name = ...'
+          const assignments = objFile.getDescendantsOfKind(SyntaxKind.BinaryExpression);
+          for (const ass of assignments) {
+              const left = ass.getLeft().getText();
+              if (left === `exports.${prop}` || left === `module.exports.${prop}`) return resolveHandler(ass.getRight());
+          }
+          // Or variable declaration
+          const varDec = objFile.getVariableDeclaration(prop);
+          if (varDec) return resolveHandler(varDec.getInitializer() || varDec);
+      }
+  }
+
+  if (node.getKind() === SyntaxKind.Identifier) {
+    const symbol = node.getSymbol();
+    if (symbol) {
+      const decls = symbol.getDeclarations();
+      for (const d of decls) {
+        if (d.getKind() === SyntaxKind.VariableDeclaration || d.getKind() === SyntaxKind.PropertyAssignment) {
+          return resolveHandler(d.getInitializer() || d);
+        }
+        if (d.getKind() === SyntaxKind.FunctionDeclaration) return d;
+      }
+    }
+    
+    // Check Imports specifically if symbol failed
+    const sourceFile = node.getSourceFile();
+    const imports = sourceFile.getImportDeclarations();
+    for (const imp of imports) {
+        const named = imp.getNamedImports();
+        for (const n of named) {
+            if (n.getName() === node.getText()) {
+                const sf = manualResolve(sourceFile, imp.getModuleSpecifierValue());
+                if (sf) {
+                    const vd = sf.getVariableDeclaration(node.getText()) || sf.getFunction(node.getText());
+                    if (vd) return resolveHandler(vd.getInitializer?.() || vd);
+                }
+            }
+        }
+    }
+  }
+  return node;
+}
+
+function analyzeHandler(node) {
+  const inputs = { body: [], query: [], params: [] };
+  const outputs = { statusCodes: [], responseTypes: [] };
+  
+  let reqName = "req";
+  let resName = "res";
+
+  if (typeof node.getParameters === "function") {
+    const params = node.getParameters();
+    if (params.length > 0) reqName = params[0].getName();
+    if (params.length > 1) resName = params[1].getName();
+  }
+
+  if (typeof node.getDescendants === "function") {
+    node.getDescendants().forEach(desc => {
+      const text = desc.getText();
+      if (text.startsWith(`${reqName}.body.`)) inputs.body.push(text.split(`${reqName}.body.`)[1].split(/[ .([]/)[0]);
+      if (text.startsWith(`${reqName}.body['`) || text.startsWith(`${reqName}.body["`)) {
+          const parts = text.split(/['"]/);
+          if (parts.length > 1) inputs.body.push(parts[1]);
+      }
+      if (text.startsWith(`${reqName}.query.`)) inputs.query.push(text.split(`${reqName}.query.`)[1].split(/[ .([]/)[0]);
+      if (text.startsWith(`${reqName}.query['`) || text.startsWith(`${reqName}.query["`)) {
+          const parts = text.split(/['"]/);
+          if (parts.length > 1) inputs.query.push(parts[1]);
+      }
+      if (text.startsWith(`${reqName}.params.`)) inputs.params.push(text.split(`${reqName}.params.`)[1].split(/[ .([]/)[0]);
+      if (text.startsWith(`${reqName}.params['`) || text.startsWith(`${reqName}.params["`)) {
+          const parts = text.split(/['"]/);
+          if (parts.length > 1) inputs.params.push(parts[1]);
+      }
+
+      if (desc.getKind() === SyntaxKind.VariableDeclaration) {
+        const nameNode = desc.getNameNode();
+        const init = desc.getInitializer();
+        if (nameNode.getKind() === SyntaxKind.ObjectBindingPattern && init) {
+          const initText = init.getText();
+          if (initText.includes(`${reqName}.body`)) nameNode.getElements().forEach(el => inputs.body.push(el.getName()));
+          if (initText.includes(`${reqName}.query`)) nameNode.getElements().forEach(el => inputs.query.push(el.getName()));
+          if (initText.includes(`${reqName}.params`)) nameNode.getElements().forEach(el => inputs.params.push(el.getName()));
+        }
+      }
+
+      if (desc.getKind() === SyntaxKind.CallExpression) {
+        const callExp = desc.getExpression();
+        const callText = callExp.getText();
+        
+        // res.status(200)
+        if (callExp.getKind() === SyntaxKind.PropertyAccessExpression && callExp.getName() === "status") {
+          const obj = callExp.getExpression().getText();
+          if (obj === resName || obj.endsWith(`.${resName}`)) {
+            const args = desc.getArguments();
+            if (args.length > 0) outputs.statusCodes.push(args[0].getText());
+          }
+        }
+
+        // ApiError or new ApiError
+        if (callText.includes("ApiError")) {
+            const possibleCall = desc;
+            const args = possibleCall.getArguments();
+            if (args.length > 0) outputs.statusCodes.push(args[0].getText());
+        }
+        
+        if (callText.includes(`.json`)) outputs.responseTypes.push("application/json");
+        if (callText.includes(`.send`)) outputs.responseTypes.push("text/plain");
+        if (callText.includes(`.download`)) outputs.responseTypes.push("application/octet-stream");
+      }
+    });
+  }
+
+  return {
+    inputs: {
+      body: [...new Set(inputs.body)],
+      query: [...new Set(inputs.query)],
+      params: [...new Set(inputs.params)]
+    },
+    outputs: {
+      statusCodes: [...new Set(outputs.statusCodes)].length > 0 ? [...new Set(outputs.statusCodes)] : ["200"],
+      responseTypes: [...new Set(outputs.responseTypes)].length > 0 ? [...new Set(outputs.responseTypes)] : ["application/json"]
+    }
+  };
+}

package/src/scanners/index.js

@@ -0,0 +1,101 @@
+import { readFile, access } from "fs/promises";
+import path from "path";
+import { globSync } from "glob";
+import { Project } from "ts-morph";
+import { scanExpressProject } from "./expressScanner.js";
+import { scanModels } from "./modelScanner.js";
+
+export async function scanProject(root) {
+  const result = {
+    projectName: "my-project",
+    projectDescription: "",
+    projectVersion: "1.0.0",
+    projectAuthor: "",
+    packages: { dependencies: {}, devDependencies: {} },
+    routes: [],
+    models: {},
+    files: [],
+    hasReadme: false,
+    existingReadme: "",
+  };
+
+  // =========================
+  // package.json
+  // =========================
+  const pkgPath = path.join(root, "package.json");
+
+  try {
+    await access(pkgPath);
+    const pkgData = await readFile(pkgPath, "utf-8");
+    const pkg = JSON.parse(pkgData);
+
+    result.projectName = pkg.name ?? "my-project";
+    result.projectDescription = pkg.description ?? "";
+    result.projectVersion = pkg.version ?? "1.0.0";
+    result.projectAuthor = pkg.author ?? "";
+    result.packages.dependencies = pkg.dependencies ?? {};
+    result.packages.devDependencies = pkg.devDependencies ?? {};
+  } catch {
+    // ignore if not found
+  }
+
+  // =========================
+  // README
+  // =========================
+  const readmePath = path.join(root, "README.md");
+
+  try {
+    await access(readmePath);
+    result.hasReadme = true;
+    result.existingReadme = await readFile(readmePath, "utf-8");
+  } catch {
+    // ignore if not found
+  }
+
+  // =========================
+  // Find Files
+  // =========================
+  const files = globSync("**/*.{js,ts,jsx,tsx}", {
+    cwd: root,
+    ignore: ["node_modules/**", "dist/**", ".git/**", "*.config.*", "tests/**"],
+    absolute: true,
+  });
+
+  result.files = files.map((f) => path.relative(root, f));
+
+  // =========================
+  // ts-morph Project
+  // =========================
+  const project = new Project({
+    compilerOptions: {
+      allowJs: true,
+    },
+  });
+
+  files.forEach((file) => {
+    project.addSourceFileAtPath(file);
+  });
+
+  // console.log(
+  //   "Source File =",
+  //   project.getSourceFiles().map((file) => file.getFilePath()),
+  // );
+
+  // =========================
+  // Detect Framework
+  // =========================
+  const deps = {
+    ...result.packages.dependencies,
+    ...result.packages.devDependencies,
+  };
+
+  // Always scan for models to find Mongoose schemas
+  result.models = scanModels(project);
+
+  if (deps["express"] || project.getSourceFiles().some(f => f.getText().includes('express'))) {
+    const expressRoutes = scanExpressProject(project, root);
+    result.routes = expressRoutes;
+  }
+
+  return result;
+}

package/src/scanners/modelScanner.js

@@ -0,0 +1,204 @@
+import { SyntaxKind } from "ts-morph";
+
+/**
+ * Scans for Mongoose schemas in the project and converts them to OpenAPI schemas.
+ */
+export function scanModels(project) {
+  const models = {};
+
+  for (const sourceFile of project.getSourceFiles()) {
+    // Look for new Schema(...) or mongoose.Schema(...)
+    const newExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.NewExpression);
+    
+    for (const newExpr of newExpressions) {
+        const typeText = newExpr.getExpression().getText();
+        if (typeText === "Schema" || typeText === "mongoose.Schema" || typeText.endsWith(".Schema")) {
+            const args = newExpr.getArguments();
+            if (args.length > 0 && args[0].getKind() === SyntaxKind.ObjectLiteralExpression) {
+                const schemaObj = args[0];
+                const modelName = inferModelName(sourceFile, newExpr);
+                
+                // Capitalize model name for consistency
+                const capitalized = modelName.charAt(0).toUpperCase() + modelName.slice(1);
+                models[capitalized] = parseSchemaObject(schemaObj);
+            }
+        }
+    }
+  }
+
+  return models;
+}
+
+function inferModelName(sourceFile, node) {
+    // Try to find the variable name it's assigned to (e.g., const userSchema = new Schema(...))
+    const varDec = node.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
+    if (varDec) {
+        let name = varDec.getName();
+        // Remove 'Schema' suffix if present
+        return name.replace(/Schema$/i, "");
+    }
+    
+    // Check if it's exported as a model: mongoose.model('User', userSchema)
+    const sourceFileText = sourceFile.getText();
+    const modelMatch = sourceFileText.match(/mongoose\.model\(['"]([^'"]+)['"]/);
+    if (modelMatch) {
+        return modelMatch[1];
+    }
+
+    // Fallback to filename
+    return sourceFile.getBaseNameWithoutExtension();
+}
+
+function parseSchemaObject(obj) {
+    const properties = {
+        _id: { type: "string", example: "60d0fe4f5311236168a109ca" }
+    };
+    const required = [];
+
+    for (const property of obj.getProperties()) {
+        if (property.getKind() === SyntaxKind.PropertyAssignment) {
+            const name = property.getName().replace(/['"]/g, "");
+            const initializer = property.getInitializer();
+            
+            if (initializer) {
+                const info = parseFieldInfo(initializer, name);
+                properties[name] = info.schema;
+                if (info.required) required.push(name);
+            }
+        }
+    }
+
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {})
+    };
+}
+
+function parseFieldInfo(node, fieldName = "") {
+    let type = "string";
+    let isRequired = false;
+    let enumValues = null;
+    let defaultValue = undefined;
+
+    if (node.getKind() === SyntaxKind.Identifier) {
+        const text = node.getText();
+        type = mapMongooseType(text);
+    } else if (node.getKind() === SyntaxKind.ObjectLiteralExpression) {
+        const typeProp = node.getProperty("type");
+        if (typeProp && typeProp.getKind() === SyntaxKind.PropertyAssignment) {
+            const typeInit = typeProp.getInitializer();
+            if (typeInit) type = mapMongooseType(typeInit.getText());
+        }
+        
+        const requiredProp = node.getProperty("required");
+        if (requiredProp && (requiredProp.getKind() === SyntaxKind.PropertyAssignment || requiredProp.getKind() === SyntaxKind.ShorthandPropertyAssignment)) {
+             let val = "";
+             if (requiredProp.getKind() === SyntaxKind.PropertyAssignment) {
+                 val = requiredProp.getInitializer().getText();
+             } else {
+                 val = requiredProp.getName();
+             }
+             isRequired = val === "true" || val.startsWith("[true");
+        }
+
+        const enumProp = node.getProperty("enum");
+        if (enumProp && enumProp.getKind() === SyntaxKind.PropertyAssignment) {
+            const enumInit = enumProp.getInitializer();
+            if (enumInit.getKind() === SyntaxKind.ArrayLiteralExpression) {
+                enumValues = enumInit.getElements().map(e => e.getText().replace(/['"]/g, ""));
+            }
+        }
+
+        const defaultProp = node.getProperty("default");
+        if (defaultProp && defaultProp.getKind() === SyntaxKind.PropertyAssignment) {
+            defaultValue = defaultProp.getInitializer().getText().replace(/['"]/g, "");
+            if (type === "number") defaultValue = Number(defaultValue);
+            if (type === "boolean") defaultValue = defaultValue === "true";
+        }
+    } else if (node.getKind() === SyntaxKind.ArrayLiteralExpression) {
+        const elements = node.getElements();
+        if (elements.length > 0) {
+            const subInfo = parseFieldInfo(elements[0], fieldName);
+            return {
+                schema: { type: "array", items: subInfo.schema },
+                required: false
+            };
+        } else {
+            return { schema: { type: "array", items: { type: "object" } }, required: false };
+        }
+    }
+
+    const schema = { type };
+    if (enumValues) schema.enum = enumValues;
+    
+    // Format detection
+    const format = detectFormat(fieldName, node.getText());
+    if (format) schema.format = format;
+
+    // Example generation
+    const example = generateExample(fieldName, type, enumValues);
+    if (example !== undefined) schema.example = example;
+
+    // Default value
+    if (defaultValue !== undefined) schema.default = defaultValue;
+
+    return {
+        schema,
+        required: isRequired
+    };
+}
+
+function detectFormat(name, text) {
+    const n = name.toLowerCase();
+    if (n.includes("email")) return "email";
+    if (n.includes("password")) return "password";
+    if (n.includes("url") || n.includes("uri")) return "uri";
+    if (n.includes("uuid")) return "uuid";
+    // Check if the type text suggests a Date
+    if (n.includes("date") || n.includes("at") || text.includes("Date") || text.includes("at")) return "date-time";
+    return undefined;
+}
+
+function generateExample(name, type, enumValues) {
+    if (enumValues && enumValues.length > 0) return enumValues[0];
+    const n = name.toLowerCase();
+    if (n.includes("email")) return "user@example.com";
+    if (n.includes("username")) return "john_doe";
+    if (n.includes("fullname") || n.includes("name")) return "John Doe";
+    if (n.includes("phone") || n.includes("mobile")) return "+1234567890";
+    if (n.includes("password")) return "********";
+    if (n.includes("url")) return "https://example.com";
+    if (n.includes("id") && !n.includes("guid")) return "60d0fe4f5311236168a109ca";
+    
+    if (type === "number") {
+        if (n.includes("age")) return 25;
+        if (n.includes("count")) return 10;
+        if (n.includes("price")) return 99.99;
+        return 123;
+    }
+    if (type === "boolean") return true;
+    if (type === "string") {
+        if (n.includes("date") || n.includes("at")) return "2024-01-01T00:00:00Z";
+        if (n.includes("gender")) return "Male";
+        if (n.includes("city")) return "New York";
+        return n.charAt(0).toUpperCase() + n.slice(1);
+    }
+    return undefined;
+}
+
+function mapMongooseType(text) {
+    const map = {
+        "String": "string",
+        "Number": "number",
+        "Boolean": "boolean",
+        "Date": "string",
+        "ObjectId": "string",
+        "Schema.Types.ObjectId": "string",
+        "Buffer": "string",
+        "Mixed": "object",
+        "Map": "object",
+        "Decimal128": "number"
+    };
+    return map[text] || "string";
+}