@far-world-labs/verblets 0.1.1

package/src/lib/parse-js-parts/index.js

@@ -0,0 +1,333 @@
+import { parse } from 'acorn';
+import * as walk from 'acorn-walk';
+import path from 'node:path';
+
+const stripRootDir = (filePath, root = process.cwd()) => {
+  return path.resolve('./', filePath).replace(new RegExp(`^${root}`), '');
+};
+
+const convertImport = (filePath, importPath) => {
+  return stripRootDir(path.resolve(path.dirname(filePath), importPath));
+};
+
+const scanFile = (file, code) => {
+  const functionsMap = {};
+  const functionsSeen = {};
+  const variablesMap = {};
+  const importsMap = {};
+  const exportsMap = {};
+
+  const comments = [];
+
+  const ast = parse(code, {
+    sourceType: 'module',
+    ecmaVersion: 'latest',
+    onComment: comments,
+  });
+
+  const commentsMap = comments.reduce((acc, comment) => {
+    const commentNew = { ...comment };
+    delete commentNew.value;
+    return { ...acc, [commentNew.start]: commentNew };
+  }, {});
+
+  walk.simple(ast, {
+    ImportDeclaration(importNode) {
+      const declaration = importNode.specifiers
+        .filter((s) => s.type === 'ImportDefaultSpecifier')
+        .map((s) => {
+          return s.local.name;
+        })?.[0];
+      const specifiers = importNode.specifiers
+        .filter((s) => s.type === 'ImportSpecifier')
+        .map((s) => {
+          return { ...s.imported }.name; // also has local name
+        });
+      const source = importNode.source.value;
+      const importKey = source.startsWith('.')
+        ? convertImport(file, source)
+        : source;
+      importsMap[importKey] = {
+        start: importNode.start,
+        end: importNode.end,
+        declaration,
+        specifiers,
+        source,
+      };
+    },
+
+    ExportNamedDeclaration(expNode) {
+      if (expNode.source) {
+        // Handle re-exports
+        const source = expNode.source.value;
+        const importKey = source.startsWith('.')
+          ? convertImport(file, source)
+          : source;
+
+        // Named exports
+        if (expNode.specifiers) {
+          expNode.specifiers.forEach((specifier) => {
+            if (specifier.type === 'ExportSpecifier') {
+              exportsMap[specifier.exported.name ?? specifier.local.name] = {
+                start: expNode.start,
+                end: expNode.end,
+                type: 'NamedExport',
+                local: specifier.exported.name ?? specifier.local.name,
+                source: importKey,
+              };
+              importsMap[importKey] = {
+                start: expNode.start,
+                end: expNode.end,
+                declaration: specifier.exported.name ?? specifier.local.name,
+                specifiers: [],
+                source,
+              };
+            } else if (specifier.type === 'ExportNamespaceSpecifier') {
+              exportsMap[specifier.exported.name ?? specifier.local.name] = {
+                start: expNode.start,
+                end: expNode.end,
+                type: 'NamespaceExport',
+                source: importKey,
+              };
+              importsMap[importKey] = {
+                start: expNode.start,
+                end: expNode.end,
+                declaration: null,
+                specifiers: [],
+                source,
+              };
+            }
+          });
+        }
+      } else if (expNode.declaration.type === 'VariableDeclaration') {
+        // Handle local exports
+        expNode.declaration.declarations.forEach((decNode) => {
+          exportsMap[decNode.id.name] = {
+            start: expNode.start,
+            end: expNode.end,
+            type: 'LocalExport',
+            local: decNode.id.name,
+          };
+
+          if (decNode.init.type === 'ArrowFunctionExpression') {
+            functionsMap[`ArrowFunctionExpression:${decNode.id.name}`] = {
+              start: decNode.init.start,
+              end: decNode.init.end,
+              name: decNode.id.name,
+              functionName: `<arrow:${decNode.id.name}>`,
+              async: decNode.init.async,
+              generator: decNode.init.generator,
+              type: 'ArrowFunctionExpression',
+              exported: true,
+            };
+          }
+        });
+      }
+    },
+
+    ExportAllDeclaration(expNode) {
+      if (expNode.source) {
+        const source = expNode.source.value;
+        const importKey = source.startsWith('.')
+          ? convertImport(file, source)
+          : source;
+        exportsMap[expNode.exported.name] = {
+          start: expNode.start,
+          end: expNode.end,
+          type: 'AllExport',
+          local: expNode.exported.name,
+          source: importKey,
+        };
+        importsMap[importKey] = {
+          start: expNode.start,
+          end: expNode.end,
+          declaration: null,
+          specifiers: [],
+          source,
+        };
+      }
+    },
+
+    ExportDefaultDeclaration(expNode) {
+      if (expNode.declaration.type === 'Identifier') {
+        exportsMap.default = {
+          type: 'LocalExport',
+          local: expNode.declaration.name,
+        };
+      } else if (expNode.declaration.type === 'ArrowFunctionExpression') {
+        exportsMap.default = {
+          type: 'DefaultExport',
+          start: expNode.start,
+          end: expNode.end,
+        };
+
+        functionsMap[`ArrowFunctionExpression:default`] = {
+          start: expNode.declaration.start,
+          end: expNode.declaration.end,
+          functionName: '<default-export>',
+          async: expNode.declaration.async,
+          generator: expNode.declaration.generator,
+          type: 'ArrowFunctionExpression',
+        };
+      }
+    },
+
+    FunctionDeclaration(fnNode) {
+      functionsMap[`${fnNode.type}:${fnNode.id.name}`] = {
+        start: fnNode.start,
+        end: fnNode.end,
+        functionName: `<declaration:${fnNode.id.name}>`,
+        name: fnNode.id.name,
+        type: fnNode.type,
+        async: fnNode.async,
+        generator: fnNode.generator,
+        exported: false,
+      };
+    },
+
+    VariableDeclaration(varNode) {
+      const arrowDeclarations = varNode.declarations.filter((d) => {
+        return (
+          d.id.type === 'Identifier' &&
+          d.init?.type === 'ArrowFunctionExpression' &&
+          d.init?.body.type === 'BlockStatement'
+        );
+      });
+
+      arrowDeclarations.forEach((arrowFnNode) => {
+        functionsSeen[
+          `${arrowFnNode.init.start}:${arrowFnNode.init.end}`
+        ] = true;
+
+        functionsMap[`ArrowFunctionExpression:${arrowFnNode.id.name}`] = {
+          start: arrowFnNode.start,
+          end: arrowFnNode.end,
+          name: arrowFnNode.id.name,
+          functionName: `<arrow:${arrowFnNode.id.name}>`,
+          async: arrowFnNode.init.async,
+          generator: arrowFnNode.init.generator,
+          type: 'ArrowFunctionExpression',
+          exported: false,
+        };
+      });
+
+      const fnExpDeclarations = varNode.declarations.filter((d) => {
+        return (
+          d.id.type === 'Identifier' &&
+          d.init?.type === 'FunctionExpression' &&
+          d.init?.body.type === 'BlockStatement'
+        );
+      });
+
+      fnExpDeclarations.forEach((fnExpNode) => {
+        functionsSeen[`${fnExpNode.init.start}:${fnExpNode.init.end}`] = true;
+
+        functionsMap[`FunctionExpression:${fnExpNode.id.name}`] = {
+          start: fnExpNode.start,
+          end: fnExpNode.end,
+          name: fnExpNode.id.name,
+          functionName: `<exp:${fnExpNode.id.name}>`,
+          async: fnExpNode.init.async,
+          generator: fnExpNode.init.generator,
+          type: 'FunctionExpression',
+          exported: false,
+        };
+      });
+    },
+
+    // Property Assignment
+    AssignmentExpression(node) {
+      if (
+        (node.right.type === 'FunctionExpression' ||
+          node.right.type === 'ArrowFunctionExpression') &&
+        node.value
+      ) {
+        functionsSeen[`${node.right.start}:${node.right.end}`] = true;
+
+        functionsMap[`${node.value.type}:${node.left.property.name}`] = {
+          start: node.start,
+          end: node.end,
+          name: node.left.property.name,
+          functionName: `${node.value.type}:${node.left.property.name}`,
+          async: node.right.async,
+          generator: node.right.generator,
+          type: node.right.type,
+          exported: false,
+        };
+      }
+    },
+
+    // Object Definition
+    Property(node) {
+      if (
+        node.value.type === 'FunctionExpression' ||
+        node.value.type === 'ArrowFunctionExpression'
+      ) {
+        functionsSeen[`${node.value.start}:${node.value.end}`] = true;
+
+        functionsMap[`Property:${node.key.name}`] = {
+          start: node.start,
+          end: node.end,
+          name: node.key.name,
+          functionName: `<property:${node.key.name}>`,
+          async: node.value.async,
+          generator: node.value.generator,
+          type: node.value.type,
+          exported: false,
+        };
+      }
+    },
+
+    // Class Definition
+    ClassDeclaration(node) {
+      const className = node.id.name;
+      node.body.body.forEach((classElement) => {
+        if (classElement.type === 'MethodDefinition') {
+          functionsSeen[
+            `${classElement.value.start}:${classElement.value.end}`
+          ] = true;
+
+          functionsMap[
+            `MethodDefinition:${className}.${classElement.key.name}`
+          ] = {
+            start: node.start,
+            end: node.end,
+            className: className,
+            functionName: `${className}.${classElement.key.name}`,
+            name: classElement.key.name,
+            async: classElement.value.async,
+            generator: classElement.value.generator,
+            type: 'MethodDefinition',
+            exported: false,
+          };
+        }
+      });
+    },
+  });
+
+  walk.simple(ast, {
+    FunctionExpression(node) {
+      if (!functionsSeen[`${node.start}:${node.end}`]) {
+        functionsMap[`${node.type}:${node.start}`] = {
+          start: node.start,
+          functionName: `<exp>`,
+          end: node.end,
+          type: node.type,
+          async: node.async,
+          generator: node.generator,
+        };
+      }
+    },
+  });
+
+  return {
+    name: stripRootDir(file),
+    functionsMap,
+    variablesMap,
+    importsMap,
+    exportsMap,
+    commentsMap,
+  };
+};
+
+export default scanFile;

