Reference

Map a day-config dict into a typed ReleaseType -> int map.

Keys must match a ReleaseType value (major, minor, patch, default, case-insensitive). Unknown keys raise ConfigError so user typos surface immediately instead of being silently ignored. Non-integer values also raise ConfigError.

Map a raw fix-style value into a typed FixStyle.

Returns None when the value is missing so callers can distinguish "not configured" from "explicitly set". Unknown names raise ConfigError with the list of valid choices.

Map a list of group names into a typed tuple of DependencyGroup.

Returns None when the value is missing so callers can distinguish "not configured" from "explicitly empty". An explicit empty list is accepted and means "check nothing"; the runner will produce an empty report in that case. Unknown group names raise ConfigError.

Return the cooldown threshold (days) for the given release type.

The cooldown_days map is always fully populated thanks to per-key gap-fill in the field validator, so a direct lookup is safe for every ReleaseType member.

Remove the state file from disk if it exists.

Used when a fix run produces no managed pins, so we do not leave behind an empty file that suggests we are still tracking something.

Return a fresh, empty state with last_run_at set to now.

Read the state file at root / STATE_FILENAME.

Returns an empty state when the file is simply absent (the common, expected case for a first run). Every other failure mode halts: chill-out's bookkeeping is too important to silently discard. The file is chill-out's own output, so any read failure points at a bug, a partial write, a permissions problem, or a version mismatch — none of which should be papered over.

Raises:

Write the current state to root / STATE_FILENAME.

The output is pretty-printed JSON with a trailing newline so it diffs cleanly under version control. Datetimes are rendered as RFC 3339 / ISO 8601 strings via the Pydantic field serializers in state.schema.

Apply the given fix actions to the project.

Returns an AppliedFixes carrying one AppliedFix per entry actually written to the project's manifests, plus a list of human-readable log lines describing the changes for the CLI to surface. The per-entry records capture the literal pinned_spec written to disk so the next run can detect whether the user has since edited it (drift) and clean stale entries up before planning fresh fixes.

Apply fixes via the ecosystem's override mechanism.

Used as a fallback when a normal direct pin doesn't dislodge a violating version (typically because it stays hoisted at a parent level the direct pin can't reach). The exact mechanism varies by ecosystem (see supports_overrides for a survey); the contract here is the same regardless of which one a backend reaches for.

Returns an AppliedFixes carrying one entry per override actually written plus human-readable log lines, or None when the ecosystem doesn't support an override mechanism.

Return all release info for name, or None if it cannot be retrieved.

Caching and in-flight dedupe live one layer up in RegistryClient; backends do neither and just translate one HTTP call into a PackageInfo.

Return the dependency declarations for a single (name, version) pair.

Used by principal-rollback to discover which transitive ranges a candidate principal version declares. Returns None if the manifest cannot be retrieved.

Enumerate every package in the project's lockfile.

Returns the full resolved dependency set, principals and transitives alike. Each InstalledPackage carries enough context (via_chain, groups, member_owners) for downstream filters and fix planning to tell them apart.

Parse a version string the way this ecosystem parses one.

Returns None for inputs that don't fit the ecosystem's version grammar; the cooldown engine treats that as "skip this candidate" rather than raising, so a single weird release never blocks the rest of the search. The returned ParsedVersion carries everything the engine needs (release segments, pre-release flag, and an opaque sort key) without the engine having to know which flavor of version it's looking at.

Return True if version satisfies the ecosystem-specific range_spec.

Used by principal-rollback to test whether a candidate principal's declared range admits the safe transitive version.

Recompute the project's lockfile from its current manifests.

Used by the fix workflow after a cleanup pass that removed stale managed pins but did not apply any fresh fixes (the apply step regenerates the lockfile on its own when it runs). Returns a short human-readable line describing the action taken so the CLI can surface it in its log output.

Implementations should raise EcosystemError if regeneration fails.

Try to undo a previously-applied managed pin from this project's manifests.

