pipework 0.269.0 → 0.271.0

package/src/cli/commands/lint.ts

@@ -2,7 +2,8 @@ import { spawnSync } from 'node:child_process'
 import { dirname, relative } from 'node:path'
 import { findConfig } from '../../core/config/discover.js'
 import { error } from '../output.js'
-import { builtinConfigArgs, lintTargets, loadLintIncludes, resolveEslintBin } from './check.js'
+import { builtinConfigArgs, lintPopulation, lintTargets, loadLintIncludes, resolveEslintBin, resolveModulePaths } from './check.js'
+import { parseShard } from './shard.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.
@@ -36,6 +37,7 @@ export function namesFiles(args: readonly string[]): boolean {
  * those. Every argument is forwarded verbatim. Returns eslint's exit code.
  */
 export async function lintCommand(cwd: string, args: readonly string[]): Promise<number> {
+  if (args.includes('--list-files')) return listFiles(cwd, args)
   const eslintBin = resolveEslintBin(cwd)
   const configPath = findConfig(cwd)
   const root = configPath === null ? cwd : dirname(configPath)
@@ -60,3 +62,34 @@ export async function lintCommand(cwd: string, args: readonly string[]): Promise
   }
   return result.status ?? 1
 }
+
+/**
+ * `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.
+ */
+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
+    }
+  } 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
+  }
+
+  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
+  }
+  const population = lintPopulation(root, scope.paths, await loadLintIncludes(root), shard)
+  if (population.files.length > 0) process.stdout.write(population.files.join('\n') + '\n')
+  return 0
+}

package/src/cli/index.ts

@@ -18,8 +18,13 @@ ${bold('Commands:')}
   openapi           Write an http surface's OpenAPI document (no database needed; --surface <name>, --out <file>)
   run <script>      Execute a script as a traced, audited flow (with --tenant: one transaction, rolled back if it throws)
   test              Run tests with automatic database setup
-  check             Type-check, lint, and boundary enforcement
+  check             Type-check, lint, and boundary enforcement (--format json, --only/--skip steps)
+  doctrine [files]  Doctrine rules alone; JSON per violation and per scanned file with --format json
+  flow [files]      Flow annotation rules alone (same options)
+  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
   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)
@@ -49,6 +54,15 @@ ${bold('Scoping (check, test):')}
   --reap                  Drop orphan test databases and exit (test only)
   --shard <i>/<n>         Run part i of n disjoint parts of the selected run (test, check); the n parts together equal the unsharded run
 
+${bold('Steps (check, doctrine, flow, cardinality, startup):')}
+  --format json           Structured result: {step, status, pipeworkVersion, reads, files, violations}; check emits an array, one record per step
+  --output-file <path>    Write the JSON there instead of stdout (human lines stay on stderr)
+  --only <a,b>            check: run only these steps
+  --skip <a,b>            check: run all but these steps (not with --only)
+                          Steps: checksums, vitest-config, eslint-config, config-load, doctrine, flow, cardinality,
+                          coverage, lint, typecheck, startup, boundaries, dependencies, install
+                          doctrine, flow and cardinality take file paths: only those files are judged
+
 ${bold('Examples:')}
   pipework init
   pipework upgrade
@@ -74,14 +88,27 @@ ${bold('Examples:')}
   pipework test --reap                # drop orphan test databases
   pipework check --staged
   pipework check --all
