# Crow Config Documentation

Welcome to the technical reference manual for **`crow-config`**, the standalone configuration parsing and surgical editing engine built for **Crow** ([crow-config.errorware.net](https://crow-config.errorware.net)).

---

## The Problem `crow-config` Solves

System administration interfaces and web control panels (such as Webmin, Cockpit, or custom DevOps scripts) routinely corrupt server configuration files. Standard serialization approaches (deserializing to an Abstract Syntax Tree or struct and serializing back) suffer from catastrophic flaws when dealing with production Linux files:

1. **Comment Stripping**: Comments explaining firewall exceptions, deprecated subnets, or compliance requirements are destroyed.
2. **Formatting Flattening**: Alignment whitespace, intentional indentation, and blank grouping lines are wiped out, creating massive, noisy Git diffs.
3. **Loss of Directive Ordering**: Many Linux configurations (such as PostgreSQL's `pg_hba.conf` and Linux `ufw` rules) are strictly **order-dependent** ("first match wins"). A naive re-serializer that sorts keys or re-orders lines silently inverts firewall priorities or opens databases to unauthorized access.
4. **Panic Fragility**: An unexpected flag or trailing syntax element triggers a parser crash, rendering the management tool unusable on custom setups.

`crow-config` solves this with a **lossless Concrete Syntax Tree (CST)**, a **declarative semantic schema layer**, and an **intermediate representation (IR)** designed explicitly for generic UI widgets.

---

## Workspace Architecture

The engine is organized into two primary crates:

| Crate | Purpose | Dependencies |
| :--- | :--- | :--- |
| [`crow-config-core`](architecture.md) | Core engine abstractions: `CstNode`, `Span`, `SourceSpan`, `SyntaxKind`, `PluginManifest`, `WidgetKind`, `FieldType`, `RiskLevel`, `RowIr`, `FieldIr`, `EditOp`, `ConfigPlugin`, `ConfigDocument`. | `serde`, `serde_json`, `toml`, `thiserror` |
| [`crow-config-schemas`](schema-manifests.md) | Authored format plugins (`HostsPlugin`, `SshdPlugin`, `PgHbaPlugin`, `UfwPlugin`), embedded TOML schemas, real-world test data, diagnostic IR dump tools, and property tests. | `crow-config-core`, `serde`, `serde_json`, `toml`, `proptest` |

---

## Table of Contents

### 1. Architecture & Internals
- [**Three-Layer Architecture**](architecture.md)
  How raw file buffers flow through CST tokenization, schema mapping, and View-Binding IR generation.
- [**Lossless CST Engine**](cst-engine.md)
  Deep dive into `CstNode`, trivia preservation, byte spans, and panic-free error recovery.
- [**Semantic Schema Manifests**](schema-manifests.md)
  Specification of TOML manifests, field validation, risk ratings, and external tool validators.
- [**View-Binding IR**](view-binding-ir.md)
  The generic UI JSON contract: `rule_table`, `key_value_list`, and row structures.
- [**Mutation Engine & In-Place Editing**](mutation-api.md)
  Applying `EditOp` operations (`UpdateField`, `DeleteRow`, `InsertRow`, `MoveRow`) directly to the CST.

### 2. Format Plugins
- [**/etc/hosts**](plugins/hosts.md)
  Static host mapping table, IP validation, host alias lists, and inline comments.
- [**sshd_config**](plugins/sshd.md)
  OpenSSH daemon configuration, directive precedence, and high-consequence risk ratings.
- [**pg_hba.conf**](plugins/pg-hba.md)
  PostgreSQL client authentication, first-match-wins order sensitivity, and auth method risk.
- [**ufw.rules**](plugins/ufw.md)
  Ubuntu Uncomplicated Firewall rules, action precedence, and port/protocol filters.

### 3. Developer Guides
- [**Authoring New Format Plugins**](authoring-plugins.md)
  Step-by-step guide to writing a custom format plugin with manifests, parsers, binders, and mutators.
- [**Testing & Verification**](testing-and-verification.md)
  Lossless round-trip tests, proptest fuzzing invariants, and diagnostic CLI tools.