Used by the fix workflow to clean stale pins before computing a new round of fixes, so cooldowns that have elapsed in the meantime do not leave their pins behind.

Implementations look up pin.package at the site recorded in pin.manifest_path (interpreted relative to self.root) using the appropriate mechanism for pin.mechanism, and:

• Return RemovalOutcome.REMOVED if the entry is still present and matches the recorded pin.pinned_spec. The entry is deleted in place.
• Return RemovalOutcome.DRIFTED if the entry is present but its value differs from the recorded value. Implementations leave the entry untouched; the caller is expected to drop the pin from state and warn the user.
• Return RemovalOutcome.ORPHAN if the entry is no longer present at all. Implementations leave the manifest alone; the caller drops the pin silently.

Implementations must not run lockfile regeneration; the runner orchestrates that step once after the full batch of removals.

Return True if this ecosystem implements an override mechanism.

Most package managers expose some flavor of "force one resolution everywhere regardless of who declared it" knob (npm overrides, yarn resolutions, pnpm pnpm.overrides, uv override-dependencies, cargo [patch], go replace, maven dependencyManagement, gradle resolutionStrategy.force). A handful of others, notably bundler and composer, don't, so backends for those ecosystems return False here and the runner falls back to plain direct pins.

Detect a multi-member workspace and return its layout.

Returns None for standalone (single-root) projects or when no workspace declaration is present.

Return True if this ecosystem applies to the given project root.

Apply pins. Routes via_overrides actions through apply_override_fixes.

Splits the incoming actions into two groups based on the via_overrides flag, which the planner sets for shared transitive violations in workspace contexts. Direct pins land in self.root's package.json dependencies; override pins go through the workspace-root override path. Both groups trigger their own npm install, in this order: write direct pins first, then npm install from the member, then write overrides at the workspace root, then npm install from there.

When the override path returns None (the planner tagged via_overrides but no workspace root could be located), the action falls back to a direct pin so it isn't silently lost. That fallback is genuinely defensive: with the current planner and the two shipping ecosystems, the override path always resolves when the planner asked for it.

Force transitive versions via npm's overrides field.

Direct pins in dependencies only affect what the project's own code resolves to. When a violating version is hoisted at the workspace-root node_modules (where a different consumer in the tree pulled it in), a direct pin in a workspace-member's package.json can leave that root copy untouched. overrides is npm's blessed mechanism for forcing one resolution everywhere regardless of who declared it.

Overrides must live in the workspace root's package.json to apply tree-wide, so this writes to the directory that owns the lockfile rather than self.root (which may be a workspace member). When that root manifest doesn't exist, return None so the caller can fall back to direct pinning.

Fetch all release timestamps for a package from the npm registry.

Returns None if the package is missing (404). Raises RegistryError on transport failures, non-2xx responses other than 404, non-JSON bodies, or any drift in the response shape that fails Pydantic validation.

Fetch dependency declarations for {name}@{version} from the npm registry.

Returns None for 404 responses. Merges dependencies and peerDependencies into a single deps map; npm treats peer deps as runtime constraints just like regular deps for resolution purposes, so the cooldown engine should see both when checking whether a safe transitive can be hoisted.

Load the full dependency tree from npm list.

The returned list contains every package npm reports as installed, principals (top-level installs) and transitives alike. Each InstalledPackage is keyed by (name, version) because npm routinely installs multiple copies of the same package at different versions in different branches of node_modules; each copy actually loads at runtime for whichever code requires it, so we report them independently.

The work happens in three phases that mirror the pypi backend's shape:

1. Run npm list to materialize the dependency tree, optionally also at the workspace root for cross-member ownership attribution.
2. Read the project's own package.json to learn which top-level names belong to which semantic group.
3. Walk the tree once per top-level entry to attribute every reachable (name, version) to its principal's groups, then a second walk to assemble the actual InstalledPackage records with their via_chain and ownership metadata.

Parse a version string with strict semver semantics.

