linked-rolls 0.74.0 → 0.76.0

package/lib/filiation/edits.js

@@ -1,21 +1,24 @@
 /**
  * The edits of a version, proposed from what it inserts and deletes:
- * which of its changes belong together, and what kind of change each
- * group is. Why a change was made is left to the editor.
+ * which of its changes belong together, and what shape each group
+ * takes, from which the motivation a program can give it follows. Why
+ * a musical change was made is left to the editor.
  */
 import { v5 } from "uuid";
+import { motivationProposedFor, musicalChange, technicalChange } from "../model/Edit.js";
 import { deletedBy, editsOf, insertedBy } from "../model/Version.js";
 import { distance, mm, subtract } from "../model/Quantity.js";
 import { trackerBarOf } from "../systems/index.js";
 import { operationOf, substitutionsBetween } from "../collation/substitution.js";
-import { isCollationsOwn, unchecked } from "../collation/Collation.js";
+import { isCollationsOwn } from "../collation/Collation.js";
 import { predecessorOf } from "../analysis/stemma.js";
 import { placeOf, snapshotOf } from "../analysis/text.js";
 import { symbolsIn, versionIn } from "../lookup/lookup.js";
 import { groupBy } from "../shared/utils.js";
-import { declaring, reading } from "../ops/draft.js";
+import { reading } from "../ops/draft.js";
 import { ineffectiveAmong } from "./presence.js";
 import { reads } from "./readings.js";
+import { editRules, madeWith } from "./record.js";
 /**
  * How far a perforation may be put from where it stood for the two to be
  * one move. WM 225 moves commands by up to about 60 mm.
@@ -278,8 +281,8 @@ const rowsAmong = (groups, within) => {
 };
 /** Whether the bar spells an accent with exactly these commands. */
 const spellsAccent = (bar, types) => (bar?.accents ?? []).some(accent => sameSequence(types, accent));
