@platformos/platformos-check-common 0.0.2

package/src/utils/types.ts

@@ -0,0 +1,57 @@
+/**
+ * ArgumentTypes extracts the type of the arguments of a function.
+ *
+ * @example
+ *
+ * function doStuff(a: number, b: string) {
+ *   // do stuff
+ * }
+ *
+ * type DoStuffArgs = ArgumentTypes<typeof doStuff> // = [number, string].
+ */
+export type ArgumentTypes<F extends Function> = F extends (...args: infer T) => void ? T : never;
+
+/**
+ * WithOptional<T, K> turns the properties K of type T optional.
+ *
+ * @example
+ *
+ * interface Dependencies {
+ *   log(msg: string): void;
+ *   loadConfig(uri: string): Config;
+ * }
+ *
+ * function check({
+ *  log = defaultLogger,
+ *  loadConfig,
+ * }: WithOptional<Dependencies, 'log'>) {
+ *   // log can be undefined and we'll use the default value.
+ *   // but loadConfig is not optional
+ * }
+ */
+export type WithOptional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+
+/**
+ * WithRequired<T, K> turns the optional properties K in keyof T as required.
+ */
+export type WithRequired<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
+
+/**
+ * assertNever(x: never);
+ *
+ * You use this in the default case of switch statements to make sure you
+ * exhaust your discriminated union.
+ *
+ * If you don't, typescript is going to complain that assertNever is being
+ * called with a non-never value.
+ *
+ * @example
+ * switch (fruit.type) {
+ *   case BANANA: // ...
+ *   case APPLE: // ...
+ *   default: return assertNever(fruit.type);
+ * }
+ */
+export function assertNever(x: never): never {
+  throw new Error(`We should never reach this code, you are missing a case for ${x}`);
+}

package/src/visitor.spec.ts

