@platformos/platformos-check-common 0.0.2

package/src/utils/block.ts

@@ -0,0 +1,300 @@
+import {
+  JSONNode,
+  LiteralNode,
+  Preset,
+  Section,
+  SourceCodeType,
+  ThemeBlock,
+  Context,
+  StaticBlockDef,
+} from '../types';
+import { getLocEnd, getLocStart, nodeAtPath } from '../json';
+import { doesFileExist } from './file-utils';
+
+export type BlockDefNodeWithPath = {
+  node: Section.Block | ThemeBlock.Block;
+  path: string[];
+};
+
+export type PresetBlockNodeWithPath = {
+  node: Preset.Block;
+  path: string[];
+};
+
+export function getBlocks(validSchema: ThemeBlock.Schema | Section.Schema) {
+  const rootLevelThemeBlocks: BlockDefNodeWithPath[] = [];
+  const rootLevelLocalBlocks: BlockDefNodeWithPath[] = [];
+  const presetLevelBlocks: { [key: number]: PresetBlockNodeWithPath[] } = {};
+  const defaultLevelBlocks: BlockDefNodeWithPath[] = [];
+
+  const rootLevelBlocks = validSchema.blocks;
+  const presets = validSchema.presets;
+
+  // Helper function to categorize blocks
+  function categorizeRootLevelBlocks(block: Preset.Block, index: number) {
+    if (!block) return;
+    const hasName = 'name' in block;
+
+    if (hasName) {
+      rootLevelLocalBlocks.push({
+        node: block,
+        path: ['blocks', String(index), 'type'],
+      });
+    } else if (block.type !== '@app') {
+      rootLevelThemeBlocks.push({
+        node: block,
+        path: ['blocks', String(index), 'type'],
+      });
+    }
+  }
+
+  function categorizePresetLevelBlocks(
+    block: Preset.Block,
+    currentPath: string[],
+    depth: number = 0,
+  ) {
+    if (!block) return;
+
+    if (!presetLevelBlocks[depth]) {
+      presetLevelBlocks[depth] = [];
+    }
+
+    presetLevelBlocks[depth].push({
+      node: block,
+      path: currentPath.concat('type'),
+    });
+
+    if ('blocks' in block) {
+      if (Array.isArray(block.blocks)) {
+        block.blocks.forEach((nestedBlock: Preset.PresetBlockForArray, index: number) => {
+          categorizePresetLevelBlocks(
+            nestedBlock,
+            currentPath.concat('blocks', String(index)),
+            depth + 1,
+          );
+        });
+      } else if (typeof block.blocks === 'object' && block.blocks !== null) {
+        Object.entries(block.blocks).forEach(([key, nestedBlock]) => {
+          categorizePresetLevelBlocks(nestedBlock, currentPath.concat('blocks', key), depth + 1);
+        });
+      }
+    }
+  }
+
+  function categorizeDefaultLevelBlocks(block: Preset.Block, index: number) {
+    const hasName = 'name' in block;
+
+    if (hasName) {
+      defaultLevelBlocks.push({
+        node: block,
+        path: ['default', 'blocks', String(index), 'type'],
+      });
+    }
+  }
+
+  if (Array.isArray(rootLevelBlocks)) {
+    rootLevelBlocks.forEach((block, index) => {
+      categorizeRootLevelBlocks(block, index);
+    });
+  }
+
+  if (presets) {
+    presets.forEach((preset: Preset.Preset, presetIndex: number) => {
+      if ('blocks' in preset && preset.blocks) {
+        if (Array.isArray(preset.blocks)) {
+          preset.blocks.forEach((block, blockIndex) => {
+            categorizePresetLevelBlocks(
+              block,
+              ['presets', String(presetIndex), 'blocks', String(blockIndex)],
+              0,
+            );
+          });
+        } else if (typeof preset.blocks === 'object') {
+          Object.entries(preset.blocks).forEach(([key, block]) => {
+            categorizePresetLevelBlocks(block, ['presets', String(presetIndex), 'blocks', key], 0);
+          });
+        }
+      }
+    });
+  }
+
+  if ('default' in validSchema) {
+    validSchema.default?.blocks?.forEach((block, index) => {
+      categorizeDefaultLevelBlocks(block, index);
+    });
+  }
+
+  return {
+    rootLevelThemeBlocks,
+    rootLevelLocalBlocks,
+    presetLevelBlocks,
+    defaultLevelBlocks,
+  };
+}
+
+export function isInvalidPresetBlock(
+  blockId: string,
+  blockNode: Preset.Block,
+  rootLevelThemeBlocks: BlockDefNodeWithPath[],
+  staticBlockDefs: StaticBlockDef[],
+): boolean {
+  if (blockNode.static) {
+    return !staticBlockDefs.some((block) => block.type === blockNode.type && block.id === blockId);
+  }
+
+  const isPrivateBlockType = blockNode.type.startsWith('_');
+  const isThemeInRootLevel = rootLevelThemeBlocks.some((block) => block.node.type === '@theme');
+  const needsExplicitRootBlock = isPrivateBlockType || !isThemeInRootLevel;
+  const isPresetInRootLevel = rootLevelThemeBlocks.some(
+    (block) => block.node.type === blockNode.type,
+  );
+
+  return !isPresetInRootLevel && needsExplicitRootBlock;
+}
+
+export function isInvalidDefaultBlock(
+  blockNode: Section.Block | ThemeBlock.Block,
+  rootLevelThemeBlocks: BlockDefNodeWithPath[],
+): boolean {
+  const isPrivateBlockType = blockNode.type.startsWith('_');
+  const isThemeInRootLevel = rootLevelThemeBlocks.some((block) => block.node.type === '@theme');
+  const needsExplicitRootBlock = isPrivateBlockType || !isThemeInRootLevel;
+  const isDefaultInRootLevel = rootLevelThemeBlocks.some(
+    (block) => block.node.type === blockNode.type,
+  );
+
+  return !isDefaultInRootLevel && needsExplicitRootBlock;
+}
+
+async function validateBlockTargeting(
+  nestedBlock: Preset.PresetBlockForArray | Preset.PresetBlockForHash,
+  nestedPath: string[],
+  context: Context<SourceCodeType.LiquidHtml>,
+  parentNode: Preset.PresetBlockForArray | Preset.PresetBlockForHash,
+  rootLevelThemeBlocks: BlockDefNodeWithPath[],
+  allowedBlockTypes: string[],
+  offset: number,
+  ast: JSONNode,
+  staticBlockDefs: StaticBlockDef[] = [],
+) {
+  const typeNode = nodeAtPath(ast, nestedPath)! as LiteralNode;
+  const blockId = 'id' in nestedBlock ? nestedBlock.id! : nestedPath.at(-2)!;
+
+  if (typeNode) {
+    if (isInvalidPresetBlock(blockId, nestedBlock, rootLevelThemeBlocks, staticBlockDefs)) {
+      const isStaticBlock = !!nestedBlock.static;
+      const isPrivateBlock = nestedBlock.type.startsWith('_');
+      const errorMessage = isStaticBlock
+        ? `Could not find a static block of type "${nestedBlock.type}" with id "${blockId}" in "blocks/${parentNode.type}.liquid".`
+        : isPrivateBlock
+        ? `Private block type "${nestedBlock.type}" is not allowed in "${parentNode.type}" blocks.`
+        : `Block type "${nestedBlock.type}" is not allowed in "${
+            parentNode.type
+          }" blocks. Allowed types are: ${allowedBlockTypes.join(', ')}.`;
+      reportWarning(errorMessage, offset, typeNode, context);
+    }
+
+    const exists = await validateBlockFileExistence(nestedBlock.type, context);
+
+    if (!exists) {
+      reportWarning(
+        `Theme block 'blocks/${nestedBlock.type}.liquid' does not exist.`,
+        offset,
+        typeNode,
+        context,
+      );
+    }
+  }
+
+  if ('blocks' in nestedBlock && nestedBlock.blocks) {
+    validateNestedBlocks(
+      context,
+      nestedBlock,
+      nestedBlock.blocks,
+      nestedPath.slice(0, -1),
+      offset,
+      ast,
+    );
+  }
+}
+
+export async function validateNestedBlocks(
+  context: Context<SourceCodeType.LiquidHtml>,
+  parentNode: Preset.PresetBlockForHash | Preset.PresetBlockForArray,
+  nestedBlocks: Preset.PresetBlockHash | Preset.PresetBlockForArray[],
+  currentPath: string[],
+  offset: number,
+  ast: JSONNode,
+) {
+  if (!nestedBlocks) return;
+
+  const parentSchema = await context.getBlockSchema?.(parentNode.type);
+  if (!parentSchema || parentSchema instanceof Error) return;
+
+  const { validSchema, staticBlockDefs } = parentSchema;
+  if (!validSchema || validSchema instanceof Error) return;
+
+  const { rootLevelThemeBlocks } = getBlocks(validSchema);
+  const allowedBlockTypes = rootLevelThemeBlocks.map((block) => block.node.type);
+
+  if (Array.isArray(nestedBlocks)) {
+    await Promise.all(
+      nestedBlocks.map((nestedBlock, index) => {
+        const nestedPath = currentPath.concat(['blocks', String(index), 'type']);
+        return validateBlockTargeting(
+          nestedBlock,
+          nestedPath,
+          context,
+          parentNode,
+          rootLevelThemeBlocks,
+          allowedBlockTypes,
+          offset,
+          ast,
+          staticBlockDefs,
+        );
+      }),
+    );
+  } else if (typeof nestedBlocks === 'object') {
+    await Promise.all(
+      Object.entries(nestedBlocks).map(([key, nestedBlock]) => {
+        const nestedPath = currentPath.concat(['blocks', key, 'type']);
+        return validateBlockTargeting(
+          nestedBlock,
+          nestedPath,
+          context,
+          parentNode,
+          rootLevelThemeBlocks,
+          allowedBlockTypes,
+          offset,
+          ast,
+          staticBlockDefs,
+        );
+      }),
+    );
+  }
+}
+
+export function reportWarning(
+  message: string,
+  offset: number,
+  astNode: JSONNode,
+  context: Context<SourceCodeType.LiquidHtml>,
+) {
+  context.report({
+    message,
+    startIndex: offset + getLocStart(astNode),
+    endIndex: offset + getLocEnd(astNode),
+  });
+}
+
+export async function validateBlockFileExistence(
+  blockType: string,
+  context: Context<SourceCodeType.LiquidHtml>,
+): Promise<boolean> {
+  if (blockType === '@theme' || blockType === '@app') {
+    return true;
+  }
+
+  const blockPath = `blocks/${blockType}.liquid`;
+  return await doesFileExist(context, blockPath);
+}

