@platformos/platformos-language-server-common 0.0.2

package/src/diagnostics/runChecks.spec.ts

@@ -0,0 +1,285 @@
+import {
+  allChecks,
+  LiquidCheckDefinition,
+  path,
+  Severity,
+  SourceCodeType,
+} from '@platformos/platformos-check-common';
+import { MockFileSystem } from '@platformos/platformos-check-common/src/test';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { Connection } from 'vscode-languageserver';
+import { DocumentManager } from '../documents';
+import { DiagnosticsManager } from './DiagnosticsManager';
+import { makeRunChecks } from './runChecks';
+
+const LiquidFilter: LiquidCheckDefinition = {
+  meta: {
+    code: 'LiquidFilter',
+    name: 'Complains about every LiquidFilter',
+    docs: {
+      description: 'Complains about every LiquidFilter',
+      recommended: true,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.ERROR,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      LiquidFilter: async (node) => {
+        context.report({
+          message: 'Liquid filter can not be used',
+          startIndex: node.position.start,
+          endIndex: node.position.end,
+        });
+      },
+    };
+  },
+};
+
+describe('Module: runChecks', () => {
+  let diagnosticsManager: DiagnosticsManager;
+  let documentManager: DocumentManager;
+  let connection: { sendDiagnostics: ReturnType<typeof vi.fn> };
+  let runChecks: ReturnType<typeof makeRunChecks>;
+  let fs: MockFileSystem;
+  const rootUri = path.normalize('browser:///theme');
+  const fileUri = path.join(rootUri, 'app', 'input.liquid');
+
+  beforeEach(() => {
+    connection = {
+      sendDiagnostics: vi.fn(),
+    };
+
+    documentManager = new DocumentManager();
+    diagnosticsManager = new DiagnosticsManager(connection as any as Connection);
+    fs = new MockFileSystem(
+      {
+        '.pos': '',
+        'app/input.liquid': `{{ 'any' | filter }}`,
+        '.git/test': 'test',
+        'modules/test': 'test',
+      },
+      rootUri,
+    );
+    runChecks = makeRunChecks(documentManager, diagnosticsManager, {
+      fs,
+      loadConfig: async () => ({
+        context: 'theme' as const,
+        settings: {},
+        checks: [LiquidFilter],
+        rootUri,
+      }),
+      themeDocset: {
+        graphQL: async () => null,
+        filters: async () => [],
+        objects: async () => [],
+        liquidDrops: async () => [],
+        tags: async () => [],
+        systemTranslations: async () => ({}),
+      },
+      jsonValidationSet: {
+        schemas: async () => [],
+      },
+    });
+  });
+
+  it('should send diagnostics when there are errors', async () => {
+    const fileContents = await fs.readFile(fileUri);
+    const fileVersion = 0;
+    documentManager.open(fileUri, fileContents, fileVersion);
+
+    await runChecks([fileUri]);
+    expect(connection.sendDiagnostics).toBeCalled();
+    expect(connection.sendDiagnostics).toBeCalledWith({
+      uri: fileUri,
+      version: fileVersion,
+      diagnostics: [
+        {
+          source: 'theme-check',
+          code: 'LiquidFilter',
+          message: 'Liquid filter can not be used',
+          severity: 1,
+          range: {
+            start: {
+              line: 0,
+              character: 8,
+            },
+            end: {
+              line: 0,
+              character: 17,
+            },
+          },
+        },
+      ],
+    });
+  });
+
+  it('should send an empty array when the errors were cleared', async () => {
+    const fileContentsWithError = `{{ 'any' | filter }}`;
+    const fileContentsWithoutError = `{{ 'any' }}`;
+    let fileVersion = 1;
+
+    // Open and have errors
+    documentManager.open(fileUri, fileContentsWithError, fileVersion);
+    await runChecks([fileUri]);
+
+    // Change doc to fix errors
+    fileVersion = 2;
+    documentManager.change(fileUri, fileContentsWithoutError, fileVersion);
+    await runChecks([fileUri]);
+
+    expect(connection.sendDiagnostics).toBeCalledTimes(2);
+    expect(connection.sendDiagnostics).toHaveBeenLastCalledWith({
+      uri: fileUri,
+      version: fileVersion,
+      diagnostics: [],
+    });
+  });
+
+  it('should send diagnostics per URI when there are errors', async () => {
+    const files = [
+      {
+        fileURI: path.join(rootUri, 'app', 'input1.liquid'),
+        fileContents: `{{ 'any' | filter }}`,
+        fileVersion: 0,
+        diagnostics: [
+          {
+            source: 'theme-check',
+            code: 'LiquidFilter',
+            message: 'Liquid filter can not be used',
+            severity: 1,
+            range: {
+              start: {
+                line: 0,
+                character: 8,
+              },
+              end: {
+                line: 0,
+                character: 17,
+              },
+            },
+          },
+        ],
+      },
+      {
+        fileURI: path.join(rootUri, 'app', 'input2.liquid'),
+        // same but on a new line
+        fileContents: `\n{{ 'any' | filter }}`,
+        fileVersion: 0,
+        diagnostics: [
+          {
+            source: 'theme-check',
+            code: 'LiquidFilter',
+            message: 'Liquid filter can not be used',
+            severity: 1,
+            range: {
+              start: {
+                line: 1,
+                character: 8,
+              },
+              end: {
+                line: 1,
+                character: 17,
+              },
+            },
+          },
+        ],
+      },
+    ];
+
+    files.forEach(({ fileURI, fileContents, fileVersion }) => {
+      documentManager.open(fileURI, fileContents, fileVersion);
+    });
+
+    await runChecks([path.join(rootUri, 'app', 'input1.liquid')]);
+
+    files.forEach(({ fileURI, fileVersion, diagnostics }) => {
+      expect(connection.sendDiagnostics).toBeCalledWith({
+        uri: fileURI,
+        version: fileVersion,
+        diagnostics,
+      });
+    });
+  });
+
+  it('should use the contents of the default translations file buffer (if any) instead of the result of the factory', async () => {
+    const defaultPath = 'locales/en.default.json';
+    const defaultURI = path.join(rootUri, ...defaultPath.split('/'));
+    const frPath = 'locales/fr.json';
+    const frURI = path.join(rootUri, ...frPath.split('/'));
+    const files = {
+      '.pos': '',
+      'app/test': '',
+      '.git/test': 'test',
+      'modules/test': 'test',
+      [defaultPath]: JSON.stringify({ hello: 'hello' }),
+      [frPath]: JSON.stringify({ hello: 'bonjour', hi: 'salut' }),
+    };
+
+    const matchingTranslation = allChecks.filter((c) => c.meta.code === 'MatchingTranslations');
+    expect(matchingTranslation).to.have.lengthOf(1);
+    runChecks = makeRunChecks(documentManager, diagnosticsManager, {
+      fs: new MockFileSystem(files, rootUri),
+      loadConfig: async () => ({
+        context: 'theme',
+        settings: {},
+        checks: matchingTranslation,
+        rootUri: rootUri,
+      }),
+      themeDocset: {
+        graphQL: async () => null,
+        filters: async () => [],
+        objects: async () => [],
+        liquidDrops: async () => [],
+        tags: async () => [],
+        systemTranslations: async () => ({}),
+      },
+      jsonValidationSet: {
+        schemas: async () => [],
+      },
+    });
+
+    // Open and have errors
+    documentManager.open(frURI, files[frPath], 0);
+    await runChecks([frURI]);
+    expect(connection.sendDiagnostics).toHaveBeenCalledWith(
+      expect.objectContaining({
+        uri: frURI,
+        version: 0,
+        diagnostics: expect.arrayContaining([
+          {
+            source: 'theme-check',
+            code: 'MatchingTranslations',
+            codeDescription: { href: expect.any(String) },
+            message: `A default translation for 'hi' does not exist`,
+            severity: 1,
+            range: {
+              end: {
+                character: 31,
+                line: 0,
+              },
+              start: {
+                character: 19,
+                line: 0,
+              },
+            },
+          },
+        ]),
+      }),
+    );
+
+    // Change the contents of the defaultURI buffer, expect frURI to be fixed
+    documentManager.open(defaultURI, files[defaultPath], 0);
+    documentManager.change(defaultURI, JSON.stringify({ hello: 'hello', hi: 'hi' }), 1);
+    connection.sendDiagnostics.mockClear();
+    await runChecks([frURI]);
+    expect(connection.sendDiagnostics).toHaveBeenCalledWith({
+      uri: frURI,
+      version: 0,
+      diagnostics: [],
+    });
+  });
+});

