Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
chore: remove docs/map-update directory (#86)
Tanner Kocherdfefda2c7cc3
diff --git a/docs/map-update/README.md b/docs/map-update/README.mddeleted file mode 100644index 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.mddeleted file mode 100644index 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.