Under the Hood

{
  "build": "next build",
  "vercel-build": "pnpm exec convex deploy --cmd 'pnpm build:vercel' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL",
  "build:vercel": "tsx src/db/migrate.ts && tsx src/db/backfill-users-if-empty.ts && tsx src/db/ingest-sde-if-empty.ts && next build && node scripts/assert-route-classification.mjs",
  "assert:routes": "node scripts/assert-route-classification.mjs",
  "assert:routes-present": "node scripts/assert-routes-present.mjs"
}

{
  "_comment": "Expected `next build` render mode for every route, asserted by scripts/assert-route-classification.mjs after a build. Guards the conversion-track payoff (3.0.4.8+3.0.4.9): a route must not silently regress to a more dynamic mode. Modes: 'static' = ○ (fully prerendered), 'partial' = ◐ (partial prerender — static shell + request-time <Suspense> holes), 'dynamic' = ƒ (server-rendered per request). New routes must be added here or the check fails. If a change is intentional, update this file in the same commit.",
  "_reasons": {
    "/sites": "Client-state class/type filters (not searchParams) plus a searchParams-driven sort; the live-price overlay streams from a dynamic hole.",
    "/admin": "Per-user: the session-gated single-page dashboard (KPIs, status strip, traffic, users) is a request-time dynamic hole; visx charts are client-only islands inside it.",
    "/api/industry/blueprints": "Blueprint search index is deploy-static SDE data (cached 'max', SDE-tag revalidated), so the handler prerenders to a static JSON asset — no per-request input.",
    "dynamic /api/*": "Route handlers — per-request by nature (auth, mutations, DB queries, crons, external calls). Justified dynamic."
  },
  "routes": {
    "/": "partial",
    "/admin": "partial",
    "/changelog": "static",
    "/industry/[id]": "partial",
    "/api/industry/blueprints": "static",
    "/api/account/skills": "dynamic",
    "/api/cron/refresh-gsc": "dynamic",
    "/api/telemetry": "dynamic"
  }
}

const expected = readJson(join(HERE, 'route-classification.json')).routes;
const appRoutes = readJson(appRoutesManifestPath); // { "<file>/page": "/route", ... }
const prerender = readJson(prerenderManifestPath);
const prerendered = new Set([
  ...Object.keys(prerender.routes ?? {}),
  ...Object.keys(prerender.dynamicRoutes ?? {}),
]);

function metaPathFor(route) {
  const base = route === '/' ? 'index' : route.replace(/^\//, '');
  return join(APP_DIR, `${base}.meta`);
}

function classify(route) {
  if (!prerendered.has(route)) return 'dynamic';
  const metaPath = metaPathFor(route);
  if (!existsSync(metaPath)) return 'partial';
  return 'postponed' in readJson(metaPath) ? 'partial' : 'static';
}

const routes = [...new Set(Object.values(appRoutes))]
  .filter((r) => !r.startsWith('/_') && r !== '/favicon.ico')
  .sort();

const errors = [];
for (const route of routes) {
  const actual = classify(route);
  const want = expected[route];
  if (!want) {
    errors.push(`unclassified route "${route}" (built as ${actual}) — add it to scripts/route-classification.json`);
  } else if (actual !== want) {
    errors.push(`"${route}": expected ${want} but built as ${actual}`);
  }
}
for (const route of Object.keys(expected)) {
  if (!routes.includes(route)) {
    errors.push(`stale entry "${route}" in scripts/route-classification.json — route no longer exists`);
  }
}

if (errors.length > 0) {
  console.error('\n✗ Route render-mode classification check failed:');
  for (const e of errors) console.error(`  - ${e}`);
  console.error('\nIf the change is intentional, update scripts/route-classification.json in the same commit.\n');
  process.exit(1);
}

// CI presence check (no build required): every route-defining file under
// src/app has a classification entry in scripts/route-classification.json, and
// every classification entry still has a file. The full render-MODE assert
// (assert-route-classification.mjs) needs a `next build` and runs at deploy;
// this lighter check catches an added/removed route that forgot the JSON in
// plain CI, where the build doesn't run.
const ROUTE_FILE = /^(page|route)\.(tsx?|jsx?)$/;
const SITEMAP_FILE = /^sitemap\.(tsx?|jsx?)$/;
const ROBOTS_FILE = /^robots\.(tsx?|jsx?)$/;

function routeKey(relPosix) {
  const parts = relPosix.split('/');
  const base = parts.pop();
  const prefix = parts.length ? `/${parts.join('/')}` : '';
  if (SITEMAP_FILE.test(base)) return `${prefix}/sitemap.xml`;
  if (ROBOTS_FILE.test(base)) return `${prefix}/robots.txt`;
  return prefix === '' ? '/' : prefix;
}

const routeFiles = walk(APP_DIR).filter((f) => {
  const base = path.basename(f);
  return ROUTE_FILE.test(base) || SITEMAP_FILE.test(base) || ROBOTS_FILE.test(base);
});

const discovered = new Set(
  routeFiles.map((f) => routeKey(path.relative(APP_DIR, f).split(path.sep).join('/'))),
);

const classification = JSON.parse(readFileSync(CLASSIFICATION_PATH, 'utf8'));
const classified = new Set(Object.keys(classification.routes ?? {}));

const missing = [...discovered].filter((k) => !classified.has(k)).sort();
const stale = [...classified].filter((k) => !discovered.has(k)).sort();

if (missing.length || stale.length) {
  if (missing.length) {
    console.error(`✗ ${missing.length} route(s) under ${APP_DIR} missing from ${CLASSIFICATION_PATH}:`);
    for (const k of missing) console.error(`    ${k}`);
  }
  if (stale.length) {
    console.error(`✗ ${stale.length} entry(ies) in ${CLASSIFICATION_PATH} with no route file:`);
    for (const k of stale) console.error(`    ${k}`);
  }
  process.exit(1);
}

- run: pnpm typecheck

- run: pnpm lint

# Lightweight presence gate (no build): every src/app route is classified
# in route-classification.json and vice-versa. The full render-MODE assert
# (assert:routes) needs `next build` and runs at deploy, so this catches a
# route added or removed without its classification entry here in plain CI.
- run: pnpm assert:routes-present

// Mechanical authorization-classification guard. Every route handler under
// src/app/api must self-declare its authorization class on its own comment line:
//
//   // authz: public | auth | admin | cron | service
//
// This asserts ONLY that the marker is present, unique, and well-formed — it does
// NOT verify the route's actual auth logic, and there is deliberately no central
// route→class table (the class lives next to the code that enforces it). A new
// route with no marker fails this test, so an unclassified handler can't ship
// silently — the same spirit as scripts/assert-route-classification.mjs.
const MARKER_RE = /^[ \t]*\/\/[ \t]*authz:[ \t]*([a-z]+)[ \t]*$/gm;
const VALID_CLASSES = new Set(['public', 'auth', 'admin', 'cron', 'service']);

describe('authz classification markers', () => {
  it('finds at least one API route file (guards against a broken glob passing vacuously)', () => {
    expect(ROUTE_FILES.length).toBeGreaterThan(0);
  });

  it.each(ROUTE_FILES)('%s declares exactly one valid authz class', (file) => {
    const src = readFileSync(file, 'utf8');
    const matches = [...src.matchAll(MARKER_RE)];

    expect(matches.length).toBeGreaterThan(0);
    expect(matches.length).toBeLessThan(2);

    const cls = matches[0][1];
    expect(VALID_CLASSES.has(cls)).toBe(true);
  });
});