@floh-solutions/pharos-cli 0.23.0 → 0.25.0

package/dist/issue-scan.js

@@ -0,0 +1,455 @@
+import { normalizeRepo } from "@floh-solutions/gh-core";
+import { FALLBACK_TERMINAL_STATES } from "./wiql-build.js";
+/**
+ * The join behind `pharos issue drift` and `pharos issue backfill`, with no I/O
+ * in it.
+ *
+ * **Separate from the command for the same reason `wiql-build.ts` is** — this is
+ * where the bugs are. Every interesting question here is a comparison between
+ * two records that came from two different systems, and comparisons are exactly
+ * what can be proved without a network: which spelling of a repository counts as
+ * the same repository, what "still open" means on a board that renamed its
+ * states, whether one piece of evidence on each of two layers is one link or
+ * two. The command file around this reads, calls, and prints.
+ *
+ * ## The one idea both verbs are built on
+ *
+ * **The Azure DevOps side is the enumerable one, and that is what makes a
+ * 400-issue repository affordable.**
+ *
+ * GitHub cannot answer "which of my issues has Pharos adopted" — the answer
+ * lives in a comment on each issue, so asking costs one request per issue and a
+ * backfill would spend four hundred requests deciding what to do before doing
+ * anything. Azure DevOps *can*: a work item carries its `Hyperlink` relations on
+ * its own row, so one WIQL plus one `workitemsbatch` returns every link on the
+ * board at once.
+ *
+ * That index is correct as an answer to "what is already adopted" because
+ * `adopt` writes the Azure DevOps end **first** (`issue.ts` ▸ the write order).
+ * The half-state it can leave is a hyperlink with no comment, never a comment
+ * with no hyperlink — so an issue missing from this index was either never
+ * adopted, or adopted by something that died before its first write. Both mean
+ * the same thing to a backfill.
+ *
+ * The mirror-image state is still possible if somebody deletes the relation by
+ * hand, and it is why {@link backfillCandidates} produces *candidates* rather
+ * than a work list: the per-issue marker read that would catch it happens at
+ * adoption time, on the handful being written, instead of on all four hundred.
+ *
+ * ## Two traps peers already paid for
+ *
+ * 1. **Repositories are compared on {@link normalizeRepo}, never with `===`.**
+ *    GitHub resolves a repository case-insensitively and echoes back whatever
+ *    spelling it was created with, so `Contoso/Widgets` and `contoso/widgets`
+ *    are one repository and two strings. The app track reported a perfectly good
+ *    link as half-written over exactly this (#787).
+ * 2. **Evidence is counted nowhere.** `["marker","mention"]` is two pieces of
+ *    evidence and one side — both are GitHub's — so a link with no `Hyperlink`
+ *    at all passes a length check (#782 found this in its own code). Whether
+ *    both platforms carry a link is `gh-core`'s `isTwoSided`, and whether the
+ *    GitHub half was even *looked at* is {@link IssueSide.markers} being present
+ *    rather than empty.
+ */
+// MARK: - which work items to look at
+/**
+ * The statement `drift` runs when nobody passed `--wiql`.
+ *
+ * **BOTH `System.HyperLinkCount` AND `System.ExternalLinkCount`, and the reason
+ * this reads as belt-and-braces is that it once was neither.**
+ *
+ * This narrowed on `ExternalLinkCount` alone, on the stated grounds that it was
+ * the *broader* filter and that a false negative here is far worse than a false
+ * positive. The asymmetry argument is right. The premise was wrong, and it made
+ * the command silently useless: **the two counters are disjoint, not nested.**
+ * Azure DevOps counts each relation kind separately —
+ * `RelatedLinkCount` (work item ↔ work item), `HyperLinkCount` (a plain
+ * `Hyperlink`), `ExternalLinkCount` (an `ArtifactLink`: a commit, PR or build),
+ * `AttachedFileCount`.
+ *
+ * `adopt` writes a **`Hyperlink`** — it must, because minting the native
+ * `vstfs:///GitHub/Issue/…` artifact URI needs a connection id that is behind a
+ * 401 on our scopes (§2). So every pair this tool creates increments
+ * `HyperLinkCount` and leaves `ExternalLinkCount` at zero, and the old default
+ * could **never** see a link Pharos had made. It answered "no drift" forever,
+ * exit 0, which is the failure mode a drift detector must not have.
+ *
+ * Measured on the live board (#801, re-verified): an adopted pair read
+ * `HyperLinkCount 1, ExternalLinkCount 0`, and the two work items that DID
+ * match `ExternalLinkCount > 0` each carried an `ArtifactLink` and no
+ * `Hyperlink`.
+ *
+ * Both are kept rather than swapping one for the other, because a client whose
+ * org *does* have the Azure Boards GitHub connection gets a native artifact
+ * link in addition to ours (§2) — narrowing to hyperlinks alone would then miss
+ * exactly the boards that are best integrated.
+ *
+ * There is no way to ask WIQL about the *contents* of a relation — it queries
+ * fields, and a `Hyperlink`'s URL is not one. So this narrows to work items that
+ * have external links at all and the URLs are parsed afterwards, in
+ * {@link linksOnWorkItems}.
+ *
+ * `[System.TeamProject] = @project` is not redundant with the project in the
+ * URL: WIQL happily returns items from every project the token can read, and a
+ * drift report that reached across an organisation would be answering a question
+ * nobody asked. Same argument `buildWiql` already makes.
+ */
+export function driftWiql() {
+    return ("SELECT [System.Id] FROM WorkItems"
+        + " WHERE [System.TeamProject] = @project"
+        + " AND ([System.HyperLinkCount] > 0 OR [System.ExternalLinkCount] > 0)"
+        + " ORDER BY [System.ChangedDate] DESC");
+}
+/**
+ * The statement `adopt` runs **before creating anything**, to find a work item
+ * that already links the issue in front of it.
+ *
+ * ## Why this is not `driftWiql`
+ *
+ * Two narrower choices, and both are the point.
+ *
+ * **`HyperLinkCount` alone.** `drift` asks "is any link here broken", so it
+ * takes both counters — a client whose organisation *does* have the Azure
+ * Boards connection gets a native `ArtifactLink` in addition to ours, and
+ * missing those would miss the best-integrated boards. This asks a different
+ * question: *did Pharos already adopt this issue*, and Pharos writes a
+ * `Hyperlink`, always, because the connection id an artifact link needs is
+ * behind a 401 on our scopes (§2). So `ExternalLinkCount` here would add every
+ * work item that ever had a commit, a PR or a build attached — which on a real
+ * board is most of them — to a query that runs on the way to a single
+ * adoption. Measured on the live board (#801): the adopted pair answered
+ * `HyperLinkCount 1, ExternalLinkCount 0`, and `[System.HyperLinkCount] > 0`
+ * returned it while `[System.ExternalLinkCount] > 0` returned two other items
+ * and not it.
+ *
+ * **Capped, newest first.** `drift` is a deliberate sweep and reads the whole
+ * board; this is a guard on a one-issue verb and must not turn it into one. The
+ * state it exists to catch is a work item written minutes ago, so ordering by
+ * `ChangedDate` descending and stopping at {@link ADOPT_GUARD_LIMIT} keeps the
+ * cost flat while looking exactly where the answer is. A board with more
+ * hyperlinked work items than that is not a wrong answer — it is a partial one,
+ * and `adopt` says so rather than reporting a clean check.
+ *
+ * There is still no way to ask WIQL about the *contents* of a relation, so the
+ * URLs are matched afterwards, client-side, by {@link claimsOn}. That is the
+ * same narrow-then-filter shape `drift` uses and the same reason.
+ */
+export function adoptGuardWiql() {
+    return ("SELECT [System.Id] FROM WorkItems"
+        + " WHERE [System.TeamProject] = @project"
+        + " AND [System.HyperLinkCount] > 0"
+        + " ORDER BY [System.ChangedDate] DESC");
+}
+/**
+ * How many hyperlinked work items `adopt`'s guard looks at. Two
+ * `workitemsbatch` calls at the 200-per-request chunk, on top of the WIQL.
+ */
+export const ADOPT_GUARD_LIMIT = 400;
+/**
+ * Every GitHub issue link on a batch of work items, flattened.
+ *
+ * `hyperlinks` is a function rather than a field because reading relations off a
+ * `WorkItem` is the command's business — this file is not allowed to care what
+ * shape Azure DevOps returns.
+ */
+export function linksOnWorkItems(items, describe, hyperlinks) {
+    const out = [];
+    for (const item of items) {
+        const workItem = describe(item);
+        for (const link of hyperlinks(item)) {
+            out.push({
+                workItem,
+                repo: normalizeRepo(link.repo),
+                spelling: link.repo,
+                issueNumber: link.issueNumber,
+            });
+        }
+    }
+    return out;
+}
+/**
+ * The links that name one particular issue — "who on this board already claims
+ * it".
+ *
+ * Compared on {@link normalizeRepo}, never with `===`: GitHub resolves a
+ * repository case-insensitively and echoes back whichever spelling it was
+ * created with, so a `Hyperlink` written as `Contoso/Widgets` and a coordinate
+ * typed as `contoso/widgets` are one issue and two strings. #787 reported a
+ * perfectly good link as half-written over exactly this, and here the same slip
+ * would be worse: it would report *no* claim, and a second work item is what
+ * follows from that.
+ */
+export function claimsOn(links, coordinate) {
+    const repo = normalizeRepo(coordinate.repo);
+    return links.filter((link) => link.repo === repo && link.issueNumber === coordinate.number);
+}
+/** The repositories a set of links touches, lower-cased and de-duplicated. */
+export function reposOf(links) {
+    return [...new Set(links.map((link) => link.repo))].sort();
+}
+/** The catalogue as this file needs it, or the stock names with a warning attached. */
+export function finishedStates(catalog, failure) {
+    if (catalog === undefined) {
+        return {
+            source: "fallback",
+            terminal: FALLBACK_TERMINAL_STATES,
+            byType: new Map(),
+            ambiguous: [],
+            note: "COULD NOT read this project's state categories"
+                + (failure === undefined ? "" : ` (${failure})`)
+                + ", so these are Azure DevOps' stock names. A project that renames its states will have "
+                + "work items misclassified here — treat a state drift row as a question rather than a "
+                + "finding until this reads.",
+        };
+    }
+    return {
+        source: "categories",
+        terminal: catalog.terminal,
+        byType: new Map([...catalog.byType].map(([type, states]) => [type, states.terminal])),
+        ambiguous: catalog.ambiguous,
+        note: "Read from this project's own state categories, so it is right whatever the process "
+            + "template calls things."
+            + (catalog.ambiguous.length === 0
+                ? ""
+                : ` ${catalog.ambiguous.join(", ")} mean different things on different work item types, `
+                    + "so each work item was judged against its own."),
+    };
+}
+/**
+ * Is this work item finished?
+ *
+ * **Its own type's list first**, because that is the whole reason `StateCatalog`
+ * carries `byType`: `Resolved` can be terminal on a Bug and open on a User
+ * Story, and one flat list gets one of them wrong. The flat list is the fallback
+ * for a type the catalogue does not know — a work item type added since, or a
+ * batch that came back with no `System.WorkItemType` at all.
+ *
+ * **An unknown state counts as open**, matching `stateCatalog`'s own rule and
+ * for its reason: the two mistakes are not equal. Calling a finished work item
+ * open puts a row in front of somebody who can dismiss it; calling an open one
+ * finished hides drift, which is the one thing this command exists to surface.
+ */
+export function isFinished(states, type, state) {
+    if (state === null || state === "")
+        return false;
+    const perType = type === null ? undefined : states.byType.get(type);
+    if (perType !== undefined)
+        return perType.includes(state);
+    return states.terminal.includes(state);
+}
+export function terminalStateFor(states, type) {
+    // The catalogue could not be read at all. `drift` degrades to the stock names
+    // because a misclassified ROW is a question somebody can dismiss; here the
+    // same guess would be a WRITE, so it refuses instead.
+    if (states.source === "fallback")
+        return { kind: "unknown" };
+    const perType = type === null ? undefined : states.byType.get(type);
+    const candidates = perType ?? states.terminal;
+    if (candidates.length === 0)
+        return { kind: "none" };
+    if (candidates.length === 1)
+        return { kind: "one", state: candidates[0] };
+    return { kind: "several", states: [...candidates].sort() };
+}
+/**
+ * Judge one link.
+ *
+ * **Order matters, and it is worst-first.** A pair whose issue cannot be read
+ * has no state to compare and no marker to look for, so reporting it as three
+ * problems would be reporting one problem three times — and the three rows would
+ * not even agree, because two of them would be inferred from an absence. Each
+ * link produces at most one row.
+ */
+export function judgeLink(link, side, states) {
+    const coordinate = `${link.spelling}#${link.issueNumber}`;
+    const base = { workItem: link.workItem, coordinate, issue: null };
+    if (side.missing === true) {
+        return {
+            healthy: false,
+            drift: {
+                ...base,
+                kind: "missing-issue",
+                evidence: ["hyperlink"],
+                detail: `Work item #${link.workItem.id} links ${coordinate}, and GitHub says there is no such `
+                    + "issue. It was deleted, transferred to another repository, or the link was written "
+                    + "with the wrong number.",
+                ...(side.problem === undefined ? {} : { problem: side.problem }),
+            },
+        };
+    }
+    if (side.issue === undefined) {
+        return {
+            healthy: false,
+            drift: {
+                ...base,
+                kind: "unreadable",
+                evidence: ["hyperlink"],
+                problem: side.problem ?? "the issue could not be read",
+                detail: `Work item #${link.workItem.id} links ${coordinate} and that repository could not be `
+                    + "read from this machine, so nothing about this pair was checked. This is usually a "
+                    + "repository nobody here is bound to — somebody else adopted it, configured "
+                    + "differently — which is information rather than a fault.",
+            },
+        };
+    }
+    const issue = { ...side.issue, coordinate };
+    const evidence = ["hyperlink"];
+    let marked = false;
+    if (side.markers !== undefined) {
+        // Only markers naming THIS work item count. An issue carrying a marker for
+        // some other work item is not this link's other half, and taking it as one
+        // would report a genuinely broken pair as complete.
+        for (const found of side.markers) {
+            if (found.workItemId !== link.workItem.id)
+                continue;
+            for (const piece of found.evidence) {
+                if (piece === "hyperlink")
+                    continue;
+                if (!evidence.includes(piece))
+                    evidence.push(piece);
+                marked = true;
+            }
+        }
+    }
+    evidence.sort();
+    // Checked before the state comparison because a half-written link is a fact
+    // about the LINK, and the state comparison is a fact about the work — a pair
+    // that is both gets reported as the one somebody has to fix first.
+    if (side.markers !== undefined && !marked) {
+        return {
+            healthy: false,
+            drift: {
+                ...base,
+                kind: "one-sided",
+                missing: "marker",
+                issue,
+                evidence,
+                detail: `Work item #${link.workItem.id} links ${coordinate} and nothing on the issue says so. `
+                    + "The reporter cannot see that anybody picked this up, and no sweep starting from "
+                    + "GitHub will find the work item. This is what a failed `adopt` leaves behind.",
+                recover: `pharos issue link ${coordinate} ${link.workItem.id}`,
+            },
+        };
+    }
+    const finished = isFinished(states, link.workItem.type, link.workItem.state);
+    const closed = side.issue.state === "closed";
+    if (closed && !finished) {
+        return {
+            healthy: false,
+            drift: {
+                ...base,
+                kind: "state",
+                direction: "issue-closed",
+                issue,
+                evidence,
+                detail: `${coordinate} is closed${side.issue.stateReason === null ? "" : ` (${side.issue.stateReason})`}`
+                    + ` and work item #${link.workItem.id} is ${describeState(link.workItem.state)}. Either `
+                    + "the board has not caught up, or it was closed on GitHub without the work being done.",
+            },
+        };
+    }
+    if (!closed && finished) {
+        return {
+            healthy: false,
+            drift: {
+                ...base,
+                kind: "state",
+                direction: "work-item-finished",
+                issue,
+                evidence,
+                detail: `Work item #${link.workItem.id} is ${describeState(link.workItem.state)} and `
+                    + `${coordinate} is still open. The reporter has not been told it is done — this is the `
+                    + "one that is rude on a public repository.",
+            },
+        };
+    }
+    return { healthy: true };
+}
+function describeState(state) {
+    return state === null || state === "" ? "in an unnamed state" : `in "${state}"`;
+}
+/** The counts a drift report leads with, so nobody has to tally the rows. */
+export function tallyDrift(rows) {
+    const counts = {
+        state: 0,
+        "missing-issue": 0,
+        "one-sided": 0,
+        unreadable: 0,
+    };
+    for (const row of rows)
+        counts[row.kind] += 1;
+    return counts;
+}
+/**
+ * Which issues in a repository the board has never heard of.
+ *
+ * `linked` is the set of issue numbers already reached by a `Hyperlink` — the
+ * index this file's header argues for, and the reason this costs two Azure
+ * DevOps calls instead of one GitHub call per issue.
+ *
+ * **Ordered by issue number ascending**, which is a decision rather than an
+ * accident. The sweep arrives in `updated_at` order, so taking the first `n` of
+ * *that* would adopt a different set every run as issues get touched — and a
+ * `--limit` that means something different each time is a `--limit` nobody can
+ * resume against. Oldest issue first is stable, obvious, and makes a second run
+ * carry on where the first stopped.
+ */
+export function backfillCandidates(issues, linked) {
+    return issues
+        .filter((issue) => !linked.has(issue.number))
+        .sort((left, right) => left.number - right.number);
+}
+/** The issue numbers already linked from the board, for one repository. */
+export function linkedNumbersIn(links, repo) {
+    const wanted = normalizeRepo(repo);
+    return new Set(links.filter((link) => link.repo === wanted).map((link) => link.issueNumber));
+}
+/** How many writes adopting `count` issues costs. One create, one comment, each. */
+export const WRITES_PER_ADOPTION = 2;
+// MARK: - running the reads
+/**
+ * Run `work` over `items`, at most `limit` at a time, keeping the input order.
+ *
+ * `drift` reads two endpoints per link and a board with four hundred of them is
+ * the case this milestone exists for, so doing them one at a time is minutes of
+ * waiting. `Promise.all` over all of them is the other extreme and it is worse:
+ * GitHub's secondary rate limit is explicitly about concurrency rather than
+ * volume, and tripping it turns a diagnostic into an hour's ban on a token
+ * somebody else is also using.
+ *
+ * Rejections are **not** caught here. A caller that wants a failed read to
+ * become a row rather than an exception says so in `work` — which `drift` does,
+ * because one unreadable repository must not kill a sweep (#782).
+ */
+export async function inBatches(items, limit, work) {
+    const results = new Array(items.length);
+    let next = 0;
+    const runner = async () => {
+        for (;;) {
+            const index = next++;
+            if (index >= items.length)
+                return;
+            results[index] = await work(items[index], index);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));
+    return results;
+}
+/** How many issue reads `drift` has in flight at once. */
+export const READ_CONCURRENCY = 6;
+/**
+ * A WIQL failure that names the field this file introduced.
+ *
+ * `System.ExternalLinkCount` is queryable on every process template Azure DevOps
+ * ships, and this has not been run against a customised one. If a project
+ * somehow does not expose it the statement fails to parse, which reads as "drift
+ * is broken" — so the error says which clause is suspect and hands over the
+ * escape hatch `pharos query` already established.
+ */
+export function looksLikeWiqlRejection(message) {
+    const text = message.toLowerCase();
+    return (text.includes("externallinkcount")
+        || text.includes("wiql")
+        || text.includes("does not exist")
+        || text.includes("is not recognized"));
+}
+//# sourceMappingURL=issue-scan.js.map

package/dist/issue-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"issue-scan.js","sourceRoot":"","sources":["../src/issue-scan.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -27,7 +27,9 @@ export declare const EXIT_FAILED = 1;
 export declare const EXIT_USAGE = 2;
 export declare const EXIT_REFUSED = 3;
 export type ExitCode = 0 | 1 | 2 | 3;
-export type ErrorKind = "usage" | "config" | "auth" | "refused" | "conflict" | "notFound" | "rateLimit" | "network" | "ado" | "internal";
+export type ErrorKind = "usage" | "config" | "auth" | "refused" | "conflict" | "notFound" | "rateLimit" | "network" | "ado"
+/** GitHub said no, and none of the kinds above describe it more usefully. */
+ | "github" | "internal";
 export interface Io {
     stdout: (line: string) => void;
     stderr: (line: string) => void;
@@ -84,4 +86,19 @@ export declare function emitText(io: Io, text: string): ExitCode;
  *     repeating the identical call is correct.
  */
 export declare function reportError(io: Io, error: unknown): ExitCode;
+/**
+ * The same classification `reportError` uses, without emitting anything.
+ *
+ * For the one shape that needs it: a verb that has **already written one half of
+ * something** when the second half fails. `pharos issue adopt` creates the work
+ * item and then comments on the issue, so a failure at the second step must
+ * report the first step's result rather than only the error — otherwise the work
+ * item exists and nothing anywhere names it. Re-classifying by hand there would
+ * be a second, drifting copy of this table.
+ */
+export declare function failureOf(error: unknown): {
+    kind: ErrorKind;
+    code: ExitCode;
+    body: Record<string, unknown>;
+};
 //# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErC,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,UAAU,GACV,UAAU,GACV,WAAW,GACX,SAAS,GACT,KAAK,GACL,UAAU,CAAC;AAEf,MAAM,WAAW,EAAE;IACjB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,QAAQ;gBAGtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQvC;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAGrD;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAI5D"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErC,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,UAAU,GACV,UAAU,GACV,WAAW,GACX,SAAS,GACT,KAAK;AACP,6EAA6E;GAC3E,QAAQ,GACR,UAAU,CAAC;AAEf,MAAM,WAAW,EAAE;IACjB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,QAAQ;gBAGtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQvC;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAGrD;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAI5D;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG;IACzC,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,CAGA"}