yaml-dsl-spec 0.0.1 → 0.1.0

package/lib/function-table.js

@@ -0,0 +1,129 @@
+'use strict';
+
+const FUNCTION_TABLE_POINTER = '/x-yaml-dsl-functions';
+const FUNCTION_TABLE_FIELD = 'x-yaml-dsl-functions';
+const MACRO_KINDS = new Set(['function_call', 'merge', 'loop', 'transform']);
+const MERGE_BEHAVIORS = new Set(['shallow', 'deep', 'join']);
+const ROLE_NAMES = ['callee', 'callee_arguments', 'content', 'loop_variables', 'collection', 'body'];
+const FUNCTION_NAME_START = /^[A-Za-z_]/;
+const FUNCTION_NAME_CHARACTERS = /^[A-Za-z0-9_:-]*$/;
+
+const hasOwn = (object, field) => Object.prototype.hasOwnProperty.call(object, field);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** A macro of the table: its `kind`, `mergeBehavior`, `nameSuffix` and its arguments by role. */
+class MacroEntry {
+  constructor(kind, mergeBehavior, nameSuffix, roles) {
+    this.kind = kind;
+    this.mergeBehavior = mergeBehavior;
+    this.nameSuffix = nameSuffix;
+    this.roles = roles;
+  }
+
+  /** The name of the entry's argument that plays `role`. */
+  role(role) {
+    return hasOwn(this.roles, role) ? this.roles[role] : null;
+  }
+}
+
+/** The functions and macros a schema publishes at `#/x-yaml-dsl-functions`. */
+class FunctionTable {
+  constructor(entries = new Map()) {
+    this.entries = entries;
+  }
+
+  /** The table `schema` publishes, or throws a message naming what is wrong with it. */
+  static fromSchema(schema) {
+    if (!isObject(schema) || !hasOwn(schema, FUNCTION_TABLE_FIELD)) return new FunctionTable();
+    const table = schema[FUNCTION_TABLE_FIELD];
+    if (!isObject(table)) {
+      throw new Error(`${FUNCTION_TABLE_POINTER} is not a mapping of function names`);
+    }
+    const entries = new Map(Object.entries(table)
+      .sort(([first], [second]) => compareText(first, second))
+      .map(([name, entry]) => [name, functionEntry(name, entry)]));
+    return new FunctionTable(entries);
+  }
+
+  /** The entry a call's function name calls, a suffixed macro name included. */
+  entry(functionName) {
+    const direct = this.entries.get(functionName);
+    if (direct && (!direct.macroEntry || !direct.macroEntry.nameSuffix)) return direct;
+    for (const [name, entry] of this.entries) {
+      const suffixPattern = entry.macroEntry && entry.macroEntry.nameSuffix;
+      if (!suffixPattern || !functionName.startsWith(name)) continue;
+      if (suffixPattern.test(functionName.slice(name.length))) return entry;
+    }
+    return null;
+  }
+}
+
+/** Orders names by their UTF-8 bytes, as a sorted map of the crate holds them. */
+function compareText(first, second) {
+  return Buffer.compare(Buffer.from(first, 'utf8'), Buffer.from(second, 'utf8'));
+}
+
+function functionEntry(name, entry) {
+  const listed = isObject(entry) ? entry.arguments : undefined;
+  if (!Array.isArray(listed)) throw new Error(`function \`${name}\` has no arguments list`);
+  const functionArguments = listed.map((argument) => {
+    const argumentName = isObject(argument) ? argument.name : undefined;
+    if (typeof argumentName !== 'string') throw new Error(`an argument of \`${name}\` has no name`);
+    return {
+      name: argumentName,
+      repeated: typeof argument.repeated === 'boolean' ? argument.repeated : false,
+      default: hasOwn(argument, 'default') ? argument.default : null,
+    };
+  });
+  const macroEntry = hasOwn(entry, 'macro') ? macroEntryOf(name, entry.macro) : null;
+  return { arguments: functionArguments, macroEntry };
+}
+
+function macroEntryOf(name, value) {
+  const kind = isObject(value) ? value.kind : undefined;
+  if (!MACRO_KINDS.has(kind)) {
+    const shown = typeof kind === 'string' ? `Some(${JSON.stringify(kind)})` : 'None';
+    throw new Error(`macro \`${name}\` has an unknown kind ${shown}`);
+  }
+  const written = typeof value.merge_behavior === 'string' ? value.merge_behavior : null;
+  if (written !== null && !MERGE_BEHAVIORS.has(written)) {
+    throw new Error(`macro \`${name}\` has an unknown merge_behavior \`${written}\``);
+  }
+  let nameSuffix = null;
+  if (typeof value.name_suffix_pattern === 'string') {
+    try {
+      nameSuffix = new RegExp(`^(?:${value.name_suffix_pattern})$`, 'u');
+    } catch (error) {
+      throw new Error(`macro \`${name}\`: ${error.message}`);
+    }
+  }
+  const roles = {};
+  for (const role of ROLE_NAMES) {
+    if (typeof value[role] === 'string') roles[role] = value[role];
+  }
+  return new MacroEntry(kind, written || 'shallow', nameSuffix, roles);
+}
+
+/**
+ * A call written in a key, `<name> <marker><function>[splat]` or the marker alone,
+ * as `{ name, function, splat }`; `null` for a key that writes none.
+ */
+function parseCallKey(key, marker) {
+  const trimmed = key.trimEnd();
+  const space = trimmed.lastIndexOf(' ');
+  const callStart = space === -1 ? 0 : space + 1;
+  const callText = trimmed.slice(callStart);
+  if (!callText.startsWith(marker.call_marker)) return null;
+  const rest = callText.slice(marker.call_marker.length);
+  const splatOperator = marker.splat_operator;
+  const splat = typeof splatOperator === 'string' && rest.endsWith(splatOperator);
+  const functionName = splat ? rest.slice(0, rest.length - splatOperator.length) : rest;
+  if (!FUNCTION_NAME_START.test(functionName) || !FUNCTION_NAME_CHARACTERS.test(functionName)) return null;
+  return {
+    name: callStart > 0 ? trimmed.slice(0, callStart).trim() : null,
+    function: functionName,
+    splat,
+  };
+}
+
+module.exports = { FUNCTION_TABLE_POINTER, FunctionTable, MacroEntry, parseCallKey };

