@mountainpass/addressr 2.0.4 → 2.1.1

package/lib/client/elasticsearch.js

@@ -3,10 +3,12 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.ELASTIC_PORT = void 0;
+exports.ES_LOCALITY_INDEX_NAME = exports.ELASTIC_PORT = void 0;
 exports.dropIndex = dropIndex;
+exports.dropLocalityIndex = dropLocalityIndex;
 exports.esConnect = esConnect;
 exports.initIndex = initIndex;
+exports.initLocalityIndex = initLocalityIndex;
 var _debug = _interopRequireDefault(require("debug"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 const waitPort = require('wait-port');
@@ -14,6 +16,7 @@ const elasticsearch = require('@opensearch-project/opensearch');
 const logger = (0, _debug.default)('api');
 const error = (0, _debug.default)('error');
 const ES_INDEX_NAME = process.env.ES_INDEX_NAME || 'addressr';
+const ES_LOCALITY_INDEX_NAME = exports.ES_LOCALITY_INDEX_NAME = `${ES_INDEX_NAME}-localities`;
 const ELASTIC_PORT = exports.ELASTIC_PORT = Number.parseInt(process.env.ELASTIC_PORT || '9200');
 const ELASTIC_HOST = process.env.ELASTIC_HOST || '127.0.0.1';
 const ELASTIC_USERNAME = process.env.ELASTIC_USERNAME || undefined;
@@ -164,6 +167,138 @@ async function initIndex(esClient, clear, synonyms) {
   });
   logger(`indexGetResult:\n${JSON.stringify(indexGetResult, undefined, 2)}`);
 }