@@ -0,0 +1,163 @@
+import { LiquidHtmlNode, LiquidHtmlNodeTypes, SourceCodeType } from './types';
+import { toJSONAST, toLiquidHTMLAST, toSourceCode } from './to-source-code';
+import { expect, describe, it, assert } from 'vitest';
+import { Visitor, findCurrentNode, findJSONNode, visit } from './visitor';
+import { NodeTypes } from '@platformos/liquid-html-parser';
+
+describe('Module: visitor', () => {
+  it('should return an array of the return type of the visitor', async () => {
+    const visitor: Visitor<SourceCodeType.LiquidHtml, string> = {
+      LiquidTag: async (node) => {
+        if (node.name !== 'render' && node.name !== 'include') {
+          return;
+        }
+
+        if (
+          typeof node.markup === 'string' ||
+          node.markup.snippet.type === LiquidHtmlNodeTypes.VariableLookup
+        ) {
+          return;
+        }
+
+        return node.markup.snippet.value;
+      },
+    };
+
+    const ast = toAST(`
+      {% render 'a' %}
+      {% render block %}
+      {% include 'b' %}
+    `);
+
+    expect(await visit(ast!, visitor)).to.eql(['a', 'b']);
+  });
+
+  function toAST(code: string) {
+    return toSourceCode('/tmp/foo.liquid', code).ast as LiquidHtmlNode;
+  }
+});
+
+describe('findCurrentNode', () => {
+  it.each([
+    {
+      desc: 'at the end of a tag name',
+      source: '{% render█ "a" %}',
+      expected: NodeTypes.LiquidTag,
+      ancestors: [NodeTypes.Document],
+    },
+    {
+      desc: 'at the end of a lookup',
+      source: '{{ product.title█ }}',
+      expected: NodeTypes.String,
+      ancestors: [
+        NodeTypes.Document,
+        NodeTypes.LiquidVariableOutput,
+        NodeTypes.LiquidVariable,
+        NodeTypes.VariableLookup,
+      ],
+    },
+    {
+      desc: 'at the beginning of a lookup',
+      source: '{{ product.█title }}',
+      expected: NodeTypes.String,
+      ancestors: [
+        NodeTypes.Document,
+        NodeTypes.LiquidVariableOutput,
+        NodeTypes.LiquidVariable,
+        NodeTypes.VariableLookup,
+      ],
+    },
+    {
+      desc: 'at the start of a condition',
+      source: '{% if █cond %}{% endif %}',
+      expected: NodeTypes.VariableLookup,
+      ancestors: [NodeTypes.Document, NodeTypes.LiquidTag],
+    },
+    {
+      desc: 'at the start of a child condition',
+      source: '{% if cond %}{% elsif █cond %}{% endif %}',
+      expected: NodeTypes.VariableLookup,
+      ancestors: [NodeTypes.Document, NodeTypes.LiquidTag, NodeTypes.LiquidBranch],
+    },
+    {
+      desc: 'at the start of a comparison',
+      source: '{% if █cond < b %}{% endif %}',
+      expected: NodeTypes.VariableLookup,
+      ancestors: [NodeTypes.Document, NodeTypes.LiquidTag, NodeTypes.Comparison],
+    },
+    {
+      desc: 'at the start of a logical expression',
+      source: '{% if █cond and b %}{% endif %}',
+      expected: NodeTypes.VariableLookup,
+      ancestors: [NodeTypes.Document, NodeTypes.LiquidTag, NodeTypes.LogicalExpression],
+    },
+    {
+      desc: 'at the start of a named-variable variable lookup',
+      source: '{{ product[█key] }}',
+      expected: NodeTypes.VariableLookup,
+      ancestors: [
+        NodeTypes.Document,
+        NodeTypes.LiquidVariableOutput,
+        NodeTypes.LiquidVariable,
+        NodeTypes.VariableLookup,
+      ],
+    },
+    {
+      desc: 'between the end of a text node and the start of a tag',
+      source: '{% if open %}<div>foo█{% else %}</div>{% endif %}',
+      expected: NodeTypes.TextNode,
+      ancestors: [
+        NodeTypes.Document,
+        NodeTypes.LiquidTag,
+        NodeTypes.LiquidBranch,
+        NodeTypes.HtmlElement,
+      ],
+    },
+  ])('should find the current node and ancestors when $desc', ({ source, expected, ancestors }) => {
+    const CURSOR = '█';
+    const offset = source.indexOf(CURSOR);
+    const ast = toLiquidHTMLAST(source.replace(CURSOR, ''));
+    assert(!(ast instanceof Error), 'AST should not be an error');
+
+    const [currentNode, actualAncestors] = findCurrentNode(ast, offset);
+
+    expect(actualAncestors.map((x) => x.type)).to.eql(ancestors, `In "${source}"`);
+    expect(currentNode.type).to.equal(expected, `In "${source}"`);
+  });
+
+  describe('findJSONNode', () => {
+    it.each([
+      {
+        desc: 'string value',
+        source: '{ "key": "█t:value" }',
+        expected: 'Literal',
+        ancestors: ['Object', 'Property'],
+      },
+      {
+        desc: 'string key',
+        source: '{ "█key": "t:value" }',
+        expected: 'Identifier',
+        ancestors: ['Object', 'Property'],
+      },
+      {
+        desc: 'nested string value',
+        source: '{ "key": { "key2": "█t:value" } }',
+        expected: 'Literal',
+        ancestors: ['Object', 'Property', 'Object', 'Property'],
+      },
+    ])(
+      'should find the current node when the target is $desc',
+      ({ source, expected, ancestors }) => {
+        const CURSOR = '█';
+        const offset = source.indexOf(CURSOR);
+        const ast = toJSONAST(source.replace(CURSOR, ''));
+        assert(!(ast instanceof Error), 'AST should not be an error');
+
+        const [currentNode, actualAncestors] = findJSONNode(ast, offset);
+
+        expect(actualAncestors.map((x) => x.type)).to.eql(ancestors, `In "${source}"`);
+        expect(currentNode.type).to.equal(expected, `In "${source}"`);
+      },
+    );
+  });
+});

package/src/visitor.ts

