pipework 0.251.0 → 0.252.1

package/src/workspace/changed-files.ts

@@ -0,0 +1,163 @@
+import { execSync } from 'node:child_process'
+import { relative, resolve, sep } from 'node:path'
+import { scrubGitEnv } from './scrub-git-env.js'
+
+export type DiffMode = 'uncommitted' | 'staged' | 'branch'
+
+// Base branches a `branch`-mode diff is taken against when the blueprint does
+// not configure `fastPath.baseBranches`, in priority order — the working
+// branch first.
+const DEFAULT_BASE_BRANCHES: readonly string[] = ['integration', 'main']
+
+// Base refs are interpolated into git commands, so only plain ref characters
+// are admitted — anything else is treated as not-a-base rather than executed.
+const SAFE_REF = /^[A-Za-z0-9._/-]+$/
+
+type GitEnv = ReturnType<typeof scrubGitEnv>
+
+/**
+ * Files changed under `mode`, as paths relative to `anchor` (the directory
+ * holding pipework.config.ts — the same base module paths are relative to).
+ *
+ * Three path coordinate systems meet here, and they only coincide when the
+ * anchor IS the git toplevel: `git diff --name-only` prints toplevel-relative
+ * paths regardless of cwd, `git ls-files --others` prints cwd-relative paths,
+ * and module paths are anchor-relative. Every git command therefore runs from
+ * the toplevel and every returned path is rebased onto the anchor before it is
+ * handed to `filesToModules` — otherwise a config dir below the toplevel
+ * (monorepo layout, e.g. <repo>/packages/backend) makes every diff path miss
+ * the module prefix match and `rootChanged` widens every scoped run to all
+ * modules. A change outside the anchor subtree comes back as a `../` path,
+ * which deliberately matches no module and keeps the fail-wide behavior.
+ *
+ * `branch` mode (the `--fast` path) returns `null` — never an empty array —
+ * when the set cannot be computed (no base branch, unrelated history, no git):
+ * the caller must fail open on `null`, widening to everything, never silently
+ * scoping to nothing. Issue #325.
+ *
+ * `uncommitted` / `staged` modes return `[]` on a non-git or empty tree — a
+ * clean tree genuinely has nothing to do, and the caller exits 0 (#266). An
+ * empty array always means "computed cleanly, nothing changed".
+ */
+export function changedFiles(
+  anchor: string,
+  mode: DiffMode,
+  baseBranches?: readonly string[],
+): string[] | null {
+  const env = scrubGitEnv()
+
+  let toplevel: string
+  try {
+    toplevel = git(anchor, env, 'git rev-parse --show-toplevel').trim()
+    if (toplevel === '') throw new Error('no toplevel')
+  } catch {
+    // Not a git repository: branch mode must fail open (null), the tree modes
+    // report a genuinely empty diff (#266).
+    return mode === 'branch' ? null : []
+  }
+
+  if (mode === 'branch') {
+    try {
+      const base = baseBranch(toplevel, env, baseBranches)
+      if (base === null) return null
+      const mergeBase = git(toplevel, env, `git merge-base ${base} HEAD`).trim()
+      if (mergeBase === '') return null
+      const committed = parseLines(git(toplevel, env, `git diff --name-only ${mergeBase}`))
+      const untracked = parseLines(git(toplevel, env, 'git ls-files --others --exclude-standard'))
+      return rebase([...new Set([...committed, ...untracked])], toplevel, anchor)
+    } catch {
+      return null
+    }
+  }
+
+  try {
+    if (mode === 'staged') {
+      return rebase(parseLines(git(toplevel, env, 'git diff --name-only --cached')), toplevel, anchor)
+    }
+    const diffRaw = git(toplevel, env, 'git diff --name-only HEAD')
+    const untrackedRaw = git(toplevel, env, 'git ls-files --others --exclude-standard')
+    return rebase([...new Set([...parseLines(diffRaw), ...parseLines(untrackedRaw)])], toplevel, anchor)
+  } catch {
+    return []
+  }
+}
+
+/** Toplevel-relative git paths → anchor-relative POSIX paths. */
+function rebase(files: readonly string[], toplevel: string, anchor: string): string[] {
+  return files.map(f => relative(resolve(anchor), resolve(toplevel, f)).split(sep).join('/'))
+}
+
+function git(cwd: string, env: GitEnv, cmd: string): string {
+  return execSync(cmd, { cwd, env, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] })
+}
+
+/**
+ * The base branch a `branch`-mode diff would be taken against, for scope
+ * reporting (the population line). `null` when none exists or git is absent.
+ */
+export function resolveBaseBranch(anchor: string, baseBranches?: readonly string[]): string | null {
+  try {
+    return baseBranch(anchor, scrubGitEnv(), baseBranches)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * The first configured base ref that resolves to a commit, or `null` when none
+ * does. A configured entry may be any committish — a local branch, a
+ * remote-tracking ref like 'origin/main', a tag — so a stale or absent local
+ * ref can be routed around instead of failing every fast run wide.
+ */
+function baseBranch(cwd: string, env: GitEnv, baseBranches?: readonly string[]): string | null {
+  for (const ref of baseBranches ?? DEFAULT_BASE_BRANCHES) {
+    if (!SAFE_REF.test(ref)) continue
+    try {
+      git(cwd, env, `git rev-parse --verify --quiet ${ref}^{commit}`)
+      return ref
+    } catch {
+      // Not this one — try the next.
+    }
+  }
+  return null
+}
+
+export function filesToModules(
+  files: readonly string[],
+  modulePaths: readonly string[],
+): { modules: Set<string>; rootChanged: boolean } {
+  const sorted = [...modulePaths].sort((a, b) => b.length - a.length)
+  const modules = new Set<string>()
+  let rootChanged = false
+
+  for (const file of files) {
+    // A `../` path is a change outside the config dir's subtree. It can affect
+    // every module (root lockfile, shared tsconfig) but can never BE a module
+    // file — not even of the synthesized '.' module — so it always fails wide.
+    if (file.startsWith('../')) {
+      rootChanged = true
+      continue
+    }
+    let matched = false
+    for (const modPath of sorted) {
+      // '.' is the synthesized implicit module for a single-package repo — it
+      // is the config dir itself, so it contains every anchor-relative file.
+      // Rebased paths never carry a leading './', so the prefix check below
+      // can never match '.' on its own.
+      if (modPath === '.' || file === modPath || file.startsWith(modPath + '/')) {
+        modules.add(modPath)
+        matched = true
+        break
+      }
+    }
+    if (!matched) {
+      rootChanged = true
+    }
+  }
+
+  return { modules, rootChanged }
+}
+
+function parseLines(raw: string): string[] {
+  return raw.split('\n').filter(line => line.length > 0)
+}

package/src/workspace/check-deps.ts

@@ -0,0 +1,213 @@
+import { readFileSync, existsSync, readdirSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+
+const WRAPPED_PACKAGES = [
+  'postgres',
+  'pg',
+  '@neondatabase/serverless',
+  'drizzle-orm',
+  'fastify',
+  'zod',
+  'pino',
+  'jose',
+] as const
+
+const WRAPPED_SCOPES = [
+  '@fastify/',
+  'drizzle-orm/',
+  'pino/',
+  'zod/',
+] as const
+
+export interface DepViolation {
+  readonly package: string
+  readonly dependency: string
+  readonly field: 'dependencies' | 'devDependencies'
+  readonly message: string
+}
+
+export interface DepCheckResult {
+  readonly violations: readonly DepViolation[]
+  readonly packagesChecked: number
+}
+
+interface WorkspacePackage {
+  readonly name: string
+  readonly root: string
+  readonly exempt: boolean
+  readonly exemptDeps: readonly string[]
+}
+
+export function checkDependencies(cwd: string): DepCheckResult {
+  const packages = discoverPackages(cwd)
+  const violations: DepViolation[] = []
+
+  for (const pkg of packages) {
+    if (pkg.exempt) continue
+    checkPackageDeps(pkg, violations)
+  }
+
+  return {
+    violations,
+    packagesChecked: packages.filter(p => !p.exempt).length,
+  }
+}
+
+function isBanned(dep: string, exemptDeps: readonly string[]): boolean {
+  if (exemptDeps.includes(dep)) return false
+
+  if ((WRAPPED_PACKAGES as readonly string[]).includes(dep)) return true
+
+  for (const scope of WRAPPED_SCOPES) {
+    if (dep.startsWith(scope)) {
+      if (!exemptDeps.some(e => dep.startsWith(e) || dep === e)) return true
+    }
+  }
+
+  return false
+}
+
+function checkPackageDeps(pkg: WorkspacePackage, violations: DepViolation[]): void {
+  const pkgPath = join(pkg.root, 'package.json')
+  if (!existsSync(pkgPath)) return
+
+  let pkgJson: Record<string, unknown>
+  try {
+    pkgJson = JSON.parse(readFileSync(pkgPath, 'utf-8')) as Record<string, unknown>
+  } catch {
+    return
+  }
+
+  const fields = ['dependencies', 'devDependencies'] as const
+
+  for (const field of fields) {
+    const deps = pkgJson[field]
+    if (typeof deps !== 'object' || deps === null) continue
+
+    for (const dep of Object.keys(deps as Record<string, unknown>)) {
+      if (dep === 'pipework') continue
+      if (!isBanned(dep, pkg.exemptDeps)) continue
+
+      const wrapped = matchWrappedPackage(dep)
+      violations.push({
+        package: pkg.name,
+        dependency: dep,
+        field,
+        message: `Direct dependency on "${dep}" — this is wrapped by pipework.${wrapped !== null ? `\n    Import from pipework instead of "${dep}".` : ''}`,
+      })
+    }
+  }
+}
+
+function matchWrappedPackage(dep: string): string | null {
+  if (dep === 'postgres' || dep === 'pg' || dep === '@neondatabase/serverless') return 'pipe()'
+  if (dep === 'drizzle-orm' || dep.startsWith('drizzle-orm/')) return 'pipe.define(), schema.*'
+  if (dep === 'fastify' || dep.startsWith('@fastify/')) return 'surface.http(), fitting()'
+  if (dep === 'zod' || dep.startsWith('zod/')) return 'pipe.define() shapes'
+  if (dep === 'pino' || dep.startsWith('pino/')) return 'pipework logging'
+  if (dep === 'jose') return 'pipework auth'
+  return null
+}
+
+function discoverPackages(cwd: string): WorkspacePackage[] {
+  const workspaceFile = join(cwd, 'pnpm-workspace.yaml')
+  if (existsSync(workspaceFile)) {
+    return discoverFromPnpmWorkspace(cwd, workspaceFile)
+  }
+
+  const rootPkg = readPackageJson(cwd)
+  if (rootPkg !== null) {
+    const workspaces = rootPkg['workspaces']
+    if (Array.isArray(workspaces)) {
+      return expandGlobs(cwd, workspaces as string[])
+    }
+    if (typeof workspaces === 'object' && workspaces !== null) {
+      const packages = (workspaces as Record<string, unknown>)['packages']
+      if (Array.isArray(packages)) {
+        return expandGlobs(cwd, packages as string[])
+      }
+    }
+  }
+
+  return []
+}
+
+function discoverFromPnpmWorkspace(cwd: string, file: string): WorkspacePackage[] {
+  const content = readFileSync(file, 'utf-8')
+  const patterns: string[] = []
+  for (const line of content.split('\n')) {
+    const match = line.match(/^\s*-\s+['"]?([^'"]+)['"]?\s*$/)
+    if (match?.[1] !== undefined && match[1] !== '.') {
+      patterns.push(match[1])
+    }
+  }
+  return expandGlobs(cwd, patterns)
+}
+
+function expandGlobs(cwd: string, patterns: string[]): WorkspacePackage[] {
+  const packages: WorkspacePackage[] = []
+
+  for (const pattern of patterns) {
+    if (pattern === '.') continue
+
+    if (pattern.includes('*')) {
+      const base = pattern.replace(/\/?\*.*$/, '')
+      const baseDir = join(cwd, base)
+      if (!existsSync(baseDir)) continue
+
+      for (const entry of readdirSync(baseDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name === 'node_modules') continue
+        const pkgDir = join(baseDir, entry.name)
+        const pkg = tryLoadPackage(pkgDir)
+        if (pkg !== null) packages.push(pkg)
+      }
+    } else {
+      const pkgDir = join(cwd, pattern)
+      const pkg = tryLoadPackage(pkgDir)
+      if (pkg !== null) packages.push(pkg)
+    }
+  }
+
+  return packages
+}
+
+function tryLoadPackage(dir: string): WorkspacePackage | null {
+  const pkgJson = readPackageJson(dir)
+  if (pkgJson === null) return null
+
+  const name = typeof pkgJson['name'] === 'string' ? pkgJson['name'] : dirname(dir)
+  const boundaries = getBoundaryConfig(pkgJson)
+
+  return {
+    name,
+    root: dir,
+    exempt: boundaries?.exempt === true || boundaries?.dependencies?.exempt === true,
+    exemptDeps: boundaries?.dependencies?.allow ?? [],
+  }
+}
+
+function readPackageJson(dir: string): Record<string, unknown> | null {
+  const file = join(dir, 'package.json')
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8')) as Record<string, unknown>
+  } catch {
+    return null
+  }
+}
+
+interface BoundaryConfig {
+  readonly exempt?: boolean
+  readonly dependencies?: {
+    readonly exempt?: boolean
+    readonly allow?: readonly string[]
+  }
+}
+
+function getBoundaryConfig(pkgJson: Record<string, unknown>): BoundaryConfig | null {
+  const pw = pkgJson['pipework']
+  if (typeof pw !== 'object' || pw === null) return null
+  const boundaries = (pw as Record<string, unknown>)['boundaries']
+  if (typeof boundaries !== 'object' || boundaries === null) return null
+  return boundaries as BoundaryConfig
+}

package/src/workspace/checksum.ts

@@ -0,0 +1,20 @@
+import { createHash } from 'node:crypto'
+
+export function computeChecksum(input: string): string {
+  const hash = createHash('sha256').update(input).digest('hex').slice(0, 16)
+  return `sha256:${hash}`
+}
+
+export function checksumFromPackageJson(content: string): string | undefined {
+  try {
+    const parsed = JSON.parse(content) as Record<string, unknown>
+    if (typeof parsed['_checksum'] === 'string') return parsed['_checksum']
+    return undefined
+  } catch {
+    return undefined
+  }
+}
+
+export function isStale(expected: string, actual: string | undefined): boolean {
+  return actual !== expected
+}

package/src/workspace/dependency-graph.ts

@@ -0,0 +1,67 @@
+import type { ResolvedModule } from './discover.js'
+import { modulePackageName } from './module-package-name.js'
+
+export interface ModuleGraph {
+  affected(changed: ReadonlySet<string>): ReadonlySet<string>
+  dependentsOf(modulePath: string): ReadonlySet<string>
+  allModules(): ReadonlySet<string>
+}
+
+export function buildModuleGraph(
+  modules: readonly ResolvedModule[],
+  projectName: string,
+): ModuleGraph {
+  const packageToPath = new Map<string, string>()
+  for (const mod of modules) {
+    packageToPath.set(modulePackageName(mod, projectName), mod.relativePath)
+  }
+
+  const allPaths = new Set(modules.map(m => m.relativePath))
+
+  const dependents = new Map<string, Set<string>>()
+  for (const path of allPaths) {
+    dependents.set(path, new Set())
+  }
+
+  for (const mod of modules) {
+    const deps = { ...mod.config.dependencies, ...mod.config.devDependencies }
+    for (const [pkgName, version] of Object.entries(deps)) {
+      if (version === null || !version.startsWith('workspace:')) continue
+      const depPath = packageToPath.get(pkgName)
+      if (depPath === undefined) continue
+      dependents.get(depPath)!.add(mod.relativePath)
+    }
+  }
+
+  return {
+    affected(changed: ReadonlySet<string>): ReadonlySet<string> {
+      const result = new Set<string>()
+      const queue = [...changed]
+
+      while (queue.length > 0) {
+        const current = queue.pop()!
+        if (result.has(current)) continue
+        if (!allPaths.has(current)) continue
+        result.add(current)
+        const deps = dependents.get(current)
+        if (deps !== undefined) {
+          for (const dep of deps) {
+            if (!result.has(dep)) {
+              queue.push(dep)
+            }
+          }
+        }
+      }
+
+      return result
+    },
+
+    dependentsOf(modulePath: string): ReadonlySet<string> {
+      return dependents.get(modulePath) ?? new Set()
+    },
+
+    allModules(): ReadonlySet<string> {
+      return allPaths
+    },
+  }
+}

package/src/workspace/detect-pipework-copies.ts

@@ -0,0 +1,93 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface PipeworkCopy {
+  readonly version: string
+  readonly path: string
+}
+
+export interface PipeworkInstall {
+  /** Copies the install resolves: the hoisted copy plus every store copy the virtual-store lockfile names. */
+  readonly copies: PipeworkCopy[]
+  /** Store copies the lockfile does not name: stale directories pnpm left behind. */
+  readonly orphans: PipeworkCopy[]
+}
+
+// Pipework versions named by the keys of `node_modules/.pnpm/lock.yaml`, or undefined when the
+// file is absent, unreadable, or names none (a key format this scan does not know). Keys seen across pnpm versions: `pipework@0.211.0(peers):`,
+// `/pipework@0.211.0(peers):`, `/pipework/0.11.0_peerhash:`, any of them quoted. Scanned by
+// line so no YAML parser is needed; `pipework-flow-parser@…` never matches (`@` or `/` must follow).
+function readLockedVersions(storeDir: string): Set<string> | undefined {
+  let raw: string
+  try {
+    raw = readFileSync(join(storeDir, 'lock.yaml'), 'utf8')
+  } catch {
+    return undefined
+  }
+  const versions = new Set<string>()
+  for (const line of raw.split('\n')) {
+    const m = /^\s*['"]?\/?pipework[@/]([^()_:'"\s]+)/.exec(line)
+    if (m !== null) versions.add(m[1]!)
+  }
+  return versions.size === 0 ? undefined : versions
+}
+
+// Detects every physical copy of pipework resolvable from a workspace's install tree.
+// Two copies of the SAME version are harmless (the runtime broker shares one ALS across
+// them); copies of DIFFERENT versions are the multi-instance hazard — a shared library
+// resolving a different pipework than its workspace forks the ALS and error classes
+// (no active context; 403->500), and on 0.12.0+ the broker throws at first use. Catching
+// the skew here, at check/CI time, surfaces it before first request.
+//
+// A virtual-store directory the install does not resolve (its version is not in the store's
+// lock.yaml) is an orphan: pnpm leaves the previous version's directory behind after a move.
+// It is reported apart and never counted as a loaded copy. With no readable lock.yaml, or one
+// naming no pipework, every store directory counts.
+export function detectPipeworkInstall(cwd: string): PipeworkInstall {
+  const copies = new Map<string, PipeworkCopy>()
+  const orphans = new Map<string, PipeworkCopy>()
+
+  const read = (pkgJsonPath: string): PipeworkCopy | undefined => {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) as { name?: string; version?: string }
+      if (pkg.name === 'pipework' && typeof pkg.version === 'string') {
+        return { version: pkg.version, path: pkgJsonPath }
+      }
+    } catch {
+      // not a readable/parseable package.json — skip
+    }
+    return undefined
+  }
+
+  // Hoisted copy: always resolved.
+  const hoisted = read(join(cwd, 'node_modules', 'pipework', 'package.json'))
+  if (hoisted !== undefined) copies.set(hoisted.path, hoisted)
+
+  // pnpm virtual store: node_modules/.pnpm/pipework@<version>[_<peerhash>]/node_modules/pipework.
+  // `pipework@` (not `pipework-`) excludes pipework-flow-parser and other prefixed packages.
+  const pnpmDir = join(cwd, 'node_modules', '.pnpm')
+  try {
+    const locked = readLockedVersions(pnpmDir)
+    for (const entry of readdirSync(pnpmDir)) {
+      if (!entry.startsWith('pipework@')) continue
+      const c = read(join(pnpmDir, entry, 'node_modules', 'pipework', 'package.json'))
+      if (c === undefined) continue
+      if (locked === undefined || locked.has(c.version)) copies.set(c.path, c)
+      else orphans.set(c.path, c)
+    }
+  } catch {
+    // no .pnpm store (npm/yarn, or not installed) — the hoisted check above still applies
+  }
+
+  return { copies: [...copies.values()], orphans: [...orphans.values()] }
+}
+
+/** The copies the install resolves; see detectPipeworkInstall for the orphans. */
+export function detectPipeworkCopies(cwd: string): PipeworkCopy[] {
+  return detectPipeworkInstall(cwd).copies
+}
+
+/** Distinct pipework versions across the resolved copies, sorted. More than one means skew. */
+export function distinctPipeworkVersions(copies: readonly PipeworkCopy[]): string[] {
+  return [...new Set(copies.map((c) => c.version))].sort()
+}