package/src/utils/error.spec.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest';
+import { ParseErrorCode } from 'jsonc-parser';
+import { asError, isError } from './error';
+
+describe('Function: asError', () => {
+  it('should return the same Error instance if given an Error', () => {
+    const error = new Error('An error occurred');
+
+    const result = asError(error);
+
+    expect(result).toBe(error);
+    expect(result.message).toBe('An error occurred');
+  });
+
+  it('should create an Error from a string message', () => {
+    const error = 'Error string';
+
+    const result = asError(error);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Error string');
+  });
+
+  it('should create an Error from a ParseError with InvalidSymbol code', () => {
+    const error = {
+      error: ParseErrorCode.InvalidSymbol,
+      offset: 0,
+      length: 1,
+    };
+
+    const result = asError(error);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Invalid symbol found in the input.');
+  });
+
+  it('should create an Error from any object with toString function', () => {
+    const error = {
+      toString: () => 'Custom error description',
+    };
+
+    const result = asError(error);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('Custom error description');
+  });
+
+  it('should create a generic Error for unknown errors', () => {
+    const error = null;
+    const result = asError(error);
+
+    expect(result).toBeInstanceOf(Error);
+    expect(result.message).toBe('An unknown error occurred');
+  });
+});
+
+describe('Function: isError', () => {
+  it('should return true for Error instances', () => {
+    const error = new Error('An error occurred');
+    const result = isError(error);
+
+    expect(result).toBe(true);
+  });
+
+  it('should return false for non-Error instances', () => {
+    const error = 'Error string';
+    const result = isError(error);
+
+    expect(result).toBe(false);
+  });
+});

