@eloquence98/ctx 0.3.0 → 0.4.0

package/README.md

@@ -4,9 +4,9 @@ Dump a truthful structural index of a codebase.
 
 No analysis. No opinions. No guessing.
 
-ctx scans a directory and prints a map of folders, files, and statically detectable exported symbols. It tells you exactly what exists—nothing more, nothing less.
+ctx scans a directory and prints a map of folders, files, and trivially detectable exported symbols. It tells you exactly what exists — nothing more, nothing less.
 
-## ⚡️ Quick Start
+## Quick Start
 
 No installation required. Run it directly with npx:
 
@@ -14,13 +14,15 @@ No installation required. Run it directly with npx:
 npx @eloquence98/ctx ./path-to-project
 ```
 
-## 📖 What it does
+## What It Does
 
 ctx provides a high-level map of a project. It identifies:
 
-- 📂 Folders
-- 📄 Files
-- ➡️ Exported Symbols (when statically detectable)
+- Folders
+- Files
+- Exported symbols (both ES modules and CommonJS, when trivially detectable)
+
+Exports that cannot be statically determined from source text are silently ignored.
 
 ## Example Output
 
@@ -34,11 +36,21 @@ src/
    └─ styles.css
 ```
 
-If exports cannot be determined (e.g., non-code files or complex dynamic exports), the file is listed without symbols.
+Files whose exports cannot be determined are listed without symbols.
+
+## Supported Export Patterns
+
+#### ES Modules:
+
+`export function`, `export const/let/var`, `export class`, `export type`, `export interface`, `export default function/class`
 
-## 🧠 Why this exists
+#### CommonJS:
 
-When working with LLMs (ChatGPT, Claude, etc.), new contributors, or legacy codebases, you don't always need the content of the files immediately; you need to understand the topology of the project first.
+`exports.name = ...`, `module.exports.name = ...`, `module.exports = { name1, name2 }`, `module.exports = function/class`
+
+## Why This Exists
+
+When working with LLMs, new contributors, or legacy codebases, you don't always need the content of the files immediately, you need to understand the topology of the project first.
 
 ctx gives you that map.
 
@@ -46,43 +58,45 @@ ctx gives you that map.
 2.  Paste it into an LLM context window.
 3.  Ask informed questions about the architecture before dumping raw code.
 
-## 🚫 What it does NOT do
-
-ctx is intentionally dumb. That is why it is reliable.
+## What It Does Not Do
 
-It does not:
+ctx is intentionally shallow. That is why it is reliable.
 
-- ❌ Interpret architecture or infer domains.
-- ❌ Explain code intent.
-- ❌ Refactor or execute code.
-- ❌ Read node_modules or .git folders.
-- ❌ Read environment variables.
+- Does not interpret architecture or infer domains
+- Does not explain code intent
+- Does not refactor or execute code
+- Does not read `node_modules`, `.git`, or environment files
+- Does not parse re-exports, barrel files, or computed names
 
