@goplayerjuggler/abc-tools 1.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/test.yml

@@ -0,0 +1,53 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Use Node.js (latest LTS)
+      uses: actions/setup-node@v3
+      with:
+        node-version: 'lts/*'
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run linter
+      run: npm run lint
+
+    - name: Run tests
+      id: run-tests
+      run: npm test
+
+    # - name: Run tests and collect coverage
+    #   id: run-tests
+    #   run: |
+    #     # Generate Jest coverage (creates coverage/ and coverage/lcov.info)
+    #     # If your npm test script doesn't pass args to Jest, replace with: npx jest --coverage
+    #     npm test -- --coverage --coverageReporters=lcov
+
+    # - name: Upload coverage artifact
+    #   if: always()
+    #   uses: actions/upload-artifact@v4
+    #   with:
+    #     name: coverage-report
+    #     path: coverage/
+
+    # - name: Upload coverage to Codecov
+    #   if: always()
+    #   uses: codecov/codecov-action@v3
+    #   with:
+    #     files: coverage/lcov.info
+    #     flags: unittests
+    #     name: codecov-umbrella
+    #     fail_ci_if_error: false

package/LICENSE

@@ -0,0 +1,22 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2025 Malcolm Schonfield
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+---
+
+For the full text of the GNU General Public License v3.0, see:
+https://www.gnu.org/licenses/gpl-3.0.txt

package/README.md

@@ -0,0 +1,96 @@
+# abc-tools
+
+A JavaScript library with utility functions for tunes written in ABC format. Particularly applicable to Irish and other traditional music.
+# Features :
+## Modal contour sort algorithm
+Sorts melodies by their modal contour, independent of key and mode. 
+The algorithm used for sorting is new/original, as far as I know, and is described [here](./docs/contour_sort.md) 
+## Extracting initial bars and incipits
+
+# About this project
+The writing of the sort algorithm, its implementation along with implementation of other features, and the project setup, were all done with the help of Claude.ai and github copilot.
+
+## license
+
+This project is licensed under the [GNU General Public License v3.0](LICENSE).
+
+This means you are free to use, modify, and distribute this software, but any derivative works must also be distributed under the GPL-3.0 license. See the [LICENSE](LICENSE) file for full details.
+
+## installation
+
+```
+npm install tune-contour-sort
+```
+
+## usage / sorting
+
+```javascript
+const { getContour, sort, sortArray } = require('tune-contour-sort');
+
+// Get sort object for a single tune
+const abc = `X:1
+L:1/8
+K:G
+GBG AGA`;
+
+const sortObj = getContour(abc);
+console.log(sortObj);
+
+
+// Compare two tunes
+const tune1 = getContour(abc1);
+const tune2 = getContour(abc2);
+const comparison = sort(tune1, tune2);
+// Returns: -1 (tune1 < tune2), 0 (equal), or 1 (tune1 > tune2)
+
+// Sort an array of tunes
+const tunes = [
+  { title: 'Tune A', abc: '...' },
+  { title: 'Tune B', abc: '...' },
+  { title: 'Tune C', abc: '...' }
+];
+
+const sorted = sortArray(tunes);
+```
+## API / sorting
+
+### `getContour(abc)`
+
+Generates a sort object from ABC notation.
+
+**Parameters:**
+- `abc` (string): ABC notation string with headers (K:, L:, etc.)
+
+**Returns:** Object with:
+- `sortKey` (string): Hexadecimal encoding of the modal contour
+- `rhythmicDivisions` (array, optional): Information about subdivided notes
+- `version` (string): Algorithm version
+- `part` (string): Tune part (default 'A')
+
+### `sort(sortObjA, sortObjB)`
+
+Compares two sort objects.
+
+**Parameters:**
+- `sortObjA` (object): First sort object
+- `sortObjB` (object): Second sort object
+
+**Returns:** Number
+- `-1` if A sorts before B
+- `0` if equal
+- `1` if A sorts after B
+
+### `sortArray(tuneArray)`
+
+Sorts an array of tune objects.
+
+**Parameters:**
+- `tuneArray` (array): Array of objects with `abc` property
+
+**Returns:** Sorted array (with `sortObject` added to each item)
+
+
+## contributing
+
+Issues and pull requests welcome at https://github.com/goplayerjuggler/abc-tools
+

