@platformos/platformos-language-server-common 0.0.2

package/src/types.ts

@@ -0,0 +1,173 @@
+import {
+  Config,
+  Dependencies as ThemeCheckDependencies,
+} from '@platformos/platformos-check-common';
+import { AbstractFileSystem } from '@platformos/platformos-common';
+import { URI } from 'vscode-languageserver';
+import * as rpc from 'vscode-jsonrpc';
+
+import { WithOptional } from './utils';
+import { Range } from 'vscode-json-languageservice';
+import { Reference } from '@platformos/platformos-graph';
+
+export type Dependencies = WithOptional<
+  RequiredDependencies,
+  'log' | 'getMetafieldDefinitions' | 'fetchMetafieldDefinitionsForURI'
+>;
+
+export interface RequiredDependencies {
+  /**
+   * A basic logging function.
+   *
+   * You might want console.log in development, and bugsnag in production.
+   */
+  log(message: string): void;
+
+  /**
+   * loadConfig(uri)
+   *
+   * In local environments, it's possible for one Language Server to deal
+   * with a workspace that contains many different configurations. In the
+   * browser, it isn't.
+   *
+   * loadConfig is the runtime-agnostic solution.
+   *
+   * @example
+   *
+   * Here's an example VS Code workspace a partner could run
+   * ```
+   * theme1/
+   *   src/
+   *     locales/
+   *     sections/
+   *     snippets/
+   *   dist/
+   *     locales/
+   *     sections/
+   *       foo.liquud
+   *     snippets/
+   * theme2/
+   *   locales/
+   *   sections/
+   *   snippets/
+   * ```
+   *
+   * In this situation, we have 3 different "roots."
+   *
+   * @param uri - a file path
+   * @returns {Promise<Config>}
+   */
+  loadConfig(uri: URI, fs: AbstractFileSystem): Promise<Config>;
+
+  /**
+   * In local environments, the Language Server can download the latest versions
+   * of themes docset from `Shopify/theme-liquid-docs`. However, this is not
+   * possible in the browser, so we implement different solutions for each
+   * environment.
+   */
+  themeDocset: NonNullable<ThemeCheckDependencies['themeDocset']>;
+
+  /**
+   * In local environments, the Language Server can download the latest versions
+   * of themes schemas from `Shopify/theme-liquid-docs`. Due to limitations in
+   * browser environments, json schemas must be precompiled into validators prior
+   * to theme-check instantiation.
+   */
+  jsonValidationSet: NonNullable<ThemeCheckDependencies['jsonValidationSet']>;
+
+  /**
+   * A file system abstraction that allows the Language Server to read files by URI.
+   *
+   * In Node.js, this is a wrapper around node:fs/promises.
+   *
+   * In VS Code, this is a wrapper around the VS Code API.
+   *
+   * The browser accepts a custom implementation.
+   */
+  fs: AbstractFileSystem;
+
+  /**
+   * In local environments, the Language Server can download the metafield definitions
+   * and provide a set of memoized definitions. In other environments, we rely on dynamically
+   * fetching the set of metafield definitions every time.
+   */
+  getMetafieldDefinitions: ThemeCheckDependencies['getMetafieldDefinitions'];
+
+  /**
+   * Fetch Metafield definitions using the CLI provided the URI of the project root.
+   * This should only be used in node environments; not on the browser.
+   */
+  fetchMetafieldDefinitionsForURI: (uri: URI) => Promise<void>;
+}
+
+export namespace ThemeGraphReferenceRequest {
+  export const method = 'themeGraph/references';
+  export const type = new rpc.RequestType<Params, Response, void>(method);
+  export interface Params {
+    uri: string;
+    offset?: number;
+    includeIndirect?: boolean;
+  }
+  export type Response = AugmentedReference[];
+}
+
+export namespace ThemeGraphDependenciesRequest {
+  export const method = 'themeGraph/dependencies';
+  export const type = new rpc.RequestType<Params, Response, void>(method);
+  export interface Params {
+    uri: string;
+    offset?: number;
+    includeIndirect?: boolean;
+  }
+  export type Response = AugmentedReference[];
+}
+
+export namespace ThemeGraphRootRequest {
+  export const method = 'themeGraph/rootUri';
+  export const type = new rpc.RequestType<Params, Response, void>(method);
+  export interface Params {
+    uri: string;
+  }
+  export type Response = string;
+}
+
+export namespace ThemeGraphDeadCodeRequest {
+  export const method = 'themeGraph/deadCode';
+  export const type = new rpc.RequestType<Params, Response, void>(method);
+  export interface Params {
+    uri: string;
+  }
+  export type Response = string[];
+}
+
+export namespace ThemeGraphDidUpdateNotification {
+  export const method = 'themeGraph/onDidChangeTree';
+  export const type = new rpc.NotificationType<Params>(method);
+  export interface Params {
+    uri: string;
+  }
+}
+
+export type AugmentedLocationWithExistence = {
+  uri: string;
+  range: undefined;
+  excerpt: undefined;
+  position: undefined;
+  exists: boolean;
+};
+
+export type AugmentedLocationWithExcerpt = {
+  uri: string;
+  range: [number, number];
+  excerpt: string;
+  position: Range;
+  exists: boolean;
+};
+
+export type AugmentedLocation = AugmentedLocationWithExistence | AugmentedLocationWithExcerpt;
+
+export interface AugmentedReference extends Reference {
+  source: AugmentedLocation;
+  target: AugmentedLocation;
+  indirect: boolean;
+}

