@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/server/mutants/validateMutantParam.js

@@ -0,0 +1,69 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import operators from './operators/index.js';
+
+const ARTIFACT_PATTERN = /^(pages\/.+\.json|api\/.+\.json|events\.json)$/;
+
+// The `mutant` of a journey POST: one mutant from POST /lowdefy-docs/mutants,
+// with the build it was listed against. Returns an error message, or
+// undefined when it is valid.
+function validateMutantParam(mutant) {
+  if (!type.isObject(mutant)) {
+    return `The "mutant" param must be an object { buildId, artifact, key, arg, operator }. Received ${JSON.stringify(
+      mutant
+    )}.`;
+  }
+  if (
+    !type.isString(mutant.artifact) ||
+    !ARTIFACT_PATTERN.test(mutant.artifact) ||
+    mutant.artifact.includes('..')
+  ) {
+    return `"mutant.artifact" must be a page, endpoint or app events artifact path, such as "pages/tickets.json". Received ${JSON.stringify(
+      mutant.artifact
+    )}.`;
+  }
+  if (type.isUndefined(operators[mutant.operator])) {
+    return `"mutant.operator" must be one of ${Object.keys(operators).join(
+      ', '
+    )}. Received ${JSON.stringify(mutant.operator)}.`;
+  }
+  if (!type.isString(mutant.key)) {
+    return `"mutant.key" must be a string. Received ${JSON.stringify(mutant.key)}.`;
+  }
+  if (
+    !type.isNone(mutant.pointer) &&
+    !(
+      type.isArray(mutant.pointer) &&
+      mutant.pointer.every((step) => type.isString(step) || type.isInt(step))
+    )
+  ) {
+    return `"mutant.pointer" must be an array of keys and indexes. Received ${JSON.stringify(
+      mutant.pointer
+    )}.`;
+  }
+  if (!type.isNone(mutant.nodeHash) && !type.isString(mutant.nodeHash)) {
+    return `"mutant.nodeHash" must be a string. Received ${JSON.stringify(mutant.nodeHash)}.`;
+  }
+  if (!type.isNone(mutant.arg) && !type.isString(mutant.arg)) {
+    return `"mutant.arg" must be a string. Received ${JSON.stringify(mutant.arg)}.`;
+  }
+  return undefined;
+}
+
+export default validateMutantParam;

package/lib/server/mutants/validateMutantsBody.js

@@ -0,0 +1,88 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import operators from './operators/index.js';
+
+function isStringArray(value) {
+  return type.isArray(value) && value.every((item) => type.isString(item));
+}
+
+// Ids name build artifacts (`pages/<id>.json`), so one that climbs out of
+// the build directory is refused, as readConfigFile refuses it.
+function isId(value) {
+  return type.isString(value) && !value.includes('..');
+}
+
+function isIdArray(value) {
+  return type.isArray(value) && value.every((item) => isId(item));
+}
+
+// The body of POST /lowdefy-docs/mutants: what a set of journey runs
+// exercised. Returns { body } with defaults, or { error } naming the field.
+function validateMutantsBody(body) {
+  if (!type.isObject(body)) {
+    return { error: `The body must be a JSON object. Received ${JSON.stringify(body)}.` };
+  }
+  const { pages = [], requests = [], endpoints = [], appEvents = false } = body;
+  if (!isIdArray(pages)) {
+    return { error: `"pages" must be an array of page ids. Received ${JSON.stringify(pages)}.` };
+  }
+  if (
+    !type.isArray(requests) ||
+    !requests.every(
+      (request) => type.isObject(request) && isId(request.pageId) && isId(request.requestId)
+    )
+  ) {
+    return {
+      error: `"requests" must be an array of { pageId, requestId }. Received ${JSON.stringify(
+        requests
+      )}.`,
+    };
+  }
+  if (!isIdArray(endpoints)) {
+    return {
+      error: `"endpoints" must be an array of endpoint ids. Received ${JSON.stringify(endpoints)}.`,
+    };
+  }
+  if (!type.isBoolean(appEvents)) {
+    return { error: `"appEvents" must be a boolean. Received ${JSON.stringify(appEvents)}.` };
+  }
+  if (!type.isNone(body.operators)) {
+    const unknown = isStringArray(body.operators)
+      ? body.operators.filter((name) => type.isUndefined(operators[name]))
+      : [body.operators];
+    if (unknown.length > 0) {
+      return {
+        error: `"operators" must be an array of operator names (${Object.keys(operators).join(
+          ', '
+        )}). Received ${JSON.stringify(body.operators)}.`,
+      };
+    }
+  }
+  return {
+    body: {
+      pages,
+      requests: requests.map(({ pageId, requestId }) => ({ pageId, requestId })),
+      endpoints,
+      appEvents,
+      operators: body.operators ?? null,
+    },
+  };
+}
+
+export default validateMutantsBody;

package/lib/server/mutants/walkArtifact.js

