dinorex 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# 🦕 Dinorex
+
+> AI-powered API documentation generator. One command, full docs.
+
+Dinorex scans your Node.js project — routes, controllers, services, and DB models — and uses AI to automatically generate an interactive docs UI, a Postman collection, and a Swagger/OpenAPI file.
+
+---
+
+## Install
+
+```bash
+npm install -g dinorex
+```
+
+Or use without installing (requires Node 18+):
+
+```bash
+npx dinorex scan
+```
+
+---
+
+## Setup: Your Anthropic API Key
+
+Dinorex uses Claude AI to analyze your code. You need a free Anthropic API key.
+
+1. Go to [https://console.anthropic.com](https://console.anthropic.com)
+2. Create an account and generate an API key
+3. Set it in your environment:
+
+```bash
+# Mac/Linux — add to ~/.zshrc or ~/.bashrc
+export ANTHROPIC_API_KEY=sk-ant-your-key-here
+
+# Windows (PowerShell)
+$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"
+
+# Or pass it directly every time
+dinorex scan --api-key sk-ant-your-key-here
+```
+
+---
+
+## Usage
+
+### Scan your project and open docs
+```bash
+cd your-project/
+dinorex scan
+# Opens http://localhost:4321 automatically
+```
+
+### Scan a specific folder
+```bash
+dinorex scan ./backend --port 5000
+```
+
+### After adding new endpoints — smart rescan
+```bash
+dinorex scan
+# Dinorex detects only new/changed files and updates the spec incrementally
+# No need to re-analyze everything from scratch
+```
+
+### Force a full re-analysis
+```bash
+dinorex scan --full
+```
+
+### Generate files only (no UI server)
+```bash
+dinorex generate ./backend --out ./docs
+# Outputs: *-postman.json, *-openapi.yaml, *-spec.json
+```
+
+---
+
+## What gets scanned
+
+| Pattern | Examples |
+|---|---|
+| Routes | `routes/`, `*route*.js`, `*router*.js` |
+| Controllers | `controllers/`, `*controller*.js` |
+| Services | `services/`, `*service*.js` |
+| Models/Schemas | `models/`, `schemas/`, `*model*.js`, `*schema*.js` |
+
+Ignores: `node_modules`, `dist`, `build`, `.git`, test files.
+
+---
+
+## Output
+
+- **Interactive UI** at `http://localhost:4321` — browse, search, and test endpoints live
+- **Postman Collection** — download and import directly into Postman
+- **Swagger/OpenAPI YAML** — import into any OpenAPI-compatible tool
+
+---
+
+## Works with
+
+- Express.js
+- Fastify
+- NestJS
+- Koa
+- Any Node.js framework that uses route files
+
+---
+
+## Cache & incremental updates
+
+Dinorex stores a `.dinorex/spec.json` file in your project directory (auto-gitignored). On subsequent runs it only re-analyzes new or changed files — making rescans much faster.
+
+---
+
+## Options
+
+```
+dinorex scan [directory]
+  -p, --port <port>    Port to run docs server (default: 4321)
+  --no-open            Don't auto-open the browser
+  --api-key <key>      Anthropic API key
+
+dinorex generate [directory]
+  --out <dir>          Output directory (default: ./dinorex-output)
+  --api-key <key>      Anthropic API key
+```

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "dinorex",
+  "version": "1.0.0",
+  "description": "AI-powered API documentation generator — one command, full docs.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "dinorex": "src/cli.js"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "dev": "nodemon src/server.js"
+  },
+  "keywords": [
+    "api",
+    "swagger",
+    "postman",
+    "openapi",
+    "documentation",
+    "cli",
+    "ai"
+  ],
+  "author": "Dinorex",
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.20.0",
+    "chalk": "^5.3.0",
+    "commander": "^11.1.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "glob": "^10.3.10",
+    "js-yaml": "^4.1.0",
+    "multer": "^1.4.5-lts.1",
+    "ora": "^7.0.1",
+    "chokidar": "^3.5.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/agent.groq.js

