refhound 0.1.0b1__tar.gz

refhound-0.1.0b1/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src/refhound
+      - run: uv run pytest --cov=refhound --cov-report=xml --cov-fail-under=70
+      - uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.xml
+
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --all-extras
+      - run: uv run pytest
+
+  security-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras
+      - run: uv run pytest tests/security
+
+  docs-and-package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --all-extras
+      - run: uv run sphinx-build -W docs docs/_build
+      - run: uv build
+      - run: uv run --isolated --with dist/*.whl refhound --version
+      - run: uv run --isolated --with dist/*.whl refhound --help
+      - run: uv run --isolated --with dist/*.whl refhound scan --help
+      - run: uv run --isolated --with dist/*.whl refhound doctor --help

refhound-0.1.0b1/.github/workflows/packages.yml

@@ -0,0 +1,176 @@
+name: Packages
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - "debian/**"
+      - "packaging/**"
+      - "pyproject.toml"
+      - "src/**"
+      - ".github/workflows/packages.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  arch:
+    name: Arch Linux package
+    runs-on: ubuntu-latest
+    container: archlinux:latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and install package
+        run: |
+          set -euo pipefail
+          pacman -Syu --noconfirm base-devel git python python-build python-hatchling \
+            python-installer python-wheel python-typer python-rich python-pydantic \
+            python-sqlalchemy python-platformdirs python-httpx python-yaml pacman-contrib
+
+          version=$(python3 -c "import ast,pathlib; m=ast.parse(pathlib.Path('src/refhound/_version.py').read_text()); print(next(ast.literal_eval(n.value) for n in m.body if isinstance(n, ast.Assign) and any(getattr(t, 'id', '') == '__version__' for t in n.targets)))")
+
+          # checkout falls back to a source tarball when the image has no git,
+          # so build the release tarball from the working tree instead of git.
+          # COPYFILE_DISABLE keeps macOS tar from adding AppleDouble ._ members.
+          export COPYFILE_DISABLE=1
+          stage=$(mktemp -d)
+          tree="$stage/RefHound-$version"
+          mkdir -p "$tree"
+          cp -a "$GITHUB_WORKSPACE/." "$tree/"
+          rm -rf "$tree/.git" "$tree/artifacts" "$tree/.venv" "$tree/dist" \
+            "$tree/build" "$tree/docs/_build" "$tree/.pytest_cache" "$tree/.ruff_cache" \
+            "$tree/.mypy_cache" "$tree/.pybuild" "$tree/debian/.debhelper" \
+            "$tree/debian/refhound"
+          find "$tree" -name __pycache__ -type d -prune -exec rm -rf {} +
+          find "$tree" -name '*.egg-info' -type d -prune -exec rm -rf {} +
+          # macOS resource forks, for local runs of this recipe.
+          find "$tree" -name '._*' -delete
+          mkdir -p artifacts/source
+          tar -czf "artifacts/source/refhound-$version.tar.gz" -C "$stage" "RefHound-$version"
+          rm -rf "$stage"
+
+          useradd -m builder
+          chown -R builder:builder "$GITHUB_WORKSPACE"
+          chmod -R a+rX artifacts
+
+          su builder -s /bin/bash -c "
+            set -euo pipefail
+            cd '$GITHUB_WORKSPACE/packaging/arch'
+            REFHOUND_LOCAL_TARBALL='$GITHUB_WORKSPACE/artifacts/source/refhound-$version.tar.gz' \
+              makepkg -f --noconfirm
+          "
+
+          mkdir -p artifacts/arch
+          cp packaging/arch/refhound-*.pkg.tar.zst artifacts/arch/
+          pacman -U --noconfirm artifacts/arch/refhound-*.pkg.tar.zst
+          refhound --version
+          refhound scan --help >/dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-arch
+          path: artifacts/arch/*.pkg.tar.zst
+
+  debian:
+    name: Debian package
+    runs-on: ubuntu-latest
+    container: debian:trixie-slim
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build and install package
+        run: |
+          set -euo pipefail
+          apt-get update
+          apt-get install -y --no-install-recommends \
+            build-essential ca-certificates debhelper dh-python git lintian \
+            pybuild-plugin-pyproject python3-all python3-hatchling python3-typer \
+            python3-rich python3-pydantic python3-sqlalchemy python3-platformdirs \
+            python3-httpx python3-yaml
+
+          dpkg-buildpackage -us -uc -b
+          mkdir -p artifacts/debian
+          cp ../refhound_*.deb artifacts/debian/
+
+          apt-get install -y ./artifacts/debian/refhound_*.deb
+          refhound --version
+          refhound scan --help >/dev/null
+          lintian --fail-on error artifacts/debian/refhound_*.deb
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-debian
+          path: artifacts/debian/*.deb
+
+  rpm:
+    name: RPM package (${{ matrix.image }})
+    runs-on: ubuntu-latest
+    container: ${{ matrix.image }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - image: fedora:latest
+            artifact: rpm-fedora
+          - image: opensuse/tumbleweed:latest
+            artifact: rpm-opensuse
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install build tools
+        run: |
+          set -euo pipefail
+          if command -v dnf >/dev/null; then
+            dnf install -y git tar gzip rpm-build python3-devel pyproject-rpm-macros \
+              python3-hatchling python3-typer python3-rich python3-pydantic \
+              python3-sqlalchemy python3-platformdirs python3-httpx python3-pyyaml
+          else
+            zypper --non-interactive install git tar gzip rpm-build python3-devel \
+              python-rpm-macros python3-pip python3-hatchling python3-typer \
+              python3-rich python3-pydantic python3-SQLAlchemy python3-platformdirs \
+              python3-httpx python3-PyYAML
+          fi
+
+      - name: Build and install package
+        run: |
+          set -euo pipefail
+          version=$(python3 -c "import ast,pathlib; m=ast.parse(pathlib.Path('src/refhound/_version.py').read_text()); print(next(ast.literal_eval(n.value) for n in m.body if isinstance(n, ast.Assign) and any(getattr(t, 'id', '') == '__version__' for t in n.targets)))")
+
+          # checkout falls back to a source tarball when the image has no git,
+          # so build the release tarball from the working tree instead of git.
+          # COPYFILE_DISABLE keeps macOS tar from adding AppleDouble ._ members.
+          export COPYFILE_DISABLE=1
+          stage=$(mktemp -d)
+          tree="$stage/RefHound-$version"
+          mkdir -p "$tree"
+          cp -a "$GITHUB_WORKSPACE/." "$tree/"
+          rm -rf "$tree/.git" "$tree/artifacts" "$tree/.venv" "$tree/dist" \
+            "$tree/build" "$tree/docs/_build" "$tree/.pytest_cache" "$tree/.ruff_cache" \
+            "$tree/.mypy_cache" "$tree/.pybuild" "$tree/debian/.debhelper" \
+            "$tree/debian/refhound"
+          find "$tree" -name __pycache__ -type d -prune -exec rm -rf {} +
+          find "$tree" -name '*.egg-info' -type d -prune -exec rm -rf {} +
+          # macOS resource forks, for local runs of this recipe.
+          find "$tree" -name '._*' -delete
+          mkdir -p "$HOME/rpmbuild"/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}
+          tar -czf "$HOME/rpmbuild/SOURCES/refhound-$version.tar.gz" -C "$stage" "RefHound-$version"
+          rm -rf "$stage"
+          rpmbuild --define "_topdir $HOME/rpmbuild" -ba --nodeps packaging/rpm/refhound.spec
+
+          mkdir -p artifacts/${{ matrix.artifact }}
+          cp "$HOME"/rpmbuild/RPMS/noarch/*.rpm artifacts/${{ matrix.artifact }}/
+
+          if command -v dnf >/dev/null; then
+            dnf install -y artifacts/${{ matrix.artifact }}/*.rpm
+          else
+            zypper --non-interactive install --allow-unsigned-rpm artifacts/${{ matrix.artifact }}/*.rpm
+          fi
+          refhound --version
+          refhound scan --help >/dev/null
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-${{ matrix.artifact }}
+          path: artifacts/${{ matrix.artifact }}/*.rpm

refhound-0.1.0b1/.github/workflows/release.yml

@@ -0,0 +1,133 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+    inputs:
+      publish_pypi:
+        description: "Publish the built wheel and sdist to PyPI"
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Verify tag matches the packaged version
+        if: github.ref_type == 'tag'
+        run: |
+          set -euo pipefail
+          version=$(python -c "import ast, pathlib; m = ast.parse(pathlib.Path('src/refhound/_version.py').read_text()); print(next(ast.literal_eval(n.value) for n in m.body if isinstance(n, ast.Assign) and any(getattr(t, 'id', '') == '__version__' for t in n.targets)))")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match src/refhound/_version.py ($version)" >&2
+            exit 1
+          fi
+      - run: uv build
+      - run: uv run --isolated --with twine twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/*
+
+  verify-install:
+    name: Install wheel in isolation (Python ${{ matrix.python }})
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.12", "3.13"]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+      - run: uv run --isolated --python ${{ matrix.python }} --with dist/*.whl refhound --version
+      - run: uv run --isolated --python ${{ matrix.python }} --with dist/*.whl refhound --help
+      - run: uv run --isolated --python ${{ matrix.python }} --with dist/*.whl refhound scan --help
+      - run: uv run --isolated --python ${{ matrix.python }} --with dist/*.whl python -c "import refhound; print(refhound.__version__)"
+
+  packages:
+    name: Native packages
+    uses: ./.github/workflows/packages.yml
+
+  pypi:
+    name: Publish to PyPI
+    needs: [build, verify-install]
+    if: >-
+      (github.event_name == 'workflow_dispatch' && inputs.publish_pypi) ||
+      (github.event_name == 'push' && vars.PUBLISH_TO_PYPI == 'true')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/refhound
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: python-dist
+          path: dist
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist
+          print-hash: true
+
+  github-release:
+    name: GitHub release
+    needs: [build, verify-install, packages]
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: release-assets
+      - name: Generate checksums
+        run: |
+          set -euo pipefail
+          cd release-assets
+          find . -type f ! -name SHA256SUMS -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
+          cat SHA256SUMS
+      - name: Create release with all artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+          # This job does not check out the repository, so gh needs the repo name.
+          GH_REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          mapfile -t assets < <(find release-assets -type f)
+          case "$GITHUB_REF_NAME" in
+            *a[0-9]*|*b[0-9]*|*rc[0-9]*) flags=(--prerelease) ;;
+            *) flags=() ;;
+          esac
+          if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" "${assets[@]}" --clobber
+          else
+            gh release create "$GITHUB_REF_NAME" \
+              --title "RefHound $GITHUB_REF_NAME" \
+              --generate-notes \
+              "${flags[@]}" \
+              "${assets[@]}"
+          fi

refhound-0.1.0b1/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# Tooling caches
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Build output
+docs/_build/
+dist/
+build/
+.coverage
+coverage.xml
+
+# Debian build output
+.pybuild/
+debian/.debhelper/
+debian/debhelper-build-stamp
+debian/files
+debian/refhound/
+debian/*.substvars
+debian/*.debhelper
+
+# OS
+.DS_Store

refhound-0.1.0b1/.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs configuration for the Sphinx documentation.
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt

refhound-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to RefHound are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0b1] - 2026-11-04
+
+The first beta. The Python API is still an alpha surface until 1.0, but the
+CLI, package formats and release pipeline are usable.
+
+### Added
+
+- Public Python API in `refhound.api` with `scan_repository()`, typed
+  `ScanOptions` and a documented alpha stability contract.
+- Snapshot serialization moved out of the CLI into `refhound.snapshots`, so
+  library users can persist results without importing Typer or Rich.
+- `scan --no-store` for one-off analysis without database reads or writes.
+- Timeline filters for findings on a path or at a severity.
+- `SHA256SUMS` for every GitHub release asset.
+- Documented PyPI trusted publishing and manual release workflow.
+
+### Changed
+
+- Configuration is validated strictly; unknown keys and mistyped values are
+  errors instead of being ignored.
+- Unsupported `--format` values fail with exit code 2 instead of silently
+  falling back to the default renderer.
+- The package classifier is now `Development Status :: 4 - Beta`.
+
+### Fixed
+
+- Incomplete scans are no longer served from the snapshot cache; completeness,
+  diagnostics and failed detectors are persisted and restored.
+- Remote URL credentials are sanitized before they reach logs, SQLite or
+  repository snapshots, including a migration for existing databases.
+- `--offline` rejects `--unshallow` and `--refresh-remote` before any network
+  call.
+- CI help tests are independent of ANSI styling forced by GitHub Actions.
+- Native package builds work in container jobs: git safe-directory handling,
+  `file://` local sources for `makepkg`, and openSUSE's `python-rpm-macros`
+  package set.
+
+## [0.1.0a1] - 2026-11-04
+
+### Packaging
+
+- Single version source in `src/refhound/_version.py`, read by Hatchling and
+  Sphinx.
+- PyPI-ready wheel and sdist metadata with project URLs and Python 3.13.
+- Arch `PKGBUILD`, Debian packaging and an RPM spec for Fedora, RHEL 10+ and
+  openSUSE, built and smoke-tested in distribution containers.
+- Tag-driven release workflow with isolated wheel verification, GitHub release
+  assets and optional PyPI trusted publishing.
+
+### Security
+
+- Centralized secret fragment redaction; values of eight characters or less
+  now expose no prefix or suffix in models, reports, baselines, or storage.
+- Sanitized remote URL userinfo and credential-like query parameters before
+  command descriptions, repository models, logging, and reporting.
+- Enforced whole-process streaming timeouts, stderr draining, child cleanup,
+  and OID validation at the batch ``cat-file`` boundary.
+
+### Fixed
+
+- ``findings --json`` now applies the same severity/category/score filters as
+  table output and uses its own versioned schema.
+- Findings use one critical-first deterministic severity order.
+- Detector exceptions now produce structured incomplete-scan diagnostics.
+- Removed a foreign project URL from SARIF metadata.
+
+### Changed
+
+- Remote acquisition now distinguishes analysis freshness, mirror refresh,
+  and offline use; reports carry acquisition and object-format metadata.
+- Profiles are executable pipeline specifications and vendored content uses a
+  shared file/secret policy.
+- JSON/baseline/storage schemas are explicitly versioned; incomplete scans use
+  exit code 5.
+
+### Deprecated
+
+- No interfaces are deprecated in this unreleased version.
+
+### Removed
+
+- Removed the non-functional ``--jobs`` and ``--fetch-lfs`` options. RefHound
+  v0.1 does not claim parallel scanning or external LFS payload fetching.
+
+### Added
+
+- Core scan pipeline: refs, commit graph, blob inventory, secret detection,
+  unreachable/lost-chain archaeology, deleted-file and churn analysis,
+  timeline/identity/temporal anomaly detection, force-push change
+  detection, risk scoring, and interesting-commit ranking.
+- Secret detectors: GitHub/GitLab tokens, AWS/GCP cloud credentials,
+  private keys, JWT, database connection URIs, generic passwords, generic
+  provider tokens and entropy-only candidates.
+- Reporting: console tables, JSON, Markdown and SARIF 2.1.0, plus
+  repository statistics and baselines.
+- Storage: SQLite persistence (SQLAlchemy) of scan ref snapshots for
+  ref-change / force-push detection between scans.
+- Internal provider adapter scaffold (not exposed as a supported v0.1 feature).
+- CLI commands: `scan`, `findings`, `secrets`, `refs`, `commits`, `objects`,
+  `dangling`, `unreachable`, `lost`, `explain`, `explain-lost`, `timeline`,
+  `authors`, `stats`, `history`, `interesting`, `report`, `diff-scan`,
+  `baseline`, `doctor`, `cache info/list/refresh/remove/prune`, `analyze churn`.
+- Profiles (`quick`, `standard`, `deep`, `forensic`), `--fail-on`, baselines,
+  JSON/SARIF/Markdown output, exit-code contract (0/1/2/3/4/5).
+- Test suite: 78 unit, security, schema and integration tests including
+  secret-redaction, SHA-1/SHA-256, repository-shape and lost-chain guarantees.

refhound-0.1.0b1/CONTRIBUTING.md

@@ -0,0 +1,59 @@
+# Contributing
+
+Thanks for helping with RefHound.
+
+## Getting started
+
+```
+git clone <url> RefHound
+cd RefHound
+uv sync --all-extras
+```
+
+## Quality gates
+
+Every change must pass:
+
+```
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy src/refhound
+uv run pytest
+```
+
+Run them locally before pushing:
+
+```
+uv run ruff check . && uv run ruff format . && uv run mypy src/refhound && uv run pytest
+```
+
+## Tests
+
+* Unit tests live in `tests/unit/` and never touch git on disk.
+* Integration tests in `tests/integration/` build small repositories with
+  the fixtures in `tests/conftest.py` (simple repos, deleted-branch repos,
+  bare remotes) and exercise the full `Engine` pipeline.
+* The security contract (full secrets never appear in any output or
+  storage) is enforced by tests — keep it that way when adding features.
+
+## Conventions
+
+* Python 3.12+, `from __future__ import annotations` everywhere.
+* Type everything; mypy is run in `strict` mode.
+* Facts and interpretation stay separate. Any inference that could be wrong
+  must carry an explicit confidence value and be labeled a heuristic in
+  user-facing text.
+* Redaction: never print, log, persist or serialize a full secret.
+* New detectors go under `src/refhound/detectors/` and are registered in
+  `src/refhound/detectors/registry.py` with a test proving redaction.
+* Git is always invoked through `GitRunner`; never use `shell=True` and
+  always validate object IDs before interpolation.
+
+## Documentation
+
+User-facing docs live in `docs/` and are written in reStructuredText. Update
+`docs/index.rst` and the relevant topic page when changing behaviour.
+
+## Changelog
+
+Add an entry to `CHANGELOG.md` for user-visible changes.