@@ -0,0 +1,179 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { type } from '@lowdefy/helpers';
+
+import getArtifactKind from './getArtifactKind.js';
+import isRoutineStep from '../isRoutineStep.js';
+
+function rootScope({ artifact, root }) {
+  const kind = getArtifactKind(artifact);
+  switch (kind) {
+    case 'page':
+      return {
+        kind,
+        pageId: root.pageId,
+        role: 'block',
+        region: 'block',
+        blockId: root.blockId ?? root.pageId,
+        blockType: root.type,
+        parentBlockId: null,
+      };
+    case 'app':
+      return { kind, pageId: 'app', role: 'events', region: 'events', blockId: null };
+    case 'request':
+      return { kind, pageId: root.pageId, requestId: root.requestId, role: 'requestRoot' };
+    case 'endpoint':
+      return { kind, endpointId: root.endpointId, role: 'endpointRoot' };
+    default:
+      return null;
+  }
+}
+
+function blockChildScope({ scope, key }) {
+  switch (key) {
+    case 'slots':
+      return { ...scope, role: 'slots', region: 'slots' };
+    case 'events':
+      return { ...scope, role: 'events', region: 'events' };
+    case 'properties':
+      return { ...scope, role: 'value', region: 'blockProperties' };
+    case 'validate':
+      return { ...scope, role: 'validate', region: 'validate' };
+    case 'requests':
+      // Only the page itself holds requests; the server never runs this copy
+      // of their config (it reads the request artifact), so only the payload
+      // the browser evaluates is walked.
+      return scope.parentBlockId === null
+        ? { ...scope, role: 'requests', region: 'requests' }
+        : null;
+    default:
+      return { ...scope, role: 'value', region: 'blockOther' };
+  }
+}
+
+// The scope of `child`, found at `key` in `node` (scope `scope`), or null to
+// leave the subtree out. A scope names the node's role in the artifact
+// (block, action, payload, step, ...) and where it sits (page, block,
+// event), which is what operators enumerate by and anchors are built from.
+function childScope({ scope, key, child }) {
+  switch (scope.role) {
+    case 'block':
+      return blockChildScope({ scope, key });
+    case 'slots':
+      return { ...scope, role: 'slot' };
+    case 'slot':
+      return key === 'blocks' ? { ...scope, role: 'slotBlocks' } : null;
+    case 'slotBlocks':
+      return {
+        ...scope,
+        role: 'block',
+        region: 'block',
+        parentBlockId: scope.blockId,
+        blockId: child?.blockId,
+        blockType: child?.type,
+      };
+    case 'events':
+      return { ...scope, role: 'event', eventName: key };
+    case 'event':
+      return key === 'try' || key === 'catch' ? { ...scope, role: 'actions', branch: key } : null;
+    case 'actions':
+      return { ...scope, role: 'action', actionId: child?.id, actionType: child?.type };
+    case 'action':
+      return {
+        ...scope,
+        role: 'value',
+        region: key === 'params' ? 'actionParams' : 'actionOther',
+      };
+    case 'validate':
+      return { ...scope, role: 'validateEntry' };
+    case 'requests':
+      return { ...scope, role: 'request', requestId: child?.requestId };
+    case 'request':
+      return key === 'payload' ? { ...scope, role: 'payload', region: 'requestPayload' } : null;
+    case 'requestRoot':
+      return key === 'properties' ? { ...scope, role: 'value', region: 'requestProperties' } : null;
+    case 'endpointRoot':
+      return key === 'routine' ? { ...scope, role: 'routine', region: 'routine' } : null;
+    case 'routine':
+      // An array of routine items: steps, controls, or nested arrays.
+      if (isRoutineStep(child)) {
+        return { ...scope, role: 'step', stepId: child.stepId, stepType: child.type };
+      }
+      if (type.isArray(child)) {
+        return { ...scope, role: 'routine' };
+      }
+      if (type.isObject(child) && Object.keys(child).some((childKey) => childKey.startsWith(':'))) {
+        return { ...scope, role: 'control' };
+      }
+      return { ...scope, role: 'routineValue' };
+    case 'control':
+      // `:then`, `:else`, `:try`, `:parallel`, ... hold more steps; `:if`,
+      // `:set_state`, `:return`, ... hold values.
+      return { ...scope, role: type.isArray(child) ? 'routine' : 'routineValue' };
+    case 'step':
+    case 'routineValue':
+      return { ...scope, role: 'routineValue' };
+    default:
+      return { ...scope, role: 'value' };
+  }
+}
+
+// Depth-first walk of one deserialised build artifact, calling visit for every
+// object with its parent, its key in the parent, its scope and its pointer:
+// the keys and array indexes that lead from the root to it.
+function walkArtifact({ artifact, root, visit }) {
+  function walk({ node, parent, keyInParent, scope, pointer }) {
+    if (type.isArray(node)) {
+      node.forEach((child, index) => {
+        const next = childScope({ scope, key: index, child });
+        if (next !== null) {
+          walk({
+            node: child,
+            parent: node,
+            keyInParent: index,
+            scope: next,
+            pointer: [...pointer, index],
+          });
+        }
+      });
+      return;
+    }
+    if (!type.isObject(node)) {
+      return;
+    }
+    visit({ node, parent, keyInParent, artifact, scope, pointer });
+    Object.keys(node).forEach((key) => {
+      const next = childScope({ scope, key, child: node[key] });
+      if (next !== null) {
+        walk({
+          node: node[key],
+          parent: node,
+          keyInParent: key,
+          scope: next,
+          pointer: [...pointer, key],
+        });
+      }
+    });
+  }
+  const scope = rootScope({ artifact, root });
+  if (scope === null) {
+    return;
+  }
+  walk({ node: root, parent: null, keyInParent: null, scope, pointer: [] });
+}
+
+export default walkArtifact;

