ghostpkg 0.2.0__tar.gz → 0.4.0__tar.gz

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/CHANGELOG.md

@@ -6,6 +6,55 @@ this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-01
+
+### Added
+- **On-disk cache for registry lookups.** Scanning a 150-package manifest drops
+  from 4.7s to 0.4s on a warm cache. Previously every scan cost one request per
+  dependency, every run, which is slow in CI and rude to the registry.
+- `--no-cache` to bypass it, and `ghostpkg clear-cache` to delete it.
+- `GHOSTPKG_CACHE_DIR` to override the location. The default is
+  `%LOCALAPPDATA%\ghostpkg` on Windows, `~/Library/Caches/ghostpkg` on macOS and
+  `$XDG_CACHE_HOME/ghostpkg` elsewhere, worked out without a dependency.
+
+### Notes on the cache design
+- **Time-to-live depends on the answer, and "does not exist" is held for only an
+  hour.** A free name can be registered at any moment — that is the whole attack
+  — so a negative result must not be trusted for long. Young packages are held
+  six hours, established ones a day.
+- Cache failures are never fatal. A corrupt file, a wrong schema, a malformed
+  entry or an unwritable directory all degrade to no cache rather than breaking
+  a run. There are tests for each of those.
+- Written atomically via a temporary file and `os.replace`, once per run, so a
+  killed process cannot leave a half-written cache behind.
+
+## [0.3.0] - 2026-09-01
+
+### Fixed
+- **npm typo detection did not work at all.** Lookalike names were compared
+  against the 2,000 most-downloaded *PyPI* projects regardless of ecosystem, so
+  `expresss` was never flagged as a typo of `express` -- `express` was not in
+  the list being compared against.
+
+### Added
+- A list of the 2,000 most-downloaded npm packages, built from the registry's
+  own download-count API. `nearest_popular()` now picks the list matching the
+  ecosystem.
+- Scoped npm names are compared on the part after the slash, since that is what
+  a squat targets: `@evil/expresss` is flagged, `@types/node` and `@babel/core`
+  are not.
+
+### Changed
+- Typo distance is now Damerau-Levenshtein: swapping two adjacent characters
+  counts as one edit rather than two. Transposition is the commonest typosquat
+  shape, and under plain Levenshtein `recat`, `lodahs` and `webpakc` all scored
+  two edits, which put them outside the budget for names that short. All three
+  are caught now, and the false-positive rate across both 2,000-name lists is
+  still zero -- there are tests asserting exactly that.
+- Names shorter than five characters are no longer compared at all. Below that
+  the name space is too dense for edit distance to mean anything: `core` sits
+  one edit from `cors`.
+
 ## [0.2.0] - 2026-09-01
 
 ### Fixed
@@ -60,6 +109,8 @@ First release.
 - No corpus of hallucinated package names is shipped, following the decision of
   the USENIX'25 authors not to publish theirs.
 