package/src/lib/parse-js-parts/index.spec.js

@@ -0,0 +1,156 @@
+import { describe, expect, it } from 'vitest';
+import parseJSParts from './index.js';
+
+const examples = [
+  {
+    name: 'Single function declaration',
+    inputs: {
+      file: 'testFile.js',
+      code: `
+        import testModule from './testModule.js';
+
+        export function testFunc() {
+          return 'abc';
+        }
+      `,
+    },
+    want: {
+      name: 'testFile.js',
+      functionsMap: [
+        {
+          name: 'testFunc',
+          type: 'FunctionDeclaration',
+        },
+      ],
+      importsMap: [
+        {
+          declaration: 'testModule',
+          source: '/testModule.js',
+        },
+      ],
+    },
+  },
+  {
+    name: 'Arrow function declaration',
+    inputs: {
+      file: 'arrowFuncFile.js',
+      code: `
+      import arrowModule from './arrowModule.js';
+
+      export const arrowFunc = () => {
+        return 'xyz';
+      };
+    `,
+    },
+    want: {
+      name: 'arrowFuncFile.js',
+      functionsMap: [
+        {
+          name: 'arrowFunc',
+          type: 'ArrowFunctionExpression',
+        },
+      ],
+      importsMap: [
+        {
+          declaration: 'arrowModule',
+          source: '/arrowModule.js',
+        },
+      ],
+    },
+  },
+  {
+    name: 'Class method declaration',
+    inputs: {
+      file: 'classMethodFile.js',
+      code: `
+      export class MyClass {
+        myMethod() {
+          return 'Hello World';
+        }
+      }
+    `,
+    },
+    want: {
+      name: 'classMethodFile.js',
+      functionsMap: [
+        {
+          className: 'MyClass',
+          name: 'myMethod',
+          type: 'MethodDefinition',
+        },
+      ],
+      importsMap: [],
+    },
+  },
+  {
+    name: 'Multiple function declarations',
+    inputs: {
+      file: 'multipleFunctionsFile.js',
+      code: `
+      import additionalModule from './additionalModule.js';
+
+      export function firstFunc() {
+        return 'First';
+      }
+
+      export const secondFunc = () => {
+        return 'Second';
+      };
+
+      export class ThirdClass {
+        thirdFunc() {
+          return 'Third';
+        }
+      }
+    `,
+    },
+    want: {
+      name: 'multipleFunctionsFile.js',
+      functionsMap: [
+        {
+          name: 'firstFunc',
+          type: 'FunctionDeclaration',
+        },
+        {
+          name: 'secondFunc',
+          type: 'ArrowFunctionExpression',
+        },
+        {
+          className: 'ThirdClass',
+          name: 'thirdFunc',
+          type: 'MethodDefinition',
+        },
+      ],
+      importsMap: [
+        {
+          declaration: 'additionalModule',
+          source: '/additionalModule.js',
+        },
+      ],
+    },
+  },
+];
+
+describe('Parse JS parts', () => {
+  examples.forEach((example) => {
+    it(example.name, () => {
+      const result = parseJSParts(example.inputs.file, example.inputs.code);
+
+      if (example.want.functionsMap) {
+        example.want.functionsMap.forEach((fn) => {
+          const found =
+            result.functionsMap[`${fn.type}:${fn.name}`]?.name ||
+            result.functionsMap[`${fn.type}:${fn.className}.${fn.name}`]?.name;
+          expect(fn.name).equals(found);
+        });
+      }
+      if (example.want.importsMap) {
+        example.want.importsMap.forEach((importDef) => {
+          expect(importDef.declaration).equals(
+            result.importsMap[`${importDef.source}`]?.declaration
+          );
+        });
+      }
+    });
+  });
+});

