Selective Path Coercion (100% Public API Coercion implementation)#579
Selective Path Coercion (100% Public API Coercion implementation)#579
Conversation
…chema definitions and refinements, and refine various type and regex functionalities.
… handling and new unit tests.
…ort` to use `parsedNumber`, and integrate `port` into the ArkType scope.
…, and enhance `number` and `boolean` coercion in `arkenv`.
…ransformation, supporting numeric refinements.
…ding numeric and boolean values.
…and boolean type coercion and add new playground debug files.
…oerce` utility and remove playground files.
…ve boolean from the root scope.
…t coercion from their definitions and from the `type` export, relying on global coercion instead.
…bers, booleans, ranges, and optional properties.
…lity to improve type inference
…m-lock.yaml to streamline the project
…oolean nodes, improving internal handling and type inference
… and boolean types, enhancing type handling
… boolean types, ensuring correct application order and type handling
…numeric and boolean types, adding warnings for reliance on undocumented ArkType APIs
…e type assertions in the `coerce` function.
…internal type and removing `any` casts.
… `coerce` utility.
…pe union coercion.
…d introduce a PoC for generic path-based coercion.
…schema introspection and data-level coercion, removing reliance on internal APIs and updating documentation.
…ted playground files.
…arsing keywords and internal ArkType API usage, and simplifying the `port` keyword.
…amples workflow - Removed the `id-token: write` permission from the `sync-examples.yml` workflow to streamline permissions and enhance security.
…th improved type annotations, null checks, and compatibility fixes.
🦋 Changeset detectedLatest commit: 3a322bc The changes in this PR will be included in the next version bump. This PR includes changesets to release 6 packages
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
bot
added
docs
yamcodes
changed the title
commit: |
📦 Bundle Size Report
✅ All size limits passed! |
WalkthroughRefactors the environment variable coercion system to use ArkType's public introspection API ( Changes
Sequence DiagramsequenceDiagram
participant app as App Code
participant createEnv as createEnv()
participant coerce as coerce()
participant introspection as schema.in.json
participant coercionMap as CoercionMap
participant applier as applyCoercion()
participant pipe as type().pipe()
participant validator as ArkType Validator
app->>createEnv: createEnv({ schema, env })
createEnv->>coerce: coerce(schema)
rect rgb(240, 248, 255)
note over coerce,introspection: Introspection Phase (One-time)
coerce->>introspection: schema.in.json
introspection-->>coerce: JSON representation
coerce->>coerce: findCoercionPaths()
note over coerce: Traverse JSON, find numeric<br/>& boolean leaf nodes
coerce->>coercionMap: Collect target paths
end
alt Coercion paths found
coerce->>pipe: type('unknown').pipe(...)
pipe->>applier: Register coercion handler
rect rgb(255, 250, 240)
note over applier,validator: Data Flow (Runtime)
app->>pipe: validate(env)
pipe->>applier: applyCoercion(data)
applier->>applier: Clone data, traverse<br/>paths via CoercionMap
applier->>applier: Parse strings to<br/>numbers/booleans
applier-->>pipe: Coerced data
end
pipe->>validator: pipe(schema)
validator-->>pipe: Validation result
else No coercion needed
coerce-->>createEnv: Return schema unchanged
end
pipe-->>createEnv: Result
createEnv-->>app: env object
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
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. Comment |
…ng via JSON Schema and add test output logs.
…te coercion public API proposal.
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (3)
.changeset/humble-lizards-judge.md (1)
1-9: Consider adding migration guidance.The breaking changes are clearly documented. However, users migrating from the old
booleankeyword orportmorph may benefit from explicit migration examples showing:
- How to replace removed
booleankeyword usage- How to handle the
portkeyword change (if users were relying on string input)📝 Suggested addition for migration guidance
* **BREAKING**: The `boolean` keyword has been removed. Universal boolean coercion is now handled by the `arkenv` package. * **BREAKING**: The `port` keyword has been changed from a `string -> number` morph to a pure `number` refinement. Numeric coercion is now handled centrally. * Added `maybeParsedNumber` and `maybeParsedBoolean` internal morphs to support central coercion. + +**Migration:** +- If using `boolean` keyword directly, use `"boolean"` in your arkenv schema instead. +- If using `port` keyword with string inputs, these will now be automatically coerced by arkenv before validation.packages/arkenv/src/utils/coerce.test.ts (1)
59-66: Consider adding a test for root-level boolean coercion.The root-level primitive test only covers numeric coercion. For completeness, consider adding a test case for root-level boolean schemas.
🔎 Suggested additional test case
it("should work with root-level boolean primitives", () => { const schema = type("boolean"); const coercedSchema = coerce(schema); expect(coercedSchema("true")).toBe(true); expect(coercedSchema("false")).toBe(false); });openspec/changes/archive/2025-12-20-add-coercion/design.md (1)
65-75: Array coercion behavior needs clearer guidance.Line 75 states that root-level sequences and array elements are "out of scope for automatic string-to-number coercion unless the environment variable is pre-processed into an array." This limitation should be highlighted more prominently in the flow section or as a known limitation upfront, since it may surprise users with array-typed environment variables.
Consider documenting:
- How users should structure schemas if they need array element coercion.
- Whether future versions will support automatic array element coercion.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (3)
examples/with-bun-react/bun.lockis excluded by!**/*.lockexamples/with-bun/bun.lockis excluded by!**/*.lockpnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (33)
.changeset/cyan-loops-hear.md.changeset/humble-lizards-judge.md.changeset/open-spiders-tan.md.gitignoreapps/playgrounds/node/.env.exampleapps/playgrounds/node/index.tsexamples/basic/.env.exampleexamples/basic/index.tsopenspec/changes/archive/2025-12-20-add-coercion/design.mdopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdopenspec/changes/archive/2025-12-20-add-coercion/tasks.mdopenspec/changes/coercion-public-api/design.mdopenspec/changes/coercion-public-api/proposal.mdopenspec/changes/coercion-public-api/specs/coercion-refactor/spec.mdopenspec/changes/coercion-public-api/tasks.mdopenspec/specs/coercion/spec.mdpackages/arkenv/ARKTYPE_INTERNALS.mdpackages/arkenv/README.mdpackages/arkenv/package.jsonpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/create-env.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/utils/index.tspackages/internal/keywords/src/index.test.tspackages/internal/keywords/src/index.tspackages/internal/scope/src/index.test.tspackages/internal/scope/src/index.ts
💤 Files with no reviewable changes (2)
- examples/basic/.env.example
- apps/playgrounds/node/.env.example
🧰 Additional context used
📓 Path-based instructions (17)
openspec/changes/*/proposal.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Create proposal.md with sections: Why, What Changes (with BREAKING markers), and Impact
Files:
openspec/changes/coercion-public-api/proposal.md
**/*.{ts,tsx,json,md}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Use Biome for linting and formatting instead of ESLint and Prettier
Files:
openspec/changes/coercion-public-api/proposal.mdpackages/internal/keywords/src/index.test.tsopenspec/specs/coercion/spec.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tsopenspec/changes/coercion-public-api/design.mdpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tsopenspec/changes/archive/2025-12-20-add-coercion/tasks.mdopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdpackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdopenspec/changes/coercion-public-api/tasks.mdpackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tsopenspec/changes/coercion-public-api/specs/coercion-refactor/spec.mdpackages/internal/scope/src/index.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
**/*.{ts,tsx}: Prefertypeoverinterfacefor type definitions in TypeScript
Use TypeScript 5.1+ features when appropriate
Leverageconsttype parameters for better inference in TypeScript
Use JSDoc comments for public APIs
Use tabs for indentation (configured in Biome)
Use double quotes for strings (configured in Biome)
Organize imports automatically (Biome handles this)
Avoid explicit types when TypeScript can infer them (noInferrableTypeserror)
Useas constwhere appropriate for immutable values (useAsConstAssertionerror)
Don't reassign function parameters (noParameterAssignerror)
Place default parameters last in function signatures (useDefaultParameterLasterror)
Always initialize enum values (useEnumInitializerserror)
Declare one variable per statement (useSingleVarDeclaratorerror)
Avoid unnecessary template literals (noUnusedTemplateLiteralerror)
PreferNumber.parseIntover globalparseInt(useNumberNamespaceerror)
Use kebab-case for TypeScript filenames (e.g.,create-env.ts)
Use camelCase for function names (e.g.,createEnv)
Use PascalCase for type names (e.g.,ArkEnvError)
Use UPPER_SNAKE_CASE for environment variables and constants
Include examples in JSDoc comments when helpful for public APIs
Document complex type logic with JSDoc comments
UseArkEnvErrorfor environment variable validation errors
Provide clear, actionable error messages that include the variable name and expected type
**/*.{ts,tsx}: UsecreateEnv(schema)as the main function for validated environment objects, available as the default export
Use built-in validators (host, port, url, email) fromsrc/types.tswhen available instead of custom validation
UseArkEnvErrorfor environment variable errors, not generic errors
Environment schema definitions should use built-in validators, ArkType string literals, and support default values in the schema pattern
Use logical grouping for related environment variables in schemas
Use descriptive env...
Files:
packages/internal/keywords/src/index.test.tspackages/arkenv/src/utils/index.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
**/*.test.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
Co-locate tests with components:
Component.tsxnext toComponent.test.tsx
**/*.test.{ts,tsx}: Test individual functions, components, and hooks in isolation with mocked dependencies using the*.test.tsor*.test.tsxsuffix
Mockprocess.envin tests for different scenarios and save/restore original env inbeforeEach/afterEachhooks
Use Vitest'sdescribe/itstructure in test files
Test edge cases including invalid and missing environment variable values
Use Vitest for testing framework
**/*.test.{ts,tsx}: Use Vitest for unit and integration tests
Test individual functions, components, and hooks in isolation with mocked dependencies in unit tests
Unit tests should focus on individual function logic and edge cases, component rendering and props, error handling and validation, and type checking
Unit tests should execute in less than 100ms per test
Mock external dependencies (clipboard, network, etc.) in unit tests
Co-locate unit test files with source files using naming convention: source file → test file (e.g., create-env.ts → create-env.test.ts)
Test component behavior, not aesthetics, and focus on what users can do and what the component guarantees through its API
Test component public API (props, events, and component contract), user behavior (clicks, typing, focus, keyboard, ARIA), state transitions, accessibility, and side effects in component tests
Do not test pure styling or CSS classes, library internals (Radix/shadcn), implementation details (hooks, setState, private variables), or visual variants in component tests
Use Testing Library with user-event for real user simulation in component tests
Query by role, name, label, and text (accessibility first) in component tests
Use beforeEach/afterEach for cleanup, not beforeAll/afterAll when possible
Keep tests fast, deterministic, and parallelizable
Mock at component boundaries (network, time, context)
Files:
packages/internal/keywords/src/index.test.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.test.ts
openspec/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/**/spec.md: Include at least one scenario per requirement using #### Scenario: header format with WHEN and THEN bullet points
Use SHALL/MUST for normative requirements rather than should/may unless intentionally non-normative
Files:
openspec/specs/coercion/spec.mdopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdopenspec/changes/coercion-public-api/specs/coercion-refactor/spec.md
packages/*/package.json
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Packages in packages/ directory must be published to npm and require changesets for versioning, proper exports, and type definitions
Files:
packages/arkenv/package.json
**/package.json
📄 CodeRabbit inference engine (.cursor/rules/monorepo.mdc)
Use workspace:* protocol for workspace dependencies between packages
Files:
packages/arkenv/package.json
{packages,apps,tooling}/**/package.json
📄 CodeRabbit inference engine (.cursor/rules/pnpm.mdc)
When referencing workspace packages in dependencies, use the
workspace:*protocol instead of version numbers
Files:
packages/arkenv/package.json
packages/arkenv/**/*.ts
📄 CodeRabbit inference engine (.cursor/rules/arktype.mdc)
packages/arkenv/**/*.ts: Use ArkType'stype()function to define schemas in environment variable definitions
Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Use the scoped$type system for custom types defined inscope.ts
Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Use union types for enums in ArkType schemas (e.g.,"'dev' | 'prod'") instead of separate enum definitions
Leverage ArkType's built-in types (e.g.,string.host,number.port) where possible in environment schemas
Convert ArkType validation errors toArkEnvErrorfor user-friendly error messages that include variable name and expected type
Files:
packages/arkenv/src/utils/index.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.ts
**/index.ts
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
Use barrel exports (
index.ts) for package entry points
Files:
packages/arkenv/src/utils/index.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
packages/arkenv/src/**/*.ts
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Main library implementation should be in
src/create-env.ts, built-in validators insrc/types.ts, error handling insrc/errors.ts, and utilities insrc/utils.ts
Files:
packages/arkenv/src/utils/index.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.ts
**/*.integration.test.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
**/*.integration.test.{ts,tsx}: Use integration tests with*.integration.test.tsor*.integration.test.tsxsuffix to test how multiple units work together without mocking their interactions
Integration tests should verify interactions between multiple units (like components + hooks + services) without mocking their interactions
**/*.integration.test.{ts,tsx}: Test how multiple units (components, hooks, functions) work together without mocking their interactions in integration tests
Integration tests should focus on component and hook interactions, function composition and data flow, real dependencies between units, and state synchronization across boundaries
Integration tests should execute between 100ms - 2000ms per test
Use *.integration.test.ts suffix to distinguish integration tests from unit tests
Files:
packages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.ts
**/README.md
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
Document environment requirements in README files
Files:
packages/arkenv/README.md
openspec/changes/*/tasks.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
Create tasks.md with numbered implementation checklist items as checkboxes (- [ ] format)
Files:
openspec/changes/coercion-public-api/tasks.md
openspec/changes/*/specs/**/spec.md
📄 CodeRabbit inference engine (openspec/AGENTS.md)
openspec/changes/*/specs/**/spec.md: Use ## ADDED|MODIFIED|REMOVED|RENAMED Requirements as delta headers in spec.md files under changes
Ensure change proposals contain delta specs for each affected capability under changes/[change-id]/specs/[capability]/spec.md
Files:
openspec/changes/coercion-public-api/specs/coercion-refactor/spec.md
{bin,examples,playgrounds}/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)
Console usage is allowed in
bin/and example/playground directories, otherwise treated as warning
Files:
examples/basic/index.ts
examples/**/*.{ts,tsx}
📄 CodeRabbit inference engine (.github/copilot-instructions.md)
examples/**/*.{ts,tsx}: Ensure examples demonstrate secure default practices
Add examples in theexamples/directory for new functionality, demonstrating real-world usage patterns
Files:
examples/basic/index.ts
🧠 Learnings (45)
📓 Common learnings
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Environment schema definitions should use built-in validators, ArkType string literals, and support default values in the schema pattern
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable errors, not generic errors
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: For breaking changes, always create an OpenSpec proposal first
Applied to files:
openspec/changes/coercion-public-api/proposal.md
📚 Learning: 2025-11-24T16:05:35.714Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-24T16:05:35.714Z
Learning: Applies to openspec/changes/*/proposal.md : Create proposal.md with sections: Why, What Changes (with BREAKING markers), and Impact
Applied to files:
openspec/changes/coercion-public-api/proposal.md
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Applied to files:
openspec/changes/coercion-public-api/proposal.mdopenspec/specs/coercion/spec.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tsopenspec/changes/coercion-public-api/design.mdpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tsopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdpackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.ts.changeset/cyan-loops-hear.mdpackages/arkenv/src/error.integration.test.tsopenspec/changes/coercion-public-api/specs/coercion-refactor/spec.mdpackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's built-in types (e.g., `string.host`, `number.port`) where possible in environment schemas
Applied to files:
openspec/changes/coercion-public-api/proposal.mdopenspec/specs/coercion/spec.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tsopenspec/changes/coercion-public-api/design.mdpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.ts.changeset/open-spiders-tan.mdopenspec/changes/archive/2025-12-20-add-coercion/tasks.mdopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdpackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.ts.changeset/cyan-loops-hear.mdpackages/arkenv/src/error.integration.test.tsopenspec/changes/coercion-public-api/specs/coercion-refactor/spec.mdpackages/internal/scope/src/index.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.ts.changeset/humble-lizards-judge.mdexamples/basic/index.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use union types for enums in ArkType schemas (e.g., `"'dev' | 'prod'"`) instead of separate enum definitions
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tsopenspec/changes/coercion-public-api/design.mdpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.ts.changeset/cyan-loops-hear.mdpackages/arkenv/src/error.integration.test.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tspackages/arkenv/README.mdpackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.ts.changeset/cyan-loops-hear.mdapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/scope.ts : Define custom types in `scope.ts` using ArkType's scoped type system for reusability across schemas
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/index.tspackages/arkenv/src/utils/coerce.ts.changeset/open-spiders-tan.mdopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/internal/scope/src/index.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Environment schema definitions should use built-in validators, ArkType string literals, and support default values in the schema pattern
Applied to files:
openspec/changes/coercion-public-api/proposal.mdopenspec/specs/coercion/spec.mdpackages/arkenv/package.jsonpackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tsopenspec/changes/archive/2025-12-20-add-coercion/specs/coercion/spec.mdpackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.test.tsapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/package.jsonpackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Convert ArkType validation errors to `ArkEnvError` for user-friendly error messages that include variable name and expected type
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/src/utils/index.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/utils/coerce.test.tspackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tsapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to packages/arkenv/src/**/*.ts : Main library implementation should be in `src/create-env.ts`, built-in validators in `src/types.ts`, error handling in `src/errors.ts`, and utilities in `src/utils.ts`
Applied to files:
openspec/changes/coercion-public-api/proposal.mdpackages/arkenv/src/utils/index.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/create-env.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/error.integration.test.tsapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.test.{ts,tsx} : Test edge cases including invalid and missing environment variable values
Applied to files:
packages/internal/keywords/src/index.test.tspackages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.test.ts
📚 Learning: 2025-09-10T19:35:18.179Z
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 136
File: .changeset/vast-bananas-win.md:2-3
Timestamp: 2025-09-10T19:35:18.179Z
Learning: The arkenv package is currently in v0.x.x (pre-1.0) development phase, where breaking changes are acceptable in minor version bumps according to semantic versioning conventions.
Applied to files:
packages/arkenv/package.json
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition
Applied to files:
packages/arkenv/package.jsonpackages/arkenv/src/utils/coerce.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-24T16:04:11.901Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/monorepo.mdc:0-0
Timestamp: 2025-11-24T16:04:11.901Z
Learning: packages/arkenv should not depend on other workspace packages; packages/vite-plugin depends on arkenv; apps/www may depend on workspace packages
Applied to files:
packages/arkenv/package.json
📚 Learning: 2025-11-24T16:03:45.295Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/arktype.mdc:0-0
Timestamp: 2025-11-24T16:03:45.295Z
Learning: Applies to packages/arkenv/**/*.ts : Use the scoped `$` type system for custom types defined in `scope.ts`
Applied to files:
packages/arkenv/package.jsonpackages/arkenv/src/utils/index.tspackages/arkenv/src/utils/coerce.ts.changeset/open-spiders-tan.mdpackages/arkenv/ARKTYPE_INTERNALS.mdopenspec/changes/archive/2025-12-20-add-coercion/design.mdpackages/arkenv/src/custom-types.integration.test.tspackages/internal/scope/src/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/index.ts : Use barrel exports (`index.ts`) for package entry points
Applied to files:
packages/arkenv/src/utils/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Prefer tree-shakeable exports for better bundling
Applied to files:
packages/arkenv/src/utils/index.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Integration tests should focus on component and hook interactions, function composition and data flow, real dependencies between units, and state synchronization across boundaries
Applied to files:
packages/arkenv/src/coercion.integration.test.tspackages/internal/scope/src/index.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Test how multiple units (components, hooks, functions) work together without mocking their interactions in integration tests
Applied to files:
packages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Integration tests should verify interactions between multiple units (like components + hooks + services) without mocking their interactions
Applied to files:
packages/arkenv/src/coercion.integration.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Use integration tests with `*.integration.test.ts` or `*.integration.test.tsx` suffix to test how multiple units work together without mocking their interactions
Applied to files:
packages/arkenv/src/coercion.integration.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.integration.test.{ts,tsx} : Use *.integration.test.ts suffix to distinguish integration tests from unit tests
Applied to files:
packages/arkenv/src/coercion.integration.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Test component public API (props, events, and component contract), user behavior (clicks, typing, focus, keyboard, ARIA), state transitions, accessibility, and side effects in component tests
Applied to files:
packages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/type.test.tspackages/arkenv/src/utils/coerce.test.tspackages/internal/scope/src/index.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.test.{ts,tsx} : Use Vitest's `describe`/`it` structure in test files
Applied to files:
packages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Use Vitest for unit and integration tests
Applied to files:
packages/arkenv/src/coercion.integration.test.tspackages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.test.{ts,tsx} : Mock `process.env` in tests for different scenarios and save/restore original env in `beforeEach`/`afterEach` hooks
Applied to files:
packages/arkenv/src/create-env.test.tspackages/arkenv/src/type.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Co-locate unit test files with source files using naming convention: source file → test file (e.g., create-env.ts → create-env.test.ts)
Applied to files:
packages/arkenv/src/create-env.test.tspackages/arkenv/src/utils/coerce.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` as the main function for validated environment objects, available as the default export
Applied to files:
packages/arkenv/src/create-env.test.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsapps/playgrounds/node/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors
Applied to files:
packages/arkenv/src/create-env.test.tspackages/arkenv/src/create-env.tspackages/arkenv/src/type.test.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Use `ArkEnvError` for environment variable errors, not generic errors
Applied to files:
packages/arkenv/src/create-env.test.tspackages/arkenv/src/create-env.tsopenspec/changes/archive/2025-12-20-add-coercion/proposal.mdpackages/arkenv/README.mdpackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.tsapps/playgrounds/node/index.tsexamples/basic/index.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.test.{ts,tsx} : Use Vitest for testing framework
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-24T16:04:58.629Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: apps/playgrounds/bun/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2025-11-24T16:04:58.629Z
Learning: Applies to apps/playgrounds/bun/**/*.test.{ts,tsx,js,jsx} : Use `import { test, expect } from "bun:test"` for writing tests
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-24T16:04:47.583Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: apps/playgrounds/bun-react/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2025-11-24T16:04:47.583Z
Learning: Applies to apps/playgrounds/bun-react/**/*.test.{ts,tsx,js,jsx} : Use `bun:test` for unit and integration testing with `test` and `expect` from the built-in test module
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to packages/vite-plugin/src/**/*.test.ts : Use fixture-based testing pattern for Vite plugin tests by placing fixtures in __fixtures__ directory
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-24T16:04:47.583Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: apps/playgrounds/bun-react/.cursor/rules/use-bun-instead-of-node-vite-npm-pnpm.mdc:0-0
Timestamp: 2025-11-24T16:04:47.583Z
Learning: Applies to apps/playgrounds/bun-react/**/*.test.{ts,tsx,js,jsx} : Use `bun test` instead of `jest` or `vitest` for running tests
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to packages/vite-plugin/src/**/*.test.ts : Test the Vite plugin using the with-vite-react example as a fixture and validate that the plugin works with real Vite projects
Applied to files:
packages/arkenv/src/create-env.test.ts
📚 Learning: 2025-11-24T16:05:35.714Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: openspec/AGENTS.md:0-0
Timestamp: 2025-11-24T16:05:35.714Z
Learning: Applies to openspec/changes/*/tasks.md : Create tasks.md with numbered implementation checklist items as checkboxes (- [ ] format)
Applied to files:
openspec/changes/archive/2025-12-20-add-coercion/tasks.md
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from `src/types.ts` when available instead of custom validation
Applied to files:
packages/arkenv/src/type.test.tspackages/arkenv/src/custom-types.integration.test.tspackages/arkenv/src/error.integration.test.tspackages/internal/scope/src/index.test.tspackages/internal/keywords/src/index.ts
📚 Learning: 2025-12-05T20:33:10.676Z
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 498
File: apps/playgrounds/node/index.ts:2-2
Timestamp: 2025-12-05T20:33:10.676Z
Learning: ArkType 2.1.28+ supports Standard Schema specification, allowing interoperability with other Standard Schema-compliant validation libraries (e.g., Zod, Valibot) within the same schema definition
Applied to files:
openspec/changes/archive/2025-12-20-add-coercion/proposal.md
📚 Learning: 2025-12-12T13:20:01.954Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/test-patterns.mdc:0-0
Timestamp: 2025-12-12T13:20:01.954Z
Learning: Applies to **/*.test.{ts,tsx} : Unit tests should focus on individual function logic and edge cases, component rendering and props, error handling and validation, and type checking
Applied to files:
packages/arkenv/src/utils/coerce.test.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Prefer `Number.parseInt` over global `parseInt` (`useNumberNamespace` error)
Applied to files:
packages/internal/scope/src/index.test.ts
📚 Learning: 2025-11-29T22:11:39.931Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-29T22:11:39.931Z
Learning: Applies to **/*.{ts,tsx} : Use descriptive environment variable names that indicate purpose and format
Applied to files:
examples/basic/index.ts
📚 Learning: 2025-11-24T16:04:00.957Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .cursor/rules/coding-guidelines.mdc:0-0
Timestamp: 2025-11-24T16:04:00.957Z
Learning: Applies to **/*.{ts,tsx} : Use PascalCase for type names (e.g., `ArkEnvError`)
Applied to files:
examples/basic/index.ts
🧬 Code graph analysis (10)
packages/internal/keywords/src/index.test.ts (1)
packages/internal/keywords/src/index.ts (1)
port(37-37)
packages/arkenv/package.json (3)
packages/arkenv/src/index.test.ts (2)
arkenv(50-53)vi(65-81)packages/bun-plugin/src/index.ts (2)
cwd(187-241)processEnvSchema(12-37)packages/vite-plugin/src/index.ts (1)
arkenv(49-86)
packages/arkenv/src/coercion.integration.test.ts (2)
packages/arkenv/src/create-env.ts (1)
createEnv(36-56)packages/arkenv/src/type.ts (1)
type(3-3)
packages/arkenv/src/create-env.test.ts (2)
packages/arkenv/src/create-env.ts (1)
createEnv(36-56)packages/arkenv/src/index.ts (1)
createEnv(13-13)
packages/arkenv/src/create-env.ts (1)
packages/arkenv/src/utils/coerce.ts (1)
coerce(172-182)
packages/arkenv/src/utils/coerce.test.ts (2)
packages/arkenv/src/type.ts (1)
type(3-3)packages/arkenv/src/utils/coerce.ts (1)
coerce(172-182)
packages/arkenv/src/custom-types.integration.test.ts (1)
packages/arkenv/src/type.ts (1)
type(3-3)
packages/arkenv/src/error.integration.test.ts (1)
packages/arkenv/src/errors.test.ts (1)
errors(94-106)
apps/playgrounds/node/index.ts (2)
packages/arkenv/src/index.test.ts (4)
vi(65-81)vi(25-35)arkenv(50-53)afterEach(4-82)packages/arkenv/src/array-defaults.integration.test.ts (1)
env(14-30)
packages/internal/keywords/src/index.ts (1)
packages/arkenv/src/type.ts (1)
type(3-3)
🪛 LanguageTool
openspec/changes/coercion-public-api/proposal.md
[style] ~5-~5: To elevate your writing, try using a synonym here.
Context: ...codebase fragile to ArkType updates and hard to maintain as it requires deep knowled...
(HARD_TO)
[style] ~5-~5: Consider a different adjective to strengthen your wording.
Context: ...tes and hard to maintain as it requires deep knowledge of ArkType's node architectur...
(DEEP_PROFOUND)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
- GitHub Check: test-e2e (a11y)
- GitHub Check: test-e2e (e2e)
- GitHub Check: test-build (lts/*)
| # arktype clone | ||
| arktype |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Search for arktype references in common places
rg -n "arktype" --type ts --type js --type json --type yaml --type yml | head -30Repository: yamcodes/arkenv
Length of output: 86
🏁 Script executed:
# Search for arktype references more broadly
rg -n "arktype" --type ts --type js --type json | head -50Repository: yamcodes/arkenv
Length of output: 3895
🏁 Script executed:
# Check for shell scripts that might reference arktype cloning
find . -type f \( -name "*.sh" -o -name "*.bash" \) | xargs grep -l "arktype" 2>/dev/null || echo "No shell scripts with arktype"
# Check package.json for any build/setup scripts mentioning arktype
fd "package.json" | xargs grep -A 5 -B 5 '"scripts"' | grep -A 30 "arktype\|clone" | head -40
# Check the actual .gitignore file around lines 45-50
cat -n .gitignore | sed -n '40,55p'Repository: yamcodes/arkenv
Length of output: 230
🏁 Script executed:
# Check for any documentation about arktype in the repo
find . -type f \( -name "*.md" -o -name "*.txt" -o -name "*.mdx" \) | xargs grep -l "arktype" 2>/dev/null | head -5
# Check for build configuration files
find . -maxdepth 2 -type f \( -name "vite.config.*" -o -name "tsconfig*" -o -name "turbo.json" -o -name ".npmrc" -o -name "pnpm-workspace.yaml" \)
# Check root package.json for any scripts that might generate arktype
cat package.json | grep -A 100 '"scripts"' | head -50Repository: yamcodes/arkenv
Length of output: 1778
🏁 Script executed:
# Check pnpm-workspace.yaml for monorepo configuration
cat pnpm-workspace.yaml
# Check if arktype appears as a local workspace package
find . -maxdepth 3 -path "*/node_modules" -prune -o -type d -name "arktype" -print
# Check for any introspection files or generated schema files
find . -path "*/node_modules" -prune -o -type f -name "*.in.json" -print 2>/dev/null | head -10
# Look for any reference to "arktype" in coercion-related files
find . -path "*/node_modules" -prune -o -type f \( -name "*coercion*" -o -name "*coerce*" \) -printRepository: yamcodes/arkenv
Length of output: 937
🏁 Script executed:
# Check the coercion-related files to understand the arktype reference
cat -n packages/arkenv/src/utils/coerce.ts
# Also check the coercion integration test
cat -n packages/arkenv/src/coercion.integration.test.ts | head -60Repository: yamcodes/arkenv
Length of output: 8829
🏁 Script executed:
# Check if there's a recently created arktype directory
ls -la | grep arktype
# Check git log to see when this gitignore entry was added and any context
git log --oneline -n 20 -- .gitignore
# Check if there are any references to arktype in CI/CD configs
find . -path "*/node_modules" -prune -o -type f \( -name "*.yml" -o -name "*.yaml" -o -name ".github" \) -o -path "*/.github/*" -print 2>/dev/null | head -20Repository: yamcodes/arkenv
Length of output: 969
🏁 Script executed:
# Check the specific commit that added the arktype gitignore entry
git show 3a322bc --stat | head -40
# Get more details about what files were changed in that commit
git show 3a322bc --name-only | head -30
# Check if there's an arktype directory that was created
git show 3a322bc:.gitignore | tail -10Repository: yamcodes/arkenv
Length of output: 3498
🏁 Script executed:
# Check if arktype directory exists or was created
test -d arktype && echo "arktype directory exists" || echo "arktype directory does not exist"
# Check the cursor rules file that was added in the commit
cat -n .cursor/rules/arktype.mdc | head -60Repository: yamcodes/arkenv
Length of output: 1983
🏁 Script executed:
# Check the PR/commit message more thoroughly
git log --format=fuller 3a322bc | head -40
# Check if there's any documentation about this in the changeset files
cat .changeset/*.md 2>/dev/null | grep -i "arktype\|clone" -A 2 -B 2Repository: yamcodes/arkenv
Length of output: 1211
Remove the arktype gitignore entry—it's unused and misleading.
The implementation uses ArkType's public introspection API (.in.json) to identify coercion targets, not artifact generation or cloning. No arktype/ directory is created, and the entry should not be in .gitignore.
🤖 Prompt for AI Agents
In .gitignore around lines 47 to 48, remove the obsolete "arktype" entry because
the project does not generate or clone an arktype/ directory; update the file by
deleting that line so the gitignore no longer misleadingly ignores "arktype".
| 1. **Keywords**: Define `parsedNumber` and `parsedBoolean` in `@repo/keywords` as reusable building blocks that handle string-to-primitive conversion. | ||
| 2. **Scope**: Keep `number` and `boolean` as standard ArkType types in `@repo/scope` so they remain "constrainable" (supporting ranges, divisors, etc.). | ||
| 3. **Transformation**: In `createEnv`, use ArkType's `schema.transform()` to walk the fully parsed schema. The transformer identifies numeric and boolean leaf nodes and automatically wraps them in the appropriate coercion morph. | ||
|
|
There was a problem hiding this comment.
Documentation has minor inconsistencies with the implementation.
- Line 11 mentions
parsedNumberandparsedBoolean, but the implementation usesmaybeParsedNumberandmaybeParsedBoolean. - Line 13 mentions using
schema.transform(), but the implementation usesfindCoercionPaths()withschema.in.jsonintrospection and.pipe()composition.
Consider updating the documentation to match the actual implementation approach.
🤖 Prompt for AI Agents
In openspec/changes/archive/2025-12-20-add-coercion/proposal.md around lines 11
to 14, the doc references `parsedNumber`/`parsedBoolean` and
`schema.transform()`, but the code uses `maybeParsedNumber`/`maybeParsedBoolean`
and a `findCoercionPaths()` approach that inspects `schema.in.json` and composes
coercions with `.pipe()`; update the text to use the actual symbol names
(`maybeParsedNumber`, `maybeParsedBoolean`) and replace the description of
transformation to describe using `findCoercionPaths()` with `schema.in.json`
introspection and `.pipe()` composition (or alternatively note that the
implementation differs if you intend to keep the doc as-is), and ensure the
Scope line still clarifies that `number` and `boolean` remain constrainable in
`@repo/scope`.
|
Because We cannot access properties like Sticking to Closing in favor of #578 |
1 participant
This is an attempt to implement coercion, this time by relying on 100% public API which makes ArkEnv much, much more reliable (100% reliable) instead of having to compromise on reliability.
Closes #577, clones #576 (re-opened due to branch rename)
Summary by CodeRabbit
Release Notes
Breaking Changes
New Features
Improvements
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.