🚀 Why AI Context Builder?

When feeding code to LLMs (Claude, GPT, Gemini, DeepSeek) for refactoring, debugging, architecture reviews, or migrations, standard approaches fail:

• Copy-pasting individual files leaves out essential interfaces, models, and constructor dependencies.
• Dumping entire repositories blows through context limits and confuses the model with irrelevant noise.
• Naive AI summarization tools truncate methods, replace real code with ellipses (// ...rest unchanged), and strip critical implementation details.

AI Context Builder solves this:

• 🛡️ Complete Source Files: Every included file is included in full. Never summarized, truncated, pseudo-coded, or replaced with ellipses.
• 📁 Preserve Original Relative Paths: Relative workspace paths (e.g. src/Application/Customers/CustomerService.cs) are preserved verbatim. Absolute paths are never exposed.
• 📄 One Output Artifact: The entire dependency-aware context lives in exactly one self-contained, beautifully formatted Markdown document (*-context.md).
• ⚖️ No Hidden Limits: When no token budget is specified, all eligible transitive dependencies are traversed without artificial depth or file-count caps.
• 🔒 100% Local & Private: Runs strictly locally. No source code upload, no external API keys required, and zero telemetry.

🧩 Architecture

Visual Studio Code Extension / Visual Studio VSIX / CI / CLI
                             |
                             v
               Context Orchestrator CLI (`aicontext`)
                             |
             +---------------+---------------+
             |                               |
        Shared Core (.NET 10):          Workers (Language-Neutral Protocol):
        - Neutral Dependency Graph       - In-Process .NET Worker (C#, VB.NET, Razor, Blazor, Roslyn)
        - Upward Workspace Discovery     - Node.js Worker (TypeScript Compiler API 5.9, React, Angular, Vue, HTML, SCSS)
        - Deterministic Scoring Engine   - Python Worker (AST, tokenize, import analysis)
        - Token Budget Selector          - Java & Go Analyzers (Project metadata & syntax)
        - Secret Preflight Scanner
        - Safe Markdown Generator

The orchestrator is implemented in .NET 10 / C# for instant native CLI execution and in-process Roslyn semantic analysis, while dedicated workers communicate via standard I/O using a versioned JSON protocol (protocolVersion: "1.0").

🌐 Supported Languages & Capability Matrix

Every analyzer explicitly discloses its capability level in the generated Markdown metadata:

💻 CLI Quickstart

Build the Solution

dotnet build

The compiled CLI wrapper is located at ./bin/aicontext.

Usage Examples

# 1. Analyze C# Service with unlimited token budget
./bin/aicontext generate --file src/Application/Customers/CustomerService.cs

# 2. Analyze Angular Component with HTML template and SCSS partials
./bin/aicontext generate --file src/app/customers/customer.component.ts --framework angular

# 3. Analyze React Component with a 64k token budget and auto comment stripping
./bin/aicontext generate --file src/components/CustomerPage.tsx --max-tokens 64000 --comments auto

# 4. Analyze Python module and output machine-readable JSON metadata
./bin/aicontext generate --file app/services/customer_service.py --format json

# 5. Check active language workers
./bin/aicontext check-workers

Options Reference

Usage:
  aicontext generate --file <path> [options]
  aicontext check-workers

Required:
  --file <path>                  Target source file to analyze

Options:
  --workspace <path>             Workspace root directory boundary
  --project <path>               Explicit project file (.csproj, tsconfig.json, etc.)
  --symbol <qualified-name>      Specific class, function, or symbol to select as root
  --output <path>                Destination Markdown file path
  --max-tokens <int>             Token budget (omitted means unlimited)
  --max-depth <int>              Maximum dependency traversal depth (omitted means unlimited)
  --comments preserve|remove|auto Comment preservation policy (default: preserve)
  --language <lang>              Force specific language analyzer
  --framework <fw>               Force specific framework adapter
  --analysis-level <level>       Best, Semantic, SyntaxAware, ImportGraph
  --task <text>                  Custom prompt task heading
  --include-tests <bool>         Include test files (default: false)
  --include-generated <bool>     Include generated files (default: false)
  --include-attributes <bool>    Include attributes/decorators (default: false)
  --include-companions <bool>    Include companion templates/styles (default: true)
  --include-config <bool>        Include configuration files (default: true)
  --save <bool>                  Write result to file (default: true)
  --copy <bool>                  Copy result to clipboard (default: false)
  --format text|json             Output format (default: text)
  --omit-timestamp               Omit generation timestamp for deterministic golden testing
  --verbose                      Enable verbose diagnostic logging
  --help                         Display help message
  --version                      Display version information

🔌 VS Code Extension Guide

Generate clean, dependency-aware AI prompts directly inside your editor with single-click ease.

How to Use

1. Right-Click in the File Explorer (Fastest)

• Right-click any source file in the Explorer tree (.cs, .ts, .tsx, .razor, .py, .java, .go, etc.).
• Click AI Prompt: Generate from Current File.
• The extension automatically traverses direct and transitive dependencies, links companion templates/styles, strips internal noise, and opens the clean prompt in a new editor tab ready to copy into your AI chat.

2. Right-Click Inside Code (Targeted Symbol)

• Place your cursor on any class name, interface, method, or function.
• Right-click and choose AI Prompt: Generate from Symbol at Cursor.
• Generates a focused prompt centered on that specific symbol and its required dependency tree.

3. Command Palette (Ctrl+Shift+P / Cmd+Shift+P)

• Press Ctrl+Shift+P and type AI Prompt to see all available actions.
• Choose AI Prompt: Generate with Options... to open an interactive QuickPick wizard to set:
  • Token budget limits (e.g. 16k, 32k, 64k, 128k)
  • Maximum traversal depth
  • Comment stripping policy (Preserve, Remove, or Auto)
  • Task description to pre-populate for the consuming AI

Commands Reference

🎥 Adding Animated GIF Demos to the Marketplace & GitHub

The VS Code Marketplace and GitHub READMEs support animated .gif files natively! To show an animated walkthrough:

1. Record a short 5–10 second clip of yourself:
   • Right-clicking a file in the VS Code explorer.
   • Selecting AI Prompt: Generate from Current File.
   • Showing the clean markdown prompt opening in the editor and pasting it into your AI chat.
2. Recommended Free Screen-to-GIF Tools:
   • Linux: Peek (sudo apt install peek) or Kooha
   • Windows: ScreenToGif (super clean editor)
   • macOS: Kap or Gifski
3. Drop the GIF into docs/images/demo.gif and embed it in your README.md:

   ![AI Prompt Generator in Action](https://github.com/SitholeWB/ai-prompt-context-builder/raw/HEAD/docs/images/demo.gif)
   

Extension Settings (aiPromptContextBuilder.*)

Customize default behavior in Settings (Ctrl+, -> search aiContextBuilder):

{
  "aiPromptContextBuilder.executablePath": "aicontext",
  "aiPromptContextBuilder.defaultTokenBudget": null,
  "aiPromptContextBuilder.commentMode": "Preserve",
  "aiPromptContextBuilder.includeCompanionFiles": true,
  "aiPromptContextBuilder.includeTests": false,
  "aiPromptContextBuilder.includeGeneratedFiles": false,
  "aiPromptContextBuilder.openAfterGeneration": true
}

🔒 Security & Privacy Guarantee

• Zero Cloud Leakage: No remote AI API calls, telemetry, or external network requests.
• Preflight Secret Scanner: Inspects candidate files before inclusion for private keys, AWS/Slack/GitHub keys, and database connection strings with passwords. Secret values are never printed to logs or Markdown files.
• Path Traversal Protection: Canonicalizes all file paths and enforces strict workspace boundaries. Symlinks escaping the workspace and .git internals are automatically rejected.

🧪 Testing & Debugging

The repository features comprehensive automated acceptance tests and step-by-step developer debugging tools:

• Run Acceptance Tests: dotnet run --project tests/AiPromptContextBuilder.Tests.csproj
• VS Code F5 Debugging: Pre-configured .vscode/launch.json for stepping through CLI execution and tests.
• Detailed Guide: See docs/testing-and-debugging.md for worker pipe debugging, AST inspection, and golden-file regression workflows.

📚 Documentation Index

• Architecture Design & Data Flow
• Language Adapter Contract
• Dependency Semantics & Importance Scoring
• Security & Workspace Boundaries
• Supported Languages Reference
• Testing and Debugging Guide
• Visual Studio Extension Plan (VSIX)
• Known Limitations & Transparent Disclosures

👤 Author & Maintainer

Welcome Bonginhlahla Sithole
📍 South Africa, KwaZulu Natal
🔗 GitHub: @SitholeWB
📦 VS Code Marketplace: sitholewb

📄 License

Distributed under the MIT License.