strategy

C++/C Language Strategy

Phase Strategy

C/C++ separates declarations (headers) from implementations (source files), so 2-Phase analysis is used.

Phase	Target	Focus	Condition
1 — Structure	.h, .hpp, .hxx, .hh, .inl, .ipp	Class design, API surface, inheritance, dependencies	Always
2 — Implementation	.cpp, .cc, .cxx, .c	Complexity, bug patterns, resource management, logic defects	User selects subsystem scope

Phase 1 Behavior

1. Filter analysis plan to entries with a header field, or files with extensions .h/.hpp/.hxx/.hh/.inl/.ipp
2. Analyze each header with analyze-file skill (file_role: "declaration")
3. Generate Phase 1 report — structure report + subsystem classification table
4. Propose Phase 2 scope selection to user

Phase Transition

After Phase 1 report, present to user:

Structure analysis complete. Select subsystems for deep-dive:

#	Subsystem	Files	Hotspots	Key Issues
1	Combat (Attack, Enemy, Weapon)	45 cpp	3	God function
2	Stat (Stat, SpecialStat, Buff)	32 cpp	5	Extension explosion
3	UI (Widget, UIHandler)	88 cpp	1	—

Specify by number, glob pattern, or "all".

Subsystem classification is auto-generated from dependency clusters and naming patterns found in Phase 1.

Phase 2 Behavior

1. Filter .cpp files in the user-selected scope from analysis plan
2. Analyze each .cpp with analyze-file skill (file_role: "implementation")
   • Pass the paired .h mirror as read-only context (do not re-analyze)
3. Generate Phase 2 report (implementation quality, bugs, security)

File Classification

Extension	file_role	Phase	Note
.h, .hpp, .hxx, .hh	declaration	1	Class declarations, API, macros
.inl, .ipp	declaration	1	Inline implementations (treated as headers)
.cpp, .cc, .cxx, .c	implementation	2	Function bodies, logic
.generated.h, *.gen.cpp	skip	—	Code-generator output

Auto-Exclusions

• *.generated.h, *.gen.cpp — code generator output
• ThirdParty/** — third-party libraries
• **/build/**, **/out/** — build artifacts

Framework Detection

Framework detection is owned by each framework pack via its own strategy/SKILL.md framework_detection YAML block. When /analyze init gate loads a language pack, it subsequently enumerates installed code-analysis-{framework}:strategy skills whose requires_language equals this language, and applies each pack's signatures.

Framework strategies extend (never replace) this language strategy — static_tools, entry points, and dead-code exclusions from both packs are combined by the orchestrator.

analyze-file Adjustments

declaration (.h) analysis

Focus: What role does this file play in the project architecture?

• Class declaration structure: fields, methods, visibility, virtual functions
• Inheritance: base classes, interface implementations
• API surface: design quality of public methods/types
• Dependencies: unnecessary includes, circular dependencies
• Issue focus: God class, excessive public API, wrong abstractions, ISP violations

Lightweight mode: Even if function bodies are inlined in headers, defer deep implementation analysis to Phase 2. Report only obvious bugs found inline.

implementation (.cpp) analysis

Focus: Implementation quality and latent defects

• Context loading: Read the paired .h mirror first to understand class structure/API
• Per-function complexity, depth, and size analysis
• Resource management: memory alloc/dealloc pairs, RAII compliance
• Error handling: unchecked return values, exception safety
• Issue focus: God function, memory leaks, race conditions, hardcoded values, unused variables
• Verify consistency between API intent (from .h) and implementation (.cpp)

Entry Points (canonical)

The following YAML block is the authoritative declaration consumed by phase3-trace. Surrounding notes are clarifying commentary only.

entry_points:
  symbols:
    - main
    - WinMain
    - DllMain
  include_root_files: true

• symbols: canonical runtime entry symbols the language runtime calls directly.
• include_root_files: true: files with no incoming edges in the import graph are treated as additional entry points (library exports without callers). Queried via MATCH (f:File) WHERE NOT ()-[:IMPORTS]->(f) RETURN f.path.

Dead Code Exclusions

Do NOT flag as dead code:

• main() function — always an entry point
• Functions in files with no dependents (may be library exports)
• Template specializations — may be instantiated indirectly
• operator overloads — called by implicit conversions/expressions
• Pure virtual method overrides — called through base class pointers
• Callback functions passed to library APIs (registered via function pointer)

Post-Analysis Steps

After structure-analyzer Step 1.5 snapshots the GitNexus graph, the core CLI automatically runs pair-headers for C++ projects (codeanalyzer pair-headers). This pairs .h/.cpp files by matching base names and updates analysis-plan.json with header/source fields for each compilation unit. Metrics are then computed via codeanalyzer compute-metrics.

Hooks Provided

This plugin provides the following extension hooks. The core pipeline registers these at init time and invokes them at the corresponding pipeline stages.

Hook Point	Skill Name	Invocation Context
after-analyze-file	code-analysis-cpp:after-analyze-file	Per-file, after mirror document is written
after-phase3-trace	code-analysis-cpp:after-phase3-trace	After Phase 3 flow analysis completes
phase4-docs	code-analysis-cpp:phase4-docs	During Phase 4 documentation generation

Static Tools

The core orchestrator invokes these via codeanalyzer run-tools --strategy <this-file> --phase <phase>. All tools are hard-require — missing tools abort /analyze initialization.

static_tools:
  phase1:
    - name: ca-pair-headers
      command: "codeanalyzer pair-headers --scope={scope}"
      output_parser: ca-json
    - name: ca-metrics
      command: "codeanalyzer compute-metrics --file {file} --json"
      output_parser: ca-json
  phase2:
    - name: clang-tidy
      command: "clang-tidy {file} --quiet --export-fixes=- --format=json"
      output_parser: clang-tidy-json
    - name: cppcheck
      command: "cppcheck --template='{severity}|{line}|{id}|{message}' --enable=all {file}"
      output_parser: cppcheck-pipe
    - name: include-what-you-use
      command: "include-what-you-use {file}"
      output_parser: iwyu-text
    - name: ca-metrics
      command: "codeanalyzer compute-metrics --file {file} --json"
      output_parser: ca-json
  phase3: []
  phase4: []

Installation (platform hints)

• macOS: brew install llvm cppcheck include-what-you-use
• Debian: apt install clang-tidy cppcheck iwyu
• Windows: install LLVM toolchain (winget install LLVM.LLVM), cppcheck separately.