jsonata-w 1.0.0

package/README.md

@@ -0,0 +1,61 @@
+# JSONata Workflow (jsonata-w)
+
+The **w** stands for **Workflow**. A command-line utility optimized to assist AI agents in transforming and inspecting JSON files, but equally powerful for manual workflows.
+
+## Commands
+
+### Inspect
+Inspects the structure of a JSON file.
+
+```bash
+jsonata-w inspect <file> [options]
+```
+
+#### Options
+- `-s, --summary`: Show a high-level summary of the JSON structure (paths and keys).
+- `--schema`: Generate and print the JSON schema for the scanned file.
+- `-d, --depth <number>`: Limit the depth of inspection (default: 1).
+- `--jsonpath <query>`: Filter the input JSON using a JSONPath expression before inspecting.
+- `--jsonata <expression>`: Filter the input JSON using a JSONata expression before inspecting.
+
+#### Examples
+**Summary view:**
+```bash
+jsonata-w inspect data.json --summary
+```
+
+**Filter with JSONPath:**
+```bash
+jsonata-w inspect data.json --jsonpath "$.users[*].name"
+```
+
+### Transform
+Transforms a JSON file using a JSONata expression file. The input and output paths are defined directly within the JSONata file using a standard configuration block.
+
+```bash
+jsonata-w transform <file>
+```
+
+#### Configuration Block
+The JSONata file MUST start with a configuration comment block:
+
+```javascript
+/* @config {
+  "input": "./path/to/input.json",
+  "output": "./path/to/output.json",
+  "schema": "./optional/schema.json"
+} */
+
+(
+  /* Your JSONata expression here */
+  $
+)
+```
+
+- `input`: Path to the source JSON file (relative to the .jsonata file).
+- `output`: Path where the transformed JSON will be saved (relative to the .jsonata file).
+- `schema`: (Optional) Path to a JSON schema for validation.
+
+#### Features
+- **Embedded Config**: No need for CLI arguments for input/output.
+- **Auto-Unflattening**: Results containing dot-notation keys (e.g., `{"a.b": 1}`) are automatically expanded into nested objects (`{"a": {"b": 1}}`). This simplifies generating deep hierarchies.

