@hawon/nexus 0.3.0 → 0.3.1

package/dist/cli/index.d.ts

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

package/{src/codebase/index.ts → dist/codebase/index.d.ts}

@@ -1,8 +1,3 @@
 export { mapCodebase } from "./mapper.js";
 export { generateOnboardingGuide } from "./onboard.js";
-export type {
-  FileNode,
-  DependencyEdge,
-  CodebaseMap,
-  MapOptions,
-} from "./types.js";
+export type { FileNode, DependencyEdge, CodebaseMap, MapOptions, } from "./types.js";

package/dist/codebase/index.js

@@ -0,0 +1,2 @@
+export { mapCodebase } from "./mapper.js";
+export { generateOnboardingGuide } from "./onboard.js";

package/dist/codebase/mapper.d.ts

@@ -0,0 +1,2 @@
+import type { CodebaseMap, MapOptions } from "./types.js";
+export declare function mapCodebase(options: MapOptions): Promise<CodebaseMap>;

package/dist/codebase/mapper.js

@@ -0,0 +1,446 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, extname, resolve } from "node:path";
+const DEFAULT_IGNORE = [
+    "node_modules",
+    ".git",
+    "dist",
+    "build",
+    "__pycache__",
+    ".next",
+    ".nuxt",
+    "coverage",
+    ".cache",
+    ".venv",
+    "venv",
+    "target",
+];
+const LANGUAGE_MAP = {
+    ".ts": "TypeScript",
+    ".tsx": "TypeScript",
+    ".js": "JavaScript",
+    ".jsx": "JavaScript",
+    ".mjs": "JavaScript",
+    ".cjs": "JavaScript",
+    ".py": "Python",
+    ".go": "Go",
+    ".rs": "Rust",
+    ".java": "Java",
+    ".kt": "Kotlin",
+    ".rb": "Ruby",
+    ".php": "PHP",
+    ".c": "C",
+    ".cpp": "C++",
+    ".cc": "C++",
+    ".h": "C",
+    ".hpp": "C++",
+    ".cs": "C#",
+    ".swift": "Swift",
+    ".scala": "Scala",
+    ".lua": "Lua",
+    ".sh": "Shell",
+    ".bash": "Shell",
+    ".zsh": "Shell",
+    ".json": "JSON",
+    ".yaml": "YAML",
+    ".yml": "YAML",
+    ".toml": "TOML",
+    ".xml": "XML",
+    ".html": "HTML",
+    ".css": "CSS",
+    ".scss": "SCSS",
+    ".sql": "SQL",
+    ".md": "Markdown",
+    ".vue": "Vue",
+    ".svelte": "Svelte",
+};
+function detectLanguage(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    return LANGUAGE_MAP[ext];
+}
+function extractImports(content, language) {
+    return extractImportsWithType(content, language).map((e) => e.path);
+}
+function extractImportsWithType(content, language) {
+    const imports = [];
+    if (!language)
+        return imports;
+    switch (language) {
+        case "TypeScript":
+        case "JavaScript": {
+            // import ... from "..."
+            const esImports = content.matchAll(/import\s+.*?\s+from\s+["']([^"']+)["']/g);
+            for (const m of esImports)
+                imports.push({ path: m[1], type: "import" });
+            // import "..."
+            const sideEffects = content.matchAll(/import\s+["']([^"']+)["']/g);
+            for (const m of sideEffects)
+                imports.push({ path: m[1], type: "import" });
+            // require("...")
+            const requires = content.matchAll(/require\s*\(\s*["']([^"']+)["']\s*\)/g);
+            for (const m of requires)
+                imports.push({ path: m[1], type: "require" });
+            // export ... from "..."
+            const reExports = content.matchAll(/export\s+.*?\s+from\s+["']([^"']+)["']/g);
+            for (const m of reExports)
+                imports.push({ path: m[1], type: "import" });
+            break;
+        }
+        case "Python": {
+            const fromImports = content.matchAll(/from\s+(\S+)\s+import/g);
+            for (const m of fromImports)
+                imports.push({ path: m[1], type: "import" });
+            const directImports = content.matchAll(/^import\s+(\S+)/gm);
+            for (const m of directImports)
+                imports.push({ path: m[1], type: "import" });
+            break;
+        }
+        case "Go": {
+            const singleImport = content.matchAll(/import\s+"([^"]+)"/g);
+            for (const m of singleImport)
+                imports.push({ path: m[1], type: "import" });
+            const blockImport = content.matchAll(/import\s*\(([\s\S]*?)\)/g);
+            for (const m of blockImport) {
+                const pkgs = m[1].matchAll(/"([^"]+)"/g);
+                for (const p of pkgs)
+                    imports.push({ path: p[1], type: "import" });
+            }
+            break;
+        }
+        case "Rust": {
+            const useStmts = content.matchAll(/use\s+([^;]+);/g);
+            for (const m of useStmts)
+                imports.push({ path: m[1].trim(), type: "import" });
+            break;
+        }
+        case "Java":
+        case "Kotlin": {
+            const javaImports = content.matchAll(/import\s+(?:static\s+)?([^;]+);/g);
+            for (const m of javaImports)
+                imports.push({ path: m[1].trim(), type: "import" });
+            break;
+        }
+    }
+    return imports;
+}
+function extractExports(content, language) {
+    const exports = [];
+    if (!language)
+        return exports;
+    switch (language) {
+        case "TypeScript":
+        case "JavaScript": {
+            // export function/const/class/type/interface/enum NAME
+            const namedExports = content.matchAll(/export\s+(?:default\s+)?(?:function|const|let|var|class|type|interface|enum|abstract\s+class)\s+(\w+)/g);
+            for (const m of namedExports)
+                exports.push(m[1]);
+            // export { ... }
+            const braceExports = content.matchAll(/export\s*\{([^}]+)\}/g);
+            for (const m of braceExports) {
+                const names = m[1].split(",").map((s) => s.trim().split(/\s+as\s+/).pop().trim());
+                exports.push(...names.filter(Boolean));
+            }
+            // export default
+            if (/export\s+default\s/.test(content) && !exports.includes("default")) {
+                exports.push("default");
+            }
+            // module.exports
+            if (/module\.exports\s*=/.test(content)) {
+                exports.push("module.exports");
+            }
+            break;
+        }
+        case "Python": {
+            // __all__ = [...]
+            const allMatch = content.match(/__all__\s*=\s*\[([^\]]+)\]/);
+            if (allMatch) {
+                const names = allMatch[1].matchAll(/["'](\w+)["']/g);
+                for (const n of names)
+                    exports.push(n[1]);
+            }
+            break;
+        }
+        case "Rust": {
+            const pubItems = content.matchAll(/pub\s+(?:fn|struct|enum|trait|type|const|static|mod)\s+(\w+)/g);
+            for (const m of pubItems)
+                exports.push(m[1]);
+            break;
+        }
+        case "Go": {
+            // Exported identifiers start with uppercase
+            const funcs = content.matchAll(/func\s+(?:\([^)]*\)\s+)?([A-Z]\w*)\s*\(/g);
+            for (const m of funcs)
+                exports.push(m[1]);
+            const types = content.matchAll(/type\s+([A-Z]\w*)\s+/g);
+            for (const m of types)
+                exports.push(m[1]);
+            break;
+        }
+    }
+    return exports;
+}
+function extractFunctions(content, language) {
+    const functions = [];
+    if (!language)
+        return functions;
+    switch (language) {
+        case "TypeScript":
+        case "JavaScript": {
+            // function name(
+            const funcDecls = content.matchAll(/function\s+(\w+)\s*\(/g);
+            for (const m of funcDecls)
+                functions.push(m[1]);
+            // const/let/var name = ( | => | function
+            const arrowFuncs = content.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?(?:\([^)]*\)|[^=])\s*=>/g);
+            for (const m of arrowFuncs)
+                functions.push(m[1]);
+            // const name = function
+            const funcExprs = content.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?function/g);
+            for (const m of funcExprs)
+                functions.push(m[1]);
+            // method definitions in classes: name(
+            const methods = content.matchAll(/^\s+(?:async\s+)?(\w+)\s*\([^)]*\)\s*(?::\s*\w+)?\s*\{/gm);
+            for (const m of methods) {
+                if (!["if", "for", "while", "switch", "catch", "constructor"].includes(m[1])) {
+                    functions.push(m[1]);
+                }
+            }
+            break;
+        }
+        case "Python": {
+            const defs = content.matchAll(/def\s+(\w+)\s*\(/g);
+            for (const m of defs)
+                functions.push(m[1]);
+            break;
+        }
+        case "Go": {
+            const goFuncs = content.matchAll(/func\s+(?:\([^)]*\)\s+)?(\w+)\s*\(/g);
+            for (const m of goFuncs)
+                functions.push(m[1]);
+            break;
+        }
+        case "Rust": {
+            const rsFuncs = content.matchAll(/fn\s+(\w+)\s*[(<]/g);
+            for (const m of rsFuncs)
+                functions.push(m[1]);
+            break;
+        }
+        case "Java":
+        case "Kotlin": {
+            const javaMethods = content.matchAll(/(?:public|private|protected|static|\s)+[\w<>\[\]]+\s+(\w+)\s*\(/g);
+            for (const m of javaMethods) {
+                if (!["if", "for", "while", "switch", "catch", "class"].includes(m[1])) {
+                    functions.push(m[1]);
+                }
+            }
+            break;
+        }
+    }
+    return [...new Set(functions)];
+}
+function extractClasses(content, language) {
+    const classes = [];
+    if (!language)
+        return classes;
+    switch (language) {
+        case "TypeScript":
+        case "JavaScript":
+        case "Java":
+        case "Kotlin":
+        case "Python": {
+            const classDecls = content.matchAll(/class\s+(\w+)/g);
+            for (const m of classDecls)
+                classes.push(m[1]);
+            break;
+        }
+        case "Rust": {
+            const structs = content.matchAll(/(?:struct|enum|trait)\s+(\w+)/g);
+            for (const m of structs)
+                classes.push(m[1]);
+            break;
+        }
+        case "Go": {
+            const goTypes = content.matchAll(/type\s+(\w+)\s+struct/g);
+            for (const m of goTypes)
+                classes.push(m[1]);
+            break;
+        }
+        case "C++":
+        case "C#": {
+            const cppClasses = content.matchAll(/(?:class|struct)\s+(\w+)/g);
+            for (const m of cppClasses)
+                classes.push(m[1]);
+            break;
+        }
+    }
+    return [...new Set(classes)];
+}
+async function walkDirectory(dir, rootDir, ignoreSet, maxFiles, maxDepth, currentDepth, files) {
+    if (currentDepth > maxDepth || files.length >= maxFiles)
+        return;
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (files.length >= maxFiles)
+            break;
+        if (ignoreSet.has(entry.name))
+            continue;
+        if (entry.name.startsWith(".") && entry.name !== ".")
+            continue;
+        const fullPath = join(dir, entry.name);
+        const relPath = relative(rootDir, fullPath);
+        if (entry.isDirectory()) {
+            await walkDirectory(fullPath, rootDir, ignoreSet, maxFiles, maxDepth, currentDepth + 1, files);
+        }
+        else if (entry.isFile()) {
+            const language = detectLanguage(entry.name);
+            let fileStat;
+            try {
+                fileStat = await stat(fullPath);
+            }
+            catch {
+                continue;
+            }
+            // Skip binary/large files
+            if (fileStat.size > 1_000_000)
+                continue;
+            let content = "";
+            let lineCount = 0;
+            let imports = [];
+            let importInfos = [];
+            let exports = [];
+            let functions = [];
+            let classes = [];
+            if (language) {
+                try {
+                    content = await readFile(fullPath, "utf-8");
+                    lineCount = content.split("\n").length;
+                    importInfos = extractImportsWithType(content, language);
+                    imports = importInfos.map((e) => e.path);
+                    exports = extractExports(content, language);
+                    functions = extractFunctions(content, language);
+                    classes = extractClasses(content, language);
+                }
+                catch {
+                    // Binary file or encoding issue
+                }
+            }
+            files.push({
+                path: relPath,
+                type: "file",
+                language,
+                size: fileStat.size,
+                imports,
+                importInfos,
+                exports,
+                functions,
+                classes,
+                lineCount,
+            });
+        }
+    }
+}
+function resolveImportPath(fromFile, importSpecifier, allFilePaths) {
+    // Skip external/node modules
+    if (!importSpecifier.startsWith(".") &&
+        !importSpecifier.startsWith("/")) {
+        return null;
+    }
+    const fromDir = fromFile.includes("/")
+        ? fromFile.substring(0, fromFile.lastIndexOf("/"))
+        : ".";
+    let resolved;
+    if (importSpecifier.startsWith("/")) {
+        resolved = importSpecifier.substring(1);
+    }
+    else {
+        // Resolve relative path
+        const parts = fromDir.split("/").filter(Boolean);
+        const importParts = importSpecifier.split("/");
+        for (const p of importParts) {
+            if (p === "..")
+                parts.pop();
+            else if (p !== ".")
+                parts.push(p);
+        }
+        resolved = parts.join("/");
+    }
+    // Try exact match first, then with extensions
+    const extensions = ["", ".ts", ".tsx", ".js", ".jsx", ".mjs", "/index.ts", "/index.tsx", "/index.js", "/index.jsx"];
+    for (const ext of extensions) {
+        const candidate = resolved + ext;
+        // Strip .js extension that TypeScript ESM uses for .ts files
+        const tsCandidate = candidate.replace(/\.js$/, ".ts");
+        if (allFilePaths.has(candidate))
+            return candidate;
+        if (allFilePaths.has(tsCandidate))
+            return tsCandidate;
+    }
+    return null;
+}
+function buildDependencyGraph(files) {
+    const edges = [];
+    const allPaths = new Set(files.map((f) => f.path));
+    for (const file of files) {
+        const infos = file.importInfos ?? file.imports.map((p) => ({ path: p, type: "import" }));
+        for (const info of infos) {
+            const resolved = resolveImportPath(file.path, info.path, allPaths);
+            if (resolved) {
+                edges.push({ from: file.path, to: resolved, type: info.type });
+            }
+        }
+    }
+    return edges;
+}
+function findEntryPoints(files, edges) {
+    const imported = new Set(edges.map((e) => e.to));
+    return files
+        .filter((f) => f.language && !imported.has(f.path))
+        .map((f) => f.path);
+}
+function findHotspots(files, edges, topN = 10) {
+    const incomingCount = new Map();
+    for (const edge of edges) {
+        incomingCount.set(edge.to, (incomingCount.get(edge.to) ?? 0) + 1);
+    }
+    return [...incomingCount.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, topN)
+        .map(([path]) => path);
+}
+export async function mapCodebase(options) {
+    const root = resolve(options.root);
+    const ignorePatterns = options.ignore ?? DEFAULT_IGNORE;
+    const ignoreSet = new Set(ignorePatterns);
+    const maxFiles = options.maxFiles ?? 10_000;
+    const maxDepth = options.maxDepth ?? 50;
+    const files = [];
+    await walkDirectory(root, root, ignoreSet, maxFiles, maxDepth, 0, files);
+    const edges = buildDependencyGraph(files);
+    // Compute language stats
+    const languages = {};
+    let totalLines = 0;
+    for (const file of files) {
+        if (file.language) {
+            languages[file.language] = (languages[file.language] ?? 0) + 1;
+        }
+        totalLines += file.lineCount;
+    }
+    const entryPoints = findEntryPoints(files, edges);
+    const hotspots = findHotspots(files, edges);
+    return {
+        root,
+        files,
+        dependencies: edges,
+        languages,
+        totalFiles: files.length,
+        totalLines,
+        entryPoints,
+        hotspots,
+        generatedAt: new Date().toISOString(),
+    };
+}

