reiidoda/OccamO

# OccamO：复杂度与性能回归监控           OccamO 是一款面向 CI 的分析器，用于发现算法复杂度热点和回归问题。它将基准分支（main）与 PR 分支进行对比，通过稳定的 ID 匹配函数，并仅报告变差的部分。可选的规则引擎、调用图加权、热路径信号和动态验证功能让输出更具可操作性。 OccamO 也是一个适用于 CI/CD 流水线和 GitHub Actions 的静态分析与性能回归测试工具，提供 SARIF/code-scanning 集成以及基于策略的质量门禁。 核心亮点： - 真正的基线回归差异对比，提供前后风险评分和提示。 - 稳定的函数 ID（路径 + qualname + 标准化主体哈希）确保可靠的差异对比。 - 仅变更和差异函数模式，有效降低 PR 中的噪音。 - 基础设施即代码的门禁（警告/失败阈值、预算、不可回归路径）。 - GitHub 原生用户体验：PR 评论、Job 摘要、注释、检查运行、SARIF。 - 多种输出格式：JSON、Markdown、HTML、SARIF、趋势、Slack/Teams、代码片段。 - 可选支持通过 tree-sitter 分析 JS/TS/Java/Kotlin/Go。 ## 主要用途 - 在合并前检测 Pull Request 中的复杂度回归。 - 在 CI/CD 流水线中强制执行性能和代码质量门禁。 - 为代码扫描和安全/合规工具生成 SARIF。 - 在 PR 评论和检查运行中展示对开发者友好的发现。 - 随时间推移追踪性能风险的趋势数据。 ## 目录 - 安装 - 快速开始 - 主要用途 - GitHub Actions - 基线 - 配置 - 输出 - 语言支持 - 动态验证 - 集成 - VS Code 扩展 - 开发者体验 - 基准测试 - SEO 与可发现性 - 文档与策略 - 贡献 ## 安装 ``` pip install occamo ``` 扩展组件： ``` pip install "occamo[gitignore]" # gitignore-style .occamoignore matching pip install "occamo[bench]" # benchmark harness pip install "occamo[js]" # JS/TS/Java/Kotlin/Go analysis via tree-sitter pip install "occamo[dev]" # lint/test/dev tools ``` ## 快速开始 ``` occamo init --preset minimal occamo analyze . --changed-only ``` 典型的 PR 命令： ``` occamo analyze . \ --changed-only \ --compare-base \ --md out/occamo.md \ --json out/occamo.json ``` ## GitHub Actions 直接使用 CLI： ``` name: OccamO on: pull_request: push: branches: [ main ] jobs: occamo: permissions: contents: read pull-requests: write # only if posting PR comments checks: write # only if posting check runs security-events: write # only if uploading SARIF runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: "3.12" - name: Install OccamO run: pip install ./ - name: Analyze run: | occamo analyze . --changed-only --compare-base \ --md out/occamo.md \ --json out/occamo.json \ --sarif out/occamo.sarif - name: Job summary run: cat out/occamo.md >> $GITHUB_STEP_SUMMARY - name: Upload SARIF uses: github/codeql-action/upload-sarif@v3 with: sarif_file: out/occamo.sarif ``` 复合操作： ``` - uses: reiidoda/OccamO/action@v1 with: install: "true" install_target: "occamo" compare_base: "true" baseline_auto: "true" comment_out: "out/occamo.comment.md" post_comment: "true" check_run_out: "out/occamo.check_run.json" post_check_run: "true" ``` 如果需要不可变的操作版本以保证构建的可复现性，请固定使用 `@v1.x.y`。 ## 基线 在默认分支上生成基线，并在 PR 中自动下载： ``` name: OccamO Baseline on: push: branches: [ main ] jobs: baseline: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-python@v5 with: python-version: "3.12" - run: pip install ./ - run: occamo baseline . --json out/occamo.json - uses: actions/upload-artifact@v4 with: name: occamo-baseline path: out/occamo.json ``` 在非 GitHub CI 中，将基线 JSON 存储为构建产物，并通过 `--baseline-json` 传入。 ## 配置 创建 `.occamo.yml`（完整模板请参见 `.occamo.example.yml`）： ``` include: - "src" exclude: - "tests" changed_only: true compare_base: true diff_functions: true new_findings_only: true languages: - "python" gating_preset: "balanced" ``` 注意事项： - 使用 `.occamoignore` 进行 gitignore 风格的排除（通过 `occamo[gitignore]` 安装）。 - 使用 `# occamo: ignore reason="..." ticket="ABC-123"` 忽略某个函数。 - 使用 `occamo config validate` 验证配置，使用 `occamo config show` 检查配置。 - JS/TS/Java/Kotlin/Go 分析需要安装 `occamo[js]` 并设置 `languages`。 - 使用 `min_function_lines` 跳过小型辅助函数，在 PR 中使用 `new_findings_only`。 - 使用预算和不可回归路径来保护关键区域。 ## 输出 OccamO 可以生成： - JSON 报告 - Markdown 摘要 - HTML 报告 - SARIF - GitHub 注释 - PR 评论 Markdown - Check-run 负载 - 趋势 JSON + HTML - Slack/Teams 通知负载 - 快速修复代码片段（可直接复制粘贴的模板） 报告模式：`schema/occamo.schema.json`。 ## 语言支持 - Python（内置） - JavaScript/TypeScript, Java, Kotlin, Go（可选，通过 `occamo[js]`） ## 动态验证 动态验证在子进程中执行代码，以确认或降低静态分析的发现等级。此功能可选，建议仅在受信任的 CI 环境中使用。 有关复现性指导，请参见 `docs/REPRODUCIBILITY.md`。 ## 集成 OccamO 优先支持 CLI，可在 GitLab CI、Jenkins 和 Azure DevOps 中运行。 复制/粘贴示例请参见 `docs/INTEGRATIONS.md`。 ## VS Code 扩展 Beta 版扩展位于 `vscode/` 目录，可将 OccamO JSON 报告加载为编辑器诊断。设置说明请参见 `vscode/README.md`。 ## 开发者体验 Pre-commit hook： ``` repos: - repo: https://github.com/reiidoda/OccamO rev: v0.1.0 hooks: - id: occamo args: [--changed-only, --diff-functions, --new-findings-only, --max-findings, "25"] ``` 快速修复代码片段： ``` occamo analyze . --snippets out/occamo.snippets.md ``` ## 基准测试 ``` occamo-bench --json out/occamo.bench.json occamo-bench --json out/occamo.bench.pr.json \ --baseline out/occamo.bench.json --max-regression 0.15 ``` ## SEO 与可发现性 OccamO 针对以下搜索意图： - static analysis for performance regressions - complexity analysis tool for CI/CD - GitHub Actions code-quality gate - SARIF performance/code scanning output - pull request regression guard for Python and polyglot repos 有关持续的可发现性指导和仓库元数据策略，请参见 `docs/SEO_DISCOVERABILITY.md`。 ## 文档与策略 - 架构：`docs/ARCHITECTURE.md` - 系统设计：`docs/SYSTEM_DESIGN.md` - 面向对象设计：`docs/OO_DESIGN.md` - 设计模式：`docs/DESIGN_PATTERNS.md` - 企业蓝图：`docs/ENTERPRISE_BLUEPRINT.md` - 项目结构：`docs/PROJECT_STRUCTURE.md` - 路线图：`docs/ROADMAP.md` - 测试策略：`docs/TESTING_STRATEGY.md` - 数据库策略：`docs/DATABASE_STRATEGY.md` - API 设计与安全：`docs/API_SECURITY.md` - UML 视图：`docs/UML.md` - AI/ML 策略：`docs/AI_ML_DS_NEUROSCIENCE.md` - 参考手册映射：`docs/REFERENCE_MANUAL_MAPPING.md` - SEO/可发现性策略：`docs/SEO_DISCOVERABILITY.md` - 外部 SEO 增长指南：`docs/SEO_EXTERNAL_GROWTH.md` - 文档索引：`docs/README.md` - 规则与 Rule SDK：`docs/RULES.md`、`docs/RULE_SDK.md` - IR 模型：`docs/IR.md` - 策略食谱：`docs/POLICY_COOKBOOK.md` - ADR 流程：`docs/ADR.md` - 供应链：`docs/SUPPLY_CHAIN.md` - 发布：`docs/RELEASING.md` - 治理：`GOVERNANCE.md` - 支持：`SUPPORT.md` - 隐私：`PRIVACY.md` - 安全：`SECURITY.md` ## 贡献 请参见 `CONTRIBUTING.md` 和 `CODE_OF_CONDUCT.md`。 ## 许可证 Apache-2.0

标签：GitHub Actions, Hotspot 检测, IPv6支持, Pull Request 检查, Python, SARIF, Tree-sitter, 云安全监控, 基准比对, 复杂度分析, 性能回归测试, 无后门, 策略即代码, 算法复杂度, 聊天机器人安全, 自动笔记, 请求拦截, 质量控制门, 逆向工具, 静态分析