Skip to content

Add JSDoc to all public exports + small bun-plugin, @repo/types refactor#739

Merged
yamcodes merged 17 commits intomainfrom
copilot/add-jsdoc-to-exports
Jan 16, 2026
Merged

Add JSDoc to all public exports + small bun-plugin, @repo/types refactor#739
yamcodes merged 17 commits intomainfrom
copilot/add-jsdoc-to-exports

Conversation

Copy link
Contributor

Copilot AI commented Jan 16, 2026

Added JSDoc documentation to all user-facing exports across arkenv, @arkenv/bun-plugin, and @arkenv/vite-plugin packages for IDE autocomplete and hover tooltips.

Changes

arkenv package:

  • type export - Documents ArkType's type function scoped with built-in validators
  • EnvSchema type - Describes valid schema definition structure
  • ArkEnvError class - Explains validation error with usage example
  • Re-exports in index.ts - Added descriptive JSDoc for better DX

@arkenv/bun-plugin package:

  • processEnvSchema function - Added parameters, return type, and filtering behavior
  • ProcessEnvAugmented type - Documents process.env augmentation pattern

@arkenv/vite-plugin package:

  • ImportMetaEnvAugmented type - Documents import.meta.env augmentation pattern (matching ProcessEnvAugmented documentation style)

Example

import { type, createEnv, ArkEnvError } from 'arkenv';

// JSDoc now explains that `type` includes built-in validators like host, port, url
const schema = type({
  HOST: 'string.host',
  PORT: 'number.port',
});

// JSDoc explains validation behavior and error handling
try {
  const env = createEnv(schema);
} catch (error) {
  if (error instanceof ArkEnvError) {
    // JSDoc explains formatted error messages
    console.error(error.message);
  }
}

All JSDoc is preserved in generated .d.ts files.

Original prompt

This section details on the original issue you should resolve

<issue_title>Add jsdoc to all exports</issue_title>
<issue_description></issue_description>

<agent_instructions>add jsdoc to all exports, meaning, anything the user of a package can import.

Not literally meaning any const that is exported from any file</agent_instructions>

Comments on the Issue (you are @copilot in this section)

@yamcodes `ProcessEnvAugmented` from the bun plugin is documented well, so we can similarly document `ImportMetaEnvAugmented` from vite plugin

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Summary by CodeRabbit

  • Breaking Changes

    • Renamed public type EnvSchemaWithType → CompiledEnvSchema
    • Removed a previously exported internal schema helper from the public API
  • New Features

    • Added a dedicated ArkEnvError class for clearer validation errors
    • Introduced EnvSchema type and a parse function for schema-driven env validation
    • Bun plugin rebuilt: supports automatic schema discovery, hybrid usage, and .mts/.cts files
  • Documentation

    • JSDoc and examples updated for clarity

✏️ Tip: You can customize this high-level summary in your review settings.

@changeset-bot
Copy link

changeset-bot bot commented Jan 16, 2026

🦋 Changeset detected

Latest commit: d773d0a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages
Name Type
@arkenv/bun-plugin Minor
@repo/types Minor

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

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 16, 2026

Caution

Review failed

An error occurred during the review process. Please try again later.

Walkthrough

Renames public type EnvSchemaWithTypeCompiledEnvSchema across packages, adds EnvSchema<def> and ArkEnvError, moves Bun plugin implementation to plugin.ts (re-exports from index.ts), introduces a hybrid Bun plugin with dynamic schema discovery, and adds utility functions and tests for env handling.

Changes

