code-foundry 1.8.0 → 1.9.0

package/.github/code-foundry.yml

@@ -41,4 +41,6 @@ custom_workflows: preserve
 staging_validation_mode: fast
 performance: auto
 performance_command:
+performance_profile:
+performance_budget_file: performance-package-budgets.json
 opencode_security_model:

package/.gitignore

@@ -46,6 +46,7 @@ cache/
 !.github/actions/cache/action.yml
 typechain/
 coverage.json
+performance-results/
 tests/.bin/
 **/.app/
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.9.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.8.0...v1.9.0) (2026-09-08)
+
+
+### Features
+
+* **performance:** standardize package audit contracts ([#501](https://github.com/0xPlayerOne/code-foundry/issues/501)) ([ab30081](https://github.com/0xPlayerOne/code-foundry/commit/ab3008120772922a1affd1e5648a99b97b02e455))
+
 ## [1.8.0](https://github.com/0xPlayerOne/code-foundry/compare/v1.7.0...v1.8.0) (2026-09-08)
 
 

package/README.md

@@ -37,6 +37,8 @@ contract. For normal updates, edit that file and run `npx code-foundry sync`.
 
 - Short workflow callers for CI, Test, Security, CodeQL, Draft PR, Release PR,
   and Release.
+- A deterministic performance lane with ordered command support, stable result
+  artifacts, and an optional shared Node package budget profile.
 - A small `.githooks/pre-commit` launcher with language-aware formatting and
   linting.
 - An optional `.mise.toml`/`mise.lock`, repository profile configuration, and

package/docs/CONFIGURATION.md

@@ -37,7 +37,9 @@ repository manifests and source
 | `toolchain`                | `auto`, `native`, `mise`                                                         | Environment setup policy; defaults to `auto`                                                                        |
 | `staging_validation_mode`  | `fast`, `audit`                                                                  | Validation tier for pull requests targeting `staging`; defaults to `fast`                                           |
 | `performance`              | `auto`, `true`, `false`                                                          | Run a deterministic performance task when a supported entrypoint exists; defaults to `auto`                         |
-| `performance_command`      | JSON string array                                                                | Command argv for non-package performance harnesses; package scripts take precedence                                 |
+| `performance_command`      | JSON argv array or array of argv arrays                                          | One or more ordered commands for non-package harnesses; package scripts take precedence                             |
+| `performance_profile`      | empty, `node-package`                                                            | Optional shared package import, memory, archive, and dependency budget harness                                      |
+| `performance_budget_file`  | repository path                                                                  | Budget policy for the shared package harness; defaults to `performance-package-budgets.json`                        |
 | `features`                 | `all` or a list                                                                  | Standard workflow callers                                                                                           |
 | `codeql`                   | `auto`, `true`, `false`                                                          | CodeQL policy; public repositories default to enabled, non-public repositories default to disabled                  |
 | `codeql_rust_shards`       | JSON array of paths                                                              | Rust scan scopes; `["all"]` keeps the safe single full scan                                                         |
@@ -62,7 +64,8 @@ Supported features are `ci`, `codeql`, `security`, `test`, `draft-pr`,
 
 The shared Test workflow exposes a deterministic `Performance` job. In JavaScript
 repositories it discovers `performance:check` first and `perf:check` second. Other
-repositories can declare an argv array without shell interpolation:
+repositories can declare one argv array, or an ordered array of argv arrays, without
+shell interpolation:
 
 ```yaml
 performance: true
@@ -70,6 +73,37 @@ performance_command: '["python3","scripts/performance_audit.py","--check"]'
 performance_runner: ubuntu-latest
 ```
 
+The `node-package` profile adds a shared, repository-configured audit:
+
+```yaml
+performance: true
+performance_profile: node-package
+performance_budget_file: performance-package-budgets.json
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "importTarget": "./dist/index.js",
+  "controlImport": "typebox",
+  "samples": 7,
+  "budgets": {
+    "coldImportP95Ms": 150,
+    "coldImportRssMaxBytes": 25000000,
+    "packedBytes": 500000,
+    "productionDependencyCount": 20
+  }
+}
+```
+
+Supported budgets are `coldImportP50Ms`, `coldImportP95Ms`,
+`coldImportRssMaxBytes`, `coldImportRelativeP50`, `packedBytes`,
+`unpackedBytes`, `packageFileCount`, `packageMapFileCount`, and
+`productionDependencyCount`. The profile writes
+`performance-results/node-package.json`. Every performance run also writes
+`performance-results/summary.json`, including repository-owned scripts and
+configured commands, so artifact consumers have one stable status contract.
+
 `performance: false` disables discovery. Performance budgets, fixtures, mock
 providers, and live endpoint credentials remain repository-owned. The shared job
 owns checkout, pinned setup, billing controls, concurrency, and artifact upload;

package/docs/WORKFLOWS.md

@@ -76,15 +76,15 @@ repositories can opt in or out without a code change.
 
 ## Standard workflow responsibilities
 
-| Workflow   | Responsibility                                                |
-| ---------- | ------------------------------------------------------------- |
-| CI         | Format, lint, type-check, and build                           |
-| Test       | Unit, performance, integration, E2E, and smoke tests          |
-| Security   | Profile, audits, and public-only Dependency Review            |
-| CodeQL     | GitHub-native code scanning, kept separate from CI            |
-| Draft PR   | Create/update development pull requests                       |
-| Release PR | Promote `staging` into `main` (staging-release topology only) |
-| Release    | Release Please, GitHub release, and optional npm publication  |
+| Workflow   | Responsibility                                                    |
+| ---------- | ----------------------------------------------------------------- |
+| CI         | Format, lint, type-check, and build                               |
+| Test       | Unit, standardized performance, integration, E2E, and smoke tests |
+| Security   | Profile, audits, and public-only Dependency Review                |
+| CodeQL     | GitHub-native code scanning, kept separate from CI                |
+| Draft PR   | Create/update development pull requests                           |
+| Release PR | Promote `staging` into `main` (staging-release topology only)     |
+| Release    | Release Please, GitHub release, and optional npm publication      |
 
 Use concise job names such as `CI / Format`, `Test / Unit`, and
 `CodeQL / Analyze (Python)`. Per-language CodeQL analyzers (Rust shards

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "code-foundry",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "A fast, language-aware repository factory for agent-ready workflows, testing, security, and release automation.",
   "homepage": "https://github.com/0xPlayerOne/code-foundry#readme",
   "bugs": {

package/src/commands/sync.mjs

@@ -1092,6 +1092,8 @@ function createDefaultConfig(root, source, configuredWorkflow) {
     staging_validation_mode: 'fast',
     performance: 'auto',
     performance_command: '',
+    performance_profile: '',
+    performance_budget_file: 'performance-package-budgets.json',
     prune_standard: 'false',
     cache_packages: 'auto',
     cache_build: 'auto',

package/src/lib/node-package-performance.mjs

@@ -0,0 +1,224 @@
+// @ts-check
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+
+const METRICS = new Set([
+  'coldImportP50Ms',
+  'coldImportP95Ms',
+  'coldImportRssMaxBytes',
+  'coldImportRelativeP50',
+  'packedBytes',
+  'unpackedBytes',
+  'packageFileCount',
+  'packageMapFileCount',
+  'productionDependencyCount',
+])
+
+/** @param {number[]} values @param {number} percent */
+export function percentile(values, percent) {
+  if (values.length === 0) throw new Error('percentile requires at least one value')
+  // oxlint-disable-next-line unicorn/no-array-sort -- The project typechecks against ES2022.
+  const ordered = [...values].sort((a, b) => a - b)
+  const position = ((ordered.length - 1) * percent) / 100
+  const lower = Math.floor(position)
+  const upper = Math.min(lower + 1, ordered.length - 1)
+  const fraction = position - lower
+  return ordered[lower] + (ordered[upper] - ordered[lower]) * fraction
+}
+
+/** @param {string} root @param {string} budgetFile @param {string} resultsDirectory */
+export function runNodePackagePerformance(
+  root,
+  budgetFile = 'performance-package-budgets.json',
+  resultsDirectory = 'performance-results'
+) {
+  const packageJson = readJson(resolve(root, 'package.json'), 'package.json')
+  const policy = readJson(resolve(root, budgetFile), budgetFile)
+  if (policy.schemaVersion !== 1) throw new Error(`${budgetFile} must declare schemaVersion 1.`)
+
+  const samples = policy.samples ?? 7
+  if (!Number.isInteger(samples) || samples < 3 || samples > 50)
+    throw new Error(`${budgetFile} samples must be an integer from 3 through 50.`)
+  const budgets = policy.budgets
+  if (!budgets || typeof budgets !== 'object' || Array.isArray(budgets))
+    throw new Error(`${budgetFile} budgets must be an object.`)
+  for (const [name, maximum] of Object.entries(budgets)) {
+    if (!METRICS.has(name)) throw new Error(`${budgetFile} contains unknown metric ${name}.`)
+    if (typeof maximum !== 'number' || !Number.isFinite(maximum) || maximum < 0)
+      throw new Error(`${budgetFile} budget ${name} must be a non-negative finite number.`)
+  }
+
+  const importTarget = resolve(root, policy.importTarget ?? packageEntry(packageJson))
+  if (!existsSync(importTarget))
+    throw new Error(`Node package performance import target does not exist: ${importTarget}`)
+  const imports = measureImports(root, pathToFileURL(importTarget).href, samples)
+  const control = policy.controlImport
+    ? measureImports(root, String(policy.controlImport), samples)
+    : null
+  const pack = npmJson(root, ['pack', '--dry-run', '--json', '--ignore-scripts'], 'npm pack')
+  const packed = Array.isArray(pack) ? pack[0] : pack
+  if (!packed || typeof packed !== 'object') throw new Error('npm pack returned no package result.')
+  /** @type {Array<{path?: string}>} */
+  const files = Array.isArray(packed.files) ? packed.files : []
+  const productionDependencyCount = npmProductionDependencyCount(root)
+  const metrics = {
+    coldImportP50Ms: round(
+      percentile(
+        imports.map((sample) => sample.durationMs),
+        50
+      )
+    ),
+    coldImportP95Ms: round(
+      percentile(
+        imports.map((sample) => sample.durationMs),
+        95
+      )
+    ),
+    coldImportRssMaxBytes: Math.max(...imports.map((sample) => sample.rssDeltaBytes)),
+    ...(control
+      ? {
+          coldImportRelativeP50: round(
+            percentile(
+              imports.map((sample) => sample.durationMs),
+              50
+            ) /
+              percentile(
+                control.map((sample) => sample.durationMs),
+                50
+              )
+          ),
+        }
+      : {}),
+    packedBytes: numberField(packed, 'size'),
+    unpackedBytes: numberField(packed, 'unpackedSize'),
+    packageFileCount: files.length,
+    packageMapFileCount: files.filter(
+      (file) => file && typeof file === 'object' && String(file.path ?? '').endsWith('.map')
+    ).length,
+    productionDependencyCount,
+  }
+  const failures = Object.entries(budgets).flatMap(([name, maximum]) => {
+    const value = metrics[/** @type {keyof typeof metrics} */ (name)]
+    if (typeof value !== 'number' || !Number.isFinite(value)) return [`${name}: metric unavailable`]
+    return value > maximum ? [`${name}: ${value} > ${maximum}`] : []
+  })
+  const result = {
+    schemaVersion: 1,
+    kind: 'code-foundry-node-package-performance',
+    recordedAt: new Date().toISOString(),
+    package: typeof packageJson.name === 'string' ? packageJson.name : null,
+    importTarget: String(policy.importTarget ?? packageEntry(packageJson)),
+    controlImport: policy.controlImport ?? null,
+    samples,
+    metrics,
+    budgets,
+    failures,
+    passed: failures.length === 0,
+  }
+  const output = resolve(root, resultsDirectory, 'node-package.json')
+  mkdirSync(dirname(output), { recursive: true })
+  writeFileSync(output, `${JSON.stringify(result, null, 2)}\n`)
+  return result
+}
+
+/** @param {string} root @param {string} specifier @param {number} samples */
+function measureImports(root, specifier, samples) {
+  return Array.from({ length: samples }, () => {
+    const source = [
+      'const before = process.memoryUsage().rss',
+      'const started = performance.now()',
+      `await import(${JSON.stringify(specifier)})`,
+      'const durationMs = performance.now() - started',
+      'const rssDeltaBytes = Math.max(0, process.memoryUsage().rss - before)',
+      'process.stdout.write(JSON.stringify({ durationMs, rssDeltaBytes }))',
+    ].join(';')
+    const result = spawnSync(process.execPath, ['--input-type=module', '--eval', source], {
+      cwd: root,
+      encoding: 'utf8',
+      env: process.env,
+    })
+    if (result.error) throw result.error
+    if (result.status !== 0)
+      throw new Error(`cold import failed for ${specifier}: ${result.stderr.trim()}`)
+    const value = JSON.parse(result.stdout)
+    if (
+      typeof value.durationMs !== 'number' ||
+      !Number.isFinite(value.durationMs) ||
+      typeof value.rssDeltaBytes !== 'number' ||
+      !Number.isFinite(value.rssDeltaBytes)
+    )
+      throw new Error(`cold import returned invalid metrics for ${specifier}.`)
+    return value
+  })
+}
+
+/** @param {Record<string, any>} packageJson */
+function packageEntry(packageJson) {
+  const rootExport = packageJson.exports?.['.'] ?? packageJson.exports
+  if (typeof rootExport === 'string') return rootExport
+  if (rootExport && typeof rootExport === 'object') {
+    for (const key of ['import', 'default', 'node', 'require']) {
+      if (typeof rootExport[key] === 'string') return rootExport[key]
+    }
+  }
+  for (const key of ['module', 'main']) {
+    if (typeof packageJson[key] === 'string') return packageJson[key]
+  }
+  throw new Error('Unable to infer a package import target; set importTarget in the budget file.')
+}
+
+/** @param {string} root */
+function npmProductionDependencyCount(root) {
+  const result = spawnSync('npm', ['ls', '--omit=dev', '--all', '--parseable', '--silent'], {
+    cwd: root,
+    encoding: 'utf8',
+    env: process.env,
+  })
+  if (result.error || result.status !== 0) return null
+  return Math.max(
+    0,
+    result.stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean).length - 1
+  )
+}
+
+/** @param {string} root @param {string[]} args @param {string} label */
+function npmJson(root, args, label) {
+  const result = spawnSync('npm', args, { cwd: root, encoding: 'utf8', env: process.env })
+  if (result.error) throw result.error
+  if (result.status !== 0) throw new Error(`${label} failed: ${result.stderr.trim()}`)
+  try {
+    return JSON.parse(result.stdout)
+  } catch {
+    throw new Error(`${label} did not return valid JSON.`)
+  }
+}
+
+/** @param {string} file @param {string} label */
+function readJson(file, label) {
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(
+      `${label} must contain valid JSON: ${error instanceof Error ? error.message : error}`,
+      { cause: error }
+    )
+  }
+}
+
+/** @param {Record<string, any>} value @param {string} field */
+function numberField(value, field) {
+  if (typeof value[field] !== 'number' || !Number.isFinite(value[field]))
+    throw new Error(`npm pack result is missing numeric ${field}.`)
+  return value[field]
+}
+
+/** @param {number} value */
+function round(value) {
+  return Math.round(value * 1000) / 1000
+}

package/src/runtime.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // @ts-check
 
-import { appendFileSync, existsSync, readFileSync } from 'node:fs'
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { spawnSync } from 'node:child_process'
 import { detectPackageManager, resolveProfile } from './lib/profile.mjs'
@@ -9,6 +9,7 @@ import { configured, readConfig } from './lib/config.mjs'
 import { classifyTestFiles } from './lib/test-discovery.mjs'
 import { classifyValidationMode, evaluateValidationGate } from './lib/validation-policy.mjs'
 import { readReleaseConfig, validateGeneratedReleaseDiff } from './lib/release-policy.mjs'
+import { runNodePackagePerformance } from './lib/node-package-performance.mjs'
 
 const root = process.cwd()
 const config = readConfig(resolve(root, '.github/code-foundry.yml'))
@@ -56,23 +57,118 @@ function performanceEnabled() {
   return configured(config.performance, 'auto') !== 'false'
 }
 
-function performanceCommand() {
+function performanceCommands() {
   const raw = configured(config.performance_command, '').trim()
-  if (!raw) return null
+  if (!raw) return []
   let command
   try {
     command = JSON.parse(raw)
   } catch {
-    throw new Error('performance_command must be a JSON array of command arguments.')
+    throw new Error('performance_command must be a JSON argv array or an array of argv arrays.')
   }
+  if (!Array.isArray(command) || command.length === 0)
+    throw new Error('performance_command must be a non-empty JSON array.')
+  const commands = command.every((argument) => typeof argument === 'string') ? [command] : command
   if (
-    !Array.isArray(command) ||
-    command.length === 0 ||
-    command.some((argument) => typeof argument !== 'string' || argument.length === 0)
-  ) {
-    throw new Error('performance_command must be a non-empty JSON array of non-empty strings.')
+    !commands.every(
+      (argv) =>
+        Array.isArray(argv) &&
+        argv.length > 0 &&
+        argv.every((argument) => typeof argument === 'string' && argument.length > 0)
+    )
+  )
+    throw new Error(
+      'performance_command must contain one argv array or only non-empty argv arrays of non-empty strings.'
+    )
+  return /** @type {string[][]} */ (commands)
+}
+
+function performanceProfile() {
+  const profile = configured(config.performance_profile, '').trim()
+  if (!profile) return ''
+  if (profile !== 'node-package')
+    throw new Error(`Unsupported performance_profile: ${profile}. Expected node-package.`)
+  return profile
+}
+
+const performanceResultsDirectory = 'performance-results'
+
+/** @returns {{source: string, argv: string[]}[]} */
+function selectedPerformanceCommands() {
+  const name = ['performance:check', 'perf:check'].find((candidate) => hasScript(candidate))
+  if (name) {
+    const [manager, args] = packageCommand(['run', name])
+    return manager ? [{ source: `package-script:${name}`, argv: [manager, ...args] }] : []
+  }
+  return performanceCommands().map((argv) => ({ source: 'configuration', argv }))
+}
+
+/** @param {string} startedAt @param {'passed'|'failed'} status @param {{source: string, argv: string[], status: number}[]} commands @param {string[]} artifacts @param {string|null} error */
+function writePerformanceSummary(startedAt, status, commands, artifacts, error = null) {
+  const directory = resolve(root, performanceResultsDirectory)
+  mkdirSync(directory, { recursive: true })
+  writeFileSync(
+    resolve(directory, 'summary.json'),
+    `${JSON.stringify(
+      {
+        schemaVersion: 1,
+        kind: 'code-foundry-performance-summary',
+        status,
+        startedAt,
+        completedAt: new Date().toISOString(),
+        commands,
+        profile: performanceProfile() || null,
+        artifacts,
+        error,
+      },
+      null,
+      2
+    )}\n`
+  )
+}
+
+function runPerformance() {
+  if (!performanceEnabled()) return
+  const startedAt = new Date().toISOString()
+  /** @type {{source: string, argv: string[], status: number}[]} */
+  const records = []
+  /** @type {string[]} */
+  const artifacts = []
+  try {
+    for (const command of selectedPerformanceCommands()) {
+      const result = spawnSync(command.argv[0], command.argv.slice(1), {
+        cwd: root,
+        stdio: 'inherit',
+        env: process.env,
+      })
+      if (result.error) throw result.error
+      const status = result.status ?? 1
+      records.push({ ...command, status })
+      if (status !== 0) {
+        writePerformanceSummary(startedAt, 'failed', records, artifacts, `command exited ${status}`)
+        process.exitCode = status
+        return
+      }
+    }
+    if (performanceProfile() === 'node-package') {
+      const result = runNodePackagePerformance(
+        root,
+        configured(config.performance_budget_file, 'performance-package-budgets.json'),
+        performanceResultsDirectory
+      )
+      artifacts.push(`${performanceResultsDirectory}/node-package.json`)
+      if (!result.passed) {
+        writePerformanceSummary(startedAt, 'failed', records, artifacts, result.failures.join('; '))
+        process.exitCode = 1
+        return
+      }
+    }
+    writePerformanceSummary(startedAt, 'passed', records, artifacts)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    writePerformanceSummary(startedAt, 'failed', records, artifacts, message)
+    throw error
   }
-  return command
 }
 
 /** @param {string} task */
@@ -299,7 +395,9 @@ function relevant(task) {
   if (task === 'performance') {
     if (!performanceEnabled()) return false
     return Boolean(
-      (scripted && scripted.some((candidate) => hasScript(candidate))) || performanceCommand()
+      (scripted && scripted.some((candidate) => hasScript(candidate))) ||
+      performanceCommands().length > 0 ||
+      performanceProfile()
     )
   }
   if (scripted && scripted.some((candidate) => hasScript(candidate)))
@@ -465,11 +563,7 @@ function ci(task) {
     return
   }
   if (task === 'performance') {
-    if (!performanceEnabled()) return
-    if (runScript(['performance:check', 'perf:check'])) return
-    const command = performanceCommand()
-    if (command) run(command[0], command.slice(1))
-    return
+    return runPerformance()
   }
   /** @type {Record<string, string[]>} */
   const scriptsByTask = {

package/src/templates/gitignore

@@ -46,6 +46,7 @@ cache/
 !.github/actions/cache/action.yml
 typechain/
 coverage.json
+performance-results/
 tests/.bin/
 **/.app/