docs: record task 1 line ending verification

2026-08-04 14:34:42 +02:00
parent ad07a75490
commit be0e49fbc7
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Task 1 — Deterministic line endings
+
+## Status
+
+Complete. The repository now declares the cross-platform line-ending policy, verifies it
+against tracked files (or an explicit test fixture), and performs the Docker-script check before
+their executable permissions are set in the core image.
+
+## Changed files
+
+- `.gitattributes` — required LF/CRLF Git normalization contract.
+- `.editorconfig` — editor-side UTF-8, final-newline, LF default and PowerShell CRLF policy.
+- `scripts/verify-line-endings.sh` — tracked-file/fixture CRLF verifier.
+- `scripts/test-verify-line-endings.sh` — LF and CRLF fixture regression test.
+- `docker/core.Dockerfile` — image build invokes the verifier on `/app/docker` before `chmod`.
+
+## Red / green evidence
+
+### RED
+
+`bash scripts/test-verify-line-endings.sh` exited 1 before the verifier existed. Its final
+assertion output was `missing CRLF path: bad.sh`; the test had captured the underlying attempt to
+run the absent verifier, so no CRLF paths could be reported. This confirmed the test was exercising
+the missing implementation rather than passing spuriously.
+
+### GREEN
+
+After implementing the verifier and setting its executable mode:
+
+```text
+$ bash scripts/test-verify-line-endings.sh
+line-ending verifier tests passed
+```
+
+The test confirms that `bad.sh`, `compose.yaml`, and `Dockerfile` are all reported for CRLF, that
+the LF-only `ok.sh` is absent from the report, and that converting every fixture file to LF returns
+0.
+
+## Commands and output summary
+
+| Command | Result |
+| --- | --- |
+| `bash scripts/test-verify-line-endings.sh` (before implementation) | Exit 1 (expected RED). |
+| `chmod +x scripts/verify-line-endings.sh scripts/test-verify-line-endings.sh` | Set executable modes for both shell interfaces. |
+| `bash scripts/test-verify-line-endings.sh` | Passed: `line-ending verifier tests passed`. |
+| `bash scripts/verify-line-endings.sh` | Passed (exit 0) against tracked repository files. |
+| `bash -n scripts/verify-line-endings.sh scripts/test-verify-line-endings.sh` | Passed. |
+| `git add --renormalize .` | Completed; no existing tracked files required line-ending-only normalization. |
+| `git check-attr text eol -- ...` | Confirmed LF attributes for `.sh`, Dockerfile, YAML, TypeScript, Python, and JSON examples. |
+| `git diff --check` and `git diff --cached --check` | Passed. |
+
+## Renormalization review
+
+After `git add --renormalize .`, the staged diff contained only the intentional
+`docker/core.Dockerfile` change (3 insertions, 1 deletion). There were no unrelated or
+line-ending-only changes to review. New, untracked Task 1 files were then added explicitly.
+
+## Self-review
+
+- Default mode uses `git ls-files`, so it inspects only tracked repository content and avoids
+  untracked secrets and mounted volumes.
+- Explicit-root mode is reserved for the isolated test fixture and uses `find`, as required.
+- Detection uses `LC_ALL=C grep -Il $'\r'`; violations are printed as paths relative to the
+  selected root and return exit 1.
+- The Dockerfile runs the verifier immediately after copying Docker scripts and before `chmod`.
+- The exact `.gitattributes` contract from the task brief is present verbatim.
+
+## Commit
+
+Task implementation: `ad07a75` (`build: enforce portable line endings`)
+
+## Concerns
+
+None. The prescribed verifier and repository-integrity checks pass. A full Docker image build was
+not run because this task's required validation is the shell verifier suite; the Dockerfile change
+is structurally covered by the reviewed build instruction ordering.