mana-scribe 1.0.0

package/.c8rc.json

@@ -0,0 +1,10 @@
+{
+  "reporter": ["lcov", "text"],
+  "report-dir": "./coverage",
+  "exclude": [
+    "tests/**",
+    "node_modules/**"
+  ],
+  "check-coverage": false,
+  "skip_empty": true
+}

package/.github/workflows/tests.yml

@@ -0,0 +1,37 @@
+name: Node.js Tests
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 24.x]
+
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./coverage/lcov.info

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2025 Colin A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# mana-scribe
+[![Tests](https://github.com/matortheeternal/mana-scribe/actions/workflows/tests.yml/badge.svg)](https://github.com/matortheeternal/mana-scribe/actions/workflows/tests.yml) [![codecov](https://codecov.io/github/matortheeternal/mana-scribe/graph/badge.svg?token=Z81O4KMEOH)](https://codecov.io/github/matortheeternal/mana-scribe)
+
+ Mana Scribe is a utility for working with Magic: The Gathering mana costs and activation costs.
+
+Supports both brace `{3}{R/U}` and shortform `3R/U` notation.
+
+## Features
+
+- Parse MTG mana costs into structured objects
+- Supports all major symbols: generic, colored, hybrid, phyrexian, snow, energy, tap/untap, variable
+- Works with both Scryfall braces and shortform notation
+- Compute:
+  - Converted mana cost
+  - Color identity
+  - Devotion
+- Extensible design — add new symbol types by subclassing
+
+Note: When the parser encounters an unrecognized symbol it stops parsing and returns the symbols it parsed so far.  You can access the unparsed string component through the property `remainingStr`.
+
+## Installation
+
+```bash
+npm install mana-scribe
+```
+
+## Usage
+```js
+import { ManaCost } from 'mana-scribe';
+
+const cost = ManaCost.parse('{3}{R}{R}{R}');
+console.log(cost.cmc);                // 6
+console.log(cost.colors);             // ['R']
+console.log(cost.colorIdentity);      // ['R']
+console.log(cost.getDevotionTo('R')); // 3
+
+console.log(cost.toString(true));     // "{3}{R}{R}{R}"
+console.log(cost.toString(false));    // "3RRR"
+```
+### Shortform example
+```js
+const cost = ManaCost.parse('2WU/B');
+console.log(cost.cmc);     // 3
+console.log(cost.colors);  // ['W','U','B']
+```
+
+## Activation costs
+`ActivationCost` offers the same functionality as the `ManaCost` class, but supports additional symbols such as Tap, Untap, and Energy.
+
+```js
+import { ActivationCost } from 'mana-scribe';
+
+const cost = ActivationCost.parse('{1}{G}{T}');
+console.log(cost.symbols.map(s => s.type)); // ["generic", "colored", "tap"]
+console.log(cost.toString(true));           // "{1}{G}{T}"
+```
+
+## Extending
+
+The library is class-based. Each symbol type is a subclass of a base Symbol class and implements:
+
+- `static match(str)` → returns a regex match object if it applies
+- `get colors()` → returns an array of the colors associated with the symbol
+- `cmcValue()` → returns an integer corresponding to how much this symbol contributes to a card's overall converted mana cost.
+
+This makes it easy to add custom symbols or patch existing ones in your own project.
+
+## Project Status
+
+This is an early but complete implementation.
+
+Current priorities:
+- [x] Support core MTG symbols
+- [x] Add test coverage
+- [ ] Other improvements? TBD
+
+## License
+
+This project is licensed under the MIT License.  See LICENSE for more info.

package/jasmine.json

@@ -0,0 +1,8 @@
+{
+  "spec_dir": ".",
+  "spec_files": [
+    "tests/**/*.test.js"
+  ],
+  "random": false,
+  "stopSpecOnExpectationFailure": false
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "mana-scribe",
+  "version": "1.0.0",
+  "description": "Library for parsing and querying Magic: The Gathering mana costs — with support for CMC, devotion, and color identity.",
+  "keywords": [
+    "mtg",
+    "magic the gathering",
+    "mana",
+    "cost",
+    "parser"
+  ],
+  "homepage": "https://github.com/matortheeternal/mana-scribe#readme",
+  "bugs": {
+    "url": "https://github.com/matortheeternal/mana-scribe/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matortheeternal/mana-scribe.git"
+  },
+  "license": "MIT",
+  "author": "mator",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "jasmine": "^5.12.0"
+  },
+  "scripts": {
+    "test": "jasmine --config=jasmine.json",
+    "coverage": "c8 npm test"
+  }
+}

package/src/costs/ActivationCost.js

@@ -0,0 +1,32 @@
+import Cost from './Cost.js';
+import ColoredManaSymbol from '../symbols/ColoredManaSymbol.js';
+import ColoredPhyrexianManaSymbol from '../symbols/ColoredPhyrexianManaSymbol.js';
+import ColorlessManaSymbol from '../symbols/ColorlessManaSymbol.js';
+import ColorlessPhyrexianManaSymbol from '../symbols/ColorlessPhyrexianManaSymbol.js';
+import EnergySymbol from '../symbols/EnergySymbol.js';
+import FiveColorHybridManaSymbol from '../symbols/FiveColorHybridManaSymbol.js';
+import FourColorHybridManaSymbol from '../symbols/FourColorHybridManaSymbol.js';
+import GenericHybridManaSymbol from '../symbols/GenericHybridManaSymbol.js';
+import GenericManaSymbol from '../symbols/GenericManaSymbol.js';
+import HalfColoredManaSymbol from '../symbols/HalfColoredManaSymbol.js';
+import InfiniteManaSymbol from '../symbols/InfiniteManaSymbol.js';
+import SnowManaSymbol from '../symbols/SnowManaSymbol.js';
+import TapSymbol from '../symbols/TapSymbol.js';
+import ThreeColorHybridManaSymbol from '../symbols/ThreeColorHybridManaSymbol.js';
+import TwoColorHybridManaSymbol from '../symbols/TwoColorHybridManaSymbol.js';
+import UntapSymbol from '../symbols/UntapSymbol.js';
+import VariableManaSymbol from '../symbols/VariableManaSymbol.js';
+
+export default class ActivationCost extends Cost {
+    static get allowedSymbols() {
+        return [
+            ColoredPhyrexianManaSymbol, GenericHybridManaSymbol, FiveColorHybridManaSymbol,
+            FourColorHybridManaSymbol, ThreeColorHybridManaSymbol, TwoColorHybridManaSymbol,
+            ColorlessPhyrexianManaSymbol, HalfColoredManaSymbol,
+            GenericManaSymbol, VariableManaSymbol,
+            InfiniteManaSymbol, SnowManaSymbol,
+            ColoredManaSymbol, ColorlessManaSymbol,
+            EnergySymbol, TapSymbol, UntapSymbol,
+        ];
+    }
+}

package/src/costs/Cost.js

@@ -0,0 +1,48 @@
+import { NotImplementedError } from '../customErrors.js';
+
+export default class Cost {
+    static get allowedSymbols() {
+        throw new NotImplementedError('allowedSymbols');
+    }
+
+    static parse(str) {
+        const cost = new this();
+        cost.parseSymbols(str);
+        return cost;
+    }
+
+    constructor(symbols = []) {
+        this.symbols = symbols;
+    }
+
+    get colors() {
+        const set = new Set(this.symbols.flatMap(sym => sym.colors));
+        return [...set];
+    }
+
+    parseSymbols(str) {
+        let remainingStr = str.trim();
+        while (remainingStr.length) {
+            const symbol = this.parseNextSymbol(remainingStr);
+            if (!symbol) break;
+            symbol.apply(this.symbols);
+            if (remainingStr === symbol.remainingStr) break;
+            remainingStr = symbol.remainingStr;
+        }
+        this.remainingStr = remainingStr;
+    }
+
+    parseNextSymbol(str) {
+        for (const symbol of this.constructor.allowedSymbols) {
+            const match = symbol.match(str);
+            if (!match) continue;
+            return symbol.parse(match, str);
+        }
+    }
+
+    toString(useBraces = false) {
+        return this.symbols.map(sym => {
+            return sym.toString(useBraces);
+        }).join('');
+    }
+}

package/src/costs/ManaCost.js

@@ -0,0 +1,38 @@
+import Cost from './Cost.js';
+import ColoredManaSymbol from '../symbols/ColoredManaSymbol.js';
+import ColoredPhyrexianManaSymbol from '../symbols/ColoredPhyrexianManaSymbol.js';
+import ColorlessManaSymbol from '../symbols/ColorlessManaSymbol.js';
+import ColorlessPhyrexianManaSymbol from '../symbols/ColorlessPhyrexianManaSymbol.js';
+import FiveColorHybridManaSymbol from '../symbols/FiveColorHybridManaSymbol.js';
+import FourColorHybridManaSymbol from '../symbols/FourColorHybridManaSymbol.js';
+import GenericHybridManaSymbol from '../symbols/GenericHybridManaSymbol.js';
+import GenericManaSymbol from '../symbols/GenericManaSymbol.js';
+import HalfColoredManaSymbol from '../symbols/HalfColoredManaSymbol.js';
+import InfiniteManaSymbol from '../symbols/InfiniteManaSymbol.js';
+import SnowManaSymbol from '../symbols/SnowManaSymbol.js';
+import ThreeColorHybridManaSymbol from '../symbols/ThreeColorHybridManaSymbol.js';
+import TwoColorHybridManaSymbol from '../symbols/TwoColorHybridManaSymbol.js';
+import VariableManaSymbol from '../symbols/VariableManaSymbol.js';
+
+export default class ManaCost extends Cost {
+    static get allowedSymbols() {
+        return [
+            ColoredPhyrexianManaSymbol, GenericHybridManaSymbol, FiveColorHybridManaSymbol,
+            FourColorHybridManaSymbol, ThreeColorHybridManaSymbol, TwoColorHybridManaSymbol,
+            ColorlessPhyrexianManaSymbol, HalfColoredManaSymbol,
+            GenericManaSymbol, VariableManaSymbol,
+            InfiniteManaSymbol, SnowManaSymbol,
+            ColoredManaSymbol, ColorlessManaSymbol
+        ];
+    }
+
+    get cmc() {
+        return this.symbols.reduce((sum, sym) => sum + sym.cmcValue(), 0);
+    }
+
+    getDevotionTo(color) {
+        return this.symbols.reduce((devotion, sym) => {
+            return devotion + (sym.colors.includes(color) ? 1 : 0);
+        }, 0);
+    }
+}

package/src/customErrors.js

@@ -0,0 +1,6 @@
+export class NotImplementedError extends Error {
+    constructor(methodName) {
+        super(`Method "${methodName}" not implemented`);
+        this.name = 'NotImplementedError';
+    }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+import ActivationCost from './costs/ActivationCost.js';
+import ManaCost from './costs/ManaCost.js';
+
+export { ActivationCost, ManaCost };

package/src/symbols/ColoredManaSymbol.js

@@ -0,0 +1,20 @@
+import Symbol from './Symbol.js';
+
+export default class ColoredManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{[WUBRG]}/i)
+            || str.match(/^[WUBRG]/i);
+    }
+
+    get colors() {
+        return [this.raw];
+    }
+
+    get type() {
+        return 'coloredMana';
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/ColoredPhyrexianManaSymbol.js

@@ -0,0 +1,20 @@
+import Symbol from './Symbol.js';
+
+export default class ColoredPhyrexianManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{(h\/[wubrg]|[wubrg]\/h)}/i)
+            || str.match(/^(h\/[wubrg]|[wubrg]\/h)/i);
+    }
+
+    get colors() {
+        return this.raw.split('/').filter(c => 'WUBRG'.includes(c));
+    }
+
+    get type() {
+        return 'coloredPhyrexianMana';
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/ColorlessManaSymbol.js

@@ -0,0 +1,20 @@
+import Symbol from './Symbol.js';
+
+export default class ColorlessManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{C}/i)
+            || str.match(/^C/i);
+    }
+
+    get colors() {
+        return [];
+    }
+
+    get type() {
+        return 'colorlessMana';
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/ColorlessPhyrexianManaSymbol.js

@@ -0,0 +1,12 @@
+import ColorlessManaSymbol from './ColorlessManaSymbol.js';
+
+export default class ColorlessPhyrexianManaSymbol extends ColorlessManaSymbol {
+    static match(str) {
+        return str.match(/^{(h\/c|c\/h|h)}/i)
+            || str.match(/^(h\/c|c\/h|h)/i);
+    }
+
+    get type() {
+        return 'colorlessPhyrexianMana';
+    }
+}

package/src/symbols/EnergySymbol.js

@@ -0,0 +1,12 @@
+import NonManaSymbol from './NonManaSymbol.js';
+
+export default class EnergySymbol extends NonManaSymbol {
+    static match(str) {
+        return str.match(/^{E}/i)
+            || str.match(/^E/i);
+    }
+
+    get type() {
+        return 'energy';
+    }
+}

package/src/symbols/FiveColorHybridManaSymbol.js

@@ -0,0 +1,12 @@
+import HybridManaSymbol from './HybridManaSymbol.js';
+
+export default class FiveColorHybridManaSymbol extends HybridManaSymbol {
+    static match(str) {
+        return super.match(str, 5, /^{[WUBRG](\/[WUBRG]){4}}/i)
+            || super.match(str, 5, /^[WUBRG](\/[WUBRG]){4}/i);
+    }
+
+    get type() {
+        return 'fiveColorHybridMana';
+    }
+}

package/src/symbols/FourColorHybridManaSymbol.js

@@ -0,0 +1,12 @@
+import HybridManaSymbol from './HybridManaSymbol.js';
+
+export default class FourColorHybridManaSymbol extends HybridManaSymbol {
+    static match(str) {
+        return super.match(str, 4, /^{[WUBRG](\/[WUBRG]){3}}/i)
+            || super.match(str, 4, /^[WUBRG](\/[WUBRG]){3}/i);
+    }
+
+    get type() {
+        return 'fourColorHybridMana';
+    }
+}

package/src/symbols/GenericHybridManaSymbol.js

@@ -0,0 +1,20 @@
+import Symbol from './Symbol.js';
+
+export default class GenericHybridManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{\d\/([WUBRGC])}/i)
+            || str.match(/^\d\/([WUBRGC])/i)
+    }
+
+    get colors() {
+        return this.raw.split('/').filter(c => 'WUBRG'.includes(c));
+    }
+
+    get type() {
+        return 'genericHybridMana';
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/GenericManaSymbol.js

@@ -0,0 +1,16 @@
+import Symbol from './Symbol.js';
+
+export default class GenericManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{[0-9][0-9]?}/)
+            || str.match(/^[0-9][0-9]?/);
+    }
+
+    get type() {
+        return 'genericMana';
+    }
+
+    cmcValue() {
+        return parseInt(this.raw);
+    }
+}

