@platformos/platformos-check-common 0.0.2

package/src/liquid-doc/liquidDoc.ts

@@ -0,0 +1,147 @@
+import { SourceCodeType, UriString } from '../types';
+import { visit } from '../visitor';
+import { LiquidHtmlNode } from '../types';
+import {
+  LiquidDocExampleNode,
+  LiquidDocParamNode,
+  LiquidDocDescriptionNode,
+} from '@platformos/liquid-html-parser';
+
+export type GetDocDefinitionForURI = (
+  uri: UriString,
+  category: 'blocks' | 'app/views/partials',
+  name: string,
+) => Promise<DocDefinition | undefined>;
+
+export type DocDefinition = {
+  uri: UriString;
+  liquidDoc?: DocContent;
+};
+
+type DocContent = {
+  parameters?: LiquidDocParameter[];
+  examples?: LiquidDocExample[];
+  description?: LiquidDocDescription;
+};
+
+interface LiquidDocNode {
+  nodeType: 'param' | 'example' | 'description';
+}
+
+export interface LiquidDocParameter extends LiquidDocNode {
+  nodeType: 'param';
+  name: string;
+  description: string | null;
+  type: string | null;
+  required: boolean;
+}
+
+export interface LiquidDocExample extends LiquidDocNode {
+  content: string;
+  nodeType: 'example';
+}
+
+export interface LiquidDocDescription extends LiquidDocNode {
+  content: string;
+  nodeType: 'description';
+}
+
+export async function hasLiquidDoc(partial: LiquidHtmlNode): Promise<boolean> {
+  let foundDocTag = false;
+  await visit<SourceCodeType.LiquidHtml, void>(partial, {
+    async LiquidRawTag(node) {
+      if (node.name === 'doc') foundDocTag = true;
+    },
+  });
+  return foundDocTag;
+}
+
+export async function extractDocDefinition(
+  uri: UriString,
+  ast: LiquidHtmlNode,
+): Promise<DocDefinition> {
+  let hasDocTag = false;
+  const nodes: (LiquidDocParameter | LiquidDocExample | LiquidDocDescription)[] = await visit<
+    SourceCodeType.LiquidHtml,
+    LiquidDocParameter | LiquidDocExample | LiquidDocDescription
+  >(ast, {
+    async LiquidRawTag(node) {
+      if (node.name === 'doc') hasDocTag = true;
+      return undefined;
+    },
+    async LiquidDocParamNode(node: LiquidDocParamNode) {
+      return {
+        name: node.paramName.value,
+        description: node.paramDescription?.value ?? null,
+        type: node.paramType?.value ?? null,
+        required: node.required,
+        nodeType: 'param',
+      };
+    },
+    async LiquidDocExampleNode(node: LiquidDocExampleNode) {
+      return {
+        content: handleMultilineIndentation(node.content.value.trim()),
+        nodeType: 'example',
+      };
+    },
+    async LiquidDocDescriptionNode(node: LiquidDocDescriptionNode) {
+      return {
+        content: handleMultilineIndentation(node.content.value.trim()),
+        nodeType: 'description',
+      };
+    },
+  });
+
+  if (!hasDocTag) return { uri };
+
+  const { parameters, examples, description } = nodes.reduce(
+    (acc, node) => {
+      if (node.nodeType === 'param') {
+        acc.parameters.push(node as LiquidDocParameter);
+      } else if (node.nodeType === 'example') {
+        acc.examples.push(node as LiquidDocExample);
+      } else if (node.nodeType === 'description' && !acc.description) {
+        acc.description = node as LiquidDocDescription;
+      }
+      return acc;
+    },
+    {
+      parameters: [] as LiquidDocParameter[],
+      examples: [] as LiquidDocExample[],
+      description: undefined as LiquidDocDescription | undefined,
+    },
+  );
+
+  return {
+    uri,
+    liquidDoc: {
+      ...(parameters.length && { parameters }),
+      ...(examples.length && { examples }),
+      ...(description && { description }),
+    },
+  };
+}
+
+function handleMultilineIndentation(text: string): string {
+  const lines = text.split('\n');
+
+  if (lines.length <= 1) return text;
+
+  const nonEmptyLines = lines.slice(1).filter((line) => line.trim().length > 0);
+  const indentLengths = nonEmptyLines.map((line) => {
+    const match = line.match(/^\s*/);
+    return match ? match[0].length : 0;
+  });
+
+  if (indentLengths.length === 0) return text;
+
+  const minIndent = Math.min(...indentLengths);
+
+  return [
+    lines[0],
+    ...lines.slice(1).map((line) => {
+      if (line.trim().length === 0) return line; // Skip empty lines
+      return line.slice(minIndent);
+    }),
+  ].join('\n');
+}

