@domorium/validator 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -2,6 +2,69 @@
 
 All notable changes to `@domorium/validator` are documented here.
 
+## 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`,
+  `HEBREW 1 TSH 5761`, `FRENCH_R 2 VEND 8` and even `GREGORIAN 1 JAN 2000` were
+  all reported as invalid, because only v5.5.1's `@#D…@` escape was understood.
+  Each calendar's own months and epochs now apply, so `HEBREW 1 JAN 5761` is
+  refused and `BCE` is confined to the two calendars that permit it. A calendar
+  binds to the date after it, so `FROM JULIAN 1670 TO GREGORIAN 1800` is two
+  dates in two calendars.
+- **Three v5.5.1 date forms are now refused inside a 7.0 document**, which may
+  make a file that was quiet noisy: the `@#D…@` calendar escape, a slashed year
+  such as `1 JAN 1857/58`, and the `INT 1950 (around 1950)` and `(unknown)`
+  phrase forms. Version 7.0 removed all three; a date phrase belongs in a
+  `PHRASE` substructure. GEDCOM 5.5.1 documents keep them.
+- Stop reporting a payload the specification allows to be omitted. A payload may
+  be left out whenever its data type admits the empty string, which covers 61 of
+  the 182 payload types — `1 EVEN` with only a `TYPE` beneath it was being
+  flagged. `AGE`, `DateValue` and `DatePeriod` have their own explicit
+  permission: omitting the payload and giving a `PHRASE` instead is the
+  specification's own way to record that something happened but not what.
+- Accept a leading UTF-8 byte order mark instead of reporting it as an
+  unexpected character. This was invisible in a browser, which strips the mark
+  while decoding, and affected anyone reading a file from disk.
+- Say what belongs in a pointer slot. `Value for SOUR should be POINTER` named
+  the rule rather than the problem; a payload that is not a pointer at all now
+  reads `should be a pointer to a SOUR record, written as "@xref@"`, while an
+  xref that resolves to nothing names the records it could have meant.
+
 ## 1.2.0 - 2026-08-07
 
 - Keep the spaces that belong to a value. The lexer treated the delimiter after

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                                              |