package/src/symbols/HalfColoredManaSymbol.js

@@ -0,0 +1,21 @@
+import Symbol from './Symbol.js';
+
+export default class HalfColoredManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{\|[WUBRGS]}/i)
+            || str.match(/^\|[WUBRGS]/i);
+    }
+
+    get colors() {
+        const c = this.raw[1];
+        return c === 'S' ? [] : [c];
+    }
+
+    get type() {
+        return 'halfColoredMana';
+    }
+
+    cmcValue() {
+        return 0.5;
+    }
+}

package/src/symbols/HybridManaSymbol.js

@@ -0,0 +1,21 @@
+import Symbol from './Symbol.js';
+
+function getHybridCount(str) {
+    return new Set(str.split('/')).size;
+}
+
+export default class HybridManaSymbol extends Symbol {
+    static match(str, hybridCount, expr) {
+        const matchData = str.match(expr);
+        if (!matchData || getHybridCount(matchData[0]) !== hybridCount) return;
+        return matchData;
+    }
+
+    get colors() {
+        return this.raw.split('/');
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/InfiniteManaSymbol.js

@@ -0,0 +1,16 @@
+import Symbol from './Symbol.js';
+
+export default class InfiniteManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{I}/i)
+            || str.match(/^I/i)
+    }
+
+    get type() {
+        return 'infiniteMana';
+    }
+
+    cmcValue() {
+        return Infinity;
+    }
+}