package/src/liquid-doc/utils.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+import { BasicParamTypes, parseParamType } from './utils';
+
+describe('liquid-doc/utils', () => {
+  describe('parseParamType', () => {
+    const validParamTypes = new Set([...Object.values(BasicParamTypes), 'product']);
+
+    it('should parse all values provided in the `validParamTypes` set', () => {
+      const tests = {
+        string: ['string', false],
+        product: ['product', false],
+        'string[]': ['string', true],
+        'product[]': ['product', true],
+        invalid: undefined,
+      };
+
+      Object.entries(tests).forEach(([input, expected]) => {
+        const result = parseParamType(validParamTypes, input);
+        expect(result).toEqual(expected);
+      });
+    });
+  });
+});

package/src/liquid-doc/utils.ts

@@ -0,0 +1,125 @@
+import { LiquidExpression, NodeTypes } from '@platformos/liquid-html-parser';
+import { assertNever } from '../utils';
+import { isSnippet } from '../to-schema';
+import { isBlock } from '../to-schema';
+import { ObjectEntry, UriString } from '../types';
+
+/**
+ * The base set of supported param types for LiquidDoc.
+ *
+ * This is used in conjunction with objects defined in [liquid docs](https://shopify.dev/docs/api/liquid/objects)
+ * to determine ALL supported param types for LiquidDoc.
+ *
+ * References `getValidParamTypes`
+ */
+export enum BasicParamTypes {
+  String = 'string',
+  Number = 'number',
+  Boolean = 'boolean',
+  Object = 'object',
+}
+
+export enum SupportedDocTagTypes {
+  Param = 'param',
+  Example = 'example',
+  Description = 'description',
+}
+
+/**
+ * Provides a default completion value for an argument / parameter of a given type.
+ */
+export function getDefaultValueForType(type: string | null) {
+  switch (type?.toLowerCase()) {
+    case BasicParamTypes.String:
+      return "''";
+    case BasicParamTypes.Number:
+      return '0';
+    case BasicParamTypes.Boolean:
+      return 'false';
+    case BasicParamTypes.Object: // Objects don't have a sensible default value (maybe `theme`?)
+    default:
+      return '';
+  }
+}
+
+/**
+ * Casts the value of a LiquidNamedArgument to a string representing the type of the value.
+ */
+export function inferArgumentType(arg: LiquidExpression): BasicParamTypes {
+  switch (arg.type) {
+    case NodeTypes.String:
+      return BasicParamTypes.String;
+    case NodeTypes.Number:
+      return BasicParamTypes.Number;
+    case NodeTypes.LiquidLiteral:
+      return BasicParamTypes.Boolean;
+    case NodeTypes.Range:
+    case NodeTypes.VariableLookup:
+      return BasicParamTypes.Object;
+    default:
+      // This ensures that we have a case for every possible type for arg.value
+      return assertNever(arg);
+  }
+}
+
+/**
+ * Checks if the provided argument type is compatible with the expected type.
+ * Makes certain types more permissive:
+ * - Boolean accepts any value, since everything is truthy / falsy in Liquid
+ */
+export function isTypeCompatible(expectedType: string, actualType: BasicParamTypes): boolean {
+  const normalizedExpectedType = expectedType.toLowerCase();
+
+  if (normalizedExpectedType === BasicParamTypes.Boolean) {
+    return true;
+  }
+
+  return normalizedExpectedType === actualType;
+}
+
+/**
+ * Checks if the provided file path supports the LiquidDoc tag.
+ */
+export function filePathSupportsLiquidDoc(uri: UriString) {
+  return isSnippet(uri) || isBlock(uri);
+}
+
+/**
+ * Dynamically generates a map of LiquidDoc param types using object entries from
+ * [liquid docs](https://shopify.dev/docs/api/liquid/objects).
+ *
+ * This is used in conjunction with the base set of supported param.
+ *
+ * References `BasicParamTypes`
+ */
+export function getValidParamTypes(objectEntries: ObjectEntry[]): Map<string, string | undefined> {
+  const paramTypes: Map<string, string | undefined> = new Map([
+    [BasicParamTypes.String, undefined],
+    [BasicParamTypes.Number, undefined],
+    [BasicParamTypes.Boolean, undefined],
+    [
+      BasicParamTypes.Object,
+      'A generic type used to represent any liquid object or primitive value.',
+    ],
+  ]);
+
+  objectEntries.forEach((obj) => paramTypes.set(obj.name, obj.summary || obj.description));
+
+  return paramTypes;
+}
+
+export function parseParamType(
+  validParamTypes: Set<string>,
+  value: string,
+): [pseudoType: string, isArray: boolean] | undefined {
+  const paramTypeMatch = value.match(/^([a-z_]+)(\[\])?$/);
+
+  if (!paramTypeMatch) return undefined;
+
+  const extractedParamType = paramTypeMatch[1];
+  const isArrayType = !!paramTypeMatch[2];
+
+  if (!validParamTypes.has(extractedParamType)) return undefined;
+
+  return [extractedParamType, isArrayType];
+}

