linked-rolls 0.57.0 → 0.59.0

package/lib/{EditionView.d.ts → view/EditionView.d.ts}

@@ -1,11 +1,9 @@
-import { Edition } from "./Edition.js";
-import { FeatureOrPatch, HorizontalSpan, NestedFeature } from "./Feature.js";
-import { AnySymbol, Expression, Note } from "./Symbol.js";
-import { Version } from "./Version.js";
-import { NegotiatedEvent } from "./ReproducingSystem.js";
-import { TrackerBar } from "./TrackerBar.js";
-import { Modification, ProductionEvent, RollCopy } from "./RollCopy.js";
-import { Millimeters } from "./Quantity.js";
+import { Edition } from "../model/Edition.js";
+import { FeatureOrPatch, HorizontalSpan, NestedFeature } from "../model/Feature.js";
+import { AnySymbol } from "../model/Symbol.js";
+import { Version } from "../model/Version.js";
+import { Modification, ProductionEvent, RollCopy } from "../model/RollCopy.js";
+import { Millimeters } from "../model/Quantity.js";
 export type Path = (string | number)[];
 export declare const getAt: <T>(path: Path, obj: unknown) => T | undefined;
 export declare class EditionView {
@@ -30,7 +28,13 @@ export declare class EditionView {
     private readonly symbolsById;
     private featuresById?;
     constructor(edition: Edition);
+    /** What stands at the path, or null where nothing does. A zero or an empty string stands there as well. */
     atPath<T>(path: Path): T | null;
+    /**
+     * Walks the edition and records where each id stands and where it is
+     * referenced. The constructor does this; a second call starts afresh
+     * rather than recording every reference twice.
+     */
     indexObjects(): void;
     version(id: string): Readonly<Version> | undefined;
     copy(id: string): Readonly<RollCopy> | undefined;
@@ -43,6 +47,11 @@ export declare class EditionView {
     features(ids: readonly string[]): Readonly<NestedFeature>[];
     getPath(anyId: string): Path | undefined;
     linksTo(anyId: string): Path[];
+    /**
+     * Calls back on the version and its ancestors along the principal
+     * line. A stemma that loops back on itself is walked once round, so
+     * that an edition in that state can still be read and repaired.
+     */
     travelUp(versionId: string, callback: (version: Readonly<Version>) => void): void;
     /** The version and its ancestors along the principal line, from the version up to the root. */
     lineageOf(versionId: string): Readonly<Version>[];
@@ -60,29 +69,6 @@ export declare class EditionView {
      * `mergeFeatures` asks before it reads them as one.
      */
     actOf(featureId: string): Readonly<ProductionEvent | Modification> | undefined;
-    /**
-     * How a place on the edition's shared axis relates to the paper of
-     * this version: place × factor = millimetres of its own paper.
-     *
-     * Copies cut for different systems are scaled onto one axis so that
-     * they can be collated at all, which leaves a version of another
-     * system carrying places in the axis copy's millimetres. A
-     * performance needs the paper the roll actually ran on, and the
-     * factor is the inverse of the scale `alignCopy` recorded.
-     *
-     * It is read only from the copies of the version's own system, since
-     * under the shared axis a green version's notes are carried by red
-     * copies too and those say nothing about green paper. A copy whose
-     * scale is put down to its own paper having stretched is left out as
-     * well: that is a fact about the one exemplar, not about the speed
-     * the system's rolls were cut at. Where what remains disagrees,
-     * `constraintProblems` reports it rather than averaging it away.
-     */
-    toOwnPaperOf(version: Readonly<Version>): number | undefined;
-    /** The scales of the version's own copies that are not their own paper stretch. */
-    speedScalesIn(version: Readonly<Version>): number[];
-    /** The copies of the version's own system that carry any of its symbols. */
-    copiesOwning(version: Readonly<Version>): Readonly<RollCopy>[];
     /** The version the given one's text is read against, by its principal derivation. */
     predecessorOf(versionId: string): Readonly<Version> | undefined;
     /**
@@ -114,14 +100,4 @@ export declare class EditionView {
     withGenerations(): Array<Version & {
         generation: number;
     }>;
-    /**
-     * The symbol as a performance needs it: where it lies, and the
-     * position the performing bar reads it on.
-     *
-     * Nothing where that bar reads nothing of it, which is the case a
-     * transfer between systems leaves behind: a red `ForzandoOn` a
-     * green version still inherits cannot be performed on a green
-     * machine, and an edit has yet to say what took its place.
-     */
-    simplifySymbol(symbol: Note | Expression, bar: TrackerBar): NegotiatedEvent | null;
 }

package/lib/{EditionView.js → view/EditionView.js}

@@ -1,9 +1,8 @@
-import { isPlaced, withBorneFeatures } from "./Feature.js";
-import { deletedBy, insertedBy, principalDerivationOf } from "./Version.js";
-import { systemIdOf } from "./TrackerBar.js";
-import { featuresMadeBy, featuresOf, isPaperStretch } from "./RollCopy.js";
-import { idOf, idsOf } from "./Assumption.js";
-import { mean } from "./Quantity.js";
+import { isPlaced, withBorneFeatures } from "../model/Feature.js";
+import { deletedBy, insertedBy, principalDerivationOf } from "../model/Version.js";
+import { featuresMadeBy, featuresOf } from "../model/RollCopy.js";
+import { idOf, idsOf } from "../model/Assumption.js";
+import { mean } from "../model/Quantity.js";
 export const getAt = (path, obj) => {
     let node = obj;
     for (const key of path) {
@@ -95,11 +94,18 @@ export class EditionView {
         this.symbolsById = byIdIn(edition.versions.flatMap(insertedBy));
         this.indexObjects();
     }
+    /** What stands at the path, or null where nothing does. A zero or an empty string stands there as well. */
     atPath(path) {
-        const node = getAt(path, this.edition);
-        return node || null;
+        return getAt(path, this.edition) ?? null;
     }
+    /**
+     * Walks the edition and records where each id stands and where it is
+     * referenced. The constructor does this; a second call starts afresh
+     * rather than recording every reference twice.
+     */
     indexObjects() {
+        this.paths.clear();
+        this.links.clear();
         const visited = new WeakSet();
         const link = (id, trail) => {
             const trails = this.links.get(id);
@@ -172,14 +178,19 @@ export class EditionView {
     linksTo(anyId) {
         return (this.links.get(anyId) ?? []).map(pathOf);
     }
+    /**
+     * Calls back on the version and its ancestors along the principal
+     * line. A stemma that loops back on itself is walked once round, so
+     * that an edition in that state can still be read and repaired.
+     */
     travelUp(versionId, callback) {
-        const v = this.version(versionId);
-        if (!v)
-            return;
-        callback(v);
-        const principal = principalDerivationOf(v);
-        if (principal) {
-            this.travelUp(idOf(principal), callback);
+        const visited = new Set();
+        let v = this.version(versionId);
+        while (v && !visited.has(v.id)) {
+            visited.add(v.id);
+            callback(v);
+            const principal = principalDerivationOf(v);
+            v = principal && this.version(idOf(principal));
         }
     }
     /** The version and its ancestors along the principal line, from the version up to the root. */
@@ -221,46 +232,6 @@ export class EditionView {
             return copy.production;
         return copy.modifications.find(act => states(featuresMadeBy(act)));
     }
-    /**
-     * How a place on the edition's shared axis relates to the paper of
-     * this version: place × factor = millimetres of its own paper.
-     *
-     * Copies cut for different systems are scaled onto one axis so that
-     * they can be collated at all, which leaves a version of another
-     * system carrying places in the axis copy's millimetres. A
-     * performance needs the paper the roll actually ran on, and the
-     * factor is the inverse of the scale `alignCopy` recorded.
-     *
-     * It is read only from the copies of the version's own system, since
-     * under the shared axis a green version's notes are carried by red
-     * copies too and those say nothing about green paper. A copy whose
-     * scale is put down to its own paper having stretched is left out as
-     * well: that is a fact about the one exemplar, not about the speed
-     * the system's rolls were cut at. Where what remains disagrees,
-     * `constraintProblems` reports it rather than averaging it away.
-     */
-    toOwnPaperOf(version) {
-        const scales = this.speedScalesIn(version);
-        return scales.length === 1 ? 1 / scales[0] : undefined;
-    }
-    /** The scales of the version's own copies that are not their own paper stretch. */
-    speedScalesIn(version) {
-        return [...new Set(this.copiesOwning(version)
-                .filter(copy => !copy.conditions.some(isPaperStretch))
-                .map(copy => copy.measurements.scale)
-                .filter((scale) => scale !== undefined && scale > 0))];
-    }
-    /** The copies of the version's own system that carry any of its symbols. */
-    copiesOwning(version) {
-        const system = systemIdOf(version.system);
-        const carrying = new Set(this.snapshot(version.id)
-            .flatMap(symbol => idsOf(symbol.carriers))
-            .flatMap(id => {
-            const copy = this.copyOf(id);
-            return copy ? [copy.id] : [];
-        }));
-        return this.edition.copies.filter(copy => carrying.has(copy.id) && systemIdOf(copy.production?.system) === system);
-    }
     /** The version the given one's text is read against, by its principal derivation. */
     predecessorOf(versionId) {
         const v = this.version(versionId);
@@ -355,24 +326,4 @@ export class EditionView {
         }));
         return withGen;
     }
-    /**
-     * The symbol as a performance needs it: where it lies, and the
-     * position the performing bar reads it on.
-     *
-     * Nothing where that bar reads nothing of it, which is the case a
-     * transfer between systems leaves behind: a red `ForzandoOn` a
-     * green version still inherits cannot be performed on a green
-     * machine, and an edit has yet to say what took its place.
-     */
-    simplifySymbol(symbol, bar) {
-        const horizontal = this.placeOf(symbol);
-        const position = bar.positionOf(symbol);
-        if (!horizontal || position === undefined)
-            return null;
-        return {
-            ...symbol,
-            horizontal,
-            vertical: { unit: 'track', from: position }
-        };
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -16,6 +16,10 @@
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
     },
+    "./validate": {
+      "types": "./lib/validate.d.ts",
+      "default": "./lib/validate.js"
+    },
     "./welte-t100": {
       "types": "./lib/systems/welteT100/system.d.ts",
       "default": "./lib/systems/welteT100/system.js"
@@ -28,7 +32,6 @@
       "types": "./lib/systems/welteLicensee/system.d.ts",
       "default": "./lib/systems/welteLicensee/system.js"
     },
-    "./lib/*": "./lib/*",
     "./package.json": "./package.json"
   },
   "files": [
@@ -40,6 +43,7 @@
     "build": "npm run build:schema && rm -rf lib && tsc",
     "prepublishOnly": "npm run build && vitest run && npm run smoke",
     "test": "vitest",
+    "lint": "oxlint -c .oxlintrc.json src test scripts schema",
     "build:schema": "npx ts-json-schema-generator --additional-properties --validation-keywords see --path 'src/**/*.ts' --type 'Edition' > schema_.json && node schema/postprocess.js && rm schema_.json && mv schema.json src/schema.json",
     "build:docs": "node schema/docs/generate.ts src/schema.json docs/index.html",
     "smoke": "node scripts/smoke.mjs"
@@ -50,6 +54,7 @@
     "@types/node": "^24.13.3",
     "jsonld": "^9.0.0",
     "n3": "^2.7.12",
+    "oxlint": "^1.85.0",
     "ts-json-schema-generator": "^2.9.0",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",

package/lib/Emulation.d.ts

@@ -1,36 +0,0 @@
-import { MidiFile } from "midifile-ts";
-import { EditionView } from "./EditionView.js";
-import { Version } from "./Version.js";
-import { AnyPerformedRollFeature, EmulatedCurve, NegotiatedEvent, ReproducingSystem } from "./ReproducingSystem.js";
-import { Millimeters } from "./Quantity.js";
-export type EmulationScope = {
-    /** Only notes whose onset lies within this span of the roll are played. */
-    range?: [Millimeters, Millimeters];
-    /** Start the clock at the first note rather than at the beginning of the roll. */
-    skipToFirstNote?: boolean;
-};
-/**
- * A version of the edition, performed: the symbols are negotiated into
- * placed events, the reproducing system plays them, and the result goes
- * out as MIDI in which every note and pedal step is labelled with the
- * symbol it performs.
- */
-export declare class Emulation<Options extends object> {
-    readonly system: ReproducingSystem<Options>;
-    options: Options;
-    midiEvents: AnyPerformedRollFeature[];
-    negotiatedEvents: NegotiatedEvent[];
-    curves: readonly EmulatedCurve[];
-    source?: string;
-    constructor(system: ReproducingSystem<Options>, options?: Options);
-    /**
-     * Moves the negotiated events to where their statements put them.
-     * The view supplies the copies, whose measurements decide how far
-     * before or after its reference a command goes, and a punch
-     * diameter, or a millimetre, where no copy agrees with a statement.
-     */
-    applyConstraints(view: EditionView): void;
-    emulateVersion(version: Version, view: EditionView, { range, skipToFirstNote }?: EmulationScope): AnyPerformedRollFeature[];
-    findEventsPerforming(id: string): AnyPerformedRollFeature[];
-    asMIDI(): MidiFile;
-}

package/lib/Emulation.js

@@ -1,250 +0,0 @@
-import { MIDIControlEvents } from "midifile-ts";
-import { idOf } from "./Assumption.js";
-import { isCommand, pairsAmong, placementsOf } from "./Symbol.js";
-import { add, mean, mm, seconds, subtract } from "./Quantity.js";
-import { punchDiameterOf } from "./RollCopy.js";
-/** The punch diameter the edition's copies report, where any of them does. */
-const meanPunchDiameterOf = (view) => {
-    const measured = view.edition.copies
-        .map(punchDiameterOf)
-        .filter(value => value !== undefined);
-    return measured.length > 0 ? mean(measured) : undefined;
-};
-const propertiesOf = (view, version) => ({
-    punchDiameter: meanPunchDiameterOf(view),
-    tempo: view.edition.tempoAdjustment,
-    toOwnPaper: view.toOwnPaperOf(version)
-});
-/** The onset a symbol has on each copy carrying it, by the copy's index, as the mean of its chains there. */
-const onsetsByCopy = (view, symbolId) => {
-    const symbol = view.symbol(symbolId);
-    if (!symbol)
-        return new Map();
-    const onsets = view.placedCarriersOf(symbol).flatMap((carrier) => {
-        const copy = view.getPath(carrier.id)?.[1];
-        return typeof copy === 'number' ? [[copy, carrier.horizontal.from]] : [];
-    });
-    const copies = new Set(onsets.map(([copy]) => copy));
-    return new Map([...copies].map(copy => [copy, mean(onsets.filter(([at]) => at === copy).map(([, onset]) => onset))]));
-};
-/**
- * The measured distance from the onset of the reference to the onset of
- * the follower on each copy carrying both, negative where the follower
- * comes first there.
- */
-const offsetsBetween = (view, followerId, referenceId) => {
-    const references = onsetsByCopy(view, referenceId);
-    return [...onsetsByCopy(view, followerId)].flatMap(([copy, onset]) => {
-        const reference = references.get(copy);
-        return reference === undefined ? [] : [subtract(onset, reference)];
-    });
-};
-/**
- * How far before or after its reference a follower is put when the
- * measurement does not already have it there: as far as the copies
- * that agree with the statement put it, and one gap where none does.
- */
-const distanceOnSide = (side, offsets, gap) => {
-    const agreeing = offsets.filter(offset => side === 'before' ? offset < 0 : offset > 0);
-    return agreeing.length > 0 ? mm(Math.abs(mean(agreeing))) : gap;
-};
-/**
- * How far each event has to move for the placements to hold:
- * an aligned event takes the onset of its reference, one placed before
- * or after its reference keeps its place where the measurement has it
- * on that side and is moved there where it does not, and a paired
- * event follows its partner so that the distance between the two is
- * kept. Events that stay where they are do not appear.
- */
-const displacementsOf = (events, offsetsBetween, gap) => {
-    const byId = new Map(events.map(event => [event.id, event]));
-    /** Where an event comes to lie once its statement and those of its references hold. */
-    const placedOnsetOf = (event, visited = new Set()) => {
-        const measured = event.horizontal.from;
-        const placement = placementsOf(event)[0];
-        const reference = placement && byId.get(idOf(placement.reference));
-        if (!placement || !reference || reference.id === event.id || visited.has(event.id))
-            return measured;
-        const referenceOnset = placedOnsetOf(reference, new Set([...visited, event.id]));
-        const distance = (side) => distanceOnSide(side, offsetsBetween(event.id, reference.id), gap);
-        switch (placement.relation) {
-            case 'alignedWith': return referenceOnset;
-            case 'before': return measured < referenceOnset ? measured : subtract(referenceOnset, distance('before'));
-            case 'after': return measured > referenceOnset ? measured : add(referenceOnset, distance('after'));
-        }
-    };
-    const displacements = new Map(events
-        .map((event) => [event, subtract(placedOnsetOf(event), event.horizontal.from)])
-        .filter(([, distance]) => distance !== 0));
-    pairsAmong(events).forEach(([one, other]) => {
-        const shared = displacements.get(one) ?? displacements.get(other);
-        if (shared === undefined)
-            return;
-        displacements.set(one, shared);
-        displacements.set(other, shared);
-    });
-    return displacements;
-};
-/** The earliest of the times, or the beginning of the roll where there are none. */
-const earliestOf = (times) => times.length === 0 ? seconds(0) : times.reduce((soonest, at) => at < soonest ? at : soonest);
-/**
- * A version of the edition, performed: the symbols are negotiated into
- * placed events, the reproducing system plays them, and the result goes
- * out as MIDI in which every note and pedal step is labelled with the
- * symbol it performs.
- */
-export class Emulation {
-    constructor(system, options = system.defaultOptions) {
-        Object.defineProperty(this, "system", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "options", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        Object.defineProperty(this, "midiEvents", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        // sorted list of events with the negotiated assumptions already applied
-        Object.defineProperty(this, "negotiatedEvents", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "curves", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
-        Object.defineProperty(this, "source", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: void 0
-        });
-        this.system = system;
-        this.options = options;
-    }
-    /**
-     * Moves the negotiated events to where their statements put them.
-     * The view supplies the copies, whose measurements decide how far
-     * before or after its reference a command goes, and a punch
-     * diameter, or a millimetre, where no copy agrees with a statement.
-     */
-    applyConstraints(view) {
-        const gap = meanPunchDiameterOf(view) ?? mm(1);
-        const offsets = (follower, reference) => offsetsBetween(view, follower, reference);
-        displacementsOf(this.negotiatedEvents, offsets, gap).forEach((distance, event) => {
-            event.horizontal.from = add(event.horizontal.from, distance);
-            event.horizontal.to = add(event.horizontal.to, distance);
-        });
-    }
-    emulateVersion(version, view, { range, skipToFirstNote = false } = {}) {
-        this.source = version.id;
-        /** A note plays only where its onset falls in the range; expressions play throughout. */
-        const inScope = (event) => !range || event.type !== 'note' || (event.horizontal.from > range[0] && event.horizontal.from < range[1]);
-        this.negotiatedEvents =
-            view.snapshot(version.id)
-                .filter(isCommand)
-                .map(symbol => view.simplifySymbol(symbol, this.system.trackerBar))
-                .filter(event => event !== null)
-                .filter(inScope);
-        if (this.negotiatedEvents.length === 0) {
-            this.midiEvents = [];
-            this.curves = [];
-            return this.midiEvents;
-        }
-        this.applyConstraints(view);
-        const performance = this.system.perform(this.negotiatedEvents, this.options, propertiesOf(view, version));
-        this.curves = performance.curves;
-        const onsets = performance.events.filter(event => event.type === 'noteOn').map(event => event.at);
-        const origin = skipToFirstNote ? earliestOf(onsets) : seconds(0);
-        this.midiEvents = performance.events
-            .map(event => ({ ...event, at: subtract(event.at, origin) }))
-            .filter(event => event.at >= 0)
-            .sort((a, b) => a.at - b.at);
-        return this.midiEvents;
-    }
-    findEventsPerforming(id) {
-        return this.midiEvents.filter(event => event.performs.id === id);
-    }
-    asMIDI() {
-        const TICKS_PER_SECOND = 1000;
-        const events = [];
-        this.midiEvents.sort((a, b) => a.at - b.at);
-        const text = (text, deltaTime = 0) => ({ type: 'meta', subtype: 'text', text, deltaTime });
-        const controller = (controllerType, value, deltaTime = 0) => ({ type: 'channel', subtype: 'controller', controllerType, value, deltaTime, channel: 0 });
-        const controllerOf = (event) => event.type === 'damper' ? MIDIControlEvents.SUSTAIN : MIDIControlEvents.SOFT_PEDAL;
-        events.push(text(`linked-rolls (${this.system.name})`));
-        if (this.source) {
-            events.push(text(this.source));
-        }
-        for (const [key, value] of Object.entries(this.options)) {
-            events.push(text(`${key}=${typeof value === 'object' ? JSON.stringify(value) : value}`));
-        }
-        events.push({
-            type: 'meta',
-            subtype: 'setTempo',
-            microsecondsPerBeat: 1000000,
-            deltaTime: 0
-        });
-        // both pedals start at rest
-        events.push(controller(MIDIControlEvents.SUSTAIN, 0), controller(MIDIControlEvents.SOFT_PEDAL, 0));
-        // a pedal step is labelled with its command only where that
-        // command changes, so the file is not swamped with labels
-        const lastCause = {};
-        let currentTick = 0;
-        for (const event of this.midiEvents) {
-            const tick = Math.round(event.at * TICKS_PER_SECOND);
-            const deltaTime = tick - currentTick;
-            currentTick = tick;
-            if (event.type === 'noteOn') {
-                events.push(text(event.performs.id, deltaTime));
-                events.push({
-                    type: 'channel',
-                    subtype: 'noteOn',
-                    noteNumber: event.pitch,
-                    velocity: +event.velocity.toFixed(0),
-                    deltaTime: 0,
-                    channel: 0
-                });
-            }
-            else if (event.type === 'noteOff') {
-                events.push({
-                    type: 'channel',
-                    subtype: 'noteOff',
-                    noteNumber: event.pitch,
-                    velocity: 127,
-                    deltaTime,
-                    channel: 0
-                });
-            }
-            else {
-                const labelled = lastCause[event.type] === event.performs.id;
-                lastCause[event.type] = event.performs.id;
-                if (!labelled) {
-                    events.push(text(event.performs.id, deltaTime));
-                }
-                events.push(controller(controllerOf(event), event.value, labelled ? deltaTime : 0));
-            }
-        }
-        return {
-            header: {
-                ticksPerBeat: TICKS_PER_SECOND,
-                formatType: 0,
-                trackCount: 1
-            },
-            tracks: [events]
-        };
-    }
-}