autoremediator 0.21.2 → 0.22.0

package/dist/api/freshness/step.js

@@ -0,0 +1,286 @@
+import { assertAutonomyAllows, AutonomyRefusedError, summarizeAutonomy, } from "../autonomy/index.js";
+import { createChangeRequestsForReports } from "../change-request/index.js";
+import { defaultRunDeps } from "../runs/deps.js";
+import { applyPlan, persistPlan, rollbackRun } from "../runs/index.js";
+import { defaultFreshnessDeps } from "./deps.js";
+import { assessClimbs, buildClimbs, gatherFreshness, reportFrom } from "./report.js";
+/**
+ * Failed attempts after which one `applyFreshness` call stops trying other packages. A step that
+ * fails is rolled back and costs an install and a test run, so a project where everything fails
+ * must not spend the whole night finding that out.
+ */
+export const MAX_FAILED_ATTEMPTS = 3;
+/** The pseudo advisory id a step's run is recorded under; it also names the change request branch. */
+export const stepRunId = (step) => `FRESHNESS-${step.toVersion}`;
+const describeStep = (step) => `${step.packageName} ${step.fromVersion} -> ${step.toVersion} (${step.level}, step ${step.index} of ${step.of})`;
+/** The preview report `persistPlan` turns into a one-item plan. */
+export function stepReport(step, assessment, applied = false) {
+    return {
+        cveId: stepRunId(step),
+        cveDetails: null,
+        vulnerablePackages: [],
+        results: [
+            {
+                packageName: step.packageName,
+                strategy: "version-bump",
+                fromVersion: step.fromVersion,
+                toVersion: step.toVersion,
+                applied,
+                dryRun: !applied,
+                dependencyScope: "direct",
+                message: `Freshness step: ${describeStep(step)}${assessment ? `; upgrade impact ${assessment.breakability}: ${assessment.summary}` : ""}`,
+            },
+        ],
+        summary: `Dependency freshness: ${describeStep(step)}.`,
+    };
+}
+/** Gather, build, rate and order the climbs, leaving out packages in `skip`. */
+export async function analyse(options, deps, cache, skip = new Set()) {
+    const gathered = await gatherFreshness(options, deps);
+    const built = buildClimbs(gathered);
+    const wanted = built.climbs.filter((climb) => !skip.has(climb.packageName));
+    const ordered = await assessClimbs(wanted, {
+        cwd: gathered.cwd,
+        policy: gathered.policy,
+        allowHigh: options.allowHigh ?? false,
+        assess: options.assess ?? true,
+    }, deps, cache);
+    return {
+        report: reportFrom(gathered, ordered, built.unplanned),
+        climbs: ordered,
+        eligible: ordered.find((climb) => !climb.held),
+        held: ordered
+            .filter((climb) => climb.held)
+            .map((climb) => ({ packageName: climb.packageName, reason: climb.held.message })),
+    };
+}
+async function record(climb, options, cwd) {
+    const step = climb.steps[0];
+    const { runId, planId } = await persistPlan(stepReport(step, climb.assessment), {
+        cwd,
+        ...(options.policy ? { policy: options.policy } : {}),
+        ...(options.packageManager ? { packageManager: options.packageManager } : {}),
+        ...(options.runTests === undefined ? {} : { runTests: options.runTests }),
+        ...(options.typecheck === undefined ? {} : { typecheck: options.typecheck }),
+        ...(options.ignoreMemory ? { ignoreMemory: true } : {}),
+        source: options.source ?? "sdk",
+    }, cwd);
+    return { step, ...(climb.assessment ? { assessment: climb.assessment } : {}), runId, planId };
+}
+/**
+ * Record the next freshness step as a plan, for `applyPlan` to carry out after review. The step is
+ * the first of the safest climb that is not held; only one plan is recorded because applying it
+ * changes the manifests every other plan was made against. Changes nothing in the project.
+ */
+export async function planFreshnessStep(options = {}, deps = defaultFreshnessDeps) {
+    const cwd = options.cwd ?? process.cwd();
+    const analysis = await analyse(options, deps, new Map());
+    const autonomy = summarizeAutonomy(cwd, options.policy);
+    if (autonomy?.level === "L0") {
+        return {
+            reason: `Autonomy is L0 (observe): no plan was recorded, so there is nothing to apply.`,
+            held: analysis.held,
+            report: analysis.report,
+        };
+    }
+    if (!analysis.eligible) {
+        return {
+            reason: describeNothing(analysis),
+            held: analysis.held,
+            report: analysis.report,
+        };
+    }
+    const planned = await record(analysis.eligible, options, cwd);
+    return { planned, held: analysis.held, report: analysis.report };
+}
+function describeNothing(analysis) {
+    if (!analysis.report.policy) {
+        return "The policy has no `freshness` key, so there is no limit to climb towards.";
+    }
+    if (analysis.climbs.length === 0) {
+        return analysis.report.unplanned.length > 0
+            ? "Some packages are past the policy but no climb could be made for them (see unplanned)."
+            : "Every direct dependency is within the freshness policy.";
+    }
+    return "Every step that is due is held (see held).";
+}
+const MAX_STEPS_LIMIT = 50;
+/**
+ * Take freshness steps, one verified upgrade at a time, at most `maxSteps` of them (default 1).
+ * Each step is its own recorded run: planned, applied through `applyPlan` (so the verifier, the
+ * project's own checks, agent repair and earned autonomy apply as they do everywhere), and, if it
+ * does not hold, taken back out with `rollbackRun` and the package left alone for this call. With
+ * `changeRequest`, each applied step becomes its own change request and the working tree returns
+ * to where it started.
+ */
+export async function applyFreshness(options = {}, deps = defaultFreshnessDeps, runDeps = defaultRunDeps) {
+    const cwd = options.cwd ?? process.cwd();
+    const maxSteps = options.maxSteps ?? 1;
+    if (!Number.isInteger(maxSteps) || maxSteps < 1 || maxSteps > MAX_STEPS_LIMIT) {
+        throw new Error(`maxSteps must be a whole number from 1 to ${MAX_STEPS_LIMIT}.`);
+    }
+    // Earned autonomy: below L2 nothing is changed, exactly as for applyPlan.
+    assertAutonomyAllows(cwd, options.policy, "apply", "freshness apply");
+    const cache = new Map();
+    const skip = new Set();
+    const stopped = [];
+    const outcomes = [];
+    const awaiting = new Set();
+    const failedPackages = new Set();
+    let first;
+    let last;
+    let applied = 0;
+    let failed = 0;
+    while (applied < maxSteps && failed < MAX_FAILED_ATTEMPTS) {
+        const analysis = await analyse(options, deps, cache, skip);
+        first ??= analysis.report;
+        last = analysis;
+        const climb = analysis.eligible;
+        if (!climb)
+            break;
+        const planned = await record(climb, options, cwd);
+        const step = planned.step;
+        const base = {
+            step,
+            ...(planned.assessment ? { assessment: planned.assessment } : {}),
+            runId: planned.runId,
+            planId: planned.planId,
+        };
+        const run = await applyPlan({
+            cwd,
+            runId: planned.runId,
+            ...(options.verify === undefined ? {} : { verify: options.verify }),
+            ...(options.repair === undefined ? {} : { repair: options.repair }),
+            ...(options.model ? { model: options.model } : {}),
+            ...(options.repairAgent ? { repairAgent: options.repairAgent } : {}),
+            ...(options.repairBudget ? { repairBudget: options.repairBudget } : {}),
+            ...(options.signal ? { signal: options.signal } : {}),
+        }, runDeps).catch((error) => {
+            // A refusal is not a failed step: stop here instead of recording every remaining package as failed.
+            if (error instanceof AutonomyRefusedError)
+                throw error;
+            return {
+                status: "failed",
+                message: error instanceof Error ? error.message : String(error),
+                items: [],
+            };
+        });
+        const runSummary = { status: run.status, message: run.message };
+        if (run.status === "applied") {
+            applied++;
+            const outcome = {
+                ...base,
+                status: "applied",
+                message: `Upgraded ${describeStep(step)}.`,
+                run: runSummary,
+            };
+            outcomes.push(outcome);
+            if (options.changeRequest?.enabled) {
+                await openChangeRequest(outcome, options, cwd, runDeps);
+                // The step now lives on its own branch for review. A later step of the same package would
+                // build on a change that is not merged, so it waits for the next call.
+                skip.add(step.packageName);
+                if (step.index < step.of) {
+                    awaiting.add(step.packageName);
+                    stopped.push({
+                        packageName: step.packageName,
+                        reason: `step ${step.index} of ${step.of} awaits review in its change request; the next step comes after it is merged.`,
+                    });
+                }
+            }
+            continue;
+        }
+        // The step did not hold. The verifier or the project's own checks already took it back out; the
+        // rollback closes the run's record and makes sure the project is exactly as before.
+        failed++;
+        const detail = run.items?.[0]?.message ?? run.message;
+        const rolledBack = await rollbackRun({ cwd, runId: planned.runId, force: true }, runDeps)
+            .then(() => true)
+            .catch(() => false);
+        outcomes.push({
+            ...base,
+            status: "failed",
+            message: `${describeStep(step)} did not hold: ${detail}`,
+            run: runSummary,
+            rolledBack,
+        });
+        stopped.push({ packageName: step.packageName, reason: detail });
+        failedPackages.add(step.packageName);
+        skip.add(step.packageName);
+    }
+    // The loop always runs once with maxSteps >= 1 and a failure budget above 0; this is for exactness.
+    first ??= (await analyse(options, deps, cache, skip)).report;
+    for (const entry of last?.held ?? [])
+        stopped.push(entry);
+    // Packages with a step still to take, by the last analysis (taken before the step that followed it).
+    const doneWith = (name, steps) => steps <= 1 && outcomes.some((o) => o.step.packageName === name && o.status === "applied");
+    const remaining = [
+        ...new Set([
+            ...(last?.climbs ?? [])
+                .filter((climb) => !climb.held &&
+                !failedPackages.has(climb.packageName) &&
+                !doneWith(climb.packageName, climb.steps.length))
+                .map((climb) => climb.packageName),
+            ...awaiting,
+        ]),
+    ];
+    const status = outcomes.length === 0
+        ? "nothing-to-do"
+        : failed === 0
+            ? "ok"
+            : applied === 0
+                ? "failed"
+                : "partial";
+    return {
+        status,
+        steps: outcomes,
+        stopped,
+        remaining,
+        report: first,
+        message: summarise(status, applied, failed, remaining.length, first),
+    };
+}
+function summarise(status, applied, failed, remaining, report) {
+    if (status === "nothing-to-do") {
+        if (!report.policy)
+            return "The policy has no `freshness` key, so there is no limit to climb towards.";
+        return report.climbs.length === 0
+            ? "Every direct dependency is within the freshness policy."
+            : "Every step that is due is held; see stopped.";
+    }
+    return `${applied} step(s) applied, ${failed} failed and rolled back; ${remaining} package(s) still have steps to take.`;
+}
+async function openChangeRequest(outcome, options, cwd, runDeps) {
+    const report = {
+        ...stepReport(outcome.step, outcome.assessment, true),
+        ...(outcome.runId ? { runId: outcome.runId } : {}),
+    };
+    try {
+        const [result] = await createChangeRequestsForReports({
+            cwd,
+            options: options.changeRequest,
+            reports: [report],
+        });
+        if (result) {
+            outcome.changeRequest = result;
+            if (result.error)
+                outcome.message = `${outcome.message} Change request not created: ${result.error}`;
+        }
+    }
+    catch (error) {
+        outcome.message = `${outcome.message} Change request not created: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    // The step's change now sits on its own branch and the working tree is back on the base branch,
+    // so node_modules must follow the lockfile again before the next step is tried.
+    if (outcome.changeRequest?.created) {
+        await runDeps
+            .reinstall({
+            cwd,
+            options: options.packageManager ? { packageManager: options.packageManager } : undefined,
+        })
+            .catch((error) => {
+            outcome.message = `${outcome.message} Reinstall after returning to the base branch failed: ${error instanceof Error ? error.message : String(error)}`;
+        });
+    }
+}
+//# sourceMappingURL=step.js.map

package/dist/api/freshness/step.js.map

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

package/dist/api/freshness/types.d.ts

@@ -0,0 +1,192 @@
+import type { FreshnessPolicy } from "../../platform/freshness-policy.js";
+import type { ChangeRequestOptions, ChangeRequestResult, PackageManager, RemediateOptions } from "../../platform/types.js";
+import type { Breakability } from "../../remediation/impact/impact.js";
+import type { ApplyPlanOptions, RunReport } from "../runs/index.js";
+export type { FreshnessPolicy };
+/** How a package stands against the latest release. The distances are 0 for a current package. */
+export interface FreshnessDistance {
+    /** Latest major minus installed major. */
+    majorsBehind: number;
+    /** Latest minor minus installed minor, counted only when the installed copy is on the latest major. */
+    minorsBehind: number;
+    /** Latest patch minus installed patch, counted only when major and minor match. */
+    patchesBehind: number;
+    /** Stable releases newer than the installed version, up to the latest. Needs the registry's version list. */
+    releasesBehind?: number;
+    /** Days since the installed version was published. Needs the registry's publish times. */
+    ageDays?: number;
+}
+export type FreshnessStatus = "current" | "behind" | "ignored" | "not-installed" | "unreadable";
+export interface FreshnessPackage extends Partial<FreshnessDistance> {
+    name: string;
+    field: "dependencies" | "devDependencies";
+    /** The range in package.json. */
+    range: string;
+    /** The installed version; absent when the dependency is not installed. */
+    installed?: string;
+    /** The latest release the registry reports; equal to `installed` for a current package. */
+    latest?: string;
+    status: FreshnessStatus;
+    /** 0 (current) to 100 (far behind); see the guide for how it is made. Only for packages that count. */
+    penalty?: number;
+    /** The policy limits this package is past, in words. Empty when it is within them or there is no policy. */
+    exceeds: string[];
+    /**
+     * Set when the policy has `maxAgeDays`, the package is behind, and the installed version's publish
+     * time is unknown (the registry could not be read or does not list the version): the age limit
+     * cannot be checked, so the package is neither within policy nor climbed. The value says why.
+     */
+    unknownAge?: string;
+}
+/** What `assessUpgrade` said about a step, or that it could not say. */
+export interface StepAssessment {
+    breakability: Breakability | "Unknown";
+    score?: number;
+    summary: string;
+}
+/** One verified upgrade: one package, one jump. */
+export interface FreshnessStep {
+    packageName: string;
+    field: "dependencies" | "devDependencies";
+    fromVersion: string;
+    toVersion: string;
+    level: "patch" | "minor" | "major";
+    /**
+     * `catch-up` stays inside the installed breaking boundary; `major` crosses into the next one. A
+     * boundary is a major, or, for a 0.x version, a 0.minor (0.x minors may break).
+     */
+    kind: "catch-up" | "major";
+    /** The release this step lands on is deprecated, and no other candidate exists: the step is held. */
+    deprecated?: true;
+    /** 1-based position in this package's climb, and how many steps the climb has. */
+    index: number;
+    of: number;
+}
+export type HeldReason = "high-breakability" | "major-bump-not-allowed" | "only-newer-release-deprecated" | "package-not-allowed";
+export interface FreshnessClimb {
+    packageName: string;
+    installed: string;
+    latest: string;
+    /** Every step needed to get inside the policy, in order. Only the first is ever taken in one go. */
+    steps: FreshnessStep[];
+    /** What `assessUpgrade` says about the first step. Absent when assessment was not requested. */
+    assessment?: StepAssessment;
+    /** Why the first step will not be taken. A held climb is reported and never applied. */
+    held?: {
+        reason: HeldReason;
+        message: string;
+    };
+}
+export interface FreshnessCounts {
+    /** Direct dependencies in package.json that come from a registry. */
+    direct: number;
+    current: number;
+    behind: number;
+    ignored: number;
+    notInstalled: number;
+    /** Installed, but a version that cannot be read as semver. Not counted in the score. */
+    unreadable: number;
+    /** Behind and past a policy limit. */
+    exceeding: number;
+    /** Behind, with `maxAgeDays` set, and an unknown publish time: the age limit could not be checked. */
+    unknownAge: number;
+}
+export interface FreshnessReport {
+    schemaVersion: "1.0";
+    generatedAt: string;
+    cwd: string;
+    packageManager: PackageManager;
+    /** The policy's `freshness` key; null when there is none, and then nothing is planned. */
+    policy: FreshnessPolicy | null;
+    /** 0 to 100, higher is fresher. 100 when there is nothing to count. */
+    score: number;
+    counts: FreshnessCounts;
+    /** Behind packages first, worst penalty first; then current ones, then the rest. */
+    packages: FreshnessPackage[];
+    /** One climb per package past the policy, in the order the steps would be taken. */
+    climbs: FreshnessClimb[];
+    /** Packages past the policy, or whose age could not be checked, for which no climb could be made, with why. */
+    unplanned: Array<{
+        packageName: string;
+        reason: string;
+    }>;
+    notes: string[];
+}
+export interface FreshnessOptions {
+    /** Project directory (default: process.cwd()). */
+    cwd?: string;
+    /** Policy file path or inline policy (default: `.github/autoremediator.yml`). */
+    policy?: string;
+    packageManager?: PackageManager;
+    /** Only these packages. */
+    packages?: string[];
+    /** Rate the first step of each climb with `assessUpgrade` to order and hold them. Default false for the report. */
+    assess?: boolean;
+    /** Take steps `assessUpgrade` rates High. They are held otherwise. */
+    allowHigh?: boolean;
+    /**
+     * Plan as if the repository's memory were empty: pinned packages and rejected upgrades in
+     * `.autoremediator/memory.md` are not consulted. SDK and CLI only, never over MCP or HTTP.
+     */
+    ignoreMemory?: boolean;
+}
+export interface PlanFreshnessStepOptions extends Omit<FreshnessOptions, "assess"> {
+    /** Never rate steps (default: they are rated, since the rating orders and holds them). */
+    assess?: boolean;
+    runTests?: boolean;
+    typecheck?: boolean;
+    /** Provenance recorded with the run. */
+    source?: RemediateOptions["source"];
+}
+export interface PlannedFreshnessStep {
+    step: FreshnessStep;
+    assessment?: StepAssessment;
+    runId: string;
+    planId: string;
+}
+export interface FreshnessPlanResult {
+    /** The step now waiting as a recorded plan; absent when nothing is eligible. */
+    planned?: PlannedFreshnessStep;
+    /** Why no plan was recorded, when none was. */
+    reason?: string;
+    held: Array<{
+        packageName: string;
+        reason: string;
+    }>;
+    report: FreshnessReport;
+}
+export interface ApplyFreshnessOptions extends PlanFreshnessStepOptions, Pick<ApplyPlanOptions, "repair" | "model" | "repairAgent" | "repairBudget" | "signal" | "verify"> {
+    /** Most steps to take in this call (default 1: a scheduled job takes one reviewable step per run). */
+    maxSteps?: number;
+    /** One change request per step, on a branch named for the package and step. Needs a git repository. */
+    changeRequest?: ChangeRequestOptions;
+}
+export type StepOutcomeStatus = "applied" | "failed" | "skipped";
+export interface FreshnessStepOutcome {
+    step: FreshnessStep;
+    assessment?: StepAssessment;
+    runId?: string;
+    planId?: string;
+    status: StepOutcomeStatus;
+    message: string;
+    /** The step's own run, after apply (and rollback, if it failed). */
+    run?: Pick<RunReport, "status" | "message">;
+    /** A failed step was taken back out with `rollbackRun`. */
+    rolledBack?: boolean;
+    changeRequest?: ChangeRequestResult;
+}
+export interface ApplyFreshnessResult {
+    status: "ok" | "partial" | "failed" | "nothing-to-do";
+    steps: FreshnessStepOutcome[];
+    /** Packages the planner stopped on, with why: a failed step, or a held one. */
+    stopped: Array<{
+        packageName: string;
+        reason: string;
+    }>;
+    /** Packages with a step still to take after this call. */
+    remaining: string[];
+    /** The report before the first step. */
+    report: FreshnessReport;
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/api/freshness/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/api/freshness/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,cAAc,EACd,gBAAgB,EACjB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEpE,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,kGAAkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,YAAY,EAAE,MAAM,CAAC;IACrB,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;IACtB,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,eAAe,GAAG,YAAY,CAAC;AAEhG,MAAM,WAAW,gBAAiB,SAAQ,OAAO,CAAC,iBAAiB,CAAC;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAAC;IAC1C,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,eAAe,CAAC;IACxB,uGAAuG;IACvG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4GAA4G;IAC5G,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wEAAwE;AACxE,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,YAAY,GAAG,SAAS,CAAC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAAC;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;IACnC;;;OAGG;IACH,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,qGAAqG;IACrG,UAAU,CAAC,EAAE,IAAI,CAAC;IAClB,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,UAAU,GAClB,mBAAmB,GACnB,wBAAwB,GACxB,+BAA+B,GAC/B,qBAAqB,CAAC;AAE1B,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,oGAAoG;IACpG,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,gGAAgG;IAChG,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,wFAAwF;IACxF,IAAI,CAAC,EAAE;QAAE,MAAM,EAAE,UAAU,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAChD;AAED,MAAM,WAAW,eAAe;IAC9B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,wFAAwF;IACxF,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,KAAK,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,EAAE,cAAc,CAAC;IAC/B,0FAA0F;IAC1F,MAAM,EAAE,eAAe,GAAG,IAAI,CAAC;IAC/B,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,eAAe,CAAC;IACxB,oFAAoF;IACpF,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,oFAAoF;IACpF,MAAM,EAAE,cAAc,EAAE,CAAC;IACzB,+GAA+G;IAC/G,SAAS,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mHAAmH;IACnH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CAAC,gBAAgB,EAAE,QAAQ,CAAC;IAChF,0FAA0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,wCAAwC;IACxC,MAAM,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,MAAM,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,qBACf,SACE,wBAAwB,EACxB,IAAI,CACF,gBAAgB,EAChB,QAAQ,GAAG,OAAO,GAAG,aAAa,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAC1E;IACH,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uGAAuG;IACvG,aAAa,CAAC,EAAE,oBAAoB,CAAC;CACtC;AAED,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,aAAa,CAAC;IACpB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,CAAC,CAAC;IAC5C,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,IAAI,GAAG,SAAS,GAAG,QAAQ,GAAG,eAAe,CAAC;IACtD,KAAK,EAAE,oBAAoB,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,OAAO,EAAE,KAAK,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD,0DAA0D;IAC1D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wCAAwC;IACxC,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/api/freshness/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/api/freshness/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/api/freshness/types.ts"],"names":[],"mappings":""}

package/dist/api/guard/checks.d.ts

@@ -0,0 +1,31 @@
+import type { GuardAlternative, GuardFinding } from "./types.js";
+export interface PackumentVersion {
+    version: string;
+    scripts?: Record<string, string>;
+    deprecated?: string;
+    dist?: {
+        attestations?: unknown;
+    };
+}
+/** The parts of a full npm packument that the checks read. */
+export interface Packument {
+    name: string;
+    "dist-tags"?: Record<string, string>;
+    time?: Record<string, string>;
+    versions?: Record<string, PackumentVersion>;
+}
+/** Which version a range or tag installs. Prefers stable, non-deprecated releases. */
+export declare function resolveVersion(packument: Packument, range: string | undefined): string | undefined;
+export interface JudgeInput {
+    packument: Packument;
+    version: string;
+    now: number;
+    minPublishAgeHours: number;
+}
+/** Checks that need only the registry document. */
+export declare function judgePackument(input: JudgeInput): {
+    findings: GuardFinding[];
+    alternative?: GuardAlternative;
+};
+export declare function verdictOf(findings: readonly GuardFinding[]): "allow" | "warn" | "block";
+//# sourceMappingURL=checks.d.ts.map

package/dist/api/guard/checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.d.ts","sourceRoot":"","sources":["../../../src/api/guard/checks.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEjE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE;QAAE,YAAY,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CACnC;AAED,8DAA8D;AAC9D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;CAC7C;AAWD,sFAAsF;AACtF,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,GAAG,SAAS,CASpB;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,mDAAmD;AACnD,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG;IACjD,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,WAAW,CAAC,EAAE,gBAAgB,CAAC;CAChC,CA+EA;AAED,wBAAgB,SAAS,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAGvF"}

package/dist/api/guard/checks.js

@@ -0,0 +1,101 @@
+import semver from "semver";
+import { findLookalike } from "./popular.js";
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+const INSTALL_SCRIPTS = ["preinstall", "install", "postinstall"];
+const hasInstallScripts = (v) => INSTALL_SCRIPTS.some((key) => Boolean(v?.scripts?.[key]));
+const hasProvenance = (v) => Boolean(v?.dist?.attestations);
+const cleanText = (text) => text.replaceAll(/\s+/g, " ").slice(0, 160);
+/** Which version a range or tag installs. Prefers stable, non-deprecated releases. */
+export function resolveVersion(packument, range) {
+    const tags = packument["dist-tags"] ?? {};
+    const versions = packument.versions ?? {};
+    if (!range)
+        return tags.latest;
+    if (range in tags)
+        return tags[range];
+    if (semver.valid(range) && versions[range])
+        return range;
+    const all = Object.keys(versions).filter((v) => semver.valid(v));
+    const stable = all.filter((v) => !semver.prerelease(v) && !versions[v]?.deprecated);
+    return semver.maxSatisfying(stable, range) ?? semver.maxSatisfying(all, range) ?? undefined;
+}
+/** Checks that need only the registry document. */
+export function judgePackument(input) {
+    const { packument, version, now, minPublishAgeHours } = input;
+    const findings = [];
+    let alternative;
+    const versions = packument.versions ?? {};
+    const current = versions[version];
+    const name = packument.name;
+    const publishedAt = packument.time?.[version] ? Date.parse(packument.time[version]) : Number.NaN;
+    const ageMs = now - publishedAt;
+    // Look-alike names are only worrying for packages that have not been around long.
+    const lookalike = findLookalike(name);
+    if (lookalike) {
+        const created = packument.time?.created ? Date.parse(packument.time.created) : Number.NaN;
+        const young = Number.isFinite(created) && now - created < 30 * DAY;
+        findings.push({
+            check: "typosquat",
+            severity: young ? "block" : "warn",
+            message: `"${name}" looks like "${lookalike}"${young ? ", and was first published less than 30 days ago" : ""}. Check that you meant it.`,
+        });
+        alternative = { packageName: lookalike, reason: "the widely used package with a similar name" };
+    }
+    if (Number.isFinite(ageMs) && minPublishAgeHours > 0 && ageMs < minPublishAgeHours * HOUR) {
+        findings.push({
+            check: "cooldown",
+            severity: "block",
+            message: `${name}@${version} was published ${(ageMs / HOUR).toFixed(1)} hours ago; the minimum age is ${minPublishAgeHours} hours. New releases are where compromised packages show up first.`,
+        });
+        const cutoff = now - minPublishAgeHours * HOUR;
+        const older = Object.keys(versions)
+            .filter((v) => semver.valid(v) && !semver.prerelease(v) && !versions[v]?.deprecated)
+            .filter((v) => Date.parse(packument.time?.[v] ?? "") < cutoff)
+            .toSorted((a, b) => semver.rcompare(a, b))[0];
+        if (older) {
+            alternative = {
+                packageName: name,
+                version: older,
+                reason: "the newest release that is old enough",
+            };
+        }
+    }
+    // Compare with the release before this one.
+    const earlier = Object.keys(versions)
+        .filter((v) => semver.valid(v) && !semver.prerelease(v) && semver.lt(v, version))
+        .toSorted((a, b) => semver.rcompare(a, b))[0];
+    const previous = earlier ? versions[earlier] : undefined;
+    if (hasInstallScripts(current)) {
+        const added = previous !== undefined && !hasInstallScripts(previous);
+        const recent = Number.isFinite(ageMs) && ageMs < 7 * DAY;
+        findings.push({
+            check: "install-scripts",
+            severity: added && recent ? "block" : "warn",
+            message: added
+                ? `${name}@${version} runs install scripts that ${earlier} did not${recent ? ", and it was published this week" : ""}. Install scripts run code on your machine at install time.`
+                : `${name}@${version} runs install scripts (${INSTALL_SCRIPTS.filter((k) => current?.scripts?.[k]).join(", ")}).`,
+        });
+    }
+    if (!hasProvenance(current) && hasProvenance(previous)) {
+        findings.push({
+            check: "provenance",
+            severity: "warn",
+            message: `${earlier} was published with build provenance and ${version} was not. A release made outside the usual pipeline can mean a stolen publish token.`,
+        });
+    }
+    if (current?.deprecated) {
+        findings.push({
+            check: "deprecated",
+            severity: "warn",
+            message: `${name}@${version} is deprecated: ${cleanText(current.deprecated)}`,
+        });
+    }
+    return { findings, ...(alternative ? { alternative } : {}) };
+}
+export function verdictOf(findings) {
+    if (findings.some((finding) => finding.severity === "block"))
+        return "block";
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "allow";
+}
+//# sourceMappingURL=checks.js.map