@lowdefy/server-dev 6.1.0 → 7.1.0

package/lib/server/mutants/describeEvent.js

@@ -0,0 +1,22 @@
+/*
+  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.
+*/
+
+// `assign_submit.onClick`, or `app.onInit` for an app event.
+function describeEvent(scope) {
+  return `${scope.blockId ?? 'app'}.${scope.eventName}`;
+}
+
+export default describeEvent;

package/lib/server/mutants/enumerateArtifact.js

@@ -0,0 +1,56 @@
+/*
+  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 walkArtifact from './walkArtifact.js';
+
+// Every mutant the given operators can make in one deserialised artifact, as
+// { operator, key, arg, anchor, describe, pointer, node }, node being the target
+// and pointer the path from the artifact root to it. A
+// target without a ~k (an object the build made rather than read from config)
+// cannot be addressed and is left out.
+function enumerateArtifact({ artifact, root, operators }) {
+  const applicable = operators.filter((operator) =>
+    operator.artifacts.some((pattern) => pattern.test(artifact))
+  );
+  const mutants = [];
+  if (applicable.length === 0) {
+    return mutants;
+  }
+  walkArtifact({
+    artifact,
+    root,
+    visit: (visit) => {
+      applicable.forEach((operator) => {
+        operator
+          .enumerate(visit)
+          .filter((target) => type.isString(target.key))
+          .forEach((target) =>
+            mutants.push({
+              operator: operator.name,
+              ...target,
+              pointer: visit.pointer,
+              node: visit.node,
+            })
+          );
+      });
+    },
+  });
+  return mutants;
+}
+
+export default enumerateArtifact;

package/lib/server/mutants/findNodeByKey.js

@@ -0,0 +1,45 @@
+/*
+  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';
+
+// The node of a deserialised build artifact whose ~k is `key`, with the
+// container that holds it. serializer.deserialize restores ~k as a
+// non-enumerable property, so it is read directly; Object.keys skips it.
+function findNodeByKey({ root, key }) {
+  const stack = [{ node: root, parent: null, keyInParent: null }];
+  while (stack.length > 0) {
+    const entry = stack.pop();
+    const { node } = entry;
+    if (!type.isObject(node) && !type.isArray(node)) {
+      continue;
+    }
+    if (node['~k'] === key) {
+      return entry;
+    }
+    const children = type.isArray(node)
+      ? node.map((child, index) => ({ node: child, parent: node, keyInParent: index }))
+      : Object.keys(node).map((childKey) => ({
+          node: node[childKey],
+          parent: node,
+          keyInParent: childKey,
+        }));
+    stack.push(...children.reverse());
+  }
+  return null;
+}
+
+export default findNodeByKey;

package/lib/server/mutants/findNodeByPointer.js

@@ -0,0 +1,49 @@
+/*
+  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 hashMutantTarget from './hashMutantTarget.js';
+
+// The node a pointer (the keys and array indexes from the artifact root, as
+// the mutant listing recorded them) leads to, with the container that holds
+// it, or null. A page the dev server rebuilds is issued new ~k keys, so a
+// mutant's key can miss while the page's config, and so its shape, is
+// unchanged. The node is taken only when its content hash is the one listed, so
+// a pointer into changed content finds nothing rather than another node.
+function findNodeByPointer({ root, pointer, nodeHash }) {
+  if (!type.isArray(pointer) || pointer.length === 0 || !type.isString(nodeHash)) {
+    return null;
+  }
+  let parent = null;
+  let node = root;
+  for (const step of pointer) {
+    if (!type.isObject(node) && !type.isArray(node)) {
+      return null;
+    }
+    if (!Object.prototype.hasOwnProperty.call(node, step)) {
+      return null;
+    }
+    parent = node;
+    node = node[step];
+  }
+  if (!type.isObject(node) || hashMutantTarget(node) !== nodeHash) {
+    return null;
+  }
+  return { node, parent, keyInParent: pointer[pointer.length - 1] };
+}
+
+export default findNodeByPointer;

package/lib/server/mutants/getArtifactKind.js

@@ -0,0 +1,32 @@
+/*
+  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 {
+  ENDPOINT_ARTIFACT,
+  EVENTS_ARTIFACT,
+  PAGE_ARTIFACT,
+  REQUEST_ARTIFACT,
+} from './artifactPatterns.js';
+
+function getArtifactKind(artifact) {
+  if (REQUEST_ARTIFACT.test(artifact)) return 'request';
+  if (PAGE_ARTIFACT.test(artifact)) return 'page';
+  if (ENDPOINT_ARTIFACT.test(artifact)) return 'endpoint';
+  if (EVENTS_ARTIFACT.test(artifact)) return 'app';
+  return null;
+}
+
+export default getArtifactKind;

package/lib/server/mutants/groupMutantCopies.js

@@ -0,0 +1,56 @@
+/*
+  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 { stableStringify } from '@lowdefy/helpers';
+
+function copyPage(mutant) {
+  return mutant.anchor.pageId ?? mutant.artifact;
+}
+
+// A `_ref`'d layout, menu or template is copied into every page artifact that
+// uses it, so one written node is enumerated once per page. Mutants with the
+// same operator, source, arg and target content are one mutant: the copy on
+// the first page by page id is kept, and the other pages are listed under
+// `copies`. Each other copy's own artifact, key and anchor are listed under
+// `copyTargets`, in the same order: the build keys every copy apart, so a
+// journey that reaches the node on another page is run against that page's
+// copy. Each copy also carries its `pointer`, the path to it from the artifact
+// root, which finds it again when its page is rebuilt and its keys are not. Templated copies whose content differs stay apart.
+function groupMutantCopies({ mutants }) {
+  const groups = new Map();
+  mutants.forEach((mutant) => {
+    const group = stableStringify([mutant.operator, mutant.source, mutant.arg, mutant.nodeHash]);
+    if (!groups.has(group)) {
+      groups.set(group, []);
+    }
+    groups.get(group).push(mutant);
+  });
+  return [...groups.values()].map((group) => {
+    const [kept, ...others] = [...group].sort((a, b) => copyPage(a).localeCompare(copyPage(b)));
+    return {
+      ...kept,
+      copies: others.map(copyPage),
+      copyTargets: others.map(({ artifact, key, anchor, pointer }) => ({
+        artifact,
+        key,
+        anchor,
+        pointer,
+      })),
+    };
+  });
+}
+
+export default groupMutantCopies;

package/lib/server/mutants/hashArtifact.js

@@ -0,0 +1,25 @@
+/*
+  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 crypto from 'node:crypto';
+
+// The content hash of a deserialised artifact. JSON.stringify leaves out the
+// non-enumerable ~k, so two builds of unchanged config hash the same.
+function hashArtifact(root) {
+  return crypto.createHash('sha1').update(JSON.stringify(root)).digest('hex');
+}
+
+export default hashArtifact;

package/lib/server/mutants/hashMutantTarget.js

@@ -0,0 +1,34 @@
+/*
+  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 crypto from 'node:crypto';
+
+// The content of a mutant's target, to tell copies of one written node apart
+// from different nodes. The build gives blocks and requests ids that embed the
+// page id and position (`block:tickets:footer:0`), so those are left out: two
+// pages using one `_ref`'d layout carry the same node under different ids.
+// JSON.stringify already leaves out the non-enumerable ~k.
+function hashMutantTarget(node) {
+  const content = JSON.stringify(node, (key, value) => {
+    if (key === 'id' && typeof value === 'string' && /^(block|request):/.test(value)) {
+      return undefined;
+    }
+    return value;
+  });
+  return crypto.createHash('sha1').update(content).digest('hex');
+}
+
+export default hashMutantTarget;

package/lib/server/mutants/listMutants.js

@@ -0,0 +1,122 @@
+/*
+  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 { resolveConfigLocation } from '@lowdefy/errors';
+import { type } from '@lowdefy/helpers';
+
+import collectSharedIds from './collectSharedIds.js';
+import enumerateArtifact from './enumerateArtifact.js';
+import groupMutantCopies from './groupMutantCopies.js';
+import hashArtifact from './hashArtifact.js';
+import hashMutantTarget from './hashMutantTarget.js';
+import mutantId from './mutantId.js';
+import operatorDefinitions from './operators/index.js';
+import positionFreePath from './positionFreePath.js';
+
+function artifactPaths({ pages, requests, endpoints, appEvents }) {
+  return [
+    ...pages.map((pageId) => `pages/${pageId}.json`),
+    ...requests.map(({ pageId, requestId }) => `pages/${pageId}/requests/${requestId}.json`),
+    ...endpoints.map((endpointId) => `api/${endpointId}.json`),
+    ...(appEvents ? ['events.json'] : []),
+  ];
+}
+
+// Every mutant on the artifacts a set of journey runs exercised, each with a
+// build-independent id, its anchor, the source line and config path of its
+// target, and `_ref` copies grouped into one mutant. Also returns the content
+// hash of every artifact read, so a harden run can tell which of its verdicts
+// a config edit left standing, and `ids`, the id of every copy before
+// grouping, so a harden run can tell whether a mutant an earlier run listed
+// still exists, whichever copy that run kept.
+async function listMutants({
+  pages = [],
+  requests = [],
+  endpoints = [],
+  appEvents = false,
+  operators,
+  readConfigFile,
+  keyMap,
+  refMap,
+}) {
+  const selected = type.isNone(operators)
+    ? Object.values(operatorDefinitions)
+    : operators.map((name) => operatorDefinitions[name]);
+  const sharedIds = collectSharedIds({ keyMap });
+  const artifacts = {};
+  const mutants = [];
+  for (const artifact of [...new Set(artifactPaths({ pages, requests, endpoints, appEvents }))]) {
+    const root = await readConfigFile(artifact);
+    if (type.isNone(root)) {
+      continue;
+    }
+    artifacts[artifact] = hashArtifact(root);
+    enumerateArtifact({ artifact, root, operators: selected }).forEach(({ node, ...mutant }) => {
+      const location = resolveConfigLocation({ configKey: mutant.key, keyMap, refMap });
+      const config = location?.config ?? null;
+      mutants.push({
+        ...mutant,
+        id: mutantId({
+          artifact,
+          configPath: positionFreePath({ configPath: config ?? mutant.key, sharedIds }),
+          operator: mutant.operator,
+          arg: mutant.arg,
+        }),
+        artifact,
+        source: location?.source ?? null,
+        config,
+        nodeHash: hashMutantTarget(node),
+      });
+    });
+  }
+  return {
+    artifacts,
+    ids: mutants.map(({ id }) => id),
+    mutants: groupMutantCopies({ mutants }).map(
+      ({
+        id,
+        operator,
+        artifact,
+        key,
+        arg,
+        anchor,
+        pointer,
+        nodeHash,
+        source,
+        config,
+        describe,
+        copies,
+        copyTargets,
+      }) => ({
+        id,
+        operator,
+        artifact,
+        key,
+        arg,
+        anchor,
+        pointer,
+        nodeHash,
+        source,
+        config,
+        describe,
+        copies,
+        copyTargets,
+      })
+    ),
+  };
+}
+
+export default listMutants;