-[Unreleased]: https://github.com/M1rwana12/ghostpkg/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/M1rwana12/ghostpkg/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.4.0
+[0.3.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.3.0
 [0.2.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.2.0
 [0.1.0]: https://github.com/M1rwana12/ghostpkg/releases/tag/v0.1.0

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ghostpkg
-Version: 0.2.0
+Version: 0.4.0
 Summary: Catch package names that do not exist before you install them
 Project-URL: Homepage, https://github.com/m1rwana12/ghostpkg
 Project-URL: Issues, https://github.com/m1rwana12/ghostpkg/issues
@@ -180,6 +180,7 @@ and report TOML keys as package names.
 | `--strict` | Promote warnings to blocks |
 | `--json` | Machine-readable output for scripts and CI |
 | `-q`, `--quiet` | Hide packages that passed |
+| `--no-cache` | Neither read nor write the cache |
 | `--version` | Print the version |
 
 ### Exit codes
@@ -190,6 +191,25 @@ and report TOML keys as package names.
 | `1` | At least one package blocked |
 | `2` | Usage error, unreadable manifest, or the registry was unreachable |
 
+### Caching
+
+Lookups are cached on disk, so re-scanning a 150-package manifest takes 0.4s
+instead of 4.7s.
+
+Time-to-live depends on the answer, and the negative case is the one that
+matters: **"does not exist" is held for only an hour**, because a free name can
+be registered at any moment and that is the entire attack. Young packages are
+held six hours, established ones a day.
+
+```bash
+ghostpkg scan requirements.txt --no-cache   # bypass it
+ghostpkg clear-cache                        # delete it
+GHOSTPKG_CACHE_DIR=/tmp/gp ghostpkg check x # move it
+```
+
+A corrupt, unreadable or unwritable cache degrades to no cache rather than
+breaking your run.
+
 ### JSON output
 
 ```console
@@ -217,7 +237,7 @@ $ ghostpkg check somepkgthatisnotreal9911 --json
 | First published < 1 year ago | 🟡 Warning | Weaker version of the same signal. |
 | Only one release | 🟡 Warning | Squats are usually published once and abandoned. |
 | No repository or homepage link | 🟡 Warning | Real projects almost always link to source. |
-| 1–2 characters from a popular name, **and** recently published | 🟡 Warning | Classic typosquat shape. Age matters: an old lookalike is just a package with a similar name. |
+| 1–2 edits from a popular name, **and** recently published | 🟡 Warning | Classic typosquat shape. A swap of adjacent characters counts as one edit, because `recat`/`react` is what squatters actually publish. Age matters: an old lookalike is just a package with a similar name. |
 
 Warnings are advisory by default. Nothing but non-existence blocks unless you pass
 `--strict`.
@@ -353,11 +373,12 @@ earns its keep. Use both.
 > that stand between you and it, and they are advisory. Improving this is the main
 > open problem — see [issues](https://github.com/M1rwana12/ghostpkg/issues).
 
-- Typo detection compares against the 2,000 most-downloaded PyPI projects, so a squat
-  on a less popular package won't be flagged as a lookalike.
-- npm scoped packages (`@scope/name`) are checked, but the popular-name list is
-  PyPI-derived, so npm typosquat detection is weaker.
-- Every check is a live registry request. There is no caching yet.
+- Typo detection compares against the 2,000 most-downloaded projects in each
+  ecosystem, so a squat on a less popular package won't be flagged as a lookalike.
+- Names shorter than five characters are not compared at all: below that the name
+  space is too dense for edit distance to mean anything.
+- The cache lives on disk. `ghostpkg clear-cache` removes it and
+  `GHOSTPKG_CACHE_DIR` moves it.
 - Registry outages surface as exit code `2` rather than a silent pass — deliberately,
   but it does mean a flaky network fails your build.
 

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/README.en.md

@@ -133,6 +133,7 @@ and report TOML keys as package names.
 | `--strict` | Promote warnings to blocks |
 | `--json` | Machine-readable output for scripts and CI |
 | `-q`, `--quiet` | Hide packages that passed |
+| `--no-cache` | Neither read nor write the cache |
 | `--version` | Print the version |
 
 ### Exit codes
@@ -143,6 +144,25 @@ and report TOML keys as package names.
 | `1` | At least one package blocked |
 | `2` | Usage error, unreadable manifest, or the registry was unreachable |
 
+### Caching
+
+Lookups are cached on disk, so re-scanning a 150-package manifest takes 0.4s
+instead of 4.7s.
+
+Time-to-live depends on the answer, and the negative case is the one that
+matters: **"does not exist" is held for only an hour**, because a free name can
+be registered at any moment and that is the entire attack. Young packages are
+held six hours, established ones a day.
+
+```bash
+ghostpkg scan requirements.txt --no-cache   # bypass it
+ghostpkg clear-cache                        # delete it
+GHOSTPKG_CACHE_DIR=/tmp/gp ghostpkg check x # move it
+```
+
+A corrupt, unreadable or unwritable cache degrades to no cache rather than
+breaking your run.
+
 ### JSON output
 
 ```console
@@ -170,7 +190,7 @@ $ ghostpkg check somepkgthatisnotreal9911 --json
 | First published < 1 year ago | 🟡 Warning | Weaker version of the same signal. |
 | Only one release | 🟡 Warning | Squats are usually published once and abandoned. |
 | No repository or homepage link | 🟡 Warning | Real projects almost always link to source. |
-| 1–2 characters from a popular name, **and** recently published | 🟡 Warning | Classic typosquat shape. Age matters: an old lookalike is just a package with a similar name. |
+| 1–2 edits from a popular name, **and** recently published | 🟡 Warning | Classic typosquat shape. A swap of adjacent characters counts as one edit, because `recat`/`react` is what squatters actually publish. Age matters: an old lookalike is just a package with a similar name. |
 
 Warnings are advisory by default. Nothing but non-existence blocks unless you pass
 `--strict`.
@@ -306,11 +326,12 @@ earns its keep. Use both.
 > that stand between you and it, and they are advisory. Improving this is the main
 > open problem — see [issues](https://github.com/M1rwana12/ghostpkg/issues).
 
-- Typo detection compares against the 2,000 most-downloaded PyPI projects, so a squat
-  on a less popular package won't be flagged as a lookalike.
-- npm scoped packages (`@scope/name`) are checked, but the popular-name list is
-  PyPI-derived, so npm typosquat detection is weaker.
-- Every check is a live registry request. There is no caching yet.
+- Typo detection compares against the 2,000 most-downloaded projects in each
+  ecosystem, so a squat on a less popular package won't be flagged as a lookalike.
+- Names shorter than five characters are not compared at all: below that the name
+  space is too dense for edit distance to mean anything.
+- The cache lives on disk. `ghostpkg clear-cache` removes it and
+  `GHOSTPKG_CACHE_DIR` moves it.
 - Registry outages surface as exit code `2` rather than a silent pass — deliberately,
   but it does mean a flaky network fails your build.
 

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/README.md

@@ -86,14 +86,23 @@ ghostpkg scan package.json
 
 # машинозчитуваний вивід
 ghostpkg check somepkg --json
+
+# видалити кеш
+ghostpkg clear-cache
 ```
 
+Результати запитів кешуються на диск: повторна перевірка манифесту зі 150
+залежностей займає 0,4 с замість 4,7 с. **Відповідь «пакета не існує»
+зберігається лише годину** — вільне ім'я можуть зареєструвати будь-якої
+миті, і саме в цьому вся атака.
+
 | Прапорець | Призначення |
 |---|---|
 | `-e`, `--ecosystem` | `pypi` (типово) або `npm` |
 | `--strict` | Підвищує попередження до блокувань |
 | `--json` | Вивід у JSON для скриптів і CI |
 | `-q`, `--quiet` | Ховає пакети, які пройшли перевірку |
+| `--no-cache` | Не читати й не писати кеш |
 
 `scan` розпізнає `requirements*.txt`, `pyproject.toml` (PEP 621 і Poetry)
 та `package.json`. Невідомий формат він **відхиляє з помилкою, а не вгадує**.
@@ -163,11 +172,12 @@ $ ghostpkg check react-router-dom-utils -e npm
 > попередження, і вони дорадчі. Це головна відкрита проблема —
 > див. [issues](https://github.com/M1rwana12/ghostpkg/issues).
 
-- Виявлення опечаток порівнює з 2 000 найпопулярніших проєктів PyPI, тому підробка
-  під менш популярний пакет як схожа назва не позначиться.
-- Пакети npm з областю (`@scope/name`) перевіряються, але список популярних назв
-  побудований на PyPI — тож для npm виявлення опечаток слабше.
-- Кожна перевірка — це живий запит до реєстру. Кешування ще немає.
+- Виявлення опечаток порівнює з 2 000 найпопулярніших проєктів кожної екосистеми,
+  тому підробка під менш популярний пакет як схожа назва не позначиться.
+- Імена коротші за 5 символів не порівнюються: там простір назв надто щільний,
+  щоб відстань редагування щось означала.
+- Кеш зберігається локально. `ghostpkg clear-cache` видаляє його,
+  `GHOSTPKG_CACHE_DIR` змінює розташування.
 
 ---
 

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/ghostpkg/__init__.py

@@ -1,6 +1,6 @@
 """ghostpkg -- catch package names that do not exist before you install them."""
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 
 from .assess import Finding, Verdict, assess
 from .registries import PackageFacts, RegistryError, fetch

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/ghostpkg/assess.py

@@ -18,7 +18,7 @@ from __future__ import annotations
 from dataclasses import dataclass, field
 from enum import Enum
 
-from .data import TOP_PYPI
+from .data import TOP_NPM, TOP_PYPI
 from .registries import PackageFacts
 
 YOUNG_DAYS = 90
@@ -45,25 +45,44 @@ class Finding:
 
 
 def edit_distance(left: str, right: str, cutoff: int = 3) -> int:
-    """Levenshtein distance, abandoning early once it exceeds `cutoff`."""
+    """Damerau-Levenshtein distance, abandoning early once it exceeds `cutoff`.
+
+    Swapping two adjacent characters counts as one edit, not two. That matters
+    here more than it looks: transposition is the commonest typosquat shape --
+    `recat` for `react`, `lodahs` for `lodash`, `webpakc` for `webpack`. Plain
+    Levenshtein scores all three as two edits, which put them outside the budget
+    for names of that length and let every one of them through.
+    """
     if left == right:
         return 0
     if abs(len(left) - len(right)) > cutoff:
         return cutoff + 1
 
+    before_previous: list[int] = []
     previous = list(range(len(right) + 1))
     for i, a in enumerate(left, 1):
         current = [i]
         for j, b in enumerate(right, 1):
-            current.append(
-                min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a != b))
-            )
+            cost = min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a != b))
+            if (
+                i > 1
+                and j > 1
+                and a == right[j - 2]
+                and left[i - 2] == b
+            ):
+                cost = min(cost, before_previous[j - 2] + 1)
+            current.append(cost)
         if min(current) > cutoff:
             return cutoff + 1
-        previous = current
+        before_previous, previous = previous, current
     return previous[-1]
 
 
+POPULAR: dict[str, frozenset[str]] = {"pypi": TOP_PYPI, "npm": TOP_NPM}
+
+MIN_COMPARABLE_LENGTH = 5
+
+
 def _typo_budget(name: str) -> int:
     """How many edits still count as a plausible typo of a popular name.
 
@@ -74,18 +93,40 @@ def _typo_budget(name: str) -> int:
     return 2 if len(name) >= 10 else 1
 
 
-def nearest_popular(name: str, popular: frozenset[str] = TOP_PYPI) -> tuple[str, int] | None:
+def _comparable(name: str, ecosystem: str) -> str:
+    """The part of a name worth comparing.
+
+    An npm squat on a scoped package targets the part after the slash, since
+    the scope is usually owned by whoever it names.
+    """
+    lowered = name.lower()
+    if ecosystem == "npm" and lowered.startswith("@") and "/" in lowered:
+        return lowered.rsplit("/", 1)[1]
+    return lowered
+
+
+def nearest_popular(name: str, ecosystem: str = "pypi") -> tuple[str, int] | None:
     """Closest popular package name within the typo budget, if any."""
+    popular = POPULAR.get(ecosystem)
+    if not popular:
+        return None
+
     lowered = name.lower()
-    if lowered in popular:
+    target = _comparable(name, ecosystem)
+
+    if lowered in popular or target in popular:
+        return None
+    # Below this length the name space is too dense for edit distance to mean
+    # anything: 'core' sits one edit from 'cors'.
+    if len(target) < MIN_COMPARABLE_LENGTH:
         return None
 
-    budget = _typo_budget(lowered)
+    budget = _typo_budget(target)
     best: tuple[str, int] | None = None
     for candidate in popular:
-        if abs(len(candidate) - len(lowered)) > budget:
+        if abs(len(candidate) - len(target)) > budget:
             continue
-        distance = edit_distance(lowered, candidate, cutoff=budget)
+        distance = edit_distance(target, candidate, cutoff=budget)
         if 0 < distance <= budget and (best is None or distance < best[1]):
             best = (candidate, distance)
             if distance == 1:
@@ -114,7 +155,7 @@ def assess(facts: PackageFacts, strict: bool = False) -> Finding:
     is_young = facts.age_days is not None and facts.age_days < NEW_DAYS
 
     if is_young:
-        neighbour = nearest_popular(facts.name)
+        neighbour = nearest_popular(facts.name, facts.ecosystem)
         if neighbour is not None:
             popular_name, distance = neighbour
             reasons.append(

ghostpkg-0.4.0/ghostpkg/cache.py

@@ -0,0 +1,165 @@
+"""On-disk cache for registry lookups.
+
+Scanning a manifest costs one request per dependency, every time. A 200-line
+requirements.txt in CI is 200 requests on every run, which is slow for the user
+and rude to the registry.
+
+Time-to-live depends on what was cached, and the important case is the negative
+one. A name that does not exist today can be registered tomorrow -- that is the
+entire attack this tool exists to catch -- so "does not exist" is held only
+briefly. Established packages change slowly and are held far longer.
+
+Cache failures are never fatal. An unwritable or corrupt cache degrades to no
+cache at all rather than breaking a build.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+from dataclasses import asdict
+from pathlib import Path
+
+from .registries import PackageFacts
+
+SCHEMA = 1
+
+TTL_MISSING = 60 * 60             # 1 hour  -- a free name can be taken any time
+TTL_YOUNG = 6 * 60 * 60           # 6 hours -- facts still moving
+TTL_ESTABLISHED = 24 * 60 * 60    # 1 day   -- changes slowly
+
+ESTABLISHED_DAYS = 365
+
+
+def default_dir() -> Path:
+    """Per-platform cache directory, worked out by hand.
+
+    A dependency for this would contradict the zero-dependency rule for the
+    sake of three lines.
+    """
+    override = os.environ.get("GHOSTPKG_CACHE_DIR")
+    if override:
+        return Path(override)
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        return Path(base) / "ghostpkg"
+    if sys.platform == "darwin":
+        return Path(os.path.expanduser("~/Library/Caches")) / "ghostpkg"
+    base = os.environ.get("XDG_CACHE_HOME") or os.path.expanduser("~/.cache")
+    return Path(base) / "ghostpkg"
+
+
+def ttl_for(facts: PackageFacts) -> int:
+    if not facts.exists:
+        return TTL_MISSING
+    if facts.age_days is not None and facts.age_days >= ESTABLISHED_DAYS:
+        return TTL_ESTABLISHED
+    return TTL_YOUNG
+
+
+class Cache:
+    """Read once, write once. Threads only read, so no locking is needed."""
+
+    def __init__(self, directory: Path | None = None, enabled: bool = True) -> None:
+        self.enabled = enabled
+        self.directory = directory or default_dir()
+        self._entries: dict[str, dict] = {}
+        self._dirty = False
+        self.hits = 0
+        self.misses = 0
+        if self.enabled:
+            self._load()
+
+    @property
+    def path(self) -> Path:
+        return self.directory / "registry.json"
+
+    def _load(self) -> None:
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return
+        if not isinstance(raw, dict) or raw.get("schema") != SCHEMA:
+            return
+        entries = raw.get("entries")
+        if isinstance(entries, dict):
+            self._entries = entries
+
+    @staticmethod
+    def _key(ecosystem: str, name: str) -> str:
+        return f"{ecosystem}:{name.lower()}"
+
+    def get(self, ecosystem: str, name: str) -> PackageFacts | None:
+        if not self.enabled:
+            return None
+        entry = self._entries.get(self._key(ecosystem, name))
+        if not isinstance(entry, dict):
+            self.misses += 1
+            return None
+        stored_at = entry.get("at")
+        ttl = entry.get("ttl")
+        facts = entry.get("facts")
+        if not isinstance(stored_at, (int, float)) or not isinstance(ttl, (int, float)):
+            self.misses += 1
+            return None
+        if time.time() - stored_at > ttl:
+            self.misses += 1
+            return None
+        try:
+            revived = PackageFacts(**facts)
+        except (TypeError, ValueError):
+            self.misses += 1
+            return None
+        self.hits += 1
+        # keep the caller's spelling of the name rather than the cached one
+        if revived.name != name:
+            revived = PackageFacts(**{**asdict(revived), "name": name})
+        return revived
+
+    def put(self, facts: PackageFacts) -> None:
+        if not self.enabled:
+            return
+        self._entries[self._key(facts.ecosystem, facts.name)] = {
+            "at": time.time(),
+            "ttl": ttl_for(facts),
+            "facts": asdict(facts),
+        }
+        self._dirty = True
+
+    def _prune(self) -> None:
+        now = time.time()
+        self._entries = {
+            key: entry
+            for key, entry in self._entries.items()
+            if isinstance(entry, dict)
+            and isinstance(entry.get("at"), (int, float))
+            and now - entry["at"] <= entry.get("ttl", 0)
+        }
+
+    def save(self) -> None:
+        """Write atomically. Any failure is silent -- a cache is a convenience."""
+        if not self.enabled or not self._dirty:
+            return
+        self._prune()
+        payload = {"schema": SCHEMA, "entries": self._entries}
+        try:
+            self.directory.mkdir(parents=True, exist_ok=True)
+            handle, temporary = tempfile.mkstemp(dir=str(self.directory), suffix=".tmp")
+            with os.fdopen(handle, "w", encoding="utf-8") as file:
+                json.dump(payload, file)
+            os.replace(temporary, self.path)
+        except OSError:
+            try:
+                os.unlink(temporary)  # noqa: F821
+            except (OSError, NameError):
+                pass
+
+    def clear(self) -> bool:
+        try:
+            self.path.unlink()
+            return True
+        except OSError:
+            return False

{ghostpkg-0.2.0 → ghostpkg-0.4.0}/ghostpkg/cli.py

@@ -11,6 +11,7 @@ from pathlib import Path
 
 from . import __version__
 from .assess import Finding, Verdict, assess
+from .cache import Cache
 from .manifests import UnsupportedManifest, load_manifest
 from .registries import RegistryError, fetch
 
@@ -89,12 +90,25 @@ def summarise(findings: list[Finding], palette: Palette) -> None:
         print(palette.green(f"  all {len(findings)} packages look fine"))
 
 
-def evaluate(names: list[str], ecosystem: str, strict: bool) -> list[Finding]:
+def evaluate(
+    names: list[str],
+    ecosystem: str,
+    strict: bool,
+    cache: Cache | None = None,
+) -> list[Finding]:
     def one(name: str) -> Finding:
-        return assess(fetch(name, ecosystem), strict=strict)
+        facts = cache.get(ecosystem, name) if cache else None
+        if facts is None:
+            facts = fetch(name, ecosystem)
+            if cache:
+                cache.put(facts)
+        return assess(facts, strict=strict)
 
     with concurrent.futures.ThreadPoolExecutor(max_workers=MAX_WORKERS) as pool:
-        return list(pool.map(one, names))
+        findings = list(pool.map(one, names))
+    if cache:
+        cache.save()
+    return findings
 
 
 def build_parser() -> argparse.ArgumentParser:
@@ -124,6 +138,11 @@ def build_parser() -> argparse.ArgumentParser:
         )
         command.add_argument("--json", action="store_true", help="machine-readable output")
         command.add_argument("-q", "--quiet", action="store_true", help="hide passing packages")
+        command.add_argument(
+            "--no-cache", action="store_true", help="ignore and do not write the cache"
+        )
+
+    sub.add_parser("clear-cache", help="delete the cached registry lookups")
 
     return parser
 
@@ -131,6 +150,12 @@ def build_parser() -> argparse.ArgumentParser:
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
 
+    if args.command == "clear-cache":
+        cache = Cache(enabled=True)
+        removed = cache.clear()
+        print(f"ghostpkg: {'removed ' + str(cache.path) if removed else 'nothing to remove'}")
+        return EXIT_OK
+
     if args.command == "scan":
         if not args.path.exists():
             print(f"ghostpkg: no such file: {args.path}", file=sys.stderr)
@@ -149,8 +174,9 @@ def main(argv: list[str] | None = None) -> int:
     else:
         names, ecosystem = args.names, args.ecosystem
 
+    cache = Cache(enabled=not args.no_cache)
     try:
-        findings = evaluate(names, ecosystem, args.strict)
+        findings = evaluate(names, ecosystem, args.strict, cache)
     except RegistryError as exc:
         print(f"ghostpkg: {exc}", file=sys.stderr)
         return EXIT_ERROR