explainthisrepo 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# ExplainThisRepo
+
+This folder contains a high-performance, lightweight port of the ExplainThisRepo CLI tool.
+While the original Python implementation is the primary version of this tool, this Node.js port was created to provide a "zero-compilation" experience for users where Python C-extensions (like Pillow) can be difficult to build.
+
+## Features
+- **Automated Repository Analysis**: Seamlessly fetches repository data and documentation via the GitHub REST API.
+- **AI-Driven Contextualization**: Uses Google Gemini 2.5 Flash Lite to extract technical value and purpose from codebases.
+- **Senior Engineer Perspective**: Generates explanations tailored for developers, focusing on architecture, target audience, and execution.
+- **Markdown Generation**: Automatically outputs a clean, structured `EXPLAIN.md` file for immediate reading.
+- **TypeScript Core**: Built with type safety and modern asynchronous patterns for reliable performance.
+
+## Installation
+
+Follow these steps to set up the project locally on your machine:
+
+1. **Clone the Repository**
+   ```bash
+   git clone https://github.com/Spectra010s/ExplainThisRepo.git
+   cd ExplainThisRepo/node_version
+   ```
+
+2. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Set Up Environment Variables**
+   Create a `.env` file in the root directory or export the variable directly in your terminal:
+   ```bash
+   export GEMINI_API_KEY=your_actual_api_key_here
+   ```
+
+4. **Build the Project**
+   Compile the TypeScript source code into executable JavaScript:
+   ```bash
+   npm run build
+   ```
+5  **Link the command globally:**
+```bash
+   npm link
+   ```
+
+
+## Usage
+
+Once the project is built, you can use the CLI tool to analyze any public GitHub repository.
+
+### Running the CLI
+Execute the tool by passing the `owner/repo` string as an argument:
+
+```bash
+node dist/cli.js facebook/react
+```
+
+### Expected Workflow
+1. The tool fetches the repository description and README from GitHub.
+2. It processes the information and sends a structured prompt to the Gemini AI.
+3. An `EXPLAIN.md` file is generated in your current working directory containing:
+   - Project Overview
+   - Functional Breakdown
+   - Target User Identification
+   - Setup/Execution Instructions
+
+### Scripts
+- `npm run build`: Compiles TypeScript to the `dist` folder.
+- `npm run format`: Formats the codebase using Prettier.
+- `npm start`: Runs the tool (requires the repository argument).
+
+## Contributing
+
+Contributions are what make the open-source community an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
+
+-️ **Report Bugs**: Open an issue if you find any unexpected behavior.
+- **Feature Requests**: Proposals for new features are always welcome.
+- **Pull Requests**: Ensure your code follows the existing style and all linting passes.
+
+> Note: Please run npm run format before submitting a Pull Request to ensure code consistency.
+
+## License
+This project is licensed under the MIT License as specified in the package configuration.
+
+## Author Info
+
+**Spectra010s**
+- [Portfolio](https://spectra010s.vercel.app)
+- [Twitter/X](https://x.com/Spectra010s)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import os from "node:os";
+import process from "node:process";
+import { fetchRepo, fetchReadme } from "./github.js";
+import { buildPrompt } from "./prompt.js";
+import { generateExplanation } from "./generate.js";
+import { writeOutput } from "./writer.js";
+function usage() {
+    console.log("usage:");
+    console.log("  explainthisrepo owner/repo");
+    console.log("  explainthisrepo owner/repo --detailed");
+    console.log("  explainthisrepo --doctor");
+    console.log("  explainthisrepo --version");
+}
+function getPkgVersion() {
+    return process.env.npm_package_version || "unknown";
+}
+function printVersion() {
+    console.log(getPkgVersion());
+}
+function hasEnv(key) {
+    const v = process.env[key];
+    return Boolean(v && v.trim());
+}
+async function checkUrl(url, timeoutMs = 6000) {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "User-Agent": "explainthisrepo" },
+            signal: controller.signal,
+        });
+        clearTimeout(t);
+        return { ok: res.ok, msg: `ok (${res.status})` };
+    }
+    catch (e) {
+        clearTimeout(t);
+        return { ok: false, msg: `failed (${e?.name || "Error"}: ${e?.message || e})` };
+    }
+}
+async function runDoctor() {
+    console.log("explainthisrepo doctor report\n");
+    console.log(`node: ${process.version}`);
+    console.log(`os: ${os.type()} ${os.release()}`);
+    console.log(`platform: ${process.platform} ${process.arch}`);
+    console.log(`version: ${getPkgVersion()}`);
+    console.log("\nenvironment:");
+    console.log(`- GEMINI_API_KEY set: ${hasEnv("GEMINI_API_KEY")}`);
+    console.log(`- GITHUB_TOKEN set: ${hasEnv("GITHUB_TOKEN")}`);
+    console.log("\nnetwork checks:");
+    const gh = await checkUrl("https://api.github.com");
+    console.log(`- github api: ${gh.msg}`);
+    const gem = await checkUrl("https://generativelanguage.googleapis.com");
+    console.log(`- gemini endpoint: ${gem.msg}`);
+    return gh.ok ? 0 : 1;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "-h" || args[0] === "--help") {
+        usage();
+        process.exit(0);
+    }
+    if (args[0] === "--version") {
+        printVersion();
+        process.exit(0);
+    }
+    if (args[0] === "--doctor") {
+        const code = await runDoctor();
+        process.exit(code);
+    }
+    let detailed = false;
+    if (args.length === 2) {
+        if (args[1] !== "--detailed") {
+            usage();
+            process.exit(1);
+        }
+        detailed = true;
+    }
+    else if (args.length !== 1) {
+        usage();
+        process.exit(1);
+    }
+    const target = args[0];
+    if (!target.includes("/") || target.split("/").length !== 2) {
+        console.log("Invalid format. Use owner/repo");
+        process.exit(1);
+    }
+    const [owner, repo] = target.split("/");
+    if (!owner || !repo) {
+        console.log("Invalid format. Use owner/repo");
+        process.exit(1);
+    }
+    console.log(`Fetching ${owner}/${repo}...`);
+    try {
+        const repoData = await fetchRepo(owner, repo);
+        const readme = await fetchReadme(owner, repo);
+        const prompt = buildPrompt(repoData.full_name, repoData.description, readme, detailed);
+        console.log("Generating explanation...");
+        const output = await generateExplanation(prompt);
+        console.log("Writing EXPLAIN.md...");
+        writeOutput(output);
+        const wordCount = output.split(/\s+/).filter(Boolean).length;
+        console.log("EXPLAIN.md generated successfully 🎉");
+        console.log(`Words: ${wordCount}`);
+        console.log("Open EXPLAIN.md to read it.");
+    }
+    catch (e) {
+        console.log("Failed to generate explanation.");
+        console.log(`error: ${e?.message || e}`);
+        console.log("\nfix:");
+        console.log("- Ensure GEMINI_API_KEY is set");
+        console.log("- Or run: explainthisrepo --doctor");
+        process.exit(1);
+    }
+}
+main();