package/lib/json-path.js

@@ -0,0 +1,149 @@
+'use strict';
+
+const { Diagnostic } = require('./diagnostic-report');
+
+/** One step of a concrete path into a document: `{ key }` or `{ index }`. */
+function keyStep(key) {
+  return { key };
+}
+
+function indexStep(index) {
+  return { index };
+}
+
+/** A parsed path and the keys its wildcard steps do not select or descend into. */
+class PathPattern {
+  constructor(selectors, skipKeys) {
+    this.selectors = selectors;
+    this.skipKeys = skipKeys;
+  }
+
+  /** The pattern `text` writes, or throws a `Diagnostic` naming why it is none. */
+  static parse(text, skipKeys = []) {
+    const invalid = () =>
+      Diagnostic.unplaced(`\`${text}\` is not a path of the supported JSONPath subset`);
+    if (!text.startsWith('$')) throw invalid();
+    const rest = text.slice(1);
+    const selectors = [];
+    let index = 0;
+    while (index < rest.length) {
+      const descendant = rest.startsWith('..', index);
+      if (descendant) index += 2;
+      else if (rest[index] === '.') index += 1;
+      let name;
+      let consumed;
+      if (rest.startsWith("['", index)) {
+        const close = rest.indexOf("']", index + 2);
+        if (close === -1) throw invalid();
+        name = rest.slice(index + 2, close);
+        consumed = close - index + 2;
+      } else if (rest.startsWith('[*]', index)) {
+        name = null;
+        consumed = 3;
+      } else if (rest.startsWith('*', index)) {
+        name = null;
+        consumed = 1;
+      } else {
+        const ends = [rest.indexOf('.', index), rest.indexOf('[', index)].filter((end) => end !== -1);
+        const end = ends.length > 0 ? Math.min(...ends) : rest.length;
+        if (end === index) throw invalid();
+        name = rest.slice(index, end);
+        consumed = end - index;
+      }
+      index += consumed;
+      if (!descendant) selectors.push(name === null ? { kind: 'wildcard' } : { kind: 'name', name });
+      else if (name !== null) selectors.push({ kind: 'descendant_name', name });
+      else if (index === rest.length) selectors.push({ kind: 'descendant_all' });
+      else throw invalid();
+    }
+    return new PathPattern(selectors, [...skipKeys]);
+  }
+
+  /** Every node of `document` the pattern selects, `{ path, value }`, in document order. */
+  select(document) {
+    const selected = [];
+    this.collect(document, [], selected);
+    return selected;
+  }
+
+  collect(value, path, selected) {
+    if (this.selects(path)) selected.push({ path: [...path], value });
+    if (value.kind === 'map') {
+      for (const entry of value.value) {
+        path.push(keyStep(entry.key));
+        this.collect(entry.value, path, selected);
+        path.pop();
+      }
+    } else if (value.kind === 'list') {
+      value.value.forEach((item, itemIndex) => {
+        path.push(indexStep(itemIndex));
+        this.collect(item, path, selected);
+        path.pop();
+      });
+    }
+  }
+
+  /** Whether the pattern selects the node at `path`. */
+  selects(path) {
+    return this.matchesFrom(0, path);
+  }
+
+  /** Whether `path` is the node a step selects or anywhere below it. */
+  covers(path) {
+    for (let length = 0; length <= path.length; length += 1) {
+      if (this.selects(path.slice(0, length))) return true;
+    }
+    return false;
+  }
+
+  skipped(step) {
+    return 'key' in step && this.skipKeys.includes(step.key);
+  }
+
+  matchesFrom(selectorIndex, path) {
+    const selector = this.selectors[selectorIndex];
+    if (!selector) return path.length === 0;
+    const [first] = path;
+    switch (selector.kind) {
+      case 'name':
+        return first !== undefined && first.key === selector.name
+          && this.matchesFrom(selectorIndex + 1, path.slice(1));
+      case 'wildcard':
+        return first !== undefined && !this.skipped(first)
+          && this.matchesFrom(selectorIndex + 1, path.slice(1));
+      case 'descendant_name':
+        for (let depth = 0; depth < path.length; depth += 1) {
+          if (path.slice(0, depth).every((step) => !this.skipped(step))
+            && path[depth].key === selector.name
+            && this.matchesFrom(selectorIndex + 1, path.slice(depth + 1))) {
+            return true;
+          }
+        }
+        return false;
+      default:
+        return path.length > 0 && path.every((step) => !this.skipped(step));
+    }
+  }
+}
+
+/** Several path entries; a node is selected when any of them selects it. */
+class PathSet {
+  constructor(patterns = []) {
+    this.patterns = patterns;
+  }
+
+  /** The set of `entries`, each `{ path, skipKeys }`, or throws the first path's `Diagnostic`. */
+  static parse(entries) {
+    return new PathSet(entries.map(({ path, skipKeys }) => PathPattern.parse(path, skipKeys || [])));
+  }
+
+  selects(path) {
+    return this.patterns.some((pattern) => pattern.selects(path));
+  }
+
+  covers(path) {
+    return this.patterns.some((pattern) => pattern.covers(path));
+  }
+}
+
+module.exports = { PathPattern, PathSet, keyStep, indexStep };

