chore: tighten path-fix comments — one-line WHYs, no line-number rot

Following an audit pass: comments narrating WHAT (`posix so forward-slash
on Windows`) deleted; multi-line blocks compressed to one-liners; rot
phrases removed (`this PR`, hardcoded `build.ts:1031`, "during initial
review"); JSDoc shrunk; backslash-acceptance rationale + Windows-specific
specifier surprise preserved as one-liners.

No behavior change. 421/477 vitest, 33/33 vxrn, 9/9 resolve, lint 0/0.

Author: YevheniiKotyrlo

packages/compiler/src/transformSWC.ts

@@ -12,8 +12,7 @@ import { configuration } from './configure'
 import { asyncGeneratorRegex, debug, parsers, runtimePublicPath } from './constants'
 import type { Options } from './types'
 
-// POSIX-only sentinel — Vite plugin context hands us forward-slash ids; the
-// other caller (patches.ts) hands native paths, so we normalize id below.
+// POSIX-only — id is normalized below
 const ignoreId = /node_modules\/(\.vite|vite)\//
 
 export async function transformSWC(

packages/one/src/cli/build.ts

@@ -547,7 +547,6 @@ export async function build(args: {
                       chunkInfo.name,
                       Path.extname(chunkInfo.name)
                     )
-                    // posix so nested-chunk fileNames stay forward-slash on Windows
                     return posix.join(dir, `${name}-[hash].cjs`)
                   },
                   assetFileNames: (assetInfo) => {
@@ -602,7 +601,6 @@ export async function build(args: {
       const outChunks = middlewareBuildInfo.output.filter((x) => x.type === 'chunk')
       const chunk = outChunks.find((x) => x.facadeModuleId === fullPath)
       if (!chunk) throw new Error(`internal err finding middleware`)
-      // posix so manifest entry stays forward-slash on Windows
       builtMiddlewares[middleware.file] = posix.join(
         outDir,
         'middlewares',

packages/one/src/metro-config/getViteMetroPluginOptions.ts

@@ -233,8 +233,7 @@ export function getViteMetroPluginOptions({
         [
           'one/babel-plugin-one-router-metro',
           {
-            // both values are inlined by babel into metro-entry.js as JS module
-            // specifiers — Metro's isRelativeImport regex rejects `..\foo` on Windows
+            // inlined as JS module specifiers; Metro's isRelativeImport rejects `..\foo` on Windows
             ONE_ROUTER_APP_ROOT_RELATIVE_TO_ENTRY: normalizePath(
               path.relative(
                 path.dirname(metroEntryPath),

packages/one/src/utils/posixPathContract.test.ts

@@ -1,8 +1,4 @@
-// POSIX path contract tests — locks in the cross-platform behavior of the
-// Node primitives this PR's fixes depend on. If a future Node version
-// changes any of these, the failing test surfaces the regression before
-// the framework breaks on Windows again.
-
+// Lock in cross-platform output of Node primitives — a regression here is a future Windows break.
 import { posix } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { describe, expect, it } from 'vitest'
@@ -41,9 +37,7 @@ describe('pathToFileURL — canonical file:// URL specifier', () => {
   })
 
   it('round-trips through JSON.stringify without backslashes leaking in', () => {
-    // The motivating defect: emitting `import "${absolutePath}"` puts
-    // backslashes into the generated JS source on Windows. A file:// URL
-    // does not.
+    // motivating defect: bare absolute path puts backslashes in emitted JS on Windows
     const href = pathToFileURL('/proj/src/setup.ts').href
     const stringified = JSON.stringify(href)
     expect(stringified.includes('\\\\')).toBe(false)
@@ -56,9 +50,7 @@ describe('Vite normalizePath — converts on Windows, no-op on POSIX', () => {
   })
 
   it('converts backslashes (Windows-shaped input)', () => {
-    // normalizePath only converts on Windows hosts. We assert the contract
-    // shape — on Windows: backslashes converted; on POSIX: passthrough
-    // because backslash is a valid filename character.
+    // Windows converts; POSIX passthrough (backslash is a valid filename char there)
     const input = String.raw`C:\proj\src\foo.tsx`
     const out = normalizePath(input)
     if (process.platform === 'win32') {
@@ -70,10 +62,7 @@ describe('Vite normalizePath — converts on Windows, no-op on POSIX', () => {
 })
 
 describe('toServerOutputPath — cross-platform parity', () => {
-  // toServerOutputPath uses path.posix.join + replace(/\\/g, '/') so the
-  // output must be byte-identical across platforms. The fact that we
-  // converted from Vite's normalizePath to this implementation was driven
-  // by a Linux Docker test failure during initial review.
+  // posix.join + backslash-replace (not normalizePath) — output must be byte-identical across platforms
   const cases: Array<[string, string, string]> = [
     ['foo.js', 'dist', 'dist/server/foo.js'],
     ['subdir/bar.js', 'dist', 'dist/server/subdir/bar.js'],
@@ -93,11 +82,7 @@ describe('toServerOutputPath — cross-platform parity', () => {
 })
 
 describe('seed bug regression — SSR loader path doubling on Windows', () => {
-  // Direct regression test for the specific shape that hit production:
-  // build.ts:1031 minted `dist\server\assets\time_ssr-XXX.js` (native sep);
-  // oneServe.ts:168 then ran `.includes('dist/server')` on it (forward slash);
-  // the check missed; `join('./','dist/server','dist\\server\\...')` was
-  // called; result was `dist\server\dist\server\...` — passed to await import().
+  // serverJsPath minted native sep; oneServe `.includes('/server')` missed; prefix doubled, await import() crashed
   it('does not double-prefix backslash-shaped server-output input', () => {
     const windowsShapedInput = String.raw`dist\server\assets\time_ssr-COqAsxju.js`
     expect(toServerOutputPath(windowsShapedInput, 'dist')).toBe(

packages/one/src/utils/toServerOutputPath.test.ts

@@ -22,10 +22,7 @@ describe('toServerOutputPath', () => {
   })
 
   it('treats backslashes as separators on every platform (the Windows path-doubling case)', () => {
-    // Simulates what `path.join` produces on Windows after the first prefix
-    // has been added by an earlier caller. The function must convert
-    // backslashes to forward slashes here regardless of host OS so the
-    // sentinel check matches and the prefix isn't doubled.
+    // already-prefixed backslash input — must normalize before sentinel check
     expect(toServerOutputPath('dist\\server\\assets\\loader-abc.js', 'dist')).toBe(
       'dist/server/assets/loader-abc.js'
     )
@@ -44,8 +41,7 @@ describe('toServerOutputPath', () => {
   })
 
   it('does not false-positive on inputs that contain ${outDir}/server as a substring but are not rooted under it', () => {
-    // Without startsWith, `.includes('dist/server')` would match this input
-    // and skip the prefix — incorrectly treating it as already-prefixed.
+    // startsWith required: .includes would match foo/dist/server/x and wrongly skip
     expect(toServerOutputPath('foo/dist/server/bar.js', 'dist')).toBe(
       'dist/server/foo/dist/server/bar.js'
     )

packages/one/src/utils/toServerOutputPath.ts

@@ -1,10 +1,6 @@
 import { posix } from 'node:path'
 
-/**
- * Idempotent: prepends `${outDir}/server/` to `input` if not already rooted there.
- * Output is forward-slash on every platform. Backslash input is accepted (legacy
- * callers may hand us `path.join`-shaped strings).
- */
+// Idempotent. Returns forward-slash output. Accepts backslash input (legacy path.join-shaped callers).
 export function toServerOutputPath(input: string, outDir: string): string {
   const normalized = input.replace(/\\/g, '/')
   const prefix = `${outDir}/server/`

packages/one/src/vite/one.ts

@@ -251,9 +251,7 @@ export function one(options: One.PluginOptions = {}): PluginOption {
             } catch {}
           }
 
-          // for bare imports, map real path → node_modules path. resolved.id
-          // is POSIX (Vite normalizes); realpathSync/join return native on
-          // Windows, so normalize both sides before the startsWith check.
+          // resolved.id is POSIX (Vite's getRealPath normalizes); realpathSync returns native — normalize both
           const realPkgDir = normalizePath(realpathSync(nmPkgDir))
           if (resolved.id.startsWith(realPkgDir)) {
             const relativePart = resolved.id.slice(realPkgDir.length)

packages/one/src/vite/plugins/virtualEntryPlugin.ts

@@ -87,8 +87,7 @@ function getSetupFileImport(
   if (!setupFile)
     return { importStatement: '', promiseDeclaration: '', promiseVarName: '' }
 
-  // file:// URL is the canonical specifier shape; bare Windows path with
-  // backslashes is not (mirrors the native sibling in createNativeDevEngine.ts)
+  // file:// URL is canonical; bare Windows absolute path has backslashes (mirrors createNativeDevEngine.ts)
   const resolvedSetupFile = root
     ? pathToFileURL(resolve(root, setupFile)).href
     : setupFile

packages/vxrn/src/utils/createNativeDevEngine.ts

@@ -559,8 +559,7 @@ const VIRTUAL_NATIVE_ENTRY = 'virtual:native-entry'
 
 function nativeVirtualEntryPlugin(root: string, opts?: { dev?: boolean }): Plugin {
   const isDev = opts?.dev !== false
-  // absolute path so `import.meta.glob('./app/...')` resolves; forward-slash
-  // for Vite/rolldown module-graph convention
+  // absolute for import.meta.glob resolution; forward-slash for module-graph convention
   const resolvedId = normalizePath(resolve(root, '__virtual-native-entry.tsx'))
 
   // read config passed from One's vite plugin via globalThis

packages/vxrn/src/utils/patches.test.ts

@@ -4,8 +4,7 @@ import { mkdtemp, rm, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-// 'junction' avoids the admin requirement for 'dir' symlinks on Windows;
-// ignored on POSIX (per Node fs docs)
+// 'junction' avoids Windows admin requirement; type ignored on POSIX
 
 // mock heavy deps that aren't needed for patch resolution tests
 vi.mock('@vxrn/compiler', () => ({ transformSWC: vi.fn() }))