docs(validation): api docs & minor fixes

[dreamorosi]

Summary

Changes

Please provide a summary of what's being changed

This PR adds docstrings to all the types/functions/parameters/errors for the upcoming Validation utility and enables Typedoc for the package.

While documenting the code I noticed a few inconsistencies or redundant code paths, which are refactored in this PR along with their respective tests. I also added the build command and removed the private marker from the package.json file, since we're gonna start publishing in the next release.

Please add the issue number below, if no issue is present the PR might get blocked and not be reviewed

Issue number: closes #3712

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[Copilot]

Pull Request Overview

This PR enhances the Validation utility by adding comprehensive documentation, refactoring error handling, updating middleware/decorator logic, and aligning tests with these changes.

• Added detailed jsdoc comments and API docs in the README
• Refactored error handling and validation logic for consistency
• Updated tests and type definitions to support upcoming publishing

Reviewed Changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/validation/README.md	Expanded API docs and added a new "Features" section for better usability
packages/validation/src/utils.ts	Added documentation for error cause extraction
packages/validation/src/errors.ts	Introduced jsdoc comments and restructured error classes for clarity
packages/validation/tests/unit/middleware.test.ts	Updated middleware tests and renamed imports for consistency
packages/validation/src/decorator.ts	Added detailed jsdoc comments and refined error handling in the decorator
packages/validation/src/types.ts	Updated types for validation parameters and external references
packages/validation/src/middleware.ts	Replaced the earlier middleware with a polished validator function and improved error messages
packages/validation/src/validate.ts	Enhanced schema compilation error handling and updated externalRefs processing
vitest.config.ts	Adjusted file exclusion patterns for improved test coverage
packages/validation/tests/unit/decorator.test.ts	Updated tests to reflect the new decorator behavior and naming
packages/validation/tests/unit/validate.test.ts	Modified tests for custom formats and error types during schema compilation
README.md	Updated badges and added usage instructions for the Validation utility
packages/validation/src/index.ts & tests/unit/index.test.ts	Removed re‑exports to match the new package organization

Comments suppressed due to low confidence (3)

packages/validation/src/decorator.ts:170

• For consistency with the middleware and test expectations, consider updating the error message to 'Inbound schema validation failed'.

throw new SchemaValidationError('Inbound validation failed', {

packages/validation/src/validate.ts:132

• Ensure that the use of addSchema correctly handles both single schema objects and arrays of schemas, as expected by Ajv.

ajvInstance.addSchema(externalRefs);

packages/validation/src/index.ts:1

• Confirm that the removal of exports from this file is intentional and that any necessary documentation or package structure updates have been made.

/* exports removed */

[am29d]

Looks good, just need to clarify accidental comment.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud