Update documentation for first release [skip ci]

BeckettFrey · BeckettFrey · commit c57f2ec922af · 2026-02-26T14:29:11.000-06:00
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 WISC Lab
+
+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.
diff --git a/README.md b/README.md
@@ -1,216 +1,174 @@
-# ShredGuard
+# ShredGuard by [WISC Lab](https://kidspeech.wisc.edu/)
 
-A CLI tool to scan files for configurable regex patterns (PHI identifiers) and optionally replace matches with deterministic pseudonyms. Integrates with pre-commit framework.
+[![CI](https://github.com/WiscLab/shred-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/WISCLab/shred-guard/actions/workflows/ci.yml) [![CD](https://github.com/WISCLab/shred-guard/actions/workflows/cd.yml/badge.svg)](https://github.com/WISCLab/shred-guard/actions/workflows/cd.yml)
 
-## Features
+Scan files for PHI (Protected Health Information) patterns and replace them with deterministic pseudonyms. Integrates seamlessly with pre-commit hooks.
 
-- Scan files for PHI patterns using configurable regex
-- Replace matches with deterministic pseudonyms (same value = same ID)
-- Pre-commit integration for automated checks
-- Respects `.gitignore` patterns
-- Ruff-style output format (`file:line:col: SGxxx Message`)
-- Cross-platform support (Windows, macOS, Linux)
 
-## Installation
+## Appendix
 
-```bash
-pip install shredguard
-```
+- [Value Proposition](https://raw.githubusercontent.com/WiscLab/shred-guard/main/value-proposition.svg)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [shredguard init](#shredguard-init)
+  - [shredguard check](#shredguard-check)
+  - [shredguard fix](#shredguard-fix)
+- [Configuration](#configuration)
+- [Pre-commit](#pre-commit)
+- [Reference](#reference)
+  - [CLI Options](#cli-options)
+  - [Configuration Reference](#configuration-reference)
+  - [Built-in Pattern Suggestions](#built-in-pattern-suggestions)
+  - [Exit Codes](#exit-codes)
+  - [Binary File Handling](#binary-file-handling)
+- [License](#license)
 
-Or install from source:
+## Installation
 
 ```bash
-pip install -e .
+pip install shred-guard
 ```
 
 ## Quick Start
 
-1. Add configuration to your `pyproject.toml`:
-
-```toml
-[tool.shredguard]
-[[tool.shredguard.patterns]]
-regex = "SUB-\\d{4,6}"
-description = "Subject ID"
-
-[[tool.shredguard.patterns]]
-regex = "\\b\\d{3}-\\d{2}-\\d{4}\\b"
-description = "SSN-like pattern"
-
-[[tool.shredguard.patterns]]
-regex = "MRN\\d{6,10}"
-description = "Medical Record Number"
-```
-
-2. Run a check:
+Run the interactive setup wizard:
 
 ```bash
-shredguard check .
+shredguard init
 ```
 
-3. Fix (replace) found patterns:
+This walks you through:
+- Selecting PHI patterns to detect (SSNs, emails, MRNs, custom patterns)
+- Configuring file restrictions
+- Setting up pre-commit hooks
 
-```bash
-shredguard fix --prefix REDACTED .
-```
+## Commands
 
-## Pre-commit Setup
+### `shredguard init`
 
-Add to your `.pre-commit-config.yaml`:
-
-```yaml
-repos:
-  - repo: https://github.com/shredguard/shredguard
-    rev: v0.1.0
-    hooks:
-      - id: shredguard-check
-```
-
-Or to automatically fix:
-
-```yaml
-repos:
-  - repo: https://github.com/shredguard/shredguard
-    rev: v0.1.0
-    hooks:
-      - id: shredguard-fix
-        args: [--prefix, REDACTED]
-```
-
-## CLI Reference
+Interactive setup wizard. Creates your configuration and optionally sets up pre-commit integration.
 
 ### `shredguard check`
 
-Scan files for PHI patterns.
+Scan for PHI patterns:
 
 ```bash
-shredguard check [OPTIONS] [FILES]...
+shredguard check .                    # Scan current directory
+shredguard check data/ notes.txt     # Scan specific paths
 ```
 
-**Arguments:**
-- `FILES` - Files or directories to scan (default: current directory)
-
-**Options:**
-- `--all-files` - Scan all files (typically used with pre-commit)
-- `--no-gitignore` - Don't respect `.gitignore` patterns
-- `--config PATH` - Path to config file (default: searches for `pyproject.toml`)
-- `--verbose, -v` - Show verbose output (skipped files, etc.)
-
-**Exit codes:**
-- `0` - No matches found
-- `1` - Matches found or error
+Output uses ruff-style formatting:
+```
+patient_notes.txt:1:9: SG001 Subject ID [SUB-1234]
+patient_notes.txt:2:6: SG002 SSN [123-45-6789]
+```
 
 ### `shredguard fix`
 
-Replace PHI patterns with pseudonyms.
+Replace PHI with pseudonyms:
 
 ```bash
-shredguard fix [OPTIONS] [FILES]...
+shredguard fix .                                    # Replace with REDACTED-0, REDACTED-1, ...
+shredguard fix --prefix ANON .                     # Custom prefix: ANON-0, ANON-1, ...
+shredguard fix --output-map mapping.json .         # Save original -> pseudonym mapping
 ```
 
-**Arguments:**
-- `FILES` - Files or directories to scan and fix (default: current directory)
-
-**Options:**
-- `--prefix PREFIX` - Prefix for pseudonyms (default: `REDACTED`)
-- `--output-map PATH` - Write JSON mapping of originals to pseudonyms
-- `--all-files` - Scan all files
-- `--no-gitignore` - Don't respect `.gitignore` patterns
-- `--config PATH` - Path to config file
-- `--verbose, -v` - Show verbose output
+Replacements are deterministic: and the same value always gets the same pseudonym within a run.
 
-## Configuration Reference
+## Configuration
 
-Configuration is read from `pyproject.toml` under the `[tool.shredguard]` section.
+Configuration lives in `pyproject.toml` (or `/*/*.toml` set with --config):
 
-### Patterns
+```toml
+[tool.shredguard]
 
-Define patterns to scan for:
+[[tool.shredguard.patterns]]
+regex = "SUB-\\d{4,6}"
+description = "Subject ID"
 
-```toml
 [[tool.shredguard.patterns]]
-regex = "SUB-\\d{4,6}"        # Required: regex pattern
-description = "Subject ID"     # Optional: description for output
-files = ["*.csv", "data/**"]   # Optional: only scan matching files
-exclude_files = ["*_test.*"]   # Optional: exclude matching files
+regex = "\\b\\d{3}-\\d{2}-\\d{4}\\b"
+description = "SSN"
 ```
 
-**Pattern fields:**
-- `regex` (required) - Regular expression pattern to match
-- `description` (optional) - Human-readable description shown in output
-- `files` (optional) - List of glob patterns; only scan files matching these
-- `exclude_files` (optional) - List of glob patterns; skip files matching these
-
-### Pattern Codes
-
-Patterns are assigned stable codes (SG001, SG002, etc.) based on their order in the config file.
+Each pattern can optionally include `files` and `exclude_files` globs to control which files are scanned.
 
-## Example Workflow
+## Pre-commit
 
-1. Create test files with PHI:
+Add to `.pre-commit-config.yaml`:
 
-```bash
-echo "Patient SUB-1234 was enrolled on 2024-01-15" > patient_notes.txt
-echo "SSN: 123-45-6789" >> patient_notes.txt
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: shredguard-check
+        name: shredguard check
+        entry: shredguard check
+        language: system
+        types: [text]
 ```
 
-2. Check for PHI:
+Or let `shredguard init` set this up for you.
 
-```bash
-$ shredguard check patient_notes.txt
-patient_notes.txt:1:9: SG001 Subject ID [SUB-1234]
-patient_notes.txt:2:6: SG002 SSN-like pattern [123-45-6789]
+## Reference
 
-Found 2 matches in 1 file
-```
+### CLI Options
 
-3. Replace PHI with pseudonyms:
+**`shredguard check [OPTIONS] [FILES]...`**
 
-```bash
-$ shredguard fix --prefix ANON --output-map mapping.json patient_notes.txt
-Replaced 2 occurrences of 2 unique values in 1 file
-Mapping written to: mapping.json
-```
+| Option | Description |
+|--------|-------------|
+| `--all-files` | Scan all files recursively |
+| `--no-gitignore` | Don't respect `.gitignore` patterns |
+| `--config PATH` | Path to config file |
+| `-v, --verbose` | Show verbose output (skipped files, etc.) |
 
-4. Verify replacement:
+**`shredguard fix [OPTIONS] [FILES]...`**
 
-```bash
-$ cat patient_notes.txt
-Patient ANON-0 was enrolled on 2024-01-15
-SSN: ANON-1
-
-$ cat mapping.json
-{
-  "SUB-1234": "ANON-0",
-  "123-45-6789": "ANON-1"
-}
-```
+| Option | Description |
+|--------|-------------|
+| `--prefix TEXT` | Prefix for pseudonyms (default: `REDACTED`) |
+| `--output-map PATH` | Write JSON mapping of originals to pseudonyms |
+| `--all-files` | Scan all files recursively |
+| `--no-gitignore` | Don't respect `.gitignore` patterns |
+| `--config PATH` | Path to config file |
+| `-v, --verbose` | Show verbose output |
 
-## Deterministic Replacement
+### Configuration Reference
 
-ShredGuard uses deterministic pseudonym assignment:
-- The same matched value always gets the same pseudonym within a single run
-- IDs are assigned in order of first encounter (0, 1, 2, ...)
-- The mapping can be saved to a JSON file for reference
+```toml
+[[tool.shredguard.patterns]]
+regex = "SUB-\\d{4,6}"        # Required: regex pattern
+description = "Subject ID"     # Optional: shown in output
+files = ["*.csv", "data/**"]   # Optional: only scan matching files
+exclude_files = ["*_test.*"]   # Optional: skip matching files
+```
 
-## Binary File Detection
+### Built-in Pattern Suggestions
 
-Binary files are automatically detected and skipped using a null byte heuristic (checking first 8KB). Use `--verbose` to see which files are skipped.
+When running `shredguard init`, you can choose from these common patterns:
 
-## Development
+| Pattern | Description |
+|---------|-------------|
+| `SUB-\d{4,6}` | Subject ID |
+| `\b\d{3}-\d{2}-\d{4}\b` | Social Security Number |
+| `MRN\d{6,10}` | Medical Record Number |
+| `[email pattern]` | Email addresses |
+| `[phone pattern]` | Phone numbers (10 digits) |
+| `\b\d{5}(?:-\d{4})?\b` | ZIP codes |
 
-Install development dependencies:
+### Exit Codes
 
-```bash
-pip install -e ".[dev]"
-```
+| Code | Meaning |
+|------|---------|
+| `0` | Success (no matches found for `check`) |
+| `1` | Matches found or error |
 
-Run tests:
+### Binary File Handling
 
-```bash
-pytest
-```
+Binary files are automatically detected and skipped (null byte check in first 8KB). Use `--verbose` to see skipped files.
 
 ## License
 
-MIT
+[MIT](https://github.com/WiscLab/shred-guard/blob/main/LICENSE)
diff --git a/pyproject.toml b/pyproject.toml
@@ -7,14 +7,12 @@ name = "shred-guard"
 dynamic = ["version"]
 description = "A CLI tool to scan files for configurable regex patterns (PHI identifiers) and optionally replace matches with deterministic pseudonyms"
 readme = "README.md"
-license = "MIT"
 requires-python = ">=3.10"
 authors = [
-    { name = "ShredGuard Contributors" }
+    { name = "@BeckettFrey" }
 ]
 keywords = ["phi", "pii", "redaction", "pre-commit", "security"]
 classifiers = [
-    "Development Status :: 4 - Beta",
     "Environment :: Console",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
diff --git a/src/shredguard/cli.py b/src/shredguard/cli.py
@@ -373,7 +373,7 @@ def init() -> None:
         click.echo(f"  [{i}] {pattern['description']}")
         click.secho(f"      regex: {pattern['regex']}", fg="bright_black")
 
-        if click.confirm(f"      Include this pattern?", default=True):
+        if click.confirm("      Include this pattern?", default=True):
             selected_patterns.append(pattern.copy())
         click.echo()
 
diff --git a/tests/test_fixer.py b/tests/test_fixer.py
@@ -7,7 +7,6 @@
 from shredguard.config import Pattern
 from shredguard.fixer import (
     Fixer,
-    FixResult,
     PrefixCollisionError,
     check_prefix_collisions,
     apply_fixes,
diff --git a/tests/test_gitignore.py b/tests/test_gitignore.py
@@ -1,6 +1,5 @@
 """Tests for shredguard.gitignore module."""
 
-import pytest
 from pathlib import Path
 
 from shredguard.gitignore import (
diff --git a/tests/test_scanner.py b/tests/test_scanner.py
@@ -1,6 +1,5 @@
 """Tests for shredguard.scanner module."""
 
-import pytest
 from pathlib import Path
 
 from shredguard.config import Pattern
diff --git a/value-proposition.svg b/value-proposition.svg