-/** What kind of change a group is, where its shape says. */
-const typeOf = (group, bar, accentsAt, options) => {
+/** The shape a group of changes takes, where it is one the program knows. */
+const shapeOfGroup = (group, bar, accentsAt, options) => {
     const inserted = inOrder(ofSide(group.changes, 'insert'));
     const deleted = inOrder(ofSide(group.changes, 'delete'));
     if (group.grouping === 'substitution' || group.changes.some(change => change.foreign))
@@ -343,8 +346,8 @@ const settingsOf = (options) => ({
  * punched across three lines or more at one place are one edit, as a
  * cancel row is.
  *
- * The type is read off the shape: a pair the bar spells an accent with is
- * an additional accent, as is a note set off from its chord by a few
+ * The shape is read off the group: a pair the bar spells an accent with
+ * is an additional accent, as is a note set off from its chord by a few
  * millimetres where the version puts an accent's On; a perforation put
  * elsewhere is a shift, or where it begins about where the other did,
  * shortened or prolonged; a note struck again is shortened, two tied
@@ -427,11 +430,11 @@ export const proposeEdits = (edition, versionId, options = {}) => {
     const proposed = [...substituted, ...recoded, ...lines, ...rows]
         .sort((a, b) => byPlace(inOrder(a.changes)[0], inOrder(b.changes)[0]))
         .map((group) => {
-        const editType = typeOf(group, bar, accentsAt, settings);
+        const shape = shapeOfGroup(group, bar, accentsAt, settings);
         return {
             insert: inOrder(ofSide(group.changes, 'insert')).map(change => change.symbol.id),
             delete: inOrder(ofSide(group.changes, 'delete')).map(change => change.symbol.id),
-            ...(editType && { editType }),
+            ...(shape && { shape }),
             grouping: group.grouping
         };
     });
@@ -441,60 +444,87 @@ export const proposeEdits = (edition, versionId, options = {}) => {
 const EDITS = '3c9e0f62-1d4b-4a7e-9b55-8e2f7a6d1c04';
 const exchangeKey = (inserted, deleted) => `${[...inserted].sort().join(',')}/${[...deleted].sort().join(',')}`;
 /**
- * Whether the edit is left for a proposal to group again: one a
- * collation or an adoption wrote, that nobody has given a motivation.
+ * The motivation a program states for each change the version makes,
+ * by the id of the symbol it inserts or deletes: the one the shape of
+ * the proposed edit it belongs to calls for (`motivationProposedFor`),
+ * musical or technical. A version that derives from none makes no
+ * change, and its symbols are given none.
  * @category Filiation
  */
-export const isRegroupable = (edit) => isCollationsOwn(edit) && (edit.motivation === undefined || edit.motivation === unchecked);
+export const proposedMotivations = (edition, versionId, options = {}) => {
+    const motivations = new Map();
+    if (!predecessorOf(edition, versionId))
+        return motivations;
+    for (const edit of proposeEdits(edition, versionId, options)) {
+        const motivation = motivationProposedFor(edit.shape);
+        for (const id of [...edit.insert, ...edit.delete])
+            motivations.set(id, motivation);
+    }
+    return motivations;
+};
+/**
+ * The motivation a program states for an edit making these changes:
+ * the generic musical one where any of them is a musical change, or one
+ * the proposal does not see, and the technical one where all are
+ * technical.
+ */
+export const motivationOfChanges = (motivations, symbolIds) => symbolIds.some(id => (motivations.get(id) ?? musicalChange) === musicalChange) ? musicalChange : technicalChange;
 /**
  * The edits the version comes to state when the proposal is adopted:
  * those it keeps, and those put in place of the rest.
  */
 const adoptedEditsOf = (edition, version, options) => {
     const edits = editsOf(version);
-    const held = edits.filter(edit => !isRegroupable(edit));
+    const held = edits.filter(edit => !isCollationsOwn(edit));
     const spoken = new Set(held.flatMap(edit => [...(edit.insert ?? []).map(symbol => symbol.id), ...(edit.delete ?? [])]));
     const symbolOf = new Map(insertedBy(version).map(symbol => [symbol.id, symbol]));
     const stated = new Map(edits.map(edit => [exchangeKey((edit.insert ?? []).map(symbol => symbol.id), edit.delete ?? []), edit]));
-    const made = (inserted, deleted, editType) => {
+    const made = (inserted, deleted, motivation) => {
         const key = exchangeKey(inserted, deleted);
         const same = stated.get(key);
+        // An edit over the same changes stays, with the kind of change it states, which the editor may have said.
         if (same)
-            return same.editType || !editType ? same : { ...same, editType };
+            return same.motivation === undefined ? { ...same, motivation } : same;
         return {
             type: 'edit',
             id: v5(`edit|${version.id}|${key}`, EDITS),
-            ...(editType && { editType }),
-            motivation: unchecked,
+            motivation,
             ...(inserted.length > 0 && { insert: inserted.map(id => symbolOf.get(id)) }),
             ...(deleted.length > 0 && { delete: [...deleted] })
         };
     };
     const proposed = proposeEdits(edition, version.id, options).flatMap(edit => {
+        const motivation = motivationProposedFor(edit.shape);
         const free = (ids) => ids.filter(id => !spoken.has(id));
         const [inserted, deleted] = [free(edit.insert), free(edit.delete)];
         if (inserted.length === edit.insert.length && deleted.length === edit.delete.length) {
-            return [made(inserted, deleted, edit.editType)];
+            return [made(inserted, deleted, motivation)];
         }
         // What an edit that stays leaves of a proposed one stands symbol by symbol.
-        return [...inserted.map(id => made([id], [])), ...deleted.map(id => made([], [id]))];
+        return [...inserted.map(id => made([id], [], motivation)), ...deleted.map(id => made([], [id], motivation))];
     });
-    return [...held, ...proposed];
+    return { held, proposed };
 };
 /**
- * Puts the proposed edits (`proposeEdits`) in place of those of the
- * versions that a collation or an adoption wrote and nobody has given a
- * motivation, every version but the root where none are named. An edit
- * someone motivated, typed beyond what a collation types, or held under a
- * belief stays as it is, and what a proposed edit shares with it stands
- * symbol by symbol beside it. An edit stated already over the very same
- * symbols as a proposed one is kept with its id and what was written on
- * it, the proposed type filled in where it states none; the others are
- * new, with ids that adopting again gives again, and marked unchecked,
- * so that what is left to the editor is to say why.
+ * Puts the proposed edits (`proposeEdits`) in place of the program's
+ * edits of the versions, every version but the root where none are
+ * named: those that say nothing of why they were made, or only that they
+ * are musical or technical changes (`isCollationsOwn`). An edit with a
+ * motivation of the editor's or held under a belief stays as it is, and
+ * what a proposed edit shares with it stands symbol by symbol beside it.
+ * An edit stated already over the very same symbols as a proposed one
+ * is kept with its id and the kind of change it states, which the
+ * editor may have said otherwise than the program read it; the others
+ * are new, with ids that adopting again gives again. An edit that
+ * states no kind has the motivation its shape calls for
+ * (`motivationProposedFor`): the generic musical one for a musical
+ * change, whose reason is left to the editor, and the technical one for
+ * a technical change.
  *
  * Applied on the same draft after `adoptStemma`, it proposes the edits of
- * the stemma adopted, as one undo step.
+ * the stemma adopted, as one undo step. The edition's creation comes to
+ * name the rule that keeps an edit at one place among its principles,
+ * and this release among its software.
  * @category Operations
  */
 export const adoptEdits = (versionIds, options = {}) => reading(edition => {
@@ -502,12 +532,14 @@ export const adoptEdits = (versionIds, options = {}) => reading(edition => {
         .map(id => versionIn(edition, id))
         .filter((version) => version !== undefined && predecessorOf(edition, version.id) !== undefined);
     const adopted = new Map(targets.flatMap(version => {
-        const edits = adoptedEditsOf(edition, version, options);
+        const { held, proposed } = adoptedEditsOf(edition, version, options);
+        const edits = [...held, ...proposed];
         const stated = editsOf(version);
         if (edits.length === stated.length && edits.every((edit, index) => edit === stated[index]))
             return [];
-        return [[version.id, { ...version, edits, motivations: declaring(version.motivations, edits) }]];
+        return [[version.id, { ...version, edits }]];
     }));
+    const creation = madeWith(edition.creation, [editRules.onePlace]);
     // Each version is put in place whole: one that an operation before put
     // on the same draft, as adopting a stemma does, is no draft to write to.
     return draft => {
@@ -516,5 +548,7 @@ export const adoptEdits = (versionIds, options = {}) => reading(edition => {
             if (changed)
                 draft.versions[index] = changed;
         });
+        if (adopted.size > 0)
+            draft.creation = creation;
     };
 });

package/lib/filiation/index.d.ts

@@ -9,6 +9,7 @@ export { defaultCosts, type Costs, type Scored, type Support } from "./search.js
 export { transfersOf, systemAbove } from "./systems.js";
 export { proposeStemma, defaultMovedWithin, type FiliationOptions, type ProposedVersion, type StemmaProposal, type Unpinned } from "./proposal.js";
 export { adoptionOf, adoptStemma, type Adoption } from "./adoption.js";
+export { stemmaRules, editRules } from "./record.js";
 export { stemmaChanges, type VersionChange } from "./changes.js";
 export { sharedTexts, differencesBetween, defaultSameText, type SharedText, type KeptApart } from "./texts.js";
-export { proposeEdits, adoptEdits, isRegroupable, defaultShiftWithin, defaultPairWithin, defaultResizeWithin, defaultSamePlaceWithin, type EditOptions, type EditGrouping, type ProposedEdit } from "./edits.js";
+export { proposeEdits, adoptEdits, proposedMotivations, defaultShiftWithin, defaultPairWithin, defaultResizeWithin, defaultSamePlaceWithin, type EditOptions, type EditGrouping, type ProposedEdit } from "./edits.js";

package/lib/filiation/index.js

@@ -9,6 +9,7 @@ export { defaultCosts } from "./search.js";
 export { transfersOf, systemAbove } from "./systems.js";
 export { proposeStemma, defaultMovedWithin } from "./proposal.js";
 export { adoptionOf, adoptStemma } from "./adoption.js";
+export { stemmaRules, editRules } from "./record.js";
 export { stemmaChanges } from "./changes.js";
 export { sharedTexts, differencesBetween, defaultSameText } from "./texts.js";
-export { proposeEdits, adoptEdits, isRegroupable, defaultShiftWithin, defaultPairWithin, defaultResizeWithin, defaultSamePlaceWithin } from "./edits.js";
+export { proposeEdits, adoptEdits, proposedMotivations, defaultShiftWithin, defaultPairWithin, defaultResizeWithin, defaultSamePlaceWithin } from "./edits.js";

package/lib/filiation/record.d.ts

@@ -0,0 +1,49 @@
+/**
+ * What adopting a proposal records of how it was found: the published
+ * rules the proposal follows, among the principles of the edition, and
+ * the release of this library, among the software it was made with.
+ */
+import { EditionCreation } from "../model/Edition.js";
+/**
+ * The published rules the proposal of a stemma follows, by IRI, each
+ * under the cost or the step that carries it out. They are the
+ * editorial principles of the edition of WM 225, which are suggested
+ * for the filiation of piano rolls at large.
+ * @category Filiation
+ */
+export declare const stemmaRules: {
+    /** An addition at the same place is not made twice independently, so a reading arising costs ten times one lost. */
+    readonly sharedAddition: 'https://welte225.org/rules#shared-addition';
+    /** Redundancies are cleaned up in two branches independently, so losing one counts for less. */
+    readonly independentCleanup: 'https://welte225.org/rules#independent-cleanup';
+    /** A re-cut for another system was an editorial pass of its own, so what it lacks counts for less. */
+    readonly recutLoss: 'https://welte225.org/rules#recut-loss';
+    /** A copy may fail to show a reading of the version it carries. */
+    readonly copyDeviation: 'https://welte225.org/rules#copy-deviation';
+    /** A lost state is posited only where shared additions require it. */
+    readonly lostStates: 'https://welte225.org/rules#lost-states';
+    /** Copies of one system that differ in a few readings carry one text. */
+    readonly oneText: 'https://welte225.org/rules#one-text';
+    /** Later versions are the more refined, which orients the root. */
+    readonly refinement: 'https://welte225.org/rules#refinement';
+    /** A version derives from one exemplar, so a stemma is a tree. */
+    readonly noContamination: 'https://welte225.org/rules#no-contamination';
+};
+/**
+ * The published rules the proposal of edits follows, by IRI.
+ * @category Filiation
+ */
+export declare const editRules: {
+    /** An edit stays at one place: it runs across no command both texts keep. */
+    readonly onePlace: 'https://welte225.org/rules#one-place';
+};
+/**
+ * The edition's creation as adopting a proposal leaves it. Its
+ * principles come to name the rules the proposal follows, in place of
+ * those given to be replaced, which are the rules of the same kind that
+ * it no longer follows; the principles the editor named stay. Its
+ * software comes to name this release of the library, in place of any
+ * other release of it, so that the release named finds again what the
+ * edition states.
+ */
+export declare const madeWith: (creation: Readonly<EditionCreation>, rules: readonly string[], replacing?: readonly string[]) => EditionCreation;

package/lib/filiation/record.js

@@ -0,0 +1,49 @@
+import { linkedRolls } from "../software.js";
+/**
+ * The published rules the proposal of a stemma follows, by IRI, each
+ * under the cost or the step that carries it out. They are the
+ * editorial principles of the edition of WM 225, which are suggested
+ * for the filiation of piano rolls at large.
+ * @category Filiation
+ */
+export const stemmaRules = {
+    /** An addition at the same place is not made twice independently, so a reading arising costs ten times one lost. */
+    sharedAddition: 'https://welte225.org/rules#shared-addition',
+    /** Redundancies are cleaned up in two branches independently, so losing one counts for less. */
+    independentCleanup: 'https://welte225.org/rules#independent-cleanup',
+    /** A re-cut for another system was an editorial pass of its own, so what it lacks counts for less. */
+    recutLoss: 'https://welte225.org/rules#recut-loss',
+    /** A copy may fail to show a reading of the version it carries. */
+    copyDeviation: 'https://welte225.org/rules#copy-deviation',
+    /** A lost state is posited only where shared additions require it. */
+    lostStates: 'https://welte225.org/rules#lost-states',
+    /** Copies of one system that differ in a few readings carry one text. */
+    oneText: 'https://welte225.org/rules#one-text',
+    /** Later versions are the more refined, which orients the root. */
+    refinement: 'https://welte225.org/rules#refinement',
+    /** A version derives from one exemplar, so a stemma is a tree. */
+    noContamination: 'https://welte225.org/rules#no-contamination'
+};
+/**
+ * The published rules the proposal of edits follows, by IRI.
+ * @category Filiation
+ */
+export const editRules = {
+    /** An edit stays at one place: it runs across no command both texts keep. */
+    onePlace: 'https://welte225.org/rules#one-place'
+};
+/**
+ * The edition's creation as adopting a proposal leaves it. Its
+ * principles come to name the rules the proposal follows, in place of
+ * those given to be replaced, which are the rules of the same kind that
+ * it no longer follows; the principles the editor named stay. Its
+ * software comes to name this release of the library, in place of any
+ * other release of it, so that the release named finds again what the
+ * edition states.
+ */
+export const madeWith = (creation, rules, replacing = []) => {
+    const replaced = new Set(replacing);
+    const principles = [...new Set([...(creation.principles ?? []).filter(rule => !replaced.has(rule)), ...rules])];
+    const software = [...(creation.software ?? []).filter(program => program.name !== linkedRolls.name), linkedRolls];
+    return { ...creation, principles, software };
+};

package/lib/index.d.ts

@@ -61,6 +61,7 @@ export * from './analysis/witnesses.js';
 export { alignFeatures, ALIGNMENT_METHOD, fromAxis, ownFeaturesOf, toAxis, tooShortToShorten, type AlignmentResult } from './collation/alignment.js';
 export * from './collation/statistics.js';
 export * from './model/Edition.js';
+export { linkedRolls } from './software.js';
 export * from './lookup/lookup.js';
 export * from './lookup/paths.js';
 export * from './analysis/stemma.js';

package/lib/index.js

@@ -24,6 +24,7 @@ export * from './analysis/witnesses.js';
 export { alignFeatures, ALIGNMENT_METHOD, fromAxis, ownFeaturesOf, toAxis, tooShortToShorten } from './collation/alignment.js';
 export * from './collation/statistics.js';
 export * from './model/Edition.js';
+export { linkedRolls } from './software.js';
 export * from './lookup/lookup.js';
 export * from './lookup/paths.js';
 export * from './analysis/stemma.js';

package/lib/io/asJsonLd.js

@@ -114,7 +114,11 @@ const isDoubtedReference = (value) => isRecord(value)
  */
 const quote = (subject, key, reference, listed) => {
     const { '@annotation': { '@id': annotation, ...about }, ...object } = reference;
-    return { '@id': { '@id': subject, [key]: listed ? [object] : object }, annotation, ...about };
+    return {
+        '@id': { '@id': subject, [key]: listed ? [object] : object },
+        annotation,
+        ...about
+    };
 };
 /** The value a node states under a key, less the doubted references, which go to the quoted. */
 const unquoted = (subject, key, value, quoted) => {

package/lib/io/importJsonLd.js

@@ -1,7 +1,9 @@
 import { derivedKeys } from "./asJsonLd.js";
-import { migrate, plainCopyId } from "./migrate.js";
+import { migrate, plainCopyId, uncheckedMotivation } from "./migrate.js";
 import { isDateString } from "../shared/utils.js";
 import { putOnAxis } from "../collation/alignment.js";
+import { editsOf } from "../model/Version.js";
+import { motivationOfChanges, proposedMotivations } from "../filiation/edits.js";
 import schema from "../schema.json" with { type: 'json' };
 export const importDate = (str) => {
     const [y, m, d] = str.split('-').map(s => parseInt(s, 10));
@@ -83,9 +85,21 @@ const withoutEmptyCreations = (json) => Array.isArray(json.versions)
     : json;
 /** A statement an export quoted rather than stated: an included node whose id is a triple. */
 const isQuotedStatement = (node) => node !== null && typeof node === 'object' && node['@id'] !== null && typeof node['@id'] === 'object';
-/** The reference a quoted statement made, annotated again with the belief the export set beside it. */
+/**
+ * A belief named by its id alone, as a quoted statement of a document
+ * written before 0.76 named the belief of the proposition set it
+ * belonged to, which was stated with the set (`migrate`).
+ */
+const isNamedBelief = (belief) => belief !== null && typeof belief === 'object' && Object.keys(belief).every(key => key === '@id');
+/**
+ * The reference a quoted statement made, annotated again with the belief
+ * the export set beside it, or where it belonged to a proposition set,
+ * naming the set again for `migrate` to resolve.
+ */
 const referenceOf = (statement) => {
-    const { '@id': { '@id': subject, ...made }, annotation, ...about } = statement;
+    const { '@id': { '@id': subject, ...made }, annotation, ...stated } = statement;
+    const { belief, ...rest } = stated;
+    const about = isNamedBelief(belief) ? rest : stated;
     const [key, value] = Object.entries(made)[0];
     const listed = Array.isArray(value);
     return {
@@ -142,5 +156,29 @@ export const importJsonLd = (json) => {
         ? context.find((c) => c['@base'])?.['@base'] || ''
         : '';
     (edition.copies ?? []).forEach(putOnAxis);
-    return edition;
+    return withKindsReadOffShapes(edition);
+};
+/**
+ * Gives an edit that a document written before 0.76 left unchecked the
+ * motivation its shape calls for, read in the edition as it stands: the
+ * generic musical one or the technical one (`migrate`). The
+ * shapes are read off a copy, since what reads an edition settles it
+ * for good, and the edition an import returns is the caller's to change.
+ */
+const withKindsReadOffShapes = (edition) => {
+    if (!(edition.versions ?? []).some(version => editsOf(version).some(edit => edit.motivation === uncheckedMotivation)))
+        return edition;
+    const probe = structuredClone(edition);
+    const versions = edition.versions.map(version => {
+        if (!editsOf(version).some(edit => edit.motivation === uncheckedMotivation))
+            return version;
+        const motivations = proposedMotivations(probe, version.id);
+        return {
+            ...version,
+            edits: editsOf(version).map(edit => edit.motivation === uncheckedMotivation
+                ? { ...edit, motivation: motivationOfChanges(motivations, [...(edit.insert ?? []).map(symbol => symbol.id), ...(edit.delete ?? [])]) }
+                : edit)
+        };
+    });
+    return { ...edition, versions };
 };

package/lib/io/migrate.d.ts

@@ -13,6 +13,13 @@
 type Json = any;
 /** A copy's id without the `copy/` that documents of earlier releases put before it. */
 export declare const plainCopyId: (id: string) => string;
+/**
+ * The motivation an edit of a version that derives from another is left
+ * with where only the edition can tell what kind of change it is: one
+ * that states neither a kind nor a reason, as a collation once left
+ * them. `importJsonLd` reads its kind off its shape (`proposedMotivations`).
+ */
+export declare const uncheckedMotivation = "unchecked";
 /**
  * Brings the JSON of an edition written by an earlier release of the
  * format up to the current shape. A document that is current already