@platformos/platformos-check-common 0.0.2

package/src/to-schema.ts

@@ -0,0 +1,231 @@
+import {
+  ContentForMarkup,
+  LiquidRawTag,
+  NamedTags,
+  NodeTypes,
+} from '@platformos/liquid-html-parser';
+import { isPartial as isPartialPath } from '@platformos/platformos-common';
+import { parseJSON } from './json';
+import * as path from './path';
+import { toJSONAST } from './to-source-code';
+import {
+  AppBlockSchema,
+  ThemeBlockSchema,
+  IsValidSchema,
+  LiquidHtmlNode,
+  SectionSchema,
+  SourceCode,
+  SourceCodeType,
+  ThemeBlock,
+  ThemeSchemaType,
+  UriString,
+  Context,
+  Schema,
+  StaticBlockDef,
+} from './types';
+import { visit } from './visitor';
+
+export async function toSchema(
+  mode: 'app' | 'theme',
+  uri: UriString,
+  sourceCode: SourceCode,
+  isValidSchema: IsValidSchema | undefined,
+  isStrict: boolean = true,
+): Promise<AppBlockSchema | SectionSchema | ThemeBlockSchema | undefined> {
+  if (sourceCode.type !== SourceCodeType.LiquidHtml) return undefined;
+  switch (true) {
+    case mode === 'app' && isBlock(uri):
+      return toAppBlockSchema(uri, sourceCode.ast, isStrict);
+    case mode === 'theme' && isBlock(uri):
+      return toBlockSchema(uri, sourceCode.ast, isValidSchema, isStrict);
+    case mode === 'theme' && isSection(uri):
+      return toSectionSchema(uri, sourceCode.ast, isValidSchema, isStrict);
+    default:
+      return undefined;
+  }
+}
+
+export function isBlock(uri: UriString) {
+  return path.dirname(uri).endsWith('blocks');
+}
+
+export function isSection(uri: UriString) {
+  return path.dirname(uri).endsWith('sections');
+}
+
+export function isPartial(uri: UriString) {
+  return isPartialPath(uri);
+}
+
+// Legacy alias for backwards compatibility
+export const isSnippet = isPartial;
+
+export function isBlockSchema(
+  schema: AppBlockSchema | SectionSchema | ThemeBlockSchema | undefined,
+): schema is ThemeBlockSchema {
+  return schema?.type === ThemeSchemaType.Block;
+}
+
+export function isSectionSchema(
+  schema: AppBlockSchema | SectionSchema | ThemeBlockSchema | undefined,
+): schema is SectionSchema {
+  return schema?.type === ThemeSchemaType.Section;
+}
+
+async function toValidSchema<T>(
+  uri: string,
+  schemaNode: LiquidRawTag | Error,
+  parsed: any | Error,
+  isValidSchema: IsValidSchema | undefined,
+): Promise<T | Error> {
+  if (!isValidSchema) return new Error('No JSON validator provided');
+  if (schemaNode instanceof Error) return parsed;
+  if (await isValidSchema(uri, schemaNode.body.value)) {
+    return parsed as T;
+  } else {
+    return new Error('Invalid schema');
+  }
+}
+
+export async function toBlockSchema(
+  uri: UriString,
+  liquidAst: LiquidHtmlNode | Error,
+  isValidSchema: IsValidSchema | undefined,
+  isStrict: boolean,
+): Promise<ThemeBlockSchema> {
+  const name = path.basename(uri, '.liquid');
+  const schemaNode = await toSchemaNode(liquidAst);
+  const staticBlockDefs = await toStaticBlockDefs(liquidAst);
+  const parsed = toParsed(schemaNode, isStrict);
+  const ast = toAst(schemaNode);
+
+  return {
+    type: ThemeSchemaType.Block,
+    validSchema: await toValidSchema<ThemeBlock.Schema>(uri, schemaNode, parsed, isValidSchema),
+    offset: schemaNode instanceof Error ? 0 : schemaNode.blockStartPosition.end,
+    name,
+    parsed,
+    ast,
+    value: schemaNode instanceof Error ? '' : schemaNode.body.value,
+    staticBlockDefs,
+  };
+}
+
+// Coincidentally very similar right now... but could be different in the future
+// given there might be a plan to support folders in the blocks folder.
+// e.g. if we start having a stricter "parsed" object / ways to get settings.
+export async function toSectionSchema(
+  uri: UriString,
+  liquidAst: LiquidHtmlNode | Error,
+  isValidSchema: IsValidSchema | undefined,
+  isStrict: boolean,
+): Promise<SectionSchema> {
+  const name = path.basename(uri, '.liquid');
+  const schemaNode = await toSchemaNode(liquidAst);
+  const staticBlockDefs = await toStaticBlockDefs(liquidAst);
+  const parsed = toParsed(schemaNode, isStrict);
+  const ast = toAst(schemaNode);
+
+  return {
+    type: ThemeSchemaType.Section,
+    validSchema: await toValidSchema(uri, schemaNode, parsed, isValidSchema),
+    offset: schemaNode instanceof Error ? 0 : schemaNode.blockStartPosition.end,
+    name,
+    parsed,
+    ast,
+    value: schemaNode instanceof Error ? '' : schemaNode.body.value,
+    staticBlockDefs,
+  };
+}
+
+// validSchema not implemented yet. You can still `visit` the ast.
+export async function toAppBlockSchema(
+  uri: UriString,
+  liquidAst: LiquidHtmlNode | Error,
+  isStrict: boolean,
+): Promise<AppBlockSchema> {
+  const name = path.basename(uri, '.liquid');
+  const schemaNode = await toSchemaNode(liquidAst);
+  const parsed = toParsed(schemaNode, isStrict);
+  const ast = toAst(schemaNode);
+
+  return {
+    type: ThemeSchemaType.AppBlock,
+    offset: schemaNode instanceof Error ? 0 : schemaNode.blockStartPosition.end,
+    name,
+    parsed,
+    ast,
+    value: schemaNode instanceof Error ? '' : schemaNode.body.value,
+  };
+}
+
+async function toSchemaNode(ast: LiquidHtmlNode | Error): Promise<Error | LiquidRawTag> {
+  if (ast instanceof Error) return ast;
+  return (
+    (
+      await visit<SourceCodeType.LiquidHtml, LiquidRawTag>(ast, {
+        async LiquidRawTag(node) {
+          if (node.name === 'schema') {
+            return node;
+          }
+        },
+      })
+    )[0] ?? new Error('No schema tag found')
+  );
+}
+
+async function toStaticBlockDefs(ast: LiquidHtmlNode | Error): Promise<StaticBlockDef[]> {
+  if (ast instanceof Error) return [];
+  return await visit<SourceCodeType.LiquidHtml, StaticBlockDef>(ast, {
+    async LiquidTag(node) {
+      if (node.name !== NamedTags.content_for) return;
+      if (typeof node.markup === 'string') return;
+      const contentForMarkup: ContentForMarkup = node.markup;
+      if (contentForMarkup.contentForType.value !== 'block') return;
+      const type = contentForMarkup.args.find((x) => x.name === 'type');
+      const id = contentForMarkup.args.find((x) => x.name === 'id');
+      if (!type || !id) return;
+      if (type.value.type !== NodeTypes.String) return;
+      if (id.value.type !== NodeTypes.String) return;
+
+      return {
+        type: type.value.value,
+        id: id.value.value,
+      };
+    },
+  });
+}
+
+export function getSchema(context: Context<SourceCodeType.LiquidHtml, Schema>) {
+  const name = path.basename(context.file.uri, '.liquid');
+  switch (true) {
+    case isBlock(context.file.uri):
+      return context.getBlockSchema?.(name);
+    case isSection(context.file.uri):
+      return context.getSectionSchema?.(name);
+    default:
+      return undefined;
+  }
+}
+
+export async function getSchemaFromJSON(context: Context<SourceCodeType.JSON, Schema>) {
+  const originalSource = context.file.source;
+
+  const parsed = parseJSON(originalSource);
+  const ast = toJSONAST(originalSource);
+
+  return {
+    parsed,
+    ast,
+  };
+}
+
+function toParsed(schemaNode: LiquidRawTag | Error, isStrict: boolean): any | Error {
+  if (schemaNode instanceof Error) return schemaNode;
+  return parseJSON(schemaNode.body.value, undefined, isStrict);
+}
+
+function toAst(schemaNode: LiquidRawTag | Error): SourceCode<SourceCodeType.JSON>['ast'] | Error {
+  if (schemaNode instanceof Error) return schemaNode;
+  return toJSONAST(schemaNode.body.value);
+}

