explainthisrepo 0.4.4 → 0.5.0

package/dist/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import os from "node:os";
 import process from "node:process";
+import fs from "node:fs";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -10,6 +11,7 @@ import { buildPrompt, buildQuickPrompt, buildSimplePrompt } from "./prompt.js";
 import { generateExplanation } from "./generate.js";
 import { writeOutput } from "./writer.js";
 import { readRepoSignalFiles } from "./repo_reader.js";
+import { readLocalRepoSignalFiles } from "./local_reader.js";
 import { fetchLanguages } from "./github.js";
 import { detectStack } from "./stack-detector.js";
 import { printStack } from "./stack_printer.js";
@@ -22,8 +24,8 @@ function resolveRepoTarget(target) {
         target = target.replace("http//", "http://");
     }
     if (target.startsWith("git@github.com:")) {
-        const path = target.replace("git@github.com:", "");
-        const [owner, repoRaw] = path.split("/", 2);
+        const p = target.replace("git@github.com:", "");
+        const [owner, repoRaw] = p.split("/", 2);
         if (!owner || !repoRaw)
             throw new Error("Invalid GitHub SSH URL");
         return { owner, repo: repoRaw.replace(/\.git$/, "") };
@@ -83,10 +85,7 @@ async function checkUrl(url, timeoutMs = 6000) {
         clearTimeout(t);
         const message = e instanceof Error ? e.message : String(e);
         const name = e instanceof Error ? e.name : "Error";
-        return {
-            ok: false,
-            msg: `failed (${name}: ${message})`,
-        };
+        return { ok: false, msg: `failed (${name}: ${message})` };
     }
 }
 async function runDoctor() {
@@ -135,7 +134,7 @@ async function main() {
         .name("explainthisrepo")
         .description("Explain GitHub repositories in plain English")
         .version(getPkgVersion(), "-v, --version", "Show version")
-        .argument("[repository]", "GitHub repository (owner/repo or URL)")
+        .argument("[repository]", "GitHub repository (owner/repo or URL) or local path")
         .option("--doctor", "Run diagnostics")
         .option("--quick", "Quick summary mode")
         .option("--simple", "Simple summary mode")
@@ -151,6 +150,9 @@ Examples:
   $ explainthisrepo owner/repo --quick
   $ explainthisrepo owner/repo --simple
   $ explainthisrepo owner/repo --stack
+  $ explainthisrepo .
+  $ explainthisrepo ./path/to/directory
+  $ explainthisrepo . --stack
   $ explainthisrepo --doctor`);
     program.parse(process.argv);
     const options = program.opts();
@@ -172,58 +174,86 @@ Examples:
     if (!repository) {
         program.error("repository argument required");
     }
-    let owner, repo;
-    try {
-        ({ owner, repo } = resolveRepoTarget(repository));
+    const local = fs.existsSync(repository);
+    let owner = "";
+    let repo = "";
+    let localPath = "";
+    if (local) {
+        localPath = path.resolve(repository);
+        console.log(`Analyzing local directory: ${repository}`);
     }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.error(`error: ${message}`);
-        process.exit(1);
-    }
-    console.log(`Fetching ${owner}/${repo}...`);
-    if (options.stack) {
+    else {
         try {
-            const languages = await fetchLanguages(owner, repo);
-            const read = await readRepoSignalFiles(owner, repo);
-            const report = detectStack({
-                languages,
-                tree: read.tree,
-                keyFiles: read.keyFiles,
-            });
-            printStack(report, owner, repo);
-            return;
+            ({ owner, repo } = resolveRepoTarget(repository));
         }
         catch (e) {
             const message = e instanceof Error ? e.message : String(e);
             console.error(`error: ${message}`);
             process.exit(1);
         }
+        console.log(`Fetching ${owner}/${repo}...`);
     }
-    let repoData;
-    try {
-        repoData = await fetchRepo(owner, repo);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.error("Failed to fetch repository data.");
-        console.error(`error: ${message}`);
-        console.error("\nfix:");
-        console.error("- Ensure the repository exists and is public");
-        console.error("- Or set GITHUB_TOKEN to avoid rate limits");
-        process.exit(1);
+    if (options.stack) {
+        let read;
+        let languages = {};
+        if (local) {
+            read = readLocalRepoSignalFiles(localPath);
+        }
+        else {
+            try {
+                languages = await fetchLanguages(owner, repo);
+                read = await readRepoSignalFiles(owner, repo);
+            }
+            catch (e) {
+                const message = e instanceof Error ? e.message : String(e);
+                console.error(`error: ${message}`);
+                process.exit(1);
+            }
+        }
+        const report = detectStack({
+            languages,
+            tree: read.tree,
+            keyFiles: read.keyFiles,
+        });
+        const label = local ? repository : owner;
+        const sublabel = local ? "" : repo;
+        printStack(report, label, sublabel);
+        return;
     }
+    let repoData = null;
     let readme = null;
-    try {
-        readme = await fetchReadme(owner, repo);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.warn(`Warning: Could not fetch README: ${message}`);
-        readme = null;
+    if (!local) {
+        try {
+            repoData = await fetchRepo(owner, repo);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            console.error("Failed to fetch repository data.");
+            console.error(`error: ${message}`);
+            console.error("\nfix:");
+            console.error("- Ensure the repository exists and is public");
+            console.error("- Or set GITHUB_TOKEN to avoid rate limits");
+            process.exit(1);
+        }
+        try {
+            readme = await fetchReadme(owner, repo);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            console.warn(`Warning: Could not fetch README: ${message}`);
+            readme = null;
+        }
     }
     if (options.quick) {
-        const prompt = buildQuickPrompt(repoData.full_name, repoData.description, readme);
+        let quickReadme = readme;
+        const repoName = local ? localPath : (repoData?.full_name ?? "");
+        const description = local ? null : (repoData?.description ?? null);
+        if (local) {
+            const read = readLocalRepoSignalFiles(localPath);
+            const readmeKey = Object.keys(read.keyFiles).find((k) => k.toLowerCase().startsWith("readme"));
+            quickReadme = readmeKey !== undefined ? read.keyFiles[readmeKey] : null;
+        }
+        const prompt = buildQuickPrompt(repoName, description, quickReadme);
         console.log("Generating explanation...");
         const output = await generateWithExit(prompt);
         console.log("Quick summary 🎉");
@@ -231,16 +261,20 @@ Examples:
         return;
     }
     if (options.simple) {
-        const readResult = await safeReadRepoFiles(owner, repo);
-        const prompt = buildSimplePrompt(repoData.full_name, repoData.description, readme, readResult?.treeText ?? null);
+        const readResult = local
+            ? readLocalRepoSignalFiles(localPath)
+            : await safeReadRepoFiles(owner, repo);
+        const prompt = buildSimplePrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, readResult?.treeText ?? null);
         console.log("Generating explanation...");
         const output = await generateWithExit(prompt);
         console.log("Simple summary 🎉");
         console.log(output.trim());
         return;
     }
-    const readResult = await safeReadRepoFiles(owner, repo);
-    const prompt = buildPrompt(repoData.full_name, repoData.description, readme, options.detailed || false, readResult?.treeText ?? null, readResult?.filesText ?? null);
+    const readResult = local
+        ? readLocalRepoSignalFiles(localPath)
+        : await safeReadRepoFiles(owner, repo);
+    const prompt = buildPrompt(local ? localPath : (repoData?.full_name ?? ""), local ? null : (repoData?.description ?? null), local ? null : readme, options.detailed || false, readResult?.treeText ?? null, readResult?.filesText ?? null);
     console.log("Generating explanation...");
     const output = await generateWithExit(prompt);
     console.log("Writing EXPLAIN.md...");

package/dist/local_reader.d.ts

@@ -0,0 +1,2 @@
+import { type RepoReadResult } from "./repo_reader.js";
+export declare function readLocalRepoSignalFiles(dirPath: string): RepoReadResult;

package/dist/local_reader.js

@@ -0,0 +1,77 @@
+import fs from "node:fs";
+import path from "node:path";
+const KEY_FILENAMES = new Set([
+    "readme.md", "readme.txt", "readme.rst", "readme",
+    "package.json", "pyproject.toml", "setup.py", "setup.cfg",
+    "requirements.txt", "cargo.toml", "go.mod", "pom.xml",
+    "build.gradle", "composer.json", "gemfile", "makefile",
+    "dockerfile", "docker-compose.yml", "docker-compose.yaml",
+    ".env.example", "tsconfig.json", "angular.json", "next.config.js",
+    "vite.config.js", "vite.config.ts", "webpack.config.js",
+]);
+const SKIP_DIRS = new Set([
+    ".git", ".hg", ".svn", "node_modules", "__pycache__",
+    ".venv", "venv", "env", ".env", "dist", "build",
+    ".idea", ".vscode", ".mypy_cache", ".pytest_cache",
+    "coverage", ".coverage", "htmlcov",
+]);
+const MAX_FILE_BYTES = 32_000;
+const MAX_KEY_FILES = 12;
+function walkDir(root, dir, tree, keyFiles) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const dirs = [];
+    const files = [];
+    for (const entry of entries) {
+        if (entry.isDirectory() && !SKIP_DIRS.has(entry.name)) {
+            dirs.push(entry);
+        }
+        else if (entry.isFile()) {
+            files.push(entry);
+        }
+    }
+    dirs.sort((a, b) => a.name.localeCompare(b.name));
+    files.sort((a, b) => a.name.localeCompare(b.name));
+    for (const file of files) {
+        const absPath = path.join(dir, file.name);
+        const relPath = path.relative(root, absPath).replace(/\\/g, "/");
+        tree.push({ path: relPath, type: "blob" });
+        if (KEY_FILENAMES.has(file.name.toLowerCase()) &&
+            Object.keys(keyFiles).length < MAX_KEY_FILES) {
+            try {
+                const fd = fs.openSync(absPath, "r");
+                const buf = Buffer.alloc(MAX_FILE_BYTES);
+                const bytesRead = fs.readSync(fd, buf, 0, MAX_FILE_BYTES, 0);
+                fs.closeSync(fd);
+                keyFiles[relPath] = buf.subarray(0, bytesRead).toString("utf8");
+            }
+            catch {
+            }
+        }
+    }
+    for (const subdir of dirs) {
+        walkDir(root, path.join(dir, subdir.name), tree, keyFiles);
+    }
+}
+export function readLocalRepoSignalFiles(dirPath) {
+    const root = path.resolve(dirPath);
+    const tree = [];
+    const keyFiles = {};
+    walkDir(root, root, tree, keyFiles);
+    const treeText = tree.map((item) => item.path).join("\n");
+    const filesText = Object.entries(keyFiles)
+        .map(([relPath, content]) => `### ${relPath}\n${content}`)
+        .join("\n\n");
+    return {
+        tree,
+        treeText,
+        keyFiles,
+        filesText,
+        selectedFiles: Object.keys(keyFiles),
+    };
+}

package/dist/repo_reader.d.ts

@@ -1,4 +1,4 @@
-type TreeItem = {
+export type TreeItem = {
     path: string;
     type: "blob" | "tree";
     size?: number;
@@ -11,4 +11,3 @@ export type RepoReadResult = {
     keyFiles: Record<string, string>;
 };
 export declare function readRepoSignalFiles(owner: string, repo: string): Promise<RepoReadResult>;
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "A CLI developer tool to explain any GitHub repository in plain English",
   "license": "MIT",
   "type": "module",