dumpling-cli 0.2.0__tar.gz → 0.4.0__tar.gz

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/.dumplingconf.example

@@ -26,13 +26,17 @@ salt = "${DUMPLING_GLOBAL_SALT}"
 #
 # Each column maps to an anonymizer spec: { strategy = "…", <options> }
 # ---------------------------------------------------------------------------
+# Faker strategy: `faker = "module::Type"` matches the Rust `fake` crate layout.
+#   Crate docs: https://docs.rs/fake/latest/fake/
+#   Faker modules: https://docs.rs/fake/latest/fake/faker/index.html
+#   Upstream repo: https://github.com/cksac/fake-rs
 [rules."public.users"]
-# email  — random-looking email at example.com; force quoted string output
-email         = { strategy = "email", domain = "customer_identity", unique_within_domain = true }
-# name   — random placeholder full name
-full_name     = { strategy = "name" }
-first_name    = { strategy = "first_name" }
-last_name     = { strategy = "last_name" }
+# email  — fake email via Rust `fake` crate; force quoted string output
+email         = { strategy = "faker", faker = "internet::SafeEmail", domain = "customer_identity", unique_within_domain = true }
+# name   — locale-aware full name (see `locale`); other generators use `faker = "module::Type"`
+full_name     = { strategy = "faker", faker = "name::Name" }
+first_name    = { strategy = "faker", faker = "name::FirstName" }
+last_name     = { strategy = "faker", faker = "name::LastName" }
 # phone  — US-style (xxx) xxx-xxxx
 phone         = { strategy = "phone" }
 # ssn    — SHA-256 hex of original; use per-column salt for extra protection