package/src/utils/error.ts

@@ -0,0 +1,48 @@
+import { ParseError, ParseErrorCode } from 'jsonc-parser';
+
+const PARSE_ERROR_MESSAGES: Record<ParseErrorCode, string> = {
+  [ParseErrorCode.InvalidSymbol]: 'Invalid symbol found in the input.',
+  [ParseErrorCode.InvalidNumberFormat]: 'Invalid number format detected.',
+  [ParseErrorCode.PropertyNameExpected]: 'Property name expected but not found.',
+  [ParseErrorCode.ValueExpected]: 'A value was expected but not found.',
+  [ParseErrorCode.ColonExpected]: 'Colon `:` expected after the property name.',
+  [ParseErrorCode.CommaExpected]: 'Comma `,` expected between elements and properties.',
+  [ParseErrorCode.CloseBraceExpected]: 'Closing brace `}` expected.',
+  [ParseErrorCode.CloseBracketExpected]: 'Closing bracket `]` expected.',
+  [ParseErrorCode.EndOfFileExpected]: 'End of file expected.',
+  [ParseErrorCode.InvalidCommentToken]: 'Invalid comment token found.',
+  [ParseErrorCode.UnexpectedEndOfComment]: 'Unexpected end of comment.',
+  [ParseErrorCode.UnexpectedEndOfString]: 'Unexpected end of string.',
+  [ParseErrorCode.UnexpectedEndOfNumber]: 'Unexpected end of number.',
+  [ParseErrorCode.InvalidUnicode]: 'Invalid Unicode escape sequence.',
+  [ParseErrorCode.InvalidEscapeCharacter]: 'Invalid escape character found.',
+  [ParseErrorCode.InvalidCharacter]: 'Invalid character found in the input.',
+};
+
+export function isError(error: unknown): error is Error {
+  return error instanceof Error;
+}
+
+export function asError(error: unknown): Error {
+  if (error instanceof Error) {
+    return error;
+  }
+
+  if (typeof error === 'string') {
+    return new Error(error);
+  }
+
+  if (error && typeof error === 'object' && 'error' in error) {
+    return new Error(getParseErrorMessage(error as ParseError));
+  }
+
+  if (error && typeof error.toString === 'function') {
+    return new Error(error.toString());
+  }
+
+  return new Error('An unknown error occurred');
+}
+
+function getParseErrorMessage(parseError: ParseError): string {
+  return PARSE_ERROR_MESSAGES[parseError.error] || 'Unknown parse error.';
+}

