field-redactor 1.5.0 → 1.6.0

package/docs/guides/migration-1.5-to-1.6.md

@@ -0,0 +1,56 @@
+# Migration: npm 1.5.x → 1.6.0
+
+**1.6.0** is a minor release: new features and aliases with no required config changes for typical upgrades from **1.5.0**.
+
+## Install
+
+```bash
+npm install field-redactor@1.6.0
+# or
+yarn add field-redactor@1.6.0
+```
+
+## What you can adopt (optional)
+
+### Path rules and pass keys
+
+```typescript
+FieldRedactor.createSafe({
+  pathRules: [{ path: 'metadata.*.value', mode: 'shallow' }],
+  passKeys: [/^id$/]
+});
+```
+
+See [Path rules & allowlists](path-rules.md).
+
+### Preferred Opaque / Remove names
+
+| Prefer | Legacy (still works) |
+| --- | --- |
+| `opaqueSecretKeys` | `fullSecretKeys` |
+| `removeSecretKeys` | `deleteSecretKeys` |
+| `CustomObjectMatchType.Opaque` | `CustomObjectMatchType.Full` |
+| `CustomObjectMatchType.Remove` | `CustomObjectMatchType.Delete` |
+
+Builder methods `.opaque()` / `.remove()` were already the preferred labels in 1.5.0.
+
+## Behavior-sensitive notes
+
+### Package `exports`
+
+Only the package root is exported. If you imported internal files (for example `field-redactor/dist/objectRedactor`), switch to the public API from `field-redactor`.
+
+### Deep imports of moved modules
+
+Source files were reorganized under `api/`, `engine/`, `rules/`, etc. That affects only consumers who imported unpublished internal paths—not `import { FieldRedactor } from 'field-redactor'`.
+
+## No action required
+
+- Existing `secretKeys` / `deepSecretKeys` / `fullSecretKeys` / `deleteSecretKeys` configs
+- `createSafe()`, builder, presets, `dryRun` / `dryRunSync`
+- Copy-on-write and sync APIs from 1.5.0
+
+## Links
+
+- [Release notes v1.6.0](../release-notes/v1.6.0.md)
+- [CHANGELOG](../../CHANGELOG.md)

package/docs/guides/path-rules.md

@@ -0,0 +1,47 @@
+# Path rules and allowlists
+
+Use **path rules** when sensitivity lives at a stable JSON location rather than a reusable key name. Use **passKeys** (or a `pass` path rule) to keep specific fields visible inside a deep-redacted subtree.
+
+## Path rules
+
+Path patterns use `.` between object keys, `[index]` for array positions, and `*` as a single-segment wildcard.
+
+```typescript
+import { FieldRedactorConfigBuilder } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .pathRule('metadata.*.value', 'shallow')
+  .pathRule('session.token', 'remove')
+  .buildSafeRedactor();
+```
+
+| Mode | Effect at matched path |
+| --- | --- |
+| `shallow` | Redact scalar values (or recurse into objects/arrays) |
+| `deep` | Redact all descendant primitives |
+| `opaque` | Stringify and redact the value |
+| `remove` | Delete the field |
+| `pass` | Leave the field and subtree unchanged |
+
+Path rules take precedence over key-regex rules but not over schema (`customObjects`) matches.
+
+## Allowlist keys (`passKeys`)
+
+When a parent is deep-redacted, matching key names are preserved:
+
+```typescript
+FieldRedactor.createSafe({
+  deepSecretKeys: [/accountInfo/],
+  passKeys: [/^id$/, /^externalId$/]
+});
+```
+
+Equivalent path-rule form for a single field:
+
+```typescript
+.pathRule('accountInfo.id', 'pass')
+```
+
+## dryRun attribution
+
+`report.pathRules` includes path-based matches with `pattern` set to the configured path expression (for example `metadata.*.value`).

package/docs/reference/config.md

@@ -12,6 +12,8 @@
 | **Remove** | `deleteSecretKeys` | `RegExp[]` | `[]` | Delete matching keys |
 | **Schema** | `customObjects` | `CustomObject[]` | `[]` | Per-shape rules; see [metadata guide](../guides/metadata-redaction.md) |
 | **Value-pattern** | `valuePatterns` | `RegExp[]` | `[]` | Opt-in: redact scalars whose string form matches a pattern |
+| **Path rule** | `pathRules` | `PathRule[]` | `[]` | Apply a mode at a JSON path (`metadata.*.value`) |
+| **Allowlist** | `passKeys` | `RegExp[]` | `[]` | Never redact matching key names under deep parents |
 | — | `schemaNames` | `string[]` | — | Optional labels parallel to `customObjects` for `dryRun` reports |
 | — | `ignoreBooleans` | `boolean` | `false` | Skip boolean redaction when `true` |
 | — | `ignoreNullOrUndefined` | `boolean` | `true` | Skip null/undefined redaction when `true` |