package/lib/pattern-dialect.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/** The regular expression a `yaml-dsl.yml` pattern writes, or `null` where it writes none. */
+function compilePattern(text) {
+  try {
+    return new RegExp(text, 'u');
+  } catch {
+    return null;
+  }
+}
+
+/** The named groups of a compiled pattern, in the order the pattern writes them. */
+function groupNamesOf(pattern) {
+  const anyText = new RegExp(`${pattern.source}|`, 'u');
+  return Object.keys(anyText.exec('').groups || {});
+}
+
+module.exports = { compilePattern, groupNamesOf };

package/lib/resolved-value.js

@@ -0,0 +1,85 @@
+'use strict';
+
+const { scalarTextOf } = require('./yaml-node');
+
+/**
+ * A value of the folded, expanded document, with where it was written. `kind` is
+ * a node's kind, or `reference`, `call` or `template`; `value` is what a node of
+ * that kind holds, a list of values and of map entries `{ key, keyPosition, value }`
+ * included, or the reference, the call, or the template's parts.
+ */
+class Value {
+  constructor(kind, value, position) {
+    this.kind = kind;
+    this.value = value;
+    this.position = position;
+  }
+
+  static string(text, position) {
+    return new Value('string', text, position);
+  }
+
+  /** A node as written, each value with its position: nothing resolved. */
+  static fromNode(node) {
+    let value;
+    if (node.kind === 'list') value = node.value.map((item) => Value.fromNode(item));
+    else if (node.kind === 'map') {
+      value = node.value.map((entry) => ({
+        key: entry.key,
+        keyPosition: entry.keyPosition,
+        value: Value.fromNode(entry.value),
+      }));
+    } else value = node.value;
+    return new Value(node.kind, value, node.position);
+  }
+
+  entries() {
+    return this.kind === 'map' ? this.value : null;
+  }
+
+  items() {
+    return this.kind === 'list' ? this.value : null;
+  }
+
+  get(key) {
+    const found = (this.entries() || []).find((entry) => entry.key === key);
+    return found ? found.value : null;
+  }
+
+  asStr() {
+    return this.kind === 'string' ? this.value : null;
+  }
+
+  /** A scalar's text, for splicing into a longer string. */
+  scalarText() {
+    if (this.kind === 'reference' && this.value.target.kind === 'local') {
+      return this.value.target.value.scalarText();
+    }
+    return scalarTextOf(this.kind, this.value);
+  }
+
+  /** The value with every local reference replaced by the local's value. */
+  localValue() {
+    if (this.kind === 'reference' && this.value.target.kind === 'local') {
+      return this.value.target.value.localValue();
+    }
+    return this;
+  }
+}
+
+/**
+ * A name read by one of the definition's reference rules: `{ scope, scopeKey,
+ * name, path, text, target }`. A target is `{ kind: 'local', value }`, or a
+ * `kind` of `local_unknown`, `builtin`, `declaration` with its `position`, or
+ * `undeclared`.
+ */
+function reference(fields) {
+  return { scopeKey: null, ...fields };
+}
+
+/** A call left for the target to evaluate: `{ function, arguments, expandFinalArgument }`. */
+function call(functionName, callArguments) {
+  return { function: functionName, arguments: callArguments, expandFinalArgument: false };
+}
+
+module.exports = { Value, reference, call };

