scjson 0.1.5

package/bin/scjson.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Agent Name: js-cli-runner
+ *
+ * Part of the scjson project.
+ * Developed by Softoboros Technology Inc.
+ * Licensed under the BSD 1-Clause License.
+ */
+
+const { program } = require('../index.js');
+program.parse(process.argv);

package/index.js

@@ -0,0 +1,243 @@
+/**
+ * Agent Name: js-cli
+ *
+ * Part of the scjson project.
+ * Developed by Softoboros Technology Inc.
+ * Licensed under the BSD 1-Clause License.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Command } = require('commander');
+const { XMLParser, XMLBuilder } = require('fast-xml-parser');
+const Ajv = require('ajv');
+
+const program = new Command();
+const schema = require('../scjson.schema.json');
+
+/**
+ * Remove nulls and empty containers from values recursively.
+ *
+ * @param {*} value - Candidate value.
+ * @returns {*} Sanitised value.
+ */
+function removeEmpty(value) {
+  if (Array.isArray(value)) {
+    const arr = value.map(removeEmpty).filter(v => v !== undefined);
+    return arr.length > 0 ? arr : undefined;
+  }
+  if (value && typeof value === 'object') {
+    const obj = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = removeEmpty(v);
+      if (r !== undefined) obj[k] = r;
+    }
+    return Object.keys(obj).length > 0 ? obj : undefined;
+  }
+  if (value === null) {
+    return undefined;
+  }
+  if (value === '') {
+    return undefined;
+  }
+  return value;
+}
+
+const ajv = new Ajv({ useDefaults: true, strict: false });
+const validate = ajv.compile(schema);
+
+/**
+ * Convert an SCXML string to scjson.
+ *
+ * @param {string} xmlStr - XML input.
+ * @param {boolean} [omitEmpty=true] - Remove empty values when true.
+ * @returns {string} JSON representation.
+ *
+ * Removes the XML namespace attribute and injects default values
+ * expected by the schema.
+ */
+function xmlToJson(xmlStr, omitEmpty = true) {
+  const parser = new XMLParser({ ignoreAttributes: false });
+  let obj = parser.parse(xmlStr);
+  if (obj.scxml) {
+    obj = obj.scxml;
+  }
+  if (omitEmpty) {
+    obj = removeEmpty(obj) || {};
+  }
+  if (obj['@_xmlns']) {
+    delete obj['@_xmlns'];
+  }
+  if (obj.version === undefined) {
+    obj.version = 1.0;
+  }
+  if (obj.datamodel_attribute === undefined) {
+    obj.datamodel_attribute = 'null';
+  }
+  if (!validate(obj)) {
+    throw new Error('Invalid scjson');
+  }
+  if (omitEmpty) {
+    obj = removeEmpty(obj) || {};
+  }
+  return JSON.stringify(obj, null, 2);
+}
+
+/**
+ * Convert a scjson string to SCXML.
+ *
+ * @param {string} jsonStr - JSON input.
+ * @returns {string} XML output.
+ */
+function jsonToXml(jsonStr) {
+  const builder = new XMLBuilder({ ignoreAttributes: false, format: true });
+  const obj = JSON.parse(jsonStr);
+  if (!validate(obj)) {
+    throw new Error('Invalid scjson');
+  }
+  return builder.build({ scxml: obj });
+}
+
+program
+  .name('scjson')
+  .description('SCXML <-> scjson converter and validator');
+
+program
+  .command('validate')
+  .description('validate a scjson or SCXML file by round-tripping it')
+  .argument('<file>', 'file path')
+  .option('-r, --recursive', 'recurse into directories')
+  .action((file, options) => {
+    const src = path.resolve(file);
+    let success = true;
+
+    function validateFile(p) {
+      const data = fs.readFileSync(p, 'utf8');
+      try {
+        if (p.endsWith('.scxml')) {
+          const json = xmlToJson(data);
+          jsonToXml(json);
+        } else if (p.endsWith('.scjson')) {
+          const xml = jsonToXml(data);
+          xmlToJson(xml);
+        } else {
+          return;
+        }
+      } catch (e) {
+        console.error(`Validation failed for ${p}: ${e.message}`);
+        success = false;
+      }
+    }
+
+    if (fs.statSync(src).isDirectory()) {
+      const pattern = options.recursive ? '**/*' : '*';
+      const files = require('glob').sync(pattern, { cwd: src, nodir: true });
+      files.forEach(f => validateFile(path.join(src, f)));
+    } else {
+      validateFile(src);
+    }
+
+    if (!success) {
+      process.exitCode = 1;
+    }
+  });
+
+function convertDirectoryJson(inputDir, outputDir, recursive, verify, keepEmpty) {
+  const pattern = recursive ? '**/*.scxml' : '*.scxml';
+  const files = require('glob').sync(pattern, { cwd: inputDir, nodir: true });
+  files.forEach(f => {
+    const src = path.join(inputDir, f);
+    const dest = path.join(outputDir, f.replace(/\.scxml$/, '.scjson'));
+    convertScxmlFile(src, dest, verify, keepEmpty);
+  });
+}
+
+function convertDirectoryXml(inputDir, outputDir, recursive, verify, keepEmpty) {
+  const pattern = recursive ? '**/*.scjson' : '*.scjson';
+  const files = require('glob').sync(pattern, { cwd: inputDir, nodir: true });
+  files.forEach(f => {
+    const src = path.join(inputDir, f);
+    const dest = path.join(outputDir, f.replace(/\.scjson$/, '.scxml'));
+    convertScjsonFile(src, dest, verify, keepEmpty);
+  });
+}
+
+function convertScxmlFile(src, dest, verify, keepEmpty) {
+  const xmlStr = fs.readFileSync(src, 'utf8');
+  try {
+    const jsonStr = xmlToJson(xmlStr, !keepEmpty);
+    if (verify) {
+      jsonToXml(jsonStr);
+    } else {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, jsonStr);
+    }
+    if (verify) console.log(`Verified ${src}`);
+  } catch (e) {
+    console.error(`Failed to convert ${src}: ${e.message}`);
+  }
+}
+
+function convertScjsonFile(src, dest, verify) {
+  const jsonStr = fs.readFileSync(src, 'utf8');
+  try {
+    const xmlStr = jsonToXml(jsonStr);
+    if (verify) {
+      xmlToJson(xmlStr);
+    } else {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, xmlStr);
+    }
+    if (verify) console.log(`Verified ${src}`);
+  } catch (e) {
+    console.error(`Failed to convert ${src}: ${e.message}`);
+  }
+}
+
+program
+  .command('json')
+  .argument('<path>', 'SCXML file or directory')
+  .option('-o, --output <path>', 'output file or directory')
+  .option('-r, --recursive', 'recurse into directories')
+  .option('-v, --verify', 'verify conversion without writing output')
+  .option('--keep-empty', 'keep null or empty items when producing JSON')
+  .action((p, opts) => {
+    const src = path.resolve(p);
+    const out = opts.output ? path.resolve(opts.output) : src;
+
+    if (fs.statSync(src).isDirectory()) {
+      convertDirectoryJson(src, out, opts.recursive, opts.verify, opts.keepEmpty);
+    } else {
+      const dest = opts.output && !opts.output.endsWith('.json') && !opts.output.endsWith('.scjson')
+        ? path.join(out, path.basename(src).replace(/\.scxml$/, '.scjson'))
+        : (opts.output || src.replace(/\.scxml$/, '.scjson'));
+      convertScxmlFile(src, dest, opts.verify, opts.keepEmpty);
+    }
+  });
+
+program
+  .command('xml')
+  .argument('<path>', 'scjson file or directory')
+  .option('-o, --output <path>', 'output file or directory')
+  .option('-r, --recursive', 'recurse into directories')
+  .option('-v, --verify', 'verify conversion without writing output')
+  .option('--keep-empty', 'keep null or empty items when producing JSON')
+  .action((p, opts) => {
+    const src = path.resolve(p);
+    const out = opts.output ? path.resolve(opts.output) : src;
+
+    if (fs.statSync(src).isDirectory()) {
+      convertDirectoryXml(src, out, opts.recursive, opts.verify, opts.keepEmpty);
+    } else {
+      const dest = opts.output && !opts.output.endsWith('.xml') && !opts.output.endsWith('.scxml')
+        ? path.join(out, path.basename(src).replace(/\.scjson$/, '.scxml'))
+        : (opts.output || src.replace(/\.scjson$/, '.scxml'));
+      convertScjsonFile(src, dest, opts.verify, opts.keepEmpty);
+    }
+  });
+
+if (require.main === module) {
+  program.parse(process.argv);
+}
+
+module.exports = { program, xmlToJson, jsonToXml };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "scjson",
+  "version": "0.1.5",
+  "description": "Convert SCXML to/from scjson (JSON-based representation of state machines)",
+  "keywords": [
+    "scjson",
+    "scxml",
+    "state-machine",
+    "conversion",
+    "json",
+    "cli",
+    "xml"
+  ],
+  "homepage": "https://github.com/SoftOboros/scjson/tree/main/js",
+  "bugs": {
+    "url": "https://github.com/SoftOboros/scjson/issues"
+  },
+  "license": "BSD-1-Clause",
+  "author": "Softoboros Technology Inc. <ira@softoboros.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SoftOboros/scjson.git"
+  },
+  "bin": {
+    "scjson": "bin/scjson.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "index.js",
+    "tests/"
+  ],
+  "main": "index.js",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "jest",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "commander": "^14.0.0",
+    "eslint": "^9.31.0",
+    "fast-xml-parser": "^5.2.5"
+  },
+  "devDependencies": {
+    "jest": "^30.0.4"
+  }
+}

