@bakery-framework/core 2.0.0-alpha.8 → 2.0.0-rc.1

package/src/compiler/compiler.ts

@@ -20,13 +20,13 @@ const RX_IMPORT =
  * evaluation.
  *
  * This used to be a top-level `await` reading `<cwd>/package.json`, which put a
- * filesystem read on the boot path of every process that loads this module —
+ * filesystem read on the boot path of every process that loads this module,
  * and `handlers/assets/ts.ts` imports it, so that is every worker and every dev
  * restart. The value it produces is needed only when something actually
  * compiles; a production process serving out of a warm compile cache never
  * needs it at all.
  *
- * Memoised as a promise, not a value, so two concurrent first compiles share
+ * Memoized as a promise, not a value, so two concurrent first compiles share
  * one read instead of racing to do it twice.
  */
 let definesPromise: Promise<MapOf<string>> | null = null
@@ -37,8 +37,7 @@ async function buildDefines(): Promise<MapOf<string>> {
     const file = await Bun.file(`${process.cwd()}/package.json`).json()
     if (file?.version) bakeryVersion = file.version
   } catch {
-    // No package.json in cwd, or it is unreadable. The version is cosmetic —
-    // it lands in a banner and a build define — so the default above stands.
+    // No package.json in cwd, or it is unreadable. The version is cosmetic (    // it lands in a banner and a build define), so the default above stands.
   }
 
   return {
@@ -80,7 +79,13 @@ function nextVirtualId(): string {
 }
 
 function preprocessImports(source: string, filePath: fs.AbsolutePath): string {
-  const fileDir = fs.resolve(filePath)
+  // The file's **directory**, not the file. A relative import resolves against
+  // the directory containing the importer, and resolving against the path
+  // itself produced `…/src/entry.ts/a.css`, which exists nowhere, so every
+  // `import './x.css'` from a compiled module registered a virtual asset that
+  // could only 404. It has been wrong since before the workspace split, with
+  // no test and neither app using the feature.
+  const fileDir = fs.dirname(filePath)
 
   const matches = [...source.matchAll(RX_IMPORT)]
 
@@ -91,7 +96,7 @@ function preprocessImports(source: string, filePath: fs.AbsolutePath): string {
 
     // The key is the bare id, never the `/_virtual/` URL. Storing the full URL
     // meant getKey() returned an already-prefixed value that got prefixed again
-    // on the next compile — which both threw a StringCache collision and left
+    // on the next compile, which both threw a StringCache collision and left
     // VirtualAssetHandler (which looks up by bare id) unable to resolve it.
     const id =
       Strings.getKey(assetPath) || `${Date.now()}_${nextVirtualId()}.${ext}`
@@ -113,15 +118,15 @@ function preprocessImports(source: string, filePath: fs.AbsolutePath): string {
  * Compile `source`, naming `path` so a failure can say where it happened.
  *
  * The two branches are not symmetric on purpose. Without a path there is no
- * file to name and no caller that can render a 500 — the Vue plugin compiles
- * fragments of an SFC it has already parsed — so a failure logs and hands the
+ * file to name and no caller that can render a 500 (the Vue plugin compiles
+ * fragments of an SFC it has already parsed), so a failure logs and hands the
  * source back. With a path the failure is a served request, and the answer is
  * `null`: `TSHandler` turns that into the 500 it has always had a branch for.
  *
  * It used to be neither. The transpiler was wrapped only on the pathless
  * branch, so a syntax error in a `.ts` asset threw straight past `compile()`,
- * past `TSHandler` — leaving its `'Compilation Failed'` arm permanently
- * unreachable — and into the worker's catch-all, which printed
+ * past `TSHandler` (leaving its `'Compilation Failed'` arm permanently
+ * unreachable), and into the worker's catch-all, which printed
  * `Unhandled Server Error: <message>` with no file and no line while the client
  * got `An unexpected error occurred.` A total blackout for a one-character typo.
  */
@@ -149,8 +154,7 @@ export async function compileText(source: string, path?: fs.AbsolutePath) {
 
   if (failed) {
     // `errorWithPosition`, not `errorMsg`: the thrown `BuildMessage` has no
-    // stack, so `errorMsg` degrades to the bare message and the line number —
-    // the only thing that makes this actionable — is dropped. The file comes
+    // stack, so `errorMsg` degrades to the bare message and the line number (    // the only thing that makes this actionable) is dropped. The file comes
     // from `{file}`; the diagnostic's own `position.file` is `input.ts`,
     // because `transform()` was handed a string.
     compLog.COMPILE_FAIL({ file: path, error: errorWithPosition(failed) })
@@ -165,7 +169,7 @@ export async function compileText(source: string, path?: fs.AbsolutePath) {
   // relative directory imports went second, once `ts.test.ts` pinned that the
   // handler already resolves `/lib`, `/lib.js` and their nested forms to the
   // directory's index server-side. Resolution belongs to the import map and
-  // the handlers — the compiler only transpiles.
+  // the handlers: the compiler only transpiles.
   return await PluginHooks.onCompile(transformed!, path)
 }
 
@@ -190,7 +194,7 @@ type CompileResult = {
  * `export default …` and nothing else.
  *
  * Not all CJS: `exports.greet = …` is statically analysable and Bun emits a real
- * named export for it. It is the whole-object form — `module.exports = { … }` —
+ * named export for it. It is the whole-object form: `module.exports = { … }`,
  * whose members cannot be known without running the module, and that is the one
  * that breaks.
  *
@@ -208,7 +212,7 @@ type CompileResult = {
 /**
  * Bun's CJS wrapper, in a spelling minification cannot destroy.
  *
- * The obvious check — `content.includes('__commonJS')` — held in dev and
+ * The obvious check: `content.includes('__commonJS')`: held in dev and
  * silently never matched in PROD, where minification renames the helper to a
  * single letter. The consequence was the worst kind of split: named imports
  * of CJS packages worked all through development and broke only in the
@@ -220,7 +224,7 @@ const RX_CJS_WRAPPER = /\{\s*exports\s*:\s*\{\s*\}\s*\}/
 /**
  * A `module.exports = { … }` assignment, whatever the module variable is
  * called after minification (`n.exports={…}`). The helper's own
- * `mod.exports);` never matches — no `= {` follows it.
+ * `mod.exports);` never matches: no `= {` follows it.
  */
 const RX_MODULE_EXPORTS = /[A-Za-z_$][\w$]*\.exports\s*=\s*\{/g
 
@@ -241,7 +245,7 @@ export function isCjsDefaultOnly(content: string): boolean {
  * A bundle consisting of nothing but a non-empty `export { … }` list.
  *
  * Such a file names bindings that were never declared, so every one of them is
- * a `ReferenceError` the moment the browser evaluates it — and `Bun.build`
+ * a `ReferenceError` the moment the browser evaluates it, and `Bun.build`
  * reports it as **`success: true` with zero diagnostics**.
  *
  * The cause is `sideEffects`, and it is not specific to one package. When the
@@ -260,11 +264,11 @@ export function isCjsDefaultOnly(content: string): boolean {
  * `["./dist/attach-styles.js", "./dist/assets/*.css.js"]`, so its barrel
  * bundles to 3,549 bytes of pure export list and throws `AggregateError: 189
  * errors` on import. Most modern libraries set `sideEffects: false`, so any
- * re-export barrel among them is a candidate — this is a wide class, not a
+ * re-export barrel among them is a candidate. This is a wide class, not a
  * single broken package.
  *
- * `bundleReExportShim` repairs it; this only recognises it. `export {}` on its
- * own is a legal empty module and is not flagged — the list has to name
+ * `bundleReExportShim` repairs it; this only recognizes it. `export {}` on its
+ * own is a legal empty module and is not flagged: the list has to name
  * something for the file to be self-contradictory.
  */
 export function isEmptyExportList(content: string): boolean {
@@ -280,8 +284,8 @@ export function isEmptyExportList(content: string): boolean {
  *
  * The `sideEffects` drop described on {@link isEmptyExportList} keys on the
  * *entry* being inside the offending package. Re-exporting the very same file
- * from a module that is not — the shim lands in `.cache/`, which is never
- * inside `node_modules` — leaves the tree-shaker with an entry it has no
+ * from a module that is not: the shim lands in `.cache/`, which is never
+ * inside `node_modules`: leaves the tree-shaker with an entry it has no
  * manifest for, and the imports survive. Measured on `@vue-material/core`:
  * 3,549 bytes of husk becomes a 428,470-byte bundle with all 189 exports.
  *
@@ -290,16 +294,16 @@ export function isEmptyExportList(content: string): boolean {
  * than a no-op. So: try with it, fall back to without.
  *
  * **Every installed package is `external`, and that is load-bearing rather than
- * an optimisation.** Left to itself the shim inlines the whole reachable tree —
+ * an optimization.** Left to itself the shim inlines the whole reachable tree:
  * `@vue-material/core` came out at 428KB with `vue` baked in, and `vue` is a
  * *peer* dependency the app resolves for itself. Two Vue runtimes in one page
  * is not a size problem, it is broken reactivity and a duplicated component
- * registry. Externalised, each dependency stays a bare specifier that the
+ * registry. Externalized, each dependency stays a bare specifier that the
  * import map sends to its own `/_nm/<dep>`, so there is exactly one copy of
  * each; the same bundle drops to 260KB.
  *
- * Externalising *installed packages* specifically, rather than Bun's
- * `packages: 'external'`, because that switch also externalises `node:*` —
+ * Externalizing *installed packages* specifically, rather than Bun's
+ * `packages: 'external'`, because that switch also externalizes `node:*`,
  * turning a builtin Bun would otherwise polyfill for the browser into a bare
  * import nothing can resolve.
  */
@@ -324,7 +328,7 @@ async function bundleReExportShim(
     if (writeErr) return null
 
     // Wrapped, because naming a `default` the package does not export is a
-    // *throw* from `Bun.build`, not a `success: false` — and that throw is the
+    // *throw* from `Bun.build`, not a `success: false`, and that throw is the
     // expected outcome of the first attempt for any package without one.
     const [buildErr, build] = await Try.catch(() =>
       Bun.build({
@@ -356,7 +360,7 @@ const RESERVED_EXPORT_NAMES = new Set(['default', '__esModule'])
  * How long the export probe may take before it is killed.
  *
  * Generous, because it pays a process start and a module evaluation, and it runs
- * once per package — the result is cached with the bundle. Short enough that a
+ * once per package: the result is cached with the bundle. Short enough that a
  * package which hangs on import costs a pause rather than a wedged server.
  */
 const CJS_PROBE_TIMEOUT_MS = 5_000
@@ -421,7 +425,7 @@ function objectLiteralKeys(src: string, open: number): string[] | null {
 
     if (c === ':') {
       take(i)
-      // `{ a: expr, b }` — the value is skipped wholesale so a comma inside it
+      // `{ a: expr, b }`. The value is skipped wholesale so a comma inside it
       // cannot be mistaken for the next key.
       i = endOfValue(src, i + 1)
       if (src[i] !== ',') return keys
@@ -435,25 +439,25 @@ function objectLiteralKeys(src: string, open: number): string[] | null {
 /**
  * Export names read out of the **bundled** output, without running anything.
  *
- * This is the job `cjs-module-lexer` does for Node and Vite: recognise a small
+ * This is the job `cjs-module-lexer` does for Node and Vite: recognize a small
  * set of known-safe `module.exports` shapes and answer nothing for the rest. It
- * is deliberately one shape here — `module.exports = { … }`, the object literal
- * — because that is the only form that reaches this code path at all. Bun
+ * is deliberately one shape here: `module.exports = { … }`, the object literal
+ *, because that is the only form that reaches this code path at all. Bun
  * already emits real named exports for `exports.name = …`, so a package written
  * that way never gets here.
  *
  * Reading the *bundle* rather than the source matters. Bun has already
- * normalised the module into a `__commonJS((exports, module) => { … })` wrapper,
+ * normalized the module into a `__commonJS((exports, module) => { … })` wrapper,
  * so there is a single known shape to look inside. The string-literal hazard
  * that made the old import rewriter corrupt user code is reduced, not
- * eliminated — a string containing `module.exports = {` would still fool this —
+ * eliminated: a string containing `module.exports = {` would still fool this,
  * which is why a failed or empty reading falls through to the probe instead of
  * being trusted as "no exports".
  */
 export function staticCjsExportNames(bundled: string): string[] {
   // `RX_MODULE_EXPORTS`, not the literal `module.exports = {`: minification
   // renames the module variable and drops the spaces (`n.exports={`), and the
-  // literal spelling made this reader dev-only — the probe silently took over
+  // literal spelling made this reader dev-only, the probe silently took over
   // every PROD bundle.
   const matches = [...bundled.matchAll(RX_MODULE_EXPORTS)]
   if (matches.length === 0) return []
@@ -483,12 +487,12 @@ export function staticCjsExportNames(bundled: string): string[] {
  * The fallback for whatever `staticCjsExportNames` cannot see. Something has to
  * run the module, and the question is only *where*: it used to be here, which
  * meant an arbitrary `node_modules` package executing inside the server process
- * — in production as well as dev — free to start a timer, open a socket, or
+ * (in production as well as dev) free to start a timer, open a socket, or
  * mutate a global that then outlives the request that caused it.
  *
  * A child process does not make execution safe, and nothing can: a module-scope
  * write to the filesystem still happens. What it buys is containment of
- * everything *in-process* — crashes, hangs, globals, listeners — and a package
+ * everything *in-process* (crashes, hangs, globals, listeners), and a package
  * that hangs on import is killed by the timeout rather than wedging a bundle.
  */
 async function cjsExportNames(path: string): Promise<string[]> {
@@ -511,7 +515,7 @@ async function cjsExportNames(path: string): Promise<string[]> {
     proc.kill()
 
     // **The exit code is deliberately not consulted.** A package that leaves a
-    // timer or a listener running — which plenty do at module scope — has
+    // timer or a listener running (which plenty do at module scope) has
     // already printed its answer and then simply fails to exit, so the probe
     // kills it and the exit code reports the kill. Requiring a clean exit threw
     // away a correct result and fell back to default-only, which is the very
@@ -539,8 +543,8 @@ async function cjsExportNames(path: string): Promise<string[]> {
  *     export const greet = __cjs.greet
  *
  * That shim is what gets bundled, so the browser gets a module that really does
- * provide `greet`. A package that throws on import — one touching `window` at
- * module scope, say — yields no names, and the caller keeps the plain bundle it
+ * provide `greet`. A package that throws on import (one touching `window` at
+ * module scope, say) yields no names, and the caller keeps the plain bundle it
  * already has.
  *
  * Non-identifier keys are skipped rather than mangled: `module.exports['a-b']`
@@ -605,14 +609,14 @@ export async function bundleModule(
     //
     // That is reachable from outside this repo. `PROD` is an accessor on
     // `process.env`, and Bun's `process.env` proxy stringifies on write, so an
-    // embedder that assigns the flag at all — even `process.env.PROD = true` —
+    // embedder that assigns the flag at all, even `process.env.PROD = true`:
     // leaves a string behind. The suite's own instance of this is fixed at the
     // source (see `setModeFlag` in `src/tests/fixtures.ts`); this guards the
     // writes we do not own.
     minify: Boolean(import.meta.env.PROD),
     define: await getDefines(),
     // Installed packages stay bare imports and resolve through the import map
-    // — which covers every one of them by construction (`initImportMap`). The
+    //, which covers every one of them by construction (`initImportMap`). The
     // alternative was measured on `@vue-material/core`: each `/_nm/` bundle
     // inlined its own copy of `vue`, and two Vue instances in one page is
     // broken reactivity, not a size problem. A ref created by one Vue is
@@ -625,7 +629,7 @@ export async function bundleModule(
     const content = await build.outputs[0].text()
 
     // A bundle that cannot possibly work is not a success, whatever `build`
-    // says — see `isEmptyExportList`. Repairable in the common case, so try
+    // says. See `isEmptyExportList`. Repairable in the common case, so try
     // that before refusing.
     if (isEmptyExportList(content)) {
       const repaired = await bundleReExportShim(path, await getDefines())
@@ -639,7 +643,7 @@ export async function bundleModule(
     }
 
     // Only for the shape that breaks, and only after the cheap build has proved
-    // it is that shape — so nothing is imported speculatively.
+    // it is that shape, so nothing is imported speculatively.
     if (isCjsDefaultOnly(content)) {
       const interop = await bundleCjsWithNamedExports(
         path,

package/src/compiler/dev-service.ts

@@ -29,7 +29,7 @@ export function notifySockets(server: any, filename: string) {
  * `{type: 'error', title, body}`. client/livereload.ts renders it as an
  * overlay and removes it on the next successful reload frame.
  *
- * Legacy reload frames stay plain filename strings — the client distinguishes
+ * Legacy reload frames stay plain filename strings: the client distinguishes
  * the two by a leading `{`, so this must always be JSON and filenames must
  * never be. Paths that cannot reach a live socket at all (worker dead, boot
  * failure before `Bun.serve`) are covered client-side by the disconnect
@@ -38,7 +38,7 @@ export function notifySockets(server: any, filename: string) {
  * Two producers reach here. The watcher's `catch` below sends internal watcher
  * faults directly; every *request-time* failure arrives through `emitDevError`
  * and the sink `startCompileService` installs. That second producer is the
- * point of the whole apparatus — for a long time only the first existed, so the
+ * point of the whole apparatus: for a long time only the first existed, so the
  * overlay was reachable solely on an IO fault inside the watcher loop and never
  * appeared for the failures developers actually hit.
  */
@@ -65,7 +65,7 @@ export const DEV_ERROR_PLUGIN = 'bakery:dev-error-overlay'
  *
  * 4xx is deliberately excluded. A 404 for a mistyped URL or an absent
  * `favicon.ico` is the router working as designed, and covering the page for it
- * would train developers to dismiss the overlay reflexively — which is how the
+ * would train developers to dismiss the overlay reflexively, which is how the
  * feature dies a second time. 5xx is the band that means "your code, or the
  * framework, broke", and that is the band this overlay exists for.
  *
@@ -113,7 +113,7 @@ export function formatDevErrorFrame(
   const body = String(error?.errorBody ?? '')
 
   return {
-    title: path ? `${code} ${text} — ${path}` : `${code} ${text}`,
+    title: path ? `${code} ${text}: ${path}` : `${code} ${text}`,
     body:
       body.length > MAX_DEV_ERROR_BODY
         ? `${body.slice(0, MAX_DEV_ERROR_BODY)}\n… truncated`
@@ -132,7 +132,7 @@ export function formatDevErrorFrame(
  * emits through a hook that is a no-op until it does.
  *
  * Null in PROD, in a cluster worker, and in every test that does not install
- * one — `emitDevError` is then a single optional call and nothing else runs.
+ * one: `emitDevError` is then a single optional call and nothing else runs.
  */
 let devErrorSink: ((title: string, body: string) => void) | null = null
 
@@ -154,14 +154,14 @@ export function emitDevError(title: string, body: string): void {
  * `ServerPlugin.onError` is the framework's own observation point for request
  * errors: `router.ts handleRequestError` calls it first, before the plugin
  * response check, before `config.onError`, and before the error-handler
- * registry — so it sees every failure the error path sees (thrown handler,
+ * registry, so it sees every failure the error path sees (thrown handler,
  * 5xx `Response`, and Bun's `error()` callback), with `errorBody` still holding
  * the full stack. Using it is what lets the overlay be wired without router.ts
  * or the error handlers ever hearing about the compiler.
  *
  * It returns `undefined` unconditionally. `PluginHooks.onError` treats that as
  * "no opinion" and carries on down the list, so registering this cannot change
- * which page a failing request answers with — it only observes.
+ * which page a failing request answers with: it only observes.
  */
 export function createDevErrorPlugin(): ServerPlugin {
   return {
@@ -186,7 +186,7 @@ export function createDevErrorPlugin(): ServerPlugin {
  * running it first costs the others nothing.
  *
  * The array is mutated in place because `initConfig` hands back a frozen
- * config — `config.plugins = [...]` would throw, and the array itself is the
+ * config: `config.plugins = [...]` would throw, and the array itself is the
  * only writable seam. Host configs are built with `{...base}` and never
  * override `plugins`, so every host shares this exact array and one
  * registration covers all of them. Idempotent by name, because a re-registration
@@ -339,7 +339,7 @@ export async function handleDevMaster(): Promise<never> {
         ...inspectArgs,
         // Respawn whatever entry started this process. The entry now lives in
         // @bakery-framework/cli, and core must not reach into a package that depends on
-        // it — argv[1] is both correct and dependency-free.
+        // it: argv[1] is both correct and dependency-free.
         process.argv[1],
         '--dev',
         '--dev-worker',
@@ -386,8 +386,8 @@ export async function handleDevMaster(): Promise<never> {
       serveLog.RESTART_REQ()
       // Clear only when the exiting worker had actually come up: then the
       // scrollback is routine request logs and clearing keeps the console
-      // readable. A worker that exited before binding — the sync engine also
-      // exits 42 mid-boot (orm/sync/engine.ts) — printed the only record of
+      // readable. A worker that exited before binding: the sync engine also
+      // exits 42 mid-boot (orm/sync/engine.ts): printed the only record of
       // why, and wiping it left the developer staring at a blank screen where
       // the error had just been. Keeping scrollback is chosen over
       // capture-and-reprint because worker stdio is inherited, not piped.
@@ -417,7 +417,7 @@ const fileTypeGlob = Glob.fromExt([
   'jsx',
   'vue',
 ])
-// `.tsx`/`.jsx` are here — the cheap path — and not in `prioFilesGlob`:
+// `.tsx`/`.jsx` are here (the cheap path), and not in `prioFilesGlob`:
 // TSXHandler re-imports the page module with `?v=<mtime>` (handlers/assets/
 // tsx.ts, same mechanism as ApiHandler), so an edited page never serves stale
 // and the route-cache flush + browser reload below is all a page edit needs.
@@ -430,7 +430,7 @@ const watchIgnores = Glob.strings(
   // The framework's own cache directory (`Bakery.cacheDir`).
   '**/.cache/**/*',
   // `bakery/` (`Bakery.dataDir`) holds the database plus
-  // `backups/schema.<timestamp>.ts` files the DB backup writes at runtime —
+  // `backups/schema.<timestamp>.ts` files the DB backup writes at runtime,
   // without this, taking a backup while the dev server ran flushed the route
   // cache and reloaded the browser. It is un-dotted on purpose (see
   // `core/bakery.ts`), which is exactly why it has to be named here: a
@@ -443,20 +443,20 @@ const watchIgnores = Glob.strings(
 )
 
 // `'api/**/*'` used to be a third entry here, left over from when API routes
-// lived at the repo root. They live under `<root>/api` now — `src/api` by
-// default — so the pattern matched nothing and API routes never triggered the
+// lived at the repo root. They live under `<root>/api` now (`src/api` by
+// default), so the pattern matched nothing and API routes never triggered the
 // restart below. The route *file* still hot-reloaded through the `?v=<mtime>`
 // cache-buster, which is why this looked fine: only its imports went stale.
 // The replacement is `isBackendPriorityFile`, which asks the config where the
 // api directory actually is instead of hard-coding it.
 //
-// `'**/*.tsx'` was the second entry here, and it made every page edit — the
-// most common edit there is — cost a full process restart (config, plugins,
+// `'**/*.tsx'` was the second entry here, and it made every page edit (the
+// most common edit there is) cost a full process restart (config, plugins,
 // import map, tsconfig sync, schema-sync check). The only reason it needed a
 // restart was Bun's module registry caching the imported page module, and
 // TSXHandler now busts that per request in dev exactly as ApiHandler always
 // has. Pages take the cheap path via `tsScriptGlob` above. The one thing the
-// restart still bought — flushing *components* a page imports — is a
+// restart still bought (flushing *components* a page imports) is a
 // documented limitation (docs/getting-started/first-app.md): touch
 // server.config.ts or restart when editing a shared Layout.tsx.
 const prioFilesGlob = Glob.strings('server.config.ts')
@@ -465,8 +465,8 @@ const prioFilesGlob = Glob.strings('server.config.ts')
  * Whether a change to `filePath` requires a full backend restart rather than a
  * livereload notification.
  *
- * `filePath` is watcher-relative — i.e. relative to the app's cwd, with forward
- * slashes — so the configured api root is converted to the same shape.
+ * `filePath` is watcher-relative, i.e. relative to the app's cwd, with forward
+ * slashes, so the configured api root is converted to the same shape.
  *
  * Host-specific roots are not consulted: a `hosts` entry can override `root`,
  * but the watcher runs outside any request and so has no host context. The
@@ -490,8 +490,8 @@ export function isBackendPriorityFile(filePath: string): boolean {
  * restart time. cli/dev.ts now hashes the schema sources, records the hash
  * under `.cache/` after a *successful* sync only, and consults this
  * before the next one. Pure so the fail-closed branches are testable: any
- * indeterminate state (`currentHash: null` — sources unreadable; `storedHash:
- * null` — no successful sync on record) must sync, never skip.
+ * indeterminate state (`currentHash: null` (sources unreadable; `storedHash:
+ * null`) no successful sync on record) must sync, never skip.
  */
 export function classifySchemaSync(opts: {
   /** `--sync` / `-s` was passed: the developer asked, so sync regardless. */
@@ -534,7 +534,7 @@ const MODULE_ROUTE_EXT = /\.(tsx|jsx)$/
  *
  * Editing a `.tsx` page is instant: the page module carries a `?v=<mtime>`
  * specifier, so Bun re-imports it and the change is served on the next
- * request. Creating one is not — Bun caches the *directory listing* it
+ * request. Creating one is not: Bun caches the *directory listing* it
  * resolved against, so a file that did not exist at boot fails to import at
  * any specifier, including a freshly-stamped one. The page 500s with
  * `Cannot find module '<path>?v=<mtime>'` until the process restarts. That is
@@ -543,13 +543,12 @@ const MODULE_ROUTE_EXT = /\.(tsx|jsx)$/
  * change and restarts already.
  *
  * `rename` is the creation signal. Measured on Windows: an in-place write
- * (`Bun.write`, `fs.writeFile`) emits only `change` and keeps the fast path —
- * 14-15ms edit-to-served — while creating a file emits `rename` then
+ * (`Bun.write`, `fs.writeFile`) emits only `change` and keeps the fast path ( * 14-15ms edit-to-served), while creating a file emits `rename` then
  * `change`. Writers that replace rather than overwrite report `rename` for an
  * *edit* too and pay one restart (~440ms): shell redirection (`> file`) does
  * this, and an editor that saves atomically will as well. That is the safe
- * direction to be wrong in — a slower save beats a page that does not serve
- * at all — but it is why this is scoped as narrowly as possible.
+ * direction to be wrong in (a slower save beats a page that does not serve
+ * at all), but it is why this is scoped as narrowly as possible.
  * Deletes are `rename` with no file, and need no restart.
  *
  * Scoped to imported modules: a new `.html`, `.css` or client `.ts` is read or
@@ -577,7 +576,7 @@ async function processFileEvent(
     }
 
     // Checked before the cheap path below: a *new* page cannot be imported by
-    // this process at all — see `isCreatedRouteModule`.
+    // this process at all. See `isCreatedRouteModule`.
     if (
       isCreatedRouteModule(
         filePath,
@@ -636,7 +635,7 @@ export async function startCompileService(server: any): Promise<void> {
     if (kind === 'ignored') continue
 
     if (kind === 'package') {
-      // Log only, no restart — deliberately. `bun install` rewrites the
+      // Log only, no restart, deliberately. `bun install` rewrites the
       // lockfile several times, and restarting on each would put the dev server
       // in a loop for the duration of an install. The line tells you a restart
       // is warranted; you decide when.
@@ -651,7 +650,7 @@ export async function startCompileService(server: any): Promise<void> {
       // A single bad event must not kill the watcher: before this, a throw
       // here unwound the for-await and file watching silently stopped until
       // the next manual restart. The server is alive at this point, so the
-      // browser is told too — this is the in-worker sender for the error
+      // browser is told too: this is the in-worker sender for the error
       // overlay protocol.
       serveLog.WATCHER_ERR({ error: String(error) })
       notifyError(server, 'Dev watcher error', String(error))

package/src/compiler/prompt-tracker.ts

@@ -3,7 +3,7 @@ import { cacheDir } from '../core/context'
 import { Try } from '../utils/common/try'
 
 /**
- * **`cacheDir` comes from `core/context`, not from `Bakery` — do not change it
+ * **`cacheDir` comes from `core/context`, not from `Bakery`. Do not change it
  * back.** `logger.ts` imports this module, so importing `core/bakery` here
  * completed a cycle:
  *
@@ -14,7 +14,7 @@ import { Try } from '../utils/common/try'
  * import arrived first found `Logger` still in its temporal dead zone. That
  * shipped in 1.2.3 and made `import '@bakery-framework/core'` throw
  * `ReferenceError: Cannot access 'Logger' before initialization` from a clean
- * install — see `tests/module-cycle.test.ts`.
+ * install. See `tests/module-cycle.test.ts`.
  *
  * `core/context` holds the same single definition of the path and imports
  * nothing that reaches the logger.