@condorcet.vote/cef-writer 1.2.0

package/dist/Ranking.d.ts

@@ -0,0 +1,91 @@
+/**
+ * An ordered ranking of candidates.
+ *
+ * The ranking is expressed as an ordered list of ranks; each rank is itself a
+ * list of candidate names tied at that position. An empty top-level ranking
+ * (`[]`) renders as the `/EMPTY_RANKING/` blank-ballot sentinel.
+ *
+ * A `Ranking` is immutable and self-validating: any specification violation
+ * (reserved character, empty rank, duplicate candidate) throws a
+ * {@link CefFormatException} at construction time. Render it to a CEF string
+ * with {@link format} (or by casting to `string` via {@link toString}).
+ */
+export declare class Ranking {
+    readonly ranks: readonly (readonly string[])[];
+    /**
+     * @param ranks Ordered ranks; each inner list is non-empty. Pass `[]` for
+     *              the `/EMPTY_RANKING/` blank ballot.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    constructor(ranks: readonly (readonly string[])[]);
+    /**
+     * Build a {@link Ranking} from a ranking-only string.
+     *
+     * The string may contain candidate names joined by the `>` (rank) and `=`
+     * (tie) operators, or the `/EMPTY_RANKING/` sentinel. Any reserved character
+     * (`^`, `*`, `#`, `;`, `,`, `/`), the `||` tag separator, or a line break is
+     * rejected — there is no way to smuggle a weight, quantifier, tag or inline
+     * comment through the string.
+     *
+     * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromString(ranking: string): Ranking;
+    /**
+     * Validate a ranking-only string without allocating a {@link Ranking}.
+     *
+     * Runs the exact same checks as {@link fromString} (empty input, `||` tag
+     * separator, reserved characters, line breaks, duplicate candidates) but
+     * never materialises the parsed structure nor a `Ranking` instance — useful
+     * for hot paths that write the ranking string verbatim after a strict format
+     * check.
+     *
+     * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertValidString(ranking: string): void;
+    /**
+     * Trim a ranking-only string and reject the two patterns that the
+     * per-candidate validation cannot catch on its own: an empty input and the
+     * `||` tag separator. Returns the trimmed work string.
+     *
+     * @throws {CefFormatException}
+     */
+    private static normalizeString;
+    /**
+     * Render the ranking — *without* trailing newline, tags, weight, quantifier
+     * or inline comment — using the spacing flavor selected by `autoFormat`.
+     *
+     * When `autoFormat` is `true` (default), ranks are separated by `" > "` and
+     * tied candidates by `" = "`; when `false`, the most compact `>` / `=` form
+     * is emitted. An empty ranking yields the `/EMPTY_RANKING/` sentinel.
+     */
+    format(autoFormat?: boolean): string;
+    /**
+     * Render the ranking in its relaxed (auto-formatted) flavor.
+     */
+    toString(): string;
+    /**
+     * Split a cleaned ranking string into its raw, *un-validated* rank/tie
+     * structure. The `/EMPTY_RANKING/` sentinel maps to an empty list. Ranks are
+     * separated by `>`, tied candidates within a rank by `=`; every token is
+     * trimmed but not otherwise checked here.
+     */
+    private static split;
+    /**
+     * @throws {CefFormatException}
+     */
+    private static validate;
+    /**
+     * Trim and validate a single candidate name, rejecting reserved characters,
+     * line breaks, invalid UTF-8 and duplicates. The `seen` set is updated to
+     * detect repeats across the whole ranking.
+     *
+     * @throws {CefFormatException}
+     */
+    private static assertCandidate;
+}
+//# sourceMappingURL=Ranking.d.ts.map

package/dist/Ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Ranking.d.ts","sourceRoot":"","sources":["../src/Ranking.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AACH,qBAAa,OAAO;IAClB,SAAgB,KAAK,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAEtD;;;;;OAKG;gBACgB,KAAK,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE;IAIxD;;;;;;;;;;;;OAYG;WACW,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIlD;;;;;;;;;;;;OAYG;WACW,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAgBtD;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;IAkB9B;;;;;;;OAOG;IACI,MAAM,CAAC,UAAU,UAAO,GAAG,MAAM;IAWxC;;OAEG;IACI,QAAQ,IAAI,MAAM;IAIzB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,KAAK;IAoBpB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;IAqBvB;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,eAAe;CAc/B"}

package/dist/Ranking.js

