@mailwoman/geographic-model 10.0.0 → 10.2.0

package/lib/load.ts

@@ -3,27 +3,17 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The authoring loader: a directory of JSON files in, one {@link GeographicModelDocument} out.
+ *   Loads a directory of JSON files into one {@link GeographicModelDocument}.
  *
- *   **The filesystem layout is authoring convenience and carries no meaning.** A concept means the
- *   same thing whichever file it was written in, and a file may hold any subset of the tables. What a
- *   directory does carry is one manifest — `model.json`, holding the document's `version` — because a
- *   version assembled from whichever fragment happened to declare one is a version nobody chose.
+ *   File layout does not assign meaning to a file. Any file may hold any subset of the tables.
+ *   Only `model.json` may declare the document's `version`.
  *
- *   Two properties make the loader safe to build an artifact from:
+ *   The loader sorts files by path before reading them, so directory enumeration order never affects
+ *   the output. It records the source file of every record and maps each validation issue back to that
+ *   file. A duplicate-identifier issue also reports the file that used the identifier first.
  *
- *   1. **Enumeration order cannot reach the output.** {@link mergeGeographicModelFiles} sorts the
- *      files it was handed before reading any of them, so the merged tables are a function of the file
- *      NAMES and their contents. `readdir` order, and therefore the filesystem, is out of the answer.
- *   2. **Every issue names the file it came from.** The document validator addresses a record by its
- *      position in the merged table (`$.concepts[7].kind`), which is the one thing an author cannot
- *      see; the loader keeps a per-record origin and re-addresses each issue to its source file. A
- *      duplicate identifier names both files — the one that claimed it and the one that claimed it
- *      first — because "already used" is unactionable without the other half.
- *
- *   Validation itself is delegated whole to `./validate.ts`. What the loader checks on its own is only
- *   what the validator cannot see: whether a file parses, whether it is an object, and whether the
- *   keys it uses are tables.
+ *   `./validate.ts` performs document validation. The loader checks only that each file parses, holds
+ *   an object and uses known table keys.
  */
 
 import { readLocalTextFile } from "@mailwoman/core/fs/readers"
@@ -43,12 +33,13 @@ import {
 	ValidationIssueCode,
 } from "#validation/issues"
 /**
- * The manifest every model directory carries: the document's `version`, and nothing else.
+ * The manifest file that every model directory contains.
+ * It holds only the document's `version`.
  */
 export const MODEL_MANIFEST_FILENAME = "model.json"
 
 /**
- * The keys a source file may use. They are the document's tables, minus the manifest's `version`.
+ * The table keys that a non-manifest source file may use.
  */
 const TABLE_FIELDS = ["relations", "concepts", "mappings", "observations", "derivedFacts"] as const
 
@@ -57,49 +48,49 @@ type TableField = (typeof TABLE_FIELDS)[number]
 const MANIFEST_FIELDS = ["version"] as const
 
 /**
- * The document path a record occupies, e.g. `$.concepts[7]` or `$.concepts[7].assertions[1]`. Group 3 is present only
- * for an assertion, which is the one record that nests.
+ * Matches a record's path in the merged document, such as `$.concepts[7]` or `$.concepts[7].assertions[1]`.
+ * Group 3 matches only for a nested assertion.
  */
 const RECORD_PATH_PATTERN = /^\$\.([A-Za-z]+)\[(\d+)\](?:\.assertions\[(\d+)\])?/u
 
 /**
- * Every way loading can fail. The document validator's whole vocabulary, plus the one failure only a loader meets: a
- * file that is not JSON at all.
+ * Load issue codes: every validation code plus `MalformedJSON`.
  */
 export const LoadIssueCode = {
 	...ValidationIssueCode,
 	/**
-	 * A source file could not be parsed as JSON. Emitted by the loader alone; the document validator is handed values,
-	 * never text.
+	 * A source file is not valid JSON.
 	 */
 	MalformedJSON: "malformed_json",
 } as const
 
