@khiem_enhance/ai-doc-agent 0.1.3 → 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

@@ -16,17 +16,22 @@ program
     .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,43 +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 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 ----------
     if (only === "architecture" || only === "all") {
-        const tree = files.map((f) => path_1.default.relative(root, f)).join("\n");
-        // IMPORTANT: limit payload by file count + maxChars
-        const architectureSourceRaw = files
-            .slice(0, maxFiles)
-            .map((f) => `FILE: ${f}\n${(0, contentReader_1.readFile)(f)}`)
-            .join("\n\n");
-        const architectureSource = truncate(architectureSourceRaw, maxChars);
-        const architecture = await (0, architecture_1.generateArchitectureDoc)(tree, architectureSource);
+        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 ----------
     if (only === "modules" || only === "all") {
-        const modules = (0, moduleDetector_1.detectModules)(files, root);
-        for (const [moduleName, moduleFiles] of Object.entries(modules)) {
+        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");
-            // IMPORTANT: limit payload by file count + maxChars
-            const sourceRaw = moduleFiles
-                .slice(0, maxFiles)
-                .map((f) => `FILE: ${f}\n${(0, contentReader_1.readFile)(f)}`)
-                .join("\n\n");
-            const source = truncate(sourceRaw, maxChars);
-            const doc = await (0, modules_1.generateModuleDocs)(moduleName, fileList, source);
+            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/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,6 +1,6 @@
 {
   "name": "@khiem_enhance/ai-doc-agent",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "AI-powered documentation generator from source code",
   "license": "MIT",
   "bin": {