pipework 0.273.0 → 0.275.0

package/src/cli/commands/lint-settings.ts

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { lintIncludeGlobs } from '../../lint/include.js'
+import { resolveLintConfig } from '../../lint/resolver.js'
+import { hasEslintConfig, pipeworkVersion, type LintPopulation } from './check.js'
+
+interface EslintApi {
+  isPathIgnored(file: string): Promise<boolean>
+  calculateConfigForFile(file: string): Promise<unknown>
+}
+type EslintCtor = new (options: Record<string, unknown>) => EslintApi
+
+export interface FileCoverage {
+  readonly file: string
+  readonly covered: boolean
+  readonly reason?: 'ignored' | 'no matching configuration'
+}
+
+export interface ModuleDigest {
+  readonly module: string
+  readonly digest: string
+  readonly inputs: Record<string, unknown>
+}
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+function resolveFrom(cwd: string, request: string): string {
+  return createRequire(import.meta.url).resolve(request, { paths: [cwd, here] })
+}
+
+function packageVersion(cwd: string, name: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolveFrom(cwd, `${name}/package.json`), 'utf-8')) as { version?: string }
+    return pkg.version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+async function loadEslint(cwd: string): Promise<EslintCtor> {
+  const mod = await import(pathToFileURL(resolveFrom(cwd, 'eslint')).href) as { ESLint?: EslintCtor; default?: { ESLint?: EslintCtor } }
+  const ctor = mod.ESLint ?? mod.default?.ESLint
+  if (ctor === undefined) throw new Error('eslint is installed but does not export ESLint')
+  return ctor
+}
+
+/**
+ * eslint as `check` runs it in `dir`: the directory's own eslint.config.* when it has
+ * one, else pipework's resolved preset for that directory (what `--config preset.js`
+ * loads, with the same cwd).
+ */
+async function eslintFor(ESLint: EslintCtor, dir: string): Promise<EslintApi> {
+  if (hasEslintConfig(dir)) return new ESLint({ cwd: dir })
+  return new ESLint({ cwd: dir, overrideConfigFile: true, baseConfig: await resolveLintConfig(dir) })
+}
+
+/**
+ * Whether eslint would lint each candidate file: not ignored, and some config block
+ * applies. The answer is eslint's own, asked with the config `check` uses.
+ */
+export async function classifyCoverage(cwd: string, population: LintPopulation): Promise<FileCoverage[]> {
+  const ESLint = await loadEslint(cwd)
+  const instances = new Map<string, EslintApi>()
+  const out: FileCoverage[] = []
+  for (const { file, dir } of population.candidates) {
+    let eslint = instances.get(dir)
+    if (eslint === undefined) {
+      eslint = await eslintFor(ESLint, dir)
+      instances.set(dir, eslint)
+    }
+    const abs = resolve(cwd, file)
+    if (await eslint.isPathIgnored(abs)) {
+      out.push({ file, covered: false, reason: 'ignored' })
+    } else if (await eslint.calculateConfigForFile(abs) === undefined) {
+      out.push({ file, covered: false, reason: 'no matching configuration' })
+    } else {
+      out.push({ file, covered: true })
+    }
+  }
+  return out
+}
+
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value) as unknown
+  return proto === Object.prototype || proto === null
+}
+
+function describeNamed(value: object): Record<string, unknown> {
+  const meta = (value as { meta?: { name?: unknown; version?: unknown } }).meta
+  const rules = (value as { rules?: unknown }).rules
+  return {
+    object: value.constructor.name,
+    ...(typeof meta?.name === 'string' ? { name: meta.name } : {}),
+    ...(typeof meta?.version === 'string' ? { version: meta.version } : {}),
+    ...(typeof rules === 'object' && rules !== null ? { rules: Object.keys(rules).sort() } : {}),
+  }
+}
+
+/**
+ * A JSON value with sorted keys. A function is its name, a plugin or parser object its
+ * `meta` and rule names: never identity, so the same settings hash the same in every run.
+ */
+function canonical(value: unknown, seen: Set<object> = new Set()): unknown {
+  if (value === undefined) return null
+  if (typeof value === 'function') return { function: value.name }
+  if (typeof value === 'bigint') return String(value)
+  if (typeof value === 'symbol') return value.toString()
+  if (value instanceof RegExp) return { regexp: value.toString() }
+  if (typeof value !== 'object' || value === null) return value
+  if (seen.has(value)) return { cycle: true }
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) return value.map(v => canonical(v, seen))
+    if (!isPlainObject(value)) return describeNamed(value)
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value).sort()) {
+      const item = (value as Record<string, unknown>)[key]
+      // `plugins` and `parser` hold live objects whose identity is meaningless.
+      if ((key === 'parser' || key === 'processor') && typeof item === 'object' && item !== null) out[key] = describeNamed(item)
+      else if (key === 'plugins' && typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        out[key] = Object.fromEntries(Object.keys(item).sort().map(name =>
+          [name, describeNamed((item as Record<string, object>)[name]!)]))
+      } else out[key] = canonical(item, seen)
+    }
+    return out
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function sha256(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+function ignoreGlobs(blocks: readonly unknown[]): string[] {
+  const globs: string[] = []
+  for (const block of blocks) {
+    if (typeof block !== 'object' || block === null) continue
+    const b = block as { files?: unknown; ignores?: unknown }
+    if (b.files === undefined && Array.isArray(b.ignores)) {
+      for (const g of b.ignores) if (typeof g === 'string') globs.push(g)
+    }
+  }
+  return globs
+}
+
+/**
+ * The digest of what decides lint for one module directory: include globs, and the
+ * sorted distinct resolved configs (eslint's own `calculateConfigForFile`: rules,
+ * language options, settings) over every covered file, so extras, module overrides and
+ * per-file blocks are all in and the set does not move when a file joins a region whose
+ * config is already present. Global ignores, plugin names and the preset blocks are
+ * inputs only where pipework's preset is what runs; a directory with its own
+ * eslint.config.* is described by the configs alone. The tsconfig the type-aware rules
+ * read is not an input.
+ */
+export async function digestModule(
+  cwd: string,
+  ESLint: EslintCtor,
+  label: string,
+  dir: string,
+  includes: readonly string[] | undefined,
+  coveredFiles: readonly string[],
+): Promise<ModuleDigest> {
+  const own = hasEslintConfig(dir)
+  const blocks = own ? undefined : await resolveLintConfig(dir)
+  const eslint = await eslintFor(ESLint, dir)
+  const configs = new Map<string, unknown>()
+  for (const file of coveredFiles) {
+    // eslint's Config is a class instance with its own toJSON (plugins and parsers by name).
+    const resolved = await eslint.calculateConfigForFile(resolve(cwd, file))
+    const config = canonical(JSON.parse(JSON.stringify(resolved ?? null)))
+    configs.set(JSON.stringify(config), config)
+  }
+  const inputs = canonical({
+    pipework: pipeworkVersion(),
+    eslint: packageVersion(cwd, 'eslint'),
+    typescriptEslint: packageVersion(cwd, '@typescript-eslint/eslint-plugin'),
+    include: lintIncludeGlobs(dir, includes),
+    configs: [...configs.keys()].sort().map(k => configs.get(k)),
+    ...(blocks === undefined ? {} : {
+      ignores: ignoreGlobs(blocks),
+      plugins: [...new Set(blocks.flatMap(b => typeof b === 'object' && b !== null && 'plugins' in b
+        ? Object.keys((b as { plugins: object }).plugins) : []))].sort(),
+      blocks,
+    }),
+  }) as Record<string, unknown>
+  return { module: label, digest: sha256(inputs), inputs }
+}
+
+export async function settingsDigests(
+  cwd: string,
+  population: LintPopulation,
+  includes: { for: (mod: string) => readonly string[] | undefined },
+  coverage: readonly FileCoverage[],
+  rootPass: boolean,
+): Promise<ModuleDigest[]> {
+  const ESLint = await loadEslint(cwd)
+  const coveredIn = new Map<string, string[]>()
+  const dirOf = new Map(population.candidates.map(c => [c.file, c.dir]))
+  for (const c of coverage) {
+    const dir = dirOf.get(c.file)
+    if (c.covered && dir !== undefined) coveredIn.set(dir, [...(coveredIn.get(dir) ?? []), c.file])
+  }
+  const out: ModuleDigest[] = []
+  const hasRoot = population.modules.some(m => m.path === '.' || m.path === '')
+  for (const mod of population.modules) {
+    const dir = join(cwd, mod.path)
+    out.push(await digestModule(cwd, ESLint, mod.path === '' ? '.' : mod.path, dir, mod.includes, coveredIn.get(dir) ?? []))
+  }
+  if (rootPass && !hasRoot) {
+    out.push(await digestModule(cwd, ESLint, '.', cwd, includes.for('.'), coveredIn.get(cwd) ?? []))
+  }
+  return out.sort((a, b) => a.module < b.module ? -1 : a.module > b.module ? 1 : 0)
+}

package/src/cli/commands/lint.ts

@@ -3,7 +3,8 @@ import { dirname, relative } from 'node:path'
 import { findConfig } from '../../core/config/discover.js'
 import { error } from '../output.js'
 import { builtinConfigArgs, lintPopulation, lintTargets, loadLintIncludes, resolveEslintBin, resolveModulePaths } from './check.js'
-import { parseShard } from './shard.js'
+import { parseShard, type Shard } from './shard.js'
+import { classifyCoverage, settingsDigests } from './lint-settings.js'
 
 // eslint options that take their value as the next argument. Anything else starting
 // with `-` is a switch, so the argument after it is a file.
@@ -38,6 +39,7 @@ export function namesFiles(args: readonly string[]): boolean {
  */
 export async function lintCommand(cwd: string, args: readonly string[]): Promise<number> {
   if (args.includes('--list-files')) return listFiles(cwd, args)
+  if (args.includes('--settings-digest')) return settingsDigest(cwd, args)
   const eslintBin = resolveEslintBin(cwd)
   const configPath = findConfig(cwd)
   const root = configPath === null ? cwd : dirname(configPath)
@@ -64,32 +66,81 @@ export async function lintCommand(cwd: string, args: readonly string[]): Promise
 }
 
 /**
- * `pipework lint --list-files [--shard i/n]`: the repo-relative files `check`'s lint
- * pass covers, one per line, read from pipework.config.ts. Nothing is linted.
+ * `--list-files` and `--settings-digest` take only `--shard <i>/<n>` and `--format json`.
+ * Returns the parsed options, or null after reporting the problem.
  */
-async function listFiles(cwd: string, args: readonly string[]): Promise<number> {
-  const rest = args.filter(a => a !== '--list-files')
-  let shard
-  if (rest.length === 2 && rest[0] === '--shard') {
-    try {
-      shard = parseShard(rest[1]!)
-    } catch (err) {
-      error(err instanceof Error ? err.message : String(err))
-      return 1
+function parseReportArgs(flag: string, args: readonly string[]): { shard: Shard | undefined; json: boolean } | null {
+  let shard: Shard | undefined
+  let json = false
+  const rest = args.filter(a => a !== flag)
+  const bad = (): null => {
+    error(`${flag} takes only --shard <i>/<n> and --format json; got ${rest.join(' ')}. It does not run eslint.`)
+    return null
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!
+    if (arg === '--shard' && i + 1 < rest.length) {
+      try {
+        shard = parseShard(rest[++i]!)
+      } catch (err) {
+        error(err instanceof Error ? err.message : String(err))
+        return null
+      }
+    } else if ((arg === '--format' && rest[i + 1] === 'json') || arg === '--format=json') {
+      if (arg === '--format') i++
+      json = true
+    } else {
+      return bad()
     }
-  } else if (rest.length > 0) {
-    error(`--list-files takes only --shard <i>/<n>; got ${rest.join(' ')}. It lists files and does not run eslint.`)
-    return 1
   }
+  return { shard, json }
+}
 
+async function reportPopulation(cwd: string, flag: string, args: readonly string[]) {
+  const opts = parseReportArgs(flag, args)
+  if (opts === null) return null
   const configPath = findConfig(cwd)
   const root = configPath === null ? cwd : dirname(configPath)
   const scope = await resolveModulePaths(root)
   if (scope.configError !== undefined) {
-    error(`Cannot list lint files: pipework.config.ts failed to load: ${scope.configError.message}`)
-    return 1
+    error(`Cannot ${flag === '--list-files' ? 'list lint files' : 'digest lint settings'}: pipework.config.ts failed to load: ${scope.configError.message}`)
+    return null
   }
-  const population = lintPopulation(root, scope.paths, await loadLintIncludes(root), shard)
-  if (population.files.length > 0) process.stdout.write(population.files.join('\n') + '\n')
+  const includes = await loadLintIncludes(root)
+  const population = lintPopulation(root, scope.paths, includes, opts.shard)
+  return { ...opts, root, includes, population }
+}
+
+/**
+ * `pipework lint --list-files [--shard i/n] [--format json]`: the repo-relative files
+ * `check`'s lint pass covers and eslint will lint, one per line. Files the include globs
+ * reach but the lint config ignores are left out; `--format json` lists every candidate
+ * with `covered` and, when false, why. Nothing is linted.
+ */
+async function listFiles(cwd: string, args: readonly string[]): Promise<number> {
+  const ctx = await reportPopulation(cwd, '--list-files', args)
+  if (ctx === null) return 1
+  const coverage = await classifyCoverage(ctx.root, ctx.population)
+  if (ctx.json) {
+    process.stdout.write(JSON.stringify(coverage, null, 2) + '\n')
+    return 0
+  }
+  const covered = coverage.filter(c => c.covered).map(c => c.file)
+  if (covered.length > 0) process.stdout.write(covered.join('\n') + '\n')
+  return 0
+}
+
+/**
+ * `pipework lint --settings-digest [--shard i/n] [--format json]`: one sha256 per
+ * module (the root pass is `.`) of what decides lint there. Nothing is linted.
+ */
+async function settingsDigest(cwd: string, args: readonly string[]): Promise<number> {
+  const ctx = await reportPopulation(cwd, '--settings-digest', args)
+  if (ctx === null) return 1
+  const coverage = await classifyCoverage(ctx.root, ctx.population)
+  const rootPass = ctx.shard === undefined || ctx.shard.index === 1
+  const digests = await settingsDigests(ctx.root, ctx.population, ctx.includes, coverage, rootPass)
+  if (ctx.json) process.stdout.write(JSON.stringify(digests, null, 2) + '\n')
+  else if (digests.length > 0) process.stdout.write(digests.map(d => `${d.module} ${d.digest}`).join('\n') + '\n')
   return 0
 }

package/src/cli/index.ts

@@ -24,7 +24,8 @@ ${bold('Commands:')}
   cardinality [files]  @downstream cardinality rules alone (same options)
   startup           Startup validation alone: pipework.config.ts loaded, no database
   lint [eslint args]  Lint the current module (the workspace at its root) with check's config; every argument goes to eslint
-                    lint --list-files [--shard i/n]: print the files check's lint covers, lint nothing
+                    lint --list-files [--shard i/n] [--format json]: print the files eslint will lint (json: every candidate, covered or not), lint nothing
+                    lint --settings-digest [--shard i/n] [--format json]: print a digest per module of the resolved lint settings, lint nothing
   codemod           Fill missing @downstream cardinality across the corpus
   db                Database lifecycle: setup, teardown, reset
   alerts unit-fault Record an abnormal systemd stop (ExecStopPost=pipework alerts unit-fault --unit %n)
@@ -93,6 +94,7 @@ ${bold('Examples:')}
   pipework lint                       # the module you are in, exactly as check lints it
   pipework lint --format json --output-file r.json src/a.ts   # only src/a.ts
   pipework lint --list-files --shard 1/4   # the files check's lint pass covers for part 1 of 4, from pipework.config.ts
+  pipework lint --settings-digest --format json   # per-module digest of what decides lint, for a lint-result cache key
   pipework codemod
   pipework codemod --dry-run
   pipework alerts unit-fault --unit subseam-core.service   # reads $SERVICE_RESULT, $EXIT_CODE, $EXIT_STATUS

package/src/request/http/server.ts

@@ -447,6 +447,16 @@ export function createServer(instance: Manifold, config: ServerConfig = {}): Pip
       if (handler.meta.route?.cancelOnDisconnect !== false) {
         reply.raw.once('close', onClose)
         reply.raw.once('finish', () => { reply.raw.removeListener('close', onClose) })
+        // An injected request has no socket: light-my-request keeps the caller's signal on the raw request, and its abort is the disconnect.
+        const injected = (req.raw as { _lightMyRequest?: { signal?: AbortSignal } })._lightMyRequest?.signal
+        if (injected !== undefined) {
+          const onInjectAbort = (): void => { onClose() }
+          if (injected.aborted) onInjectAbort()
+          else {
+            injected.addEventListener('abort', onInjectAbort, { once: true })
+            reply.raw.once('finish', () => { injected.removeEventListener('abort', onInjectAbort) })
+          }
+        }
       }
       // Ends the upload stream and closes the connection if the body was left unread.
       const finishUpload = (failed: boolean): void => {
@@ -726,6 +736,7 @@ export function createServer(instance: Manifold, config: ServerConfig = {}): Pip
       payload: opts.payload as string,
       query: opts.query as Record<string, string>,
       ...(opts.remoteAddress !== undefined ? { remoteAddress: opts.remoteAddress } : {}),
+      ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
     })
     const r = response as unknown as { statusCode: number; headers: Record<string, string | number | string[] | undefined>; body: string; rawPayload: Buffer; json(): unknown }
     return { statusCode: r.statusCode, headers: r.headers, body: r.body, rawPayload: r.rawPayload, json: () => r.json() }

package/src/request/http/types.ts

@@ -140,6 +140,8 @@ export interface InjectOptions {
   query?: Record<string, string | readonly string[]>
   /** The socket address the request appears to come from (default `127.0.0.1`). Lets a test exercise `request.ip` and `trustProxy`. */
   remoteAddress?: string
+  /** Aborting it while the handler runs is a client disconnect: the request's signal aborts with `RequestAbortedError` and its transaction rolls back (a `cancelOnDisconnect: false` route runs on). */
+  signal?: AbortSignal
 }
 
 /** Response from server.inject() — statusCode, headers, body, rawPayload, json() helper. */