Skip to content

Commit 4d383bb

Browse files
carlos-almcarlos-alm
authored
refactor: Titan v3.8.0 — decompose god-functions, structured logging, error handling (#775)
* fix: replace empty catch blocks with structured error handling Replace catch blocks that silently swallow errors with proper error variable capture and debug() logging across 10 files. This addresses Pillar II (Rule 10: emptyCatch) violations identified by the gauntlet audit. Files that already had proper error handling were verified and left unchanged. * fix: replace console.log with structured logging in non-CLI-output code * refactor: add error-handling helpers for intentional catch suppression * refactor: decompose makePartition into focused graph operations * refactor: extract visitor dispatch helpers from walkWithVisitors Decompose walkWithVisitors (cognitive=65, halstead.bugs=1.05) into focused helper functions: mergeFunctionNodeTypes, initVisitors, isSkipped, dispatchEnterFunction, dispatchEnterNode, dispatchExitNode, clearSkipFlags, dispatchExitFunction, collectResults. The main function is now a thin orchestrator delegating to single-purpose dispatch helpers. * refactor: extract parameter and callee resolution helpers from visitor-utils Split extractParamNames by extracting extractRestParamNames, extractObjectDestructNames, and extractArrayDestructNames. Extract resolveOptionalChainCallee from resolveCalleeName. Reduces cognitive complexity and cyclomatic complexity of the two main functions. * refactor: decompose handleVarDeclarator in dataflow-visitor Extract resolveValueNode, unwrapExpressionList, recordDestructuredAssignment, and recordSimpleAssignment from the monolithic handleVarDeclarator function. Reduces cognitive complexity from 48 to focused single-purpose helpers. * refactor: extract classifyNode helper and simplify complexity-visitor Consolidate the enterNode classification logic into a single classifyNode function. Simplify enterFunction/exitFunction by merging equivalent branches for fileLevelWalk mode. Reduces cognitive complexity from 37 to focused single-purpose helpers. * refactor: decompose ast-store-visitor name extraction and node collection Extract extractThrowName, extractAwaitName from extractName (removed). Extract resolveNameAndText from collectNode to separate per-kind name/text resolution from the row-building logic. Reduces cognitive complexity and cyclomatic branching in the visitor factory. * refactor: decompose engine.ts native analysis and deduplicate MI override Extract detectNativeNeeds and runNativeFileAnalysis from runNativeAnalysis to separate needs-detection from per-file dispatch. Extract shared overrideCyclomaticFromCfg helper to eliminate duplicated MI recalculation in storeNativeCfgResults and storeCfgResults. * refactor: extract named constants and sumCounts helper in metrics Replace magic numbers in the MI formula with named constants (MI_BASE, MI_VOLUME_COEFF, etc.) and the Halstead bugs divisor. Extract sumCounts helper from computeHalsteadDerived. Reduces halsteadEffort and addresses Rule 7 magic-values warning. * refactor: extract sub-functions from features domain god-functions * refactor: split buildAstNodes and fix console.log usage * refactor: decompose graph build pipeline stages Extract repeated patterns into focused helper functions: - pipeline.ts: closeNativeDb, reopenNativeDb, suspendNativeDb, refreshJsDb - insert-nodes.ts: marshalSymbolBatches, buildFileHashes - resolve-imports.ts: buildReexportMap, findBarrelCandidates, reparseBarrelFiles - watcher.ts: prepareWatcherStatements, processPendingFiles, writeJournalAndChangeEvents * refactor: extract rendering sub-functions from inspect and diff-impact-mermaid * refactor: split hybridSearchData into keyword, vector, and merge steps * refactor: extract class declaration handlers in Kotlin and Swift extractors * refactor: reduce complexity in language extractors Extract helper functions from main handler functions in solidity, zig, javascript, python, go, rust, and java extractors to reduce cognitive complexity, cyclomatic complexity, and halstead effort metrics. * fix: address remaining quality issues across domains Extract sub-functions to reduce halsteadEffort and cognitive complexity in 11 FAIL targets: dependencies, communities, server, parser, context, overview, impact, exports, path, viewer, dataflow. All functions now pass gate thresholds (cognitive <= 30, halstead.bugs <= 1.0, MI >= 20). * refactor: address quality warnings * docs: add Titan audit report v3.8.0 * docs: update Titan report with PR URLs * style: format resolve-imports barrel key lookup * fix: move suppressError helpers to infrastructure/suppress.ts (#775) Resolves layer-boundary violation where shared/errors.ts imported from infrastructure/logger.ts. The suppress helpers now live in infrastructure/ alongside their logger dependency, keeping shared/ dependency-free. * fix: add clarifying comment to parenDepthDelta and fix TS indexing (#775) Document mutual exclusivity of paren/comma checks in splitTopLevelCommas. Use local variable to satisfy noUncheckedIndexedAccess. * fix: correct TypeScript type errors in extracted functions (#775) Type Map<unknown, unknown> in buildNodeDepsResult to Map<string, string | null>. Use NativeDatabase type in buildNativeDataflowResult parameter.
1 parent 4155231 commit 4d383bb

56 files changed

Lines changed: 3485 additions & 2508 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎generated/titan/titan-report-v3.8.0-2026-04-03T00-15-00.md‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,263 @@
1+
# Titan Audit Report
2+
3+
**Version:** 3.8.0
4+
**Date:** 2026-04-02 06:05 UTC - 2026-04-03 00:15 UTC
5+
**Branch:** worktree-titan-run
6+
**Target:** . (codegraph self-audit)
7+
8+
---
9+
10+
## Executive Summary
11+
12+
The Titan pipeline audited 69 targets across 13 domains of the codegraph codebase (v3.8.0). The forge phase executed 20 commits addressing empty catch blocks, console.log misuse, god-function decomposition, and complexity reduction across 63 targets. All 20 gate validations passed (8 PASS, 12 WARN, 0 FAIL, 0 rollbacks). The pipeline remained fresh throughout -- main did not advance during execution. The quality score held steady at 68, with meaningful improvements in function decomposition and error handling patterns, though the score metric is dominated by caller coverage and call confidence rather than complexity.
13+
14+
---
15+
16+
## Pipeline Timeline
17+
18+
| Phase | Duration | Notes |
19+
|-------|----------|-------|
20+
| RECON | 6.2 min | Mapped 555 files, 14733 symbols, 13 domains |
21+
| GAUNTLET | 21.6 min | 69 targets audited across 16 batches |
22+
| SYNC | 12.3 min | 10 clusters, 3 abstractions, 14-phase execution plan |
23+
| FORGE | 324.9 min (5.4 hr) | 20 commits, 63 targets completed, 0 failures |
24+
| GATE | (inline with forge) | 20 runs: 8 PASS, 12 WARN, 0 FAIL |
25+
| CLOSE | 11.9 min | Report generation, PR planning, issue creation |
26+
| **Total** | **377.0 min (6.3 hr)** | |
27+
28+
---
29+
30+
## Metrics: Before & After
31+
32+
| Metric | Baseline | Final | Delta | Trend |
33+
|--------|----------|-------|-------|-------|
34+
| Quality Score | 68 | 68 | 0 | -- |
35+
| Total Files | 555 | 555 | 0 | -- |
36+
| Total Symbols | 14733 | 15297 | +564 | (new helper functions from decomposition) |
37+
| Total Edges | 28994 | 30177 | +1183 | (new internal call edges) |
38+
| Functions Above Threshold | 50 | 50 | 0 | -- |
39+
| Dead Symbols | 11223 | 11647 | +424 | (extracted helpers not yet consumed externally) |
40+
| Cycle Count (file) | 1 | 1 | 0 | -- |
41+
| Cycle Count (function) | 8 | 9 | +1 | -- |
42+
| Community Count | 117 | 108 | -9 | (improved cohesion) |
43+
| Community Drift Score | 39-41 | 28 | -12 | (improved) |
44+
| Avg Cognitive Complexity | 5.6 | 5.6 | 0 | -- |
45+
| Min Maintainability Index | 13.4 | 20.3 | +6.9 | (improved) |
46+
47+
**Note on quality score stability:** The quality score (68) is computed from caller coverage (35.5%) and call confidence (85.1%), which are resolution metrics unaffected by complexity refactoring. The real improvements show in the community drift score (-12 points), minimum MI (+6.9), and the decomposition of 16 DECOMPOSE-verdict targets.
48+
49+
### Complexity Improvement: Top Movers
50+
51+
Functions that were decomposed or significantly improved:
52+
53+
| Function | File | Before (cog/MI/bugs) | After | Change |
54+
|----------|------|----------------------|-------|--------|
55+
| makePartition | partition.ts | 104 / 13.4 / 4.49 | Decomposed into focused helpers | Worst offender addressed |
56+
| walkWithVisitors | visitor.ts | 65 / 43.7 / - | Dispatch extracted to helpers | Reduced coupling |
57+
| buildDataflowEdges | dataflow.ts | 62 / 28.7 / 1.37 | Sub-functions extracted | Decomposed |
58+
| renderContextResult | inspect.ts | 59 / 27.2 / 1.48 | Rendering sub-functions extracted | Decomposed |
59+
| resolveImports | resolve-imports.ts | 53 / 39.4 / 1.19 | Stage logic separated | Decomposed |
60+
| handleVarDeclarator | dataflow-visitor.ts | 48 / 31.6 / - | Helper extraction | Simplified |
61+
| buildComplexityMetrics | complexity.ts | 117 / 32.1 / 1.25 | Sub-routines extracted | Partially decomposed |
62+
| hybridSearchData | hybrid.ts | 38 / 24.6 / 1.43 | Split into keyword/vector/merge | Decomposed |
63+
| handleKotlinClassDecl | kotlin.ts | 72 / 37.7 / - | Handler extraction | Reduced nesting |
64+
| handleSwiftClassDecl | swift.ts | 69 / 39.3 / - | Handler extraction | Reduced nesting |
65+
66+
### Remaining Hot Spots
67+
68+
Functions still above thresholds (carried forward for next Titan run):
69+
70+
| Function | File | Cognitive | MI | Bugs |
71+
|----------|------|-----------|-----|------|
72+
| buildComplexityMetrics | src/features/complexity.ts | 117 | 32.1 | 1.17 |
73+
| louvain_impl | crates/.../graph_algorithms.rs | 85 | 30.6 | 2.72 |
74+
| extract_param_names_strategy | crates/.../dataflow.rs | 83 | 23.1 | 1.36 |
75+
| extract_dynamic_import_names | crates/.../javascript.rs | 79 | 44.1 | 1.07 |
76+
| extract_csharp_class_fields | crates/.../csharp.rs | 78 | 50.0 | 0.37 |
77+
| collect_self_assignments | crates/.../python.rs | 70 | 52.9 | 0.40 |
78+
| CfgBuilder.process_try_catch | crates/.../cfg.rs | 62 | 34.2 | 1.85 |
79+
| build_import_edges | crates/.../edge_builder.rs | 61 | 42.5 | 0.94 |
80+
| run_pipeline | crates/.../build_pipeline.rs | 40 | 29.5 | 5.29 |
81+
| match_cpp_node | crates/.../cpp.rs | 40 | 20.3 | 2.37 |
82+
83+
**Key observation:** The remaining hot spots are predominantly in the native Rust engine (`crates/codegraph-core/`), which was out of scope for this TypeScript-focused audit. A future Titan run targeting the Rust codebase would address these.
84+
85+
---
86+
87+
## Audit Results Summary
88+
89+
**Targets audited:** 69
90+
**Pass:** 10 | **Warn:** 7 | **Fail:** 36 | **Decompose:** 16
91+
92+
### By Pillar
93+
94+
| Pillar | Pass | Warn | Fail |
95+
|--------|------|------|------|
96+
| I -- Structural Purity | 12 | 9 | 48 |
97+
| II -- Data & Type Sovereignty | 43 | 7 | 19 |
98+
| III -- Ecosystem Synergy | 69 | 0 | 0 |
99+
| IV -- Quality Vigil | 60 | 0 | 9 |
100+
101+
### Most Common Violations
102+
103+
| Violation | Count |
104+
|-----------|-------|
105+
| Rule 1: halsteadEffort (Pillar I) | 57 |
106+
| Rule 1: cognitive (Pillar I) | 45 |
107+
| Rule 1: mi (Pillar I) | 45 |
108+
| Rule 1: cyclomatic (Pillar I) | 42 |
109+
| Rule 1: maxNesting (Pillar I) | 37 |
110+
| Rule 10: emptyCatch (Pillar II) | 19 |
111+
| Rule 7: magicValues (Pillar II) | 16 |
112+
| Rule 15: structuredLogging (Pillar IV) | 9 |
113+
114+
---
115+
116+
## Changes Made
117+
118+
### Commits: 20
119+
120+
| SHA | Message | Files | Domain |
121+
|-----|---------|-------|--------|
122+
| 8d15cef | fix: replace empty catch blocks with structured error handling | 10 | cross-cutting |
123+
| bf30812 | fix: replace console.log with structured logging in non-CLI-output code | 5 | shared/features |
124+
| 1a02ab5 | refactor: add error-handling helpers for intentional catch suppression | 1 | shared |
125+
| 8f06fdd | refactor: decompose makePartition into focused graph operations | 2 | graph-algorithms |
126+
| 2557e71 | refactor: extract visitor dispatch helpers from walkWithVisitors | 1 | ast-analysis |
127+
| 363a641 | refactor: extract parameter and callee resolution helpers from visitor-utils | 1 | ast-analysis |
128+
| 59152ee | refactor: decompose handleVarDeclarator in dataflow-visitor | 1 | ast-analysis |
129+
| ad47ee8 | refactor: extract classifyNode helper and simplify complexity-visitor | 1 | ast-analysis |
130+
| 417b736 | refactor: decompose ast-store-visitor name extraction and node collection | 1 | ast-analysis |
131+
| 8df0567 | refactor: decompose engine.ts native analysis and deduplicate MI override | 1 | ast-analysis |
132+
| 65d002e | refactor: extract named constants and sumCounts helper in metrics | 1 | ast-analysis |
133+
| ce00461 | refactor: extract sub-functions from features domain god-functions | 5 | features |
134+
| af4b728 | refactor: split buildAstNodes and fix console.log usage | 1 | features |
135+
| c2b4c12 | refactor: decompose graph build pipeline stages | 4 | graph-build |
136+
| 201095b | refactor: extract rendering sub-functions from inspect and diff-impact-mermaid | 2 | presentation |
137+
| ece3d96 | refactor: split hybridSearchData into keyword, vector, and merge steps | 1 | search |
138+
| b1dd5a6 | refactor: extract class declaration handlers in Kotlin and Swift extractors | 2 | extractors |
139+
| 13748ef | refactor: reduce complexity in language extractors | 7 | extractors |
140+
| e815616 | fix: address remaining quality issues across domains | 11 | cross-cutting |
141+
| 0cd62ce | refactor: address quality warnings | 6 | cross-cutting |
142+
143+
### PR Split Plan
144+
145+
| PR # | Title | Concern | Domain | Commits | Files | Depends On | URL |
146+
|------|-------|---------|--------|---------|-------|------------|-----|
147+
| 1 | fix: replace empty catch blocks with structured error handling | quality_fix + abstraction | cross-cutting | 2 | 11 | -- | [#764](https://github.com/optave/ops-codegraph-tool/pull/764) |
148+
| 2 | fix: replace console.log with structured logging | quality_fix | shared/features | 1 | 5 | -- | [#765](https://github.com/optave/ops-codegraph-tool/pull/765) |
149+
| 3 | refactor: decompose makePartition | decomposition | graph-algorithms | 1 | 2 | -- | [#766](https://github.com/optave/ops-codegraph-tool/pull/766) |
150+
| 4 | refactor: extract rendering sub-functions (inspect + mermaid) | decomposition | presentation | 1 | 2 | -- | [#767](https://github.com/optave/ops-codegraph-tool/pull/767) |
151+
| 5 | refactor: split hybridSearchData | decomposition | search | 1 | 1 | -- | [#768](https://github.com/optave/ops-codegraph-tool/pull/768) |
152+
| 6 | refactor: extract class declaration handlers (extractors) | decomposition | extractors | 2 | 9 | -- | [#769](https://github.com/optave/ops-codegraph-tool/pull/769) |
153+
| 7 | refactor: address quality warnings in shared modules | warning | cross-cutting | 1 | 6 | -- | [#770](https://github.com/optave/ops-codegraph-tool/pull/770) |
154+
| 8 | refactor: decompose ast-analysis visitor framework | decomposition | ast-analysis | 7 | 7 | PR #1 | [#771](https://github.com/optave/ops-codegraph-tool/pull/771) |
155+
| 9 | refactor: extract sub-functions from features god-functions | decomposition | features | 2 | 6 | PR #1 | [#772](https://github.com/optave/ops-codegraph-tool/pull/772) |
156+
| 10 | refactor: decompose graph build pipeline stages | decomposition | graph-build | 1 | 4 | PR #1 | [#773](https://github.com/optave/ops-codegraph-tool/pull/773) |
157+
| 11 | fix: address remaining quality issues across domains | quality_fix | cross-cutting | 1 | 11 | PR #1 | [#774](https://github.com/optave/ops-codegraph-tool/pull/774) |
158+
159+
**Merge order:** PR #1 first, then PRs #2-#7 (independent, any order), then PRs #8-#11 (after PR #1 merges)
160+
161+
---
162+
163+
## Gate Validation History
164+
165+
**Total runs:** 20
166+
**Pass:** 8 | **Warn:** 12 | **Fail:** 0
167+
**Rollbacks:** 0
168+
169+
### Check Results Across All Runs
170+
171+
| Check | Pass | Warn | Fail | Skip |
172+
|-------|------|------|------|------|
173+
| manifesto | 15 | 5 | 0 | 0 |
174+
| cycles | 20 | 0 | 0 | 0 |
175+
| complexity | 15 | 5 | 0 | 0 |
176+
| semanticAssertions | 20 | 0 | 0 | 0 |
177+
| archSnapshot | 15 | 0 | 0 | 5 |
178+
| lint | 20 | 0 | 0 | 0 |
179+
| build | 0 | 0 | 0 | 20 |
180+
| tests | 20 | 0 | 0 | 0 |
181+
| syncAlignment | 20 | 0 | 0 | 0 |
182+
| blastRadius | 18 | 2 | 0 | 0 |
183+
184+
### Warning Patterns
185+
- **manifesto warn (5):** Expected during decomposition -- new helper functions temporarily fail halsteadEffort thresholds
186+
- **complexity warn (5):** Some decomposed functions still above cognitive threshold but improved
187+
- **blastRadius warn (2):** Large cross-cutting commits (empty catches, quality warnings) touched many files
188+
189+
---
190+
191+
## Issues Discovered
192+
193+
### Codegraph Bugs (1)
194+
1. **[#763](https://github.com/optave/ops-codegraph-tool/issues/763)** -- `codegraph cycles --json` and `codegraph stats --json` timeout on large codebases (555 files, 14733 symbols). Detected during SYNC phase. Severity: limitation.
195+
196+
### Tooling Issues (1)
197+
1. **[#762](https://github.com/optave/ops-codegraph-tool/issues/762)** -- Embeddings unavailable without `@huggingface/transformers` installed. DRY checks limited to grep-only. Detected during RECON phase. Severity: limitation.
198+
199+
### Process Suggestions (3)
200+
1. **Presentation layer console.log exemption:** Presentation layer files (`queries-cli/*.ts`) use `console.log` as their output mechanism. Rule 15 (structured logging) should exempt presentation layer files or have a separate threshold for CLI output files.
201+
2. **Empty catch distinction:** Empty catch blocks in `pipeline.ts` and `connection.ts` are best-effort cleanup patterns (close errors, checkpoint errors). Rule 10 should distinguish between swallowed errors in business logic vs. cleanup/teardown code.
202+
3. **Magic number false positives:** Magic number counts are inflated by type definition files (`types.ts`) and config files (`config.ts`) which contain `DEFAULTS` objects with numeric thresholds -- these are named constants, not magic values.
203+
204+
### Codebase Observations (0)
205+
No additional codebase observations beyond what the audit covered.
206+
207+
---
208+
209+
## Domains Analyzed
210+
211+
| Domain | Root Dirs | Files | Status |
212+
|--------|-----------|-------|--------|
213+
| cli | src/cli/, src/cli/commands/ | 48 | Not audited (low priority) |
214+
| features | src/features/ | 23 | Audited: 10 targets, decompositions applied |
215+
| presentation | src/presentation/ | 31 | Audited: 9 targets, rendering helpers extracted |
216+
| extractors-ts | src/extractors/ | 34 | Audited: 9 targets, nesting reduced |
217+
| domain-analysis | src/domain/analysis/, src/domain/ | 47 | Audited: 5 targets, quality fixes |
218+
| graph-build | src/domain/graph/ | 15 | Audited: 4 targets, pipeline decomposed |
219+
| ast-analysis | src/ast-analysis/ | 22 | Audited: 7 targets, visitor framework refactored |
220+
| graph-algorithms | src/graph/ | 22 | Audited: 2 targets, makePartition decomposed |
221+
| database | src/db/ | 20 | Audited: 5 targets, empty catches fixed |
222+
| mcp | src/mcp/ | 40 | Audited: 3 targets, error handling improved |
223+
| shared-infra | src/shared/, src/infrastructure/ | 16 | Audited: 10 targets, error helpers added |
224+
| native-engine | crates/codegraph-core/src/ | 52 | Not audited (Rust, out of scope) |
225+
| search | src/domain/search/ | 10 | Audited: 1 target, hybrid search decomposed |
226+
227+
---
228+
229+
## Pipeline Freshness
230+
231+
**Main at RECON:** a058615
232+
**Main at CLOSE:** a058615
233+
**Commits behind:** 0
234+
**Overall staleness:** fresh
235+
236+
### Drift Events
237+
238+
| Phase | Staleness | Impacted Targets | Action |
239+
|-------|-----------|-----------------|--------|
240+
| gauntlet | none | 0 | Continued normally |
241+
| sync | none | 0 | Continued normally |
242+
| close | none | 0 | Report generated normally |
243+
244+
### Stale Targets
245+
None. Pipeline remained fully fresh throughout execution.
246+
247+
---
248+
249+
## Recommendations for Next Run
250+
251+
1. **Target the native Rust engine.** The top remaining hot spots (louvain_impl, extract_param_names_strategy, run_pipeline, match_cpp_node) are all in `crates/codegraph-core/`. A Rust-focused Titan run would yield the highest improvement.
252+
253+
2. **Address buildComplexityMetrics (cognitive=117).** This remains the single worst TypeScript function. It was partially decomposed but needs further splitting -- the walk function and metric computation should be fully separated.
254+
255+
3. **Investigate the +1 function cycle.** Function-level cycles went from 8 to 9. Identify the new cycle introduced during refactoring and resolve it.
256+
257+
4. **Reduce dead symbol count.** The +424 increase in dead symbols is expected (newly extracted helper functions not yet consumed externally), but a follow-up pass should verify these helpers are properly exported and consumed.
258+
259+
5. **Fix build pipeline for dist/.** Several gate runs had to skip `build` and `archSnapshot` checks because the dist/ directory was stale. Ensure `npm run build` runs before gate validation in future Titan runs.
260+
261+
6. **Refine manifesto rules.** The 3 process suggestions (console.log exemption for presentation, empty catch distinction for cleanup code, magic number false positives for config objects) would reduce noise in future audits.
262+
263+
7. **Install @huggingface/transformers.** This would enable semantic DRY detection via embeddings, improving duplicate code identification.

0 commit comments

Comments
 (0)