@swaggerexpert/arazzo-criterion 1.0.0

package/es/index.mjs

@@ -0,0 +1,11 @@
+export { default as Grammar } from "./grammar.mjs";
+export { default as parse } from "./parse/index.mjs";
+export { default as test } from "./test/index.mjs";
+export { default as evaluate } from "./evaluate/index.mjs";
+export { default as CSTTranslator } from "./parse/translators/CSTTranslator.mjs";
+export { default as ASTTranslator } from "./parse/translators/ASTTranslator/index.mjs";
+export { default as XMLTranslator } from "./parse/translators/XMLTranslator.mjs";
+export { default as Trace } from "./parse/trace/Trace.mjs";
+export { default as ArazzoCriterionError } from "./errors/ArazzoCriterionError.mjs";
+export { default as ArazzoCriterionParseError } from "./errors/ArazzoCriterionParseError.mjs";
+export { default as ArazzoCriterionEvaluateError } from "./errors/ArazzoCriterionEvaluateError.mjs";

package/es/parse/callbacks/cst.mjs

@@ -0,0 +1,24 @@
+import { utilities, identifiers } from 'apg-lite';
+const cst = nodeType => {
+  return (state, chars, phraseIndex, phraseLength, data) => {
+    if (state === identifiers.SEM_PRE) {
+      const node = {
+        type: nodeType,
+        text: utilities.charsToString(chars, phraseIndex, phraseLength),
+        start: phraseIndex,
+        length: phraseLength,
+        children: []
+      };
+      if (data.stack.length > 0) {
+        data.stack[data.stack.length - 1].children.push(node);
+      } else {
+        data.root = node;
+      }
+      data.stack.push(node);
+    }
+    if (state === identifiers.SEM_POST) {
+      data.stack.pop();
+    }
+  };
+};
+export default cst;

package/es/parse/index.mjs

@@ -0,0 +1,35 @@
+import { Parser, Stats } from 'apg-lite';
+import Grammar from "../grammar.mjs";
+import ASTTranslator from "./translators/ASTTranslator/index.mjs";
+import Trace from "./trace/Trace.mjs";
+import ArazzoCriterionParseError from "../errors/ArazzoCriterionParseError.mjs";
+const grammar = new Grammar();
+const parse = (condition, {
+  startRule = 'condition',
+  stats = false,
+  trace = false,
+  translator = new ASTTranslator()
+} = {}) => {
+  if (typeof condition !== 'string') {
+    throw new TypeError('Criterion condition must be a string');
+  }
+  try {
+    const parser = new Parser();
+    if (translator) parser.ast = translator;
+    if (stats) parser.stats = new Stats();
+    if (trace) parser.trace = new Trace();
+    const result = parser.parse(grammar, startRule, condition);
+    return {
+      result,
+      tree: result.success && translator ? parser.ast.getTree() : undefined,
+      stats: parser.stats,
+      trace: parser.trace
+    };
+  } catch (error) {
+    throw new ArazzoCriterionParseError('Unexpected error during Arazzo Criterion parsing', {
+      cause: error,
+      condition
+    });
+  }
+};
+export default parse;

package/es/parse/trace/Expectations.mjs

@@ -0,0 +1,6 @@
+class Expectations extends Array {
+  toString() {
+    return this.map(c => `"${String(c)}"`).join(', ');
+  }
+}
+export default Expectations;

package/es/parse/trace/Trace.mjs

@@ -0,0 +1,30 @@
+import { Trace as BaseTrace } from 'apg-lite';
+import Expectations from "./Expectations.mjs";
+class Trace extends BaseTrace {
+  inferExpectations() {
+    const lines = this.displayTrace().split('\n');
+    const expectations = new Set();
+    let lastMatchedIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+
+      // capture the max match line (first one that ends in a single character match)
+      if (line.includes('M|')) {
+        const textMatch = line.match(/]'(.*)'$/);
+        if (textMatch && textMatch[1]) {
+          lastMatchedIndex = i;
+        }
+      }
+
+      // collect terminal failures after the deepest successful match
+      if (i > lastMatchedIndex) {
+        const terminalFailMatch = line.match(/N\|\[TLS\(([^)]+)\)]/);
+        if (terminalFailMatch) {
+          expectations.add(terminalFailMatch[1]);
+        }
+      }
+    }
+    return new Expectations(...expectations);
+  }
+}
+export default Trace;

package/es/parse/translators/ASTTranslator/index.mjs

