yaml-dsl-spec 0.1.1 → 0.1.3

package/README.md

@@ -9,20 +9,4 @@ if (read.problems) for (const problem of read.problems) console.error(String(pro
 else for (const { definition } of read.dsls) console.log(definition.id);
 ```
 
-| Export | Is |
-|---|---|
-| `readDslDefinitions(file, text)` | `{ dsls }`, each DSL of a `yaml-dsl.yml`, `{ definition, block }`, validated against its version's schema and the checks the schema cannot state; or `{ problems }`, every problem at the field it is about |
-| `Diagnostic`, `Position` | a problem at its place: `message`, `position` and `notes` (`label`, `rule`, `help`) |
-| `yamlReader.parseYaml(file, text, tagKeys)` | `{ node }`, YAML read with each value's place, or `{ problem }` |
-| `Node`, `numberJson` | a YAML value as written, and a number's text as JSON |
-| `dslDefinition.dslDefinitionFromJson(block)` | a DSL block with its defaults, its fields named as the standard names them |
-| `jsonPath` | `PathPattern` and `PathSet`, the standard's JSONPath subset |
-| `resolved` | `Value`, a resolved document's value with its place |
-| `functionTable` | `FunctionTable`, a schema's `x-yaml-dsl-functions` |
-| `schemaValidation` | `SchemaCache` and `LoadedSchema`, a document validated against its schema, each problem at its place |
-| `parseCallKey`, `closestName` | a call written in a key, and the allowed name closest to a misspelt one |
-| `yamlDslSchema(version)`, `yamlDslSchemas` | the JSON Schema of `yaml-dsl.yml`, at a version, or by version |
-| `functionTableSchema(version)`, `functionTableSchemas` | the JSON Schema of a DSL's function table, `x-yaml-dsl-functions`, at a version, or by version |
-| `YAML_DSL_VERSIONS`, `FUNCTION_TABLE_VERSIONS` | the versions the package reads |
-
-A version is a minor, such as `1.0`, or a major, such as `1`, which is its newest minor in the package.
+Its API is the core's, designed in the [package design](https://github.com/litebitus/yaml-dsl-spec/blob/main/docs/package-design.md).

package/index.js

@@ -49,6 +49,7 @@ module.exports = {
   schemaValidation: {
     SchemaCache: schemaValidation.SchemaCache,
     LoadedSchema: schemaValidation.LoadedSchema,
+    ValidationRules: schemaValidation.ValidationRules,
     childValue: schemaValidation.childValue,
   },
 };

package/lib/definition-reader.js

@@ -13,6 +13,7 @@ const { compilePattern, groupNamesOf } = require('./pattern-dialect');
 const { Position } = require('./source-position');
 const { Value } = require('./resolved-value');
 const { SchemaCache, closestName, nodeJsonText } = require('./schema-validation');
+const { ValidationRules } = require('./validation-rules');
 const { parseYaml } = require('./yaml-reader');
 const { YAML_DSL_VERSIONS, yamlDslSchemaFile } = require('./schema-catalog');
 
@@ -37,7 +38,7 @@ function readDslDefinitions(file, text) {
   } catch (error) {
     return { problems: [Diagnostic.unplaced(error.message)] };
   }
-  const schemaProblems = schema.validate(Value.fromNode(root), []);
+  const schemaProblems = schema.validate(Value.fromNode(root), new ValidationRules());
   if (schemaProblems.length > 0) return { problems: schemaProblems };
   const blocks = (root.get('dsls') && root.get('dsls').items()) || [];
   const problems = [];

package/lib/dsl-definition.js

@@ -125,7 +125,9 @@ const DSL_FIELDS = {
   })), emptyList),
   tag_keys: withDefault(listOf(struct({ tag: required(text), key: required(text) })), emptyList),
   validator: optional(struct({
+    merge_base_keys: withDefault(listOf(text), emptyList),
     child_values_from_parent_key: withDefault(listOf(struct({ pattern: required(text) })), emptyList),
+    allow_quoted_values: withDefault(listOf(oneOf(['boolean', 'integer', 'number'])), emptyList),
   })),
 };
 

package/lib/function-table.js

@@ -64,7 +64,7 @@ function compareText(first, second) {
 }
 
 function functionEntry(name, entry) {
-  const listed = isObject(entry) ? entry.arguments : undefined;
+  const listed = Array.isArray(entry) ? entry : 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;
@@ -75,7 +75,9 @@ function functionEntry(name, entry) {
       default: hasOwn(argument, 'default') ? argument.default : null,
     };
   });
-  const macroEntry = hasOwn(entry, 'macro') ? macroEntryOf(name, entry.macro) : null;
+  const macroEntry = isObject(entry) && hasOwn(entry, 'macro')
+    ? macroEntryOf(name, entry.macro)
+    : null;
   return { arguments: functionArguments, macroEntry };
 }
 
@@ -101,6 +103,9 @@ function macroEntryOf(name, value) {
   for (const role of ROLE_NAMES) {
     if (typeof value[role] === 'string') roles[role] = value[role];
   }
+  if (!hasOwn(roles, 'loop_variables') && typeof value.loop_variable === 'string') {
+    roles.loop_variables = value.loop_variable;
+  }
   return new MacroEntry(kind, written || 'shallow', nameSuffix, roles);
 }
 

package/lib/json-path.js

@@ -11,6 +11,23 @@ function indexStep(index) {
   return { index };
 }
 
+/** A `['name']` step's name and the text after the step, or `null`. */
+function quotedName(text) {
+  if (!text.startsWith("['")) return null;
+  const close = text.indexOf("'", 2);
+  if (close <= 2 || text[close + 1] !== ']') return null;
+  return { name: text.slice(2, close), remaining: text.slice(close + 2) };
+}
+
+/** A dotted step's name, which runs to the next `.` or `[`, and the text after it, or `null`. */
+function dottedName(text) {
+  if (text.startsWith('*')) return null;
+  const stepEnd = text.search(/[.[]/);
+  const end = stepEnd === -1 ? text.length : stepEnd;
+  if (end === 0) return null;
+  return { name: text.slice(0, end), remaining: text.slice(end) };
+}
+
 /** A parsed path and the keys its wildcard steps do not select or descend into. */
 class PathPattern {
   constructor(selectors, skipKeys) {
@@ -23,38 +40,37 @@ class PathPattern {
     const invalid = () =>
       Diagnostic.unplaced(`\`${text}\` is not a path of the supported JSONPath subset`);
     if (!text.startsWith('$')) throw invalid();
-    const rest = text.slice(1);
+    let 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;
+    while (rest.length > 0) {
+      let step;
+      if (rest.startsWith('..')) {
+        const after = rest.slice(2);
+        if (after === '*') {
+          step = { selector: { kind: 'descendant_all' }, remaining: '' };
+        } else {
+          const named = quotedName(after) || dottedName(after);
+          if (!named) throw invalid();
+          step = {
+            selector: { kind: 'descendant_name', name: named.name },
+            remaining: named.remaining,
+          };
+        }
+      } else if (rest.startsWith('.*')) {
+        step = { selector: { kind: 'wildcard' }, remaining: rest.slice(2) };
+      } else if (rest.startsWith('.')) {
+        const named = dottedName(rest.slice(1));
+        if (!named) throw invalid();
+        step = { selector: { kind: 'name', name: named.name }, remaining: named.remaining };
+      } else if (rest.startsWith('[*]')) {
+        step = { selector: { kind: 'wildcard' }, remaining: rest.slice(3) };
       } 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;
+        const named = quotedName(rest);
+        if (!named) throw invalid();
+        step = { selector: { kind: 'name', name: named.name }, remaining: named.remaining };
       }
-      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();
+      selectors.push(step.selector);
+      rest = step.remaining;
     }
     return new PathPattern(selectors, [...skipKeys]);
   }