package/src/path.ts

@@ -0,0 +1,45 @@
+import { RelativePath, UriString } from './types';
+import { URI, Utils } from 'vscode-uri';
+
+export { URI, Utils };
+
+export function relative(uri: UriString | URI, rootUri: UriString): RelativePath {
+  return normalize(uri)
+    .replace(rootUri, '')
+    .replace(/\\\\/g, '/') // We expect forward slash paths (windows path get normalized)
+    .replace(/^\/+/, '');
+}
+
+export function join(rootUri: UriString | URI, ...paths: string[]): string {
+  return normalize(Utils.joinPath(asUri(rootUri), ...paths));
+}
+
+export function resolve(uri: UriString | URI, path: string): string {
+  return normalize(Utils.resolvePath(asUri(uri), path));
+}
+
+export function normalize(uri: UriString | URI): UriString {
+  const normalized = asUri(uri).toString(true);
+  // On Windows machines, paths use backslash ('\') as separator
+  // This causes issues since backslashes in glob patterns are treated as escape characters
+  // and in various URI contexts, forward slashes are expected
+  // We replace all backslashes with forward slashes for cross-platform consistency
+  return normalized.replace(/\\/g, '/');
+}
+
+export function dirname(uri: UriString | URI): UriString {
+  return normalize(Utils.dirname(asUri(uri)));
+}
+
+export function basename(uri: UriString | URI, ext?: string): string {
+  const base = Utils.basename(asUri(uri));
+  return ext ? base.replace(new RegExp(`${ext.replace(/\./g, '\\.')}$`), '') : base;
+}
+
+export function fsPath(uri: UriString | URI): string {
+  return asUri(uri).fsPath;
+}
+
+function asUri(uri: UriString | URI): URI {
+  return URI.isUri(uri) ? uri : URI.parse(uri);
+}

package/src/tags/content-for.ts

@@ -0,0 +1,25 @@
+export const RESERVED_CONTENT_FOR_ARGUMENTS = [
+  'attributes',
+  'block',
+  'blocks',
+  'class',
+  'context',
+  'inherit',
+  'resource',
+  'resources',
+  'schema',
+  'section',
+  'sections',
+  'settings',
+  'snippet',
+  'snippets',
+  'src',
+  'style',
+  'styles',
+  'template',
+  'templates',
+];
+
+export const REQUIRED_CONTENT_FOR_ARGUMENTS = ['id', 'type'];
+
+export const CLOSEST_ARGUMENT = 'closest.';

