@xano/xanoscript-language-server 12.17.0 → 12.19.0

package/parser/policy/policyDocs.js

@@ -0,0 +1,76 @@
+/**
+ * Markdown for a check and for one of its params, rendered from the catalogue entry as served.
+ * Nothing is written here that the catalogue does not say.
+ */
+
+const code = (value) => "`" + (value === "" ? '""' : value) + "`";
+
+/** The value set a param (or its list items) is closed to, if any. */
+export function paramValues(spec) {
+  return spec?.values ?? spec?.items?.values ?? null;
+}
+
+/** One line under a check: `name` (type, required). */
+function paramLine(name, spec) {
+  const flags = [spec?.type ?? "string"];
+  if (spec?.required) flags.push("required");
+  return `- ${code(name)} (${flags.join(", ")})`;
+}
+
+/**
+ * @param {Object} check a catalogue item
+ * @param {{scopeFields?: Set<string>}} [catalogue] leaves the shared scope fields out of the list
+ */
+export function checkMarkdown(check, catalogue) {
+  const lines = [`**${check.label || check.id}**`, "", code(check.id)];
+  if (check.description) lines.push("", check.description);
+  const facts = [];
+  if (check.category) facts.push(`Category: ${check.category}`);
+  if (check.object_kinds?.length) {
+    facts.push(`Inspects: ${check.object_kinds.join(", ")}`);
+  }
+  if (facts.length) lines.push("", facts.join(" · "));
+
+  const scope = catalogue?.scopeFields ?? new Set();
+  const own = Object.entries(check.params ?? {}).filter(([name]) => !scope.has(name));
+  if (own.length) {
+    lines.push("", "Params:", ...own.map(([name, spec]) => paramLine(name, spec)));
+  }
+  if (check.requires_one_of?.length) {
+    lines.push("", `Set at least one of ${check.requires_one_of.map(code).join(", ")}.`);
+  }
+  const applicable = (check.scope_fields ?? []).map((field) => field.name);
+  if (applicable.length) {
+    lines.push("", `Scope fields: ${applicable.map(code).join(", ")}.`);
+  }
+  if (check.fix_hint) lines.push("", `Fix: ${check.fix_hint}`);
+  return lines.join("\n");
+}
+
+/**
+ * @param {string} checkId
+ * @param {string} path the param name, or `name.field` for a field of an object param
+ * @param {Object} spec its catalogue schema
+ */
+export function paramMarkdown(checkId, path, spec) {
+  const flags = [spec?.type ?? "string"];
+  if (spec?.required) flags.push("required");
+  const lines = [`**${path}** (${flags.join(", ")}) · ${code(checkId)}`];
+  if (spec?.description) lines.push("", spec.description);
+  const values = paramValues(spec);
+  if (values?.length) lines.push("", `One of: ${values.map(code).join(", ")}.`);
+  if (spec?.properties) {
+    lines.push("", `Fields: ${Object.keys(spec.properties).map(code).join(", ")}.`);
+  }
+  if (spec?.requires_one_of?.length) {
+    lines.push("", `Set at least one of ${spec.requires_one_of.map(code).join(", ")}.`);
+  }
+  if (spec?.minimum !== undefined) lines.push("", `At least ${spec.minimum}.`);
+  if (spec && "default" in spec) {
+    lines.push("", `Default: ${code(JSON.stringify(spec.default))}`);
+  }
+  if (spec && "example" in spec) {
+    lines.push("", `Example: ${code(JSON.stringify(spec.example))}`);
+  }
+  return lines.join("\n");
+}

package/parser/policy/policyLiteral.js