+  pipework check --format json --skip lint,typecheck --output-file r.json
+  pipework doctrine --format json --output-file d.json src/a.ts src/b.ts
   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 codemod
   pipework codemod --dry-run
   pipework alerts unit-fault --unit subseam-core.service   # reads $SERVICE_RESULT, $EXIT_CODE, $EXIT_STATUS
   pipework alerts stale --max-age jobs.claim=5m            # exit 1 with a line per stale loop; 0 and silent when none
 `
 
+function parseFormat(format: string | undefined, outputFile: string | undefined): 'human' | 'json' {
+  if (format !== undefined && format !== 'human' && format !== 'json') {
+    throw new Error(`--format takes "json" or "human"; got "${format}".`)
+  }
+  if (outputFile !== undefined && format !== 'json') {
+    throw new Error('--output-file needs --format json.')
+  }
+  return format === 'json' ? 'json' : 'human'
+}
+
 export async function run(argv: string[]): Promise<void> {
   // `lint` hands everything after it to eslint, flags included, so it is dispatched
   // before parseArgs, which would refuse eslint's options.
@@ -129,6 +156,10 @@ export async function run(argv: string[]): Promise<void> {
       test: { type: 'boolean' },
       'admin-url': { type: 'string' },
       'dry-run': { type: 'boolean' },
+      format: { type: 'string' },
+      'output-file': { type: 'string' },
+      only: { type: 'string' },
+      skip: { type: 'string' },
     },
   })
 
@@ -256,7 +287,30 @@ export async function run(argv: string[]): Promise<void> {
         const { parseShard: parseShardCheck } = await import('./commands/shard.js')
         const shardCheck = values.shard === undefined ? undefined : parseShardCheck(values.shard)
         const { check } = await import('./commands/check.js')
-        await check(cwd, parsedCheck.scope, shardCheck)
+        const { parseStepSelection } = await import('./commands/check-steps.js')
+        await check(cwd, parsedCheck.scope, shardCheck, {
+          format: parseFormat(values.format, values['output-file']),
+          outputFile: values['output-file'],
+          select: parseStepSelection(values.only, values.skip),
+        })
+        break
+      }
+      case 'doctrine':
+      case 'flow':
+      case 'cardinality':
+      case 'startup': {
+        if (values.only !== undefined || values.skip !== undefined) {
+          throw new Error(`--only and --skip select steps of check; ${command} is one step.`)
+        }
+        const { parseScope: parseScopeStep } = await import('./commands/scope.js')
+        const parsedStep = parseScopeStep({ all: values.all, module: values.module, staged: values.staged, fast: values.fast, full: values.full })
+        const { stepCommand } = await import('./commands/check.js')
+        process.exitCode = await stepCommand(cwd, command, {
+          format: parseFormat(values.format, values['output-file']),
+          outputFile: values['output-file'],
+          scope: parsedStep.scope,
+          files: positionals.slice(1),
+        })
         break
       }
       case 'codemod': {

package/src/lint/config.ts

@@ -1,6 +1,7 @@
 import tseslint from '@typescript-eslint/eslint-plugin'
 import tsparser from '@typescript-eslint/parser'
 import { noReexports } from './rules/no-reexports.js'
+import { doctrineRules } from './rules/doctrine.js'
 
 export const rules = {
   '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }],
@@ -11,6 +12,10 @@ export const rules = {
   '@typescript-eslint/no-unnecessary-condition': 'error',
   '@typescript-eslint/strict-boolean-expressions': 'error',
   'pipework/no-reexports': 'error',
+  'define/prefer-pipe-define': 'error',
+  'define/no-raw-pgTable': 'error',
+  'define/brand-primary-key': 'error',
+  'define/use-traits': 'error',
 } as const
 
 export interface LintOptions {
@@ -33,6 +38,7 @@ export function createLintConfig(config?: LintOptions): unknown[] {
   const appliedPlugins: Record<string, unknown> = {
     '@typescript-eslint': tseslint,
     'pipework': { rules: { 'no-reexports': noReexports } },
+    'define': { rules: doctrineRules },
     ...config?.extraPlugins,
   }
 

package/src/lint/doctrine.ts

@@ -11,27 +11,36 @@ export interface DoctrineViolation {
 export interface DoctrineResult {
   readonly violations: readonly DoctrineViolation[]
   readonly scanned: number
+  /** Every file read, in input order; a clean one has no violation. */
+  readonly scannedFiles: readonly string[]
 }
 
 export function validateDoctrine(cwd: string, sourceFiles: readonly string[]): DoctrineResult {
   const violations: DoctrineViolation[] = []
   let scanned = 0
+  const scannedFiles: string[] = []
 
   for (const file of sourceFiles) {
     const abs = join(cwd, file)
     if (!existsSync(abs)) continue
 
-    const content = readFileSync(abs, 'utf-8')
-    const lines = content.split('\n')
     scanned++
-
-    checkSchemaTableUsage(file, lines, violations)
-    checkRawPgTableImport(file, lines, violations)
-    checkUnbrandedPrimaryKeys(file, lines, violations)
-    checkHandWrittenTraitFields(file, lines, violations)
+    scannedFiles.push(file)
+    violations.push(...doctrineViolations(file, readFileSync(abs, 'utf-8')))
   }
 
-  return { violations, scanned }
+  return { violations, scanned, scannedFiles }
+}
+
+/** The four doctrine scans over one file's text; shared by `check` and the eslint rules. */
+export function doctrineViolations(file: string, content: string): DoctrineViolation[] {
+  const lines = content.split('\n')
+  const violations: DoctrineViolation[] = []
+  checkSchemaTableUsage(file, lines, violations)
+  checkRawPgTableImport(file, lines, violations)
+  checkUnbrandedPrimaryKeys(file, lines, violations)
+  checkHandWrittenTraitFields(file, lines, violations)
+  return violations
 }
 
 const SCHEMA_TABLE_PATTERN = /\bschema\.table\s*\(/

package/src/lint/rules/doctrine.ts

@@ -0,0 +1,31 @@
+import { basename } from 'node:path'
+import type { Rule } from 'eslint'
+import { doctrineViolations, isSourceFileName } from '../doctrine.js'
+
+const RULES = ['prefer-pipe-define', 'no-raw-pgTable', 'brand-primary-key', 'use-traits'] as const
+
+function doctrineRule(name: string): Rule.RuleModule {
+  const id = `define/${name}`
+  return {
+    meta: {
+      type: 'problem',
+      docs: { description: `Doctrine rule ${id}; same scan as the doctrine step of pipework check.` },
+      schema: [],
+    },
+    create(context) {
+      return {
+        'Program:exit'() {
+          if (!isSourceFileName(basename(context.filename))) return
+          for (const v of doctrineViolations(context.filename, context.sourceCode.text)) {
+            if (v.rule !== id) continue
+            context.report({ loc: { line: v.line, column: 0 }, message: v.message })
+          }
+        },
+      }
+    },
+  }
+}
+
+export const doctrineRules: Record<string, Rule.RuleModule> = Object.fromEntries(
+  RULES.map(name => [name, doctrineRule(name)]),
+)

package/src/trace/cardinality/check.ts

@@ -8,9 +8,15 @@ import { join } from 'node:path'
 import { collectFlowStepSites } from '../check/flow-step-site.js'
 import { analyzeCardinality, type AnalyzerEntry, type CardinalityResult } from './analyze.js'
 
+export interface CardinalityCheckResult extends CardinalityResult {
+  /** Every file parsed, in input order; a clean one has no violation. */
+  readonly scannedFiles: readonly string[]
+}
+
 /** Analyzes `@downstream` cardinality across `sourceFiles` (paths relative to `cwd`). */
-export function checkCardinality(cwd: string, sourceFiles: readonly string[]): CardinalityResult {
+export function checkCardinality(cwd: string, sourceFiles: readonly string[]): CardinalityCheckResult {
   const entries: AnalyzerEntry[] = []
+  const scannedFiles: string[] = []
 
   for (const file of sourceFiles) {
     const abs = join(cwd, file)
@@ -23,11 +29,12 @@ export function checkCardinality(cwd: string, sourceFiles: readonly string[]): C
       // the type checker's diagnostic, not this check's.
       continue
     }
+    scannedFiles.push(file)
 
     for (const site of sites) {
       entries.push({ file, site })
     }
   }
 
-  return analyzeCardinality(entries)
+  return { ...analyzeCardinality(entries), scannedFiles }
 }

package/src/trace/check/coverage-check.ts

@@ -37,6 +37,8 @@ export interface CoverageViolation {
 export interface CoverageCheckResult {
   readonly violations: readonly CoverageViolation[]
   readonly scanned: number
+  /** Every file parsed, in input order; a clean one has no violation. */
+  readonly scannedFiles: readonly string[]
 }
 
 interface IoSite {
@@ -61,6 +63,7 @@ export function checkCoverage(
 ): CoverageCheckResult {
   const violations: CoverageViolation[] = []
   let scanned = 0
+  const scannedFiles: string[] = []
 
   for (const file of sourceFiles) {
     const abs = join(cwd, file)
@@ -78,6 +81,7 @@ export function checkCoverage(
       continue
     }
     scanned++
+    scannedFiles.push(file)
 
     const ioSites = collectIoSites(program, extras)
     const flowStepRanges = collectFlowStepRanges(sites)
@@ -124,7 +128,7 @@ export function checkCoverage(
     }
   }
 
-  return { violations, scanned }
+  return { violations, scanned, scannedFiles }
 }
 
 interface FlowStepRange {

package/src/trace/check/flow-check.ts

@@ -23,12 +23,15 @@ export interface FlowViolation {
 export interface FlowCheckResult {
   readonly violations: readonly FlowViolation[]
   readonly scanned: number
+  /** Every file parsed, in input order; a clean one has no violation. */
+  readonly scannedFiles: readonly string[]
 }
 
 /** Validates every `@flow_step` annotation in `sourceFiles` (paths relative to `cwd`). */
 export function checkFlowAnnotations(cwd: string, sourceFiles: readonly string[]): FlowCheckResult {
   const violations: FlowViolation[] = []
   let scanned = 0
+  const scannedFiles: string[] = []
 
   for (const file of sourceFiles) {
     const abs = join(cwd, file)
@@ -42,13 +45,14 @@ export function checkFlowAnnotations(cwd: string, sourceFiles: readonly string[]
       continue
     }
     scanned++
+    scannedFiles.push(file)
 
     for (const site of sites) {
       collectSiteViolations(file, site, violations)
     }
   }
 
-  return { violations, scanned }
+  return { violations, scanned, scannedFiles }
 }
 
 function collectSiteViolations(file: string, site: FlowStepSite, out: FlowViolation[]): void {