@platformos/platformos-check-common 0.0.2

package/src/liquid-doc/arguments.ts

@@ -0,0 +1,315 @@
+/**
+ * Helper methods shared between `render` tag and `content_for` tag to report
+ * errors when LiquidDoc exists
+ */
+import {
+  ContentForMarkup,
+  RenderMarkup,
+  FunctionMarkup,
+  LiquidNamedArgument,
+  NodeTypes,
+} from '@platformos/liquid-html-parser';
+import { Context, LiquidDocParameter, SourceCodeType, StringCorrector } from '..';
+import {
+  BasicParamTypes,
+  getDefaultValueForType,
+  inferArgumentType,
+  isTypeCompatible,
+} from './utils';
+import { isLiquidString } from '../checks/utils';
+
+/**
+ * Report error when unknown arguments are provided for `content_for` tag or `render` tag
+ */
+export function reportUnknownArguments(
+  context: Context<SourceCodeType.LiquidHtml>,
+  node: ContentForMarkup | RenderMarkup | FunctionMarkup,
+  unknownProvidedArgs: LiquidNamedArgument[],
+  name: string,
+) {
+  let errorOwnerMessage = '';
+  if (node.type === NodeTypes.ContentForMarkup) {
+    errorOwnerMessage = ` in content_for tag for static block '${name}'`;
+  } else if (node.type === NodeTypes.RenderMarkup) {
+    errorOwnerMessage = ` in render tag for partial '${name}'`;
+  } else if (node.type === NodeTypes.FunctionMarkup) {
+    errorOwnerMessage = ` in function tag for partial '${name}'`;
+  }
+
+  for (const arg of unknownProvidedArgs) {
+    context.report({
+      message: `Unknown argument '${arg.name}'${errorOwnerMessage}.`,
+      startIndex: arg.position.start,
+      endIndex: arg.position.end,
+      suggest: [
+        {
+          message: `Remove '${arg.name}'`,
+          fix: makeRemoveArgumentCorrector(node, arg),
+        },
+      ],
+    });
+  }
+}
+
+/**
+ * Report error when missing arguments are provided for `content_for` tag or `render` tag
+ */
+export function reportMissingArguments(
+  context: Context<SourceCodeType.LiquidHtml>,
+  node: ContentForMarkup | RenderMarkup | FunctionMarkup,
+  missingRequiredArgs: LiquidDocParameter[],
+  name: string,
+) {
+  let errorOwnerMessage = '';
+  if (node.type === NodeTypes.ContentForMarkup) {
+    errorOwnerMessage = ` in content_for tag for static block '${name}'`;
+  } else if (node.type === NodeTypes.RenderMarkup) {
+    errorOwnerMessage = ` in render tag for partial '${name}'`;
+  } else if (node.type === NodeTypes.FunctionMarkup) {
+    errorOwnerMessage = ` in function tag for partial '${name}'`;
+  }
+
+  for (const arg of missingRequiredArgs) {
+    context.report({
+      message: `Missing required argument '${arg.name}'${errorOwnerMessage}.`,
+      startIndex: node.position.start,
+      endIndex: node.position.end,
+      suggest: [
+        {
+          message: `Add required argument '${arg.name}'`,
+          fix: makeAddArgumentCorrector(node, arg),
+        },
+      ],
+    });
+  }
+}
+
+export function reportDuplicateArguments(
+  context: Context<SourceCodeType.LiquidHtml>,
+  node: ContentForMarkup | RenderMarkup | FunctionMarkup,
+  duplicateArgs: LiquidNamedArgument[],
+  name: string,
+) {
+  let errorOwnerMessage = '';
+  if (node.type === NodeTypes.ContentForMarkup) {
+    errorOwnerMessage = ` in content_for tag for static block '${name}'`;
+  } else if (node.type === NodeTypes.RenderMarkup) {
+    errorOwnerMessage = ` in render tag for partial '${name}'`;
+  } else if (node.type === NodeTypes.FunctionMarkup) {
+    errorOwnerMessage = ` in function tag for partial '${name}'`;
+  }
+
+  for (const arg of duplicateArgs) {
+    context.report({
+      message: `Duplicate argument '${arg.name}'${errorOwnerMessage}.`,
+      startIndex: arg.position.start,
+      endIndex: arg.position.end,
+      suggest: [
+        {
+          message: `Remove duplicate argument '${arg.name}'`,
+          fix: makeRemoveArgumentCorrector(node, arg),
+        },
+      ],
+    });
+  }
+}
+
+/**
+ * Find type mismatch between the arguments provided for `content_for` tag and `render` tag
+ * and their associated file's LiquidDoc
+ */
+export function findTypeMismatchParams(
+  liquidDocParameters: Map<string, LiquidDocParameter>,
+  providedParams: LiquidNamedArgument[],
+) {
+  const typeMismatchParams: LiquidNamedArgument[] = [];
+
+  for (const arg of providedParams) {
+    if (arg.value.type === NodeTypes.VariableLookup) {
+      continue;
+    }
+
+    const liquidDocParamDef = liquidDocParameters.get(arg.name);
+    if (liquidDocParamDef && liquidDocParamDef.type) {
+      const paramType = liquidDocParamDef.type.toLowerCase();
+      const supportedTypes = Object.keys(BasicParamTypes).map((type) => type.toLowerCase());
+      if (!supportedTypes.includes(paramType)) {
+        continue;
+      }
+
+      if (!isTypeCompatible(paramType, inferArgumentType(arg.value))) {
+        typeMismatchParams.push(arg);
+      }
+    }
+  }
+
+  return typeMismatchParams;
+}
+
+/**
+ * Report error if the type mismatches between LiquidDoc and provided arguments
+ */
+export function reportTypeMismatches(
+  context: Context<SourceCodeType.LiquidHtml>,
+  typeMismatchArgs: LiquidNamedArgument[],
+  liquidDocParameters: Map<string, LiquidDocParameter>,
+) {
+  for (const arg of typeMismatchArgs) {
+    const paramDef = liquidDocParameters.get(arg.name);
+    if (!paramDef || !paramDef.type) continue;
+
+    const expectedType = paramDef.type.toLowerCase();
+    const actualType = inferArgumentType(arg.value);
+
+    const suggestions = generateTypeMismatchSuggestions(
+      expectedType,
+      arg.value.position.start,
+      arg.value.position.end,
+    );
+
+    context.report({
+      message: `Type mismatch for argument '${arg.name}': expected ${expectedType}, got ${actualType}`,
+      startIndex: arg.value.position.start,
+      endIndex: arg.value.position.end,
+      suggest: suggestions,
+    });
+  }
+}
+
+/**
+ * Generates suggestions for type mismatches based on the expected type and node positions
+ */
+export function generateTypeMismatchSuggestions(
+  expectedType: string,
+  startPosition: number,
+  endPosition: number,
+) {
+  const defaultValue = getDefaultValueForType(expectedType);
+  const suggestions = [];
+
+  // Only add the "replace with default" suggestion if the default is not an empty string
+  if (defaultValue !== '') {
+    suggestions.push({
+      message: `Replace with default value '${defaultValue}' for ${expectedType}`,
+      fix: (fixer: StringCorrector) => {
+        return fixer.replace(startPosition, endPosition, defaultValue);
+      },
+    });
+  }
+
+  // Always include the "remove value" suggestion
+  suggestions.push({
+    message: `Remove value`,
+    fix: (fixer: StringCorrector) => {
+      return fixer.remove(startPosition, endPosition);
+    },
+  });
+
+  return suggestions;
+}
+
+function isLastArg(
+  node: RenderMarkup | ContentForMarkup | FunctionMarkup,
+  arg: LiquidNamedArgument,
+): boolean {
+  return (
+    node.args.length == 1 || arg.position.start == node.args[node.args.length - 1].position.start
+  );
+}
+
+export function getBlockName(node: ContentForMarkup) {
+  if (node.contentForType.value !== 'block') {
+    return;
+  }
+
+  const contentForTypeArg = node.args.find((arg) => arg.name == 'type')?.value;
+
+  if (!contentForTypeArg || !isLiquidString(contentForTypeArg)) {
+    return;
+  }
+
+  return contentForTypeArg.value;
+}
+
+export function getPartialName(node: RenderMarkup | FunctionMarkup): string | undefined {
+  if (node.type === NodeTypes.RenderMarkup) {
+    if (!isLiquidString(node.snippet)) {
+      return;
+    }
+    return node.snippet.value;
+  }
+
+  if (node.type === NodeTypes.FunctionMarkup) {
+    if (!isLiquidString(node.partial)) {
+      return;
+    }
+    return node.partial.value;
+  }
+}
+
+export async function getLiquidDocParams(
+  context: Context<SourceCodeType.LiquidHtml>,
+  relativePath: string,
+) {
+  const docDefinition = context.getDocDefinition && (await context.getDocDefinition(relativePath));
+
+  if (!docDefinition?.liquidDoc?.parameters) {
+    return;
+  }
+
+  return new Map(docDefinition.liquidDoc.parameters.map((p) => [p.name, p]));
+}
+
+export function makeRemoveArgumentCorrector(
+  node: ContentForMarkup | RenderMarkup | FunctionMarkup,
+  arg: LiquidNamedArgument,
+) {
+  return (fixer: StringCorrector) => {
+    const sourceBeforeArg = node.source.slice(node.position.start, arg.position.start);
+    const matches = sourceBeforeArg.match(/,\s*/g);
+    const lastCommaMatch = matches?.[matches.length - 1];
+    let startPos = lastCommaMatch
+      ? arg.position.start - (lastCommaMatch.length - 1)
+      : arg.position.start;
+
+    if (isLastArg(node, arg)) {
+      // Remove the leading comma if it's the last parameter
+      startPos -= 1;
+    }
+
+    const sourceAfterArg = node.source.substring(arg.position.end, node.position.end);
+    const trailingCommaMatch = sourceAfterArg.match(/\s*,/);
+    if (trailingCommaMatch) {
+      return fixer.remove(startPos, arg.position.end + trailingCommaMatch[0].length);
+    }
+    return fixer.remove(startPos, arg.position.end);
+  };
+}
+
+export function makeAddArgumentCorrector(
+  node: ContentForMarkup | RenderMarkup | FunctionMarkup,
+  arg: LiquidDocParameter,
+) {
+  return (fixer: StringCorrector) => {
+    const paramToAdd = `, ${arg.name}: ${getDefaultValueForType(arg.type)}`;
+
+    if (node.args.length == 0) {
+      return fixer.insert(node.position.end - 1, paramToAdd);
+    }
+
+    const lastArg = node.args[node.args.length - 1];
+    const sourceAfterLastArg = node.source.substring(lastArg.position.end, node.position.end);
+
+    const trailingCommaAndWhitespaceMatch = sourceAfterLastArg.match(/\s*,\s*/);
+    if (trailingCommaAndWhitespaceMatch) {
+      // IF there is already a trailing comma after the last arg, we want to find it and replace it with our own while stripping whitespace
+      return fixer.replace(
+        lastArg.position.end,
+        lastArg.position.end + trailingCommaAndWhitespaceMatch[0].length,
+        `${paramToAdd} `,
+      );
+    }
+
+    return fixer.insert(lastArg.position.end, paramToAdd);
+  };
+}

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

