hier_config AGENTS.md

hier_config — Agent & Contributor Guide

This file is the canonical quick reference for AI coding agents (and humans) working in this repository. The deep documentation lives in docs/ and on Read the Docs; this file is the index.

Project Overview

hier_config is a Python library that compares network device configurations (running vs intended) and generates minimal remediation commands. It parses config text into hierarchical trees and computes diffs respecting vendor-specific syntax rules. Runtime dependencies are deliberately minimal (pydantic only).

Build & Test Commands

All commands use poetry (not pip):

# Full lint + test suite (what CI runs)
poetry run ./scripts/build.py lint-and-test

# Lint only (ruff, mypy, pyright, pylint, yamllint, flynt — run in parallel)
poetry run ./scripts/build.py lint

# Tests only (95% coverage required)
poetry run ./scripts/build.py pytest --coverage

# Run a single test
poetry run pytest tests/test_driver_cisco_xr.py::test_name -v

# Run a single test file
poetry run pytest tests/test_driver_cisco_xr.py -v

# Auto-fix formatting
poetry run ruff format hier_config tests scripts

# Validate docs (required if docs/ or mkdocs.yml changed)
poetry run mkdocs build --strict

Architecture in Brief

Three-layer design — full detail in docs/dev/architecture.md:

• Tree (base.py, root.py, child.py, children.py): HConfig root and HConfigChild nodes; key operations config_to_get_to(), future(), unified_diff(), dump_simple().
• Driver (platforms/): each platform subclasses HConfigDriverBase and overrides _instantiate_rules() returning HConfigDriverRules — typed, frozen Pydantic rule models matched against config lineage via MatchRule tuples.
• Workflow (workflows.py, reporting.py): WorkflowRemediation exposes remediation_config / rollback_config; constructors live in constructors.py (get_hconfig(), get_hconfig_fast_load(), get_hconfig_driver()).