package/tests/cli.test.js

@@ -0,0 +1,172 @@
+/**
+ * Agent Name: js-cli-tests
+ *
+ * Part of the scjson project.
+ * Developed by Softoboros Technology Inc.
+ * Licensed under the BSD 1-Clause License.
+ */
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const cliPath = path.resolve(__dirname, '../bin/scjson.js');
+
+function createScxml() {
+  return '<scxml xmlns="http://www.w3.org/2005/07/scxml"/>';
+}
+
+function createScjson() {
+  const json = {
+    version: 1,
+    datamodel_attribute: 'null',
+  };
+  return JSON.stringify(json, null, 2);
+}
+
+describe('scjson CLI', () => {
+  test('shows help', () => {
+    const res = spawnSync('node', [cliPath, '--help'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+    expect(res.stdout).toMatch(/scjson/);
+  });
+
+  test('single json conversion', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    const xmlPath = path.join(dir, 'sample.scxml');
+    fs.writeFileSync(xmlPath, createScxml());
+
+    const res = spawnSync('node', [cliPath, 'json', xmlPath], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    const outPath = path.join(dir, 'sample.scjson');
+    expect(fs.existsSync(outPath)).toBe(true);
+    const data = JSON.parse(fs.readFileSync(outPath, 'utf8'));
+    expect(data.version).toBe(1);
+  });
+
+  test('directory json conversion', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    const srcDir = path.join(dir, 'src');
+    fs.mkdirSync(srcDir);
+    ['a', 'b'].forEach(n => {
+      fs.writeFileSync(path.join(srcDir, `${n}.scxml`), createScxml());
+    });
+
+    const res = spawnSync('node', [cliPath, 'json', srcDir], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    ['a', 'b'].forEach(n => {
+      expect(fs.existsSync(path.join(srcDir, `${n}.scjson`))).toBe(true);
+    });
+  });
+
+  test('single xml conversion', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    const jsonPath = path.join(dir, 'sample.scjson');
+    fs.writeFileSync(jsonPath, createScjson());
+
+    const res = spawnSync('node', [cliPath, 'xml', jsonPath], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    const outPath = path.join(dir, 'sample.scxml');
+    expect(fs.existsSync(outPath)).toBe(true);
+    const data = fs.readFileSync(outPath, 'utf8');
+    expect(data).toMatch(/scxml/);
+  });
+
+  test('directory xml conversion', () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    const srcDir = path.join(dir, 'jsons');
+    fs.mkdirSync(srcDir);
+    ['x', 'y'].forEach(n => {
+      fs.writeFileSync(path.join(srcDir, `${n}.scjson`), createScjson());
+    });
+
+    const res = spawnSync('node', [cliPath, 'xml', srcDir], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    ['x', 'y'].forEach(n => {
+      expect(fs.existsSync(path.join(srcDir, `${n}.scxml`))).toBe(true);
+    });
+  });
+
+  function buildDataset(base) {
+    const d1 = path.join(base, 'level1');
+    const d2 = path.join(d1, 'level2');
+    fs.mkdirSync(d2, { recursive: true });
+    ['a', 'b'].forEach(n => {
+      fs.writeFileSync(path.join(d1, `${n}.scxml`), createScxml());
+      fs.writeFileSync(path.join(d2, `${n}.scxml`), createScxml());
+    });
+  }
+
+  test('recursive conversion', () => {
+    const dataset = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    buildDataset(dataset);
+    const scjsonDir = path.join(dataset, 'outjson');
+    const scxmlDir = path.join(dataset, 'outxml');
+
+    let res = spawnSync('node', [cliPath, 'json', dataset, '-o', scjsonDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+    res = spawnSync('node', [cliPath, 'xml', scjsonDir, '-o', scxmlDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    const jsonFiles = require('glob').sync('**/*.scjson', { cwd: scjsonDir, nodir: true });
+    const xmlFiles = require('glob').sync('**/*.scxml', { cwd: scxmlDir, nodir: true });
+
+    expect(jsonFiles.length).toBeGreaterThan(0);
+    expect(xmlFiles.length).toBeGreaterThan(0);
+    expect(xmlFiles.length).toBeLessThanOrEqual(jsonFiles.length);
+  });
+
+  test('recursive validation', () => {
+    const dataset = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    buildDataset(dataset);
+    const scjsonDir = path.join(dataset, 'outjson');
+    const scxmlDir = path.join(dataset, 'outxml');
+
+    let res = spawnSync('node', [cliPath, 'json', dataset, '-o', scjsonDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+    res = spawnSync('node', [cliPath, 'xml', scjsonDir, '-o', scxmlDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    // Corrupt one file to trigger failure
+    fs.writeFileSync(path.join(scjsonDir, 'corrupt.scjson'), 'bad');
+
+    const validateRes = spawnSync('node', [cliPath, 'validate', dataset, '-r'], { encoding: 'utf8' });
+    expect(validateRes.stderr).toMatch(/Validation failed/);
+    expect(validateRes.status).not.toBe(0);
+  });
+
+  test('recursive verify', () => {
+    const dataset = fs.mkdtempSync(path.join(os.tmpdir(), 'scjson-'));
+    buildDataset(dataset);
+    const scjsonDir = path.join(dataset, 'outjson');
+    const scxmlDir = path.join(dataset, 'outxml');
+
+    let res = spawnSync('node', [cliPath, 'json', dataset, '-o', scjsonDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+    res = spawnSync('node', [cliPath, 'xml', scjsonDir, '-o', scxmlDir, '-r'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+
+    res = spawnSync('node', [cliPath, 'json', scxmlDir, '-r', '-v'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+    res = spawnSync('node', [cliPath, 'xml', scjsonDir, '-r', '-v'], { encoding: 'utf8' });
+    expect(res.stderr).not.toMatch(/Failed to convert/);
+    expect(res.status).toBe(0);
+  });
+});