infrahub-auditing-repo

Infrahub Repo Auditor

Overview

Comprehensive audit of an Infrahub repository against all rules and best practices from the infrahub-skills plugin. Produces a structured report covering schemas, objects, checks, generators, transforms, menus, .infrahub.yml configuration, and deployment readiness.

Project Context

Project structure: !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 config: !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"

When to Use

• Before deploying a repository to Infrahub
• When onboarding to an existing Infrahub project
• After significant refactoring to catch regressions
• As a periodic quality gate in development workflows
• When troubleshooting schema loading, object sync, or pipeline failures

How It Works

When invoked, the auditor:

1. Discovers the project structure (.infrahub.yml, schemas, objects, checks, generators, transforms, menus)
2. Validates each component against the rules defined in the infrahub-skills plugin
3. Cross-references between components (e.g., query names match between Python files and .infrahub.yml)
4. Generates a markdown report with findings organized by severity

The phased procedure that ties these steps together lives in audit-procedure.md — read that file when running an audit. It defines the eight phases (project structure → schema → objects → Python components → cross-references → registration → best practices → deployment) and the per-finding severity levels used in the final report.

Audit Categories

Priority	Category	What It Checks
CRITICAL	Project Structure	.infrahub.yml exists, paths valid
CRITICAL	Schema Validation	Naming, relationships, deprecated fields
CRITICAL	Object Validation	YAML structure, value types, refs
CRITICAL	Python Components	Class inheritance, required methods
HIGH	Cross-References	Query names match, target groups
HIGH	Relationships	Bidirectional IDs, cardinality
HIGH	Registration	All files registered, no orphans
MEDIUM	Best Practices	human_friendly_id, display_label
MEDIUM	Deployment	Git status, bootstrap placement
LOW	Patterns & Style	Code organization, naming

Running the Audit

Tell Claude: "Audit this Infrahub repo" or "Run the Infrahub repo auditor"

The auditor will scan the current working directory, walk the phases defined in audit-procedure.md, and produce the report described below.

Report Format

The report is written to AUDIT_REPORT.md in the project root with this structure:

# Infrahub Repository Audit Report

## Summary

- Total findings: N
- Critical: N | High: N | Medium: N | Low: N | Info: N

## Project Structure

...

## Schema Audit

...

## Object Data Audit

...

## Checks Audit

...

## Generators Audit

...

## Transforms Audit

...

## Menus Audit

...

## Cross-Reference Integrity

...

## Deployment Readiness

...

Audit Rules Reference

The auditor checks rules from all skills:

• ../infrahub-managing-schemas/ -- Naming, relationships, attributes, hierarchy, display, extensions, uniqueness, migration
• ../infrahub-managing-objects/ -- Format, values, children, ranges, organization
• ../infrahub-managing-checks/ -- Architecture, Python class, API, registration
• ../infrahub-managing-generators/ -- Architecture, Python class, tracking, API
• ../infrahub-managing-transforms/ -- Types, Python/Jinja2, hybrid, artifacts, API
• ../infrahub-managing-menus/ -- Format, item properties, hierarchy, icons
• ../infrahub-common/ -- Git integration, caching, .infrahub.yml reference, GraphQL

Rules and Procedure

• audit-procedure.md — the eight-phase walkthrough that drives every audit run
• rules/ — detailed audit rule definitions referenced from the phases
• examples.md — sample audit reports and finding patterns