refactor(www): improve JSDoc link processing

[yamcodes]

• Convert {@link} tags to Markdown links
• Normalize newlines in JSDoc content

Closes #698

Summary by CodeRabbit

• Bug Fixes
  • Improved hover documentation rendering by properly formatting reference links as Markdown or inline code and normalizing whitespace for cleaner display.

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8a56182

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[coderabbitai]

Walkthrough

Updates JSDoc hover documentation rendering by reformatting @link annotations to Markdown links or inline code and normalizing whitespace in hover docs. Reorders an export declaration in the arkenv package index without semantic changes.

Changes

Cohort / File(s)	Summary
Hover Documentation Transformation apps/www/source.config.ts	Adds text transformation for hover docs that converts @link annotations to Markdown links (for HTTP targets) or inline code (for non-HTTP), collapses single newlines into spaces, normalizes multiple newlines to single blank lines, and trims whitespace. Runs before existing text whitelisting logic. Addresses issue where JSDoc appears cut off or poorly formatted.
Export Declaration Reordering packages/arkenv/src/index.ts	Relocates EnvSchema export declaration to after its corresponding import. No functional or semantic changes; declaration order adjustment only.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Fix Twoslash issues #664: Modifies apps/www/source.config.ts Twoslash/hover-processing logic for transformer and hover doc rendering
• Reduce repetitive CTA for reading the docs #679: Updates MDX/MD processing pipeline in apps/www/source.config.ts with remark-directive and rehype optimizations

Suggested labels

docs, www

Poem

🐰 Hover docs now gleam and shine,
Links reformat, whitespace align!
From @link to markdown's way,
JSDoc renders crisp today!

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The PR includes one out-of-scope change: reordering type exports in packages/arkenv/src/index.ts, unrelated to the JSDoc link processing objective.	Remove the type export reordering from packages/arkenv/src/index.ts or move it to a separate PR focused on code organization.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'refactor(www): improve JSDoc link processing' directly describes the main change—improving JSDoc link processing in the www app.
Linked Issues check	✅ Passed	The PR addresses all coding requirements from issue #698: converts {@link} tags to Markdown links, normalizes newlines, and fixes JSDoc rendering problems.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7aea140 and 8a56182.

📒 Files selected for processing (2)

• apps/www/source.config.ts
• packages/arkenv/src/index.ts

🧰 Additional context used

📓 Path-based instructions (4)

**/*.{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:

• apps/www/source.config.ts
• packages/arkenv/src/index.ts

apps/www/**/*.{ts,tsx,js,jsx}

📄 CodeRabbit inference engine (apps/www/.cursor/rules/posthog-integration.mdc)

apps/www/**/*.{ts,tsx,js,jsx}: If using TypeScript, use an enum to store feature flag names. If using JavaScript, store feature flag names as strings to an object declared as a constant to simulate an enum. Use UPPERCASE_WITH_UNDERSCORE naming convention for enum/const object members.
If a custom property for a person or event is referenced in two or more files or two or more callsites in the same file, use an enum or const object with UPPERCASE_WITH_UNDERSCORE naming convention, similar to feature flags.

Files:

• apps/www/source.config.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

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

🧠 Learnings (14)

📓 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

📚 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/arkenv/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/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: Applies to packages/arkenv/**/*.ts : Use ArkType's `type()` function to define schemas in environment variable definitions

Applied to files:

• 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: 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/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: 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/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: 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/arkenv/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/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: 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/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: Applies to packages/arkenv/**/*.ts : Leverage ArkType's type inference for TypeScript types instead of manual type definitions

Applied to files:

• 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: Applies to packages/arkenv/**/*.ts : Use the scoped `$` type system for custom types defined in `scope.ts`

Applied to files:

• packages/arkenv/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/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/arkenv/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/arkenv/src/index.ts