package/eslint.config.js

@@ -0,0 +1,44 @@
+const js = require("@eslint/js");
+const globals = require("globals");
+const pluginJest = require('eslint-plugin-jest');
+
+module.exports = [
+  {
+    ...js.configs.recommended,
+    plugins: { jest: pluginJest },
+    languageOptions: {
+      ...js.configs.recommended.languageOptions,
+      globals: {
+        ...globals.node,...pluginJest.environments.globals.globals
+      },
+      ecmaVersion: 12,
+      sourceType: "module",
+    },
+    
+    ignores: [
+      "**/node_modules/",
+      "**/coverage/",
+      "**/dist/",
+    ],
+    rules: {
+      ...js.configs.recommended.rules,
+      // "arrow-spacing": "error"
+      "curly": ["error", "all"],
+      // "eol-last": ["error", "always"],
+      "eqeqeq": ["error", "always"],
+      "no-console": "off",
+      "no-eval": "error",
+      "no-implied-eval": "error",
+      // "no-trailing-spaces": "error",
+      "no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "no-var": "error",
+      "no-with": "error",
+      "prefer-const": "error",
+      "prefer-template": "error",
+      // "comma-dangle": ["error", "never"],
+      // "indent": ["error", 2],
+      // "quotes": ["error", "single", { avoidEscape: true }],
+      // "semi": ["error", "always"],
+    }
+  }
+];

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@goplayerjuggler/abc-tools",
+  "version": "1.0.0",
+  "description": "sorting algorithm and implementation for ABC tunes; plus other tools to come later",
+  "main": "src/index.js",
+  "scripts": {
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix"
+  },
+  "keywords": [
+    "abc",
+    "music",
+    "melody",
+    "sorting",
+    "modal",
+    "tune",
+    "traditional",
+    "irish",
+    "folk"
+  ],
+  "author": "Malcolm Schonfield",
+  "license": "GPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/goplayerjuggler/abc-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/goplayerjuggler/abc-tools/issues"
+  },
+  "homepage": "https://github.com/goplayerjuggler/abc-tools#readme",
+  "engines": {
+    "node": ">=12.0.0"
+  },
+  "devDependencies": {
+    "@eslint/eslintrc": "^3.3.1",
+    "@eslint/js": "^9.37.0",
+    "eslint": "^9.37.0",
+    "eslint-plugin-jest": "^29.0.1",
+    "globals": "^16.4.0",
+    "jest": "^30.2.0",
+    "jsdoc": "^4.0.5"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "coverageDirectory": "coverage",
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/**/*.test.js"
+    ],
+    "testMatch": [
+      "**/test/**/*.test.js",
+      "**/?(*.)+(spec|test).js"
+    ]
+  }
+}

package/src/contour-sort.js

