context-it

High‑signal code context & function signature extraction for multi‑language repositories (TypeScript / JavaScript, Go, Java, Python, Rust, PHP)

📦 Installation

Global install:

npm i -g @saintno/context-it

Verify:

ctx --version

✨ What It Does

context-it walks your source tree, detects supported source files, extracts function & method signatures (optionally full source), and produces a clean, uniform Markdown dossier you can drop into an AI prompt, code review, or architecture discussion.

Core goals:

• Minimize noise, maximize semantic relevance
• Normalize cross‑language function representation
• Provide optional full file source on demand
• Be fast (Bun runtime + lightweight parsing heuristics)
• Be extensible via pluggable parsers

✅ Supported Languages

| Language | Extensions | Parser | |----------|------------|--------| | TypeScript / JavaScript | .ts, .tsx, .js, .jsx | TypeScriptParser | | Go | .go | GoParser | | Java | .java | JavaParser | | Python | .py | PythonParser | | Rust | .rs | RustParser | | PHP | .php | PhpParser |

🚀 Quick Start

Install dependencies:

bun install

Generate function signatures for current directory (copied to clipboard):

ctx

Generate full code + signatures for specific paths:

ctx ./src/core ./src/tests

Output to a file:

ctx ./src --output CODE_CONTEXT.md

Signatures only (no full source embedding):

ctx -f

Verbose mode (also prints the Markdown to stdout):

ctx -f -v ./src/core/processors

🧠 Output Format

A file section looks like:

## src/core/processors/tsParser.ts
### Function Signatures
```typescript
function identity<T>(value: T): T
[Container] map<U>(fn: (value: T) => U): U
```
---

Class methods are prefixed with [ClassName]. Return types follow a trailing colon. Parameters show name: type where available.

🏗 Architecture Overview

| Layer | Responsibility | Key File | |-------|----------------|----------| | CLI | Argument parsing, orchestration | src/cli/index.ts | | Parser abstraction | Shared interface & lifecycle | BaseParser | | Language parsers | Heuristic signature extraction | (See table above) | | Markdown generation | Uniform document assembly | MarkdownGenerator | | File traversal | Recursive, filter by extension | fileWalker | | Types | Shared structures | types.ts |

Parsers register themselves via:

MarkdownGenerator.registerParser(new TypeScriptParser())

(See initialization in src/cli/index.ts)

🔍 Parsing Philosophy

Rather than full AST fidelity (expensive / brittle per language), parsers aim for 90–95% semantic accuracy optimized for:

• AI prompt priming
• Quick capability overviews
• Architectural summarization

Examples:

• GoParser uses a lightweight state machine to handle nested generics & multi‑return forms.
• TypeScriptParser avoids typescript dependency, scanning top‑level depth, supporting forwardRef, alias exports, generics, and class methods.
• PhpParser synthesizes method context and normalizes variadic / union / nullable forms.

🧪 Test Coverage

All language parsers include focused test suites under src/tests/ verifying:

• Grouped / complex parameters
• Class / receiver / trait / interface methods
• Generics & variadic forms
• Comment stripping robustness
• Multi‑return or union types
• Edge constructs (e.g. forwardRef wrappers in TypeScript, channel directions in Go)

Run:

bun test

🛠 Extending with a New Language

1. Create a parser implementing BaseParser methods in src/core/processors/.
2. Implement:
   • extensions
   • extractFunctionMatches(code)
   • parseFunctionSignature(match)
   • parseParameters(str)
3. Register it in the CLI bootstrap (or provide dynamic plugin discovery).
4. Add a test file under src/tests/.
5. (Optional) Add language → markdown alias in MarkdownGenerator if new.

Template snippet:

export class FooParser extends BaseParser {
  extensions = [".foo"];

  protected extractFunctionMatches(code: string): string[] {
    // return raw declaration fragments
    return [];
  }

  protected parseFunctionSignature(decl: string): FunctionSignature | null {
    return {
      name: "helloFoo",
      parameters: [],
      returnType: "Foo"
    };
  }

  protected parseParameters(paramsStr: string): Param[] {
    return [];
  }

  protected extractReturnType(_decl: string): string | undefined {
    return undefined;
  }
}

📋 CLI Options

| Flag | Description | Default | |------|-------------|---------| | paths... | One or more files / directories | process.cwd() | | -i, --input <paths> | (Deprecated) Comma-separated paths | – | | -o, --output <file> | Write Markdown to file | Clipboard | | -f, --functions-only | Exclude full source blocks | false | | -v, --verbose | Echo generated markdown | false | | -h, --help | Show help | – |

📑 Example Signature Normalization

| Original Code | Normalized Output | |---------------|------------------| | func (s *Service) Start() error | [Service] Start(): error | | function greet(name: string = "Hi"): string | function greet(name: string): string | | public <R> map(Function<T,R> f) | [Container] map<R>(f: Function<T, R>): R | | fn process(data: Vec<String>) -> Result<(), Error> | function process(data: Vec<String>): Result<(), Error> |

📌 Design Principles

• Deterministic formatting (stable diff‑ability)
• Shallow parsing where “good enough” beats full grammar
• Extensibility first via registration API
• Clipboard‑first UX for frictionless prompt assembly
• Language parity in signature style

🧩 Roadmap Ideas

• Optional inline docstring / comment summarization
• Plugin loader (e.g. ~/.context-it/parsers)
• Graph mode: call relationships (best‑effort)
• Incremental / cached runs
• HTML export with navigation index
• Embeddings vector export (LLM retrieval)

🤝 Contributing

1. Fork & branch
2. Add / modify parser or generator
3. Include / update tests under src/tests
4. Run bun test
5. Open PR with rationale

🐛 Reporting Issues

Please include:

• Reproducer snippet
• Expected vs actual signature
• Language & version
• Parser name (e.g. [TypeScriptParser](src/core/processors/tsParser.ts:1))

⚙️ Performance Notes

• Bun’s FS + fast regex scanning keeps large trees quick
• TypeScript parsing avoids AST building overhead
• Go & Rust use single‑pass scans for function tokens
• Memory profile stays proportional to concurrently processed file set

🔒 Limitations

• Does not fully parse advanced grammar edge cases (e.g. ultra‑complex nested generics with constraints intersections)
• Formatting assumes UTF‑8 & normalized line endings
• Multi‑language mixed embedded DSLs not yet parsed (e.g. SQL inside strings)
• Return type inference is not performed if omitted in original source

🧾 License

MIT (or your chosen license—add one if missing). Add a LICENSE file if you intend to distribute publicly.

🙌 Acknowledgments

• Bun for speed & DX
• Radix / React patterns inspired forwardRef support
• Community language syntax references

📣 Final Tip

Run with -f first to scope relevance. If you need deeper inspection on a subset, re-run including full source only for those paths. This keeps prompt size lean and focus tight.

Happy context harvesting!