@@ -54,7 +56,9 @@ const redactor = FieldRedactorConfigBuilder.create()
   .buildSafeRedactor();
 ```
 
-Methods: `shallow`, `deep`, `opaque`, `remove` / `delete`, `schema`, `valuePattern`, `usePreset`, `redactor`, `syncRedactor`, `ignoreBooleans`, `ignoreNullOrUndefined`, `cloneInput`, `strict`, `onConfigWarning`, `build`, `buildRedactor`, `buildSafeRedactor`.
+Methods: `shallow`, `deep`, `opaque`, `remove` / `delete`, `schema`, `valuePattern`, `pathRule`, `passKey`, `usePreset`, `redactor`, `syncRedactor`, `ignoreBooleans`, `ignoreNullOrUndefined`, `cloneInput`, `strict`, `onConfigWarning`, `build`, `buildRedactor`, `buildSafeRedactor`.
+
+**Precedence:** Schema → path rule → opaque → deep → remove → shallow → value-pattern → default.
 
 ## Configuration validation
 

package/docs/release-notes/README.md

@@ -4,6 +4,7 @@ Per-version release notes for published **field-redactor** git tags. npm release
 
 | Version | npm | Notes |
 | --- | --- | --- |
+| **v1.6.0** | Yes | [v1.6.0.md](v1.6.0.md) — path rules, passKeys, naming aliases, architecture |
 | **v1.5.0** | Yes | [v1.5.0.md](v1.5.0.md) — DX polish, value patterns, unified traversal |
 | v1.3.0 | No (superseded by 1.5.0) | [v1.3.0.md](v1.3.0.md) — sync API, COW, builder, dryRun, presets |
 | v1.2.2 | No | [v1.2.2.md](v1.2.2.md) |
@@ -14,7 +15,8 @@ Per-version release notes for published **field-redactor** git tags. npm release
 
 ## Migration
 
-- [1.2.x → 1.5.0](../guides/migration-1.2-to-1.5.md) — recommended upgrade path from the previous npm line.
+- [1.5.x → 1.6.0](../guides/migration-1.5-to-1.6.md) — path rules, naming aliases, package exports
+- [1.2.x → 1.5.0](../guides/migration-1.2-to-1.5.md) — upgrade path from the previous npm line
 
 ## Internal milestones (removed)
 

package/docs/release-notes/v1.6.0.md

@@ -0,0 +1,59 @@
+# Release notes — v1.6.0
+
+Field Redactor **1.6.0** adds path-based rules and pass-key allowlists, preferred Opaque/Remove naming aliases, and a large internal architecture cleanup. The public root API remains backward compatible with **1.5.0**.
+
+**Upgrade from 1.5.0:** Additive for normal `import { … } from 'field-redactor'` consumers. See [Migration: 1.5 → 1.6](../guides/migration-1.5-to-1.6.md) if you deep-imported `dist/` paths or want the new vocabulary.
+
+## Highlights
+
+| Area | What’s new |
+| --- | --- |
+| **Path rules** | `pathRules` / `.pathRule()` — redact by JSON path (`metadata.*.value`) with modes shallow, deep, opaque, remove, pass |
+| **Pass keys** | `passKeys` / `.passKey()` — exempt key names under deep parents |
+| **Naming** | Preferred `opaqueSecretKeys` / `removeSecretKeys` and `CustomObjectMatchType.Opaque` / `Remove` (legacy names still work) |
+| **Architecture** | Shared `RuleResolver`, layered `src/` packages, unified MaybeAsync traversal |
+
+## Path rules and pass keys
+
+```typescript
+import { FieldRedactorConfigBuilder } from 'field-redactor';
+
+const redactor = FieldRedactorConfigBuilder.create()
+  .pathRule('metadata.*.value', 'shallow')
+  .pathRule('session.token', 'remove')
+  .deep(/accountInfo/)
+  .passKey(/^id$/, /^profile$/)
+  .buildSafeRedactor();
+```
+
+**Precedence:** schema → path rule → opaque/deep/remove/shallow key rules → value pattern → default.
+
+## Naming aliases
+
+```typescript
+// Preferred
+{ opaqueSecretKeys: [/payload/], removeSecretKeys: [/authKey/] }
+
+// Still supported
+{ fullSecretKeys: [/payload/], deleteSecretKeys: [/authKey/] }
+
+CustomObjectMatchType.Opaque; // same value as Full
+CustomObjectMatchType.Remove; // same value as Delete
+```
+
+## Package boundary
+
+`package.json` `"exports"` now exposes only the package root (`.`). Deep imports such as `field-redactor/dist/...` are unsupported.
+
+## Internal (no intended API change)
+
+- `RuleResolver` is the single source of truth for traversal and dry-run attribution
+- Source layout: `api/`, `engine/`, `rules/`, `dryrun/`, `config/`, `util/`
+- Removed internal `ObjectRedactorSyncTraversal` alias (never part of the public export surface)
+- Contributor guide: [CONTRIBUTING.md](../../CONTRIBUTING.md)
+
+## Links
+
+- [CHANGELOG](../../CHANGELOG.md)
+- [Path rules guide](../guides/path-rules.md)
+- [Migration 1.5 → 1.6](../guides/migration-1.5-to-1.6.md)

package/jest.config.js

@@ -8,7 +8,9 @@ module.exports = {
   coverageDirectory: './tmp/jest-coverage',
   coveragePathIgnorePatterns: [
     './node_modules/',
-    './tests/mocks/'
+    './tests/mocks/',
+    './tests/helpers/',
+    './tests/integration/fixtures/'
   ],
   collectCoverage: true,
   coverageThreshold: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "field-redactor",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Utility for redacting PII from complex JSON objects for which simpler redaction tools are insufficient.",
   "author": {
     "name": "Andrew Molony",
@@ -47,5 +47,11 @@
     "trailingComma": "none",
     "printWidth": 120
   },
-  "prepublishOnly": "yarn build"
+  "prepublishOnly": "yarn build",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
 }