package/src/diagnostics/runChecks.ts

@@ -0,0 +1,147 @@
+import {
+  check,
+  findRoot,
+  makeFileExists,
+  Offense,
+  path,
+  Reference,
+  SectionSchema,
+  Severity,
+  SourceCodeType,
+  ThemeBlockSchema,
+} from '@platformos/platformos-check-common';
+
+import { CSSLanguageService } from '../css/CSSLanguageService';
+import { AugmentedSourceCode, DocumentManager } from '../documents';
+import { Dependencies } from '../types';
+import { DiagnosticsManager } from './DiagnosticsManager';
+import { offenseSeverity } from './offenseToDiagnostic';
+import { ThemeGraphManager } from '../server/ThemeGraphManager';
+
+export function makeRunChecks(
+  documentManager: DocumentManager,
+  diagnosticsManager: DiagnosticsManager,
+  {
+    fs,
+    loadConfig,
+    themeDocset,
+    jsonValidationSet,
+    getMetafieldDefinitions,
+    cssLanguageService,
+    themeGraphManager,
+  }: Pick<
+    Dependencies,
+    'fs' | 'loadConfig' | 'themeDocset' | 'jsonValidationSet' | 'getMetafieldDefinitions'
+  > & { cssLanguageService?: CSSLanguageService; themeGraphManager?: ThemeGraphManager },
+) {
+  return async function runChecks(triggerURIs: string[]): Promise<void> {
+    // This function takes an array of triggerURIs so that we can correctly
+    // recheck on file renames that came from out of bounds in a
+    // workspaces.
+    //
+    // e.g. if a user renames
+    //  theme1/snippets/a.liquid to
+    //  theme1/snippets/b.liquid
+    //
+    // then we recheck theme1
+    const fileExists = makeFileExists(fs);
+    const rootURIs = await Promise.all(triggerURIs.map((uri) => findRoot(uri, fileExists)));
+    const deduplicatedRootURIs = new Set<string>(rootURIs.filter((x): x is string => !!x));
+    await Promise.all([...deduplicatedRootURIs].map(runChecksForRoot));
+
+    return;
+
+    async function runChecksForRoot(configFileRootUri: string) {
+      const config = await loadConfig(configFileRootUri, fs);
+      const theme = documentManager.theme(config.rootUri);
+
+      const cssOffenses = cssLanguageService
+        ? await Promise.all(
+            theme.map((sourceCode) => getCSSDiagnostics(cssLanguageService, sourceCode)),
+          ).then((offenses) => offenses.flat())
+        : [];
+
+      const themeOffenses = await check(theme, config, {
+        fs,
+        themeDocset,
+        jsonValidationSet,
+        getMetafieldDefinitions,
+
+        async getReferences(uri: string): Promise<Reference[]> {
+          if (!themeGraphManager) return [];
+          return themeGraphManager.getReferences(uri);
+        },
+
+        // TODO should do something for app blocks?
+        async getBlockSchema(name) {
+          // We won't preload here. If it's available, we'll give it. Otherwise expect nothing.
+          const uri = path.join(config.rootUri, 'blocks', `${name}.liquid`);
+          const doc = documentManager.get(uri);
+          if (doc?.type !== SourceCodeType.LiquidHtml) return undefined;
+          const schema = await doc.getSchema();
+          return schema as ThemeBlockSchema | undefined;
+        },
+
+        async getSectionSchema(name) {
+          // We won't preload here. If it's available, we'll give it. Otherwise expect nothing.
+          const uri = path.join(config.rootUri, 'sections', `${name}.liquid`);
+          const doc = documentManager.get(uri);
+          if (doc?.type !== SourceCodeType.LiquidHtml) return undefined;
+          const schema = await doc.getSchema();
+          return schema as SectionSchema | undefined;
+        },
+
+        async getDocDefinition(relativePath) {
+          const uri = path.join(config.rootUri, relativePath);
+          const doc = documentManager.get(uri);
+          if (doc?.type !== SourceCodeType.LiquidHtml) return undefined;
+          return doc.getLiquidDoc();
+        },
+      });
+      const offenses = [...themeOffenses, ...cssOffenses];
+
+      // We iterate over the theme files (as opposed to offenses) because if
+      // there were offenses before, we need to send an empty array to clear
+      // them.
+      for (const sourceCode of theme) {
+        const sourceCodeOffenses = offenses.filter((offense) => offense.uri === sourceCode.uri);
+        diagnosticsManager.set(sourceCode.uri, sourceCode.version, sourceCodeOffenses);
+      }
+    }
+  };
+}
+
+async function getCSSDiagnostics(
+  cssLanguageService: CSSLanguageService,
+  sourceCode: AugmentedSourceCode,
+): Promise<Offense[]> {
+  if (sourceCode.type !== SourceCodeType.LiquidHtml) {
+    return [];
+  }
+
+  const diagnostics = await cssLanguageService.diagnostics({
+    textDocument: { uri: sourceCode.uri },
+  });
+
+  return diagnostics
+    .map(
+      (diagnostic): Offense => ({
+        check: 'css',
+        message: diagnostic.message,
+        end: {
+          index: sourceCode.textDocument.offsetAt(diagnostic.range.end),
+          line: diagnostic.range.end.line,
+          character: diagnostic.range.end.character,
+        },
+        start: {
+          index: sourceCode.textDocument.offsetAt(diagnostic.range.start),
+          line: diagnostic.range.start.line,
+          character: diagnostic.range.start.character,
+        },
+        severity: offenseSeverity(diagnostic),
+        uri: sourceCode.uri,
+        type: SourceCodeType.LiquidHtml,
+      }),
+    )
+    .filter((offense) => offense.severity !== Severity.INFO);
+}