package/src/to-source-code.ts

@@ -0,0 +1,75 @@
+import { toLiquidHtmlAST } from '@platformos/liquid-html-parser';
+
+import { toJSONNode } from './jsonc/parse';
+import * as path from './path';
+import {
+  GraphQLDocumentNode,
+  GraphQLSourceCode,
+  JSONNode,
+  JSONSourceCode,
+  LiquidSourceCode,
+  SourceCodeType,
+} from './types';
+import { asError } from './utils/error';
+
+export function toLiquidHTMLAST(source: string) {
+  try {
+    return toLiquidHtmlAST(source);
+  } catch (error) {
+    return asError(error);
+  }
+}
+
+export function toJSONAST(source: string): JSONNode | Error {
+  try {
+    return toJSONNode(source);
+  } catch (error) {
+    return asError(error);
+  }
+}
+
+export function toGraphQLAST(source: string): GraphQLDocumentNode | Error {
+  try {
+    return {
+      type: 'Document',
+      content: source,
+    } as GraphQLDocumentNode;
+  } catch (error) {
+    return asError(error);
+  }
+}
+
+export function toSourceCode(
+  uri: string,
+  source: string,
+  version?: number,
+): LiquidSourceCode | JSONSourceCode | GraphQLSourceCode {
+  const isLiquid = uri.endsWith('.liquid');
+  const isGraphQL = uri.endsWith('.graphql');
+
+  if (isLiquid) {
+    return {
+      uri: path.normalize(uri),
+      source,
+      type: SourceCodeType.LiquidHtml,
+      ast: toLiquidHTMLAST(source),
+      version,
+    };
+  } else if (isGraphQL) {
+    return {
+      uri: path.normalize(uri),
+      source,
+      type: SourceCodeType.GraphQL,
+      ast: toGraphQLAST(source),
+      version,
+    };
+  } else {
+    return {
+      uri: path.normalize(uri),
+      source,
+      type: SourceCodeType.JSON,
+      ast: toJSONAST(source),
+      version,
+    };
+  }
+}

