edf2csv 0.5.86 → 0.5.88

package/CHANGELOG.md

@@ -3,6 +3,63 @@
 Notable changes to edf2csv. Versions follow [semantic versioning](https://semver.org); while the
 major version is 0, a minor bump may contain breaking changes.
 
+## 0.5.88
+
+### Fixed: a worker killed from outside made the batch exit 2, "the command line is the problem"
+
+`worstOf` combines the children's exit codes into the run's:
+
+```ts
+return codes.includes(EXIT_ERROR) ? EXIT_ERROR : EXIT_USAGE;
+```
+
+which assumes every child exits 1 or 2. A child killed by a signal exits 130 or 143 — its own
+interrupt handler does that — so a `--jobs` worker stopped by SIGTERM fell through to 2. The
+exit-code table calls 2 "The command line is the problem", and warnings-and-errors "The command
+was invoked incorrectly, or asked for something the recording can't provide". The command was
+fine; something killed a worker, which is how the out-of-memory killer and a scheduler's time
+limit both arrive. A script branching on 2 to mean "I typed it wrong" would retry forever.
+
+Asked the other way round now: 2 is the narrow claim, so every recording has to have earned it,
+and anything else in the list makes the run a failure. `[143]` is 1, `[2]` is still 2, `[2, 143]`
+is 1.
+
+Pinned by testing the mapping directly rather than by racing a signal at a real worker — the
+mapping is the defect, and a batch long enough to catch mid-flight is a race in a test suite.
+
+## 0.5.87
+
+### Fixed: `--info --stdout` described files the command never writes
+
+```
+$ edf2csv mixed-rates.edf --info --stdout
+Would write 1,155 rows, roughly 22.2 KB.
+warning: Channels use 3 different sampling rates (256 Hz, 128 Hz, 1 Hz).
+         They are written to one file per rate so no channel is resampled.
+```
+
+for a command that refuses to run, writes nothing, and names no file:
+
+```
+$ edf2csv mixed-rates.edf --stdout
+error: --stdout needs exactly one table, but this recording produces 3 ...
+```
+
+`--info` exists to say what a conversion will do, and refusing is one of the things it does.
+It was not passed `--stdout` at all, so the plan it described was a different command's.
+
+The conversion's three `--stdout` guards are lifted into `stdoutRefusal` and `--info` asks the
+same question, so there is one wording rather than two that can drift — the test asserts the
+preview contains the refusal's own sentence. Reported as a warning rather than a refusal, for
+the reason 0.5.51 gives about the destination guards: `--info` writes nothing, so a rule about
+the output has no business stopping it from describing the recording, and being told the command
+will not work is exactly what was asked. New diagnostic code `STDOUT_UNSUPPORTED`, documented on
+all three pages.
+
+`--info --stdout --json` is no longer refused either. That guard exists because a CSV and a
+summary cannot share stdout; under `--info` there is no CSV, and the description *is* the JSON.
+It was the one way a script could see this warning at all.
+
 ## 0.5.86
 
 ### Fixed: a file holding half a million samples was told no data was written

package/dist/cli.d.ts

@@ -9,4 +9,13 @@
  */
 import { defaultOutputDir } from './convert/run.js';
 export declare function main(argv: readonly string[]): Promise<number>;
-export { defaultOutputDir };
+/**
+ * The exit code for a run in which several files failed for different reasons.
+ *
+ * 2 means "you invoked it wrong" and 1 means "something went wrong with a file". When both
+ * happened, 1 is the honest answer: the invocation cannot be the whole story once a file has
+ * genuinely failed. With a single input there is only ever one code, so its exit status is
+ * exactly what it always was.
+ */
+declare function worstOf(codes: readonly number[]): number;
+export { defaultOutputDir, worstOf };

package/dist/cli.js

@@ -18,7 +18,7 @@ import process from 'node:process';
 import { EdfError } from './edf/errors.js';
 import { EdfFile } from './edf/reader.js';
 import { buildPlan, withoutFileRateWarning } from './convert/plan.js';
-import { ConversionError, USAGE_ERROR_CODES, convert, defaultOutputDir } from './convert/run.js';
+import { ConversionError, USAGE_ERROR_CODES, convert, defaultOutputDir, stdoutRefusal, } from './convert/run.js';
 import { ChannelSelectionError } from './convert/channels.js';
 // Shared with the library so a bad option is the same error whichever way it arrived.
 import { OptionError } from './convert/options.js';
@@ -256,7 +256,17 @@ export async function main(argv) {
     // Both of these claim stdout. Allowing them together wrote the CSV and then the summary
     // object onto one stream, producing a document that is neither valid CSV nor valid
     // JSON — and silently, since each half looked right on its own.
-    if (toStdout && asJson) {
+    /*
+      Not under --info, which writes no CSV for --json to collide with.
+  
+      The two claim stdout because one puts a CSV there and the other a summary. `--info` puts
+      neither: it prints a description, and under --json that description *is* the JSON. So
+      `--info --stdout --json` — a script asking "would --stdout work on this recording, in a
+      form I can parse" — was refused for a conflict that cannot arise, which is the same shape
+      as the destination guards 0.5.51 stopped applying to it. It is also the only way to see
+      the STDOUT_UNSUPPORTED warning from a script.
+    */
+    if (toStdout && asJson && values['info'] !== true) {
         /*
           `error: ` and the seven-space continuation, like every other refusal.
     
@@ -409,7 +419,7 @@ export async function main(argv) {
                 if (batch && !asJson && index > 0)
                     process.stdout.write('\n');
                 try {
-                    warnings += await showInfo(input, shared, asJson, jsonIndent, batch);
+                    warnings += await showInfo(input, shared, asJson, jsonIndent, batch, values['stdout'] === true);
                 }
                 catch (error) {
                     failures.push(reportError(error, batch ? input : undefined));
@@ -618,7 +628,7 @@ export async function main(argv) {
     }
 }
 /** Print one recording's `--info`, and return how many diagnostics it raised. */
-async function showInfo(input, shared, asJson, jsonIndent, batch = false) {
+async function showInfo(input, shared, asJson, jsonIndent, batch = false, toStdout = false) {
     const file = await EdfFile.open(input);
     try {
         /*
@@ -664,6 +674,30 @@ async function showInfo(input, shared, asJson, jsonIndent, batch = false) {
             recordStarts: timing.starts,
         }, shared);
         plan.diagnostics.push(...timing.diagnostics);
+        /*
+          What --stdout would do with this recording, which --info did not ask.
+    
+          `--info --stdout` on a three-rate file predicted "Would write 1,155 rows, roughly
+          22.2 KB" and said the channels "are written to one file per rate" — for a command that
+          refuses to run, writes nothing and names no file. --info exists to say what a
+          conversion will do, and refusing is one of the things it does.
+    
+          A warning rather than a refusal, for the reason 0.5.51 gives about the destination
+          guards: --info writes nothing, so a rule about the output has no business stopping it
+          from describing the recording — and being told the command will not work is exactly
+          what was asked. The conversion's own guard supplies the words, so there is one wording.
+        */
+        if (toStdout) {
+            const refusal = stdoutRefusal(file, plan);
+            if (refusal) {
+                plan.diagnostics.push({
+                    code: 'STDOUT_UNSUPPORTED',
+                    severity: 'warning',
+                    message: `--stdout would refuse this recording: ${refusal.message.replace(/^--stdout /u, '')}`,
+                    ...(refusal.hint === undefined ? {} : { hint: refusal.hint }),
+                });
+            }
+        }
         process.stdout.write(asJson ? `${infoJson(file, plan, jsonIndent)}\n` : `${formatInfo(file, plan)}\n`);
         // Under --json the warnings travel inside the document, exactly as they do for a
         // conversion, so stderr stays empty and the whole result is one parseable thing.
@@ -1254,7 +1288,22 @@ function assertDistinct(inputs, destinations) {
  * exactly what it always was.
  */
 function worstOf(codes) {
-    return codes.includes(EXIT_ERROR) ? EXIT_ERROR : EXIT_USAGE;
+    /*
+      Anything that is not "the command line is the problem" is a failure of the run.
+  
+      This tested for `EXIT_ERROR` and fell through to `EXIT_USAGE` for everything else, on the
+      assumption that a child exits 1 or 2. A child killed by a signal exits 130 or 143 — its
+      own interrupt handler does that — so a `--jobs` worker stopped by SIGTERM made the batch
+      exit 2, which cli-reference's table defines as "The command line is the problem" and
+      warnings-and-errors as "The command was invoked incorrectly, or asked for something the
+      recording can't provide". The command was fine; something killed a worker. The
+      out-of-memory killer and a scheduler's time limit both arrive exactly this way, and the
+      serial path reports the same event as the failure it is.
+  
+      Asking the question the other way round is also the honest one: 2 is the narrow claim,
+      so it should be the one that has to be earned by every code in the list.
+    */
+    return codes.some((code) => code !== EXIT_USAGE) ? EXIT_ERROR : EXIT_USAGE;
 }
 /**
  * Convert one recording in a separate process, and collect everything it printed.
@@ -1567,7 +1616,10 @@ function message(error, indent = '') {
     // one, alongside the usage text, so they pass nothing and stay flush left.
     return printableLines(error instanceof Error ? error.message : String(error), indent);
 }
-export { defaultOutputDir };
+// `worstOf` is exported for the test that pins the exit-code mapping. A batch's verdict is
+// one of the few things a script branches on, and the mapping is easier to check directly
+// than by racing a signal at a worker.
+export { defaultOutputDir, worstOf };
 /**
  * Whether this file was executed rather than imported.
  *