feat(device-profiler): add JSON output format (#377)

Add JSON output format to device-profiler CLI tool, enabling machine-readable output for automation and integration with other tools.

Users can now choose between table (default) and JSON output formats using the --format or -f flag.

Features:
- CLI option: --format/-f with choices table/json (default: table)
- JSON formatter with numeric register values (0-65535)
- Progress suppression in JSON mode
- Comprehensive documentation with examples
- 100% test coverage for JSON formatter

Implementation:
- Register values as 16-bit unsigned integers using readUInt16BE(0)
- Big-endian byte order (Modbus standard)
- Direct numeric access, no parsing required
- Maintains backward compatibility (table format default)

All 120 tests passing with 98%+ coverage.

Closes #372

Author: groupsky

packages/device-profiler/README.md

@@ -10,6 +10,7 @@ Device profiler for discovering Modbus register maps through automated scanning.
 - Timing measurement for each read operation
 - Error classification (timeout, CRC, Modbus exceptions)
 - Summary table of discovered registers
+- **JSON output format** for automation and integration
 
 ## Installation
 
@@ -22,17 +23,27 @@ npm install @ya-modbus/device-profiler
 ### CLI
 
 ```bash
+# Table output (default)
 ya-modbus-profile --port /dev/ttyUSB0 --slave-id 1 --baud 9600
+
+# JSON output for automation
+ya-modbus-profile --port /dev/ttyUSB0 --slave-id 1 --format json
 ```
 
 Options:
 
-- `--port` - Serial port or TCP host:port
-- `--slave-id` - Modbus slave ID
-- `--baud` - Baud rate for RTU (default: 9600)
-- `--start` - Start register address (default: 0)
-- `--end` - End register address (default: 100)
-- `--batch` - Batch size for reads (default: 10)
+- `--port` - Serial port (e.g., `/dev/ttyUSB0`) or TCP host:port (e.g., `localhost:502`)
+- `--slave-id` - Modbus slave ID (1-247)
+- `--type` - Register type: `holding` or `input` (default: `holding`)
+- `--start` - Start register address (default: `0`)
+- `--end` - End register address (default: `100`)
+- `--batch` - Batch size for reads (default: `10`)
+- `--baud` - Baud rate for RTU (default: `9600`)
+- `--parity` - Parity for RTU: `none`, `even`, `odd` (default: `none`)
+- `--data-bits` - Data bits for RTU (default: `8`)
+- `--stop-bits` - Stop bits for RTU (default: `1`)
+- `--timeout` - Response timeout in milliseconds (default: `1000`)
+- `-f, --format` - Output format: `table` or `json` (default: `table`)
 
 ### Programmatic
 
@@ -56,14 +67,134 @@ await scanRegisters({
 
 ## Output
 
-The scanner produces a summary showing:
+### Table Format (Default)
+
+The scanner produces a summary table showing:
 
 - Register address
 - Register type (holding/input)
 - Read success/failure
-- Response time
+- Register value (hex-encoded)
+- Response time (milliseconds)
 - Error details (if any)
 
+Example:
+
+```
+Scanning holding registers from 0 to 10...
+
+Progress: 11/11 (100%)
+
+Scan complete!
+
+┌─────────┬─────────┬─────────┬───────┬────────┬───────┐
+│ Address │ Type    │ Status  │ Value │ Timing │ Error │
+├─────────┼─────────┼─────────┼───────┼────────┼───────┤
+│ 0       │ holding │ ✓       │ 1234  │ 15ms   │       │
+│ 1       │ holding │ ✗       │       │ 1000ms │ Timeout waiting for response │
+│ 2       │ holding │ ✓       │ 5678  │ 12ms   │       │
+└─────────┴─────────┴─────────┴───────┴────────┴───────┘
+```
+
+### JSON Format
+
+For automation and integration with other tools, use `--format json` to output machine-readable JSON:
+
+```bash
+ya-modbus-profile --port /dev/ttyUSB0 --slave-id 1 --format json
+```
+
+#### JSON Structure
+
+The JSON output includes:
+
+- **`timestamp`** (string): ISO 8601 timestamp when the scan completed
+- **`scan`** (object): Scan configuration
+  - `type` (string): Register type (`"holding"` or `"input"`)
+  - `startAddress` (number): Starting register address
+  - `endAddress` (number): Ending register address (inclusive)
+  - `batchSize` (number): Batch size used for reading
+- **`connection`** (object): Connection details
+  - `port` (string): Serial port path or TCP host:port
+- **`results`** (array): Array of scan results, one per register
+  - `address` (number): Register address
+  - `type` (string): Register type (`"holding"` or `"input"`)
+  - `success` (boolean): Whether the read succeeded
+  - `value` (number | null): 16-bit register value (0-65535) or `null` if failed
+  - `timing` (number): Read operation duration in milliseconds
+  - `error` (string, optional): Error message (only present when `success=false`)
+  - `errorType` (string, optional): Error classification (only present when `success=false`)
+    - `"timeout"`: Device did not respond within timeout period
+    - `"crc"`: CRC check failed (data corruption)
+    - `"modbus_exception"`: Device returned a Modbus exception
+    - `"unknown"`: Other errors
+- **`summary`** (object): Scan statistics
+  - `total` (number): Total registers scanned
+  - `successful` (number): Number of successful reads
+  - `failed` (number): Number of failed reads
+  - `totalTimeMs` (number): Total scan duration in milliseconds
+  - `averageTimeMs` (number): Average read time per register in milliseconds
+
+#### JSON Example
+
+```json
+{
+  "timestamp": "2026-02-13T18:17:41.367Z",
+  "scan": {
+    "type": "holding",
+    "startAddress": 0,
+    "endAddress": 10,
+    "batchSize": 10
+  },
+  "connection": {
+    "port": "/dev/ttyUSB0"
+  },
+  "results": [
+    {
+      "address": 0,
+      "type": "holding",
+      "success": true,
+      "value": 4660,
+      "timing": 15
+    },
+    {
+      "address": 1,
+      "type": "holding",
+      "success": false,
+      "value": null,
+      "timing": 1000,
+      "error": "Timeout waiting for response",
+      "errorType": "timeout"
+    },
+    {
+      "address": 2,
+      "type": "holding",
+      "success": true,
+      "value": 22136,
+      "timing": 12
+    }
+  ],
+  "summary": {
+    "total": 3,
+    "successful": 2,
+    "failed": 1,
+    "totalTimeMs": 1027,
+    "averageTimeMs": 342.33
+  }
+}
+```
+
+#### JSON Output Notes
+
+- **Progress messages** are suppressed in JSON mode for clean output
+- **Register values** are 16-bit unsigned integers (0-65535) in big-endian format
+  - Direct numeric access, no parsing needed
+  - Example: bytes `[0x12, 0x34]` = 4660 decimal (0x1234 hex)
+  - Format as hex if needed: `value.toString(16).padStart(4, '0')`
+- **Error fields** (`error`, `errorType`) are only included when `success=false`
+- **Timing precision** is milliseconds with up to 2 decimal places
+- **Output is formatted** with 2-space indentation for readability
+
 ## License
 
 GPL-3.0-or-later

packages/device-profiler/src/cli.test.ts

@@ -1,10 +1,12 @@
 import type { Transport } from '@ya-modbus/driver-types'
 
 import { runProfileScan } from './cli.js'
+import * as jsonFormatterModule from './json-formatter.js'
 import { RegisterType } from './read-tester.js'
 
 jest.mock('chalk')
 jest.mock('cli-table3')
+jest.mock('./json-formatter.js')
 
 describe('runProfileScan', () => {
   let mockConsoleLog: jest.SpyInstance
@@ -121,4 +123,106 @@ describe('runProfileScan', () => {
 
     expect(mockTransport.close).toHaveBeenCalled()
   })
+
+  describe('JSON output format', () => {
+    it('should output JSON when format is json', async () => {
+      const mockFormatJSON = jest.fn().mockReturnValue('{"test": "json"}')
+      ;(jsonFormatterModule.formatJSON as jest.Mock) = mockFormatJSON
+
+      const mockTransport: Transport = {
+        readHoldingRegisters: jest.fn().mockResolvedValue(Buffer.from([0x12, 0x34])),
+        close: jest.fn().mockResolvedValue(undefined),
+      } as unknown as Transport
+
+      await runProfileScan({
+        transport: mockTransport,
+        type: RegisterType.Holding,
+        startAddress: 0,
+        endAddress: 0,
+        format: 'json',
+        port: '/dev/ttyUSB0',
+      })
+
+      expect(mockFormatJSON).toHaveBeenCalled()
+      expect(mockConsoleLog).toHaveBeenCalledWith('{"test": "json"}')
+      expect(mockTransport.close).toHaveBeenCalled()
+    })
+
+    it('should suppress progress output when format is json', async () => {
+      const mockFormatJSON = jest.fn().mockReturnValue('{}')
+      ;(jsonFormatterModule.formatJSON as jest.Mock) = mockFormatJSON
+
+      const mockStdoutWrite = jest.spyOn(process.stdout, 'write').mockImplementation()
+
+      const mockTransport: Transport = {
+        readHoldingRegisters: jest.fn().mockResolvedValue(Buffer.from([0x00, 0x00])),
+        close: jest.fn().mockResolvedValue(undefined),
+      } as unknown as Transport
+
+      await runProfileScan({
+        transport: mockTransport,
+        type: RegisterType.Holding,
+        startAddress: 0,
+        endAddress: 5,
+        format: 'json',
+        port: 'localhost:502',
+      })
+
+      // Progress should not be written to stdout in JSON mode
+      expect(mockStdoutWrite).not.toHaveBeenCalled()
+
+      mockStdoutWrite.mockRestore()
+    })
+
+    it('should output table when format is table (default)', async () => {
+      const mockTransport: Transport = {
+        readHoldingRegisters: jest.fn().mockResolvedValue(Buffer.from([0x00, 0x00])),
+        close: jest.fn().mockResolvedValue(undefined),
+      } as unknown as Transport
+
+      await runProfileScan({
+        transport: mockTransport,
+        type: RegisterType.Holding,
+        startAddress: 0,
+        endAddress: 0,
+        format: 'table',
+        port: '/dev/ttyUSB0',
+      })
+
+      const logOutput = mockConsoleLog.mock.calls.map((call) => call[0]).join('\n')
+      expect(logOutput).toContain('Address')
+      expect(mockTransport.close).toHaveBeenCalled()
+    })
+
+    it('should pass correct metadata to JSON formatter', async () => {
+      const mockFormatJSON = jest.fn().mockReturnValue('{}')
+      ;(jsonFormatterModule.formatJSON as jest.Mock) = mockFormatJSON
+
+      const mockTransport: Transport = {
+        readInputRegisters: jest.fn().mockResolvedValue(Buffer.from([0xab, 0xcd])),
+        close: jest.fn().mockResolvedValue(undefined),
+      } as unknown as Transport
+
+      await runProfileScan({
+        transport: mockTransport,
+        type: RegisterType.Input,
+        startAddress: 100,
+        endAddress: 200,
+        batchSize: 25,
+        format: 'json',
+        port: 'localhost:502',
+      })
+
+      expect(mockFormatJSON).toHaveBeenCalledWith(
+        expect.any(Array),
+        expect.objectContaining({
+          type: RegisterType.Input,
+          startAddress: 100,
+          endAddress: 200,
+          batchSize: 25,
+          port: 'localhost:502',
+        })
+      )
+    })
+  })
 })

packages/device-profiler/src/cli.ts

@@ -5,7 +5,8 @@
 import type { Transport } from '@ya-modbus/driver-types'
 
 import { formatProgress, formatSummary } from './console-formatter.js'
-import { PROGRESS_UPDATE_INTERVAL_MS } from './constants.js'
+import { DEFAULT_BATCH_SIZE, PROGRESS_UPDATE_INTERVAL_MS } from './constants.js'
+import { formatJSON } from './json-formatter.js'
 import { RegisterType } from './read-tester.js'
 import { scanRegisters, type ScanResult } from './register-scanner.js'
 
@@ -23,6 +24,10 @@ export interface ProfileScanOptions {
   endAddress: number
   /** Maximum registers to read in a single batch (default: 10) */
   batchSize?: number
+  /** Output format: table or json (default: table) */
+  format?: 'table' | 'json'
+  /** Connection port (for JSON metadata) */
+  port?: string
 }
 
 /**
@@ -31,12 +36,15 @@ export interface ProfileScanOptions {
  * @param options - Scan configuration
  */
 export async function runProfileScan(options: ProfileScanOptions): Promise<void> {
-  const { transport, type, startAddress, endAddress, batchSize } = options
+  const { transport, type, startAddress, endAddress, batchSize, format = 'table', port } = options
   const results: ScanResult[] = []
+  const isJsonFormat = format === 'json'
 
   try {
-    console.log(`Scanning ${type} registers from ${startAddress} to ${endAddress}...`)
-    console.log()
+    if (!isJsonFormat) {
+      console.log(`Scanning ${type} registers from ${startAddress} to ${endAddress}...`)
+      console.log()
+    }
 
     let lastProgressUpdate = 0
     await scanRegisters({
@@ -46,21 +54,35 @@ export async function runProfileScan(options: ProfileScanOptions): Promise<void>
       endAddress,
       ...(batchSize !== undefined && { batchSize }),
       onProgress: (current, total) => {
-        const now = Date.now()
-        if (now - lastProgressUpdate >= PROGRESS_UPDATE_INTERVAL_MS || current === total) {
-          process.stdout.write(`\r${formatProgress(current, total)}`)
-          lastProgressUpdate = now
+        if (!isJsonFormat) {
+          const now = Date.now()
+          if (now - lastProgressUpdate >= PROGRESS_UPDATE_INTERVAL_MS || current === total) {
+            process.stdout.write(`\r${formatProgress(current, total)}`)
+            lastProgressUpdate = now
+          }
         }
       },
       onResult: (result) => {
         results.push(result)
       },
     })
 
-    console.log('\n')
-    console.log('Scan complete!')
-    console.log()
-    console.log(formatSummary(results))
+    if (isJsonFormat) {
+      console.log(
+        formatJSON(results, {
+          type,
+          startAddress,
+          endAddress,
+          batchSize: batchSize ?? DEFAULT_BATCH_SIZE,
+          port: port ?? '',
+        })
+      )
+    } else {
+      console.log('\n')
+      console.log('Scan complete!')
+      console.log()
+      console.log(formatSummary(results))
+    }
   } finally {
     await transport.close()
   }