Cohort / File(s) Change Summary
Changesets
\.changeset/kind-garlics-move.md`, `.changeset/wacky-oranges-care.md`, `.changeset/mighty-kids-count.md``
Changelog entries: bump @arkenv/bun-plugin, document removal of processEnvSchema export, rename EnvSchemaWithTypeCompiledEnvSchema, add .mts/.cts support.
Type system
\packages/internal/types/src/schema.ts`, `packages/arkenv/src/create-env.ts`, `packages/vite-plugin/src/index.ts``
Rename EnvSchemaWithTypeCompiledEnvSchema; update imports/overloads; add exported EnvSchema<def> type in create-env.ts.
Error handling
\packages/arkenv/src/errors.ts`, `packages/arkenv/src/index.ts``
New exported ArkEnvError class for formatted validation errors; small JSDoc tweak in index.ts.
Bun plugin core
\packages/bun-plugin/src/index.ts`, `packages/bun-plugin/src/plugin.ts``
Move full plugin implementation into plugin.ts; index.ts now re-exports arkenv and hybrid; add hybrid plugin supporting static config and runtime discovery.
Bun plugin utils & tests
\packages/bun-plugin/src/utils.ts`, `packages/bun-plugin/src/utils.test.ts`, `packages/bun-plugin/src/plugin.test.ts``
New processEnvSchema() and registerLoader() utilities; tests added/updated to reflect new plugin location and behavior; removed direct processEnvSchema export usage where applicable.
Arktype additions
\packages/arkenv/src/arktype/index.ts`**`
New exports: distill type and parse function (parsing/validation API) added.
Vite plugin docs
\packages/vite-plugin/src/types.ts`**`
JSDoc examples simplified/removed; no type signature changes.

Sequence Diagram(s)

sequenceDiagram
    actor Dev as Developer
    participant Bun as Bun
    participant Plugin as "@arkenv/bun-plugin (hybrid)"
    participant FS as FileSystem
    participant Loader as ModuleLoader

    rect rgba(100,150,200,0.5)
    Dev->>Plugin: arkenv(schema)         Note right of Plugin: Static mode
    Plugin->>Plugin: processEnvSchema(schema)
    Plugin-->>Plugin: build env map
    Plugin->>Loader: registerLoader(build, envMap)
    end

    rect rgba(150,100,200,0.5)
    Bun->>Plugin: hybrid.setup(build)    Note right of Plugin: Hybrid/dynamic mode
    Plugin->>FS: import ./src/env.ts or ./env.ts
    alt schema found
        FS-->>Plugin: schema module
        Plugin->>Plugin: processEnvSchema(discovered)
        Plugin-->>Plugin: merge into env map
        Plugin->>Loader: registerLoader(build, envMap)
    else not found
        FS-->>Plugin: not found
        Plugin-->>Bun: log error + sample env.ts
    end
    end
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

Suggested labels

@arkenv/bun-plugin

Poem

🐰 I hopped through types and bounced on code,

Compiled schemas now lighten the load,
Bun finds env in files it may seek,
ArkEnvError sings when validations speak,
A rabbit's cheer for a tidy new node!

🚥 Pre-merge checks | ✅ 3 | ❌ 2
❌ Failed checks (2 warnings)
Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The PR includes significant refactoring beyond JSDoc: bun-plugin architecture restructuring, removing/renaming exports (processEnvSchema, EnvSchemaWithType→CompiledEnvSchema), and new error handling, which extends beyond the stated scope of adding documentation. Separate refactoring changes (bun-plugin restructuring, type renaming, export removal) from JSDoc additions into distinct PRs to maintain focus on documentation goals.
Docstring Coverage ⚠️ Warning Docstring coverage is 40.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately reflects the main changes: JSDoc additions to public exports across packages and refactoring in bun-plugin and @repo/types.
Linked Issues check ✅ Passed The PR successfully implements the core objective from #738 by adding JSDoc documentation to all public exports across arkenv, bun-plugin, and vite-plugin packages as required.

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


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

Comment @coderabbitai help to get the list of available commands and usage tips.

Co-authored-by: yamcodes <2014360+yamcodes@users.noreply.github.com>
Copilot AI changed the title [WIP] Add JSDoc to all exports in the package Add JSDoc to all public exports Jan 16, 2026
Copilot AI requested a review from yamcodes January 16, 2026 15:05
@github-actions github-actions bot added arkenv Changes to the `arkenv` npm package. @arkenv/vite-plugin Issues or Pull Requests involving the Vite plugin for ArkEnv labels Jan 16, 2026
@pkg-pr-new
Copy link

