@platformos/platformos-common 0.0.15 → 0.0.17

package/src/documents-locator/DocumentsLocator.ts

@@ -1,6 +1,6 @@
 import yaml from 'js-yaml';
 import { AbstractFileSystem, FileType } from '../AbstractFileSystem';
-import { getAppPaths, getModulePaths, PlatformOSFileType } from '../path-utils';
+import { getAppPaths, getModulePaths, parseModulePrefix, PlatformOSFileType } from '../path-utils';
 import { URI, Utils } from 'vscode-uri';
 
 export type DocumentType =
@@ -34,9 +34,8 @@ export async function loadSearchPaths(
   }
 }
 
-type ModulePathInfo =
-  | { isModule: false; key: string }
-  | { isModule: true; moduleName: string; key: string };
+/** Maximum number of concrete paths generated by a single dynamic search-path expansion. */
+const MAX_DYNAMIC_PATH_EXPANSIONS = 100;
 
 export class DocumentsLocator {
   constructor(private readonly fs: AbstractFileSystem) {}
@@ -49,17 +48,6 @@ export class DocumentsLocator {
     }
   }
 
-  private parseModulePath(fileName: string): ModulePathInfo {
-    if (!fileName.startsWith('modules/')) {
-      return { isModule: false, key: fileName };
-    }
-
-    const [, moduleName, ...rest] = fileName.split('/');
-    const key = rest.join('/');
-
-    return moduleName ? { isModule: true, moduleName, key } : { isModule: false, key: fileName };
-  }
-
   private getSearchPaths(type: 'partial' | 'graphql' | 'asset', moduleName?: string): string[] {
     const fileType: PlatformOSFileType = {
       partial: PlatformOSFileType.Partial,
@@ -75,7 +63,7 @@ export class DocumentsLocator {
     fileName: string,
     type: 'partial' | 'graphql' | 'asset',
   ): Promise<string | undefined> {
-    const parsed = this.parseModulePath(fileName);
+    const parsed = parseModulePrefix(fileName);
     const searchPaths = this.getSearchPaths(type, parsed.isModule ? parsed.moduleName : undefined);
 
     let targetFile = parsed.key;
@@ -101,7 +89,7 @@ export class DocumentsLocator {
     filePrefix: string,
     type: 'partial' | 'graphql' | 'asset',
   ): Promise<string[]> {
-    const parsed = this.parseModulePath(filePrefix);
+    const parsed = parseModulePrefix(filePrefix);
     const searchPaths = this.getSearchPaths(type, parsed.isModule ? parsed.moduleName : undefined);
 
     const results = new Set<string>();
@@ -185,7 +173,8 @@ export class DocumentsLocator {
    * concrete directory prefixes by enumerating subdirectories at each dynamic
    * segment. Static segments pass through unchanged.
    *
-   * Results are cached per (rootUri, searchPath) and capped at 100 entries.
+   * Results are cached per (rootUri, searchPath) and capped at
+   * MAX_DYNAMIC_PATH_EXPANSIONS entries per dynamic segment.
    */
   private async expandDynamicPath(rootUri: URI, searchPath: string): Promise<string[]> {
     const segments = searchPath.split('/');
@@ -211,9 +200,9 @@ export class DocumentsLocator {
         }
         for (const sub of subdirs) {
           nextPrefixes.push(prefix ? `${prefix}/${sub}` : sub);
-          if (nextPrefixes.length >= 100) break;
+          if (nextPrefixes.length >= MAX_DYNAMIC_PATH_EXPANSIONS) break;
         }
-        if (nextPrefixes.length >= 100) break;
+        if (nextPrefixes.length >= MAX_DYNAMIC_PATH_EXPANSIONS) break;
       }
       prefixes = nextPrefixes;
     }
@@ -269,7 +258,7 @@ export class DocumentsLocator {
    * Returns undefined for theme_render_rc (ambiguous search path) and asset.
    */
   locateDefault(rootUri: URI, nodeName: DocumentType, fileName: string): string | undefined {
-    const parsed = this.parseModulePath(fileName);
+    const parsed = parseModulePrefix(fileName);
 
     let basePath: string;
     let ext: string;

package/src/frontmatter.ts

@@ -0,0 +1,533 @@
+/**
+ * Frontmatter schema definitions for platformOS Liquid file types.
+ *
+ * Each Liquid file type in platformOS has a YAML frontmatter section at the
+ * top of the file that configures server-side behaviour. The schema for each
+ * type is different — Pages have slug/layout, Emails have to/from/subject, etc.
+ *
+ * This module provides:
+ *   - FrontmatterFieldSchema  — type definition for a single field
+ *   - FrontmatterSchema       — type definition for a complete schema
+ *   - FRONTMATTER_SCHEMAS     — per-type schemas keyed by PlatformOSFileType
+ *   - getFrontmatterSchema()  — convenience lookup that returns undefined for
+ *                               types without a frontmatter schema
+ */
+
+import { FILE_TYPE_DIRS, PlatformOSFileType } from './path-utils';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type FrontmatterFieldType = 'string' | 'boolean' | 'integer' | 'number' | 'array' | 'object';
+
+export interface FrontmatterFieldSchema {
+  /** The expected YAML type(s) for this field's value. */
+  type: FrontmatterFieldType | FrontmatterFieldType[];
+  /** Whether this field must be present. */
+  required?: boolean;
+  /** Human-readable description of this field. */
+  description?: string;
+  /** Whether this field name is deprecated in favour of a newer one. */
+  deprecated?: boolean;
+  /** Message shown when this deprecated field is used. */
+  deprecatedMessage?: string;
+  /**
+   * Allowed values for this field. When set, a validator should warn if the
+   * field value is not one of these entries.
+   */
+  enumValues?: (string | number)[];
+}
+
+export interface FrontmatterSchema {
+  /** Human-readable name of the file type, used in diagnostics. */
+  name: string;
+  /**
+   * Known frontmatter fields.
+   * Checks can use this to surface unknown keys or missing required keys.
+   * Any key not listed here will produce an "unknown field" warning.
+   */
+  fields: Record<string, FrontmatterFieldSchema>;
+}
+
+// ─── Schemas ──────────────────────────────────────────────────────────────────
+
+/**
+ * Per-type frontmatter schemas.
+ *
+ * Only Liquid file types are present here — GraphQL, YAML, and Asset types
+ * do not use frontmatter.
+ *
+ * Field lists are derived from the server-side converter files in
+ * app/services/app_builder/converters/. Enum constraints mirror server validations.
+ * Unknown keys always produce a warning; file types with arbitrary frontmatter
+ * (e.g. Migration) are omitted so no validation runs for them.
+ */
+export const FRONTMATTER_SCHEMAS: Partial<Record<PlatformOSFileType, FrontmatterSchema>> = {
+  // ── Page ─────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Page]: {
+    name: 'Page',
+    fields: {
+      slug: {
+        type: 'string',
+        description: 'URL slug for this page. Supports dynamic segments (e.g. users/:id).',
+      },
+      layout: {
+        type: 'string',
+        description: 'Layout template to wrap this page (path relative to app root, no extension).',
+      },
+      layout_name: {
+        type: 'string',
+        description: 'Alias for layout.',
+        deprecated: true,
+        deprecatedMessage: 'Use `layout` instead of `layout_name`.',
+      },
+      method: {
+        type: 'string',
+        description: 'HTTP method this page responds to.',
+        enumValues: ['delete', 'get', 'patch', 'post', 'put', 'options'],
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect to.',
+      },
+      redirect_url: {
+        type: 'string',
+        description: 'Alias for redirect_to.',
+        deprecated: true,
+        deprecatedMessage: 'Use `redirect_to` instead of `redirect_url`.',
+      },
+      redirect_code: {
+        type: 'integer',
+        description: 'HTTP redirect status code.',
+        enumValues: [301, 302, 307],
+      },
+      authorization_policies: {
+        type: 'array',
+        description: 'List of authorization policy names that must pass before rendering.',
+      },
+      response_headers: {
+        type: 'string',
+        description: 'Liquid template that renders a JSON object of HTTP response headers.',
+      },
+      metadata: {
+        type: 'object',
+        description: 'Arbitrary metadata object (e.g. SEO title/description, robots directives).',
+      },
+      max_deep_level: {
+        type: 'integer',
+        description: 'Maximum number of dynamic URL segments to capture.',
+      },
+      searchable: {
+        type: 'boolean',
+        description: 'Whether this page is included in platformOS search indexes.',
+      },
+      format: {
+        type: 'string',
+        description: 'Response format (html, json, xml, csv, …). Often encoded in the filename.',
+      },
+      default_layout: {
+        type: 'boolean',
+        description: 'Use the instance default layout.',
+      },
+      handler: {
+        type: 'string',
+        description: 'Template handler type.',
+      },
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+      dynamic_cache: {
+        type: 'object',
+        description: 'Dynamic cache settings: { key, layout, expire }.',
+      },
+      static_cache: {
+        type: 'object',
+        description: 'Static cache settings: { expire }.',
+      },
+      cache_for: {
+        type: 'integer',
+        description: 'Static cache expiration in seconds.',
+      },
+      subdomain: {
+        type: 'string',
+        description: 'Subdomain routing.',
+      },
+      require_verified_user: {
+        type: 'boolean',
+      },
+      admin_page: {
+        type: 'boolean',
+      },
+      enable_profiler: {
+        type: 'boolean',
+      },
+      metadata_title: {
+        type: 'string',
+        description: 'SEO <title> shorthand (alias for metadata.title).',
+      },
+      metadata_meta_description: {
+        type: 'string',
+        description: 'SEO meta description shorthand (alias for metadata.meta_description).',
+      },
+      metadata_canonical_url: {
+        type: 'string',
+        description: 'Canonical URL shorthand (alias for metadata.canonical_url).',
+      },
+    },
+  },
+
+  // ── Layout ───────────────────────────────────────────────────────────────────
+  // liquid_view_converter.rb: primary_key derived from physical_file_path; no `name` property.
+  [PlatformOSFileType.Layout]: {
+    name: 'Layout',
+    fields: {
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Partial ──────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Partial]: {
+    name: 'Partial',
+    fields: {
+      metadata: {
+        type: 'object',
+        description:
+          'Partial metadata. `metadata.params` declares accepted parameters; `metadata.name` is a human-readable label for the style guide.',
+      },
+      converter: {
+        type: 'string',
+        description: 'Content converter, e.g. `markdown`.',
+      },
+    },
+  },
+
+  // ── AuthorizationPolicy ──────────────────────────────────────────────────────
+  // authorization_policy_converter.rb: name, content, flash_alert, redirect_to, http_status, metadata.
+  // Note: only flash_alert is supported — flash_notice is NOT a valid property here.
+  [PlatformOSFileType.Authorization]: {
+    name: 'AuthorizationPolicy',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this authorization policy.',
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect the user to when the policy fails.',
+      },
+      flash_alert: {
+        type: 'string',
+        description: 'Flash alert message shown after a failed authorization redirect.',
+      },
+      http_status: {
+        type: 'integer',
+        description: 'HTTP status code returned on policy failure.',
+        enumValues: [403, 404],
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Email ────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Email]: {
+    name: 'Email',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this email notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Recipient email address (may use Liquid).',
+      },
+      from: {
+        type: 'string',
+        description: 'Sender email address.',
+      },
+      reply_to: {
+        type: 'string',
+        description: 'Reply-to email address.',
+      },
+      cc: {
+        type: 'string',
+        description: 'Carbon-copy recipients.',
+      },
+      bcc: {
+        type: 'string',
+        description: 'Blind carbon-copy recipients.',
+      },
+      subject: {
+        type: 'string',
+        description: 'Email subject line (may use Liquid).',
+      },
+      layout: {
+        type: 'string',
+        description: 'Layout partial to wrap the email body.',
+      },
+      layout_path: {
+        type: 'string',
+        description: 'Alias for layout.',
+        deprecated: true,
+        deprecatedMessage: 'Use `layout` instead of `layout_path`.',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay delivery after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this email is never sent. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description:
+          'Liquid expression or boolean; email is only sent when this evaluates to true.',
+      },
+      locale: {
+        type: 'string',
+        description: 'Locale for the email.',
+      },
+      forced: {
+        type: 'boolean',
+      },
+      attachments: {
+        type: 'string',
+      },
+      unique_args: {
+        type: 'object',
+        description: 'Extra key/value pairs passed to the email delivery provider.',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── ApiCall ──────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.ApiCall]: {
+    name: 'ApiCall',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this API call notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Target URL for the HTTP request (may use Liquid).',
+      },
+      request_type: {
+        type: 'string',
+        description: 'HTTP method: GET, POST, PUT, PATCH, or DELETE.',
+        enumValues: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+      },
+      request_headers: {
+        type: 'string',
+        description: 'Liquid template rendering a JSON object of request headers.',
+      },
+      headers: {
+        type: 'string',
+        description: 'Alias for request_headers.',
+        deprecated: true,
+        deprecatedMessage: 'Use `request_headers` instead of `headers`.',
+      },
+      callback: {
+        type: 'string',
+        description: 'Liquid template executed after the HTTP response is received.',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay the request after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this API call is never executed. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description: 'Liquid expression or boolean; call is only made when this evaluates to true.',
+      },
+      format: {
+        type: 'string',
+        description: 'Request body encoding format (http, json, …).',
+      },
+      locale: {
+        type: 'string',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── Sms ──────────────────────────────────────────────────────────────────────
+  [PlatformOSFileType.Sms]: {
+    name: 'SMS',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this SMS notification.',
+      },
+      to: {
+        type: 'string',
+        description: 'Recipient phone number in E.164 format (may use Liquid).',
+      },
+      content: {
+        type: 'string',
+        description: 'SMS body (may use Liquid).',
+      },
+      delay: {
+        type: 'integer',
+        description: 'Seconds to delay sending after being triggered.',
+      },
+      enabled: {
+        type: 'boolean',
+        description: 'When false, this SMS is never sent. Defaults to true.',
+      },
+      trigger_condition: {
+        type: ['boolean', 'string'],
+        description: 'Liquid expression or boolean; SMS is only sent when this evaluates to true.',
+      },
+      locale: {
+        type: 'string',
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+
+  // ── FormConfiguration ────────────────────────────────────────────────────────
+  [PlatformOSFileType.FormConfiguration]: {
+    name: 'FormConfiguration',
+    fields: {
+      name: {
+        type: 'string',
+        description: 'Unique identifier for this form, used in include_form / function calls.',
+      },
+      resource: {
+        type: ['string', 'object'],
+        description: 'Model or resource type this form operates on.',
+      },
+      resource_owner: {
+        type: 'string',
+        description: 'Who owns the resource being created/updated.',
+      },
+      fields: {
+        type: 'object',
+        description: 'Field definitions — what data this form accepts and validates.',
+      },
+      configuration: {
+        type: 'object',
+        description: 'Alias for fields.',
+      },
+      redirect_to: {
+        type: 'string',
+        description: 'URL to redirect to after a successful form submission.',
+      },
+      return_to: {
+        type: 'string',
+        description: 'Alias for redirect_to.',
+        deprecated: true,
+        deprecatedMessage: 'Use `redirect_to` instead of `return_to`.',
+      },
+      flash_notice: {
+        type: 'string',
+        description: 'Flash notice message shown after a successful submission.',
+      },
+      flash_alert: {
+        type: 'string',
+        description: 'Flash alert message shown after a failed submission.',
+      },
+      spam_protection: {
+        type: 'string',
+        description: 'Spam protection mechanism to use.',
+        enumValues: ['recaptcha', 'recaptcha_v2', 'recaptcha_v3', 'hcaptcha'],
+      },
+      request_allowed: {
+        type: 'boolean',
+        description: 'Whether the request is allowed. Default: true.',
+      },
+      live_reindex: {
+        type: 'boolean',
+      },
+      default_payload: {
+        type: ['string', 'object'],
+      },
+      callback_actions: {
+        type: 'string',
+        description: 'Liquid template with GraphQL mutations to run after submission.',
+      },
+      async_callback_actions: {
+        type: 'object',
+        description: 'Async callback settings: { content, delay, max_attempts, priority }.',
+      },
+      email_notifications: {
+        type: 'array',
+        description: 'Email notification names to trigger after successful form submission.',
+      },
+      sms_notifications: {
+        type: 'array',
+        description: 'SMS notification names to trigger after successful form submission.',
+      },
+      api_call_notifications: {
+        type: 'array',
+        description: 'API call notification names to trigger after successful form submission.',
+      },
+      response_headers: {
+        type: ['string', 'object'],
+      },
+      metadata: {
+        type: 'object',
+      },
+    },
+  },
+};
+
+// ─── Lookup helper ────────────────────────────────────────────────────────────
+
+/**
+ * Returns the frontmatter schema for a given file type, or undefined if no
+ * schema is defined for that type (e.g. GraphQL, YAML, Asset types).
+ */
+export function getFrontmatterSchema(
+  fileType: PlatformOSFileType | undefined,
+): FrontmatterSchema | undefined {
+  if (fileType === undefined) return undefined;
+  return FRONTMATTER_SCHEMAS[fileType];
+}
+
+// ─── Frontmatter association directories ──────────────────────────────────────
+
+/**
+ * Maps frontmatter list-field names to their canonical app-relative directory.
+ *
+ * Derived from FILE_TYPE_DIRS[type][0] so it always stays in sync with the
+ * single source of truth in path-utils.ts.
+ *
+ * Used by both the ValidFrontmatter check (file-existence validation) and the
+ * FrontmatterDefinitionProvider (go-to-definition) to resolve association paths.
+ */
+export const FRONTMATTER_ASSOCIATION_DIRS: Readonly<Record<string, string>> = {
+  authorization_policies: FILE_TYPE_DIRS[PlatformOSFileType.Authorization][0],
+  email_notifications: FILE_TYPE_DIRS[PlatformOSFileType.Email][0],
+  sms_notifications: FILE_TYPE_DIRS[PlatformOSFileType.Sms][0],
+  api_call_notifications: FILE_TYPE_DIRS[PlatformOSFileType.ApiCall][0],
+};
+
+// ─── Liquid expression detection ──────────────────────────────────────────────
+
+/**
+ * Returns true if the value contains a Liquid output tag (`{{`) or tag (`{%`).
+ * Used to skip static validation of dynamic frontmatter values.
+ */
+export function containsLiquid(value: string): boolean {
+  return value.includes('{{') || value.includes('{%');
+}

package/src/index.ts

@@ -3,3 +3,4 @@ export * from './translation-provider/TranslationProvider';
 export * from './route-table';
 export * from './AbstractFileSystem';
 export * from './path-utils';
+export * from './frontmatter';

package/src/path-utils.ts

@@ -220,6 +220,19 @@ export function isKnownLiquidFile(uri: UriString): boolean {
   return type !== undefined && LIQUID_FILE_TYPES.has(type);
 }
 
+/**
+ * Returns true if the URI has a `.liquid` extension but does not match any
+ * recognized platformOS directory. Useful for detecting misplaced files that
+ * the server will silently ignore.
+ *
+ * @example
+ * isUnclassifiedLiquidFile('file:///project/scripts/helper.liquid') // → true
+ * isUnclassifiedLiquidFile('file:///project/app/views/pages/home.liquid') // → false (Page)
+ */
+export function isUnclassifiedLiquidFile(uri: UriString): boolean {
+  return uri.endsWith('.liquid') && getFileType(uri) === undefined;
+}
+
 /**
  * Returns true if the URI belongs to a recognized platformOS GraphQL directory
  * and should be linted. Files outside known directories (e.g. generator
@@ -264,3 +277,45 @@ export function isMigration(uri: UriString): boolean {
 export function isFormConfiguration(uri: UriString): boolean {
   return getFileType(uri) === PlatformOSFileType.FormConfiguration;
 }
+
+// ─── Module prefix utilities ──────────────────────────────────────────────────
+
+/**
+ * Result of parsing a `modules/{name}/...` prefix from a path or key.
+ * Used by DocumentsLocator and TranslationProvider to route lookups to the
+ * correct module directory.
+ */
+export type ModulePrefix =
+  | { isModule: false; key: string }
+  | { isModule: true; moduleName: string; key: string };
+
+/**
+ * Parse a `modules/{name}/{rest}` prefix from a path or translation key.
+ * Returns the module name and the remaining key, or marks it as non-module.
+ *
+ * @example
+ * parseModulePrefix('modules/community/components/card') // → { isModule: true, moduleName: 'community', key: 'components/card' }
+ * parseModulePrefix('modules/community/hello.world')     // → { isModule: true, moduleName: 'community', key: 'hello.world' }
+ * parseModulePrefix('app/views/partials/card')           // → { isModule: false, key: 'app/views/partials/card' }
+ * parseModulePrefix('modules/community')                 // → { isModule: false, key: 'modules/community' } (no key segment)
+ */
+export function parseModulePrefix(path: string): ModulePrefix {
+  if (!path.startsWith('modules/')) {
+    return { isModule: false, key: path };
+  }
+
+  const withoutPrefix = path.slice('modules/'.length);
+  const slashIdx = withoutPrefix.indexOf('/');
+
+  if (slashIdx === -1) {
+    // Just "modules/name" with no key segment
+    return { isModule: false, key: path };
+  }
+
+  const moduleName = withoutPrefix.slice(0, slashIdx);
+  const key = withoutPrefix.slice(slashIdx + 1);
+
+  // moduleName must be non-empty to be a valid module prefix.
+  // key may be empty (e.g. 'modules/users/') — that means "all files in the module".
+  return moduleName ? { isModule: true, moduleName, key } : { isModule: false, key: path };
+}