package/src/lib/path-aliases/index.js

@@ -0,0 +1,39 @@
+const defaultDelimiter = '/';
+
+/**
+ * Splits sequences using the given delimiter.
+ * @param {string[]} sequences - An array of strings.
+ * @param {string} delimiter - Delimiter to split the sequences.
+ * @returns {string[][]} - An array of split sequences.
+ */
+const splitSequences = (sequences, delimiter = defaultDelimiter) =>
+  sequences.map((sequence) => sequence.split(delimiter));
+
+/**
+ * Creates unique sequence tails for the given sequences.
+ * @param {string[]} sequences - An array of strings.
+ * @param {string} delimiter - Delimiter to split and join the sequences.
+ * @returns {Object} - An object mapping the original path to its unique tail.
+ */
+export default (sequences, delimiter = defaultDelimiter) => {
+  const splitSequencesList = splitSequences(sequences, delimiter);
+  const tailsUnique = {};
+
+  sequences.forEach((sequence, index) => {
+    const splitSequence = splitSequencesList[index];
+
+    for (let i = 1; i <= splitSequence.length; i += 1) {
+      const tail = splitSequence.slice(-i).join(delimiter);
+      const conflictingSequences = sequences.filter((seq) =>
+        seq.endsWith(tail)
+      );
+
+      if (conflictingSequences.length === 1) {
+        tailsUnique[sequence] = tail;
+        break;
+      }
+    }
+  });
+
+  return tailsUnique;
+};