package/src/utils/array.ts

@@ -0,0 +1,6 @@
+// Array.prototype.findLast is only available in es2023. Which feels too new?
+export function findLast<T>(array: T[], pred: (n: T) => boolean): T | undefined {
+  for (let i = array.length - 1; i >= 0; i--) {
+    if (pred(array[i])) return array[i];
+  }
+}

package/src/utils/debounce.ts

@@ -0,0 +1,60 @@
+import { ArgumentTypes } from '@platformos/platformos-check-common';
+
+export interface DebouncedFunction<F extends Function> {
+  /**
+   * A function that will execute on the trailing edge of a timer with the
+   * last arguments it was called with (unless forced)
+   */
+  (...args: ArgumentTypes<F>): void;
+
+  /**
+   * Debounced version of a function but making sure that it is called with
+   * this specific set of arguments.
+   *
+   * Subsequent calls will be ignored until the timer has expired and the
+   * function has executed.
+   */
+  force(...args: ArgumentTypes<F>): void;
+}
+
+/**
+ * debounce(fn, ms)
+ *
+ * A debounced function only executes once after a timer has expired. Repeated
+ * call to the debounced function before its timer has expired result in a delayed
+ * execution of the function.
+ *
+ * This is useful in cases where you have an "expensive" function that you only want
+ * to execute after the user is idle for a little bit.
+ *
+ * e.g. Run theme check after the user has stopped typing for at least 100ms.
+ *
+ * The debounced function has the same type signature as its argument.
+ *
+ * The input function must return void (or else you might "bomb" when you resolve).
+ *
+ * @param fn a function that should be debounced
+ * @param ms milliseconds after last function call for it to execute
+ * @returns a function that will execute on the trailing edge of a timer with the last argument it was called with
+ */
+export function debounce<F extends Function>(fn: F, ms?: number): DebouncedFunction<F> {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+  let force = false; // force use a certain set of arguments in the next call
+
+  const debouncedFn = (...args: ArgumentTypes<F>): void => {
+    if (timeoutId !== null && force) return;
+    if (timeoutId !== null) clearTimeout(timeoutId);
+    timeoutId = setTimeout(async () => {
+      await Promise.resolve(fn(...args));
+      timeoutId = null;
+      force = false;
+    }, ms);
+  };
+
+  debouncedFn.force = (...args: ArgumentTypes<F>): void => {
+    debouncedFn(...args);
+    force = true;
+  };
+
+  return debouncedFn;
+}

