# Research & Design Decisions — i18n-ci-guard

## Summary
- **Feature**: `i18n-ci-guard`
- **Discovery Scope**: Simple Addition (one Python script + one GH Actions
  workflow + one baseline file). Extension-flavoured because it builds on
  established `scripts/` conventions and the canonical CJK regex used by
  the larger audit pipeline.
- **Key Findings**:
  - The canonical CJK match command `git grep -nIP '[\x{4e00}-\x{9fff}]'
    -- <path>` is already used by the unmerged audit pipeline (PR #27)
    and is portable on every git ≥2.4 (`ubuntu-latest` ships ≥2.40).
  - `scripts/check_i18n_logs.py` is a strong CLI/style precedent:
    Python-stdlib-only, exit `0`/`1`, output as `<file>:<line>:
    <reason>: <snippet>`, canonical regex `[一-鿿]`.
  - The repository has no existing `pull_request`-triggered GH Actions
    workflow; this guard introduces the first one. The only existing
    workflow (`.github/workflows/docker-image.yml`) runs on tag pushes
    only.
  - Current per-path counts on this branch:
    `backend/app=2707, frontend/src=902, locales/en.json=0`. These are
    sample counts; the committed baseline must be regenerated against
    `main` at implementation time.

## Research Log

### Canonical scan command
- **Context**: Requirement 2 needs a stable per-path CJK count and
  Requirement 5.5 forbids third-party packages.
- **Sources Consulted**:
  - `audit_cjk.sh` from PR #27 commit `3481408`.
  - `git grep` man page.
- **Findings**:
  - `git grep -nIP '[\x{4e00}-\x{9fff}]' -- <path>` returns one match
    per matching line in tracked, text-only files. `-I` excludes binary
    files; `-P` enables PCRE2 so the `\x{...}` Unicode range works.
  - This matches the input format consumed by the existing audit
    classifier, so the guard's match counts are directly comparable
    across pipelines.
- **Implications**:
  - The guard re-uses this exact command; no new dependencies.
  - Because `-I` skips binary files and tracked-only is the default,
    Requirements 2.5 and 2.6 are satisfied by the command itself
    rather than by additional script logic.

### Baseline file format
- **Context**: Requirement 4 needs a diff-friendly committed baseline.
- **Sources Consulted**:
  - Diff churn behaviour of JSON vs. line-oriented text in this repo's
    history (e.g. `locales/*.json` PR diffs frequently re-key, while
    plain-text `parity.txt` from PR #27 reads cleanly).
- **Findings**:
  - Line-oriented `<path>\t<count>` files produce minimal diffs and
    require no JSON parser.
  - A two-line file (one per scoped path) is large enough to be
    self-explanatory and small enough to never line-shuffle.
- **Implications**:
  - Use plain text, sorted by path, single trailing newline. Reject
    the file as malformed if the script cannot parse it (Req 4.5).

### Locale-catalogue scan path
- **Context**: Requirement 1 wants `key:line` per CJK offender in
  `locales/en.json`.
- **Sources Consulted**:
  - `scripts/check_i18n_logs.py` (`flatten_keys` reuse pattern).
  - `check_parity.py` from PR #27 (`flatten`, `[cjk-in-en]` block).
- **Findings**:
  - Both precedents flatten the locale dict and run the canonical
    regex against each leaf string value. Line numbers are derivable
    by re-reading the file as text and matching the value's first
    occurrence (good enough for an actionable error message).
  - Empty-string values and non-string leaf values (booleans, null)
    are skipped.
- **Implications**:
  - Implement a tiny flatten-then-scan helper inside the guard
    script; do not add a new shared utility module.

### GH Actions trigger and budget
- **Context**: Requirements 5.1, 5.5, 5.6.
- **Sources Consulted**:
  - GitHub-hosted runners reference (`ubuntu-latest`).
  - `actions/setup-python@v5` README.
- **Findings**:
  - `ubuntu-latest` has Python 3.10+ pre-installed; `actions/setup-python@v5`
    pins to 3.11 in <5 s.
  - A single `git grep` over the scoped paths runs in <2 s on this
    repo (~3.6k matches). End-to-end the workflow comfortably fits
    inside the 60 s ceiling.
- **Implications**:
  - Use `actions/checkout@v4` with `fetch-depth: 1`,
    `actions/setup-python@v5` with `python-version: '3.11'`, and run
    the script directly. No caching layer needed.

## Architecture Pattern Evaluation

| Option | Description | Strengths | Risks / Limitations | Notes |
|--------|-------------|-----------|---------------------|-------|
| A. Extend `check_i18n_logs.py` | Add `--cjk-guard` mode to existing script | Reuses one file | Conflates two scopes; existing script is module-scoped, guard is subtree-scoped | Rejected |
| B. New `scripts/ci/i18n_cjk_guard.py` + new workflow | Single-purpose script + workflow + baseline file | Clean SRP; matches "one script per responsibility" precedent | One additional file | **Selected** |
| C. Shared `cjk_scan.py` helper + thin guard | Factor regex/git-grep into helper | DRY for regex constant | Premature abstraction; only one shared symbol today | Rejected |

## Design Decisions

### Decision: Single-purpose CI script + GH Actions workflow (Option B)
- **Context**: Requirements 1–6 demand a small, self-contained guard.
- **Alternatives Considered**: A (extend), C (shared helper).
- **Selected Approach**: New script `scripts/ci/i18n_cjk_guard.py`,
  new workflow `.github/workflows/i18n-cjk-guard.yml`, baseline file
  `.kiro/specs/i18n-ci-guard/baseline.txt`.
- **Rationale**: Matches the project's "one focused script per
  responsibility" convention; isolates a CI-blocking surface from the
  existing i18n developer scripts; keeps the baseline collocated with
  the spec for review traceability.
- **Trade-offs**: One more file in `scripts/` vs. tighter cohesion.
- **Follow-up**: When a third caller wants the canonical regex, factor
  it out then.

### Decision: Plain-text baseline format
- **Context**: Requirement 4.2 demands stable, diff-friendly format.
- **Alternatives Considered**: JSON, YAML.
- **Selected Approach**: One line per scoped path: `<path>\t<count>`,
  sorted lexicographically by path, single trailing newline.
- **Rationale**: Zero parser dependency; predictable diffs; trivial
  to refresh atomically.
- **Trade-offs**: Less expressive than JSON (no nested structure), but
  the data model is two integers — nesting is unnecessary.

### Decision: Refresh via `--update-baseline` subcommand-style flag
- **Context**: Requirement 4.3 needs an explicit refresh path.
- **Alternatives Considered**: Separate `update_baseline.py` script;
  Makefile target.
- **Selected Approach**: Single script with two modes: default (check
  + exit 0/1) and `--update-baseline` (overwrite baseline + exit 0).
- **Rationale**: One CLI surface to remember; the failure message
  prints the exact command to run.
- **Trade-offs**: Slightly more conditional logic in one script;
  acceptable given the small total LoC.

### Decision: Workflow runs only on `pull_request` to `main`
- **Context**: Requirement 5.1.
- **Alternatives Considered**: Run on `push` to all branches as well;
  run on `pull_request` to any base branch.
- **Selected Approach**: `on.pull_request.branches: [main]` only.
- **Rationale**: Aligns with how the existing project uses `main` as
  the protected branch (see `gh pr list` history; every feature PR
  targets `main`). Avoids redundant runs on intra-branch chains.
- **Trade-offs**: A direct push to `main` would not be guarded — but
  branch protection already discourages that path (per
  `dev-guidelines.md`).

## Risks & Mitigations

- **Risk**: Baseline drifts upward unintentionally during
  `--update-baseline` runs, hiding real regressions.
  - *Mitigation*: Failure message instructs contributors to refresh
    *only when intentional*; the baseline file is reviewed in the same
    PR diff. Acceptance Criteria 3.3 makes this explicit.
- **Risk**: `git grep -P` not built with PCRE on a developer's local
  git build (rare on Linux/macOS, possible on minimal Windows builds).
  - *Mitigation*: The guard prints a clear error if `git grep` exits
    non-zero with PCRE mode; documents Python ≥3.11 + git ≥2.20 as
    prerequisites.
- **Risk**: Baseline counts captured on a feature branch include
  changes not yet on `main`, mis-anchoring the ratchet.
  - *Mitigation*: The implementation task explicitly recomputes
    baseline against `origin/main` before committing; documented in
    `tasks.md`.

## References
- PR #27 audit pipeline (`audit_cjk.sh`, `check_parity.py`,
  `classify.py`) — methodology source of truth.
- `scripts/check_i18n_logs.py` — CLI/style precedent.
- `git grep` man page — `-n`, `-I`, `-P` flag semantics.
- GitHub Actions `actions/setup-python@v5` and `actions/checkout@v4`
  README pages.