Update strict mode documentation with trade-offs and usage guidance

[Harikishanth]

Description

Document the trade-offs, risks, and appropriate use cases for the strict: false option in TypeValidationOptions. Addresses the lack of clarity around when disabling strict mode is appropriate and what breaks when you do.

Fixes #38

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (code improvements without changing functionality)
• Other (please specify):

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have checked my code for security vulnerabilities
• Any dependent changes have been merged and published in downstream modules

Screenshots (if applicable)

N/A — documentation only change.

How Has This Been Tested?

This is a documentation-only change. No runtime behaviour is modified.

• pnpm lint passes locally
• pnpm test passes locally — all 332+ existing tests still pass

Test Configuration:

• OS: Windows 11
• Node.js version: 18+
• Other dependencies: pnpm, TypeScript 5.9

Related Documentation

• Issue: [DOC] Type validation can be bypassed with strict: false - trade-offs unclear #38
• Style reference: existing JSDoc in src/abstracts/AbstractCollection.ts

Additional Notes

Three files updated:

• src/abstracts/AbstractCollection.ts — expanded JSDoc on the strict option with warnings, appropriate use cases, what breaks, and performance notes
• ARCHITECTURE.md — added "Type Validation Trade-offs" section covering default behaviour, when strict: false is appropriate, what breaks, and performance considerations
• CONTRIBUTING.md — added explicit guidance discouraging strict: false in test suites unless testing that specific behaviour

Summary by CodeRabbit

• Documentation
  • Enhanced architectural documentation with detailed guidance on type validation options and their performance implications.
  • Updated contributor testing standards with type-safety best practices.
  • Clarified inline documentation explaining runtime validation behavior, trade-offs, and appropriate use cases.

[coderabbitai]

Warning

Rate limit exceeded

@Harikishanth has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 54 minutes and 42 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 0ff80d26-29de-4ef6-8d29-9a1ea52bfdc6

📥 Commits

Reviewing files that changed from the base of the PR and between 12f77f5 and c6c029a.

📒 Files selected for processing (1)

• src/abstracts/AbstractCollection.ts

📝 Walkthrough

Walkthrough

This PR documents the type validation trade-offs and use cases for the strict: false option across three documentation layers: the source code JSDoc, the architecture guide, and the testing standards. No runtime logic or type signatures were modified.

Changes

Type Validation Trade-offs Documentation

Layer / File(s)	Summary
Type validation JSDoc in collection constructor src/abstracts/AbstractCollection.ts	The TypeValidationOptions.strict documentation is expanded with a detailed warning about mixed-type acceptance, explicit use cases (legacy code, untyped data, performance-critical paths), safety implications (silent corruption, delayed errors), performance overhead notes, and extended code examples.
Architecture guide and testing standards ARCHITECTURE.md, CONTRIBUTING.md	A new "Type Validation Trade-offs: strict Mode" section in ARCHITECTURE.md documents default behavior, consequences of disabling checks, recommended scenarios, common failure modes, and performance impact. CONTRIBUTING.md adds a testing guideline warning against strict: false in general test suites, with examples showing when it is and is not appropriate.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 Documentation blooms, a safety net unfurled,
Warnings guard the path where strict becomes a pearl,
From JSDoc to guide, the trade-offs gently told—
Type safety's escape hatch now crystal-clear and bold! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Linked Issues check	✅ Passed	The PR comprehensively addresses all coding requirements from issue #38: JSDoc warnings on strict option [ARCHITECTURE.md, CONTRIBUTING.md, AbstractCollection.ts], use-case guidance [ARCHITECTURE.md], documentation of what breaks [all files], and performance notes [ARCHITECTURE.md].
Out of Scope Changes check	✅ Passed	All changes are strictly documentation-related and directly address issue #38 requirements; no unrelated code changes, runtime logic modifications, or out-of-scope additions detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title directly and accurately summarizes the main change: documentation updates to clarify strict mode trade-offs and usage guidance across multiple files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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 and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 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.

Inline comments:
In `@src/abstracts/AbstractCollection.ts`:
- Line 63: Update the example comment in AbstractCollection to actually
demonstrate the mixed-type runtime failure: change the illustrative expression
from using list.get(0) * 2 to list.get(1) * 2 so it accesses the string element
(added earlier) and produces NaN; ensure the text around the example still says
"May produce unexpected results at runtime" and references list.get to keep
context consistent.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 16979f7d-280f-47d5-8b50-9ac119ef6adb

📥 Commits

Reviewing files that changed from the base of the PR and between 4eb1506 and 12f77f5.

📒 Files selected for processing (3)

• ARCHITECTURE.md
• CONTRIBUTING.md
• src/abstracts/AbstractCollection.ts