pkg-pr-new bot commented Jan 16, 2026

Open in StackBlitz

npm i https://pkg.pr.new/arkenv@739
npm i https://pkg.pr.new/@arkenv/bun-plugin@739
npm i https://pkg.pr.new/@arkenv/vite-plugin@739

commit: d773d0a

@arkenv-bot
Copy link
Contributor

arkenv-bot bot commented Jan 16, 2026

📦 Bundle Size Report

Package Size Limit Diff Status
@arkenv/vite-plugin 1.55 kB 1.95 kB 0.0%
arkenv 1.38 kB 2.93 kB 0.0%
@arkenv/bun-plugin 2.01 kB 2.44 kB +0.5%

All size limits passed!

@github-actions github-actions bot added the tests This issue or PR is about adding, removing or changing tests label Jan 16, 2026
@github-actions github-actions bot added the docs Improvements or additions to documentation label Jan 16, 2026
@yamcodes yamcodes changed the title Add JSDoc to all public exports Add JSDoc to all public exports + small bun-plugin refactor Jan 16, 2026
@yamcodes yamcodes marked this pull request as ready for review January 16, 2026 19:12
@yamcodes yamcodes changed the title Add JSDoc to all public exports + small bun-plugin refactor Add JSDoc to all public exports + small bun-plugin, @repo/types refactor Jan 16, 2026
- Renamed type `EnvSchemaWithType` to `CompiledEnvSchema`
- Updated JSDoc for schema definitions
- Clar
@yamcodes
Copy link
Owner

@coderabbitai review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 16, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

Copy link
Contributor

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Fix all issues with AI agents
In `@packages/bun-plugin/src/utils.ts`:
- Around line 31-57: The build.onLoad filter regex currently omits .mts (and
.cts), making the args.path.endsWith(".mts") branch in the loader logic
unreachable; update the filter passed to build.onLoad to include both mts and
cts (e.g., add "mts" and "cts" to the group) and ensure the loader determination
in the code that checks args.path.endsWith(".tsx"), ".jsx", ".ts", ".mts" also
accounts for ".cts" so the file extension checks and the filter are consistent
(refer to build.onLoad filter, envMap replacement loop, and the loader
assignment that uses args.path.endsWith).
🧹 Nitpick comments (5)
packages/bun-plugin/src/utils.ts (1)

59-61: Silent error swallowing may hide issues during development.

Returning undefined on error silently ignores file read/transform failures. Consider logging the error in development mode or at minimum adding a comment explaining why errors are intentionally ignored.

Optional: Log errors in development
 		} catch {
+			// Silently fall back to default handling if file read/transform fails
 			return undefined;
 		}

Or for more visibility during debugging:

-		} catch {
+		} catch (error) {
+			if (process.env.DEBUG) {
+				console.warn(`[`@arkenv/bun-plugin`] Failed to transform ${args.path}:`, error);
+			}
 			return undefined;
 		}
packages/bun-plugin/src/utils.test.ts (1)

1-36: Well-structured test following coding guidelines.

The test file correctly uses Vitest's describe/it structure, mocks process.env with proper cleanup, and is co-located with the source file. The as const assertion on line 24 is appropriate for ArkType schema definitions.

Consider expanding test coverage.

The current test validates the primary filtering behavior. Additional test cases could strengthen coverage:

  • Schema with only non-prefixed variables (empty map result)
  • Schema with only prefixed variables (all included)
  • Validation failure scenarios (missing required env vars)
packages/bun-plugin/src/plugin.ts (3)

55-63: Consider adding JSDoc for the hybrid export.

The hybrid object is a public export that acts both as a function and a BunPlugin. Adding a brief JSDoc comment would improve discoverability and explain its dual nature to users. Based on learnings, JSDoc comments should be used for public APIs.