npm publishes its registry data in semver form (MAJOR.MINOR.PATCH with optional -prerelease and +build), so anything that doesn't fit that grammar gets None. The cooldown engine treats None as "skip this candidate" rather than raising, so a non-semver oddity like a date-tagged version doesn't block the rest of the search.

The returned ParsedVersion carries the original string verbatim so safe versions round-trip back through fix actions in the exact form the registry published.

The sort key wraps the parsed semver.Version itself in a single-element tuple. semver.Version already compares the way npm expects (pre-releases sort before their final version, build metadata is ignored), so we don't need anything custom here.

Check whether version satisfies an npm semver range_spec.

Shells out to node -e "require('semver').satisfies(...)". If node or the semver package isn't available, conservatively returns True (the original script's "assume compatible" fallback for transitive deps with no discoverable range).

Recompute package-lock.json by running npm install from the project root.

Reverse a previously-applied managed pin from the project's package.json.

For PinMechanism.DIRECT this removes the entry from dependencies (and the parallel devDependencies, optionalDependencies, peerDependencies blocks if the pin landed there). For PinMechanism.OVERRIDE this removes the entry from overrides at the recorded manifest path.

See Ecosystem.remove_managed_pin for outcome semantics.

Detect an npm workspace by reading the lockfile-rooted package.json.

Walks up to find the workspace root (the directory that owns the lockfile, which may be self.root itself or an ancestor for a member project). If the root's package.json declares a workspaces field, expand the globs against the root directory and read each member's name from its own package.json.

Returns None when there's no lockfile, no workspaces field, or none of the globs resolve to a directory with a readable package.json.

The work is split into _locate_workspace_root, which finds the directory that owns the lockfile and reads its package.json, and _discover_workspace_members, which expands the glob patterns and assembles the name -> directory map. Both helpers are static so they can be exercised independently of a live NpmEcosystem instance.

Return the publish timestamp for the given version, if known.

Apply pins. Routes via_overrides actions through apply_override_fixes.

Direct pins are written into self.root's pyproject.toml and validated with uv lock. Override pins go through the workspace root's [tool.uv].override-dependencies field and trigger a workspace-wide uv lock to recompute the resolution.

Force transitive versions via uv's override-dependencies mechanism.

Writes one entry per action to [tool.uv].override-dependencies in the workspace root's pyproject.toml (or self.root when there's no workspace), then runs uv lock from that directory to recompute the workspace-wide resolution. Returns an AppliedFixes on success, or None when no usable workspace root could be located.

Fetch all releases and their upload timestamps for a package from PyPI.

The PyPI JSON API returns one entry per uploaded artifact; we take the earliest upload time for each version as its publish date. Releases with no surviving uploads (empty artifact list) are dropped from the result. Schema validation guarantees every artifact carries at least one usable timestamp, so any release with at least one artifact will produce a PackageRelease.

Fetch the dependency declarations for a single PyPI release.

Pulls info.requires_dist from the per-version JSON endpoint. Markers that gate a requirement on an extra are skipped: those represent optional installs and don't constrain the base resolution.

Enumerate every package in uv.lock, principals and transitives alike.

The lockfile is the source of truth for what will actually be installed. Each entry becomes an InstalledPackage with a via_chain computed by reverse-graph BFS from the direct deps declared in pyproject.toml. Direct deps get an empty via_chain (they are principals); transitives get the shortest chain of intermediates back to a principal.

Group attribution follows the same union semantic as npm: forward-walk from each principal and tag every reachable package with that principal's groups. Transitives reached through multiple principals accumulate the union, matching the runner's "included if reachable through any included group" rule.

Requires uv.lock to exist; raises EcosystemError if it's missing (run uv lock to generate one).

Parse a version string with PEP 440 semantics.

PEP 440 is a superset of semver for parsing purposes: anything packaging.Version accepts (including 2-segment releases like 3.12, post-releases like 1.0.post1, epochs like 1!2.0, and dev releases) becomes a usable ParsedVersion. Inputs outside that grammar return None; the cooldown engine treats None as "skip this candidate" rather than raising.

