autodocsync 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,275 @@
+# AutoDocSync
+
+![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg) ![Node.js](https://img.shields.io/badge/Node.js-20+-green.svg) ![Ollama](https://img.shields.io/badge/AI-Ollama-purple.svg) ![AST](https://img.shields.io/badge/AST-TypeScript-blue.svg)
+
+**Automated OpenAPI Documentation with AST & Local LLMs**
+
+AutoDocSync is a high-performance CLI tool for Express.js developers. It bridges the gap between your source code and documentation by using **TypeScript AST (Abstract Syntax Tree)** to statically analyze your project and **Local AI (Ollama)** to generate human-readable endpoint descriptions — entirely on your machine.
+
+> [!NOTE]
+> AutoDocSync was built to solve the "Stale Docs" problem. By making documentation generation part of your workflow, your OpenAPI spec stays accurate as your code evolves.
+
+---
+
+## How It Works
+
+AutoDocSync does not guess your routes or rely on manual annotations. It performs a deep static analysis of your Express project to understand exactly how your API behaves.
+
+```mermaid
+graph TD
+    A[Source Code] --> B{AST Scanner}
+    B -- "Express Routes" --> C[Logic Extraction]
+    B -- "Mongoose Models" --> D[Schema Parsing]
+    C --> E[Context Builder]
+    D --> E
+    E --> F((Local Ollama))
+    F -- "Mistral" --> G[AI Enhancement]
+    G --> H[Final OpenAPI 3.0 Spec]
+```
+
+**Deep Integration**
+
+- **AST Parsing** — Powered by `ts-morph`, the scanner traces `.use()` calls to resolve full URL prefixes and identifies imported handlers and middlewares.
+- **Payload Extraction** — Automatically detects request bodies, query parameters, and URL params directly from your handler logic.
+- **Smart Schemas** — Parses Mongoose models to construct accurate OpenAPI components, including required fields, enums, and contextual examples (e.g., `email` → `user@example.com`).
+- **Privacy-First AI** — Uses a local Ollama instance. No API keys, no data sent to the cloud, and zero inference cost.
+
+---
+
+## Quick Start
+
+Follow these steps in order to get AutoDocSync running in your Express project.
+
+### Step 1 — Install AutoDocSync
+
+Inside your Express project root, install AutoDocSync as a development dependency:
+
+```bash
+npm install --save-dev autodocsync
+```
+
+### Step 2 — Install Ollama
+
+AutoDocSync uses a locally running Ollama instance to generate AI-powered descriptions.
+
+Download and install Ollama from the official site: [https://ollama.com](https://ollama.com)
+
+Once installed, verify it is running:
+
+```bash
+ollama --version
+```
+
+### Step 3 — Pull the Mistral Model
+
+AutoDocSync uses the Mistral model for description generation. Pull it with:
+
+```bash
+ollama pull mistral
+```
+
+> [!TIP]
+> This is a one-time download. Once pulled, the model is cached locally and reused across all future runs.
+
+### Step 4 — Generate Your Documentation
+
+With everything set up, run the following command from your Express project root:
+
+```bash
+npx autodocsync generate . -o ./docs
+```
+
+This scans your project and writes a production-ready `openapi.json` file to the `./docs` directory.
+
+---
+
+## Example Output
+
+Running `npx autodocsync generate . -o ./docs` on a standard Express + Mongoose project produces a file like `docs/openapi.json`. Below is a realistic excerpt:
+
+```json
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "My Backend Service",
+    "description": "Industry standard API documentation for professional backend integration.",
+    "version": "1.0.0",
+    "contact": {
+      "name": "Engineering Team Support"
+    }
+  },
+  "servers": [
+    {
+      "url": "/api/v1",
+      "description": "Primary Production/Active version API server"
+    }
+  ],
+  "tags": [
+    { "name": "Auth", "description": "Authentication algorithms, secure login, and session management" },
+    { "name": "User", "description": "User profile management, account settings, and event registrations" }
+  ],
+  "paths": {
+    "/auth/login": {
+      "post": {
+        "tags": ["Auth"],
+        "summary": "Login user",
+        "description": "Authenticates a registered user using their email and password. Returns a signed JWT token and sets an httpOnly access token cookie on success.",
+        "security": [],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "email":    { "type": "string", "example": "user@example.com" },
+                  "password": { "type": "string", "example": "********" }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
+              }
+            }
+          },
+          "401": {
+            "description": "Action failed due to client or server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/users/{id}": {
+      "get": {
+        "tags": ["User"],
+        "summary": "Get user by id",
+        "description": "Retrieves the full profile of a user by their MongoDB ObjectId. Requires a valid bearer token or session cookie.",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": { "type": "string", "example": "60d0fe4f5311236168a109ca" }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/SuccessResponse" }
+              }
+            }
+          },
+          "404": {
+            "description": "Action failed due to client or server error",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/ErrorResponse" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "cookieAuth": { "type": "apiKey", "in": "cookie", "name": "accessToken" },
+      "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }
+    },
+    "schemas": {
+      "SuccessResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean", "example": true },
+          "message": { "type": "string", "example": "Operation completed successfully." },
+          "data":    { "type": "object", "nullable": true }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "properties": {
+          "success": { "type": "boolean", "example": false },
+          "message": { "type": "string", "example": "Detailed error message explaining the failure." },
+          "error":   { "type": "object", "nullable": true }
+        }
+      }
+    }
+  },
+  "security": [
+    { "cookieAuth": [] },
+    { "bearerAuth": [] }
+  ]
+}
+```
+
+> [!TIP]
+> Drop the generated `openapi.json` into [Swagger UI](https://swagger.io/tools/swagger-ui/) or [Redoc](https://redocly.com/redoc/) for instant, interactive API documentation.
+
+---
+
+## CLI Reference
+
+| Command | Argument | Option | Description |
+| :--- | :--- | :--- | :--- |
+| `generate` | `[projectDir]` | `-o, --output <dir>` | Scans the project and writes `openapi.json` to the specified output directory. |
+
+---
+
+## Why AutoDocSync?
+
+| Feature | Benefit |
+| :--- | :--- |
+| Real-time accuracy | Docs are always in sync with your actual code — no drift. |
+| $0 inference cost | Runs on your own hardware. No API subscriptions required. |
+| OpenAPI 3.0 compliant | Output is compatible with Swagger UI, Redoc, and any standard tooling. |
+| Zero manual effort | No `@swagger` JSDoc comments or route decorators needed. |
+
+---
+
+## Project Structure
+
+| Path | Purpose |
+| :--- | :--- |
+| `bin/index.js` | CLI entry point and argument parsing. |
+| `src/scanners/` | AST logic for Express route and Mongoose model parsing. |
+| `src/llm.js` | Integration with the local Ollama API. |
+| `src/openapi-gen.js` | Core logic for compiling and writing the OpenAPI spec. |
+
+---
+
+## Troubleshooting
+
+| Issue | Resolution |
+| :--- | :--- |
+| Ollama is not running | Open the Ollama desktop app or run `ollama serve` in a separate terminal. |
+| Model not found | Run `ollama pull mistral` to download the required model. |
+| Slow generation or timeout | Large codebases may take a moment. Ensure at least **8 GB of RAM** is available and Ollama is idle before running. |
+| Empty or partial output | Confirm your project uses standard Express route patterns (`.get`, `.post`, `.use`, etc.). |
+
+---
+
+## Contributing
+
+Contributions are welcome. Whether it's adding support for additional frameworks (Fastify, NestJS, Hono) or improving the LLM prompts for better descriptions, feel free to open an issue or submit a pull request.
+
+---
+
+## License
+
+Distributed under the **MIT License**.
+
+---
+
+*Built for developers who want documentation that actually keeps up with their code.*

package/bin/index.js

@@ -12,6 +12,7 @@ import {
 import {
   describeEndpointWithMistral,
   summarizeProjectWithMistral,
+  generateREADMEWithMistral,
 } from "../src/llm.js";
 import { generateOpenAPI } from "../src/openapi-gen.js";
 
@@ -100,6 +101,13 @@ program
       console.log(
         `[docSync] SUCCESS: openapi.json generated at ${path.join(outDir, "openapi.json")}`,
       );
+
+      console.log("[docSync] Projecting professional README.md with Mistral...");
+      const readmeContent = await generateREADMEWithMistral(openApiSpec);
+      fs.writeFileSync(path.join(outDir, "README.md"), readmeContent, "utf-8");
+      console.log(
+        `[docSync] SUCCESS: README.md generated at ${path.join(outDir, "README.md")}`,
+      );
     } else {
       console.log(
         "[docSync] Generating openapi.json (without AI enhancement)...",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autodocsync",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Combines TS code parsing and local LLMs to generate OpenAPI specs automatically",
   "main": "src/openapi-gen.js",
   "type": "module",
@@ -27,4 +27,4 @@
     "glob": "^10.3.10",
     "ts-morph": "^21.0.1"
   }
-}
+}

package/src/check-ollama.js

@@ -25,6 +25,7 @@ export function printOllamaGuide() {
 ║         autodocs-sync — setup required           ║
 ╠══════════════════════════════════════════════════╣
 ║  Ollama is not running on this machine.          ║
+║  ❌ Run: ollama serve                            ║
 ║                                                  ║
 ║  To enable AI-powered docs:                      ║
 ║                                                  ║
@@ -35,7 +36,7 @@ export function printOllamaGuide() {
 ║     $ ollama pull mistral                        ║
 ║                                                  ║
 ║  3. Regenerate docs manually after setup         ║
-║     $ npx autodocs                               ║
+║     $ npx autodocsync generate . -o ./docs       ║
 ╚══════════════════════════════════════════════════╝
   `);
 }
@@ -44,7 +45,7 @@ export function printModelGuide() {
   console.log(`
 [autodocs] Ollama is running but mistral is not pulled yet.
 Run: ollama pull mistral
-Then run: npx autodocs
+Then run: npx autodocsync generate . -o ./docs
   `);
 }
 

package/src/llm.js

@@ -3,19 +3,19 @@ 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';
-  
+  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',
+
+    const response = await axios.post("http://localhost:11434/api/generate", {
+      model: "mistral",
       prompt: prompt,
-      stream: false
+      stream: false,
     });
 
     const data = response.data;
@@ -30,10 +30,10 @@ export async function describeEndpointWithMistral(endpoint) {
 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',
+    const response = await axios.post("http://localhost:11434/api/generate", {
+      model: "mistral",
       prompt: prompt,
-      stream: false
+      stream: false,
     });
 
     const data = response.data;
@@ -44,13 +44,63 @@ export async function summarizeProjectWithMistral(readme) {
   }
 }
 
+export async function generateREADMEWithMistral(openApiSpec) {
+  try {
+    const prompt = `As a Visionary Technical Architect and documentation specialist, generate an "Ultra-Premium" (Vercel/Linear-tier) README.md file for the following API project.
+
+Project Name: ${openApiSpec.info.title}
+Project Goal: ${openApiSpec.info.description}
+
+---
+
+## 🏗️ High-Level Structuring Instructions:
+
+1.  **Header**: Premium title with dynamic-looking badges (License, Node.js version, Tech used).
+2.  **The Vision**: A high-impact executive summary and a "The Problem vs. The Solution" section illustrating why this project matters.
+3.  **Real-Time Architecture**: Provide a high-quality Mermaid.js diagram illustrating the core logic and flow of the API.
+4.  **Premium Feature Grid**: Use a clear, sophisticated layout to list key features with professional, benefit-driven copy.
+5.  **Tech Stack**: List all core technologies (Node.js, Express, etc.).
+6.  **Interactive API Documentation**: Generate a clean, comprehensive "API Reference" table with Path, Method, and Description.
+7.  **The Golden Path (Quick Start)**: A copy-paste ready installation and usage section designed for zero friction.
+8.  **Development & Roadmap**: Sections for contributors, including a vision for future improvements.
+9.  **Premium Formatting**: Use GitHub-style "Alerts" (> [!TIP], > [!NOTE]) and professional hierarchy throughout.
+
+---
+
+## Technical Context (OpenAPI 3.0):
+${JSON.stringify(openApiSpec, null, 2).slice(0, 6000)}
+
+---
+
+**CRITICAL**: Return ONLY the Markdown content. Do not add conversational text or wrap in code blocks. Make it look better than any standard technical README. Focus on clarity, aesthetics, and developer experience.`;
+
+    const response = await axios.post("http://localhost:11434/api/generate", {
+      model: "mistral",
+      prompt: prompt,
+      stream: false,
+    });
+
+    const data = response.data;
+    return (
+      data.response?.trim() ||
+      "# " + openApiSpec.info.title + "\n\nGenerated API documentation."
+    );
+  } catch (error) {
+    console.error("[llm] Failed to generate README:", error.message);
+    return "# " + openApiSpec.info.title + "\n\nGenerated 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.`
+    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.`;
+  return (
+    descriptions[method] ||
+    `Performs a ${method} request to the ${resource} endpoint.`
+  );
 }

package/src/openapi-gen.js

@@ -127,7 +127,14 @@ export function generateOpenAPI(scan, enhancedDescriptions = {}) {
     let description =
       enhancedDescriptions[route.path]?.[route.method] ||
       `Performs a ${route.method} operation on the ${relativePath} resource.`;
-    if (!enhancedDescriptions[route.path]?.[route.method]) {
+
+    const isCleanHandler = 
+      route.handlerName && 
+      route.handlerName !== "[Anonymous]" && 
+      !route.handlerName.includes("{") && 
+      !route.handlerName.includes("=>");
+
+    if (!enhancedDescriptions[route.path]?.[route.method] && isCleanHandler) {
       description += `\n\n**Implementation details:** This endpoint is handled by \`${route.handlerName}\`.`;
     }
 
@@ -139,9 +146,9 @@ export function generateOpenAPI(scan, enhancedDescriptions = {}) {
 
     const operation = {
       tags: [tagName],
-      summary: camelToTitle(
-        route.handlerName || `${route.method} ${relativePath}`,
-      ),
+      summary: isCleanHandler 
+        ? camelToTitle(route.handlerName)
+        : `${route.method} ${relativePath}`,
       description: description,
       responses: {},
     };

package/src/scanners/expressScanner.js

@@ -41,11 +41,16 @@ export function scanExpressProject(project, root) {
   for (const sourceFile of project.getSourceFiles()) {
     const routePrefix = filePrefixMap.get(sourceFile.getFilePath()) || "";
     const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+    const excludeCallers = ["axios", "fetch", "superagent", "request"];
 
     for (const callExpr of callExpressions) {
       const expression = callExpr.getExpression();
       if (expression.getKind() !== SyntaxKind.PropertyAccessExpression) continue;
 
+      // Skip common HTTP clients to avoid false positives (e.g., axios.post)
+      const callerName = expression.getExpression().getText();
+      if (excludeCallers.includes(callerName.toLowerCase())) continue;
+
       const methodName = expression.getName();
       if (!methods.includes(methodName)) continue;
 
@@ -57,6 +62,10 @@ export function scanExpressProject(project, root) {
       // Pattern 1: router.get('/path', handler)
       if (args.length >= 2 && args[0].getKind() === SyntaxKind.StringLiteral) {
           pathStr = args[0].getLiteralText();
+          
+          // Skip external URLs (http:// or https://)
+          if (pathStr.startsWith("http")) continue;
+
           for (let i = 1; i < args.length - 1; i++) {
               middlewares.push(args[i].getText());
           }
@@ -70,6 +79,10 @@ export function scanExpressProject(project, root) {
               const routeArgs = routeCall.getArguments();
               if (routeArgs.length > 0 && routeArgs[0].getKind() === SyntaxKind.StringLiteral) {
                   pathStr = routeArgs[0].getLiteralText();
+                  
+                  // Skip external URLs (http:// or https://)
+                  if (pathStr.startsWith("http")) continue;
+
                   for (let i = 0; i < args.length - 1; i++) {
                       middlewares.push(args[i].getText());
                   }
@@ -80,16 +93,26 @@ export function scanExpressProject(project, root) {
 
       if (!pathStr || !handlerNode) continue;
 
+      // Ensure the handler is actually a function or a reference (exclude object literals)
+      const isFunctionHandler = [SyntaxKind.Identifier, SyntaxKind.FunctionExpression, SyntaxKind.ArrowFunction, SyntaxKind.CallExpression].includes(handlerNode.getKind());
+      if (!isFunctionHandler) continue;
+
       const fullPath = (routePrefix + pathStr).replace(/\/\//g, "/").replace(/\/$/, "") || "/";
       const resolvedHandler = resolveHandler(handlerNode);
       const analysis = analyzeHandler(resolvedHandler);
 
+      // Clean handler name: if it's an inline function, mark it for the generator to handle
+      let handlerName = handlerNode.getText();
+      if (handlerName.length > 50 || handlerName.includes("{") || handlerName.includes("=>")) {
+          handlerName = `[Anonymous]`;
+      }
+
       routes.push({
         method: methodName.toUpperCase(),
         path: fullPath,
         file: path.relative(root, sourceFile.getFilePath()),
         middlewares,
-        handlerName: handlerNode.getText(),
+        handlerName: handlerName,
         ...analysis,
         handlerCode: resolvedHandler ? resolvedHandler.getText().slice(0, 500) : ""
       });

package/src/scanners/modelScanner.js

@@ -7,12 +7,19 @@ export function scanModels(project) {
   const models = {};
 
   for (const sourceFile of project.getSourceFiles()) {
-    // Look for new Schema(...) or mongoose.Schema(...)
+    const schemaAliases = getMongooseSchemaAliases(sourceFile);
     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")) {
+        
+        // Detect schema instantiations based on dynamic imports or standard signatures
+        let isSchema = false;
+        if (schemaAliases.has(typeText) || typeText.endsWith("Schema")) {
+            isSchema = true;
+        }
+
+        if (isSchema) {
             const args = newExpr.getArguments();
             if (args.length > 0 && args[0].getKind() === SyntaxKind.ObjectLiteralExpression) {
                 const schemaObj = args[0];
@@ -29,26 +36,122 @@ export function scanModels(project) {
   return models;
 }
 
+function getMongooseSchemaAliases(sourceFile) {
+    const aliases = new Set(["Schema", "mongoose.Schema"]);
+    
+    // Check ES6 imports
+    for (const imp of sourceFile.getImportDeclarations()) {
+        if (imp.getModuleSpecifierValue() === 'mongoose') {
+            const defaultImport = imp.getDefaultImport();
+            if (defaultImport) {
+                aliases.add(`${defaultImport.getText()}.Schema`);
+            }
+            for (const namedImport of imp.getNamedImports()) {
+                if (namedImport.getName() === "Schema") {
+                    aliases.add(namedImport.getAliasNode() ? namedImport.getAliasNode().getText() : "Schema");
+                }
+            }
+        }
+    }
+
+    // Check CommonJS requires
+    for (const stmt of sourceFile.getVariableStatements()) {
+        for (const dec of stmt.getDeclarations()) {
+            const init = dec.getInitializer();
+            if (init && init.getKind() === SyntaxKind.CallExpression && init.getExpression().getText() === "require") {
+                const args = init.getArguments();
+                if (args.length > 0 && (args[0].getText() === "'mongoose'" || args[0].getText() === '"mongoose"')) {
+                    const nameNode = dec.getNameNode();
+                    if (nameNode.getKind() === SyntaxKind.Identifier) {
+                        aliases.add(`${nameNode.getText()}.Schema`);
+                    } else if (nameNode.getKind() === SyntaxKind.ObjectBindingPattern) {
+                        for (const el of nameNode.getElements()) {
+                            if (el.getPropertyNameNode() && el.getPropertyNameNode().getText() === "Schema") {
+                                aliases.add(el.getNameNode().getText());
+                            } else if (!el.getPropertyNameNode() && el.getNameNode().getText() === "Schema") {
+                                aliases.add("Schema");
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }
+    
+    return aliases;
+}
+
 function inferModelName(sourceFile, node) {
-    // Try to find the variable name it's assigned to (e.g., const userSchema = new Schema(...))
+    // 1. Try to find if it's passed directly to mongoose.model('Name', new Schema(...)) or similar
+    const parentCall = node.getFirstAncestorByKind(SyntaxKind.CallExpression);
+    if (parentCall) {
+        const exprText = parentCall.getExpression().getText();
+        if (exprText.includes("mongoose.model") || exprText.includes(".model")) {
+            const args = parentCall.getArguments();
+            if (args.length > 0) {
+                const name = resolveStringValue(args[0]);
+                if (name) return name;
+            }
+        }
+    }
+
+    // 2. Try to find the variable name it's assigned to
     const varDec = node.getFirstAncestorByKind(SyntaxKind.VariableDeclaration);
     if (varDec) {
-        let name = varDec.getName();
-        // Remove 'Schema' suffix if present
-        return name.replace(/Schema$/i, "");
+        const varName = varDec.getName();
+        
+        // Look for model registered somewhere else in the same file: mongoose.model('ModelName', varName)
+        const calls = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+        for (const call of calls) {
+            const exprText = call.getExpression().getText();
+            if (exprText.includes("model")) {
+                const args = call.getArguments();
+                if (args.length >= 2 && args[1].getText() === varName) {
+                    const name = resolveStringValue(args[0]);
+                    if (name) return name;
+                }
+            }
+        }
+        
+        // Remove 'Schema' suffix if present as a fallback
+        return varName.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 resolveStringValue(node) {
+    if (node.getKind() === SyntaxKind.StringLiteral || node.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral) {
+        return node.getLiteralText ? node.getLiteralText() : node.getText().replace(/['"]/g, "");
+    }
+    
+    // Advanced: Try standard TS resolution for constants (e.g., MODEL_NAMES.USER)
+    try {
+        const symbol = node.getSymbol();
+        if (symbol) {
+            const declarations = symbol.getDeclarations();
+            if (declarations && declarations.length > 0) {
+                const decl = declarations[0];
+                if (decl.getKind() === SyntaxKind.PropertyAssignment || decl.getKind() === SyntaxKind.VariableDeclaration) {
+                    const init = decl.getInitializer();
+                    if (init && (init.getKind() === SyntaxKind.StringLiteral || init.getKind() === SyntaxKind.NoSubstitutionTemplateLiteral)) {
+                        return init.getLiteralText ? init.getLiteralText() : init.getText().replace(/['"]/g, "");
+                    }
+                }
+                if (decl.getKind() === SyntaxKind.EnumMember) {
+                    const val = decl.getValue();
+                    if (typeof val === 'string') return val;
+                }
+            }
+        }
+    } catch(e) {
+        // Ignore resolution errors if ts-morph typechecker is unavailable
+    }
+    
+    return null;
+}
+
 function parseSchemaObject(obj) {
     const properties = {
         _id: { type: "string", example: "60d0fe4f5311236168a109ca" }
@@ -86,6 +189,15 @@ function parseFieldInfo(node, fieldName = "") {
         type = mapMongooseType(text);
     } else if (node.getKind() === SyntaxKind.ObjectLiteralExpression) {
         const typeProp = node.getProperty("type");
+        
+        // Recursive feature: If there is no 'type' property, treat as a nested subdocument schema
+        if (!typeProp) {
+            return {
+                schema: parseSchemaObject(node),
+                required: false
+            };
+        }
+
         if (typeProp && typeProp.getKind() === SyntaxKind.PropertyAssignment) {
             const typeInit = typeProp.getInitializer();
             if (typeInit) type = mapMongooseType(typeInit.getText());