@@ -0,0 +1,9 @@
+import CSTTranslator from "../CSTTranslator.mjs";
+import transformers, { transformCSTtoAST } from "./transformers.mjs";
+class ASTTranslator extends CSTTranslator {
+  getTree() {
+    const cst = super.getTree();
+    return transformCSTtoAST(cst, transformers);
+  }
+}
+export default ASTTranslator;

package/es/parse/translators/ASTTranslator/transformers.mjs

@@ -0,0 +1,195 @@
+import { parse as parseRuntimeExpression } from '@swaggerexpert/arazzo-runtime-expression';
+import parse from "../../index.mjs";
+export const transformCSTtoAST = (node, transformerMap) => {
+  const transformer = transformerMap[node.type];
+  if (!transformer) {
+    throw new Error(`No transformer for CST node type: ${node.type}`);
+  }
+  return transformer(node);
+};
+
+// A basic-expr is not a registered CST rule, so its alternatives
+// (paren-expr / comparison-expr / test-expr) and the literal alternatives
+// (number / string / boolean / null) surface directly as children.
+const OPERAND_TYPES = new Set(['paren-expr', 'comparison-expr', 'test-expr', 'runtime-expression-operand', 'number', 'string', 'boolean', 'null']);
+
+/**
+ * Split an operand token at the boundary between its runtime-expression base and the
+ * trailing criterion navigation, returning both as text. The base is the longest
+ * leading substring that parses as a runtime expression.
+ *
+ * The grammar cannot find this boundary itself - a runtime expression and the
+ * criterion accessors both use "." - so it is resolved here by delegating to
+ * @swaggerexpert/arazzo-runtime-expression.
+ */
+const splitAtRuntimeExpression = operand => {
+  const full = parseRuntimeExpression(operand);
+  if (full.result.success) {
+    return {
+      expressionText: operand,
+      navigationText: ''
+    };
+  }
+
+  // A failing parse reports how far it matched; walk down from there to the
+  // longest prefix that parses cleanly (robust against stopping mid-rule).
+  for (let n = full.result.maxMatched; n > 0; n -= 1) {
+    if (parseRuntimeExpression(operand.slice(0, n)).result.success) {
+      return {
+        expressionText: operand.slice(0, n),
+        navigationText: operand.slice(n)
+      };
+    }
+  }
+  throw new Error(`Operand is not a valid runtime expression: "${operand}"`);
+};
+
+/**
+ * Parse a criterion navigation remainder (e.g. ".data[0].id") into a MemberAccess /
+ * IndexAccess path by parsing it against the grammar's `runtime-expression-navigation`
+ * rule (a secondary entry point); the ASTTranslator produces the path array directly.
+ * Throws if the remainder is not a valid accessor sequence.
+ */
+const parseNavigation = navigationText => {
+  const {
+    result,
+    tree
+  } = parse(navigationText, {
+    startRule: 'runtime-expression-navigation'
+  });
+  if (!result.success) {
+    throw new Error(`Invalid criterion navigation: "${navigationText}"`);
+  }
+  return tree;
+};
+
+/**
+ * Parse an operand token into its runtime-expression base and criterion navigation,
+ * both already parsed. `navigation` is an empty array when there are no accessors.
+ */
+const parseOperand = operand => {
+  const {
+    expressionText,
+    navigationText
+  } = splitAtRuntimeExpression(operand);
+  const runtimeExpression = {
+    type: 'RuntimeExpression',
+    text: expressionText,
+    expression: parseRuntimeExpression(expressionText).tree
+  };
+  const navigation = navigationText === '' ? [] : parseNavigation(navigationText);
+  return {
+    runtimeExpression,
+    navigation
+  };
+};
+const foldLeftAssociative = (operands, operator) => operands.reduce((left, right) => ({
+  type: 'LogicalExpression',
+  operator,
+  left,
+  right
+}));
+const transformers = {
+  ['condition'](node) {
+    const child = node.children.find(c => c.type === 'logical-or-expr');
+    return transformCSTtoAST(child, transformers);
+  },
+  ['logical-or-expr'](node) {
+    const operands = node.children.filter(c => c.type === 'logical-and-expr').map(c => transformCSTtoAST(c, transformers));
+    return operands.length === 1 ? operands[0] : foldLeftAssociative(operands, '||');
+  },
+  ['logical-and-expr'](node) {
+    const operands = node.children.filter(c => OPERAND_TYPES.has(c.type)).map(c => transformCSTtoAST(c, transformers));
+    return operands.length === 1 ? operands[0] : foldLeftAssociative(operands, '&&');
+  },
+  ['paren-expr'](node) {
+    const inner = node.children.find(c => c.type === 'logical-or-expr');
+    const argument = transformCSTtoAST(inner, transformers);
+    const negated = node.children.some(c => c.type === 'logical-not-op');
+    return negated ? {
+      type: 'UnaryExpression',
+      operator: '!',
+      argument
+    } : argument;
+  },
+  ['test-expr'](node) {
+    const operandNode = node.children.find(c => OPERAND_TYPES.has(c.type));
+    const argument = transformCSTtoAST(operandNode, transformers);
+    const negated = node.children.some(c => c.type === 'logical-not-op');
+    return negated ? {
+      type: 'UnaryExpression',
+      operator: '!',
+      argument
+    } : argument;
+  },
+  ['comparison-expr'](node) {
+    const operands = node.children.filter(c => OPERAND_TYPES.has(c.type));
+    const opNode = node.children.find(c => c.type === 'comparison-op');
+    return {
+      type: 'BinaryExpression',
+      operator: opNode.text,
+      left: transformCSTtoAST(operands[0], transformers),
+      right: transformCSTtoAST(operands[1], transformers)
+    };
+  },
+  ['runtime-expression-operand'](node) {
+    const {
+      runtimeExpression,
+      navigation
+    } = parseOperand(node.text);
+    if (navigation.length === 0) return runtimeExpression;
+    return {
+      type: 'RuntimeExpressionNavigation',
+      expression: runtimeExpression,
+      navigation
+    };
+  },
+  ['runtime-expression-navigation'](node) {
+    return node.children.filter(c => c.type === 'member-access' || c.type === 'index-access').map(c => transformCSTtoAST(c, transformers));
+  },
+  ['member-access'](node) {
+    const nameNode = node.children.find(c => c.type === 'member-name');
+    return {
+      type: 'MemberAccess',
+      name: nameNode.text
+    };
+  },
+  ['index-access'](node) {
+    const indexNode = node.children.find(c => c.type === 'index');
+    return {
+      type: 'IndexAccess',
+      value: Number(indexNode.text)
+    };
+  },
+  ['number'](node) {
+    return {
+      type: 'Literal',
+      valueType: 'number',
+      value: Number(node.text)
+    };
+  },
+  ['string'](node) {
+    // strip surrounding single quotes, then collapse doubled '' into a single '
+    const inner = node.text.slice(1, -1).replace(/''/g, "'");
+    return {
+      type: 'Literal',
+      valueType: 'string',
+      value: inner
+    };
+  },
+  ['boolean'](node) {
+    return {
+      type: 'Literal',
+      valueType: 'boolean',
+      value: node.text === 'true'
+    };
+  },
+  ['null'](node) {
+    return {
+      type: 'Literal',
+      valueType: 'null',
+      value: null
+    };
+  }
+};
+export default transformers;