Short releases get zero-padded for the major / minor / micro view: 3.12 reports major=3, minor=12, micro=0 so the engine classifies it as a minor release. Versions with more than three release segments truncate to the first three for classification but keep the full release tuple in the sort key, so 1.2.3.4 still sorts after 1.2.3 the way packaging compares it.

The original string is preserved verbatim so safe versions round-trip back through fix actions in the exact form the registry published, even when packaging would canonicalize it differently (e.g. 2.0.0-rc1 -> 2.0.0rc1).

The sort_key wraps packaging.Version in a single-element tuple. Version already implements PEP 440 ordering directly (epochs first, then release, then pre-release, then post-release, then dev-release); the tuple wrapper exists so the ParsedVersion.sort_key contract stays uniform across ecosystems.

Return True if version satisfies a PEP 440 range_spec.

An empty or whitespace-only range matches any version (matches packaging's SpecifierSet("") semantics). Unparsable inputs are treated permissively to match the original script's "assume compatible" behavior for transitive deps with no discoverable range.

Recompute uv.lock by running uv lock from the project root.

Reverse a previously-applied managed pin from the project's pyproject.toml.

For PinMechanism.DIRECT this removes the entry from [project.dependencies], [project.optional-dependencies], or [dependency-groups.*] (whichever holds it). For PinMechanism.OVERRIDE this removes the entry from [tool.uv.override-dependencies] at the recorded manifest path.

See Ecosystem.remove_managed_pin for outcome semantics.

Detect a uv workspace by walking up to find a pyproject.toml with [tool.uv.workspace].

Starts at self.root and walks toward the filesystem root until it finds a pyproject.toml declaring [tool.uv.workspace]. Reads members (glob patterns) and exclude, expands the globs, and returns a WorkspaceTopology keyed by each member's project.name.

Returns None when no workspace declaration is reachable from self.root.

Bind an ecosystem to an HTTP session and start with an empty cache.

Parameters:

Return release info for name, going to the registry only on a cache miss.

Return the dependency declarations for (name, version), cached after the first call.

Map a day-config dict into a typed ReleaseType -> int map.

Keys must match a ReleaseType value (major, minor, patch, default, case-insensitive). Unknown keys raise ConfigError so user typos surface immediately instead of being silently ignored. Non-integer values also raise ConfigError.

Map a raw fix-style value into a typed FixStyle.

Returns None when the value is missing so callers can distinguish "not configured" from "explicitly set". Unknown names raise ConfigError with the list of valid choices.

Map a list of group names into a typed tuple of DependencyGroup.

Returns None when the value is missing so callers can distinguish "not configured" from "explicitly empty". An explicit empty list is accepted and means "check nothing"; the runner will produce an empty report in that case. Unknown group names raise ConfigError.

Return the cooldown threshold (days) for the given release type.

The cooldown_days map is always fully populated thanks to per-key gap-fill in the field validator, so a direct lookup is safe for every ReleaseType member.

Return the publish timestamp for the given version, if known.

Apply the given fix actions to the project.

Returns an AppliedFixes carrying one AppliedFix per entry actually written to the project's manifests, plus a list of human-readable log lines describing the changes for the CLI to surface. The per-entry records capture the literal pinned_spec written to disk so the next run can detect whether the user has since edited it (drift) and clean stale entries up before planning fresh fixes.

Apply fixes via the ecosystem's override mechanism.

Used as a fallback when a normal direct pin doesn't dislodge a violating version (typically because it stays hoisted at a parent level the direct pin can't reach). The exact mechanism varies by ecosystem (see supports_overrides for a survey); the contract here is the same regardless of which one a backend reaches for.

Returns an AppliedFixes carrying one entry per override actually written plus human-readable log lines, or None when the ecosystem doesn't support an override mechanism.

Return all release info for name, or None if it cannot be retrieved.

Caching and in-flight dedupe live one layer up in RegistryClient; backends do neither and just translate one HTTP call into a PackageInfo.

Return the dependency declarations for a single (name, version) pair.