package/dist/generate.d.ts

@@ -0,0 +1 @@
+export declare function generateExplanation(prompt: string): Promise<string>;

package/dist/generate.js

@@ -0,0 +1,36 @@
+import { GoogleGenerativeAI } from "@google/generative-ai";
+const DEFAULT_MODEL = "gemini-2.5-flash-lite";
+function getApiKey() {
+    const key = process.env.GEMINI_API_KEY;
+    if (!key || !key.trim()) {
+        throw new Error([
+            "GEMINI_API_KEY is not set.",
+            "",
+            "Fix:",
+            '  export GEMINI_API_KEY="your_key_here"',
+        ].join("\n"));
+    }
+    return key.trim();
+}
+export async function generateExplanation(prompt) {
+    const apiKey = getApiKey();
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const modelName = (process.env.GEMINI_MODEL || DEFAULT_MODEL).trim();
+    const model = genAI.getGenerativeModel({ model: modelName });
+    try {
+        const result = await model.generateContent(prompt);
+        const text = result?.response?.text?.() ?? "";
+        if (!text.trim()) {
+            throw new Error("Gemini returned no text");
+        }
+        return text.trim();
+    }
+    catch (err) {
+        const msg = err?.message ? String(err.message) : String(err);
+        throw new Error([
+            "Failed to generate explanation (Gemini).",
+            `Model: ${modelName}`,
+            `Error: ${msg}`,
+        ].join("\n"));
+    }
+}

package/dist/github.d.ts

@@ -0,0 +1,2 @@
+export declare function fetchRepo(owner: string, repo: string): Promise<any>;
+export declare function fetchReadme(owner: string, repo: string): Promise<string | null>;

package/dist/github.js

