@ossiq/cli-darwin-arm64 0.1.12 → 0.1.14

package/bin/ossiq/_internal/ossiq/domain/README.md

@@ -12,7 +12,9 @@ This document lists the external specifications that define or inform the domain
 
 | Field | Registry | Meaning |
 |-------|----------|---------|
-| `is_deprecated: bool` | npm | The package's latest version carries a `deprecated` field — the whole package is considered deprecated. Set via `npm deprecate <pkg>`. |
+| `registry_status: RegistryStatus \| None` | npm / PyPI | The registry's verdict on the whole package, in PEP 792's vocabulary: `active`, `deprecated`, `archived`, `quarantined`. npm: `deprecated` when `versions[latest].deprecated` is set (via `npm deprecate <pkg>`), else `active`. PyPI: the Simple API's project status. `None` when the registry gave none, which is not `active`. |
+| `is_deprecated: bool` | npm / PyPI | Read-only, derived from `registry_status`: true for `deprecated` and `archived`. `quarantined` is an administrator's safety verdict, not a maintainer's decision, so it does not count. |
+| `deprecation_message: str \| None` | npm / PyPI | npm's `deprecated` note on the latest version, or PyPI's PEP 792 reason. |
 | `is_unpublished: bool` | npm | `time.unpublished` is present in the packument — the entire package was removed from the registry. |
 | `canonical_name: str \| None` | npm | When a package is installed under an npm alias (e.g. `"chalk-legacy": "npm:chalk@4"`), `name` is the alias and `canonical_name` is the real registry name used for lookups. `None` when `name` already is the canonical registry name. |
 
@@ -20,7 +22,8 @@ This document lists the external specifications that define or inform the domain
 
 | Field | Registry | Meaning |
 |-------|----------|---------|
-| `is_deprecated: bool` | npm | This specific version's manifest has a truthy `deprecated` field. |
+| `is_deprecated: bool` | npm | This specific version's manifest has a truthy `deprecated` field. PyPI has no per-release deprecation; a yanked release is its equivalent. |
+| `deprecation_message: str \| None` | npm | The `deprecated` note on this version. |
 | `is_yanked: bool` | PyPI | The version exists on PyPI but is marked yanked — excluded from normal resolution. |
 | `is_unpublished: bool` | npm | The version was individually deleted after release (present in `time` but absent from `versions`), or the entire package was unpublished (all versions inherit this flag). |
 | `is_prerelease: bool` | npm / PyPI | Version string contains a pre-release segment (e.g. `alpha`, `beta`, `rc`, `dev`). Set by registry adapters during version list construction. |
@@ -34,9 +37,11 @@ This document lists the external specifications that define or inform the domain
 | `is_installed_prerelease` | `version.is_prerelease` | Installed version is a pre-release. |
 | `is_installed_yanked` | `version.is_yanked or version.is_unpublished` | Installed version was pulled from the registry (covers both PyPI yanked and npm unpublished). |
 | `is_installed_deprecated` | `version.is_deprecated or package.is_deprecated` | Installed version or its parent package is deprecated. |
+| `registry_status` | `package.registry_status` | The registry's verdict on the whole package. Unlike `is_installed_deprecated`, a deprecated release of an otherwise live package does not show here. |
+| `deprecation_message` | `package.deprecation_message`, else the installed version's | The note behind the deprecation. |
 | `is_installed_package_unpublished` | `package.is_unpublished` | The entire package has been removed from the registry. |
 
-Display priority in all renderers: **UNPUBLISHED** > **YANKED** > **DEPRECATED** > pre-release.
+Display priority in all renderers: **UNPUBLISHED** > **YANKED** > **QUARANTINED** > **ARCHIVED** > **DEPRECATED** > pre-release.
 
 ---
 
@@ -126,6 +131,9 @@ Priority ordering for display: **OVERRIDE** > **ADDITIVE** > **PINNED** > **NARR
 | `type` | `ConstraintType` | Classification of the constraint (see above). |
 | `source_file` | `str \| None` | The file that declared it (e.g. `"package.json"`, `"pyproject.toml"`). |
 | `scope_path` | `list[str] \| None` | For npm nested overrides, the path through the dependency tree; `None` for flat constraints. |
