docs: add sprint 36-40 plans and codehealth brief

2026-02-17 20:37:54 -07:00
parent 3dd2ef2577
commit 19880d6cbc
6 changed files with 593 additions and 0 deletions
--- a/sprint_codehealth_A.md
+++ b/sprint_codehealth_A.md
@@ -0,0 +1,155 @@
+# Sprint Code-Health-A: Dispatch & Duplication Elimination
+
+> **Goal:** Eliminate the worst semantic-density killers — the copy-paste dispatch chains
+> and duplicated generator methods that account for ~2,000+ lines of redundant code.
+>
+> **Prerequisite:** None. This sprint can run independently.
+> **Estimated steps:** 12–15
+> **Estimated tests:** 30–40
+
+---
+
+## Context
+
+Three major duplication sites inflate the codebase:
+
+1. **ProjectionGenerator.h `dispatchGenerate()`** — 220-line if-else chain dispatching
+   ~90 annotation/node types by string comparison. Every new annotation type adds 2 lines.
+2. **CompactAST.h `extractSemanticSummary()`** — 340-line if-else chain doing the same
+   string-match + static_cast + JSON serialization for every annotation type.
+3. **Generator `emitBody()` duplication** — identical 12-line function copy-pasted into
+   RustGenerator, JavaGenerator, JavaScriptGenerator, and every other generator.
+
+---
+
+## Steps
+
+### Step 1–3: Annotation Self-Registration
+
+**Goal:** Each annotation type registers itself so dispatch chains become table lookups.
+
+**Step 1: AnnotationRegistry infrastructure**
+- Create `AnnotationRegistry.h` with:
+  ```cpp
+  using AnnotationFactory = std::function<ASTNode*(const std::string&)>;
+  using AnnotationVisitor = std::function<std::string(const ProjectionGenerator*, const ASTNode*)>;
+  using AnnotationSerializer = std::function<nlohmann::json(const ASTNode*)>;
+
+  class AnnotationRegistry {
+      static auto& visitors() { static std::unordered_map<std::string, AnnotationVisitor> m; return m; }
+      static auto& serializers() { static std::unordered_map<std::string, AnnotationSerializer> m; return m; }
+  public:
+      static void registerVisitor(const std::string& type, AnnotationVisitor v);
+      static void registerSerializer(const std::string& type, AnnotationSerializer s);
+      static std::string dispatch(const ProjectionGenerator* gen, const ASTNode* node);
+      static nlohmann::json serialize(const ASTNode* node);
+  };
+  ```
+- Tests: registry lookup works, unknown type returns fallback string
+
+**Step 2: Migrate ProjectionGenerator dispatch (Part 1 — Subjects 1–5)**
+- For each annotation in Subjects 1–5 (Memory, Type System, Concurrency, Scope, Shims):
+  add a static registration block in the annotation's own header
+- Replace corresponding if-else branches in `dispatchGenerate()` with `AnnotationRegistry::dispatch()`
+- Tests: all existing step tests for these annotations still pass, dispatch returns same results
+
+**Step 3: Migrate ProjectionGenerator dispatch (Part 2 — Subjects 6–9 + Core + AST nodes)**
+- Complete the migration for remaining subjects (Optimization, Meta, Policy, Workflow, Semantic Core)
+- Migrate non-annotation AST node dispatch (ClassDeclaration, EnumDeclaration, SQL nodes, etc.)
+- Delete the entire 220-line if-else chain, replace with:
+  ```cpp
+  std::string dispatchGenerate(const ProjectionGenerator* gen, const ASTNode* node) {
+      return AnnotationRegistry::dispatch(gen, node);
+  }
+  ```
+- Tests: full dispatch regression (all 90+ types), empty node, unknown type
+
+### Step 4–5: CompactAST Serialization Refactor
+
+**Step 4: Add `toCompactJson()` virtual method to annotation base**
+- Add virtual `nlohmann::json toCompactJson() const { return {}; }` to `ASTNode` or annotation base
+- Implement for the first 20 annotation types (Subjects 1–3)
+- Tests: round-trip: serialize → deserialize → compare for each type
+
+**Step 5: Complete CompactAST migration**
+- Implement `toCompactJson()` for remaining annotation types (Subjects 4–9 + Core)
+- Replace `extractSemanticSummary()` 340-line chain with:
+  ```cpp
+  json extractSemanticSummary(const ASTNode* node) {
+      json sem;
+      for (auto* a : node->getChildren("annotations")) {
+          json j = a->toCompactJson();
+          if (!j.empty()) sem[a->shortName()] = j;
+      }
+      return sem;
+  }
+  ```
+- Tests: equivalence with old output for all annotation types, empty annotations, mixed types
+
+### Step 6–7: Generator Base Class Cleanup
+
+**Step 6: Extract shared generator methods to ProjectionGenerator base**
+- Move `emitBody()`, `appendIndented()`, `quoteIdentifier()` to `ProjectionGenerator` base
+- Remove duplicates from RustGenerator, JavaGenerator, JavaScriptGenerator,
+  PythonGenerator, CppGenerator, MySQLGenerator, CommonLispGenerator, WatGenerator
+- Tests: each generator produces identical output before/after for sample ASTs
+
+**Step 7: Extract shared STUB patterns to base**
+- The `"// STUB: empty AST body; user implementation required"` pattern appears in every generator
+- Move to `ProjectionGenerator::emitStubBody()` with language-aware comment syntax:
+  - `//` for C-family, `#` for Python, `;;` for Lisp, `--` for SQL
+- Tests: STUB output correct for each language, non-empty body unchanged
+
+### Step 8–9: LSPClient Response Handler Dedup
+
+**Step 8: Extract JSON response parsing helpers**
+- LSPClient.h has repeated `result.is_array()` / `result.is_object()` / `result.contains("items")`
+  patterns for completions, symbols, definitions
+- Create private helpers:
+  ```cpp
+  std::vector<CompletionItem> parseCompletionItems(const nlohmann::json& result);
+  std::vector<DocumentSymbol> parseDocumentSymbols(const nlohmann::json& result);
+  DefinitionLocation parseDefinitionLocation(const nlohmann::json& result);
+  ```
+- Tests: parse array form, parse object-with-items form, empty result, malformed result
+
+**Step 9: Simplify handleResponse dispatch**
+- Replace the `if (id == lastCompletionRequestId_)` chain with a request-type map:
+  ```cpp
+  std::unordered_map<int, std::function<void(const json&)>> pendingHandlers_;
+  ```
+- Each `sendRequest()` registers its handler; `handleResponse()` becomes a lookup
+- Tests: concurrent requests, handler cleanup after response, unknown id ignored
+
+### Step 10–11: Headless RPC Dispatch Cleanup
+
+**Step 10: Audit DispatchPart1–4.h for string-match duplication**
+- These files dispatch RPC method strings to handler functions
+- Assess: can these use a `std::unordered_map<string, handler>` like the LSP fix?
+- If yes: refactor. If the dispatch is already small (~10 per file), leave it.
+- Tests: all headless RPC methods still route correctly
+
+**Step 11: Consolidate dispatch infrastructure**
+- If AnnotationRegistry and RPC dispatch both use string→function maps,
+  extract a shared `StringDispatch<ReturnType>` template utility
+- Tests: template works for both use cases
+
+### Step 12: Regression & Metrics
+
+**Step 12: Full regression + line count delta**
+- Run all existing tests (615 files)
+- Measure: total .h lines before vs after
+- Expected savings: ~1,500–2,000 lines removed
+- Document in progress.md
+- Tests: no regressions, line count report
+
+---
+
+## Success Criteria
+
+- [ ] No if-else chain in codebase exceeds 30 lines for type dispatch
+- [ ] `emitBody()` exists in exactly one place (base class)
+- [ ] CompactAST `extractSemanticSummary()` is under 20 lines
+- [ ] ProjectionGenerator `dispatchGenerate()` is under 10 lines
+- [ ] All 615 existing tests pass
+- [ ] Net line reduction: ≥1,500 lines