gedcom-ts 2.0.2 → 2026.5.0

package/CHANGELOG.md

@@ -2,6 +2,181 @@
 
 All notable changes of gedcom-ts
 
+## [Unreleased]
+
+## [2026.5.0] - 2026-05-15
+
+### Versioning
+
+À partir de cette release, le numéro de version du paquet npm et de **`GEDCOM_LIBRARY_VERSION`** (`src/version.ts`, exporté dans `HEAD`.`SOUR`.`VERS`) suit un schéma **CalVer** :
+
+- format **`AAAA.M.micro`** (ex. **`2026.5.0`** = mai 2026, première publication de la série) ;
+- remplace l’ancien **semver** (`2.1.0`, `2.0.x`, …) pour les releases applicatives ;
+- la propriété `version` de `package.json` et `GEDCOM_LIBRARY_VERSION` doivent rester **identiques** (vérifié par `tests/version-package-sync.spec.ts`) ;
+- les branches de release peuvent porter le même libellé (ex. `2026.5.0`).
+
+Les entrées historiques du changelog conservent leurs numéros semver d’origine.
+
+### Highlights
+
+- Nouvelle couche **`src/dataset/`** : mutations du graphe `ReadGed`, opérations famille, validation typée, commandes sûres (`try*` / `CommandResult`) et clones.
+- Extension majeure de la **couche d’édition** (`*Edit`, factories, médias, variants de nom, attributs, options d’export).
+- **Round-trip des notes sous actes** corrigé (import `2 NOTE` / `3 CONT` après `DATE`, ordre d’export `ActLine`).
+- Refactor interne : médias centralisés, buffer des enregistrements préservés, `Person.clone` / `Act.clone`.
+
+### Added
+
+#### Dataset (`src/dataset/`)
+
+- **`readGedMutations`** : `addPersonToReadGed`, `removePersonFromReadGedByIndi` (mise à jour `mapPersons`, `persons`, lieux, `groupPartners`).
+- **`ReadGedEdit`** / `editReadGed` : `addPerson`, `removePersonByIndi`, `preserved()` → `PreservedTopLevelEdit` (`append`, `insertAt`, `replaceAt`, `removeAt`, `clear`).
+- **`graphOps`** : `nextFamilyId`, `createMarriageFamily`, `linkChildToFamily`, `unlinkChildFromFamily`, `removeFamilyReferencesFromDataset`.
+- **`CreateUnionFamilyOptions`** : `eventTag` sur `createMarriageFamily` / `tryCreateMarriageFamily` (défaut `MARR` ; aussi `ENGA`, `MARB`, `MARC`, `MARL`, `MARS`, `EVEN` + `CreateActInit`, etc.) ; constante **`GEDCOM_7_PAIR_UNION_EVENT_TAGS`**.
+- **`readGedCommands`** : `tryAddPersonToReadGed`, `tryRemovePersonFromReadGedByIndi`, `tryLinkChildToFamily`, `tryUnlinkChildFromFamily`, `tryCreateMarriageFamily` ; `validate*Command` ; **`CommandResult`** / `commandBlockingIssues`.
+- **`validation`** : `ModelConsistencyIssue` avec `code`, `severity` (`error` | `warn`), `validatePerson` / `validateReadGed` ; options `checkMarrParticipants`, `checkDuplicateIndis`, `checkFamcWithoutSpouses`, `checkFamsWithoutSpouses`, `checkDuplicateFamsEntries`, `checkAncestorCycles` ; `assertPersonConsistent` / `assertReadGedConsistent` avec `failOn`.
+- **`cloneModels`** : `clonePerson`, `cloneAct` (délèguent à `Person.clone` / `Act.clone`).
+
+#### Import / modèle
+
+- **`PreservedRecordsBuffer`** : encapsulation des blocs `0 …` préservés (`SplitGedcom` / `ReadGed.preservedTopLevelRecords`).
+- **`ReadGed.rehydratePlacesFromActs()`** : reconstruction de `placesMap` après édition manuelle du graphe.
+- **`importGedcomNote`** : `createNoteFromGedcomPayload`, `appendGedcomNoteSubline`, `isPersonLevelGedcomLine`, `isActLevelGedcomNoteLine`, `isGedcomNoteContinuationTag`.
+- **`registerTrackedMedia`** : chemins relatifs uniques pour médias personne / acte.
+- **`uriBasename`** : nom de fichier logique depuis une URI média.
+- **`clonePrimitives`** : briques de copie profonde partagées (dates, lieux, notes, médias, variants, attributs).
+- **`Person.clone(newIndi)`**, **`Act.clone()`** sur les classes domaine.
+
+#### Fluent edit layer (extensions)
+
+- **`factories`** : `createAct`, `createNote`, `createPersonStub`, `createPersonNameVariant`, `createIndiAttribute` (+ types `CreateActInit`, `CreatePersonStubInit`).
+- **`NoteEdit`** / `editNote` ; **`NotesEdit`** : `addNew`, `insertNewAt`, `removeNote`, `indexOfNote`.
+- **`ActMediaEdit`** / **`PersonMediaEdit`** / **`MultimediaFileEdit`** ; **`NameVariantsEdit`** / **`PersonNameVariantEdit`** ; **`IndiAttributesEdit`**.
+- **`ActsEdit`** : `addNew`, `insertNewAt`, `removeAct`, `indexOfAct`.
+- **`ActEdit`** : `notes()`, `multimedia()`, `clearNotes`, `clearMultimedia`.
+- **`PersonEdit`** : `multimedia()`, `nameVariants()`, `attributes()`, `appendFams`, `removeFamsAt`, `removeFamsById`, etc.
+- **`GedcomExportOptionsEdit`** / `editGedcomExportOptions` : `setExtraTopLevelRecords`, `setHeadCopyright`, `setHeadDestination`, `setHeadLanguageTag`, `setHeadSchemaTagDefs`, `clear*`.
+
+#### Public API (`src/index.ts`)
+
+- Réexport de tout le dataset, des commandes `try*`, des types de validation, `GEDCOM_7_PAIR_UNION_EVENT_TAGS`, `Gedcom7PairUnionEventTag`, `CreateUnionFamilyOptions`, `CommandResult`, etc.
+
+#### Tests
+
+- `tests/dataset/readGedCommands.spec.ts` : commandes et validations FAM optionnelles.
+- `tests/edit/extendedLayer.spec.ts` : ReadGed, graphe, export options, clones, validation, `removeFamilyReferencesFromDataset`.
+- `tests/edit/editApi.spec.ts` : facades étendues.
+- `tests/commons/Person.spec.ts` / `Act.spec.ts` : notes d’acte (`2 NOTE` / `3 CONT`, ordre après `DATE`).
+- `tests/export/GEDCOM.spec.ts` : round-trip ZIP avec note multi-lignes sous acte.
+- `tests/utils/uriBasename.spec.ts`.
+
+#### Documentation
+
+- README : section **Dataset editing** (ReadGed, graphe, clones, validation, commandes) ; table `ReadGed` mise à jour (`rehydratePlacesFromActs`, plus de `addPerson` direct sur `ReadGed`).
+
+### Changed
+
+- **`ReadGed`** : `addPerson` / `removePersonByIndi` retirés de la classe ; préférer `editReadGed` ou `addPersonToReadGed` / `removePersonFromReadGedByIndi`.
+- **`Person.addMultimedia` / `addMultimediaFromUri`** et **`Act.addMultimedia` / `addMultimediaFromUri`** : délégation à `registerTrackedMedia`.
+- **`SplitGedcom`** : liste préservée via `PreservedRecordsBuffer` au lieu d’un tableau interne brut.
+- **`package.json`** / **`package-lock.json`** : version **`2026.5.0`** (CalVer).
+- CI (`.gitlab-ci.yml`) : ajustements mineurs liés à la release.
+
+### Fixed
+
+- **Notes d’acte au réimport** : `parsePersonLine` n’attache plus les `NOTE` de niveau 2 au individu ; `convertToActs` traite `2 NOTE` et `3 CONC`/`CONT` **avant** les blocs `pendingAfterDate` / `Plac` / `Sdate`, ce qui évite de perdre les `3 CONT` lorsque l’export place la note après `DATE` (`ActLine`).
+- **`ReadGedEdit.addPerson`** : discrimination TypeScript correcte sur `CommandResult` (`r.ok === false`).
+- Alignement **`GEDCOM_LIBRARY_VERSION`** ↔ **`package.json`** pour la série `2026.5.0`.
+
+## [2.1.0] - 2026-05-13
+
+### Highlights
+
+- Major GEDCOM 7 coverage push: round-trip preservation (`preservedTopLevelRecords`, label-keyed FAM / NOTE xrefs, level-0 `OBJE`), richer `HEAD` export options, full P1.4 dates and places (INT/EST/CAL, `3 PHRASE`, `3 TIME`, `2 SDATE`, `2 PHRASE` event-level, ISO date input, verbatim fallback).
+- New **fluent edit layer** (`editPerson`, `editAct`, `editActs`, `editDateAct`, `editPlace`, `editNotes` + `*Edit` classes) for in-place model mutations with chainable APIs.
+- **README fully rewritten** with a complete public-API reference and a link to the live graphical demo at **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Added
+
+#### Import
+
+- `ReadGed.preservedTopLevelRecords`: top-level `0 …` GEDCOM records that are not loaded into the typed model (e.g. `REPO`, `SOUR`, `SUBM`, and undecodable `OBJE`) are preserved in file order. `0 TRLR` is not stored.
+- **FAM / `@N` xrefs non numériques** : enregistrements `0 @F…@ FAM` et `0 @N…@ NOTE|SNOTE` indexés par libellé puis mappés vers des ids internes numériques (comme pour les `INDI` textuels) ; `FAMS` / `FAMC` / notes résolus via tables de pointeurs.
+- **OBJE de niveau 0** : si le bloc contient un `FILE` exploitable, il est retiré de `preservedTopLevelRecords` et sert à hydrater `MultimediaFile.sourceUri` pour les pointeurs `1 OBJE` / `2 OBJE` (`PersonGedcomImportOptions` / résolution interne dans `ReadGed`).
+- **Import actes (FAM)** : `1 HUSB` / `1 WIFE` avec pointeur `@I{n}@` **ou** xref textuelle `@Libellé@` (même clé que `0 @Libellé@ INDI`) alimentent les participants des actes extraits (`extractActEntriesAndIndis`).
+- `ReadGed.resolveIndividualPointer(raw)`, `ReadGed.getChildrenForParent(parent)`, `ReadGed.getChildrenOfFamily(familyId)` exposés publiquement pour naviguer le graphe importé.
+
+#### Export
+
+- `GedcomExportOptions` enrichies : `extraTopLevelRecords` (round-trip), `headLanguageTag`, **`headCopyright`** (`1 COPR`), **`headDestination`** (`1 DEST`), **`headSchemaTagDefs`** (`HEAD`.`SCHMA` / `2 TAG …`).
+- `HEAD`.`SOUR` structuré : émission de **`2 VERS`** + **`2 NAME`** sous `SOUR`, en plus du `CHAR` / `LANG` standard.
+- Constante **`GEDCOM_LIBRARY_VERSION`** (`src/version.ts`, alignée sur `package.json` via test) utilisée pour `2 VERS` à l’export.
+- **FAM** : sexes U / X / indéfini sont exportés en **`1 HUSB`** (placeholder GEDCOM moins biaisé que `WIFE`).
+
+#### Domain model — dates, places, events (P1.4)
+
+- **`DateAct`** :
+  - qualificateurs **INT**, **EST**, **CAL** ;
+  - phrase finale `(...)` et **`datePhrase`** ;
+  - import **`3 PHRASE`** sous `DATE` ;
+  - **`3 TIME`** sous `DATE` / **`SDATE`** (`dateTime`) ;
+  - entrée date **`YYYY-MM-DD`** / **`YYYY-MM`** ;
+  - **`verbatimDatePayload`** pour charges non typées (URI, texte hors parseur) ;
+  - tolérance `(...)` sur les bornes d’intervalles (`parseCoreDateValue`) ;
+  - format mois/année slash strict **`d{1,2}/d{2,4}`** uniquement (évite les faux positifs sur URL).
+- **`Act`** :
+  - **`2 SDATE`** (+ sous-lignes) sur `sdateAct` ;
+  - **`2 PHRASE`** niveau événement (`eventPhrases`) ;
+  - **`preservedSubrecordPrefix`** / **`preservedSubrecordSuffix`** pour sous-lignes non modélisées (`HUSB`/`AGE`/`4 PHRASE`, `3 DATE` sous `STAT`, …) avec ré-export ;
+  - tri des actes : **`DATE`** sinon **`SDATE`** valide.
+- **`Place`** : **`placPhrase`** et import **`3 PHRASE`** direct sous `PLAC` ; export **`3 PHRASE`** pour date et lieu quand présents ; export **`3 TIME`** / blocs **`SDATE`** / **`2 PHRASE`** événement.
+
+#### Fluent edit layer
+
+- Nouveau module `src/edit/` réexporté depuis la racine du paquet :
+  - **`editPerson`** / `PersonEdit` (identité, liens `FAMC` / `FAMS`, name variants, attributes, accès chaîné à `acts()` / `notes()`) ;
+  - **`editActs`** / `ActsEdit` (add, replaceAt, removeAt, clear, sortByDate, at) ;
+  - **`editAct`** / `ActEdit` (type, indis, date, sdate, place, EVEN, phrases, preserved prefix/suffix) ;
+  - **`editDateAct`** / `DateActEdit` (clear, applyGedcomPayload, setExactDate, setQualified, setBetween, setFromTo, setTime, setDatePhrase, setVerbatimPayload) ;
+  - **`editPlace`** / `PlaceEdit` (city/county/state/country, GEDCOM 7 payload, placPhrase, coordinates) ;
+  - **`editNotes`** / `NotesEdit` (add, replaceAt, removeAt, clear) ;
+  - chaînage cohérent (`this`) sur le modèle existant, mutation in-place.
+
+#### Public API surface
+
+- Types exportés : `PersonGedcomImportOptions`, `GedcomExportOptions`, `TypeDateActSimpleQualifier`, `Gedcom7EventTag`, `IndiGedcomSubLine`, `GedcomDatasetVersion`.
+- Classes / valeurs réexportées depuis l’index : `PersonNameVariant`, `PersonNameTranslation`, `IndiAttribute`, `ActConstructionOptions`, `GEDCOM_7_ALL_EVENT_TAGS`, `GEDCOM_7_EVENT_SORT_ORDER`, `GEDCOM_7_EVENT_TAG_SET`, `selectPrimaryNameVariant`, `extractPersonNameVariants`, `extractIndiAttributes`, `createEmptyReadGed`, `IMPORT_ERR_ZIP_GED_UNREADABLE`, **`GEDCOM_LIBRARY_VERSION`**.
+
+#### Tests
+
+- **Golden export** : fixture `tests/fixtures/golden-in/marriage-marr-roundtrip.ged` + fichiers attendus `tests/fixtures/golden-out/*.golden.txt` ; `tests/import/goldenMarrExport.spec.ts` verrouille le bloc `1 MARR` exporté (fixture minimale + extrait `maximal70` pour `@I1@`) et l’idempotence import → export → import.
+- Non-régression `ReadGed.groupPartners()` appelée plusieurs fois (les enfants et conjoints ne sont plus dupliqués).
+
+#### Documentation
+
+- **README intégralement réécrit** : référence complète de l’API publique (un sous-titre par export de `src/index.ts`), tables synthétiques pour `ReadGed`, `GedcomExportOptions` et la couche `*Edit`, exemples mis à jour pour chaque type / classe / fonction exposés.
+- Mention en tête du README du **site de démo graphique** : **[https://gedcomts.jaunet.me](https://gedcomts.jaunet.me)**.
+
+### Changed
+
+- Export `FAM` : sexe inconnu / non binaire / absent (`U`, `X`, `undefined`) émet **`1 HUSB`** au lieu de **`1 WIFE`** pour le rôle conjoint (placeholder GEDCOM moins biaisé).
+
+### Fixed
+
+- Export GEDCOM : terminaison correcte `0 TRLR` avec saut de ligne (au lieu du seul tag `TRLR`).
+- **`ReadGed.groupPartners()`** : les cartes `partnersMap` et `childsMap` sont vidées avant reconstruction, afin que des rappels successifs (après édition des liens en mémoire) ne dupliquent plus conjoints ni enfants.
+
+## [2.0.4] - 2026-05-11
+
+### Added
+
+- GEDCOM 7–oriented export: default `SUBM` pointer in `HEAD` and a minimal `@U1@ SUBM` record before `TRLR`.
+- `Place` supports structured locality fields (`county`, `state`, `country`) and comma-separated `PLAC` payloads aligned with the default `HEAD`.`PLAC`.`FORM`.
+- Event and person media: `FILE` with `https?://` URIs without a local `File`; optional `OBJE @O{n}@` pointers with generated `0 @O{n}@ OBJE` records when `MultimediaFile.sourceUri` and `objeXrefId` are set.
+- Import of `2 OBJE @O{n}@` under individual events (same model as level-1 `OBJE` on `INDI`).
+- `guessMediaFormFromUri()` exported from the package entrypoint (MIME guess for `OBJE`.`FILE`.`FORM`).
+- `resolveDatasetVersion` / `GedcomDatasetVersion` and GEDCOM 7 event tag constants (`GEDCOM_7_ALL_EVENT_TAGS`, etc.) on the public API.
+- Tests: `gedcom7Export`, `mediaFormFromUri`, `datasetVersion`, import smoke test against the gedcom.io `maximal70.ged` sample (file added to the repo for CI).
+
 ## [2.0.2] - 2026-05-11
 
 ### Fixed