This repository was archived by the owner on Mar 9, 2026. It is now read-only.
docs: improve documentation with JSDoc and reorganized README for v0.1.3#44
Merged
docs: improve documentation with JSDoc and reorganized README for v0.1.3#44
Conversation
Add detailed JSDoc comments to all TypeScript type definitions for better IDE integration and developer experience. Changes: - src/types/IssueCode.ts: Add security rationale for each issue code with practical examples - src/types/ParseIssue.ts: Add property-level explanations and usage examples - src/types/ParseResult.ts: Add discriminated union documentation with type narrowing patterns Benefits: - Improved IDE autocomplete with inline documentation - Better hover tooltips showing security implications - Clear examples of type narrowing with 'data !== null' - Reduced need to context-switch to external documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Reorganize README.md with "philosophy-first" approach: - Add Table of Contents for easier navigation - Add Installation section (npm, yarn, pnpm, bun) - Add Quick Start section with minimal working example - Reorganize sections: Overview → Design principles → Security scope → Design decisions → Installation → Quick Start → API This new structure ensures users understand the boundary-focused philosophy before writing code, reducing potential misuse. Update AGENTS.md (implementation guide): - Update API contract section with accurate discriminated union types - Add type narrowing pattern documentation (data !== null) - Add references to JSDoc in type definition files Update CLAUDE.md (Claude Code guidance): - Add README's philosophy-first structure explanation - Add new "Type Safety and IDE Integration" section - Document type narrowing patterns and common mistakes - Clarify that .ok property does not exist (use data !== null) Benefits: - Better onboarding: new users can start in 5 minutes - Reduced misuse: philosophy explained before API usage - Accurate technical docs: matches actual implementation - Improved Claude Code assistance: clear guidance on type safety 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #44 +/- ##
=========================================
Coverage 100.00% 100.00%
=========================================
Files 3 3
Lines 22 22
Branches 6 6
=========================================
Hits 22 22 🚀 New features to boost your workflow:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
This PR improves the documentation for v0.1.3 release with comprehensive JSDoc comments and a reorganized README structure. The changes focus on better onboarding experience, IDE integration, and clearer communication of the boundary-focused philosophy.
Changes:
Benefits:
data !== null)Boundary Checklist (Required)
This PR is documentation-only and does not modify the parser implementation or API. The boundary checklist applies to implementation changes, not documentation improvements.
Type of Change
Testing
Documentation verification:
bun run check:type:source)bun run test)bun run check:type:example)bun run build)Manual verification:
🤖 Generated with Claude Code
Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com