+| `is_ossiq_authored` | `bool` | An `OVERRIDE` whose value is still what OSS IQ last wrote (`ossiq:metadata`); `False` for the user's own. |
+| `override_key` | `str \| None` | npm only: the range a version-keyed rule (`foo@^1`) applies to; `None` when it applies to every version. |
+| `override_value` | `str \| None` | npm only: what the matching rule forces — a version, a range or a `$name` reference. |
 
 ### `PeerRequirement` — peer constraint tracking
 
@@ -138,6 +146,16 @@ Priority ordering for display: **OVERRIDE** > **ADDITIVE** > **PINNED** > **NARR
 
 Violations (installed version not satisfying `spec`) are surfaced in `ScanRecord.peer_violations`.
 
+### `IncomingEdge` and `InstalledCopy` — who asked for which copy
+
+npm installs the same name at several versions (nested `node_modules`), so a package is not one node with a pile of constraints but several copies, each with its own requirers.
+
+`IncomingEdge` (in `project.py`) is one parent's requirement on an installed package: `requirer_name`, `requirer_version`, `spec` and `is_peer`. `Dependency.parent_edges` holds them next to `parent_constraints`, which remains the flat spec list the solver reads.
+
+`InstalledCopy` (in `project.py`) is one physical copy: its `version`, the `edges` that resolve to it, and its own `constraint_info`. `ScanRecord.installed_copies` lists every copy newest first; `installed_version` is the first. Under pip and uv there is always exactly one.
+
+The npm lockfile graph attaches each edge to the copy Node would resolve for that parent — the parent's own `node_modules`, then each ancestor's, up to the top level — which is how `package-lock.json` v2/v3 lays the tree out.
+
 ---
 
 ## Dependency Categories
@@ -285,6 +303,14 @@ Key response fields used:
 
 `yanked` maps to `PackageVersion.is_yanked`. A yanked version still exists on PyPI but is excluded from normal resolution; pip will refuse to install it unless the version is pinned exactly.
 
+### PyPI Simple API (PEP 792 project status)
+**Spec**: https://packaging.python.org/en/latest/specifications/project-status-markers/
+**Applies to**: `Package.registry_status`, `Package.deprecation_message`
+
+The JSON API above carries no project status. The Simple API does, in the head of each project page: `<meta name="pypi:project-status" content="archived">` and an optional `pypi:project-status-reason`. The statuses are `active`, `deprecated`, `archived` and `quarantined`; an index may omit the tag for an active project, so an absent tag reads as `active`.
+
+Endpoint: `https://pypi.org/simple/{name}/` with `Accept: application/vnd.pypi.simple.v1+html`. A page lists every file of the project (numpy's is 2 MB), so the request asks for the first 2 KB with a `Range` header and `Accept-Encoding: identity`; PyPI answers `206`. A failed request leaves `registry_status` as `None`.
+
 ### npm Registry API
 **Spec**: https://github.com/npm/registry/blob/master/docs/REGISTRY.md
 **Applies to**: `Package`, `PackageVersion`, `ProjectPackagesRegistry.NPM`
@@ -295,7 +321,7 @@ Key response fields used:
 - `name`, `description`, `author`, `homepage`, `repository.url`
 - `versions.{ver}.dependencies`, `versions.{ver}.devDependencies`, `versions.{ver}.peerDependencies`
 - `versions.{ver}.deprecated` — non-empty string means this version is deprecated → `PackageVersion.is_deprecated`
-- `dist-tags.latest` — current latest version; if `versions[latest].deprecated` is set → `Package.is_deprecated`
+- `dist-tags.latest` — current latest version; if `versions[latest].deprecated` is set → `Package.registry_status = DEPRECATED` (else `ACTIVE`), with the note in `Package.deprecation_message`
 - `time.{ver}` — publish timestamp per version
 - `time.unpublished` — present when the entire package was unpublished → `Package.is_unpublished`; every version also gets `PackageVersion.is_unpublished=True`
 - `dist.integrity`, `dist.tarball` — download and verification

package/bin/ossiq/_internal/ossiq/solver/README.md

@@ -15,6 +15,8 @@ solver/
 ├── problem.py             SolverProblem, CandidateVersion, PackageConstraint
 ├── universe.py            SolvablePool — builds SolverProblem from registry
 ├── version_matchers.py    npm semver + PEP 440 range matching — raw constraint → bool
+├── npm_range.py           npm range grammar (Lark) + node-semver's rewrite rules → comparator sets
+├── pep508.py              Which declared PyPI requirements apply to a project (extras + environment markers)
 ├── encoder.py             ConstraintEncoder — produces EncodedProblem (WCNF)
 ├── weights.py             Constraint weight constants + semver_rank_weight()
 └── dependencies_solver.py       Public API: solve_direct(), solve_transitive()
@@ -51,7 +53,8 @@ deps / transitive_records
   SolvablePool.build()          universe.py
     – deduplicates by canonical_name (highest ConstraintType priority wins)
     – fetches candidates from warm registry cache
-    – filters yanked, unpublished, prerelease (unless allowed)
+    – filters yanked, unpublished, prerelease (unless allowed), and deprecated releases when
+      allow_deprecated=False (only `ossiq add` choosing a live package passes that)
     – sorts candidates descending (newest first)
     – stamps has_cve=True on versions any of the package's CVEs affects (cves_by_package;
       judged by version_matchers.cve_affects_version, ranges included)