package/src/utils/file-utils.ts

@@ -0,0 +1,58 @@
+import { Context, SourceCodeType, Schema, RelativePath } from '../types';
+import { fetch } from 'cross-fetch';
+
+export async function doesFileExist<T extends SourceCodeType, S extends Schema>(
+  context: Context<T, S>,
+  relativePath: RelativePath,
+): Promise<boolean> {
+  const uri = context.toUri(relativePath);
+  return await context.fileExists(uri);
+}
+
+export async function doesFileExceedThreshold<T extends SourceCodeType, S extends Schema>(
+  context: Context<T, S>,
+  relativePath: RelativePath,
+  thresholdInBytes: number,
+): Promise<[exceeds: boolean, fileSize: number]> {
+  const uri = context.toUri(relativePath);
+  if (!context.fileSize) return [false, 0];
+  const fileSize = await context.fileSize(uri);
+  return [fileSize > thresholdInBytes, fileSize];
+}
+
+export async function getFileSize(url: string): Promise<number> {
+  try {
+    const response = await fetch(url, { method: 'HEAD' });
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const fileSize = response.headers.get('Content-Length');
+    if (fileSize === null) return 0;
+    return parseFloat(fileSize);
+  } catch (error) {
+    return 0;
+  }
+}
+
+export async function hasRemoteAssetSizeExceededThreshold(url: string, thresholdInBytes: number) {
+  const fileSize = await getFileSize(url);
+  return fileSize > thresholdInBytes;
+}
+
+export async function hasLocalAssetSizeExceededThreshold<
+  T extends SourceCodeType,
+  S extends Schema,
+>(context: Context<T, S>, relativePath: RelativePath, thresholdInBytes: number) {
+  const fileExists = await doesFileExist(context, relativePath);
+  if (!fileExists) return false;
+
+  const [fileExceedsThreshold, _fileSize] = await doesFileExceedThreshold(
+    context,
+    relativePath,
+    thresholdInBytes,
+  );
+
+  return fileExceedsThreshold;
+}