package/es/parse/translators/CSTTranslator.mjs

@@ -0,0 +1,42 @@
+import { Ast as AST } from 'apg-lite';
+import cstCallback from "../callbacks/cst.mjs";
+class CSTTranslator extends AST {
+  constructor() {
+    super();
+
+    // logical / comparison spine
+    this.callbacks['condition'] = cstCallback('condition');
+    this.callbacks['logical-or-expr'] = cstCallback('logical-or-expr');
+    this.callbacks['logical-and-expr'] = cstCallback('logical-and-expr');
+    this.callbacks['paren-expr'] = cstCallback('paren-expr');
+    this.callbacks['comparison-expr'] = cstCallback('comparison-expr');
+    this.callbacks['test-expr'] = cstCallback('test-expr');
+    this.callbacks['logical-not-op'] = cstCallback('logical-not-op');
+    this.callbacks['comparison-op'] = cstCallback('comparison-op');
+
+    // comparable operand (runtime expression + navigation), captured as one token
+    this.callbacks['runtime-expression-operand'] = cstCallback('runtime-expression-operand');
+
+    // navigation (secondary entry point; parses the accessor remainder of an operand)
+    this.callbacks['runtime-expression-navigation'] = cstCallback('runtime-expression-navigation');
+    this.callbacks['member-access'] = cstCallback('member-access');
+    this.callbacks['index-access'] = cstCallback('index-access');
+    this.callbacks['member-name'] = cstCallback('member-name');
+    this.callbacks['index'] = cstCallback('index');
+
+    // literals
+    this.callbacks['number'] = cstCallback('number');
+    this.callbacks['string'] = cstCallback('string');
+    this.callbacks['boolean'] = cstCallback('boolean');
+    this.callbacks['null'] = cstCallback('null');
+  }
+  getTree() {
+    const data = {
+      stack: [],
+      root: null
+    };
+    this.translate(data);
+    return data.root;
+  }
+}
+export default CSTTranslator;