Used by principal-rollback to discover which transitive ranges a candidate principal version declares. Returns None if the manifest cannot be retrieved.

Enumerate every package in the project's lockfile.

Returns the full resolved dependency set, principals and transitives alike. Each InstalledPackage carries enough context (via_chain, groups, member_owners) for downstream filters and fix planning to tell them apart.

Parse a version string the way this ecosystem parses one.

Returns None for inputs that don't fit the ecosystem's version grammar; the cooldown engine treats that as "skip this candidate" rather than raising, so a single weird release never blocks the rest of the search. The returned ParsedVersion carries everything the engine needs (release segments, pre-release flag, and an opaque sort key) without the engine having to know which flavor of version it's looking at.

Return True if version satisfies the ecosystem-specific range_spec.

Used by principal-rollback to test whether a candidate principal's declared range admits the safe transitive version.

Recompute the project's lockfile from its current manifests.

Used by the fix workflow after a cleanup pass that removed stale managed pins but did not apply any fresh fixes (the apply step regenerates the lockfile on its own when it runs). Returns a short human-readable line describing the action taken so the CLI can surface it in its log output.

Implementations should raise EcosystemError if regeneration fails.

Try to undo a previously-applied managed pin from this project's manifests.

Used by the fix workflow to clean stale pins before computing a new round of fixes, so cooldowns that have elapsed in the meantime do not leave their pins behind.

Implementations look up pin.package at the site recorded in pin.manifest_path (interpreted relative to self.root) using the appropriate mechanism for pin.mechanism, and:

• Return RemovalOutcome.REMOVED if the entry is still present and matches the recorded pin.pinned_spec. The entry is deleted in place.
• Return RemovalOutcome.DRIFTED if the entry is present but its value differs from the recorded value. Implementations leave the entry untouched; the caller is expected to drop the pin from state and warn the user.
• Return RemovalOutcome.ORPHAN if the entry is no longer present at all. Implementations leave the manifest alone; the caller drops the pin silently.

Implementations must not run lockfile regeneration; the runner orchestrates that step once after the full batch of removals.

Return True if this ecosystem implements an override mechanism.

Most package managers expose some flavor of "force one resolution everywhere regardless of who declared it" knob (npm overrides, yarn resolutions, pnpm pnpm.overrides, uv override-dependencies, cargo [patch], go replace, maven dependencyManagement, gradle resolutionStrategy.force). A handful of others, notably bundler and composer, don't, so backends for those ecosystems return False here and the runner falls back to plain direct pins.

Detect a multi-member workspace and return its layout.

Returns None for standalone (single-root) projects or when no workspace declaration is present.

Apply pins. Routes via_overrides actions through apply_override_fixes.

Splits the incoming actions into two groups based on the via_overrides flag, which the planner sets for shared transitive violations in workspace contexts. Direct pins land in self.root's package.json dependencies; override pins go through the workspace-root override path. Both groups trigger their own npm install, in this order: write direct pins first, then npm install from the member, then write overrides at the workspace root, then npm install from there.

When the override path returns None (the planner tagged via_overrides but no workspace root could be located), the action falls back to a direct pin so it isn't silently lost. That fallback is genuinely defensive: with the current planner and the two shipping ecosystems, the override path always resolves when the planner asked for it.

Force transitive versions via npm's overrides field.

Direct pins in dependencies only affect what the project's own code resolves to. When a violating version is hoisted at the workspace-root node_modules (where a different consumer in the tree pulled it in), a direct pin in a workspace-member's package.json can leave that root copy untouched. overrides is npm's blessed mechanism for forcing one resolution everywhere regardless of who declared it.

Overrides must live in the workspace root's package.json to apply tree-wide, so this writes to the directory that owns the lockfile rather than self.root (which may be a workspace member). When that root manifest doesn't exist, return None so the caller can fall back to direct pinning.

Fetch all release timestamps for a package from the npm registry.

Returns None if the package is missing (404). Raises RegistryError on transport failures, non-2xx responses other than 404, non-JSON bodies, or any drift in the response shape that fails Pydantic validation.

