edf2csv 0.5.86 → 0.5.87

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 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.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.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.