package/src/lib/path-aliases/index.spec.js

@@ -0,0 +1,70 @@
+import * as R from 'ramda';
+import { describe, expect, it } from 'vitest';
+
+import testAdvice from '../../chains/test-advice/index.js';
+import alias from './index.js';
+
+const examples = [
+  {
+    name: 'Basic usage',
+    inputs: {
+      sequences: ['foo/bar/baz.js', 'foo/biz/baz.js', 'foo/biz/qux.js'],
+    },
+    want: {
+      'foo/bar/baz.js': 'bar/baz.js',
+      'foo/biz/baz.js': 'biz/baz.js',
+      'foo/biz/qux.js': 'qux.js',
+    },
+  },
+  {
+    name: 'Deeper conflict',
+    inputs: {
+      sequences: ['a/y/x/w/v.js', 'b/y/z/w/v.js'],
+      delimiter: '/',
+    },
+    want: {
+      'a/y/x/w/v.js': 'x/w/v.js',
+      'b/y/z/w/v.js': 'z/w/v.js',
+    },
+  },
+  {
+    name: 'No delimiter conflict',
+    inputs: {
+      sequences: ['192.168.0.1', '192.168.1.1', '10.0.0.1'],
+      delimiter: '.',
+    },
+    want: {
+      '192.168.0.1': '168.0.1',
+      '192.168.1.1': '1.1',
+      '10.0.0.1': '0.0.1',
+    },
+  },
+];
+
+describe('Path aliases', async () => {
+  examples.forEach((example) => {
+    it(example.name, () => {
+      const got = alias(example.inputs.sequences, example.inputs.delimiter);
+      const gotSorted = R.sort(
+        ([k1], [k2]) => k1.localeCompare(k2),
+        Object.entries(got)
+      );
+      const wantSorted = R.sort(
+        ([k1], [k2]) => k1.localeCompare(k2),
+        Object.entries(example.want)
+      );
+
+      expect(gotSorted).toStrictEqual(wantSorted);
+    });
+  });
+});
+
+describe('Path aliases - advice', async () => {
+  const advices = await testAdvice('./src/lib/path-aliases/index.js');
+
+  advices.forEach((a) => {
+    it(a.name, () => expect(true).toBe(true));
+  });
+
+  it('Trigger failure', () => expect(advices.length).toBe(0));
+});