+async function dropLocalityIndex(esClient) {
+  let exists = await esClient.indices.exists({
+    index: ES_LOCALITY_INDEX_NAME
+  });
+  if (exists.body) {
+    const deleteIndexResult = await esClient.indices.delete({
+      index: ES_LOCALITY_INDEX_NAME
+    });
+    logger({
+      deleteIndexResult
+    });
+  }
+}
+async function initLocalityIndex(esClient, clear, synonyms) {
+  if (clear) {
+    await dropLocalityIndex(esClient);
+  }
+  const exists = await esClient.indices.exists({
+    index: ES_LOCALITY_INDEX_NAME
+  });
+  const indexBody = {
+    settings: {
+      index: {
+        analysis: {
+          filter: {
+            my_synonym_filter: {
+              type: 'synonym',
+              lenient: true,
+              synonyms: synonyms || []
+            },
+            comma_stripper: {
+              type: 'pattern_replace',
+              pattern: ',',
+              replacement: ''
+            }
+          },
+          analyzer: {
+            my_analyzer: {
+              tokenizer: 'whitecomma',
+              filter: ['uppercase', 'asciifolding', 'my_synonym_filter', 'comma_stripper', 'trim']
+            }
+          },
+          tokenizer: {
+            whitecomma: {
+              type: 'pattern',
+              pattern: String.raw`[\W,]+`,
+              lowercase: false
+            }
+          }
+        }
+      }
+    },
+    aliases: {},
+    mappings: {
+      properties: {
+        locality_name: {
+          type: 'text',
+          analyzer: 'my_analyzer',
+          fields: {
+            raw: {
+              type: 'keyword'
+            }
+          }
+        },
+        locality_class_code: {
+          type: 'keyword'
+        },
+        locality_class_name: {
+          type: 'keyword'
+        },
+        primary_postcode: {
+          type: 'keyword'
+        },
+        state_abbreviation: {
+          type: 'keyword'
+        },
+        state_name: {
+          type: 'keyword'
+        },
+        postcodes: {
+          type: 'keyword'
+        },
+        locality_pid: {
+          type: 'keyword'
+        }
+      }
+    }
+  };
+  if (exists.body) {
+    const indexCloseResult = await esClient.indices.close({
+      index: ES_LOCALITY_INDEX_NAME
+    });
+    logger({
+      indexCloseResult
+    });
+    const indexPutSettingsResult = await esClient.indices.putSettings({
+      index: ES_LOCALITY_INDEX_NAME,
+      body: indexBody
+    });
+    logger({
+      indexPutSettingsResult
+    });
+    const indexPutMappingResult = await esClient.indices.putMapping({
+      index: ES_LOCALITY_INDEX_NAME,
+      body: indexBody.mappings
+    });
+    logger({
+      indexPutMappingResult
+    });
+    const indexOpenResult = await esClient.indices.open({
+      index: ES_LOCALITY_INDEX_NAME
+    });
+    logger({
+      indexOpenResult
+    });
+    const refreshResult = await esClient.indices.refresh({
+      index: ES_LOCALITY_INDEX_NAME
+    });
+    logger({
+      refreshResult
+    });
+  } else {
+    logger(`creating index: ${ES_LOCALITY_INDEX_NAME}`);
+    const indexCreateResult = await esClient.indices.create({
+      index: ES_LOCALITY_INDEX_NAME,
+      body: indexBody
+    });
+    logger({
+      indexCreateResult
+    });
+  }
+}
 async function esConnect(esport = ELASTIC_PORT, eshost = ELASTIC_HOST, interval = 1000, timeout = 0) {
   // we keep trying to connect, no matter what
 

package/lib/service/address-service.js

@@ -8,9 +8,15 @@ exports.dropIndex = dropIndex;
 exports.fetchGnafFile = fetchGnafFile;
 exports.getAddress = getAddress;
 exports.getAddresses = getAddresses;
+exports.getLocality = getLocality;
+exports.getPostcode = getPostcode;
+exports.getState = getState;
 exports.loadGnaf = loadGnaf;
 exports.mapAddressDetails = mapAddressDetails;
 exports.searchForAddress = searchForAddress;
+exports.searchForLocality = searchForLocality;
+exports.searchForPostcode = searchForPostcode;
+exports.searchForState = searchForState;
 exports.setAddresses = setAddresses;
 exports.unzipFile = unzipFile;
 var _debug = _interopRequireDefault(require("debug"));
@@ -706,6 +712,13 @@ async function loadAddressDetails(file, expectedCount, context, {
         }
         const indexingBody = [];
         for (const row of chunk.data) {
+          // Accumulate postcodes per locality for the locality index
+          if (context.postcodesByLocality && row.LOCALITY_PID && row.POSTCODE) {
+            if (!context.postcodesByLocality[row.LOCALITY_PID]) {
+              context.postcodesByLocality[row.LOCALITY_PID] = new Set();
+            }
+            context.postcodesByLocality[row.LOCALITY_PID].add(row.POSTCODE);
+          }
           const item = mapAddressDetails(row, context, actualCount, expectedCount);
           items.push(item);
           actualCount += 1;
@@ -875,6 +888,197 @@ async function searchForAddress(searchString, p, pageSize = PAGE_SIZE) {
   logger('hits', JSON.stringify(searchResp.body.hits, undefined, 2));
   return searchResp;
 }
+async function searchForLocality(searchString, p, pageSize = PAGE_SIZE) {
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      from: (p - 1 || 0) * pageSize,
+      size: pageSize,
+      query: {
+        bool: {
+          ...(searchString && {
+            should: [{
+              multi_match: {
+                fields: ['locality_name'],
+                query: searchString,
+                fuzziness: 'AUTO',
+                type: 'bool_prefix',
+                lenient: true,
+                operator: 'AND'
+              }
+            }, {
+              multi_match: {
+                fields: ['locality_name'],
+                query: searchString,
+                type: 'phrase_prefix',
+                lenient: true,
+                operator: 'AND'
+              }
+            }]
+          })
+        }
+      },
+      sort: ['_score', {
+        'locality_name.raw': {
+          order: 'asc'
+        }
+      }]
+    }
+  });
+  logger('locality hits', JSON.stringify(searchResp.body.hits, undefined, 2));
+  return searchResp;
+}
+async function getLocality(pid) {
+  const resp = await globalThis.esClient.get({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    id: `/localities/${pid}`
+  });
+  return resp;
+}
+async function searchForPostcode(searchString) {
+  const query = searchString && searchString.length > 0 ? {
+    bool: {
+      filter: [{
+        prefix: {
+          postcodes: searchString
+        }
+      }]
+    }
+  } : {
+    bool: {
+      filter: [{
+        exists: {
+          field: 'postcodes'
+        }
+      }]
+    }
+  };
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      from: 0,
+      size: 0,
+      query,
+      aggs: {
+        postcodes: {
+          terms: {
+            field: 'postcodes',
+            size: 20
+          },
+          aggs: {
+            localities: {
+              terms: {
+                field: 'locality_name.raw',
+                size: 100
+              }
+            }
+          }
+        }
+      }
+    }
+  });
+  logger('postcode hits', JSON.stringify(searchResp.body.aggregations, undefined, 2));
+  return searchResp;
+}
+async function getPostcode(postcode) {
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      size: 0,
+      query: {
+        term: {
+          postcodes: postcode
+        }
+      },
+      aggs: {
+        localities: {
+          terms: {
+            field: 'locality_name.raw',
+            size: 100
+          }
+        }
+      }
+    }
+  });
+  return searchResp;
+}
+async function getState(abbreviation) {
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      size: 0,
+      query: {
+        term: {
+          state_abbreviation: abbreviation.toUpperCase()
+        }
+      },
+      aggs: {
+        state_name: {
+          terms: {
+            field: 'state_name',
+            size: 1
+          }
+        },
+        localities: {
+          terms: {
+            field: 'locality_name.raw',
+            size: 1000
+          }
+        },
+        postcodes: {
+          terms: {
+            field: 'postcodes',
+            size: 1000
+          }
+        }
+      }
+    }
+  });
+  return searchResp;
+}
+async function searchForState(searchString) {
+  const query = searchString ? {
+    bool: {
+      should: [{
+        prefix: {
+          state_abbreviation: searchString.toUpperCase()
+        }
+      }, {
+        wildcard: {
+          state_name: `*${searchString.toUpperCase()}*`
+        }
+      }]
+    }
+  } : {
+    match_all: {}
+  };
+  const searchResp = await globalThis.esClient.search({
+    index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+    body: {
+      from: 0,
+      size: 0,
+      query,
+      aggs: {
+        states: {
+          terms: {
+            field: 'state_abbreviation',
+            size: 20
+          },
+          aggs: {
+            state_name: {
+              terms: {
+                field: 'state_name',
+                size: 1
+              }
+            }
+          }
+        }
+      }
+    }
+  });
+  logger('state hits', JSON.stringify(searchResp.body.aggregations, undefined, 2));
+  return searchResp;
+}
 async function sendIndexRequest(indexingBody, initialBackoff = Number.parseInt(process.env.ADDRESSR_INDEX_BACKOFF || '30000'), {
   refresh = false
 } = {}) {
@@ -1024,7 +1228,9 @@ async function loadGnafData(directory, {
     //   throw new Error(`Cannot file '${countsFile}' or '${contentsFile}'`)
     // }
   }
-  const loadContext = {};
+  const loadContext = {
+    postcodesByLocality: {}
+  };
   await loadAuthFiles(files, directory, loadContext, filesCounts);
   // loadContext now contains all the auth files, so we can build the synonyms
   const synonyms = buildSynonyms(loadContext);
@@ -1074,6 +1280,51 @@ async function loadGnafData(directory, {
       });
     }
   }
