Metadata-Version: 2.1
Name: ctw
Version: 2.0.0
Summary: 快速准确的代码行数统计工具，支持 24 种编程语言，提供多维度分析（代码行数、注释、空行、圈复杂度等），支持 JSON/CSV/表格输出、Git 集成、并行扫描、增量缓存
Author-email: th35tr0n9 <th35tr0n9@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/th35tr0n9/ctw
Project-URL: Repository, https://github.com/th35tr0n9/ctw
Project-URL: Issues, https://github.com/th35tr0n9/ctw/issues
Keywords: code,counter,lines,solidity,move,statistics,loc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: prettytable
Provides-Extra: all
Requires-Dist: rich ; extra == 'all'
Requires-Dist: chardet ; extra == 'all'
Provides-Extra: chardet
Requires-Dist: chardet ; extra == 'chardet'
Provides-Extra: dev
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: rich ; extra == 'dev'
Requires-Dist: chardet ; extra == 'dev'
Provides-Extra: rich
Requires-Dist: rich ; extra == 'rich'

# ctw - 代码行数统计工具

[![PyPI version](https://badge.fury.io/py/ctw.svg)](https://pypi.org/project/ctw/)
[![Python](https://img.shields.io/pypi/pyversions/ctw.svg)](https://pypi.org/project/ctw/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

一个快速、准确的代码行数统计工具，支持 **24 种编程语言**，提供代码行数、注释、空行、导入语句、圈复杂度等多维度统计。

## 特性

- **24 种语言支持**：Solidity、Move、Python、JavaScript、TypeScript、Java、Go、Rust、C、C++、Kotlin、Swift、Scala、Ruby、PHP、Shell、SQL、C#、Dart、Lua、R、YAML、TOML、Markdown
- **多种输出格式**：表格（彩色 rich / prettytable）、JSON、CSV
- **智能分析**：纯代码行数、去重代码行数、行内注释检测、圈复杂度估算
- **灵活过滤**：按语言筛选、正则匹配文件名、自定义排除目录、`.ctwignore` 支持
- **Git 集成**：只统计 git 跟踪的文件、统计两个分支间的变更
- **高性能**：多线程并行扫描、增量缓存、文件级 SHA256 去重
- **跨平台**：支持 Windows / macOS / Linux，Python 3.7+

## 安装

```bash
pip install ctw
```

安装可选依赖以获得更好的体验：

```bash
# 彩色表格输出
pip install ctw[rich]

# 自动编码检测
pip install ctw[chardet]

# 全部可选依赖
pip install ctw[all]
```

## 快速开始

```bash
# 统计当前目录所有支持的语言
ctw

# 统计指定目录
ctw ./src

# 只统计 Python 和 Java
ctw ./src -l python java

# 查看版本
ctw -v
```

## 输出格式

### 表格输出（默认）

```bash
ctw ./src -l python --no-hash
```

```
                        代码统计 (3 个文件)
┌────────────┬────────┬────────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┐
│ 文件名     │ 语言   │ 代码行 │ 注释 │ 空行 │ 引入 │ 纯代码│ 去重 │ 行内 │ 复杂 │
├────────────┼────────┼────────┼──────┼──────┼──────┼──────┼──────┼──────┼──────┤
│ main.py    │ python │    120 │   15 │   20 │    8 │   77 │   77 │    3 │   12 │
│ utils.py   │ python │     85 │   10 │   12 │    5 │   58 │   58 │    1 │    8 │
│ config.py  │ python │     40 │    5 │    6 │    3 │   26 │   26 │    0 │    2 │
│ 合计       │        │    245 │   30 │   38 │   16 │  161 │  161 │    4 │   22 │
└────────────┴────────┴────────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┘
```

### JSON 输出

```bash
ctw ./src -l python --format json
```

```json
{
  "files": [...],
  "summary": {
    "file_count": 3,
    "total": 245,
    "comments": 30,
    "blanks": 38,
    "imports": 16,
    "pure_code": 161,
    "dedup_code": 161,
    "inline_comments": 4,
    "complexity": 22
  }
}
```

### CSV 输出

```bash
ctw ./src --format csv > report.csv
```

## 命令行参数

### 基本用法

| 参数 | 说明 |
|------|------|
| `path` | 要扫描的目录路径（默认当前目录） |
| `-v, --version` | 显示版本号 |
| `-l, --lang` | 指定语言（如 `python java solidity`） |
| `--list-langs` | 列出所有支持的语言 |

### 输出控制

| 参数 | 说明 |
|------|------|
| `-f, --format` | 输出格式：`table`（默认）、`json`、`csv` |
| `--sort-by` | 排序字段：`total`、`code`、`dedup`、`comments`、`blanks`、`complexity`、`name`、`lang` |
| `--top N` | 只显示前 N 个文件 |
| `--group` | 按语言分组显示 |
| `--no-hash` | 不显示 SHA256 列 |
| `--verbose` | 显示详细信息（进度、调试） |
| `-q, --quiet` | 安静模式，只输出数据 |

### 过滤与排除

| 参数 | 说明 |
|------|------|
| `--exclude` | 排除目录，逗号分隔（如 `test,docs,vendor`） |
| `--include` | 只统计匹配正则表达式的文件名 |

### Git 集成

| 参数 | 说明 |
|------|------|
| `--git-only` | 只统计 git 跟踪的文件 |
| `--diff` | 只统计两个 git ref 之间变更的文件（如 `main..dev`） |

### 性能选项

| 参数 | 说明 |
|------|------|
| `--cache` | 启用增量缓存（缓存到 `.ctw_cache`） |
| `--workers N` | 并行工作线程数（默认 4） |
| `--encoding` | 指定文件编码（默认自动检测，回退 utf-8） |

## 使用示例

```bash
# 按纯代码行数排序，只看前 10 个文件
ctw ./src --sort-by code --top 10

# 按语言分组统计
ctw ./src --group

# 排除测试和文档目录
ctw ./src --exclude test,docs,vendor

# 只统计文件名匹配 test_ 的文件
ctw ./src --include "test_.*"

# 只统计 git 跟踪的文件
ctw ./src --git-only

# 统计 main 和 dev 分支之间的变更
ctw ./src --diff main..dev

# JSON 输出，方便 CI/CD 集成
ctw ./src --format json --quiet

# 启用缓存加速重复扫描
ctw ./src --cache

# 指定编码处理 GBK 文件
ctw ./src --encoding gbk
```

## .ctwignore

在项目根目录创建 `.ctwignore` 文件，每行一个目录名，自动排除：

```
node_modules
vendor
.cache
generated
```

支持 `#` 开头的注释行。

## 统计指标说明

| 指标 | 说明 |
|------|------|
| 代码行数 | 文件总行数 |
| 注释 | 单行注释 + 多行注释的行数 |
| 空行 | 空白行数 |
| 版本/引入 | import、pragma、require 等导入语句行数 |
| 纯代码行数 | 总行数 - 注释 - 空行 - 导入 |
| 去重纯代码行数 | 纯代码行数 - 重复代码块行数 |
| 行内注释 | 代码行中包含注释的行数（如 `x = 1  # comment`） |
| 复杂度 | 圈复杂度估算（if/for/while/switch 等分支关键字计数） |
| SHA256 | 文件内容的 SHA256 哈希值，用于去重 |

## 支持的语言

| 语言 | 扩展名 |
|------|--------|
| Solidity | `.sol` |
| Move | `.move` |
| Python | `.py` |
| JavaScript | `.js`, `.jsx`, `.mjs` |
| TypeScript | `.ts`, `.tsx` |
| Java | `.java` |
| Go | `.go` |
| Rust | `.rs` |
| C | `.c`, `.h` |
| C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` |
| Kotlin | `.kt`, `.kts` |
| Swift | `.swift` |
| Scala | `.scala`, `.sc` |
| Ruby | `.rb` |
| PHP | `.php` |
| Shell | `.sh`, `.bash`, `.zsh` |
| SQL | `.sql` |
| C# | `.cs` |
| Dart | `.dart` |
| Lua | `.lua` |
| R | `.r`, `.R` |
| YAML | `.yml`, `.yaml` |
| TOML | `.toml` |
| Markdown | `.md`, `.markdown` |

## 作为库使用

```python
from ctw import CodeAnalyzer, print_results

analyzer = CodeAnalyzer(
    target_dir="./src",
    languages=["python", "javascript"],
    exclude_dirs={"test", "vendor"},
)
results = analyzer.run()

# 直接输出
print_results(results, output_format="json", group_by_lang=True)

# 或自行处理结果
for r in results:
    print(f"{r.filename}: {r.pure_code} 行代码, 复杂度 {r.complexity}")
```

## 开发

```bash
# 克隆仓库
git clone https://github.com/th35tr0n9/ctw.git
cd ctw

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v
```

## License

MIT
