(v1) Unify error normalization and formatting

.changeset/unified-error-normalization.md

@@ -0,0 +1,18 @@
+---
+"arkenv": major
+---
+
+#### Refactor error system to use normalized `EnvIssue` and add `{ safe: true }` API
+
+Introduce a unified `EnvIssue` type for programmatic access to validation issues via `ArkEnvError.issues`, and add the non-throwing `{ safe: true }` configuration option to `arkenv`.
+
+Error messages now use ANSI colors instead of a bullet-point prefix:
+
+```diff
+- - [PORT] must be a valid port number (was "invalid-port")
++ PORT must be a valid port number (was "invalid-port")
+```
+
+Note: Header (red), variable path (yellow), and received value (cyan) are now styled with ANSI escape codes. Update any test suites asserting on exact error text.
+
+**BREAKING CHANGE**: `ValidationIssue` and `formatInternalErrors` removed. Use `EnvIssue` and `formatIssues` instead.

apps/www/bin/twoslash-mdx.ts

@@ -1,7 +1,7 @@
 // biome-ignore-all lint/suspicious/noConsole: This is a CLI debugging script
 import fs from "node:fs";
 import { createTwoslasher } from "twoslash";
-import { arktypeTwoslashOptions } from "../lib/twoslash-options";
+import { arktypeTwoslashOptions } from "~/lib/twoslash-options";
 
 const mdxPath = process.argv[2];
 if (!mdxPath) {

apps/www/components/page/compatibility-rails.tsx

@@ -9,13 +9,13 @@ import {
 } from "@icons-pack/react-simple-icons";
 import { Square } from "lucide-react";
 import type { JSX } from "react";
+import { ArkTypeIcon } from "~/components/icons/arktype-icon";
+import { JoiIcon } from "~/components/icons/joi-icon";
+import { SolidStartIcon } from "~/components/icons/solid-start-icon";
+import { TypiaIcon } from "~/components/icons/typia-icon";
+import { ValibotIcon } from "~/components/icons/valibot-icon";
+import { VinxiIcon } from "~/components/icons/vinxi-icon";
 import { cn } from "~/lib/utils";
-import { ArkTypeIcon } from "../icons/arktype-icon";
-import { JoiIcon } from "../icons/joi-icon";
-import { SolidStartIcon } from "../icons/solid-start-icon";
-import { TypiaIcon } from "../icons/typia-icon";
-import { ValibotIcon } from "../icons/valibot-icon";
-import { VinxiIcon } from "../icons/vinxi-icon";
 
 type RailItem = {
 	name: string;

apps/www/components/ui/popover.tsx

@@ -1,7 +1,7 @@
 "use client";
 import * as PopoverPrimitive from "@radix-ui/react-popover";
 import * as React from "react";
-import { cn } from "../../lib/cn";
+import { cn } from "~/lib/cn";
 
 const Popover = PopoverPrimitive.Root;
 

apps/www/content/docs/arkenv/options.mdx

@@ -87,3 +87,32 @@ const env = arkenv(
 // env.PORT  → 3000 (default applied)
 // env.DEBUG → false (default applied)
 ```
+
+## `safe`
+
+Whether to return a safe result object instead of throwing an error on validation failure. Defaults to `false`.
+
+When enabled, the function returns an object with `{ success: true, data }` or `{ success: false, issues }`.
+
+```ts twoslash
+import arkenv from "arkenv";
+// ---cut---
+const result = arkenv(
+  { PORT: "number" },
+  { safe: true, env: { PORT: "invalid" } }
+);
+
+if (!result.success) {
+  console.error("Validation failed:", result.issues);
+} else {
+  console.log("Port is:", result.data.PORT);
+}
+```
+
+:::warn Not supported in Integrations
+The `safe: true` option is purposefully omitted from the configuration options of framework integrations (like `@arkenv/vite-plugin`, `@arkenv/nextjs`, etc.).
+
+Framework integrations rely on injecting the raw, validated environment variables into the build process. If `safe: true` were enabled, a validation failure would result in the plugin silently injecting the `{ success: false, issues }` wrapper object into your application bundle instead of crashing the build, leading to broken downstream behavior.
+
+If you need to handle validation failures programmatically without failing the build, you should invoke `arkenv()` manually rather than using an automated bundler plugin.
+:::

apps/www/content/docs/arkenv/quickstart.mdx

@@ -164,6 +164,25 @@ const dbConfig = {
 console.log(`Connecting to ${dbConfig.host}:${dbConfig.port}...`);
 ```
 
+## Safe parsing (Non-throwing)
+
+By default, calling `arkenv()` will throw an `ArkEnvError` if validation fails. If you prefer to handle validation issues without catching thrown exceptions, you can pass the `{ safe: true }` option instead. It returns a result object containing either the successfully parsed data or an array of validation issues.
+
+```ts title="env.ts" twoslash
+import { arkenv } from 'arkenv';
+
+const result = arkenv({
+  PORT: "number = 3000",
+}, { safe: true });
+
+if (result.success) {
+  console.log("Validated config:", result.data);
+  // result.data.PORT is guaranteed to be a number here
+} else {
+  console.error("Validation failed:", result.issues);
+}
+```
+
 ## Next steps
 
 <Cards>

docs/CONTEXT.md

@@ -176,6 +176,15 @@ pnpm run test:e2e                     # E2E tests
 - Run `pnpm release` after merging PRs to publish packages
 - Only packages in `packages/` are published to npm
 
+## Design Decisions
+
+**Split Parsing Engines (ArkType vs Standard Schema):**
+
+- ArkEnv maintains two distinct parsing engines: `src/arktype/index.ts` and `src/parse-standard.ts`.
+- Despite visual similarities, they are strictly isolated to guarantee the `arkenv/standard` module boundary remains "ArkType-free".
+- Unifying them would force bundlers to trace static imports and drag ArkType into the dependency tree of Standard Schema users, violating the zero-dependency goal.
+- We prioritize optimal tree-shaking, bundle size isolation, and decoupling over dogmatic DRYness.
+
 ## Domain context
 
 **Environment Variable Validation:**
@@ -225,8 +234,12 @@ pnpm run test:e2e                     # E2E tests
 - Leverages ArkType's `type.infer` and `type.validate` utilities
 - Typesafe environment object returned from `arkenv`
 
-**Error Handling:**
+**Error Handling & Vocabulary:**
 
+- **Issue vs. Error Distinction**: ArkEnv strictly differentiates between an "Issue" and an "Error".
+  - **Issue (`EnvIssue`)**: A single, isolated validation failure on a specific environment variable.
+  - **Error (`ArkEnvError`)**: The overarching runtime exception that is thrown when validation fails. It contains an array of `EnvIssue`s.
+- Functions dealing with individual failures should use "Issue" (e.g., `formatIssues`), while functions dealing with the final halting exception should use "Error" (e.g., `ArkEnvError`).
 - `ArkEnvError` extends `Error` and formats ArkType validation errors
 - Errors include variable names and expected types
 - Fail-fast approach: app won't start if validation fails

docs/adr/0010-bundle-isolation-over-dryness.md

@@ -0,0 +1,27 @@
+# 10. Bundle Isolation trumps DRYness
+
+Date: 2026-06-21
+
+## Status
+
+Accepted
+
+## Context
+
+ArkEnv operates as a zero-dependency environment variable parser. It uses ArkType as its primary validation engine (`arkenv`), while also offering a completely separate entry point (`arkenv/standard`) that leverages Standard Schema 1.0 (for users preferring Zod, Valibot, etc.).
+
+During the refactoring to a single core repository with multiple internal exports, a code review raised concerns about code duplication between `src/arktype/index.ts` and `src/parse-standard.ts`. Both files implement similar logic for parsing objects, extracting issue metadata, and formatting validation results. The suggestion was to "aggressively unify or codeshare" these implementations to abide by the DRY (Don't Repeat Yourself) principle.
+
+However, sharing utilities across the core ArkType engine and the Standard Schema engine introduces hidden module graph entanglements. Bundlers like Webpack, Rollup, and esbuild often rely on static imports for tree-shaking. A single shared `utils.ts` file imported by both entry points can easily trick the bundler's heuristics into statically tracing the dependency tree back to `arktype`. This would drag the entire 50kb+ ArkType AST engine into the production bundle of users who only wanted to use `arkenv/standard` with Zod.
+
+## Decision
+
+We intentionally duplicate parsing, formatting, and issue-mapping logic across the `arktype` and `standard` engine implementations to maintain an airtight module boundary. **Bundle isolation strictly trumps DRYness across core/standard boundaries.**
+
+We will not create shared abstractions or utility files that bridge these two domains. The small maintenance cost of duplicated internal logic is a worthwhile trade-off to guarantee that `arkenv/standard` users never incur a bundle size penalty from ArkType.
+
+## Consequences
+
+- The footprint of `@arkenv/standard` remains strictly minimal and fully decoupled from ArkType.
+- Contributors must be aware that fixing a bug in the error extraction logic for ArkType may require a mirrored fix in the Standard Schema logic.
+- Future code reviews raising concerns about DRYness between these files should be directed to this ADR.