explainthisrepo 0.1.1 → 0.1.3

package/dist/cli.js

@@ -8,10 +8,12 @@ import { fetchRepo, fetchReadme } from "./github.js";
 import { buildPrompt } from "./prompt.js";
 import { generateExplanation } from "./generate.js";
 import { writeOutput } from "./writer.js";
+import { readRepoSignalFiles } from "./repo_reader.js";
 function usage() {
     console.log("usage:");
     console.log("  explainthisrepo owner/repo");
     console.log("  explainthisrepo owner/repo --detailed");
+    console.log("  explainthisrepo owner/repo --quick");
     console.log("  explainthisrepo --doctor");
     console.log("  explainthisrepo --version");
 }
@@ -85,12 +87,16 @@ async function main() {
         process.exit(code);
     }
     let detailed = false;
+    let quick = false;
     if (args.length === 2) {
-        if (args[1] !== "--detailed") {
+        if (args[1] === "--detailed")
+            detailed = true;
+        else if (args[1] === "--quick")
+            quick = true;
+        else {
             usage();
             process.exit(1);
         }
-        detailed = true;
     }
     else if (args.length !== 1) {
         usage();
@@ -110,9 +116,15 @@ async function main() {
     try {
         const repoData = await fetchRepo(owner, repo);
         const readme = await fetchReadme(owner, repo);
-        const prompt = buildPrompt(repoData.full_name, repoData.description, readme, detailed);
+        const readResult = await readRepoSignalFiles(owner, repo);
+        const prompt = buildPrompt(repoData.full_name, repoData.description, readme, detailed, quick, readResult.treeText, readResult.filesText);
         console.log("Generating explanation...");
         const output = await generateExplanation(prompt);
+        if (quick) {
+            console.log("Quick summary 🎉");
+            console.log(output.trim());
+            return;
+        }
         console.log("Writing EXPLAIN.md...");
         writeOutput(output);
         const wordCount = output.split(/\s+/).filter(Boolean).length;

package/dist/github.d.ts

@@ -1,2 +1,4 @@
 export declare function fetchRepo(owner: string, repo: string): Promise<any>;
 export declare function fetchReadme(owner: string, repo: string): Promise<string | null>;
+export declare function fetchTree(owner: string, repo: string): Promise<any[]>;
+export declare function fetchFile(owner: string, repo: string, filePath: string): Promise<string>;

package/dist/github.js

@@ -95,3 +95,28 @@ export async function fetchReadme(owner, repo) {
         throw err;
     }
 }
+export async function fetchTree(owner, repo) {
+    return requestWithRetry(async () => {
+        const repoRes = await github.get(`/repos/${owner}/${repo}`);
+        const defaultBranch = repoRes.data?.default_branch;
+        const res = await github.get(`/repos/${owner}/${repo}/git/trees/${defaultBranch}`, {
+            params: { recursive: 1 },
+        });
+        return (res.data?.tree || []).map((item) => ({
+            path: item.path,
+            type: item.type,
+            size: item.size,
+        }));
+    });
+}
+export async function fetchFile(owner, repo, filePath) {
+    return requestWithRetry(async () => {
+        const res = await github.get(`/repos/${owner}/${repo}/contents/${filePath}`, {
+            headers: {
+                ...getGithubHeaders(),
+                Accept: "application/vnd.github.v3.raw",
+            },
+        });
+        return res.data;
+    });
+}

package/dist/prompt.d.ts

@@ -1 +1 @@
-export declare function buildPrompt(repoName: string, description: string | null, readme: string | null, detailed?: boolean): string;
+export declare function buildPrompt(repoName: string, description: string | null, readme: string | null, detailed?: boolean, quick?: boolean, treeText?: string | null, filesText?: string | null): string;

package/dist/prompt.js

@@ -1,4 +1,28 @@
-export function buildPrompt(repoName, description, readme, detailed = false) {
+export function buildPrompt(repoName, description, readme, detailed = false, quick = false, treeText = null, filesText = null) {
+    if (quick) {
+        const readmeSnippet = (readme || "").slice(0, 2000);
+        return `
+You are a senior software engineer.
+
+Write a ONE-SENTENCE plain-English definition of what this GitHub repository is.
+
+Repository:
+- Name: ${repoName}
+- Description: ${description || "No description provided"}
+
+README snippet:
+${readmeSnippet || "No README provided"}
+
+Rules:
+- Output MUST be exactly 1 sentence.
+- Plain English.
+- No markdown.
+- No quotes.
+- No bullet points.
+- No extra text.
+- Do not add features not stated in the description/README.
+`.trim();
+    }
     let prompt = `
 You are a senior software engineer.
 
@@ -11,6 +35,12 @@ Repository:
 README content:
 ${readme || "No README provided"}
 
+Repository structure:
+${treeText || "No tree rovided"}
+
+Key files (snippets):
+${filesText || "No code files provided"}
+
 Instructions:
 - Explain what this project does.
 - Say who it is for.

package/dist/repo_reader.d.ts

@@ -0,0 +1,6 @@
+export type RepoReadResult = {
+    treeText: string;
+    filesText: string;
+    selectedFiles: string[];
+};
+export declare function readRepoSignalFiles(owner: string, repo: string): Promise<RepoReadResult>;

package/dist/repo_reader.js

@@ -0,0 +1,121 @@
+import { fetchTree, fetchFile } from "./github.js";
+const MAX_FILES = 20;
+const MAX_TOTAL_BYTES = 150_000;
+const MAX_FILE_CHARS = 6000;
+function isSkippablePath(p) {
+    const s = p.toLowerCase();
+    return (s.includes("node_modules/") ||
+        s.startsWith("node_modules/") ||
+        s.includes("dist/") ||
+        s.startsWith("dist/") ||
+        s.includes(".git/") ||
+        s.startsWith(".git/") ||
+        s.endsWith(".min.js") ||
+        s.endsWith(".min.css") ||
+        s.endsWith(".map") ||
+        s.endsWith(".lock") ||
+        s === "package-lock.json" ||
+        s === "pnpm-lock.yaml" ||
+        s === "bun.lockb" ||
+        s === "yarn.lock");
+}
+function scoreSignalFile(p) {
+    const s = p.toLowerCase();
+    if (s === "package.json")
+        return 100;
+    if (s === "pyproject.toml" || s === "requirements.txt")
+        return 90;
+    if (s === "go.mod" || s === "cargo.toml" || s === "pom.xml" || s === "build.gradle")
+        return 85;
+    if (s === "tsconfig.json")
+        return 75;
+    if (s === "next.config.js" || s === "next.config.mjs" || s === "vite.config.ts" || s === "vite.config.js")
+        return 70;
+    if (s === "svelte.config.js" || s === "nuxt.config.ts" || s === "nuxt.config.js")
+        return 70;
+    if (s === "dockerfile" || s.endsWith("dockerfile"))
+        return 65;
+    if (s === "docker-compose.yml" || s === "compose.yml")
+        return 60;
+    if (s === "vercel.json" || s === "netlify.toml")
+        return 55;
+    if (s.endsWith("/main.ts") || s.endsWith("/main.js") || s.endsWith("/index.ts") || s.endsWith("/index.js"))
+        return 60;
+    if (s.endsWith("/app.ts") || s.endsWith("/app.js") || s.endsWith("/server.ts") || s.endsWith("/server.js"))
+        return 58;
+    if (s.endsWith("/cli.ts") || s.endsWith("/cli.js"))
+        return 57;
+    if (s.endsWith("main.py") || s.endsWith("__main__.py"))
+        return 55;
+    if (s.startsWith("apps/") || s.startsWith("packages/"))
+        return 50;
+    if (s.endsWith(".ts") || s.endsWith(".js") || s.endsWith(".py") || s.endsWith(".go") || s.endsWith(".rs"))
+        return 15;
+    return 0;
+}
+function buildTreeSummary(tree) {
+    const lines = [];
+    const top = new Set();
+    const second = new Set();
+    for (const item of tree) {
+        const parts = item.path.split("/");
+        if (parts.length >= 1)
+            top.add(parts[0]);
+        if (parts.length >= 2)
+            second.add(`${parts[0]}/${parts[1]}`);
+    }
+    lines.push("Top-level:");
+    lines.push(Array.from(top).sort().join("  "));
+    lines.push("\nSecond-level:");
+    lines.push(Array.from(second).sort().slice(0, 60).join("\n"));
+    return lines.join("\n");
+}
+export async function readRepoSignalFiles(owner, repo) {
+    const tree = await fetchTree(owner, repo);
+    const blobs = tree
+        .filter((x) => x.type === "blob")
+        .map((x) => ({ path: x.path, type: "blob", size: x.size }));
+    const scored = blobs
+        .filter((x) => !isSkippablePath(x.path))
+        .map((x) => ({
+        path: x.path,
+        size: x.size ?? 0,
+        score: scoreSignalFile(x.path),
+    }))
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score);
+    const selected = [];
+    let totalBytes = 0;
+    for (const f of scored) {
+        if (selected.length >= MAX_FILES)
+            break;
+        if (f.size > 0 && f.size > 200_000)
+            continue;
+        if (totalBytes + (f.size || 2000) > MAX_TOTAL_BYTES)
+            continue;
+        selected.push(f.path);
+        totalBytes += f.size || 2000;
+    }
+    const treeText = buildTreeSummary(tree);
+    const fileBlocks = [];
+    for (const filePath of selected) {
+        try {
+            const content = await fetchFile(owner, repo, filePath);
+            const trimmed = (content || "").slice(0, MAX_FILE_CHARS);
+            fileBlocks.push([
+                `FILE: ${filePath}`,
+                "```",
+                trimmed,
+                "```",
+                "",
+            ].join("\n"));
+        }
+        catch {
+        }
+    }
+    return {
+        treeText,
+        filesText: fileBlocks.join("\n"),
+        selectedFiles: selected,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "explainthisrepo",
-  "version": "0.1.1",
-  "description": "CLI tool to explain a GitHub repository in plain English",
+  "version": "0.1.3",
+  "description": "ExplainThisRepo is a CLI developer tool to explain any GitHub repository in plain English",
   "license": "MIT",
   "type": "module",
   "author": "Caleb Wodi <calebwodi33@gmail.com>",
@@ -20,6 +20,10 @@
     "explain",
     "repository",
     "ai",
+    "repo-analysis",
+    "code-explanater",
+    "documentation",
+    "developer-productivity",
     "developer-tools"
   ],
   "bin": {