package/src/docset/HtmlDocset.ts

@@ -0,0 +1,43 @@
+import * as htmlData from '@vscode/web-custom-data/data/browsers.html-data.json';
+import type { MarkupContent } from 'vscode-languageserver-protocol';
+
+export interface HtmlData {
+  version: number;
+  tags: Tag[];
+  globalAttributes: Attribute[];
+  valueSets: ValueSet[];
+}
+
+export interface Tag {
+  name: string;
+  description: string | MarkupContent;
+  attributes: Attribute[];
+  references: Reference[];
+  void?: boolean;
+}
+
+export interface Attribute {
+  name: string;
+  description: string | MarkupContent;
+  references?: Reference[];
+  valueSet?: ValueSetId;
+}
+
+export interface Reference {
+  name: string;
+  url: string;
+}
+
+type ValueSetId = string;
+
+export interface ValueSet {
+  name: ValueSetId;
+  values: Value[];
+}
+
+export interface Value {
+  name: string;
+  description?: MarkupContent;
+}
+
+export const HtmlData = htmlData as HtmlData;

package/src/docset/MarkdownRenderer.spec.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+
+import { render, renderHtmlEntry, type HtmlEntry } from './MarkdownRenderer';
+import type { DocsetEntry } from '@platformos/platformos-check-common';
+
+const DOC_ENTRY: DocsetEntry = {
+  name: 'entry',
+  summary: 'summary',
+  description: 'description',
+  deprecated: false,
+};
+
+const HTML_ENTRY: HtmlEntry = {
+  name: 'entry',
+  description: 'description',
+};
+
+describe('MarkdownRenderer', () => {
+  describe('render()', () => {
+    it('converts a docset entry to markdown', async () => {
+      expect(render(DOC_ENTRY)).toEqual(`### entry\nsummary\n\n---\n\ndescription`);
+    });
+
+    describe('when the entry has syntax', () => {
+      it('includes the syntax in the markdown', async () => {
+        expect(render({ ...DOC_ENTRY, syntax: 'string | image_tag' })).toEqual(
+          `### entry\n\`\`\`liquid\n{{ string | image_tag }}\n\`\`\`\n\n---\n\nsummary\n\n---\n\ndescription`,
+        );
+      });
+
+      describe('and the syntax already includes liquid tags', () => {
+        it('does not wrap the syntax in curly braces', async () => {
+          expect(render({ ...DOC_ENTRY, syntax: '{% form %}' })).toEqual(
+            `### entry\n\`\`\`liquid\n{% form %}\n\`\`\`\n\n---\n\nsummary\n\n---\n\ndescription`,
+          );
+        });
+      });
+    });
+  });
+
+  describe('renderHtmlEntry()', () => {
+    it('converts a docset entry to markdown', async () => {
+      expect(renderHtmlEntry(HTML_ENTRY)).toEqual(`### entry\ndescription`);
+    });
+  });
+});