@@ -0,0 +1,161 @@
+import { NodeTypes as LiquidHtmlNodeTypes } from '@platformos/liquid-html-parser';
+import { AST, LiquidHtmlNode, NodeOfType, SourceCodeType, NodeTypes, JSONNode } from './types';
+
+export type VisitorMethod<S extends SourceCodeType, T, R> = (
+  node: NodeOfType<S, T>,
+  ancestors: AST[S][],
+) => Promise<R | R[] | undefined>;
+
+export type Visitor<S extends SourceCodeType, R> = {
+  /** Happens once per node, while going down the tree */
+  [T in NodeTypes[S]]?: VisitorMethod<S, T, R>;
+};
+
+function isNode<S extends SourceCodeType>(x: any): x is NodeOfType<S, NodeTypes[S]> {
+  return x !== null && typeof x === 'object' && typeof x.type === 'string';
+}
+
+export type ExecuteFunction<S extends SourceCodeType> = (node: AST[S], lineage: AST[S][]) => void;
+
+/**
+ * @example
+ *
+ * const links = visit<'LiquidHTML', DocumentLink>(liquidAST, {
+ *   'LiquidTag': (node, ancestors) => {
+ *     if (node.name === 'render' || node.name === 'include') {
+ *       return DocumentLink.create(...);
+ *     }
+ *   },
+ * })
+ *
+ * Note: this is the ChatGPT-rewritten version of the recursive method.
+ * If you want to refactor it, just ask it to do it for you :P
+ */
+export async function visit<S extends SourceCodeType, R>(
+  node: AST[S],
+  visitor: Visitor<S, R>,
+): Promise<R[]> {
+  const results: R[] = [];
+  const stack: { node: AST[S]; lineage: AST[S][] }[] = [{ node, lineage: [] }];
+  const pushStack = (node: AST[S], lineage: AST[S][]) => stack.push({ node, lineage });
+
+  while (stack.length > 0) {
+    // Visit current node
+    const { node, lineage } = stack.pop() as {
+      node: AST[S];
+      lineage: AST[S][];
+    };
+
+    const visitNode = visitor[node.type as any as NodeTypes[S]];
+    const result = visitNode
+      ? await Promise.resolve(visitNode(node as NodeOfType<S, NodeTypes[S]>, lineage))
+      : undefined;
+    if (Array.isArray(result)) {
+      results.push(...result);
+    } else if (result !== undefined) {
+      results.push(result);
+    }
+
+    // Enqueue child nodes
+    forEachChildNodes(node, lineage.concat(node), pushStack);
+  }
+
+  return results;
+}
+
+export function forEachChildNodes<S extends SourceCodeType>(
+  node: AST[S],
+  lineage: AST[S][],
+  execute: ExecuteFunction<S>,
+) {
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (let i = value.length - 1; i >= 0; i--) {
+        execute(value[i], lineage);
+      }
+    } else if (isNode<S>(value)) {
+      execute(value, lineage);
+    }
+  }
+}
+
+export function findCurrentNode(
+  ast: LiquidHtmlNode,
+  cursorPosition: number,
+): [node: LiquidHtmlNode, ancestors: LiquidHtmlNode[]] {
+  let prev: LiquidHtmlNode | undefined;
+  let current: LiquidHtmlNode = ast;
+  let ancestors: LiquidHtmlNode[] = [];
+
+  while (current !== prev) {
+    prev = current;
+    forEachChildNodes<SourceCodeType.LiquidHtml>(
+      current,
+      ancestors.concat(current),
+      (child, lineage) => {
+        if (
+          isUnclosed(child) ||
+          (isCovered(child, cursorPosition) && size(child) <= size(current))
+        ) {
+          current = child;
+          ancestors = lineage;
+        }
+      },
+    );
+  }
+
+  return [current, ancestors];
+}
+
+function isCovered(node: LiquidHtmlNode, offset: number): boolean {
+  switch (node.type) {
+    // `product.█title` should cover `title`
+    case LiquidHtmlNodeTypes.String:
+    // `if █cond` should cover `cond`
+    case LiquidHtmlNodeTypes.VariableLookup:
+    // `if █cond and other` should cover `cond`
+    case LiquidHtmlNodeTypes.LogicalExpression:
+    // `if █cond < other` should cover `cond`
+    case LiquidHtmlNodeTypes.Comparison:
+      return node.position.start <= offset && offset <= node.position.end;
+
+    // default case avoids ambiguity by having the cursor in the [excluded, included] range
+    default:
+      return node.position.start < offset && offset <= node.position.end;
+  }
+}
+
+function size(node: LiquidHtmlNode): number {
+  return node.position.end - node.position.start;
+}
+
+function isUnclosed(node: LiquidHtmlNode): boolean {
+  if ('blockEndPosition' in node) {
+    return node.blockEndPosition?.end === -1;
+  } else if ('children' in node) {
+    return node.children!.length > 0;
+  }
+  return false;
+}
+
+export function findJSONNode(
+  ast: JSONNode,
+  cursorPosition: number,
+): [node: JSONNode, ancestors: JSONNode[]] {
+  let prev: JSONNode | undefined;
+  let current: JSONNode = ast;
+  let ancestors: JSONNode[] = [];
+  const offset = cursorPosition;
+
+  while (current !== prev) {
+    prev = current;
+    forEachChildNodes<SourceCodeType.JSON>(current, ancestors.concat(current), (child, lineage) => {
+      if (child.loc.start.offset <= offset && offset < child.loc.end.offset) {
+        current = child;
+        ancestors = lineage;
+      }
+    });
+  }
+
+  return [current, ancestors];
+}