⏰ 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: Deploy-Preview
• GitHub Check: test-build (latest)
• GitHub Check: test-typesafety
• GitHub Check: test-build (lts/*)

🔇 Additional comments (2)

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

3-4: LGTM - Minor organizational improvement.

Grouping the EnvSchema export with its import from the same module improves file organization.

apps/www/source.config.ts (1)

120-135: The JSDoc link transformation is correctly implemented.

The code properly handles all JSDoc @link format variants. When custom text is provided (e.g., {@link ArkEnvError | error}), showing the text rather than the symbol name is intentional behavior, as evidenced by actual usage in the codebase where developers explicitly provide custom text when they want different display text. For symbol-only links (e.g., {@link createEnv}), the symbol name is used as expected. HTTP links render as Markdown with proper text/target handling.

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 Gitleaks (8.30.0)

apps/www/source.config.ts

panic: allocator_unix: failed to reserve memory: cannot allocate memory

goroutine 1 [running]:
github.com/wasilibs/wazero-helpers/allocator.alloc(0x1911020?, 0x100000000)
/Users/zrice/Go/pkg/mod/github.com/wasilibs/wazero-helpers@v0.0.0-20240620070341-3dff1577cd52/allocator/nonmoving_unix.go:33 +0x10e
github.com/tetratelabs/wazero/experimental.MemoryAllocatorFunc.Allocate(0xa84539?, 0xd4ac60?, 0x47d43a?)
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/experimental/memory.go:28 +0x1c
github.com/tetratelabs/wazero/internal/wasm.NewMemoryInstance(0xc00010fbc0, {0x7fdf2ab1a000?, 0xe87630?}, {0xf90c48, 0xc00012f600})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/memory.go:78 +0xab
github.com/tetratelabs/wazero/internal/wasm.(*ModuleInstance).buildMemory(0xc000186f00, 0xc0001f71e0, {0x7fdf2ab1a000?, 0xe87630?})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/module.go:653 +0x4c
github.com/tetratelabs/wazero/internal/wa

... [truncated 302 characters] ...

1e0, {0xf8a300, 0xc000238a80}, 0x0?, {0xe18d1d?, 0x0?}, 0x0?, {0x1932260, 0x0, 0x0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/store.go:327 +0x5a
github.com/tetratelabs/wazero.(*runtime).InstantiateModule(0xc0002398c0, {0xf8a300, 0xc000238a80}, {0xf8e7e0, 0xc00026c700}, {0xf92da0, 0xc0002841e0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/runtime.go:337 +0x1e5
github.com/tetratelabs/wazero.(*runtime).InstantiateWithConfig(0xc0002398c0, {0xf8a300, 0xc000238a80}, {0x1528cd0?, 0xd45020?, 0xe87630?}, {0xf92da0, 0xc0002841e0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/runtime.go:302 +0x74
github.com/wasilibs/go-re2/internal.init.0()
/Users/zrice/Go/pkg/mod/github.com/wasilibs/go-re2@v1.9.0/internal/re2_wazero.go:184 +0x39c

packages/arkenv/src/index.ts

panic: allocator_unix: failed to reserve memory: cannot allocate memory

goroutine 1 [running]:
github.com/wasilibs/wazero-helpers/allocator.alloc(0x1911020?, 0x100000000)
/Users/zrice/Go/pkg/mod/github.com/wasilibs/wazero-helpers@v0.0.0-20240620070341-3dff1577cd52/allocator/nonmoving_unix.go:33 +0x10e
github.com/tetratelabs/wazero/experimental.MemoryAllocatorFunc.Allocate(0xa84539?, 0xd4ac60?, 0x47d43a?)
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/experimental/memory.go:28 +0x1c
github.com/tetratelabs/wazero/internal/wasm.NewMemoryInstance(0xc000119d10, {0x7f2f84e66000?, 0xe87630?}, {0xf90c48, 0xc00014d580})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/memory.go:78 +0xab
github.com/tetratelabs/wazero/internal/wasm.(*ModuleInstance).buildMemory(0xc000150f00, 0xc0001d11e0, {0x7f2f84e66000?, 0xe87630?})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/module.go:653 +0x4c
github.com/tetratelabs/wazero/internal/wa

... [truncated 302 characters] ...

060, {0xf8a300, 0xc000238630}, 0x0?, {0xe18d1d?, 0x0?}, 0x0?, {0x1932260, 0x0, 0x0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/internal/wasm/store.go:327 +0x5a
github.com/tetratelabs/wazero.(*runtime).InstantiateModule(0xc000239470, {0xf8a300, 0xc000238630}, {0xf8e7e0, 0xc000252680}, {0xf92da0, 0xc00026a1e0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/runtime.go:337 +0x1e5
github.com/tetratelabs/wazero.(*runtime).InstantiateWithConfig(0xc000239470, {0xf8a300, 0xc000238630}, {0x1528cd0?, 0xd45020?, 0xe87630?}, {0xf92da0, 0xc00026a1e0})
/Users/zrice/Go/pkg/mod/github.com/tetratelabs/wazero@v1.9.0/runtime.go:302 +0x74
github.com/wasilibs/go-re2/internal.init.0()
/Users/zrice/Go/pkg/mod/github.com/wasilibs/go-re2@v1.9.0/internal/re2_wazero.go:184 +0x39c

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/arkenv@703

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

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

commit: 8a56182

[arkenv-bot]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (Asia/Almaty)
arkenv	Ready	Preview, Comment	Jan 6 2026, 10:47 PM (Asia/Almaty)