Fetch dependency declarations for {name}@{version} from the npm registry.

Returns None for 404 responses. Merges dependencies and peerDependencies into a single deps map; npm treats peer deps as runtime constraints just like regular deps for resolution purposes, so the cooldown engine should see both when checking whether a safe transitive can be hoisted.

Load the full dependency tree from npm list.

The returned list contains every package npm reports as installed, principals (top-level installs) and transitives alike. Each InstalledPackage is keyed by (name, version) because npm routinely installs multiple copies of the same package at different versions in different branches of node_modules; each copy actually loads at runtime for whichever code requires it, so we report them independently.

The work happens in three phases that mirror the pypi backend's shape:

1. Run npm list to materialize the dependency tree, optionally also at the workspace root for cross-member ownership attribution.
2. Read the project's own package.json to learn which top-level names belong to which semantic group.
3. Walk the tree once per top-level entry to attribute every reachable (name, version) to its principal's groups, then a second walk to assemble the actual InstalledPackage records with their via_chain and ownership metadata.

Parse a version string with strict semver semantics.

npm publishes its registry data in semver form (MAJOR.MINOR.PATCH with optional -prerelease and +build), so anything that doesn't fit that grammar gets None. The cooldown engine treats None as "skip this candidate" rather than raising, so a non-semver oddity like a date-tagged version doesn't block the rest of the search.

The returned ParsedVersion carries the original string verbatim so safe versions round-trip back through fix actions in the exact form the registry published.

The sort key wraps the parsed semver.Version itself in a single-element tuple. semver.Version already compares the way npm expects (pre-releases sort before their final version, build metadata is ignored), so we don't need anything custom here.

Check whether version satisfies an npm semver range_spec.

Shells out to node -e "require('semver').satisfies(...)". If node or the semver package isn't available, conservatively returns True (the original script's "assume compatible" fallback for transitive deps with no discoverable range).

Recompute package-lock.json by running npm install from the project root.

Reverse a previously-applied managed pin from the project's package.json.

For PinMechanism.DIRECT this removes the entry from dependencies (and the parallel devDependencies, optionalDependencies, peerDependencies blocks if the pin landed there). For PinMechanism.OVERRIDE this removes the entry from overrides at the recorded manifest path.

See Ecosystem.remove_managed_pin for outcome semantics.

Detect an npm workspace by reading the lockfile-rooted package.json.

Walks up to find the workspace root (the directory that owns the lockfile, which may be self.root itself or an ancestor for a member project). If the root's package.json declares a workspaces field, expand the globs against the root directory and read each member's name from its own package.json.

Returns None when there's no lockfile, no workspaces field, or none of the globs resolve to a directory with a readable package.json.

The work is split into _locate_workspace_root, which finds the directory that owns the lockfile and reads its package.json, and _discover_workspace_members, which expands the glob patterns and assembles the name -> directory map. Both helpers are static so they can be exercised independently of a live NpmEcosystem instance.

Apply pins. Routes via_overrides actions through apply_override_fixes.

Direct pins are written into self.root's pyproject.toml and validated with uv lock. Override pins go through the workspace root's [tool.uv].override-dependencies field and trigger a workspace-wide uv lock to recompute the resolution.

Force transitive versions via uv's override-dependencies mechanism.

Writes one entry per action to [tool.uv].override-dependencies in the workspace root's pyproject.toml (or self.root when there's no workspace), then runs uv lock from that directory to recompute the workspace-wide resolution. Returns an AppliedFixes on success, or None when no usable workspace root could be located.

Fetch all releases and their upload timestamps for a package from PyPI.

The PyPI JSON API returns one entry per uploaded artifact; we take the earliest upload time for each version as its publish date. Releases with no surviving uploads (empty artifact list) are dropped from the result. Schema validation guarantees every artifact carries at least one usable timestamp, so any release with at least one artifact will produce a PackageRelease.

Fetch the dependency declarations for a single PyPI release.