package/src/utils/htmlTagNames.ts

@@ -0,0 +1,61 @@
+import { LiquidHtmlNode, HtmlElement, NodeTypes } from '@platformos/liquid-html-parser';
+import { TextDocumentPositionParams, Range } from 'vscode-languageserver';
+import { TextDocument } from 'vscode-languageserver-textdocument';
+import { isCovered } from './isCovered';
+
+export function getHtmlElementNameRanges(
+  node: LiquidHtmlNode,
+  ancestors: LiquidHtmlNode[],
+  params: TextDocumentPositionParams,
+  textDocument: TextDocument,
+): Range[] | null {
+  let htmlElementNode: HtmlElement | null = null;
+
+  // Try parent node as HTML Element
+  // <name> case
+  const parentNode = ancestors.at(-1);
+  if (
+    parentNode &&
+    parentNode.type === NodeTypes.HtmlElement &&
+    parentNode.name.length > 0 &&
+    isCovered(textDocument.offsetAt(params.position), {
+      start: parentNode.name[0].position.start,
+      end: parentNode.name.at(-1)!.position.end,
+    })
+  ) {
+    htmlElementNode = parentNode;
+  }
+
+  // </name> case
+  if (
+    node.type === NodeTypes.HtmlElement &&
+    node.name.length > 0 &&
+    isCovered(textDocument.offsetAt(params.position), node.blockEndPosition)
+  ) {
+    htmlElementNode = node;
+  }
+
+  if (!htmlElementNode || isDanglingOpenHtmlElement(htmlElementNode)) return null;
+
+  const nameNodes = htmlElementNode.name;
+  const firstNode = nameNodes.at(0)!;
+  const lastNode = nameNodes.at(-1)!;
+  const startRange = Range.create(
+    textDocument.positionAt(firstNode.position.start),
+    textDocument.positionAt(lastNode.position.end),
+  );
+
+  const endRange = Range.create(
+    // </ means offset 2 characters
+    textDocument.positionAt(htmlElementNode.blockEndPosition.start + 2),
+    textDocument.positionAt(htmlElementNode.blockEndPosition.end - 1),
+  );
+
+  return [startRange, endRange];
+}
+
+export function isDanglingOpenHtmlElement(node: LiquidHtmlNode) {
+  return (
+    node.type === NodeTypes.HtmlElement && node.blockEndPosition.start === node.blockEndPosition.end
+  );
+}

package/src/utils/index.ts

@@ -0,0 +1,12 @@
+export {
+  ArgumentTypes,
+  WithOptional,
+  WithRequired,
+  memo,
+  memoize,
+  parseJSON,
+} from '@platformos/platformos-check-common';
+export * from './debounce';
+export * from './array';
+export * from './node';
+export * from './isCovered';

package/src/utils/isCovered.ts

@@ -0,0 +1,3 @@
+export function isCovered(offset: number, range: { start: number; end: number }): boolean {
+  return range.start <= offset && offset <= range.end;
+}

package/src/utils/liquidDoc.spec.ts

