Metadata-Version: 2.4
Name: ossiq
Version: 0.1.9
Summary: Utility to forecast risks associated with currently installed packages updates
Project-URL: bugs, https://github.com/ossiq/ossiq/issues
Project-URL: changelog, https://github.com/ossiq/ossiq/blob/master/changelog.md
Project-URL: homepage, https://github.com/ossiq/ossiq
Project-URL: repository, https://github.com/ossiq/ossiq.git
Author-email: Maksym Klymyshyn <klymyshyn@gmail.com>
Maintainer-email: Maksym Klymyshyn <klymyshyn@gmail.com>
License-Expression: AGPL-3.0-only
License-File: AUTHORS
License-File: LICENSE
Keywords: engineering,maintenance,tech debt,techdebt,toc
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Security
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Software Distribution
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: common-expression-language>=0.5.6
Requires-Dist: frictionless>=5.19.0
Requires-Dist: hatch>=1.16.5
Requires-Dist: jsonschema>=4.18.0
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic<3,>=2.0.0
Requires-Dist: python-sat==1.9.dev2
Requires-Dist: requests-cache>=1.3.1
Requires-Dist: requests>=2.28.0
Requires-Dist: semver>=3.0.0
Requires-Dist: univers>=32.0.1
Provides-Extra: cli
Requires-Dist: rich>=13.0.0; extra == 'cli'
Requires-Dist: termcolor>=2.0.0; extra == 'cli'
Requires-Dist: typer>=0.9.0; extra == 'cli'
Provides-Extra: docs
Requires-Dist: myst-parser>=5.0.0; extra == 'docs'
Requires-Dist: sphinx-autobuild>=2025.8.25; extra == 'docs'
Requires-Dist: sphinx-immaterial>=0.13.9; extra == 'docs'
Requires-Dist: sphinx>=8.0.0; extra == 'docs'
Requires-Dist: sphinxext-opengraph>=0.13.0; extra == 'docs'
Description-Content-Type: text/markdown

# OSS IQ