package/src/test/MockFileSystem.spec.ts

@@ -0,0 +1,71 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { MockFileSystem } from './MockFileSystem';
+import { FileType } from '@platformos/platformos-common';
+
+describe('MockFileSystem', () => {
+  let fs: MockFileSystem;
+
+  beforeEach(() => {
+    fs = new MockFileSystem({
+      'layout/theme.liquid': 'theme.liquid content',
+      'layout/password.liquid': 'password.liquid content',
+      'app/views/partials/product-card.liquid': 'product-card.liquid content',
+      'app/views/partials/product-variant.liquid': 'product-variant.liquid content',
+      'sections/section.liquid': 'section.liquid content',
+      'assets/js/foo.js': 'foo.js content',
+      'assets/js/bar.js': 'bar.js content',
+      'assets/theme.js': 'theme.js content',
+    });
+  });
+
+  describe('readFile', () => {
+    it('returns the content of existing files', async () => {
+      expect(await fs.readFile('file:/layout/theme.liquid')).toBe('theme.liquid content');
+      expect(await fs.readFile('file:/assets/js/foo.js')).toBe('foo.js content');
+    });
+
+    it('throws an error for files that do not exist', async () => {
+      await expect(fs.readFile('does not exist')).rejects.toThrow('File not found');
+    });
+  });
+
+  describe('readDirectory', () => {
+    it('returns the list of files in a leaf', async () => {
+      const result = await fs.readDirectory('file:/layout');
+      expect(result).to.eql([
+        ['file:/layout/theme.liquid', FileType.File],
+        ['file:/layout/password.liquid', FileType.File],
+      ]);
+    });
+
+    it('returns the list of files and directories in a branch', async () => {
+      const result = await fs.readDirectory('file:/assets');
+      expect(result).to.eql([
+        ['file:/assets/js', FileType.Directory],
+        ['file:/assets/theme.js', FileType.File],
+      ]);
+    });
+
+    it('returns the list of files and directories at the root', async () => {
+      const result = await fs.readDirectory('file:/');
+      expect(result).to.eql([
+        ['file:/layout', FileType.Directory],
+        ['file:/app', FileType.Directory],
+        ['file:/sections', FileType.Directory],
+        ['file:/assets', FileType.Directory],
+      ]);
+    });
+
+    it('throws an error for directories that do not exist', async () => {
+      await expect(fs.readDirectory('file:/does not exist')).rejects.toThrow('Directory not found');
+    });
+  });
+
+  describe('stat', () => {
+    it('returns the size of existing files', async () => {});
+
+    it('throws an error for files that do not exist', async () => {
+      await expect(fs.stat('file:/does not exist')).rejects.toThrow();
+    });
+  });
+});

package/src/test/MockFileSystem.ts

