pipework 0.274.0 → 0.275.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