refactor(cli): replace magic exit codes with ExitStatus constants

dfa1 · claude · dfa1 · commit 0bab2561ab6f · 2026-05-31T00:09:33.000+02:00
Introduce public ExitStatus class (OK=0, USAGE_ERROR=1,
FILE_NOT_FOUND=2, ERROR=3) and replace bare numeric literals in all
CLI command classes and VortexCli entry point.

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/CountCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/CountCommand.java
@@ -14,19 +14,19 @@ private CountCommand() {
     static int run(String[] args) {
         if (args.length != 2) {
             System.err.println("usage: count <file.vortex>");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         try (VortexReader reader = VortexReader.open(path)) {
             System.out.println(reader.layout().rowCount());
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/ExitStatus.java b/cli/src/main/java/io/github/dfa1/vortex/cli/ExitStatus.java
@@ -0,0 +1,12 @@
+package io.github.dfa1.vortex.cli;
+
+public final class ExitStatus {
+
+    public static final int OK             = 0;
+    public static final int USAGE_ERROR    = 1;
+    public static final int FILE_NOT_FOUND = 2;
+    public static final int ERROR          = 3;
+
+    private ExitStatus() {
+    }
+}
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/ExportCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/ExportCommand.java
@@ -18,21 +18,21 @@ private ExportCommand() {
     static int run(String[] args) {
         if (args.length != 2) {
             System.err.println("usage: export <file.vortex>");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         try {
             Writer stdout = new OutputStreamWriter(System.out, StandardCharsets.UTF_8);
             CsvExporter.exportCsv(path, stdout, ExportOptions.defaults());
             stdout.flush();
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/FilterCommand.java
@@ -41,31 +41,31 @@ private record ParsedFilter(String column, Op op, Comparable<?> value) {}
     static int run(String[] args) {
         if (args.length < 3) {
             System.err.println("usage: filter <file.vortex> <expr>  (e.g. \"price >= 100\")");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         String expr = String.join(" ", Arrays.asList(args).subList(2, args.length));
         ParsedFilter pf;
         try {
             pf = parseFilter(expr);
         } catch (IllegalArgumentException e) {
             System.err.println("error: " + e.getMessage());
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         ScanOptions scanOptions = new ScanOptions(List.of(), toRowFilter(pf), ScanOptions.NO_LIMIT);
         RowPredicate rowPred = toRowPredicate(pf);
         try {
             Writer stdout = new OutputStreamWriter(System.out, StandardCharsets.UTF_8);
             CsvExporter.exportCsvFiltered(path, stdout, ExportOptions.defaults(), scanOptions, rowPred);
             stdout.flush();
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/ImportCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/ImportCommand.java
@@ -15,12 +15,12 @@ private ImportCommand() {
     static int run(String[] args) {
         if (args.length < 2 || args.length > 3) {
             System.err.println("usage: import <file.csv> [out.vortex]");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path csvPath = Path.of(args[1]);
         if (!Files.exists(csvPath)) {
             System.err.println("file not found: " + csvPath);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         Path vortexPath = args.length == 3 ? Path.of(args[2]) : deriveOutputPath(csvPath);
         ImportOptions options = ImportOptions.defaults()
@@ -35,11 +35,11 @@ static int run(String[] args) {
             String cascadingInfo = cascadingDepth > 0 ? String.format(", cascading depth %d", cascadingDepth) : "";
             System.out.printf("written: %s  (%s → %s, %.1f%% smaller%s)%n",
                     vortexPath, formatBytes(csvBytes), formatBytes(vortexBytes), savings * 100, cascadingInfo);
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             clearProgress();
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/InspectCommand.java
@@ -15,19 +15,19 @@ private InspectCommand() {
     static int run(String[] args) {
         if (args.length != 2) {
             System.err.println("usage: inspect <file.vortex>");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         try (VortexReader reader = VortexReader.open(path)) {
             System.out.print(VortexInspector.inspect(reader));
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/SchemaCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/SchemaCommand.java
@@ -15,19 +15,19 @@ private SchemaCommand() {
     static int run(String[] args) {
         if (args.length != 2) {
             System.err.println("usage: schema <file.vortex>");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         try (VortexReader reader = VortexReader.open(path)) {
             System.out.println(formatDType(reader.dtype()));
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/SelectCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/SelectCommand.java
@@ -20,23 +20,23 @@ private SelectCommand() {
     static int run(String[] args) {
         if (args.length < 3) {
             System.err.println("usage: select <file.vortex> <col1> [col2 ...]");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         List<String> columns = Arrays.asList(args).subList(2, args.length);
         ExportOptions options = ExportOptions.defaults().withColumns(columns);
         try {
             Writer stdout = new OutputStreamWriter(System.out, StandardCharsets.UTF_8);
             CsvExporter.exportCsv(path, stdout, options);
             stdout.flush();
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 }
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/StatsCommand.java b/cli/src/main/java/io/github/dfa1/vortex/cli/StatsCommand.java
@@ -18,17 +18,17 @@ private StatsCommand() {
     static int run(String[] args) {
         if (args.length != 2) {
             System.err.println("usage: stats <file.vortex>");
-            return 1;
+            return ExitStatus.USAGE_ERROR;
         }
         Path path = Path.of(args[1]);
         if (!Files.exists(path)) {
             System.err.println("file not found: " + path);
-            return 2;
+            return ExitStatus.FILE_NOT_FOUND;
         }
         try (VortexReader reader = VortexReader.open(path)) {
             if (!(reader.dtype() instanceof DType.Struct schema)) {
                 System.err.println("error: root dtype is not a struct");
-                return 3;
+                return ExitStatus.ERROR;
             }
             long totalRows = reader.layout().rowCount();
             Map<String, ArrayStats> stats = reader.columnStats();
@@ -47,10 +47,10 @@ static int run(String[] args) {
                 String max = s.max() != null ? s.max().toString() : "n/a";
                 System.out.printf("%-20s  %-12s  %15s  %15s%n", name, type, min, max);
             }
-            return 0;
+            return ExitStatus.OK;
         } catch (IOException e) {
             System.err.println("error: " + e.getMessage());
-            return 3;
+            return ExitStatus.ERROR;
         }
     }
 
diff --git a/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java b/cli/src/main/java/io/github/dfa1/vortex/cli/VortexCli.java
@@ -4,7 +4,7 @@
 
 /// Entry point for the Vortex command-line tool.
 ///
-/// Exit codes: 0 = success, 1 = usage error, 2 = file not found, 3 = decode error.
+/// Exit codes: see {@link ExitStatus}.
 public final class VortexCli {
 
     private VortexCli() {
@@ -13,7 +13,7 @@ private VortexCli() {
     public static void main(String[] args) {
         if (args.length == 0) {
             printUsage(System.err);
-            System.exit(1);
+            System.exit(ExitStatus.USAGE_ERROR);
         }
         int exit = switch (args[0]) {
             case "inspect" -> InspectCommand.run(args);
@@ -27,7 +27,7 @@ public static void main(String[] args) {
             default -> {
                 System.err.println("unknown subcommand: " + args[0]);
                 printUsage(System.err);
-                yield 1;
+                yield ExitStatus.USAGE_ERROR;
             }
         };
         System.exit(exit);

Original file line number	Diff line number	Diff line change
`@@ -14,19 +14,19 @@ private CountCommand() {`
`14`	`14`	`static int run(String[] args) {`
`15`	`15`	`if (args.length != 2) {`
`16`	`16`	`System.err.println("usage: count <file.vortex>");`
`17`		`- return 1;`
	`17`	`+ return ExitStatus.USAGE_ERROR;`
`18`	`18`	`}`
`19`	`19`	`Path path = Path.of(args[1]);`
`20`	`20`	`if (!Files.exists(path)) {`
`21`	`21`	`System.err.println("file not found: " + path);`
`22`		`- return 2;`
	`22`	`+ return ExitStatus.FILE_NOT_FOUND;`
`23`	`23`	`}`
`24`	`24`	`try (VortexReader reader = VortexReader.open(path)) {`
`25`	`25`	`System.out.println(reader.layout().rowCount());`
`26`		`- return 0;`
	`26`	`+ return ExitStatus.OK;`
`27`	`27`	`} catch (IOException e) {`
`28`	`28`	`System.err.println("error: " + e.getMessage());`
`29`		`- return 3;`
	`29`	`+ return ExitStatus.ERROR;`
`30`	`30`	`}`
`31`	`31`	`}`
`32`	`32`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,21 +18,21 @@ private ExportCommand() {`
`18`	`18`	`static int run(String[] args) {`
`19`	`19`	`if (args.length != 2) {`
`20`	`20`	`System.err.println("usage: export <file.vortex>");`
`21`		`- return 1;`
	`21`	`+ return ExitStatus.USAGE_ERROR;`
`22`	`22`	`}`
`23`	`23`	`Path path = Path.of(args[1]);`
`24`	`24`	`if (!Files.exists(path)) {`
`25`	`25`	`System.err.println("file not found: " + path);`
`26`		`- return 2;`
	`26`	`+ return ExitStatus.FILE_NOT_FOUND;`
`27`	`27`	`}`
`28`	`28`	`try {`
`29`	`29`	`Writer stdout = new OutputStreamWriter(System.out, StandardCharsets.UTF_8);`
`30`	`30`	`CsvExporter.exportCsv(path, stdout, ExportOptions.defaults());`
`31`	`31`	`stdout.flush();`
`32`		`- return 0;`
	`32`	`+ return ExitStatus.OK;`
`33`	`33`	`} catch (IOException e) {`
`34`	`34`	`System.err.println("error: " + e.getMessage());`
`35`		`- return 3;`
	`35`	`+ return ExitStatus.ERROR;`
`36`	`36`	`}`
`37`	`37`	`}`
`38`	`38`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,19 +15,19 @@ private InspectCommand() {`
`15`	`15`	`static int run(String[] args) {`
`16`	`16`	`if (args.length != 2) {`
`17`	`17`	`System.err.println("usage: inspect <file.vortex>");`
`18`		`- return 1;`
	`18`	`+ return ExitStatus.USAGE_ERROR;`
`19`	`19`	`}`
`20`	`20`	`Path path = Path.of(args[1]);`
`21`	`21`	`if (!Files.exists(path)) {`
`22`	`22`	`System.err.println("file not found: " + path);`
`23`		`- return 2;`
	`23`	`+ return ExitStatus.FILE_NOT_FOUND;`
`24`	`24`	`}`
`25`	`25`	`try (VortexReader reader = VortexReader.open(path)) {`
`26`	`26`	`System.out.print(VortexInspector.inspect(reader));`
`27`		`- return 0;`
	`27`	`+ return ExitStatus.OK;`
`28`	`28`	`} catch (IOException e) {`
`29`	`29`	`System.err.println("error: " + e.getMessage());`
`30`		`- return 3;`
	`30`	`+ return ExitStatus.ERROR;`
`31`	`31`	`}`
`32`	`32`	`}`
`33`	`33`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,19 +15,19 @@ private SchemaCommand() {`
`15`	`15`	`static int run(String[] args) {`
`16`	`16`	`if (args.length != 2) {`
`17`	`17`	`System.err.println("usage: schema <file.vortex>");`
`18`		`- return 1;`
	`18`	`+ return ExitStatus.USAGE_ERROR;`
`19`	`19`	`}`
`20`	`20`	`Path path = Path.of(args[1]);`
`21`	`21`	`if (!Files.exists(path)) {`
`22`	`22`	`System.err.println("file not found: " + path);`
`23`		`- return 2;`
	`23`	`+ return ExitStatus.FILE_NOT_FOUND;`
`24`	`24`	`}`
`25`	`25`	`try (VortexReader reader = VortexReader.open(path)) {`
`26`	`26`	`System.out.println(formatDType(reader.dtype()));`
`27`		`- return 0;`
	`27`	`+ return ExitStatus.OK;`
`28`	`28`	`} catch (IOException e) {`
`29`	`29`	`System.err.println("error: " + e.getMessage());`
`30`		`- return 3;`
	`30`	`+ return ExitStatus.ERROR;`
`31`	`31`	`}`
`32`	`32`	`}`
`33`	`33`
Original file line number	Diff line number	Diff line change
`@@ -20,23 +20,23 @@ private SelectCommand() {`
`20`	`20`	`static int run(String[] args) {`
`21`	`21`	`if (args.length < 3) {`
`22`	`22`	`System.err.println("usage: select <file.vortex> <col1> [col2 ...]");`
`23`		`- return 1;`
	`23`	`+ return ExitStatus.USAGE_ERROR;`
`24`	`24`	`}`
`25`	`25`	`Path path = Path.of(args[1]);`
`26`	`26`	`if (!Files.exists(path)) {`
`27`	`27`	`System.err.println("file not found: " + path);`
`28`		`- return 2;`
	`28`	`+ return ExitStatus.FILE_NOT_FOUND;`
`29`	`29`	`}`
`30`	`30`	`List<String> columns = Arrays.asList(args).subList(2, args.length);`
`31`	`31`	`ExportOptions options = ExportOptions.defaults().withColumns(columns);`
`32`	`32`	`try {`
`33`	`33`	`Writer stdout = new OutputStreamWriter(System.out, StandardCharsets.UTF_8);`
`34`	`34`	`CsvExporter.exportCsv(path, stdout, options);`
`35`	`35`	`stdout.flush();`
`36`		`- return 0;`
	`36`	`+ return ExitStatus.OK;`
`37`	`37`	`} catch (IOException e) {`
`38`	`38`	`System.err.println("error: " + e.getMessage());`
`39`		`- return 3;`
	`39`	`+ return ExitStatus.ERROR;`
`40`	`40`	`}`
`41`	`41`	`}`
`42`	`42`	`}`
Original file line number	Diff line number	Diff line change
`@@ -18,17 +18,17 @@ private StatsCommand() {`
`18`	`18`	`static int run(String[] args) {`
`19`	`19`	`if (args.length != 2) {`
`20`	`20`	`System.err.println("usage: stats <file.vortex>");`
`21`		`- return 1;`
	`21`	`+ return ExitStatus.USAGE_ERROR;`
`22`	`22`	`}`
`23`	`23`	`Path path = Path.of(args[1]);`
`24`	`24`	`if (!Files.exists(path)) {`
`25`	`25`	`System.err.println("file not found: " + path);`
`26`		`- return 2;`
	`26`	`+ return ExitStatus.FILE_NOT_FOUND;`
`27`	`27`	`}`
`28`	`28`	`try (VortexReader reader = VortexReader.open(path)) {`
`29`	`29`	`if (!(reader.dtype() instanceof DType.Struct schema)) {`
`30`	`30`	`System.err.println("error: root dtype is not a struct");`
`31`		`- return 3;`
	`31`	`+ return ExitStatus.ERROR;`
`32`	`32`	`}`
`33`	`33`	`long totalRows = reader.layout().rowCount();`
`34`	`34`	`Map<String, ArrayStats> stats = reader.columnStats();`
`@@ -47,10 +47,10 @@ static int run(String[] args) {`
`47`	`47`	`String max = s.max() != null ? s.max().toString() : "n/a";`
`48`	`48`	`System.out.printf("%-20s %-12s %15s %15s%n", name, type, min, max);`
`49`	`49`	`}`
`50`		`- return 0;`
	`50`	`+ return ExitStatus.OK;`
`51`	`51`	`} catch (IOException e) {`
`52`	`52`	`System.err.println("error: " + e.getMessage());`
`53`		`- return 3;`
	`53`	`+ return ExitStatus.ERROR;`
`54`	`54`	`}`
`55`	`55`	`}`
`56`	`56`