@lowdefy/server-dev 6.1.0 → 7.0.0

package/lib/server/mutants/mutantRuns.test.mjs

@@ -0,0 +1,136 @@
+/*
+  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 { cachedPromises, serializer } from '@lowdefy/helpers';
+
+import createMutantReadConfigFile from './createMutantReadConfigFile.js';
+import { journeyActorToken } from '../auth/journeyActor.js';
+import { openMutantRun, readMutantRun } from './mutantRuns.js';
+import { pageFixture } from './test/fixtures.mjs';
+
+const ARTIFACT = 'pages/tickets.json';
+
+// As the API context reads a build artifact: through cachedPromises, so every
+// request shares one parsed object per path while the cache holds it.
+function createCachedReadConfigFile(files) {
+  const store = new Map();
+  const cache = { get: (key) => store.get(key), set: (key, value) => store.set(key, value) };
+  return cachedPromises({
+    cache,
+    getter: async (filePath) => serializer.deserializeFromString(files[filePath] ?? 'null'),
+  });
+}
+
+function setup(mutantOverrides = {}) {
+  const { root } = pageFixture();
+  const success = root.slots.content.blocks[3].slots.content.blocks[0];
+  const files = {
+    [ARTIFACT]: serializer.serializeToString(root),
+    'events.json': serializer.serializeToString({ onInit: { try: [], catch: [] } }),
+  };
+  const readConfigFile = createCachedReadConfigFile(files);
+  const opened = openMutantRun({
+    mutant: {
+      buildId: 'build-1',
+      artifact: ARTIFACT,
+      key: success['~k'],
+      arg: null,
+      operator: 'drop-block',
+      ...mutantOverrides,
+    },
+  });
+  return { opened, readConfigFile, root };
+}
+
+function mutantCookie(payload, token = journeyActorToken) {
+  return `session=abc; lowdefy_journey_mutant=${token}.${payload}`;
+}
+
+test('a read of the target path returns the mutated copy and counts one application', async () => {
+  const { opened, readConfigFile } = setup();
+  const read = createMutantReadConfigFile({ readConfigFile, run: opened.run });
+  const page = await read(ARTIFACT);
+  expect(page.slots.content.blocks[3].slots.content.blocks).toEqual([]);
+  expect(opened.run.applied).toBe(1);
+  expect(opened.run.misses).toEqual([]);
+  opened.close();
+});
+
+test('a read of another path is untouched', async () => {
+  const { opened, readConfigFile } = setup();
+  const read = createMutantReadConfigFile({ readConfigFile, run: opened.run });
+  expect(await read('events.json')).toBe(await readConfigFile('events.json'));
+  expect(opened.run.applied).toBe(0);
+  opened.close();
+});
+
+test('a mutated read followed by an unmutated read through a shared cache returns the original', async () => {
+  const { opened, readConfigFile } = setup();
+  const mutated = await createMutantReadConfigFile({ readConfigFile, run: opened.run })(ARTIFACT);
+  const original = await readConfigFile(ARTIFACT);
+  expect(mutated.slots.content.blocks[3].slots.content.blocks).toHaveLength(0);
+  expect(original.slots.content.blocks[3].slots.content.blocks).toHaveLength(1);
+  // The copy keeps ~k, so the mutant can still be found in it.
+  expect(mutated.slots.content.blocks[0]['~k']).toEqual(original.slots.content.blocks[0]['~k']);
+  opened.close();
+});
+
+test('a key not found and an apply with no arg each record a miss and apply nothing', async () => {
+  const missingKey = setup({ key: 'not-a-key' });
+  const page = await createMutantReadConfigFile({
+    readConfigFile: missingKey.readConfigFile,
+    run: missingKey.opened.run,
+  })(ARTIFACT);
+  expect(missingKey.opened.run.applied).toBe(0);
+  expect(missingKey.opened.run.misses).toEqual([{ reason: 'key not found', path: ARTIFACT }]);
+  expect(JSON.stringify(page)).toEqual(JSON.stringify(missingKey.root));
+  missingKey.opened.close();
+
+  const name = missingKey.root.slots.content.blocks[1];
+  const noArg = setup({ operator: 'flip-visible', key: name['~k'], arg: null });
+  await createMutantReadConfigFile({ readConfigFile: noArg.readConfigFile, run: noArg.opened.run })(
+    ARTIFACT
+  );
+  expect(noArg.opened.run.applied).toBe(0);
+  expect(noArg.opened.run.misses).toEqual([
+    { reason: 'flip-visible needs arg visible or properties.disabled', path: ARTIFACT },
+  ]);
+  noArg.opened.close();
+});
+
+test('readMutantRun returns the open run a verified mutant cookie names', () => {
+  const { opened } = setup();
+  expect(readMutantRun(mutantCookie(opened.cookiePayload))).toBe(opened.run);
+  opened.close();
+});
+
+test('readMutantRun returns null for a forged token, a missing cookie and a closed run', () => {
+  const { opened } = setup();
+  expect(readMutantRun(mutantCookie(opened.cookiePayload, '0'.repeat(64)))).toBeNull();
+  expect(readMutantRun('session=abc')).toBeNull();
+  expect(readMutantRun(undefined)).toBeNull();
+  opened.close();
+  expect(readMutantRun(mutantCookie(opened.cookiePayload))).toBeNull();
+});
+
+test('openMutantRun gives every run its own 16-byte id', () => {
+  const first = setup().opened;
+  const second = setup().opened;
+  expect(first.id).toMatch(/^[0-9a-f]{32}$/);
+  expect(first.id).not.toEqual(second.id);
+  first.close();
+  second.close();
+});

package/lib/server/mutants/operators/dropAction.js

@@ -0,0 +1,47 @@
+/*
+  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 { EVENTS_ARTIFACT, PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+import describeEvent from '../describeEvent.js';
+import removeFromParent from '../removeFromParent.js';
+
+function enumerate({ node, parent, keyInParent, scope }) {
+  if (scope.role !== 'action') {
+    return [];
+  }
+  return [
+    {
+      key: node['~k'],
+      arg: null,
+      anchor: buildAnchor({ scope, type: 'action' }),
+      describe: `drop-action ${node.type} "${node.id}" (${keyInParent + 1} of ${
+        parent.length
+      }) from ${describeEvent(scope)}`,
+    },
+  ];
+}
+
+function apply({ parent, keyInParent }) {
+  return removeFromParent({ parent, keyInParent });
+}
+
+export default {
+  name: 'drop-action',
+  artifacts: [PAGE_ARTIFACT, EVENTS_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/dropBlock.js

@@ -0,0 +1,44 @@
+/*
+  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 { PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+import removeFromParent from '../removeFromParent.js';
+
+function enumerate({ node, scope }) {
+  if (scope.role !== 'block' || scope.parentBlockId === null) {
+    return [];
+  }
+  return [
+    {
+      key: node['~k'],
+      arg: null,
+      anchor: buildAnchor({ scope, type: 'block' }),
+      describe: `drop-block ${node.type} "${scope.blockId}" from ${scope.parentBlockId}`,
+    },
+  ];
+}
+
+function apply({ parent, keyInParent }) {
+  return removeFromParent({ parent, keyInParent });
+}
+
+export default {
+  name: 'drop-block',
+  artifacts: [PAGE_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/dropPayload.js

@@ -0,0 +1,52 @@
+/*
+  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 { PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+
+// The payload a page artifact's request carries is what the browser
+// evaluates and sends, so dropping one key changes what the server receives.
+function enumerate({ node, scope }) {
+  if (scope.role !== 'payload') {
+    return [];
+  }
+  return Object.keys(node).map((arg) => ({
+    key: node['~k'],
+    arg,
+    anchor: buildAnchor({ scope, type: 'request' }),
+    describe: `drop-payload "${arg}" from request "${scope.requestId}"`,
+  }));
+}
+
+function apply({ node, arg }) {
+  if (!type.isString(arg)) {
+    return { applied: false, reason: 'drop-payload needs the payload key as arg' };
+  }
+  if (!Object.prototype.hasOwnProperty.call(node, arg)) {
+    return { applied: false, reason: `payload has no key "${arg}"` };
+  }
+  delete node[arg];
+  return { applied: true };
+}
+
+export default {
+  name: 'drop-payload',
+  artifacts: [PAGE_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/dropStep.js

@@ -0,0 +1,44 @@
+/*
+  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 } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+import removeFromParent from '../removeFromParent.js';
+
+function enumerate({ node, scope }) {
+  if (scope.role !== 'step') {
+    return [];
+  }
+  return [
+    {
+      key: node['~k'],
+      arg: null,
+      anchor: buildAnchor({ scope, type: 'endpoint' }),
+      describe: `drop-step ${node.type} "${scope.stepId}" from endpoint "${scope.endpointId}"`,
+    },
+  ];
+}
+
+function apply({ parent, keyInParent }) {
+  return removeFromParent({ parent, keyInParent });
+}
+
+export default {
+  name: 'drop-step',
+  artifacts: [ENDPOINT_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/flipVisible.js

@@ -0,0 +1,53 @@
+/*
+  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 { get, set, type } from '@lowdefy/helpers';
+
+import { PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+
+const ARGS = ['visible', 'properties.disabled'];
+
+function enumerate({ node, scope }) {
+  if (scope.role !== 'block') {
+    return [];
+  }
+  return ARGS.filter((arg) => !type.isUndefined(get(node, arg))).map((arg) => ({
+    key: node['~k'],
+    arg,
+    anchor: buildAnchor({ scope, type: 'block' }),
+    describe: `flip-visible ${arg} on ${scope.blockId}`,
+  }));
+}
+
+function apply({ node, arg }) {
+  if (!ARGS.includes(arg)) {
+    return { applied: false, reason: `flip-visible needs arg visible or properties.disabled` };
+  }
+  const value = get(node, arg);
+  if (type.isUndefined(value)) {
+    return { applied: false, reason: `block has no ${arg}` };
+  }
+  set(node, arg, type.isBoolean(value) ? !value : { _not: value });
+  return { applied: true };
+}
+
+export default {
+  name: 'flip-visible',
+  artifacts: [PAGE_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/index.js

@@ -0,0 +1,37 @@
+/*
+  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 dropAction from './dropAction.js';
+import dropBlock from './dropBlock.js';
+import dropPayload from './dropPayload.js';
+import dropStep from './dropStep.js';
+import flipVisible from './flipVisible.js';
+import retargetLink from './retargetLink.js';
+import skipValidate from './skipValidate.js';
+import swapIf from './swapIf.js';
+
+const operators = {
+  [dropAction.name]: dropAction,
+  [skipValidate.name]: skipValidate,
+  [flipVisible.name]: flipVisible,
+  [swapIf.name]: swapIf,
+  [dropPayload.name]: dropPayload,
+  [retargetLink.name]: retargetLink,
+  [dropBlock.name]: dropBlock,
+  [dropStep.name]: dropStep,
+};
+
+export default operators;

package/lib/server/mutants/operators/retargetLink.js

@@ -0,0 +1,72 @@
+/*
+  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 { EVENTS_ARTIFACT, PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+import describeEvent from '../describeEvent.js';
+
+// The build's default pages always include 404, so a retargeted Link always
+// lands somewhere. Links by url, back or home name no page and are skipped.
+function linksToPage(params) {
+  if (type.isString(params)) {
+    return true;
+  }
+  return (
+    type.isObject(params) &&
+    !type.isUndefined(params.pageId) &&
+    type.isUndefined(params.url) &&
+    type.isUndefined(params.back) &&
+    type.isUndefined(params.home)
+  );
+}
+
+function enumerate({ node, scope }) {
+  if (scope.role !== 'action' || node.type !== 'Link') {
+    return [];
+  }
+  if (!linksToPage(node.params)) {
+    return [];
+  }
+  return [
+    {
+      key: node['~k'],
+      arg: null,
+      anchor: buildAnchor({ scope, type: 'action' }),
+      describe: `retarget-link Link "${node.id}" from ${describeEvent(scope)} to 404`,
+    },
+  ];
+}
+
+function apply({ node }) {
+  if (type.isString(node.params)) {
+    node.params = '404';
+    return { applied: true };
+  }
+  if (linksToPage(node.params)) {
+    node.params.pageId = '404';
+    return { applied: true };
+  }
+  return { applied: false, reason: 'Link names no page' };
+}
+
+export default {
+  name: 'retarget-link',
+  artifacts: [PAGE_ARTIFACT, EVENTS_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/skipValidate.js

@@ -0,0 +1,77 @@
+/*
+  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 { PAGE_ARTIFACT } from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+import describeEvent from '../describeEvent.js';
+import removeFromParent from '../removeFromParent.js';
+
+// Page artifacts only: the build refuses Validate in app events.
+function enumerate({ node, parent, keyInParent, scope }) {
+  if (scope.role === 'action' && node.type === 'Validate') {
+    return [
+      {
+        key: node['~k'],
+        arg: null,
+        anchor: buildAnchor({ scope, type: 'action' }),
+        describe: `skip-validate Validate "${node.id}" from ${describeEvent(scope)}`,
+      },
+    ];
+  }
+  if (scope.role === 'block' && !type.isNone(node.required) && node.required !== false) {
+    return [
+      {
+        key: node['~k'],
+        arg: 'required',
+        anchor: buildAnchor({ scope, type: 'block' }),
+        describe: `skip-validate required on ${scope.blockId}`,
+      },
+    ];
+  }
+  if (scope.role === 'validateEntry') {
+    return [
+      {
+        key: node['~k'],
+        arg: null,
+        anchor: buildAnchor({ scope, type: 'block' }),
+        describe: `skip-validate validate rule ${keyInParent + 1} of ${parent.length} on ${
+          scope.blockId
+        }`,
+      },
+    ];
+  }
+  return [];
+}
+
+function apply({ node, parent, keyInParent, arg }) {
+  if (arg === 'required') {
+    if (type.isUndefined(node.required)) {
+      return { applied: false, reason: 'block has no required' };
+    }
+    delete node.required;
+    return { applied: true };
+  }
+  return removeFromParent({ parent, keyInParent });
+}
+
+export default {
+  name: 'skip-validate',
+  artifacts: [PAGE_ARTIFACT],
+  enumerate,
+  apply,
+};

package/lib/server/mutants/operators/swapIf.js

@@ -0,0 +1,112 @@
+/*
+  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 {
+  ENDPOINT_ARTIFACT,
+  EVENTS_ARTIFACT,
+  PAGE_ARTIFACT,
+  REQUEST_ARTIFACT,
+} from '../artifactPatterns.js';
+import buildAnchor from '../buildAnchor.js';
+
+const REGIONS = [
+  'blockProperties',
+  'actionParams',
+  'requestPayload',
+  'requestProperties',
+  'routine',
+];
+
+function anchorType(scope) {
+  switch (scope.region) {
+    case 'blockProperties':
+      return 'block';
+    case 'actionParams':
+      return 'action';
+    case 'routine':
+      return 'endpoint';
+    default:
+      return 'request';
+  }
+}
+
+function describeWhere(scope) {
+  switch (scope.region) {
+    case 'blockProperties':
+      return `${scope.blockId}.properties`;
+    case 'actionParams':
+      return `action "${scope.actionId}" params`;
+    case 'routine':
+      return `endpoint "${scope.endpointId}"`;
+    case 'requestPayload':
+      return `request "${scope.requestId}" payload`;
+    default:
+      return `request "${scope.requestId}" properties`;
+  }
+}
+
+function isSwappableIf(node) {
+  return type.isObject(node._if) && !type.isUndefined(node._if.else);
+}
+
+function isSwappableRoutineIf(node, scope) {
+  return (
+    scope.role === 'control' && !type.isUndefined(node[':if']) && !type.isUndefined(node[':else'])
+  );
+}
+
+function enumerate({ node, scope }) {
+  if (!REGIONS.includes(scope.region)) {
+    return [];
+  }
+  if (!isSwappableIf(node) && !isSwappableRoutineIf(node, scope)) {
+    return [];
+  }
+  const operator = isSwappableIf(node) ? '_if' : ':if';
+  return [
+    {
+      key: node['~k'],
+      arg: null,
+      anchor: buildAnchor({ scope, type: anchorType(scope) }),
+      describe: `swap-if ${operator} in ${describeWhere(scope)}`,
+    },
+  ];
+}
+
+function apply({ node }) {
+  if (isSwappableIf(node)) {
+    const { then, else: otherwise } = node._if;
+    node._if.then = otherwise;
+    node._if.else = then;
+    return { applied: true };
+  }
+  if (!type.isUndefined(node[':if']) && !type.isUndefined(node[':else'])) {
+    const then = node[':then'];
+    node[':then'] = node[':else'];
+    node[':else'] = then;
+    return { applied: true };
+  }
+  return { applied: false, reason: 'no _if or :if with an else branch' };
+}
+
+export default {
+  name: 'swap-if',
+  artifacts: [PAGE_ARTIFACT, REQUEST_ARTIFACT, ENDPOINT_ARTIFACT, EVENTS_ARTIFACT],
+  enumerate,
+  apply,
+};