slopguard-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/.gitignore

@@ -41,3 +41,14 @@ Thumbs.db
 
 # Local scan artifacts
 slopguard-report.json
+
+# Node / Next.js (Phase A onwards)
+node_modules/
+.next/
+out/
+.turbo/
+
+# Local secrets — never commit. Use Doppler / 1Password / Fly.io secrets.
+.env
+.env.*
+!.env.example

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: slopguard-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Defend developers and AI coding agents against slopsquatting (hallucinated package names).
 Project-URL: Homepage, https://github.com/hariomunknownslab/slopguard
 Project-URL: Repository, https://github.com/hariomunknownslab/slopguard
 Project-URL: Issues, https://github.com/hariomunknownslab/slopguard/issues
 Author-email: SlopGuard <contact@unknownslab.com>
 License: MIT
-License-File: LICENSE
 Keywords: ai,llm,package-hallucination,security,slopsquatting,supply-chain
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -40,7 +39,8 @@ Description-Content-Type: text/markdown
 # SlopGuard
 
 [![CI](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml/badge.svg)](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/slopguard.svg)](https://pypi.org/project/slopguard/)
+[![PyPI](https://img.shields.io/pypi/v/slopguard-cli.svg)](https://pypi.org/project/slopguard-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/slopguard-cli.svg)](https://pypi.org/project/slopguard-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **Slopsquatting** is what happens when an LLM hallucinates a plausible-sounding

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/README.md

@@ -1,7 +1,8 @@
 # SlopGuard
 
 [![CI](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml/badge.svg)](https://github.com/hariomunknownslab/slopguard/actions/workflows/ci.yml)
-[![PyPI](https://img.shields.io/pypi/v/slopguard.svg)](https://pypi.org/project/slopguard/)
+[![PyPI](https://img.shields.io/pypi/v/slopguard-cli.svg)](https://pypi.org/project/slopguard-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/slopguard-cli.svg)](https://pypi.org/project/slopguard-cli/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 **Slopsquatting** is what happens when an LLM hallucinates a plausible-sounding

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "slopguard-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Defend developers and AI coding agents against slopsquatting (hallucinated package names)."
 readme = "README.md"
 license = { text = "MIT" }

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/slopguard/__init__.py

@@ -2,6 +2,6 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.1.1"
 
 __all__ = ["__version__"]

{slopguard_cli-0.1.0 → slopguard_cli-0.1.1}/tests/test_cli.py

@@ -107,7 +107,7 @@ def runner() -> CliRunner:
 def test_version_subcommand(runner: CliRunner) -> None:
     result = runner.invoke(app, ["version"])
     assert result.exit_code == 0
-    assert result.stdout.strip() == "0.1.0"
+    assert result.stdout.strip() == "0.1.1"
 
 
 def test_scan_fixtures_no_network_terminal(runner: CliRunner, fixtures_dir: Path) -> None:
@@ -183,4 +183,4 @@ def test_module_main_runs() -> None:
         check=False,
     )
     assert result.returncode == 0
-    assert result.stdout.strip() == "0.1.0"
+    assert result.stdout.strip() == "0.1.1"

slopguard_cli-0.1.0/.github/workflows/ci.yml

@@ -1,52 +0,0 @@
-name: CI
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.11", "3.12"]
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-          cache: pip
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
-      - name: Lint
-        run: |
-          ruff check slopguard/ tests/
-          ruff format --check slopguard/ tests/
-      - name: Type check
-        run: mypy --strict slopguard/
-      - name: Test
-        run: pytest -q --cov=slopguard --cov-report=term --cov-fail-under=85
-      - name: Build wheel
-        if: matrix.python-version == '3.11'
-        run: |
-          pip install build
-          python -m build
-      - name: Smoke-test wheel install
-        if: matrix.python-version == '3.11'
-        run: |
-          python -m venv /tmp/wheel-venv
-          /tmp/wheel-venv/bin/pip install dist/*.whl
-          /tmp/wheel-venv/bin/slopguard version
-          # Fixtures contain known hallucinations on purpose, so scan exits 1.
-          # Assert that, then validate the JSON payload.
-          set +e
-          /tmp/wheel-venv/bin/slopguard scan tests/fixtures --no-network --format json --output /tmp/report.json
-          rc=$?
-          set -e
-          test "$rc" = "1"
-          test "$(jq -r .slopguard_version /tmp/report.json)" = "0.1.0"
-          test "$(jq -r .summary.hallucinated /tmp/report.json)" -ge 1

slopguard_cli-0.1.0/.github/workflows/release.yml

@@ -1,68 +0,0 @@
-name: Release to PyPI
-
-# Triggered when a GitHub release is published, or manually via the Actions UI.
-# The first run will register the project on PyPI under whoever owns the
-# trusted publisher configuration on the PyPI side.
-#
-# Setup once on PyPI: https://pypi.org/manage/account/publishing/ → "Add a new
-# pending publisher" with:
-#   PyPI Project Name: slopguard
-#   Owner:             hariomunknownslab
-#   Repository name:   slopguard
-#   Workflow name:     release.yml
-#   Environment name:  (leave blank)
-# After the first successful run, PyPI promotes the pending publisher to a real
-# project-scoped trusted publisher; no token is ever stored.
-
-on:
-  release:
-    types: [published]
-  workflow_dispatch:
-    inputs:
-      ref:
-        description: "Git ref to publish (tag, branch, or SHA). Defaults to the workflow's ref."
-        required: false
-        default: ""
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    name: Build sdist + wheel
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: ${{ inputs.ref || github.ref }}
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - name: Install build
-        run: python -m pip install --upgrade build
-      - name: Build
-        run: python -m build
-      - name: Verify metadata
-        run: |
-          python -m pip install twine
-          python -m twine check dist/*
-      - name: Upload artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: pypi-dists
-          path: dist/
-
-  publish:
-    name: Publish to PyPI
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write   # required for OIDC trusted publishing
-    steps:
-      - name: Download artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: pypi-dists
-          path: dist/
-      - name: Publish
-        uses: pypa/gh-action-pypi-publish@release/v1

slopguard_cli-0.1.0/.github/workflows/slopguard.yml.example

@@ -1,35 +0,0 @@
-# Copy this file into your own repository as `.github/workflows/slopguard.yml`.
-#
-# It installs SlopGuard, scans the repository on every pull request and push to
-# main, and uploads the JSON report as a build artifact. The job fails the
-# build whenever SlopGuard exits non-zero.
-
-name: SlopGuard
-
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  slopguard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-
-      - name: Install SlopGuard
-        run: pip install slopguard-cli
-
-      - name: Scan
-        run: slopguard scan . --format json --output slopguard-report.json
-
-      - name: Upload report
-        if: always()
-        uses: actions/upload-artifact@v4
-        with:
-          name: slopguard-report
-          path: slopguard-report.json

slopguard_cli-0.1.0/CONTRIBUTING.md

@@ -1,30 +0,0 @@
-# Contributing to SlopGuard
-
-Thanks for the interest. SlopGuard is MIT-licensed and welcomes contributions.
-
-## Quick start
-
-```bash
-git clone https://github.com/hariomunknownslab/slopguard
-cd slopguard
-python -m venv .venv && source .venv/bin/activate
-make install
-make all   # lint, typecheck, test
-```
-
-## Ground rules
-
-- `ruff check` and `ruff format` must pass cleanly.
-- `mypy --strict slopguard/` must pass with zero errors.
-- Test coverage on `slopguard/` must stay ≥ 85%.
-- No `Any`, no unjustified `# type: ignore`.
-- Do not add features outside the v0.1 scope without filing an issue first.
-
-## Reporting hallucinated package names
-
-Open an issue with:
-- the package name (and ecosystem),
-- the LLM / tool that suggested it,
-- the prompt that produced the suggestion (if shareable).
-
-Curated reports feed the next iteration of the hallucination database.

slopguard_cli-0.1.0/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 SlopGuard
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

slopguard_cli-0.1.0/docs/ci-integration.md

@@ -1,106 +0,0 @@
-# CI integration
-
-SlopGuard is built to fail your CI before a slopsquatted package reaches
-`node_modules` or `site-packages`.
-
-## GitHub Actions
-
-Copy `.github/workflows/slopguard.yml.example` into your repo as
-`.github/workflows/slopguard.yml`:
-
-```yaml
-name: SlopGuard
-on:
-  pull_request:
-  push:
-    branches: [main]
-
-jobs:
-  slopguard:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.11"
-      - run: pip install slopguard-cli
-      - run: slopguard scan . --format json --output slopguard-report.json
-      - uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: slopguard-report
-          path: slopguard-report.json
-```
-
-The workflow fails the job whenever SlopGuard exits non-zero. Tune
-`--fail-on hallucinated` if you want suspicious-tier findings to surface as
-warnings rather than block the build.
-
-## Pre-commit
-
-SlopGuard isn't packaged as a pre-commit hook in v0.1 (see
-[deferred items](https://github.com/hariomunknownslab/slopguard) on the v0.2 roadmap),
-but a local hook is one line:
-
-```yaml
-# .pre-commit-config.yaml
-repos:
-  - repo: local
-    hooks:
-      - id: slopguard
-        name: slopguard scan
-        entry: slopguard scan
-        language: system
-        pass_filenames: false
-        always_run: true
-```
-
-## Other CI providers
-
-`slopguard scan` is provider-agnostic. Anything that can install Python and
-run a shell command works:
-
-```bash
-pip install slopguard-cli
-slopguard scan . --format json --output slopguard-report.json
-```
-
-If a finding lands above the configured threshold, SlopGuard exits 1 and your
-pipeline fails.
-
-## CI-friendly flags
-
-- `--format json --output <file>` — machine-readable artifact you can hand to
-  a downstream summariser or commenter.
-- `--fail-on hallucinated` — strictest tier. Useful when you do not want
-  suspicious findings to break the build but still want them in the artifact.
-- `--no-network` — useful in air-gapped CI. Detection falls back to the
-  embedded seed DB + name-pattern signal.
-- `--concurrency` — bump up to 32 or 64 on a fast runner with many
-  dependencies; the public registries tolerate it.
-
-## Reading the JSON
-
-```json
-{
-  "slopguard_version": "0.1.0",
-  "summary": { "total": 47, "clean": 44, "suspicious": 2, "hallucinated": 1, "errors": 0 },
-  "findings": [
-    {
-      "name": "react-codeshift",
-      "ecosystem": "npm",
-      "manifest": "package.json",
-      "risk": "hallucinated",
-      "score": 0.95,
-      "signals": [
-        { "type": "hallucination_db_hit", "weight": 0.9, "detail": "Matched seed DB entry; recurrence 0.71 across 3 models." }
-      ],
-      "remediation": "Remove this dependency. Verify the package your AI suggested actually exists at the source you trust."
-    }
-  ],
-  "exit_code": 1
-}
-```
-
-The schema is documented in section 8 of the v0.1 spec. Treat it as a public
-API contract — version-bump SlopGuard if you ever need to break it.

slopguard_cli-0.1.0/docs/detection.md

@@ -1,77 +0,0 @@
-# How detection works
-
-SlopGuard scores each dependency by combining independent signals into a single
-risk score in `[0.0, 1.0]`, then maps the score to a tier:
-
-| Tier | Default range | Meaning |
-|---|---|---|
-| `hallucinated` | score ≥ 0.85 | High confidence the dependency is a hallucinated / slopsquat package. |
-| `suspicious` | 0.40 ≤ score < 0.85 | Worth a human look before installing. |
-| `clean` | score < 0.40 | No actionable evidence of risk. |
-| `error` | n/a | SlopGuard could not score the dependency (e.g. registry unreachable). |
-
-Thresholds are configurable in `.slopguard.yaml`.
-
-## Signals
-
-| Signal | Trigger | Weight |
-|---|---|---|
-| `hallucination_db_hit` | Exact match (lowercased) in the embedded seed DB. | +0.90 |
-| `registry_not_found` | Registry returned 404 for the name. | +0.85 |
-| `very_recently_published` | First release < 7 days ago. | +0.35 |
-| `recently_published` | First release < 30 days ago. | +0.20 |
-| `low_downloads` | < 100 downloads (last month for npm, last week for PyPI). | +0.15 |
-| `new_publisher` | Publisher account < 30 days old. | +0.20 |
-| `single_release_new_account` | Publisher's only release; account < 60 days old. | +0.30 |
-| `levenshtein_typo` | Levenshtein distance 1–2 from a top-1000 popular package. | +0.25 |
-| `name_pattern_suspicious` | Matches a classic hallucination shape: `<stem>-(helpers?\|utils?\|async\|pro\|kit\|sdk\|tools?\|extras?\|plus\|next\|core)`. | +0.10 |
-
-The final score is the sum of triggered signal weights, capped at 1.0.
-
-## Order of operations per dependency
-
-1. **Hallucination-DB hit.** Short-circuit to `hallucinated`. Skip the registry
-   probe unless `--verbose` is set (verbose still probes for completeness in the
-   JSON report).
-2. **`--no-network`.** Only the DB hit and `name_pattern_suspicious` apply.
-3. **Registry probe.** Async, bounded by `--concurrency`, with timeouts and
-   exponential back-off on 5xx / 429.
-4. **404 → `registry_not_found` + stop.** The name doesn't exist on the
-   registry; Levenshtein and name-pattern signals are still emitted for
-   diagnostic value.
-5. **200 → full signal sweep.** Compute every applicable signal from registry
-   metadata.
-
-## Edge cases
-
-- **Scoped npm packages (`@org/name`):** registry probe is skipped (private /
-  internal packages are common at these names). They are scored `clean` unless
-  the seed DB has them.
-- **Local file dependencies (`file:`, `link:`):** ignored entirely.
-- **Git URL dependencies:** out of scope for v0.1 scoring — emitted as `clean`
-  with an informational `git_dependency` signal in the JSON output.
-- **Version pins:** not used for v0.1 detection. Version-specific signals are
-  on the v0.2 roadmap.
-
-## The hallucination database
-
-`slopguard/data/hallucinations_seed.json` ships embedded in the wheel and is
-loaded via `importlib.resources` at runtime. The current seed is **placeholder
-data**: the production database will be assembled from academic research on
-LLM-suggested packages plus a live probing harness. The schema is fixed at
-`schema_version: 1`; future updates will preserve backwards compatibility.
-
-## Popular-package lists
-
-Top-1000 npm and PyPI names live in `slopguard/data/popular_packages.json` and
-back the Levenshtein-typo signal. The lists are synthesised for v0.1 and will
-be replaced with authoritative download-count rankings before release.
-
-## What detection does *not* do (v0.1)
-
-- No live LLM probing.
-- No CVE / advisory matching.
-- No license scanning, no SBOM.
-- No supply-chain attestation (Sigstore, provenance, etc.).
-
-See the build spec, section 14, for the full list of deferred capabilities.

slopguard_cli-0.1.0/docs/usage.md

@@ -1,103 +0,0 @@
-# Usage
-
-## Install
-
-```bash
-pip install slopguard-cli
-# or
-brew install slopguard   # formula ships in dist/homebrew/ in a later release
-```
-
-The PyPI distribution name is `slopguard-cli`; the installed binary and
-Python import are still `slopguard`.
-
-## Commands
-
-### `slopguard scan`
-
-```text
-slopguard scan [PATH] [OPTIONS]
-```
-
-| Argument / Option | Default | Notes |
-|---|---|---|
-| `PATH` | current working directory | A project directory or a single manifest file. |
-| `--format` | `terminal` | `terminal` for Rich output, `json` for the wire format. |
-| `--output` | — | Write JSON to a file (only with `--format=json`). |
-| `--config` | auto-detected `.slopguard.yaml` | Path to a config file. SlopGuard walks up 3 parents from PATH. |
-| `--fail-on` | `suspicious` | `any` / `hallucinated` / `suspicious` / `none` — risk level that triggers exit 1. |
-| `--no-network` | off | Skip registry probes; rely on the seed DB + name-pattern signal. |
-| `--timeout` | 5.0s | Per-request timeout for registry probes. |
-| `--concurrency` | 16 | Maximum concurrent registry probes. |
-| `--verbose` / `-v` | off | Show debug logs. With `--verbose`, DB-hit findings still probe the registry for completeness. |
-
-### `slopguard version`
-
-Prints the package version and exits 0.
-
-## Exit codes
-
-| Code | Meaning |
-|---|---|
-| 0 | Scan complete, no findings at or above the `--fail-on` threshold. |
-| 1 | Scan complete, findings at or above the `--fail-on` threshold present. |
-| 2 | Could not run (bad input, no manifests found, IO error, etc.). |
-
-## Manifest auto-detection
-
-`slopguard scan` walks the target directory up to 2 levels deep, skipping
-`node_modules`, `.venv`, `venv`, `__pycache__`, `.git`, `dist`, `build`.
-
-Recognised manifests:
-
-- `package.json`, `package-lock.json` (npm)
-- `requirements.txt`, `pyproject.toml`, `Pipfile` (Python)
-
-If a `package.json` and `package-lock.json` sit in the same directory, the
-lockfile is skipped — the manifest's directly-declared dependencies are what
-matter for slopsquat detection.
-
-## `.slopguard.yaml`
-
-```yaml
-# Every field is optional.
-
-ignore:
-  packages:                 # exact package names to skip
-    - internal-tool
-    - my-private-pkg
-  patterns:                 # regex patterns matched against package names
-    - "^@mycompany/"
-
-fail_on: suspicious         # any | hallucinated | suspicious | none
-
-network:
-  enabled: true
-  timeout_seconds: 5
-  concurrency: 16
-
-scoring:
-  suspicious_min_score: 0.4
-  hallucinated_min_score: 0.85
-```
-
-Merge precedence: **CLI flags > `.slopguard.yaml` > defaults.**
-
-## Three useful invocations
-
-```bash
-# 1. Default scan of the current directory.
-slopguard scan
-
-# 2. Scan a specific service in a monorepo.
-slopguard scan ./mono/services/api
-
-# 3. CI mode: JSON output, file artifact, fail only on hallucinated.
-slopguard scan --format json --output slopguard-report.json --fail-on hallucinated
-```
-
-## Performance
-
-A scan of ~200 dependencies completes in **under 10 seconds** on a residential
-broadband connection with `--concurrency 16`. Registry round-trips dominate;
-results are memoised in-process so duplicate dependency entries are free.