@@ -0,0 +1,167 @@
+import { DocDefinition } from '@platformos/platformos-check-common';
+import { describe, expect, it } from 'vitest';
+import { formatLiquidDocContentMarkdown, formatLiquidDocParameter } from './liquidDoc';
+
+describe('Module: liquidDoc', async () => {
+  describe('formatLiquidDocContentMarkdown', async () => {
+    const name = 'product-card';
+
+    const mockDocDefinition: DocDefinition = {
+      uri: `file:///${name}.liquid`,
+      liquidDoc: {
+        parameters: [
+          {
+            name: 'title',
+            description: 'The title of the product',
+            type: 'string',
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'border-radius',
+            description: 'The border radius in px',
+            type: 'number',
+            required: false,
+            nodeType: 'param',
+          },
+          {
+            name: 'no-type',
+            description: 'This parameter has no type',
+            type: null,
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'no-description',
+            description: null,
+            type: 'string',
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'no-type-or-description',
+            description: null,
+            type: null,
+            required: true,
+            nodeType: 'param',
+          },
+        ],
+        description: {
+          content: 'This is a description',
+          nodeType: 'description',
+        },
+        examples: [
+          {
+            content: '{{ product }}',
+            nodeType: 'example',
+          },
+          {
+            content: '{{ product.title }}',
+            nodeType: 'example',
+          },
+        ],
+      },
+    };
+
+    it('should format the LiquidDoc content correctly', async () => {
+      // prettier-ignore
+      const expectedHoverContent = 
+`### ${name}
+
+**Description:**
+
+
+This is a description
+
+**Parameters:**
+- \`title\`: string - The title of the product
+- \`border-radius\` (Optional): number - The border radius in px
+- \`no-type\` - This parameter has no type
+- \`no-description\`: string
+- \`no-type-or-description\`
+
+**Examples:**
+\`\`\`liquid
+{{ product }}
+\`\`\`
+\`\`\`liquid
+{{ product.title }}
+\`\`\``;
+
+      const result = formatLiquidDocContentMarkdown(name, mockDocDefinition);
+      expect(result).toEqual(expectedHoverContent);
+    });
+
+    it('should only return name if LiquidDocDefinition found', async () => {
+      const expectedHoverContent = `### ${name}`;
+
+      const result = formatLiquidDocContentMarkdown(name);
+      expect(result).toEqual(expectedHoverContent);
+    });
+  });
+
+  describe('formatLiquidDocParameter', async () => {
+    it('should format a required parameter correctly', async () => {
+      expect(
+        formatLiquidDocParameter({
+          name: 'title',
+          description: 'The title of the product',
+          type: 'string',
+          required: true,
+          nodeType: 'param',
+        }),
+      ).toEqual('- `title`: string - The title of the product');
+    });
+
+    it('should format an optional parameter correctly', async () => {
+      expect(
+        formatLiquidDocParameter({
+          name: 'title',
+          description: 'The title of the product',
+          type: 'string',
+          required: false,
+          nodeType: 'param',
+        }),
+      ).toEqual('- `title` (Optional): string - The title of the product');
+    });
+
+    it('should format a parameter with no type correctly', async () => {
+      expect(
+        formatLiquidDocParameter({
+          name: 'title',
+          description: 'The title of the product',
+          type: null,
+          required: true,
+          nodeType: 'param',
+        }),
+      ).toEqual('- `title` - The title of the product');
+    });
+
+    it('should format a parameter with no description correctly', async () => {
+      expect(
+        formatLiquidDocParameter({
+          name: 'title',
+          description: null,
+          type: null,
+          required: true,
+          nodeType: 'param',
+        }),
+      ).toEqual('- `title`');
+    });
+
+    it('should format a parameter when it is meant to be in a header', async () => {
+      expect(
+        formatLiquidDocParameter(
+          {
+            name: 'title',
+            description: 'The title of the product',
+            type: 'string',
+            required: true,
+            nodeType: 'param',
+          },
+          true,
+        ),
+      ).toEqual('### `title`: string\n\nThe title of the product');
+    });
+  });
+});

package/src/utils/liquidDoc.ts

