@mailwoman/geographic-model 9.3.0 → 10.0.0

package/lib/artifact.ts

@@ -93,7 +93,6 @@ export interface CompiledGeographicModel {
  * `String.prototype.localeCompare` is the trap this exists to avoid — its answer depends on the machine's collation, so
  * an artifact ordered with it is reproducible only on the machine that built it.
  */
-export { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
 
 /**
  * Rebuild `value` with every object's keys in code-point order, at every depth. Arrays keep their order — ordering

package/lib/compile.ts

@@ -31,12 +31,9 @@
  *   it total for any graph rather than for the graphs the validator happens to admit.
  */
 
-import {
-	ARTIFACT_SCHEMA_VERSION,
-	type CompiledGeographicModel,
-	compareIdentifiers,
-	type InheritanceClosureEntry,
-} from "#artifact"
+import { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
+
+import { ARTIFACT_SCHEMA_VERSION, type CompiledGeographicModel, type InheritanceClosureEntry } from "#artifact"
 import {
 	type ConceptID,
 	type ConceptRecord,
@@ -50,7 +47,6 @@ import {
 	toDerivedFactID,
 } from "#schema"
 import { parseGeographicModelDocument } from "#validate"
-
 /**
  * The name a fact derived by `isA` inheritance carries in its `derivation` field. A consumer branches on this rather
  * than on where the record sits.

package/lib/load.ts

@@ -26,11 +26,12 @@
  *   keys it uses are tables.
  */
 
-import { readDirectoryEntries, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { readLocalTextFile } from "@mailwoman/core/fs/readers"
 import { isPlainObject } from "@mailwoman/core/objects"
+import { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
 import { resolvePath } from "path-ts"
+import { Globerator } from "spliterator/node/fs"
 
-import { compareIdentifiers } from "#artifact"
 import type { GeographicModelDocument } from "#schema"
 import { validateGeographicModelDocument } from "#validate"
 import {
@@ -40,8 +41,7 @@ import {
 	readString,
 	type ValidationIssue,
 	ValidationIssueCode,
-} from "#validation-issues"
-
+} from "#validation/issues"
 /**
  * The manifest every model directory carries: the document's `version`, and nothing else.
  */
@@ -364,7 +364,12 @@ export function mergeGeographicModelFiles(files: readonly GeographicModelSourceF
  * a link out of it is a record whose home nobody can state.
  */
 async function listSourceFiles(root: string, prefix = ""): Promise<string[]> {
-	const entries = await readDirectoryEntries(resolvePath(root, prefix))
+	const entries = await Globerator.from("*", {
+		cwd: resolvePath(root, prefix),
+		withFileTypes: true,
+		onlyFiles: false,
+	}).toArray()
+
 	const found: string[] = []
 
 	for (const entry of entries.toSorted((left, right) => compareIdentifiers(left.name, right.name))) {

package/lib/lookup.ts

@@ -18,9 +18,10 @@
  *   concept it had never heard of.
  */
 
+import { compareByCodePoint as compareIdentifiers } from "@mailwoman/core/strings/compare"
 import type { POICategoryID } from "@mailwoman/poi-taxonomy/types"
 
-import { type CompiledGeographicModel, compareIdentifiers } from "#artifact"
+import type { CompiledGeographicModel } from "#artifact"
 import type {
 	ConceptID,
 	ConceptRecord,

package/lib/validate.ts

@@ -41,7 +41,6 @@ import {
 import {
 	add,
 	checkFieldNames,
-	listVocabulary,
 	readArray,
 	readBoolean,
 	readString,
@@ -50,9 +49,10 @@ import {
 	readVocabularyValue,
 	type ValidationIssue,
 	ValidationIssueCode,
-} from "#validation-issues"
+} from "#validation/issues"
+import { checkReferences } from "#validation/references"
 
-export { type ValidationIssue, ValidationIssueCode } from "#validation-issues"
+export { type ValidationIssue, ValidationIssueCode } from "#validation/issues"
 
 /**
  * The whole document, or every reason it is not one.
@@ -101,14 +101,14 @@ const DERIVATION_INPUT_FIELDS = ["kind", "id"] as const
  */
 const COUNTRY_PATTERN = /^[A-Z]{2}$/
 
-interface AssertionView {
+export interface AssertionView {
 	path: string
 	id?: string
 	relation?: string
 	target?: string
 }
 
-interface ConceptView {
+export interface ConceptView {
 	path: string
 	id?: string
 	kind?: ConceptKind
@@ -116,7 +116,7 @@ interface ConceptView {
 	assertions: AssertionView[]
 }
 
-interface RelationView {
+export interface RelationView {
 	path: string
 	id?: string
 	domainKinds?: ConceptKind[]
@@ -126,13 +126,13 @@ interface RelationView {
 	inverse?: string
 }
 
-interface MappingView {
+export interface MappingView {
 	path: string
 	id?: string
 	concept?: string
 }
 
-interface TripleView {
+export interface TripleView {
 	path: string
 	id?: string
 	subject?: string
@@ -140,17 +140,17 @@ interface TripleView {
 	object?: string
 }
 
-interface DerivationInputView {
+export interface DerivationInputView {
 	path: string
 	kind?: DerivationInputKind
 	id?: string
 }
 
-interface DerivedFactView extends TripleView {
+export interface DerivedFactView extends TripleView {
 	inputs: DerivationInputView[]
 }
 
-interface DocumentView {
+export interface DocumentView {
 	relations: RelationView[]
 	concepts: ConceptView[]
 	mappings: MappingView[]
@@ -158,7 +158,7 @@ interface DocumentView {
 	derivedFacts: DerivedFactView[]
 }
 
-interface ReferenceTables {
+export interface ReferenceTables {
 	concepts: Map<string, ConceptView>
 	relations: Map<string, RelationView>
 	assertions: ReadonlyMap<string, unknown>
@@ -424,353 +424,6 @@ function readTable<T>(
 	return records
 }
 
-/**
- * Index a table by identifier, reporting every record after the first that claims an identifier already taken. The
- * first claimant keeps the identifier, so a duplicate never silently displaces the record other rows resolve against.
- */
-function indexByID<T extends { path: string; id?: string }>(
-	issues: ValidationIssue[],
-	records: readonly T[],
-	label: string
-): Map<string, T> {
-	const index = new Map<string, T>()
-
-	for (const record of records) {
-		if (record.id === undefined) continue
-
-		if (index.has(record.id)) {
-			add(
-				issues,
-				`${record.path}.id`,
-				ValidationIssueCode.DuplicateID,
-				`\`${record.id}\` is already used by another ${label}`
-			)
-
-			continue
-		}
-
-		index.set(record.id, record)
-	}
-
-	return index
-}
-
-interface EdgeCheck {
-	subjectKind?: ConceptKind
-	subjectPath: string
-	relationID?: string
-	relationPath: string
-	objectID?: string
-	objectPath: string
-}
-
-/**
- * Resolve one subject–relation–object edge and check it against the relation's declared domain and range kinds.
- *
- * Shared by authored assertions, source observations, and derived facts. The three differ in who stands behind them and
- * in what provenance they carry, and the structural question asked of them is the same one.
- */
-function checkEdge(issues: ValidationIssue[], edge: EdgeCheck, tables: ReferenceTables): void {
-	const relation = edge.relationID === undefined ? undefined : tables.relations.get(edge.relationID)
-
-	if (edge.relationID !== undefined && !relation) {
-		add(
-			issues,
-			edge.relationPath,
-			ValidationIssueCode.UnknownRelation,
-			`\`${edge.relationID}\` is not a relation declared in this document`
-		)
-	}
-
-	const object = edge.objectID === undefined ? undefined : tables.concepts.get(edge.objectID)
-
-	if (edge.objectID !== undefined && !object) {
-		add(
-			issues,
-			edge.objectPath,
-			ValidationIssueCode.UnknownConcept,
-			`\`${edge.objectID}\` is not a concept declared in this document`
-		)
-	}
-
-	if (!relation) return
-
-	if (edge.subjectKind && relation.domainKinds && !relation.domainKinds.includes(edge.subjectKind)) {
-		add(
-			issues,
-			edge.subjectPath,
-			ValidationIssueCode.DomainKindMismatch,
-			`relation \`${relation.id}\` accepts ${listVocabulary(relation.domainKinds)} on the asserting side, not \`${edge.subjectKind}\``
-		)
-	}
-
-	if (object?.kind && relation.rangeKinds && !relation.rangeKinds.includes(object.kind)) {
-		add(
-			issues,
-			edge.objectPath,
-			ValidationIssueCode.RangeKindMismatch,
-			`relation \`${relation.id}\` accepts ${listVocabulary(relation.rangeKinds)} on the target side, not \`${object.kind}\``
-		)
-	}
-}
-
-function sameKinds(left: readonly ConceptKind[], right: readonly ConceptKind[]): boolean {
-	return left.length === right.length && left.every((kind) => right.includes(kind))
-}
-
-/**
- * Check one relation's inverse and its transitivity against the kinds it declares.
- */
-function checkRelation(
-	issues: ValidationIssue[],
-	relation: RelationView,
-	index: ReadonlyMap<string, RelationView>
-): void {
-	const inversePath = `${relation.path}.inverse`
-
-	if (relation.transitive === true && relation.domainKinds && relation.rangeKinds) {
-		const chainable = relation.rangeKinds.some((kind) => relation.domainKinds?.includes(kind))
-
-		if (!chainable) {
-			add(
-				issues,
-				`${relation.path}.transitive`,
-				ValidationIssueCode.TransitiveKindsDisjoint,
-				"a transitive relation has to be able to chain, so its range kinds and its domain kinds must overlap"
-			)
-		}
-	}
-
-	if (relation.inverse === undefined) return
-
-	const inverse = index.get(relation.inverse)
-
-	if (!inverse) {
-		add(
-			issues,
-			inversePath,
-			ValidationIssueCode.UnknownRelation,
-			`\`${relation.inverse}\` is not a relation declared in this document`
-		)
-
-		return
-	}
-
-	if (relation.symmetric === true && inverse.id !== relation.id) {
-		add(
-			issues,
-			inversePath,
-			ValidationIssueCode.InverseNotReciprocal,
-			`\`${relation.id}\` is symmetric, so it is its own inverse; it names \`${relation.inverse}\``
-		)
-
-		return
-	}
-
-	if (inverse.inverse !== relation.id) {
-		add(
-			issues,
-			inversePath,
-			ValidationIssueCode.InverseNotReciprocal,
-			`\`${relation.inverse}\` does not name \`${relation.id}\` as its own inverse`
-		)
-	}
-
-	if (
-		inverse.id !== relation.id &&
-		relation.domainKinds &&
-		relation.rangeKinds &&
-		inverse.domainKinds &&
-		inverse.rangeKinds &&
-		!(sameKinds(relation.domainKinds, inverse.rangeKinds) && sameKinds(relation.rangeKinds, inverse.domainKinds))
-	) {
-		add(
-			issues,
-			inversePath,
-			ValidationIssueCode.InverseKindsMismatch,
-			`an inverse reads the same edge backwards, so \`${relation.inverse}\` has to declare this relation's range kinds as its domain kinds, and the reverse`
-		)
-	}
-}
-
-/**
- * Follow `isA` upward from one concept and report the trail if it returns to where it started.
- *
- * The direct self-edge is left out of the walk: `checkIsA` already reports that as a self-reference, at the entry that
- * carries it, and a second report saying the same concept cycles through itself tells its author nothing new.
- */
-function findIsACycle(start: ConceptView, concepts: ReadonlyMap<string, ConceptView>): string[] | undefined {
-	if (start.id === undefined) return undefined
-
-	const startID = start.id
-	const visited = new Set<string>()
-
-	const frontier: Array<{ id: string; trail: string[] }> = (start.isA ?? [])
-		.filter((parent) => parent !== startID)
-		.map((parent) => ({ id: parent, trail: [startID, parent] }))
-
-	while (frontier.length) {
-		const step = frontier.pop()
-
-		if (!step) break
-
-		if (step.id === startID) return step.trail
-
-		if (visited.has(step.id)) continue
-
-		visited.add(step.id)
-
-		for (const parent of concepts.get(step.id)?.isA ?? []) {
-			frontier.push({ id: parent, trail: [...step.trail, parent] })
-		}
-	}
-
-	return undefined
-}
-
-function checkIsA(issues: ValidationIssue[], concept: ConceptView, concepts: ReadonlyMap<string, ConceptView>): void {
-	if (!concept.isA) return
-
-	for (const [index, parent] of concept.isA.entries()) {
-		const parentPath = `${concept.path}.isA[${index}]`
-
-		if (parent === concept.id) {
-			add(issues, parentPath, ValidationIssueCode.SelfReference, "a concept is not a kind of itself")
-
-			continue
-		}
-
-		if (!concepts.has(parent)) {
-			add(
-				issues,
-				parentPath,
-				ValidationIssueCode.UnknownConcept,
-				`\`${parent}\` is not a concept declared in this document`
-			)
-		}
-	}
-
-	const cycle = findIsACycle(concept, concepts)
-
-	if (cycle) {
-		add(issues, `${concept.path}.isA`, ValidationIssueCode.CyclicIsA, `\`isA\` cycles through ${cycle.join(" → ")}`)
-	}
-}
-
-function checkDerivationInputs(issues: ValidationIssue[], fact: DerivedFactView, tables: ReferenceTables): void {
-	const byKind: Record<DerivationInputKind, ReadonlyMap<string, unknown>> = {
-		[DerivationInputKind.Concept]: tables.concepts,
-		[DerivationInputKind.Relation]: tables.relations,
-		[DerivationInputKind.Assertion]: tables.assertions,
-		[DerivationInputKind.Mapping]: tables.mappings,
-		[DerivationInputKind.Observation]: tables.observations,
-		[DerivationInputKind.DerivedFact]: tables.derivedFacts,
-	}
-
-	for (const input of fact.inputs) {
-		if (input.kind === undefined || input.id === undefined) continue
-
-		if (input.kind === DerivationInputKind.DerivedFact && input.id === fact.id) {
-			add(issues, `${input.path}.id`, ValidationIssueCode.SelfReference, "a derived fact is not one of its own inputs")
-
-			continue
-		}
-
-		if (!byKind[input.kind].has(input.id)) {
-			add(
-				issues,
-				`${input.path}.id`,
-				ValidationIssueCode.UnknownDerivationInput,
-				`no \`${input.kind}\` record in this document is identified by \`${input.id}\``
-			)
-		}
-	}
-}
-
-function checkReferences(issues: ValidationIssue[], view: DocumentView): void {
-	const assertions: AssertionView[] = []
-
-	for (const concept of view.concepts) {
-		assertions.push(...concept.assertions)
-	}
-
-	const relations = indexByID(issues, view.relations, "relation")
-	const concepts = indexByID(issues, view.concepts, "concept")
-
-	const tables: ReferenceTables = {
-		relations,
-		concepts,
-		assertions: indexByID(issues, assertions, "assertion"),
-		mappings: indexByID(issues, view.mappings, "mapping"),
-		observations: indexByID(issues, view.observations, "observation"),
-		derivedFacts: indexByID(issues, view.derivedFacts, "derived fact"),
-	}
-
-	for (const relation of view.relations) {
-		checkRelation(issues, relation, relations)
-	}
-
-	for (const concept of view.concepts) {
-		checkIsA(issues, concept, concepts)
-
-		for (const assertion of concept.assertions) {
-			checkEdge(
-				issues,
-				{
-					subjectKind: concept.kind,
-					subjectPath: `${assertion.path}.relation`,
-					relationID: assertion.relation,
-					relationPath: `${assertion.path}.relation`,
-					objectID: assertion.target,
-					objectPath: `${assertion.path}.target`,
-				},
-				tables
-			)
-		}
-	}
-
-	for (const mapping of view.mappings) {
-		if (mapping.concept !== undefined && !concepts.has(mapping.concept)) {
-			add(
-				issues,
-				`${mapping.path}.concept`,
-				ValidationIssueCode.UnknownConcept,
-				`\`${mapping.concept}\` is not a concept declared in this document`
-			)
-		}
-	}
-
-	for (const triple of [...view.observations, ...view.derivedFacts]) {
-		const subject = triple.subject === undefined ? undefined : concepts.get(triple.subject)
-
-		if (triple.subject !== undefined && !subject) {
-			add(
-				issues,
-				`${triple.path}.subject`,
-				ValidationIssueCode.UnknownConcept,
-				`\`${triple.subject}\` is not a concept declared in this document`
-			)
-		}
-
-		checkEdge(
-			issues,
-			{
-				subjectKind: subject?.kind,
-				subjectPath: `${triple.path}.subject`,
-				relationID: triple.relation,
-				relationPath: `${triple.path}.relation`,
-				objectID: triple.object,
-				objectPath: `${triple.path}.object`,
-			},
-			tables
-		)
-	}
-
-	for (const fact of view.derivedFacts) {
-		checkDerivationInputs(issues, fact, tables)
-	}
-}
-
 function collectIssues(input: unknown): ValidationIssue[] {
 	const issues: ValidationIssue[] = []