+/**
+ * A {@link LoadIssueCode} value.
+ */
 export type LoadIssueCode = (typeof LoadIssueCode)[keyof typeof LoadIssueCode]
 
 /**
- * One violation, addressed to the file an author can open.
+ * One load issue, attributed to its source file.
  */
 export interface SourcedIssue {
 	/**
-	 * The source file, relative to the model directory, with `/` separators on every platform.
+	 * The source file path relative to the model directory, with `/` separators on every platform.
 	 */
 	file: string
 	/**
-	 * The JSONPath-style address into the MERGED document, kept so a reader can find the record in the table the
-	 * validator saw.
+	 * The JSONPath-style location in the merged document.
 	 */
 	path: string
 	code: LoadIssueCode
 	message: string
 	/**
-	 * For a duplicate identifier: the file that claimed it first.
+	 * For a duplicate identifier, the file that used the identifier first.
 	 */
-	otherFile?: string
+	otherFile: string | null
 }
 
 /**
- * One authoring file: its path relative to the model directory, and its text.
+ * A source file's path relative to the model directory, plus its text.
  */
 export interface GeographicModelSourceFile {
 	path: string
@@ -107,7 +98,7 @@ export interface GeographicModelSourceFile {
 }
 
 /**
- * Render every issue as one line, `file:path: message [code]`, in the order the loader produced them.
+ * Formats each issue as one `file:path: message [code]` line, in input order.
  */
 export function formatSourcedIssues(issues: readonly SourcedIssue[]): string {
 	return issues
@@ -120,8 +111,8 @@ export function formatSourcedIssues(issues: readonly SourcedIssue[]): string {
 }
 
 /**
- * Thrown when a model directory does not load. Carries every issue, and states them all in its message, so a caller
- * that only prints `error.message` still sees the whole list.
+ * The error thrown when a model directory does not load.
+ * Its message lists every issue.
  */
 export class GeographicModelLoadError extends Error {
 	readonly issues: readonly SourcedIssue[]
@@ -135,16 +126,16 @@ export class GeographicModelLoadError extends Error {
 }
 
 /**
- * Where one record came from, kept so a validation issue addressed to the merged table can be re-addressed to a file.
+ * The source of one record in the merged document.
  */
 interface RecordOrigin {
 	file: string
 	/**
-	 * The table the record was appended to, or `assertions` for one nested inside a concept — the namespace its
-	 * identifier is unique within.
+	 * The record's table, or `assertions` for an assertion nested in a concept.
+	 * Identifiers are unique within a table.
 	 */
 	table: string
-	id?: string
+	id: string | null
 }
 
 interface MergeState {
@@ -152,23 +143,21 @@ interface MergeState {
 	tables: Record<TableField, unknown[]>
 	origins: Map<string, RecordOrigin>
 	/**
-	 * Table → identifier → the file that used it first. The validator reports the SECOND claimant, so this is what names
-	 * the other half of the pair.
+	 * Maps each table to its identifiers and the file that used each identifier first.
+	 * The validator reports only the second use.
 	 */
 	firstClaims: Map<string, Map<string, string>>
-	version?: string
+	version: string | null
 }
 
 function sourced(file: string, issues: readonly ValidationIssue[]): SourcedIssue[] {
-	return issues.map((issue) => ({ file, path: issue.path, code: issue.code, message: issue.message }))
+	return issues.map((issue) => ({ file, path: issue.path, code: issue.code, message: issue.message, otherFile: null }))
 }
 
 /**
- * Parse one source file, or report why it could not be parsed.
+ * Parses one source file, or records the parse failure and returns `undefined`.
  *
- * The house wrapper lives in `@mailwoman/core/objects`, and this package takes no dependency on `@mailwoman/core` — the
- * boundary record keeps world semantics out of core, and a build-time loader is not the reason to reverse it. The
- * parser's own message is also the useful half of the report here, which a wrapper returning a fallback discards.
+ * The loader calls `JSON.parse` directly because the report needs the parser's error message.
  */
 function readSourceJSON(file: GeographicModelSourceFile, issues: SourcedIssue[]): unknown {
 	try {
@@ -180,14 +169,15 @@ function readSourceJSON(file: GeographicModelSourceFile, issues: SourcedIssue[])
 			path: "$",
 			code: LoadIssueCode.MalformedJSON,
 			message: error instanceof Error ? error.message : String(error),
+			otherFile: null,
 		})
 
 		return undefined
 	}
 }
 
-function claim(state: MergeState, table: string, id: string | undefined, file: string): void {
-	if (id === undefined) return
+function claim(state: MergeState, table: string, id: string | null, file: string): void {
+	if (!id) return
 
 	const claims = state.firstClaims.get(table) ?? new Map<string, string>()
 
@@ -198,10 +188,10 @@ function claim(state: MergeState, table: string, id: string | undefined, file: s
 	}
 }
 
-function recordID(entry: unknown): string | undefined {
-	if (!isPlainObject(entry)) return undefined
+function recordID(entry: unknown): string | null {
+	if (!isPlainObject(entry)) return null
 
-	return typeof entry.id === "string" ? entry.id : undefined
+	return typeof entry.id === "string" ? entry.id : null
 }
 
 function readManifestFile(state: MergeState, file: GeographicModelSourceFile, value: unknown): void {
@@ -219,7 +209,7 @@ function readManifestFile(state: MergeState, file: GeographicModelSourceFile, va
 }
 
 /**
- * Append one file's tables to the merged document, recording where every record came from.
+ * Appends one file's tables to the merged document and records each record's origin.
  */
 function readTableFile(state: MergeState, file: GeographicModelSourceFile, value: unknown): void {
 	const issues: ValidationIssue[] = []
@@ -232,8 +222,7 @@ function readTableFile(state: MergeState, file: GeographicModelSourceFile, value
 		return
 	}
 
-	// `version` is admitted to the field check and then refused on its own, so the report names where a version belongs
-	// instead of only saying the field is unknown here.
+	// The field check allows `version` so that the specific error below can say where it belongs.
 	checkFieldNames(issues, "$", value, [...TABLE_FIELDS, ...MANIFEST_FIELDS])
 
 	if ("version" in value) {
@@ -277,7 +266,7 @@ function readTableFile(state: MergeState, file: GeographicModelSourceFile, value
 }
 
 /**
- * Re-address one validation issue from its position in the merged document to the file the record was authored in.
+ * Attributes one validation issue to the file that contains the record.
  */
 function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
 	const match = RECORD_PATH_PATTERN.exec(issue.path)
@@ -285,30 +274,29 @@ function attribute(state: MergeState, issue: ValidationIssue): SourcedIssue {
 	const key = match ? `${match[1]}[${match[2]}]${nested ? `.assertions[${nested}]` : ""}` : undefined
 	const origin = key ? state.origins.get(key) : undefined
 
-	// A document-level issue — `$.version`, or the root itself — is about the manifest, which is the only file that
-	// contributes anything outside a table.
+	// Only the manifest contributes fields outside the tables, so it owns document-level issues.
 	const file = origin?.file ?? MODEL_MANIFEST_FILENAME
 
 	const claimant =
 		issue.code === ValidationIssueCode.DuplicateID && origin?.id
 			? state.firstClaims.get(origin.table)?.get(origin.id)
-			: undefined
+			: null
 
 	return {
 		file,
 		path: issue.path,
 		code: issue.code,
 		message: issue.message,
-		...(claimant ? { otherFile: claimant } : {}),
+		otherFile: claimant ?? null,
 	}
 }
 
 /**
- * Merge authoring files into one document, and validate the result.
+ * Merges source files into one document and validates it.
+ *
+ * The function sorts files by path first, so the input order never affects the result.
  *
- * The files are sorted by path before anything is read, so any enumeration order produces the same tables in the same
- * order. Throws {@link GeographicModelLoadError} with every issue, each addressed to its source file; returns nothing
- * partial.
+ * @throws {GeographicModelLoadError} With every issue, each attributed to its source file.
  */
 export function mergeGeographicModelFiles(files: readonly GeographicModelSourceFile[]): GeographicModelDocument {
 	const state: MergeState = {
@@ -316,6 +304,7 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 		tables: { relations: [], concepts: [], mappings: [], observations: [], derivedFacts: [] },
 		origins: new Map(),
 		firstClaims: new Map(),
+		version: null,
 	}
 
 	const ordered = files.toSorted((left, right) => compareIdentifiers(left.path, right.path))
@@ -327,6 +316,7 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 			path: "$",
 			code: LoadIssueCode.MissingField,
 			message: `a model directory carries \`${MODEL_MANIFEST_FILENAME}\`, holding the document's \`version\``,
+			otherFile: null,
 		})
 	}
 
@@ -344,7 +334,7 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 		readTableFile(state, file, value)
 	}
 
-	// A record issue cannot be addressed to a file that failed to parse, so the structural pass reports alone.
+	// Validation issues cannot be attributed reliably after a structural failure, so those failures stop here.
 	if (state.issues.length) throw new GeographicModelLoadError(state.issues)
 
 	const result = validateGeographicModelDocument({ version: state.version, ...state.tables })
@@ -357,11 +347,9 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
 }
 
 /**
- * Every `*.json` file under `root`, relative to it, in code-point order.
+ * Lists every `*.json` file under `root` as a relative path, sorted by code point at each level.
  *
- * Directory entries are sorted at each level rather than taken as `readdir` returns them, so the list is a property of
- * the tree and not of the filesystem that stored it. Symbolic links are not followed: a model directory is source, and
- * a link out of it is a record whose home nobody can state.
+ * Symbolic links are skipped because only regular files and directories match.
  */
 async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
 	const entries = await Globerator.from("*", {
@@ -390,9 +378,9 @@ async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
 }
 
 /**
- * Load a model directory: read every `*.json` file under it, merge them, and validate the result.
+ * Reads every `*.json` file under `root`, merges the files and validates the merged document.
  *
- * Throws {@link GeographicModelLoadError} with every issue, each addressed to its source file.
+ * @throws {GeographicModelLoadError} With every issue, each attributed to its source file.
  */
 export async function loadGeographicModelDirectory(root: string): Promise<GeographicModelDocument> {
 	const paths = await listSourceFiles(root)

package/lib/lookup.ts

@@ -3,19 +3,8 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   The read surface over a compiled artifact: every question answered by one map probe, none by
- *   walking the graph.
- *
- *   The shape is deliberate. `@mailwoman/geographic-model` compiles authored records into an artifact
- *   precisely so a runtime consumer never traverses anything — so the index exposes lookups
- *   (`concept`, `ancestorsOf`, `derivedFactsAbout`, `conceptsForExternalID`) and no walk, no cursor,
- *   and no query language.
- *
- *   Two absences are distinguished everywhere, because they are different answers. A lookup for a
- *   concept the artifact does not carry returns `undefined` — the model cannot speak to it. A lookup
- *   for a concept it does carry, which nothing was derived about, returns an empty list — the model
- *   carries it and states nothing. A reader that collapsed the two would report "no ancestors" for a
- *   concept it had never heard of.
+ *   Read-only lookups over a compiled artifact. Queries use prebuilt maps rather than traversing the graph.
+ *   The lookup returns `undefined` for unknown concepts and an empty list for known concepts with no related facts.
  */
 
 import { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
@@ -32,36 +21,32 @@ import type {
 } from "#schema"
 
 /**
- * Lookups over one compiled artifact.
+ * Lookup methods for one compiled artifact.
  */
 export interface GeographicModelIndex {
 	/**
-	 * The artifact these lookups read, so a consumer holding the index never has to carry both.
+	 * Compiled artifact used by this index.
 	 */
 	readonly model: CompiledGeographicModel
 	/**
-	 * One concept record, or `undefined` when the artifact does not carry it.
+	 * Concept record, or `undefined` if absent.
 	 */
 	concept(id: ConceptID): ConceptRecord | undefined
 	/**
-	 * One relation definition, or `undefined` when the artifact does not carry it.
+	 * Relation definition, or `undefined` if absent.
 	 */
 	relation(id: RelationID): RelationRecord | undefined
 	/**
-	 * Every concept this one is a kind of, transitively, in code-point order. Empty for a concept that is a kind of
-	 * nothing; `undefined` for a concept the artifact does not carry.
+	 * Transitive ancestors in code-point order; `undefined` if the concept is absent.
 	 */
 	ancestorsOf(id: ConceptID): readonly ConceptID[] | undefined
 	/**
-	 * Every derived fact whose subject is this concept, in artifact order. Empty for a concept nothing was derived about;
-	 * `undefined` for a concept the artifact does not carry.
+	 * Derived facts in artifact order; `undefined` if the concept is absent.
 	 */
 	derivedFactsAbout(id: ConceptID): readonly DerivedFactRecord[] | undefined
 	/**
-	 * The concepts a mapping translates this external identifier into, in code-point order.
-	 *
-	 * An empty list is a true negative rather than an unread answer: the artifact carries every mapping the document
-	 * authored, so nothing having declared this identifier is the whole of what there is to know about it.
+	 * Concepts mapped from this external ID, in code-point order.
+	 * An empty list means no mapping is recorded.
 	 */
 	conceptsForExternalID(vocabulary: ExternalVocabulary, externalID: POICategoryID): readonly ConceptID[]
 }
@@ -71,10 +56,9 @@ function externalKey(vocabulary: ExternalVocabulary, externalID: string): string
 }
 
 /**
- * Index a compiled artifact for reading.
+ * Build lookup maps over a compiled artifact.
  *
- * Every table is walked once here so that no table is ever walked again. Nothing is copied — the records handed back
- * are the artifact's own.
+ * Return references to the artifact's records without copying them.
  */
 export function createGeographicModelIndex(model: CompiledGeographicModel): GeographicModelIndex {
 	const concepts = new Map<string, ConceptRecord>(model.concepts.map((concept) => [String(concept.id), concept]))

package/lib/packaged.ts

@@ -0,0 +1,50 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Reads the compiled model this package ships in `data/geographic-model.json`.
+ */
+
+import { readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
+import { resolvePackagePath } from "@mailwoman/core/module/resolvers"
+import { resolvePath } from "path-ts"
+
+import { type CompiledGeographicModel, parseCompiledGeographicModel } from "#artifact"
+
+/**
+ * The authoring directory and the artifact it compiles to.
+ *
+ * Probes for `model/model.json`, so a genuinely missing `data/` throws naming the path.
+ */
+export async function packagedModelPaths(): Promise<{ source: string; artifact: string }> {
+	const candidates = [resolvePackagePath("@mailwoman/geographic-model", "data")]
+	const probes: Array<[string, boolean]> = []
+
+	for (const candidate of candidates) {
+		probes.push([candidate, await pathExists(resolvePath(candidate, "model/model.json"))])
+	}
+
+	const found = probes.find(([, exists]) => exists)?.[0]
+
+	if (!found) {
+		throw new Error(`geographic-model: could not find data/model — looked in ${candidates.join(", ")}`)
+	}
+
+	return { source: resolvePath(found, "model"), artifact: resolvePath(found, "geographic-model.json") }
+}
+
+/**
+ * Read the committed artifact.
+ *
+ * The reader checks the format version.
+ * It trusts the records because the loader validated them on input.
+ */
+export async function readCompiledGeographicModel(): Promise<CompiledGeographicModel> {
+	const text = await readLocalTextFile((await packagedModelPaths()).artifact)
+
+	// A corrupt committed artifact is a broken build and the `SyntaxError` names the offset.
+	// The package's parse wrappers live in `@mailwoman/core`, which this package deliberately does not depend on.
+	// oxlint-disable-next-line no-restricted-properties -- see the note above.
+	return parseCompiledGeographicModel(JSON.parse(text))
+}