autodocsync 1.0.0 → 1.0.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "autodocsync",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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/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());