@codyswann/lisa 4.27.5 → 4.27.7

package/dist/core/enforcement-census.js

@@ -0,0 +1,252 @@
+/**
+ * The fleet census: how many checkouts resolve enforcement, re-derived on
+ * every run.
+ *
+ * The per-session staleness notice reports **this** checkout to **this**
+ * session, and it is right to do so — it keeps running while stale, and it
+ * prints once per session rather than per call, both deliberately. The gap it
+ * leaves is that nobody was looking at the fleet, so the only fleet-wide number
+ * that ever existed was hand-taken and frozen in a code comment
+ * (CodySwannGT/lisa#3490).
+ *
+ * Two rules shape everything below, and both are learned from that notice:
+ *
+ *   - **Report, do not gate.** No finding about the fleet may change the exit
+ *     status. Reddening a build because someone else's checkout is stale would
+ *     be a worse control than the one it replaces, and it would be routed
+ *     around — and a guard routed around protects nothing.
+ *   - **"Resolves nothing" and "resolves something old" are different
+ *     findings.** They have different remedies, and folding them into one "N
+ *     stale" number loses the serious half — which is exactly how the
+ *     unenforced checkouts stayed easy to miss. They are separate
+ *     fields here, and `countStale` is defined over the resolving set alone, so
+ *     folding them takes a code change that a named test refuses.
+ *
+ * Nothing in this module stores a count. The roster names where to look, the
+ * checkouts on disk answer, and the reference version is a maximum over the
+ * evidence found during the same run. A census that restated today's number in
+ * a different file would go stale exactly the way the comment did.
+ * @module core/enforcement-census
+ */
+import { createHash } from "node:crypto";
+import { readdir, realpath } from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { applyReference, collectCheckoutCoverage, isOlderVersion, versionEvidence, } from "./enforcement-coverage.js";
+import { readJsonOrNull } from "../utils/json-utils.js";
+import { pathExists } from "../utils/file-operations.js";
+/** The fleet roster `scripts/lisa-update-local.sh` already maintains. */
+export const DEFAULT_ROSTER_FILE = ".lisa.workspaces.json";
+/**
+ * Expand a leading `~` the way the roster's other reader does.
+ * @param value - A path that may start with `~`
+ * @returns The expanded path
+ */
+function expandHome(value) {
+    return value.startsWith("~")
+        ? path.join(os.homedir(), value.slice(1))
+        : value;
+}
+/**
+ * Read a fleet roster file.
+ *
+ * The primary shape is the one already on disk: an object mapping checkout path
+ * to target branch, which `scripts/lisa-update-local.sh` reads. An array of
+ * paths is accepted too, so a census can be pointed at an ad-hoc list without
+ * inventing a branch for each entry.
+ * @param rosterPath - Path to the roster file
+ * @returns The checkouts it names, or null when it cannot be read
+ */
+export async function readFleetRoster(rosterPath) {
+    const parsed = await readJsonOrNull(rosterPath);
+    if (parsed === null || typeof parsed !== "object")
+        return null;
+    const raw = Array.isArray(parsed)
+        ? parsed.filter((entry) => typeof entry === "string")
+        : Object.keys(parsed);
+    return raw.map(entry => ({
+        label: entry,
+        checkoutPath: path.resolve(expandHome(entry)),
+        source: "roster",
+    }));
+}
+/**
+ * Find checkouts under a directory, without a roster.
+ *
+ * Discovery exists because a hand-maintained roster can go stale the same way
+ * the frozen comment did: a checkout nobody added is a checkout the census
+ * cannot see, and an unseen checkout reads as coverage it does not have. A
+ * candidate is any directory containing a `.git` entry, found no deeper than
+ * `depth` levels so the walk stays bounded on a large disk.
+ * @param root - Directory to search
+ * @param depth - How many levels below `root` to descend
+ * @returns The checkouts found, in listing order
+ */
+export async function scanForCheckouts(root, depth) {
+    const resolved = path.resolve(expandHome(root));
+    if (depth < 0 || !(await pathExists(resolved)))
+        return [];
+    if (await pathExists(path.join(resolved, ".git"))) {
+        return [{ label: resolved, checkoutPath: resolved, source: "scan" }];
+    }
+    const entries = await readdir(resolved, { withFileTypes: true }).catch(() => []);
+    const children = entries
+        .filter(entry => entry.isDirectory() && !entry.name.startsWith("."))
+        .filter(entry => entry.name !== "node_modules")
+        .map(entry => path.join(resolved, entry.name));
+    const found = await Promise.all(children.map(child => scanForCheckouts(child, depth - 1)));
+    return found.flat();
+}
+/**
+ * Collapse entries that name the same checkout twice.
+ *
+ * Two roster spellings of one directory, or a roster entry a scan also found,
+ * would otherwise be counted twice — inflating both the numerator and the
+ * denominator and making the census disagree with itself.
+ * @param entries - Entries from every source
+ * @returns One entry per distinct checkout, first spelling wins
+ */
+export async function dedupeRoster(entries) {
+    const keyed = await Promise.all(entries.map(async (entry) => ({
+        entry,
+        key: await realpath(entry.checkoutPath).catch(() => entry.checkoutPath),
+    })));
+    return keyed
+        .filter((candidate, index) => keyed.findIndex(other => other.key === candidate.key) === index)
+        .map(candidate => candidate.entry);
+}
+/**
+ * Count the resolving checkouts whose governing copy is behind.
+ *
+ * Defined over the resolving set on purpose, and named so that folding the
+ * unguarded class into it is a visible edit rather than an accident. A checkout
+ * that resolves nothing has no copy to be behind: calling it stale describes a
+ * guard that would refuse things, and there is none.
+ * @param checkouts - Every record in the run
+ * @returns How many resolving checkouts are behind the reference
+ */
+export function countStale(checkouts) {
+    return checkouts.filter(entry => (entry.resolution === "partial" || entry.resolution === "full") &&
+        entry.vintage === "behind").length;
+}
+/**
+ * Reduce a run to its disjoint classes.
+ * @param checkouts - Every record in the run
+ * @returns The summary
+ */
+export function summarizeFleetCensus(checkouts) {
+    const resolving = checkouts.filter(entry => entry.resolution === "partial" || entry.resolution === "full");
+    const count = (list, predicate) => list.filter(predicate).length;
+    return {
+        total: checkouts.length,
+        unreadable: count(checkouts, entry => entry.resolution === "unreadable"),
+        unguarded: count(checkouts, entry => entry.resolution === "none"),
+        partial: count(checkouts, entry => entry.resolution === "partial"),
+        full: count(checkouts, entry => entry.resolution === "full"),
+        resolving: resolving.length,
+        behind: countStale(checkouts),
+        undateable: count(resolving, entry => entry.vintage === "undateable"),
+        current: count(resolving, entry => entry.vintage === "current"),
+        withoutReceipt: count(resolving, entry => !entry.receipt.present),
+        installBehindDeclared: count(checkouts, entry => isInstallBehindDeclared(entry)),
+        covered: count(checkouts, entry => entry.resolution === "full" &&
+            entry.vintage === "current" &&
+            entry.receipt.present),
+    };
+}
+/**
+ * Whether a checkout's installed Lisa is older than the one it declares.
+ *
+ * The comparison is against the range's own floor, read as a plain version once
+ * the usual range punctuation is stripped. A range this cannot parse yields
+ * `false` — absence of proof never becomes proof of drift.
+ * @param coverage - One record
+ * @returns Whether the installed copy is behind the declared one
+ */
+export function isInstallBehindDeclared(coverage) {
+    const { declared, installed } = coverage.install;
+    if (declared === null || installed === null)
+        return false;
+    // Bounded quantifiers rather than `\d+`: a range string arrives from a
+    // manifest this repository does not own, and an unbounded pattern over
+    // untrusted input is the shape that backtracks pathologically.
+    const floor = /(\d{1,9}\.\d{1,9}\.\d{1,9})/u.exec(declared)?.[1];
+    return floor !== undefined && isOlderVersion(installed, floor);
+}
+/**
+ * Resolve the newest Lisa this run can point at.
+ *
+ * A maximum over evidence found on the same disk during the same run, never a
+ * network lookup and never a nominated authority. A copy is reported behind
+ * only when something newer can actually be pointed at, so the worst case is
+ * silence rather than a fleet-wide false alarm.
+ * @param checkouts - Records collected with no reference
+ * @param seed - A version the caller can vouch for, such as its own manifest
+ * @returns The reference version and what proved it
+ */
+export function resolveReference(checkouts, seed) {
+    const candidates = checkouts.flatMap(entry => versionEvidence(entry).map(version => ({
+        version,
+        source: entry.label,
+    })));
+    const all = seed === null
+        ? candidates
+        : [
+            { version: seed, source: "this checkout's own manifest" },
+            ...candidates,
+        ];
+    const best = all.reduce((winner, candidate) => winner === null || isOlderVersion(winner.version, candidate.version)
+        ? candidate
+        : winner, null);
+    return best === null
+        ? { version: null, source: "no Lisa version could be found on this disk" }
+        : best;
+}
+/**
+ * Run the census.
+ *
+ * Never throws for a fleet finding and never returns a status: the caller
+ * prints this and exits 0. The only thing that can fail here is the census
+ * itself, and a checkout it cannot read comes back as `unreadable` rather than
+ * as an exception, because one unreachable directory must not stop the other
+ * twenty-six from being measured.
+ * @param options - Roster and reference inputs
+ * @returns The measured fleet
+ */
+export async function runFleetCensus(options) {
+    const undated = await Promise.all(options.roster.map(entry => collectCheckoutCoverage({
+        label: entry.label,
+        checkoutPath: entry.checkoutPath,
+        reference: null,
+    })));
+    const resolved = options.reference != null && options.reference !== ""
+        ? { version: options.reference, source: "supplied by the caller" }
+        : resolveReference(undated, options.seedVersion ?? null);
+    const checkouts = undated.map(entry => applyReference(entry, resolved.version));
+    return {
+        measuredAt: (options.now?.() ?? new Date()).toISOString(),
+        reference: resolved.version,
+        referenceSource: resolved.source,
+        rosterOrigin: options.rosterOrigin,
+        checkouts,
+        summary: summarizeFleetCensus(checkouts),
+    };
+}
+/**
+ * A stable, path-free label for a checkout.
+ *
+ * The census names real local checkouts, and those paths embed client and
+ * product names that must never reach a public issue or PR. Redaction keeps the
+ * counts and the per-checkout rows — which is all a fleet finding needs — while
+ * making the report safe to paste. It is derived from the path, so the same
+ * checkout carries the same label between runs and can still be discussed.
+ * @param checkoutPath - The real path
+ * @returns A stable anonymous label
+ */
+export function redactedLabel(checkoutPath) {
+    return `checkout-${createHash("sha256")
+        .update(checkoutPath)
+        .digest("hex")
+        .slice(0, 8)}`;
+}
+//# sourceMappingURL=enforcement-census.js.map