@@ -0,0 +1,102 @@
+import {
+  BasicParamTypes,
+  DocDefinition,
+  getDefaultValueForType,
+  LiquidDocParameter,
+  SupportedDocTagTypes,
+} from '@platformos/platformos-check-common';
+
+export function formatLiquidDocParameter(
+  { name, type, description, required }: LiquidDocParameter,
+  heading: boolean = false,
+) {
+  const nameStr = required ? `\`${name}\`` : `\`${name}\` (Optional)`;
+  const typeStr = type ? `: ${type}` : '';
+
+  if (heading) {
+    const descStr = description ? `\n\n${description}` : '';
+    return `### ${nameStr}${typeStr}${descStr}`;
+  }
+
+  const descStr = description ? ` - ${description}` : '';
+  return `- ${nameStr}${typeStr}${descStr}`;
+}
+
+export function formatLiquidDocTagHandle(label: string, description: string, example: string) {
+  return `### @${label}\n\n${description}\n\n` + `**Example**\n\n\`\`\`liquid\n${example}\n\`\`\``;
+}
+
+export const SUPPORTED_LIQUID_DOC_TAG_HANDLES = {
+  [SupportedDocTagTypes.Param]: {
+    description:
+      'Provides information about a parameter for the snippet.\n' +
+      `- The type of parameter is optional and can be ${Object.values(BasicParamTypes)
+        .map((type) => `\`${type}\``)
+        .join(', ')}\n` +
+      ` or liquid object that isn't exclusively a global object in our [API Docs](https://shopify.dev/docs/api/liquid/objects)\n` +
+      '- An optional parameter is denoted by square brackets around the parameter name\n' +
+      '- The description is optional Markdown text',
+    example:
+      '{% doc %}\n' +
+      "  @param {string} name - The person's name\n" +
+      "  @param {number} [fav_num] - The person's favorite number\n" +
+      "  @param {product} prod - The person's chosen product\n" +
+      '{% enddoc %}\n',
+    template: `param {$2} $1$0`,
+  },
+  [SupportedDocTagTypes.Example]: {
+    description: 'Provides an example on how to use the snippet.',
+    example:
+      '{% doc %}\n' + '  @example {% render "snippet-name", arg1: "value" %}\n' + '{% enddoc %}\n',
+    template: `example $0`,
+  },
+  [SupportedDocTagTypes.Description]: {
+    description: 'Provides information on what the snippet does.',
+    example:
+      '{% doc %}\n' + '  @description This snippet renders a product image.\n' + '{% enddoc %}\n',
+    template: `description $0`,
+  },
+};
+
+export function getParameterCompletionTemplate(name: string, type: string | null) {
+  const paramDefaultValue = getDefaultValueForType(type);
+
+  const valueTemplate = paramDefaultValue === "''" ? `'$1'$0` : `\${1:${paramDefaultValue}}$0`;
+
+  return `${name}: ${valueTemplate}`;
+}
+
+export function formatLiquidDocContentMarkdown(
+  name: string,
+  docDefinition?: DocDefinition,
+): string {
+  const liquidDoc = docDefinition?.liquidDoc;
+
+  if (!liquidDoc) {
+    return `### ${name}`;
+  }
+
+  const parts = [`### ${name}`];
+
+  if (liquidDoc.description) {
+    const description = liquidDoc.description.content;
+    parts.push('', '**Description:**', '\n', description);
+  }
+
+  if (liquidDoc.parameters?.length) {
+    const parameters = liquidDoc.parameters
+      .map((param) => formatLiquidDocParameter(param))
+      .join('\n');
+    parts.push('', '**Parameters:**', parameters);
+  }
+
+  if (liquidDoc.examples?.length) {
+    const examples = liquidDoc.examples
+      ?.map(({ content }) => `\`\`\`liquid\n${content}\n\`\`\``)
+      .join('\n');
+
+    parts.push('', '**Examples:**', examples);
+  }
+
+  return parts.join('\n');
+}

package/src/utils/node.ts

