feat: array-length array-min-length incorporate union types

[hughgrigg]

Summary by CodeRabbit

• Bug Fixes
  • Improved type narrowing for array-length assertions and matchers when a value can be either an object or an array.
  • Better handling of readonly arrays in length-based checks, producing more accurate inferred types.
  • Added coverage for union-typed properties to verify correct narrowing and runtime behavior.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR updates assertArrayLength and assertArrayMinLength overloads to accept TActual extends object | null | undefined instead of requiring array-typed generics, narrowing via Extract<NonNullable<TActual>, readonly unknown[]>. Corresponding *.type.ts files introduce ArrayBranchOf/ArrayMatchElement/ArrayMatchBranch helpers and apply readonly-array detection to the extracted branch. New tests validate narrowing of union-typed fields.

Changes

Array assertion type-narrowing widening

Layer / File(s)	Summary
assertArrayLength overload and matcher types src/assert/array-length/array-length.assert.ts, src/assert/array-length/array-length.type.ts, src/assert/array-length/array-length.test.ts	Widens the assertArrayLength generic to object | null | undefined, narrows via Extract<NonNullable<TActual>, readonly unknown[]>, introduces ArrayBranchOf/ArrayMatchElement/ArrayMatchBranch helpers and applies IsKnownReadonlyArray to the extracted branch; adds tests narrowing a union Statement field via both assertArrayLength and the arrayOfLength matcher.
assertArrayMinLength overload and matcher types src/assert/array-min-length/array-min-length.assert.ts, src/assert/array-min-length/array-min-length.type.ts, src/assert/array-min-length/array-min-length.test.ts	Applies the same generic widening and branch-extraction pattern to assertArrayMinLength, introduces equivalent helper types, and adds tests narrowing a union Statement field via both assertArrayMinLength and the arrayOfMinLength matcher.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• KensioSoftware/smartass#39: Both PRs change the TypeScript overload/type-narrowing logic for the same array assertion APIs and their related matcher/type helpers.
• KensioSoftware/smartass#40: Both PRs modify the same array-length.type.ts and array-min-length.type.ts refinement machinery for readonly-branch handling.
• KensioSoftware/smartass#52: Both PRs update the same assertions and matcher types to preserve readonly/mutability via Extract<NonNullable<...>, readonly unknown[]>.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the PR’s main change: improving array-length and array-min-length handling for union types.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/hg/array-length-union-types

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (2)

src/assert/array-length/array-length.test.ts (1)

314-350: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider extracting shared test interfaces.

The PolicyStatement and PolicyDocument interfaces are defined identically in four test blocks across array-length.test.ts and array-min-length.test.ts. Extracting them to a shared test fixture would reduce duplication and make it easier to update the test shapes consistently.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/assert/array-length/array-length.test.ts` around lines 314 - 350, The
test blocks in array-length.test.ts and array-min-length.test.ts repeat the same
PolicyStatement and PolicyDocument interface definitions, so extract those
shared types into a common test fixture and reuse them in the affected tests.
Update the relevant assertions around assertObjectMatches and
arrayOfLength/arrayMinLength to import or reference the shared interfaces,
keeping the existing type-narrowing checks unchanged while removing the
duplicated local declarations.

src/assert/array-length/array-length.type.ts (1)

15-23: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider extracting shared array-branch helpers.

ArrayBranchOf, ArrayMatchElement, and ArrayMatchBranch are identical in array-length.type.ts and array-min-length.type.ts. Duplicating these type utilities risks divergence over time. Consider extracting them to a shared module (e.g., src/assert/array-branch.type.ts) and importing from both.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/assert/array-length/array-length.type.ts` around lines 15 - 23, Extract
the shared array-branch type helpers used by ArrayBranchOf, ArrayMatchElement,
and ArrayMatchBranch into a single reusable module so array-length.type.ts and
array-min-length.type.ts both import the same definitions. Keep the existing
type names and behavior intact, but move the duplicated utility types into a
shared file (such as a common array-branch type module) and update both
assertion type files to reference that shared source.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/assert/array-length/array-length.test.ts`:
- Around line 314-350: The test blocks in array-length.test.ts and
array-min-length.test.ts repeat the same PolicyStatement and PolicyDocument
interface definitions, so extract those shared types into a common test fixture
and reuse them in the affected tests. Update the relevant assertions around
assertObjectMatches and arrayOfLength/arrayMinLength to import or reference the
shared interfaces, keeping the existing type-narrowing checks unchanged while
removing the duplicated local declarations.

In `@src/assert/array-length/array-length.type.ts`:
- Around line 15-23: Extract the shared array-branch type helpers used by
ArrayBranchOf, ArrayMatchElement, and ArrayMatchBranch into a single reusable
module so array-length.type.ts and array-min-length.type.ts both import the same
definitions. Keep the existing type names and behavior intact, but move the
duplicated utility types into a shared file (such as a common array-branch type
module) and update both assertion type files to reference that shared source.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9f6d9fad-c6cd-4cec-ae11-39703286ec5c

📥 Commits

Reviewing files that changed from the base of the PR and between b6fcd63 and 7e475aa.

📒 Files selected for processing (6)

• src/assert/array-length/array-length.assert.ts
• src/assert/array-length/array-length.test.ts
• src/assert/array-length/array-length.type.ts
• src/assert/array-min-length/array-min-length.assert.ts
• src/assert/array-min-length/array-min-length.test.ts
• src/assert/array-min-length/array-min-length.type.ts