@fin14/core 0.1.0

package/src/budget/validator.js

@@ -0,0 +1,74 @@
+import { BYTES_PER_KB, STRICT_IPV6_LIMIT_BYTES } from '../constants.js'
+import { resolveBudget } from '../glob.js'
+
+export function deriveStatusWarnings(results, totalBytes, limitBytes, hasOverride, file) {
+  const overBudget = totalBytes > limitBytes
+  const warnings = []
+
+  if (totalBytes > STRICT_IPV6_LIMIT_BYTES && !overBudget && !hasOverride) {
+    warnings.push({
+      code: 'E13',
+      message: `${file}: ${(totalBytes / BYTES_PER_KB).toFixed(1)}kB exceeds IPv6 heuristic (12.2kB)`,
+      path: file,
+      strictFailure: true,
+    })
+  }
+
+  for (const result of results) {
+    if (result.external === true) {
+      warnings.push({
+        code: 'E14',
+        message: `external resource counted: ${result.displayPath}`,
+        path: result.path,
+        strictFailure: true,
+      })
+    }
+  }
+
+  return warnings
+}
+
+export function validate(results, skipped, warnings, config, file) {
+  const limitBytes = resolveBudget(file, config)
+  const hasOverride = limitBytes !== config.budget.default
+  const totalBytes = results.reduce((sum, r) => sum + r.bytes, 0)
+  const overBudget = totalBytes > limitBytes
+  const unknownBudget = warnings.some(w => w.code === 'E19')
+
+  const newWarnings = [...warnings, ...deriveStatusWarnings(results, totalBytes, limitBytes, hasOverride, file)]
+
+  const status = overBudget ? 'fail' : newWarnings.length > 0 ? 'warn' : 'pass'
+
+  const cutCandidates = computeCutCandidates(results, totalBytes, limitBytes, overBudget)
+
+  return {
+    file,
+    totalBytes,
+    limitBytes,
+    status,
+    overBudget,
+    unknownBudget,
+    resources: results,
+    skippedResources: skipped,
+    warnings: newWarnings,
+    cutCandidates,
+  }
+}
+
+export function computeCutCandidates(results, totalBytes, limitBytes, overBudget) {
+  const sorted = [...results].sort((a, b) => b.bytes - a.bytes)
+
+  if (overBudget) {
+    const overage = totalBytes - limitBytes
+    const candidates = []
+    let cumulative = 0
+    for (const resource of sorted) {
+      candidates.push(resource)
+      cumulative += resource.bytes
+      if (cumulative >= overage) break
+    }
+    return candidates.length > 0 ? candidates : [sorted[0]]
+  } else {
+    return sorted.slice(0, 3)
+  }
+}

package/src/compress.js

@@ -0,0 +1,23 @@
+import { gzipSync, brotliCompressSync, constants } from 'node:zlib'
+import { GZIP_MIN_LEVEL, GZIP_MAX_LEVEL } from './constants.js'
+
+export function compress(content, config) {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  if (config.compression === 'brotli') {
+    return brotliCompressSync(buf, {
+      params: { [constants.BROTLI_PARAM_QUALITY]: config.compression_level },
+    }).length
+  }
+  const level = Math.min(Math.max(config.compression_level, GZIP_MIN_LEVEL), GZIP_MAX_LEVEL)
+  return gzipSync(buf, { level }).length
+}
+
+export function gzipLevelClampNotice(budget) {
+  if (budget.compression !== 'gzip') return null
+  const level = budget.compression_level
+  if (level < GZIP_MIN_LEVEL || level > GZIP_MAX_LEVEL) {
+    const effective = Math.min(Math.max(level, GZIP_MIN_LEVEL), GZIP_MAX_LEVEL)
+    return `compression_level ${level} clamped to ${effective} (gzip range ${GZIP_MIN_LEVEL}–${GZIP_MAX_LEVEL}); use brotli for level 0 or 10–11`
+  }
+  return null
+}

package/src/config.js

