songsheet 5.0.0 → 6.0.0

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(/usr/bin/git -C /Users/administrator/Projects/songsheet log --oneline --all)",
+      "Bash(/usr/bin/git -C /Users/administrator/Projects/songsheet diff v4.0.0..v5.0.0 -- index.js)",
+      "Bash(npm install:*)",
+      "Bash(npx vitest run:*)",
+      "Bash(node -e:*)",
+      "WebSearch",
+      "WebFetch(domain:tonejs.github.io)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.andronio.me)",
+      "WebFetch(domain:www.guitarland.com)",
+      "Bash(npm test:*)",
+      "Bash(/usr/bin/git diff HEAD~2..HEAD -- package.json)"
+    ]
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,180 @@
+# Songsheet
+
+A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric character alignment.
+
+## Quick Start
+
+```js
+import { parse, transpose } from 'songsheet'
+
+const song = parse(rawText)          // synchronous, returns plain object
+const songInA = transpose(song, 2)   // up 2 semitones
+const songInBb = transpose(song, 3, { preferFlats: true })
+```
+
+## Architecture
+
+```
+index.js              — Public API: re-exports parse + transpose
+src/
+  lexer.js            — scanChordLine(), isChordLine(), lexExpression()
+  parser.js           — parse(), expression parser, section assembly
+  transpose.js        — transpose(), note math
+test/
+  lexer.test.js       — Chord line detection, bar lines, edge cases
+  parser.test.js      — All 4 song fixture tests + bar line tests
+  expression.test.js  — Expression parsing and resolution
+  transpose.test.js   — Semitone math, round-trips, flat/sharp preference
+*.txt                 — Song fixtures (do not modify)
+```
+
+## Module Format
+
+ESM only (`"type": "module"` in package.json). No CommonJS.
+
+## Dev Commands
+
+```bash
+npm test              # vitest run — all tests
+npx vitest            # watch mode
+npx vitest run test/parser.test.js   # single file
+```
+
+## AST Shape
+
+`parse()` returns:
+
+```js
+{
+  title: 'SONG TITLE',
+  author: 'AUTHOR NAME',
+  sections: {
+    verse: {
+      count: 4,
+      chords: [{ root: 'G', type: '' }, { root: 'F', type: '' }, ...],
+      lyrics: ['lyric line 1', ...],
+      lines: [
+        {
+          chords: [{ root: 'G', type: '', column: 0 }, ...],
+          barLines: [],           // column positions of | markers
+          lyrics: 'lyric line 1',
+          characters: [
+            { character: 'B', chord: { root: 'G', type: '' } },
+            { character: 'l' },
+            ...
+          ]
+        }
+      ]
+    },
+    chorus: { ... },
+  },
+  structure: [
+    {
+      sectionType: 'verse',
+      sectionIndex: 0,
+      chords: [...],
+      lyrics: [...],
+      lines: [...],
+      expression: null,   // non-null on directive entries
+    },
+    ...
+  ]
+}
+```
+
+## Key Design Decisions
+
+- **Chord line detection**: Exhaustive left-to-right scan — every non-whitespace token must parse as a valid chord or `|`, otherwise the line is lyrics
+- **root includes accidental**: `root: 'Bb'` not `root: 'B', accidental: 'b'`
+- **Synchronous parse**: No Promise wrapper, plain objects (no Immutable.js)
+- **Expression AST preserved**: `(VERSE, CHORUS*2)` stored as tree AND resolved to flat chords
+- **Character alignment includes barLines**: `{ character: 'r', barLine: true }` at `|` column positions
+- **Column preservation**: Chord lines are never trimmed — column positions match the original file
+
+## Songsheet Format
+
+```
+SONG TITLE - AUTHOR NAME
+
+G                               F
+ Lyrics aligned under chords...
+               C                G
+ More lyrics here
+
+F                C             D
+ Chorus lyrics...
+
+ Verse lyrics without chords (inherits first verse's chord pattern)
+
+CHORUS
+CHORUS*2
+
+PRECHORUS:
+D
+ Labeled section with chords...
+
+INSTRUMENTAL: (VERSE, CHORUS*2)
+FILL: D G D A D
+
+BRIDGE
+```
+
+### Section Type Inference
+
+1. 1st block with chords+lyrics → `verse`
+2. 2nd block with chords+lyrics → `chorus`
+3. 3rd block with chords+lyrics → `bridge`
+4. Subsequent lyric-only blocks → `verse` (inherits first verse's chords)
+5. `LABEL:` with body → named section (e.g., `prechorus`)
+6. `LABEL: expression` → directive (e.g., `instrumental`, `fill`)
+7. `LABEL` or `LABEL*N` → section reference / repeat
+
+### Expression Grammar
+
+```
+Expression = Sequence
+Sequence   = Item (',' Item)*
+Item       = Atom ('*' Number)?
+Atom       = SectionRef | ChordList | '(' Sequence ')'
+```
+
+Examples: `(VERSE, CHORUS*2)`, `(D G D A)*4`, `D G D A D`
+
+## Future Features
+
+### Percentage-based timing (`%`)
+Support `%` notation for specifying timing or duration within a measure:
+
+```
+G%50 C%50            — split measure: 50% G, 50% C
+D%75 G%25            — 3/4 D, 1/4 G
+```
+
+This would add a `duration` or `percent` field to chord objects:
+```js
+{ root: 'G', type: '', percent: 50 }
+```
+
+### Slash chords
+Parse slash chords like `G/B`, `Am/E`:
+```js
+{ root: 'G', type: '', bass: 'B' }
+```
+
+### Time signature support
+```
+TIME: 3/4
+```
+Stored as `song.timeSignature = { beats: 3, value: 4 }`.
+
+### Key detection
+Auto-detect the song's key from its chord progression. Useful for intelligent transposition suggestions.
+
+### Measure/bar grouping
+Currently `|` markers are tracked by column position. Future: group chords into explicit measures with bar lines as structural delimiters.
+
+### Multi-voice / harmony lines
+Support for parallel harmony notation — multiple chord lines mapped to the same lyric line.
+
+### Nashville number system output
+Convert chord roots to Nashville numbers (1, 2, 3...) relative to the detected or specified key.

package/README.md

@@ -1,2 +1,137 @@
 # songsheet
-A songsheet interpreter
+
+A zero-dependency songsheet parser and transposer. Parses plaintext songsheet files into a structured AST with chord-lyric character alignment.
+
+## Install
+
+```bash
+npm install songsheet
+```
+
+## Usage
+
+```js
+import { parse, transpose } from 'songsheet'
+
+const song = parse(rawText)          // synchronous, returns plain object
+const songInA = transpose(song, 2)   // up 2 semitones
+const songInF = transpose(song, -2)  // down 2 semitones
+const songInBb = transpose(song, 3, { preferFlats: true })
+```
+
+## Songsheet Format
+
+```
+SONG TITLE - AUTHOR NAME
+
+G                               F
+ Lyrics aligned under chords...
+               C                G
+ More lyrics here
+
+F                C             D
+ Chorus lyrics...
+
+ Verse lyrics without chords (inherits first verse's chord pattern)
+
+CHORUS
+CHORUS*2
+
+PRECHORUS:
+D
+ Labeled section with chords...
+
+INSTRUMENTAL: (VERSE, CHORUS*2)
+FILL: D G D A D
+
+BRIDGE
+```
+
+### Section Type Inference
+
+1. 1st block with chords+lyrics → `verse`
+2. 2nd block with chords+lyrics → `chorus`
+3. 3rd block with chords+lyrics → `bridge`
+4. Subsequent lyric-only blocks → `verse` (inherits first verse's chords)
+5. `LABEL:` with body → named section (e.g., `prechorus`)
+6. `LABEL: expression` → directive (e.g., `instrumental`, `fill`)
+7. `LABEL` or `LABEL*N` → section reference / repeat
+
+### Expression Grammar
+
+```
+Expression = Sequence
+Sequence   = Item (',' Item)*
+Item       = Atom ('*' Number)?
+Atom       = SectionRef | ChordList | '(' Sequence ')'
+```
+
+Examples: `(VERSE, CHORUS*2)`, `(D G D A)*4`, `D G D A D`
+
+## AST Shape
+
+`parse()` returns:
+
+```js
+{
+  title: 'SONG TITLE',
+  author: 'AUTHOR NAME',
+
+  // Unique section definitions
+  sections: {
+    verse: {
+      count: 4,
+      chords: [{ root: 'G', type: '' }, { root: 'F', type: '' }, ...],
+      lyrics: ['lyric line 1', ...],
+      lines: [
+        {
+          chords: [{ root: 'G', type: '', column: 0 }, ...],
+          barLines: [],           // column positions of | markers
+          lyrics: 'lyric line 1',
+          characters: [
+            { character: 'B', chord: { root: 'G', type: '' } },
+            { character: 'l' },
+            ...
+          ]
+        }
+      ]
+    },
+    chorus: { ... },
+  },
+
+  // Ordered playback structure
+  structure: [
+    {
+      sectionType: 'verse',
+      sectionIndex: 0,
+      chords: [...],
+      lyrics: [...],
+      lines: [...],
+      expression: null,   // non-null on directive entries
+    },
+    ...
+  ]
+}
+```
+
+## Transposition
+
+`transpose()` deep-walks the AST and replaces every chord root. It auto-detects whether the song uses flats or sharps, or you can override with `{ preferFlats: true }`.
+
+```js
+const song = parse(rawText)
+const up2 = transpose(song, 2)                       // G → A
+const down3 = transpose(song, -3, { preferFlats: true }) // G → Eb
+```
+
+## Development
+
+```bash
+npm test              # vitest run — all tests
+npx vitest            # watch mode
+npx vitest run test/parser.test.js   # single file
+```
+
+## License
+
+ISC

package/index.d.ts

@@ -0,0 +1,54 @@
+export interface Chord {
+  root: string
+  type: string
+}
+
+export interface PositionedChord extends Chord {
+  column: number
+}
+
+export interface Character {
+  character: string
+  chord?: Chord
+  barLine?: true
+}
+
+export interface Line {
+  chords: PositionedChord[]
+  barLines: number[]
+  lyrics: string
+  characters: Character[]
+}
+
+export type Expression =
+  | { type: 'section_ref'; name: string }
+  | { type: 'chord_list'; chords: Chord[] }
+  | { type: 'sequence'; items: Expression[] }
+  | { type: 'repeat'; body: Expression; count: number }
+
+export interface Section {
+  count: number
+  chords: Chord[]
+  lyrics: string[]
+  lines: Line[]
+}
+
+export interface StructureEntry {
+  sectionType: string
+  sectionIndex: number
+  chords: Chord[]
+  lyrics: string[]
+  lines: Line[]
+  expression: Expression | null
+}
+
+export interface Song {
+  title: string
+  author: string
+  bpm: number | null
+  sections: Record<string, Section>
+  structure: StructureEntry[]
+}
+
+export function parse(raw: string): Song
+export function transpose(song: Song, semitones: number, options?: { preferFlats?: boolean }): Song

package/index.js

@@ -1,214 +1,2 @@
-const { Map, List, fromJS } = require('immutable')
-
-const isCaps = string => string.toUpperCase() === string
-
-const chordRegExp = /(([A-G]{1}[b#]{0,1})([\w+]*))/g // http://regexr.com/3eesm
-const wordRegExp = /([A-Za-z#\+7])+/g // http://regexr.com/3eep7
-
-const isChordLine = string => string.match(chordRegExp) && string.match(wordRegExp)
-  ? string.match(chordRegExp).length === string.match(wordRegExp).length && !string.match(/:/)
-  : false
-
-const multiplyRegExp = /([A-Z]*|\((.*)\))\*([0-9])/ // http://regexr.com/3eero
-
-const multiplyExpand = line => {
-  const multiplyExecResults = multiplyRegExp.exec(line)
-  return multiplyExecResults 
-    ? line.replace(multiplyRegExp, 
-      `${multiplyExecResults[2] || multiplyExecResults[1]} `
-        .repeat(multiplyRegExp.exec(line)[3]))
-        .replace(/[\(\)]/g, '')
-        .slice(0, -1)
-    : line.replace(/[\(\)]/g, '')
-}
-
-const notSectionHeader = (lines) => !(lines.length === 1 && isCaps(lines[0]))
-
-const getLyrics = ({ rawSection }) => {
-  const lines = rawSection.split('\n')
-  
-  return notSectionHeader(lines)
-    ? lines.reduce((lyrics, line) => {
-        if (!isChordLine(line) && !isCaps(line)) {
-          lyrics.push(line)
-        }
-        return lyrics
-      }, [])
-    : []
-}
-
-const getChordLines = ({ rawSection }) => {
-  const lines = rawSection.split('\n')
-
-  return notSectionHeader(lines)
-    ? lines.reduce((chords, line) => {
-        if (isChordLine(line)) {
-          chords.push(line)
-        }
-        return chords
-      }, [])
-    : []
-}
-
-const getChords = ({ rawSection, song }) => {
-  const rawSectionLine = /.*[A-Z]:/.test(rawSection)
-    ? rawSection.match(/.*[A-Z]:(.*)/)[1]
-    : false
-
-  return rawSectionLine
-    ? multiplyExpand(rawSectionLine)
-        .match(wordRegExp)
-        .map(word => {
-          const section = song.get('sections').get(word.toLowerCase())
-          return section
-            ? section.get('chords').toArray()
-            : word
-        })
-        .reduce((a, b) => a.concat(b), []) // flatten the array
-    : getChordLines({ rawSection }).reduce((chords, line) => {
-        let match
-        while ( ( match = chordRegExp.exec(line) ) != null ) {
-          const [,, root, type] = match
-          chords.push({ root, type })
-        }
-        return chords
-      }, [])
-}
-
-const eachCharacterWithChordLine = ({ chordLine }) => (character, index) => {
-  const chordCheck = chordLine.charAt(index).match(/[A-G]/)
-
-  const chord = chordCheck
-    ? chordLine.slice(index).match(/[^ ]*/)[0]
-    : ''
-
-  return chordCheck 
-    ? { chord, character }
-    : { character }
-}
-
-const eachLyricLineWithChords = ({ chordLines }) => (lyricLine, i) => {
-  const chordLine = chordLines[i]
-
-  return chordLine
-    ? lyricLine
-        .match(/(.)/g)
-        .map(eachCharacterWithChordLine({ chordLine }))
-    : []    
-}
-
-const getLyricLineCharacters = ({ rawSection }) => {
-  const lyrics = getLyrics({ rawSection })
-  const chordLines = getChordLines({ rawSection })
-  return lyrics && chordLines
-    ? lyrics.map(eachLyricLineWithChords({ chordLines }))
-    : []
-}
-
-const getSectionType = ({ rawSection, lyrics, chords, song }) => {
-  // (1st, 2nd, 3rd, and all remaining ordering from cascading logic of !chorus, !bridge, verses.length >= 1)
-
-  const sections = song.get('sections')
-  const verse = sections.get('verse')
-  const chorus = sections.get('chorus')
-  const bridge = sections.get('bridge')
-
-  // consider the 1st section with chords to be the verse
-  if (!verse) {
-    if (lyrics && chords.length > 0) {
-      return ['verse']
-    }
-  // consider the 2nd section with chords to be the chorus
-  } else if (verse.get('count') === 1 && lyrics.length > 0 && chords.length > 0 && !chorus) {
-    return ['chorus']
-  // consider the 3rd section with chords to be a bridge
-  } else if (verse.get('count') >= 1 && lyrics.length > 0 && chords.length > 0 && chorus && !bridge) {
-    return ['bridge']
-  // consider all remaining sections with lyrics and no chords to be verses
-  } else if (verse.get('count') >= 1 && lyrics.length > 0 && chords.length === 0 && chorus) {
-    return ['verse']
-  } else {
-    // if LABEL: - defines and gives a section a label
-    if (/.*[A-Z]:/.test(rawSection)) {
-      const [, sectionTitle] = rawSection.match(/(.*[A-Z]):/)
-      return [sectionTitle.toLowerCase()]
-    }
-
-    // CHORUS, CHORUS*N
-    if (rawSection.substr(0, 6) === 'CHORUS') {
-      if (rawSection.length === 6) return ['chorus']
-      if (rawSection[6] === '*') {
-        const repeat = rawSection.split('*')[1]
-
-        const sectionTypes = []
-        let i = 0
-        while (i < repeat) {
-          sectionTypes.push('chorus')
-          i++
-        }
-
-        return sectionTypes
-      }
-    }
-
-    // bridge is built in
-    if (rawSection === 'BRIDGE') return ['bridge']
-
-    // TODO: INSTRUMENTAL (BRIDGE, CHORUS*2)
-    if (rawSection.split(' ')[0] === 'INSTRUMENTAL') return ['instrumental']
-
-    // if LABEL matches on previously defined LABEL:
-    if (rawSection.toLowerCase() && sections.get(rawSection.toLowerCase())) return [rawSection.toLowerCase()]
-
-    // otherwise it's a verse
-    if (lyrics && chords.length === 0) return ['verse']
-  }
-}
-
-const parse = (rawSongsheet) => new Promise((resolve, reject) => {
-  const rawSections = rawSongsheet.replace('\r\n', '\n').replace(/^\s*\n/gm, '\n').split('\n\n')
-  resolve(rawSections.reduce((song, rawSection, structureIndex) => {
-    const presentLyrics = getLyrics({ rawSection })
-    const presentChords = getChords({ rawSection, song })
-    const presentLyricLineCharacters = getLyricLineCharacters({ rawSection })
-
-    const sectionTypes = getSectionType({ rawSection, lyrics: presentLyrics, chords: presentChords, song }) || []
-
-    return sectionTypes.reduce((song, sectionType) => {
-      const section = song.get('sections').get(sectionType)
-
-      const lyrics = presentLyrics.length === 0 && section && section.get('lyrics')
-        ? section.get('lyrics')
-        : fromJS(presentLyrics)
-
-      const chords = presentChords.length === 0 && section && section.get('chords')
-        ? section.get('chords')
-        : fromJS(presentChords)
-
-      const lyricLineCharacters = presentLyrics.length === 0 && section && section.get('lyricLineCharacters')
-        ? section.get('lyricLineCharacters')
-        : fromJS(presentLyricLineCharacters)
-
-      return (!section
-        ? song.mergeDeepIn(['sections', sectionType], { lyrics, chords, lyricLineCharacters, count: 0 })
-        : song)
-        .updateIn(['sections', sectionType, 'count'], count => count + 1)
-        .updateIn(['structure'], structure => structure.push(Map({ sectionType, lyrics, chords, lyricLineCharacters, sectionIndex: song.getIn(['sections', sectionType, 'count']) || 0 })))
-    }, song)
-  }, Map({
-    title: rawSections[0].split(' - ')[0],
-    author: rawSections[0].split(' - ')[1],
-    structure: List(),
-    sections: Map({}),
-    rawSongsheet
-  })))
-})
-
-module.exports = () => ({ 
-  parse,
-  chordRegExp,
-  wordRegExp,
-  isChordLine,
-  multiplyRegExp,
-  multiplyExpand
-})
+export { parse } from './src/parser.js'
+export { transpose } from './src/transpose.js'

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "songsheet",
-  "version": "5.0.0",
+  "version": "6.0.0",
   "description": "A songsheet interpreter",
-  "main": "index.js",
+  "type": "module",
+  "exports": "./index.js",
   "scripts": {
-    "test": "node test.js"
+    "test": "vitest run"
   },
   "repository": {
     "type": "git",
@@ -24,12 +25,6 @@
   },
   "homepage": "https://github.com/williamcotton/songsheet#readme",
   "devDependencies": {
-    "tape": "^4.5.1",
-    "fs-promise": "^0.5.0"
-  },
-  "dependencies": {
-    "immutable": "^3.8.1",
-    "react-addons-pure-render-mixin": "^15.3.2",
-    "tokenizer": "^1.1.2"
+    "vitest": "^3.0.0"
   }
 }

package/spent-some-time-in-buffalo.txt

@@ -1,10 +1,11 @@
 SPENT SOME TIME IN BUFFALO - WILLIE COTTON
+(100 BPM)
 
-D
+D                        |
  Sweating bullets in the morning
-G 
+G                                 |
  The same old rhyme, the same old reason
-        A                               C                                   D 
+        A                               C                                   D     |
  Had to get our fill of drinking up the last warm night of this here summer season
 
  Riding shotgun down to Dansville
@@ -12,16 +13,19 @@ G
  Pretty soon this truck'll be kicking up rock salt in everybody's front lawn
  
 PRECHORUS:
-D
+D                         |
  Spent some time in Buffalo
+D                          |
  Dug my life out of the snow
+D                                      |
  And when those lake winds start to blow
+D                               |
  I've had my fill it's time to go
 
 CHORUS:
-C                            G                                D
+C                            G                                D    |
  Head out west to find the good life but I'm thinking of you now
-C                                    G                                     D 
+C                                  G                                     D    |
  Can't pay the rent, packing up my tent, picking up my money, I'm headed home
 
  Just like Jimmie nobody wants me