@@ -0,0 +1,279 @@
+/**
+ * agent.groq.js — Free Groq/Llama3 version of the Dinorex AI agent.
+ *
+ * Get a free API key at: https://console.groq.com
+ * Set it:  export GROQ_API_KEY=gsk_your_key_here
+ *
+ * To use this instead of the Anthropic agent, change the import in cli.js and server.js:
+ *   import { analyzeWithAI, analyzeIncremental } from "./agent.groq.js";
+ */
+
+const GROQ_API_URL = "https://api.groq.com/openai/v1/chat/completions";
+const MODEL = "llama-3.3-70b-versatile";
+const MAX_CHARS = 12000; // safe limit per request (~3000 tokens of context)
+
+function buildContext(files) {
+  return files.map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n");
+}
+
+const SYSTEM_FULL = `You are an expert API analyst. Analyze source code (JavaScript OR TypeScript) and extract a complete API specification.
+
+Supported frameworks — recognize ALL of these:
+- Express / Fastify / Koa: router.get('/path', handler), app.post('/path', handler)
+- NestJS decorators: @Controller('base'), @Get(':id'), @Post(), @Put(), @Patch(), @Delete(), @Body(), @Param(), @Query(), @UseGuards()
+- TypeScript DTOs, interfaces, type aliases, class properties
+- Mongoose / Sequelize / TypeORM / Prisma schemas
+- Zod / Joi / Yup schemas: extract field names and types
+- class-validator decorators: @IsString(), @IsEmail(), etc.
+
+Rules:
+- Return ONLY valid JSON. No markdown, no explanation, no code fences.
+- Infer realistic example values from model/schema field names and types.
+- Group endpoints into logical collections (e.g. "Users", "Auth", "Products").
+- Detect auth guards: @UseGuards(), authMiddleware, isAuthenticated, verifyToken, requireAuth, JwtAuthGuard → requiresAuth: true.
+- For NestJS: combine @Controller('users') prefix with method paths (@Get(':id') → /users/:id).
+- TypeScript optional fields (field?: type) → required: false.
+
+Return ONLY this JSON structure, nothing else:
+{
+  "projectName": "string",
+  "baseUrl": "http://localhost:3000",
+  "version": "1.0.0",
+  "description": "string",
+  "collections": [
+    {
+      "name": "string",
+      "description": "string",
+      "endpoints": [
+        {
+          "id": "unique-kebab-slug",
+          "method": "GET|POST|PUT|PATCH|DELETE",
+          "path": "/api/resource/:id",
+          "summary": "Short title",
+          "description": "Longer description",
+          "requiresAuth": false,
+          "pathParams": [{ "name": "id", "type": "string", "description": "...", "example": "abc123" }],
+          "queryParams": [{ "name": "page", "type": "integer", "description": "...", "example": 1 }],
+          "requestBody": {
+            "contentType": "application/json",
+            "schema": {
+              "fieldName": { "type": "string", "example": "value", "required": true, "description": "..." }
+            }
+          },
+          "responses": {
+            "200": { "description": "Success", "example": {} },
+            "400": { "description": "Bad Request" },
+            "401": { "description": "Unauthorized" },
+            "404": { "description": "Not Found" },
+            "500": { "description": "Server Error" }
+          }
+        }
+      ]
+    }
+  ]
+}`;
+
+const SYSTEM_INCREMENTAL = `You are an expert API analyst doing an INCREMENTAL update to an existing API spec.
+
+You understand JavaScript AND TypeScript including Express, NestJS decorators, DTOs, Zod schemas, Mongoose/TypeORM/Prisma models.
+
+You will receive:
+1. The EXISTING spec (full JSON)
+2. NEW or CHANGED source files to analyze
+
+Your job:
+- Extract endpoints from new/changed files
+- If endpoint already exists (same method + path): update it if code changed, keep it if unchanged
+- If it is NEW: add it to the correct collection (create collection if needed)
+- Remove endpoints whose source files are listed under REMOVED FILES
+- Keep all existing endpoints from unchanged files
+
+Return the COMPLETE updated spec JSON. No markdown, no explanation, ONLY JSON.`;
+
+async function callGroq(systemPrompt, userMessage) {
+  const apiKey = process.env.GROQ_API_KEY;
+  if (!apiKey) {
+    throw new Error(
+      "GROQ_API_KEY is not set.\nGet a free key at https://console.groq.com\nThen run: export GROQ_API_KEY=gsk_your_key_here"
+    );
+  }
+
+  const response = await fetch(GROQ_API_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "Authorization": `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      model: MODEL,
+      temperature: 0.1, // low temp = more deterministic JSON output
+      max_tokens: 8000,
+      messages: [
+        { role: "system", content: systemPrompt },
+        { role: "user", content: userMessage },
+      ],
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text();
+    throw new Error(`Groq API error ${response.status}: ${err}`);
+  }
+
+  const data = await response.json();
+  const raw = data.choices?.[0]?.message?.content || "";
+  return raw;
+}
+
+function parseJSON(raw) {
+  // Strip any accidental markdown fences Llama might add
+  const cleaned = raw
+    .trim()
+    .replace(/^```json\s*/i, "")
+    .replace(/^```\s*/i, "")
+    .replace(/```\s*$/i, "")
+    .trim();
+
+  // Find the first { and last } to extract just the JSON object
+  const start = cleaned.indexOf("{");
+  const end = cleaned.lastIndexOf("}");
+  if (start === -1 || end === -1) {
+    throw new Error(`No JSON object found in response.\n\nSnippet: ${raw.slice(0, 300)}`);
+  }
+
+  const jsonStr = cleaned.slice(start, end + 1);
+
+  try {
+    return JSON.parse(jsonStr);
+  } catch (err) {
+    throw new Error(`Invalid JSON from Groq: ${err.message}\n\nSnippet: ${jsonStr.slice(0, 300)}`);
+  }
+}
+
+/**
+ * Split files into batches that fit within MAX_CHARS each.
+ */
+function batchFiles(files) {
+  const batches = [];
+  let current = [];
+  let size = 0;
+
+  for (const f of files) {
+    const len = f.content.length + f.path.length + 20;
+    if (size + len > MAX_CHARS && current.length > 0) {
+      batches.push(current);
+      current = [];
+      size = 0;
+    }
+    // If a single file is too large, truncate it
+    const truncated = { ...f, content: f.content.slice(0, MAX_CHARS) };
+    current.push(truncated);
+    size += len;
+  }
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+
+/**
+ * Merge multiple partial specs into one, deduplicating endpoints by method+path.
+ */
+function mergeSpecs(specs) {
+  const base = specs[0];
+  const collectionsMap = {};
+
+  for (const spec of specs) {
+    for (const col of spec.collections) {
+      if (!collectionsMap[col.name]) {
+        collectionsMap[col.name] = { ...col, endpoints: [] };
+      }
+      for (const ep of col.endpoints) {
+        const key = `${ep.method}:${ep.path}`;
+        const existing = collectionsMap[col.name].endpoints.find(
+          e => `${e.method}:${e.path}` === key
+        );
+        if (!existing) collectionsMap[col.name].endpoints.push(ep);
+      }
+    }
+  }
+
+  return {
+    ...base,
+    collections: Object.values(collectionsMap),
+  };
+}
+
+export async function analyzeWithAI(collected, projectName = "API") {
+  // Priority order: routes+controllers first (most important), then services, then models
+  const allFiles = [
+    ...collected.routes.map(f => ({ ...f, kind: "ROUTE" })),
+    ...collected.controllers.map(f => ({ ...f, kind: "CONTROLLER" })),
+    ...collected.services.map(f => ({ ...f, kind: "SERVICE" })),
+    ...collected.models.map(f => ({ ...f, kind: "MODEL" })),
+  ];
+
+  const batches = batchFiles(allFiles);
+  console.log(`\n  📦 Sending ${batches.length} batch(es) to Groq (${allFiles.length} files total)...`);
+
+  const partialSpecs = [];
+
+  for (let i = 0; i < batches.length; i++) {
+    const batch = batches[i];
+    const context = batch
+      .map(f => `### [${f.kind}] ${f.path}\n\`\`\`\n${f.content}\n\`\`\``)
+      .join("\n\n");
+
+    const userMessage = `Project name: "${projectName}" (batch ${i + 1} of ${batches.length})
+
+${context}
+
+Extract all API endpoints found in these files and return ONLY the JSON spec.`;
+
+    const raw = await callGroq(SYSTEM_FULL, userMessage);
+    const partial = parseJSON(raw);
+    partialSpecs.push(partial);
+
+    // Small delay between batches to avoid rate limiting
+    if (i < batches.length - 1) await sleep(1000);
+  }
+
+  return batches.length === 1 ? partialSpecs[0] : mergeSpecs(partialSpecs);
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+export async function analyzeIncremental(existingSpec, diff) {
+  const { newFiles, changedFiles, removedFiles } = diff;
+
+  if (!newFiles.length && !changedFiles.length && !removedFiles.length) {
+    return { spec: existingSpec, changed: false };
+  }
+
+  const filesToAnalyze = [...newFiles, ...changedFiles];
+  const removedContext = removedFiles.length > 0
+    ? `\n\nREMOVED FILES (delete their endpoints):\n${removedFiles.join("\n")}`
+    : "";
+
+  // Spec JSON itself can be large — truncate for incremental context
+  const specStr = JSON.stringify(existingSpec, null, 2);
+  const specTruncated = specStr.length > 6000
+    ? specStr.slice(0, 6000) + "\n... [truncated]"
+    : specStr;
+
+  const changedContext = filesToAnalyze
+    .map(f => `### ${f.path}\n\`\`\`\n${f.content.slice(0, 3000)}\n\`\`\``)
+    .join("\n\n");
+
+  const userMessage = `EXISTING SPEC:
+${specTruncated}
+
+NEW/CHANGED FILES:
+${changedContext}${removedContext}
+
+Return the complete updated spec JSON only.`;
+
+  const raw = await callGroq(SYSTEM_INCREMENTAL, userMessage);
+  const updated = parseJSON(raw);
+  return { spec: updated, changed: true };
+}

package/src/agent.js

@@ -0,0 +1,155 @@
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic();
+
+function buildContext(files) {
+  return files.map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``).join("\n\n");
+}
+
+const SYSTEM_FULL = `You are an expert API analyst. Analyze source code (JavaScript OR TypeScript) and extract a complete API specification.
+
+Supported frameworks and patterns — recognize ALL of these:
+- Express / Fastify / Koa: router.get('/path', handler), app.post('/path', handler)
+- NestJS decorators: @Controller('base'), @Get(':id'), @Post(), @Put(), @Patch(), @Delete(), @Body(), @Param(), @Query(), @UseGuards()
+- TypeScript types & interfaces: extract field names/types from DTOs, interfaces, type aliases, class properties
+- Mongoose/Sequelize/TypeORM/Prisma schemas: extract model fields and types
+- tRPC routers: t.router({ ... }), publicProcedure, protectedProcedure — map to equivalent REST-style endpoints
+- Zod/Joi/Yup schemas: extract field names and types as request/response body schemas
+- Class-validator decorators: @IsString(), @IsEmail(), @IsNumber(), etc. → use as field type hints
+
+Rules:
+- Return ONLY valid JSON. No markdown, no explanation.
+- Infer realistic example values from model/schema field names and types (TypeScript types count).
+- Group endpoints into logical tags/collections (e.g. "Users", "Auth", "Products").
+- Detect auth guards/middleware: @UseGuards(), @Roles(), authMiddleware, isAuthenticated, verifyToken, requireAuth, JwtAuthGuard, etc. → requiresAuth: true.
+- For NestJS: combine @Controller('users') prefix with method decorator paths (e.g. @Get(':id') → /users/:id).
+- Use DTO classes, interfaces, Zod schemas, or Mongoose models to build realistic request/response body examples.
+- TypeScript optional fields (field?: type) → required: false. Non-optional → required: true.
+
+Return this exact structure:
+{
+  "projectName": "string",
+  "baseUrl": "http://localhost:3000",
+  "version": "1.0.0",
+  "description": "string",
+  "collections": [
+    {
+      "name": "string",
+      "description": "string",
+      "endpoints": [
+        {
+          "id": "unique-kebab-slug",
+          "method": "GET|POST|PUT|PATCH|DELETE",
+          "path": "/api/resource/:id",
+          "summary": "Short title",
+          "description": "Longer description",
+          "requiresAuth": false,
+          "pathParams": [{ "name": "id", "type": "string", "description": "...", "example": "abc123" }],
+          "queryParams": [{ "name": "page", "type": "integer", "description": "...", "example": 1 }],
+          "requestBody": {
+            "contentType": "application/json",
+            "schema": {
+              "fieldName": { "type": "string", "example": "value", "required": true, "description": "..." }
+            }
+          },
+          "responses": {
+            "200": { "description": "Success", "example": {} },
+            "400": { "description": "Bad Request" },
+            "401": { "description": "Unauthorized" },
+            "404": { "description": "Not Found" },
+            "500": { "description": "Server Error" }
+          }
+        }
+      ]
+    }
+  ]
+}`;
+
+const SYSTEM_INCREMENTAL = `You are an expert API analyst doing an INCREMENTAL update to an existing API spec.
+
+You understand JavaScript AND TypeScript, including: Express, Fastify, NestJS decorators (@Controller, @Get, @Post, etc.), DTOs, Zod/Joi schemas, Mongoose/TypeORM/Prisma models, and class-validator decorators.
+
+You will receive:
+1. The EXISTING spec (full JSON)
+2. NEW or CHANGED source files to analyze
+
+Your job:
+- Extract endpoints from the new/changed files
+- For each endpoint, check if it already exists in the spec (match by method + path)
+- If it EXISTS and is unchanged: keep it as-is (don't re-add)
+- If it EXISTS but the code changed: update it with improved info
+- If it's NEW: add it to the correct collection (create the collection if needed)
+- Remove endpoints whose source files were deleted (listed under REMOVED FILES)
+- Keep all existing endpoints from files that weren't changed
+
+Return the COMPLETE updated spec JSON (same structure as input). No markdown, no explanation, only JSON.`;
+
+export async function analyzeWithAI(collected, projectName = "API") {
+  const allFiles = [
+    ...collected.routes,
+    ...collected.controllers,
+    ...collected.services,
+    ...collected.models,
+  ];
+
+  const context = [
+    collected.routes.length > 0 ? "## ROUTES\n" + buildContext(collected.routes) : null,
+    collected.controllers.length > 0 ? "## CONTROLLERS\n" + buildContext(collected.controllers) : null,
+    collected.services.length > 0 ? "## SERVICES\n" + buildContext(collected.services) : null,
+    collected.models.length > 0 ? "## MODELS\n" + buildContext(collected.models) : null,
+  ].filter(Boolean).join("\n\n---\n\n");
+
+  const response = await client.messages.create({
+    model: "claude-opus-4-5",
+    max_tokens: 8000,
+    system: SYSTEM_FULL,
+    messages: [{
+      role: "user",
+      content: `Project: "${projectName}"\n\n${context}\n\nExtract all API endpoints and return the JSON spec.`
+    }],
+  });
+
+  return parseJSON(response.content[0].text);
+}
+
+export async function analyzeIncremental(existingSpec, diff) {
+  const { newFiles, changedFiles, removedFiles } = diff;
+
+  if (newFiles.length === 0 && changedFiles.length === 0 && removedFiles.length === 0) {
+    return { spec: existingSpec, changed: false };
+  }
+
+  const changedContext = [...newFiles, ...changedFiles]
+    .map(f => `### ${f.path}\n\`\`\`\n${f.content}\n\`\`\``)
+    .join("\n\n");
+
+  const removedContext = removedFiles.length > 0
+    ? `\n\nREMOVED FILES (delete their endpoints):\n${removedFiles.join("\n")}`
+    : "";
+
+  const response = await client.messages.create({
+    model: "claude-opus-4-5",
+    max_tokens: 8000,
+    system: SYSTEM_INCREMENTAL,
+    messages: [{
+      role: "user",
+      content: `EXISTING SPEC:\n${JSON.stringify(existingSpec, null, 2)}\n\nNEW/CHANGED FILES:\n${changedContext}${removedContext}\n\nReturn the complete updated spec.`
+    }],
+  });
+
+  const updated = parseJSON(response.content[0].text);
+  return { spec: updated, changed: true };
+}
+
+function parseJSON(raw) {
+  const cleaned = raw.trim()
+    .replace(/^```json\s*/i, "")
+    .replace(/^```\s*/i, "")
+    .replace(/```\s*$/i, "")
+    .trim();
+  try {
+    return JSON.parse(cleaned);
+  } catch (err) {
+    throw new Error(`AI returned invalid JSON: ${err.message}\n\nSnippet: ${raw.slice(0, 300)}`);
+  }
+}