package/dist/cli.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const SourceLoader_1 = require("./core/SourceLoader");
+const StructureInspector_1 = require("./core/StructureInspector");
+const SchemaValidator_1 = require("./core/SchemaValidator");
+const SchemaGenerator_1 = require("./core/SchemaGenerator");
+const JsonataTransformer_1 = require("./core/JsonataTransformer");
+const ConfigParser_1 = require("./core/ConfigParser");
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const jest_diff_1 = require("jest-diff");
+const js_yaml_1 = __importDefault(require("js-yaml"));
+const loader = new SourceLoader_1.SourceLoader();
+const validator = new SchemaValidator_1.SchemaValidator();
+const generator = new SchemaGenerator_1.SchemaGenerator();
+const transformer = new JsonataTransformer_1.JsonataTransformer();
+function unflatten(data) {
+    if (typeof data !== 'object' || data === null)
+        return data;
+    if (Array.isArray(data))
+        return data;
+    const result = {};
+    for (const i in data) {
+        const keys = i.split('.');
+        keys.reduce(function (r, e, j) {
+            return r[e] || (r[e] = (keys[j + 1] === undefined ? data[i] : {}));
+        }, result);
+    }
+    return result;
+}
+/**
+ * Creates a subset of 'data' containing only the keys found in 'template'.
+ * This is used for "subset-only" validation where extra output fields are ignored.
+ */
+function pickSubset(data, template) {
+    if (template === null || typeof template !== 'object')
+        return data;
+    if (data === null || typeof data !== 'object')
+        return data;
+    if (Array.isArray(template)) {
+        if (!Array.isArray(data))
+            return data;
+        // For arrays, we just return the data as is (subset matching in arrays is ambiguous)
+        return data;
+    }
+    const result = {};
+    for (const key in template) {
+        if (key in data) {
+            result[key] = pickSubset(data[key], template[key]);
+        }
+    }
+    return result;
+}
+(0, yargs_1.default)((0, helpers_1.hideBin)(process.argv))
+    .command('inspect <file>', 'Inspect JSON structure', (yargs) => {
+    return yargs
+        .positional('file', { describe: 'JSON file to inspect', type: 'string', demandOption: true })
+        .option('depth', { alias: 'd', type: 'number', default: 1, describe: 'Depth to inspect' })
+        .option('summary', { alias: 's', type: 'boolean', default: false, describe: 'Show structure summary' })
+        .option('schema', { type: 'boolean', default: false, describe: 'Generate JSON schema from file' })
+        .option('jsonata', { type: 'string', describe: 'JSONata expression to narrow down inspection' })
+        .option('jsonpath', { type: 'string', describe: 'JSONPath expression to narrow down inspection' })
+        .conflicts('jsonata', 'jsonpath');
+}, async (argv) => {
+    try {
+        const json = loader.load(argv.file);
+        let targetJson = json;
+        if (argv.jsonata) {
+            const result = await transformer.evaluate(json, argv.jsonata);
+            targetJson = result;
+        }
+        else if (argv.jsonpath) {
+            // Dynamically import jsonpath to avoid top-level issues if possible, 
+            // but standard import is fine given we installed it.
+            const jp = require('jsonpath');
+            const result = jp.query(json, argv.jsonpath);
+            // jp.query returns an array of matches. If we want inspection behavior on the result, likely we want the array.
+            targetJson = result;
+        }
+        if (argv.schema) {
+            const schema = generator.generate(targetJson);
+            console.log(JSON.stringify(schema, null, 2));
+            return;
+        }
+        const inspector = new StructureInspector_1.StructureInspector(targetJson);
+        if (argv.summary) {
+            const summary = inspector.summarize();
+            console.log(summary.join('\n'));
+        }
+        else {
+            console.log(JSON.stringify(inspector.inspect(argv.depth), null, 2));
+        }
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(1);
+    }
+})
+    .command('transform <file>', 'Transform JSON using a single JSONata file with embedded @config', (yargs) => {
+    return yargs
+        .positional('file', { describe: 'JSONata file with embedded @config', type: 'string', demandOption: true });
+}, async (argv) => {
+    try {
+        const filePath = path_1.default.resolve(argv.file);
+        if (!fs_1.default.existsSync(filePath)) {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        const fileContent = fs_1.default.readFileSync(filePath, 'utf-8');
+        const config = ConfigParser_1.ConfigParser.extract(fileContent);
+        const fileDir = path_1.default.dirname(filePath);
+        const resolvePath = (p) => path_1.default.resolve(fileDir, p);
+        const inputPath = resolvePath(config.input);
+        const outputPath = resolvePath(config.output);
+        console.log(`Loading input from ${inputPath}...`);
+        const json = loader.load(inputPath);
+        console.log(`Executing transformation...`);
+        // Use evaluate since we already have the content
+        const result = await transformer.evaluate(json, fileContent);
+        console.log(`Unflattening result...`);
+        const finalResult = unflatten(result);
+        if (config.schema) {
+            const schemaPath = resolvePath(config.schema);
+            console.log(`Validating against schema ${schemaPath}...`);
+            const validation = validator.validate(finalResult, schemaPath);
+            if (!validation.valid) {
+                console.error('Validation Failed:', JSON.stringify(validation.errors, null, 2));
+                process.exit(1);
+            }
+            else {
+                console.log('Validation passed.');
+            }
+        }
+        if (config.examples) {
+            const examplePath = resolvePath(config.examples);
+            console.log(`Validating against example ${examplePath}...`);
+            if (!fs_1.default.existsSync(examplePath)) {
+                throw new Error(`Example file not found: ${examplePath}`);
+            }
+            const exampleContent = fs_1.default.readFileSync(examplePath, 'utf-8');
+            const exampleData = (examplePath.endsWith('.yaml') || examplePath.endsWith('.yml'))
+                ? js_yaml_1.default.load(exampleContent)
+                : JSON.parse(exampleContent);
+            const validationSubset = pickSubset(finalResult, exampleData);
+            const difference = (0, jest_diff_1.diff)(exampleData, validationSubset);
+            if (difference && !difference.includes('Compared values have no visual difference')) {
+                console.error('❌ Example Validation Failed!');
+                const getKeysRecursive = (obj, depth = 0) => {
+                    if (depth > 2 || !obj || typeof obj !== 'object' || Array.isArray(obj))
+                        return [];
+                    const keys = Object.keys(obj);
+                    return keys.map(k => {
+                        const nested = getKeysRecursive(obj[k], depth + 1);
+                        return nested.length > 0 ? `${k} -> [${nested.join(', ')}]` : k;
+                    });
+                };
+                console.error(`\nDiagnostic:`);
+                console.error(`- Expected keys: ${JSON.stringify(getKeysRecursive(exampleData))}`);
+                console.error(`- Actual keys:   ${JSON.stringify(getKeysRecursive(finalResult))}`);
+                console.error('\nTips for resolution:');
+                console.error('- Check for property naming discrepancies or casing (e.g., "button" vs "Button").');
+                console.error('- Ensure all expected keys in your example file are being generated correctly by your JSONata logic.');
+                console.error('- Verify that the value types (arrays, objects, strings) strictly match the example.');
+                console.error('\nAI Optimization Hint:');
+                console.error('The diff below indicates mismatches between the target example (Expected) and your generated output (Received).');
+                console.error('If a property is missing in Received, check your JSONata mapping for that specific node.');
+                console.error('If Received structure is different, adjust your $processNode or nested object builders to match the example nesting.');
+                console.error('\n--- DIFF START ---\n');
+                console.error(difference);
+                console.error('\n--- DIFF END ---\n');
+                process.exit(1);
+            }
+            else {
+                console.log('✅ Example validation passed.');
+            }
+        }
+        const dir = path_1.default.dirname(outputPath);
+        if (!fs_1.default.existsSync(dir))
+            fs_1.default.mkdirSync(dir, { recursive: true });
+        fs_1.default.writeFileSync(outputPath, JSON.stringify(finalResult, null, 2));
+        console.log(`Transformed ${config.input} -> ${config.output}`);
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(1);
+    }
+})
+    .demandCommand(1, 'You need at least one command before moving on')
+    .strict()
+    .help()
+    .alias('h', 'help')
+    .parse();

package/dist/core/ConfigParser.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConfigParser = void 0;
+const comment_parser_1 = require("comment-parser");
+class ConfigParser {
+    static extract(content) {
+        const blocks = (0, comment_parser_1.parse)(content);
+        for (const block of blocks) {
+            const configTag = block.tags.find(tag => tag.tag === 'config');
+            if (configTag) {
+                // Reconstruct the raw content from the source tokens to bypass JSDoc type parsing (which eats braces)
+                const rawContent = configTag.source.map((line, index) => {
+                    const t = line.tokens;
+                    if (index === 0) {
+                        // First line: skip tag
+                        return (t.postTag || '') + (t.name || '') + (t.postName || '') + (t.type || '') + (t.postType || '') + (t.description || '');
+                    }
+                    else {
+                        // Subsequent lines: take everything after delimiter
+                        // Note: postDelimiter is usually the space after *, but we might want it for indentation
+                        return (t.postDelimiter || '') + (t.tag || '') + (t.postTag || '') + (t.name || '') + (t.postName || '') + (t.type || '') + (t.postType || '') + (t.description || '');
+                    }
+                }).join('\n');
+                try {
+                    return JSON.parse(rawContent);
+                }
+                catch (_e) {
+                    throw new Error('Invalid JSON in @config block');
+                }
+            }
+        }
+        throw new Error('No @config block found in JSONata file. usage: /* @config { "input": "...", "output": "..." } */');
+    }
+}
+exports.ConfigParser = ConfigParser;

package/dist/core/JsonataTransformer.js

@@ -0,0 +1,27 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonataTransformer = void 0;
+const jsonata_1 = __importDefault(require("jsonata"));
+const fs_1 = __importDefault(require("fs"));
+class JsonataTransformer {
+    async evaluate(json, expression) {
+        const transformer = (0, jsonata_1.default)(expression);
+        // Register custom bindings if needed (e.g. for logging)
+        transformer.registerFunction('log', (arg) => {
+            console.log(arg);
+            return arg;
+        });
+        return transformer.evaluate(json);
+    }
+    async transform(json, expressionFile) {
+        if (!fs_1.default.existsSync(expressionFile)) {
+            throw new Error(`Expression file not found: ${expressionFile}`);
+        }
+        const expression = fs_1.default.readFileSync(expressionFile, 'utf-8');
+        return this.evaluate(json, expression);
+    }
+}
+exports.JsonataTransformer = JsonataTransformer;

package/dist/core/SchemaGenerator.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaGenerator = void 0;
+const to_json_schema_1 = __importDefault(require("to-json-schema"));
+class SchemaGenerator {
+    generate(json) {
+        return (0, to_json_schema_1.default)(json, {
+            objects: {
+                postProcessFnc: (schema, obj, defaultFnc) => {
+                    return defaultFnc(schema, obj);
+                }
+            },
+            arrays: {
+                mode: 'first' // or 'all' or 'uniform'
+            }
+        });
+    }
+}
+exports.SchemaGenerator = SchemaGenerator;

package/dist/core/SchemaValidator.js

@@ -0,0 +1,36 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchemaValidator = void 0;
+const ajv_1 = __importDefault(require("ajv"));
+const fs_1 = __importDefault(require("fs"));
+class SchemaValidator {
+    constructor() {
+        this.ajv = new ajv_1.default();
+    }
+    validate(data, schemaPath) {
+        if (!fs_1.default.existsSync(schemaPath)) {
+            throw new Error(`Schema file not found: ${schemaPath}`);
+        }
+        const schemaContent = fs_1.default.readFileSync(schemaPath, 'utf-8');
+        let schema;
+        try {
+            schema = JSON.parse(schemaContent);
+        }
+        catch (_e) {
+            throw new Error(`Invalid JSON schema in file: ${schemaPath}`);
+        }
+        const validate = this.ajv.compile(schema);
+        const valid = validate(data);
+        if (!valid) {
+            return {
+                valid: false,
+                errors: validate.errors || []
+            };
+        }
+        return { valid: true };
+    }
+}
+exports.SchemaValidator = SchemaValidator;

package/dist/core/SourceLoader.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SourceLoader = void 0;
+const fs_1 = __importDefault(require("fs"));
+class SourceLoader {
+    constructor() {
+        this.cache = new Map();
+    }
+    load(path) {
+        if (this.cache.has(path)) {
+            return this.cache.get(path);
+        }
+        if (!fs_1.default.existsSync(path)) {
+            throw new Error(`File not found: ${path}`);
+        }
+        const content = fs_1.default.readFileSync(path, 'utf-8');
+        try {
+            const json = JSON.parse(content);
+            this.cache.set(path, json);
+            return json;
+        }
+        catch (_e) {
+            throw new Error(`Invalid JSON in file: ${path}`);
+        }
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+}
+exports.SourceLoader = SourceLoader;

package/dist/core/StructureInspector.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StructureInspector = void 0;
+class StructureInspector {
+    constructor(json) {
+        this.json = json;
+    }
+    inspect(depth = 1) {
+        const summarize = (obj, currentDepth) => {
+            if (currentDepth > depth) {
+                if (Array.isArray(obj))
+                    return `Array[${obj.length}]`;
+                return typeof obj;
+            }
+            if (Array.isArray(obj)) {
+                return obj.map(item => summarize(item, currentDepth + 1));
+            }
+            if (typeof obj === 'object' && obj !== null) {
+                const summary = {};
+                for (const key in obj) {
+                    summary[key] = summarize(obj[key], currentDepth + 1);
+                }
+                return summary;
+            }
+            return obj;
+        };
+        return summarize(this.json, 1);
+    }
+    summarize() {
+        const paths = new Map();
+        const addKeys = (path, keys) => {
+            if (!paths.has(path))
+                paths.set(path, new Set());
+            keys.forEach(k => paths.get(path).add(k));
+        };
+        const traverse = (obj, currentPath) => {
+            if (Array.isArray(obj)) {
+                if (obj.length > 0) {
+                    const limit = Math.min(obj.length, 5);
+                    for (let i = 0; i < limit; i++) {
+                        const item = obj[i];
+                        if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+                            const keys = Object.keys(item);
+                            const itemPath = currentPath + '[*]';
+                            addKeys(itemPath, keys);
+                            keys.forEach(k => traverse(item[k], itemPath === '' ? k : `${itemPath}.${k}`));
+                        }
+                        else if (Array.isArray(item)) {
+                            traverse(item, currentPath + '[*]');
+                        }
+                    }
+                }
+            }
+            else if (typeof obj === 'object' && obj !== null) {
+                const keys = Object.keys(obj);
+                if (currentPath === '') {
+                    addKeys('(root)', keys);
+                }
+                else {
+                    addKeys(currentPath, keys);
+                }
+                keys.forEach(k => traverse(obj[k], currentPath === '' ? k : `${currentPath}.${k}`));
+            }
+        };
+        traverse(this.json, '');
+        const result = [];
+        const sortedPaths = Array.from(paths.keys()).sort();
+        sortedPaths.forEach(path => {
+            const keys = paths.get(path);
+            if (keys && keys.size > 0) {
+                const keyList = Array.from(keys).join(', ');
+                result.push(`${path} = {${keyList}}`);
+            }
+        });
+        return result;
+    }
+}
+exports.StructureInspector = StructureInspector;

package/dist/core/TransformConfig.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./core/SourceLoader"), exports);
+__exportStar(require("./core/StructureInspector"), exports);
+__exportStar(require("./core/SchemaValidator"), exports);
+__exportStar(require("./core/SchemaGenerator"), exports);
+__exportStar(require("./core/JsonataTransformer"), exports);
+__exportStar(require("./core/ConfigParser"), exports);
+__exportStar(require("./core/TransformConfig"), exports);

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "jsonata-w",
+  "version": "1.0.0",
+  "description": "Tool to assist AI in transforming JSON files",
+  "main": "dist/index.js",
+  "bin": {
+    "jsonata-w": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "cli": "node dist/cli.js $*",
+    "test": "jest",
+    "lint": "eslint src test",
+    "lint:fix": "eslint src test --fix",
+    "check": "npm run lint && tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@types/jsonpath": "^0.2.4",
+    "ajv": "^8.17.1",
+    "comment-parser": "^1.4.1",
+    "jest-diff": "^30.2.0",
+    "js-yaml": "^4.1.1",
+    "jsonata": "^2.1.0",
+    "jsonpath": "^1.1.1",
+    "to-json-schema": "^0.2.5",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.19.3",
+    "@types/to-json-schema": "^0.2.4",
+    "@types/yargs": "^17.0.33",
+    "eslint": "^9.39.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.51.0"
+  }
+}