@codyswann/lisa 4.12.0 → 4.13.1

package/dist/core/two-channel-delivery-scan.js

@@ -0,0 +1,191 @@
+/** How a workflow spells a path inside the installed Lisa package. */
+const PACKAGE_PREFIX = "node_modules/@codyswann/lisa/";
+/** Directories a consumer keeps its own executable artifacts in. */
+const CALLER_DIRECTORIES = "scripts|bin|tools";
+/**
+ * A caller-tree path literal: one of the caller directories, a body, and a
+ * file extension, with nothing path-like immediately before it.
+ */
+const CALLER_PATH = new RegExp(`(?<![A-Za-z0-9_@./-])((?:${CALLER_DIRECTORIES})/[A-Za-z0-9._/-]*[A-Za-z0-9_-]\\.[A-Za-z0-9]+)`, "g");
+/** A package path literal, used only to decide whether a step is covered. */
+const PACKAGE_PATH = new RegExp(`${PACKAGE_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[A-Za-z0-9_@./-]+`, "g");
+/** A line that is nothing but a YAML comment. */
+const COMMENT_LINE = /^\s*#/;
+/** The start of a step in a `steps:` list, capturing a `name:` value. */
+const STEP_START = /^\s*-\s+(?:name:\s*(.*)|(?:uses|run|id):)/;
+/**
+ * Split a workflow into steps, keeping the preamble as an unnamed first step.
+ *
+ * The preamble is not dead weight: `nightly-e2e-health.yml` declares
+ * `inputs.health_script` with a default of `scripts/check-nightly-e2e-health.mjs`,
+ * which is a caller-tree read that never appears in a step at all. Dropping the
+ * preamble would lose it.
+ * @param text - Raw workflow YAML
+ * @returns Steps in file order, the first being the preamble
+ */
+export function extractSteps(text) {
+    const lines = text.split("\n").filter(line => !COMMENT_LINE.test(line));
+    return lines.reduce((steps, line) => {
+        const started = STEP_START.exec(line);
+        const current = steps[steps.length - 1];
+        const appended = {
+            name: current?.name ?? "",
+            body: `${current?.body ?? ""}\n${line}`,
+        };
+        return started === null
+            ? [...steps.slice(0, -1), appended]
+            : [...steps, { name: (started[1] ?? "").trim(), body: line }];
+    }, [{ name: "", body: "" }]);
+}
+/**
+ * Every distinct match of one global pattern in a chunk of text.
+ * @param pattern - A global regular expression with one capturing group, or none
+ * @param text - Text to search
+ * @returns Distinct matches, in first-seen order
+ */
+function matchesIn(pattern, text) {
+    return [
+        ...new Set([...text.matchAll(pattern)].map(match => match[1] ?? match[0])),
+    ];
+}
+/**
+ * Whether a step names a package-relative candidate for the same artifact.
+ *
+ * Compared by suffix rather than by basename: a package candidate for
+ * `scripts/lisa-gates.mjs` spells the whole tail
+ * `…/all/copy-overwrite/scripts/lisa-gates.mjs`, and matching on the bare file
+ * name would let an unrelated package file with a colliding name vouch for a
+ * caller path it has nothing to do with.
+ * @param packagePaths - Package literals found in the step
+ * @param callerPath - The caller-tree path
+ * @returns Whether the fast channel already delivers this artifact
+ */
+function isPackageBacked(packagePaths, callerPath) {
+    return packagePaths.some(candidate => candidate.endsWith(`/${callerPath}`));
+}
+/** Shell file-test flags whose operand is a path that may be absent. */
+const FILE_TEST_FLAG = /-[defrswx]$/;
+/** How the Actions expression language asks whether a path exists. */
+const HASH_FILES = "hashFiles(";
+/** Quoting and leading-`./` noise sitting between a flag and its operand. */
+const OPERAND_NOISE = new Set(['"', "'", ".", "/", " ", "\t"]);
+/**
+ * Drop trailing quoting and path noise, so a flag sits at the end or does not.
+ *
+ * A loop rather than a `/["\'./]+$/` replace: a quantified class anchored at
+ * the end of a caller-supplied slice is the shape linters flag for
+ * super-linear backtracking, and nothing here needs a pattern.
+ * @param value - Text to trim
+ * @returns The same text without its trailing noise characters
+ */
+function withoutOperandNoise(value) {
+    return value.length > 0 && OPERAND_NOISE.has(value.slice(-1))
+        ? withoutOperandNoise(value.slice(0, -1))
+        : value;
+}
+/** How far back to look for whatever introduced an occurrence. */
+const LOOKBEHIND = 32;
+/**
+ * Every index at which `needle` occurs in `haystack`.
+ *
+ * Written with `split` rather than a global regular expression because the
+ * needle is a caller-supplied path: compiling it into a pattern is where a
+ * super-linear match would come from, and there is nothing here to match
+ * loosely.
+ * @param haystack - Text to search
+ * @param needle - Literal to find
+ * @returns Start indices, ascending
+ */
+function occurrenceIndices(haystack, needle) {
+    return haystack
+        .split(needle)
+        .slice(0, -1)
+        .reduce((indices, chunk) => {
+        const previous = indices.at(-1) ?? -needle.length;
+        return [...indices, previous + needle.length + chunk.length];
+    }, []);
+}
+/**
+ * Whether a step tests for the path's existence before reading it.
+ *
+ * Recognises the two spellings that actually occur — a shell file test
+ * (`[ -f scripts/x.mjs ]`, `test -e …`) and the Actions `hashFiles()`
+ * expression. It does not attempt to decide what the absent branch DOES,
+ * because that needs a shell parser and the answer would still be a guess.
+ * What it reports is narrower and checkable: the step can tell the path is
+ * missing, so its absence need not be loud.
+ * @param body - The step's text
+ * @param callerPath - The caller-tree path
+ * @returns Whether the read sits behind an existence test
+ */
+function isGuarded(body, callerPath) {
+    return occurrenceIndices(body, callerPath).some(index => {
+        const before = body.slice(Math.max(0, index - LOOKBEHIND), index);
+        return (FILE_TEST_FLAG.test(withoutOperandNoise(before)) ||
+            before.includes(HASH_FILES));
+    });
+}
+/**
+ * Every caller-tree read in one step.
+ * @param step - The step
+ * @returns One occurrence per distinct caller path
+ */
+function occurrencesIn(step) {
+    const packagePaths = matchesIn(PACKAGE_PATH, step.body);
+    return matchesIn(CALLER_PATH, step.body).map(callerPath => ({
+        step: step.name,
+        path: callerPath,
+        packageBacked: isPackageBacked(packagePaths, callerPath),
+        guarded: isGuarded(step.body, callerPath),
+    }));
+}
+/**
+ * Collapse repeated reads of one path into the single coupling they are.
+ * @param workflow - Workflow file name
+ * @param occurrences - Every occurrence found in that workflow
+ * @param lanesFor - Delivery lanes shipping a caller path
+ * @returns One coupling per distinct path, sorted by path
+ */
+function collapse(workflow, occurrences, lanesFor) {
+    const paths = [...new Set(occurrences.map(occurrence => occurrence.path))];
+    return paths
+        .map(callerPath => {
+        const found = occurrences.filter(occurrence => occurrence.path === callerPath);
+        return {
+            workflow,
+            step: found[0]?.step ?? "",
+            path: callerPath,
+            lanes: lanesFor(callerPath),
+            packageBacked: found.every(occurrence => occurrence.packageBacked),
+            guarded: found.some(occurrence => occurrence.guarded),
+        };
+    })
+        .sort((left, right) => left.path.localeCompare(right.path));
+}
+/**
+ * Read every caller-tree coupling out of one reusable workflow.
+ * @param options - Inputs
+ * @param options.workflow - Workflow file name, as a consumer spells it after `@main`
+ * @param options.text - Raw workflow YAML
+ * @param options.lanesFor - Delivery lanes shipping a caller path
+ * @returns One coupling per distinct caller path, sorted by path
+ */
+export function scanWorkflow(options) {
+    const steps = extractSteps(options.text);
+    return collapse(options.workflow, steps.flatMap(occurrencesIn), options.lanesFor);
+}
+/**
+ * Whether a workflow can be called by another repository at all.
+ *
+ * Only a `workflow_call` workflow travels the `@main` channel; the rest run in
+ * this repository and reach no consumer, so a caller-tree read in one of them
+ * is a claim about this checkout and not about anybody else's.
+ * @param text - Raw workflow YAML
+ * @returns Whether the workflow declares `workflow_call`
+ */
+export function isReusable(text) {
+    return text
+        .split("\n")
+        .some(line => line.trimStart().startsWith("workflow_call:"));
+}
+//# sourceMappingURL=two-channel-delivery-scan.js.map