@@ -0,0 +1,162 @@
+import { CefFormat } from './CefFormat';
+import { DuplicateCandidateException, InvalidValueException } from './Exception';
+/**
+ * An ordered ranking of candidates.
+ *
+ * The ranking is expressed as an ordered list of ranks; each rank is itself a
+ * list of candidate names tied at that position. An empty top-level ranking
+ * (`[]`) renders as the `/EMPTY_RANKING/` blank-ballot sentinel.
+ *
+ * A `Ranking` is immutable and self-validating: any specification violation
+ * (reserved character, empty rank, duplicate candidate) throws a
+ * {@link CefFormatException} at construction time. Render it to a CEF string
+ * with {@link format} (or by casting to `string` via {@link toString}).
+ */
+export class Ranking {
+    ranks;
+    /**
+     * @param ranks Ordered ranks; each inner list is non-empty. Pass `[]` for
+     *              the `/EMPTY_RANKING/` blank ballot.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    constructor(ranks) {
+        this.ranks = Ranking.validate(ranks);
+    }
+    /**
+     * Build a {@link Ranking} from a ranking-only string.
+     *
+     * The string may contain candidate names joined by the `>` (rank) and `=`
+     * (tie) operators, or the `/EMPTY_RANKING/` sentinel. Any reserved character
+     * (`^`, `*`, `#`, `;`, `,`, `/`), the `||` tag separator, or a line break is
+     * rejected — there is no way to smuggle a weight, quantifier, tag or inline
+     * comment through the string.
+     *
+     * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromString(ranking) {
+        return new Ranking(Ranking.split(Ranking.normalizeString(ranking)));
+    }
+    /**
+     * Validate a ranking-only string without allocating a {@link Ranking}.
+     *
+     * Runs the exact same checks as {@link fromString} (empty input, `||` tag
+     * separator, reserved characters, line breaks, duplicate candidates) but
+     * never materialises the parsed structure nor a `Ranking` instance — useful
+     * for hot paths that write the ranking string verbatim after a strict format
+     * check.
+     *
+     * @param ranking Ranking only, e.g. `"A > B = C"` or `"/EMPTY_RANKING/"`.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertValidString(ranking) {
+        const work = Ranking.normalizeString(ranking);
+        if (work === CefFormat.EMPTY_RANKING) {
+            return;
+        }
+        const seen = new Set();
+        for (const rankString of work.split('>')) {
+            for (const candidate of rankString.split('=')) {
+                Ranking.assertCandidate(candidate, seen);
+            }
+        }
+    }
+    /**
+     * Trim a ranking-only string and reject the two patterns that the
+     * per-candidate validation cannot catch on its own: an empty input and the
+     * `||` tag separator. Returns the trimmed work string.
+     *
+     * @throws {CefFormatException}
+     */
+    static normalizeString(ranking) {
+        const work = ranking.trim();
+        if (work === '') {
+            throw new InvalidValueException('Ranking string cannot be empty; use "/EMPTY_RANKING/" for a blank ballot.');
+        }
+        // The "||" tag separator is the only forbidden pattern that per-candidate
+        // validation would not catch on its own ("|" is not a reserved character),
+        // so reject it explicitly here. Every reserved character and line break is
+        // rejected later, candidate by candidate.
+        CefFormat.assertNoTagSeparator(work, 'Ranking');
+        return work;
+    }
+    /**
+     * Render the ranking — *without* trailing newline, tags, weight, quantifier
+     * or inline comment — using the spacing flavor selected by `autoFormat`.
+     *
+     * When `autoFormat` is `true` (default), ranks are separated by `" > "` and
+     * tied candidates by `" = "`; when `false`, the most compact `>` / `=` form
+     * is emitted. An empty ranking yields the `/EMPTY_RANKING/` sentinel.
+     */
+    format(autoFormat = true) {
+        if (this.ranks.length === 0) {
+            return CefFormat.EMPTY_RANKING;
+        }
+        const rankSep = autoFormat ? ' > ' : '>';
+        const tieSep = autoFormat ? ' = ' : '=';
+        return this.ranks.map((rank) => rank.join(tieSep)).join(rankSep);
+    }
+    /**
+     * Render the ranking in its relaxed (auto-formatted) flavor.
+     */
+    toString() {
+        return this.format();
+    }
+    /**
+     * Split a cleaned ranking string into its raw, *un-validated* rank/tie
+     * structure. The `/EMPTY_RANKING/` sentinel maps to an empty list. Ranks are
+     * separated by `>`, tied candidates within a rank by `=`; every token is
+     * trimmed but not otherwise checked here.
+     */
+    static split(work) {
+        if (work === CefFormat.EMPTY_RANKING) {
+            return [];
+        }
+        const rawRanking = [];
+        for (const rankString of work.split('>')) {
+            const rank = [];
+            for (const candidate of rankString.split('=')) {
+                rank.push(candidate.trim());
+            }
+            rawRanking.push(rank);
+        }
+        return rawRanking;
+    }
+    /**
+     * @throws {CefFormatException}
+     */
+    static validate(ranks) {
+        const cleaned = [];
+        const seen = new Set();
+        ranks.forEach((rank, rankIndex) => {
+            if (rank.length === 0) {
+                throw new InvalidValueException(`Rank #${String(rankIndex + 1)} is empty.`);
+            }
+            const cleanedRank = [];
+            for (const candidate of rank) {
+                cleanedRank.push(Ranking.assertCandidate(candidate, seen));
+            }
+            cleaned.push(cleanedRank);
+        });
+        return cleaned;
+    }
+    /**
+     * Trim and validate a single candidate name, rejecting reserved characters,
+     * line breaks, invalid UTF-8 and duplicates. The `seen` set is updated to
+     * detect repeats across the whole ranking.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertCandidate(candidate, seen) {
+        const trimmed = candidate.trim();
+        CefFormat.assertValueIsClean(trimmed, 'Ranked candidate');
+        if (seen.has(trimmed)) {
+            throw new DuplicateCandidateException(`Candidate "${trimmed}" appears more than once in the ranking.`);
+        }
+        seen.add(trimmed);
+        return trimmed;
+    }
+}

package/dist/VoteLine.d.ts

@@ -0,0 +1,156 @@
+import { Ranking } from './Ranking';
+/**
+ * A single ballot.
+ *
+ * Instances are never built with `new`: use one of the static named
+ * constructors — {@link fromRanking} (typed ranks or a {@link Ranking}),
+ * {@link fromString} (a full CEF vote-line string), or
+ * {@link fromRawRankingString} (a pre-validated *verbatim* ranking string).
+ *
+ * The ranking is held as a {@link Ranking} value object on {@link ranking}. An
+ * empty ranking renders as the `/EMPTY_RANKING/` blank-ballot sentinel. In the
+ * verbatim mode the ranking string is written untouched and is *not* parsed,
+ * so {@link ranking} is `null`.
+ *
+ * Optional companions:
+ *   - `tags`          — labels separated by `,`, appended before `||`;
+ *   - `weight`        — strictly positive integer; only meaningful when the
+ *                       `Weight Allowed` parameter is enabled in the document;
+ *   - `quantifier`    — strictly positive integer that collapses identical
+ *                       votes onto a single line;
+ *   - `inlineComment` — free-form trailing comment introduced by `#`.
+ */
+export declare class VoteLine {
+    /**
+     * The parsed ranking, or `null` when the ballot was built from a verbatim
+     * ranking string via {@link fromRawRankingString} — in that mode the ranking
+     * is deliberately *not* parsed into a {@link Ranking} structure.
+     */
+    readonly ranking: Ranking | null;
+    /**
+     * Verbatim, pre-validated ranking string written to the output untouched.
+     * Set only in the {@link fromRawRankingString} mode; `null` otherwise (when
+     * {@link ranking} carries the parsed structure instead).
+     */
+    private readonly rawRanking;
+    readonly tags: readonly string[];
+    readonly weight: number | null;
+    readonly quantifier: number | null;
+    readonly inlineComment: string | null;
+    /**
+     * @internal Use a static named constructor instead: {@link fromRanking},
+     *           {@link fromString} or {@link fromRawRankingString}.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    private constructor();
+    /**
+     * Build a {@link VoteLine} from typed ranks or a ready-made {@link Ranking}.
+     *
+     * This is the primary, typed constructor. The `ranking` argument is either an
+     * ordered list of ranks (each inner list a non-empty group of tied
+     * candidates; pass `[]` for the `/EMPTY_RANKING/` blank ballot) or a
+     * {@link Ranking} value object.
+     *
+     * @throws {CefFormatException} on any specification violation
+     */
+    static fromRanking(ranking: readonly (readonly string[])[] | Ranking, options?: {
+        tags?: readonly string[];
+        weight?: number | null;
+        quantifier?: number | null;
+        inlineComment?: string | null;
+    }): VoteLine;
+    /**
+     * Build a {@link VoteLine} from a raw CEF vote-line string.
+     *
+     * Accepted shape — every component except the ranking is optional:
+     *
+     *     [tag1, tag2 || ] ranking [ ^weight] [ *quantifier] [# comment]
+     *
+     * Both the relaxed and the compact spacing flavors are accepted, e.g.
+     * `"A>B^7*2"` and `"A > B ^7 * 2"` parse identically. The `/EMPTY_RANKING/`
+     * sentinel is recognised as a blank ballot.
+     *
+     * The string is parsed into its components; the resulting `VoteLine` is then
+     * constructed through the normal constructor, so every validation rule
+     * (reserved characters, empty rank, duplicate candidate, positive weight /
+     * quantifier) applies.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromString(line: string): VoteLine;
+    /**
+     * Validate that `line` is a syntactically valid CEF vote line, without
+     * allocating a `VoteLine` instance.
+     *
+     * The exact same parsing and validation pipeline that {@link fromString} uses
+     * is applied — only the final object construction is skipped. Useful for hot
+     * paths that want to write a pre-built line straight to the output after a
+     * strict format check.
+     *
+     * @throws {CefFormatException}
+     */
+    static assertValidString(line: string): void;
+    /**
+     * Build a {@link VoteLine} from a ranking-only string, kept *verbatim*.
+     *
+     * The special, allocation-light sibling of {@link fromRanking}: the ranking
+     * string is validated as a ranking and *nothing else* — any reserved
+     * character (`^`, `*`, `#`, `;`, `,`, `/`), the `||` tag separator, or a line
+     * break is rejected, so it cannot smuggle a weight, quantifier, tag or inline
+     * comment — but it is **not** parsed into a {@link Ranking}. The string is
+     * stored as-is and written untouched by {@link format} (only the
+     * library-built companions — the `||` separator, `^weight`, `*quantifier` —
+     * follow `autoFormat`). The resulting instance therefore has a `null`
+     * {@link ranking}. Used by `Cef.addRawVote()`.
+     *
+     * @throws {CefFormatException}
+     */
+    static fromRawRankingString(ranking: string, options?: {
+        tags?: readonly string[];
+        weight?: number | null;
+        quantifier?: number | null;
+    }): VoteLine;
+    /**
+     * Shared parser+validator used by {@link fromString} and
+     * {@link assertValidString}.
+     *
+     * Trims the input, extracts every component, and runs the same per-field
+     * validation (reserved characters, empty rank, duplicate candidate, positive
+     * weight / quantifier, single-line comment) that the constructor performs.
+     * Returns the components.
+     *
+     * @throws {CefFormatException}
+     */
+    private static parseStringComponents;
+    /**
+     * Render the ballot — *without* trailing newline or inline comment — using
+     * the spacing flavor selected by `autoFormat`.
+     */
+    format(autoFormat?: boolean): string;
+    /**
+     * Return the ranking part of the line: the verbatim string in raw mode, or
+     * the parsed ranking rendered with `autoFormat` otherwise.
+     */
+    private renderRanking;
+    /**
+     * Reject a non-null, non-positive weight or quantifier.
+     *
+     * @throws {CefFormatException}
+     */
+    private static assertCompanions;
+    /**
+     * Wrap a ranking string with the tag prefix and the weight / quantifier
+     * suffix, using the spacing flavor selected by `autoFormat`.
+     */
+    private assembleLine;
+    /**
+     * @throws {CefFormatException}
+     */
+    private static validateTags;
+    /**
+     * Strip trailing whitespace, mirroring PHP's `rtrim()`.
+     */
+    private static rtrim;
+}
+//# sourceMappingURL=VoteLine.d.ts.map

package/dist/VoteLine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VoteLine.d.ts","sourceRoot":"","sources":["../src/VoteLine.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,QAAQ;IACnB;;;;OAIG;IACH,SAAgB,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IAExC;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAE3C,SAAgB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAExC,SAAgB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAEtC,SAAgB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAE1C,SAAgB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7C;;;;;OAKG;IACH,OAAO;IAwCP;;;;;;;;;OASG;WACW,WAAW,CACvB,OAAO,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,GAAG,OAAO,EACjD,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC1B,GACL,QAAQ;IAWX;;;;;;;;;;;;;;;;;OAiBG;WACW,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ;IAahD;;;;;;;;;;OAUG;WACW,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAInD;;;;;;;;;;;;;;OAcG;WACW,oBAAoB,CAChC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,GACL,QAAQ;IAUX;;;;;;;;;;OAUG;IACH,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAgFpC;;;OAGG;IACI,MAAM,CAAC,UAAU,UAAO,GAAG,MAAM;IAIxC;;;OAGG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;OAIG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B;;;OAGG;IACH,OAAO,CAAC,YAAY;IAsBpB;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,YAAY;IAkB3B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,KAAK;CAGrB"}