Skip to content

Commit b64f03e

Browse files
HenryLok0HenryLok0
committed
docs: update README download command and enhance usage options
- Corrected the download command for Windows in the README. - Expanded the options section with detailed descriptions for various analysis flags.
1 parent 6d24ae1 commit b64f03e

2 files changed

Lines changed: 133 additions & 13 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
dist/
22
target/
3+
.cursor/
34
build/
45
*.egg-info/
56
__pycache__/

‎README.md‎

Lines changed: 132 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ chmod +x codestate
2929
./codestate
3030

3131
# Windows (PowerShell)
32-
Invoke-WebRequest -Uri "https://github.com/HenryLok0/CodeState/releases/latest/download/codestate-windows-amd64.exe" -OutFile "codestate.exe"
32+
Invoke-WebRequest -Uri "https://github.com/HenryLok0/CodeState/releases/latest/download/codestate.exe" -OutFile "codestate.exe"
3333
.\codestate.exe
3434
```
3535

@@ -48,20 +48,23 @@ cargo build --release
4848
CodeState is designed to be instantly useful for different daily scenarios.
4949

5050
### 1. Basic Scan: How big is this project?
51+
5152
Just run the tool without any arguments to get a blazingly fast overview of the language distribution, total lines of code, and comment density.
5253

5354
```bash
5455
codestate
5556
```
5657

5758
### 2. Code Health Check: What needs refactoring?
59+
5860
Use the summary flag to get a detailed breakdown of codebase health, including average function complexity and TODO counts.
5961

6062
```bash
6163
codestate --summary
6264
```
6365

6466
### 3. Find Bug Hotspots: Where should I focus my code review?
67+
6568
CodeState integrates directly with Git to find "Hotspots"—files that are modified most frequently. Files with high complexity *and* high churn are prime candidates for bugs.
6669

6770
```bash
@@ -94,21 +97,137 @@ This action will automatically run CodeState and post a beautiful report as a PR
9497
9598
CodeState's new Rust engine focuses on speed and simplicity.
9699
97-
| Flag | Description |
98-
|---|---|
99-
| `(no flags)` | Scan current directory and print basic language distribution & LOC. |
100-
| `--hotspot` | Analyze git history and show the files with the most commits. |
101-
| `--summary` | Generate a health summary of the project. |
102-
| `--details` | Show file-by-file metrics (complexity, TODOs, comments). |
103-
| `--runall` | Run a self-test suite of all features. |
104100
105-
## Advantages over standard line counters
101+
| Option | Description |
102+
| ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
103+
| **[Basic Analysis & Filtering]** | |
104+
| `directory` | Target directory to analyze (default: current directory) |
105+
| `--exclude` | Directories to exclude (e.g. --exclude .git venv node_modules) |
106+
| `--ext` | File extensions to include (e.g. --ext .py .js) |
107+
| `--only-lang` | Only analyze specific file extensions, comma separated (e.g. py,js) |
108+
| `--top N` | Show only the top N files by lines or complexity |
109+
| `--failures-only` | Show only files with issues (naming, size, complexity, etc.) |
110+
| `--regex` | User-defined regex rules for custom code checks (space separated, enclose in quotes) |
111+
| `--file-age` | Show file creation and last modified time |
112+
| `--uncommitted` | Show stats for files with uncommitted changes (git diff) |
113+
| `--size` | Show each file's size in bytes as a table |
114+
| `--list-extensions` | List all file extensions found in the project with count and percentage |
115+
| `--min-lines <N>` | Only show files with total lines >= N |
116+
| `--find <keyword/regex>` | Find all lines matching a keyword or regex in the codebase |
117+
| `--cache` | Build and use cache for much faster repeated analysis (highly recommended for large codebases) |
118+
| `--cache-delete` | Delete all cache data in `.codestate` (force rebuild cache on next run) |
119+
| **[Statistics & Detailed Analysis]** | |
120+
| `--details` | Show detailed statistics for each file |
121+
| `--dup` | Show duplicate code blocks (5+ lines) |
122+
| `--maxmin` | Show file with most/least lines |
123+
| `--langdist` | Show language (file extension) distribution as ASCII pie chart |
124+
| `--complexitymap` | Show ASCII heatmap of file complexity |
125+
| `--complexity-graph` | Show an ASCII bar chart of file complexity |
126+
| `--warnsize` | Warn for large files/functions (optionally specify file and function line thresholds, default 300/50) |
127+
| `--naming` | Check function/class naming conventions (PEP8, PascalCase) |
128+
| `--apidoc` | Show API/function/class docstring summaries |
129+
| `--deadcode` | Show unused (dead) functions/classes in Python files |
130+
| `--typestats` | Show function parameter/type annotation statistics (Python) |
131+
| `--trend` | Show line count trend for a specific file |
132+
| `--refactor-suggest` | Show files/functions that are refactor candidates, with reasons |
133+
| `--autofix-suggest` | Suggest auto-fix patches for naming, comments, and duplicate code |
134+
| `--refactor-map` | Show a table of files/functions that are refactor candidates |
135+
| `--complexity-threshold <value>` | Set custom complexity threshold for warnings (**requires a value**, e.g. --complexity-threshold 5) |
136+
| `--open <file>` | Show detailed analysis for a single file |
137+
| `--blame <file>` | Show git blame statistics for a file |
138+
| `--compare <dir1> <dir2>` | Compare statistics between two directories |
139+
| **[Output / Reports]** | |
140+
| `--html` | Export result as HTML table |
141+
| `--md` | Export result as Markdown table |
142+
| `--json` | Export result as JSON |
143+
| `--csv` | Export summary statistics as CSV |
144+
| `--excel` | Export summary statistics as Excel (.xlsx) |
145+
| `--details-csv` | Export per-file details as CSV |
146+
| `--groupdir-csv` | Export grouped-by-directory stats as CSV |
147+
| `--groupext-csv` | Export grouped-by-extension stats as CSV |
148+
| `--test-coverage <coverage.xml>` | Show test coverage analysis from a coverage.xml file |
149+
| `--output`, `-o` | Output file for HTML/Markdown/JSON/CSV/Excel export |
150+
| `--report-issues` | Export all detected issues (naming, size, complexity, etc.) as a markdown or JSON report |
151+
| **[Project Structure & Health]** | |
152+
| `--tree` | Show ASCII tree view of project structure |
153+
| `--structure-mermaid` | Generate a Mermaid diagram of the project directory structure |
154+
| `--health` | Show project health score and suggestions |
155+
| `--summary` | Generate a markdown project summary (print or --output) |
156+
| `--badge-sustainability` | Output SVG sustainability/health badge |
157+
| `--lang-card-svg` | Output SVG language stats card (like GitHub top-langs) |
158+
| **[Contributors / CI]** | |
159+
| `--authors` | Show git main author and last modifier for each file |
160+
| `--contributors` | Show contributor statistics (file count, line count, commit count per author) |
161+
| `--contributors-detail` | Show detailed contributor statistics |
162+
| `--hotspot` | Show most frequently changed files (git hotspots) |
163+
| `--churn` | Show most changed files in the last N days (default 30) |
164+
| `--ci` | CI/CD mode: exit non-zero if major issues found |
165+
| **[Automation / README / Badges]** | |
166+
| `--badges` | Auto-detect and print project language/framework/license/CI badges for README |
167+
| `--readme` | Auto-generate a README template based on analysis |
168+
| **[Other]** | |
169+
| `--style-check` | Check code style: indentation, line length, trailing whitespace, EOF newline |
170+
| `--openapi` | Generate OpenAPI 3.0 JSON for Flask/FastAPI routes |
171+
| `--multi <dir1> [dir2 ...]` | Analyze multiple root directories (monorepo support, **requires at least one directory**) |
172+
| `--version` | Show codestate version and exit |
173+
174+
175+
## Examples
176+
177+
```bash
178+
# Analyze the current directory (default)
179+
codestate
180+
181+
# Analyze a specific directory and exclude build and dist folders
182+
codestate myproject --exclude build dist
183+
184+
# Only analyze Python and JavaScript files
185+
codestate --only-lang py,js
186+
187+
# Show only the top 5 largest files
188+
codestate --top 5
189+
190+
# Show detailed statistics for each file
191+
codestate --details
192+
193+
# Export results as HTML
194+
codestate --html --output report.html
195+
196+
# Export results as CSV
197+
codestate --csv --output report.csv
198+
199+
# Export results as Excel
200+
codestate --excel --output report.xlsx
201+
202+
# Show only files with issues (naming, size, complexity, etc.)
203+
codestate --failures-only
204+
205+
# Show file creation and last modified time
206+
codestate --file-age
207+
208+
# Generate a markdown project summary
209+
codestate --summary --output PROJECT_SUMMARY.md
210+
211+
# Set custom complexity threshold (requires a value)
212+
codestate --complexity-threshold 5 --failures-only
213+
214+
# Analyze multiple directories (requires at least one directory)
215+
codestate --multi src tests
216+
217+
# List all file extensions with count and percentage
218+
codestate --list-extensions
219+
```
220+
221+
## Why CodeState?
106222