📝 Suggested JSDoc addition
+/**
+ * Hybrid export that can be used both as a function `arkenv(schema)` and
+ * directly as a `BunPlugin` for zero-config usage.
+ *
+ * `@example`
+ * // As a function
+ * Bun.build({ plugins: [arkenv(mySchema)] })
+ *
+ * // As a plugin (zero-config)
+ * Bun.build({ plugins: [arkenv] })
+ */
 export const hybrid = arkenv as typeof arkenv & BunPlugin;

65-118: Consider using ArkEnvError instead of generic Error for schema discovery failures.

The error thrown at line 105-107 uses a generic Error. Per coding guidelines, environment-related errors should use ArkEnvError for consistency. This provides better error handling semantics across the library.

♻️ Suggested fix

Add the import at the top:

 import type { CompiledEnvSchema, SchemaShape } from "@repo/types";
 import type { EnvSchema } from "arkenv";
+import { ArkEnvError } from "arkenv";
 import type { BunPlugin } from "bun";

Then update the error:

-		throw new Error(
-			`@arkenv/bun-plugin: No environment schema found.\n\nChecked paths:\n${pathsList}\n\nPlease create a schema file at one of these locations exporting your environment definition.\n${example}`,
-		);
+		throw new ArkEnvError([
+			{
+				path: "",
+				message: `No environment schema found.\n\nChecked paths:\n${pathsList}\n\nPlease create a schema file at one of these locations exporting your environment definition.\n${example}`,
+			},
+		]);

70-70: Avoid any type for schema variable.

Using any bypasses TypeScript's type checking. Consider using a more specific type or unknown with runtime narrowing.

♻️ Suggested improvement
-		let schema: any;
+		let schema: CompiledEnvSchema | EnvSchema<SchemaShape> | undefined;

Then adjust the assignment and null check accordingly.

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 384f126 and 998806a.

📒 Files selected for processing (13)
  • .changeset/kind-garlics-move.md
  • .changeset/wacky-oranges-care.md
  • packages/arkenv/src/create-env.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/utils.ts
  • packages/internal/types/src/schema.ts
  • packages/vite-plugin/src/index.ts
  • packages/vite-plugin/src/types.ts
🧰 Additional context used
📓 Path-based instructions (5)
**/*.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)

**/*.{ts,tsx}: Prefer type over interface for type definitions in TypeScript
Use TypeScript 5.1+ features when appropriate
Leverage const type 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 (noInferrableTypes error)
Use as const where appropriate for immutable values (useAsConstAssertion error)
Don't reassign function parameters (noParameterAssign error)
Place default parameters last in function signatures (useDefaultParameterLast error)
Always initialize enum values (useEnumInitializers error)
Declare one variable per statement (useSingleVarDeclarator error)
Avoid unnecessary template literals (noUnusedTemplateLiteral error)
Prefer Number.parseInt over global parseInt (useNumberNamespace error)
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
Use ArkEnvError for environment variable validation errors
Provide clear, actionable error messages that include the variable name and expected type

**/*.{ts,tsx}: Use createEnv(schema) function (or default import as arkenv) to create validated environment objects in TypeScript
Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas
Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')
Use ArkEnvError for environment variable errors instead of generic Error types
For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'deve...

Files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.ts
packages/arkenv/**/*.ts

📄 CodeRabbit inference engine (.cursor/rules/arktype.mdc)

packages/arkenv/**/*.ts: Use ArkType's type() 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 in scope.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 to ArkEnvError for user-friendly error messages that include variable name and expected type

Files:

  • packages/arkenv/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
**/index.ts

📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)

Use barrel exports (index.ts) for package entry points

Files:

  • packages/arkenv/src/index.ts
  • packages/vite-plugin/src/index.ts
  • packages/bun-plugin/src/index.ts
**/*.test.{ts,tsx}

📄 CodeRabbit inference engine (.cursor/rules/coding-guidelines.mdc)

Co-locate tests with components: Component.tsx next to Component.test.tsx

**/*.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)