@@ -0,0 +1,97 @@
+import axios from "axios";
+const GITHUB_API_BASE = "https://api.github.com";
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getGithubHeaders() {
+    const headers = {
+        Accept: "application/vnd.github.v3+json",
+        "User-Agent": "ExplainThisRepo",
+    };
+    const token = process.env.GITHUB_TOKEN || process.env.GITHUB_API_KEY;
+    if (token && token.trim()) {
+        headers.Authorization = `Bearer ${token.trim()}`;
+    }
+    return headers;
+}
+const github = axios.create({
+    baseURL: GITHUB_API_BASE,
+    headers: getGithubHeaders(),
+    timeout: 12000,
+});
+function formatAxiosError(err) {
+    if (!axios.isAxiosError(err))
+        return "Unknown error";
+    const status = err.response?.status;
+    const data = err.response?.data;
+    const msg = data?.message || err.message;
+    if (status === 404)
+        return "Repository not found (404). Check owner/repo.";
+    if (status === 401)
+        return "GitHub auth failed (401). Invalid GITHUB_TOKEN.";
+    if (status === 403 && typeof msg === "string" && msg.toLowerCase().includes("rate limit")) {
+        return "GitHub rate limit hit (403). Set GITHUB_TOKEN to increase limits.";
+    }
+    if (status === 429)
+        return "GitHub rate limit hit (429). Try again in a minute.";
+    if (status && status >= 500)
+        return `GitHub server error (${status}). Try again later.`;
+    return `GitHub request failed (${status ?? "no status"}): ${msg}`;
+}
+async function requestWithRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? 3;
+    const baseDelayMs = opts?.baseDelayMs ?? 700;
+    let attempt = 0;
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            attempt += 1;
+            const isAxios = axios.isAxiosError(err);
+            const status = isAxios ? err.response?.status : undefined;
+            const retryable = status === 403 || status === 429 || (status !== undefined && status >= 500);
+            if (!retryable || attempt > maxRetries) {
+                throw new Error(formatAxiosError(err));
+            }
+            const resetHeader = isAxios ? err.response?.headers?.["x-ratelimit-reset"] : undefined;
+            if ((status === 403 || status === 429) && resetHeader) {
+                const resetSeconds = Number(resetHeader);
+                if (!Number.isNaN(resetSeconds)) {
+                    const waitMs = Math.max(resetSeconds * 1000 - Date.now(), 1000);
+                    await sleep(Math.min(waitMs, 30_000));
+                    continue;
+                }
+            }
+            const delay = baseDelayMs * Math.pow(2, attempt - 1);
+            await sleep(Math.min(delay, 8000));
+        }
+    }
+}
+export async function fetchRepo(owner, repo) {
+    return requestWithRetry(async () => {
+        const res = await github.get(`/repos/${owner}/${repo}`);
+        return res.data;
+    });
+}
+export async function fetchReadme(owner, repo) {
+    try {
+        return await requestWithRetry(async () => {
+            const res = await github.get(`/repos/${owner}/${repo}/readme`, {
+                headers: {
+                    ...getGithubHeaders(),
+                    Accept: "application/vnd.github.v3.raw",
+                },
+            });
+            return res.data;
+        });
+    }
+    catch (err) {
+        if (axios.isAxiosError(err)) {
+            const status = err.response?.status;
+            if (status === 404)
+                return null;
+        }
+        throw err;
+    }
+}

package/dist/prompt.d.ts

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

package/dist/prompt.js

@@ -0,0 +1,43 @@
+export function buildPrompt(repoName, description, readme, detailed = false) {
+    let prompt = `
+You are a senior software engineer.
+
+Your task is to explain a GitHub repository clearly and concisely for a human reader.
+
+Repository:
+- Name: ${repoName}
+- Description: ${description || "No description provided"}
+
+README content:
+${readme || "No README provided"}
+
+Instructions:
+- Explain what this project does.
+- Say who it is for.
+- Explain how to run or use it.
+- Do not assume missing details.
+- If something is unclear, say so.
+- Avoid hype or marketing language.
+- Be concise and practical.
+- Use clear markdown headings.
+`.trim();
+    if (detailed) {
+        prompt += `
+
+Additional instructions:
+- Explain the high-level architecture.
+- Describe the folder structure.
+- Mention important files and their roles.
+`;
+    }
+    prompt += `
+
+Output format:
+# Overview
+# What this project does
+# Who it is for
+# How to run or use it
+# Notes or limitations
+`;
+    return prompt.trim();
+}

package/dist/writer.d.ts

@@ -0,0 +1 @@
+export declare function writeOutput(content: string): void;

package/dist/writer.js

@@ -0,0 +1,6 @@
+import fs from "fs";
+import path from "path";
+export function writeOutput(content) {
+    const outputPath = path.join(process.cwd(), "EXPLAIN.md");
+    fs.writeFileSync(outputPath, content, "utf8");
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "explainthisrepo",
+  "version": "0.1.0",
+  "description": "CLI tool to explain a GitHub repository in plain English",
+  "license": "MIT",
+  "type": "module",
+  "author": "Caleb Wodi <calebwodi33@gmail.com>",
+  "homepage": "https://explainthisrepo.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calchiwo/ExplainThisRepo.git",
+    "directory": "node_version"
+  },
+  "bugs": {
+    "url": "https://github.com/calchiwo/ExplainThisRepo/issues"
+  },
+  "keywords": [
+    "github",
+    "cli",
+    "explain",
+    "repository",
+    "ai",
+    "developer-tools"
+  ],
+  "bin": {
+    "explainthisrepo": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@google/generative-ai": "^0.24.1",
+    "axios": "^1.13.2",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}