fastscript 1.0.0 → 3.0.0

package/src/regression-guard.mjs

@@ -0,0 +1,245 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+
+function normalize(path) {
+  return String(path || "").replace(/\\/g, "/");
+}
+
+function readJson(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function parseArgs(args = []) {
+  const options = {
+    mode: "all",
+    autoBaseline: false,
+    failOnRegression: true,
+    benchmarkLatest: resolve("benchmarks", "suite-latest.json"),
+    benchmarkBaseline: resolve("benchmarks", "suite-baseline.json"),
+    fidelityLatest: resolve(".fastscript", "conversion", "latest", "fidelity-report.json"),
+    fidelityBaseline: resolve(".fastscript", "baselines", "fidelity-baseline.json"),
+    out: resolve(".fastscript", "regression", "latest.json"),
+    warmBuildBudgetPct: Number(process.env.FASTSCRIPT_REGRESSION_WARM_PCT || 0.15),
+    coldBuildBudgetPct: Number(process.env.FASTSCRIPT_REGRESSION_COLD_PCT || 0.2),
+    typecheckBudgetPct: Number(process.env.FASTSCRIPT_REGRESSION_TYPECHECK_PCT || 0.2),
+    jsBudgetPct: Number(process.env.FASTSCRIPT_REGRESSION_JS_PCT || 0.1),
+    cssBudgetPct: Number(process.env.FASTSCRIPT_REGRESSION_CSS_PCT || 0.1),
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--mode") {
+      const value = String(args[i + 1] || options.mode).toLowerCase();
+      options.mode = ["all", "benchmark", "fidelity"].includes(value) ? value : "all";
+      i += 1;
+      continue;
+    }
+    if (arg === "--auto-baseline") {
+      options.autoBaseline = true;
+      continue;
+    }
+    if (arg === "--no-fail") {
+      options.failOnRegression = false;
+      continue;
+    }
+    if (arg === "--benchmark-latest") {
+      options.benchmarkLatest = resolve(args[i + 1] || options.benchmarkLatest);
+      i += 1;
+      continue;
+    }
+    if (arg === "--benchmark-baseline") {
+      options.benchmarkBaseline = resolve(args[i + 1] || options.benchmarkBaseline);
+      i += 1;
+      continue;
+    }
+    if (arg === "--fidelity-latest") {
+      options.fidelityLatest = resolve(args[i + 1] || options.fidelityLatest);
+      i += 1;
+      continue;
+    }
+    if (arg === "--fidelity-baseline") {
+      options.fidelityBaseline = resolve(args[i + 1] || options.fidelityBaseline);
+      i += 1;
+      continue;
+    }
+    if (arg === "--out") {
+      options.out = resolve(args[i + 1] || options.out);
+      i += 1;
+      continue;
+    }
+  }
+
+  return options;
+}
+
+function budgetExceeded(current, baseline, pct) {
+  const max = baseline * (1 + pct);
+  return { exceeded: current > max, max };
+}
+
+function compareBenchmark(latest, baseline, options) {
+  const findings = [];
+  const byId = new Map((baseline?.corpora || []).filter((item) => !item.skipped).map((item) => [item.id, item]));
+
+  for (const corpus of latest.corpora || []) {
+    if (corpus.skipped) continue;
+    const base = byId.get(corpus.id);
+    if (!base) continue;
+
+    const checks = [
+      {
+        metric: "warmBuildP95TrimmedMs",
+        current: Number(corpus?.timingsMs?.buildWarm?.p95Trimmed || 0),
+        baseline: Number(base?.timingsMs?.buildWarm?.p95Trimmed || 0),
+        budgetPct: options.warmBuildBudgetPct,
+      },
+      {
+        metric: "coldBuildMs",
+        current: Number(corpus?.timingsMs?.buildCold?.ms || 0),
+        baseline: Number(base?.timingsMs?.buildCold?.ms || 0),
+        budgetPct: options.coldBuildBudgetPct,
+      },
+      {
+        metric: "typecheckP95TrimmedMs",
+        current: Number(corpus?.timingsMs?.typecheck?.p95Trimmed || 0),
+        baseline: Number(base?.timingsMs?.typecheck?.p95Trimmed || 0),
+        budgetPct: options.typecheckBudgetPct,
+      },
+      {
+        metric: "firstLoadJsGzipBytes",
+        current: Number(corpus?.bundles?.js || 0),
+        baseline: Number(base?.bundles?.js || 0),
+        budgetPct: options.jsBudgetPct,
+      },
+      {
+        metric: "firstLoadCssGzipBytes",
+        current: Number(corpus?.bundles?.css || 0),
+        baseline: Number(base?.bundles?.css || 0),
+        budgetPct: options.cssBudgetPct,
+      },
+    ];
+
+    for (const check of checks) {
+      if (!Number.isFinite(check.current) || !Number.isFinite(check.baseline) || check.baseline <= 0) continue;
+      const status = budgetExceeded(check.current, check.baseline, check.budgetPct);
+      if (status.exceeded) {
+        findings.push({
+          domain: "benchmark",
+          corpus: corpus.id,
+          metric: check.metric,
+          current: check.current,
+          baseline: check.baseline,
+          maxAllowed: Number(status.max.toFixed(2)),
+          budgetPct: check.budgetPct,
+        });
+      }
+    }
+  }
+
+  return {
+    status: findings.length ? "fail" : "pass",
+    findings,
+    corporaCompared: (latest.corpora || []).filter((item) => !item.skipped).length,
+  };
+}
+
+function compareFidelity(latest, baseline) {
+  const findings = [];
+
+  const latestStatus = String(latest?.status || "unknown");
+  const baselineStatus = String(baseline?.status || "unknown");
+  if (latestStatus !== "pass") {
+    findings.push({ domain: "fidelity", metric: "status", current: latestStatus, baseline: baselineStatus, expected: "pass" });
+  }
+
+  const latestChecksFail = (latest?.checks || []).filter((item) => item.status !== "pass").map((item) => item.id);
+  if (latestChecksFail.length) {
+    findings.push({ domain: "fidelity", metric: "checks", current: latestChecksFail, baseline: [] });
+  }
+
+  const latestProbesFail = (latest?.probes || []).filter((item) => item.status !== "pass").map((item) => item.id);
+  if (latestProbesFail.length) {
+    findings.push({ domain: "fidelity", metric: "probes", current: latestProbesFail, baseline: [] });
+  }
+
+  const baselineRequired = new Set((baseline?.required || []).map((item) => String(item || "")));
+  const latestRequired = new Set((latest?.required || []).map((item) => String(item || "")));
+  for (const id of baselineRequired) {
+    if (!latestRequired.has(id)) {
+      findings.push({ domain: "fidelity", metric: "requiredProbeMissing", probe: id });
+    }
+  }
+
+  return {
+    status: findings.length ? "fail" : "pass",
+    findings,
+    requiredCount: latestRequired.size,
+  };
+}
+
+function ensureBaselineOrLoad(path, latest, options) {
+  const baseline = readJson(path, null);
+  if (baseline) return { baseline, created: false };
+  if (!options.autoBaseline) {
+    throw new Error(`regression baseline missing: ${normalize(relative(resolve("."), path))}`);
+  }
+  writeJson(path, latest);
+  return { baseline: latest, created: true };
+}
+
+export async function runRegressionGuard(args = []) {
+  const options = parseArgs(args);
+  const report = {
+    generatedAt: new Date().toISOString(),
+    mode: options.mode,
+    benchmark: null,
+    fidelity: null,
+    baselineCreated: {
+      benchmark: false,
+      fidelity: false,
+    },
+    status: "pass",
+    findings: [],
+  };
+
+  if (options.mode === "all" || options.mode === "benchmark") {
+    const latest = readJson(options.benchmarkLatest, null);
+    if (!latest) throw new Error(`benchmark latest missing: ${normalize(relative(resolve("."), options.benchmarkLatest))}`);
+
+    const baselineState = ensureBaselineOrLoad(options.benchmarkBaseline, latest, options);
+    report.baselineCreated.benchmark = baselineState.created;
+    report.benchmark = compareBenchmark(latest, baselineState.baseline, options);
+    report.findings.push(...report.benchmark.findings);
+  }
+
+  if (options.mode === "all" || options.mode === "fidelity") {
+    const latest = readJson(options.fidelityLatest, null);
+    if (!latest) throw new Error(`fidelity latest missing: ${normalize(relative(resolve("."), options.fidelityLatest))}`);
+
+    const baselineState = ensureBaselineOrLoad(options.fidelityBaseline, latest, options);
+    report.baselineCreated.fidelity = baselineState.created;
+    report.fidelity = compareFidelity(latest, baselineState.baseline);
+    report.findings.push(...report.fidelity.findings);
+  }
+
+  if (report.findings.length) report.status = "fail";
+
+  writeJson(options.out, report);
+
+  console.log(`regression guard: ${report.status}`);
+  console.log(`regression report: ${normalize(relative(resolve("."), options.out))}`);
+
+  if (options.failOnRegression && report.status === "fail") {
+    throw new Error(`regression guard failed with ${report.findings.length} finding(s)`);
+  }
+}

