pipework 0.269.0 → 0.271.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.271.0
+
+- **Added: the doctrine rules run in eslint** (#947). `define/prefer-pipe-define`, `define/no-raw-pgTable`, `define/brand-primary-key` and `define/use-traits` are now ESLint rules in the lint preset, on at `error`, with the same ids, lines and messages `pipework check`'s doctrine step reports, from one shared implementation. `pipework lint`, editors and plain `eslint` with the generated config see them per file; test files and `.d.ts` are not judged. Turn one off through `lint.extra` rules like any preset rule. `check` keeps its doctrine step, so a finding in a linted file may appear in both steps.
+
+## 0.270.0
+
+- **Added: check's steps run on their own, with JSON per violation** (#946). `pipework doctrine`, `pipework flow`, `pipework cardinality` and `pipework startup` each run one step of `check`, with `--format json` (a record of `rule`, `file`, `line`, `message` per violation and one entry per scanned file), `--output-file <path>`, the scope flags, and for the first three explicit file paths. `pipework check` gains `--format json` (one record per step) and `--only` / `--skip` by step name; a step not selected is reported as skipped, never passed. Each record's `reads` and REFERENCE.md say what a verdict depends on: doctrine and flow read only the file; cardinality cycles and the derived cap read every scanned file.
+- **Added: `pipework lint --list-files`** (#946). Prints the repo-relative files `pipework check`'s lint pass covers, one per line and sorted, without linting: each module's include globs plus the files at the workspace root outside every module. It reads `pipework.config.ts`, not a package `lint` script, and `--shard i/n` prints the files of that shard (the root files belong to shard 1), so a runner can derive its lint shard from the lint configuration. `check` lints the same population, from one function.
+
 ## 0.269.0
 
 - **Added: a route can opt out of cancel-on-disconnect** (#944). Since 0.266.0 a client that closes the connection aborts the request and rolls its transaction back, which loses the work of a webhook receiver whose sender abandons slow deliveries (GitHub after 10 s) and does not redeliver. `.route(method, path, { cancelOnDisconnect: false })` skips the disconnect listener for that route: its `signal` never aborts, the handler runs to completion and the transaction commits after the socket has closed. The default is unchanged (`true`).

package/REFERENCE.md

@@ -601,10 +601,54 @@ Thrown for configuration problems — includes a suggestion for how to fix.
 
 `pipework lint [eslint args and files...]` runs eslint in the current directory with the config, include globs, ignores and eslint binary `pipework check` uses for that module (at the workspace root: the whole workspace). With no files named it lints the module's include globs; with files named it lints only those. Every other argument goes to eslint verbatim, so `pipework lint --format json --output-file r.json src/a.ts` writes `r.json` for `src/a.ts` alone. The exit code is eslint's.
 
+`pipework lint --list-files [--shard i/n]` prints, one per line and sorted, the repo-relative files `pipework check`'s lint pass covers, and lints nothing. The set comes from `pipework.config.ts` (`lint.include`, `lint.modules.<path>.include`, the declared modules), not from a package `lint` script, so a runner that shards or caches lint per file derives its population from the lint configuration. It is the same population `check` lints: each module's include globs, plus the files at the workspace root outside every module (`lint.include` globs applied at the root, such as `*.ts` and `scripts/**/*.ts`), which belong to shard 1. `--shard i/n` splits modules as `check --shard` does. `--list-files` takes no other argument and exits 1 naming one it is given.
+
 Generated module manifests declare `"lint": "pipework lint"` and `"type-check": "tsc --noEmit -p tsconfig.check.json"` (the config `check` type-checks with, which resolves sibling packages from source), so `pnpm -C <module> run lint --format json --output-file r.json <file>` gives `check`'s verdict for that file. `test` stays `vitest run`: `pipework test` provisions test databases and project filters that a bare `vitest run` in a module does not. Run `pipework sync` (or `pipework install`) to regenerate the manifests and `eslint.config.js`.
 
+The lint preset also carries the four doctrine rules at `error`: `define/prefer-pipe-define`, `define/no-raw-pgTable`, `define/brand-primary-key` and `define/use-traits`. They are the same scans `pipework check`'s doctrine step runs (one implementation, same file, line and message), skip test files and `.d.ts`, and can be turned off through `lint.extra` rules like any preset rule. `check` keeps its doctrine step for files outside the lint globs, so a finding in a linted file can appear in both steps.
+
 `lint.modules.<path>` overrides apply per file: the root `eslint.config.js` carries each module's `rules` and `configs` with their `files` and `ignores` globs prefixed by the module's path, so plain `eslint <file>` from the workspace root or a module directory agrees with `pipework check`.
 
+### `pipework check` steps
+
+`pipework check` runs these steps, in this order, and each has a name: `checksums`, `vitest-config`, `eslint-config`, `config-load`, `doctrine`, `flow`, `cardinality`, `coverage`, `lint`, `typecheck`, `startup`, `boundaries`, `dependencies`, `install`.
+
+- `--only <a,b>` runs just those steps; `--skip <a,b>` runs all but those. Names are comma-separated. An unknown name, or `--only` with `--skip`, is refused with an error that lists the valid names. A step that is not selected is named as skipped in the output and never counts as passed; the closing line then reads `Selected checks passed (not run: ...)` instead of `All checks passed`.
+- `--format json` writes one record per step, as a JSON array in the order above, to stdout, or to the file named by `--output-file <path>`. Every human line stays on stderr. A step that did not run (not selected, no modules resolved, no `pipework.config.ts`, no `scripts/check-boundaries.js`) has `"status": "skipped"` and a `reason`. The exit code is 1 when any step failed.
+
+`pipework doctrine`, `pipework flow`, `pipework cardinality` and `pipework startup` run one step alone. Each takes `--format json`, `--output-file <path>` and the scope flags of `check` (`--all`, `--module`, `--staged`, `--fast`, `--full`). `doctrine`, `flow` and `cardinality` also take file paths: with files, only those files are judged; without, they judge the source files `check` judges for the scope. `startup` takes no files. The exit code is 1 when the step fails, else 0; the human output is what `check` prints for that step. `pipework doctrine --format json --output-file d.json src/a.ts` writes a single record for `src/a.ts`.
+
+A record:
+
+```json
+{
+  "step": "doctrine",
+  "status": "failed",
+  "pipeworkVersion": "0.269.0",
+  "reads": "Each file's verdict depends only on that file's bytes and the pipework version; no other file is read.",
+  "files": [
+    { "file": "src/a.ts", "violations": [{ "rule": "define/prefer-pipe-define", "file": "src/a.ts", "line": 3, "message": "..." }] },
+    { "file": "src/b.ts", "violations": [] }
+  ],
+  "violations": [{ "rule": "define/prefer-pipe-define", "file": "src/a.ts", "line": 3, "message": "..." }]
+}
+```
+
+`status` is `passed`, `failed` or `skipped`. `violations` is every violation, flat; a violation that is not at a line (a config value) has `line: 0`. `files` is on `doctrine`, `flow`, `cardinality` and `coverage` only and lists every file scanned, clean ones with an empty `violations`, so a gate can bank one verdict per file. A file that does not parse is not judged by `flow`, `cardinality` or `coverage` and is absent from `files`. The other steps carry `status` and `violations` (empty for steps that report no structured violations). `coverage` never fails: its violations are warnings under `"status": "passed"`.
+
+What each verdict reads (also in each record's `reads`):
+
+| step | reads |
+|---|---|
+| `doctrine` | only the file's bytes and the pipework version |
+| `flow` | only the file's bytes and the pipework version |
+| `cardinality` | `cardinality/mismatch` and `cardinality/unannotated-ambiguity`: only the file's bytes. `cardinality/step-cycle`: ALL scanned source files (the call graph spans files). `cardinality/structural-max-too-low` and `-stale`: all scanned source files and `trace.structuralMax` in `pipework.config.ts`. With explicit file arguments the graph holds only those files, so cycles and the derived cap reflect that subset |
+| `coverage` | the file's bytes, the pipework version and `trace.io` in `pipework.config.ts` |
+| `startup` | `pipework.config.ts` loaded and everything it imports (it is evaluated, so every `define()` and registration it reaches counts); no database, no connection. Its violations are `startup/<phase>` with file `pipework.config.ts` |
+| `lint` | the files the lint globs name, `eslint.config.js`, the tsconfig chain and `lint.*` in `pipework.config.ts`; type-aware rules also read the files a linted file imports. Not per-file independent |
+| `typecheck` | each module's tsconfig and the whole program it names. Not per-file independent |
+| `checksums`, `eslint-config`, `vitest-config`, `config-load`, `boundaries`, `dependencies`, `install` | the files named in the record's `reads` |
+
 ### Types
 
 **`StatementEvent`**

package/dist/cli/commands/check-steps.d.ts

@@ -0,0 +1,34 @@
+export declare const STEP_NAMES: readonly ["checksums", "vitest-config", "eslint-config", "config-load", "doctrine", "flow", "cardinality", "coverage", "lint", "typecheck", "startup", "boundaries", "dependencies", "install"];
+export type StepName = typeof STEP_NAMES[number];
+export interface StepViolation {
+    readonly rule: string;
+    readonly file: string;
+    /** 1-based; 0 when the violation is not at a line (a config value, a whole-project fault). */
+    readonly line: number;
+    readonly message: string;
+}
+export interface FileVerdict {
+    readonly file: string;
+    readonly violations: readonly StepViolation[];
+}
+export interface StepRecord {
+    readonly step: StepName;
+    readonly status: 'passed' | 'failed' | 'skipped';
+    readonly pipeworkVersion: string;
+    /** What the verdict depends on. */
+    readonly reads: string;
+    /** Only on a skipped step: why it did not run. */
+    readonly reason?: string;
+    /** Every scanned file, clean ones with an empty list. Only doctrine, flow, cardinality and coverage. */
+    readonly files?: readonly FileVerdict[];
+    readonly violations: readonly StepViolation[];
+}
+/** What each step's verdict depends on, for a gate that keys cached verdicts. */
+export declare const STEP_READS: Readonly<Record<StepName, string>>;
+export declare function record(step: StepName, version: string, status: StepRecord['status'], violations?: readonly StepViolation[], scannedFiles?: readonly string[], reason?: string): StepRecord;
+export type StepSelection = (step: StepName) => boolean;
+/** --only and --skip take comma-separated step names; either alone, never both. */
+export declare function parseStepSelection(only: string | undefined, skip: string | undefined): StepSelection;
+/** The JSON to stdout, or to `outputFile` when given. */
+export declare function emitJson(value: unknown, outputFile: string | undefined): void;
+//# sourceMappingURL=check-steps.d.ts.map

package/dist/cli/commands/check-steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-steps.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check-steps.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,UAAU,iMAGb,CAAA;AAEV,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAA;AAEhD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,8FAA8F;IAC9F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,mCAAmC;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,kDAAkD;IAClD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,wGAAwG;IACxG,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAA;CAC9C;AAED,iFAAiF;AACjF,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAezD,CAAA;AAED,wBAAgB,MAAM,CACpB,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,EAC5B,UAAU,GAAE,SAAS,aAAa,EAAO,EACzC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,EAChC,MAAM,CAAC,EAAE,MAAM,GACd,UAAU,CAMZ;AAED,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAA;AAEvD,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAgBpG;AAED,yDAAyD;AACzD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAI7E"}

package/dist/cli/commands/check-steps.js

@@ -0,0 +1,60 @@
+// The vocabulary of `check`'s steps: names, the structured record each step
+// yields, the --only/--skip selection, and the JSON writer.
+import { writeFileSync } from 'node:fs';
+export const STEP_NAMES = [
+    'checksums', 'vitest-config', 'eslint-config', 'config-load', 'doctrine', 'flow',
+    'cardinality', 'coverage', 'lint', 'typecheck', 'startup', 'boundaries', 'dependencies', 'install',
+];
+/** What each step's verdict depends on, for a gate that keys cached verdicts. */
+export const STEP_READS = {
+    'checksums': 'package.json (its _generated and _checksum fields).',
+    'vitest-config': 'vitest.config.ts, any stale vitest configs under the workspace, and the vitest section of pipework.config.ts (loaded, with everything it imports).',
+    'eslint-config': 'eslint.config.js and the pipework version.',
+    'config-load': 'pipework.config.ts and everything it imports (it is evaluated).',
+    'doctrine': "Each file's verdict depends only on that file's bytes and the pipework version; no other file is read.",
+    'flow': "Each file's verdict depends only on that file's bytes and the pipework version; no other file is read. A file that does not parse is not judged and is absent from files.",
+    'cardinality': "cardinality/mismatch and cardinality/unannotated-ambiguity depend only on the file's own bytes. cardinality/step-cycle depends on ALL scanned source files (the call graph spans files), and the cardinality/structural-max-* verdicts depend on all scanned source files and trace.structuralMax in pipework.config.ts (loaded, with everything it imports). With explicit file arguments only those files form the graph, so cycles and the derived cap reflect that subset. A file that does not parse is absent from files.",
+    'coverage': "Each file's verdict depends on that file's bytes, the pipework version and trace.io in pipework.config.ts (loaded, with everything it imports). Violations are warnings: the step never fails.",
+    'lint': 'The files the lint include globs name, eslint.config.js, the tsconfig chain and lint.* in pipework.config.ts; type-aware rules also read the files a linted file imports. Not per-file independent.',
+    'typecheck': "Every module's tsconfig and the whole program it names. Not per-file independent.",
+    'startup': 'pipework.config.ts loaded, and everything that config imports (it is evaluated, so every define() and registration it reaches counts). Needs no database and opens no connection.',
+    'boundaries': 'scripts/check-boundaries.js and the repository files it scans.',
+    'dependencies': 'package.json of each workspace package.',
+    'install': "The pipework copies under node_modules (pnpm's virtual-store lockfile and each copy's package.json).",
+};
+export function record(step, version, status, violations = [], scannedFiles, reason) {
+    const base = { step, status, pipeworkVersion: version, reads: STEP_READS[step] };
+    const withReason = reason === undefined ? base : { ...base, reason };
+    if (scannedFiles === undefined)
+        return { ...withReason, violations };
+    const files = scannedFiles.map(file => ({ file, violations: violations.filter(v => v.file === file) }));
+    return { ...withReason, files, violations };
+}
+/** --only and --skip take comma-separated step names; either alone, never both. */
+export function parseStepSelection(only, skip) {
+    const valid = `Valid steps: ${STEP_NAMES.join(', ')}.`;
+    if (only !== undefined && skip !== undefined) {
+        throw new Error(`--only and --skip cannot be combined. ${valid}`);
+    }
+    const raw = only ?? skip;
+    if (raw === undefined)
+        return () => true;
+    const flag = only !== undefined ? '--only' : '--skip';
+    const names = raw.split(',').map(n => n.trim());
+    for (const name of names) {
+        if (!STEP_NAMES.includes(name)) {
+            throw new Error(`${flag} names an unknown step "${name}". ${valid}`);
+        }
+    }
+    const set = new Set(names);
+    return only !== undefined ? step => set.has(step) : step => !set.has(step);
+}
+/** The JSON to stdout, or to `outputFile` when given. */
+export function emitJson(value, outputFile) {
+    const text = JSON.stringify(value, null, 2) + '\n';
+    if (outputFile === undefined)
+        process.stdout.write(text);
+    else
+        writeFileSync(outputFile, text, 'utf-8');
+}
+//# sourceMappingURL=check-steps.js.map

package/dist/cli/commands/check-steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-steps.js","sourceRoot":"","sources":["../../../src/cli/commands/check-steps.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/check.d.ts

@@ -1,7 +1,25 @@
 import type { ScopeMode } from '../../workspace/affected.js';
 import { type Shard } from './shard.js';
-export declare function check(cwd: string, scope?: ScopeMode, shard?: Shard): Promise<void>;
+import { type StepRecord, type StepSelection } from './check-steps.js';
+export interface CheckOptions {
+    /** `json`: one record per step on stdout (or `outputFile`); human lines stay on stderr. */
+    readonly format?: 'human' | 'json';
+    readonly outputFile?: string | undefined;
+    /** Which steps run; the rest are recorded as skipped. */
+    readonly select?: StepSelection;
+}
+export declare function check(cwd: string, scope?: ScopeMode, shard?: Shard, options?: CheckOptions): Promise<void>;
+export interface StepCommandOptions {
+    readonly format?: 'human' | 'json';
+    readonly outputFile?: string | undefined;
+    readonly scope?: ScopeMode;
+    /** Explicit files (doctrine, flow, cardinality): only these are judged. */
+    readonly files?: readonly string[];
+}
+/** `pipework doctrine|flow|cardinality|startup`: one step alone. Returns the exit code. */
+export declare function stepCommand(cwd: string, step: 'doctrine' | 'flow' | 'cardinality' | 'startup', options?: StepCommandOptions): Promise<number>;
 /** The startup checks that need no database — what `serve` would refuse before connecting. */
+export declare function startupStep(cwd: string): Promise<StepRecord>;
 export declare function runStartupChecks(cwd: string): Promise<boolean>;
 /** One line per platform-mode database: the role a running manifold connects as, and the only callers that may open the owner. */
 export declare function describeRuntimeRoles(databases: ReadonlyMap<string, {
@@ -38,8 +56,12 @@ export interface ModuleScope {
 export declare function resolveModulePaths(cwd: string, scope?: ScopeMode): Promise<ModuleScope>;
 export declare function verifyVitestConfig(cwd: string): Promise<boolean>;
 export declare function verifyEslintConfig(cwd: string): boolean;
+export declare function doctrineStep(cwd: string, sourceFiles: readonly string[]): StepRecord;
+export declare function flowStep(cwd: string, sourceFiles: readonly string[]): StepRecord;
 export declare function runFlowCheck(cwd: string, sourceFiles: string[]): boolean;
+export declare function cardinalityStep(cwd: string, sourceFiles: readonly string[], configuredStructuralMax?: number, fullScope?: boolean): StepRecord;
 export declare function runCardinalityCheck(cwd: string, sourceFiles: string[], configuredStructuralMax?: number, fullScope?: boolean): boolean;
+export declare function coverageStep(cwd: string, sourceFiles: readonly string[], extras?: Readonly<Record<string, 'read' | 'write'>>): StepRecord;
 export declare function runCoverageCheckWarning(cwd: string, sourceFiles: string[], extras?: Readonly<Record<string, 'read' | 'write'>>): void;
 export declare function resolveTscBin(cwd: string): string;
 export declare function resolveEslintBin(cwd: string): string;
@@ -95,6 +117,26 @@ export declare function readEslintReport(stdout: string): {
  */
 export declare function builtinConfigArgs(dir: string): string[];
 export declare function lintDirectory(eslintBin: string, dir: string, label: string, cacheLocation: string | ((fingerprint: string) => string), configured?: readonly string[]): Promise<boolean>;
+export declare function runLint(cwd: string, allModules: string[], shard?: Shard): Promise<boolean>;
+export interface LintPopulation {
+    /** The sharded modules, each with the include globs `check` lints it with. */
+    readonly modules: ReadonlyArray<{
+        readonly path: string;
+        readonly includes: readonly string[] | undefined;
+    }>;
+    /** Root files outside every module; empty off shard 1. */
+    readonly root: string[];
+    /** Every file the run lints, repo-relative and sorted. */
+    readonly files: string[];
+}
+/**
+ * The files `check`'s lint pass covers: each sharded module's include globs plus the
+ * root-outside-modules pass (shard 1 only). `runLint` lints this population and
+ * `pipework lint --list-files` prints it, so the two cannot drift.
+ */
+export declare function lintPopulation(cwd: string, allModules: readonly string[], includes: {
+    for: (mod: string) => readonly string[] | undefined;
+}, shard?: Shard): LintPopulation;
 /**
  * Root-level lintable files that no module covers (#402).
  *

package/dist/cli/commands/check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"check.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/check.ts"],"names":[],"mappings":"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"}