package/es/parse/translators/XMLTranslator.mjs

@@ -0,0 +1,7 @@
+import CSTTranslator from "./CSTTranslator.mjs";
+class XMLTranslator extends CSTTranslator {
+  getTree() {
+    return this.toXml();
+  }
+}
+export default XMLTranslator;

package/es/test/index.mjs

@@ -0,0 +1,13 @@
+import parse from "../parse/index.mjs";
+const test = condition => {
+  if (typeof condition !== 'string') return false;
+  try {
+    const {
+      result
+    } = parse(condition);
+    return result.success;
+  } catch {
+    return false;
+  }
+};
+export default test;

package/package.json

@@ -0,0 +1,95 @@
+{
+  "name": "@swaggerexpert/arazzo-criterion",
+  "publishConfig": {
+    "access": "public"
+  },
+  "version": "1.0.0",
+  "description": "Arazzo Criterion Object (simple type) parser, validator and evaluator.",
+  "main": "./cjs/index.cjs",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./es/index.mjs",
+      "require": "./cjs/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "watch": {
+    "test": "{src,test}/*.js"
+  },
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "grammar:compile": "node ./scripts/apg-js.js --lite --in=./src/grammar.bnf --out=./src/grammar.js",
+    "build": "npm run grammar:compile && npm run build:es && npm run build:cjs && npm run build:cjs:apg-lite",
+    "build:es": "cross-env BABEL_ENV=es babel src --out-dir es --extensions '.js' --out-file-extension '.mjs'",
+    "build:cjs": "cross-env BABEL_ENV=cjs babel src --out-dir cjs --extensions '.js' --out-file-extension '.cjs'",
+    "build:cjs:apg-lite": "cross-env BABEL_ENV=cjs babel node_modules/apg-lite/lib/parser.js --out-file ./cjs/apg-lite.cjs",
+    "test": "cross-env UPDATE_SNAPSHOT=new mocha",
+    "test:watch": "npm-watch test",
+    "watch": "npm-watch"
+  },
+  "engines": {
+    "node": ">=16.14.0"
+  },
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swaggerexpert/arazzo-criterion.git"
+  },
+  "keywords": [
+    "arazzo",
+    "criterion",
+    "simple",
+    "condition",
+    "parser",
+    "validator",
+    "evaluator"
+  ],
+  "author": "Vladimír Gorej <vladimir.gorej@gmail.com>",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/swaggerexpert/arazzo-criterion/issues"
+  },
+  "homepage": "https://github.com/swaggerexpert/arazzo-criterion#readme",
+  "files": [
+    "es/",
+    "cjs/",
+    "types/",
+    "LICENSE",
+    "NOTICE",
+    "package.json",
+    "README.md",
+    "SECURITY.md"
+  ],
+  "dependencies": {
+    "@swaggerexpert/arazzo-runtime-expression": "^3.1.0",
+    "apg-lite": "^1.0.5"
+  },
+  "devDependencies": {
+    "@babel/cli": "=8.0.1",
+    "@babel/core": "=8.0.1",
+    "@babel/preset-env": "=8.0.2",
+    "@commitlint/cli": "=20.5.3",
+    "@commitlint/config-conventional": "=20.5.3",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@semantic-release/release-notes-generator": "^14.1.0",
+    "apg-js": "^4.4.0",
+    "babel-plugin-module-resolver": "^5.0.2",
+    "chai": "=6.2.2",
+    "cross-env": "^10.0.0",
+    "husky": "=9.1.7",
+    "mocha": "=11.7.6",
+    "mocha-expect-snapshot": "^8.0.0",
+    "npm-watch": "^0.13.0",
+    "prettier": "^3.1.1",
+    "semantic-release": "^25.0.2"
+  },
+  "overrides": {
+    "jest-snapshot": "^30.4.1",
+    "@babel/core": "$@babel/core"
+  }
+}