@@ -0,0 +1,227 @@
+import { tokenMatcher } from "chevrotain";
+import {
+  ColonToken,
+  CommaToken,
+  LCurly,
+  LSquare,
+  Minus,
+  RCurly,
+  RSquare,
+} from "../../lexer/control.js";
+import {
+  FloatLiteral,
+  IntegerLiteral,
+  SingleQuotedStringLiteral,
+  StringLiteral,
+} from "../../lexer/literal.js";
+import { MultiLineStringToken } from "../../lexer/multiline.js";
+import {
+  DotToken,
+  FalseToken,
+  Identifier,
+  NewlineToken,
+  NullToken,
+  TrueToken,
+} from "../../lexer/tokens.js";
+
+/**
+ * A rule's `params` as values, each with the token it was written at, so a problem the catalogue
+ * finds can be pointed at in the source.
+ *
+ * The parser has already accepted the tokens as a constant (the schema machinery's
+ * `[constant]`); this only reads them back. Anything that is not a plain literal (a variable, a
+ * filter, an expression) comes back as `{kind: "expression"}`: the platform refuses those with
+ * "Policy parameters must be literal values."
+ *
+ * @typedef {{kind: "object", token: Object, entries: {key: string, keyToken: Object, value: PolicyValue}[]}
+ *   | {kind: "array", token: Object, items: PolicyValue[]}
+ *   | {kind: "string"|"number"|"boolean"|"null", token: Object, value: any}
+ *   | {kind: "expression", token: Object}} PolicyValue
+ */
+
+/** Whether a token is of a type (or one of its categories). */
+export const isA = (token, type) => !!token && tokenMatcher(token, type);
+
+/** A catalogue entry's own property, never an inherited one (`constructor`, `toString`). */
+export const own = (object, key) => object && Object.hasOwn(object, key) ? object[key] : undefined;
+
+/** Native Parser::stripQuotes: double quotes use C escapes, single quotes only \\ and \'. */
+export function policyStringValue(image) {
+  if (image.startsWith('"""') || image.startsWith("'''")) {
+    return image.slice(3, -3).replace(/^\r?\n/, "").replace(/\r?\n[ ]*$/, "");
+  }
+  if (image.startsWith('"')) {
+    const bytes = [];
+    const encoder = new TextEncoder();
+    const controls = { a: 7, b: 8, f: 12, n: 10, r: 13, t: 9, v: 11 };
+    for (const match of image.slice(1, -1).matchAll(/\\([0-7]{1,3}|x[\da-fA-F]{1,2}|[\s\S])|([^\\]+)/g)) {
+      const escape = match[1];
+      if (escape && /^[0-7]/.test(escape)) bytes.push(parseInt(escape, 8) & 255);
+      else if (escape && /^x[\da-fA-F]/.test(escape)) bytes.push(parseInt(escape.slice(1), 16));
+      else if (escape && Object.hasOwn(controls, escape)) bytes.push(controls[escape]);
+      else for (const byte of encoder.encode(escape ?? match[2])) bytes.push(byte);
+    }
+    return new TextDecoder().decode(new Uint8Array(bytes));
+  }
+  return image.slice(1, -1).replace(/\\([\\'])/g, "$1");
+}
+
+const unquote = (token) => policyStringValue(token.image);
+
+const isString = (token) =>
+  isA(token, StringLiteral) ||
+  isA(token, SingleQuotedStringLiteral) ||
+  isA(token, MultiLineStringToken);
+
+const isNumber = (token) =>
+  isA(token, IntegerLiteral) || isA(token, FloatLiteral);
+
+/** A token that ends a value inside an object or array, or the value itself. */
+const isBoundary = (token) =>
+  !token ||
+  isA(token, CommaToken) ||
+  isA(token, NewlineToken) ||
+  isA(token, RCurly) ||
+  isA(token, RSquare);
+
+/**
+ * Read one value from `tokens[from..to]` (inclusive).
+ * @param {Object[]} tokens
+ * @param {number} from
+ * @param {number} to
+ * @returns {PolicyValue|null}
+ */
+export function readPolicyLiteral(tokens, from, to) {
+  let i = from;
+  const peek = (ahead = 0) => (i + ahead <= to ? tokens[i + ahead] : null);
+
+  const skipLayout = () => {
+    while (isA(peek(), NewlineToken) || isA(peek(), CommaToken)) i++;
+  };
+
+  /** Skip the rest of a non-literal value, up to the separator that ends it. */
+  const expression = (token) => {
+    let depth = 0;
+    while (peek()) {
+      const t = peek();
+      if (isA(t, LCurly) || isA(t, LSquare)) depth++;
+      else if (isA(t, RCurly) || isA(t, RSquare)) {
+        if (depth === 0) break;
+        depth--;
+      } else if (depth === 0 && (isA(t, CommaToken) || isA(t, NewlineToken)))
+        break;
+      i++;
+    }
+    return { kind: "expression", token };
+  };
+
+  /** A scalar is literal only when nothing (a filter, an operator) follows it. */
+  const scalar = (node) => (isBoundary(peek()) ? node : expression(node.token));
+
+  const value = () => {
+    const token = peek();
+    if (!token) return null;
+
+    if (isA(token, LCurly)) {
+      i++;
+      const entries = [];
+      for (;;) {
+        skipLayout();
+        const keyToken = peek();
+        if (!keyToken) break;
+        if (isA(keyToken, RCurly)) {
+          i++;
+          break;
+        }
+        let key;
+        if (isString(keyToken)) {
+          key = unquote(keyToken);
+          i++;
+        } else if (isA(keyToken, Identifier)) {
+          key = keyToken.image;
+          i++;
+          while (isA(peek(), DotToken) && isA(peek(1), Identifier)) {
+            key += "." + peek(1).image;
+            i += 2;
+          }
+        } else {
+          return expression(token);
+        }
+        if (isA(peek(), ColonToken)) i++;
+        entries.push({ key, keyToken, value: value() });
+      }
+      return scalar({ kind: "object", token, entries });
+    }
+
+    if (isA(token, LSquare)) {
+      i++;
+      const items = [];
+      for (;;) {
+        skipLayout();
+        const next = peek();
+        if (!next) break;
+        if (isA(next, RSquare)) {
+          i++;
+          break;
+        }
+        const before = i;
+        items.push(value());
+        if (i === before) i++; // never loop on a token nothing can read
+      }
+      return scalar({ kind: "array", token, items });
+    }
+
+    if (isString(token)) {
+      i++;
+      return scalar({ kind: "string", token, value: unquote(token) });
+    }
+    if (isA(token, Minus) && isNumber(peek(1))) {
+      const number = peek(1);
+      i += 2;
+      return scalar({ kind: "number", token, value: -Number(number.image) });
+    }
+    if (isNumber(token)) {
+      i++;
+      return scalar({ kind: "number", token, value: Number(token.image) });
+    }
+    if (isA(token, TrueToken) || isA(token, FalseToken)) {
+      i++;
+      return scalar({
+        kind: "boolean",
+        token,
+        value: isA(token, TrueToken),
+      });
+    }
+    if (isA(token, NullToken)) {
+      i++;
+      return scalar({ kind: "null", token, value: null });
+    }
+    return expression(token);
+  };
+
+  return value();
+}
+
+/**
+ * The plain JavaScript value of a node (objects and arrays included), or undefined for an
+ * expression.
+ * @param {PolicyValue|null} node
+ */
+export function policyLiteralValue(node) {
+  if (!node) return undefined;
+  switch (node.kind) {
+    case "object": {
+      const out = Object.create(null);
+      for (const entry of node.entries) {
+        out[entry.key] = policyLiteralValue(entry.value);
+      }
+      return out;
+    }
+    case "array":
+      return node.items.map(policyLiteralValue);
+    case "expression":
+      return undefined;
+    default:
+      return node.value;
+  }
+}

package/parser/policy/validatePolicyRule.js

@@ -0,0 +1,323 @@
+import { policyLiteralValue } from "./policyLiteral.js";
+
+/**
+ * One rule's check id and params against the check catalogue.
+ *
+ * Everything here is read from the catalogue the host loaded (see `catalogue.js`): the check
+ * ids, each check's params with their types, closed value sets, nested fields, `required`,
+ * `requires_one_of`, `minimum` and `non_empty`, and the scope fields that apply to it. Nothing
+ * names a check. The findings are worded like the platform's refusals (`Registry::validateParams`,
+ * `coerce`, `unknownCheck`) without their `rule[i] ("KEY.Rn"): params:` prefix, since a diagnostic
+ * already points at the place; they are a preview, and the platform's own answer on save decides.
+ * Where the platform stops at the first refusal, this reports every problem, one per param.
+ *
+ * Two bounds are the platform's own constants, not the catalogue's: a string or string[] param
+ * holds at most `STRING_MAX_LENGTH` characters, and a name longer than `NEAREST_MAX_LENGTH` bytes
+ * gets no near miss.
+ *
+ * Check-specific rules the catalogue does not publish (`Check::validate`, `authoredRefusal`,
+ * renamed ids and params, statement wildcards) are left to the platform.
+ *
+ * Whether a value is a literal at all, and duplicate names, are the block's shape, not the
+ * catalogue's: the parser reports those (policy_parser.js) and this skips such values.
+ */
+
+/** `Registry::STRING_MAX_LENGTH`: the longest string a string or string[] param may hold, in characters. */
+const STRING_MAX_LENGTH = 1024;
+
+/** `Registry::NEAREST_MAX_LENGTH`: the longest name, in bytes, a near miss is looked for. */
+const NEAREST_MAX_LENGTH = 128;
+
+/** Edit distance, as PHP's `levenshtein` (insert, delete and replace all cost 1). */
+function levenshtein(a, b) {
+  if (a === b) return 0;
+  if (!a.length) return b.length;
+  if (!b.length) return a.length;
+  let previous = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(
+        previous[j] + 1,
+        current[j - 1] + 1,
+        previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+    previous = current;
+  }
+  return previous[b.length];
+}
+
+/**
+ * The closest names to a misspelling, nearest first, at most two (`Registry::nearest`): within
+ * three edits, or one containing the other. A name longer than `NEAREST_MAX_LENGTH` bytes gets
+ * none, since edit distance costs the product of the two lengths per candidate.
+ * @param {string} wanted
+ * @param {string[]} candidates
+ * @returns {string[]}
+ */
+export function nearestNames(wanted, candidates) {
+  wanted = String(wanted).trim();
+  if (wanted === "" || new TextEncoder().encode(wanted).length > NEAREST_MAX_LENGTH) return [];
+  wanted = wanted.toLowerCase();
+  const scored = [];
+  for (const candidate of candidates) {
+    const lower = candidate.toLowerCase();
+    const distance = levenshtein(lower, wanted);
+    if (distance > 3 && !lower.includes(wanted) && !wanted.includes(lower)) {
+      continue;
+    }
+    scored.push([candidate, distance]);
+  }
+  scored.sort((a, b) => a[1] - b[1] || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  return scored.slice(0, 2).map(([name]) => name);
+}
+
+/** "Did you mean …? " naming the nearest candidates to a misspelling, or "" when none is near. */
+export function didYouMean(name, candidates) {
+  const near = nearestNames(name, candidates);
+  return near.length ? `Did you mean ${near.map((n) => `"${n}"`).join(" or ")}? ` : "";
+}
+
+/** `Registry::provided`: set when not null/false, not an empty or blank string, not an empty list or object. */
+function provided(value) {
+  if (value === null || value === undefined || value === false) return false;
+  if (typeof value === "string") return value.trim() !== "";
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === "object") return Object.keys(value).length > 0;
+  return true;
+}
+
+/**
+ * A param's value as the platform validates it (`Registry::validateParams`): one left out, or written
+ * as `null` when its type is not `any`, is its default.
+ */
+const inForce = (literal, schema, name) =>
+  Object.hasOwn(literal, name) && (literal[name] !== null || schema[name]?.type === "any")
+    ? literal[name]
+    : schema[name]?.default;
+
+const isEmptyList = (node) =>
+  (node.kind === "array" && node.items.length === 0) ||
+  (node.kind === "object" && node.entries.length === 0);
+
+/** The sentence for a check id that is not in the catalogue. */
+export function unknownCheckMessage(id, ids) {
+  return `"${id}" is not a policy check. ${didYouMean(id, ids)}`.trim();
+}
+
+/**
+ * `Registry::coerce`: whether a value has its param's declared type and values.
+ * @returns {{token: Object, message: string}|null}
+ */
+function coerce(node, spec, checkId, name) {
+  const type = String(spec?.type ?? "string");
+  const fail = (what, token = node.token) => ({
+    token,
+    message: `param "${name}" of check "${checkId}" must ${what}.`,
+  });
+
+  switch (type) {
+    case "integer": {
+      const whole = node.kind === "number" && Number.isFinite(node.value) && Math.floor(node.value) === node.value;
+      const minimum = spec.minimum;
+      if (!whole || (minimum !== undefined && node.value < minimum)) {
+        return fail(`be a whole number${minimum !== undefined ? ` of at least ${minimum}` : ""}`);
+      }
+      return null;
+    }
+    case "number":
+      return node.kind === "number" && Number.isFinite(node.value) ? null : fail("be a finite number");
+    case "object":
+      // PHP reads an empty list and an empty object alike, so `[]` passes as an object.
+      return node.kind === "object" || isEmptyList(node) ? null : fail("be an object");
+    case "array":
+      return node.kind === "array" || isEmptyList(node) ? null : fail("be an array");
+    case "any":
+      return null;
+    case "string[]": {
+      if (!(node.kind === "array" || isEmptyList(node))) {
+        return fail("be a list of strings");
+      }
+      const values = spec.items?.values ?? spec.values ?? [];
+      for (const item of node.items ?? []) {
+        if (!item || item.kind !== "string") {
+          return fail("be a list of strings", item?.token);
+        }
+        if (values.length && !values.includes(item.value)) {
+          return fail(`contain only: ${values.join(", ")}`, item.token);
+        }
+        if (item.value.trim() === "") {
+          return fail("not contain empty strings", item.token);
+        }
+        if ([...item.value].length > STRING_MAX_LENGTH) {
+          return fail(`list strings of at most ${STRING_MAX_LENGTH} characters`, item.token);
+        }
+      }
+      return null;
+    }
+    case "bool":
+      return node.kind === "boolean" ? null : fail("be a boolean");
+    default: {
+      if (node.kind !== "string") return fail("be a string");
+      if ([...node.value].length > STRING_MAX_LENGTH) {
+        return fail(`be at most ${STRING_MAX_LENGTH} characters`);
+      }
+      const values = spec?.values ?? [];
+      if (values.length && !values.includes(node.value)) {
+        const named = values.filter((value) => String(value) !== "");
+        return fail(`be one of: ${named.join(", ")}${named.length !== values.length ? " (or omit it)" : ""}`);
+      }
+      return null;
+    }
+  }
+}
+
+/** An object param's declared fields, or null when it has none or its keys are the author's own (`<placeholder>`). */
+function closedProperties(spec) {
+  const properties = spec?.properties;
+  if (spec?.type !== "object" || !properties || typeof properties !== "object") return null;
+  const keys = Object.keys(properties);
+  if (keys.length === 0 || keys.some((key) => key.startsWith("<"))) return null;
+  return properties;
+}
+
+/**
+ * Why a set scope field cannot change what a rule of this check selects, or null when it can,
+ * read from the check's published `scope_fields` (the same reading as Studio's rule form).
+ */
+function inapplicableScope(check, name, literal) {
+  const field = (check.scope_fields ?? []).find((item) => item?.name === name);
+  if (!field) {
+    return `"${name}" does not apply to check "${check.id}", so it cannot change what this rule selects.`;
+  }
+  for (const [param, condition] of Object.entries(field.applies_when ?? {})) {
+    const value = inForce(literal, check.params ?? {}, param);
+    if (condition === "non_empty") {
+      if (!provided(value)) {
+        return `"${name}" applies to check "${check.id}" only when ${param} is set.`;
+      }
+    } else if (Array.isArray(condition) && !condition.includes(String(value ?? ""))) {
+      return `"${name}" applies to check "${check.id}" only when ${param} is ${condition.join(" or ")}.`;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {{checkId: string|null, checkToken: Object|null, paramsToken: Object|null,
+ *   params: import('./policyLiteral.js').PolicyValue|null, ruleToken: Object}} rule
+ * @param {ReturnType<import('./catalogue.js').getPolicyCatalogue>} catalogue
+ * @returns {{token: Object, message: string, advisory?: boolean}[]} the problems, one per param;
+ *   `advisory` marks a finding that mirrors platform logic beyond the published schema (a scope
+ *   field's applicability, an object param's "one of" fields), which a host shows as a warning
+ */
+export function validatePolicyRule(rule, catalogue) {
+  const out = [];
+  const report = (token, message) => out.push({ token, message });
+  const advise = (token, message) => out.push({ token, message, advisory: true });
+
+  if (!catalogue?.checks?.size || rule.checkId === null) return out;
+
+  const check = catalogue.checks.get(rule.checkId);
+  if (!check) {
+    report(rule.checkToken ?? rule.ruleToken, unknownCheckMessage(rule.checkId, catalogue.ids));
+    return out;
+  }
+
+  const id = check.id;
+  const schema = check.params ?? {};
+  const anchor = rule.paramsToken ?? rule.checkToken ?? rule.ruleToken;
+  const params = rule.params?.kind === "null" || (rule.params?.kind === "array" && !rule.params.items.length)
+    ? null : rule.params;
+
+  // Not an object (the parser has said so): nothing to hold against the check.
+  if (params && params.kind !== "object") return out;
+
+  // Unknown names, in the order they are written; a repeated name counts once.
+  const given = new Map();
+  for (const entry of params?.entries ?? []) {
+    if (given.has(entry.key)) continue;
+    given.set(entry.key, entry);
+    if (!Object.hasOwn(schema, entry.key)) {
+      const names = Object.keys(schema);
+      report(
+        entry.keyToken,
+        `unknown param "${entry.key}" for check "${id}". ${didYouMean(entry.key, names)}Accepted params: ${names.join(", ") || "none"}.`
+      );
+    }
+  }
+
+  const literal = policyLiteralValue(params) ?? {};
+
+  for (const [name, spec] of Object.entries(schema)) {
+    const entry = given.get(name);
+    const node = entry?.value;
+    const has = !!node && node.kind !== "expression" && (node.kind !== "null" || spec.type === "any");
+    if (!has) {
+      if (spec.required && (!node || node.kind === "null")) {
+        report(anchor, `check "${id}" requires param "${name}".`);
+      }
+      continue;
+    }
+
+    const problem = coerce(node, spec, id, name);
+    if (problem) {
+      report(problem.token, problem.message);
+      continue;
+    }
+
+    if ((spec.required || spec.non_empty) && ((node.kind === "string" && node.value.trim() === "") || isEmptyList(node))) {
+      report(node.token, `check "${id}": ${name} must not be empty.`);
+      continue;
+    }
+
+    const properties = closedProperties(spec);
+    if (properties && node.kind === "object" && node.entries.length) {
+      const seen = new Set();
+      for (const field of node.entries) {
+        seen.add(field.key);
+        const property = Object.hasOwn(properties, field.key) ? properties[field.key] : null;
+        if (!property) {
+          report(field.keyToken, `check "${id}": Unknown ${name} field: ${field.key}`);
+          continue;
+        }
+        if (!field.value || field.value.kind === "expression") continue;
+        const nested = coerce(field.value, property, id, `${name}.${field.key}`);
+        if (nested) {
+          report(nested.token, nested.message);
+        } else if (property.type === "string" && field.value.value.trim() === "") {
+          report(field.value.token, `check "${id}": ${name}.${field.key} must not be empty.`);
+        }
+      }
+      for (const [key, property] of Object.entries(properties)) {
+        if (property.required && !seen.has(key)) {
+          report(entry.keyToken, `check "${id}": ${name}.${key} is required.`);
+        }
+      }
+      const oneOf = spec.requires_one_of ?? [];
+      const value = literal[name] ?? {};
+      if (oneOf.length && !oneOf.some((key) => provided(value[key]))) {
+        advise(entry.keyToken, `check "${id}": ${name} requires ${oneOf.map((key) => `${name}.${key}`).join(" or ")}.`);
+      }
+    }
+  }
+
+  // "One of A or B", with each param's default in force where it is not set.
+  const oneOf = check.requires_one_of ?? [];
+  if (oneOf.length) {
+    if (!oneOf.some((name) => provided(inForce(literal, schema, name)))) {
+      report(anchor, `check "${id}" requires ${oneOf.join(" or ")}.`);
+    }
+  }
+
+  // A scope field set on a check it cannot narrow (the platform refuses it on save).
+  for (const [name, entry] of given) {
+    if (catalogue.scopeFields?.has(name) && name in schema && provided(literal[name])) {
+      const why = inapplicableScope(check, name, literal);
+      if (why) advise(entry.keyToken, why);
+    }
+  }
+
+  return out;
+}