package/src/types/schema-prop-factory.ts

@@ -0,0 +1,112 @@
+export type Schema = {
+  [key: string]: SchemaProp<any>;
+};
+
+export type SchemaType = 'string' | 'number' | 'boolean' | 'object' | 'array';
+
+export type SettingValue<T extends SchemaProp<any>> = T extends SchemaProp<infer U> ? U : never;
+
+export type Settings<S extends Schema> = {
+  [K in keyof S]: SettingValue<S[K]>;
+};
+
+export interface SchemaPropOptions<T> {
+  type: SchemaType;
+  defaultValue?: T;
+  optional?: boolean;
+  properties?: Schema;
+  itemType?: SchemaProp<any>;
+}
+
+export class SchemaProp<T> {
+  options: SchemaPropOptions<T>;
+
+  constructor(options: SchemaPropOptions<T>) {
+    this.options = options;
+  }
+
+  /** Creates a string setting definition */
+  static string(defaultValue?: string): SchemaProp<string> {
+    return new SchemaProp({ type: 'string', defaultValue });
+  }
+
+  /** Creates a number setting definition */
+  static number(defaultValue?: number): SchemaProp<number> {
+    return new SchemaProp({ type: 'number', defaultValue });
+  }
+
+  /** Creates a boolean setting definition */
+  static boolean(defaultValue?: boolean): SchemaProp<boolean> {
+    return new SchemaProp({ type: 'boolean', defaultValue });
+  }
+
+  /**
+   * Creates an object setting definition
+   *
+   * Usage:
+   * ```
+   * const schema = {
+   *   user: SchemaProp.object({
+   *     age: SchemaProp.number(),
+   *     name: SchemaProp.string(),
+   *   })
+   * };
+   * ```
+   *
+   * @returns a schema property definition for an object type
+   */
+  static object<S extends Schema>(
+    /** The schema of the object's properties */
+    properties: S,
+    defaultValue?: Settings<S>,
+  ): SchemaProp<Settings<S>> {
+    const schema = new SchemaProp({ type: 'object', defaultValue, properties });
+    return schema;
+  }
+
+  /**
+   * Creates an array setting definition
+   *
+   * Usage:
+   * ```
+   * const schema = {
+   *   numbers: SchemaProp.array(SchemaProp.number(), [0, 1]),
+   *   strings: SchemaProp.array(SchemaProp.string(), ["foo", "bar"]),
+   *   users: SchemaProp.array(SchemaProp.object({
+   *    name: SchemaProp.string(),
+   *    age: SchemaProp.number(),
+   *   })),
+   * };
+   * ```
+   *
+   * @param itemType the type of the items in the array
+   * @returns a schema property definition for an object type
+   */
+  static array<SP extends SchemaProp<any>>(
+    /** The schema prop type of the items in the array */
+    itemType: SP,
+    defaultValue?: Array<SettingValue<SP>>,
+  ): SchemaProp<Array<SettingValue<SP>>> {
+    const schema = new SchemaProp({ type: 'array', defaultValue, itemType });
+    return schema;
+  }
+
+  /**
+   * A schema prop can be optional, making the setting T | undefined.
+   *
+   * Usage:
+   * ```
+   * const Schema = {
+   *   age: SchemaProp.number().optional(),
+   * }
+   * ```
+   */
+  optional(): SchemaProp<T | undefined> {
+    this.options.optional = true;
+    return this as unknown as SchemaProp<T | undefined>;
+  }
+
+  defaultValue(): T | undefined {
+    return this.options.defaultValue;
+  }
+}

