explainthisrepo 0.1.3 → 0.1.5

package/dist/cli.js

@@ -5,15 +5,19 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { fetchRepo, fetchReadme } from "./github.js";
-import { buildPrompt } from "./prompt.js";
+import { buildPrompt, buildSimplePrompt } from "./prompt.js";
 import { generateExplanation } from "./generate.js";
 import { writeOutput } from "./writer.js";
 import { readRepoSignalFiles } from "./repo_reader.js";
+import { fetchLanguages } from "./github.js";
+import { detectStack } from "./stack-detector.js";
+import { printStack } from "./stack_printer.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 owner/repo --simple");
     console.log("  explainthisrepo --doctor");
     console.log("  explainthisrepo --version");
 }
@@ -88,11 +92,17 @@ async function main() {
     }
     let detailed = false;
     let quick = false;
+    let simple = false;
+    let stack = false;
     if (args.length === 2) {
         if (args[1] === "--detailed")
             detailed = true;
         else if (args[1] === "--quick")
             quick = true;
+        else if (args[1] === "--simple")
+            simple = true;
+        else if (args[1] === "--stack")
+            stack = true;
         else {
             usage();
             process.exit(1);
@@ -102,6 +112,13 @@ async function main() {
         usage();
         process.exit(1);
     }
+    if ((quick && simple) ||
+        (detailed && simple) ||
+        (detailed && quick) ||
+        (stack && (quick || simple || detailed))) {
+        usage();
+        process.exit(1);
+    }
     const target = args[0];
     if (!target.includes("/") || target.split("/").length !== 2) {
         console.log("Invalid format. Use owner/repo");
@@ -113,6 +130,17 @@ async function main() {
         process.exit(1);
     }
     console.log(`Fetching ${owner}/${repo}...`);
+    if (stack) {
+        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;
+    }
     try {
         const repoData = await fetchRepo(owner, repo);
         const readme = await fetchReadme(owner, repo);
@@ -125,6 +153,14 @@ async function main() {
             console.log(output.trim());
             return;
         }
+        if (simple) {
+            console.log("Summarizing...");
+            const simplePrompt = buildSimplePrompt(output);
+            const simpleOutput = await generateExplanation(simplePrompt);
+            console.log("Simple summary 🎉");
+            console.log(simpleOutput.trim());
+            return;
+        }
         console.log("Writing EXPLAIN.md...");
         writeOutput(output);
         const wordCount = output.split(/\s+/).filter(Boolean).length;

package/dist/github.d.ts

@@ -2,3 +2,5 @@ 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>;
+export type RepoLanguageMap = Record<string, number>;
+export declare function fetchLanguages(owner: string, repo: string): Promise<RepoLanguageMap>;

package/dist/github.js

@@ -120,3 +120,9 @@ export async function fetchFile(owner, repo, filePath) {
         return res.data;
     });
 }
+export async function fetchLanguages(owner, repo) {
+    return requestWithRetry(async () => {
+        const res = await github.get(`/repos/${owner}/${repo}/languages`);
+        return res.data;
+    });
+}

package/dist/prompt.d.ts

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

package/dist/prompt.js

@@ -36,7 +36,7 @@ README content:
 ${readme || "No README provided"}
 
 Repository structure:
-${treeText || "No tree rovided"}
+${treeText || "No tree provided"}
 
 Key files (snippets):
 ${filesText || "No code files provided"}
@@ -71,3 +71,32 @@ Output format:
 `;
     return prompt.trim();
 }
+export function buildSimplePrompt(longExplanation) {
+    return `
+You are a senior software engineer.
+
+Rewrite the long repository explanation below into a SIMPLE version in the exact style specified.
+
+Input explanation:
+${longExplanation}
+
+Output style rules:
+- Plain English.
+- No markdown.
+- Do NOT use headings like "Overview", "What this project does", etc.
+- Start with exactly this line:
+Key points from the repo:
+- Then output 4 to 7 bullets only.
+- Each bullet MUST start with: ⬤
+- Each bullet title should be 1–3 words only (example: "Purpose", "Stack", "Entrypoints", "How it works", "Usage", "Structure").
+- Each bullet body should be 1–2 lines max.
+- If the input contains architecture/pipeline steps, capture them naturally.
+- If the input does NOT contain architecture/pipeline steps, do NOT invent them.
+- Optional: end with one extra line starting with:
+Also interesting:
+- Do NOT add features not present in the input.
+- No quotes.
+
+Make it feel like a human developer explaining to another developer in simple terms.
+`.trim();
+}

package/dist/repo_reader.d.ts

@@ -1,6 +1,14 @@
+type TreeItem = {
+    path: string;
+    type: "blob" | "tree";
+    size?: number;
+};
 export type RepoReadResult = {
+    tree: TreeItem[];
     treeText: string;
     filesText: string;
     selectedFiles: string[];
+    keyFiles: Record<string, string>;
 };
 export declare function readRepoSignalFiles(owner: string, repo: string): Promise<RepoReadResult>;
+export {};

package/dist/repo_reader.js

@@ -113,9 +113,36 @@ export async function readRepoSignalFiles(owner, repo) {
         catch {
         }
     }
+    const keyFiles = {};
+    const STACK_KEY_FILES = [
+        "package.json",
+        "pyproject.toml",
+        "requirements.txt",
+        "go.mod",
+        "Cargo.toml",
+        "composer.json",
+        "pom.xml",
+        "build.gradle",
+        "Dockerfile",
+        "docker-compose.yml",
+        "vercel.json",
+        "netlify.toml",
+    ];
+    for (const path of STACK_KEY_FILES) {
+        const match = tree.find(t => t.path.toLowerCase() === path.toLowerCase());
+        if (!match)
+            continue;
+        try {
+            const content = await fetchFile(owner, repo, path);
+            keyFiles[path] = content.slice(0, 20000);
+        }
+        catch { }
+    }
     return {
+        tree,
         treeText,
         filesText: fileBlocks.join("\n"),
         selectedFiles: selected,
+        keyFiles,
     };
 }

package/dist/stack-detector.d.ts

@@ -0,0 +1,23 @@
+import type { RepoLanguageMap } from "./github.js";
+type TreeItem = {
+    path: string;
+    type: string;
+    size?: number;
+};
+type StackInput = {
+    languages: RepoLanguageMap;
+    tree: TreeItem[];
+    keyFiles: Record<string, string>;
+};
+export type StackReport = {
+    languages: string[];
+    runtimes: string[];
+    frontend: string[];
+    backend: string[];
+    databases: string[];
+    tooling: string[];
+    infra: string[];
+    packageManagers: string[];
+};
+export declare function detectStack(input: StackInput): StackReport;
+export {};

package/dist/stack-detector.js

@@ -0,0 +1,54 @@
+export function detectStack(input) {
+    const report = {
+        languages: [],
+        runtimes: [],
+        frontend: [],
+        backend: [],
+        databases: [],
+        tooling: [],
+        infra: [],
+        packageManagers: [],
+    };
+    const total = Object.values(input.languages).reduce((a, b) => a + b, 0);
+    report.languages = Object.entries(input.languages)
+        .filter(([_, bytes]) => bytes / total > 0.03)
+        .map(([lang]) => lang);
+    const paths = input.tree.map(t => t.path.toLowerCase());
+    if (paths.includes("dockerfile"))
+        report.infra.push("Docker");
+    if (paths.includes("vercel.json"))
+        report.infra.push("Vercel");
+    if (paths.includes("netlify.toml"))
+        report.infra.push("Netlify");
+    if (paths.some(p => p.startsWith(".github/workflows")))
+        report.infra.push("GitHub Actions");
+    const pkgRaw = input.keyFiles["package.json"];
+    if (pkgRaw) {
+        report.runtimes.push("Node.js");
+        report.packageManagers.push("npm");
+        try {
+            const pkg = JSON.parse(pkgRaw);
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps.react)
+                report.frontend.push("React");
+            if (deps.next)
+                report.frontend.push("Next.js");
+            if (deps.express)
+                report.backend.push("Express");
+            if (deps.fastify)
+                report.backend.push("Fastify");
+            if (deps.prisma)
+                report.databases.push("Prisma");
+            if (deps.mongoose)
+                report.databases.push("MongoDB");
+            if (deps.jest)
+                report.tooling.push("Jest");
+            if (deps.vite)
+                report.tooling.push("Vite");
+            if (deps.eslint)
+                report.tooling.push("ESLint");
+        }
+        catch { }
+    }
+    return report;
+}

package/dist/stack_printer.d.ts

@@ -0,0 +1,2 @@
+import type { StackReport } from "./stack-detector.js";
+export declare function printStack(report: StackReport, owner: string, repo: string): void;

package/dist/stack_printer.js

@@ -0,0 +1,20 @@
+function section(title, items) {
+    if (!items || items.length === 0)
+        return;
+    console.log(`\n${title}:`);
+    for (const item of items) {
+        console.log(`- ${item}`);
+    }
+}
+export function printStack(report, owner, repo) {
+    console.log(`\nStack summary for ${owner}/${repo}`);
+    section("Languages", report.languages);
+    section("Runtime", report.runtimes);
+    section("Frontend", report.frontend);
+    section("Backend", report.backend);
+    section("Databases / ORM", report.databases);
+    section("Tooling", report.tooling);
+    section("Infrastructure / Deploy", report.infra);
+    section("Package Managers", report.packageManagers);
+    console.log("");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explainthisrepo",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "ExplainThisRepo is a CLI developer tool to explain any GitHub repository in plain English",
   "license": "MIT",
   "type": "module",