@@ -0,0 +1,384 @@
+const { Fraction } = require("./math.js");
+const {
+  getTonalBase,
+  getUnitLength,
+  parseABCWithBars,
+  NOTE_TO_DEGREE,
+} = require("./parser.js");
+
+/**
+ * Tune Contour Sort - Modal melody sorting algorithm
+ * Sorts tunes by their modal contour, independent of key and mode
+ */
+
+// ============================================================================
+// CORE CONSTANTS
+// ============================================================================
+
+const OCTAVE_SHIFT = 7; // 7 scale degrees per octave
+
+const baseChar = 0x0420; // middle of cyrillic
+const silenceChar = "_"; // silence character
+
+// ============================================================================
+// ENCODING FUNCTIONS
+// ============================================================================
+
+/**
+ * Calculate modal position and octave offset for a note
+ * Returns a compact representation: octave * 7 + degree (both 0-indexed)
+ */
+function calculateModalPosition(tonalBase, pitch, octaveShift) {
+  const tonalDegree = NOTE_TO_DEGREE[tonalBase];
+  const noteDegree = NOTE_TO_DEGREE[pitch.toUpperCase()];
+
+  // Calculate relative degree (how many scale steps from tonic)
+  const relativeDegree = (noteDegree - tonalDegree + 7) % 7;
+
+  // Adjust octave: lowercase notes are one octave higher
+  let octave = octaveShift;
+  if (pitch === pitch.toLowerCase()) {
+    octave += 1;
+  }
+
+  // Return position as single number: octave * 7 + degree
+  // Using offset of 2 octaves to keep values positive
+  return (octave + 2) * OCTAVE_SHIFT + relativeDegree;
+}
+
+/**
+ * Encode position and played/held status as a single character
+ * This ensures held notes (even codes) sort before played notes (odd codes)
+ *
+ * @param {number} position - encodes the degree + octave
+ * @param {boolean} isHeld - if the note is held or not
+ * @returns the encoded modal degree information (MDI). Format: baseChar + (position * 2) + (isHeld ? 0 : 1)
+ */
+function encodeToChar(position, isHeld) {
+  const code = baseChar + position * 2 + (isHeld ? 0 : 1);
+  return String.fromCharCode(code);
+}
+
+/**
+ * Decode a character back to position and held status
+ */
+function decodeChar(char) {
+  if (char === silenceChar) {
+    return { isSilence: true, position: null, isHeld: null };
+  }
+
+  const code = char.charCodeAt(0) - baseChar;
+  const position = Math.floor(code / 2);
+  const isHeld = code % 2 === 0;
+  return { position, isHeld, isSilence: false };
+}
+
+// ============================================================================
+// SORT OBJECT (contour) GENERATION
+// ============================================================================
+
+/**
+ * Generate sort object from ABC notation
+ * @returns { sortKey: string, durations: Array, version: string, part: string }
+ */
+function getContour(abc, options = {}) {
+  const tonalBase = getTonalBase(abc);
+  const unitLength = getUnitLength(abc);
+  const { bars } = parseABCWithBars(abc, options);
+
+  const sortKey = [];
+  const durations = [];
+  let index = 0;
+  // get the parsed notes - notes are tokens with a duration
+  const notes = [];
+  for (let i = 0; i < bars.length; i++) {
+    const bar = bars[i];
+    for (let j = 0; j < bar.length; j++) {
+      const token = bar[j];
+      if (token.duration) {
+        notes.push(token);
+      }
+    }
+  }
+
+  notes.forEach((note) => {
+    const { duration, isSilence } = note;
+    const comparison = duration.compare(unitLength);
+    const { encoded, encodedHeld } = isSilence
+      ? { encoded: silenceChar, encodedHeld: silenceChar }
+      : getEncodedFromNote(note, tonalBase);
+
+    if (comparison > 0) {
+      // Held note: duration > unitLength
+      const ratio = duration.divide(unitLength);
+      const nbUnitLengths = Math.floor(ratio.num / ratio.den);
+      const remainingDuration = duration.subtract(
+        unitLength.multiply(nbUnitLengths)
+      );
+
+      // const durationRatio = Math.round(ratio.num / ratio.den);
+
+      // First note is played
+      sortKey.push(encoded);
+
+      // Subsequent notes are held
+      for (let i = 1; i < nbUnitLengths; i++) {
+        sortKey.push(encodedHeld);
+      }
+
+      index += nbUnitLengths;
+      if (remainingDuration.num !== 0) {
+        pushShortNote(encoded, unitLength, duration, index, durations, sortKey);
+        index++;
+      }
+    } else if (comparison < 0) {
+      pushShortNote(encoded, unitLength, duration, index, durations, sortKey);
+
+      index++;
+    } else {
+      // Normal note: duration === unitLength
+      sortKey.push(encoded);
+      index++;
+    }
+  });
+
+  return {
+    sortKey: sortKey.join(""),
+    durations: durations.length > 0 ? durations : undefined,
+    // version: "1.0",
+    // part,
+  };
+}
+
+/**
+ * Adds a short note (duration < unitLength) to the contour
+ * @param {string} encoded - the encoded representation of the note’s modal degree information (MDI)
+ * @param {Fraction} unitLength - the unit length
+ * @param {Fraction} duration - the duration of the note
+ * @param {number} index - the index of the note
+ * @param {Array<object>} durations - the durations array
+ * @param {Array<string>} sortKey - array of MDIs
+ */
+function pushShortNote(
+  encoded,
+  unitLength,
+  duration,
+  index,
+  durations,
+  sortKey
+) {
+  const relativeDuration = duration.divide(unitLength);
+
+  durations.push({
+    i: index,
+    n: relativeDuration.num === 1 ? undefined : relativeDuration.num,
+    d: relativeDuration.den,
+  });
+  sortKey.push(encoded);
+}
+
+// ============================================================================
+// COMPARISON FUNCTIONS
+// ============================================================================
+
+/**
+ * Compare two sort objects using expansion algorithm
+ */
+function sort(objA, objB) {
+  let keyA = objA.sortKey;
+  let keyB = objB.sortKey;
+
+  const dursA = objA.durations || [];
+  const dursB = objB.durations || [];
+
+  // No durations: simple lexicographic comparison
+  if (dursA.length === 0 && dursB.length === 0) {
+    return keyA === keyB ? 0 : keyA < keyB ? -1 : 1;
+  }
+
+  // Build maps of position -> {n, d}
+  const durMapA = Object.fromEntries(
+    dursA.map((dur) => [dur.i, { n: dur.n || 1, d: dur.d }])
+  );
+  const durMapB = Object.fromEntries(
+    dursB.map((dur) => [dur.i, { n: dur.n || 1, d: dur.d }])
+  );
+
+  let posA = 0;
+  let posB = 0;
+  let logicalIndex = 0;
+  let counter = 0;
+
+  while (posA < keyA.length && posB < keyB.length) {
+    if (counter++ > 10000) {
+      throw new Error("Sort algorithm iteration limit exceeded");
+    }
+
+    const durA = durMapA[logicalIndex];
+    const durB = durMapB[logicalIndex];
+
+    // Get durations as fractions
+    const fracA = durA ? new Fraction(durA.n, durA.d) : new Fraction(1, 1);
+    const fracB = durB ? new Fraction(durB.n, durB.d) : new Fraction(1, 1);
+
+    const comp = fracA.compare(fracB);
+
+    if (comp === 0) {
+      // Same duration, compare characters directly
+      const charA = keyA.charAt(posA);
+      const charB = keyB.charAt(posB);
+
+      if (charA < charB) {
+        return -1;
+      }
+      if (charA > charB) {
+        return 1;
+      }
+
+      posA++;
+      posB++;
+      logicalIndex++;
+    } else if (comp < 0) {
+      // fracA < fracB: expand B by inserting held note
+      const charA = keyA.charAt(posA);
+      const charB = keyB.charAt(posB);
+
+      if (charA < charB) {
+        return -1;
+      }
+      if (charA > charB) {
+        return 1;
+      }
+
+      // Insert held note into B
+      const decodedB = decodeChar(charB);
+      const heldChar = decodedB.isSilence
+        ? silenceChar
+        : encodeToChar(decodedB.position, true);
+
+      keyB = keyB.substring(0, posB + 1) + heldChar + keyB.substring(posB + 1);
+
+      // Update duration map for B
+      const remainingDur = fracB.subtract(fracA);
+      delete durMapB[logicalIndex];
+
+      // Add new duration entry for the held note
+      durMapB[logicalIndex + 1] = { n: remainingDur.num, d: remainingDur.den };
+
+      // Shift all subsequent B durations by 1
+      const newDurMapB = {};
+      for (const idx in durMapB) {
+        const numIdx = parseInt(idx);
+        if (numIdx > logicalIndex + 1) {
+          newDurMapB[numIdx + 1] = durMapB[idx];
+        } else {
+          newDurMapB[numIdx] = durMapB[idx];
+        }
+      }
+      Object.assign(durMapB, newDurMapB);
+
+      posA++;
+      posB++;
+      logicalIndex++;
+    } else {
+      // fracA > fracB: expand A by inserting held note
+      const charA = keyA.charAt(posA);
+      const charB = keyB.charAt(posB);
+
+      if (charA < charB) {
+        return -1;
+      }
+      if (charA > charB) {
+        return 1;
+      }
+
+      // Insert held note into A
+      const decodedA = decodeChar(charA);
+      const heldChar = decodedA.isSilence
+        ? silenceChar
+        : encodeToChar(decodedA.position, true);
+
+      keyA = keyA.substring(0, posA + 1) + heldChar + keyA.substring(posA + 1);
+
+      // Update duration map for A
+      const remainingDur = fracA.subtract(fracB);
+      delete durMapA[logicalIndex];
+
+      durMapA[logicalIndex + 1] = { n: remainingDur.num, d: remainingDur.den };
+
+      // Shift all subsequent A durations by 1
+      const newDurMapA = {};
+      for (const idx in durMapA) {
+        const numIdx = parseInt(idx);
+        if (numIdx > logicalIndex + 1) {
+          newDurMapA[numIdx + 1] = durMapA[idx];
+        } else {
+          newDurMapA[numIdx] = durMapA[idx];
+        }
+      }
+      Object.assign(durMapA, newDurMapA);
+
+      posA++;
+      posB++;
+      logicalIndex++;
+    }
+  }
+
+  if (posA >= keyA.length && posB >= keyB.length) {
+    return 0;
+  }
+  return posA >= keyA.length ? -1 : 1;
+}
+
+/**
+ * Sort an array of objects containing ABC notation
+ */
+function sortArray(arr) {
+  for (const item of arr) {
+    if (!item.sortObject && item.abc) {
+      try {
+        item.sortObject = getContour(item.abc);
+      } catch (err) {
+        console.error(`Failed to generate sort object: ${err.message}`);
+        item.sortObject = null;
+      }
+    }
+  }
+
+  arr.sort((a, b) => {
+    if (!a.sortObject && !b.sortObject) {
+      return 0;
+    }
+    if (!a.sortObject) {
+      return 1;
+    }
+    if (!b.sortObject) {
+      return -1;
+    }
+    return sort(a.sortObject, b.sortObject);
+  });
+
+  return arr;
+}
+
+function getEncodedFromNote(note, tonalBase) {
+  // Handle pitched note
+  const { pitch, octave } = note;
+  const position = calculateModalPosition(tonalBase, pitch, octave);
+  const encodedHeld = encodeToChar(position, true);
+  const encoded = encodeToChar(position, false);
+  return { encoded, encodedHeld };
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+module.exports = {
+  getContour,
+  sort,
+  sortArray,
+  decodeChar,
+  encodeToChar,
+  calculateModalPosition,
+};

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * ABC Music Toolkit
+ * Main entry point for ABC parsing, manipulation, and sorting
+ */
+
+const parser = require('./parser.js');
+const manipulator = require('./manipulator.js');
+const sort = require('./contour-sort.js');
+
+module.exports = {
+  // Parser functions
+  ...parser,
+
+  // Manipulator functions
+  ...manipulator,
+
+  // Sort functions
+  ...sort
+};