[![PyPI version](https://img.shields.io/pypi/v/ossiq.svg)](https://pypi.org/project/ossiq)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
![maintenance-status](https://img.shields.io/badge/maintenance-actively--developed-brightgreen.svg)
> Quantify Maintenance Health. Control Your Drift.

**OSS IQ** is a free & open-source CLI tool that analyzes dependency drift at scale. Track version lag and transitive risk directly from your dependency files. It helps to move from reactive CVE-chasing to a planned, predictable maintenance rhythm.

![OSS IQ HTML Report](https://ossiq.dev/_static/images/ossiq-cli-report-2026-06-20.png)

## What is OSS IQ?

In a typical project with hundreds of dependencies, how do you answer these questions?
- How many dependencies have critical vulnerabilities?
- How far behind the latest versions are we?
- Which packages are unmaintained or abandoned?
- Which newer versions of dependencies would work best for my project?

## Key Features

- **Security Blind Spots**: Go beyond `npm audit` to see which vulnerabilities actually matter and how to prioritize them.
- **Multiple Output Formats**: CLI and interactive HTML per-project dependencies exploration tools as well as export into clearly defined JSON or CSV schemas.
- **CI/CD Integration**: Use scores and metrics to build quality gates and enforce dependency policies automatically.
- **Peer Dependency Analysis**: Detect peer constraint violations, compliance-by-override status, and dead-end configurations where no compatible version exists across both npm and Python ecosystems.
- **Transitive Impact Simulation**: Before recommending an update, simulate the full transitive cascade — see exactly which downstream packages would change, whether conflicts arise, and get a fallback recommendation when the best version is blocked.

OSS IQ bridges the gap between raw dependency data and actionable intelligence. It analyzes version lag, CVEs, transitive dependencies, and maintainer activity to produce a single, holistic view of your project dependencies.

## How It Works

1.  **Run OSS IQ**: Point the CLI to your project's manifest file (`package.json`, `pyproject.toml`, etc.). OSS IQ supports NPM and Python (uv, pip).
2.  **Analyze Everything**: Version lag, CVEs, transitive dependencies, and license compliance—all cross-referenced against public databases (OSV, npm, PyPI) using MSR Engine.
3.  **Get Your Report**: See your dependencies drift report, drill into each package details, and get a prioritized list of what to fix first.
4.  **Build Quality Gates**: Use your project metrics to set up policies and drive organization behavior.

## Quick Start

### 1. Run OSS IQ

The fastest way is to run directly from [PyPI](https://pypi.org/) with [uvx](https://docs.astral.sh/uv/) with no install required:

```bash
# JavaScript / npm or Python / uv / pip — run from your project directory
uvx --from ossiq ossiq-cli status

# Generate HTML report
uvx --from ossiq ossiq-cli status --presentation=html --output report.html

# Show all packages, including up-to-date ones
uvx --from ossiq ossiq-cli status --full

# Narrow to CVE-affected packages only (security-first workflow)
uvx --from ossiq ossiq-cli status --security
```

OSS IQ automatically detects the dependency manifest (`package.json`, `pyproject.toml`, etc.) in the target directory.


#### GitHub Token

OSS IQ performs deep analysis by mining software repository history, which can involve hundreds of API requests to GitHub. To avoid being rate-limited, it's. best to provide a GitHub Personal Access Token (PAT).

```bash
export OSSIQ_GITHUB_TOKEN=$(gh auth token)
```

#### Temporal Analysis Options

Two global options let you control how OSS IQ perceives time. They apply to all subcommands (`status`, `export`, `plan`, `apply`, `info`) and can be combined freely.

| Option | Env var | Default | Description |
|---|---|---|---|
| `--cutoff-date YYYY-MM-DD` | `OSSIQ_CUTOFF_DATE` | today | Treat versions published after this date as invisible (23:59:59 UTC of that day). Enables time-travel QA. |
| `--cooldown-period N` | `OSSIQ_COOLDOWN_PERIOD` | `7` | Versions younger than N days receive a freshness soft-penalty in the solver, reducing the risk of picking very new releases. |

```bash
# Reproduce the exact state of your dependencies as of a past date
ossiq-cli --cutoff-date 2025-01-01 status

# Widen the freshness buffer to 14 days (versions < 14 days old are soft-penalized)
ossiq-cli --cooldown-period 14 status

# Both together: time-travel view with a custom freshness window
ossiq-cli --cutoff-date 2025-01-01 --cooldown-period 14 status

# Disable the freshness penalty entirely
ossiq-cli --cooldown-period 0 status
```

The options are also readable from environment variables, which is useful for CI pipelines:

```bash
OSSIQ_CUTOFF_DATE=2025-01-01 OSSIQ_COOLDOWN_PERIOD=14 ossiq-cli status
```


If you prefer a persistent install:

```bash
# Install with uv
uv add ossiq

# Or with pip
pip install ossiq

# Then run directly
ossiq-cli status
```

### Using Docker

OSS IQ CLI is available as a Docker image for easy deployment without installing Python dependencies.

```bash
# Pull the latest image
docker pull ossiq/ossiq-cli

# Set your GitHub token (required)
export OSSIQ_GITHUB_TOKEN=$(gh auth token)

# Show dependency status
docker run --rm \
  -e OSSIQ_GITHUB_TOKEN \
  -v /path/to/your/project:/project:ro \
  ossiq/ossiq-cli status /project

# Generate an HTML report
docker run --rm \
  -e OSSIQ_GITHUB_TOKEN \
  -v /path/to/your/project:/project:ro \
  -v $(pwd)/reports:/output \
  ossiq/ossiq-cli status -p html -o /output/report.html /project

# Export to JSON for CI/CD pipelines
docker run --rm \
  -e OSSIQ_GITHUB_TOKEN \
  -v /path/to/your/project:/project:ro \
  -v $(pwd)/reports:/output \
  ossiq/ossiq-cli export -f json -o /output/metrics.json /project
```

**Docker Image Tags:**
- `ossiq/ossiq-cli:latest` - Latest stable release
- `ossiq/ossiq-cli:0.1.3` - Specific version
- `ossiq/ossiq-cli:0.1` - Latest patch in minor version

**CI/CD Integration Example (GitHub Actions):**

```yaml
jobs:
  dependency-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Analyze dependencies
        run: |
          docker run --rm \
            -e OSSIQ_GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} \
            -v ${{ github.workspace }}:/project:ro \
            ossiq/ossiq-cli status /project
```

### Dependency Update Plan

`ossiq-cli plan` shows what the solver recommends without touching any files. `ossiq-cli apply` executes those changes with rollback on failure.

```bash
# Show the plan table (read-only, no changes made)
ossiq-cli plan

# Emit a copy-pasteable bash script instead of the table
ossiq-cli plan --script

# Apply updates interactively (shows the plan, then prompts for confirmation)
ossiq-cli apply

# Apply updates non-interactively (skip confirmation, for CI)
ossiq-cli apply --yes
```

The solver simulates the full transitive impact of each recommendation before committing to it. When the top candidate would create a downstream conflict, it falls back to the next-best version automatically. The plan table shows a `↳` sub-row for each transitive package that would also move, and marks non-actionable entries with `✗`.

**npm** — backs up `package.json`, injects all recommended versions as `overrides` in one pass, runs `npm install --ignore-scripts`, then removes the overrides block.

**uv / pip** — rewrites specifiers in `pyproject.toml` or `requirements.txt` in-place, then runs `uv lock --upgrade-package` / `pip install -c <constraints>`. Changes are rolled back automatically if the update fails.

#### Options

| Option | Description |
|---|---|
| `--production` | Limit to production dependencies only |
| `--registry-type npm\|pypi` | Narrow to a specific ecosystem |
| `--security` | Include only CVE-affected packages (direct and transitive) in the update plan |
| `--allow-prerelease` | Include pre-release versions across all packages |
| `--allow-prerelease-package <name>` | Allow pre-release for a specific package (repeatable) |
| `--ignore <name>`, `-i` | Exclude a package from the update plan entirely (repeatable) |
| `--override <pkg>==<ver>` | Force a package to an exact version, bypassing the solver and the cooldown (repeatable) |
| `--pin-all` | Write `==new_version` for every updated direct dependency, converting loose specifiers (`^`, `~=`, `>=`) to exact pins |
| `--rewrite-versions` | Include already-pinned (`==x.y.z`) dependencies in the update and rewrite their pinned version |
| `--script` | (`plan` only) Print the bash script instead of the plan table — safe to pipe directly to `bash` |
| `--yes`, `-y` | (`apply` only) Skip the confirmation prompt |

All flags are accepted by both `plan` and `apply` (except where noted), so a `plan` invocation is always
a faithful preview of the matching `apply`.

#### Pinning workflow — `--pin-all` and `--rewrite-versions`

By default, packages already pinned with an exact specifier (`==x.y.z`) are **frozen** and excluded from the update plan. This prevents accidental upgrades when you have intentionally locked a version. Use `--pin-all` and `--rewrite-versions` together to manage a fully-pinned dependency file:

```bash
# Step 1: migrate all direct deps to exact pins (==x.y.z)
ossiq-cli apply --pin-all

# Step 2: on subsequent runs, preview what newer versions are available
#         (pinned deps are frozen and not shown by default)
ossiq-cli plan

# Step 3: upgrade and re-pin everything in one pass
ossiq-cli apply --pin-all --rewrite-versions

# Step 3 (selective): hold back specific packages while updating the rest
ossiq-cli apply --pin-all --rewrite-versions --ignore requests --ignore django
```

**Flag behaviour summary:**

| Flags | `>=x` (declared) | `~=x` (narrowed) | `==x` (pinned) |
|---|---|---|---|
| *(none)* | lockfile-only update | rewrite `~=new` | frozen / skipped |
| `--pin-all` | rewrite `==new` | rewrite `==new` | frozen / skipped |
| `--rewrite-versions` | lockfile-only update | rewrite `~=new` | rewrite `==new` |
| `--pin-all --rewrite-versions` | rewrite `==new` | rewrite `==new` | rewrite `==new` |

#### Cooldown: how freshness is handled

The `--cooldown-period` (default: 7 days) protects you from supply-chain attacks that ride on
freshly published releases. It acts at two levels:

1. **Inside the solver**, versions younger than the cooldown receive a heavy soft-penalty, so an
   older stable version wins whenever one satisfies the constraints.
2. **After solving**, any remaining recommendation younger than the cooldown is withheld from the
   plan and listed in a separate *"Held for cooldown"* section — it is never applied.

Two deliberate exceptions:

- **CVE fixes bypass the hold.** When the *installed* version of a package carries a known CVE, its
  recommendation is applied even if the target version is brand-new — the known-vulnerability
  exposure outweighs the freshness risk. These entries are tagged `CVE` in the plan table, and a
  `cooldown bypassed` note explains why a fresh version got through.
- **Brand-new transitive dependencies are outside the hold.** When an upgrade pulls in a package
  that was not previously in your tree, its version is resolved by npm/uv at apply time, not by the
  solver. The plan's *"New transitive dependencies"* table shows the projected version and its age,
  and flags entries younger than the cooldown with `⚠` so you can review them before applying.

#### What if a quarantined version fixes a CVE?

Sometimes the only version that fixes a CVE is younger than your cooldown period — it is, in
cooldown terms, still "quarantined". You are trading one risk against another: the *known* risk of
the unpatched CVE versus the *statistical* risk of a very fresh release (supply-chain compromise,
regressions). OSS IQ gives you three levers, from automatic to fully manual:

1. **Default behaviour** — if the installed version carries a CVE, the fix is recommended and
   applied regardless of its age. For most teams this is the right default: a concrete CVE beats a
   hypothetical supply-chain risk.
2. **`--security`** — narrow the run to CVE-affected packages only: `ossiq-cli apply --security --yes`
   patches vulnerabilities and touches nothing else. Ideal for an out-of-band security patch while
   the regular update cadence stays on cooldown.
3. **`--override pkg==version`** — force one exact version when you have vetted it yourself:
   `ossiq-cli apply --override urllib3==2.0.7`. This bypasses the solver's compatibility checks and
   the cooldown for that package. For a direct dependency the specifier is rewritten to the exact
   version; for a transitive dependency a **persistent** override entry is written (`overrides` in
   `package.json`, `override-dependencies` under `[tool.uv]`) so the forced version survives future
   installs. Remove the entry once a compatible release exists — `ossiq-cli status` reports such
   packages with the `OVERRIDE` constraint type so they stay visible.

#### Iterative updates: why a second `plan` can show more

The solver resolves updates in a **single pass** against your current lockfile. Applying a plan
re-resolves the dependency tree — updated packages bring new constraints and sometimes new
transitive dependencies — which can unlock further recommendations that were not visible before.

```bash
# Typical convergence loop: repeat until the plan is empty
ossiq-cli apply --yes
ossiq-cli plan       # may show new recommendations against the re-resolved tree
ossiq-cli apply --yes
ossiq-cli plan       # "No updates recommended" → converged
```

This is expected behaviour, not an incomplete first run: recommending against the *actual* resolved
tree (rather than a speculative future tree) keeps every step verifiable. Most projects converge in
one or two passes.

## Supported Ecosystems

### NPM

**Supported:**
- **[npm](https://docs.npmjs.com/cli/v11/commands/npm)** – Package manager for JavaScript (`package.json` + `package-lock.json`)

**Not yet supported:**
- **[Yarn](https://yarnpkg.com/)** and **[pnpm](https://pnpm.io/)** – See the [issue tracker](https://github.com/ossiq/ossiq/issues) for roadmap status.

### Python

**Supported:**
- **[uv](https://docs.astral.sh/uv/)** – Fast Rust-based package manager (`pyproject.toml` + `uv.lock`)
- **[pip lock](https://pip.pypa.io/en/stable/cli/pip_lock/)** – [pylock.toml](https://packaging.python.org/en/latest/specifications/pylock-toml/#pylock-toml-spec) lockfile format (`pyproject.toml` + `pylock.toml`)
- **[pip classic](https://pip.pypa.io/en/stable/reference/requirements-file-format/)** – Traditional `requirements.txt` (best with `pip freeze` output)

**Not yet supported:**
- **[Poetry](https://python-poetry.org/)** – Consider exporting to `pylock.toml` as a workaround ([discussion](https://github.com/orgs/python-poetry/discussions/10322))

## Data Sources

OSS IQ aggregates data from the following public sources:

| Source | Purpose |
|---|---|
| [OSV](https://osv.dev/) | Open-source vulnerability database (CVEs, security advisories) |
| [NPM Registry](https://www.npmjs.com/) | Package metadata and version history for JavaScript packages |
| [PyPI](https://pypi.org/) | Package metadata and version history for Python packages |
| [GitHub](https://github.com/) | Repository activity, releases, and maintainer signals |


### Development Mode

To contribute or run from source:

```bash
# Clone the repository
git clone https://github.com/ossiq/ossiq.git
cd ossiq

# Install dependencies
uv sync

# Run the CLI
uv run hatch run ossiq-cli status

# Generate HTML report
uv run hatch run ossiq-cli status -p html -o ./test_report.html
```

### Package Deep-Dive

Inspect a single package in detail — drift status, CVEs, transitive vulnerabilities, and its exact path in the dependency tree:

```bash
ossiq-cli info react
ossiq-cli info lodash --registry-type npm
```

The output mirrors the structure of the dependency detail panel:

```
[01] DRIFT STATUS            — version lag bar, releases behind, latest version
[02] DEPENDENCY TREE TRACE   — ancestry path from root to the package
[03] POLICY COMPLIANCE       — declared constraint vs. resolved vs. latest
[04] SECURITY ADVISORIES     — direct CVEs with severity and source
[05] VIA TRANSITIVE DEPENDENCIES — CVEs in packages pulled in by this one
[08] PEER REQUIREMENTS       — per-requirement status: ok / violation / compliance-via-override
```

If the package appears in multiple places in the tree (hoisted duplicates, diamond dependencies), each occurrence is shown separately with a **SHARED NODE** indicator.


## FAQ

**Why another Software Composition Analysis tool?**

OSS IQ is not another vulnerability scanner. It helps platform teams evaluate open-source dependencies as long-term engineering assets by analyzing lockfiles, dependency graphs, and maintenance signals, producing stable scores suitable for CI and platform governance.

**How is OSS IQ different from npm audit or pip-audit?**

Audit tools are great at finding known vulnerabilities. OSS IQ goes further by also analyzing non-security risks, such as how far behind you are from the latest version (technical debt) and whether a package is still actively maintained. We give you the full picture of dependency health, not just one part of it.


**What ecosystems are supported?**

OSS IQ currently supports popular ecosystems like npm for JavaScript and multiple dependency managers for Python (uv and classic pip). We are always working to add support for more ecosystems.

**Is OSS IQ free?**

Yes, OSS IQ is a completely free and open-source tool, licensed under the AGPL v3 license.

## License

This project is licensed under the **GNU Affero General Public License v3.0**. See the [LICENSE](LICENSE) file for details.