package/src/visitors/index.ts

@@ -0,0 +1,2 @@
+export { visitLiquid } from './liquid';
+export { visitJSON } from './json';

package/src/visitors/json.ts

@@ -0,0 +1,41 @@
+import { JSONNode, CheckNodeMethod, JSONCheck, SourceCodeType } from '../types';
+
+function isJSONNode(thing: unknown): thing is JSONNode {
+  return !!thing && typeof thing === 'object' && 'type' in thing;
+}
+
+const nonTraversableProperties = new Set(['loc']);
+
+export async function visitJSON(node: JSONNode, check: JSONCheck): Promise<void> {
+  const stack: { node: JSONNode; ancestors: JSONNode[] }[] = [{ node, ancestors: [] }];
+  let method: CheckNodeMethod<SourceCodeType.JSON, any> | undefined;
+
+  while (stack.length > 0) {
+    const { node, ancestors } = stack.pop()!;
+    const lineage = ancestors.concat(node);
+
+    method = check[node.type];
+    if (method) await method(node, ancestors);
+
+    for (const key in node) {
+      if (!node.hasOwnProperty(key) || nonTraversableProperties.has(key)) {
+        continue;
+      }
+
+      const value = node[key as keyof JSONNode];
+      if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--) {
+          const item = value[i];
+          if (isJSONNode(item)) {
+            stack.push({ node: item, ancestors: lineage });
+          }
+        }
+      } else if (isJSONNode(value)) {
+        stack.push({ node: value, ancestors: lineage });
+      }
+    }
+
+    method = check[`${node.type}:exit`];
+    if (method) await method(node, ancestors);
+  }
+}

package/src/visitors/liquid.ts

@@ -0,0 +1,40 @@
+import { nonTraversableProperties } from '@platformos/liquid-html-parser';
+import { LiquidHtmlNode, CheckNodeMethod, LiquidCheck, SourceCodeType } from '../types';
+
+function isLiquidHtmlNode(thing: unknown): thing is LiquidHtmlNode {
+  return !!thing && typeof thing === 'object' && 'type' in thing;
+}
+
+export async function visitLiquid(node: LiquidHtmlNode, check: LiquidCheck): Promise<void> {
+  const stack: { node: LiquidHtmlNode; ancestors: LiquidHtmlNode[] }[] = [{ node, ancestors: [] }];
+  let method: CheckNodeMethod<SourceCodeType.LiquidHtml, any> | undefined;
+
+  while (stack.length > 0) {
+    const { node, ancestors } = stack.pop()!;
+    const lineage = ancestors.concat(node);
+
+    method = check[node.type];
+    if (method) await method(node, ancestors);
+
+    for (const key in node) {
+      if (!node.hasOwnProperty(key) || nonTraversableProperties.has(key)) {
+        continue;
+      }
+
+      const value = node[key as keyof LiquidHtmlNode];
+      if (Array.isArray(value)) {
+        for (let i = value.length - 1; i >= 0; i--) {
+          const item = value[i];
+          if (isLiquidHtmlNode(item)) {
+            stack.push({ node: item, ancestors: lineage });
+          }
+        }
+      } else if (isLiquidHtmlNode(value)) {
+        stack.push({ node: value, ancestors: lineage });
+      }
+    }
+
+    method = check[`${node.type}:exit`];
+    if (method) await method(node, ancestors);
+  }
+}

package/tsconfig.build.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["**/*.spec.ts"],
+  "references": [
+    { "path": "../liquid-html-parser/tsconfig.build.json" },
+    { "path": "../platformos-common/tsconfig.build.json" }
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": [
+    "./src/**/*.ts",
+    "./src/**/*.json"
+  ],
+  "exclude": [
+    "./dist"
+  ],
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "tsBuildInfoFile": "dist/tsconfig.tsbuildinfo",
+    "paths": {
+      "@platformos/liquid-html-parser": [
+        "../liquid-html-parser/src"
+      ],
+      "@platformos/platformos-common": [
+        "../platformos-common/src"
+      ],
+    }
+  },
+  "references": [
+    {
+      "path": "../liquid-html-parser"
+    },
+    {
+      "path": "../platformos-common"
+    },
+  ]
+}