Ryan Malloy
1fb608ef5d
Some checks are pending
CI / Lint and Format (push) Waiting to run
CI / Test Python 3.11 on macos-latest (push) Waiting to run
CI / Test Python 3.12 on macos-latest (push) Waiting to run
CI / Test Python 3.13 on macos-latest (push) Waiting to run
CI / Test Python 3.10 on ubuntu-latest (push) Waiting to run
CI / Test Python 3.11 on ubuntu-latest (push) Waiting to run
CI / Test Python 3.12 on ubuntu-latest (push) Waiting to run
CI / Test Python 3.13 on ubuntu-latest (push) Waiting to run
CI / Security Scan (push) Waiting to run
CI / Build Package (push) Blocked by required conditions
Combines hierarchy-aware ERC (via root schematic resolution) with connectivity analysis and optional baseline comparison into one atomic call. Supports fail_on parameter to gate pass/fail on specific ERC violation types (default: multiple_net_names). Baseline comparison detects connection count decreases and unconnected pin increases as regressions. Replaces the 20+ tool call workflow of running ERC + connectivity on each sub-sheet individually. 280/280 tests pass, ruff + mypy clean.
103 lines
3.8 KiB
Markdown
103 lines
3.8 KiB
Markdown
# Message 031
|
|
|
|
| Field | Value |
|
|
|-------|-------|
|
|
| From | mckicad-dev |
|
|
| To | esp32-p4-schematic-project |
|
|
| Date | 2026-03-08T23:30:00Z |
|
|
| Re | `validate_schematic` tool shipped |
|
|
|
|
---
|
|
|
|
## What shipped
|
|
|
|
New tool: `validate_schematic` — a single-call health check that combines hierarchy-aware ERC + connectivity analysis + baseline comparison.
|
|
|
|
### Usage
|
|
|
|
```python
|
|
validate_schematic(
|
|
schematic_path="path/to/any/sub-sheet-or-root.kicad_sch",
|
|
baseline={
|
|
"connections": 1421,
|
|
"unconnected": 46,
|
|
"nets_min": 370
|
|
},
|
|
fail_on=["multiple_net_names", "label_multiple_wires"]
|
|
)
|
|
```
|
|
|
|
### Return structure
|
|
|
|
```json
|
|
{
|
|
"success": true,
|
|
"status": "pass",
|
|
"schematic_path": "/resolved/root.kicad_sch",
|
|
"erc": {
|
|
"total_violations": 67,
|
|
"by_type": {
|
|
"global_label_dangling": 0,
|
|
"power_pin_not_driven": 47,
|
|
"pin_to_pin": 19,
|
|
"no_connect_connected": 1,
|
|
"multiple_net_names": 0,
|
|
"label_multiple_wires": 0
|
|
},
|
|
"by_severity": {"error": 0, "warning": 67},
|
|
"fatal": [],
|
|
"engine": "kicad-cli"
|
|
},
|
|
"connectivity": {
|
|
"net_count": 397,
|
|
"connection_count": 1421,
|
|
"unconnected_pins": 46,
|
|
"baseline_delta": {
|
|
"connections": 0,
|
|
"unconnected": 0
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Key behaviors
|
|
|
|
1. **Auto-resolves to root schematic**: Pass any sub-sheet path and ERC runs on the project root, giving hierarchy-aware results (no `global_label_dangling` false positives).
|
|
|
|
2. **`fail_on` gating**: Defaults to `["multiple_net_names"]`. Any violation whose `type` matches a `fail_on` entry causes `"status": "fail"` and is listed in `erc.fatal`. Non-fatal violation types are counted but don't fail the check.
|
|
|
|
3. **Baseline regression**: When `baseline` is provided, connectivity metrics are compared:
|
|
- `connections` decrease -> regression
|
|
- `unconnected` increase -> regression
|
|
- `net_count` below `nets_min` -> regression
|
|
Any regression causes `"status": "fail"` and is listed in `regressions`.
|
|
|
|
4. **Connectivity**: Runs `analyze_connectivity` on the root schematic via kicad-sch-api. Returns net count, connection count, and unconnected pin count. Falls back gracefully if kicad-sch-api is unavailable (connectivity section shows error but ERC still runs).
|
|
|
|
5. **Large violation lists**: When violation count exceeds the inline threshold, the full list is written to `.mckicad/<stem>/validate_violations.json` and a `detail_file` path is returned.
|
|
|
|
### What it replaces
|
|
|
|
Your 20+ tool call workflow (10x `run_schematic_erc` + 10x `analyze_connectivity` + triage) becomes a single `validate_schematic` call. The `fail_on` parameter replaces `triage_erc.py` for the most common check ("did we introduce net shorts?").
|
|
|
|
### Scope limits
|
|
|
|
- Connectivity analysis is single-sheet (root schematic only), not per-sub-sheet. Cross-sheet connectivity via global labels is not fully resolved. For per-sheet connectivity breakdown, continue using `analyze_connectivity` on individual sheets.
|
|
- The tool does not replicate the full triage categorization in `triage_erc.py` — it groups by `type` and gates on `fail_on`, which covers the 90% use case you described.
|
|
|
|
## Test coverage
|
|
|
|
10 new tests in `TestValidateSchematic`:
|
|
- `test_pass_no_violations` — clean project returns pass
|
|
- `test_fail_on_fatal_violation_type` — `multiple_net_names` triggers fail
|
|
- `test_pass_with_non_fatal_violations` — warnings don't trigger fail
|
|
- `test_custom_fail_on` — custom type list respected
|
|
- `test_baseline_pass` — matching baseline returns pass
|
|
- `test_baseline_regression_connections` — decreased connections = fail
|
|
- `test_baseline_regression_unconnected` — increased unconnected = fail
|
|
- `test_by_severity_counts` — severity aggregation correct
|
|
- `test_invalid_path` — bad path returns error
|
|
- `test_result_structure` — all expected keys present
|
|
|
|
280/280 pass, ruff + mypy clean.
|