From d4bd75f4ba8f3051caca019e2114a538da6ad5ea Mon Sep 17 00:00:00 2001
From: Doxa Maps <maps@doxa.example>
Date: Sun, 27 Sep 2026 04:40:03 +0000
Subject: [PATCH] Library index: a data file is described by its own
 _description or _meta, not its first line

generate-library-index took the first line of every file as its description, which for a .json file is data:
the Data section read '"_meta": {', '"value": "AFG",' and a run of ISO codes (flagged by simpleresearch).
A .json file now uses _description, then _meta.description, then _meta.purpose, and otherwise says
'(no description)'. iso3-to-alpha2 now reads as what it is.
---
 documentation/reference-library-index.md | 12 ++++++------
 internal/generate-library-index.mjs      | 11 +++++++++++
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/documentation/reference-library-index.md b/documentation/reference-library-index.md
index 51067daee..5412d2214 100644
--- a/documentation/reference-library-index.md
+++ b/documentation/reference-library-index.md
@@ -245,17 +245,17 @@ and a change here can break other maps.
 
 ### Data (static reference tables)
 
-- **countries** — "value": "AFG",  
+- **countries** — (no description)  
   `import … from '@map/data/countries.json'`
-- **country-posters** — "stats": {  
+- **country-posters** — (no description)  
   `import … from '@map/data/country-posters.json'`
-- **iso-numeric-to-alpha2** — "4":"AF","8":"AL","12":"DZ","24":"AO","32":"AR","36":"AU","40":"AT","50":"BD",  
+- **iso-numeric-to-alpha2** — (no description)  
   `import … from '@map/data/iso-numeric-to-alpha2.json'`
-- **iso3-to-alpha2** — "_meta": {  
+- **iso3-to-alpha2** — alpha-3 -> alpha-2 so Intl.DisplayNames can produce a LOCALIZED country name. Drives no data fetch.  
   `import … from '@map/data/iso3-to-alpha2.json'`
-- **langFamilyByIso** — "aar": "Afro-Asiatic",  
+- **langFamilyByIso** — (no description)  
   `import … from '@map/data/langFamilyByIso.json'`
-- **langFamilyByLanguage** — {"Chamacoco":"Zamucoan","Ninam":"Yanomaman","Yagua":"Yaguan","Muinane":"Witotoan","Finnish":"Uralic","Hill Mar  
+- **langFamilyByLanguage** — (no description)  
   `import … from '@map/data/langFamilyByLanguage.json'`
 
 ### API / data sources (`@map/api`)
diff --git a/internal/generate-library-index.mjs b/internal/generate-library-index.mjs
index 7921e0ab1..d144c1c83 100644
--- a/internal/generate-library-index.mjs
+++ b/internal/generate-library-index.mjs
@@ -23,6 +23,17 @@ const LIB = join(ROOT, 'library');
 function firstDocLine(file) {
   let text;
   try { text = readFileSync(file, 'utf8'); } catch { return ''; }
+  // A .json file has no header comment: its first line is data ('"_meta": {', '"value": "AFG",'), so read
+  // the description a data file carries about itself, and otherwise say nothing rather than print a line of JSON.
+  if (file.endsWith('.json')) {
+    try {
+      const j = JSON.parse(text);
+      const m = j && typeof j === 'object' && !Array.isArray(j) ? j : {};
+      const meta = m._meta && typeof m._meta === 'object' ? m._meta : {};
+      const d = m._description || meta.description || meta.purpose || '';
+      return typeof d === 'string' ? d.replace(/`/g, '').replace(/\s+/g, ' ').trim().slice(0, 110) : '';
+    } catch { return ''; }
+  }
   const lines = text.split('\n').slice(0, 16);
   for (let raw of lines) {
     let l = raw.trim();