@@ -0,0 +1,313 @@
+import { readFile, access } from 'node:fs/promises'
+import { parse } from 'smol-toml'
+import { BYTES_PER_KB, COMPRESSION_LEVEL_MAX, COMPRESSION_LEVEL_MIN, DEFAULT_CONFIG, IGNORE_PRESETS } from './constants.js'
+
+const SSG_DETECTORS = [
+  { files: ['hugo.toml', 'hugo.yaml', 'hugo.json'],                                                dir: 'public' },
+  { files: ['.eleventy.js', 'eleventy.config.js', 'eleventy.config.mjs', 'eleventy.config.cjs'],   dir: '_site'  },
+  { files: ['astro.config.js', 'astro.config.ts', 'astro.config.mjs', 'astro.config.cjs'],         dir: 'dist'   },
+  { files: ['_config.yml', '_config.toml'],                                                         dir: '_site'  },
+  { files: ['next.config.js', 'next.config.ts', 'next.config.mjs'],                                dir: 'out'    },
+]
+
+async function detectOutputDir(cwd) {
+  for (const { files, dir } of SSG_DETECTORS) {
+    for (const file of files) {
+      try { await access(`${cwd}/${file}`); return dir } catch {}
+    }
+  }
+  return null
+}
+
+const KNOWN_KEYS = {
+  project:  new Set(['output_dir', 'build_command', 'include', 'exclude']),
+  budget:   new Set(['default', 'compression', 'compression_level', 'cut_candidate_min_bytes', 'baseline_min_delta_bytes', 'overrides', 'ignore', 'ignore_presets']),
+  network:  new Set(['timeout_ms', 'max_redirects']),
+  viewport: new Set(['default', 'mobile', 'desktop']),
+  warnings: new Set(['exclude']),
+}
+
+const OVERRIDE_KEYS = new Set(['path', 'budget'])
+
+function validateGlobList(value, fieldPath) {
+  if (!Array.isArray(value) || !value.every(v => typeof v === 'string')) {
+    throw new Error(`E04: fin14.toml: ${fieldPath} must be an array of strings`)
+  }
+  return value
+}
+
+function parseBudgetOverrides(value) {
+  if (!Array.isArray(value)) {
+    throw new Error(`E04: fin14.toml: budget.overrides must be an array of { path, budget } tables`)
+  }
+  return value.map((entry, i) => {
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new Error(`E04: fin14.toml: budget.overrides[${i}] must be a { path, budget } table`)
+    }
+    for (const key of Object.keys(entry)) {
+      if (!OVERRIDE_KEYS.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'budget.overrides[${i}].${key}'`)
+      }
+    }
+    if (typeof entry.path !== 'string') {
+      throw new Error(`E04: fin14.toml: budget.overrides[${i}].path: expected string`)
+    }
+    if (entry.budget === undefined) {
+      throw new Error(`E04: fin14.toml: budget.overrides[${i}].budget is required`)
+    }
+    return { path: entry.path, budget: parseBudgetDefault(entry.budget, `budget.overrides[${i}].budget`) }
+  })
+}
+
+const VIEWPORT_PRESET_KEYS = new Set(['width', 'height', 'lazy_visible_images'])
+
+function assertType(value, expectedType, fieldPath) {
+  if (typeof value !== expectedType) {
+    throw new Error(`fin14.toml: ${fieldPath}: expected ${expectedType}, got ${typeof value}`)
+  }
+}
+
+function assertInteger(value, fieldPath) {
+  if (typeof value !== 'number' || !Number.isInteger(value)) {
+    throw new Error(`fin14.toml: ${fieldPath}: expected integer, got ${typeof value}`)
+  }
+}
+
+function parseBudgetDefault(value, fieldPath = 'budget.default') {
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value)) {
+      throw new Error(`fin14.toml: ${fieldPath}: expected integer or "NNkb" string, got float`)
+    }
+    return value
+  }
+  if (typeof value === 'string') {
+    const match = value.match(/^(\d+(?:\.\d+)?)kb$/i)
+    if (!match) {
+      throw new Error(`fin14.toml: ${fieldPath}: invalid value "${value}", expected integer or "NNkb" string`)
+    }
+    return Math.round(parseFloat(match[1]) * BYTES_PER_KB)
+  }
+  throw new Error(`fin14.toml: ${fieldPath}: expected integer or string, got ${typeof value}`)
+}
+
+function validateViewportPreset(preset, name, userPreset) {
+  for (const key of Object.keys(userPreset)) {
+    if (!VIEWPORT_PRESET_KEYS.has(key)) {
+      throw new Error(`E04: fin14.toml: unknown field 'viewport.${name}.${key}'`)
+    }
+  }
+  const result = { ...preset }
+  if (userPreset.width !== undefined) {
+    assertInteger(userPreset.width, `viewport.${name}.width`)
+    if (userPreset.width <= 0) throw new Error(`fin14.toml: viewport.${name}.width: must be > 0`)
+    result.width = userPreset.width
+  }
+  if (userPreset.height !== undefined) {
+    assertInteger(userPreset.height, `viewport.${name}.height`)
+    if (userPreset.height <= 0) throw new Error(`fin14.toml: viewport.${name}.height: must be > 0`)
+    result.height = userPreset.height
+  }
+  if (userPreset.lazy_visible_images !== undefined) {
+    assertInteger(userPreset.lazy_visible_images, `viewport.${name}.lazy_visible_images`)
+    if (userPreset.lazy_visible_images < 0) throw new Error(`fin14.toml: viewport.${name}.lazy_visible_images: must be >= 0`)
+    result.lazy_visible_images = userPreset.lazy_visible_images
+  }
+  return result
+}
+
+function mergeConfig(user) {
+  const result = {
+    project:  { ...DEFAULT_CONFIG.project, include: [...DEFAULT_CONFIG.project.include], exclude: [...DEFAULT_CONFIG.project.exclude] },
+    budget:   { ...DEFAULT_CONFIG.budget, overrides: [...DEFAULT_CONFIG.budget.overrides], ignore: [...DEFAULT_CONFIG.budget.ignore], ignore_presets: [...DEFAULT_CONFIG.budget.ignore_presets] },
+    network:  { ...DEFAULT_CONFIG.network },
+    viewport: {
+      default: DEFAULT_CONFIG.viewport.default,
+      mobile:  { ...DEFAULT_CONFIG.viewport.mobile },
+      desktop: { ...DEFAULT_CONFIG.viewport.desktop },
+    },
+    warnings: { exclude: [...DEFAULT_CONFIG.warnings.exclude] },
+  }
+
+  for (const key of Object.keys(user)) {
+    if (!KNOWN_KEYS[key]) {
+      throw new Error(`E04: fin14.toml: unknown field '${key}'`)
+    }
+  }
+
+  if (user.project) {
+    for (const key of Object.keys(user.project)) {
+      if (!KNOWN_KEYS.project.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'project.${key}'`)
+      }
+    }
+    if (user.project.output_dir !== undefined) {
+      assertType(user.project.output_dir, 'string', 'project.output_dir')
+      result.project.output_dir = user.project.output_dir
+    }
+    if (user.project.build_command !== undefined) {
+      assertType(user.project.build_command, 'string', 'project.build_command')
+      result.project.build_command = user.project.build_command
+    }
+    if (user.project.include !== undefined) {
+      result.project.include = validateGlobList(user.project.include, 'project.include')
+    }
+    if (user.project.exclude !== undefined) {
+      result.project.exclude = validateGlobList(user.project.exclude, 'project.exclude')
+    }
+  }
+
+  if (user.budget) {
+    for (const key of Object.keys(user.budget)) {
+      if (!KNOWN_KEYS.budget.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'budget.${key}'`)
+      }
+    }
+    if (user.budget.default !== undefined) {
+      result.budget.default = parseBudgetDefault(user.budget.default)
+    }
+    if (user.budget.compression !== undefined) {
+      assertType(user.budget.compression, 'string', 'budget.compression')
+      if (!['gzip', 'brotli'].includes(user.budget.compression)) {
+        throw new Error(`fin14.toml: budget.compression: must be "gzip" or "brotli"`)
+      }
+      result.budget.compression = user.budget.compression
+    }
+    if (user.budget.compression_level !== undefined) {
+      assertInteger(user.budget.compression_level, 'budget.compression_level')
+      if (user.budget.compression_level < COMPRESSION_LEVEL_MIN || user.budget.compression_level > COMPRESSION_LEVEL_MAX) {
+        throw new Error(`fin14.toml: budget.compression_level: must be ${COMPRESSION_LEVEL_MIN}–${COMPRESSION_LEVEL_MAX}`)
+      }
+      result.budget.compression_level = user.budget.compression_level
+    }
+    if (user.budget.cut_candidate_min_bytes !== undefined) {
+      if (!Number.isInteger(user.budget.cut_candidate_min_bytes) || user.budget.cut_candidate_min_bytes < 0) {
+        throw new Error(`E04: fin14.toml: budget.cut_candidate_min_bytes must be a non-negative integer`)
+      }
+      result.budget.cut_candidate_min_bytes = user.budget.cut_candidate_min_bytes
+    }
+    if (user.budget.baseline_min_delta_bytes !== undefined) {
+      if (!Number.isInteger(user.budget.baseline_min_delta_bytes) || user.budget.baseline_min_delta_bytes < 0) {
+        throw new Error(`E04: fin14.toml: budget.baseline_min_delta_bytes must be a non-negative integer`)
+      }
+      result.budget.baseline_min_delta_bytes = user.budget.baseline_min_delta_bytes
+    }
+    if (user.budget.overrides !== undefined) {
+      result.budget.overrides = parseBudgetOverrides(user.budget.overrides)
+    }
+    if (user.budget.ignore !== undefined) {
+      result.budget.ignore = validateGlobList(user.budget.ignore, 'budget.ignore')
+    }
+    if (user.budget.ignore_presets !== undefined) {
+      const presets = validateGlobList(user.budget.ignore_presets, 'budget.ignore_presets')
+      for (const name of presets) {
+        if (!IGNORE_PRESETS[name]) {
+          throw new Error(`E04: fin14.toml: unknown budget.ignore_presets value '${name}' (known: ${Object.keys(IGNORE_PRESETS).join(', ')})`)
+        }
+      }
+      result.budget.ignore_presets = presets
+    }
+  }
+
+  if (user.network) {
+    for (const key of Object.keys(user.network)) {
+      if (!KNOWN_KEYS.network.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'network.${key}'`)
+      }
+    }
+    if (user.network.timeout_ms !== undefined) {
+      assertInteger(user.network.timeout_ms, 'network.timeout_ms')
+      if (user.network.timeout_ms <= 0) throw new Error(`fin14.toml: network.timeout_ms: must be > 0`)
+      result.network.timeout_ms = user.network.timeout_ms
+    }
+    if (user.network.max_redirects !== undefined) {
+      assertInteger(user.network.max_redirects, 'network.max_redirects')
+      if (user.network.max_redirects < 0) throw new Error(`fin14.toml: network.max_redirects: must be >= 0`)
+      result.network.max_redirects = user.network.max_redirects
+    }
+  }
+
+  if (user.viewport) {
+    for (const key of Object.keys(user.viewport)) {
+      if (!KNOWN_KEYS.viewport.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'viewport.${key}'`)
+      }
+    }
+    if (user.viewport.default !== undefined) {
+      assertType(user.viewport.default, 'string', 'viewport.default')
+      if (!['mobile', 'desktop'].includes(user.viewport.default)) {
+        throw new Error(`fin14.toml: viewport.default: must be "mobile" or "desktop"`)
+      }
+      result.viewport.default = user.viewport.default
+    }
+    if (user.viewport.mobile !== undefined) {
+      if (typeof user.viewport.mobile !== 'object' || Array.isArray(user.viewport.mobile)) {
+        throw new Error(`fin14.toml: viewport.mobile: expected object, got ${typeof user.viewport.mobile}`)
+      }
+      result.viewport.mobile = validateViewportPreset(result.viewport.mobile, 'mobile', user.viewport.mobile)
+    }
+    if (user.viewport.desktop !== undefined) {
+      if (typeof user.viewport.desktop !== 'object' || Array.isArray(user.viewport.desktop)) {
+        throw new Error(`fin14.toml: viewport.desktop: expected object, got ${typeof user.viewport.desktop}`)
+      }
+      result.viewport.desktop = validateViewportPreset(result.viewport.desktop, 'desktop', user.viewport.desktop)
+    }
+  }
+
+  if (user.warnings) {
+    for (const key of Object.keys(user.warnings)) {
+      if (!KNOWN_KEYS.warnings.has(key)) {
+        throw new Error(`E04: fin14.toml: unknown field 'warnings.${key}'`)
+      }
+    }
+    if (user.warnings.exclude !== undefined) {
+      if (!Array.isArray(user.warnings.exclude) || !user.warnings.exclude.every(v => typeof v === 'string')) {
+        throw new Error(`E04: fin14.toml: warnings.exclude must be an array of strings`)
+      }
+      result.warnings.exclude = user.warnings.exclude
+    }
+  }
+
+  return result
+}
+
+export async function loadConfig(options = {}) {
+  let raw = null
+
+  if (options.config) {
+    let content
+    try {
+      content = await readFile(options.config, 'utf8')
+    } catch (err) {
+      throw new Error(`E03: fin14.toml: ${err.message}`)
+    }
+    try {
+      raw = parse(content)
+    } catch (err) {
+      throw new Error(`E03: fin14.toml: ${err.message}`)
+    }
+  } else {
+    const defaultPath = `${process.cwd()}/fin14.toml`
+    try {
+      const content = await readFile(defaultPath, 'utf8')
+      try {
+        raw = parse(content)
+      } catch (err) {
+        throw new Error(`E03: fin14.toml: ${err.message}`)
+      }
+    } catch (err) {
+      if (err.message.startsWith('E03:')) throw err
+    }
+  }
+
+  const config = mergeConfig(raw ?? {})
+
+  if (options.outputDir !== undefined) {
+    config.project.output_dir = options.outputDir
+  }
+
+  if (config.project.output_dir === null) {
+    config.project.output_dir = await detectOutputDir(process.cwd())
+  }
+
+  return config
+}

package/src/constants.js

@@ -0,0 +1,42 @@
+export const BYTES_PER_KB = 1000
+export const MILLISECONDS_PER_SECOND = 1000
+
+export const DEFAULT_CONFIG = {
+  project: { output_dir: null, build_command: null, include: [], exclude: [] },
+  budget: {
+    default: 14000,
+    compression: 'gzip',
+    compression_level: 6,
+    cut_candidate_min_bytes: 2800,
+    baseline_min_delta_bytes: 100,
+    overrides: [],
+    ignore: [],
+    ignore_presets: [],
+  },
+  network: { timeout_ms: 5000, max_redirects: 5 },
+  viewport: {
+    default: 'mobile',
+    mobile: { width: 390, height: 844, lazy_visible_images: 1 },
+    desktop: { width: 1366, height: 768, lazy_visible_images: 1 },
+  },
+  warnings: { exclude: [] },
+}
+
+export const GZIP_MIN_LEVEL = 1
+export const GZIP_MAX_LEVEL = 9
+export const COMPRESSION_LEVEL_MIN = 0
+export const COMPRESSION_LEVEL_MAX = 11
+
+export const STRICT_IPV6_LIMIT_BYTES = 12200
+
+export const IGNORE_PRESETS = {
+  nextjs: { label: 'Next.js client JS', globs: ['_next/static/chunks/**.js'] },
+}
+
+export const SITE_PAGE_BATCH_SIZE = 50
+export const SITE_EMFILE_RETRY_BATCH_SIZE = 10
+export const SUMMARY_TOP_ASSET_LIMIT = 10
+
+export const EXTERNAL_CACHE_TTL_SECONDS = 3600
+export const EXTERNAL_DOMAIN_CONCURRENCY = 10
+export const EXTERNAL_DOMAIN_WAIT_MS = 50

package/src/crawler.js

@@ -0,0 +1,34 @@
+import { readdir, stat, lstat } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+export async function crawl(outputDir) {
+  const htmlFiles = []
+
+  async function walk(dir) {
+    const entries = await readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name)
+
+      if (entry.isSymbolicLink()) {
+        let linkTarget
+        try {
+          linkTarget = await stat(fullPath)
+        } catch {
+          continue
+        }
+        if (linkTarget.isFile() && entry.name.endsWith('.html')) {
+          htmlFiles.push(relative(outputDir, fullPath))
+        }
+      } else if (entry.isDirectory()) {
+        await walk(fullPath)
+      } else if (entry.isFile() && entry.name.endsWith('.html')) {
+        htmlFiles.push(relative(outputDir, fullPath))
+      }
+    }
+  }
+
+  await walk(outputDir)
+  return htmlFiles
+    .map(p => p.replace(/\\/g, '/'))
+    .sort()
+}

package/src/glob.js

@@ -0,0 +1,51 @@
+function globToRegExp(pattern) {
+  const normalized = pattern.replace(/\\/g, '/')
+  let re = ''
+  for (let i = 0; i < normalized.length; i++) {
+    const char = normalized[i]
+    if (char === '*') {
+      if (normalized[i + 1] === '*') {
+        if (normalized[i + 2] === '/') {
+          re += '(?:.*/)?'
+          i += 2
+        } else {
+          re += '.*'
+          i++
+        }
+      } else {
+        re += '[^/]*'
+      }
+    } else if (char === '?') {
+      re += '[^/]'
+    } else if ('.+^${}()|[]\\'.includes(char)) {
+      re += '\\' + char
+    } else {
+      re += char
+    }
+  }
+  return new RegExp('^' + re + '$')
+}
+
+export function matchGlob(path, pattern) {
+  return globToRegExp(pattern).test(path.replace(/\\/g, '/'))
+}
+
+export function matchesAny(path, patterns) {
+  return patterns.some(pattern => matchGlob(path, pattern))
+}
+
+export function filterPages(relPaths, config) {
+  const include = config.project?.include ?? []
+  const exclude = config.project?.exclude ?? []
+  return relPaths.filter(path => {
+    if (include.length > 0 && !matchesAny(path, include)) return false
+    if (matchesAny(path, exclude)) return false
+    return true
+  })
+}
+
+export function resolveBudget(relFile, config) {
+  const overrides = config.budget?.overrides ?? []
+  const match = overrides.find(override => matchGlob(relFile, override.path))
+  return match ? match.budget : config.budget.default
+}

package/src/ignore.js

@@ -0,0 +1,55 @@
+import { IGNORE_PRESETS } from './constants.js'
+import { matchesAny } from './glob.js'
+import { computeCutCandidates, deriveStatusWarnings } from './budget/validator.js'
+import { summarize } from './index.js'
+
+export function resolveIgnoreGlobs(config) {
+  const explicit = config.budget?.ignore ?? []
+  const presets = config.budget?.ignore_presets ?? []
+  const fromPresets = presets.flatMap(name => IGNORE_PRESETS[name]?.globs ?? [])
+  return [...explicit, ...fromPresets]
+}
+
+export function applyIgnore(resources, ignoreGlobs) {
+  const sumBytes = list => list.reduce((s, r) => s + r.bytes, 0)
+  if (!ignoreGlobs || ignoreGlobs.length === 0) {
+    return { counted: resources, ignored: [], countedBytes: sumBytes(resources), ignoredBytes: 0 }
+  }
+  const counted = []
+  const ignored = []
+  for (const r of resources) {
+    if (matchesAny(r.displayPath, ignoreGlobs)) ignored.push(r)
+    else counted.push(r)
+  }
+  return { counted, ignored, countedBytes: sumBytes(counted), ignoredBytes: sumBytes(ignored) }
+}
+
+export function applyIgnoreToPage(page, ignoreGlobs, config) {
+  const { counted, ignored, countedBytes, ignoredBytes } = applyIgnore(page.resources, ignoreGlobs)
+  const limitBytes = page.limitBytes
+  const hasOverride = limitBytes !== config.budget.default
+  const overBudget = countedBytes > limitBytes
+
+  const baseWarnings = page.warnings.filter(w => w.code !== 'E13' && w.code !== 'E14')
+  const warnings = [...baseWarnings, ...deriveStatusWarnings(counted, countedBytes, limitBytes, hasOverride, page.file)]
+  const status = overBudget ? 'fail' : warnings.length > 0 ? 'warn' : 'pass'
+
+  return {
+    ...page,
+    totalBytes: countedBytes,
+    overBudget,
+    status,
+    resources: counted,
+    ignoredResources: ignored,
+    ignoredBytes,
+    warnings,
+    cutCandidates: computeCutCandidates(counted, countedBytes, limitBytes, overBudget),
+  }
+}
+
+export function applyIgnoreToSummary(summary, ignoreGlobs, config) {
+  const results = summary.results.map(page => applyIgnoreToPage(page, ignoreGlobs, config))
+  const recomputed = summarize(results, summary.outputDir, summary.siteWarnings)
+  recomputed.generatedAt = summary.generatedAt
+  return recomputed
+}

package/src/index.js

@@ -0,0 +1,94 @@
+export { loadConfig } from './config.js'
+export { gzipLevelClampNotice } from './compress.js'
+export { matchGlob, filterPages, resolveBudget } from './glob.js'
+export { resolveIgnoreGlobs, applyIgnore, applyIgnoreToPage, applyIgnoreToSummary } from './ignore.js'
+export * from './constants.js'
+import { collect } from './budget/collector.js'
+import { filterPages } from './glob.js'
+import { measure } from './budget/measurer.js'
+import { validate } from './budget/validator.js'
+import { crawl } from './crawler.js'
+import { relative, resolve } from 'node:path'
+import {
+  SITE_EMFILE_RETRY_BATCH_SIZE,
+  SITE_PAGE_BATCH_SIZE,
+  SUMMARY_TOP_ASSET_LIMIT,
+} from './constants.js'
+
+export async function measurePage(file, config) {
+  const { refs, skipped, warnings: collectWarnings } = await collect(file, config.project.output_dir, config)
+  const { results, warnings: measureWarnings, unknownBudget } = await measure(refs, config)
+  const allWarnings = [...collectWarnings, ...measureWarnings]
+  const relFile = relative(config.project.output_dir, file)
+  const pageResult = validate(results, skipped, allWarnings, config, relFile)
+  if (unknownBudget) pageResult.unknownBudget = true
+  return pageResult
+}
+
+export async function measureSite(outputDir, config, options = {}) {
+  const configWithDir = { ...config, project: { ...config.project, output_dir: outputDir } }
+  const relPaths = filterPages(await crawl(outputDir), configWithDir)
+  const absPaths = relPaths.map(p => resolve(outputDir, p))
+  const total = absPaths.length
+
+  options.onStart?.({ total, files: relPaths })
+
+  let batchSize = SITE_PAGE_BATCH_SIZE
+  let i = 0
+  let done = 0
+  const results = []
+  const siteWarnings = []
+
+  while (i < absPaths.length) {
+    const batch = absPaths.slice(i, i + batchSize)
+    try {
+      const batchResults = await Promise.all(batch.map(async f => {
+        const result = await measurePage(f, configWithDir)
+        done++
+        options.onPageResult?.(result, { done, total })
+        return result
+      }))
+      results.push(...batchResults)
+      i += batch.length
+    } catch (err) {
+      if (err.code === 'EMFILE' && batchSize > SITE_EMFILE_RETRY_BATCH_SIZE) {
+        batchSize = SITE_EMFILE_RETRY_BATCH_SIZE
+        siteWarnings.push({ code: 'E15', message: `too many open files — retrying with batch size ${SITE_EMFILE_RETRY_BATCH_SIZE}`, strictFailure: false })
+      } else {
+        throw err
+      }
+    }
+  }
+
+  return summarize(results, outputDir, siteWarnings)
+}
+
+export function summarize(results, outputDir, siteWarnings = []) {
+  const pass = results.filter(r => r.status === 'pass').length
+  const warn = results.filter(r => r.status === 'warn').length
+  const fail = results.filter(r => r.status === 'fail').length
+  const totalBytes = results.reduce((s, r) => s + r.totalBytes, 0)
+
+  const seen = new Map()
+  for (const page of results) {
+    for (const res of page.resources) {
+      if (!seen.has(res.key) || seen.get(res.key).bytes < res.bytes) {
+        seen.set(res.key, res)
+      }
+    }
+  }
+  const topAssets = [...seen.values()].sort((a, b) => b.bytes - a.bytes).slice(0, SUMMARY_TOP_ASSET_LIMIT)
+
+  return {
+    outputDir,
+    generatedAt: new Date().toISOString(),
+    pages: results.length,
+    pass,
+    warn,
+    fail,
+    totalBytes,
+    topAssets,
+    siteWarnings,
+    results,
+  }
+}