@eloquence98/ctx 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# ctx
+
+Generate AI-ready context from your codebase in seconds.
+
+`ctx` scans a project directory and produces a clean, structured overview of folders and exported symbols. The output is designed to be pasted directly into AI tools to give them accurate context about your codebase.
+
+---
+
+## Why ctx
+
+AI assistants do not understand your project unless you explain it.
+
+Without ctx, you usually have to:
+
+- Manually copy files
+- Describe folder structure
+- Explain what exists and how things connect
+
+`ctx` automates this by generating a concise snapshot of your project with a single command.
+
+---
+
+## What It Does
+
+- Recursively scans a directory
+- Detects common project conventions
+- Extracts exported symbols
+- Produces readable, AI-friendly output
+- Requires zero configuration
+
+---
+
+## Installation
+
+### No install (recommended)
+
+```bash
+npx @eloquence98/ctx ./src
+```
+
+### Global install
+
+```bash
+npm install -g @eloquence98/ctx
+```
+
+### Local install (dev dependency)
+
+```bash
+npm install --save-dev @eloquence98/ctx
+```
+
+---
+
+## Usage
+
+### Scan a directory
+
+```bash
+ctx ./src
+```
+
+### Scan current directory
+
+```bash
+ctx .
+```
+
+### Output as JSON
+
+```bash
+ctx ./src -o json
+```
+
+### Write output to a file
+
+```bash
+ctx ./src > CONTEXT.md
+```
+
+---
+
+## What Gets Extracted
+
+### Code Symbols
+
+- Functions
+- Constants
+- Types
+- Interfaces
+
+### Project Structure
+
+- Routes (App Router / Pages Router)
+- Features or modules
+- Components
+- Hooks
+- Utilities and libraries
+
+Detection is convention-based and works with most modern JavaScript and TypeScript projects.
+
+---
+
+## Use Cases
+
+- Providing context to ChatGPT, Claude, or Copilot
+- Generating architecture documentation
+- Onboarding new team members
+- Understanding unfamiliar codebases
+- Preparing projects for AI-assisted refactors
+
+---
+
+## Output Philosophy
+
+The output is:
+
+- Minimal
+- Structured
+- Human-readable
+- Optimized for AI comprehension
+
+Only high-signal information is included.
+
+---
+
+## Roadmap
+
+- Clipboard support (`--copy`)
+- Config file support
+- VS Code extension
+- Watch mode
+
+---
+
+## License
+
+MIT

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+import { program } from "commander";
+import path from "path";
+import fs from "fs/promises";
+import { scanDirectory, getRoutes } from "./scanner.js";
+import { parseFile } from "./parser.js";
+import { formatMarkdown } from "./formatters/index.js";
+program
+    .name("ctx")
+    .description("Generate AI-ready context from your codebase")
+    .version("0.1.0")
+    .argument("[path]", "Path to scan", "./src")
+    .option("-o, --output <format>", "Output format: md, json", "md")
+    .action(async (targetPath, options) => {
+    const absolutePath = path.resolve(process.cwd(), targetPath);
+    console.log(`\n📁 Scanning ${absolutePath}...\n`);
+    try {
+        // Scan all files
+        const files = await scanDirectory(absolutePath);
+        if (files.length === 0) {
+            console.log("No files found. Check your path.");
+            process.exit(1);
+        }
+        // Parse all files
+        const parsedFiles = await Promise.all(files.map((file) => parseFile(file)));
+        // Get routes - try to find app directory
+        let routes = [];
+        const appDir = await findAppDirectory(absolutePath);
+        if (appDir) {
+            routes = await getRoutes(appDir);
+        }
+        // Build context
+        const context = {
+            routes,
+            features: groupByFolder(parsedFiles, absolutePath, "features"),
+            hooks: getHooks(parsedFiles),
+            lib: groupByFolder(parsedFiles, absolutePath, "lib"),
+            components: groupByFolder(parsedFiles, absolutePath, "components"),
+        };
+        // Output
+        if (options.output === "json") {
+            console.log(JSON.stringify(contextToJSON(context), null, 2));
+        }
+        else {
+            console.log(formatMarkdown(context, absolutePath));
+        }
+    }
+    catch (error) {
+        console.error("Error:", error);
+        process.exit(1);
+    }
+});
+async function findAppDirectory(basePath) {
+    const possiblePaths = [
+        path.join(basePath, "app"),
+        path.join(basePath, "src", "app"),
+        path.join(basePath, "src/app"),
+    ];
+    for (const p of possiblePaths) {
+        try {
+            const stat = await fs.stat(p);
+            if (stat.isDirectory()) {
+                return p;
+            }
+        }
+        catch {
+            // Path doesn't exist, try next
+        }
+    }
+    return null;
+}
+function groupByFolder(files, basePath, folderName) {
+    const grouped = new Map();
+    for (const file of files) {
+        const relativePath = path.relative(basePath, file.filePath);
+        const parts = relativePath.split(path.sep);
+        const folderIndex = parts.indexOf(folderName);
+        if (folderIndex === -1)
+            continue;
+        const remainingParts = parts.slice(folderIndex + 1);
+        // Need at least 2 parts: subfolder + filename
+        if (remainingParts.length < 2)
+            continue;
+        const subFolder = remainingParts[0];
+        if (!grouped.has(subFolder)) {
+            grouped.set(subFolder, []);
+        }
+        grouped.get(subFolder).push(file);
+    }
+    return grouped;
+}
+function getHooks(files) {
+    return files.filter((f) => f.filePath.includes("/hooks/") ||
+        f.filePath.includes("\\hooks\\") ||
+        f.fileName.startsWith("use-") ||
+        f.fileName.startsWith("use."));
+}
+function contextToJSON(context) {
+    return {
+        routes: context.routes,
+        features: Object.fromEntries(context.features),
+        hooks: context.hooks,
+        lib: Object.fromEntries(context.lib),
+        components: Object.fromEntries(context.components),
+    };
+}
+program.parse();

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { ScanOptions } from "./types.js";
+export declare const defaultConfig: ScanOptions;
+export declare const folderCategories: {
+    routes: string[];
+    features: string[];
+    hooks: string[];
+    lib: string[];
+    components: string[];
+};

