feat!: v0.2.0 — reshape ParseIssue and strengthen ParseResult types

[roottool]

Description

Implements all breaking changes planned for v0.2.0, focused on making ParseIssue and ParseResult more precise and honest.

• Remove ParseIssue.path (was always readonly [] — carried no information)
• Add ParseIssue.key: string (required, identifies the offending FormData key)
• Narrow ParseResult failure issues to a non-empty tuple [ParseIssue, ...ParseIssue[]]
• Export SuccessResult and FailureResult named utility types
• Update all documentation, examples, and skill references to match

Type of Change

• Refactoring (non-breaking change improving code structure)
• Bugfix (non-breaking change fixing an issue)
• Security fix (non-breaking change addressing a security issue)
• Documentation (changes to documentation only)
• Tests (adding or updating tests)
• Tooling / CI (changes to build tools, CI configuration)

Note: Despite the "refactoring" checkbox, this PR contains breaking changes to the public API under the v0.x versioning policy (minor bump = effective major).

Boundary Checklist (Required for Implementation Changes)

• No interpretation
  • Key names are treated as opaque strings
  • No structural inference ([], ., brackets, paths, etc.)
• No silent behavior
  • No merging, overwriting, autofixing, or implicit resolution
  • All boundary violations are reported explicitly
• Boundary respected
  • No validation, coercion, schema, framework conventions, or business logic

📘 Boundary rules & non-goals:
https://github.com/roottool/safe-formdata/blob/main/AGENTS.md

Security & API Stability

Security Impact

• No impact on security (no changes to forbidden keys, prototype safety)
• Reviewed against security rules in AGENTS.md

API Contract

• No changes to public API (parse function signature, type definitions)
• If API change: Is this a breaking change? Yes — see migration guide below and CHANGELOG.md

Breaking changes:

1. ParseIssue.path removed — callers referencing issue.path must delete those references
2. ParseIssue.key: string added (required) — type definitions referencing ParseIssue must be updated
3. issues: [ParseIssue, ...ParseIssue[]] on failure — explicit type annotations may need updating

Versioning

• Change is compatible with current v0.x versioning policy
• If breaking change proposed: Justification for major version bump
  • Under the 0.x policy, this minor bump is treated as an effective major. Breaking changes are documented in CHANGELOG.md.

Testing

Automated Checks

• TypeScript type checking passes (bun run check:type:source)
• All tests pass (bun run test)
• Build succeeds (bun run build)

Additional Verification

• Existing tests updated to assert issue.key (removed issue.path assertions)
• boundary-validator skill run against all changes; findings resolved

Automated Review (Optional)

boundary-validator was run as part of this PR. All findings were resolved:

• Added explicit ParseIssue[] type annotation to issues array in parse.ts
• Added comment explaining the destructuring pattern used to avoid type assertion
• Fixed JSDoc example: if (result.data) → if (result.data !== null)
• Fixed invalid_key description: "unsafe characters" → "empty or not a string"

---

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (07dffcc) to head (4a201ca).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main       #59   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines           22        23    +1     
  Branches         6         5    -1     
=========================================
+ Hits            22        23    +1     

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.