infra-kit 0.1.102 → 0.1.107

package/src/lib/package-validator/checks/__tests__/checks.test.ts

@@ -0,0 +1,130 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { checkFiles } from '../files-check'
+import { checkScripts } from '../scripts-check'
+import { checkTurbo } from '../turbo-check'
+
+const tmpDirs: string[] = []
+
+const makeTmpDir = (): string => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'checks-'))
+
+  tmpDirs.push(dir)
+
+  return dir
+}
+
+afterEach(() => {
+  while (tmpDirs.length > 0) {
+    const dir = tmpDirs.pop()
+
+    if (dir) {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+  }
+})
+
+describe('checkScripts', () => {
+  it('passes a script defined with a runnable command', () => {
+    const checks = checkScripts({ build: 'tsc' }, ['build'])
+
+    expect(checks).toEqual([{ name: 'script:build', status: 'pass', message: 'defined' }])
+  })
+
+  it('fails a script that is absent from the scripts map', () => {
+    const checks = checkScripts({}, ['build'])
+
+    expect(checks[0]).toMatchObject({ name: 'script:build', status: 'fail' })
+    expect(checks[0]?.message).toContain('missing')
+  })
+
+  it('fails a script declared with an empty value', () => {
+    const checks = checkScripts({ build: '' }, ['build'])
+
+    expect(checks[0]).toMatchObject({ name: 'script:build', status: 'fail' })
+    expect(checks[0]?.message).toContain('empty')
+  })
+
+  it('fails a script declared with a whitespace-only value', () => {
+    const checks = checkScripts({ build: '   ' }, ['build'])
+
+    expect(checks[0]).toMatchObject({ name: 'script:build', status: 'fail' })
+    expect(checks[0]?.message).toContain('empty')
+  })
+})
+
+describe('checkFiles', () => {
+  it('passes a required path that is a regular file', async () => {
+    const dir = makeTmpDir()
+
+    fs.writeFileSync(path.join(dir, 'readme.md'), '# hi')
+
+    const checks = await checkFiles(dir, ['readme.md'])
+
+    expect(checks[0]).toMatchObject({ name: 'file:readme.md', status: 'pass' })
+  })
+
+  it('fails a required file that does not exist', async () => {
+    const dir = makeTmpDir()
+
+    const checks = await checkFiles(dir, ['readme.md'])
+
+    expect(checks[0]).toMatchObject({ name: 'file:readme.md', status: 'fail' })
+    expect(checks[0]?.message).toContain('missing file')
+  })
+
+  it('fails a required path that exists but is a directory', async () => {
+    const dir = makeTmpDir()
+
+    fs.mkdirSync(path.join(dir, 'readme.md'))
+
+    const checks = await checkFiles(dir, ['readme.md'])
+
+    expect(checks[0]).toMatchObject({ name: 'file:readme.md', status: 'fail' })
+    expect(checks[0]?.message).toContain('not a file')
+  })
+})
+
+describe('checkTurbo', () => {
+  it('returns no checks when no turbo tasks are required', async () => {
+    const dir = makeTmpDir()
+
+    expect(await checkTurbo(dir, [])).toEqual([])
+  })
+
+  it('fails with a single diagnostic when turbo.json cannot be read', async () => {
+    const dir = makeTmpDir()
+
+    const checks = await checkTurbo(dir, ['build'])
+
+    expect(checks).toHaveLength(1)
+    expect(checks[0]).toMatchObject({ name: 'turbo.json', status: 'fail' })
+    expect(checks[0]?.message).toContain('cannot read/parse')
+  })
+
+  it('fails with a single diagnostic when turbo.json has no tasks object', async () => {
+    const dir = makeTmpDir()
+
+    fs.writeFileSync(path.join(dir, 'turbo.json'), JSON.stringify({ $schema: 'x' }))
+
+    const checks = await checkTurbo(dir, ['build', 'test'])
+
+    expect(checks).toHaveLength(1)
+    expect(checks[0]).toMatchObject({ name: 'turbo.json', status: 'fail' })
+    expect(checks[0]?.message).toContain('no "tasks" object')
+  })
+
+  it('reports per-task results when a tasks object exists', async () => {
+    const dir = makeTmpDir()
+
+    fs.writeFileSync(path.join(dir, 'turbo.json'), JSON.stringify({ tasks: { build: {} } }))
+
+    const checks = await checkTurbo(dir, ['build', 'test'])
+
+    expect(checks).toContainEqual(expect.objectContaining({ name: 'turbo:build', status: 'pass' }))
+    expect(checks).toContainEqual(expect.objectContaining({ name: 'turbo:test', status: 'fail' }))
+  })
+})

package/src/lib/package-validator/checks/config-check.ts

@@ -0,0 +1,30 @@
+import { DEFAULT_RULES } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+
+import { PACKAGE_CONFIG_FILE, loadPackageConfig } from '../loader'
+import type { PackageCheck } from '../types'
+
+/**
+ * Build the "config present and valid" check, returning the resolved rules when
+ * the load succeeds so the caller can run the rule-based checks against them.
+ * When the config fails to load the rules are `null` and the caller skips the
+ * rule-based checks (the expectations are unknown).
+ */
+export const checkConfig = async (
+  packageDir: string,
+  baseline: Readonly<ResolvedPackageRules> = DEFAULT_RULES,
+): Promise<{ check: PackageCheck; rules: ResolvedPackageRules | null }> => {
+  try {
+    const rules = await loadPackageConfig(packageDir, baseline)
+
+    return {
+      check: { name: PACKAGE_CONFIG_FILE, status: 'pass', message: 'present and valid' },
+      rules,
+    }
+  } catch (err) {
+    return {
+      check: { name: PACKAGE_CONFIG_FILE, status: 'fail', message: (err as Error).message },
+      rules: null,
+    }
+  }
+}

package/src/lib/package-validator/checks/files-check.ts

@@ -0,0 +1,29 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { PackageCheck } from '../types'
+
+/**
+ * Check that every required file exists relative to the package root AND is a
+ * regular file. A directory that happens to share the required name fails — a
+ * required `readme.md` must be the file, not a folder.
+ */
+export const checkFiles = async (packageDir: string, requiredFiles: string[]): Promise<PackageCheck[]> => {
+  return Promise.all(
+    requiredFiles.map(async (file) => {
+      const stat = await fs.stat(path.join(packageDir, file)).catch(() => {
+        return null
+      })
+
+      if (!stat) {
+        return { name: `file:${file}`, status: 'fail' as const, message: `missing file: ${file}` }
+      }
+
+      if (!stat.isFile()) {
+        return { name: `file:${file}`, status: 'fail' as const, message: `not a file: ${file} (found a directory)` }
+      }
+
+      return { name: `file:${file}`, status: 'pass' as const, message: 'exists' }
+    }),
+  )
+}

package/src/lib/package-validator/checks/index.ts

@@ -0,0 +1,4 @@
+export { checkConfig } from './config-check'
+export { checkFiles } from './files-check'
+export { checkScripts } from './scripts-check'
+export { checkTurbo } from './turbo-check'

package/src/lib/package-validator/checks/scripts-check.ts

@@ -0,0 +1,23 @@
+import type { PackageCheck } from '../types'
+
+/**
+ * Check that every required script is present in the package.json `scripts` map
+ * and carries a runnable command. A key declared with an empty or whitespace-only
+ * value fails as well — an empty script silently no-ops in CI, so presence alone
+ * is not enough.
+ */
+export const checkScripts = (scripts: Record<string, string>, requiredScripts: string[]): PackageCheck[] => {
+  return requiredScripts.map((script) => {
+    const value = scripts[script]
+
+    if (typeof value !== 'string') {
+      return { name: `script:${script}`, status: 'fail', message: `missing "${script}" in package.json scripts` }
+    }
+
+    if (value.trim().length === 0) {
+      return { name: `script:${script}`, status: 'fail', message: `"${script}" is empty in package.json scripts` }
+    }
+
+    return { name: `script:${script}`, status: 'pass', message: 'defined' }
+  })
+}

package/src/lib/package-validator/checks/turbo-check.ts

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { PackageCheck } from '../types'
+
+const TURBO_FILE = 'turbo.json'
+
+/**
+ * Check that every required turbo task is defined in turbo.json `tasks`. A root
+ * task may be keyed as either `name` or `//#name`, so both forms count as present.
+ * Runs only when the resolved rules ask for turbo tasks (the monorepo root).
+ *
+ * Reports a single clear diagnostic when turbo.json is unreadable or carries no
+ * `tasks` object, rather than emitting one identical "missing task" line per
+ * required task.
+ */
+export const checkTurbo = async (packageDir: string, requiredTasks: string[]): Promise<PackageCheck[]> => {
+  if (requiredTasks.length === 0) {
+    return []
+  }
+
+  let parsed: { tasks?: Record<string, unknown> }
+
+  try {
+    const raw = await fs.readFile(path.join(packageDir, TURBO_FILE), 'utf-8')
+
+    parsed = JSON.parse(raw) as { tasks?: Record<string, unknown> }
+  } catch (err) {
+    return [{ name: TURBO_FILE, status: 'fail', message: `cannot read/parse ${TURBO_FILE}: ${(err as Error).message}` }]
+  }
+
+  const tasks = parsed.tasks
+
+  if (tasks === null || typeof tasks !== 'object') {
+    return [{ name: TURBO_FILE, status: 'fail', message: `no "tasks" object defined in ${TURBO_FILE}` }]
+  }
+
+  return requiredTasks.map((task) => {
+    const defined = task in tasks || `//#${task}` in tasks
+
+    return {
+      name: `turbo:${task}`,
+      status: defined ? 'pass' : 'fail',
+      message: defined ? 'defined' : `missing turbo task "${task}" in ${TURBO_FILE}`,
+    }
+  })
+}

package/src/lib/package-validator/fs-utils.ts

@@ -0,0 +1,18 @@
+import fs from 'node:fs/promises'
+
+/**
+ * Resolve whether a path is reachable, suppressing ENOENT into a boolean.
+ *
+ * @example
+ * await pathExists('/etc/hosts') // => true
+ * await pathExists('/nope')      // => false
+ */
+export const pathExists = async (target: string): Promise<boolean> => {
+  try {
+    await fs.access(target)
+
+    return true
+  } catch {
+    return false
+  }
+}

package/src/lib/package-validator/index.ts

@@ -0,0 +1,3 @@
+export { pathExists } from './fs-utils'
+export { discoverPackages, loadPackageConfig, validatePackage } from './package-validator'
+export type { PackageCheck, PackageValidationResult } from './package-validator'

package/src/lib/package-validator/loader/config-loader.ts

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
+
+import { DEFAULT_RULES, packageConfigSchema, resolvePackageConfig } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+
+import { pathExists } from '../fs-utils'
+
+/** Per-package config filename every validated package must provide. */
+export const PACKAGE_CONFIG_FILE = 'infra-kit.config.ts'
+
+interface PackageJsonShape {
+  name?: string
+  scripts?: Record<string, string>
+}
+
+/**
+ * Read and JSON-parse a package.json, returning an empty object when it is
+ * missing or unreadable so callers can degrade into a clear "missing" check.
+ */
+export const readPackageJson = async (packageDir: string): Promise<PackageJsonShape> => {
+  try {
+    const raw = await fs.readFile(path.join(packageDir, 'package.json'), 'utf-8')
+
+    return JSON.parse(raw) as PackageJsonShape
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Load, resolve, and validate a package's `infra-kit.config.ts`.
+ *
+ * Dynamic-imports the file (ESM), resolves the Vite-style factory or object
+ * default export, validates the result against {@link packageConfigSchema}, and
+ * merges it over the defaults. Throws a descriptive error when the file is
+ * absent or the resolved config violates the schema.
+ *
+ * @example
+ * await loadPackageConfig('/repo/packages/serverless-config')
+ * // => { requiredScripts: [], requiredFiles: ['serverless.common.yml'], turboTasks: [] }
+ */
+export const loadPackageConfig = async (
+  packageDir: string,
+  baseline: Readonly<ResolvedPackageRules> = DEFAULT_RULES,
+): Promise<ResolvedPackageRules> => {
+  const configPath = path.join(packageDir, PACKAGE_CONFIG_FILE)
+
+  if (!(await pathExists(configPath))) {
+    throw new Error(`${PACKAGE_CONFIG_FILE} not found at ${configPath}`)
+  }
+
+  // Cache-bust with the file mtime so repeated loads (long-running MCP server)
+  // pick up edits without a process restart. `.ts` configs load via Node's
+  // native type stripping (the repo requires Node >= 24).
+  const stat = await fs.stat(configPath)
+  const moduleUrl = `${pathToFileURL(configPath).href}?mtime=${Number(stat.mtimeMs)}`
+
+  const imported = (await import(moduleUrl)) as { default?: unknown }
+  const rawExport = imported.default
+
+  if (rawExport === undefined) {
+    throw new Error(`${PACKAGE_CONFIG_FILE} at ${configPath} has no default export`)
+  }
+
+  const resolvedExport = typeof rawExport === 'function' ? await (rawExport as () => unknown)() : rawExport
+
+  const parsed = packageConfigSchema.safeParse(resolvedExport)
+
+  if (!parsed.success) {
+    throw new Error(`Invalid ${PACKAGE_CONFIG_FILE} at ${configPath}: ${z.prettifyError(parsed.error)}`)
+  }
+
+  return resolvePackageConfig(parsed.data, baseline)
+}

package/src/lib/package-validator/loader/index.ts

@@ -0,0 +1,2 @@
+export { loadPackageConfig, PACKAGE_CONFIG_FILE, readPackageJson } from './config-loader'
+export { discoverPackages } from './package-discovery'

package/src/lib/package-validator/loader/package-discovery.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import yaml from 'yaml'
+
+import { pathExists } from '../fs-utils'
+
+const WORKSPACE_FILE = 'pnpm-workspace.yaml'
+
+/**
+ * List the immediate child directories of `dir`, returning `[]` when the path
+ * can't be read (e.g. the parent glob segment matched a non-existent dir).
+ */
+const listChildDirs = async (dir: string): Promise<string[]> => {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => {
+    return []
+  })
+
+  return entries
+    .filter((entry) => {
+      return entry.isDirectory()
+    })
+    .map((entry) => {
+      return path.join(dir, entry.name)
+    })
+}
+
+/**
+ * Apply one glob segment to a set of directories: `*` fans out to every child
+ * directory, a literal segment keeps the dirs where that child path exists.
+ */
+const expandSegment = async (dirs: string[], segment: string): Promise<string[]> => {
+  const next: string[] = []
+
+  for (const dir of dirs) {
+    if (segment === '*') {
+      next.push(...(await listChildDirs(dir)))
+
+      continue
+    }
+
+    const candidate = path.join(dir, segment)
+
+    if (await pathExists(candidate)) {
+      next.push(candidate)
+    }
+  }
+
+  return next
+}
+
+/**
+ * Expand a single pnpm-workspace glob (only the `*` segment wildcard is
+ * supported, which covers every pattern this monorepo uses) into directories.
+ */
+const expandGlob = async (projectRoot: string, pattern: string): Promise<string[]> => {
+  let dirs = [projectRoot]
+
+  for (const segment of pattern.split('/')) {
+    dirs = await expandSegment(dirs, segment)
+  }
+
+  return dirs
+}
+
+/**
+ * Discover validatable workspace packages from `pnpm-workspace.yaml`.
+ *
+ * Negation patterns (`!…`) and everything under `vendor/` are excluded —
+ * vendor is mirrored from `starter-workspace` and is checksum-enforced by
+ * `pnpm vendor:check`, so its configs are owned upstream, not here. Only
+ * directories that actually contain a package.json are returned.
+ *
+ * @example
+ * await discoverPackages('/repo')
+ * // => ['/repo/apps/infra-kit/cli', '/repo/packages/serverless-config']
+ */
+export const discoverPackages = async (projectRoot: string): Promise<string[]> => {
+  const raw = await fs.readFile(path.join(projectRoot, WORKSPACE_FILE), 'utf-8')
+  const parsed = (yaml.parse(raw) ?? {}) as { packages?: string[] }
+
+  const patterns = (parsed.packages ?? []).filter((pattern) => {
+    return !pattern.startsWith('!') && !pattern.startsWith('vendor')
+  })
+
+  const found = new Set<string>()
+
+  for (const pattern of patterns) {
+    const dirs = await expandGlob(projectRoot, pattern)
+
+    for (const dir of dirs) {
+      if (await pathExists(path.join(dir, 'package.json'))) {
+        found.add(dir)
+      }
+    }
+  }
+
+  return [...found].sort()
+}

package/src/lib/package-validator/package-validator.ts

@@ -0,0 +1,48 @@
+import path from 'node:path'
+
+import { DEFAULT_RULES } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+
+import { checkConfig, checkFiles, checkScripts, checkTurbo } from './checks'
+import { readPackageJson } from './loader'
+import type { PackageCheck, PackageValidationResult } from './types'
+
+// Re-exported on the historical import path so consumers and tests that reach
+// for the loader through `package-validator` keep resolving after the split.
+export { discoverPackages, loadPackageConfig } from './loader'
+export type { PackageCheck, PackageValidationResult } from './types'
+
+/**
+ * Validate a single directory against its `infra-kit.config.ts` rules: the config
+ * must be present and valid, every required script must be declared, every
+ * required file must exist, and (root only) every required turbo task must be
+ * defined. When the config fails to load, only that check is reported (the rules
+ * are unknown, so the rule-based checks are skipped). `baseline` selects which
+ * under-the-hood defaults apply — package defaults or {@link ROOT_DEFAULT_RULES}.
+ *
+ * @example
+ * const result = await validatePackage('/repo/packages/serverless-config')
+ * // result.passed reflects the package's conformance; result.checks lists each check
+ */
+export const validatePackage = async (
+  packageDir: string,
+  baseline: Readonly<ResolvedPackageRules> = DEFAULT_RULES,
+): Promise<PackageValidationResult> => {
+  const pkgJson = await readPackageJson(packageDir)
+  const packageName = pkgJson.name ?? path.basename(packageDir)
+
+  const { check: configCheck, rules } = await checkConfig(packageDir, baseline)
+  const checks: PackageCheck[] = [configCheck]
+
+  if (rules) {
+    checks.push(...checkScripts(pkgJson.scripts ?? {}, rules.requiredScripts))
+    checks.push(...(await checkFiles(packageDir, rules.requiredFiles)))
+    checks.push(...(await checkTurbo(packageDir, rules.turboTasks)))
+  }
+
+  const passed = checks.every((check) => {
+    return check.status === 'pass'
+  })
+
+  return { packageDir, packageName, checks, passed }
+}

package/src/lib/package-validator/types.ts

@@ -0,0 +1,15 @@
+/** Result of a single validation check against one package. */
+export interface PackageCheck {
+  /** Stable identifier for the check, e.g. `infra-kit.config.ts`, `script:build`. */
+  name: string
+  status: 'pass' | 'fail'
+  message: string
+}
+
+/** Aggregate validation outcome for one package directory. */
+export interface PackageValidationResult {
+  packageDir: string
+  packageName: string
+  checks: PackageCheck[]
+  passed: boolean
+}