Extract Plus Code logic into testable module with full test coverage

Moves `resolvePlusCode` and `isValidPlusCode` from `process-new-event-issue.mjs`
into a standalone `plus-code.mjs` module, and adds `plus-code.test.mjs` with 22
tests covering validation, short-code recovery, ambiguous input rejection, and
failure cases. Updates AGENTS.md with testing protocol and adds TEST.md inventory.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SableRaf

.github/scripts/plus-code.mjs

@@ -0,0 +1,112 @@
+import { createRequire } from 'node:module';
+
+// OLC library path: CI installs to /tmp/script-deps, locally it's in pcd-website/node_modules
+const _require = createRequire(import.meta.url);
+export let olc = null;
+for (const candidate of [
+  '/tmp/script-deps/node_modules/open-location-code/openlocationcode.js',
+  new URL('../../pcd-website/node_modules/open-location-code/openlocationcode.js', import.meta.url).pathname,
+]) {
+  try {
+    const { OpenLocationCode } = _require(candidate);
+    olc = new OpenLocationCode();
+    break;
+  } catch { /* try next */ }
+}
+
+// OLC character set used in both validation and extraction regexes.
+const OLC = '[23456789CFGHJMPQRVWX]';
+const VALID_FULL_RE = new RegExp(`^${OLC}{8}\\+${OLC}{2,3}$`);
+
+export function isValidPlusCode(value) {
+  return VALID_FULL_RE.test(value.replace(/\s+/g, '').toUpperCase());
+}
+
+// Match the full run of OLC chars after '+' as one block, then accept only if
+// the run is exactly 2–3 chars long. This prevents V9H4+MCPARIS from being
+// misread as V9H4+MCP: the full run "MCP…" is longer than 3, so no match.
+const EXTRACT_RE = new RegExp(
+  `(${OLC}{2,8}\\+)(${OLC}+)`,
+  'i',
+);
+
+export async function resolvePlusCode(rawValue, city, country) {
+  const normalized = rawValue.replace(/\s+/g, '').toUpperCase();
+
+  if (!normalized) return { code: null, note: null };
+
+  // Fast path: already a valid full global OLC
+  if (VALID_FULL_RE.test(normalized)) return { code: normalized, note: null };
+
+  if (!olc) return { code: null, note: null };
+
+  // Try to extract a Plus Code from anywhere in the input (e.g. "My code: QX5Q+C5,DENVER").
+  // No leading anchor so we match even with arbitrary prefix text.
+  // Captures the full run of OLC chars after '+'; the suffix length check below
+  // rejects cases where city chars bleed into the suffix (see suffix.length > 3).
+  const match = normalized.match(EXTRACT_RE);
+
+  let shortCode = normalized;
+  let locationHint = '';
+
+  if (match) {
+    const [fullMatch, prefix, suffix] = match;
+
+    // Suffix must be exactly 2–3 OLC chars. A longer run means the city name bled
+    // into the code (e.g. "V9H4+MCPARIS" → suffix "MCPARIS", length 7).
+    if (suffix.length > 3) {
+      console.log(`[plus-code] rejected "${rawValue}": suffix "${suffix}" is longer than 3 chars`);
+      return { code: null, note: null };
+    }
+
+    // Reject if the matched code is immediately followed by a word character.
+    // Non-OLC chars in the city name can truncate the suffix early, e.g. V9H4+MCPARIS
+    // matches as V9H4+MCP (stops at 'A') but 'ARIS' follows — the code is embedded
+    // in a longer token and must be rejected.
+    const afterCode = normalized.slice(match.index + fullMatch.length);
+    if (/^\w/.test(afterCode)) {
+      console.log(`[plus-code] rejected "${rawValue}": extracted "${fullMatch}" is followed by word chars "${afterCode}"`);
+      return { code: null, note: null };
+    }
+
+    shortCode = prefix + suffix;
+
+    // Extract any trailing non-OLC text as a location hint (e.g. ",DENVER,COLORADO").
+    // Used only when the city/country form fields are empty.
+    if (afterCode) {
+      locationHint = afterCode
+        .replace(/,/g, ' ')
+        .trim()
+        .toLowerCase()
+        .replace(/\b\w/g, (c) => c.toUpperCase());
+    }
+  }
+
+  // Attempt recovery if we have a short OLC and a location reference.
+  // Prefer explicit city/country fields; fall back to the hint extracted from the input.
+  const locationRef = (city || country)
+    ? [city, country].filter(Boolean).join(' ')
+    : locationHint;
+
+  if (olc.isShort(shortCode) && locationRef) {
+    try {
+      const query = encodeURIComponent(locationRef);
+      const response = await fetch(
+        `https://nominatim.openstreetmap.org/search?q=${query}&format=json&limit=1`,
+        { headers: { 'User-Agent': 'PCD-Event-Intake/1.0' } },
+      );
+      const results = await response.json();
+      if (results.length > 0) {
+        const { lat, lon } = results[0];
+        const recovered = olc.recoverNearest(shortCode, parseFloat(lat), parseFloat(lon));
+        if (VALID_FULL_RE.test(recovered)) {
+          return { code: recovered, note: 'auto-recovered from short code + city' };
+        }
+      }
+    } catch (err) {
+      console.log(`[plus-code] recovery failed: ${err.message}`);
+    }
+  }
+
+  return { code: null, note: null };
+}

