playbooks

home / skills / openharmonyinsight / openharmony-skills / code-checker

code-checker skill

/skills/code-checker

This skill scans C/C++ codebases for size and circular dependency issues, analyzes maintainability, and reports actionable findings to guide refactoring.

npx playbooks add skill openharmonyinsight/openharmony-skills --skill code-checker

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
3.0 KB
---
name: code-checker
description: Scan C/C++ codebases for code quality issues including extra large files/functions and circular dependencies. Use when the user asks to check file sizes, find oversized functions, detect circular dependencies, analyze code complexity, find code smells, or identify maintainability issues in C/C++ code. Supports scanning individual files or entire directories with configurable thresholds.
---

# C/C++ Code Checker

Analyzes C/C++ code for maintainability issues: extra large files/functions and circular dependencies between modules.

## Workflow

1. **Identify scan target** - If the user doesn't specify a file or directory, ask: "Which directory or file should I scan?"
2. **Determine check type** - Ask or infer which checks to run:
   - File/Function size analysis
   - Circular dependency detection
   - Both (default for full analysis)
3. **Run the scan** - Execute the appropriate script(s)
4. **Present findings** - Show the report and summarize key issues
5. **Offer help** - Ask if the user wants refactoring assistance

## Size Analysis

Scan for extra large files and functions:

```bash
scripts/scan_cpp_size.py <path> [options]
```

**Options:**
- `-o, --output <file>` - Write report to file
- `-f, --file-threshold <n>` - Large file threshold (default: 2000 effective lines)
- `-F, --function-threshold <n>` - Large function threshold (default: 50 effective lines)

**Example:**
```bash
scripts/scan_cpp_size.py ./src --file-threshold 1500 --function-threshold 40 -o size_report.md
```

## Circular Dependency Detection

Detect circular dependencies between directory modules:

```bash
scripts/circular_header_check.py <path> [options]
```

**Options:**
- `-o, --output <file>` - Write report to file
- `-v, --verbose` - Verbose output
- `--no-gn` - Skip GN build file parsing

**Example:**
```bash
scripts/circular_header_check.py ./src -o circular_report.md
```

The circular dependency checker:
- Parses GN build files (`BUILD.gn`, `*.gni`) for include paths
- Groups files by directory modules (handles `src/` and `include/` as one component)
- Detects when module A includes files from module B, which includes A

## After Finding Issues

When issues are found:

1. **Prioritize by impact** - Start with the largest issues first
2. **Understand context** - Read the code to understand responsibility
3. **Ask the user** - "Would you like help refactoring this?"

## Refactoring Guidance

| Issue Type | Reference |
|------------|-----------|
| Large functions | [references/refactoring.md](references/refactoring.md) |
| Circular dependencies | See [references/circular-deps.md](references/circular-deps.md) |

## What Counts as "Large"?

| Category | Default Threshold | Rationale |
|----------|-------------------|-----------|
| Files | 2000 effective lines | Hard to navigate, understand |
| Functions | 50 effective lines | Beyond cognitive fit, hard to test |

*Effective lines* exclude blank lines, comments, and preprocessor directives.

## File Extensions Scanned

`.c`, `.cpp`, `.cc`, `.cxx`, `.c++`, `.h`, `.hpp`, `.hh`, `.hxx`, `.h++`, `.inl`, `.inc`

Overview

This skill scans C and C++ codebases to find maintainability problems like oversized files and functions and circular dependencies between modules. It supports scanning single files or entire directories with configurable thresholds and can output a concise report. Use it to prioritize refactors and quickly spot code smells that increase technical debt.

How this skill works

The scanner counts effective lines (excluding blanks, comments, and preprocessor lines) to flag files and functions that exceed configurable thresholds. It also parses include relationships and GN build files to group code into directory modules and detect circular include chains. Results are presented as a report with prioritized findings and optional output file support.

When to use it

  • You want to find files or functions that are too large to maintain or test easily.
  • You suspect or want to prevent circular dependencies between directory-level modules.
  • Before a major refactor to identify high-impact targets.
  • During code health reviews or CI checks to enforce maintainability thresholds.
  • When onboarding to understand hotspots in a legacy C/C++ codebase.

Best practices

  • Start with default thresholds (files: 2000 effective lines, functions: 50 effective lines) and tune for your codebase.
  • Scan whole directories for module-level dependency analysis; scan single files for quick size checks.
  • Prioritize fixes by impact: largest files/functions and cycles that block modularization.
  • Use verbose or output-file options to generate artifacts for code-review and tracking.
  • Combine results with manual code reading before applying refactors; automated rules guide but don’t replace context.

Example use cases

  • Run a full project scan to produce a size_report.md and circular_report.md before a release.
  • Check a suspicious file to see if any functions exceed the configured function threshold.
  • Detect and visualize circular header dependencies that prevent safe modularization.
  • Integrate size checks into CI to fail builds when new code introduces oversized functions.
  • Triage a legacy module by listing largest files and functions to create a phased refactor plan.

FAQ

What file types are scanned?

C and C++ source and header extensions (.c, .cpp, .cc, .cxx, .h, .hpp, .inl, .inc, etc.).

Can I change thresholds?

Yes. File and function size thresholds are configurable via command options for tailored analysis.