@@ -85,7 +88,7 @@ greedily; the pluggable RC2 driver **minimises** total violated soft cost exactl
 | L1 | Hard | — | Version outside declared `version_constraint` (PEP 440 or npm semver) |
 | L2 | Soft-Hard | `W_ENGINE = 100_000` | Engine mismatch (`python`/`node` requirement vs `engine_context`) |
 | L3 | Soft | `max(80_000 − rank × 5_000, 1_000)` | Semver-rank preference — rank 0 = latest eligible semver |
-| L4 | Soft | `W_DEPRECATED = 10_000` | Deprecated flag — penalty on selection |
+| L4 | Soft | `W_DEPRECATED = 10_000` | Deprecated flag — penalty on selection. A deprecated release still wins over a clean one that ranks two or more places below it (2 × 5 000 = 10 000), and the penalty is the same for every candidate when all are deprecated. A caller that must never get a deprecated release passes `allow_deprecated=False`, which removes them before this level applies |
 | L5 | Hard | — | CVE-affected version |
 | L6 | Soft-Hard | `W_VERY_FRESH = 100_000` | Published < 7 days ago — both direct and transitive passes |
 | L7 | — | *(reserved)* | Health score — not implemented |
@@ -116,7 +119,11 @@ Structural clauses per package (encoder):
 
 ### Version constraint dispatch (encoder.py)
 
-`version_satisfies_constraint(version, constraint, registry)` (in `version_matchers.py`) dispatches directly to PyPI (PEP 440) or npm (semver) based on the `ProjectPackagesRegistry` passed in — no exception-based fallback. Bare npm versions (e.g. `"14"`) are treated as caret ranges (`^14.0.0`). Unparseable constraints pass through (`True`) — unknown format is never a hard block.
+`version_satisfies_constraint(version, constraint, registry)` (in `version_matchers.py`) dispatches directly to PyPI (PEP 440) or npm (semver) based on the `ProjectPackagesRegistry` passed in — no exception-based fallback. npm ranges go through `npm_range.py` — a Lark grammar for the syntax plus node-semver's own rewrite rules, held to node-semver's verdicts by `tests/solver/node_semver_conformance.json`, so a partial version (`"14"`) is the X-range `14.x` exactly as npm reads it. Unparseable constraints pass through (`True`) — unknown format is never a hard block — and so does a blank one: PyPI publishes an unconstrained requirement as an empty specifier.
+
+### Which requirements apply (pep508.py)
+
+A PyPI release declares requirements gated on extras (`oauthlib<4; extra == "socialaccount"`) and on environment markers (`tomli; python_version < "3.11"`). Whether one applies depends on the project, so `RequirementScope` (`domain/`) carries the extras the project enables per package and its Python floor, and `applicable_requirements()` keeps a requirement when its marker holds in at least one environment the project can be installed into — the same stance uv's universal resolution takes. The registry (`package_version_requires`), the candidate `requires` built in `universe.py`, and the enrichment of lockfile edges all read requirements through it; the scan sets the scope once, from the lockfile's `extra = [...]` edges and `requires-python`.
 
 ---
 