@@ -0,0 +1,87 @@
+import { AbstractFileSystem, FileStat, FileTuple, FileType } from '@platformos/platformos-common';
+import { deepGet } from '../utils';
+import { normalize, relative } from '../path';
+import { MockTheme } from './MockTheme';
+import * as path from '../path';
+
+interface FileTree {
+  [fileName: string]: string | FileTree;
+}
+
+export class MockFileSystem implements AbstractFileSystem {
+  private rootUri: string;
+
+  constructor(private mockTheme: MockTheme, rootUri = 'file:///') {
+    this.rootUri = normalize(rootUri);
+  }
+
+  async readFile(uri: string): Promise<string> {
+    const relativePath = this.rootRelative(uri);
+    if (this.mockTheme[relativePath] === undefined) {
+      throw new Error('File not found');
+    } else {
+      return this.mockTheme[relativePath];
+    }
+  }
+
+  async readDirectory(uri: string): Promise<FileTuple[]> {
+    // eslint-disable-next-line no-param-reassign
+    uri = uri.replace(/\/$/, '');
+    const relativePath = this.rootRelative(uri);
+    const tree =
+      path.normalize(uri) === this.rootUri
+        ? this.fileTree
+        : deepGet(this.fileTree, relativePath.split('/'));
+    if (tree === undefined || tree === null) {
+      throw new Error(`Directory not found: ${uri} for ${this.rootUri}`);
+    }
+
+    if (typeof tree === 'string') {
+      return [[uri, FileType.File]];
+    }
+
+    return Object.entries(tree).map(([fileName, value]) => {
+      return [`${uri}/${fileName}`, typeof value === 'string' ? FileType.File : FileType.Directory];
+    });
+  }
+
+  async stat(uri: string): Promise<FileStat> {
+    const relativePath = this.rootRelative(uri);
+    const source = this.mockTheme[relativePath];
+    if (source) {
+      return {
+        type: FileType.File,
+        size: source.length ?? 0,
+      };
+    }
+
+    const readdirResult = await this.readDirectory(uri);
+    if (readdirResult) {
+      return {
+        type: FileType.Directory,
+        size: 0, // Size is not applicable for directories
+      };
+    }
+
+    throw new Error(`File not found: ${uri} for ${this.rootUri}`);
+  }
+
+  private get fileTree(): FileTree {
+    const result: FileTree = {};
+    for (const [relativePath, source] of Object.entries(this.mockTheme)) {
+      const segments = relativePath.split('/');
+      let current = result;
+      for (let i = 0; i < segments.length - 1; i++) {
+        const segment = segments[i];
+        current[segment] ??= {};
+        current = current[segment] as FileTree;
+      }
+      current[segments[segments.length - 1]] = source;
+    }
+    return result;
+  }
+
+  private rootRelative(uri: string) {
+    return relative(normalize(uri), this.rootUri);
+  }
+}

package/src/test/MockTheme.ts

@@ -0,0 +1,17 @@
+/**
+ * @example
+ * {
+ *   'theme/layout.liquid': `
+ *     <html>
+ *       {{ content_for_page }}
+ *     </html>
+ *   `,
+ *   'snippets/snip.liquid': `
+ *     <b>'hello world'</b>
+ *   `,
+ * }
+ */
+
+export type MockTheme = {
+  [relativePath in string]: string;
+};

package/src/test/chai-offer-fix-assertion.spec.ts

@@ -0,0 +1,53 @@
+import { expect, describe, it } from 'vitest';
+import { LiquidHtmlSuggestion, Offense, Fix, SourceCodeType } from '../types';
+
+describe('Module: SuggestAssertion', () => {
+  const file = 'I love tea!';
+  const suggestionMessage = 'Replace tea with coffee!';
+  const suggestion: LiquidHtmlSuggestion = {
+    message: suggestionMessage,
+    fix: (corrector) => {
+      corrector.replace(file.indexOf('tea'), file.indexOf('tea') + 3, 'coffee');
+    },
+  };
+
+  const appliedSuggestion: Fix = {
+    startIndex: file.indexOf('tea'),
+    endIndex: file.indexOf('tea') + 3,
+    insert: 'coffee',
+  };
+
+  let offense: Offense<SourceCodeType.LiquidHtml>;
+
+  it('should do negative assertions correctly', () => {
+    offense = buildOffense();
+    expect(offense).not.to.suggest(file, suggestionMessage);
+
+    offense = buildOffense([suggestion]);
+    expect(offense).not.to.suggest(file, suggestionMessage + 'typo', appliedSuggestion);
+    expect(offense).not.to.suggest(file, suggestionMessage, {
+      startIndex: 0, // wrong index,
+      endIndex: 0,
+      insert: 'coffee',
+    });
+  });
+
+  it('should do positive assertions correctly', () => {
+    offense = buildOffense([suggestion]);
+    expect(offense).to.suggest(file, suggestionMessage);
+    expect(offense).to.suggest(file, suggestionMessage, appliedSuggestion);
+  });
+
+  function buildOffense(suggestions?: LiquidHtmlSuggestion[]): Offense<SourceCodeType.LiquidHtml> {
+    return {
+      type: SourceCodeType.LiquidHtml,
+      message: 'Coffee is better',
+      uri: 'file:///app/views/partials/cookies.liquid',
+      check: '',
+      severity: 0,
+      start: { index: 0, line: 0, character: 0 },
+      end: { index: 0, line: 0, character: 0 },
+      suggest: suggestions,
+    };
+  }
+});

