@codyswann/lisa 4.16.0 → 4.17.0

package/dist/core/override-floors.js

@@ -0,0 +1,200 @@
+/**
+ * @file Shared vocabulary for npm `$name` override self-references and the
+ * security floors they can silently resolve downwards.
+ * @description
+ * An `overrides`/`resolutions` entry written `"$name"` means "whatever the
+ * direct dependency says". Lisa's templates force floors into those same two
+ * sections, so when a floored package is ALSO a direct dependency, the apply
+ * normalizes the forced literal to `$name` — and if the host's direct range
+ * starts below the floor, that rewrite would readmit exactly the versions the
+ * floor exists to exclude. `lisa apply` refuses rather than perform it.
+ *
+ * The refusal is correct. What it was missing is a way to be seen coming, and a
+ * remedy the operator can actually follow. Both halves are here, in ONE place,
+ * because they must agree by construction:
+ *
+ * - {@link classifySelfReferenceRewrite} is the single predicate. The apply's
+ *   guard and `lisa doctor` both call it, so doctor can never report clean on a
+ *   manifest the apply is about to refuse, nor cry wolf on one it accepts.
+ * - {@link suggestSatisfyingDirectRange} runs its own suggestion back through
+ *   that same predicate before returning it. Advice that has not been tested
+ *   against the guard is how CodySwannGT/lisa#3191 happened — an operator who
+ *   did what the refusal told them was refused a second time, which reads as
+ *   the guard being broken rather than the range being wrong. A suggestion that
+ *   does not verify is withheld, not printed hopefully.
+ *
+ * Nothing here rewrites a host range or lowers a floor. Raising a dependency is
+ * a version decision with its own blast radius; this module names the raise and
+ * the operator makes it.
+ * @module core/override-floors
+ */
+import semver from "semver";
+/** package.json sections whose keys are treated as direct dependencies. */
+export const DIRECT_DEPENDENCY_SECTIONS = [
+    "dependencies",
+    "devDependencies",
+    "optionalDependencies",
+    "peerDependencies",
+];
+/** package.json sections that carry npm-style version overrides. */
+export const OVERRIDE_SECTIONS = ["overrides", "resolutions"];
+/**
+ * Narrow an unknown value to a plain object record, returning {} otherwise.
+ * @param value - Candidate value
+ * @returns The value as a record, or an empty record when it is not a plain object
+ */
+export function asRecord(value) {
+    if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        return value;
+    }
+    return {};
+}
+/**
+ * Collect the names of every direct dependency declared across a package.json's
+ * dependency sections.
+ * @param pkg - Merged package.json object
+ * @returns Set of direct dependency names
+ */
+export function collectDirectDependencyNames(pkg) {
+    return new Set(DIRECT_DEPENDENCY_SECTIONS.flatMap(section => Object.keys(asRecord(pkg[section]))));
+}
+/**
+ * Collect direct dependency ranges by package name.
+ * @param pkg - Merged package.json object
+ * @returns Package name to string range map
+ */
+export function collectDirectDependencyRanges(pkg) {
+    return new Map(DIRECT_DEPENDENCY_SECTIONS.flatMap(section => Object.entries(asRecord(pkg[section])).flatMap(([name, value]) => typeof value === "string" ? [[name, value]] : [])));
+}
+/**
+ * Decide whether an override/resolution entry is a candidate for npm `$name`
+ * normalization at all.
+ * @param directDeps - Direct dependency names in the merged package
+ * @param name - Override/resolution key
+ * @param value - Override/resolution value
+ * @returns True when the entry is a literal direct-dependency collision
+ */
+export function needsSelfReferenceRewrite(directDeps, name, value) {
+    return (directDeps.has(name) &&
+        typeof value === "string" &&
+        value.length > 0 &&
+        !value.startsWith("$"));
+}
+/**
+ * The one predicate behind both the apply's refusal and doctor's report.
+ * @remarks
+ * Deliberately plain `semver.subset`, with no ceiling normalization. The
+ * normalizing variant used by the host-pin branch (`rangeContains` in the
+ * package-lisa strategy) can only turn a refusal into an acceptance, and this
+ * branch is the one that decides whether a security floor may be resolved
+ * DOWNWARDS — so it keeps the stricter reading. Any range that reaches a
+ * `widening` verdict here still has a followable way out, because
+ * {@link suggestSatisfyingDirectRange} is verified against this same function.
+ * @param floorRange - The literal override range being replaced
+ * @param directRange - The direct dependency range `$name` would resolve to
+ * @returns Whether the rewrite is safe, unprovable, or widening
+ */
+export function classifySelfReferenceRewrite(floorRange, directRange) {
+    if (!semver.validRange(floorRange) || !semver.validRange(directRange)) {
+        return "unprovable";
+    }
+    return semver.subset(directRange, floorRange) ? "safe" : "widening";
+}
+/**
+ * Derive a direct dependency range that satisfies the floor, and PROVE it does
+ * before handing it to an operator.
+ * @remarks
+ * The natural suggestion is a caret at the floor's minimum version, because
+ * that is what a person writes and what the one already-fixed instance of this
+ * defect was fixed with. It is not always right: measured, `^1.18.0` is not a
+ * subset of a bounded floor `>=1.18.0 <1.19.0`, and `^0.0.0` is not a subset of
+ * `*`. So the caret is a CANDIDATE, tested against
+ * {@link classifySelfReferenceRewrite} and discarded when it fails, falling
+ * back to the floor range verbatim — which is a subset of itself for any range
+ * semver can parse.
+ *
+ * A floor semver cannot parse yields null. Printing an untested range would be
+ * the #3191 failure exactly: advice that sends the operator back into the same
+ * refusal.
+ * @param floorRange - The literal override range acting as the floor
+ * @returns A range verified to satisfy the guard, or null when none exists
+ */
+export function suggestSatisfyingDirectRange(floorRange) {
+    const minimum = rangeMinimum(floorRange);
+    const candidates = minimum === null ? [floorRange] : [`^${minimum}`, floorRange];
+    return (candidates.find(candidate => classifySelfReferenceRewrite(floorRange, candidate) === "safe") ?? null);
+}
+/**
+ * Lowest version a range admits, without throwing on an unparseable range.
+ * @param range - An npm version range
+ * @returns The minimum version, or null when the range is not comparable
+ */
+function rangeMinimum(range) {
+    try {
+        return semver.minVersion(range)?.version ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Judge every `$name`-rewrite candidate in a merged manifest, collecting ALL
+ * conflicts rather than stopping at the first.
+ * @remarks
+ * The apply throws on the first conflict, which is right for an apply — it is
+ * about to write a file and must not. A report has the opposite obligation: an
+ * operator who fixes the one package named and re-runs, only to be handed the
+ * next one, is being drip-fed a list Lisa already had in full.
+ * @param pkg - Merged package.json, as the apply would persist it
+ * @returns What was inspected and every conflict found
+ */
+export function auditSelfReferenceRewrites(pkg) {
+    const directDeps = collectDirectDependencyNames(pkg);
+    const directRanges = collectDirectDependencyRanges(pkg);
+    const entries = OVERRIDE_SECTIONS.flatMap(section => Object.entries(asRecord(pkg[section])).map(([name, value]) => [section, name, value]));
+    const judged = entries.flatMap(([section, name, value]) => {
+        if (!needsSelfReferenceRewrite(directDeps, name, value)) {
+            return [];
+        }
+        const directRange = directRanges.get(name);
+        return directRange === undefined
+            ? []
+            : [{ section, name, floorRange: value, directRange }];
+    });
+    const verdicts = judged.map(candidate => ({
+        candidate,
+        verdict: classifySelfReferenceRewrite(candidate.floorRange, candidate.directRange),
+    }));
+    return {
+        overridesInspected: entries.length,
+        rewritesJudged: judged.length,
+        conflicts: verdicts.flatMap(({ candidate, verdict }) => verdict === "safe"
+            ? []
+            : [
+                {
+                    ...candidate,
+                    verdict,
+                    suggestedDirectRange: suggestSatisfyingDirectRange(candidate.floorRange),
+                },
+            ]),
+        rewritable: verdicts.flatMap(({ candidate, verdict }) => verdict === "safe" ? [candidate] : []),
+    };
+}
+/**
+ * The remedy sentence, shared by the apply's refusal and doctor's report so an
+ * operator is never told two different things about the same conflict.
+ * @param conflict - The conflict to describe
+ * @returns One operator-readable sentence naming the exact raise to make
+ */
+export function describeSelfReferenceRemedy(conflict) {
+    if (conflict.suggestedDirectRange === null) {
+        return (`Lisa could not derive a direct range that satisfies the floor ` +
+            `${JSON.stringify(conflict.floorRange)}, so it is not guessing one. ` +
+            `Reconcile ${conflict.name} by hand, or raise Lisa's template pin.`);
+    }
+    return (`Raise the direct dependency ${conflict.name} from ` +
+        `${JSON.stringify(conflict.directRange)} to ` +
+        `${JSON.stringify(conflict.suggestedDirectRange)}, which Lisa has ` +
+        `verified satisfies the floor ${JSON.stringify(conflict.floorRange)}.`);
+}
+//# sourceMappingURL=override-floors.js.map

package/dist/core/override-floors.js.map

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

package/dist/core/upstream-evidence-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAo6EpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAwsPjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}
+{"version":3,"file":"upstream-evidence-manifest.d.ts","sourceRoot":"","sources":["../../src/core/upstream-evidence-manifest.ts"],"names":[],"mappings":"AACA,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAo6EpE,CAAC;AAEL,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA6sPjE,CAAC;AAEL,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAk6I/D,CAAC"}

package/dist/core/upstream-evidence-manifest.js

@@ -7197,6 +7197,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/cli/doctor-lisa-owned-universal.ts": true,
     "src/cli/doctor-merge-drivers.ts": true,
     "src/cli/doctor-monitor-thresholds.ts": true,
+    "src/cli/doctor-override-floor-conflicts.ts": true,
     "src/cli/doctor-readiness-action-pins.ts": true,
     "src/cli/doctor-readiness-audit-allowlist.ts": true,
     "src/cli/doctor-readiness-blockers.ts": true,
@@ -7442,6 +7443,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "src/core/lisa-skill-sources.ts": true,
     "src/core/lisa.ts": true,
     "src/core/merge-driver-registration.ts": true,
+    "src/core/override-floors.ts": true,
     "src/core/project-config-kane.ts": true,
     "src/core/project-config.ts": true,
     "src/core/self-apply.ts": true,
@@ -7851,6 +7853,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/cli/doctor-lisa-owned-artifacts.test.ts": true,
     "tests/unit/cli/doctor-merge-drivers.test.ts": true,
     "tests/unit/cli/doctor-monitor-thresholds.test.ts": true,
+    "tests/unit/cli/doctor-override-floor-conflicts.test.ts": true,
     "tests/unit/cli/doctor-readiness-blockers.test.ts": true,
     "tests/unit/cli/doctor-readiness-capabilities.test.ts": true,
     "tests/unit/cli/doctor-readiness-concurrent-write.test.ts": true,
@@ -8124,6 +8127,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/core/lisa-plugin-selection.test.ts": true,
     "tests/unit/core/lisa-skill-sources.test.ts": true,
     "tests/unit/core/no-downstream-project-names.test.ts": true,
+    "tests/unit/core/override-floors.test.ts": true,
     "tests/unit/core/plugin-sync-marker.test.ts": true,
     "tests/unit/core/project-config-harness-migration.test.ts": true,
     "tests/unit/core/project-config-kane.test.ts": true,
@@ -8671,6 +8675,7 @@ export const UPSTREAM_SURFACE_MANIFEST = Object.freeze({
     "tests/unit/strategies/multi-repo-container-decomposition.test.ts": true,
     "tests/unit/strategies/not-established-section-contract.test.ts": true,
     "tests/unit/strategies/package-lisa-integration-script-layout.test.ts": true,
+    "tests/unit/strategies/package-lisa-override-floor-remedy.test.ts": true,
     "tests/unit/strategies/package-lisa-script-composition.test.ts": true,
     "tests/unit/strategies/package-lisa-script-report.test.ts": true,
     "tests/unit/strategies/package-lisa-version-pin.test.ts": true,