linked-rolls 0.47.0 → 0.48.0

package/lib/Collation.d.ts

@@ -85,6 +85,27 @@ export type Collation = {
 };
 /** Each of the own symbols with every inherited symbol it collates with, both in the order given. */
 export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherited: readonly Readonly<AnySymbol>[], locate: Locate, tolerance?: CollationTolerance) => Collation[];
+/**
+ * The motivation a collation writes on what it makes, saying that
+ * nobody has read it yet.
+ *
+ * A collation produces its edits by a rule, and an edition that
+ * publishes them unmarked would present a machine's output as an
+ * editor's reading. Stating that they are unchecked is the honest
+ * middle: the readings are there to be seen and argued with, and a
+ * reader can tell which of them anybody has weighed.
+ *
+ * It does not make an edit the editor's. `isCollationsOwn` passes over
+ * this motivation exactly, so a collation rewrites what it marked
+ * before, and only what somebody has actually written stays.
+ */
+export declare const unchecked = "unchecked";
+/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+export declare const uncheckedMotivation: {
+    readonly type: 'motivation';
+    readonly id: "unchecked";
+    readonly note: 'Made by collating the two texts and not yet read by an editor.';
+};
 /**
  * Whether the edit is one a collation writes by itself: a bare
  * insertion or a bare deletion saying nothing further, or an

package/lib/Collation.js

@@ -89,6 +89,27 @@ export const collationsOf = (own, inherited, locate, tolerance = defaultCollatio
 };
 /** The edit type a collation draws by itself, from the two systems' vocabularies rather than off the paper. */
 const drawnByCollation = 'replace-with-equivalent';
+/**
+ * The motivation a collation writes on what it makes, saying that
+ * nobody has read it yet.
+ *
+ * A collation produces its edits by a rule, and an edition that
+ * publishes them unmarked would present a machine's output as an
+ * editor's reading. Stating that they are unchecked is the honest
+ * middle: the readings are there to be seen and argued with, and a
+ * reader can tell which of them anybody has weighed.
+ *
+ * It does not make an edit the editor's. `isCollationsOwn` passes over
+ * this motivation exactly, so a collation rewrites what it marked
+ * before, and only what somebody has actually written stays.
+ */
+export const unchecked = 'unchecked';
+/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+export const uncheckedMotivation = {
+    type: 'motivation',
+    id: unchecked,
+    note: 'Made by collating the two texts and not yet read by an editor.'
+};
 /**
  * Whether the edit is one a collation writes by itself: a bare
  * insertion or a bare deletion saying nothing further, or an
@@ -107,4 +128,6 @@ const drawnByCollation = 'replace-with-equivalent';
  * draws a second time over the very same symbols.
  */
 export const isCollationsOwn = (edit) => edit.editType === drawnByCollation
-    || (edit.editType === undefined && edit.motivation === undefined && edit['@annotation'] === undefined);
+    || (edit.editType === undefined
+        && (edit.motivation === undefined || edit.motivation === unchecked)
+        && edit['@annotation'] === undefined);

package/lib/alignment.d.ts

@@ -32,6 +32,19 @@ export declare const revertScale: (copy: RollCopy) => void;
  *
  * Only holes are touched. What a writing or a mark spans is no valve.
  */
+/**
+ * The holes the extension cannot be taken off, being no longer than it
+ * is: the reader reported them open for less time than it holds a valve
+ * on beyond the perforation, so the constant over-corrects them and
+ * would leave them ending before they begin.
+ *
+ * They are where the constant shows its limit rather than where the
+ * copy is wrong, the extension varying by about half a millimetre with
+ * the port. What to do with them is an editorial question — a condition
+ * on the feature, a reading of the hole, a smaller extension — and
+ * `shortenHoles` throws rather than answer it.
+ */
+export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy) => Readonly<FeatureOrPatch>[];
 export declare const shortenHoles: (extension: Millimeters, copy: RollCopy) => void;
 /** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
 export declare const revertShortening: (copy: RollCopy) => void;

package/lib/alignment.js

@@ -78,9 +78,28 @@ const holesOf = (copy) => featuresOf(copy).filter(feature => feature.type === 'H
  *
  * Only holes are touched. What a writing or a mark spans is no valve.
  */
