fix(get-municipality-by-cep): refresh the CEP ranges with the other datasets

CONTRIBUTING.md says the municipality CEP ranges are generated "the same way"
as the other datasets, but scripts/data.ts never ran municipality-cep-ranges.ts,
so the Update datasets workflow never refreshed, linted or formatted its output,
and the data-summary entry for it could never be reached. It now runs after the
other generators, since it is joined against the municipality table cities.ts
rewrites, and its output is in the list the run lints and formats.

The generator also stops reimplementing normalizeMunicipalityName: it loads the
helper through the same extensionless import hook it already registers for the
dataset, so the table is built with exactly the normalization it is read with.

The OTHER_NAMES JSDoc said the variants were recent official renames, citing the
IBGE; most are hyphen and accent spellings of the Correios CEP range mirror, which
is now what it says and cites. The getting-started tables said 5574 ranges; the
table holds 5573.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RLkm9YrtAifc6XCLFVEsdH

Author: claude

CONTRIBUTING.md

@@ -94,8 +94,8 @@ release-please turns merged commits into releases.
 
 ## Datasets
 
-The tables under `src/_internals/constants/` fall in two groups, and only the first refreshes
-itself:
+The tables under `src/_internals/constants/` fall in three groups, and only the first two refresh
+themselves:
 
 - **Generated from an official source** by a script in `scripts/` (`npm run build:data`, run
   every Monday by the `Update datasets` workflow): banks (Banco Central, `banks.ts`), CBO
@@ -104,7 +104,7 @@ itself:
   `ncm.ts`). When a run changes a file, the workflow opens a pull request whose description, written
   by `scripts/data-summary.ts`, lists per table how many entries were added and removed, with a
   sample of each. Never edit these files by hand.
-- **Generated from a fetchable mirror of an official source**, the same way, but pinned to a
+- **Generated from a fetchable mirror of an official source**, by the same `npm run build:data` run (after the municipalities, which it is joined against), but pinned to a
   specific revision of the mirror because the official source itself cannot be fetched by a
   script: the CEP range of each municipality (Correios "Busca Faixa de CEP", via a community CSV
   mirror of its answers, `municipality-cep-ranges.ts`, writing `src/get-municipality-by-cep/constants.ts`).

docs/getting-started.md

@@ -70,7 +70,7 @@ A few utils embed an official dataset and weigh far more than everything else co
 | --- | --- | --- | --- |
 | `getMunicipalities` · `getMunicipalityByCode` · `getMunicipality` | 5571 IBGE municipalities, with names and codes | 154.9 - 156.5 KB | 50.3 - 50.4 KB |
 | `getCities` | 5571 IBGE municipality names | 154.3 KB | 49.9 KB |
-| `getMunicipalityByCep` | The IBGE municipality table above, plus 5574 Correios CEP ranges | 393.3 KB | 98.8 KB |
+| `getMunicipalityByCep` | The IBGE municipality table above, plus 5573 Correios CEP ranges | 393.3 KB | 98.8 KB |
 | `isValidNcm` | NCM (Nomenclatura Comum do Mercosul) codes | 114.2 KB | 24.6 KB |
 | `isValidCbo` · `getCbo` | CBO 2002 occupation titles | 119.1 KB | 30.6 KB |
 | `isValidCnae` · `getCnae` | CNAE-Subclasses 2.3 | 93.9 KB | 21.2 KB |

docs/pt-br/getting-started.md

@@ -70,7 +70,7 @@ Alguns utilitários embutem uma base de dados oficial e pesam muito mais que tod
 | --- | --- | --- | --- |
 | `getMunicipalities` · `getMunicipalityByCode` · `getMunicipality` | 5571 municípios do IBGE, com nomes e códigos | 154,9 - 156,5 KB | 50,3 - 50,4 KB |
 | `getCities` | nomes dos 5571 municípios do IBGE | 154,3 KB | 49,9 KB |
-| `getMunicipalityByCep` | a tabela de municípios do IBGE acima, mais 5574 faixas de CEP dos Correios | 393,3 KB | 98,8 KB |
+| `getMunicipalityByCep` | a tabela de municípios do IBGE acima, mais 5573 faixas de CEP dos Correios | 393,3 KB | 98,8 KB |
 | `isValidNcm` | códigos NCM (Nomenclatura Comum do Mercosul) | 114,2 KB | 24,6 KB |
 | `isValidCbo` · `getCbo` | títulos das ocupações da CBO 2002 | 119,1 KB | 30,6 KB |
 | `isValidCnae` · `getCnae` | CNAE-Subclasses 2.3 | 93,9 KB | 21,2 KB |

scripts/cities.ts

