@khiem_enhance/ai-doc-agent 0.1.1 → 0.1.5

package/dist/cache/docCache.js

@@ -0,0 +1,28 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCacheKey = getCacheKey;
+exports.readCache = readCache;
+exports.writeCache = writeCache;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const CACHE_DIR = ".ai-doc-cache";
+function sha1(input) {
+    return crypto_1.default.createHash("sha1").update(input).digest("hex");
+}
+function getCacheKey(parts) {
+    return sha1(`${parts.kind}:${parts.name}:${parts.fileList}:${parts.payload}`);
+}
+function readCache(key) {
+    const p = path_1.default.join(CACHE_DIR, `${key}.md`);
+    if (!fs_1.default.existsSync(p))
+        return null;
+    return fs_1.default.readFileSync(p, "utf-8");
+}
+function writeCache(key, content) {
+    fs_1.default.mkdirSync(CACHE_DIR, { recursive: true });
+    fs_1.default.writeFileSync(path_1.default.join(CACHE_DIR, `${key}.md`), content);
+}

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+require("dotenv/config");
 const commander_1 = require("commander");
 const generate_1 = require("./commands/generate");
 const program = new commander_1.Command();
@@ -10,8 +11,27 @@ program
     .version("0.1.0");
 program
     .command("generate")
-    .option("--only <part>", "architecture|modules", "architecture")
-    .option("--output <dir>", "Docs output directory", "docs")
     .option("--since <commit>", "Only analyze changes since commit")
-    .action(generate_1.generateDocs);
+    .option("--output <dir>", "Docs output directory", "docs")
+    .option("--only <part>", "architecture|modules|all", "all")
+    .option("--max-files <n>", "Max files included per LLM request", "8")
+    .option("--max-chars <n>", "Max characters included per LLM request", "60000")
+    .option("--module <name>", "Only generate docs for a specific module")
+    .option("--max-modules <n>", "Max modules to generate in one run", "3")
+    .action(async (opts) => {
+    // normalize options
+    const only = String(opts.only ?? "all");
+    const maxFiles = Number(opts.maxFiles ?? 8);
+    const maxChars = Number(opts.maxChars ?? 60000);
+    const maxModules = Number(opts.maxModules ?? 3);
+    await (0, generate_1.generateDocs)({
+        since: opts.since,
+        output: opts.output,
+        only: only ?? "all",
+        maxFiles: Number.isFinite(maxFiles) ? maxFiles : 8,
+        maxChars: Number.isFinite(maxChars) ? maxChars : 60000,
+        module: opts.module ? String(opts.module) : undefined,
+        maxModules: Number.isFinite(maxModules) ? maxModules : 3,
+    });
+});
 program.parse();

package/dist/commands/generate.js