package/lib/server/pageBuildRecords.js

@@ -0,0 +1,131 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import path from 'node:path';
+
+import { resolveErrorLocation } from '@lowdefy/errors';
+
+import mapPageBuildErrors from '../docs/mapPageBuildErrors.js';
+import hashConfigContent from './hashConfigContent.js';
+
+// What each page's latest JIT build read and how it ended, kept for the life of
+// the server process. The dev server uses it to tell which built pages an edit
+// touched and which pages currently fail to build, without the page being
+// requested. Pages build concurrently on one shared build context, so the files
+// a build reads are attributed through async context rather than the context.
+const buildReads = new AsyncLocalStorage();
+const records = new Map();
+
+// Recorded for a file a build read twice with different content, or could not
+// read: no content on disk matches it, so the page is always rebuilt.
+const NEVER_MATCHES = 'conflict';
+
+function recordRead({ reads, filePath, hash }) {
+  const previous = reads.files.get(filePath);
+  if (previous !== undefined && previous !== hash) {
+    reads.files.set(filePath, NEVER_MATCHES);
+    return;
+  }
+  reads.files.set(filePath, hash);
+}
+
+// Every config file a page build reads comes through readConfigFile, and all
+// app code it runs through importAppCode. App code can read anything, so a
+// build that ran it is only marked, not traced.
+function trackReadConfigFile({ readConfigFile, configDirectory }) {
+  return async function trackedReadConfigFile(filePath) {
+    const reads = buildReads.getStore();
+    const absolutePath = path.resolve(configDirectory, filePath);
+    let content;
+    try {
+      content = await readConfigFile(filePath);
+    } catch (error) {
+      if (reads) recordRead({ reads, filePath: absolutePath, hash: NEVER_MATCHES });
+      throw error;
+    }
+    if (reads) recordRead({ reads, filePath: absolutePath, hash: hashConfigContent(content) });
+    return content;
+  };
+}
+
+function trackFileReads({ context, configDirectory }) {
+  context.readConfigFile = trackReadConfigFile({
+    readConfigFile: context.readConfigFile,
+    configDirectory,
+  });
+  const importAppCode = context.importAppCode;
+  context.importAppCode = (filePath) => {
+    const reads = buildReads.getStore();
+    if (reads) reads.ranAppCode = true;
+    return importAppCode(filePath);
+  };
+}
+
+// The page route resolves a build error's source when it logs the error; a
+// build nobody requested is never logged, so its errors are located here, from
+// the keys the build added to its context.
+function locateErrors({ error, context, configDirectory }) {
+  for (const buildError of error.buildErrors ?? [error]) {
+    if (buildError.source) continue;
+    try {
+      buildError.source =
+        resolveErrorLocation(buildError, {
+          keyMap: context.keyMap,
+          refMap: context.refMap,
+          configDirectory,
+        })?.source ?? null;
+    } catch {
+      // A malformed keyMap or refMap entry leaves the error unlocated.
+    }
+  }
+}
+
+// generation names the build context the page was built on, and checkedAt the
+// change event counter when its build started: what it read is current as of
+// that event.
+async function record({ pageId, context, configDirectory, generation, checkedAt, build }) {
+  const reads = { files: new Map(), ranAppCode: false };
+  const builtAt = Date.now();
+  const describe = (errors) => ({
+    builtAt,
+    checkedAt,
+    errors,
+    files: reads.files,
+    generation,
+    ranAppCode: reads.ranAppCode,
+  });
+  let result;
+  try {
+    result = await buildReads.run(reads, build);
+  } catch (error) {
+    locateErrors({ error, context, configDirectory });
+    records.set(pageId, describe(mapPageBuildErrors(error)));
+    throw error;
+  }
+  // A plugin install ends the build before the page is built, so the page's
+  // previous record still describes it.
+  if (!result?.installing) {
+    records.set(pageId, describe(null));
+  }
+  return result;
+}
+
+function get(pageId) {
+  return records.get(pageId) ?? null;
+}
+
+export default { get, record, trackFileReads, trackReadConfigFile };