package/src/symbols/NonManaSymbol.js

@@ -0,0 +1,11 @@
+import Symbol from './Symbol.js';
+
+export default class NonManaSymbol extends Symbol {
+    get colors() {
+        return [];
+    }
+
+    cmcValue() {
+        return 0;
+    }
+}

package/src/symbols/SnowManaSymbol.js

@@ -0,0 +1,20 @@
+import Symbol from './Symbol.js';
+
+export default class SnowManaSymbol extends Symbol {
+    static match(str) {
+        return str.match(/^{S}/i)
+            || str.match(/^S/i);
+    }
+
+    get colors() {
+        return [];
+    }
+
+    get type() {
+        return 'snowMana';
+    }
+
+    cmcValue() {
+        return 1;
+    }
+}

package/src/symbols/Symbol.js

@@ -0,0 +1,44 @@
+import { NotImplementedError } from '../customErrors.js';
+
+export default class Symbol {
+    static match(str) {
+        throw new NotImplementedError('match');
+    }
+
+    static fromString(str) {
+        const matchData = this.match(str);
+        if (!matchData)
+            throw new Error(`Invalid ${this.name} input: ${str}`);
+        return this.parse(matchData, str);
+    }
+
+    static parse(match, str) {
+        return new this(match, str);
+    }
+
+    constructor(match, str) {
+        const raw = match[0];
+        this.raw = (raw[0] === '{' ? raw.slice(1, -1) : raw).toUpperCase();
+        this.remainingStr = str.slice(match[0].length);
+    }
+
+    get type() {
+        throw new NotImplementedError('type');
+    }
+
+    get cmcValue() {
+        throw new NotImplementedError('cmcValue');
+    }
+
+    get colors() {
+        return [];
+    }
+
+    apply(symbols) {
+        symbols.push(this);
+    }
+
+    toString(useBraces = false) {
+        return useBraces ? `{${this.raw}}` : this.raw;
+    }
+}