package/dist/config.js

@@ -0,0 +1,24 @@
+export const defaultConfig = {
+    entry: "./src",
+    extensions: [".ts", ".tsx", ".js", ".jsx"],
+    ignore: [
+        "node_modules",
+        ".git",
+        "dist",
+        "build",
+        ".next",
+        "*.test.*",
+        "*.spec.*",
+        "__tests__",
+        "*.d.ts",
+        ".DS_Store",
+    ],
+    maxDepth: 10,
+};
+export const folderCategories = {
+    routes: ["app", "pages"],
+    features: ["features", "modules", "domains"],
+    hooks: ["hooks"],
+    lib: ["lib", "utils", "helpers", "services"],
+    components: ["components", "ui"],
+};

package/dist/formatters/index.d.ts

@@ -0,0 +1 @@
+export { formatMarkdown } from "./markdown.js";

package/dist/formatters/index.js

@@ -0,0 +1 @@
+export { formatMarkdown } from "./markdown.js";

package/dist/formatters/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectContext } from "../types.js";
+export declare function formatMarkdown(data: ProjectContext, basePath: string): string;

package/dist/formatters/markdown.js

@@ -0,0 +1,73 @@
+export function formatMarkdown(data, basePath) {
+    let output = "";
+    // Routes section
+    if (data.routes.length > 0) {
+        output += `=== ROUTES (src/app) ===\n\n`;
+        for (const route of data.routes) {
+            output += `${route}\n`;
+        }
+        output += "\n";
+    }
+    // Features section
+    if (data.features.size > 0) {
+        output += `=== FEATURES ===\n\n`;
+        output += formatFolderGroup(data.features);
+    }
+    // Components section
+    if (data.components.size > 0) {
+        output += `=== COMPONENTS ===\n\n`;
+        output += formatFolderGroup(data.components);
+    }
+    // Hooks section
+    if (data.hooks.length > 0) {
+        output += `=== HOOKS ===\n\n`;
+        for (const file of data.hooks) {
+            output += formatSingleFile(file);
+        }
+        output += "\n";
+    }
+    // Lib section
+    if (data.lib.size > 0) {
+        output += `=== LIB ===\n\n`;
+        output += formatFolderGroup(data.lib);
+    }
+    output += `=== DONE ===\n`;
+    return output;
+}
+function formatFolderGroup(folders) {
+    let output = "";
+    for (const [folderName, files] of folders) {
+        output += `${folderName}/\n`;
+        for (const file of files) {
+            output += formatSingleFile(file);
+        }
+        output += "\n";
+    }
+    return output;
+}
+function formatSingleFile(file) {
+    const hasExports = file.functions.length > 0 ||
+        file.constants.length > 0 ||
+        file.types.length > 0 ||
+        file.interfaces.length > 0 ||
+        file.classes.length > 0;
+    if (!hasExports)
+        return "";
+    let output = `${file.fileName}\n`;
+    for (const fn of file.functions) {
+        output += `• function: ${fn}\n`;
+    }
+    for (const constant of file.constants) {
+        output += `• constant: ${constant}\n`;
+    }
+    for (const type of file.types) {
+        output += `• type: ${type}\n`;
+    }
+    for (const iface of file.interfaces) {
+        output += `• interface: ${iface}\n`;
+    }
+    for (const cls of file.classes) {
+        output += `• class: ${cls}\n`;
+    }
+    return output;
+}