-It is not a framework detector, a dependency graph tool, or a documentation generator.
+See [LIMITATIONS.md](https://github.com/Eloquence98/ctx/blob/main/limitation.md) for detailed edge cases.
 
-## ⚙️ Configuration
+## Configuration
 
 No configuration required.
 
 ctx automatically ignores:
 
-- node_modules
-- .git
-- Build outputs (dist, build, etc.)
-- Environment files (.env)
-- Test files (.test., .spec.)
+- `node_modules`, `.git`
+- Build outputs (`dist`, `build`, `.next`)
+- Environment files (`.env`)
+- Test files (`.test`., `.spec`.)
+- Hidden files and directories
 
-## 💡 Philosophy
+Only `.ts`, `.tsx`, `.js`, `.jsx` files are scanned. Both ES module and CommonJS exports are detected.
 
-Don't explain the code. Show the codebase as it exists.
-
-## ⚡️ Install (optional)
+## Install (optional)
 
 ```bash
 npm install -g @eloquence98/ctx
 ctx ./src
 ```
 
+## Philosophy
+
+Don't explain the code. Show the codebase as it exists.
+
+ctx prefers truthful omission over incorrect inference. If something cannot be determined reliably, it is excluded.
+
 ## License
 
-[MIT](https://choosealicense.com/licenses/mit/)
+[MIT ](https://choosealicense.com/licenses/mit/)

package/dist/cli.d.ts

@@ -1,2 +1,9 @@
 #!/usr/bin/env node
+/**
+ * CLI entry point for ctx.
+ * Scans a directory, parses exports, and prints a formatted tree.
+ *
+ * @example
+ * npx ctx ./src
+ */
 export {};

package/dist/cli.js

@@ -1,21 +1,29 @@
 #!/usr/bin/env node
+/**
+ * CLI entry point for ctx.
+ * Scans a directory, parses exports, and prints a formatted tree.
+ *
+ * @example
+ * npx ctx ./src
+ */
 import path from "path";
-import { scan } from "./scanner.js";
-import { parse } from "./parser.js";
 import { format } from "./formatter.js";
+import { parse } from "./parser.js";
+import { scan } from "./scanner.js";
 const args = process.argv.slice(2);
 const targetPath = args[0] || ".";
+/**
+ * Main CLI execution flow.
+ * Orchestrates scanning → parsing → formatting.
+ */
 async function main() {
     const dir = path.resolve(process.cwd(), targetPath);
-    // Scan
     const files = await scan(dir);
     if (files.length === 0) {
         console.log("No files found.");
         process.exit(1);
     }
-    // Parse
     const parsed = await Promise.all(files.map(parse));
-    // Format and print
     console.log(format(parsed, dir));
 }
 main().catch(console.error);

package/dist/formatter.d.ts

@@ -1,2 +1,15 @@
 import type { ParsedFile } from "./types.js";
+/**
+ * Formats parsed files into a tree-style string representation.
+ *
+ * @param files - Array of parsed files
+ * @param baseDir - Root directory path for relative path calculation
+ * @returns Formatted tree string
+ *
+ * @example
+ * const output = format(parsedFiles, "/project/src");
+ * // src/
+ * // ├─ index.ts → main
+ * // └─ utils.ts → format, parse
+ */
 export declare function format(files: ParsedFile[], baseDir: string): string;

package/dist/formatter.js

@@ -1,6 +1,18 @@
 import path from "path";
+/**
+ * Formats parsed files into a tree-style string representation.
+ *
+ * @param files - Array of parsed files
+ * @param baseDir - Root directory path for relative path calculation
+ * @returns Formatted tree string
+ *
+ * @example
+ * const output = format(parsedFiles, "/project/src");
+ * // src/
+ * // ├─ index.ts → main
+ * // └─ utils.ts → format, parse
+ */
 export function format(files, baseDir) {
-    // Build tree structure
     const root = { name: path.basename(baseDir), children: new Map() };
     for (const file of files) {
         const rel = path.relative(baseDir, file.path);
@@ -22,12 +34,18 @@ export function format(files, baseDir) {
             current = current.children.get(part);
         }
     }
-    // Render tree
     const lines = [];
     lines.push(root.name + "/");
     renderTree(root, "", lines);
     return lines.join("\n");
 }
+/**
+ * Recursively renders tree nodes into formatted lines.
+ *
+ * @param node - Current tree node
+ * @param prefix - Indentation prefix for current depth
+ * @param lines - Output array to append lines to
+ */
 function renderTree(node, prefix, lines) {
     const children = [...node.children.values()];
     for (let i = 0; i < children.length; i++) {
@@ -35,7 +53,6 @@ function renderTree(node, prefix, lines) {
         const isLast = i === children.length - 1;
         const connector = isLast ? "└─ " : "├─ ";
         const extension = isLast ? "   " : "│  ";
-        // Is it a file (has exports defined) or folder?
         const isFile = child.exports !== undefined;
         if (isFile) {
             const exportsStr = child.exports.length > 0 ? ` → ${child.exports.join(", ")}` : "";

package/dist/parser.d.ts

@@ -1,2 +1,13 @@
 import type { ParsedFile } from "./types.js";
+/**
+ * Parses a source file and extracts exported symbol names.
+ * Supports both ES modules and CommonJS exports.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Parsed file object with export names
+ *
+ * @example
+ * const result = await parse("./src/utils.ts");
+ * // { path: "./src/utils.ts", name: "utils.ts", exports: ["format", "parse"] }
+ */
 export declare function parse(filePath: string): Promise<ParsedFile>;

package/dist/parser.js

@@ -1,15 +1,29 @@
 import fs from "fs/promises";
 import path from "path";
+/**
+ * Parses a source file and extracts exported symbol names.
+ * Supports both ES modules and CommonJS exports.
+ *
+ * @param filePath - Absolute path to the file
+ * @returns Parsed file object with export names
+ *
+ * @example
+ * const result = await parse("./src/utils.ts");
+ * // { path: "./src/utils.ts", name: "utils.ts", exports: ["format", "parse"] }
+ */
 export async function parse(filePath) {
-    const content = await fs.readFile(filePath, "utf-8");
+    let content = await fs.readFile(filePath, "utf-8");
     const name = path.basename(filePath);
     const exports = [];
+    // Remove comments to avoid false positives from commented-out code
+    content = stripComments(content);
+    // === ES Module Exports ===
     // export function Name
     for (const match of content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g)) {
         exports.push(match[1]);
     }
-    // export const Name
-    for (const match of content.matchAll(/export\s+const\s+(\w+)/g)) {
+    // export const/let/var Name
+    for (const match of content.matchAll(/export\s+(?:const|let|var)\s+(\w+)/g)) {
         exports.push(match[1]);
     }
     // export type/interface Name
@@ -24,5 +38,167 @@ export async function parse(filePath) {
     for (const match of content.matchAll(/export\s+default\s+(?:function|class)\s+(\w+)/g)) {
         exports.push(match[1]);
     }
-    return { path: filePath, name, exports };
+    // === CommonJS Exports ===
+    // module.exports.name = ...
+    for (const match of content.matchAll(/module\.exports\.(\w+)\s*=/g)) {
+        exports.push(match[1]);
+    }
+    // exports.name = ... (but not module.exports.name)
+    for (const match of content.matchAll(/(?<!module\.)exports\.(\w+)\s*=/g)) {
+        exports.push(match[1]);
+    }
+    // module.exports = { name1, name2: value, ... }
+    for (const match of content.matchAll(/module\.exports\s*=\s*\{/g)) {
+        const startIdx = match.index + match[0].length;
+        const objectExports = parseExportsObject(content, startIdx);
+        exports.push(...objectExports);
+    }
+    // module.exports = function name() {} or async function name() {}
+    for (const match of content.matchAll(/module\.exports\s*=\s*(?:async\s+)?function\s+(\w+)/g)) {
+        exports.push(match[1]);
+    }
+    // module.exports = class Name {}
+    for (const match of content.matchAll(/module\.exports\s*=\s*class\s+(\w+)/g)) {
+        exports.push(match[1]);
+    }
+    // module.exports = Identifier (e.g., module.exports = MyClass;)
+    for (const match of content.matchAll(/module\.exports\s*=\s*([A-Z]\w*)\s*;?\s*$/gm)) {
+        exports.push(match[1]);
+    }
+    return { path: filePath, name, exports: [...new Set(exports)] };
+}
+/**
+ * Removes single-line (//) and multi-line (/* *\/) comments from source code.
+ * Preserves string literals to avoid breaking code structure.
+ *
+ * @param code - Raw source code
+ * @returns Code with comments removed
+ */
+function stripComments(code) {
+    let result = "";
+    let i = 0;
+    while (i < code.length) {
+        // Handle string literals - don't strip inside strings
+        if (code[i] === '"' || code[i] === "'" || code[i] === "`") {
+            const quote = code[i];
+            result += code[i++];
+            while (i < code.length && code[i] !== quote) {
+                if (code[i] === "\\") {
+                    result += code[i++];
+                }
+                if (i < code.length) {
+                    result += code[i++];
+                }
+            }
+            if (i < code.length) {
+                result += code[i++];
+            }
+        }
+        // Single-line comment
+        else if (code[i] === "/" && code[i + 1] === "/") {
+            while (i < code.length && code[i] !== "\n") {
+                i++;
+            }
+        }
+        // Multi-line comment
+        else if (code[i] === "/" && code[i + 1] === "*") {
+            i += 2;
+            while (i < code.length && !(code[i] === "*" && code[i + 1] === "/")) {
+                i++;
+            }
+            i += 2;
+        }
+        // Regular character
+        else {
+            result += code[i++];
+        }
+    }
+    return result;
+}
+/**
+ * Parses a CommonJS exports object literal and extracts property names.
+ * Handles nested objects/arrays by tracking bracket depth.
+ *
+ * @param content - Source code content
+ * @param startIdx - Index where the object literal begins (after opening brace)
+ * @returns Array of exported property names
+ *
+ * @example
+ * // For: module.exports = { foo, bar: value }
+ * parseExportsObject(content, indexAfterBrace);
+ * // Returns: ["foo", "bar"]
+ */
+function parseExportsObject(content, startIdx) {
+    const exports = [];
+    let depth = 0;
+    let i = startIdx;
+    let token = "";
+    let afterColon = false;
+    const keywords = new Set([
+        "function",
+        "async",
+        "class",
+        "return",
+        "const",
+        "let",
+        "var",
+        "true",
+        "false",
+        "null",
+        "undefined",
+        "new",
+        "require",
+        "await",
+    ]);
+    while (i < content.length) {
+        const char = content[i];
+        if (char === "{" || char === "[" || char === "(") {
+            depth++;
+            token = "";
+        }
+        else if (char === "}") {
+            if (depth === 0) {
+                if (token && !afterColon && !keywords.has(token)) {
+                    exports.push(token);
+                }
+                break;
+            }
+            depth--;
+            token = "";
+        }
+        else if (char === "]" || char === ")") {
+            depth--;
+            token = "";
+        }
+        else if (depth === 0) {
+            if (/[a-zA-Z_$]/.test(char)) {
+                token += char;
+            }
+            else if (/[0-9]/.test(char) && token) {
+                token += char;
+            }
+            else if (char === ":") {
+                if (token && !keywords.has(token)) {
+                    exports.push(token);
+                }
+                token = "";
+                afterColon = true;
+            }
+            else if (char === ",") {
+                if (token && !afterColon && !keywords.has(token)) {
+                    exports.push(token);
+                }
+                token = "";
+                afterColon = false;
+            }
+            else if (/\s/.test(char)) {
+                // continue
+            }
+            else {
+                token = "";
+            }
+        }
+        i++;
+    }
+    return exports;
 }

package/dist/scanner.d.ts

@@ -1 +1,12 @@
+/**
+ * Recursively scans a directory for JavaScript/TypeScript files.
+ * Ignores node_modules, build outputs, hidden files, and test files.
+ *
+ * @param dir - The directory path to scan
+ * @returns Array of absolute file paths
+ *
+ * @example
+ * const files = await scan("./src");
+ * // ["/project/src/index.ts", "/project/src/utils.ts", ...]
+ */
 export declare function scan(dir: string): Promise<string[]>;

package/dist/scanner.js

@@ -1,5 +1,6 @@
 import fs from "fs/promises";
 import path from "path";
+/** Directories and files to ignore during scanning */
 const IGNORE = [
     "node_modules",
     ".git",
@@ -14,7 +15,19 @@ const IGNORE = [
     ".idea",
     "coverage",
 ];
+/** File extensions to include in scan results */
 const EXTENSIONS = [".ts", ".tsx", ".js", ".jsx"];
+/**
+ * Recursively scans a directory for JavaScript/TypeScript files.
+ * Ignores node_modules, build outputs, hidden files, and test files.
+ *
+ * @param dir - The directory path to scan
+ * @returns Array of absolute file paths
+ *
+ * @example
+ * const files = await scan("./src");
+ * // ["/project/src/index.ts", "/project/src/utils.ts", ...]
+ */
 export async function scan(dir) {
     const files = [];
     async function walk(current) {
@@ -26,7 +39,6 @@ export async function scan(dir) {
             return;
         }
         for (const entry of entries) {
-            // Skip ignored
             if (IGNORE.includes(entry.name))
                 continue;
             if (entry.name.startsWith("."))

package/dist/types.d.ts

@@ -1,9 +1,20 @@
+/**
+ * Represents a parsed source file with its exported symbols.
+ */
 export interface ParsedFile {
+    /** Absolute path to the file */
     path: string;
+    /** Base filename (e.g., "parser.ts") */
     name: string;
+    /** List of exported symbol names */
     exports: string[];
 }
+/**
+ * Represents a folder and its parsed files.
+ */
 export interface FolderContent {
+    /** Folder path */
     folder: string;
+    /** Parsed files within this folder */
     files: ParsedFile[];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@eloquence98/ctx",
-  "version": "0.3.0",
-  "description": "Scan your codebase. Get a clean summary. Paste it to AI.",
+  "version": "0.4.0",
+  "description": "Generate a truthful structural map of your codebase for AI and humans.",
   "type": "module",
   "bin": {
     "ctx": "dist/cli.js"
@@ -15,17 +15,15 @@
     "ai",
     "context",
     "codebase",
-    "documentation",
     "cli",
     "typescript",
-    "nextjs",
-    "react"
+    "javascript"
   ],
   "author": "Eloquence98",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/Eloquence98/ctx.git"
+    "url": "git+https://github.com/Eloquence98/ctx.git"
   },
   "homepage": "https://github.com/Eloquence98/ctx",
   "files": [
@@ -35,5 +33,8 @@
     "@types/node": "^20.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@eloquence98/ctx": "file:eloquence98-ctx-0.4.0.tgz"
   }
-}
+}