@eloquence98/ctx 0.1.5 → 0.1.6

package/dist/cli.js

@@ -1,48 +1,53 @@
 #!/usr/bin/env node
 import { program } from "commander";
-import path from "path";
 import fs from "fs/promises";
-import { scanDirectory } from "./scanner.js";
-import { parseFile } from "./parser.js";
-import { detectProject, getProjectLabel } from "./detectors/index.js";
+import path from "path";
 import { getAdapter } from "./adapters/index.js";
-import { formatMarkdown } from "./formatters/markdown.js";
-import { formatAI } from "./formatters/ai.js";
+import { detectProject, getProjectLabel } from "./detectors/index.js";
+import { formatAIOptimized } from "./formatters/ai-optimized.js";
+import { formatHuman } from "./formatters/human.js";
+import { formatRaw } from "./formatters/raw.js";
+import { parseFile } from "./parser.js";
+import { scanDirectory } from "./scanner.js";
 program
     .name("ctx")
     .description("Generate AI-ready context from your codebase")
-    .version("0.1.5")
+    .version("0.1.6")
     .argument("[path]", "Path to scan", ".")
-    .option("-o, --output <format>", "Output format: md, json", "md")
-    .option("--ai", "Output in AI-optimized compact format")
+    .option("--human", "Human-readable output for onboarding")
+    .option("--raw", "Verbose output with all details")
+    .option("-o, --output <format>", "Output format: json", "")
     .action(async (targetPath, options) => {
     const absolutePath = path.resolve(process.cwd(), targetPath);
-    // Find project root and detect type
     const projectRoot = await findProjectRoot(absolutePath);
     const projectType = await detectProject(projectRoot);
     const adapter = getAdapter(projectType);
-    console.log(`\n📁 Scanning ${absolutePath}...`);
-    console.log(`📦 Detected: ${getProjectLabel(projectType)}\n`);
+    // Only show scanning message for human/raw modes
+    if (options.human || options.raw) {
+        console.log(`\n📁 Scanning ${absolutePath}...`);
+        console.log(`📦 Detected: ${getProjectLabel(projectType)}\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)));
-        // Use adapter to analyze
         const context = await adapter.analyze(absolutePath, parsedFiles);
-        // Output
+        // Output based on flags
         if (options.output === "json") {
             console.log(JSON.stringify(contextToJSON(context), null, 2));
         }
-        else if (options.ai) {
-            console.log(formatAI(context));
+        else if (options.raw) {
+            console.log(formatRaw(context));
+        }
+        else if (options.human) {
+            console.log(formatHuman(context));
         }
         else {
-            console.log(formatMarkdown(context));
+            // Default: AI-optimized
+            console.log(formatAIOptimized(context));
         }
     }
     catch (error) {

package/dist/formatters/ai-optimized.d.ts

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

package/dist/formatters/ai-optimized.js

@@ -0,0 +1,215 @@
+export function formatAIOptimized(data) {
+    const lines = [];
+    lines.push(`# Project Context (${data.projectType})`);
+    lines.push("");
+    // 1. Routes
+    if (data.routes && data.routes.length > 0) {
+        const routeGroups = parseRouteGroups(data.routes);
+        // Filter out empty shell routes
+        const filteredGroups = new Map();
+        for (const [key, value] of routeGroups) {
+            if (value.length > 0) {
+                filteredGroups.set(key, value);
+            }
+        }
+        lines.push(`## Routes (${filteredGroups.size})`);
+        for (const [group, paths] of filteredGroups) {
+            // Max 4 routes, no "+N more"
+            const displayPaths = paths.slice(0, 4);
+            lines.push(`/${group} → ${displayPaths.join(", ")}`);
+        }
+        lines.push("");
+    }
+    // 2. Core Domains
+    const features = getSectionsByPattern(data.sections, "features");
+    if (features.size > 0) {
+        lines.push(`## Core Domains (${features.size})`);
+        for (const [name, files] of features) {
+            lines.push(formatDomainLine(name, files));
+        }
+        lines.push("");
+    }
+    // 3. Auth & Session
+    const authFiles = getAuthFiles(data.sections);
+    if (authFiles.length > 0) {
+        lines.push("## Auth & Session");
+        lines.push("sign-in, session handling, token management");
+        lines.push("");
+    }
+    // 4. Shared Lib
+    const lib = getSectionsByPattern(data.sections, "lib");
+    if (lib.size > 0 || data.sections.has("LIB") || data.sections.has("Lib")) {
+        lines.push("## Shared Lib");
+        lines.push("utils — formatting, helpers");
+        const config = getSectionsByPattern(data.sections, "config");
+        if (config.size > 0) {
+            lines.push("config — api, uploads, pricing");
+        }
+        lines.push("");
+    }
+    // 5. Hooks
+    const hooks = data.sections.get("HOOKS") || data.sections.get("Hooks");
+    if (hooks && hooks.length > 0) {
+        const hookNames = hooks
+            .flatMap((f) => f.functions)
+            .filter((n) => n.startsWith("use"));
+        lines.push(`## Hooks (${hookNames.length})`);
+        lines.push(hookNames.join(", "));
+        lines.push("");
+    }
+    // 6. UI Layer
+    const components = getSectionsByPattern(data.sections, "components");
+    if (components.size > 0) {
+        const totalComponents = countTotalFiles(components);
+        lines.push("## UI Layer");
+        const folders = [...components.keys()]
+            .map((k) => k.split("/").pop()?.toLowerCase())
+            .filter(Boolean);
+        const uniqueFolders = [...new Set(folders)];
+        lines.push(`~${totalComponents} components (${uniqueFolders.join(", ")})`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// === Route Parsing ===
+function parseRouteGroups(routes) {
+    const groups = new Map();
+    let currentTopLevel = "";
+    let currentDynamic = "";
+    for (const route of routes) {
+        const trimmed = route.trim();
+        // Skip group markers like (auth), (website)
+        if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
+            continue;
+        }
+        // Calculate depth by counting leading spaces
+        const depth = route.search(/\S/);
+        // Top-level route
+        if (depth === 0) {
+            currentTopLevel = trimmed;
+            currentDynamic = "";
+            if (!groups.has(currentTopLevel)) {
+                groups.set(currentTopLevel, []);
+            }
+        }
+        // First-level dynamic segment like [slug]
+        else if (depth === 2 && trimmed.startsWith("[") && trimmed.endsWith("]")) {
+            currentDynamic = trimmed;
+            const dynamicKey = `${currentTopLevel}/${currentDynamic}`;
+            if (!groups.has(dynamicKey)) {
+                groups.set(dynamicKey, []);
+            }
+        }
+        // Child routes
+        else if (depth >= 2) {
+            // Skip dynamic segments and technical routes
+            if (isSkippableRoute(trimmed)) {
+                continue;
+            }
+            // Add to dynamic group if exists, otherwise to top level
+            if (currentDynamic && depth > 2) {
+                const dynamicKey = `${currentTopLevel}/${currentDynamic}`;
+                const children = groups.get(dynamicKey);
+                if (children && !children.includes(trimmed)) {
+                    children.push(trimmed);
+                }
+            }
+            else if (currentTopLevel) {
+                const children = groups.get(currentTopLevel);
+                if (children && !children.includes(trimmed)) {
+                    children.push(trimmed);
+                }
+            }
+        }
+    }
+    // Clean up empty groups and dynamic groups with no children
+    const cleaned = new Map();
+    for (const [key, value] of groups) {
+        // Keep if has children OR is a standalone route
+        if (value.length > 0 || !key.includes("/")) {
+            cleaned.set(key, value);
+        }
+    }
+    return cleaned;
+}
+function isSkippableRoute(route) {
+    const skipPatterns = [
+        "[",
+        "]",
+        "error",
+        "sync",
+        "verify-email",
+        "success",
+        "...nextauth",
+    ];
+    const lower = route.toLowerCase();
+    return skipPatterns.some((p) => lower.includes(p));
+}
+// === Section Helpers ===
+function getSectionsByPattern(sections, pattern) {
+    const result = new Map();
+    for (const [key, value] of sections) {
+        if (key.toLowerCase().includes(pattern.toLowerCase())) {
+            result.set(key, value);
+        }
+    }
+    return result;
+}
+function getAuthFiles(sections) {
+    for (const [key, value] of sections) {
+        if (key.toLowerCase().includes("auth")) {
+            return value;
+        }
+    }
+    return [];
+}
+function countTotalFiles(sections) {
+    let count = 0;
+    for (const files of sections.values()) {
+        count += files.length;
+    }
+    return count;
+}
+// === Domain Formatting ===
+function formatDomainLine(name, files) {
+    const cleanName = name
+        .replace(/features\//i, "")
+        .replace(/FEATURES\//i, "")
+        .toLowerCase();
+    const actionFiles = files.filter((f) => f.fileName.includes("action") || f.fileName.includes("actions"));
+    const actionCount = actionFiles.reduce((sum, f) => sum + f.functions.length, 0);
+    const intent = getIntent(cleanName, files);
+    return `${cleanName} — ${intent} (${actionCount} actions)`;
+}
+function getIntent(domain, files) {
+    const allFunctions = files
+        .flatMap((f) => f.functions)
+        .join(" ")
+        .toLowerCase();
+    // Domain-specific intent mapping
+    if (domain === "users") {
+        return "authenticate, edit profile, manage credentials";
+    }
+    if (domain === "orders") {
+        return "create/edit/cancel";
+    }
+    if (domain === "estimates") {
+        return "create/edit/convert";
+    }
+    if (domain === "files") {
+        return "upload/download";
+    }
+    // Fallback: derive from function names
+    const intents = [];
+    if (allFunctions.includes("create"))
+        intents.push("create");
+    if (allFunctions.includes("edit") || allFunctions.includes("update")) {
+        intents.push("edit");
+    }
+    if (allFunctions.includes("delete") || allFunctions.includes("cancel")) {
+        intents.push("cancel");
+    }
+    if (intents.length === 0)
+        return "manage";
+    return intents.slice(0, 3).join("/");
+}

package/dist/formatters/human.d.ts

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

package/dist/formatters/human.js

@@ -0,0 +1,200 @@
+export function formatHuman(data) {
+    const lines = [];
+    lines.push(`📁 Project: ${data.projectType} App`);
+    lines.push("");
+    // Routes - ordered: client, admin, api
+    if (data.routes && data.routes.length > 0) {
+        lines.push("┌─ Routes ─────────────────────────");
+        lines.push("│");
+        const routeGroups = parseRouteGroups(data.routes);
+        const orderedGroups = sortRouteGroups(routeGroups);
+        // Filter out empty groups
+        const filteredGroups = new Map();
+        for (const [key, value] of orderedGroups) {
+            if (value.length > 0) {
+                filteredGroups.set(key, value);
+            }
+        }
+        const groupKeys = [...filteredGroups.keys()];
+        for (let i = 0; i < groupKeys.length; i++) {
+            const group = groupKeys[i];
+            const children = filteredGroups.get(group) || [];
+            const isLast = i === groupKeys.length - 1;
+            const prefix = isLast ? "└──" : "├──";
+            const childPrefix = isLast ? "    " : "│   ";
+            const icon = getRouteIcon(group);
+            const displayGroup = group.split("/")[0];
+            lines.push(`${prefix} ${icon} ${capitalizeFirst(displayGroup)}`);
+            // Consolidate dynamic segments
+            const consolidatedChildren = consolidateRoutes(children);
+            // Show max 5 children
+            const visibleChildren = consolidatedChildren.slice(0, 5);
+            for (const child of visibleChildren) {
+                lines.push(`${childPrefix}/${child}`);
+            }
+            // Remaining as "(other X pages)"
+            if (consolidatedChildren.length > 5) {
+                const remaining = consolidatedChildren.length - 5;
+                const groupName = group.split("/")[0];
+                lines.push(`${childPrefix}(${remaining} more ${groupName} pages)`);
+            }
+        }
+        lines.push("");
+    }
+    // Domains
+    const features = getSectionsByPattern(data.sections, "features");
+    if (features.size > 0) {
+        lines.push("┌─ Domains ────────────────────────");
+        lines.push("│");
+        const featureNames = [...features.keys()];
+        for (let i = 0; i < featureNames.length; i++) {
+            const name = featureNames[i];
+            const cleanName = name.replace(/features\//i, "").toLowerCase();
+            const icon = getDomainIcon(cleanName);
+            const isLast = i === featureNames.length - 1;
+            const prefix = isLast ? "└──" : "├──";
+            lines.push(`${prefix} ${icon} features/${cleanName}`);
+        }
+        lines.push("");
+    }
+    // Infrastructure
+    lines.push("┌─ Infrastructure ─────────────────");
+    lines.push("│");
+    lines.push("├── auth / session");
+    lines.push("├── shared utils");
+    lines.push("└── ui components");
+    lines.push("");
+    return lines.join("\n");
+}
+// === Route Parsing ===
+function parseRouteGroups(routes) {
+    const groups = new Map();
+    let currentTopLevel = "";
+    let currentDynamic = "";
+    for (const route of routes) {
+        const trimmed = route.trim();
+        if (trimmed.startsWith("(") && trimmed.endsWith(")")) {
+            continue;
+        }
+        const depth = route.search(/\S/);
+        if (depth === 0) {
+            currentTopLevel = trimmed;
+            currentDynamic = "";
+            if (!groups.has(currentTopLevel)) {
+                groups.set(currentTopLevel, []);
+            }
+        }
+        else if (depth === 2 && trimmed.startsWith("[")) {
+            // Dynamic segment at first level - create combined key
+            currentDynamic = trimmed;
+            const dynamicKey = `${currentTopLevel}/${currentDynamic}`;
+            if (!groups.has(dynamicKey)) {
+                groups.set(dynamicKey, []);
+            }
+        }
+        else if (currentTopLevel) {
+            if (!isSkippableRoute(trimmed)) {
+                // Add to dynamic group if exists
+                if (currentDynamic && depth > 2) {
+                    const dynamicKey = `${currentTopLevel}/${currentDynamic}`;
+                    const children = groups.get(dynamicKey);
+                    if (children && !children.includes(trimmed)) {
+                        children.push(trimmed);
+                    }
+                }
+                else {
+                    const children = groups.get(currentTopLevel);
+                    if (children && !children.includes(trimmed)) {
+                        children.push(trimmed);
+                    }
+                }
+            }
+        }
+    }
+    return groups;
+}
+function isSkippableRoute(route) {
+    const skip = ["error", "sync", "verify-email", "success", "...nextauth"];
+    const lower = route.toLowerCase();
+    return skip.some((p) => lower.includes(p));
+}
+function sortRouteGroups(groups) {
+    const sorted = new Map();
+    const order = ["client", "admin", "api"];
+    for (const key of order) {
+        for (const [group, children] of groups) {
+            if (group.toLowerCase().includes(key)) {
+                sorted.set(group, children);
+            }
+        }
+    }
+    for (const [group, children] of groups) {
+        if (!sorted.has(group)) {
+            sorted.set(group, children);
+        }
+    }
+    return sorted;
+}
+function consolidateRoutes(routes) {
+    const consolidated = [];
+    const seen = new Set();
+    for (const route of routes) {
+        // Skip dynamic segments
+        if (route.startsWith("[") && route.endsWith("]")) {
+            continue;
+        }
+        const baseName = route.toLowerCase();
+        if (!seen.has(baseName)) {
+            seen.add(baseName);
+            // Check if there's a dynamic child
+            const hasDynamic = routes.some((r) => r.startsWith("[") && r.toLowerCase().includes(baseName.slice(0, -1)));
+            if (hasDynamic) {
+                consolidated.push(`${route} (list, detail)`);
+            }
+            else {
+                consolidated.push(route);
+            }
+        }
+    }
+    return consolidated;
+}
+// === Helpers ===
+function getSectionsByPattern(sections, pattern) {
+    const result = new Map();
+    for (const [key, value] of sections) {
+        if (key.toLowerCase().includes(pattern.toLowerCase())) {
+            result.set(key, value);
+        }
+    }
+    return result;
+}
+function getRouteIcon(group) {
+    const lower = group.toLowerCase();
+    if (lower.includes("client") || lower.includes("user"))
+        return "👤";
+    if (lower.includes("admin"))
+        return "🛠️";
+    if (lower.includes("api"))
+        return "🔌";
+    if (lower.includes("auth") || lower.includes("login"))
+        return "🔐";
+    return "📄";
+}
+function getDomainIcon(name) {
+    if (name.includes("order"))
+        return "📦";
+    if (name.includes("estimate"))
+        return "📋";
+    if (name.includes("file"))
+        return "📁";
+    if (name.includes("user"))
+        return "👤";
+    if (name.includes("auth"))
+        return "🔐";
+    if (name.includes("payment"))
+        return "💳";
+    return "📂";
+}
+function capitalizeFirst(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/dist/formatters/index.d.ts

@@ -1,2 +1,4 @@
 export { formatMarkdown } from "./markdown.js";
-export { formatAI } from "./ai.js";
+export { formatAIOptimized } from "./ai-optimized.js";
+export { formatRaw } from "./raw.js";
+export { formatHuman } from "./human.js";

package/dist/formatters/index.js

@@ -1,2 +1,4 @@
 export { formatMarkdown } from "./markdown.js";
-export { formatAI } from "./ai.js";
+export { formatAIOptimized } from "./ai-optimized.js";
+export { formatRaw } from "./raw.js";
+export { formatHuman } from "./human.js";

package/dist/formatters/raw.d.ts

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

package/dist/formatters/raw.js

@@ -0,0 +1,47 @@
+export function formatRaw(data) {
+    const lines = [];
+    lines.push(`# ${data.projectType} Project Context`);
+    lines.push("");
+    // Routes
+    if (data.routes && data.routes.length > 0) {
+        lines.push("## Routes");
+        lines.push("");
+        for (const route of data.routes) {
+            lines.push(`- ${route}`);
+        }
+        lines.push("");
+    }
+    // Sections
+    for (const [sectionName, files] of data.sections) {
+        if (sectionName === "_root")
+            continue;
+        if (files.length === 0)
+            continue;
+        lines.push(`## ${sectionName}`);
+        lines.push("");
+        for (const file of files) {
+            const exports = getExportsSummary(file);
+            if (exports) {
+                lines.push(`- ${file.fileName}: ${exports}`);
+            }
+        }
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function getExportsSummary(file) {
+    const parts = [];
+    if (file.functions.length > 0) {
+        parts.push(file.functions.map((f) => `${f}()`).join(", "));
+    }
+    if (file.constants.length > 0) {
+        parts.push(file.constants.join(", "));
+    }
+    if (file.types.length > 0) {
+        parts.push(file.types.map((t) => `type ${t}`).join(", "));
+    }
+    if (file.interfaces.length > 0) {
+        parts.push(file.interfaces.map((i) => `interface ${i}`).join(", "));
+    }
+    return parts.join(" | ");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eloquence98/ctx",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Generate AI-ready context from your codebase. One command, zero config.",
   "type": "module",
   "bin": {