@@ -58,7 +62,7 @@ wake_time     = { strategy = "time_fuzz", min_seconds = -3600, max_seconds = 360
 # credit card — redact entirely; force as quoted string
 credit_card   = { strategy = "redact", as_string = true }
 # keep the same anonymized email as users table via shared domain
-customer_email = { strategy = "email", domain = "customer_identity" }
+customer_email = { strategy = "faker", faker = "internet::SafeEmail", domain = "customer_identity" }
 
 [rules."public.audit_log"]
 # unqualified table name also works (matches any schema)

dumpling_cli-0.4.0/.github/workflows/docs-pr.yml

@@ -0,0 +1,35 @@
+# mdBook verification on pull requests only (no GitHub Pages upload or deploy).
+# Pages build + deploy live in docs.yml and run on pushes to main.
+name: Docs (PR)
+
+on:
+  pull_request:
+    paths:
+      - "README.md"
+      - "book.toml"
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+      - ".github/workflows/docs-pr.yml"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-pr-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  verify:
+    name: Build mdBook (verify)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install mdBook
+        uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: "0.4.52"
+
+      - name: Build documentation site
+        run: mdbook build

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/.github/workflows/docs.yml

@@ -1,12 +1,8 @@
+# Build and deploy the mdBook site to GitHub Pages (main branch only).
+# Pull-request verification runs in docs-pr.yml — this workflow does not run on PRs.
 name: Docs
 
 on:
-  pull_request:
-    paths:
-      - "README.md"
-      - "book.toml"
-      - "docs/**"
-      - ".github/workflows/docs.yml"
   push:
     branches:
       - main
@@ -18,16 +14,16 @@ on:
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: docs-${{ github.ref }}
+  group: docs-pages-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -40,15 +36,17 @@ jobs:
       - name: Build documentation site
         run: mdbook build
 
-      - name: Upload docs artifact
+      - name: Upload Pages deployment artifact
         uses: actions/upload-pages-artifact@v3
         with:
           path: docs/book
 
   deploy:
-    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: build
     runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/.gitignore

@@ -1,2 +1,3 @@
 /target/
 /docs/book/
+/.tools/

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/AGENTS.md

@@ -223,6 +223,8 @@ Follow these steps in order. Do not skip any step.
 
 8. **`README.md`**: Add a row to the "Anonymization strategies" table.
 
+**`faker` strategy:** Config only carries string identifiers; Dumpling never evaluates user Rust from config. To ship a new generator, add dispatch in `src/faker_dispatch.rs` and validation in `validate_anonymizer_spec` for the `faker` branch. Upstream reference: [`fake` on docs.rs](https://docs.rs/fake/latest/fake/), [`fake::faker` module index](https://docs.rs/fake/latest/fake/faker/index.html), [source on GitHub](https://github.com/cksac/fake-rs).
+
 ---
 
 ## How to Add a New Row Filter Predicate Operator
@@ -274,15 +276,29 @@ Follow these steps in order. Do not skip any step.
 
 This is a pure Rust CLI project with **no external services** (no database, Docker, or network dependencies). The Rust stable toolchain (rustc + cargo) is the only prerequisite.
 
+### One-shot environment (agents and humans)
+
+From the repository root:
+
+```bash
+./scripts/setup-dev.sh
+```
+
+This installs the **stable** toolchain with **rustfmt** and **clippy** (via `rustup` when available), runs **`cargo fetch`**, and installs a pinned **mdBook** binary under `.tools/` (same version as the Docs CI workflow) so you can run `mdbook build` without a global install. Add `.tools` to `PATH` for convenience, or invoke `.tools/mdbook build` directly.
+
+The repo root **`rust-toolchain.toml`** pins **stable** and the **components** CI uses, so `cargo` automatically selects the right toolchain in fresh checkouts.
+
 ### Quick reference
 
 | Task | Command |
 |------|---------|
+| Setup (toolchain + fetch + mdbook) | `./scripts/setup-dev.sh` |
 | Build | `cargo build` |
 | Test | `cargo test --all-targets --all-features` |
 | Lint | `cargo clippy --all-targets --all-features` |
 | Format check | `cargo fmt --all -- --check` |
 | Auto-format | `cargo fmt` |
+| Docs site (mdBook) | `mdbook build` or `.tools/mdbook build` after setup |
 | Run CLI | `./target/debug/dumpling --help` |
 
 ### Running the CLI
@@ -295,6 +311,6 @@ Dumpling is fail-closed by default — it exits non-zero without a config file.
 
 ### Notes
 
-- All 94 tests are inline `#[cfg(test)]` modules; there are no separate test files or fixtures to manage.
+- All tests are inline `#[cfg(test)]` modules; there are no separate test files or fixtures to manage.
 - The update script uses `cargo fetch` to pre-download crate dependencies. A full `cargo build` or `cargo test` will then compile from the local cache without network access.
 - No environment variables or secrets are required for building, testing, or running the CLI locally.

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

@@ -7,6 +7,31 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-05-02
+
+### Added
+
+- **`--dump-decode` CLI**: Decode PostgreSQL **custom-format** (`pg_dump -Fc`) or **directory-format** archives by running **`pg_restore -f -`** (plain SQL to stdout, no database), then anonymize—built for workflows such as **`heroku pg:backups:download`**. Requires PostgreSQL client tools (`pg_restore` on `PATH`, or **`--pg-restore-path`**).
+- **`--dump-decode-arg`** (repeatable): Extra arguments forwarded to `pg_restore`.
+- **`--dump-decode-keep-input`**: Keep the archive after a successful run. **By default** the `--input` path is **removed** after success so only anonymized output remains. **`--check`** with **`--dump-decode`** requires **`--dump-decode-keep-input`** (otherwise the dump would be deleted before config iteration).
+
+### Changed
+
+- README and mdBook documentation for PostgreSQL archive decoding and Heroku-style examples.
+
+## [0.3.0] - 2026-05-02
+
+### Added
+
+- **`faker` anonymization strategy** backed by the Rust [`fake`](https://crates.io/crates/fake) crate: select generators with `faker = "module::Type"` (for example `internet::SafeEmail`, `name::Name`). Unsupported targets fail at config load with a clear error; extending the allowlist requires a Dumpling release (see `src/faker_dispatch.rs`).
+- **JSON path rules in `[rules]`**: column keys such as `payload.profile.email` or `payload__profile__email` apply strategies to nested fields inside JSON text columns while preserving document structure. Conflicts between a whole-column rule and JSON path rules for the same base column are rejected at validation.
+- **`format` on `AnonymizerSpec`** for pattern-based faker generators such as `number::NumberWithFormat`.
+
+### Changed
+
+- **Legacy strategy names** `email`, `name`, `first_name`, and `last_name` in config are normalized at load time to `strategy = "faker"` with the same defaults as before (`internet::SafeEmail`, `name::Name`, `name::FirstName`, `name::LastName`), so existing configs keep working.
+- **`locale`** applies to both `faker` and `phone` strategies.
+
 ## [0.2.0] - 2026-05-02
 
 ### Added
@@ -30,4 +55,6 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 - Configurable output scan severities and per-category thresholds via `[output_scan]`.
 - JSON report section for output scan findings including category, count, threshold, severity, and sample locations.
 
+[0.4.0]: https://github.com/ababic/dumpling/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/ababic/dumpling/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/ababic/dumpling/compare/v0.1.0...v0.2.0

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/CONTRIBUTING.md

@@ -13,6 +13,14 @@ For AI coding agents: also read `AGENTS.md`, which contains more detailed techni
 - **Rust stable toolchain** — install via [rustup.rs](https://rustup.rs/).
 - No database, Docker, or external services are required. Dumpling is a pure CLI tool.
 
+### One-shot setup (recommended)
+
+```bash
+./scripts/setup-dev.sh
+```
+
+Installs stable + `rustfmt` + `clippy`, prefetches crates, and downloads a pinned **mdBook** under `.tools/` (for `mdbook build`, same version as CI). Optional: `export PATH="$PWD/.tools:$PATH"`.
+
 ### Build and run
 
 ```bash

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/Cargo.lock

@@ -262,7 +262,7 @@ dependencies = [
 
 [[package]]
 name = "dumpling"
-version = "0.2.0"
+version = "0.4.0"
 dependencies = [
  "anyhow",
  "chrono",

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "dumpling"
-version = "0.2.0"
+version = "0.4.0"
 edition = "2021"
 readme = "README.md"
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dumpling-cli
-Version: 0.2.0
+Version: 0.4.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -112,8 +112,8 @@ salt = "${DUMPLING_GLOBAL_SALT}"
 
 # Rules are keyed by either "table" or "schema.table"
 [rules."public.users"]
-email = { strategy = "email", domain = "customer_identity", unique_within_domain = true }
-name  = { strategy = "name", locale = "de_de" }   # German-locale name
+email = { strategy = "faker", faker = "internet::SafeEmail", domain = "customer_identity", unique_within_domain = true }
+name  = { strategy = "faker", faker = "name::Name", locale = "de_de" }   # German-locale name
 ssn   = { strategy = "hash", salt = "${env:DUMPLING_USERS_SSN_SALT}", as_string = true }   # SHA-256 of original (salted)
 age   = { strategy = "int_range", min = 18, max = 90 }
 
@@ -153,8 +153,7 @@ token = "high"
 | `redact` | Replace with `REDACTED` (string) |
 | `uuid` | Random UUIDv4-like string |
 | `hash` | SHA-256 hex of original value; supports per-column `salt` and global `salt` |
-| `email` | Random-looking email at `example.com` |
-| `name` / `first_name` / `last_name` | Locale-aware fake name (configurable via `locale`); defaults to English |
+| `faker` | Values from the Rust [`fake`](https://crates.io/crates/fake) crate ([docs.rs](https://docs.rs/fake/latest/fake/), [`faker` modules](https://docs.rs/fake/latest/fake/faker/index.html)), chosen by a **string identifier** only (`faker = "module::Type"`, e.g. `internet::SafeEmail`). Config is **data only**: nothing from TOML is compiled or executed as Rust at runtime. Use `locale` for locale-aware generators; optional `min`/`max`, `length`, `format` as documented. Unsupported targets fail at config load. New generators require a **new Dumpling release** (or your own fork), not config-side code. |
 | `phone` | Locale-aware fake phone number (configurable via `locale`); defaults to English format |
 | `int_range` | Random integer in `[min, max]` |
 | `string` | Random alphanumeric string (`length = 12` by default) |
@@ -162,6 +161,12 @@ token = "high"
 | `time_fuzz` | Shifts a time-of-day by a random number of seconds in `[min_seconds, max_seconds]` with 24h wraparound (defaults: `-300..300`) |
 | `datetime_fuzz` | Shifts a timestamp/timestamptz by a random number of seconds in `[min_seconds, max_seconds]` (defaults: `-86400..86400`) |
 
+**`faker` reference (upstream `fake` crate):** Dumpling’s `faker = "module::Type"` strings mirror the Rust [`fake`](https://crates.io/crates/fake) crate’s [`faker`](https://docs.rs/fake/latest/fake/faker/index.html) module layout. Use these when picking or extending generators:
+
+- [docs.rs — `fake` crate root](https://docs.rs/fake/latest/fake/) (overview, `Fake` / `Dummy` traits, locales)
+- [docs.rs — `fake::faker` module index](https://docs.rs/fake/latest/fake/faker/index.html) (per-domain submodules: `address`, `internet`, `name`, …)
+- [GitHub — `cksac/fake-rs`](https://github.com/cksac/fake-rs) (source, README with the CLI’s generator name list)
+
 ### Secret references
 
 Dumpling resolves secret references in string config fields so plaintext salts/keys
@@ -209,7 +214,9 @@ dumpling --security-profile hardened --input dump.sql --check
 - `unique_within_domain`: when true, different source values are assigned unique pseudonyms within the configured `domain`. NULL values are unaffected and always remain NULL.
 - `min_days` / `max_days`: used by `date_fuzz`.
 - `min_seconds` / `max_seconds`: used by `time_fuzz` and `datetime_fuzz`.
-- `locale`: selects the language/regional format for the `name`, `first_name`, `last_name`, and `phone` strategies. Supported values: `en`, `fr_fr`, `de_de`, `it_it`, `pt_br`, `pt_pt`, `ar_sa`, `zh_cn`, `zh_tw`, `ja_jp`, `cy_gb`. Defaults to `en` when not specified.
+- `locale`: selects the language/regional format for the `faker` and `phone` strategies. Supported values: `en`, `fr_fr`, `de_de`, `it_it`, `pt_br`, `pt_pt`, `ar_sa`, `zh_cn`, `zh_tw`, `ja_jp`, `cy_gb`. Defaults to `en` when not specified.
+- `faker`: required when `strategy = "faker"`. A plain string `"module::Type"` (case-insensitive) that maps to a **built-in** generator compiled into Dumpling—not arbitrary Rust or expressions. Names follow [`fake::faker`](https://docs.rs/fake/latest/fake/faker/index.html) (e.g. `internet::SafeEmail` → `faker::internet::SafeEmail` in the crate).
+- `format`: used with `faker = "number::NumberWithFormat"`; pattern uses `#` (0–9) and `^` (1–9) per the [`fake` crate docs](https://docs.rs/fake/latest/fake/).
 
 > **Note:** `table_options` are no longer supported; use explicit `rules` and optional `column_cases`.
 
@@ -282,7 +289,16 @@ Produced by `pg_dump --format=plain`. Handles:
 - `"double-quoted"` identifiers
 - `''`-escaped string literals
 
-Binary, custom, and directory formats from `pg_dump` are not supported — use `--format=plain` when running `pg_dump`.
+Binary, custom, and directory formats from `pg_dump` are not parsed directly — Dumpling’s SQL pipeline expects plain text. Use either:
+
+- **`pg_dump --format=plain`** when you control capture, or
+- **`dumpling --dump-decode`** with `--input` set to a **custom-format** (`.dump`) or **directory-format** folder: Dumpling runs `pg_restore -f -` and streams the resulting SQL (same as a manual `pg_restore` “script” output, no database required). Requires PostgreSQL client tools on `PATH` (`pg_restore`), or set `--pg-restore-path`. Use `--dump-decode-arg` to pass extra flags (e.g. `--no-owner --no-acl`). **By default** the archive is removed after a fully successful run; pass **`--dump-decode-keep-input`** to retain it. **`--check`** requires **`--dump-decode-keep-input`** so the archive still exists if changes would be detected.
+
+Example (e.g. after `heroku pg:backups:download`):
+
+```bash
+dumpling --dump-decode -i latest.dump -c .dumplingconf -o anonymized.sql
+```
 
 ### SQLite (`--format sqlite`)
 
@@ -353,7 +369,7 @@ Define default strategies in `rules."<table>"` and add ordered per-column cases
 ```toml
 [rules."public.users"]
 email = { strategy = "hash", as_string = true }   # default
-name  = { strategy = "name" }
+name  = { strategy = "faker", faker = "name::Name" }
 
 [[column_cases."public.users".email]]
 when.any = [{ column = "is_admin", op = "eq", value = "true" }]
@@ -404,7 +420,7 @@ salt = "${DUMPLING_HMAC_KEY}"
 
 [rules."public.users"]
 ssn = { strategy = "hash", as_string = true }
-email = { strategy = "email", domain = "users" }
+email = { strategy = "faker", faker = "internet::SafeEmail", domain = "users" }
 ```
 
 ```bash
@@ -470,5 +486,5 @@ See the [CI guardrails documentation](docs/src/ci-guardrails.md) for full pipeli
 
 ## Full documentation
 
-Detailed docs, including the configuration reference and release process, are available at the project's [GitHub Pages site](https://github.com) (built from `docs/src/`).
+Detailed docs, including the configuration reference and release process, are available at the project's [GitHub Pages site](https://ababic.github.io/dumpling/) (built from `docs/src/`).
 

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

@@ -91,8 +91,8 @@ salt = "${DUMPLING_GLOBAL_SALT}"
 
 # Rules are keyed by either "table" or "schema.table"
 [rules."public.users"]
-email = { strategy = "email", domain = "customer_identity", unique_within_domain = true }
-name  = { strategy = "name", locale = "de_de" }   # German-locale name
+email = { strategy = "faker", faker = "internet::SafeEmail", domain = "customer_identity", unique_within_domain = true }
+name  = { strategy = "faker", faker = "name::Name", locale = "de_de" }   # German-locale name
 ssn   = { strategy = "hash", salt = "${env:DUMPLING_USERS_SSN_SALT}", as_string = true }   # SHA-256 of original (salted)
 age   = { strategy = "int_range", min = 18, max = 90 }
 
@@ -132,8 +132,7 @@ token = "high"
 | `redact` | Replace with `REDACTED` (string) |
 | `uuid` | Random UUIDv4-like string |
 | `hash` | SHA-256 hex of original value; supports per-column `salt` and global `salt` |
-| `email` | Random-looking email at `example.com` |
-| `name` / `first_name` / `last_name` | Locale-aware fake name (configurable via `locale`); defaults to English |
+| `faker` | Values from the Rust [`fake`](https://crates.io/crates/fake) crate ([docs.rs](https://docs.rs/fake/latest/fake/), [`faker` modules](https://docs.rs/fake/latest/fake/faker/index.html)), chosen by a **string identifier** only (`faker = "module::Type"`, e.g. `internet::SafeEmail`). Config is **data only**: nothing from TOML is compiled or executed as Rust at runtime. Use `locale` for locale-aware generators; optional `min`/`max`, `length`, `format` as documented. Unsupported targets fail at config load. New generators require a **new Dumpling release** (or your own fork), not config-side code. |
 | `phone` | Locale-aware fake phone number (configurable via `locale`); defaults to English format |
 | `int_range` | Random integer in `[min, max]` |
 | `string` | Random alphanumeric string (`length = 12` by default) |
@@ -141,6 +140,12 @@ token = "high"
 | `time_fuzz` | Shifts a time-of-day by a random number of seconds in `[min_seconds, max_seconds]` with 24h wraparound (defaults: `-300..300`) |
 | `datetime_fuzz` | Shifts a timestamp/timestamptz by a random number of seconds in `[min_seconds, max_seconds]` (defaults: `-86400..86400`) |
 
+**`faker` reference (upstream `fake` crate):** Dumpling’s `faker = "module::Type"` strings mirror the Rust [`fake`](https://crates.io/crates/fake) crate’s [`faker`](https://docs.rs/fake/latest/fake/faker/index.html) module layout. Use these when picking or extending generators:
+
+- [docs.rs — `fake` crate root](https://docs.rs/fake/latest/fake/) (overview, `Fake` / `Dummy` traits, locales)
+- [docs.rs — `fake::faker` module index](https://docs.rs/fake/latest/fake/faker/index.html) (per-domain submodules: `address`, `internet`, `name`, …)
+- [GitHub — `cksac/fake-rs`](https://github.com/cksac/fake-rs) (source, README with the CLI’s generator name list)
+
 ### Secret references
 
 Dumpling resolves secret references in string config fields so plaintext salts/keys
@@ -188,7 +193,9 @@ dumpling --security-profile hardened --input dump.sql --check
 - `unique_within_domain`: when true, different source values are assigned unique pseudonyms within the configured `domain`. NULL values are unaffected and always remain NULL.
 - `min_days` / `max_days`: used by `date_fuzz`.
 - `min_seconds` / `max_seconds`: used by `time_fuzz` and `datetime_fuzz`.
-- `locale`: selects the language/regional format for the `name`, `first_name`, `last_name`, and `phone` strategies. Supported values: `en`, `fr_fr`, `de_de`, `it_it`, `pt_br`, `pt_pt`, `ar_sa`, `zh_cn`, `zh_tw`, `ja_jp`, `cy_gb`. Defaults to `en` when not specified.
+- `locale`: selects the language/regional format for the `faker` and `phone` strategies. Supported values: `en`, `fr_fr`, `de_de`, `it_it`, `pt_br`, `pt_pt`, `ar_sa`, `zh_cn`, `zh_tw`, `ja_jp`, `cy_gb`. Defaults to `en` when not specified.
+- `faker`: required when `strategy = "faker"`. A plain string `"module::Type"` (case-insensitive) that maps to a **built-in** generator compiled into Dumpling—not arbitrary Rust or expressions. Names follow [`fake::faker`](https://docs.rs/fake/latest/fake/faker/index.html) (e.g. `internet::SafeEmail` → `faker::internet::SafeEmail` in the crate).
+- `format`: used with `faker = "number::NumberWithFormat"`; pattern uses `#` (0–9) and `^` (1–9) per the [`fake` crate docs](https://docs.rs/fake/latest/fake/).
 
 > **Note:** `table_options` are no longer supported; use explicit `rules` and optional `column_cases`.
 
@@ -261,7 +268,16 @@ Produced by `pg_dump --format=plain`. Handles:
 - `"double-quoted"` identifiers
 - `''`-escaped string literals
 
-Binary, custom, and directory formats from `pg_dump` are not supported — use `--format=plain` when running `pg_dump`.
+Binary, custom, and directory formats from `pg_dump` are not parsed directly — Dumpling’s SQL pipeline expects plain text. Use either:
+
+- **`pg_dump --format=plain`** when you control capture, or
+- **`dumpling --dump-decode`** with `--input` set to a **custom-format** (`.dump`) or **directory-format** folder: Dumpling runs `pg_restore -f -` and streams the resulting SQL (same as a manual `pg_restore` “script” output, no database required). Requires PostgreSQL client tools on `PATH` (`pg_restore`), or set `--pg-restore-path`. Use `--dump-decode-arg` to pass extra flags (e.g. `--no-owner --no-acl`). **By default** the archive is removed after a fully successful run; pass **`--dump-decode-keep-input`** to retain it. **`--check`** requires **`--dump-decode-keep-input`** so the archive still exists if changes would be detected.
+
+Example (e.g. after `heroku pg:backups:download`):
+
+```bash
+dumpling --dump-decode -i latest.dump -c .dumplingconf -o anonymized.sql
+```
 
 ### SQLite (`--format sqlite`)
 
@@ -332,7 +348,7 @@ Define default strategies in `rules."<table>"` and add ordered per-column cases
 ```toml
 [rules."public.users"]
 email = { strategy = "hash", as_string = true }   # default
-name  = { strategy = "name" }
+name  = { strategy = "faker", faker = "name::Name" }
 
 [[column_cases."public.users".email]]
 when.any = [{ column = "is_admin", op = "eq", value = "true" }]
@@ -383,7 +399,7 @@ salt = "${DUMPLING_HMAC_KEY}"
 
 [rules."public.users"]
 ssn = { strategy = "hash", as_string = true }
-email = { strategy = "email", domain = "users" }
+email = { strategy = "faker", faker = "internet::SafeEmail", domain = "users" }
 ```
 
 ```bash
@@ -449,4 +465,4 @@ See the [CI guardrails documentation](docs/src/ci-guardrails.md) for full pipeli
 
 ## Full documentation
 
-Detailed docs, including the configuration reference and release process, are available at the project's [GitHub Pages site](https://github.com) (built from `docs/src/`).
+Detailed docs, including the configuration reference and release process, are available at the project's [GitHub Pages site](https://ababic.github.io/dumpling/) (built from `docs/src/`).

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/docs/src/ci-guardrails.md

@@ -29,7 +29,7 @@ violations to stderr, and exits:
 | `empty-rules-table` | warning | A `[rules]` entry has no column rules. Likely a stale or incomplete config section. |
 | `empty-column-cases-table` | warning | A `[column_cases]` entry has no column cases. |
 | `unsalted-hash` | warning | A `hash` strategy is used with no salt (neither per-column `salt` nor global `salt`). Unsalted hashes are reversible via precomputed lookup tables for low-entropy inputs (names, emails, common IDs). |
-| `inconsistent-domain-strategy` | error | The same domain name is used with two or more different strategies. This breaks referential integrity: a domain shared between `email` and `name` would try to maintain a bidirectional map between incompatible pseudonym types. |
+| `inconsistent-domain-strategy` | error | The same domain name is used with two or more different strategies. This breaks referential integrity: a domain shared between incompatible generators (for example `faker` with different `faker` targets, or `faker` vs `hash`) cannot maintain a single stable mapping. |
 | `uncovered-sensitive-column` | error | A column listed in `[sensitive_columns]` has no matching anonymization rule or case. The column will pass through unmodified, making the sensitive declaration misleading. |
 
 ---

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/docs/src/configuration.md

@@ -6,7 +6,7 @@ Use `--format` to declare the SQL dialect of your input file:
 
 | Value | Description |
 |---|---|
-| `postgres` (default) | PostgreSQL `pg_dump` plain-text format. Supports `COPY … FROM stdin` blocks, `"double-quoted"` identifiers, `''`-escaped strings. |
+| `postgres` (default) | PostgreSQL `pg_dump` plain-text format. Supports `COPY … FROM stdin` blocks, `"double-quoted"` identifiers, `''`-escaped strings. Custom-format (`-Fc`) or directory dumps can be decoded on the fly with `dumpling --dump-decode` (wraps `pg_restore -f -`; requires client tools). By default the archive is deleted after success; use `--dump-decode-keep-input` to retain it. |
 | `sqlite` | SQLite `.dump` format. Adds `INSERT OR REPLACE INTO` / `INSERT OR IGNORE INTO` support. No COPY blocks. |
 | `mssql` | SQL Server / MSSQL plain SQL. Adds `[bracket]` identifier quoting, `N'…'` Unicode string literals, and `nvarchar(n)` / `nchar(n)` length extraction. No COPY blocks. |
 
@@ -17,6 +17,28 @@ dumpling --format sqlite -i data.db.sql -o anonymized.sql
 dumpling --format mssql  -i backup.sql  -o anonymized.sql
 ```
 
+### PostgreSQL custom-format archives (`--dump-decode`)
+
+Heroku PGBackups and many pipelines ship **`pg_dump` custom format** (`-Fc`) or **directory-format** dumps to save bandwidth. Dumpling’s SQL engine still expects **plain text**; use **`--dump-decode`** so Dumpling runs **`pg_restore -f -`** (script to stdout, no database) and pipes the result through the same anonymizer as a normal plain-SQL file.
+
+**Requirements:** PostgreSQL client tools on `PATH` (`pg_restore`), or set **`--pg-restore-path`**. Use **`--dump-decode-arg`** (repeatable) for extra `pg_restore` flags, e.g. `--dump-decode-arg=--no-owner --dump-decode-arg=--no-acl`.
+
+**Input deletion:** After a **fully successful** run, Dumpling **removes** the `--input` path (single file or directory-format folder) by default so only the anonymized output remains. Pass **`--dump-decode-keep-input`** to retain the archive.
+
+**Check mode:** **`--check`** with **`--dump-decode`** requires **`--dump-decode-keep-input`**. Otherwise the default would delete the dump before you can iterate on config.
+
+Example (e.g. after `heroku pg:backups:download`):
+
+```bash
+dumpling --dump-decode -i latest.dump -c .dumplingconf -o anonymized.sql
+```
+
+Dry run while keeping the downloaded file:
+
+```bash
+dumpling --dump-decode --dump-decode-keep-input --check -i latest.dump -c .dumplingconf
+```
+
 ---
 
 ## Configuration sources
@@ -31,6 +53,16 @@ If no configuration is found, Dumpling fails closed by default and exits non-zer
 Error output includes every checked location. If you intentionally want a no-op
 run, pass `--allow-noop`.
 
+## Faker strategy and the `fake` crate
+
+When you use `strategy = "faker"` with `faker = "module::Type"`, those names align with the Rust [**`fake`**](https://crates.io/crates/fake) crate’s [`faker`](https://docs.rs/fake/latest/fake/faker/index.html) modules (for example `name::FirstName` ↔ `fake::faker::name::raw::FirstName`). Use the upstream docs to discover available generators and options:
+
+- [docs.rs — `fake` (crate overview)](https://docs.rs/fake/latest/fake/)
+- [docs.rs — `fake::faker` (all faker submodules)](https://docs.rs/fake/latest/fake/faker/index.html)
+- [GitHub — `cksac/fake-rs` (source + README)](https://github.com/cksac/fake-rs)
+
+Dumpling only exposes a **subset** wired in `src/faker_dispatch.rs`; unsupported `module::Type` pairs fail at config load.
+
 ## Baseline config template
 
 ```toml
@@ -38,7 +70,7 @@ salt = "${DUMPLING_GLOBAL_SALT}"
 
 [rules."public.users"]
 email = { strategy = "hash", salt = "${env:DUMPLING_USERS_EMAIL_SALT}", as_string = true }
-name = { strategy = "name" }
+full_name = { strategy = "faker", faker = "name::Name" }
 
 [sensitive_columns]
 "public.users" = ["employee_number", "tax_id"]
@@ -184,6 +216,15 @@ Nested JSON targeting is supported in predicate `column` values via either:
 When a JSON path traverses an array, Dumpling checks each element (useful for
 list-of-dicts JSON structures).
 
+### JSON path rules (`json` / `jsonb` columns)
+
+You can anonymise values **inside** a text column that holds JSON using the same path syntax as row-filter predicates, but on **`[rules]` keys**:
+
+- Dot notation: `"payload.profile.email" = { strategy = "email", domain = "orders_email", as_string = true }`
+- Django-style: `"payload__profile__email" = { strategy = "hash", salt = "${env:ORDER_SECRET_SALT}", as_string = true }`
+
+The part before the first dot or `__` is the **SQL column name**; the rest is the path inside the parsed JSON document. Use **quoted** keys in TOML when the name contains dots. For a given table, you can use **either** path-level rules for a column **or** one whole-column rule for that column’s base name, not both (Dumpling rejects the conflict at startup). If a path is missing in a given row, that rule is skipped for that row. When only path rules apply (no whole-column rule), the rest of the JSON is left unchanged. Path rules are applied in **longest-path-first** order. `column_cases` still match the SQL column name only; use `when` predicates with nested `column` paths to branch on JSON content.
+
 ## Safety recommendations
 
 - Prefer deterministic runs in CI by passing `--seed` (or `DUMPLING_SEED`).
@@ -202,7 +243,7 @@ list-of-dicts JSON structures).
 - Sensitive columns are detected by:
   1. built-in column-name patterns, and
   2. explicit per-table lists under `[sensitive_columns]`.
-- A sensitive column is considered covered only if it has an explicit `rules` or `column_cases` entry.
+- A sensitive column is considered covered only if it has an explicit `rules` or `column_cases` entry (including JSON path rules whose base name is that column, e.g. `payload.x.y` covers `payload`).
 - If uncovered sensitive columns are found, Dumpling exits non-zero.
 
 When `--report` is enabled, coverage fields are added to JSON output:

dumpling_cli-0.4.0/docs/src/getting-started.md

@@ -0,0 +1,33 @@
+# Getting started
+
+## Prerequisites
+
+- Rust **stable** toolchain (`rustup` recommended). The repo includes `rust-toolchain.toml` (stable + `rustfmt` + `clippy`) so CI and local `cargo` stay aligned.
+- `cargo` on your `PATH`
+
+Optional: run **`./scripts/setup-dev.sh`** once from the repo root — it installs toolchain components, **`cargo fetch`**, and a pinned **mdBook** under `.tools/` for the same docs build CI uses.
+
+## Build
+
+```bash
+cargo build --release
+./target/release/dumpling --help
+```
+
+## Test locally
+
+```bash
+cargo fmt --all -- --check
+cargo clippy --all-targets --all-features
+cargo test --all-targets --all-features
+```
+
+## Run against a dump
+
+```bash
+dumpling -i dump.sql -o sanitized.sql
+```
+
+If your input is a PostgreSQL **custom-format** file (not plain SQL), decode and anonymize in one step with **`--dump-decode`** (needs `pg_restore` from PostgreSQL client tools). See [PostgreSQL custom-format archives](configuration.md#postgresql-custom-format-archives---dump-decode) in the configuration guide.
+
+For full command examples and strategy options, see the repository `README.md`.

dumpling_cli-0.4.0/docs/src/index.md

@@ -0,0 +1,19 @@
+# Dumpling documentation
+
+Dumpling is a streaming anonymizer for plain SQL dumps. It supports PostgreSQL (`pg_dump` plain format), SQLite (`.dump`), and SQL Server / MSSQL (SSMS / mssql-scripter plain SQL output). For PostgreSQL **custom-format** archives (e.g. Heroku `pg:backups:download`), use **`--dump-decode`** so Dumpling invokes `pg_restore` and streams plain SQL—see [Dump format](configuration.html#postgresql-custom-format-archives---dump-decode) in the configuration guide.
+
+This documentation covers the operating model for day-to-day use:
+
+- how to build and run Dumpling locally,
+- how to configure transformation behavior safely,
+- how CI validates quality before changes merge,
+- and how maintainers produce tagged releases.
+
+## Documentation quality gate
+
+The mdBook site is built in CI as follows:
+
+- **Pull requests:** the **Docs (PR)** workflow runs `mdbook build` when docs-related paths change (no deploy).
+- **`main`:** the **Docs** workflow builds and deploys to GitHub Pages when docs-related paths change.
+
+This keeps the docs in a continuously deployable state instead of drifting from the codebase.

{dumpling_cli-0.2.0 → dumpling_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "dumpling-cli"
-version = "0.2.0"
+version = "0.4.0"
 description = "Static anonymizer for plain SQL dumps (PostgreSQL, SQLite, SQL Server)."
 readme = "README.md"
 requires-python = ">=3.8"

dumpling_cli-0.4.0/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "stable"
+components = ["rustfmt", "clippy"]