package/src/retention.mjs

@@ -0,0 +1,57 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function applyJsonArrayRetention(path, { timestampField = "ts", maxAgeMs = 1000 * 60 * 60 * 24 * 30 } = {}) {
+  const rows = readJson(path, []);
+  if (!Array.isArray(rows)) return { kept: 0, removed: 0 };
+  const cutoff = Date.now() - maxAgeMs;
+  const kept = rows.filter((row) => {
+    const raw = row?.[timestampField] || row?.failedAt || row?.createdAt || null;
+    const n = typeof raw === "number" ? raw : Date.parse(raw || "");
+    return Number.isFinite(n) ? n >= cutoff : true;
+  });
+  const removed = rows.length - kept.length;
+  if (removed > 0) writeFileSync(path, JSON.stringify(kept, null, 2), "utf8");
+  return { kept: kept.length, removed };
+}
+
+export function sweepFileAges(dir, { maxAgeMs = 1000 * 60 * 60 * 24 * 30 } = {}) {
+  const root = resolve(dir);
+  if (!existsSync(root)) return { removed: 0 };
+  const cutoff = Date.now() - maxAgeMs;
+  let removed = 0;
+  for (const name of readdirSync(root)) {
+    const full = join(root, name);
+    const st = statSync(full);
+    if (st.isDirectory()) continue;
+    if (st.mtimeMs < cutoff) {
+      rmSync(full, { force: true });
+      removed += 1;
+    }
+  }
+  return { removed };
+}
+
+export function runRetentionSweep({ root = ".fastscript" } = {}) {
+  const resolved = resolve(root);
+  const cacheResult = sweepFileAges(join(resolved, "cache"), {
+    maxAgeMs: Number(process.env.RETENTION_CACHE_MS || 1000 * 60 * 60 * 24 * 14),
+  });
+  const jobsResult = applyJsonArrayRetention(join(resolved, "jobs-dead-letter.json"), {
+    timestampField: "failedAt",
+    maxAgeMs: Number(process.env.RETENTION_DEAD_LETTER_MS || 1000 * 60 * 60 * 24 * 30),
+  });
+  return {
+    cache: cacheResult,
+    deadLetter: jobsResult,
+  };
+}