@@ -0,0 +1,69 @@
+import {
+  AttrEmpty,
+  LiquidHtmlNode,
+  NamedTags,
+  NodeTypes,
+  TextNode,
+} from '@platformos/liquid-html-parser';
+import { LiquidHtmlNodeOfType as NodeOfType } from '@platformos/platformos-check-common';
+
+export type HtmlElementTypes = (typeof HtmlElementTypes)[number];
+export const HtmlElementTypes = [
+  NodeTypes.HtmlElement,
+  NodeTypes.HtmlDanglingMarkerClose,
+  NodeTypes.HtmlSelfClosingElement,
+  NodeTypes.HtmlVoidElement,
+  NodeTypes.HtmlRawNode,
+] as const;
+export type NamedHtmlElementNode = NodeOfType<HtmlElementTypes>;
+
+export type HtmlAttributeTypes = (typeof HtmlAttributeTypes)[number];
+export type HtmlAttribute = NodeOfType<HtmlAttributeTypes>;
+export const HtmlAttributeTypes = [
+  NodeTypes.AttrUnquoted,
+  NodeTypes.AttrDoubleQuoted,
+  NodeTypes.AttrSingleQuoted,
+  NodeTypes.AttrEmpty,
+] as const;
+
+export function isTextNode(node: LiquidHtmlNode): node is TextNode {
+  return node.type === NodeTypes.TextNode;
+}
+
+export function isAttrEmpty(node: LiquidHtmlNode): node is AttrEmpty {
+  return node.type === NodeTypes.AttrEmpty;
+}
+
+export function isNamedHtmlElementNode(node: LiquidHtmlNode): node is NamedHtmlElementNode {
+  return (HtmlElementTypes as readonly NodeTypes[]).includes(node.type);
+}
+
+export function getCompoundName(node: NamedHtmlElementNode | HtmlAttribute): string {
+  if (typeof node.name === 'string') return node.name;
+
+  const names = node.name;
+  if (names.length === 0 || names.length > 1 || !isTextNode(names[0])) {
+    return 'unknown';
+  }
+
+  return names[0].value;
+}
+
+export function isHtmlAttribute(node: LiquidHtmlNode): node is HtmlAttribute {
+  return HtmlAttributeTypes.some((type) => node.type === type);
+}
+
+type ExcludeStringMarkup<T> = T extends { markup: string } ? never : T;
+
+export function isNamedLiquidTag<NT extends LiquidHtmlNode, T extends NamedTags>(
+  node: LiquidHtmlNode,
+  name: T,
+): node is ExcludeStringMarkup<Extract<NT, { type: NodeTypes.LiquidTag; name: T }>> {
+  return node.type === NodeTypes.LiquidTag && node.name === name && typeof node.markup !== 'string';
+}
+
+export function isLiquidVariableOutput<NT extends LiquidHtmlNode>(
+  node: LiquidHtmlNode,
+): node is ExcludeStringMarkup<Extract<NT, { type: NodeTypes.LiquidVariableOutput }>> {
+  return node.type === NodeTypes.LiquidVariableOutput && typeof node.markup !== 'string';
+}

package/src/utils/uri.ts

@@ -0,0 +1,22 @@
+import { path } from '@platformos/platformos-check-common';
+
+export const partialName = (uri: string) => path.basename(uri, '.liquid');
+export const isPartial = (uri: string) => /\b(partials|lib)(\\|\/)[^\\\/]*\.liquid/.test(uri);
+
+// asset urls have their `.liquid`` removed (if present) and require the other extension */
+export const assetName = (uri: string) => path.basename(uri, '.liquid');
+export const isAsset = (uri: string) => /\bassets(\\|\/)[^\\\/]/.test(uri);
+
+export const blockName = (uri: string) => path.basename(uri, '.liquid');
+export const isBlock = (uri: string) => /\bblocks(\\|\/)[^\\\/]/.test(uri);
+
+export const sectionName = (uri: string) => path.basename(uri, '.liquid');
+export const isSection = (uri: string) =>
+  /\bsections(\\|\/)[^\\\/]/.test(uri) && /.liquid$/.test(uri);
+
+export const sectionGroupName = (uri: string) => path.basename(uri, '.json');
+export const isSectionGroup = (uri: string) =>
+  /\bsections(\\|\/)[^\\\/]/.test(uri) && /.json$/.test(uri);
+
+export const templateName = (uri: string) => path.basename(uri, '.json');
+export const isTemplate = (uri: string) => /\btemplates(\\|\/)[^\\\/]/.test(uri);

package/src/version.ts

@@ -0,0 +1,3 @@
+import packageJson from '../package.json';
+
+export const VERSION: string = packageJson.version;