Velascat/Custodian

# Custodian Custodian 是一个可通过 pip 安装的跨仓库审计和维护工具包，专为 Python 仓库设计。它将可复用的检测器逻辑和维护辅助工具集中起来，让团队无需在每个下游仓库中重复实现相同的运维检查。 ## 为什么需要它 大型多仓库组织需要一致的健康检查和维护流程，但每个仓库都有各自的本地约定。Custodian 提供共享基础设施（检测器执行、结构稳定的结果输出、插件加载），同时允许每个下游仓库提供特定的插件和配置。 ## 快速开始 ``` pip install custodian custodian-doctor custodian-audit ``` 针对本仓库进行本地开发： ``` pip install -e .[dev] ``` ## 检测器模型 检测器按命名空间分组。每个检测器都有一个 ID、一个严重级别（LOW/MEDIUM/HIGH）以及它所需的一组分析阶段（none、`ast_forest`、`call_graph`）。 | 类别 | 数量 | 关注点 | |-------|-------|-------| | C | 24 | 文件局部代码健康度：风格、安全性、安全模式 | | D | 9 | 死代码：不可达路径、未使用的定义、无操作结构 | | F | 3 | 死字段：未使用的 dataclass / Pydantic 字段和常量 | | U | 3 | 未实现的存根：抛出 NIE / 省略号 / 仅包含文档字符串的函数体 | | K | 3 | 文档一致性：幽灵符号、值漂移、参数漂移 | | S | 4 | 结构：层级违规、循环导入、生产代码引入测试代码、conftest 防护 | | A | 2 | 架构不变量：字段数量、目录结构（声明式 YAML） | | H | 1 | 六边形分层顺序违规 | | T | 3 | 测试形态：覆盖率、断言、无条件跳过 | | G | 1 | 幽灵工作：注释中引用已移除的类型 | | N | 1 | 命名：异常类命名约定 | | P | 1 | 部分实现：空洞的返回体 | 下游仓库可以通过 `.custodian.yaml` 中的 `plugins` 配置项提供 Python 模块来添加插件检测器。具体示例请参见 `tests/fixtures/sample_consumer/`。 ## 下游配置（`.custodian.yaml`） 每个下游仓库需声明： - `repo_key`：稳定的标识符 - `src_root` 和 `tests_root`：用于扫描的相对路径 - `audit` 设置（例如过期的处理程序名称和常见词汇） - `plugins`：Custodian 使用的模块导入目标 - `maintenance` 阈值 具体示例请参见 `tests/fixtures/sample_consumer/.custodian.yaml`。 ## 版本控制与结构稳定性 Custodian 从第一天起就遵循语义化版本控制。审计输出使用 `AuditResult` 中的 `schema_version` 进行显式版本控制；v0.1 版本将输出 `schema_version = 1`。 ## 许可证 GNU Affero General Public License v3.0 或更高版本（AGPL-3.0-or-later）— 详见 [LICENSE](LICENSE)。

标签：LNA, Python, Python包, 代码健康, 代码安全, 代码审查, 代码架构, 代码规范, 依赖管理, 多仓库管理, 子域名暴力破解, 安全扫描, 开发效率工具, 开源框架, 技术债务, 持续集成, 插件化架构, 无后门, 时序注入, 死代码检测, 漏洞枚举, 自动化payload嵌入, 自动化检测, 跨仓库审计, 软件工程工具, 逆向工具, 错误基检测, 静态代码分析