@domorium/validator 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,82 @@
 
 All notable changes to `@domorium/validator` are documented here.
 
+## 1.5.0 - 2026-08-10
+
+- **The GEDCOM version is resolved against a table by longest match, and a
+  version we hold no schema for no longer validates against the newest one.**
+  `2 VERS 4.0`, a garbage version and a document with no `VERS` line were all
+  checked against GEDCOM 7 and reported clean, because nothing they were checked
+  against applied to them. Three codes replace that silence: `VAL011` for a
+  version no schema describes, `VAL012` for a document whose version cannot be
+  read, `VAL013` for one checked against another version's schema. The first two
+  suppress every schema-derived diagnostic, while lexing, tree assembly and
+  level validation still run — a 4.0 file with a level that cannot follow the
+  line above it still says so. `5.5`, `5.5.5` and `5.5 EL` are checked against
+  the 5.5.1 schema with a warning naming the substitution; `5.6`, `5.4`, `5.3`,
+  `5.0` and `4` are not, because the difference runs the wrong way and the
+  substitution would report false errors on correct lines.
+- **A structure the specification gives no substructures accepted any child.**
+  `getRules` answered `undefined` both for a leaf and for a type it could not
+  resolve, and the permissive reading of the two won: 57 structures in GEDCOM 7
+  and 89 in 5.5.1 accepted anything at all, `TRLR` among them in 5.5.1. So
+
+      0 @S1@ SOUR
+      1 TITL Open Archieven
+      2 BOGUS whatever
+
+  reported nothing. A child of a leaf structure is now an unknown tag.
+
+- `2 VERS  5.5.1`, with more than one space after the tag, selected the GEDCOM 7
+  schema and the file came back clean. The delimiter after a tag belongs to the
+  payload, so the version is trimmed before it selects anything. Present since
+  1.2.0.
+- The inline form of a 5.5.1 multimedia link was unreachable, so `1 OBJE` with
+  `FILE` and `TITL` written beneath it reported `FILE` as an unknown tag. Both
+  shapes now resolve. One type serves both, so a pointer carrying children and an
+  inline form with only a `TITL` are accepted where the specification allows
+  neither; telling them apart needs a schema that can offer two types for one
+  tag.
+- New on `GedcomDocument`: `getVersionResolution()` returns the outcome above
+  without parsing a message, and `getDialect()` names the version whose rules
+  apply — or nothing, for a version we cannot judge. `VersionResolution` and
+  `GedcomDialect` are exported alongside them.
+
+## 1.4.0 - 2026-08-09
+
+- Read a `HEAD.SCHMA` tag whose URI is a standard one as the structure it names.
+  A tag definition makes its tag an abbreviation for that URI, so a record
+  written under an alias now answers a pointer to the standard tag, a date in an
+  aliased calendar carries that calendar's months, and an aliased structure is
+  validated as the standard one — payload and substructures alike. Its position
+  is not checked: a relocated standard structure may only appear under a
+  superstructure the specification does not document it under.
+- Accept an extension tag as an enumeration value. Every one was reported as an
+  error, though the specification permits extending an enumeration with values
+  matching `extTag`. A value borrowed from another standard set, which the same
+  paragraph forbids, is still refused. An undocumented extension value reports
+  `VAL008`, as an undocumented tag already did.
+- Stop requiring a payload GEDCOM 5.5.1 does not define. `1 EVEN` with a `TYPE`
+  beneath it was reported as missing a value; the individual event structure
+  gives it no payload at all, and the family one spells it
+  `[<EVENT_DESCRIPTOR> | <NULL>]`.
+- **Reject a whole-number payload that is not a number.** `1 NCHI abc` was
+  accepted, and so were `3.7`, `12abc`, `1e3` and `Infinity`: the check compared
+  `parseInt(value) < 0`, and `NaN` fails every comparison.
+- An event with neither a payload nor substructures is a warning, `VAL010`,
+  rather than an error reading "should be Y or null" — null is what it had, and
+  the payload is optional. It is not silent either: 5.5.1 introduces the `Y`
+  convention precisely to protect against processors that prune lines having
+  neither a value nor a subordinate line.
+- A pointer whose target record type appears nowhere in the document no longer
+  reads `should be in set []`.
+- **Each kind of problem now has its own code.** Every payload problem shipped as
+  the bare string `VAL`, so a consumer could not tell a missing value from a
+  malformed one, and `VAL003` to `VAL006` sat declared and unused. See the code
+  table in the README. `unresolved-xref` and `invalid-level` keep their strings.
+- Export `GedcomError`, `GedcomErrorCode`, `Range` and `Position`. `getErrors()`
+  returns `GedcomError[]` and the type could not be named by a consumer.
+
 ## 1.3.0 - 2026-08-08
 
 - Read GEDCOM 7 dates against the calendar they name. `JULIAN 1401`,

