normalize analyze

Analyze codebase quality: health, complexity, security, duplicates, hotspots.

Subcommands

Subcommand	Description
(none)	Default: health analysis
health	File counts, complexity stats, large file warnings
overview	Comprehensive project summary with grade
complexity	Cyclomatic complexity analysis
length	Function length analysis
security	Security vulnerability patterns
docs	Documentation coverage
files	Longest files in codebase
hotspots	Git history hotspots (frequently changed files)
duplicate-functions	Detect code clones
duplicate-types	Detect similar type definitions
trace	Trace value provenance for a symbol
callers	Show what calls a symbol
callees	Show what a symbol calls
lint	Run configured linters
check-refs	Check documentation for broken links
stale-docs	Find docs with stale code references
check-examples	Check example references in docs
rules	Run syntax rules from .normalize/rules/*.scm
ast	Show AST for a file (for authoring rules)
query	Test a tree-sitter query against a file
all	Run all analysis passes with overall grade

Examples

# Quick health check
normalize analyze

# Comprehensive overview
normalize analyze overview

# Find complex functions
normalize analyze complexity --threshold 15

# Security scan
normalize analyze security

# Find code duplicates
normalize analyze duplicate-functions

# Git hotspots (frequently changed files)
normalize analyze hotspots

# Trace a symbol's data flow
normalize analyze trace parse_config

# Call graph
normalize analyze callers handle_request
normalize analyze callees main

# Syntax rules
normalize analyze rules              # Run all rules
normalize analyze rules --list       # List available rules
normalize analyze rules --fix        # Auto-fix issues
normalize analyze rules --sarif      # SARIF output for IDEs

Options

Global

• -r, --root <PATH> - Root directory
• --json - Output as JSON
• --jq <EXPR> - Filter JSON with jq
• --pretty - Human-friendly output
• --compact - Compact output without colors
• --exclude <PATTERN> - Exclude paths
• --only <PATTERN> - Include only paths
• --diff [<BASE>] - Analyze only files changed since base ref (default: origin's default branch)

Subcommand-specific

complexity:

• -t, --threshold <N> - Only show functions above threshold
• --kind <TYPE> - Filter by: function, method

files / hotspots:

• --allow <PATTERN> - Add pattern to allow file
• --reason <TEXT> - Reason for allowing (with --allow)
• -n, --limit <N> - Number of results to show

duplicate-functions:

• --elide-identifiers - Ignore identifier names when comparing (default: true)
• --elide-literals - Ignore literal values when comparing
• --show-source - Show source code for duplicates
• --min-lines <N> - Minimum function lines to consider
• --allow <LOCATION> - Add to allow file
• --reason <TEXT> - Reason for allowing

trace:

• --target <FILE> - Target file to search in
• --max-depth <N> - Maximum trace depth (default: 10)
• --recursive - Trace into called functions

rules:

• --rule <ID> - Run only this specific rule
• --list - List available rules without running
• --fix - Auto-fix issues that have fixes available
• --sarif - Output in SARIF format for IDE integration
• --debug <FLAGS> - Debug output (timing, all)

Allow Files

Patterns can be excluded via .normalize/ allow files:

File	Purpose
.normalize/large-files-allow	Exclude from analyze files
.normalize/hotspots-allow	Exclude from analyze hotspots
.normalize/duplicate-functions-allow	Exclude from duplicate detection
.normalize/duplicate-types-allow	Exclude type pairs

Add via CLI:

normalize analyze files --allow "**/generated/*.rs" --reason "generated code"
normalize analyze hotspots --allow "CHANGELOG.md" --reason "expected to change often"

Config

In .normalize/config.toml:

[analyze]
threshold = 10           # Default complexity threshold
compact = false          # Compact overview output
health = true            # Run health by default
complexity = true        # Run complexity by default
security = true          # Run security by default
duplicate_functions = false
exclude_interface_impls = true  # Exclude trait impls from doc coverage
hotspots_exclude = ["*.lock", "CHANGELOG.md"]

[analyze.weights]
health = 1.0
complexity = 0.5
security = 2.0
duplicate_functions = 0.3

Module Structure

analyze/
├── mod.rs        # Main dispatch, config
├── args.rs       # CLI argument definitions
├── report.rs     # Report formatting, grading
├── health.rs     # Health analysis
├── complexity.rs # Complexity metrics
├── security.rs   # Security patterns
├── files.rs      # File length analysis
├── hotspots.rs   # Git hotspots
├── duplicates.rs # Code clone detection
├── trace.rs      # Value provenance tracing
├── call_graph.rs # Caller/callee analysis
├── docs.rs       # Documentation coverage
├── lint.rs       # Linter integration
└── ...