@@ -12,35 +12,80 @@ const modules_1 = require("../analyzers/modules");
 const markdownWriter_1 = require("../writers/markdownWriter");
 const gitUtils_1 = require("../git/gitUtils");
 const moduleDetector_1 = require("../scanner/moduleDetector");
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const fileRanker_1 = require("../scanner/fileRanker");
+const docCache_1 = require("../cache/docCache");
+const truncate = (s, maxChars) => s.length > maxChars ? s.slice(0, maxChars) + "\n\n...<truncated>" : s;
+function buildPayload(files, maxFiles, maxChars) {
+    const raw = files
+        .slice(0, maxFiles)
+        .map((f) => `FILE: ${f}\n${(0, contentReader_1.readFile)(f)}`)
+        .join("\n\n");
+    return truncate(raw, maxChars);
+}
 async function generateDocs(options) {
     const root = process.cwd();
-    const files = options.since
+    const allFiles = options.since
         ? (0, gitUtils_1.getChangedFiles)(options.since).map((f) => path_1.default.join(root, f))
         : await (0, fileScanner_1.scanProject)(root);
+    const only = options.only ?? "all";
+    const maxFiles = Math.max(1, options.maxFiles ?? 8);
+    const maxChars = Math.max(5000, options.maxChars ?? 60000);
+    const maxModules = Math.max(1, options.maxModules ?? 3);
+    // Rank files globally for architecture (better signal, lower token)
+    const rankedAll = (0, fileRanker_1.rankFiles)(allFiles, root);
     // ---------- Architecture ----------
-    const tree = files.map((f) => path_1.default.relative(root, f)).join("\n");
-    const architectureSource = files
-        .slice(0, 25)
-        .map((f) => `FILE: ${f}\n${(0, contentReader_1.readFile)(f)}`)
-        .join("\n\n");
-    const architecture = await (0, architecture_1.generateArchitectureDoc)(tree, architectureSource);
-    (0, markdownWriter_1.writeDoc)(options.output, "architecture.md", architecture);
-    // ✅ Throttle để không chạm RPM ngay sau architecture
-    await sleep(22000);
+    if (only === "architecture" || only === "all") {
+        const tree = allFiles.map((f) => path_1.default.relative(root, f)).join("\n");
+        const architecturePayload = buildPayload(rankedAll, maxFiles, maxChars);
+        const archCacheKey = (0, docCache_1.getCacheKey)({
+            kind: "architecture",
+            name: "architecture",
+            fileList: tree,
+            payload: architecturePayload,
+        });
+        const cachedArch = (0, docCache_1.readCache)(archCacheKey);
+        const architecture = cachedArch ?? (await (0, architecture_1.generateArchitectureDoc)(tree, architecturePayload));
+        if (cachedArch) {
+            console.log("🧠 Cache hit: architecture");
+        }
+        else {
+            (0, docCache_1.writeCache)(archCacheKey, architecture);
+            console.log("🧠 Cache miss: architecture (generated)");
+        }
+        (0, markdownWriter_1.writeDoc)(options.output, "architecture.md", architecture);
+        console.log("📄 Architecture doc generated");
+    }
     // ---------- Modules ----------
-    const modules = (0, moduleDetector_1.detectModules)(files, root);
-    for (const [moduleName, moduleFiles] of Object.entries(modules)) {
-        const fileList = moduleFiles.map((f) => path_1.default.relative(root, f)).join("\n");
-        const source = moduleFiles
-            .slice(0, 20)
-            .map((f) => `FILE: ${f}\n${(0, contentReader_1.readFile)(f)}`)
-            .join("\n\n");
-        const doc = await (0, modules_1.generateModuleDocs)(moduleName, fileList, source);
-        (0, markdownWriter_1.writeDoc)(path_1.default.join(options.output, "modules"), `${moduleName}.md`, doc);
-        console.log(`📄 Module doc generated: ${moduleName}`);
-        // ✅ Throttle giữa các module để giữ < 3 request/min
-        await sleep(22000);
+    if (only === "modules" || only === "all") {
+        const modules = (0, moduleDetector_1.detectModules)(allFiles, root);
+        const entries = Object.entries(modules).filter(([name]) => options.module ? name === options.module : true);
+        const limitedEntries = entries.slice(0, maxModules);
+        for (const [moduleName, moduleFiles] of limitedEntries) {
+            const fileList = moduleFiles.map((f) => path_1.default.relative(root, f)).join("\n");
+            const rankedModuleFiles = (0, fileRanker_1.rankFiles)(moduleFiles, root);
+            const modulePayload = buildPayload(rankedModuleFiles, maxFiles, maxChars);
+            const moduleCacheKey = (0, docCache_1.getCacheKey)({
+                kind: "module",
+                name: moduleName,
+                fileList,
+                payload: modulePayload,
+            });
+            const cachedModule = (0, docCache_1.readCache)(moduleCacheKey);
+            const doc = cachedModule ?? (await (0, modules_1.generateModuleDocs)(moduleName, fileList, modulePayload));
+            if (cachedModule) {
+                console.log(`🧠 Cache hit: module ${moduleName}`);
+            }
+            else {
+                (0, docCache_1.writeCache)(moduleCacheKey, doc);
+                console.log(`🧠 Cache miss: module ${moduleName} (generated)`);
+            }
+            (0, markdownWriter_1.writeDoc)(path_1.default.join(options.output, "modules"), `${moduleName}.md`, doc);
+            console.log(`📄 Module doc generated: ${moduleName}`);
+        }
+        if (entries.length > limitedEntries.length) {
+            console.log(`ℹ️ Skipped ${entries.length - limitedEntries.length} modules due to --max-modules=${maxModules}. ` +
+                `Re-run with higher limit or specify --module <name>.`);
+        }
     }
     console.log("✅ Docs generation completed");
 }

package/dist/llm/openaiClient.js

@@ -6,14 +6,60 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.openai = void 0;
 exports.askLLM = askLLM;
 const openai_1 = __importDefault(require("openai"));
-const env_1 = require("../config/env");
-exports.openai = new openai_1.default({
-    apiKey: env_1.env.openaiKey
-});
-async function askLLM(prompt) {
-    const res = await exports.openai.chat.completions.create({
-        model: env_1.env.model,
-        messages: [{ role: "user", content: prompt }]
-    });
-    return res.choices[0].message.content;
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) {
+    throw new Error("Missing OPENAI_API_KEY.\n" +
+        "Set it before running:\n" +
+        '  export OPENAI_API_KEY="sk-xxxx"\n');
+}
+exports.openai = new openai_1.default({ apiKey });
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * askLLM with:
+ * - retry on 429 using retry-after headers
+ * - fail gracefully if retry-after is extremely long (token budget exhausted)
+ */
+async function askLLM(prompt, maxRetries = 5) {
+    const model = process.env.MODEL || "gpt-4.1-mini";
+    let attempt = 0;
+    while (true) {
+        try {
+            const res = await exports.openai.chat.completions.create({
+                model,
+                messages: [{ role: "user", content: prompt }],
+            });
+            return res.choices[0].message.content ?? "";
+        }
+        catch (err) {
+            attempt++;
+            const status = err?.status;
+            const headers = err?.headers || {};
+            const retryAfterMs = Number(headers["retry-after-ms"]) ||
+                (Number(headers["retry-after"]) || 0) * 1000;
+            if (status === 429) {
+                // If retry-after is huge => org quota/token budget exhausted for a long window.
+                if (retryAfterMs && retryAfterMs > 120000) {
+                    throw new Error([
+                        "Rate limited (429) due to token/request limits.",
+                        `Retry-After is very long: ~${Math.ceil(retryAfterMs / 1000)}s.`,
+                        "",
+                        "Fix suggestions:",
+                        "- Reduce input size:",
+                        "  ai-doc-agent generate --only architecture --max-files 5 --max-chars 30000",
+                        "- Or run modules separately:",
+                        "  ai-doc-agent generate --only modules --max-files 4 --max-chars 25000",
+                        "- Or increase your OpenAI limits / add billing on your OpenAI account.",
+                    ].join("\n"));
+                }
+                if (attempt <= maxRetries) {
+                    const wait = retryAfterMs || 20000;
+                    console.warn(`⚠️ Rate limited (429). Retrying in ${Math.ceil(wait / 1000)}s... (${attempt}/${maxRetries})`);
+                    await sleep(wait);
+                    continue;
+                }
+            }
+            // Non-429 or exceeded retries
+            throw err;
+        }
+    }
 }

package/dist/scanner/fileRanker.js

@@ -0,0 +1,48 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rankFiles = rankFiles;
+const path_1 = __importDefault(require("path"));
+const IMPORTANT_PATTERNS = [
+    /route/i,
+    /router/i,
+    /controller/i,
+    /service/i,
+    /api/i,
+    /hook/i,
+    /store/i,
+    /slice/i,
+    /middleware/i,
+    /schema/i,
+    /model/i,
+    /dto/i,
+    /validator/i,
+    /utils/i,
+];
+function rankFiles(files, root) {
+    return [...files].sort((a, b) => score(b, root) - score(a, root));
+}
+function score(filePath, root) {
+    const rel = path_1.default.relative(root, filePath);
+    let s = 0;
+    // Prefer shorter paths (usually closer to feature root)
+    s += Math.max(0, 30 - rel.split(path_1.default.sep).length * 3);
+    // Prefer key filenames/patterns
+    for (const re of IMPORTANT_PATTERNS) {
+        if (re.test(rel))
+            s += 25;
+    }
+    // Prefer index/entrypoints
+    if (/index\.(ts|tsx|js|jsx)$/.test(rel))
+        s += 20;
+    if (/main\.(ts|js)$/.test(rel))
+        s += 15;
+    if (/app\.(ts|tsx|js|jsx)$/.test(rel))
+        s += 15;
+    // Prefer config
+    if (/config/i.test(rel))
+        s += 8;
+    return s;
+}

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@khiem_enhance/ai-doc-agent",
-  "version": "0.1.1",
+  "version": "0.1.5",
   "description": "AI-powered documentation generator from source code",
   "license": "MIT",
   "bin": {
     "ai-doc-agent": "dist/cli.js"
   },
   "main": "dist/cli.js",
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build"