@domorium/validator 1.8.1 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,193 @@
 
 All notable changes to `@domorium/validator` are documented here.
 
+## 2.0.0 - 2026-08-20
+
+Removes three members of `GedcomDocument` that no consumer read, which is what
+makes this a major: `updateDocument`, which returned `this` and did nothing;
+`xRefs`, a parse product nothing outside the package looked at; and the public
+`pointers`, now private because writing to it poisoned the pointer-target cache
+keyed on it. `getErrors` and `getNodes` lose parameters they never read — a
+change to their types only, since JavaScript discards a surplus argument.
+
+- **A 5.5.1 multimedia format is read without regard to case.** `2 FORM JPG` was
+  reported against a set the specification writes in lower case, so a file holding
+  the right value in the wrong spelling read as one holding a format 5.5.1 does not
+  have — and `FORM` is required under every `OBJE`.`FILE`, so an export writing
+  extensions in upper case earned an error per photograph. That set is now compared
+  without regard to case; `png` and `pdf`, which the specification has no spelling
+  for, are still reported. The LDS status sets, which 5.5.1 writes in upper case,
+  are unchanged: the case matters differently per set, so the set is named rather
+  than the comparison.
+- **A tag typed in lower case is completed.** The lexer reads `1 sex` as the SEX
+  tag and the validator names the mistake — a tag is written in upper case, SEX —
+  but completion, which is the way out of it, matched upper case only: `1 se`
+  offered nothing where `1 SE` offered 62 tags, and a payload typed after `1 sex`
+  was offered nothing where after `1 SEX` it was offered the four values of the
+  enumeration. The typed tag is now read as the lexer reads it, and the schema is
+  asked about the tag it names rather than about the letters as they were typed.
+- **A completion on a large document is answered in under a millisecond.** Every
+  request rebuilt the flattened node array and then filtered it, so a 300k-line
+  file paid 69 ms per keystroke — for a tree the last parse built and nothing has
+  touched since, where parsing and validating that whole file takes 492 ms once.
+  The walk is now cached against the array a parse replaces, and the line the
+  cursor sits on is found by halving the nodes rather than by reading the range of
+  every one before it: 6 ms for the first completion after a parse, 0.1 ms for
+  each one after that.
+- **A second `createDocument` on one instance answers for the file it was given.**
+  A header naming a system before `GEDC`, a version no schema describes, and a
+  header naming no version at all each return before a schema is chosen, and the
+  schema, the extension tags and the GEDCOM 7 flag of the document read before
+  them stayed where they were: an instance that had read a 7.0 file offered
+  `SCHMA` while completing the header of a Personal Ancestral File, and labelled
+  a tag with a URI declared by a `HEAD`.`SCHMA` in another file. Parsing now
+  clears all three, so every call answers for its own text.
+- **`GedcomDocument` no longer carries members nothing reads.** `updateDocument`
+  returned `this` and did nothing; `getErrors` took a language it never read and
+  `getNodes` a range it never read — and that `Range` was the DOM's, ambient
+  because the package pinned no `lib`, so `getNodes(new Range())` compiled in a
+  package that must also run in Node. `pointers` and `xRefs` were mutable parse
+  products no consumer outside the package read, and assigning to `pointers`
+  poisoned the pointer-target cache keyed on it. `getErrors()` and `getNodes()`
+  take no arguments, `pointers` is private and `updateDocument` and `xRefs` are
+  gone; the package compiles against `ES2023` alone, so a DOM global cannot be
+  named by accident again.
+- **A 5.5.1 multimedia format and the four LDS ordinance statuses are read against
+  the value sets the specification spells out.** `3 FORM exe` beneath a FILE, and
+  `2 STAT nonsense` beneath BAPL, CONL, ENDL, SLGC or SLGS, were accepted: 5.5.1
+  states these closed sets in its primitive definitions rather than in an
+  enumeration vocabulary, so the scheme recorded only a type URI and the payload
+  was checked for one thing, that it was not empty. A multimedia FORM is now one
+  of `[bmp, gif, jpg, ole, pcx, tif, wav]` — 5.5 spelled two of those `jpeg` and
+  `tiff` — and each ordinance status one of the seven or eight the specification
+  lists for it. Their values are upper case where `PEDI` and `RESN` are lower, and
+  a file that mixes the two is now told so. Completion offers these values as well.
+- **A payload type the validator does not describe is left alone, rather than
+  required to be a non-empty string.** Every payload type either schema declares is
+  now named, and a test over both says so. A type new to an upstream release used to
+  reach the same check as free text and report a missing value on every structure
+  that legitimately omits it; it now fails that test instead, where a person can see
+  it.
+- **A 5.5.1 date is read against the calendar its escape names, and completion
+  offers one.** The twelve month tags lived in four places — the 5.5.1 date grammar,
+  the day-length table, the 7.0 `calendar` section and the completion reader's own
+  list — and 5.5.1, whose `calendar` section was empty, could use none of them. That
+  section now describes all six calendars 5.5.1 names, `validator/calendars.ts` is
+  the only reader of it, and the lengths stay in code with a test binding them to the
+  months both schemes name. `@#DHEBREW@ 45 XXX 5760` is reported rather than waved
+  through on a non-empty check, `@#DJULIAN@ 12 JAN 2000` is checked as a date rather
+  than accepted for being non-empty, and a date under `@#DROMAN@` or `@#DUNKNOWN@` —
+  calendars 5.5.1 names and gives no month — is still accepted, because an empty
+  month table says nothing rather than forbidding everything. Completion in a 5.5.1
+  file went from 8 candidates with the cursor after `2 DATE` to 26, the escapes and
+  the Gregorian months joining the modifiers; from none after `2 DATE 12` to 14; and
+  from none after `2 DATE 12 JAN 2000` to the two epoch spellings 5.5.1 writes.
+  Neither conformance corpus moved: 8 diagnostics over 23 official files, 14 795
+  over 14 vendor exports. See docs/adr/0012.
+
+- **A document with more than about 125k diagnostics reports all of them instead of
+  none.** Diagnostics were gathered by spreading each level's array into its
+  parent's `push`, and a spread is one argument per element: V8 refuses somewhere
+  past 125k, so `createDocument` threw a `RangeError` for exceeding the call stack
+  and the caller got an exception where it had asked a question — not a truncated
+  list, none. A file of 130 000 records each carrying one tag the schema does not
+  define there now reports its 130 000 warnings. One array is carried down the walk
+  and pushed into, so nothing is capped and no array is allocated per node.
+- **A line below one carrying a pointer but no tag answers nothing instead of
+  throwing.** `0 @I1@`, what a truncated export leaves behind, still becomes a node
+  and adopts the lines indented under it, so the walk from a node to the root met a
+  step with no tag and threw `TypeError: Cannot read properties of undefined`. Asking
+  for the type, the label or the pointer target of such a node — hovering
+  `1 NAME John /Doe/` is one way in — now gives the same empty answer already given
+  for a path the schema does not resolve.
+- **A year followed by an extension epoch is a date.** `2 DATE 2000 _MYEPOCH` was
+  reported as an invalid date value. An extension tag is admissible as a month and
+  as an epoch alike, and the reader took the pair for a day and a month — leaving
+  the date with no year, which every date must have. A month is now read only when
+  the year it must precede follows it, so the epoch reading is the one left. The
+  same value under an extension calendar, `2 DATE _MYCAL 1900 _MYEPOCH`, was
+  rejected for the same reason and is now read too.
+
+- **An unresolved pointer names the xref that failed, and lists nothing.** A `FAMC`
+  pointing at a family the file does not declare was reported as "Value for FAMC
+  should be in set [@F70@, @F75@, … 2853 more]" — the vocabulary of a closed set,
+  spent on ten families that were not the problem, ending in an admission that it
+  gave up. A pointer's set is the population of the document, so the diagnostic now
+  states the fact about the line: "No FAM record carries @F1450@". An enumeration
+  still lists its values, because for `SEX` the four of them are the whole answer.
+  Where the payload is not a pointer at all the message is unchanged — there the
+  shape is what is wrong, not the identifier.
+
+## 1.8.2 - 2026-08-18
+
+- **A tag written in mixed case is read as written, and the message says which tag
+  is meant.** `1 NoTe hello` was reported as "Unknown tag N" — the tag pattern held
+  upper case only, so it matched as far as `N` and `oTe hello` became the value, and
+  the reader was told about a tag that is nowhere in their file. The tag is now read
+  whole and the message says a tag is written in upper case, naming `NOTE`. Where
+  case is not the problem, `1 NOTEE` still reads as an unknown tag.
+- **A line carrying no level is reported once.** The parser says a GEDCOM line must
+  begin with a level, and the validator no longer adds its own word about the tag of
+  a line that is not a line.
+
+- **A tag declared twice in `HEAD.SCHMA` with different URIs is no longer reported.**
+  The specification permits it — "the schema structure may contain the same tag more
+  than once with different URIs" — and its own `extensions.ged` declares `_PARTY`
+  twice, once for a substructure and once for a record. The check now asks whether
+  the same tag was declared twice with the _same_ URI, which says nothing the first
+  declaration did not. Which of several URIs applies where a tag is used is a
+  separate question.
+
+- **A line the lexer cannot read is reported once, in words about GEDCOM.** An xref
+  with a space in it — `0 @NoTe ref@ NOTE …` — produced "unexpected character:
+  ->@<- at offset: 199, skipped 1 characters", which is true of the scanner and no
+  use to a reader. The lexer then resumed one character on, so the wreckage lexed
+  into a tag `N` and a value, and the line was reported a second time as an unknown
+  tag that is nowhere in the file. Such a line now yields one diagnostic, saying an
+  xref holds letters, digits and underscore between two @ marks, and its tokens are
+  dropped rather than read as something else. The lines around it are untouched.
+- **An unknown tag at the top level says `root`** where it said `undefined`. The
+  message about a missing tag has said `root` all along.
+- **A file whose lines end in CR is read as a file, not as one line.** 5.5.1 ends a
+  line with CR, LF, CR-LF or LF-CR; the lexer's terminator was `\r?\n` and the line
+  index counted only LF, so a CR-only document parsed to a single node, its version
+  was never found, and everything above the lexer worked from one line. All four
+  terminators now end a line, a two-character form counts as one, and positions come
+  out the same whichever is used.
+
+- **A required tag missing from a childless parent is reported where it is
+  missing.** The position came from the parent of the first child, so a parent with
+  no children at all had no position to offer and the report landed on line 1. In a
+  105 707-line export that put ten `Missing required tag FORM in FILE` diagnostics
+  at the top of the document, a hundred thousand lines from the media references
+  they describe.
+- **Six closed value sets in 5.5.1 are checked at last.** `QUAY 9`, `PEDI nonsense`,
+  `RESN whatever`, `ORDI maybe`, `STAT nonsense` under `FAMC` and `ADOP nonsense`
+  under `INDI.ADOP.FAMC` all passed, because 5.5.1 states these sets in its
+  primitive definitions rather than in an enumeration vocabulary, and a payload
+  type the field-type switch did not name was validated as free text. Each now
+  names its set in the scheme and is judged by the rule that already existed for
+  GEDCOM 7 enumerations. Every real export in the corpus already wrote these
+  correctly, so nothing new is reported there. Completion offers the same values
+  while one is typed, because it reads the same sets: a `PEDI` line in a 5.5.1
+  file now proposes `adopted`, `birth`, `foster` and `sealing`.
+- **A BC year in a 5.5.1 file is read in the spellings exports write.** `1472 B.C.`
+  passed while `1472 BC`, `1472BC` and `1472B.C.` were reported, though `YEAR_GREG`
+  carries no epoch at all and the specification only says in prose that "(B.C.)"
+  appended to the year marks a date before the common era — pinning neither the
+  spelling nor the delimiter. Every spelling now reads as the same era, in the
+  validity check and in the leap-year rule alike, so `29 FEB 1000 BC` is no longer
+  judged by whether 1000 was a leap year. Free text stays reported: `609 BC Megiddo`
+  and `abt. 716 BC (or 725)` belong in `DATE_PHRASE` parentheses. GEDCOM 7 is
+  unchanged, where `epoch = %s"BCE"` says exactly what is allowed.
+- **An age in a 5.5.1 file is no longer judged by GEDCOM 7's grammar.** `AGE <8y`
+  was reported while `AGE < 8y` passed, and `8Y` and `child` were reported while
+  `8y` and `CHILD` passed. One expression served both versions, and it was
+  written to v7's ABNF, where the delimiter after `<` or `>` is required and
+  `years = Integer %x79` pins the unit letter. 5.5.1 prints neither rule, and
+  real exports write both forms, so 5.5.1 ages are now read without a required
+  delimiter and without regard to case. v7 keeps its ABNF exactly.
+
 ## 1.8.1 - 2026-08-17
 
 - **A note written as text in a 5.5.1 file is no longer reported.** `1 NOTE plain

package/README.md

@@ -73,22 +73,27 @@ const unresolved = errors.filter(
 );
 ```
 