package/dist/codebase/onboard.d.ts

@@ -0,0 +1,2 @@
+import type { CodebaseMap } from "./types.js";
+export declare function generateOnboardingGuide(map: CodebaseMap): string;

package/dist/codebase/onboard.js

@@ -0,0 +1,179 @@
+function buildDirectoryTree(files, maxDepth) {
+    const tree = new Map();
+    for (const filePath of files) {
+        const parts = filePath.split("/");
+        for (let i = 0; i < parts.length && i < maxDepth; i++) {
+            const dir = parts.slice(0, i).join("/") || ".";
+            const child = parts[i];
+            if (!tree.has(dir))
+                tree.set(dir, new Set());
+            tree.get(dir).add(child);
+        }
+    }
+    function renderTree(dir, prefix, isLast, depth) {
+        if (depth > maxDepth)
+            return "";
+        const children = tree.get(dir);
+        if (!children)
+            return "";
+        const sorted = [...children].sort();
+        const lines = [];
+        for (let i = 0; i < sorted.length; i++) {
+            const child = sorted[i];
+            const last = i === sorted.length - 1;
+            const connector = last ? "└── " : "├── ";
+            const childPrefix = last ? "    " : "│   ";
+            const childPath = dir === "." ? child : `${dir}/${child}`;
+            const isDir = tree.has(childPath);
+            lines.push(`${prefix}${connector}${child}${isDir ? "/" : ""}`);
+            if (isDir) {
+                lines.push(renderTree(childPath, prefix + childPrefix, last, depth + 1));
+            }
+        }
+        return lines.filter(Boolean).join("\n");
+    }
+    return renderTree(".", "", false, 0);
+}
+function describeEntryPoint(path, map) {
+    const file = map.files.find((f) => f.path === path);
+    if (!file)
+        return path;
+    const parts = [];
+    if (file.language)
+        parts.push(file.language);
+    if (file.functions.length > 0) {
+        parts.push(`functions: ${file.functions.slice(0, 5).join(", ")}${file.functions.length > 5 ? "..." : ""}`);
+    }
+    if (file.classes.length > 0) {
+        parts.push(`classes: ${file.classes.join(", ")}`);
+    }
+    if (file.exports.length > 0) {
+        parts.push(`exports: ${file.exports.slice(0, 5).join(", ")}${file.exports.length > 5 ? "..." : ""}`);
+    }
+    return parts.length > 0 ? `${path} (${parts.join(" | ")})` : path;
+}
+function summarizeDependencies(map) {
+    const lines = [];
+    if (map.dependencies.length === 0) {
+        lines.push("No internal dependencies detected.");
+        return lines.join("\n");
+    }
+    // Group by source file
+    const bySource = new Map();
+    for (const edge of map.dependencies) {
+        if (!bySource.has(edge.from))
+            bySource.set(edge.from, []);
+        bySource.get(edge.from).push(edge.to);
+    }
+    // Show top importers
+    const topImporters = [...bySource.entries()]
+        .sort((a, b) => b[1].length - a[1].length)
+        .slice(0, 10);
+    for (const [source, targets] of topImporters) {
+        lines.push(`- **${source}** imports from ${targets.length} file(s): ${targets.slice(0, 5).join(", ")}${targets.length > 5 ? "..." : ""}`);
+    }
+    return lines.join("\n");
+}
+export function generateOnboardingGuide(map) {
+    const sections = [];
+    // Header
+    sections.push(`# Codebase Onboarding Guide`);
+    sections.push(`> Generated at ${map.generatedAt}`);
+    sections.push("");
+    // Project overview
+    sections.push(`## Project Overview`);
+    sections.push("");
+    sections.push(`| Metric | Value |`);
+    sections.push(`|--------|-------|`);
+    sections.push(`| Root | \`${map.root}\` |`);
+    sections.push(`| Total Files | ${map.totalFiles} |`);
+    sections.push(`| Total Lines | ${map.totalLines.toLocaleString()} |`);
+    sections.push(`| Languages | ${Object.keys(map.languages).length} |`);
+    sections.push(`| Internal Dependencies | ${map.dependencies.length} |`);
+    sections.push("");
+    // Language breakdown
+    sections.push(`## Languages`);
+    sections.push("");
+    const sortedLangs = Object.entries(map.languages).sort((a, b) => b[1] - a[1]);
+    for (const [lang, count] of sortedLangs) {
+        const pct = ((count / map.totalFiles) * 100).toFixed(1);
+        sections.push(`- **${lang}**: ${count} files (${pct}%)`);
+    }
+    sections.push("");
+    // Directory structure
+    sections.push(`## Directory Structure`);
+    sections.push("");
+    sections.push("```");
+    sections.push(buildDirectoryTree(map.files.map((f) => f.path), 3));
+    sections.push("```");
+    sections.push("");
+    // Entry points
+    sections.push(`## Entry Points`);
+    sections.push("");
+    if (map.entryPoints.length === 0) {
+        sections.push("No clear entry points detected (all files are imported by something).");
+    }
+    else {
+        sections.push("These files are not imported by any other file in the project, making them likely entry points:");
+        sections.push("");
+        const displayEntryPoints = map.entryPoints.slice(0, 20);
+        for (const ep of displayEntryPoints) {
+            sections.push(`- ${describeEntryPoint(ep, map)}`);
+        }
+        if (map.entryPoints.length > 20) {
+            sections.push(`- ...and ${map.entryPoints.length - 20} more`);
+        }
+    }
+    sections.push("");
+    // Hotspots
+    sections.push(`## Hotspot Files (Start Reading Here)`);
+    sections.push("");
+    if (map.hotspots.length === 0) {
+        sections.push("No hotspots detected.");
+    }
+    else {
+        sections.push("These files are imported most frequently, making them core modules:");
+        sections.push("");
+        for (const hp of map.hotspots) {
+            const incomingCount = map.dependencies.filter((e) => e.to === hp).length;
+            sections.push(`- **${hp}** (imported by ${incomingCount} files)`);
+        }
+    }
+    sections.push("");
+    // Dependency graph summary
+    sections.push(`## Dependency Graph`);
+    sections.push("");
+    sections.push(summarizeDependencies(map));
+    sections.push("");
+    // Key modules
+    const moduleGroups = new Map();
+    for (const file of map.files) {
+        if (!file.language)
+            continue;
+        const topDir = file.path.includes("/") ? file.path.split("/")[0] : ".";
+        if (!moduleGroups.has(topDir))
+            moduleGroups.set(topDir, []);
+        moduleGroups.get(topDir).push(file.path);
+    }
+    if (moduleGroups.size > 1) {
+        sections.push(`## Key Modules`);
+        sections.push("");
+        const sortedModules = [...moduleGroups.entries()].sort((a, b) => b[1].length - a[1].length);
+        for (const [dir, modulePaths] of sortedModules.slice(0, 15)) {
+            const langCounts = new Map();
+            for (const p of modulePaths) {
+                const file = map.files.find((f) => f.path === p);
+                if (file?.language) {
+                    langCounts.set(file.language, (langCounts.get(file.language) ?? 0) + 1);
+                }
+            }
+            const langSummary = [...langCounts.entries()]
+                .sort((a, b) => b[1] - a[1])
+                .map(([l, c]) => `${l}: ${c}`)
+                .join(", ");
+            sections.push(`- **${dir}/**: ${modulePaths.length} files (${langSummary})`);
+        }
+        sections.push("");
+    }
+    return sections.join("\n");
+}

package/dist/codebase/types.d.ts

@@ -0,0 +1,39 @@
+export type ImportInfo = {
+    path: string;
+    type: "import" | "require";
+};
+export type FileNode = {
+    path: string;
+    type: "file" | "directory";
+    language?: string;
+    size: number;
+    imports: string[];
+    /** Structured import info with type tracking. */
+    importInfos?: ImportInfo[];
+    exports: string[];
+    functions: string[];
+    classes: string[];
+    lineCount: number;
+};
+export type DependencyEdge = {
+    from: string;
+    to: string;
+    type: "import" | "require";
+};
+export type CodebaseMap = {
+    root: string;
+    files: FileNode[];
+    dependencies: DependencyEdge[];
+    languages: Record<string, number>;
+    totalFiles: number;
+    totalLines: number;
+    entryPoints: string[];
+    hotspots: string[];
+    generatedAt: string;
+};
+export type MapOptions = {
+    root: string;
+    ignore?: string[];
+    maxFiles?: number;
+    maxDepth?: number;
+};

package/dist/codebase/types.js

@@ -0,0 +1 @@
+export {};