Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

chore: remove docs/map-update directory (#86)

Tanner Kocherdfefda2c7cc3
diff --git a/docs/map-update/README.md b/docs/map-update/README.md
deleted file mode 100644
index 2cbea245..00000000
--- a/docs/map-update/README.md
+++ /dev/null
@@ -1,100 +0,0 @@
-# Map Update — Feature Overview
-
-This document describes the `ix map` overhaul and the two new analysis commands (`ix smells`, `ix subsystems`) added in the `feature/map-update` branch.
-
-## What Changed
-
-### `ix map` — Progress Bar + Timing
-
-The map command now shows a live progress bar while computing the architectural map and prints ingest/map timing on completion.
-
-```
- Computing map... ████████████░░░░░░░░░░░░░ 51%
- ingest 1240ms · map 3820ms
-```
-
-Key changes in `ix-cli/src/cli/commands/map.ts`:
-- Exponential-decay progress bar using `setInterval`
-- Ingest and map durations printed to stderr (text mode only)
-- `--full` flag preserved for bypassing incremental map cache
-
-### `ix smells` — Architecture Smell Detection
-
-Runs graph-query-based smell detection and stores results as versioned claims on `File` nodes.
-
-```bash
-ix smells # run detection with default thresholds
-ix smells --format json # machine-readable output
-ix smells --list # show previously stored claims
-ix smells --god-module-chunks 15 # tune threshold
-```
-
-**Detected smells:**
-
-| Smell | Field | Description |
-|-------|-------|-------------|
-| Orphan file | `has_smell.orphan_file` | File with no import/call connections |
-| God module | `has_smell.god_module` | File with high chunk count or fan-in/out |
-| Weak component member | `has_smell.weak_component_member` | File connected to very few others |
-
-Claims are stored with `inference_version=smell_v1` and are versioned — re-running retires old claims before writing new ones.
-
-**Backend:** `SmellService.scala` + `SmellRoutes.scala`
-
-### `ix subsystems` — Subsystem Health Scoring
-
-Scores each architectural region produced by `ix map` on a 0–1 health scale.
-
-```bash
-ix subsystems # compute and store scores
-ix subsystems --list # show stored scores
-ix subsystems --level 2 # filter to subsystem level
-ix subsystems --format json # machine-readable
-```
-
-**Health score formula:**
-
-```
-health = 0.4 × (1 − smell_rate)
- + 0.3 × tanh(chunk_density / 5)
- + 0.3 × confidence
-```
-
-| Signal | Meaning |
-|--------|---------|
-| `smell_rate` | Fraction of files in the region with smell claims (lower = healthier) |
-| `chunk_density` | Avg `CONTAINS_CHUNK` edges per file (higher = richer structure) |
-| `confidence` | MapService cohesion/boundary ratio score |
-
-Claims stored with `inference_version=subsystem_v1`.
-
-**Backend:** `SubsystemService.scala` + `SubsystemRoutes.scala`
-
-## New Files
-
-| File | Purpose |
-|------|---------|
-| `ix-cli/src/cli/commands/smells.ts` | CLI command for smell detection |
-| `ix-cli/src/cli/commands/subsystems.ts` | CLI command for subsystem scoring |
-| `memory-layer/.../smell/SmellService.scala` | Smell detection logic (AQL queries + claim storage) |
-| `memory-layer/.../smell/SubsystemService.scala` | Subsystem scoring logic |
-| `memory-layer/.../api/SmellRoutes.scala` | HTTP routes for smell endpoints |
-| `memory-layer/.../api/SubsystemRoutes.scala` | HTTP routes for subsystem endpoints |
-
-## Recommended Workflow
-
-After running `ix map`, use the new commands to get a quality picture:
-
-```bash
-ix map # build architectural map
-ix smells --format json # find problem files
-ix subsystems --format json # score each region
-```
-
-Pipe results into `ix decide` to record findings:
-
-```bash
-ix decide "Refactor auth module" \
- --rationale "god_module smell + health score 0.31" \
- --affects AuthModule
-```
diff --git a/docs/map-update/map-experience-improvements.md b/docs/map-update/map-experience-improvements.md
deleted file mode 100644
index 456517ba..00000000
--- a/docs/map-update/map-experience-improvements.md
+++ /dev/null
@@ -1,393 +0,0 @@
-# ix map Experience Improvements — Full Implementation Spec
-
----
-
-## TL;DR (Start Here)
-
-**Implement Phase 1 only (CLI renderer rewrite).**
-
-Do:
-
-* Replace flat output with tree layout
-* Group modules under subsystems
-* Add health summary line
-* Preserve JSON output exactly
-
-Do NOT:
-
-* Modify backend
-* Change API contracts
-
-Primary file:
-
-* `ix-cli/src/cli/commands/map.ts`
-
----
-
-## Goals
-
-Improve `ix map` across 3 dimensions:
-
-1. **Clarity** → readable, hierarchical output
-2. **Exploration** → drill into subsystems/modules
-3. **Performance** → avoid unnecessary recomputation
-
-All changes must be:
-
-* Incremental
-* Backwards compatible
-* Independently shippable
-
----
-
-## Current Behavior (Simplified)
-
-Pipeline:
-
-```
-ix map
- → ingest
- → POST /v1/map
- → build graph + cluster (Louvain)
- → persist regions
- → return JSON
- → CLI renders flat table
-```
-
----
-
-## Data Model (IMPORTANT)
-
-The CLI receives:
-
-```json
-{
- "regions": [
- {
- "id": "r1",
- "label": "Cli / Client",
- "level": 2,
- "parent_id": null,
- "file_count": 105,
- "confidence": 0.72,
- "is_cross_cutting": false
- },
- {
- "id": "r2",
- "label": "Queries",
- "level": 1,
- "parent_id": "r1",
- "file_count": 10,
- "confidence": 0.66,
- "is_cross_cutting": true
- }
- ]
-}
-```
-
-Levels:
-
-* 3 = System
-* 2 = Subsystem
-* 1 = Module
-
----
-
-## Problems
-
-### Output
-
-* Flat structure → no hierarchy
-* Hard to answer “what’s inside X?”
-* Truncation breaks readability
-* Cross-cutting unclear
-* Verbose mode overwhelming
-
-### Exploration
-
-* No drill-down
-* No file visibility
-* No explain integration
-
-### Performance
-
-* Always recomputes map
-* Always persists
-* Always runs ingest
-
----
-
-## Target Design
-
----
-
-## 1. Default Output (Tree Layout)
-
-Replace flat output with:
-
-```
-Architectural Map 225 files · 4 subsystems · 14 modules
-
- Cli / Client · 105 files · Moderate (72%)
- ├─ Cli / Client 53 files Well-defined
- ├─ Cli / Github 22 files Moderate
- ├─ Queries 10 files Moderate ⚠
- ╰─ Role 5 files Fuzzy ⚠
-
- Context · 56 files · Moderate (65%)
- ├─ Ingestion 12 files Well-defined
- ╰─ Model 19 files Fuzzy
-```
-
----
-
-## 2. Health Summary Line
-
-Add at top:
-
-```
-3 well-defined · 8 moderate · 3 fuzzy · 3 cross-cutting
-```
-
----
-
-## 3. Verbose Mode
-
-Keep tree, add right-aligned metrics:
-
-```
-Cli / Client · 105 files conf=72% br=651 xcut=0.03
-├─ Queries 10 files conf=66% xcut=0.15 ⚠
-```
-
----
-
-## 4. Rendering Algorithm (IMPLEMENT THIS)
-
-```ts
-const subsystems = regions.filter(r => r.level === 2);
-const modules = regions.filter(r => r.level === 1);
-
-const modulesByParent = groupBy(modules, m => m.parent_id);
-
-for (const subsystem of subsystems) {
- printSubsystem(subsystem);
-
- const children = modulesByParent[subsystem.id] || [];
-
- children.forEach((child, i) => {
- const isLast = i === children.length - 1;
- const prefix = isLast ? "╰─" : "├─";
- printModule(child, prefix);
- });
-}
-```
-
----
-
-## 5. Rendering Rules
-
-* No label truncation
-* Use terminal width (`process.stdout.columns`)
-* Indentation = 2 spaces
-* Tree chars: `├─`, `╰─`
-* Cross-cutting = `⚠`
-* Confidence shown as % in headers
-
----
-
-## 6. Flags (Future Phases)
-
-### `--subsystem <name>`
-
-Show only one subsystem + modules
-
-### `--module <name>`
-
-Show module + files
-
-### `--files`
-
-Expand full file list
-
-### Positional shorthand
-
-```
-ix map Ingestion
-ix map "Cli / Client"
-```
-
----
-
-## 7. File Listing (Future)
-
-Add to backend:
-
-```json
-"member_paths": ["src/cli/map.ts"]
-```
-
-Only for level-1 regions.
-
----
-
-## 8. Explain Integration (Future)
-
-### CLI Prompt Template
-
-```
-Explain the following subsystem:
-
-Name: {label}
-Files: {file_count}
-Confidence: {confidence}
-Child modules: {children}
-
-Boundary files:
-{top_files}
-
-Smells:
-{smells}
-
-Summarize:
-1. Purpose
-2. Structure quality
-3. Risks
-```
-
----
-
-## 9. Performance Plan
-
-### Priority
-
-1. Cache map by graph revision (HIGH)
-2. Skip persist if unchanged (HIGH)
-3. Skip ingest if fresh (MEDIUM)
-4. Optimize parent wiring (LOW)
-
----
-
-### 9a. Cache Map
-
-If `map_rev == graph_rev` → return stored map
-
----
-
-### 9b. Skip Persist
-
-```
-if storedRev == currentRev:
- skip write
-```
-
----
-
-### 9c. Skip Ingest
-
-If freshness = false → skip ingest
-
----
-
-## 10. Implementation Phases
-
----
-
-### Phase 1 — CLI Output (DO THIS FIRST)
-
-Scope:
-
-* Tree rendering
-* Health summary
-* Verbose redesign
-
-Files:
-
-* `map.ts`
-
-Constraints:
-
-* JSON output unchanged
-* No backend changes
-
----
-
-### Phase 2 — Drill-down
-
-* Add flags
-* Add member_paths
-
----
-
-### Phase 3 — Explain
-
-* CLI context builder
-* Call explain endpoint
-
----
-
-### Phase 4 — Performance
-
-* Cache map
-* Skip persist
-* Skip ingest
-
----
-
-### Phase 5 — Future
-
-* Incremental Louvain
-* `/map/explain` endpoint
-* TUI interface
-
----
-
-## 11. Acceptance Criteria (Phase 1)
-
-Must pass:
-
-* `ix map` → tree structure
-* `ix map --verbose` → tree + metrics
-* `ix map --level 3` → systems only
-* `ix map --level 1` → modules only
-* `ix map --format json` unchanged
-* No truncation up to 40 chars
-* Health summary present
-
----
-
-## 12. Risks
-
-| Risk | Mitigation |
-| --------------- | --------------- |
-| Narrow terminal | fallback layout |
-| Name ambiguity | disambiguation |
-| Cache stale | `--full` flag |
-| Payload size | level-1 only |
-| Explain quality | improve prompt |
-
----
-
-## 13. Key Files
-
-* CLI: `ix-cli/src/cli/commands/map.ts`
-* API: `MapRoutes.scala`
-* Service: `MapService.scala`
-* Graph: `MapGraphBuilder.scala`
-* Clustering: `LouvainClustering.scala`
-
----
-
-## Final Instruction for Implementer
-
-Start with Phase 1.
-
-Do not over-engineer.
-
-Focus on:
-
-* Correct grouping
-* Clean tree rendering
-* Zero regression in JSON output
-
-Then stop and validate before continuing.