Pulls info.requires_dist from the per-version JSON endpoint. Markers that gate a requirement on an extra are skipped: those represent optional installs and don't constrain the base resolution.

Enumerate every package in uv.lock, principals and transitives alike.

The lockfile is the source of truth for what will actually be installed. Each entry becomes an InstalledPackage with a via_chain computed by reverse-graph BFS from the direct deps declared in pyproject.toml. Direct deps get an empty via_chain (they are principals); transitives get the shortest chain of intermediates back to a principal.

Group attribution follows the same union semantic as npm: forward-walk from each principal and tag every reachable package with that principal's groups. Transitives reached through multiple principals accumulate the union, matching the runner's "included if reachable through any included group" rule.

Requires uv.lock to exist; raises EcosystemError if it's missing (run uv lock to generate one).

Parse a version string with PEP 440 semantics.

PEP 440 is a superset of semver for parsing purposes: anything packaging.Version accepts (including 2-segment releases like 3.12, post-releases like 1.0.post1, epochs like 1!2.0, and dev releases) becomes a usable ParsedVersion. Inputs outside that grammar return None; the cooldown engine treats None as "skip this candidate" rather than raising.

Short releases get zero-padded for the major / minor / micro view: 3.12 reports major=3, minor=12, micro=0 so the engine classifies it as a minor release. Versions with more than three release segments truncate to the first three for classification but keep the full release tuple in the sort key, so 1.2.3.4 still sorts after 1.2.3 the way packaging compares it.

The original string is preserved verbatim so safe versions round-trip back through fix actions in the exact form the registry published, even when packaging would canonicalize it differently (e.g. 2.0.0-rc1 -> 2.0.0rc1).

The sort_key wraps packaging.Version in a single-element tuple. Version already implements PEP 440 ordering directly (epochs first, then release, then pre-release, then post-release, then dev-release); the tuple wrapper exists so the ParsedVersion.sort_key contract stays uniform across ecosystems.

Return True if version satisfies a PEP 440 range_spec.

An empty or whitespace-only range matches any version (matches packaging's SpecifierSet("") semantics). Unparsable inputs are treated permissively to match the original script's "assume compatible" behavior for transitive deps with no discoverable range.

Recompute uv.lock by running uv lock from the project root.

Reverse a previously-applied managed pin from the project's pyproject.toml.

For PinMechanism.DIRECT this removes the entry from [project.dependencies], [project.optional-dependencies], or [dependency-groups.*] (whichever holds it). For PinMechanism.OVERRIDE this removes the entry from [tool.uv.override-dependencies] at the recorded manifest path.

See Ecosystem.remove_managed_pin for outcome semantics.

Detect a uv workspace by walking up to find a pyproject.toml with [tool.uv.workspace].

Starts at self.root and walks toward the filesystem root until it finds a pyproject.toml declaring [tool.uv.workspace]. Reads members (glob patterns) and exclude, expands the globs, and returns a WorkspaceTopology keyed by each member's project.name.

Returns None when no workspace declaration is reachable from self.root.

Remove the state file from disk if it exists.

Used when a fix run produces no managed pins, so we do not leave behind an empty file that suggests we are still tracking something.

Return a fresh, empty state with last_run_at set to now.

Read the state file at root / STATE_FILENAME.

Returns an empty state when the file is simply absent (the common, expected case for a first run). Every other failure mode halts: chill-out's bookkeeping is too important to silently discard. The file is chill-out's own output, so any read failure points at a bug, a partial write, a permissions problem, or a version mismatch — none of which should be papered over.

Raises:

Write the current state to root / STATE_FILENAME.

The output is pretty-printed JSON with a trailing newline so it diffs cleanly under version control. Datetimes are rendered as RFC 3339 / ISO 8601 strings via the Pydantic field serializers in state.schema.

Build a wire model from its dataclass twin.

Translate this validated wire model back into its dataclass twin.

Build a wire model from its dataclass twin.

Translate this validated wire model back into its dataclass twin.

Build a wire model from the in-memory dataclass for save().

Translate this validated wire model into the in-memory dataclass for load().