package/src/lib/pave/index.js

@@ -0,0 +1,34 @@
+/**
+ * Pave a nested object structure or array based on a dot-separated path.
+ * @param {Object|Array} obj - The object or array to modify.
+ * @param {string} path - The dot-separated path indicating where to set the value.
+ * @param {*} value - The value to set at the specified path.
+ */
+export default (obj, path, value) => {
+  const pathRe = /^([^.]+(\.[^.]+)*)$/;
+
+  if (!pathRe.test(path)) {
+    throw new Error(`Invalid path: "${path}"`);
+  }
+
+  const keys = path.split('.');
+  const objNew = JSON.parse(JSON.stringify(obj));
+  let objMutating = objNew;
+
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = Number.isNaN(parseInt(keys[i], 10))
+      ? keys[i]
+      : parseInt(keys[i], 10);
+
+    if (i === keys.length - 1) {
+      objMutating[key] = value;
+    } else {
+      if (!objMutating[key]) {
+        objMutating[key] = Number.isNaN(parseInt(keys[i + 1], 10)) ? {} : [];
+      }
+      objMutating = objMutating[key];
+    }
+  }
+
+  return objNew;
+};

package/src/lib/pave/index.spec.js

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+
+import pave from './index.js';
+
+const examples = [
+  {
+    name: 'Set a nested object value',
+    inputs: { obj: {}, path: 'a.b.c', value: 42 },
+    want: { result: { a: { b: { c: 42 } } } },
+  },
+  {
+    name: 'Set a nested array value',
+    inputs: { obj: [], path: '0.1.2', value: 42 },
+    want: { result: [[undefined, [undefined, undefined, 42]]] },
+  },
+  {
+    name: 'Set a mixed object and array value',
+    inputs: { obj: {}, path: 'a.0.b', value: 42 },
+    want: { result: { a: [{ b: 42 }] } },
+  },
+  {
+    name: 'Set a value on an existing object',
+    inputs: { obj: { x: { y: 1 } }, path: 'x.z', value: 2 },
+    want: { result: { x: { y: 1, z: 2 } } },
+  },
+  {
+    name: 'Set a value on an existing array',
+    inputs: { obj: [0, [1]], path: '1.2', value: 3 },
+    want: { result: [0, [1, undefined, 3]] },
+  },
+  {
+    name: 'Override an existing value in an object',
+    inputs: { obj: { a: { b: 1 } }, path: 'a.b', value: 99 },
+    want: { result: { a: { b: 99 } } },
+  },
+  {
+    name: 'Override an existing value in an array',
+    inputs: { obj: [0, [1, 2]], path: '1.1', value: 99 },
+    want: { result: [0, [1, 99]] },
+  },
+  {
+    name: 'Set a value with an empty path (throws)',
+    inputs: { obj: { x: 1 }, path: '', value: 42 },
+    want: { throws: true },
+  },
+  {
+    name: 'Set a value with an invalid path (throws)',
+    inputs: { obj: { x: 1 }, path: '.', value: 42 },
+    want: { throws: true },
+  },
+  {
+    name: 'Set a value with a single element path on an object',
+    inputs: { obj: {}, path: 'a', value: 42 },
+    want: { result: { a: 42 } },
+  },
+];
+
+describe('pave', () => {
+  examples.forEach((example) => {
+    it(example.name, () => {
+      const { obj } = example.inputs;
+
+      if (example.want.throws) {
+        expect(() =>
+          pave(obj, example.inputs.path, example.inputs.value)
+        ).toThrow();
+      } else {
+        const result = pave(obj, example.inputs.path, example.inputs.value);
+        expect(result).toEqual(example.want.result);
+      }
+    });
+  });
+});