package/src/utils/index.ts

@@ -0,0 +1,8 @@
+export * from './object';
+export * from './array';
+export * from './position';
+export * from './error';
+export * from './types';
+export * from './memo';
+export * from './indexBy';
+export * from './block';

package/src/utils/indexBy.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns an Record representation of the collection indexed by keyFn. Assumes
+ * the key function returns unique results.
+ */
+export function indexBy<T, K extends PropertyKey>(
+  keyFn: (x: T) => K,
+  collection: T[],
+): Record<K, T> {
+  const record = {} as Record<K, T>;
+  for (const item of collection) {
+    record[keyFn(item)] = item;
+  }
+  return record;
+}

package/src/utils/markup.ts

@@ -0,0 +1,10 @@
+import { ContentForMarkup } from '@platformos/liquid-html-parser';
+
+export function isContentForBlock(
+  nodeMarkup: string | ContentForMarkup,
+): nodeMarkup is ContentForMarkup {
+  if (typeof nodeMarkup === 'string') {
+    return false;
+  }
+  return nodeMarkup.contentForType.value === 'block';
+}

package/src/utils/memo.spec.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { memo, memoize } from './memo';
+
+describe('memo', () => {
+  const helloFn = (name: string) => `Hello ${name}!`;
+  const goodByeFn = (name: string) => `Goodbye ${name}!`;
+
+  describe('Function: memo', () => {
+    it("should memo a function's result", () => {
+      const memoedHelloFn = memo(helloFn);
+      const memoedGoodByeFn = memo(goodByeFn);
+
+      expect(memoedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoedHelloFn('Josh')).toBe('Hello Bob!');
+      expect(memoedGoodByeFn('Alice')).toBe('Goodbye Alice!');
+      expect(memoedGoodByeFn('Emily')).toBe('Goodbye Alice!');
+    });
+
+    it("should clear the function's result from cache", () => {
+      const memoedHelloFn = memo(helloFn);
+      const memoedGoodByeFn = memo(goodByeFn);
+
+      expect(memoedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoedGoodByeFn('Alice')).toBe('Goodbye Alice!');
+
+      memoedHelloFn.clearCache();
+
+      expect(memoedHelloFn('Josh')).toBe('Hello Josh!');
+      expect(memoedGoodByeFn('Emily')).toBe('Goodbye Alice!');
+    });
+  });
+
+  describe('Function: memoize', () => {
+    let spiedHelloFn: (name: string) => string;
+
+    beforeEach(() => {
+      spiedHelloFn = vi.fn(helloFn);
+    });
+
+    it("should memoize a function's result by key", () => {
+      const memoizedHelloFn = memoize(spiedHelloFn, (name: string) => name);
+
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Josh')).toBe('Hello Josh!');
+
+      expect(spiedHelloFn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should invalidate cache for a specific key', () => {
+      const memoizedHelloFn = memoize(spiedHelloFn, (name: string) => name);
+
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+
+      expect(spiedHelloFn).toHaveBeenCalledTimes(1);
+
+      memoizedHelloFn.invalidate('Bob');
+
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+
+      expect(spiedHelloFn).toHaveBeenCalledTimes(2);
+    });
+
+    it('should force a recalculation for a specific key', () => {
+      const memoizedHelloFn = memoize(spiedHelloFn, (name: string) => name);
+
+      expect(memoizedHelloFn('Bob')).toBe('Hello Bob!');
+
+      expect(spiedHelloFn).toHaveBeenCalledTimes(1);
+
+      expect(memoizedHelloFn.force('Bob')).toBe('Hello Bob!');
+      expect(spiedHelloFn).toHaveBeenCalledTimes(2);
+
+      expect(memoizedHelloFn.force('Bob')).toBe('Hello Bob!');
+      expect(spiedHelloFn).toHaveBeenCalledTimes(3);
+    });
+  });
+});

package/src/utils/memo.ts

@@ -0,0 +1,80 @@
+import { ArgumentTypes } from './types';
+
+export type MemoedFunction<F extends (...args: any[]) => any> = {
+  /** Only the first call is cached */
+  (...args: ArgumentTypes<F>): ReturnType<F>;
+  /** Clear cache */
+  clearCache(): void;
+};
+
+const Unset = Symbol('Unset');
+
+/** Returns a cached version of a function. Only caches one result. */
+export function memo<F extends (...args: any[]) => any>(fn: F): MemoedFunction<F> {
+  let cachedValue: ReturnType<F> | typeof Unset = Unset;
+
+  const memoedFunction = (...args: ArgumentTypes<F>) => {
+    if (cachedValue === Unset) {
+      cachedValue = fn(...args);
+    }
+    return cachedValue as ReturnType<F>;
+  };
+
+  memoedFunction.clearCache = () => {
+    cachedValue = Unset;
+  };
+
+  return memoedFunction;
+}
+
+/**
+ * Returns a function that is cached-by-keyFn(argument)
+ *
+ * e.g.
+ *
+ * const expensiveFunction = (thing: Thing) => ...
+ * const thingToString = (thing: Thing): string => ...
+ * const fastOnSubsequentCalls = memoize(
+ *   expensiveFunction,
+ *   thingToString,
+ * );
+ *
+ * // slow first run
+ * fastOnSubsequentCalls(thing1);
+ *
+ * // fast subsequent ones
+ * fastOnSubsequentCalls(thing1);
+ * fastOnSubsequentCalls(thing1);
+ */
+export function memoize<AT extends any[], RT>(
+  fn: (...args: AT) => RT,
+  keyFn: (...args: AT) => string,
+) {
+  let cache: Record<string, RT> = {};
+
+  const memoedFunction = (...args: AT): RT => {
+    const key = keyFn(...args);
+
+    if (!cache[key]) {
+      cache[key] = fn(...args);
+    }
+
+    return cache[key];
+  };
+
+  memoedFunction.force = (...args: AT): RT => {
+    memoedFunction.invalidate(...args);
+    return memoedFunction(...args);
+  };
+
+  memoedFunction.invalidate = (...args: AT): void => {
+    const key = keyFn(...args);
+    delete cache[key];
+  };
+
+  memoedFunction.clearCache = () => {
+    cache = {};
+  };
+
+  return memoedFunction;
+}

package/src/utils/object.ts

@@ -0,0 +1,3 @@
+export function deepGet(obj: any, path: (string | number)[]): any {
+  return path.reduce((acc, key) => acc?.[key], obj);
+}

package/src/utils/position.ts

@@ -0,0 +1,16 @@
+import lineColumn from 'line-column';
+import { Position } from '../types';
+
+export function getPosition(source: string, index: number): Position {
+  const lineCol = lineColumn(source, { origin: 0 }).fromIndex(Math.min(index, source.length - 1));
+
+  return {
+    index,
+    line: lineCol ? lineCol.line : -1,
+    character: lineCol ? lineCol.col : -1,
+  };
+}
+
+export function getOffset(source: string, line: number, column: number): number {
+  return lineColumn(source, { origin: 1 }).toIndex(line, column);
+}