107-
Why use CodeState when traditional counting tools already exist?
223+
- Instant understanding: go beyond LOC to highlight duplicates, complexity hotspots, refactor candidates, naming issues, and dead code — right in your terminal.
224+
- Visual by default: ASCII pie/heatmap/bar charts make trends obvious during reviews, without leaving the CLI.
225+
- History-aware decisions: git hotspots/churn help you prioritize the files that matter most.
226+
- Team visibility: contributors and blame insights per file unlock ownership and onboarding context.
227+
- CI-ready artifacts: export HTML/Markdown/JSON/CSV/Excel for reports, dashboards, and pipelines.
228+
- Faster repeat runs: built-in caching and .gitignore support keep large repositories snappy over time.
108229

109-
1. **Beyond Lines of Code:** Pure line counters tell you how big a project is, but CodeState tells you how *healthy* it is by calculating cyclomatic complexity, extracting TODOs, and tracking comment density.
110-
2. **Git Hotspot Analysis:** CodeState natively reads your `.git` history to find files that are churning the most. It helps teams identify which legacy files are causing the most friction.
111-
3. **CI/CD Ready & Beautiful UI:** With built-in GitHub Actions support and a gorgeous `comfy-table` terminal UI, it goes from local terminal to automated PR reviews with zero friction.
230+
Tip: Combine CodeState with a GitHub Action to post a compact Markdown summary on every PR.
112231

113232
## Star History
114233

0 commit comments

Comments
 (0)