package/dist/core/two-channel-delivery-scan.js.map

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

package/dist/core/two-channel-delivery.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Measure the gap between the two speeds Lisa ships a change at.
+ *
+ * Lisa reaches a consumer down two channels, and they do not move together:
+ *
+ * | half | channel | reaches a consumer |
+ * | --- | --- | --- |
+ * | the reusable workflow body | `uses: …@main` | their next workflow run |
+ * | scripts, configs, declarations | `lisa apply` | their next apply |
+ *
+ * For an *additive* change the asymmetry is harmless — the new workflow finds
+ * no declaration and falls back. For a change that REMOVES a built-in and
+ * replaces it with something the consumer's tree must provide, the halves are
+ * not interchangeable and they land in the wrong order: the removing half is
+ * live everywhere immediately, the restoring half only where someone applied.
+ * In the gap the property is proved by nothing, and nothing reads as red —
+ * the replacement never runs, so it posts no context, and an ABSENT required
+ * context is not a failing one (CodySwannGT/lisa#3050).
+ *
+ * ## What this module measures, and what it deliberately does not
+ *
+ * A **coupling** is one step of a `@main`-delivered reusable workflow naming a
+ * path in the CALLER's tree. `scripts/check-e2e-coverage.mjs` is a coupling;
+ * `node_modules/@codyswann/lisa/all/copy-overwrite/scripts/lisa-gates.mjs` is
+ * not — that path is inside the installed package, and whether it survives a
+ * release is `check-workflow-package-paths.mjs`'s question (#2960).
+ *
+ * That script states its own boundary: *"HOST-relative candidates in the same
+ * step (`scripts/foo.mjs`) do not count and are never extracted."* This module
+ * is exactly that excluded arm. The two do not overlap, and neither subsumes
+ * the other: #2960 asks whether a PACKAGE path survives a release, this asks
+ * whether a HOST path ever arrives at all.
+ *
+ * ## Why the resolver loop matters more than it looks
+ *
+ * Most steps resolve a script by trying candidates in order — the packaged
+ * copy first, the consumer's own copy as a fallback. Such a step is
+ * `package-backed`: the package channel delivers it, and the host copy is
+ * belt-and-braces. **A step naming a host path with NO package candidate has
+ * exactly one delivery channel, and it is the slow one.** Those are the
+ * couplings this module exists to count.
+ *
+ * ## Why an inventory of apply-lagged couplings is the deliverable, not a failure
+ *
+ * Fourteen of Lisa's own fifteen host-only couplings are `apply-lagged`, and
+ * every one of them is deliberate — Lisa's design is that `quality.yml` calls
+ * scripts `lisa apply` installs. Failing on them would mean ratifying fourteen
+ * entries on day one, and an allowlist that large stops being a record of
+ * decisions and becomes the bypass (the lesson of #2639). So `apply-lagged` is
+ * RECORDED. The ledger is the baseline; a change that adds a coupling shows up
+ * as a ledger diff a reviewer must look at, which is the reachable check the
+ * issue asked for.
+ *
+ * What fails is the shape nothing restores: `never-delivered` (create-only, so
+ * an existing consumer receives it once at scaffold time or never) and
+ * `undelivered` (Lisa ships no such path anywhere). Those are #3030's lesson
+ * — *"fixed upstream" is not "a bump brings it"* — reached from the other
+ * side, and #3169's honestly-stated haves/have-nots split.
+ *
+ * ## Refusing to pass on nothing
+ *
+ * Zero workflows, zero steps, zero couplings, or an empty delivery inventory
+ * all mean the measurement did not happen, and every one of them is reported
+ * as unmeasured rather than as a clean sweep. An empty comparison and a
+ * converged consumer must not produce the same output — this whole subject is
+ * failures that read as normal, and reproducing that here would be perverse.
+ * @module core/two-channel-delivery
+ */
+/**
+ * How one artifact reaches a consumer that already exists.
+ *
+ * Named by SPEED rather than by mechanism, because speed is what the two-
+ * channel defect is about. `workflow-ref` and `package` both arrive without
+ * anyone acting on the consumer's side; `apply` needs an apply; `create-only`
+ * and `undelivered` never arrive at all.
+ */
+export type DeliveryChannel = 
+/** Travels with the workflow body itself — live on the next run. */
+"workflow-ref"
+/** Inside the installed package — live on the next dependency bump. */
+ | "package"
+/** A refreshing copy strategy — live on the next `lisa apply`. */
+ | "apply"
+/** Written once at scaffold time — an existing consumer never receives it. */
+ | "create-only"
+/** Lisa ships nothing at this path; the consumer must author it. */
+ | "undelivered";
+/**
+ * One coupling's verdict, in the vocabulary an operator can act on.
+ *
+ * Four members rather than a drifted/clean pair, because the remedies differ
+ * and one of the four is not a defect at all.
+ */
+export type CouplingVerdict = 
+/** The step also names a package candidate, so the fast channel covers it. */
+"package-backed"
+/** Host-only, and a refreshing lane delivers it — arrives on the next apply. */
+ | "apply-lagged"
+/** Host-only, and only `create-only` delivers it — never arrives. */
+ | "never-delivered"
+/** Host-only, and Lisa delivers no such path at all. */
+ | "undelivered";
+/** What to do about one verdict. */
+export type CouplingRemedy = "none" | "run-lisa-apply" | "adopt-the-artifact" | "author-the-artifact";
+/** One host-relative path read by one step of one reusable workflow. */
+export interface CouplingInput {
+    /** Workflow file name, as a consumer spells it after `@main`. */
+    readonly workflow: string;
+    /** The step's `name:`, or an empty string for an unnamed step. */
+    readonly step: string;
+    /** The caller-tree path the step names. */
+    readonly path: string;
+    /**
+     * Delivery lanes shipping that path, as `<stack>/<strategy>` (for example
+     * `all/copy-overwrite`). Empty when Lisa ships nothing there.
+     */
+    readonly lanes: readonly string[];
+    /** Whether the same step also names a package-relative candidate. */
+    readonly packageBacked: boolean;
+    /**
+     * Whether the read sits behind a file-existence test.
+     *
+     * Not a verdict, and deliberately not one. A guard changes the SHAPE of the
+     * failure rather than its existence: unguarded, an absent path fails the job
+     * loudly; guarded, the step skips and the gate silently proves nothing. The
+     * second is the worse outcome and the one #3050 is about, so it is recorded
+     * on the entry and said in the detail rather than folded into the verdict.
+     */
+    readonly guarded: boolean;
+}
+/** One coupling, its verdict, and the evidence behind it. */
+export interface CouplingEntry extends CouplingInput {
+    /** Stable identity, `<workflow>::<path>`, used to key ratifications. */
+    readonly key: string;
+    /** The channel the path actually arrives on. */
+    readonly channel: DeliveryChannel;
+    /** The verdict. */
+    readonly verdict: CouplingVerdict;
+    /** The action this verdict calls for. */
+    readonly remedy: CouplingRemedy;
+    /** One operator-readable sentence. */
+    readonly detail: string;
+}
+/** What a run looked at, so a clean report can never mean an empty one. */
+export interface InspectionCounts {
+    /** Reusable workflows read. */
+    readonly workflows: number;
+    /** Steps inside them. */
+    readonly steps: number;
+    /** Caller-tree path reads found in those steps. */
+    readonly couplings: number;
+    /** Paths in the delivery inventory the lanes were resolved against. */
+    readonly inventory: number;
+}
+/** The whole measurement. */
+export interface TwoChannelReport {
+    /** One entry per coupling, sorted by key. */
+    readonly entries: readonly CouplingEntry[];
+    /** How many entries carry each verdict. Every key is present. */
+    readonly counts: Readonly<Record<CouplingVerdict, number>>;
+    /** What the run inspected. Printed on every run, clean or not. */
+    readonly inspected: InspectionCounts;
+    /**
+     * Unrestorable couplings nobody ratified — the findings.
+     *
+     * Sorted by key, so two runs over the same tree emit the same bytes.
+     */
+    readonly findings: readonly CouplingEntry[];
+    /**
+     * Ratification keys matching no live coupling.
+     *
+     * Reported as a failure, not pruned silently. A ratification is a record of
+     * a decision about a specific coupling; once that coupling is gone the entry
+     * is an unexamined permission that the next matching path inherits for free,
+     * which is how an allowlist added to harden a guard becomes the bypass.
+     */
+    readonly staleRatifications: readonly string[];
+    /** False when the run did not actually measure anything. */
+    readonly measured: boolean;
+    /** Why the run measured nothing, or null when it measured something. */
+    readonly unmeasuredReason: string | null;
+}
+/**
+ * Which channel a path arrives on, given the lanes shipping it.
+ *
+ * A refreshing lane wins over `create-only` when both ship the same path,
+ * because an apply reaching ANY refreshing lane rewrites the file. That is
+ * deliberately optimistic and stated rather than hidden: a project on only the
+ * create-only stack still never receives it, and resolving lanes per active
+ * stack is a later stage. Optimism that is written down can be argued with;
+ * optimism inside a `find` cannot.
+ * @param lanes - `<stack>/<strategy>` lanes shipping the path
+ * @returns The channel an existing consumer receives it on
+ */
+export declare function resolveDeliveryChannel(lanes: readonly string[]): DeliveryChannel;
+/**
+ * Classify every coupling and decide whether the run measured anything.
+ *
+ * Total and pure — the same inputs always produce the same entries in the same
+ * order. Reaching the tree is the caller's job, and a caller that could not
+ * reach it must pass the zeroes it actually saw rather than omit them: this
+ * function reports an empty sweep as unmeasured precisely so a caller cannot
+ * turn "I could not look" into "there was nothing to find".
+ * @param options - Inputs
+ * @param options.couplings - Every caller-tree path read that was found
+ * @param options.inspected - What the run looked at
+ * @param options.ratified - Ratification reasons, keyed `<workflow>::<path>`
+ * @returns The measurement
+ */
+export declare function classifyTwoChannelDelivery(options: {
+    couplings: readonly CouplingInput[];
+    inspected: InspectionCounts;
+    ratified: Readonly<Record<string, string>>;
+}): TwoChannelReport;
+//# sourceMappingURL=two-channel-delivery.d.ts.map

package/dist/core/two-channel-delivery.d.ts.map

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