@@ -57,9 +57,8 @@ const isCity = (value: unknown): value is City =>
 	"regiao-imediata" in value;
 
 /**
- * Alternative spellings kept for a handful of municipalities whose name changed at the IBGE
- * more recently than a third party dataset this library cross-checks against, keyed by the
- * 7-digit IBGE code. Curated by hand from the mismatches found joining
+ * Alternative spellings the Correios CEP range mirror uses for a handful of municipalities,
+ * mostly hyphen and accent variants and a couple of older names, keyed by the 7-digit IBGE code. Curated by hand from the mismatches found joining
  * https://gist.githubusercontent.com/hugosenari/ec1a7d88f5bdd01844424dbc9aff9590/raw/9aeb90ef777131ffaf1a6f5381d1f163c9c79b09/ceps.csv
  * against the IBGE municipalities below (see `scripts/municipality-cep-ranges.ts`); `main`
  * below fails the build if a code here stops matching a real municipality, so a future IBGE
@@ -180,12 +179,12 @@ ${body}
 };
 
 /**
- * Alternative spellings of a municipality name, keyed by its 7-digit IBGE code, for the
- * municipalities a source outside the IBGE still spells differently, usually because of a
- * recent official rename. A municipality with no variant is simply absent, at no extra cost.
- * Curated by \`scripts/cities.ts\`.
+ * Alternative spellings of a municipality name, keyed by its 7-digit IBGE code: the spellings
+ * the Correios CEP range mirror uses where it differs from the IBGE, mostly hyphen and accent
+ * variants (Biritiba Mirim, Grão-Pará) and a couple of older names. A municipality with no
+ * variant is simply absent, at no extra cost. Curated by \`scripts/cities.ts\`.
  *
- * @see Official: https://servicodados.ibge.gov.br/api/docs/localidades
+ * @see Based on: https://gist.github.com/hugosenari/ec1a7d88f5bdd01844424dbc9aff9590
  */
 export const OTHER_NAMES: Readonly<Record<string, readonly string[]>> = {
 ${otherNamesBody}

scripts/data.ts

@@ -37,6 +37,7 @@ const generatedFiles = [
 	"./src/_internals/constants/cnae.ts",
 	"./src/_internals/constants/municipalities.ts",
 	"./src/_internals/constants/states.ts",
+	"./src/get-municipality-by-cep/constants.ts",
 	"./src/is-valid-legal-nature/constants.ts",
 	"./src/is-valid-ncm/constants.ts",
 ];
@@ -45,6 +46,10 @@ const results = await Promise.all(
 	generators.map((generator) => run("node", [resolve(scriptsDir, generator)])),
 );
 
+// The CEP ranges are joined against the municipality table cities.ts has just rewritten, so
+// they are generated after it rather than alongside it.
+results.push(await run("node", [resolve(scriptsDir, "municipality-cep-ranges.ts")]));
+
 // Lint and format before checking the generators, so a failing generator never leaves
 // unformatted files behind in the working tree. `vp fmt` runs last because `vp lint --fix`
 // rewrites code without reformatting it.

scripts/municipality-cep-ranges.ts

@@ -5,7 +5,6 @@ import { register } from "node:module";
 import { resolve } from "node:path";
 
 import { fetchWithRetry } from "../src/_internals/fetch-with-retry/fetch-with-retry.ts";
-import { removeAccents } from "../src/remove-accents/remove-accents.ts";
 
 const scriptsDir = import.meta.dirname;
 
@@ -37,15 +36,10 @@ const { DATA, OTHER_NAMES } = await import("../src/_internals/constants/municipa
 
 type StateCode = keyof typeof DATA;
 
-const WHITESPACE_RUN_REGEX = /\s+/g;
-
-// Same composition as `normalizeMunicipalityName`, reimplemented from the `removeAccents`
-// primitive it is itself built from: that helper's own import of `removeAccents` omits the
-// file extension (the convention every `src/` module follows, resolved by the bundler), which
-// a plain `node` process run from `scripts/` cannot resolve, unlike every other `scripts/`
-// import, which always carries its extension.
-const normalizeMunicipalityName = (value: string): string =>
-	removeAccents(value).replaceAll(WHITESPACE_RUN_REGEX, " ").trim().toUpperCase();
+// The same helper getMunicipalityByCep matches names with, loaded through the hook above like
+// the dataset, so the table is built with exactly the normalization it is read with.
+const { normalizeMunicipalityName } =
+	await import("../src/_internals/normalize-municipality-name/normalize-municipality-name.ts");
 
 // Pinned to a specific commit of the gist, so a re-run always reads the exact CSV this table
 // was cross-checked against; bumping it is a deliberate, reviewed change.

src/_internals/constants/municipalities.ts

@@ -5643,12 +5643,12 @@ export const DATA: Record<StateCode, readonly (readonly [string, string])[]> = {
 };
 
 /**
- * Alternative spellings of a municipality name, keyed by its 7-digit IBGE code, for the
- * municipalities a source outside the IBGE still spells differently, usually because of a
- * recent official rename. A municipality with no variant is simply absent, at no extra cost.
- * Curated by `scripts/cities.ts`.
+ * Alternative spellings of a municipality name, keyed by its 7-digit IBGE code: the spellings
+ * the Correios CEP range mirror uses where it differs from the IBGE, mostly hyphen and accent
+ * variants (Biritiba Mirim, Grão-Pará) and a couple of older names. A municipality with no
+ * variant is simply absent, at no extra cost. Curated by `scripts/cities.ts`.
  *
- * @see Official: https://servicodados.ibge.gov.br/api/docs/localidades
+ * @see Based on: https://gist.github.com/hugosenari/ec1a7d88f5bdd01844424dbc9aff9590
  */
 export const OTHER_NAMES: Readonly<Record<string, readonly string[]>> = {
 	"1400605": ["São Luiz"],