package/dist/parser.d.ts

@@ -0,0 +1,2 @@
+import type { FileExports } from "./types.js";
+export declare function parseFile(filePath: string): Promise<FileExports>;

package/dist/parser.js

@@ -0,0 +1,73 @@
+import fs from "fs/promises";
+import path from "path";
+export async function parseFile(filePath) {
+    const content = await fs.readFile(filePath, "utf-8");
+    const fileName = path.basename(filePath);
+    return {
+        filePath,
+        fileName,
+        functions: extractFunctions(content),
+        constants: extractConstants(content),
+        types: extractTypes(content),
+        interfaces: extractInterfaces(content),
+        classes: extractClasses(content),
+        defaultExport: extractDefaultExport(content),
+    };
+}
+function extractFunctions(content) {
+    const functions = [];
+    // export function name
+    const funcMatches = content.matchAll(/export\s+(?:async\s+)?function\s+(\w+)/g);
+    for (const match of funcMatches) {
+        functions.push(match[1]);
+    }
+    // export const name = async? (...) => or function(
+    const arrowMatches = content.matchAll(/export\s+const\s+(\w+)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[a-zA-Z_]\w*)\s*(?:=>|\{)/g);
+    for (const match of arrowMatches) {
+        if (!functions.includes(match[1])) {
+            functions.push(match[1]);
+        }
+    }
+    return functions;
+}
+function extractConstants(content) {
+    const constants = [];
+    // Match export const that are NOT functions
+    const lines = content.split("\n");
+    for (const line of lines) {
+        // export const NAME = value (not a function)
+        const match = line.match(/export\s+const\s+(\w+)\s*=\s*(?!(?:async\s*)?(?:\(|function|\w+\s*=>))/);
+        if (match) {
+            constants.push(match[1]);
+        }
+        // Also catch: export const NAME: Type =
+        const typedMatch = line.match(/export\s+const\s+(\w+)\s*:\s*[^=]+=\s*(?!(?:async\s*)?(?:\(|function|\w+\s*=>))/);
+        if (typedMatch && !constants.includes(typedMatch[1])) {
+            constants.push(typedMatch[1]);
+        }
+    }
+    return constants;
+}
+function extractTypes(content) {
+    const matches = content.matchAll(/export\s+type\s+(\w+)/g);
+    return [...matches].map((m) => m[1]);
+}
+function extractInterfaces(content) {
+    const matches = content.matchAll(/export\s+interface\s+(\w+)/g);
+    return [...matches].map((m) => m[1]);
+}
+function extractClasses(content) {
+    const matches = content.matchAll(/export\s+(?:default\s+)?class\s+(\w+)/g);
+    return [...matches].map((m) => m[1]);
+}
+function extractDefaultExport(content) {
+    // export default function Name
+    const funcMatch = content.match(/export\s+default\s+function\s+(\w+)/);
+    if (funcMatch)
+        return funcMatch[1];
+    // export default Name
+    const simpleMatch = content.match(/export\s+default\s+(\w+)/);
+    if (simpleMatch)
+        return simpleMatch[1];
+    return undefined;
+}

package/dist/scanner.d.ts

@@ -0,0 +1,3 @@
+import type { ScanOptions } from "./types.js";
+export declare function scanDirectory(dir: string, options?: Partial<ScanOptions>): Promise<string[]>;
+export declare function getRoutes(appDir: string): Promise<string[]>;

package/dist/scanner.js

@@ -0,0 +1,73 @@
+import fs from "fs/promises";
+import path from "path";
+import { defaultConfig } from "./config.js";
+export async function scanDirectory(dir, options = {}) {
+    const config = { ...defaultConfig, ...options };
+    const files = [];
+    async function walk(currentDir, depth = 0) {
+        if (depth > config.maxDepth)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(currentDir, entry.name);
+            // Check ignore patterns
+            const shouldIgnore = config.ignore.some((pattern) => {
+                if (pattern.includes("*")) {
+                    const regex = new RegExp(pattern.replace(/\./g, "\\.").replace(/\*/g, ".*"));
+                    return regex.test(entry.name);
+                }
+                return entry.name === pattern;
+            });
+            if (shouldIgnore)
+                continue;
+            if (entry.isDirectory()) {
+                await walk(fullPath, depth + 1);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name);
+                if (config.extensions.includes(ext)) {
+                    files.push(fullPath);
+                }
+            }
+        }
+    }
+    await walk(dir);
+    return files;
+}
+export async function getRoutes(appDir) {
+    const routes = [];
+    async function walkRoutes(dir, indent = "") {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        // Sort: groups first (parentheses), then regular folders
+        const sorted = entries
+            .filter((e) => e.isDirectory())
+            .filter((e) => !e.name.startsWith("_"))
+            .sort((a, b) => {
+            const aIsGroup = a.name.startsWith("(");
+            const bIsGroup = b.name.startsWith("(");
+            if (aIsGroup && !bIsGroup)
+                return -1;
+            if (!aIsGroup && bIsGroup)
+                return 1;
+            return a.name.localeCompare(b.name);
+        });
+        for (const entry of sorted) {
+            routes.push(`${indent}${entry.name}`);
+            await walkRoutes(path.join(dir, entry.name), indent + "  ");
+        }
+    }
+    await walkRoutes(appDir);
+    return routes;
+}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+export interface FileExports {
+    filePath: string;
+    fileName: string;
+    functions: string[];
+    constants: string[];
+    types: string[];
+    interfaces: string[];
+    classes: string[];
+    defaultExport?: string;
+}
+export interface ScanOptions {
+    entry: string;
+    extensions: string[];
+    ignore: string[];
+    maxDepth: number;
+}
+export interface ProjectContext {
+    routes: string[];
+    features: Map<string, FileExports[]>;
+    hooks: FileExports[];
+    lib: Map<string, FileExports[]>;
+    components: Map<string, FileExports[]>;
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@eloquence98/ctx",
+  "version": "0.1.0",
+  "description": "Generate AI-ready context from your codebase. One command, zero config.",
+  "type": "module",
+  "bin": {
+    "ctx": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "tsx src/cli.ts ."
+  },
+  "keywords": [
+    "ai",
+    "context",
+    "codebase",
+    "documentation",
+    "cli",
+    "typescript",
+    "nextjs",
+    "react"
+  ],
+  "author": "Eloquence98",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Eloquence98/ctx.git"
+  },
+  "homepage": "https://github.com/Eloquence98/ctx",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "fast-glob": "^3.3.0"
+  }
+}