NimaShafie/oxide-sloc

# oxide-sloc [](https://github.com/NimaShafie/oxide-sloc/actions/workflows/ci.yml) [](https://github.com/NimaShafie/oxide-sloc/actions/workflows/release.yml) [](./LICENSE) **oxide-sloc** 是一个基于 Rust 构建的源代码行分析工具，专为需要比简单行计数器更多功能的团队而打造。 一个共享的分析核心，提供多种交互方式： - **CLI** — `oxidesloc analyze / report / serve`，支持全套参数 - **快速扫描** — 在 Web UI 中一键扫描，零配置 - **本地 Web UI** — 引导式 4 步流程，支持亮/暗主题，自动打开浏览器 - **丰富的 HTML 报告** — 按文件细分、语言摘要、警告分析 - **PDF 导出** — 通过本地安装的 Chromium 在后台非阻塞生成 - **策略感知计数** — 混合代码/注释行，Python docstring - **Git submodule 支持** — 自动检测 `.gitmodules` 并生成按 submodule 细分的报告 - **CI/CD 就绪** — 包含 Jenkinsfile、GitHub Actions 和 GitLab CI 流水线 - **Confluence 集成** — 通过 REST API 推送 HTML 报告或汇总表 ## 安装说明 ### 选项 1 — 预编译二进制文件（无需 Rust） 从 [Releases 页面](https://github.com/NimaShafie/oxide-sloc/releases) 下载适用于您平台的最新二进制文件： | 平台 | 文件 | |---|---| | Linux x86-64 | `oxide-sloc-linux-x86_64` | | Windows x86-64 | `oxide-sloc-windows-x86_64.exe` | | macOS x86-64 | `oxide-sloc-macos-x86_64` | | macOS Apple Silicon | `oxide-sloc-macos-arm64` | ``` # Linux / macOS — make executable and move to PATH chmod +x oxide-sloc-linux-x86_64 mv oxide-sloc-linux-x86_64 /usr/local/bin/oxidesloc # Windows — rename and add to PATH ren oxide-sloc-windows-x86_64.exe oxidesloc.exe ``` ### 选项 2 — Docker（无需 Rust） 从 GitHub Container Registry 拉取预构建的镜像： ``` docker pull ghcr.io/nimashafie/oxide-sloc:latest ``` 或者在本地构建： ``` docker compose up ``` 在浏览器中打开 [http://localhost:4317](http://localhost:4317)。 通过 Docker 从 CLI 分析目录： ``` docker run --rm \ -v /path/to/your/repo:/repo:ro \ ghcr.io/nimashafie/oxide-sloc:latest \ analyze /repo --plain ``` Chromium 已打包在 Docker 镜像中 —— PDF 导出开箱即用。 ### 选项 3 — 从源码构建（需要 Rust 1.78+） ``` cargo install --path crates/sloc-cli ``` 或者在不安装的情况下构建： ``` cargo build --release -p oxidesloc ./target/release/oxidesloc --help ``` 所有 328 个 crate 依赖项都已打包到 `vendor/` 目录中，并且 `.cargo/config.toml` 已预配置好以使用它们 —— 在克隆之后，`cargo build` 不需要网络访问。 ### 选项 4 — 物理/离线隔离系统 对于没有互联网访问的环境，所有运行时和构建时的依赖项都已打包在此存储库中： - **Rust crate** — `vendor/` 目录，由 Cargo 自动使用 - **Chart.js** — 编译进二进制文件；Web UI 不联系任何 CDN 有关逐步的离线安装说明，请参见 [`docs/airgap.md`](./docs/airgap.md)。 ## 用法 ### CLI ``` # Analyze a directory — print summary to terminal oxidesloc analyze ./my-repo --plain # Full output: JSON + HTML report oxidesloc analyze ./my-repo \ --json-out result.json \ --html-out result.html # Per-file breakdown oxidesloc analyze ./my-repo --per-file --plain # Apply a specific counting policy oxidesloc analyze ./my-repo --mixed-line-policy separate-mixed-category --plain # Include/exclude file patterns oxidesloc analyze ./my-repo \ --include-glob "src/**" \ --exclude-glob "vendor/**" \ --plain # Custom report title oxidesloc analyze ./my-repo \ --report-title "Q2 Code Review" \ --html-out report.html # Scan a super-repository — detect git submodules and report each separately oxidesloc analyze ./mono-repo \ --submodule-breakdown \ --json-out result.json \ --html-out report.html # Re-render a report from a saved JSON (change format without re-scanning) oxidesloc report result.json --html-out report.html --pdf-out report.pdf # Start the web UI (auto-opens browser) oxidesloc serve ``` ### CLI 参数参考 | 参数 | 值 | 默认值 | 描述 | |---|---|---|---| | `--mixed-line-policy` | `code-only` `code-and-comment` `comment-only` `separate-mixed-category` | `code-only` | 如何对同时包含代码和内联注释的行进行分类 | | `--python-docstrings-as-code` | *(标志)* | off | 将 docstring 视为代码而不是注释 | | `--include-glob` | glob 模式 | *(全部)* | 仅扫描匹配此模式的文件（可重复） | | `--exclude-glob` | glob 模式 | *(无)* | 跳过匹配此模式的文件（可重复） | | `--report-title` | 字符串 | 文件夹名称 | 在 HTML/PDF 报告中显示的标题 | | `--json-out` | 路径 | *(无)* | 将 JSON 分析结果写入文件 | | `--html-out` | 路径 | *(无)* | 将 HTML 报告写入文件 | | `--pdf-out` | 路径 | *(无)* | 将 PDF 报告写入文件 | | `--per-file` | *(标志)* | off | 在终端输出中包含按文件细分的结果 | | `--plain` | *(标志)* | off | 纯终端输出（无颜色） | | `--submodule-breakdown` | *(标志)* | off | 检测 `.gitmodules` 并输出按 submodule 统计的数据 | | `--config` | 路径 | `sloc.toml` | 从 TOML 配置文件加载设置 | ### Web UI ``` oxidesloc serve # → http://127.0.0.1:4317 (opens automatically) ``` Web UI 是一个引导式的 4 步流程，并提供可选的一键快速通道： | 步骤 | 配置内容 | |---|---| | **1 — 选择项目** | 目标文件夹、包含/排除 glob 模式、git submodule 细分、实时范围预览 | | **2 — 计数规则** | 混合行策略、Python docstring 处理、生成文件/压缩文件/供应商文件/锁文件/二进制文件的处理方式 | | **3 — 输出和报告** | 扫描预设、产物预设、输出目录、报告标题 | | **4 — 检查并运行** | 所有设置的摘要，一键扫描 | ### 快速扫描 侧边栏包含一个 **快速扫描** 按钮，它会使用所有默认设置立即从第 1 步提交表单。当您不需要自定义计数规则或输出选项时使用它 —— 只需浏览到您的文件夹并点击快速扫描。 Web UI 中提供的所有内容都直接映射到 CLI 参数 —— 请参见 [Web UI → CLI 转换](#web-ui--cli-translation)。 ### 配置文件 复制示例配置并编辑： ``` cp sloc.example.toml sloc.toml ``` CLI 参数始终覆盖配置文件中的值。运行 `oxidesloc --help` 以获取完整的参数列表。 ## 目前支持的语言 | 语言 | 扩展名 | |---|---| | C | `.c`, `.h` | | C++ | `.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx` | | C# | `.cs` | | Go | `.go` | | Java | `.java` | | JavaScript | `.js`, `.mjs`, `.cjs` | | Python | `.py` | | Rust | `.rs` | | Shell | `.sh`, `.bash`, `.zsh`, `.ksh` | | PowerShell | `.ps1`, `.psm1`, `.psd1` | | TypeScript | `.ts`, `.mts`, `.cts` | ### 添加新语言 添加语言支持需要修改两个 crate： 1. **`crates/sloc-languages/src/lib.rs`** — 为 `Language` 添加一个变体，实现 `display_name`/`as_slug`/`from_name`，在 `detect_language` 中注册文件扩展名，并在 `analyze_text` 中添加一个 `ScanConfig` 条目。 2. **`crates/sloc-config/src/lib.rs`** — 如果您希望该语言默认启用，请将其名称添加到 `AnalysisConfig` 使用的任何允许列表中。 ## PDF 导出 PDF 生成使用本地安装的基于 Chromium 的浏览器（Chrome、Edge、Brave、Vivaldi 或 Opera）。生成过程在后台运行 —— Web UI 会立即返回结果，同时 PDF 正在被写入。 oxide-sloc 会首先尝试 `--headless=old`（较新的 Brave 构建需要），然后回退到 `--headless`。 如果浏览器发现失败，请手动设置路径： ``` export SLOC_BROWSER=/usr/bin/chromium oxidesloc report result.json --pdf-out result.pdf ``` PDF 下载将命名为 `.pdf`，而不是一个通用文件名。 在 Docker 中，Chromium 已打包在镜像中 —— 无需额外设置。 ## Git submodule 支持 使用 **git submodule**（一个包含数十个嵌套子项目的“超级仓库”）的项目可以通过按 submodule 隔离的方式进行分析，从而分别报告每个子项目的 SLOC 总计。 ### 工作原理 1. oxide-sloc 读取项目根目录中的 `.gitmodules` 文件。 2. 每个列出的 submodule 路径用于为每个源文件标记其父 submodule。 3. 报告包含一个额外的 **Submodule breakdown** 表，显示按 submodule 划分的文件数、代码行数、注释行数和物理行数。 4. 整个项目的总计仍包含所有文件 —— submodule 表是补充细节，而不是替代。 ### CLI 用法 ``` oxidesloc analyze ./mono-repo \ --submodule-breakdown \ --json-out out/result.json \ --html-out out/report.html ``` ### Web UI 在运行扫描之前，在第 1 步中启用 **Detect and separate git submodules** 复选框。结果页面将包含一个可折叠的 Submodule breakdown 部分。 ### TOML 配置 ``` [discovery] submodule_breakdown = true ``` ## CI/CD oxide-sloc 附带了适用于 Jenkins、GitHub Actions 和 GitLab CI 的即用型流水线文件。不需要插件或集成 —— `oxidesloc` 二进制文件是除了标准 Rust 工具链之外唯一的依赖。 有关包含 Confluence 发布在内的详细设置指南，请参见 [`docs/ci-integrations.md`](./docs/ci-integrations.md)。 ### Web UI → CLI 转换 每个 Web UI 选项都与 CLI 参数一一对应，使得在任何流水线中重现 Web 配置的扫描变得非常直接： | Web UI 步骤 | 对应的 CLI 命令 | |---|---| | 步骤 1：选择项目文件夹 | `oxidesloc analyze ./my-repo` | | 步骤 1：包含模式 | `--include-glob "src/**"` | | 步骤 1：排除模式 | `--exclude-glob "vendor/**"` | | 步骤 1：submodule 细分 | `--submodule-breakdown` | | 快速扫描按钮 | `oxidesloc analyze ./my-repo --plain` | | 步骤 2：混合行策略 | `--mixed-line-policy code-only` | | 步骤 2：将 Python docstring 视为代码 | `--python-docstrings-as-code` | | 步骤 3：JSON 输出 | `--json-out result.json` | | 步骤 3：HTML 输出 | `--html-out report.html` | | 步骤 3：PDF 输出 | `--pdf-out report.pdf` | | 步骤 3：自定义标题 | `--report-title "My Report"` | | 从保存的 JSON 重新渲染 | `oxidesloc report result.json --html-out report.html` | | 自定义配置文件 | `--config ci/sloc-ci-default.toml` | ### CI 配置预设 `ci/` 目录包含适用于常见流水线场景的即用型 `sloc.toml` 文件： | 文件 | 用例 | |---|---| | `ci/sloc-ci-default.toml` | 均衡的默认设置 —— 与 Web UI 开箱即用的行为一致 | | `ci/sloc-ci-strict.toml` | 快速失败 —— 如果发现二进制文件，流水线将报错 | | `ci/sloc-ci-full-scope.toml` | 审计模式 —— 计算所有内容，包括 vendor/lockfile | ``` # Use a preset in any pipeline stage oxidesloc analyze ./src --config ci/sloc-ci-strict.toml \ --json-out out/result.json \ --html-out out/report.html ``` ### GitHub Actions `.github/workflows/` 中提供了两个工作流： | 工作流 | 触发条件 | 功能描述 | |---|---|---| | `ci.yml` | 推送到 `main`，所有 PR | fmt → clippy → build → 单元测试 → CLI 冒烟测试 → Web UI 健康检查 | | `release.yml` | 推送 `v*` 标签 | 4 个平台的交叉编译 → 发布包含二进制文件的 GitHub Release | `ci.yml` 冒烟作业运行每种分析变体（plain、per-file、所有 4 种策略、JSON+HTML、从 JSON 重新渲染），并验证 Web UI 返回 HTTP 200。 创建一个 release： ``` git tag v0.2.0 git push origin v0.2.0 ``` ### Jenkins 存储库根目录中包含一个 `Jenkinsfile`。如果 agent 上不存在 Rust，它会自动安装。 **设置步骤：** 1. 在 Jenkins 中创建一个新的 **Pipeline** 任务。 2. 将 **Definition** 设置为 → `Pipeline script from SCM`。 3. 指向此存储库。 4. Jenkins 将自动发现 `Jenkinsfile`。 **流水线阶段：** ``` Install Rust → Format → Lint → Unit tests → Build → Smoke: plain summary → Smoke: JSON + HTML reports → Smoke: per-file breakdown → Smoke: all 4 policy variants → Smoke: re-render from JSON → Smoke: HTML content sanity → Web UI health check → Archive binary + CI reports ``` **环境变量：** | 变量 | 用途 | |---|---| | `RUST_LOG` | 跟踪详细程度 (`warn`、`info`、`debug`) | | `SLOC_BROWSER` | 覆盖 PDF 导出的 Chromium 路径（同时也会检查：`BROWSER`） | | `SLOC_API_KEY` | 启用 API 密钥认证 —— 每个请求都必须携带 `X-API-Key: ` | | `SLOC_REGISTRY_PATH` | 覆盖扫描历史记录表的位置（默认：`out/web/registry.json`） | | `SKIP_WEB_CHECK` | 设置为任何非空值以跳过 Web UI 健康检查阶段 | ### GitLab CI 存储库根目录中包含 `.gitlab-ci.yml`。将其推送到任何 GitLab 项目 —— 流水线将被自动检测。 **阶段：** `quality` → `build` → `smoke` → `archive` 冒烟作业并行运行：`smoke:plain`、`smoke:per-file`、`smoke:reports`、`smoke:re-render`、`smoke:policies`、`smoke:web-ui`。 CI 报告作为 GitLab artifacts 上传并保留 7 天。 ## 本地开发 ### 前置条件 - [Rust](https://rustup.rs) 1.78 或更高版本 - `make` (Linux/macOS) — 可选但推荐 ### Make 目标 ``` make help # list all targets make check # fmt + lint + test ← run before every push make dev # fmt + lint + test + serve make fmt # cargo fmt --all make lint # cargo clippy -D warnings make test # cargo test --workspace make build # release binary → target/release/oxidesloc make serve # start web UI on http://127.0.0.1:4317 make analyze DIR=./my-repo # CLI analyze make docker-build # build Docker image locally make docker-run # run web UI in Docker on port 4317 make clean # cargo clean ``` ### 不使用 make（Windows / 原生命令） ``` cargo fmt --all cargo clippy --workspace --all-targets --all-features -- -D warnings cargo test --workspace cargo run -p oxidesloc -- serve ``` ### 格式化 在 `rustfmt.toml` 中配置：`edition = "2021"`、`max_width = 100`。 ## 存储库布局 ``` . ├── crates/ │ ├── sloc-cli/ # CLI entry point and commands │ ├── sloc-config/ # Config schema and TOML parsing │ ├── sloc-core/ # File discovery, decoding, aggregation, JSON model │ ├── sloc-languages/ # Language detection and lexical analyzers │ ├── sloc-report/ # HTML rendering and PDF export │ └── sloc-web/ │ ├── static/ # Bundled static assets (Chart.js — no CDN needed) │ └── src/ # Localhost web UI (Axum) ├── vendor/ # All 328 Rust crate sources — enables offline builds ├── .cargo/ │ └── config.toml # Tells Cargo to use vendor/ instead of crates.io ├── ci/ │ ├── sloc-ci-default.toml # CI config preset — balanced defaults │ ├── sloc-ci-strict.toml # CI config preset — fail on binaries │ └── sloc-ci-full-scope.toml # CI config preset — audit everything ├── .github/ │ └── workflows/ │ ├── ci.yml # PR / push checks + smoke tests │ └── release.yml # Cross-platform binary releases ├── docs/ │ ├── airgap.md # Air-gapped / offline installation guide │ ├── ci-integrations.md # Jenkins, GitHub Actions, GitLab CI, Confluence │ ├── licensing.md │ └── licensing-commercial.md ├── samples/ │ └── basic/ # Fixture files used by CI smoke tests ├── Dockerfile ├── docker-compose.yml ├── Makefile ├── Jenkinsfile ├── .gitlab-ci.yml ├── sloc.example.toml └── Cargo.toml ``` ## 安全 默认情况下，oxide-sloc 绑定到 `127.0.0.1:4317`（仅本地主机）。它可以通过以下措施部署在局域网 (LAN) 或无线局域网 (WLAN) 上，供个人或团队使用。 ### 强化的默认设置 - HTTP 请求体被限制在 10 MB - 错误详细信息仅在服务器端记录；浏览器中显示通用消息 - PDF 生成使用 Rust 的 `Command::args([...])`（无 shell 插值） - 每次运行 CI 时都会通过 `cargo audit` 检查依赖项的 CVE 漏洞 ### LAN / 团队部署 **第 1 步 — 绑定到网络接口** ``` # Bind to all interfaces (or use a specific LAN IP) oxidesloc serve --bind 0.0.0.0:4317 ``` 或者在 `sloc.toml` 中设置： ``` [web] bind_address = "0.0.0.0:4317" ``` **第 2 步 — 启用 API 密钥认证** 在服务器环境中设置 `SLOC_API_KEY`。设置后，每个请求都必须携带匹配的 `X-API-Key` 头。没有正确密钥的请求将收到 HTTP 401。健康检查端点 (`/healthz`) 除外，以便负载均衡器探测能继续工作。 ``` export SLOC_API_KEY="$(openssl rand -hex 32)" oxidesloc serve --bind 0.0.0.0:4317 ``` **第 3 步 — 在反向代理处终止 TLS** oxide-sloc 传输纯 HTTP。将其置于 nginx、Caddy 或 Traefik 之后以进行 HTTPS 终止： ``` server { listen 443 ssl; server_name sloc.internal; ssl_certificate /etc/ssl/certs/sloc.crt; ssl_certificate_key /etc/ssl/private/sloc.key; location / { proxy_pass http://127.0.0.1:4317; proxy_set_header X-API-Key $http_x_api_key; } } ``` 要私下报告漏洞，请参见 [`SECURITY.md`](./SECURITY.md)。 ## 许可证 [AGPL-3.0-or-later](./LICENSE)。商业支持、托管服务和专有附加组件可通过单独的安排提供。请参见 [`docs/licensing.md`](./docs/licensing.md) 和 [`docs/licensing-commercial.md`](./docs/licensing-commercial.md)。 ## 维护者 **Nima Shafie** — [github.com/NimaShafie](https://github.com/NimaShafie)

标签：CLI, Confluence集成, GitHub Actions, GitLab CI, Git子模块, HTML报告生成, IPv6支持, Jenkins, PDF导出, Python安全, Rust, SLOC, SOC Prime, TCP SYN 扫描, Web UI, WiFi技术, 人体姿态估计, 代码行数统计, 可视化界面, 开发工具, 源代码分析, 网络流量审计, 自动笔记, 请求拦截, 软件度量, 通知系统, 错误基检测, 静态代码分析