@@ -0,0 +1,296 @@
+import { expect, it, describe } from 'vitest';
+import { toSourceCode } from '../to-source-code';
+import { LiquidHtmlNode } from '../types';
+import { extractDocDefinition } from './liquidDoc';
+
+describe('Unit: extractDocDefinition', () => {
+  const uri = 'file:///app/views/partials/fake.liquid';
+
+  function toAST(code: string) {
+    return toSourceCode(uri, code).ast as LiquidHtmlNode;
+  }
+
+  it('should return default doc definition if no renderable content is present', async () => {
+    const ast = toAST(`
+        {% doc %}
+          just a description
+          @undefined asdf
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        description: {
+          content: 'just a description',
+          nodeType: 'description',
+        },
+      },
+    });
+  });
+
+  it('should extract name, description and type from param annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @param {String} firstParam - The first param
+          @param {Number} secondParam - The second param
+          @param {String} [optionalParam] - The optional param
+          @param paramWithNoType - param with no type
+          @param paramWithOnlyName
+          @param {Number} paramWithNoDescription
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        parameters: [
+          {
+            name: 'firstParam',
+            description: 'The first param',
+            type: 'String',
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'secondParam',
+            description: 'The second param',
+            type: 'Number',
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'optionalParam',
+            description: 'The optional param',
+            type: 'String',
+            required: false,
+            nodeType: 'param',
+          },
+          {
+            name: 'paramWithNoType',
+            description: 'param with no type',
+            type: null,
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'paramWithOnlyName',
+            description: null,
+            type: null,
+            required: true,
+            nodeType: 'param',
+          },
+          {
+            name: 'paramWithNoDescription',
+            description: null,
+            type: 'Number',
+            required: true,
+            nodeType: 'param',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract examples from @example annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @example
+          {{ product }}
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        examples: [
+          {
+            content: '{{ product }}',
+            nodeType: 'example',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract examples from @example annotations with multiple lines', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @example
+          {{ product }}
+          {{ product.title }}
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        examples: [
+          {
+            content: '{{ product }}\n{{ product.title }}',
+            nodeType: 'example',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract example from @example and @param annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @param {String} product - The product
+          @example
+          {{ product }} // This is an example
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        parameters: [
+          {
+            name: 'product',
+            description: 'The product',
+            type: 'String',
+            required: true,
+            nodeType: 'param',
+          },
+        ],
+        examples: [
+          {
+            content: '{{ product }} // This is an example',
+            nodeType: 'example',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract multiple examples from @example annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @example
+          {{ product }}
+          @example
+          {{ product.title }}
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        examples: [
+          {
+            content: '{{ product }}',
+            nodeType: 'example',
+          },
+          {
+            content: '{{ product.title }}',
+            nodeType: 'example',
+          },
+        ],
+      },
+    });
+  });
+
+  it('should extract description from @description annotations', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @description This is a description
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        description: {
+          content: 'This is a description',
+          nodeType: 'description',
+        },
+      },
+    });
+  });
+
+  it('should extract only the first @description annotation', async () => {
+    const ast = toAST(`
+        {% doc %}
+          @description This is a description
+          @description This is another description
+        {% enddoc %}
+      `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        description: {
+          content: 'This is a description',
+          nodeType: 'description',
+        },
+      },
+    });
+  });
+
+  it('should return snippetDefinition without liquidDoc property if doc header is not present', async () => {
+    const ast = toAST(`
+      <div>No doc header here</div>
+    `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+    });
+  });
+
+  it('should return an empty liquidDoc definition doc header is present but empty', async () => {
+    const ast = toAST(`
+      {% doc %}{% enddoc %}
+    `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {},
+    });
+  });
+
+  it('should return implicit description if multiple descriptions are provided', async () => {
+    const ast = toAST(`
+      {% doc %}
+        this is an implicit description
+        in a header
+
+        @param asdf
+
+        @description with a description annotation
+      {% enddoc %}
+    `);
+
+    const result = await extractDocDefinition(uri, ast);
+    expect(result).to.deep.equal({
+      uri,
+      liquidDoc: {
+        description: {
+          content: 'this is an implicit description\nin a header',
+          nodeType: 'description',
+        },
+        parameters: [
+          {
+            name: 'asdf',
+            description: null,
+            type: null,
+            required: true,
+            nodeType: 'param',
+          },
+        ],
+      },
+    });
+  });
+});