npm package: @mithun_krishnan/code-xray
Description: AI-powered codebase analyser — design patterns, coding standards, class summaries, and improvement suggestions
Latest version: 0.1.0

# CodeXRay

AI-powered codebase analyser that detects design patterns, assesses coding standards, summarises classes, and generates improvement suggestions. Built for **new-joiner developers** to understand a codebase quickly.

## How It Works

CodeXRay uses a **hybrid architecture**:

1. **`codexray init`** — runs in the terminal. Scans your project structure, detects tech stack and modules, creates configuration files. No AI needed.
2. **`/codexray:analyse`** — runs in VS Code Copilot Chat. Uses GitHub Copilot's LM to analyse each module for patterns, standards, and class summaries. No API key needed.
3. **`/codexray:report`** — runs in Copilot Chat. Generates executive summary, onboarding guide, and health scores from analysis data.
4. **`/codexray:suggest`** — runs in Copilot Chat. Generates prioritised improvement suggestions and quick wins.

## Installation

### Option A: Install from npm (recommended)

```bash
npm install -g @mithun_krishnan/code-xray
```

Then use from any project:

```bash
cd /path/to/your/project
codexray init
```

### Option B: Clone and link

```bash
git clone git@github.com:munnik486_comcast/CodeXray.git
cd CodeXray
npm install && npm run build
npm link
```

### Copilot Chat Commands Setup

To use `/codexray:analyse`, `/codexray:report`, and `/codexray:suggest` in Copilot Chat, copy these folders into your target project:

```
.github/prompts/codexray-analyse.prompt.md
.github/prompts/codexray-report.prompt.md
.github/prompts/codexray-suggest.prompt.md
.github/skills/codexray/
```

These prompt files tell Copilot Chat how to run the analysis. They're project-level, not part of the npm package.

## Quick Start

### 1. Install

```bash
npm install
npm run build
```

### 2. Initialise

```bash
npx codexray init
```

This scans your project and creates:
- `codexray/config.yaml` — configuration (edit to adjust scope)
- `codexray/overview.md` — project overview
- `codexray/structure.md` — module map and directory tree

### 3. Analyse

Open VS Code Copilot Chat and run:

```
/codexray:analyse
```

This generates per-module analysis in `codexray/modules/`:
- `summary.md` — what the module does
- `classes.md` — per-class/function summaries
- `patterns.md` — design patterns found

Plus codebase-wide files:
- `codexray/patterns.md` — pattern inventory
- `codexray/standards.md` — coding conventions

### 4. Report (optional)

```
/codexray:report
```

Generates `codexray/report/summary.md`, `onboarding.md`, `health.md`.

### 5. Suggest (optional)

```
/codexray:suggest
```

Generates `codexray/suggestions/improvements.md`, `quick-wins.md`.

Scope to a module: `/codexray:suggest auth`

## Configuration

Edit `codexray/config.yaml`:

```yaml
version: 1
include:
  - src/**
exclude:
  - '**/test/**'
  - '**/node_modules/**'
depth: full          # full | summary | quick
modules: []          # auto-detected if empty
language: typescript  # auto-detected
framework: ''        # auto-detected
```

### Depth Levels

| Depth | Module Files | Top-Level Files |
|-------|-------------|-----------------|
| `full` | summary + classes + patterns | overview + structure + patterns + standards |
| `summary` | summary + patterns | overview + structure + patterns + standards |
| `quick` | none | overview + structure only |

## Output Structure

```
codexray/
├── config.yaml        # Configuration
├── .lastrun           # Last analysis state (for diff-aware reruns)
├── overview.md        # Project overview
├── structure.md       # Module map + directory tree
├── patterns.md        # Codebase-wide design patterns
├── standards.md       # Coding conventions
├── modules/
│   ├── <module>/
│   │   ├── summary.md
│   │   ├── classes.md
│   │   └── patterns.md
│   └── ...
├── report/            # Generated by /codexray:report
│   ├── summary.md
│   ├── onboarding.md
│   └── health.md
└── suggestions/       # Generated by /codexray:suggest
    ├── improvements.md
    └── quick-wins.md
```

## Supported Languages

JavaScript/TypeScript, Java, Kotlin, Go, Rust, Python, PHP, Ruby, Elixir, C#, C/C++, Swift, Dart, Lua, R, Scala, Vue, Svelte.

## CLI Alternative

If you have a GitHub PAT or OpenAI API key, you can add an `ai` section to `config.yaml` and use the CLI directly:

```yaml
ai:
  type: github-copilot   # or: openai, ollama
  model: openai/gpt-4.1
  apiKey: ''              # or set GITHUB_TOKEN env var
```

Then run `codexray analyse`, `codexray report`, `codexray suggest` in the terminal.

## Requirements

- Node.js 18+
- VS Code with GitHub Copilot (for Copilot Chat commands)