+/**
+ * The holes the extension cannot be taken off, being no longer than it
+ * is: the reader reported them open for less time than it holds a valve
+ * on beyond the perforation, so the constant over-corrects them and
+ * would leave them ending before they begin.
+ *
+ * They are where the constant shows its limit rather than where the
+ * copy is wrong, the extension varying by about half a millimetre with
+ * the port. What to do with them is an editorial question — a condition
+ * on the feature, a reading of the hole, a smaller extension — and
+ * `shortenHoles` throws rather than answer it.
+ */
+export const tooShortToShorten = (extension, copy) => holesOf(copy).filter(hole => hole.horizontal.to - hole.horizontal.from <= extension);
 export const shortenHoles = (extension, copy) => {
     if (copy.ops.includes('shortened'))
         return;
+    const tooShort = tooShortToShorten(extension, copy);
+    if (tooShort.length > 0) {
+        throw new Error(`The extension of ${extension} mm cannot be taken off ${tooShort.length} `
+            + `hole(s) of copy ${copy.id}, which are no longer than it: `
+            + `${tooShort.map(hole => hole.id).join(', ')}`);
+    }
     holesOf(copy).forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
     copy.ops = [...copy.ops, 'shortened'];
     copy.measurements.readerExtension = extension;

package/lib/editionOps.js

@@ -2,7 +2,7 @@ import { current, isDraft } from "immer";
 import { v4 } from "uuid";
 import { getAt } from "./EditionView.js";
 import { isCommand, placementRelations } from "./Symbol.js";
-import { collationsOf, defaultCollationTolerance, isCollationsOwn } from "./Collation.js";
+import { collationsOf, defaultCollationTolerance, isCollationsOwn, unchecked, uncheckedMotivation } from "./Collation.js";
 import { collationToleranceOf, editsOf, insertedBy, principalDerivationOf } from "./Version.js";
 import { asSymbols, barOf, featuresByAct, featuresOf, isPaperStretch, statesNothing } from "./RollCopy.js";
 import { systemOf } from "./TrackerBar.js";
@@ -54,6 +54,17 @@ const droppedIds = (before, after) => {
 };
 const insertion = (symbol) => ({ type: 'edit', id: v4(), insert: [symbol] });
 const deletion = (symbolId) => ({ type: 'edit', id: v4(), delete: [symbolId] });
+/** The edit as a collation leaves it: made by rule, and not yet read by anybody. */
+const asUnchecked = (edit) => ({ ...edit, motivation: unchecked });
+/**
+ * The motivations with the unchecked one declared, where any edit
+ * names it and the version does not state it yet. An edit naming a
+ * motivation the version leaves undeclared points at nothing.
+ */
+const declaring = (motivations, edits) => edits.some(edit => edit.motivation === unchecked)
+    && !motivations.some(motivation => motivation.id === unchecked)
+    ? [...motivations, uncheckedMotivation]
+    : motivations;
 const isEmpty = (edit) => !edit.insert?.length && !edit.delete?.length;
 const insertedIn = (versions) => versions.flatMap(insertedBy);
 /** The edits with the change applied, less those it emptied; the very same array where it changed none. */
@@ -733,6 +744,7 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
             type: 'edit',
             id: v4(),
             editType: 'replace-with-equivalent',
+            motivation: unchecked,
             insert: [...by],
             delete: deleted
         };
@@ -740,14 +752,15 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
     const edits = [
         ...established,
         ...substituted.map(equivalence),
-        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion),
+        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion).map(asUnchecked),
         ...inherited
             .filter(symbol => !matched.has(symbol.id) && !paired.has(symbol.id))
-            .map(symbol => deletion(symbol.id))
+            .map(symbol => asUnchecked(deletion(symbol.id)))
     ];
     return onVersion(childId, (child, draft) => {
         handOverCarriers(view, draft, collations);
         child.edits = edits;
+        child.motivations = declaring(stateOf(child).motivations, edits);
         child.basedOn = [
             { ...assignReference(parentId), collationTolerance: tolerance },
             ...hypothesesBeside(stateOf(child), parentId)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {