@crewhaus/tool-pkgmgr 0.7.0

package/dist/lib/parse.d.ts

@@ -0,0 +1,308 @@
+/**
+ * Every parser in this package, and nothing else.
+ *
+ * Each one takes a string that a real manager printed — recorded in
+ * `../fixtures.ts` — and returns a shape, or `undefined` when the bytes are
+ * not what it was told to expect. None of them reads the host, none of them
+ * spawns anything, and none of them guesses: a parser that cannot find what
+ * it is looking for says so, and the caller turns that into an `unknown` with
+ * a reason rather than into a `false`.
+ *
+ * Two traps recur across the six managers and are worth stating once.
+ *
+ * LOCALISATION. `apt-cache policy`, `dnf`, `pacman -Si` and `brew` all
+ * translate their labels through gettext. Every parser below reads ENGLISH
+ * keywords, which is sound only because `../run.ts` pins `LC_ALL=C` on every
+ * child. If that pin is ever removed these parsers do not fail loudly — they
+ * find nothing, and "nothing" reads as "not installed". The suite includes a
+ * German `apt-cache policy` capture precisely so that failure has a name.
+ *
+ * COLUMN OUTPUT. `winget list` and `dnf list` print aligned columns, and a
+ * column layout is not a data format. winget truncates a wide field with an
+ * ellipsis (U+2026) and pads with spaces indistinguishable from the
+ * separator, so the parser below refuses a row it cannot split unambiguously
+ * rather than returning a version that is a prefix of the real one.
+ */
+/** Split into lines, tolerating CRLF from a Windows manager. */
+export declare function lines(text: string): string[];
+export type BrewEntry = {
+    readonly name: string;
+    readonly kind: "formula" | "cask";
+    /** Versions on disk, as brew prints them. Empty when absent. */
+    readonly installedVersions: readonly string[];
+    /** What the tap currently offers, or null when the document omits it. */
+    readonly stableVersion: string | null;
+    readonly pinned: boolean;
+    readonly outdated: boolean;
+    readonly dependencies: readonly string[];
+    readonly tap: string | null;
+};
+export type BrewInfo = {
+    readonly formula?: BrewEntry;
+    readonly cask?: BrewEntry;
+};
+/**
+ * `brew info --json=v2` — the one call that answers both halves of a query.
+ *
+ * The document always has both arrays, and a name resolves into exactly one
+ * of them, so a caller does not have to know whether it is asking about a
+ * formula or a cask before it asks. A cask spells everything differently
+ * (`token` not `name`, a scalar `version` not a `versions` object, a scalar
+ * `installed` not an array), which is why the two are normalised here rather
+ * than at the call site.
+ *
+ * Returns `undefined` when the bytes are not a v2 document at all — which is
+ * what a failed `brew` prints, and must not be read as "no such package".
+ */
+export declare function parseBrewInfoJson(stdout: string): BrewInfo | undefined;
+/**
+ * `brew list --formula --versions` — `name version [version…]`, one per line.
+ *
+ * A keg-only formula with several versions kegged prints all of them, which
+ * is why the value is an array: reporting the first as "the" installed
+ * version would be wrong for exactly the formulae (python@3.x, openssl@3) a
+ * caller is most likely to ask about.
+ */
+export declare function parseBrewListVersions(stdout: string): Map<string, string[]>;
+/** `brew deps --formula <name>` — one dependency per line, already transitive. */
+export declare function parseBrewDeps(stdout: string): string[];
+/**
+ * Homebrew's own "no such package" signal.
+ *
+ * Recorded verbatim: `brew info --json=v2 nope-nope` exits 1 and prints
+ * `Error: No available formula with the name "nope-nope".` on stderr.
+ * Matching that specific sentence rather than "exit code 1" is what keeps a
+ * tap that failed to load from being reported as a missing package.
+ */
+export declare function brewSaysNoSuchPackage(stderr: string): boolean;
+export type DpkgRow = {
+    readonly name: string;
+    readonly version: string;
+    /** dpkg's status abbreviation, e.g. "ii", "un", "rc". */
+    readonly statusAbbrev: string;
+};
+/**
+ * `dpkg-query -W -f='${binary:Package}\t${Version}\t${db:Status-Abbrev}\n'`.
+ *
+ * Tab-separated because a Debian version can contain almost anything except a
+ * tab, and named fields because the abbrev's first character is the fact that
+ * matters: `i` means the files are on disk, while `u` (unknown) and `r`
+ * (removed, config files left) are packages dpkg KNOWS ABOUT but does not
+ * have installed. An `rc` package read as installed is the classic dpkg
+ * mistake — the binary is gone and only `/etc` remains.
+ */
+export declare function parseDpkgQuery(stdout: string): DpkgRow[];
+/** True when dpkg's status abbreviation means the package is actually on disk. */
+export declare function dpkgStatusIsInstalled(abbrev: string): boolean;
+/** dpkg's own "I have never heard of this package" signal, on stderr. */
+export declare function dpkgSaysNoSuchPackage(stderr: string): boolean;
+export type AptPolicy = {
+    readonly installed: string | null;
+    readonly candidate: string | null;
+};
+/**
+ * `apt-cache policy <name>` under `LC_ALL=C`.
+ *
+ *     curl:
+ *       Installed: 7.81.0-1ubuntu1.15
+ *       Candidate: 7.81.0-1ubuntu1.16
+ *       Version table: …
+ *
+ * `(none)` is apt's word for "not installed" and becomes `null` here — which
+ * is a DIFFERENT null from "the label was not found at all", and the caller
+ * tells them apart by whether the parse returned undefined.
+ *
+ * An unknown package produces an empty document (apt-cache prints nothing and
+ * exits 0), which parses to `undefined` rather than to two nulls, so "apt has
+ * never heard of this" cannot be confused with "apt has it, not installed".
+ */
+export declare function parseAptCachePolicy(stdout: string): AptPolicy | undefined;
+export type AptSimulatedChange = {
+    readonly action: "install" | "remove";
+    readonly name: string;
+    readonly version: string | null;
+};
+/**
+ * `apt-get install -s` — the best dry run of the six managers.
+ *
+ * It resolves the whole transaction without root and prints a line per
+ * package:
+ *
+ *     Inst libnghttp2-14 (1.43.0-1 Debian:12 [amd64])
+ *     Inst curl [7.88.1-10] (7.88.1-10+deb12u5 Debian-Security:12 [amd64])
+ *     Conf curl (7.88.1-10+deb12u5 Debian-Security:12 [amd64])
+ *     Remv oldthing [1.0-1]
+ *
+ * `Conf` lines are dropped: they name the same packages as `Inst`, and
+ * counting both would double every transitive addition. `Remv` is kept,
+ * because a transaction that REMOVES something is exactly the case an
+ * operator has to see before approving an install. The optional `[old]`
+ * bracket between the name and the parenthesis is what an UPGRADE looks like,
+ * and is skipped so the version reported is the one being installed.
+ */
+export declare function parseAptSimulate(stdout: string): AptSimulatedChange[];
+/** apt's "there is no such package" signal, which it prints on stderr. */
+export declare function aptSaysNoSuchPackage(stderr: string): boolean;
+/** apt's "you are not root" signal. */
+export declare function aptSaysNeedsRoot(text: string): boolean;
+export type RpmRow = {
+    readonly name: string;
+    /** epoch:version-release, as rpm's `%{EVR}` renders it. */
+    readonly evr: string;
+    readonly arch: string;
+};
+/**
+ * `rpm -q --queryformat '%{NAME}\t%{EVR}\t%{ARCH}\n' <name>`.
+ *
+ * rpm prints "package foo is not installed" on STDOUT (not stderr) and exits
+ * 1, so that sentence has to be filtered out of the rows rather than detected
+ * by exit code alone — a query for several names prints some rows and some of
+ * those sentences in the same stream.
+ */
+export declare function parseRpmQuery(stdout: string): RpmRow[];
+/** rpm's own not-installed sentence, which it prints on stdout. */
+export declare function rpmSaysNotInstalled(stdout: string): boolean;
+export type DnfListRow = {
+    readonly name: string;
+    readonly arch: string;
+    readonly version: string;
+    readonly repo: string;
+};
+/**
+ * `dnf list --available <name>` — three columns, `name.arch version repo`.
+ *
+ * Header lines ("Available Packages", "Last metadata expiration check: …")
+ * are skipped by SHAPE rather than by text: a line qualifies only when it
+ * splits into exactly three whitespace-separated fields, the first contains a
+ * `.` separating a name from an architecture, and the second starts with a
+ * digit. Matching on the header text would break the moment dnf renames it,
+ * and dnf5 did exactly that.
+ */
+export declare function parseDnfList(stdout: string): DnfListRow[];
+/**
+ * dnf's "the cache is empty and I was told not to fetch" complaint.
+ *
+ * This is the difference between "not in the repositories" and "I do not
+ * know", and `--cacheonly` makes the second common on a fresh container.
+ */
+export declare function dnfSaysNoCache(text: string): boolean;
+/** dnf's own "no such package" signal. */
+export declare function dnfSaysNoMatch(text: string): boolean;
+/** dnf's "you are not root" signal — checked before a transaction is read. */
+export declare function dnfSaysNeedsRoot(text: string): boolean;
+export type DnfTransactionRow = {
+    readonly name: string;
+    readonly arch: string;
+    readonly version: string;
+    readonly repo: string;
+};
+/**
+ * The transaction table `dnf install --assumeno` prints before it declines.
+ *
+ *     Installing:
+ *      tree            x86_64   1.8.0-10.el9    baseos    55 k
+ *     Installing dependencies:
+ *      libfoo          x86_64   1.2-3           baseos    10 k
+ *
+ * Section headers are matched on the English words, which is sound under the
+ * pinned `LC_ALL=C` and nowhere else. A row must have at least five fields;
+ * the size is two of them ("55 k") and is dropped, since a caller who wants a
+ * download total has dnf's own summary line.
+ */
+export declare function parseDnfTransaction(stdout: string): DnfTransactionRow[];
+export type PacmanRow = {
+    readonly name: string;
+    readonly version: string;
+};
+/** `pacman -Q <name>` — `name version`, one per line. */
+export declare function parsePacmanQuery(stdout: string): PacmanRow[];
+/**
+ * `pacman -Si <name>` — a `Key : Value` block with indented continuations.
+ *
+ * Only the FIRST block is read: a name that matches in two repositories
+ * prints two blocks, and merging them would report `extra`'s version against
+ * `core`'s repository. The caller reports the first block and says the name
+ * was ambiguous.
+ */
+export declare function parsePacmanInfo(stdout: string): Map<string, string>;
+export type PacmanTarget = {
+    readonly repo: string | null;
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * `pacman -S --print --print-format '%r/%n %v'` — every target, dependencies
+ * included, with versions, no root and no transaction.
+ *
+ * A package coming from a local file rather than a repository prints an empty
+ * repo, which becomes `null` rather than a made-up repository name.
+ */
+export declare function parsePacmanSimulate(stdout: string): PacmanTarget[];
+/** pacman's own "no such package" signal. */
+export declare function pacmanSaysNoSuchPackage(stderr: string): boolean;
+/** pacman's "you are not root" signal. */
+export declare function pacmanSaysNeedsRoot(text: string): boolean;
+export type WingetRow = {
+    readonly name: string;
+    readonly id: string;
+    /** null when the row could not be split safely — see `parseWingetList`. */
+    readonly version: string | null;
+    readonly available: string | null;
+    /** Why `version` or `available` is null, when it is. */
+    readonly unparsedReason?: string;
+};
+/**
+ * `winget list --exact --query <name>` — an aligned table, which is not a
+ * data format.
+ *
+ * winget has no JSON output for `list`. The survey sketch proposed splitting
+ * by the header's character offsets; that is wrong, and this is the improved
+ * version. Offsets break on two things winget does routinely: it TRUNCATES a
+ * field that does not fit and marks the cut with `…`, and it pads with
+ * ordinary spaces, so a CJK or emoji display name — double-width in the
+ * console but one or two UTF-16 code units in the string — shifts every
+ * offset after it. A version read from a shifted offset is not an error, it
+ * is a WRONG VERSION, which is the worst answer a query tool can give.
+ *
+ * So rows are split on runs of TWO OR MORE spaces (one space is inside a
+ * display name; two is padding), and a row is refused rather than guessed at
+ * when it does not split cleanly:
+ *
+ *   - any field containing `…` was truncated, so nothing in the row is
+ *     trusted;
+ *   - fewer than three fields is not a `Name Id Version` row at all;
+ *   - the column ORDER is fixed across locales (`Name Id Version [Available]
+ *     Source`) even though the header TEXT is localised, so position 2 is the
+ *     installed version — but position 3 is ambiguous: a four-field row is
+ *     either `…Version Source` or `…Version Available`, with no way to tell.
+ *     Four fields therefore yields a null `available` with a reason.
+ */
+export declare function parseWingetList(stdout: string): WingetRow[];
+/**
+ * winget's "no installed package matched" exit code, 0x8A15002B as a signed
+ * 32-bit integer.
+ *
+ * `winget list` exits with this rather than 0-and-empty, which makes presence
+ * decidable from the EXIT CODE alone — the one part of winget's answer that
+ * is neither localised nor column-aligned.
+ */
+export declare const WINGET_NO_PACKAGES_FOUND = -1978335189;
+/**
+ * `choco list --limit-output` — `name|version`, one per line, no header.
+ *
+ * `--limit-output` is chocolatey's documented machine-readable mode and the
+ * reason choco is the easiest of the six to read. A trailing summary line
+ * ("2 packages installed.") does not appear in this mode, and is dropped by
+ * shape anyway in case an older build prints one.
+ */
+export declare function parseChocoList(stdout: string): PacmanRow[];
+/**
+ * The major version of `choco --version`.
+ *
+ * Chocolatey 2.0 removed `--local-only` from `choco list`, so which flags are
+ * legal depends on this number. Guessing would mean either an unknown-option
+ * error on v2 or a REMOTE search on v1 — and a remote search answering "yes,
+ * 8.7.1" for a package that is not installed at all is precisely the wrong
+ * answer this package exists to avoid.
+ */
+export declare function parseChocoMajorVersion(stdout: string): number | undefined;