package/src/routes.mjs

@@ -0,0 +1,178 @@
+import { dirname, extname, relative } from "node:path";
+
+function cleanSegments(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/").replace(extname(file), "");
+  return rel.split("/").filter(Boolean);
+}
+
+function isGroupSegment(segment) {
+  return segment.startsWith("(") && segment.endsWith(")");
+}
+
+function isParallelSegment(segment) {
+  return segment.startsWith("@");
+}
+
+function normalizeParamType(type) {
+  const raw = String(type || "string").toLowerCase();
+  if (raw === "int" || raw === "float" || raw === "number") return "number";
+  if (raw === "bool" || raw === "boolean") return "boolean";
+  if (raw === "str" || raw === "string") return "string";
+  return "string";
+}
+
+function segmentPriority(segment) {
+  if (!segment) return 0;
+  const token = /^:([A-Za-z_$][\w$]*)(\*)?(\?)?$/.exec(segment);
+  if (!token) return 40;
+  const catchAll = Boolean(token[2]);
+  const optional = Boolean(token[3]);
+  if (catchAll && optional) return 5;
+  if (catchAll) return 10;
+  if (optional) return 20;
+  return 30;
+}
+
+function routePriority(pathname) {
+  const parts = String(pathname || "/").split("/").filter(Boolean);
+  if (!parts.length) return 1000;
+  return parts.reduce((sum, part) => sum + segmentPriority(part), 0) + parts.length;
+}
+
+function routeSegmentValue(segment) {
+  if (!segment) return null;
+  if (isGroupSegment(segment)) return null;
+  if (isParallelSegment(segment)) return null;
+  if (segment === "index") return null;
+  const optionalCatchAll = /^\[\[\.\.\.([A-Za-z_$][\w$]*)\]\]$/.exec(segment);
+  if (optionalCatchAll) {
+    return {
+      value: `:${optionalCatchAll[1]}*?`,
+      param: { name: optionalCatchAll[1], type: "string[] | undefined", optional: true, catchAll: true },
+    };
+  }
+  const requiredCatchAll = /^\[\.\.\.([A-Za-z_$][\w$]*)\]$/.exec(segment);
+  if (requiredCatchAll) {
+    return {
+      value: `:${requiredCatchAll[1]}*`,
+      param: { name: requiredCatchAll[1], type: "string[]", optional: false, catchAll: true },
+    };
+  }
+  const optionalTyped = /^\[\[([A-Za-z_$][\w$]*)(?::([A-Za-z]+))?\]\]$/.exec(segment);
+  if (optionalTyped) {
+    const type = normalizeParamType(optionalTyped[2]);
+    return {
+      value: `:${optionalTyped[1]}?`,
+      param: { name: optionalTyped[1], type: `${type} | undefined`, optional: true, catchAll: false },
+    };
+  }
+  const simpleTyped = /^\[([A-Za-z_$][\w$]*)(?::([A-Za-z]+))?\]$/.exec(segment);
+  if (simpleTyped) {
+    const type = normalizeParamType(simpleTyped[2]);
+    return {
+      value: `:${simpleTyped[1]}`,
+      param: { name: simpleTyped[1], type, optional: false, catchAll: false },
+    };
+  }
+  return { value: segment, param: null };
+}
+
+export function inferRouteMeta(file, pagesDir) {
+  const parts = cleanSegments(file, pagesDir);
+  const pageFile = parts[parts.length - 1] || "index";
+  const parallel = parts.find((segment) => isParallelSegment(segment));
+  const slot = parallel ? parallel.slice(1) : null;
+  const routeParts = [];
+  const params = [];
+  const paramTypes = {};
+
+  for (const part of parts) {
+    const mapped = routeSegmentValue(part);
+    if (!mapped?.value) continue;
+    routeParts.push(mapped.value);
+    if (mapped.param) {
+      params.push(mapped.param.name);
+      paramTypes[mapped.param.name] = mapped.param.type;
+    }
+  }
+
+  const routePath = routeParts.length ? `/${routeParts.join("/")}` : "/";
+  const normalizedParts = parts.filter((segment) => !isGroupSegment(segment) && !isParallelSegment(segment));
+
+  return {
+    file,
+    pageFile,
+    routePath,
+    params,
+    paramTypes,
+    slot,
+    segments: normalizedParts,
+    directory: dirname(relative(pagesDir, file).replace(/\\/g, "/")),
+  };
+}
+
+export function inferRouteParamTypes(routePath, paramTypes = null) {
+  if (paramTypes && typeof paramTypes === "object" && Object.keys(paramTypes).length) {
+    return { ...paramTypes };
+  }
+  const params = {};
+  for (const segment of String(routePath || "").split("/")) {
+    const token = /^:([A-Za-z_$][\w$]*)(\*)?(\?)?$/.exec(segment);
+    if (!token) continue;
+    const name = token[1];
+    const catchAll = Boolean(token[2]);
+    const optional = Boolean(token[3]);
+    if (catchAll && optional) params[name] = "string[] | undefined";
+    else if (catchAll) params[name] = "string[]";
+    else if (optional) params[name] = "string | undefined";
+    else params[name] = "string";
+  }
+  return params;
+}
+
+export function inferRouteLayouts(file, pagesDir, layoutFiles = new Set()) {
+  const relDir = dirname(relative(pagesDir, file).replace(/\\/g, "/"));
+  const chain = [];
+  const dirs = relDir === "." ? [] : relDir.split("/").filter(Boolean);
+  const probes = [""];
+  for (const dir of dirs) {
+    probes.push(probes[probes.length - 1] ? `${probes[probes.length - 1]}/${dir}` : dir);
+  }
+
+  for (const probe of probes) {
+    const fsLayout = probe ? `${probe}/_layout.fs` : "_layout.fs";
+    const jsLayout = probe ? `${probe}/_layout.js` : "_layout.js";
+    if (layoutFiles.has(fsLayout)) chain.push(fsLayout);
+    else if (layoutFiles.has(jsLayout)) chain.push(jsLayout);
+  }
+  return chain;
+}
+
+export function compareRoutePriority(a, b) {
+  const scoreA = routePriority(a?.path || a?.routePath || "/");
+  const scoreB = routePriority(b?.path || b?.routePath || "/");
+  if (scoreA !== scoreB) return scoreB - scoreA;
+
+  const lenA = String(a?.path || a?.routePath || "/").split("/").filter(Boolean).length;
+  const lenB = String(b?.path || b?.routePath || "/").split("/").filter(Boolean).length;
+  if (lenA !== lenB) return lenB - lenA;
+
+  const slotA = String(a?.slot || "default");
+  const slotB = String(b?.slot || "default");
+  if (slotA !== slotB) return slotA.localeCompare(slotB);
+  return String(a?.path || a?.routePath || "/").localeCompare(String(b?.path || b?.routePath || "/"));
+}
+
+export function sortRoutesByPriority(routes = []) {
+  return [...routes].sort(compareRoutePriority);
+}
+
+export function isLayoutFile(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/");
+  return rel.endsWith("/_layout.fs") || rel.endsWith("/_layout.js") || rel === "_layout.fs" || rel === "_layout.js";
+}
+
+export function isNotFoundFile(file, pagesDir) {
+  const rel = relative(pagesDir, file).replace(/\\/g, "/");
+  return rel.endsWith("/404.fs") || rel.endsWith("/404.js") || rel === "404.fs" || rel === "404.js";
+}