package/src/test/chai-offer-fix-assertion.ts

@@ -0,0 +1,45 @@
+import { chai } from 'vitest';
+import { createCorrector } from '../fixes';
+import { Offense, Fix } from '../types';
+const { util } = chai;
+
+declare module 'vitest' {
+  interface Assertion {
+    /**
+     * @param source {string} - the source to correct
+     * @param message {string} - the suggestion message
+     * @param fix {Fix} - the Fix suggested
+     *
+     * @example
+     * expect(offense).to.offerFix(file, {
+     *   startIndex: 0,
+     *   endIndex: file.length,
+     *   insert: '<script ... defer></script>'
+     * });
+     */
+    offerFix: (source: string, fix: Fix) => void;
+  }
+}
+
+export const OfferFixAssertion = {
+  name: 'offerFix',
+  fn: function (this: Chai.AssertionPrototype, ...args: any[]) {
+    const offense: Offense = this._obj;
+    const source: string = args.at(0);
+    const expectedFix: Fix | undefined = args.at(1);
+    const corrector = createCorrector(offense.type, source);
+    offense.fix?.(corrector as any);
+    const actualFix = corrector.fix;
+
+    const ok = !!offense.fix && util.eql(actualFix, expectedFix);
+
+    this.assert(
+      ok,
+      `expected ${util.inspect(actualFix)} to eql ${util.inspect(expectedFix)}`,
+      `expected ${util.inspect(actualFix)} not to eql ${util.inspect(expectedFix)}`,
+      expectedFix,
+      actualFix,
+      true, // show diff
+    );
+  },
+};

package/src/test/chai-suggest-assertion.spec.ts

@@ -0,0 +1,53 @@
+import { expect, describe, it } from 'vitest';
+import { LiquidHtmlSuggestion, Offense, Fix, SourceCodeType } from '../types';
+
+describe('Module: SuggestAssertion', () => {
+  const file = 'I love tea!';
+  const suggestionMessage = 'Replace tea with coffee!';
+  const suggestion: LiquidHtmlSuggestion = {
+    message: suggestionMessage,
+    fix: (corrector) => {
+      corrector.replace(file.indexOf('tea'), file.indexOf('tea') + 3, 'coffee');
+    },
+  };
+
+  const appliedSuggestion: Fix = {
+    startIndex: file.indexOf('tea'),
+    endIndex: file.indexOf('tea') + 3,
+    insert: 'coffee',
+  };
+
+  let offense: Offense<SourceCodeType.LiquidHtml>;
+
+  it('should do negative assertions correctly', () => {
+    offense = buildOffense();
+    expect(offense).not.to.suggest(file, suggestionMessage);
+
+    offense = buildOffense([suggestion]);
+    expect(offense).not.to.suggest(file, suggestionMessage + 'typo', appliedSuggestion);
+    expect(offense).not.to.suggest(file, suggestionMessage, {
+      startIndex: 0, // wrong index,
+      endIndex: 0,
+      insert: 'coffee',
+    });
+  });
+
+  it('should do positive assertions correctly', () => {
+    offense = buildOffense([suggestion]);
+    expect(offense).to.suggest(file, suggestionMessage);
+    expect(offense).to.suggest(file, suggestionMessage, appliedSuggestion);
+  });
+
+  function buildOffense(suggestions?: LiquidHtmlSuggestion[]): Offense<SourceCodeType.LiquidHtml> {
+    return {
+      type: SourceCodeType.LiquidHtml,
+      message: 'Coffee is better',
+      uri: 'file:///app/views/partials/cookies.liquid',
+      check: '',
+      severity: 0,
+      start: { index: 0, line: 0, character: 0 },
+      end: { index: 0, line: 0, character: 0 },
+      suggest: suggestions,
+    };
+  }
+});