package/bin/ossiq/_internal/ossiq/strategy/README.md

@@ -62,7 +62,7 @@ A strategy is not one dial, it is two, kept separate on purpose:
 
 | Tier | Base reach | Escalates to `LATEST` when... |
 |---|---|---|
-| `security` | in-range | an admitted motive is `exploitable_cve` (no in-range version clears the CVE) |
+| `security` | in-range | an admitted motive is `exploitable_cve`; the pick leaves the range only when no in-range version clears the CVE |
 | `deprecation` | in-range | an admitted motive is `exploitable_cve` or `end_of_life` |
 | `standard` | in-range | same as above |
 | `latest` | latest | already maximal |
@@ -77,7 +77,7 @@ A strategy is not one dial, it is two, kept separate on purpose:
 |---|---|---|
 | `security` | no target (no CVE) | `2.32.0` — nearest CVE-clear version |
 | `deprecation` | no target | `2.32.0` |
-| `standard` | `1.10.13` — pin admits no in-range move | `2.34.2` — newest, already CVE-clear |
+| `standard` | `1.10.26` — newest in the installed major, reported but not written (`requires_widening=True`) | `2.34.2` — newest, already CVE-clear |
 | `latest` | `2.13.5` — widens the pin, `requires_widening=True` | `2.34.2` |
 | `cutting-edge` | `2.13.5` (or newer, if a prerelease exists) | `2.34.2` |
 
@@ -109,6 +109,10 @@ A strategy is not one dial, it is two, kept separate on purpose:
 - **`escalation`** — set when reach was pushed past the tier's base `MAX_REACH` (a CVE or
   end-of-life motive escalated it), or when every reachable candidate still carries a qualifying
   CVE and the newest was picked anyway. Never silently "stay put".
+- **`widening_authorized`** — an escalating motive carried the pick past the tier's base
+  `MAX_REACH` and some reachable version clears the CVE. `plan` lists the pick as an update instead
+  of holding it under *Requires constraint widening*; `apply` still confirms the widening, unless
+  `--yes` is given. Rule 8's drift-only widening never sets it.
 
 ---
 
@@ -157,6 +161,20 @@ Filtering fresh candidates out of the ladder here makes one decision serve every
 the whole point of rule 5 in the root `CLAUDE.md`. The downstream hold survives as a backstop for
 transitive recommendations, which come from the solver's *soft* freshness penalty.
 
+**Why is the package manager's release cutoff a second filter rather than a longer cooldown?**
+uv's `exclude-newer` (and its npm-side counterparts) looks like a cooldown, but it is a different
+kind of rule. OSS IQ's cooldown is advice: one number per project, and an exploitable CVE or
+end-of-life outranks it. The package manager's cutoff is enforcement: it can differ per package
+or exempt one outright, it may be a fixed instant rather than a span, and the installer refuses a
+release past it whatever OSS IQ recommends. It also binds only on a *move*, since uv leaves an
+already-locked release past the cutoff alone. Folding the two into `max(days)` loses the
+per-package rules, and lets an escalating motive "bypass" a rule `apply` cannot bypass. So
+`select_target` takes the cutoff as its own parameter and applies it ahead of the cooldown and
+outside `escalate`. A hold it causes carries `enforced_by`, so surfaces name uv rather than OSS
+IQ. Both rules always apply, so the stricter one wins. The cutoff is not dropped from the registry
+either: facts like `latest_version` and drift stay true, and the installed version stays visible
+when it postdates the cutoff.
+
 **Why may only `latest`/`cutting-edge` cross to ESM-only, and only on a `require(esm)` Node?**
 For a CommonJS project an ESM-only release is a break whatever its version number:
 `require()` of it fails outright below Node 20.19/22.12, and above that it returns the module