infrahub-auditing-repo

Infrahub 仓库审计器

概述

根据 infrahub-skills 插件中的所有规则和最佳实践，对 Infrahub 仓库进行全面审计。生成结构化报告，涵盖架构、对象、检查、生成器、转换、菜单、.infrahub.yml 配置和部署就绪情况。

审计为只读操作。 它写入的唯一文件是自己的报告 AUDIT_REPORT.md。不会触碰工作树或索引中的其他内容，也不会对它们运行任何破坏性 git 命令，包括为了撤销审计自身造成的副作用而运行的命令。审计最适合在包含未提交工作的工作树上进行，而这正是无法撤销写入操作的工作树。

rules/audit-is-read-only.md 列出了权威清单：哪些 git 命令是 禁止的，哪些命令可以读取其他版本而 不触碰工作树。在 Phase 1 之前，请先阅读该文件 和流程的 Phase 0。Bash 工具仅获准用于 只读检查，不得用于更改状态； Write 仅获准用于报告文件。

项目上下文

项目结构： !find . -maxdepth 2 -type f \( -name "*.yml" -o -name "*.yaml" -o -name "*.py" -o -name "*.gql" -o -name "*.j2" \) 2>/dev/null | head -40

Infrahub 配置： !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

使用时机

• 将仓库部署到 Infrahub 之前
• 开始使用现有 Infrahub 项目时
• 重大重构之后，用于发现回归问题
• 作为开发工作流中的定期质量门禁
• 排查架构加载、对象同步 或流水线故障时

工作原理

调用后，审计器会：

1. 发现项目结构 （.infrahub.yml、架构、对象、检查、 生成器、转换、菜单）
2. 验证每个组件是否符合 infrahub-skills 插件中 定义的规则
3. 交叉核对组件之间的关联（例如， Python 文件与 .infrahub.yml 中的查询名称 是否匹配）
4. 生成Markdown 报告，并按严重程度整理发现项

整合这些步骤的分阶段流程位于 audit-procedure.md — 运行审计时请阅读该文件。文件从 Phase 0 开始， 规定其他所有阶段都必须遵守的只读约束；随后 定义九个阶段（项目结构 → 架构 → 对象 → Python 组件 → 交叉核对 → 注册 → 最佳实践 → 部署 → YAGNI / 修复成本），以及最终报告中 每项发现所用的严重级别。

输出第一项发现之前，请阅读 rules/audit-cites-all-reference-sites.md 和 rules/audit-verifies-proposed-syntax.md。 发现项应说明如何验证，或者在 verified_against 中说明无法验证——绝不能通过降低严重级别来处理，因为严重级别由规则决定。它 会列出所有希望修改的引用位置，并将提出的 任何筛选条件、字段或配置键，与正在审计的版本 进行核实，而非依据已发布的文档。这两项要求适用于每个阶段， 并且都会为发现项添加一个字段。

Phase 7 检查 .infrahub.yml 时，请先阅读 rules/practices-watch-dependencies.md， 再评估 watch 块：缺少键、不完整的列表以及 指向未跟踪文件的条目都会静默失败，而且在提出 该键之前，必须先对照正在审计的版本加以确认。

审计类别

优先级	类别	检查内容
CRITICAL	行为规范	审计除报告外不写入任何内容，且每项发现都披露其依据；约束审计员，而非仓库
CRITICAL	项目结构	.infrahub.yml 存在，路径有效
CRITICAL	Schema 验证	命名、关系、已弃用字段
CRITICAL	对象验证	YAML 结构、值类型、引用
CRITICAL	Python 组件	类继承、必需方法
HIGH	交叉引用	查询名称匹配、目标组
HIGH	关系	双向 ID、基数
HIGH	注册	所有文件均已注册，没有孤立文件
MEDIUM	最佳实践	human_friendly_id、display_label、watch 依赖
MEDIUM–LOW	YAGNI / 修复成本	Python 实现了 Schema、GraphQL、Jinja2 或内置 IPAM/VLAN 已能完成的功能；非规范化数据；未提取的重复结构；市场已有整套领域解决方案，却仍手动实现。严重程度按修复成本阶梯划分：第 1–3 步为 MEDIUM，第 4–7 步为 LOW
MEDIUM	部署	Git 状态、引导文件位置
LOW	模式与风格	代码组织、命名

运行审计

告诉 Claude：“审计此 Infrahub 仓库”或“运行 Infrahub 仓库审计器”

审计器将扫描当前工作目录， 按照 audit-procedure.md 中定义的阶段逐步检查，并生成下文所述的报告。

报告格式

报告将以以下结构写入项目根目录中的 AUDIT_REPORT.md：

# Infrahub Repository Audit Report

## Summary

- Total findings: N
- Critical: N | High: N | Medium: N | Low: N | Info: N
- Working tree at audit time: clean | N uncommitted files
- Tree modified by this audit: no | yes, listing paths
  (the report file itself does not count)

## Project Structure

...

## Schema Audit

...

## Object Data Audit

...

## Checks Audit

...

## Generators Audit

...

## Transforms Audit

...

## Menus Audit

...

## Cross-Reference Integrity

...

## Deployment Readiness

...

## YAGNI / Cost-to-Fix Findings

Findings sorted by `ladder_step` ascending (cheapest
fix first), then by file path. Each entry names the
rule, the ladder step, the file:line, and the
suggested replacement (schema feature, GraphQL query,
Jinja2 template, `Builtin*`/`Ipam*` inheritance, or
inverse relationship declaration).

A finding also renders the evidence it carries: a
**Sites** line listing every reference the fix must
touch, a **Verified against** line naming what the
proposed syntax was resolved against, and, on a
generic-extraction finding, a **Feasibility** verdict.

...

审计规则参考

审计器会检查所有技能中的规则：

• ../infrahub-managing-schemas/ -- 命名、 关系、属性、层级、显示、 扩展、唯一性、迁移
• ../infrahub-managing-objects/ -- 格式、 值、子项、范围、组织
• ../infrahub-managing-checks/ -- 架构、Python 类、API、注册
• ../infrahub-managing-generators/ -- 架构、Python 类、跟踪、API
• ../infrahub-managing-transforms/ -- 类型、Python/Jinja2、混合模式、制品、API
• ../infrahub-managing-menus/ -- 格式、 项目属性、层级、图标
• ../infrahub-common/ -- Git 集成、 缓存、.infrahub.yml 参考、GraphQL
• ../infrahub-common/rules/workflow-information-priority.md -- 优先使用技能内容；遇到确实的空白时（例如删除节点），了解如何查阅 docs.infrahub.app

规则与流程

• audit-procedure.md — 驱动每次审计运行的 第 0 阶段约束和九阶段检查流程
• rules/ — 各阶段引用的详细审计规则
• examples.md — 示例审计报告和问题模式