Create unit tests with .test.ts or .test.tsx suffix located alongside source files, testing individual functions and components in isolation with mocked dependencies

Files:

  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
**/*.{test,integration.test}.{ts,tsx}

📄 CodeRabbit inference engine (.github/copilot-instructions.md)

**/*.{test,integration.test}.{ts,tsx}: Use Vitest's describe/it structure for all test files
Test both success and failure cases in unit and integration tests
Mock process.env in unit tests to test different environment variable scenarios

Files:

  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
🧠 Learnings (37)
📓 Common learnings
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 JSDoc comments for public APIs
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} : Include examples in JSDoc comments when helpful for public APIs
Learnt from: yamcodes
Repo: yamcodes/arkenv PR: 132
File: packages/arkenv/README.md:13-14
Timestamp: 2025-09-09T17:37:19.650Z
Learning: For yamcodes/arkenv project: Runtime support documentation should link to specific examples: Node.js (examples/basic), Bun (examples/with-bun), Vite (examples/with-vite-react-ts).
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 : Keep environment variable schemas readable and TypeScript-like using ArkType syntax
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types
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 : 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: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript
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-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")
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: .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`)
📚 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/**/*.{ts,tsx,js,jsx} : Bun automatically loads .env files, so don't use `dotenv` library

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
  • .changeset/kind-garlics-move.md
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.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/**/*.{ts,tsx,js,jsx} : Bun automatically loads .env files, so don't use the dotenv package

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use `createEnv(schema)` function (or default import as `arkenv`) to create validated environment objects in TypeScript

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • .changeset/wacky-oranges-care.md
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • .changeset/kind-garlics-move.md
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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 : Keep environment variable schemas readable and TypeScript-like using ArkType syntax

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • .changeset/wacky-oranges-care.md
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • .changeset/kind-garlics-move.md
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.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/**/*.{html,ts,tsx,css} : Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild` for bundling

Applied to files:

  • packages/bun-plugin/src/utils.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{test,integration.test}.{ts,tsx} : Mock `process.env` in unit tests to test different environment variable scenarios

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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/**/*.{ts,js} : Use `bun <file>` instead of `node <file>` or `ts-node <file>` for running scripts