-| 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               |
+| 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                              |
+| `VAL011`          | `UnsupportedVersion`    | the version is one no schema in this package describes                         |
+| `VAL012`          | `UndeterminedVersion`   | no version could be read from `HEAD`.`GEDC`.`VERS`                             |
+| `VAL013`          | `SubstitutedVersion`    | a version checked against a different version's schema                         |
+| `VAL014`          | `ImpossibleDay`         | a date naming a day its calendar does not have, such as `31 FEB`               |
+| `VAL015`          | `PersonalAncestralFile` | a header naming `SYST` before `GEDC`, so the file is a Personal Ancestral File |
+| `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
 

package/dist/completion/dateSlot.d.ts

@@ -3,6 +3,7 @@
  * nothing here: the months worth offering depend on the calendar named a few
  * tokens earlier, and the keywords depend on what the value opened with.
  */
+import { GedcomScheme } from "../schemes/schema-types";
 export type DateGrammar = "value" | "period" | "exact";
 export interface DateSlot {
     /** A calendar may be named here. */
@@ -14,4 +15,4 @@ export interface DateSlot {
     /** Bare words the grammar allows here. */
     keywords: string[];
 }
-export declare function dateSlot(typed: string, grammar: DateGrammar): DateSlot;
+export declare function dateSlot(scheme: GedcomScheme, typed: string, grammar: DateGrammar): DateSlot;

package/dist/document/gedcomDocument.d.ts

@@ -1,5 +1,5 @@
 import { GedcomError } from "../types/errors";
-import { ASTNode, ASTToken } from "../parser";
+import { ASTNode } from "../parser";
 import { type GedcomDialect, type VersionResolution } from "../validator/versionRegistry";
 import { type GedcomCompletion } from "../completion/completion";
 import type { Position } from "../types/position";
@@ -11,8 +11,7 @@ export interface CreateDocumentOptions {
 }
 export declare class GedcomDocument {
     private nodes;
-    pointers: Map<string, ASTNode[]>;
-    xRefs: Map<string, ASTToken[]>;
+    private pointers;
     private errors;
     private scheme;
     private resolution;
@@ -29,7 +28,6 @@ export declare class GedcomDocument {
     getVersionResolution(): VersionResolution | undefined;
     getDialect(): GedcomDialect | undefined;
     getCompletions(position: Position, lineText: string): GedcomCompletion[];
-    updateDocument(_text: string, _range: Range): GedcomDocument;
-    getErrors(_lang?: string): GedcomError[];
-    getNodes(_range?: Range): ASTNode[];
+    getErrors(): GedcomError[];
+    getNodes(): ASTNode[];
 }