feat: add Comuna enum with the 346 comunas of Chile

[gdespirito]

Summary

Adds a Comuna enum with the 346 comunas of Chile, following the same design as the Region enum from #23.

• Int-backed by the official CUT code (Código Único Territorial). Since the first digits of the CUT are the region number, region() is derived arithmetically — no duplicated data.
• officialName() — official spelling with accents.
• code() — zero-padded five-digit format used in official documents ('01101').
• fromName('ñuñoa') — case- and accent-insensitive lookup.
• inRegion(Region $r) / Region::comunas() — comunas of a region.
• options(?Region $r) — [code => name] arrays ready for HTML selects.

Data provenance

The enum was generated from the official SUBDERE spreadsheet (CUT_2018_v04.xls, the latest published CUT), not hand-typed. The community dataset initially considered (bdcut-cl) was discarded after cross-validation revealed it still had the Ñuble comunas under their pre-2018 codes (08xxx instead of 16xxx).

Two known typos in the SUBDERE file (missing accents in "Los Angeles" and "Los Alamos") were corrected to their official spellings.

Test plan

• 105 tests / 952 assertions passing (9 new tests, including a full sweep asserting every comuna maps to a valid region and has a non-empty name)
• PHPStan level 8 clean
• Pint clean

🤖 Generated with Claude Code

https://claude.ai/code/session_01WvDYWr2Tx3diCV3NXGrKRX

Summary by CodeRabbit

• New Features
  • Added support for all 346 Chilean comunas with official CUT codes and names.
  • Resolve comunas by name (accent- and case-insensitive), retrieve their region, and get the zero-padded 5-digit CUT code.
  • Filter comunas by region and generate selectable options (global or per region).
  • Added access to a region’s associated comunas.
• Documentation
  • Documented the new “Comunas” feature and provided example usage.
• Tests
  • Added comprehensive unit tests covering mappings, lookups, formatting, and option generation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 497877de-f326-41ff-b3de-94e5dd641d60

📥 Commits

Reviewing files that changed from the base of the PR and between 6584241 and 6a61ca2.

📒 Files selected for processing (1)

• src/Comuna.php

🚧 Files skipped from review as they are similar to previous changes (1)

• src/Comuna.php

---

📝 Walkthrough

Walkthrough

Adds a Comuna backed enum containing Chile’s 346 official CUT comuna codes and names, with lookup, region filtering, and option-generation APIs. Region can list its comunas, with accompanying tests and README documentation.

Changes

Comuna support

Layer / File(s)	Summary
Comuna enum and lookup API src/Comuna.php	Defines all comuna codes and official names, plus code formatting, region derivation, name lookup, filtering, options, and normalization methods.
Region comuna access src/Region.php	Adds Region::comunas() delegating to Comuna::inRegion().
Documentation and validation tests/Unit/ComunaTest.php, README.md	Tests the complete comuna API and documents its usage and CUT-backed behavior.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: adding the Comuna enum for Chile's 346 comunas.
Docstring Coverage	✅ Passed	Docstring coverage is 88.89% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch comunas

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/Comuna.php (1)

793-807: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Docblock key description could be clearer.

"[code => official name]" is ambiguous next to the code() method, which returns a zero-padded string ('01101'), whereas this array is keyed by the raw int value (1101). Worth wording it as "[value => official name]" to avoid confusion, since PHP would coerce a numeric-string code key back to int anyway.

📝 Suggested docblock tweak

     /**
-     * Comunas as an array suitable for HTML selects: [code => official name].
+     * Comunas as an array suitable for HTML selects: [value => official name].
      * Optionally filtered by region.
      *
      * `@return` array<int, string>
      */

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/Comuna.php` around lines 793 - 807, Clarify the `options()` docblock by
changing the return description from “[code => official name]” to “[value =>
official name]”, accurately reflecting that keys use the raw integer `value`
rather than the zero-padded string returned by `code()`.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/Comuna.php`:
- Around line 793-807: Clarify the `options()` docblock by changing the return
description from “[code => official name]” to “[value => official name]”,
accurately reflecting that keys use the raw integer `value` rather than the
zero-padded string returned by `code()`.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: aa85e30b-fa0d-4968-b242-a3e4450c4930

📥 Commits

Reviewing files that changed from the base of the PR and between 46f8f7d and 6584241.

📒 Files selected for processing (4)

• README.md
• src/Comuna.php
• src/Region.php
• tests/Unit/ComunaTest.php