Applied to files:

  • packages/bun-plugin/src/utils.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/**/*.{ts,tsx,js,jsx,html,css} : Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild` for bundling

Applied to files:

  • packages/bun-plugin/src/utils.ts
📚 Learning: 2025-12-26T19:27:11.710Z
Learnt from: danciudev
Repo: yamcodes/arkenv PR: 614
File: packages/vite-plugin/src/index.test.ts:641-654
Timestamp: 2025-12-26T19:27:11.710Z
Learning: In packages/vite-plugin/src/**/*.test.ts: The test suite uses `env.test` files (without leading dot) as test fixtures that are manually read by the `readTestConfig` helper function and stubbed into process.env with `vi.stubEnv`, not as files to be read by Vite's loadEnv during tests.

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : For environment schema definition, use ArkType string literal syntax for enumerated values (e.g., "'development' | 'production' | 'test'")

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • .changeset/wacky-oranges-care.md
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/create-env.ts
  • .changeset/kind-garlics-move.md
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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 **/*.{ts,tsx} : Use `ArkEnvError` for environment variable validation errors

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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 ArkType's `type()` function to define schemas in environment variable definitions

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • .changeset/wacky-oranges-care.md
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Provide default values for optional environment variables using ArkType syntax (e.g., 'boolean = false')

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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:

  • packages/bun-plugin/src/utils.ts
  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • .changeset/kind-garlics-move.md
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use ArkEnvError for environment variable errors instead of generic Error types

Applied to files:

  • packages/bun-plugin/src/utils.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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 **/*.{ts,tsx} : Include examples in JSDoc comments when helpful for public APIs

Applied to files:

  • packages/vite-plugin/src/types.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} : Document complex type logic with JSDoc comments

Applied to files:

  • packages/vite-plugin/src/types.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 JSDoc comments for public APIs

Applied to files:

  • packages/vite-plugin/src/types.ts
  • packages/arkenv/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: ArkType validates environment variables at runtime and TypeScript types are inferred from the schema definition

Applied to files:

  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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:

  • packages/vite-plugin/src/types.ts
  • packages/internal/types/src/schema.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/create-env.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{ts,tsx} : Use built-in validators (host, port, url, email) from ArkEnv when available instead of custom ArkType schemas

Applied to files:

  • packages/vite-plugin/src/types.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.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:

  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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:

  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/bun-plugin/src/plugin.test.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/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:

  • packages/internal/types/src/schema.ts
  • packages/arkenv/src/index.ts
  • packages/vite-plugin/src/index.ts
  • packages/arkenv/src/errors.ts
  • packages/arkenv/src/create-env.ts
  • packages/bun-plugin/src/plugin.ts
  • packages/bun-plugin/src/index.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/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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 `bun test` instead of `jest` or `vitest` for running tests

Applied to files:

  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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/bun-plugin/src/utils.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/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.test.{ts,tsx} : Create unit tests with `.test.ts` or `.test.tsx` suffix located alongside source files, testing individual functions and components in isolation with mocked dependencies

Applied to files:

  • packages/bun-plugin/src/utils.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/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.test.ts
📚 Learning: 2025-12-23T07:09:57.130Z
Learnt from: CR
Repo: yamcodes/arkenv PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-12-23T07:09:57.130Z
Learning: Applies to **/*.{test,integration.test}.{ts,tsx} : Use Vitest's `describe`/`it` structure for all test files

Applied to files:

  • packages/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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/bun-plugin/src/utils.test.ts
  • packages/bun-plugin/src/plugin.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} : Use PascalCase for type names (e.g., `ArkEnvError`)

Applied to files:

  • packages/arkenv/src/errors.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 the scoped `$` type system for custom types defined in `scope.ts`

Applied to files:

  • packages/arkenv/src/create-env.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:

  • .changeset/kind-garlics-move.md
🧬 Code graph analysis (4)
packages/bun-plugin/src/utils.ts (2)
packages/internal/types/src/schema.ts (2)
  • SchemaShape (4-4)
  • CompiledEnvSchema (18-18)
packages/arkenv/src/create-env.ts (2)
  • EnvSchema (27-27)
  • createEnv (103-162)
packages/bun-plugin/src/utils.test.ts (1)
packages/bun-plugin/src/utils.ts (1)
  • processEnvSchema (9-22)
packages/vite-plugin/src/index.ts (4)
packages/bun-plugin/src/plugin.ts (1)
  • arkenv (42-53)
packages/internal/types/src/schema.ts (2)
  • CompiledEnvSchema (18-18)
  • SchemaShape (4-4)
packages/arkenv/src/create-env.ts (1)
  • EnvSchema (27-27)
packages/arkenv/src/index.ts (1)
  • EnvSchema (4-4)
packages/arkenv/src/create-env.ts (1)
packages/internal/types/src/schema.ts (2)
  • CompiledEnvSchema (18-18)
  • SchemaShape (4-4)
🪛 ast-grep (0.40.5)
packages/bun-plugin/src/utils.ts

[warning] 39-42: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(
process\\.env\\.${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b,
"g",
)
Note: [CWE-1333] Inefficient Regular Expression Complexity [REFERENCES]
- https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
- https://cwe.mitre.org/data/definitions/1333.html

(regexp-from-variable)


[warning] 44-47: Regular expression constructed from variable input detected. This can lead to Regular Expression Denial of Service (ReDoS) attacks if the variable contains malicious patterns. Use libraries like 'recheck' to validate regex safety or use static patterns.
Context: new RegExp(
process\\.env\\[(["'])${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\1\\],
"g",
)
Note: [CWE-1333] Inefficient Regular Expression Complexity [REFERENCES]
- https://owasp.org/www-community/attacks/Regular_expression_Denial_of_Service_-_ReDoS
- https://cwe.mitre.org/data/definitions/1333.html

(regexp-from-variable)

🪛 LanguageTool
.changeset/wacky-oranges-care.md

[grammar] ~5-~5: Ensure spelling is correct
Context: ... Renamed type: CompiledEnvSchema (was EnvSchemaWithType) Breaking change: The type `EnvSchemaWi...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

