arcway 0.1.16 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.1.16",
+  "version": "0.1.17",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/pages/build-cache.js

@@ -91,6 +91,18 @@ async function cpAtomic(src, dst) {
   }
 }
 
+// Best-effort LRU timestamp bump. File mtime is what enforceCacheBudget orders
+// by, so this is how we record "recently used" for cache hits. Swallow errors —
+// a concurrent evictor may have removed the file already; that's fine.
+async function touchMeta(metaPath) {
+  const now = new Date();
+  try {
+    await fs.utimes(metaPath, now, now);
+  } catch {
+    // Ignore: entry may have been evicted concurrently.
+  }
+}
+
 async function lookupBundle({ rootDir, entryPath, configHash, kind }) {
   const bucket = bucketDir(rootDir, kind);
   const key = entryKey(entryPath);
@@ -113,6 +125,7 @@ async function lookupBundle({ rootDir, entryPath, configHash, kind }) {
   } catch {
     return { hit: false, key, bucket, metaPath, jsPath, mapPath };
   }
+  await touchMeta(metaPath);
   return { hit: true, key, bucket, metaPath, jsPath, mapPath };
 }
 
@@ -194,10 +207,26 @@ async function buildWithCache({
   return { cacheHit: false, metafile: result.metafile };
 }
 
+// Canonical, order-independent hash of a virtualInputs list so stored/current
+// sets can be compared without worrying about caller ordering.
+function hashVirtualInputs(virtualInputs) {
+  if (!virtualInputs || virtualInputs.length === 0) return '';
+  const sorted = [...virtualInputs]
+    .map((v) => ({ name: v.name, digest: v.digest }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+  return sha256(JSON.stringify(sorted));
+}
+
 // Multi-file cache for bundles with several output files (client build with
 // code-splitting). Each cache entry lives under <bucket>/<coarseKey>/ and the
 // index is a sidecar <bucket>/<coarseKey>.meta.json.
-async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
+//
+// `virtualInputs` (optional) are caller-computed digests that can't be
+// represented as a file path — e.g. the set of class-name tokens extracted
+// from a source tree. Each entry is `{ name, digest }`. The caller must
+// re-compute and pass current values on every lookup; the stored and current
+// digest sets must match exactly for a hit.
+async function lookupMultiFileCache({ rootDir, kind, coarseKey, virtualInputs }) {
   const bucket = bucketDir(rootDir, kind);
   const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
   const cacheDir = path.join(bucket, coarseKey);
@@ -207,6 +236,14 @@ async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
   if (currentHash === null || currentHash !== meta.inputsHash) {
     return { hit: false, bucket, cacheDir, metaPath };
   }
+  // Compare virtual-input digest sets. If the stored entry has virtualInputs
+  // but the caller omitted them, treat as a miss — a silent hit would serve
+  // stale output for whatever derived state the virtual digest tracks.
+  const storedVirtualHash = meta.virtualInputsHash ?? '';
+  const currentVirtualHash = hashVirtualInputs(virtualInputs);
+  if (storedVirtualHash !== currentVirtualHash) {
+    return { hit: false, bucket, cacheDir, metaPath };
+  }
   // Sanity-check every recorded output file still exists in the cache dir.
   for (const rel of meta.outputs) {
     try {
@@ -215,6 +252,7 @@ async function lookupMultiFileCache({ rootDir, kind, coarseKey }) {
       return { hit: false, bucket, cacheDir, metaPath };
     }
   }
+  await touchMeta(metaPath);
   return { hit: true, bucket, cacheDir, metaPath, meta };
 }
 
@@ -236,6 +274,7 @@ async function storeMultiFileCache({
   destDir,
   outputs,
   inputs,
+  virtualInputs,
   metadata,
 }) {
   const cacheDir = path.join(bucket, coarseKey);
@@ -250,16 +289,166 @@ async function storeMultiFileCache({
     }),
   );
   const inputsHash = await hashInputs(inputs);
+  const virtualInputsHash = hashVirtualInputs(virtualInputs);
   const metaPath = path.join(bucket, `${coarseKey}.meta.json`);
   await writeJsonAtomic(metaPath, {
     inputs,
     inputsHash,
+    virtualInputs: virtualInputs ?? [],
+    virtualInputsHash,
     outputs,
     metadata,
     mtime: Date.now(),
   });
 }
 
+// Default cap for the on-disk cache. Override with ARCWAY_PAGES_CACHE_MAX_BYTES
+// (bytes as an integer). Anything over the cap is LRU-evicted after each store.
+const DEFAULT_CACHE_MAX_BYTES = 500 * 1024 * 1024;
+
+// Newly-written entries are protected from eviction for this many milliseconds
+// to avoid racing with in-flight stores from sibling forks. 5s comfortably
+// exceeds a typical per-entry store (cpAtomic + writeJsonAtomic).
+const DEFAULT_CACHE_GRACE_PERIOD_MS = 5000;
+
+function cacheMaxBytes() {
+  const raw = Number(process.env.ARCWAY_PAGES_CACHE_MAX_BYTES);
+  return Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_CACHE_MAX_BYTES;
+}
+
+async function statOrNull(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch {
+    return null;
+  }
+}
+
+// Recursively measure a directory's total size and the most-recent mtime of any
+// file/subdir inside it. Used for multi-file cache entries whose body lives in a
+// sibling dir. Returns {size: 0, mtime: 0} when the dir is missing.
+async function measureDir(dir) {
+  let size = 0;
+  let mtime = 0;
+  let items;
+  try {
+    items = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return { size, mtime };
+  }
+  for (const item of items) {
+    const abs = path.join(dir, item.name);
+    if (item.isDirectory()) {
+      const sub = await measureDir(abs);
+      size += sub.size;
+      if (sub.mtime > mtime) mtime = sub.mtime;
+    } else {
+      const s = await statOrNull(abs);
+      if (s) {
+        size += s.size;
+        if (s.mtimeMs > mtime) mtime = s.mtimeMs;
+      }
+    }
+  }
+  return { size, mtime };
+}
+
+// Enumerate every cache entry across all kinds. Each entry is identified by its
+// sidecar `<key>.meta.json` file. Single-file entries have an accompanying
+// `<key>.js` (+ optional `.js.map`); multi-file entries have a `<coarseKey>/`
+// dir. We collect paths for both shapes so removal is unconditional.
+async function collectCacheEntries(rootDir) {
+  const root = cacheRoot(rootDir);
+  let kindDirs;
+  try {
+    kindDirs = await fs.readdir(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const kindEnt of kindDirs) {
+    if (!kindEnt.isDirectory()) continue;
+    const bucket = path.join(root, kindEnt.name);
+    let files;
+    try {
+      files = await fs.readdir(bucket);
+    } catch {
+      continue;
+    }
+    for (const file of files) {
+      if (!file.endsWith('.meta.json')) continue;
+      const baseKey = file.slice(0, -'.meta.json'.length);
+      const metaPath = path.join(bucket, file);
+      const jsPath = path.join(bucket, `${baseKey}.js`);
+      const mapPath = path.join(bucket, `${baseKey}.js.map`);
+      const dirPath = path.join(bucket, baseKey);
+
+      const metaStat = await statOrNull(metaPath);
+      if (!metaStat) continue;
+      const jsStat = await statOrNull(jsPath);
+      const mapStat = await statOrNull(mapPath);
+      const dirInfo = await measureDir(dirPath);
+
+      const size = metaStat.size + (jsStat?.size ?? 0) + (mapStat?.size ?? 0) + dirInfo.size;
+      // Use the most recent mtime across meta + dir contents. A concurrent
+      // multi-file store rewrites `.meta.json` last but populates the dir
+      // first, so dir mtime can be newer than meta mtime during a store.
+      const mtime = Math.max(metaStat.mtimeMs, dirInfo.mtime);
+      entries.push({ metaPath, jsPath, mapPath, dirPath, size, mtime });
+    }
+  }
+  return entries;
+}
+
+async function removeCacheEntry(entry) {
+  await Promise.allSettled([
+    fs.rm(entry.metaPath, { force: true }),
+    fs.rm(entry.jsPath, { force: true }),
+    fs.rm(entry.mapPath, { force: true }),
+    fs.rm(entry.dirPath, { recursive: true, force: true }),
+  ]);
+}
+
+// Enforce a byte-budget over the on-disk cache. Oldest (by filesystem mtime)
+// entries are evicted first; entries whose mtime is within `gracePeriodMs` of
+// `now` are protected so an in-flight concurrent store isn't yanked out from
+// under a sibling fork. Lock-free and idempotent: multiple forks may run this
+// concurrently and at worst slightly over-evict, which self-corrects on the
+// next cold build.
+async function enforceCacheBudget({
+  rootDir,
+  maxBytes = cacheMaxBytes(),
+  gracePeriodMs = DEFAULT_CACHE_GRACE_PERIOD_MS,
+  now = Date.now(),
+} = {}) {
+  const entries = await collectCacheEntries(rootDir);
+  const totalSize = entries.reduce((s, e) => s + e.size, 0);
+  if (totalSize <= maxBytes) {
+    return { evicted: 0, kept: entries.length, bytesFreed: 0, bytesRemaining: totalSize };
+  }
+
+  const candidates = entries
+    .filter((e) => now - e.mtime >= gracePeriodMs)
+    .sort((a, b) => a.mtime - b.mtime);
+
+  let remaining = totalSize;
+  let freed = 0;
+  let evicted = 0;
+  for (const cand of candidates) {
+    if (remaining <= maxBytes) break;
+    await removeCacheEntry(cand);
+    remaining -= cand.size;
+    freed += cand.size;
+    evicted += 1;
+  }
+  return {
+    evicted,
+    kept: entries.length - evicted,
+    bytesFreed: freed,
+    bytesRemaining: remaining,
+  };
+}
+
 // Walk every cache entry in <rootDir>/node_modules/.cache/arcway-pages/<kind>
 // and drop any whose recorded inputs no longer hash to the stored value (or
 // whose inputs are gone). Used by tests that intentionally mutate fixture
@@ -310,6 +499,8 @@ export {
   buildWithCache,
   computeConfigHash,
   cacheRoot,
+  DEFAULT_CACHE_MAX_BYTES,
+  enforceCacheBudget,
   entryKey,
   ESBUILD_VERSION,
   sha256,

package/server/pages/build-css.js

@@ -11,10 +11,16 @@ import {
   restoreMultiFileCache,
   storeMultiFileCache,
 } from './build-cache.js';
+import { hashClassTokens } from './class-token-scan.js';
 
-// Shallow-walk the pages dir and return every source-shaped file. Used as the
-// cache-invalidation input set when tailwind will scan it via @source.
-async function collectTailwindSources(pagesDir) {
+// Shallow-walk pagesDir for the CSS files tailwind will scan; these are
+// tracked as real file inputs so any byte-level edit invalidates the cache.
+// JSX/TS/etc. are not included here — they go through hashClassTokens(), which
+// produces a virtual-input digest that only busts the cache when the set of
+// string-literal tokens changes. That's a superset of every class name
+// tailwind could emit, and ignores unrelated edits (logic, whitespace,
+// comments) that can't affect the generated CSS.
+async function collectCssFiles(pagesDir) {
   const out = [];
   async function walk(dir) {
     let entries;
@@ -28,10 +34,8 @@ async function collectTailwindSources(pagesDir) {
       if (e.isDirectory()) {
         if (e.name === 'node_modules' || e.name.startsWith('.')) continue;
         await walk(full);
-      } else if (e.isFile()) {
-        if (/\.(jsx?|tsx?|mjs|cjs|css)$/i.test(e.name)) {
-          out.push(full);
-        }
+      } else if (e.isFile() && /\.css$/i.test(e.name)) {
+        out.push(full);
       }
     }
   }
@@ -60,16 +64,26 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
   rootDir = rootDir ?? path.dirname(outDir);
   const coarseKey = computeCssCoarseKey({ minify, fontFaceCss, stylesPath });
 
-  // Inputs that should invalidate the cache on content change.
+  // File inputs: stylesPath + every CSS file under pagesDir. These are hashed
+  // by full content — any byte change should invalidate the cache because raw
+  // CSS ends up in the output verbatim.
   const inputs = [];
-  if (stylesPath) {
-    inputs.push(path.resolve(stylesPath));
-  } else {
-    const scanned = await collectTailwindSources(pagesDir);
-    for (const f of scanned) inputs.push(f);
-  }
+  if (stylesPath) inputs.push(path.resolve(stylesPath));
+  const cssFiles = await collectCssFiles(pagesDir);
+  for (const f of cssFiles) inputs.push(f);
+
+  // Virtual input: a digest over every string-literal token found in the
+  // JSX/TS source tree under pagesDir. Tailwind's class-name emission depends
+  // only on which tokens appear in scanned files — not on surrounding code
+  // structure — so the digest captures the only source signal that actually
+  // matters for CSS output. Editing handler logic, comments, or whitespace
+  // leaves this digest unchanged and the CSS cache is reused.
+  const classTokensDigest = await hashClassTokens(pagesDir);
+  const virtualInputs = [
+    { name: `${path.resolve(pagesDir)}::class-tokens`, digest: classTokensDigest },
+  ];
 
-  const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey });
+  const lookup = await lookupMultiFileCache({ rootDir, kind: 'css', coarseKey, virtualInputs });
   if (lookup.hit) {
     await restoreMultiFileCache({
       cacheDir: lookup.cacheDir,
@@ -114,6 +128,7 @@ async function buildCssBundle(pagesDir, outDir, minify, stylesPath, fontFaceCss,
     destDir: clientDir,
     outputs: [cssFileName],
     inputs,
+    virtualInputs,
     metadata: { cssBundleRel },
   });
 

package/server/pages/build.js

@@ -20,6 +20,7 @@ import { buildCssBundle } from './build-css.js';
 import { generateManifest } from './build-manifest.js';
 import { resolveFonts } from './fonts.js';
 import { buildHmrRuntimeBundle } from './hmr.js';
+import { enforceCacheBudget } from './build-cache.js';
 async function buildPages(options) {
   const { rootDir } = options;
   const pagesDir = options.pagesDir ?? path.join(rootDir, 'pages');
@@ -107,6 +108,13 @@ async function buildPages(options) {
       JSON.stringify(manifest, null, 2),
     );
     await atomicSwap(outDir, buildDir);
+    // Keep the on-disk cache bounded. Fire-and-forget so the build returns
+    // immediately; eviction is idempotent across concurrent builds and any
+    // failure is non-fatal (worst case the cache grows past the cap until the
+    // next build). Tracked via `cacheEvictions` for test quiescence.
+    const eviction = enforceCacheBudget({ rootDir }).catch(() => {});
+    cacheEvictions.add(eviction);
+    eviction.finally(() => cacheEvictions.delete(eviction));
     const clientMetafile =
       devMode && clientResult.metafile
         ? rewriteMetafilePaths(clientResult.metafile, buildDir, outDir)
@@ -136,9 +144,12 @@ async function buildPages(options) {
 // Tracks fire-and-forget cleanup promises from failed builds so tests can
 // await `buildPagesIdle()` and see a clean `.build` dir.
 const pendingCleanups = new Set();
+// Tracks fire-and-forget cache-eviction promises from successful builds so
+// tests can await full quiescence and assert on post-eviction cache state.
+const cacheEvictions = new Set();
 async function buildPagesIdle() {
-  while (pendingCleanups.size > 0) {
-    await Promise.allSettled([...pendingCleanups]);
+  while (pendingCleanups.size > 0 || cacheEvictions.size > 0) {
+    await Promise.allSettled([...pendingCleanups, ...cacheEvictions]);
   }
 }
 // Serialize concurrent swaps targeting the same outDir. Without this, two

package/server/pages/class-token-scan.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+const SOURCE_FILE_PATTERN = /\.(jsx?|tsx?|mjs|cjs)$/i;
+
+// Match the *content* of any string literal — double-quoted, single-quoted, or
+// backtick template. Escape-aware so `\"` doesn't end a double-quoted string
+// prematurely. Template interpolation `${...}` is captured verbatim inside the
+// backtick group; we don't try to parse it out, so interpolation syntax leaks
+// into tokens. That's a benign false-positive signal — if the expression's
+// source changes, the digest changes; tailwind's own oxide scanner has the
+// same boundary limitation.
+const STRING_LITERAL_RE =
+  /"((?:[^"\\]|\\.)*)"|'((?:[^'\\]|\\.)*)'|`((?:[^`\\]|\\.)*)`/g;
+
+// Extract every whitespace-separated token found inside any string literal in
+// `content`. Returns a Set so callers can take a union across files. We don't
+// try to filter to "looks-like-a-tailwind-class" shapes because tailwind v4
+// accepts arbitrary-value classes like `hover:bg-[#fff]` whose superset of
+// allowed characters is broad. Over-inclusion is safe — an extra token only
+// causes unnecessary cache busts on unrelated edits, not stale output.
+function extractClassTokens(content) {
+  const tokens = new Set();
+  let match;
+  while ((match = STRING_LITERAL_RE.exec(content)) !== null) {
+    const body = match[1] ?? match[2] ?? match[3] ?? '';
+    for (const part of body.split(/\s+/)) {
+      if (part.length > 0) tokens.add(part);
+    }
+  }
+  return tokens;
+}
+
+async function walkSources(dir, onFile) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return;
+    throw err;
+  }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      await walkSources(full, onFile);
+    } else if (entry.isFile() && SOURCE_FILE_PATTERN.test(entry.name)) {
+      await onFile(full);
+    }
+  }
+}
+
+// Union every class-name-shaped token across every JSX/TS source under
+// `pagesDir`, sort, and hash. Sort so the digest is order-independent —
+// adding/removing files only affects the digest via the *set* of tokens, not
+// filesystem enumeration order, which prevents false busts from filesystem
+// reordering across platforms.
+async function hashClassTokens(pagesDir) {
+  const tokens = new Set();
+  await walkSources(pagesDir, async (filePath) => {
+    const content = await fs.readFile(filePath, 'utf-8');
+    for (const token of extractClassTokens(content)) {
+      tokens.add(token);
+    }
+  });
+  const sorted = [...tokens].sort();
+  return crypto.createHash('sha256').update(sorted.join('\n')).digest('hex');
+}
+
+export { extractClassTokens, hashClassTokens };