@sharpee/chord 3.3.0 → 3.5.0

package/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../repos/sharpee_v2/packages/chord/src/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAsBL,SAAS,EAKV,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAoBL,OAAO,EACR,MAAM,SAAS,CAAC;AAyCjB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD;AA8LD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,GAAG,OAAO,CAE3E"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../../../repos/sharpee_v2/packages/chord/src/analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EAsBL,SAAS,EAKV,MAAM,UAAU,CAAC;AAIlB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAuBL,OAAO,EACR,MAAM,SAAS,CAAC;AAsDjB;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD;AA8LD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,GAAG,OAAO,CAE3E"}

package/analyzer.js

@@ -5,9 +5,22 @@ exports.analyze = analyze;
 const catalog_js_1 = require("./catalog.js");
 const index_js_1 = require("./manifests/index.js");
 const phrasebooks_js_1 = require("./phrasebooks.js");
+const version_js_1 = require("./version.js");
 const ir_js_1 = require("./ir.js");
 /** Phase A stories register text in this locale (design.md §2.6). */
 const DEFAULT_LOCALE = 'en-US';
+/**
+ * Kebab-case a quoted author string into a story key (ADR-254).
+ *
+ * Used to derive a rank's id from its name, so a rank is addressable in
+ * diagnostics and in `if.event.band_crossed` without the author declaring one.
+ */
+function kebabId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
 /**
  * Exit-direction opposites (parser DIRECTIONS vocabulary) — the same
  * inference every plain exit line performs platform-side; here it backs
@@ -293,7 +306,18 @@ class Analyzer {
         // ADR-215: validate `use` lines against the manifest registry — an
         // unknown name is a compile error (the loader's trusted registry check
         // backstops rogue IR), a duplicate is one-`use`-per-extension.
+        const announceModes = {};
+        const VALID_ANNOUNCE_MODES = ['all', 'collapsed', 'combined', 'silent'];
         for (const use of this.ast.header?.uses ?? []) {
+            // ADR-262 D3: validate the `, announce <mode>` suffix and record it.
+            if (use.announce !== undefined) {
+                if (!VALID_ANNOUNCE_MODES.includes(use.announce)) {
+                    this.diagnostics.error('analysis.invalid-announce-mode', `\`announce ${use.announce}\` is not a mode — use one of: ${VALID_ANNOUNCE_MODES.join(', ')}.`, use.span);
+                }
+                else {
+                    announceModes[use.name] = use.announce;
+                }
+            }
             const manifest = index_js_1.EXTENSION_MANIFESTS.get(use.name);
             if (!manifest) {
                 const gated = [...index_js_1.EXTENSION_MANIFESTS.values()].filter((m) => !m.core).map((m) => m.name);
@@ -310,14 +334,27 @@ class Analyzer {
                 this.usedExtensions.add(use.name);
             }
         }
+        // ADR-261 D4: scoring's constructs sit behind `use scoring`. Gating them
+        // together is what makes D3 ("absent `use scoring` means the game has no
+        // score") a rule with no exceptions — scoring is on precisely when the
+        // header says so, and there is one place to look. Reported once per
+        // construct kind, at the first offending site, rather than once per line.
+        if (!this.usedExtensions.has('scoring') && this.scoreDecls.length > 0) {
+            this.reportScoringGate('score', this.scoreDecls[0].span);
+        }
+        // Built once (it emits diagnostics), spread in only when present so the
+        // optional `hunger` field never appears as `undefined` on a story without it.
+        const hungerDef = this.buildHunger();
         const ir = {
             format: ir_js_1.IR_FORMAT,
+            languageVersion: version_js_1.CHORD_LANGUAGE_VERSION, // ADR-257 D3 — the language version that compiled this story
             meta: {
                 title: this.ast.header?.title ?? '',
                 author: this.ast.header?.author ?? '',
                 fields: this.ast.header?.fields ?? {},
             },
             uses: [...this.usedExtensions],
+            announceModes,
             story: {
                 states: this.storyStates,
                 reversible: this.ast.header?.statesReversible ?? false,
@@ -339,6 +376,8 @@ class Analyzer {
             traits: [],
             actions: [],
             scores: this.scoreDecls,
+            ranks: this.buildRanks(),
+            ...(hungerDef !== undefined ? { hunger: hungerDef } : {}),
             sequences: [],
             machines: [],
             channels: [],
@@ -1383,6 +1422,121 @@ class Analyzer {
         for (const s of decl.scores)
             this.collectScore(s.name, s.worth, s.span, id);
     }
+    /** Construct kinds already reported by the scoring gate (one each). */
+    scoringGateReported = new Set();
+    /**
+     * Report the `use scoring` gate for one construct kind (ADR-261 D4).
+     *
+     * A gated construct must never be silently dead, so this is an error rather
+     * than a warning, backstopped by a `LoadError` in the story-loader for rogue
+     * IR — the two-layer shape ADR-215 uses for `define machine`.
+     *
+     * The third gated construct, a `rank` rung, cannot reach this check: the
+     * ladder is structurally inside the `use scoring` body, so a stray rung is
+     * `parse.rank-outside-scoring` at parse time — an earlier and more precise
+     * diagnostic. The loader's backstop covers the rogue-IR form.
+     */
+    reportScoringGate(kind, span) {
+        if (this.scoringGateReported.has(kind))
+            return;
+        this.scoringGateReported.add(kind);
+        const what = kind === 'score'
+            ? 'A `score … worth N` line needs'
+            : 'An `award` statement needs';
+        this.diagnostics.error('analysis.scoring-needs-use', `${what} \`use scoring\` in the story header — without it the game has no score at all, and SCORE says so.`, span);
+    }
+    /**
+     * Build the `use scoring` rank ladder (ADR-261 D2/D5).
+     *
+     * Rungs may be written in any order and are sorted ascending here, so the
+     * loader and the ledger both receive a sorted ladder. Three gates:
+     *
+     * - **duplicate threshold** — silently keeping one rung would make the
+     *   resolved rank depend on array order (ADR-260 D2);
+     * - **duplicate id** — two names that kebab-case alike collide in
+     *   `if.event.band_crossed`'s payload, which is keyed on the id;
+     * - **rung above max** — an unreachable rank. This check is sound for
+     *   Chord *specifically* because Chord has no statement that changes
+     *   maxScore at runtime, so the sum of declared `worth` is the whole
+     *   ceiling. A TypeScript story calling `setMaxScore` mid-game (as dungeo
+     *   does) has no compile step and is unaffected, by design.
+     */
+    buildRanks() {
+        const declared = this.ast.header?.ranks ?? [];
+        if (declared.length === 0)
+            return [];
+        const maxScore = this.scoreDecls.reduce((sum, s) => sum + s.worth, 0);
+        const byThreshold = new Map();
+        const byId = new Map();
+        const ranks = [];
+        for (const rung of declared) {
+            const id = kebabId(rung.name);
+            if (!id) {
+                this.diagnostics.error('analysis.rank-id-empty', `Rank name "${rung.name}" yields no id — a rank name needs at least one letter or digit.`, rung.span);
+                continue;
+            }
+            const clashingThreshold = byThreshold.get(rung.threshold);
+            if (clashingThreshold !== undefined) {
+                this.diagnostics.error('analysis.duplicate-rank-threshold', `Two rungs share the threshold ${rung.threshold} ("${clashingThreshold}" and "${rung.name}") — which rank applies would depend on source order.`, rung.span);
+                continue;
+            }
+            const clashingId = byId.get(id);
+            if (clashingId !== undefined) {
+                this.diagnostics.error('analysis.duplicate-rank-id', `Rank names "${clashingId}" and "${rung.name}" both reduce to the id \`${id}\` — a promotion event could not tell them apart.`, rung.span);
+                continue;
+            }
+            if (maxScore > 0 && rung.threshold > maxScore) {
+                this.diagnostics.error('analysis.rank-above-max', `Rank "${rung.name}" sits at ${rung.threshold}, above the ${maxScore} points this story declares — no player could reach it.`, rung.span);
+                continue;
+            }
+            byThreshold.set(rung.threshold, rung.name);
+            byId.set(id, rung.name);
+            ranks.push({
+                id,
+                name: rung.name,
+                threshold: rung.threshold,
+                ...(rung.phraseKey !== undefined ? { phraseKey: rung.phraseKey } : {}),
+                span: rung.span,
+            });
+        }
+        return ranks.sort((a, b) => a.threshold - b.threshold);
+    }
+    /**
+     * Lower the `use hunger` body (ADR-263 D1): dedup band thresholds, sort
+     * ascending. `grows`/`fatal` pass through for the loader's daemon and
+     * death-trigger lowering.
+     */
+    buildHunger() {
+        const decl = this.ast.header?.hunger;
+        if (!decl)
+            return undefined;
+        const seen = new Set();
+        const rungs = [];
+        for (const rung of decl.rungs) {
+            if (!rung.band) {
+                this.diagnostics.error('analysis.meter-band-empty', 'A hunger band needs a name.', rung.span);
+                continue;
+            }
+            if (seen.has(rung.threshold)) {
+                this.diagnostics.error('analysis.duplicate-hunger-threshold', `Two hunger bands share threshold ${rung.threshold} — the resolved band would depend on order.`, rung.span);
+                continue;
+            }
+            seen.add(rung.threshold);
+            rungs.push({
+                id: rung.band,
+                threshold: rung.threshold,
+                ...(rung.phraseKey !== undefined ? { phraseKey: rung.phraseKey } : {}),
+                span: rung.span,
+            });
+        }
+        rungs.sort((a, b) => a.threshold - b.threshold);
+        return {
+            ...(decl.grows !== undefined ? { grows: decl.grows } : {}),
+            ...(decl.fatal !== undefined ? { fatal: decl.fatal } : {}),
+            rungs,
+            span: decl.span,
+        };
+    }
     /** Register an owner-attached score (ratchet D12) under its qualified id. */
     collectScore(name, worth, span, ownerKey) {
         const qualified = ownerKey ? `${ownerKey}.${name}` : name;
@@ -1962,6 +2116,10 @@ class Analyzer {
                     span: stmt.span,
                 };
             case 'award': {
+                // ADR-261 D4: `award` is gated with `score` and `ranks`.
+                if (!this.usedExtensions.has('scoring')) {
+                    this.reportScoringGate('award', stmt.span);
+                }
                 // `award <score-name>` resolves owner-first (ratchet D12): the
                 // enclosing owner's qualified id, then the story-level bare name.
                 let expression = stmt.expression;