package/dist/core/enforcement-census.js.map

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

package/dist/core/enforcement-coverage.d.ts

@@ -0,0 +1,168 @@
+/**
+ * The guards the dispatcher runs, in its own order.
+ *
+ * Kept as data rather than inferred from the directory listing: a census that
+ * asks "which guard files are here" cannot notice a guard that is missing
+ * everywhere, which is the case it most needs to report.
+ */
+export declare const ENFORCEMENT_GUARDS: readonly ["block-no-verify", "parity-safety-net", "block-shell-json-parsing", "block-instruction-file-edits", "block-direct-issue-create", "block-managed-file-edits"];
+/** Which of the two trees a resolved guard came from. */
+export type GuardTree = "host" | "plugin";
+/**
+ * How much enforcement a checkout resolves.
+ *
+ * `unreadable` is a first-class answer and never a synonym for any of the
+ * others: a checkout the census could not look into has not been shown to
+ * resolve anything, and has not been shown to resolve nothing either.
+ */
+export type CoverageResolution = "unreadable" | "none" | "partial" | "full";
+/**
+ * How old the copy in force is.
+ *
+ * `not-applicable` belongs to checkouts that resolve nothing — they have no
+ * copy to be old. That value is what makes it structurally impossible to count
+ * an unguarded checkout as a stale one.
+ */
+export type CoverageVintage = "current" | "behind" | "undateable" | "not-applicable";
+/** One guard and the copy that would run for it, if any. */
+export interface GuardResolution {
+    /** Guard name, as the dispatcher spells it. */
+    readonly guard: string;
+    /** Tree the running copy comes from, or null when nothing resolved. */
+    readonly tree: GuardTree | null;
+    /** Absolute path of the copy that would run, or null. */
+    readonly script: string | null;
+    /** Whether a second copy exists that this one shadows. */
+    readonly shadows: boolean;
+}
+/** One guard tree, and the evidence that dates it. */
+export interface TreeVintage {
+    /** Which tree this is. */
+    readonly tree: GuardTree;
+    /** Absolute path of the tree. */
+    readonly root: string;
+    /** Lisa version that produced it, or null when it cannot be dated. */
+    readonly version: string | null;
+    /** The file that dated it, or the file whose absence left it undateable. */
+    readonly datedBy: string;
+}
+/** What `lisa apply` left behind, if anything. */
+export interface ReceiptSummary {
+    /** Whether a readable receipt exists. */
+    readonly present: boolean;
+    /** Lisa version that completed the apply. */
+    readonly version: string | null;
+    /** When that apply completed. */
+    readonly appliedAt: string | null;
+    /** Whether it was a full apply or the postinstall-safe subset. */
+    readonly mode: string | null;
+}
+/**
+ * What the checkout's own manifest asks for versus what is installed.
+ *
+ * Its own axis, because it fails in the affirmative: a checkout whose
+ * `node_modules` is majors behind its `package.json` resolves guards, runs
+ * them, and answers every question confidently about a version nobody is using.
+ */
+export interface InstallSummary {
+    /** Range the checkout's manifest declares, or null when it declares none. */
+    readonly declared: string | null;
+    /** Version actually present under `node_modules`, or null. */
+    readonly installed: string | null;
+}
+/** Everything one checkout resolves, right now. */
+export interface CheckoutCoverage {
+    /** Operator-facing label — the roster key, or the path when scanned. */
+    readonly label: string;
+    /** Absolute path of the checkout. */
+    readonly checkoutPath: string;
+    /** How much enforcement it resolves. */
+    readonly resolution: CoverageResolution;
+    /** Why it could not be read, when `resolution` is `unreadable`. */
+    readonly unreadableReason: string | null;
+    /** Per-guard resolution. Empty when the checkout could not be read. */
+    readonly guards: readonly GuardResolution[];
+    /** Guards no copy of which was found. */
+    readonly unresolvedGuards: readonly string[];
+    /** Every tree that contributes at least one running guard. */
+    readonly trees: readonly TreeVintage[];
+    /** The oldest tree in use — the copy that governs. Null when none is. */
+    readonly governing: TreeVintage | null;
+    /** Age of the governing copy against the reference version. */
+    readonly vintage: CoverageVintage;
+    /** The apply receipt, or its absence. */
+    readonly receipt: ReceiptSummary;
+    /** Declared versus installed Lisa in this checkout. */
+    readonly install: InstallSummary;
+}
+/**
+ * Read a dotted version's release fields, or refuse to read it at all.
+ *
+ * Prerelease and build suffixes are ignored. A string whose release fields are
+ * not all plain numbers yields `null` rather than a best guess: reading an
+ * unparseable field as 0 makes it sort BELOW every real version, which turns
+ * "this does not parse" into the confident claim "this is behind" — a
+ * measurement invented out of an absence, which is the shape of defect this
+ * whole module exists to end.
+ * @param value - A version string from a manifest or receipt this repo does not own
+ * @returns The release fields, or null when the string is not a version
+ */
+export declare function versionFields(value: string): readonly number[] | null;
+/**
+ * Compare two dotted versions on their release fields only.
+ *
+ * A version either side cannot parse yields `false`: absence of proof never
+ * becomes proof of drift, the same rule `isInstallBehindDeclared` follows. The
+ * caller that needs to distinguish "not older" from "could not tell" asks
+ * {@link versionFields} directly — `classifyVintage` does, and reports an
+ * unparseable copy as undateable rather than letting it fall through to
+ * "current".
+ * @param left - Candidate version
+ * @param right - Version to compare against
+ * @returns Whether `left` names an older Lisa than `right`
+ */
+export declare function isOlderVersion(left: string, right: string): boolean;
+/** Everything the caller must supply to measure one checkout. */
+export interface CoverageRequest {
+    /** Operator-facing label for the checkout. */
+    readonly label: string;
+    /** Path to the checkout, already expanded and resolved. */
+    readonly checkoutPath: string;
+    /** Newest Lisa the census can point at, or null when nothing dates it. */
+    readonly reference: string | null;
+}
+/**
+ * Measure what one checkout resolves right now.
+ *
+ * Every failure to look is reported as a failure to look. A checkout that is
+ * not there, or not readable, is never quietly dropped from the fleet and never
+ * counted as covered: a census that reports better coverage than exists is
+ * worse than no census, because it retires the question.
+ * @param request - The checkout to measure
+ * @returns What that checkout resolves
+ */
+export declare function collectCheckoutCoverage(request: CoverageRequest): Promise<CheckoutCoverage>;
+/**
+ * Re-classify a record's vintage against a reference resolved later.
+ *
+ * The census cannot know the newest Lisa on the disk until it has read every
+ * checkout, and the reference is a maximum over exactly that evidence. So
+ * records are collected first with no reference and dated afterwards, rather
+ * than the census guessing a reference up front and being wrong about the one
+ * checkout that carries the newest copy.
+ * @param coverage - A record collected with no reference
+ * @param reference - Newest Lisa the census can point at
+ * @returns The same record, dated
+ */
+export declare function applyReference(coverage: CheckoutCoverage, reference: string | null): CheckoutCoverage;
+/**
+ * Every Lisa version this checkout proves exists somewhere on the disk.
+ *
+ * Used to build the reference the way the dispatcher builds its own: a maximum
+ * over evidence on the same disk, never a nominated authority and never a
+ * network lookup. A copy is behind only when something newer can be pointed at.
+ * @param coverage - A collected record
+ * @returns The versions it can vouch for
+ */
+export declare function versionEvidence(coverage: CheckoutCoverage): readonly string[];
+//# sourceMappingURL=enforcement-coverage.d.ts.map

package/dist/core/enforcement-coverage.d.ts.map

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