.github/scripts/plus-code.test.mjs

@@ -0,0 +1,175 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { isValidPlusCode, resolvePlusCode, olc } from './plus-code.mjs';
+
+// Paris reference: 145 rue La Fayette
+// Full code: 8FW4V9H4+MC, short: V9H4+MC, center ~48.879188, 2.356063
+const PARIS_FULL = '8FW4V9H4+MC';
+const PARIS_LAT = 48.879188;
+const PARIS_LON = 2.356063;
+
+function makeNominatimFetch(lat, lon) {
+  return async () => ({
+    json: async () => [{ lat: String(lat), lon: String(lon) }],
+  });
+}
+
+function makeEmptyNominatimFetch() {
+  return async () => ({ json: async () => [] });
+}
+
+function makeThrowingFetch() {
+  return async () => { throw new Error('network error'); };
+}
+
+// ── isValidPlusCode ──────────────────────────────────────────────────────────
+
+describe('isValidPlusCode', () => {
+  test('valid full code', () => assert.equal(isValidPlusCode('8FW4V9H4+MC'), true));
+  test('valid 3-char suffix', () => assert.equal(isValidPlusCode('8FW4V9H4+MC7'), true));
+  test('trailing spaces normalized', () => assert.equal(isValidPlusCode('8FW4V9H4+MC  '), true));
+  test('lowercase normalized', () => assert.equal(isValidPlusCode('8fw4v9h4+mc'), true));
+  test('short code → false', () => assert.equal(isValidPlusCode('V9H4+MC'), false));
+  test('not a code → false', () => assert.equal(isValidPlusCode('NOTACODE'), false));
+  test('empty string → false', () => assert.equal(isValidPlusCode(''), false));
+});
+
+// ── resolvePlusCode — fast path ──────────────────────────────────────────────
+
+describe('resolvePlusCode — fast path', () => {
+  test('already valid full code', async () => {
+    const r = await resolvePlusCode('8FW4V9H4+MC', '', '');
+    assert.deepEqual(r, { code: '8FW4V9H4+MC', note: null });
+  });
+
+  test('valid code with trailing spaces', async () => {
+    const r = await resolvePlusCode('8FW4V9H4+MC  ', '', '');
+    assert.deepEqual(r, { code: '8FW4V9H4+MC', note: null });
+  });
+
+  test('lowercase valid code', async () => {
+    const r = await resolvePlusCode('8fw4v9h4+mc', '', '');
+    assert.deepEqual(r, { code: '8FW4V9H4+MC', note: null });
+  });
+});
+
+// ── resolvePlusCode — short code recovery ────────────────────────────────────
+
+describe('resolvePlusCode — short code recovery', () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = makeNominatimFetch(PARIS_LAT, PARIS_LON);
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function assertRecovered(result) {
+    assert.equal(result.code, PARIS_FULL);
+    assert.notEqual(result.note, null);
+    if (olc) {
+      const decoded = olc.decode(result.code);
+      assert.ok(Math.abs(decoded.latitudeCenter - PARIS_LAT) < 0.001, `lat ${decoded.latitudeCenter} not near ${PARIS_LAT}`);
+      assert.ok(Math.abs(decoded.longitudeCenter - PARIS_LON) < 0.001, `lon ${decoded.longitudeCenter} not near ${PARIS_LON}`);
+    }
+  }
+
+  test('short code + city/country fields', async () => {
+    assertRecovered(await resolvePlusCode('V9H4+MC', 'Paris', 'France'));
+  });
+
+  test('comma-separated city hint', async () => {
+    assertRecovered(await resolvePlusCode('V9H4+MC,PARIS', '', ''));
+  });
+
+  test('comma-separated city and country hint', async () => {
+    assertRecovered(await resolvePlusCode('V9H4+MC,PARIS,FRANCE', '', ''));
+  });
+
+  test('hint with spaces around commas (stripped)', async () => {
+    assertRecovered(await resolvePlusCode('V9H4+MC, Paris, France', '', ''));
+  });
+
+  test('arbitrary prefix text with comma separator', async () => {
+    assertRecovered(await resolvePlusCode('My code: V9H4+MC,PARIS', '', ''));
+  });
+
+  test('short code with no location ref → null', async () => {
+    const r = await resolvePlusCode('V9H4+MC', '', '');
+    assert.deepEqual(r, { code: null, note: null });
+  });
+});
+
+// ── resolvePlusCode — ambiguous input (city chars bleed into code) ───────────
+//
+// When city chars are valid OLC chars (e.g. P in PARIS), the extraction regex
+// absorbs them into the suffix. The result is an incorrect-but-valid-looking
+// code — this is a documented limitation. Tests assert the actual behavior so
+// future changes don't silently regress it.
+
+describe('resolvePlusCode — ambiguous input (city chars bleed into suffix)', () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    globalThis.fetch = makeNominatimFetch(PARIS_LAT, PARIS_LON);
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  // V9H4+MCPARIS: regex extracts V9H4+MCP (stops at 'A'), but 'ARIS' immediately
+  // follows the match — the code is embedded in a longer token, so we reject it.
+  test('no separator — null (code embedded in city name)', async () => {
+    const r = await resolvePlusCode('V9H4+MCPARIS', '', '');
+    assert.equal(r.code, null, 'should reject code embedded in city name');
+  });
+
+  test('no separator before city, comma before country — null (code embedded in city name)', async () => {
+    // V9H4+MCPARIS,FRANCE → regex extracts V9H4+MCP, but 'ARIS' follows immediately.
+    const r = await resolvePlusCode('V9H4+MCPARIS,FRANCE', '', '');
+    assert.equal(r.code, null, 'should reject code embedded in city name even with country hint');
+  });
+});
+
+// ── resolvePlusCode — other failure cases ────────────────────────────────────
+
+describe('resolvePlusCode — failure cases', () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test('not extractable input', async () => {
+    globalThis.fetch = makeNominatimFetch(PARIS_LAT, PARIS_LON);
+    const r = await resolvePlusCode('NOTACODE', 'Paris', 'France');
+    assert.deepEqual(r, { code: null, note: null });
+  });
+
+  test('Nominatim returns empty array', async () => {
+    globalThis.fetch = makeEmptyNominatimFetch();
+    const r = await resolvePlusCode('V9H4+MC', 'Paris', 'France');
+    assert.deepEqual(r, { code: null, note: null });
+  });
+
+  test('fetch throws', async () => {
+    globalThis.fetch = makeThrowingFetch();
+    const r = await resolvePlusCode('V9H4+MC', 'Paris', 'France');
+    assert.deepEqual(r, { code: null, note: null });
+  });
+
+  test('empty input', async () => {
+    globalThis.fetch = makeNominatimFetch(PARIS_LAT, PARIS_LON);
+    const r = await resolvePlusCode('', '', '');
+    assert.deepEqual(r, { code: null, note: null });
+  });
+});