package/README.md

@@ -25,6 +25,54 @@ const document = new GedcomDocument().createDocument(gedcomString);
 const errors = document.getErrors();
 ```
 
+## Diagnostics
+
+`getErrors()` returns `GedcomError[]`:
+
+```typescript
+import type { GedcomError, Position, Range } from "@domorium/validator";
+
+interface GedcomError {
+  code: string;
+  message: string;
+  hint?: string;
+  data?: { xref?: string; requiredRecordTag?: string; expectedLevel?: number };
+  range: Range;
+  level: "error" | "warning" | "info";
+}
+```
+
+`data` carries the facts a quick fix is built from — which xref failed to
+resolve, and what record tag it needed.
+
+Match on `code` rather than on `message`; messages are written for people and
+change. `GedcomErrorCode` is exported for this:
+
+```typescript
+import { GedcomErrorCode } from "@domorium/validator";
+
+const unresolved = errors.filter(
+  (error) => error.code === GedcomErrorCode.UnresolvedXref,
+);
+```
+
+| Code              | Member                 | Reported when                                               |
+| ----------------- | ---------------------- | ----------------------------------------------------------- |
+| `VAL001`          | `UnknownTag`           | a tag the schema does not define in this position           |
+| `VAL002`          | `MissingTag`           | a structure the schema requires is absent                   |
+| `VAL003`          | `MissingValue`         | the payload is absent where one is required                 |
+| `VAL004`          | `IncorrectValue`       | the payload does not match its data type                    |
+| `VAL005`          | `ShouldBeSetValue`     | the payload is not one of the permitted values              |
+| `VAL006`          | `MissingRef`           | a pointer payload that is not written as a pointer          |
+| `VAL007`          | `ManyOccurrences`      | more occurrences than the cardinality allows                |
+| `VAL008`          | `UndocumentedTag`      | a GEDCOM 7 extension tag with no `HEAD`.`SCHMA` declaration |
+| `VAL009`          | `DuplicateDeclaration` | a tag declared more than once in `HEAD`.`SCHMA`             |
+| `VAL010`          | `EmptyEvent`           | an event with neither a payload nor substructures           |
+| `unresolved-xref` | `UnresolvedXref`       | an xref naming no record of the required type               |
+| `invalid-level`   | `InvalidLevel`         | a level that cannot follow the line above it                |
+| `LEXER`           | `Lexer`                | the text could not be tokenized                             |
+| `PARSER`          | `Parser`               | the tokens could not be assembled into a tree               |
+
 ## Scripts
 
 | Command             | Description                                              |

package/dist/document/gedcomDocument.d.ts

@@ -1,5 +1,6 @@
 import { GedcomError } from "../types/errors";
 import { ASTNode, ASTToken } from "../parser";
+import { type GedcomDialect, type VersionResolution } from "../validator/versionRegistry";
 import { type GedcomCompletion } from "../completion/completion";
 import type { Position } from "../types/position";
 export declare class GedcomDocument {
@@ -8,6 +9,8 @@ export declare class GedcomDocument {
     xRefs: Map<string, ASTToken[]>;
     private errors;
     private scheme;
+    private resolution;
+    private requiresSchmaDeclaration;
     private extensions;
     private parseGedcom;
     createDocument(text: string): GedcomDocument;
@@ -16,6 +19,8 @@ export declare class GedcomDocument {
     getPointerTargetTag(node: ASTNode): string | undefined;
     isRecordDeclaration(node: ASTNode): boolean;
     getVersion(): string | undefined;
+    getVersionResolution(): VersionResolution | undefined;
+    getDialect(): GedcomDialect | undefined;
     getCompletions(position: Position, lineText: string): GedcomCompletion[];
     updateDocument(_text: string, _range: Range): GedcomDocument;
     getErrors(_lang?: string): GedcomError[];