https://github.com/iannil/code-lint-x
CODE-LINT-X is a static code analysis tool that detects Concept Compression in software architecture — when data fields (especially enums and integer fields) carry too many responsibilities, leading to complex conditional logic and maintainability issues.
https://github.com/iannil/code-lint-x
analysis code lint
Last synced: 9 days ago
JSON representation
CODE-LINT-X is a static code analysis tool that detects Concept Compression in software architecture — when data fields (especially enums and integer fields) carry too many responsibilities, leading to complex conditional logic and maintainability issues.
- Host: GitHub
- URL: https://github.com/iannil/code-lint-x
- Owner: iannil
- Created: 2026-01-25T08:27:47.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2026-01-25T10:16:13.000Z (5 months ago)
- Last Synced: 2026-01-26T01:07:05.056Z (5 months ago)
- Topics: analysis, code, lint
- Language: Rust
- Homepage: https://zhurongshuo.com/products/code-lint-x/
- Size: 229 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# CODE-LINT-X
> Stop guessing what `status == 3` means.
[](https://crates.io/crates/code-lint-x)
[](https://docs.rs/code-lint-x)
[](https://opensource.org/licenses/MIT)
**CODE-LINT-X** is a static code analysis tool that detects **Concept Compression** in software architecture — when data fields (especially enums and integer fields) carry too many responsibilities, leading to complex conditional logic and maintainability issues.
Based on the principle *"Data Redundancy > Control Complexity"*, CODE-LINT-X helps teams identify and refactor "Global Enums" that silently erode code quality.
---
## The Problem
```java
// Anti-pattern: Concept Compression
if (order.type == 4) { ... } // What is type 4?
// The enum has 15 values, used in 47 places across 12 packages
enum OrderType {
NORMAL, PREORDER, VIRTUAL, PRESALE, GROUP, FLASH_SALE, ...
}
```
**This leads to:**
- :hourglass: Cognitive overload when reading code
- :bug: Hidden bugs from misunderstood meanings
- :snail: Difficult maintenance and testing
- :x: High coupling across modules
---
## The Solution
```java
// Explicit, self-documenting data
if (order.is_virtual) { ... }
if (order.requires_payment) { ... }
if (order.is_group_order) { ... }
```
> *"The storage cost of an extra field is far less than the cognitive cost of maintaining if/else chains."*
---
## Features
### Core Detectors
| Detector | Description |
|----------|-------------|
| **Global Enum Detector** | Identifies enums with excessive responsibilities using Compression Index |
| **Comment Smell Detector** | Finds explanatory comments that indicate poor design (`// special case`, `// TODO`, etc.) |
| **Context-Aware Filtering** | Reduces false positives by recognizing legitimate patterns (state machines, factory patterns) |
### Multi-Language Support
| Language | Status | Features |
|----------|--------|----------|
| :coffee: Java | :white_check_mark: Full | Enums, constants, switch/if statements |
| :gopher: Go | :white_check_mark: Full | iota constants, interfaces |
| :typescript: TypeScript | :white_check_mark: Full | Enums, union types, literal types |
| :snake: Python | :white_check_mark: Full | Enum classes, old-style constants |
### Team Collaboration
- :chart_with_upwards_trend: **Trend Tracking** — Track complexity evolution over time
- :dashboard: **Team Dashboard** — Module health scores, Top 10 riskiest fields
- :hammer: **Refactoring Suggestions** — AI-free heuristic recommendations with before/after examples
- :chart: **Impact Analysis** — Change scope, risk level, estimated effort, migration plan
### CI/CD Integration
- Git hooks (pre-commit, pre-push)
- GitHub Actions compatible
- JSON/HTML report formats
- Configurable thresholds via `.codelintrc`
---
## Installation
### From Crates.io (Recommended)
```bash
cargo install code-lint-x
```
### From Source
```bash
git clone https://github.com/iannil/code-lint-x.git
cd code-lint-x
cargo install --path .
```
---
## Quick Start
### Basic Scan
```bash
# Scan your project
code-lint-x scan ./src
# Generate HTML report
code-lint-x scan ./src --format html --output report.html
# JSON output for CI/CD
code-lint-x scan ./src --format json --output results.json
```
### Configuration
Create `.codelintrc` in your project root:
```toml
[thresholds]
compression_index = "warning:30, error:60"
[detector.god_enum]
enabled = true
min_enum_values = 3
[detector.comment_smell]
enabled = true
keywords = ["special case", "except", "temporary", "hack", "TODO"]
[ignore]
paths = ["generated/", "vendor/", "*_test.go"]
[output]
format = "json"
sort_by = "severity"
```
### Git Hooks
```bash
# Install pre-commit hook
code-lint-x hook install
# Uninstall hooks
code-lint-x hook uninstall
```
### Trend Analysis
```bash
# View trends over time
code-lint-x trend --since "1 month ago"
# Group by module
code-lint-x trend --by-module
# Group by author
code-lint-x trend --by-author
```
---
## Compression Index
The **Compression Index** measures how much responsibility a single field carries:
```
Compression Index = (Control Flow References × Unique Packages) / Enum Values
```
| Index | Level | Action |
|-------|-------|--------|
| 0-20 | :white_check_mark: Healthy | No action needed |
| 20-40 | :warning: Warning | Consider refactoring |
| 40+ | :x: Critical | Refactoring recommended |
---
## Example Output
```
SCANNING: /path/to/project
├── Found 23 suspect enums
├── Found 47 comment smells
┌─ Global ENUM DETECTION ────────────────────────────────────┐
│ │
│ OrderType (order/Order.java:42) │
│ ├── Compression Index: 87.3 :x: CRITICAL │
│ ├── 15 enum values │
│ ├── 47 control flow references │
│ ├── Used in 12 packages │
│ │ │
│ Suggested Refactoring: │
│ ├─ Split into: is_virtual, is_preorder, is_group │
│ ├─ New enums: FulfillmentMode, PaymentMethod │
│ └─ Expected compression: 87.3 → 12.4 │
│ │
└────────────────────────────────────────────────────────────┘
```
---
## CLI Reference
```bash
code-lint-x [OPTIONS]
COMMANDS:
scan Scan source code for concept compression
trend Show trend analysis over time
dashboard Generate team dashboard
hook Manage git hooks
config Configuration management
init Initialize configuration file
help Show this help message
SCAN OPTIONS:
-p, --path Path to scan [default: .]
-f, --format Output format: text|json|html [default: text]
-o, --output Write output to file
-c, --config Config file [default: .codelintrc]
--since Incremental scan since commit
```
---
## Architecture
```
src/
├── analyzer/ # Smart refactoring suggestions
│ ├── suggester.rs # Generate actionable recommendations
│ ├── impact.rs # Analyze change impact and scope
│ └── context.rs # Context-aware filtering
├── cli/ # Command-line interface
├── config/ # Configuration file parser
├── core/ # AST definitions, tracer, metrics
├── detector/ # Detection algorithms
│ ├── god_enum.rs # Compression index calculator
│ └── comment_smell.rs # Comment pattern matcher
├── integration/ # Git hooks, CI/CD
├── lang/ # Language-specific parsers
│ ├── java/
│ ├── go/
│ ├── typescript/
│ └── python/
├── report/ # Report generation
│ ├── trend.rs # Historical trend tracking
│ └── dashboard.rs # Team dashboard HTML
└── scanner/ # Project scanner orchestrator
```
---
## Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## Development
```bash
# Clone the repo
git clone https://github.com/iannil/code-lint-x.git
cd code-lint-x
# Run tests
cargo test
# Run with debug output
cargo run -- scan ./tests/fixtures --format json
# Format code
cargo fmt
# Run linter
cargo clippy
```
---
## Philosophy
> "Your code is trying to tell you something. Are you listening?"
We use linters to check syntax errors. But who checks for **design rot**?
CODE-LINT-X is the first static analysis tool focused on **Concept Compression** — the silent killer of software architecture.
Don't let an `Integer` destroy your architecture. **Decompress it.**
---
## License
[MIT License](LICENSE)
---
## Links
- [Documentation](docs/index.md)
- [Project Status](docs/project/status.md)
- [Architecture](docs/project/architecture.md)
- [Book](https://zhurongshuo.com/practices/season-4/data-as-the-boundary/) — *Data as Boundary: Refactoring Software Complexity*
---
## Acknowledgments
Inspired by:
- *Yoni Goldberg's* [Node.js Best Practices](https://github.com/goldbergyoni/nodebestpractices)
- *Martin Fowler's* [Refactoring](https://refactoring.com/)
- *Michael Feathers'* Working Effectively with Legacy Code