docs(02-01): complete INF parser plan

- 02-01-SUMMARY.md: TDD execution summary with deviation notes - STATE.md: updated position, decisions, metrics, session - ROADMAP.md: phase 2 progress updated (1/2 summaries) - REQUIREMENTS.md: DRV-02 and DRV-05 marked complete
2026-04-10 11:57:54 +02:00
parent 5056922890
commit 17db5ce1a8
4 changed files with 108 additions and 11 deletions
@@ -0,0 +1,94 @@
+---
+phase: "02"
+plan: "01"
+subsystem: inf-parser
+tags: [tdd, inf-parsing, encoding-detection, token-resolution, driver-management]
+dependency_graph:
+  requires: []
+  provides: [inf-parser-service]
+  affects: [02-02-upload-endpoint, 02-03-drivers-ui]
+tech_stack:
+  added: []
+  patterns: [RawConfigParser-strict-false, BOM-sniffing, optionxform-str, set-dedup-sorted]
+key_files:
+  created:
+    - imptune/services/__init__.py
+    - imptune/services/inf_parser.py
+    - tests/test_inf_parser.py
+    - tests/fixtures/sample.inf
+    - tests/fixtures/sample_utf16.inf
+    - tests/fixtures/sample_multi_model.inf
+  modified: []
+decisions:
+  - "optionxform=str on RawConfigParser to preserve DriverDesc key casing; strings dict still uses lowercased keys for case-insensitive %TOKEN% lookup"
+  - "configparser.RawConfigParser(strict=False) avoids DuplicateOptionError on real INFs with repeated model entries"
+  - "UTF-16 fixture written as binary via Python encode('utf-16') — not as a text file — to guarantee correct BOM bytes"
+metrics:
+  duration: "~2.5 min"
+  completed: "2026-04-10"
+  tasks: 1
+  files: 6
+---
+
+# Phase 02 Plan 01: INF Parser Service Summary
+
+**One-liner:** stdlib configparser + BOM-sniffing INF parser with %TOKEN% resolution, multi-model deduplication, architecture detection, and unused-file flagging.
+
+## What Was Built
+
+`imptune/services/inf_parser.py` — a pure-function INF parser with:
+
+- `ParsedInf` dataclass exposing `driver_names`, `inf_filename`, `architecture`, `has_cat_file`, `unused_files`
+- `_detect_encoding(raw: bytes) -> str` — BOM-sniffing: `\xff\xfe`/`\xfe\xff` -> `utf-16`, `\xef\xbb\xbf` -> `utf-8-sig`, else `cp1252`
+- `_resolve_tokens(value, strings)` — regex `%([^%]+)%` expansion
+- `parse_inf(inf_text, inf_filename, zip_names) -> ParsedInf` — `RawConfigParser(strict=False, delimiters=('=',))` with `optionxform=str`; [Manufacturer] -> Models section discovery; NTamd64/NTarm64/NTx86/undecorated detection; set-based dedup; sorted output
+
+Three fixture files support the test suite: `sample.inf` (ANSI with %TOKEN%), `sample_utf16.inf` (UTF-16 LE BOM binary), `sample_multi_model.inf` (NTamd64 + undecorated sections).
+
+## Tasks
+
+| # | Task | Status | Commit |
+|---|------|--------|--------|
+| 1 | INF parser with TDD (RED then GREEN) | Complete | 290106d (RED), 5056922 (GREEN) |
+
+## Test Results
+
+- 16 tests in `tests/test_inf_parser.py` — all pass
+- Full suite: 40 tests pass, 0 failures, 0 regressions
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] configparser key lowercasing mangled DriverDesc literal names**
+- **Found during:** Task 1, GREEN phase (first test run)
+- **Issue:** configparser defaults `optionxform = str.lower`, so the literal key `Acme SuperPrint 9000` was returned as `acme superprint 9000`. The test `assert "Acme SuperPrint 9000" in result.driver_names` failed.
+- **Fix:** Set `parser.optionxform = str` to preserve original casing of option keys. The [Strings] dict still explicitly lowercases keys (`strings[key.lower()]`) for case-insensitive token resolution.
+- **Files modified:** `imptune/services/inf_parser.py`
+- **Commit:** 5056922
+
+**Note:** The plan specified `strict=False` and `RawConfigParser` correctly but did not mention `optionxform=str`. This is a real-INF edge case documented in the pitfalls section of 02-RESEARCH.md (implicitly — the note says "Strings dict keys must be lowercased" without clarifying that DriverDesc keys also get lowercased by default).
+
+### Test Count Deviation
+
+The plan specified 11 test functions; 16 were written. The extra 5 cover:
+- `test_detect_encoding_utf16be` (UTF-16 BE BOM variant)
+- `test_architecture_detection_amd64` (split from the combined architecture test)
+- `test_architecture_detection_arm64`
+- `test_architecture_detection_undecorated`
+- `test_architecture_detection_mixed`
+
+This provides more granular failure diagnosis and meets the `min_lines: 80` artifact requirement.
+
+## Self-Check
+
+- [x] `imptune/services/inf_parser.py` exists
+- [x] `imptune/services/__init__.py` exists
+- [x] `tests/test_inf_parser.py` exists (>80 lines)
+- [x] `tests/fixtures/sample.inf` exists
+- [x] `tests/fixtures/sample_utf16.inf` exists (UTF-16 LE BOM binary)
+- [x] `tests/fixtures/sample_multi_model.inf` exists
+- [x] RED commit: 290106d
+- [x] GREEN commit: 5056922
+
+## Self-Check: PASSED