package/lib/schema-catalog.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { packagedVersionFiles } = require('../schema-versions');
+
+/** Each schema family the package carries, by its file stem. */
+const FAMILIES = {
+  yamlDslSchemas: 'yaml-dsl',
+  functionTableSchemas: 'x-yaml-dsl-functions',
+};
+
+/** A family's schema files by version: a minor such as `1.0`, or a major such as `1`, its newest minor. */
+function filesOf(family) {
+  return packagedVersionFiles(family).map(([version, file]) => ({
+    version,
+    file: path.basename(file),
+    text: fs.readFileSync(file, 'utf8'),
+  }));
+}
+
+const YAML_DSL_FILES = filesOf(FAMILIES.yamlDslSchemas);
+const FUNCTION_TABLE_FILES = filesOf(FAMILIES.functionTableSchemas);
+
+/** The versions the package reads, each major before its minors. */
+const YAML_DSL_VERSIONS = YAML_DSL_FILES.map(({ version }) => version);
+const FUNCTION_TABLE_VERSIONS = FUNCTION_TABLE_FILES.map(({ version }) => version);
+
+function schemasByVersion(files) {
+  return Object.fromEntries(files.map(({ version, text }) => [version, JSON.parse(text)]));
+}
+
+const yamlDslSchemas = schemasByVersion(YAML_DSL_FILES);
+const functionTableSchemas = schemasByVersion(FUNCTION_TABLE_FILES);
+for (const schemas of [yamlDslSchemas, functionTableSchemas]) {
+  const byFile = new Map();
+  for (const [version, schema] of Object.entries(schemas)) {
+    const key = JSON.stringify(schema);
+    if (byFile.has(key)) schemas[version] = byFile.get(key);
+    else byFile.set(key, schema);
+  }
+}
+
+/** The JSON Schema of `yaml-dsl.yml` at `version`, or `null`. */
+function yamlDslSchema(version) {
+  return Object.prototype.hasOwnProperty.call(yamlDslSchemas, version) ? yamlDslSchemas[version] : null;
+}
+
+/** The JSON Schema of a DSL's function table, a document schema's `x-yaml-dsl-functions`, at `version`, or `null`. */
+function functionTableSchema(version) {
+  return Object.prototype.hasOwnProperty.call(functionTableSchemas, version) ? functionTableSchemas[version] : null;
+}
+
+/** The file name and text of the `yaml-dsl.yml` schema at `version`, or `null`. */
+function yamlDslSchemaFile(version) {
+  const found = YAML_DSL_FILES.find((entry) => entry.version === version);
+  return found ? { file: found.file, text: found.text } : null;
+}
+
+module.exports = {
+  FAMILIES,
+  YAML_DSL_VERSIONS,
+  FUNCTION_TABLE_VERSIONS,
+  yamlDslSchemas,
+  functionTableSchemas,
+  yamlDslSchema,
+  functionTableSchema,
+  yamlDslSchemaFile,
+};