⏰ 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). (6)
  • GitHub Check: test-e2e (a11y)
  • GitHub Check: test-e2e (e2e)
  • GitHub Check: test-build (latest)
  • GitHub Check: test-build (lts/*)
  • GitHub Check: test-typesafety
  • GitHub Check: Deploy-Preview
🔇 Additional comments (18)
packages/arkenv/src/index.ts (1)

7-12: LGTM!

The branding consistency update ("arkenv" → "ArkEnv") improves the documentation quality. The JSDoc appropriately documents the main export with a link to the official documentation.

packages/vite-plugin/src/types.ts (1)

4-21: LGTM!

The JSDoc documentation is comprehensive and well-structured, following the coding guidelines for public APIs. The @template descriptions clearly explain the type parameters, and the @see links provide appropriate references to both the official documentation and the original implementation credit.

.changeset/wacky-oranges-care.md (1)

1-7: Verify semver classification for breaking change.

The changeset correctly documents the type rename, but a breaking change (removing/renaming a public type) typically warrants a major version bump rather than minor, per semver conventions.

If @repo/types is an internal package not published to npm or has no external consumers, minor may be acceptable. Otherwise, consider changing to major.

packages/arkenv/src/errors.ts (1)

72-107: Well-documented error class with practical example.

The JSDoc documentation is excellent and follows coding guidelines:

  • Clear description of purpose and behavior
  • Practical @example demonstrating the recommended error handling pattern with instanceof check
  • Uses ArkType's built-in validators (number.port, string.host) per best practices

The Object.defineProperty on line 109 ensures the class name survives minification, which is good practice for error classes.

packages/internal/types/src/schema.ts (1)

6-18: LGTM!

The JSDoc documentation clearly explains the purpose and use case for CompiledEnvSchema:

  • @internal tag appropriately indicates internal usage
  • Explains the type represents a pre-constructed ArkType instance
  • Documents the intended use case (advanced/programmatic scenarios)

This documentation helps distinguish between declarative schemas and pre-compiled type instances, which is valuable for maintainability.

packages/bun-plugin/src/utils.ts (2)

5-22: Well-documented internal utility with appropriate JSDoc.

The @internal marker correctly indicates this is not part of the public API. The implementation is straightforward and the filtering logic aligns with the BUN_PUBLIC_ prefix convention for client-exposed variables.


39-49: Static analysis ReDoS warning is a false positive in this context.

The regex is constructed from environment variable keys defined in the schema, which are controlled by the developer and follow standard naming conventions (alphanumeric + underscore). The escaping on line 41/46 properly handles any special characters. The warning can be safely disregarded.

packages/vite-plugin/src/index.ts (2)

1-1: Type import updated consistently with repository-wide rename.

The import change from EnvSchemaWithType to CompiledEnvSchema aligns with the type rename in @repo/types.


12-50: Comprehensive JSDoc with examples follows coding guidelines.

The documentation includes the @param, @returns, and @example tags with practical usage examples. The overload signatures properly support both EnvSchema<T> for typesafe validation and CompiledEnvSchema for dynamic schemas. Based on learnings, this follows the guideline to use JSDoc comments for public APIs and include examples when helpful.

.changeset/kind-garlics-move.md (1)

1-7: Changeset properly documents the breaking change.

The changeset correctly identifies the removal of processEnvSchema as a breaking change and explains it's now an internal utility. The minor version bump is appropriate since the package is in pre-1.0 development phase. Based on learnings, breaking changes are acceptable in minor version bumps for v0.x.x packages.

packages/bun-plugin/src/plugin.test.ts (2)

2-2: Import updated to align with new module structure.

The import correctly references arkenv from the new ./plugin module, matching the refactored architecture where plugin functionality is now in a dedicated file.


15-46: Tests properly validate the refactored plugin API.

All test cases are updated consistently to use arkenv instead of arkenvPlugin. The tests cover:

  • Function type validation
  • Plugin object structure
  • Successful validation
  • Validation failure

The test coverage appropriately validates the plugin's public contract.

packages/bun-plugin/src/plugin.ts (2)

7-37: Well-documented JSDoc with clear usage examples.

The JSDoc provides comprehensive documentation covering both zero-config and manual configuration modes with code examples. This aligns well with the coding guidelines for public APIs.


38-53: Clean function overloads with proper type constraints.

The overloads correctly handle both CompiledEnvSchema and EnvSchema<T> inputs. The implementation delegates to processEnvSchema and returns a properly typed BunPlugin.

packages/arkenv/src/create-env.ts (3)

3-3: Type import rename looks correct.

The import of CompiledEnvSchema aligns with the type rename from EnvSchemaWithType across the repository.


13-27: Excellent JSDoc documentation for the EnvSchema type.

The JSDoc clearly explains the purpose, usage context, and includes the @template tag. This follows the coding guidelines for documenting public APIs and complex type logic.


91-106: Function overloads correctly updated for type rename.

The overloads properly handle both EnvSchema<T> and CompiledEnvSchema inputs, maintaining backward compatibility while using the renamed type.

packages/bun-plugin/src/index.ts (1)

1-5: Clean barrel export structure, but line 1 import may be redundant.

The re-export on line 3 already makes hybrid available. The separate import on line 1 is only needed because export default cannot directly reference a re-exported binding. This is a valid pattern, though you could alternatively restructure as:

export { arkenv, hybrid } from "./plugin";
export type { ProcessEnvAugmented } from "./types";
export { hybrid as default } from "./plugin";

The current approach is fine and readable.

✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.

@yamcodes
Copy link
Owner

@coderabbitai review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 16, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@yamcodes
Copy link
Owner

@coderabbitai review

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Jan 16, 2026

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@yamcodes yamcodes merged commit 16c6047 into main Jan 16, 2026
16 of 19 checks passed
@yamcodes yamcodes deleted the copilot/add-jsdoc-to-exports branch January 16, 2026 19:50
@arkenv-bot arkenv-bot bot mentioned this pull request Jan 16, 2026
yamcodes pushed a commit that referenced this pull request Jan 16, 2026
This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @arkenv/bun-plugin@0.1.0

### Minor Changes

- #### Refactoring + remove `processEnvSchema` export
_[`#739`](#739)
[`16c6047`](16c6047)
[@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)_

**Breaking change:** We've removed the `processEnvSchema` export from
this library as it's an internal utility.

### Patch Changes

- #### Support for `.mts` and `.cts` extensions
_[`#739`](#739)
[`16c6047`](16c6047)
[@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)_

Updated the Bun plugin to correctly process and load `.mts` and `.cts`
files. This ensures environment variables are properly injected when
using these TypeScript file extensions.

<details><summary>Updated 1 dependency</summary>

<small>

</small>

-   `arkenv@0.9.0`

</details>

## @repo/types@0.1.0

### Minor Changes

- #### Renamed type: `CompiledEnvSchema` (was `EnvSchemaWithType`)
_[`#739`](#739)
[`16c6047`](16c6047)
[@copilot-swe-agent](https://github.com/apps/copilot-swe-agent)_

**Breaking change:** The type `EnvSchemaWithType` has been renamed to
`CompiledEnvSchema`.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

@arkenv/vite-plugin Issues or Pull Requests involving the Vite plugin for ArkEnv arkenv Changes to the `arkenv` npm package. docs Improvements or additions to documentation tests This issue or PR is about adding, removing or changing tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add jsdoc to all exports

2 participants