package/src/symbols/TapSymbol.js

@@ -0,0 +1,12 @@
+import NonManaSymbol from './NonManaSymbol.js';
+
+export default class TapSymbol extends NonManaSymbol {
+    static match(str) {
+        return str.match(/^{T}/i)
+            || str.match(/^T/i);
+    }
+
+    get type() {
+        return 'tap';
+    }
+}

package/src/symbols/ThreeColorHybridManaSymbol.js

@@ -0,0 +1,12 @@
+import HybridManaSymbol from './HybridManaSymbol.js';
+
+export default class ThreeColorHybridManaSymbol extends HybridManaSymbol {
+    static match(str) {
+        return super.match(str, 3, /^{[WUBRG](\/[WUBRG]){2}}/i)
+            || super.match(str, 3, /^[WUBRG](\/[WUBRG]){2}/i);
+    }
+
+    get type() {
+        return 'threeColorHybridMana';
+    }
+}

package/src/symbols/TwoColorHybridManaSymbol.js

@@ -0,0 +1,12 @@
+import HybridManaSymbol from './HybridManaSymbol.js';
+
+export default class TwoColorHybridManaSymbol extends HybridManaSymbol {
+    static match(str) {
+        return super.match(str, 2, /^{[WUBRG]\/[WUBRG]}/i)
+            || super.match(str, 2, /^[WUBRG]\/[WUBRG]/i);
+    }
+
+    get type() {
+        return 'twoColorHybridMana';
+    }
+}

package/src/symbols/UntapSymbol.js

@@ -0,0 +1,12 @@
+import NonManaSymbol from './NonManaSymbol.js';
+
+export default class UntapSymbol extends NonManaSymbol {
+    static match(str) {
+        return str.match(/^{Q}/i)
+            || str.match(/^Q/i);
+    }
+
+    get type() {
+        return 'untap';
+    }
+}