package/src/types/schemas/index.ts

@@ -0,0 +1,5 @@
+export { ThemeBlock } from './theme-block';
+export { Section } from './section';
+export { Setting } from './setting';
+export { Preset } from './preset';
+export { Template } from './template';

package/src/types/schemas/preset.ts

@@ -0,0 +1,52 @@
+import { Setting } from './setting';
+
+export declare namespace Preset {
+  // Preset definitions
+  export type Preset =
+    | {
+        name: string;
+        settings?: Setting.Values;
+        blocks?: PresetBlockHash;
+        block_order?: string[];
+      }
+    | {
+        name: string;
+        settings?: Setting.Values;
+        blocks?: PresetBlockForArray[];
+      }
+    | { name: string; settings?: Setting.Values };
+
+  // Reuse the block preset types from ThemeBlock namespace
+  export type PresetBlockBase = {
+    type: string;
+    settings?: Setting.Values;
+    static?: boolean;
+    blocks?: PresetBlockHash | PresetBlockForArray[];
+  };
+
+  export type PresetBlockForHash = PresetBlockBase & {
+    block_order?: string[];
+  };
+
+  export type PresetBlockForArray = PresetBlockBase & {
+    id?: string;
+  };
+
+  // Hash format for blocks
+  export type PresetBlockHash = {
+    [id: string]: PresetBlockForHash;
+  };
+
+  /** Base type for presets */
+  export type BlockPresetBase = {
+    /** Refers to a block type. blocks/{type}.liquid */
+    type: string;
+    settings?: Setting.Values;
+  };
+
+  // prettier-ignore
+  export type Block = (
+    | PresetBlockForHash
+    | PresetBlockForArray
+  );
+}

package/src/types/schemas/section.ts

@@ -0,0 +1,86 @@
+import { Setting } from './setting';
+import { Preset } from './preset';
+
+export declare namespace Section {
+  /** {% schema %} */
+  export interface Schema {
+    name?: string;
+    tag?: 'article' | 'aside' | 'div' | 'footer' | 'header' | 'section';
+    class?: string;
+    limit?: number;
+    settings?: Setting.Any[];
+    max_blocks?: number;
+    blocks?: Block[];
+    presets?: Preset.Preset[];
+    default?: Default;
+    locales?: Record<string, Record<string, string>>;
+    enabled_on?: SectionToggle;
+    disabled_on?: SectionToggle;
+  }
+
+  // Block definitions
+  export type Block = ThemeBlock | AppBlock | SpecificThemeBlock | LocalBlock;
+
+  export type ThemeBlock = {
+    type: '@theme';
+  };
+
+  export type AppBlock = {
+    type: '@app';
+  };
+
+  export type SpecificThemeBlock = {
+    type: string;
+    limit?: number;
+    template?: string;
+  };
+
+  export type LocalBlock = {
+    type: string;
+    name: string;
+    settings?: Setting.Any[];
+  };
+
+  export type DefaultBlock = {
+    type: string;
+    settings?: Record<string, string | number | boolean | string[]>;
+  };
+
+  // Default section configuration (kind of like presets)
+  export interface Default {
+    settings?: Record<string, string | number | boolean | string[]>;
+    blocks?: Array<DefaultBlock>;
+  }
+
+  // Section toggle interface
+  export interface SectionToggle {
+    templates?: TemplateType[];
+    groups?: string[];
+  }
+
+  // Template types for section toggle
+  export type TemplateType =
+    | '*'
+    | '404'
+    | 'article'
+    | 'blog'
+    | 'captcha'
+    | 'cart'
+    | 'collection'
+    | 'customers/account'
+    | 'customers/activate_account'
+    | 'customers/addresses'
+    | 'customers/login'
+    | 'customers/order'
+    | 'customers/register'
+    | 'customers/reset_password'
+    | 'gift_card'
+    | 'index'
+    | 'list-collections'
+    | 'metaobject'
+    | 'page'
+    | 'password'
+    | 'policy'
+    | 'product'
+    | 'search';
+}