package/src/docset/MarkdownRenderer.ts

@@ -0,0 +1,179 @@
+import {
+  DocsetEntry,
+  FilterEntry,
+  ObjectEntry,
+  TagEntry,
+} from '@platformos/platformos-check-common';
+import {
+  ArrayType,
+  PseudoType,
+  ShapeType,
+  UnionType,
+  Unknown,
+  docsetEntryReturnType,
+  isArrayType,
+  isShapeType,
+  isUnionType,
+  typeToDisplayString,
+} from '../TypeSystem';
+import { shapeToTypeString, shapeToDetailString } from '../PropertyShapeInference';
+import { Attribute, Tag, Value } from './HtmlDocset';
+
+const HORIZONTAL_SEPARATOR = '\n\n---\n\n';
+
+export type HtmlEntry = Tag | Attribute | Value;
+export type DocsetEntryType = 'filter' | 'tag' | 'object';
+
+export function render(
+  entry: DocsetEntry | FilterEntry | TagEntry,
+  returnType?: PseudoType | ArrayType | ShapeType | UnionType,
+  docsetEntryType?: DocsetEntryType,
+) {
+  return [title(entry, returnType), docsetEntryBody(entry, returnType, docsetEntryType)]
+    .filter(Boolean)
+    .join('\n');
+}
+
+export function renderHtmlEntry(entry: HtmlEntry, parentEntry?: HtmlEntry) {
+  return [title(entry, Unknown), htmlEntryBody(entry, parentEntry)].join('\n');
+}
+
+function title(
+  entry: DocsetEntry | ObjectEntry | FilterEntry | HtmlEntry,
+  returnType?: PseudoType | ArrayType | ShapeType | UnionType,
+) {
+  returnType = returnType ?? docsetEntryReturnType(entry as ObjectEntry, Unknown);
+
+  if (isUnionType(returnType)) {
+    return `### ${entry.name}: \`${typeToDisplayString(returnType)}\``;
+  } else if (isShapeType(returnType)) {
+    return `### ${entry.name}: \`${shapeToTypeString(returnType.shape)}\``;
+  } else if (isArrayType(returnType)) {
+    return `### ${entry.name}: \`${returnType.valueType}[]\``;
+  } else if (returnType !== Unknown) {
+    return `### ${entry.name}: \`${returnType}\``;
+  }
+
+  return `### ${entry.name}`;
+}
+
+function sanitize(s: string | undefined) {
+  return s
+    ?.replace(/(^|\n+)>/g, ' ')
+    .replace(/>/g, '>')
+    .replace(/&lt;/g, '<')
+    .replace(/\]\(\//g, '](https://shopify.dev/')
+    .trim();
+}
+
+function docsetEntryBody(
+  entry: DocsetEntry,
+  returnType?: PseudoType | ArrayType | ShapeType | UnionType,
+  docsetEntryType?: DocsetEntryType,
+) {
+  const bodyParts = [
+    syntax(entry),
+    entry.deprecation_reason,
+    entry.summary,
+    entry.description,
+    platformOSDevReference(entry, returnType, docsetEntryType),
+  ];
+
+  // Add shape details if returnType is a ShapeType
+  if (returnType && isShapeType(returnType)) {
+    bodyParts.unshift(shapeToDetailString(returnType.shape));
+  }
+
+  return bodyParts
+    .map((x) => x?.toString())
+    .map(sanitize)
+    .filter(Boolean)
+    .join(HORIZONTAL_SEPARATOR);
+}
+
+function htmlEntryBody(entry: HtmlEntry, parentEntry?: HtmlEntry) {
+  return [description(entry), references(entry), references(parentEntry)]
+    .filter(Boolean)
+    .join(HORIZONTAL_SEPARATOR);
+}
+
+function syntax(entry: DocsetEntry | FilterEntry | TagEntry) {
+  if (!('syntax' in entry) || !entry.syntax) {
+    return undefined;
+  }
+
+  // TagEntry entries already have liquid tags as a part of the syntax
+  // explanation so we can return them directly.
+  if (entry.syntax.startsWith('{%')) {
+    return `\`\`\`liquid\n${entry.syntax}\n\`\`\``;
+  }
+
+  // Wrap the syntax in liquid tags to ensure we get proper syntax highlighting
+  // if it's available.
+  return `\`\`\`liquid\n{{ ${entry.syntax} }}\n\`\`\``;
+}
+
+function description(entry: HtmlEntry) {
+  if (!entry.description || typeof entry.description === 'string') {
+    return entry.description;
+  }
+
+  return entry.description.value;
+}
+
+const platformOSDevRoot = `https://documentation.platformos.com/api-reference/liquid`;
+
+function platformOSDevReference(
+  entry: DocsetEntry,
+  _?: PseudoType | ArrayType | ShapeType | UnionType,
+  docsetEntryType?: DocsetEntryType,
+) {
+  switch (docsetEntryType) {
+    case 'tag': {
+      if (entry.name === 'include') {
+        return `[platformOS Reference](${platformOSDevRoot}/include)`;
+      } else if (['for', 'cycle', 'ifchanged', 'tablerow'].includes(entry.name)) {
+        return `[platformOS Reference](${platformOSDevRoot}/loops#${entry.name})`;
+      } else if (entry.name === 'liquid') {
+        return `[platformOS Reference](${platformOSDevRoot}/theme#liquid)`;
+      } else if ('platformOS' in entry && entry.platformOS === true) {
+        return `[platformOS Reference](${platformOSDevRoot}/platformos-tags#${entry.name.replaceAll(
+          '_',
+          '-',
+        )})`;
+      } else {
+        return undefined;
+      }
+    }
+
+    case 'filter': {
+      if ('platformOS' in entry) {
+        return `[platformOS Reference](${platformOSDevRoot}/platformos-filters#${entry.name.replaceAll(
+          '_',
+          '-',
+        )})`;
+      } else {
+        return `[platformOS Reference](${platformOSDevRoot}/filters#${entry.name})`;
+      }
+    }
+
+    default: {
+      return undefined;
+    }
+  }
+}
+
+function references(entry: HtmlEntry | undefined) {
+  if (!entry || !('references' in entry) || !entry.references || entry.references.length === 0) {
+    return undefined;
+  }
+
+  if (entry.references.length === 1) {
+    const [ref] = entry.references;
+    return `[${ref.name}](${ref.url})`;
+  }
+
+  return [`#### Learn more`, entry.references.map((ref) => `- [${ref.name}](${ref.url})`)].join(
+    '\n\n',
+  );
+}

package/src/docset/index.ts

@@ -0,0 +1,2 @@
+export { render, renderHtmlEntry, DocsetEntryType } from './MarkdownRenderer';
+export * from './HtmlDocset';