+
+  // Phase 2: Index localities (separate post-load phase)
+  // Failures here must not affect address loading above
+  try {
+    await (0, _elasticsearch.initLocalityIndex)(globalThis.esClient, process.env.ES_CLEAR_INDEX || false, synonyms);
+    const localityIndexingBody = [];
+    for (const detailFile of addressDetailFiles) {
+      const state = _nodePath.default.basename(detailFile, _nodePath.default.extname(detailFile)).replace(/_.*/, '');
+      if (COVERED_STATES.length === 0 || COVERED_STATES.includes(state)) {
+        const stateName = await loadState(files, directory, state);
+        const localities = await loadLocality(files, directory, state);
+        for (const l of localities) {
+          if (l.LOCALITY_NAME === '') continue;
+          localityIndexingBody.push({
+            index: {
+              _index: _elasticsearch.ES_LOCALITY_INDEX_NAME,
+              _id: `/localities/${l.LOCALITY_PID}`
+            }
+          });
+          // Derive postcodes: prefer accumulated from ADDRESS_DETAIL,
+          // fall back to PRIMARY_POSTCODE from LOCALITY table
+          const accumulatedPostcodes = loadContext.postcodesByLocality[l.LOCALITY_PID];
+          const postcodes = accumulatedPostcodes ? [...accumulatedPostcodes] : l.PRIMARY_POSTCODE ? [l.PRIMARY_POSTCODE] : [];
+          localityIndexingBody.push({
+            locality_name: l.LOCALITY_NAME,
+            locality_class_code: l.LOCALITY_CLASS_CODE,
+            locality_class_name: localityClassCodeToName(l.LOCALITY_CLASS_CODE, loadContext),
+            primary_postcode: postcodes[0] || '',
+            postcodes,
+            state_abbreviation: state,
+            state_name: stateName,
+            locality_pid: l.LOCALITY_PID
+          });
+        }
+      }
+    }
+    if (localityIndexingBody.length > 0) {
+      await sendIndexRequest(localityIndexingBody, undefined, {
+        refresh: true
+      });
+    }
+    logger('Locality indexing complete');
+  } catch (error_) {
+    error('Locality indexing failed (address loading unaffected):', error_);
+  }
 }
 async function fileExists(countsFile) {
   try {

package/lib/src/waycharter-server.js

@@ -107,6 +107,177 @@ function startRest2Server() {
       parameters: ['q']
     }]
   });