package/lib/problem-wording.js

@@ -0,0 +1,223 @@
+'use strict';
+
+/* How a schema problem is worded: the field it names and the sentence about it. */
+
+const { descriptionText } = require('./requirement-markers');
+
+const DEPENDENCY_KEYWORDS = ['dependencies', 'dependentRequired', 'dependentSchemas'];
+const SCHEMA_MAP_KEYWORDS = [
+  '$defs',
+  'definitions',
+  'dependencies',
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+];
+const DEFINITION_KEYWORDS = ['$defs', 'definitions'];
+const UNSTATED_CONDITION = 'a condition the schema states';
+
+const hasOwn = (object, field) => Object.prototype.hasOwnProperty.call(object, field);
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+function unescapePointer(step) {
+  return step.replaceAll('~1', '/').replaceAll('~0', '~');
+}
+
+function escapePointer(key) {
+  return key.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function schemaNodeAt(root, pointer) {
+  if (pointer === '') return root;
+  let node = root;
+  for (const step of pointer.slice(1).split('/')) {
+    const key = unescapePointer(step);
+    if (node === null || typeof node !== 'object' || !hasOwn(node, key)) return undefined;
+    node = node[key];
+  }
+  return node;
+}
+
+/**
+ * The field a problem names: the key of the value at `pointer` in `document`, then
+ * `[<index>]` for each list index below it; the root is `the document`.
+ */
+function fieldName(document, pointer) {
+  if (pointer === '') return 'the document';
+  const steps = [];
+  let node = document;
+  for (const step of pointer.slice(1).split('/')) {
+    const key = unescapePointer(step);
+    const inList = Array.isArray(node);
+    if (inList) node = node[Number(key)];
+    else node = isObject(node) && hasOwn(node, key) ? node[key] : undefined;
+    steps.push({ key, inList });
+  }
+  let keyAt = steps.length - 1;
+  while (keyAt >= 0 && steps[keyAt].inList) keyAt -= 1;
+  const key = keyAt >= 0 ? steps[keyAt].key : '';
+  const indexes = steps.slice(keyAt + 1).map((step) => `[${step.key}]`).join('');
+  return `\`${key}${indexes}\``;
+}
+
+/** A JSON number as a report writes it. */
+function numberText(number) {
+  return String(number);
+}
+
+/**
+ * The sentence of an alternative none of whose forms holds: the first sentence of
+ * the definition holding the alternatives, where they are a described
+ * definition's, `#/$defs/<name>` or `#/definitions/<name>`; else `null`.
+ */
+function describedForm(schema, holderPointer) {
+  const steps = holderPointer.split('/').slice(1);
+  if (steps.length !== 2 || !DEFINITION_KEYWORDS.includes(steps[0])) return null;
+  const description = descriptionText(schemaNodeAt(schema, holderPointer));
+  if (!description) return null;
+  const sentence = description.split(/(?<=\.)\s/u)[0];
+  const firstSentence = sentence.endsWith('.') ? sentence.slice(0, -1) : sentence;
+  const leadingWord = /^[A-Za-z0-9]*/u.exec(firstSentence)[0];
+  if (leadingWord.length >= 2 && /^[A-Z]+$/u.test(leadingWord)) return firstSentence;
+  const [first, ...rest] = Array.from(firstSentence);
+  return first === undefined ? null : `${first.toLowerCase()}${rest.join('')}`;
+}
+
+/**
+ * The dependency keyword's pointer and the key it names, `{ keywordPointer, key }`,
+ * where `keywordPointer` lies inside a dependency: the key read from the pointer,
+ * or, for a dependency listing fields, from the field `holder` misses; else `null`.
+ */
+function dependencyOf(schema, keywordPointer, holder, missingField) {
+  const steps = keywordPointer.split('/').slice(1).map(unescapePointer);
+  let at = steps.length - 1;
+  while (at >= 0 && !(DEPENDENCY_KEYWORDS.includes(steps[at])
+    && (at === 0 || !SCHEMA_MAP_KEYWORDS.includes(steps[at - 1])))) at -= 1;
+  if (at < 0) return null;
+  const dependencyPointer = steps.slice(0, at + 1)
+    .map((step) => `/${escapePointer(step)}`)
+    .join('');
+  let key = steps[at + 1];
+  if (key === undefined) {
+    const listed = schemaNodeAt(schema, dependencyPointer);
+    if (typeof missingField !== 'string' || !isObject(listed)) return null;
+    key = Object.keys(listed).find((candidate) => isObject(holder) && hasOwn(holder, candidate)
+      && Array.isArray(listed[candidate]) && listed[candidate].includes(missingField));
+    if (key === undefined) return null;
+  }
+  if (!isObject(holder) || !hasOwn(holder, key)) return null;
+  return { keywordPointer: dependencyPointer, key };
+}
+
+/**
+ * `` `key` needs <what> ``: what each dependency of the node holding
+ * `keywordPointer` states for `key`.
+ */
+function dependencyMessage(schema, keywordPointer, key) {
+  const holder = schemaNodeAt(schema, keywordPointer.slice(0, keywordPointer.lastIndexOf('/')));
+  const statesKey = (keyword) => isObject(holder)
+    && isObject(holder[keyword])
+    && hasOwn(holder[keyword], key);
+  const neededTexts = DEPENDENCY_KEYWORDS
+    .filter(statesKey)
+    .map((keyword) => neededText(holder[keyword][key]));
+  return `\`${key}\` needs ${neededTexts.length > 0 ? neededTexts.join('; ') : UNSTATED_CONDITION}`;
+}
+
+function neededText(needed) {
+  if (Array.isArray(needed)) return keyList(needed);
+  return consequenceText(needed) || UNSTATED_CONDITION;
+}
+
+function consequenceText(node) {
+  if (!isObject(node)) return null;
+  const parts = [];
+  if (Array.isArray(node.required) && node.required.length > 0) parts.push(keyList(node.required));
+  if (isObject(node.not) && Array.isArray(node.not.required) && node.not.required.length > 0) {
+    parts.push(`${keyList(node.not.required)} must not be set`);
+  }
+  const properties = isObject(node.properties) ? node.properties : {};
+  for (const [field, fieldSchema] of Object.entries(properties)) {
+    if (isObject(fieldSchema) && typeof fieldSchema.$ref === 'string') {
+      parts.push(`\`${field}\` is a \`${referenceName(fieldSchema.$ref)}\``);
+    }
+  }
+  for (const part of Array.isArray(node.allOf) ? node.allOf : []) {
+    const partText = consequenceText(part);
+    if (partText) parts.push(partText);
+  }
+  const alternatives = ['anyOf', 'oneOf']
+    .flatMap((keyword) => (Array.isArray(node[keyword]) ? node[keyword] : []));
+  if (alternatives.length > 0) {
+    parts.push(alternatives
+      .map((alternative) => consequenceText(alternative) || UNSTATED_CONDITION)
+      .join(', or '));
+  }
+  if (parts.length === 0 && typeof node.$ref === 'string') {
+    parts.push(`a \`${referenceName(node.$ref)}\``);
+  }
+  return parts.length > 0 ? parts.join('; ') : null;
+}
+
+function referenceName(reference) {
+  return reference.slice(reference.lastIndexOf('/') + 1).replace(/^#/u, '');
+}
+
+function keyList(keys) {
+  const spans = keys.map((key) => `\`${typeof key === 'string' ? key : JSON.stringify(key)}\``);
+  return spans.length > 1 ? `${spans.slice(0, -1).join(', ')} and ${spans.at(-1)}` : spans.join('');
+}
+
+/**
+ * The indexes of the duplicate items a list reports, later first, `[later, earlier]`:
+ * from the last item back, the first one equal to an item after it, and the
+ * nearest such item; `null` for a list without duplicates.
+ */
+function duplicateItems(items) {
+  for (let earlier = items.length - 1; earlier >= 0; earlier -= 1) {
+    for (let later = earlier + 1; later < items.length; later += 1) {
+      if (jsonEqual(items[earlier], items[later])) return [later, earlier];
+    }
+  }
+  return null;
+}
+
+function jsonEqual(first, second) {
+  if (Array.isArray(first) && Array.isArray(second)) {
+    return first.length === second.length
+      && first.every((item, index) => jsonEqual(item, second[index]));
+  }
+  if (isObject(first) && isObject(second)) {
+    const keys = Object.keys(first);
+    return keys.length === Object.keys(second).length
+      && keys.every((key) => hasOwn(second, key) && jsonEqual(first[key], second[key]));
+  }
+  return first === second;
+}
+
+/**
+ * `must contain at least <min> valid item(s)`, with `and no more than <max>`
+ * where `holder` bounds it.
+ */
+function containsMessage(holder) {
+  const bound = (keyword) => (isObject(holder) && typeof holder[keyword] === 'number'
+    ? numberText(holder[keyword])
+    : null);
+  const minimum = bound('minContains') || '1';
+  const maximum = bound('maxContains');
+  return maximum === null
+    ? `must contain at least ${minimum} valid item(s)`
+    : `must contain at least ${minimum} and no more than ${maximum} valid item(s)`;
+}
+
+module.exports = {
+  fieldName,
+  numberText,
+  describedForm,
+  dependencyOf,
+  dependencyMessage,
+  duplicateItems,
+  containsMessage,
+  schemaNodeAt,
+  escapePointer,
+};

package/lib/requirement-markers.js

@@ -0,0 +1,128 @@
+'use strict';
+
+/*
+ * Requirement markers: a field's `description` opening with `[required]`,
+ * `[~required]` or `[optional]` decides whether the field is required, over its
+ * parent's `required` array.
+ */
+
+const REQUIRED_MARKER = '[required]';
+const REQUIREMENT_MARKERS = [REQUIRED_MARKER, '[~required]', '[optional]'];
+const CONDITION_KEYWORDS = new Set(['if', 'not']);
+const FORM_SELECTING_KEYWORDS = new Set(['anyOf', 'oneOf']);
+const SAME_INSTANCE_SCHEMA_KEYWORDS = new Set(['else', 'if', 'not', 'then']);
+const SAME_INSTANCE_LIST_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf']);
+const SCHEMA_MAP_KEYWORDS = new Set([
+  '$defs',
+  'definitions',
+  'dependentSchemas',
+  'patternProperties',
+  'properties',
+]);
+const DRAFT_KEYWORDS = {
+  'draft-07': {
+    childSchema: new Set([
+      'additionalItems',
+      'additionalProperties',
+      'contains',
+      'items',
+      'propertyNames',
+    ]),
+    schemaMap: new Set([
+      '$defs',
+      'definitions',
+      'dependencies',
+      'patternProperties',
+      'properties',
+    ]),
+  },
+  'draft 2019-09': {
+    childSchema: new Set([
+      'additionalItems',
+      'additionalProperties',
+      'contains',
+      'contentSchema',
+      'items',
+      'propertyNames',
+      'unevaluatedItems',
+      'unevaluatedProperties',
+    ]),
+    schemaMap: SCHEMA_MAP_KEYWORDS,
+  },
+  'draft 2020-12': {
+    childSchema: new Set([
+      'additionalProperties',
+      'contains',
+      'contentSchema',
+      'items',
+      'prefixItems',
+      'propertyNames',
+      'unevaluatedItems',
+      'unevaluatedProperties',
+    ]),
+    schemaMap: SCHEMA_MAP_KEYWORDS,
+  },
+};
+
+const isObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/** The marker a schema node's `description` opens with, or `null`. */
+function requirementMarker(node) {
+  if (!isObject(node) || typeof node.description !== 'string') return null;
+  const description = node.description.trimStart();
+  return REQUIREMENT_MARKERS.find((marker) => description.startsWith(marker)) || null;
+}
+
+/** A node's description without the marker it opens with, or `null`. */
+function descriptionText(node) {
+  if (!isObject(node) || typeof node.description !== 'string') return null;
+  const marker = requirementMarker(node);
+  const text = marker ? node.description.trimStart().slice(marker.length) : node.description;
+  return text.trim() || null;
+}
+
+/** `schema`, read in the draft named `draftName`, with each `required` array decided by markers. */
+function markedSchema(schema, draftName) {
+  return markedNode(schema, null, DRAFT_KEYWORDS[draftName]);
+}
+
+function markersOfFields(properties) {
+  const markers = new Map();
+  for (const [key, field] of Object.entries(properties)) {
+    const marker = requirementMarker(field);
+    if (marker) markers.set(key, marker);
+  }
+  return markers;
+}
+
+function markedNode(node, inheritedMarkers, keywords) {
+  if (!isObject(node)) return node;
+  const ownMarkers = isObject(node.properties) ? markersOfFields(node.properties) : null;
+  const markers = ownMarkers || inheritedMarkers;
+  const marked = {};
+  const markedChild = (child) => markedNode(child, null, keywords);
+  for (const [keyword, value] of Object.entries(node)) {
+    if (keyword === 'required') continue;
+    if (CONDITION_KEYWORDS.has(keyword)) marked[keyword] = value;
+    else if (SAME_INSTANCE_SCHEMA_KEYWORDS.has(keyword)) {
+      marked[keyword] = markedNode(value, markers, keywords);
+    } else if (SAME_INSTANCE_LIST_KEYWORDS.has(keyword) && Array.isArray(value)) {
+      const branchMarkers = FORM_SELECTING_KEYWORDS.has(keyword) ? null : markers;
+      marked[keyword] = value.map((branch) => markedNode(branch, branchMarkers, keywords));
+    } else if (keywords.childSchema.has(keyword)) {
+      marked[keyword] = Array.isArray(value) ? value.map(markedChild) : markedChild(value);
+    } else if (keywords.schemaMap.has(keyword) && isObject(value)) {
+      marked[keyword] = Object.fromEntries(Object.entries(value)
+        .map(([name, schema]) => [name, markedChild(schema)]));
+    } else {
+      marked[keyword] = value;
+    }
+  }
+  const listed = Array.isArray(node.required) ? node.required : [];
+  const required = listed.filter((key) => !markers || !markers.has(key));
+  for (const [key, marker] of ownMarkers || []) if (marker === REQUIRED_MARKER) required.push(key);
+  if (required.length > 0) marked.required = required;
+  return marked;
+}
+
+module.exports = { requirementMarker, descriptionText, markedSchema };