feat: add --format option for output formatting

- Add --format option with support for text, json, and json_pp formats
- json_pp provides pretty-printed JSON output for human readability
- Maintain backward compatibility with existing --json option
- Resolves #251

Author: djken2009

changelog.d/20250919_031500_djken2009_format_option.md

@@ -0,0 +1,46 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+For top level release notes, leave all the headers commented out.
+-->
+
+### Added
+
+- Added `--format` option to specify output format: `text` (default), `json`, or `json_pp` (pretty-printed JSON)
+- Pretty-printed JSON output support via `--format json_pp` option
+
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+### Deprecated
+
+- Deprecated `--json` option in favor of `--format json` (backward compatibility maintained)
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->
+<!--
+### Infrastructure
+
+- A bullet item for the Infrastructure category.
+
+-->

src/main.ts

@@ -33,9 +33,14 @@ export async function main(): Promise<ValidationResult> {
   // Run the schema based validator
   const schemaResult = await validate(tree, options, config)
 
+  // Handle backward compatibility: if --json is used, override format
+  const outputFormat = options.json ? 'json' : (options.format || 'text')
+
   let output_string = ''
-  if (options.json) {
-    output_string = resultToJSONStr(schemaResult)
+  if (outputFormat === 'json') {
+    output_string = resultToJSONStr(schemaResult, false)
+  } else if (outputFormat === 'json_pp') {
+    output_string = resultToJSONStr(schemaResult, true)
   } else {
     output_string = consoleFormat(schemaResult, {
       verbose: options.verbose ? options.verbose : false,

src/setup/options.ts

@@ -19,7 +19,8 @@ export type ValidatorOptions = {
   datasetPath: string
   schema?: string
   config?: string
-  json?: boolean
+  json?: boolean  // Deprecated, kept for backward compatibility
+  format?: string
   verbose?: boolean
   ignoreNiftiHeaders?: boolean
   ignoreWarnings?: boolean
@@ -42,6 +43,8 @@ const modalityType = new EnumType<string>(
   Object.keys(schema.rules.modalities),
 )
 
+const formatType = new EnumType<string>(['text', 'json', 'json_pp'])
+
 /** Extendable Cliffy Command with built in BIDS validator options */
 export const validateCommand: Command<void, void, any, string[], void> = new Command()
   .name('bids-validator')
@@ -50,7 +53,13 @@ export const validateCommand: Command<void, void, any, string[], void> = new Com
     'This tool checks if a dataset in a given directory is compatible with the Brain Imaging Data Structure specification. To learn more about Brain Imaging Data Structure visit http://bids.neuroimaging.io',
   )
   .arguments('<dataset_directory>')
-  .option('--json', 'Output machine readable JSON')
+  .option('--json', '[Deprecated] Use --format json instead. Output machine readable JSON')
+  .type('format', formatType)
+  .option(
+    '--format <format:format>',
+    'Output format: text (default), json, or json_pp (pretty-printed JSON)',
+    { default: 'text' }
+  )
   .option(
     '-s, --schema <URL-or-tag:string>',
     'Specify a schema version to use for validation',

src/utils/output.ts

@@ -171,7 +171,8 @@ function helpUrl(code: string): string {
   return `https://neurostars.org/search?q=${code}`
 }
 
-export function resultToJSONStr(result: ValidationResult): string {
+export function resultToJSONStr(result: ValidationResult, pretty: boolean = false): string {
+  const indent = pretty ? 2 : 0
   return JSON.stringify(result, (key, value) => {
     if (value?.parent) {
       // Remove parent reference to avoid circular references
@@ -182,5 +183,5 @@ export function resultToJSONStr(result: ValidationResult): string {
     } else {
       return value
     }
-  })
+  }, indent)
 }