+  const localitiesType = waycharter.registerCollection({
+    itemPath: '/:pid',
+    itemLoader: async ({
+      pid
+    }) => {
+      const resp = await (0, _addressService.getLocality)(pid);
+      const source = resp.body._source;
+      const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(source)).digest('hex');
+      return {
+        body: source,
+        headers: {
+          etag: `"${_version.version}-${hash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        },
+        status: 200
+      };
+    },
+    collectionPath: '/localities',
+    collectionLoader: async ({
+      page,
+      q
+    }) => {
+      if (q && q.length > 1) {
+        const foundLocalities = await (0, _addressService.searchForLocality)(q, page + 1, PAGE_SIZE);
+        const body = foundLocalities.body.hits.hits.map(h => {
+          return {
+            name: h._source.locality_name,
+            state: {
+              name: h._source.state_name,
+              abbreviation: h._source.state_abbreviation
+            },
+            ...(h._source.locality_class_code && {
+              class: {
+                code: h._source.locality_class_code,
+                name: h._source.locality_class_name
+              }
+            }),
+            ...(h._source.primary_postcode && {
+              postcode: h._source.primary_postcode
+            }),
+            score: h._score,
+            pid: h._id.replace('/localities/', '')
+          };
+        });
+        const responseHash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+        return {
+          body,
+          hasMore: page < foundLocalities.body.hits.total.value / PAGE_SIZE - 1,
+          headers: {
+            etag: `"${_version.version}-${responseHash}"`,
+            'cache-control': `public, max-age=${ONE_WEEK}`
+          }
+        };
+      } else {
+        return {
+          body: [],
+          hasMore: false,
+          headers: {
+            etag: `"${_version.version}"`,
+            'cache-control': `public, max-age=${ONE_WEEK}`
+          }
+        };
+      }
+    },
+    filters: [{
+      rel: 'https://addressr.io/rels/locality-search',
+      parameters: ['q']
+    }]
+  });
+  const postcodesType = waycharter.registerCollection({
+    itemPath: '/:postcode',
+    itemLoader: async ({
+      postcode
+    }) => {
+      const result = await (0, _addressService.getPostcode)(postcode);
+      const localities = result.body.aggregations.localities.buckets.map(l => ({
+        name: l.key
+      }));
+      const body = {
+        postcode,
+        localities
+      };
+      const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        headers: {
+          etag: `"${_version.version}-${hash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        },
+        status: 200
+      };
+    },
+    collectionPath: '/postcodes',
+    collectionLoader: async ({
+      q
+    }) => {
+      const result = await (0, _addressService.searchForPostcode)(q || '');
+      const buckets = result.body.aggregations.postcodes.buckets;
+      const body = buckets.map(bucket => ({
+        postcode: bucket.key,
+        localities: bucket.localities.buckets.map(l => ({
+          name: l.key
+        }))
+      }));
+      const responseHash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        hasMore: false,
+        headers: {
+          etag: `"${_version.version}-${responseHash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        }
+      };
+    },
+    filters: [{
+      rel: 'https://addressr.io/rels/postcode-search',
+      parameters: ['q']
+    }]
+  });
+  const statesType = waycharter.registerCollection({
+    itemPath: '/:abbreviation',
+    itemLoader: async ({
+      abbreviation
+    }) => {
+      const result = await (0, _addressService.getState)(abbreviation);
+      const stateName = result.body.aggregations.state_name.buckets[0]?.key || abbreviation.toUpperCase();
+      const localities = result.body.aggregations.localities.buckets.map(l => ({
+        name: l.key
+      }));
+      const postcodes = result.body.aggregations.postcodes.buckets.map(p => p.key);
+      const body = {
+        abbreviation: abbreviation.toUpperCase(),
+        name: stateName,
+        localities,
+        postcodes
+      };
+      const hash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        headers: {
+          etag: `"${_version.version}-${hash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        },
+        status: 200
+      };
+    },
+    collectionPath: '/states',
+    collectionLoader: async ({
+      q
+    }) => {
+      const result = await (0, _addressService.searchForState)(q || undefined);
+      const buckets = result.body.aggregations.states.buckets;
+      const body = buckets.map(bucket => ({
+        abbreviation: bucket.key,
+        name: bucket.state_name.buckets[0]?.key || bucket.key
+      }));
+      const responseHash = _nodeCrypto.default.createHash('md5').update(JSON.stringify(body)).digest('hex');
+      return {
+        body,
+        hasMore: false,
+        headers: {
+          etag: `"${_version.version}-${responseHash}"`,
+          'cache-control': `public, max-age=${ONE_WEEK}`
+        }
+      };
+    },
+    filters: [{
+      rel: 'https://addressr.io/rels/state-search',
+      parameters: ['q']
+    }]
+  });
   waycharter.registerResourceType({
     path: '/health',
     loader: async () => {
@@ -127,7 +298,7 @@ function startRest2Server() {
     loader: async () => {
       return {
         body: {},
-        links: [...addressesType.additionalPaths, {
+        links: [...addressesType.additionalPaths, ...localitiesType.additionalPaths, ...postcodesType.additionalPaths, ...statesType.additionalPaths, {
           rel: 'https://addressr.io/rels/health',
           uri: '/health'
         }],

package/lib/version.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.version = void 0;
 // Generated by genversion.
-const version = exports.version = '2.0.4';
+const version = exports.version = '2.1.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mountainpass/addressr",
-  "version": "2.0.4",
+  "version": "2.1.1",
   "description": "Australian Address Validation, Search and Autocomplete",
   "author": {
     "name": "Mountain Pass",

package/lib/.claude/skills/c4/scripts/c4-generate.js

@@ -1,82 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * c4-generate.mjs — Regenerate C4 architecture diagrams from source code.
- * Portable, self-contained (no npm deps). Run via: node c4-generate.mjs
- */
-"use strict";
-
-var _nodeFs = _interopRequireDefault(require("node:fs"));
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _c4Lib = require("./c4-lib.mjs");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const ROOT = process.cwd();
-const OUT_DIR = _nodePath.default.join(ROOT, "docs", "architecture", "generated");
-const OUT_JSON = _nodePath.default.join(OUT_DIR, "components.json");
-const OUT_MERMAID = _nodePath.default.join(OUT_DIR, "components.mmd");
-const C4_MODEL = _nodePath.default.join(ROOT, "docs", "architecture", "C4_MODEL.md");
-const C3_START = "<!-- c3:generated:start -->";
-const C3_END = "<!-- c3:generated:end -->";
-const C4_START = "<!-- c4:generated:start -->";
-const C4_END = "<!-- c4:generated:end -->";
-const C4_SCAFFOLD = `# C4 Architecture Model
-
-This repo uses a hybrid C4 approach:
-- C1/C2 are curated for intent and business context.
-- C3/C4 are generated from code to reduce drift.
-
-## C3: Component View (Generated)
-
-${C3_START}
-
-${C3_END}
-
-## C4: Code View (Generated)
-
-File-level dependency diagrams per component. Dashed arrows indicate cross-component imports. Grey nodes are external files.
-
-${C4_START}
-
-${C4_END}
-
-Regenerate: \`/c4\`
-Check freshness: \`/c4-check\`
-`;
-function inlineGenerated(startMarker, endMarker, content) {
-  if (!_nodeFs.default.existsSync(C4_MODEL)) return;
-  const doc = _nodeFs.default.readFileSync(C4_MODEL, "utf8");
-  const startIdx = doc.indexOf(startMarker);
-  const endIdx = doc.indexOf(endMarker);
-  if (startIdx === -1 || endIdx === -1) return;
-  const before = doc.slice(0, startIdx + startMarker.length);
-  const after = doc.slice(endIdx);
-  const updated = `${before}\n\n${content}\n\n${after}`;
-  _nodeFs.default.writeFileSync(C4_MODEL, updated);
-}
-function main() {
-  const srcRoot = (0, _c4Lib.detectSourceRoot)(ROOT);
-  const model = (0, _c4Lib.buildModel)(srcRoot);
-  const json = (0, _c4Lib.toJson)(model);
-  const c3Mermaid = (0, _c4Lib.toC3Mermaid)(model);
-  const c4Mermaid = (0, _c4Lib.toC4Mermaid)(model);
-  _nodeFs.default.mkdirSync(OUT_DIR, {
-    recursive: true
-  });
-
-  // Create scaffold if C4_MODEL.md doesn't exist
-  if (!_nodeFs.default.existsSync(C4_MODEL)) {
-    _nodeFs.default.mkdirSync(_nodePath.default.dirname(C4_MODEL), {
-      recursive: true
-    });
-    _nodeFs.default.writeFileSync(C4_MODEL, C4_SCAFFOLD);
-  }
-  _nodeFs.default.writeFileSync(OUT_JSON, json);
-  _nodeFs.default.writeFileSync(OUT_MERMAID, c3Mermaid);
-  inlineGenerated(C3_START, C3_END, `\`\`\`mermaid\n${c3Mermaid.trimEnd()}\n\`\`\``);
-  inlineGenerated(C4_START, C4_END, c4Mermaid);
-  console.log("PASS: C4 artifacts generated:");
-  console.log(`- ${_nodePath.default.relative(ROOT, OUT_JSON)}`);
-  console.log(`- ${_nodePath.default.relative(ROOT, OUT_MERMAID)}`);
-  console.log(`- ${_nodePath.default.relative(ROOT, C4_MODEL)} (C3 + C4 sections updated)`);
-}
-main();

package/lib/.claude/skills/c4/scripts/c4-lib.js

@@ -1,250 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.buildModel = buildModel;
-exports.detectSourceRoot = detectSourceRoot;
-exports.toC3Mermaid = toC3Mermaid;
-exports.toC4Mermaid = toC4Mermaid;
-exports.toJson = toJson;
-var _nodeFs = _interopRequireDefault(require("node:fs"));
-var _nodePath = _interopRequireDefault(require("node:path"));
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-/**
- * c4-lib.mjs — Portable C4 model builder (pure Node.js, no npm deps).
- * Shared by c4-generate.mjs and c4-check.mjs.
- */
-
-// ---------------------------------------------------------------------------
-// Source root detection
-// ---------------------------------------------------------------------------
-
-function detectSourceRoot(projectRoot) {
-  // 1. Try tsconfig.json
-  const tsconfigPath = _nodePath.default.join(projectRoot, "tsconfig.json");
-  if (_nodeFs.default.existsSync(tsconfigPath)) {
-    try {
-      const raw = _nodeFs.default.readFileSync(tsconfigPath, "utf8");
-      // Strip single-line comments for lenient JSON parse
-      const stripped = raw.replace(/\/\/.*$/gm, "");
-      const tsconfig = JSON.parse(stripped);
-      const rootDir = tsconfig?.compilerOptions?.rootDir;
-      if (rootDir) {
-        const candidate = _nodePath.default.resolve(projectRoot, rootDir);
-        if (_nodeFs.default.existsSync(candidate)) return candidate;
-      }
-      const includes = tsconfig?.include;
-      if (Array.isArray(includes) && includes.length > 0) {
-        // Strip glob suffixes like /**/*
-        const first = includes[0].replace(/\/\*.*$/, "");
-        const candidate = _nodePath.default.resolve(projectRoot, first);
-        if (_nodeFs.default.existsSync(candidate)) return candidate;
-      }
-    } catch {
-      // Fall through to probing
-    }
-  }
-
-  // 2. Probe common directories
-  for (const probe of ["app/src", "src", "lib"]) {
-    const candidate = _nodePath.default.join(projectRoot, probe);
-    if (_nodeFs.default.existsSync(candidate)) return candidate;
-  }
-
-  // 3. Fall back to project root
-  const fallback = projectRoot;
-
-  // 4. Verify .ts files exist somewhere
-  if (!hasFilesWithExtension(fallback, ".ts")) {
-    for (const [ext, lang] of [[".py", "Python"], [".go", "Go"], [".rs", "Rust"], [".java", "Java"]]) {
-      if (hasFilesWithExtension(fallback, ext)) {
-        throw new Error(`C4 generation does not yet support ${lang} projects`);
-      }
-    }
-    throw new Error("No TypeScript source files found");
-  }
-  return fallback;
-}
-function hasFilesWithExtension(dir, ext) {
-  try {
-    const entries = _nodeFs.default.readdirSync(dir, {
-      withFileTypes: true
-    });
-    for (const entry of entries) {
-      const full = _nodePath.default.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (hasFilesWithExtension(full, ext)) return true;
-      } else if (entry.isFile() && entry.name.endsWith(ext)) {
-        return true;
-      }
-    }
-  } catch {
-    // Directory not readable
-  }
-  return false;
-}
-
-// ---------------------------------------------------------------------------
-// File walking
-// ---------------------------------------------------------------------------
-
-function walk(dir, out) {
-  const entries = _nodeFs.default.readdirSync(dir, {
-    withFileTypes: true
-  });
-  for (const entry of entries) {
-    const full = _nodePath.default.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      walk(full, out);
-      continue;
-    }
-    if (!entry.isFile()) continue;
-    if (!entry.name.endsWith(".ts") || entry.name.endsWith(".test.ts")) continue;
-    out.push(full);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Import parsing & resolution
-// ---------------------------------------------------------------------------
-
-function parseImports(text) {
-  const specs = [];
-  const importRe = /import\s+[^"']*?["']([^"']+)["']/g;
-  const dynamicRe = /import\(\s*["']([^"']+)["']\s*\)/g;
-  const requireRe = /require\(\s*["']([^"']+)["']\s*\)/g;
-  let match;
-  while ((match = importRe.exec(text)) !== null) specs.push(match[1]);
-  while ((match = dynamicRe.exec(text)) !== null) specs.push(match[1]);
-  while ((match = requireRe.exec(text)) !== null) specs.push(match[1]);
-  return specs;
-}
-function resolveImport(fromFile, spec, srcRoot) {
-  if (!spec.startsWith(".")) return null;
-  const stripped = spec.replace(/\.js$/, "");
-  const base = _nodePath.default.resolve(_nodePath.default.dirname(fromFile), stripped);
-  const candidates = [base, `${base}.ts`, _nodePath.default.join(base, "index.ts")];
-  for (const candidate of candidates) {
-    if (_nodeFs.default.existsSync(candidate) && _nodeFs.default.statSync(candidate).isFile()) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
-// ---------------------------------------------------------------------------
-// Model building
-// ---------------------------------------------------------------------------
-
-function relToSrc(absPath, srcRoot) {
-  return _nodePath.default.relative(srcRoot, absPath).split(_nodePath.default.sep).join("/");
-}
-function componentIdForRel(rel) {
-  const [first] = rel.split("/");
-  if (!first || !rel.includes("/")) return "app";
-  return first;
-}
-function buildModel(srcRoot) {
-  const files = [];
-  walk(srcRoot, files);
-  const componentFiles = new Map();
-  const dependencies = new Map();
-  const fileDeps = [];
-  for (const absFile of files) {
-    const fromRel = relToSrc(absFile, srcRoot);
-    const fromComp = componentIdForRel(fromRel);
-    if (!componentFiles.has(fromComp)) componentFiles.set(fromComp, new Set());
-    componentFiles.get(fromComp).add(fromRel);
-    if (!dependencies.has(fromComp)) dependencies.set(fromComp, new Set());
-    const text = _nodeFs.default.readFileSync(absFile, "utf8");
-    const specs = parseImports(text);
-    for (const spec of specs) {
-      const resolved = resolveImport(absFile, spec, srcRoot);
-      if (!resolved) continue;
-      const toRel = relToSrc(resolved, srcRoot);
-      const toComp = componentIdForRel(toRel);
-      fileDeps.push({
-        from: fromRel,
-        to: toRel
-      });
-      if (toComp !== fromComp) dependencies.get(fromComp).add(toComp);
-    }
-  }
-  const components = [...componentFiles.keys()].sort().map(id => ({
-    id,
-    name: id === "app" ? "app-entry" : id,
-    kind: "generated",
-    files: [...(componentFiles.get(id) || [])].sort(),
-    depends_on: [...(dependencies.get(id) || [])].sort()
-  }));
-  return {
-    generator_version: "1",
-    source_root: _nodePath.default.relative(process.cwd(), srcRoot).split(_nodePath.default.sep).join("/") || ".",
-    components,
-    fileDeps
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Mermaid generation
-// ---------------------------------------------------------------------------
-
-function toC3Mermaid(model) {
-  const lines = ["flowchart LR"];
-  for (const component of model.components) {
-    lines.push(`  ${component.id}["${component.name}"]`);
-  }
-  for (const component of model.components) {
-    for (const to of component.depends_on) {
-      lines.push(`  ${component.id} --> ${to}`);
-    }
-  }
-  lines.push("");
-  return `${lines.join("\n")}\n`;
-}
-function fileNodeId(relPath) {
-  return relPath.replace(/[/.\\-]/g, "_").replace(/\.ts$/, "");
-}
-function fileLabel(relPath) {
-  return _nodePath.default.basename(relPath, ".ts");
-}
-function toC4Mermaid(model) {
-  const sections = [];
-  for (const component of model.components) {
-    const lines = ["flowchart LR"];
-    const fileSet = new Set(component.files);
-    for (const file of component.files) {
-      lines.push(`  ${fileNodeId(file)}["${fileLabel(file)}"]`);
-    }
-    const externalNodes = new Set();
-    const edges = new Set();
-    for (const dep of model.fileDeps) {
-      if (!fileSet.has(dep.from)) continue;
-      const edgeKey = `${dep.from}|${dep.to}`;
-      if (edges.has(edgeKey)) continue;
-      edges.add(edgeKey);
-      if (fileSet.has(dep.to)) {
-        lines.push(`  ${fileNodeId(dep.from)} --> ${fileNodeId(dep.to)}`);
-      } else {
-        const toCompId = componentIdForRel(dep.to);
-        const toComp = toCompId === "app" ? "app-entry" : toCompId;
-        const extId = fileNodeId(dep.to);
-        if (!externalNodes.has(dep.to)) {
-          externalNodes.add(dep.to);
-          lines.push(`  ${extId}["${toComp}/${fileLabel(dep.to)}"]:::ext`);
-        }
-        lines.push(`  ${fileNodeId(dep.from)} -.-> ${extId}`);
-      }
-    }
-    if (externalNodes.size > 0) {
-      lines.push(`  classDef ext fill:#f0f0f0,stroke:#999,stroke-dasharray:5 5`);
-    }
-    lines.push("");
-    sections.push(`### ${component.name}\n\n\`\`\`mermaid\n${lines.join("\n")}\n\`\`\``);
-  }
-  return sections.join("\n\n");
-}
-function toJson(model) {
-  return `${JSON.stringify(model, null, 2)}\n`;
-}

package/lib/.claude/skills/c4-check/scripts/c4-check.js

@@ -1,74 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * c4-check.mjs — Check whether C4 architecture diagrams are up to date.
- * Portable, self-contained (no npm deps). Run via: node c4-check.mjs
- */
-"use strict";
-
-var _nodeFs = _interopRequireDefault(require("node:fs"));
-var _nodePath = _interopRequireDefault(require("node:path"));
-var _c4Lib = require("../../c4/scripts/c4-lib.mjs");
-function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const ROOT = process.cwd();
-const COMPONENTS_FILE = _nodePath.default.join(ROOT, "docs", "architecture", "generated", "components.json");
-const POLICY_FILE = _nodePath.default.join(ROOT, "governance", "architecture-conformance-policy.json");
-function main() {
-  const srcRoot = (0, _c4Lib.detectSourceRoot)(ROOT);
-  const model = (0, _c4Lib.buildModel)(srcRoot);
-  const freshJson = (0, _c4Lib.toJson)(model);
-  const failures = [];
-
-  // 1. Compare JSON against existing components.json
-  if (!_nodeFs.default.existsSync(COMPONENTS_FILE)) {
-    failures.push("missing generated architecture model: docs/architecture/generated/components.json");
-  } else {
-    const existingJson = _nodeFs.default.readFileSync(COMPONENTS_FILE, "utf8");
-    if (existingJson !== freshJson) {
-      failures.push("C4 model is stale — run /c4 to regenerate");
-    }
-  }
-
-  // 2. Conformance policy check (if policy file exists)
-  if (_nodeFs.default.existsSync(POLICY_FILE)) {
-    const policy = JSON.parse(_nodeFs.default.readFileSync(POLICY_FILE, "utf8"));
-    const components = new Map();
-    for (const component of model.components) {
-      components.set(component.id, new Set(component.depends_on || []));
-    }
-    for (const id of policy.required_components || []) {
-      if (!components.has(id)) {
-        failures.push(`missing required component: ${id}`);
-      }
-    }
-    for (const rule of policy.forbidden_dependencies || []) {
-      const deps = components.get(rule.from);
-      if (!deps) {
-        failures.push(`forbidden dependency rule references unknown component: ${rule.from}`);
-        continue;
-      }
-      if (deps.has(rule.to)) {
-        failures.push(`forbidden dependency: ${rule.from} -> ${rule.to}${rule.reason ? ` (${rule.reason})` : ""}`);
-      }
-    }
-    for (const rule of policy.required_dependencies || []) {
-      const deps = components.get(rule.from);
-      if (!deps) {
-        failures.push(`required dependency rule references unknown component: ${rule.from}`);
-        continue;
-      }
-      if (!deps.has(rule.to)) {
-        failures.push(`missing required dependency: ${rule.from} -> ${rule.to}${rule.reason ? ` (${rule.reason})` : ""}`);
-      }
-    }
-  }
-  if (failures.length > 0) {
-    console.error("FAIL: C4 architecture check:");
-    for (const failure of failures) {
-      console.error(`- ${failure}`);
-    }
-    process.exit(1);
-  }
-  console.log("PASS: C4 architecture diagrams are up to date.");
-}
-main();

package/lib/.claude/skills/wardley/owm-to-svg.js

@@ -1,191 +0,0 @@
-#!/usr/bin/env node
-/**
- * Converts an OWM (Online Wardley Mapping) file to SVG and PNG.
- *
- * Usage: node owm-to-svg.mjs [input.owm] [output.svg]
- *
- * Defaults:
- *   input:  docs/wardley-map.owm
- *   output: docs/wardley-map.svg (+ .png via sips)
- */
-"use strict";
-
-var _fs = require("fs");
-var _child_process = require("child_process");
-var _path = require("path");
-const inputPath = (0, _path.resolve)(process.argv[2] || 'docs/wardley-map.owm');
-const outputSvg = (0, _path.resolve)(process.argv[3] || inputPath.replace(/\.owm$/, '.svg'));
-const outputPng = outputSvg.replace(/\.svg$/, '.png');
-const raw = (0, _fs.readFileSync)(inputPath, 'utf8');
-const lines = raw.split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('//'));
-
-// Parse
-let title = '';
-const components = [];
-const links = [];
-const evolves = [];
-for (const line of lines) {
-  const titleMatch = line.match(/^title\s+(.+)/);
-  if (titleMatch) {
-    title = titleMatch[1];
-    continue;
-  }
-  const anchorMatch = line.match(/^anchor\s+(.+?)\s+\[([0-9.]+),\s*([0-9.]+)\]/);
-  if (anchorMatch) {
-    components.push({
-      name: anchorMatch[1],
-      vis: parseFloat(anchorMatch[2]),
-      evo: parseFloat(anchorMatch[3]),
-      isAnchor: true
-    });
-    continue;
-  }
-  const compMatch = line.match(/^component\s+(.+?)\s+\[([0-9.]+),\s*([0-9.]+)\]/);
-  if (compMatch) {
-    components.push({
-      name: compMatch[1],
-      vis: parseFloat(compMatch[2]),
-      evo: parseFloat(compMatch[3]),
-      isAnchor: false
-    });
-    continue;
-  }
-  const evolveMatch = line.match(/^evolve\s+(.+?)\s+([0-9.]+)/);
-  if (evolveMatch) {
-    evolves.push({
-      name: evolveMatch[1],
-      targetEvo: parseFloat(evolveMatch[2])
-    });
-    continue;
-  }
-  const linkMatch = line.match(/^(.+?)->(.+)/);
-  if (linkMatch) {
-    links.push({
-      from: linkMatch[1].trim(),
-      to: linkMatch[2].trim()
-    });
-    continue;
-  }
-}
-
-// Layout constants
-const W = 1200;
-const H = 800;
-const PAD_LEFT = 80;
-const PAD_RIGHT = 60;
-const PAD_TOP = 60;
-const PAD_BOTTOM = 80;
-const CHART_W = W - PAD_LEFT - PAD_RIGHT;
-const CHART_H = H - PAD_TOP - PAD_BOTTOM;
-function evoToX(evo) {
-  return PAD_LEFT + evo * CHART_W;
-}
-function visToY(vis) {
-  return PAD_TOP + (1 - vis) * CHART_H;
-}
-
-// Build SVG
-const svgParts = [];
-svgParts.push(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}">`);
-svgParts.push(`<defs>
-  <marker id="evolve-arrow" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto">
-    <polygon points="0,0 8,3 0,6" fill="#c44"/>
-  </marker>
-</defs>`);
-svgParts.push(`<style>
-  text { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif; }
-  .title { font-size: 20px; font-weight: 700; }
-  .axis-label { font-size: 12px; fill: #666; }
-  .phase-label { font-size: 11px; fill: #999; }
-  .comp-label { font-size: 13px; fill: #222; }
-  .anchor-label { font-size: 13px; fill: #222; font-weight: 600; }
-  .evolve-label { font-size: 11px; fill: #c44; }
-</style>`);
-
-// Background
-svgParts.push(`<rect width="${W}" height="${H}" fill="white"/>`);
-
-// Title
-svgParts.push(`<text x="${PAD_LEFT}" y="35" class="title">${title}</text>`);
-
-// Axes
-svgParts.push(`<line x1="${PAD_LEFT}" y1="${PAD_TOP}" x2="${PAD_LEFT}" y2="${H - PAD_BOTTOM}" stroke="#333" stroke-width="1.5"/>`);
-svgParts.push(`<line x1="${PAD_LEFT}" y1="${H - PAD_BOTTOM}" x2="${W - PAD_RIGHT}" y2="${H - PAD_BOTTOM}" stroke="#333" stroke-width="1.5"/>`);
-
-// Arrow on evolution axis
-const arrowX = W - PAD_RIGHT;
-const arrowY = H - PAD_BOTTOM;
-svgParts.push(`<polygon points="${arrowX},${arrowY} ${arrowX - 8},${arrowY - 4} ${arrowX - 8},${arrowY + 4}" fill="#333"/>`);
-
-// Axis titles
-svgParts.push(`<text x="${PAD_LEFT - 10}" y="${PAD_TOP + CHART_H / 2}" class="axis-label" transform="rotate(-90 ${PAD_LEFT - 10} ${PAD_TOP + CHART_H / 2})" text-anchor="middle">Value Chain</text>`);
-svgParts.push(`<text x="${PAD_LEFT + CHART_W / 2}" y="${H - 15}" class="axis-label" text-anchor="middle">Evolution</text>`);
-
-// Phase dividers and labels
-const phases = [{
-  boundary: 0.17,
-  label: 'Genesis'
-}, {
-  boundary: 0.37,
-  label: 'Custom-Built'
-}, {
-  boundary: 0.63,
-  label: 'Product'
-}, {
-  boundary: 1.0,
-  label: 'Commodity'
-}];
-let prevBound = 0;
-for (const phase of phases) {
-  const midEvo = (prevBound + phase.boundary) / 2;
-  svgParts.push(`<text x="${evoToX(midEvo)}" y="${H - PAD_BOTTOM + 25}" class="phase-label" text-anchor="middle">${phase.label}</text>`);
-  if (phase.boundary < 1.0) {
-    const dx = evoToX(phase.boundary);
-    svgParts.push(`<line x1="${dx}" y1="${PAD_TOP}" x2="${dx}" y2="${H - PAD_BOTTOM}" stroke="#ddd" stroke-width="1" stroke-dasharray="4,4"/>`);
-  }
-  prevBound = phase.boundary;
-}
-
-// Links
-const compMap = new Map(components.map(c => [c.name, c]));
-for (const link of links) {
-  const from = compMap.get(link.from);
-  const to = compMap.get(link.to);
-  if (!from || !to) continue;
-  svgParts.push(`<line x1="${evoToX(from.evo)}" y1="${visToY(from.vis)}" x2="${evoToX(to.evo)}" y2="${visToY(to.vis)}" stroke="#aaa" stroke-width="1.5"/>`);
-}
-
-// Evolution arrows
-for (const ev of evolves) {
-  const comp = compMap.get(ev.name);
-  if (!comp) continue;
-  const x1 = evoToX(comp.evo);
-  const x2 = evoToX(ev.targetEvo);
-  const y = visToY(comp.vis);
-  svgParts.push(`<line x1="${x1 + 8}" y1="${y}" x2="${x2 - 2}" y2="${y}" stroke="#c44" stroke-width="2" stroke-dasharray="6,3" marker-end="url(#evolve-arrow)"/>`);
-  svgParts.push(`<circle cx="${x2}" cy="${y}" r="5" fill="none" stroke="#c44" stroke-width="1.5" stroke-dasharray="3,2"/>`);
-}
-
-// Components
-for (const comp of components) {
-  const cx = evoToX(comp.evo);
-  const cy = visToY(comp.vis);
-  const r = comp.isAnchor ? 0 : 6;
-  const labelClass = comp.isAnchor ? 'anchor-label' : 'comp-label';
-  if (!comp.isAnchor) {
-    svgParts.push(`<circle cx="${cx}" cy="${cy}" r="${r}" fill="white" stroke="#333" stroke-width="1.5"/>`);
-  }
-  svgParts.push(`<text x="${cx + 10}" y="${cy - 10}" class="${labelClass}">${comp.name}</text>`);
-}
-svgParts.push('</svg>');
-const svg = svgParts.join('\n');
-(0, _fs.writeFileSync)(outputSvg, svg);
-console.log(`SVG: ${outputSvg}`);
-
-// Convert to PNG via sips (macOS)
-try {
-  (0, _child_process.execSync)(`sips -s format png "${outputSvg}" --out "${outputPng}" 2>/dev/null`);
-  console.log(`PNG: ${outputPng}`);
-} catch {
-  console.log('PNG: skipped (sips not available, macOS only)');
-}