@domorium/validator 2.0.1 → 2.2.0

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to `@domorium/validator` are documented here.
 
+## 2.2.0
+
+- **The lexer's mode stack no longer grows with the document.** Each line left
+  one or two frames behind until the lex ended — 3.56 million on a 50 MB export,
+  an estimated tens of megabytes at peak. Every line now returns the lexer to
+  where it began, so the stack is at most two deep. The tokens are unchanged
+  (#80).
+- **`readDate` reads a date in a document checked against no dialect.** A file
+  whose header names no version, a Personal Ancestral File, or a version no
+  schema describes answered `null` for every date, so a consumer showing years
+  showed none for them. Such a document now reads a payload by the GEDCOM 5.5.1
+  grammar and, where that reads nothing, by the GEDCOM 7 one without `SCHMA`,
+  and answers `null` only where neither reads a possible date. Its diagnostics
+  are unchanged (#453).
+- **Year 0 in the Gregorian or Julian calendar is reported** with the new code
+  `VAL016` (`ImpossibleYear`), in both dialects, and `readDate` answers `null`
+  for it. GEDCOM 7 states that neither calendar has a year 0; 5.5.1 is held to
+  the same rule. The year is judged as the grammar reads it, so `0BC` counts and
+  an extension calendar does not (#453).
+- `GedcomDate.dualYear` documents that a date before the common era has none.
+
+## 2.1.0
+
+- **`readDate(payload)` answers what a date says, not only whether it is
+  valid.** A consumer wanting the year of a birth had to parse the payload
+  again, and a regular expression that finds `1401` in `1401 BCE` or a year in
+  `ABT HEBREW 5761` hands on a wrong year as a fact. The document now returns
+  the parse its diagnostics apply: the modifier, each date with its calendar,
+  day, month, year and epoch, a 5.5.1 phrase and dual year, and the text. It
+  reads in the document's dialect, resolves a `SCHMA` alias of a month or a
+  calendar, and answers `null` for whatever the diagnostics reject as a date
+  value, including a day its month does not have (#378).
+
 ## 2.0.1
 
 - **A 5.5.1 date names its calendar where the specification puts it.** 5.5.1

package/README.md

@@ -59,8 +59,58 @@ interface GedcomError {
 }
 ```
 
-`data` carries the facts a quick fix is built from — which xref failed to
-resolve, and what record tag it needed.
+| Field     | Type                             | What it holds                                                                                                     |
+| --------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `code`    | `string`, a `GedcomErrorCode`    | What kind of problem this is. Match on this.                                                                      |
+| `message` | `string`                         | Written for a person to read, and rewritten when a clearer wording is found. Do not match on it.                  |
+| `hint`    | `string?`                        | Declared for advice alongside the message. Nothing in this package sets it yet, so treat it as absent.            |
+| `data`    | object?                          | The structured facts a quick fix is built from, where the diagnostic has any.                                     |
+| `range`   | `Range`                          | Zero-based line and character, `end` exclusive, over the smallest text that is wrong — the payload, not the line. |
+| `level`   | `"error" \| "warning" \| "info"` | How much it matters.                                                                                              |
+
+`data` is what makes a fix offerable rather than merely reportable: an
+unresolved pointer reports the xref that failed and the record tag it needed, so
+a host can offer to create that record.
+
+For this file, where `SEX` carries a value its schema does not permit and `FAMC`
+points at a record that is not there:
+
+```gedcom
+0 HEAD
+1 GEDC
+2 VERS 7.0
+0 @I1@ INDI
+1 NAME Lisa /Simpson/
+1 SEX Q
+1 FAMC @F9@
+0 TRLR
+```
+
+`getErrors()` answers:
+
+```json
+[
+  {
+    "code": "VAL005",
+    "message": "Value for SEX should be in set [F, M, U, X]",
+    "range": {
+      "start": { "line": 5, "character": 6 },
+      "end": { "line": 5, "character": 7 }
+    },
+    "level": "error"
+  },
+  {
+    "code": "unresolved-xref",
+    "message": "No FAM record carries @F9@",
+    "data": { "xref": "@F9@", "requiredRecordTag": "FAM" },
+    "range": {
+      "start": { "line": 6, "character": 7 },
+      "end": { "line": 6, "character": 11 }
+    },
+    "level": "error"
+  }
+]
+```
 
 Match on `code` rather than on `message`; messages are written for people and
 change. `GedcomErrorCode` is exported for this:
@@ -90,11 +140,79 @@ const unresolved = errors.filter(
 | `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 |
+| `VAL016`          | `ImpossibleYear`        | a Gregorian or Julian date naming year 0, which neither calendar numbers       |
 | `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                                  |
 
+## Reading the tree
+
+`getNodes()` returns the records — the level-0 nodes — each holding its
+substructures in `children`. A node carries its line's tokens in a `tokens` map
+keyed by `TokenNames`, and which key holds the text is the thing to get right:
+
+| Token     | Written as    | Holds                                  |
+| --------- | ------------- | -------------------------------------- |
+| `LEVEL`   | `1`           | The level, as it was written.          |
+| `POINTER` | `0 @I1@ INDI` | The xref a record declares for itself. |
+| `TAG`     | `1 NAME`      | The tag.                               |
+| `XREF`    | `1 FAMC @F1@` | An xref a line points at.              |
+| `VALUE`   | `1 NAME Lisa` | A payload that is not a pointer.       |
+
+`POINTER` and `XREF` are the pair worth reading twice: a record's own xref is
+never in `XREF`, and a pointer payload is never in `VALUE`.
+
+Pulling every person's name out of a file:
+
+```typescript
+import { GedcomDocument, TokenNames } from "@domorium/validator";
+import type { ASTNode } from "@domorium/validator";
+
+const document = new GedcomDocument().createDocument(gedcomString);
+
+const payload = (node: ASTNode, tag: string): string | undefined =>
+  node.children.find((child) => child.tokens[TokenNames.TAG]?.value === tag)
+    ?.tokens[TokenNames.VALUE]?.value;
+
+for (const record of document.getNodes()) {
+  if (record.tokens[TokenNames.TAG]?.value !== "INDI") continue;
+  console.log({
+    xref: record.tokens[TokenNames.POINTER]?.value,
+    name: payload(record, "NAME"),
+    line: record.range.start.line,
+  });
+}
+```
+
+```text
+{ xref: '@I1@', name: 'Lisa /Simpson/', line: 3 }
+```
+
+`range` on a node or a token is computed from the offsets on every access, not
+stored: a large file has millions of tokens and a stored range costs three
+objects apiece. Read it freely at the edges, and use `startOffset` and
+`endOffset` inside a loop over the whole document.
+
+## What a document answers
+
+Every method reads the document last given to `createDocument`, which returns
+the same instance so the two can be chained.
+
+| Method                               | Answers                                                                                                                                                                                                            |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `createDocument(text, options?)`     | Parses and validates, and returns the document itself.                                                                                                                                                             |
+| `getErrors()`                        | Every diagnostic, in the order found.                                                                                                                                                                              |
+| `getNodes()`                         | The records, each with its substructures.                                                                                                                                                                          |
+| `getVersion()`                       | The version read from `HEAD`.`GEDC`.`VERS`, as written.                                                                                                                                                            |
+| `getDialect()`                       | Which rules were applied: `"5.5.1"` or `"7.0"`.                                                                                                                                                                    |
+| `getVersionResolution()`             | How that was decided — `supported`, `substituted`, `unsupported`, `undetermined`, or `paf` for a file whose header names a writing program before its version.                                                     |
+| `getLabel(node)`                     | The specification's name for a structure, for a UI to show instead of the tag: `HEAD` answers `Header`.                                                                                                            |
+| `getPointerTargetTag(node)`          | The record tag a pointer line must name: `FAMC` answers `FAM`.                                                                                                                                                     |
+| `isRecordDeclaration(node)`          | Whether the node declares a record other lines can point at.                                                                                                                                                       |
+| `getCompletions(position, lineText)` | What may be written at a position — `{ label, kind: "tag" \| "enum" \| "pointer", detail? }`.                                                                                                                      |
+| `readDate(payload)`                  | What a date payload says, read in the document's dialect — or `null` where the diagnostics would reject it as a date value. A document checked against no dialect reads by 5.5.1, then 7.0. See `GedcomDateValue`. |
+
 ## Scripts
 
 | Command             | Description                                              |

package/dist/document/gedcomDocument.d.ts

@@ -3,6 +3,7 @@ import { ASTNode } from "../parser";
 import { type GedcomDialect, type VersionResolution } from "../validator/versionRegistry";
 import { type GedcomCompletion } from "../completion/completion";
 import type { Position } from "../types/position";
+import type { GedcomDateValue } from "../types/date";
 export interface CreateDocumentOptions {
     /** Text that is part of a document rather than one of its own. */
     fragment?: boolean;
@@ -14,6 +15,7 @@ export declare class GedcomDocument {
     private pointers;
     private errors;
     private scheme;
+    private validatedAs;
     private resolution;
     private requiresSchmaDeclaration;
     private extensions;
@@ -28,6 +30,14 @@ export declare class GedcomDocument {
     getVersionResolution(): VersionResolution | undefined;
     getDialect(): GedcomDialect | undefined;
     getCompletions(position: Position, lineText: string): GedcomCompletion[];
+    /**
+     * Null wherever the document's own diagnostics would not call the payload a
+     * valid date value, and for one with nothing to read: an empty payload, or a
+     * 5.5.1 date in a calendar the schema gives no months. A document checked
+     * against no dialect reads by 5.5.1, then by 7.0 without its SCHMA, and is
+     * null only where neither reads a possible date.
+     */
+    readDate(value: string): GedcomDateValue | null;
     getErrors(): GedcomError[];
     getNodes(): ASTNode[];
 }