@platformos/platformos-check-common 0.0.16 → 0.0.18

package/src/checks/valid-frontmatter/index.ts

@@ -0,0 +1,344 @@
+import { isMap, isScalar, isSeq, parseDocument } from 'yaml';
+import { LiquidCheckDefinition, RelativePath, Severity, SourceCodeType } from '../../types';
+import {
+  containsLiquid,
+  FRONTMATTER_ASSOCIATION_DIRS,
+  getFrontmatterSchema,
+  getFileType,
+  PlatformOSFileType,
+} from '@platformos/platformos-common';
+import { doesFileExist } from '../../utils/file-utils';
+
+export const ValidFrontmatter: LiquidCheckDefinition = {
+  meta: {
+    code: 'ValidFrontmatter',
+    name: 'Valid Frontmatter',
+    docs: {
+      description:
+        'Validates YAML frontmatter properties (required fields, allowed values, deprecated keys) for known platformOS file types.',
+      recommended: true,
+      url: undefined,
+    },
+    type: SourceCodeType.LiquidHtml,
+    severity: Severity.WARNING,
+    schema: {},
+    targets: [],
+  },
+
+  create(context) {
+    return {
+      async onCodePathStart(file) {
+        const source = file.source;
+
+        if (/(?:^|\/)home\.html\.liquid$/.test(file.uri)) {
+          context.report({
+            message:
+              "'home.html.liquid' is deprecated. Rename to 'index.html.liquid' to serve as the root page.",
+            startIndex: 0,
+            endIndex: 0,
+          });
+        }
+
+        // Locate the frontmatter block — may be preceded by whitespace
+        const trimmed = source.trimStart();
+        if (!trimmed.startsWith('---')) return;
+
+        const leadingLen = source.length - trimmed.length;
+        const firstNewline = trimmed.indexOf('\n');
+        if (firstNewline === -1) return;
+
+        const afterOpening = trimmed.slice(firstNewline + 1);
+
+        // The closing `---` may be the very first line of afterOpening (empty frontmatter)
+        // or may follow a newline (normal frontmatter with content).
+        let yamlBody: string;
+        if (afterOpening.startsWith('---')) {
+          yamlBody = '';
+        } else {
+          const closeIdx = afterOpening.indexOf('\n---');
+          if (closeIdx === -1) return;
+          yamlBody = afterOpening.slice(0, closeIdx);
+        }
+        // Absolute offset of the first character of yamlBody in source
+        const bodyOffset = leadingLen + firstNewline + 1;
+
+        const fileType = getFileType(file.uri);
+        const schema = getFrontmatterSchema(fileType);
+        if (!schema) return;
+
+        // Parse YAML with position tracking (yaml v2 provides range arrays).
+        // Continue even when the document has parse errors — parseDocument is
+        // lenient and still builds a partial map for the valid pairs it finds.
+        // Normalize CRLF → LF so YAML values don't contain stray \r characters.
+        const doc = parseDocument(yamlBody.replace(/\r\n/g, '\n').replace(/\r/g, '\n'));
+
+        // Build lookup: key → { jsValue, absStart, absEnd, valueAbsStart, valueAbsEnd }
+        type Entry = {
+          jsValue: unknown;
+          absStart: number;
+          absEnd: number;
+          valueAbsStart: number;
+          valueAbsEnd: number;
+        };
+        const entries = new Map<string, Entry>();
+
+        // Only populate entries when the document parsed to a map (non-empty frontmatter).
+        // When frontmatter is empty (`---\n---\n`) doc.contents is null — entries stays empty
+        // and required-field validation below will still fire correctly.
+        if (isMap(doc.contents)) {
+          for (const pair of doc.contents.items) {
+            const keyNode = pair.key;
+            if (!isScalar(keyNode) || typeof keyNode.value !== 'string') continue;
+            const [ks = 0, ke = 0] = keyNode.range ?? [];
+            const valNode = isScalar(pair.value) ? pair.value : undefined;
+            const jsValue = valNode?.value;
+            const [vs = 0, ve = 0] = valNode?.range ?? [];
+            entries.set(keyNode.value, {
+              jsValue,
+              absStart: bodyOffset + ks,
+              absEnd: bodyOffset + ke,
+              valueAbsStart: bodyOffset + vs,
+              valueAbsEnd: bodyOffset + ve,
+            });
+          }
+        }
+
+        const frontmatterStart = leadingLen; // position of opening `---`
+
+        // 1. Required field validation
+        for (const [fieldName, fieldSchema] of Object.entries(schema.fields)) {
+          if (fieldSchema.required && !entries.has(fieldName)) {
+            context.report({
+              message: `Missing required frontmatter field '${fieldName}' in ${schema.name} file`,
+              startIndex: frontmatterStart,
+              endIndex: frontmatterStart + 3,
+            });
+          }
+        }
+
+        // 2. Unrecognized key warnings
+        for (const [key, entry] of entries) {
+          if (!(key in schema.fields)) {
+            context.report({
+              message: `Unknown frontmatter field '${key}' in ${schema.name} file`,
+              startIndex: entry.absStart,
+              endIndex: entry.absEnd,
+            });
+          }
+        }
+
+        // 3. Deprecated field warnings
+        for (const [key, entry] of entries) {
+          const fieldSchema = schema.fields[key];
+          if (fieldSchema?.deprecated) {
+            context.report({
+              message: fieldSchema.deprecatedMessage ?? `'${key}' is deprecated`,
+              startIndex: entry.absStart,
+              endIndex: entry.absEnd,
+            });
+          }
+        }
+
+        // 4. Enum validation — allowed values are defined in the schema.
+        // Comparison is case-insensitive for string values: both the field value and
+        // each enum entry are lowercased before comparing, so `GET` matches `get` etc.
+        for (const [key, entry] of entries) {
+          const fieldSchema = schema.fields[key];
+          if (!fieldSchema?.enumValues) continue;
+          const { jsValue, absStart, absEnd } = entry;
+          // Skip enum validation for Liquid expressions — they're dynamic and can't be statically checked.
+          if (typeof jsValue === 'string' && containsLiquid(jsValue)) continue;
+          const normalizedValue = typeof jsValue === 'string' ? jsValue.toLowerCase() : jsValue;
+          const matches = fieldSchema.enumValues.some((allowed) =>
+            typeof allowed === 'string'
+              ? allowed.toLowerCase() === normalizedValue
+              : allowed === normalizedValue,
+          );
+          if (!matches) {
+            context.report({
+              message: `Invalid value '${jsValue}' for '${key}'. Must be one of: ${fieldSchema.enumValues.join(', ')}`,
+              startIndex: absStart,
+              endIndex: absEnd,
+            });
+          }
+        }
+
+        // 5. Layout association validation (Page and Email).
+        // Both types share the primary `layout` key; deprecated aliases differ per type.
+        if (fileType === PlatformOSFileType.Page || fileType === PlatformOSFileType.Email) {
+          const deprecatedAlias =
+            fileType === PlatformOSFileType.Page ? 'layout_name' : 'layout_path';
+          const layoutEntry = entries.get('layout') ?? entries.get(deprecatedAlias);
+          if (layoutEntry) {
+            if (layoutEntry.jsValue === false) {
+              // `layout: false` (YAML boolean) does NOT disable the layout — it falls back to the
+              // instance default. Use `layout: ''` to explicitly disable layout rendering.
+              context.report({
+                message:
+                  "`layout: false` falls back to the default layout. Use `layout: ''` to disable layout rendering.",
+                startIndex: layoutEntry.valueAbsStart,
+                endIndex: layoutEntry.valueAbsEnd,
+                suggest: [
+                  {
+                    message: "Replace with `layout: ''`",
+                    fix: (corrector) => {
+                      corrector.replace(layoutEntry.valueAbsStart, layoutEntry.valueAbsEnd, "''");
+                    },
+                  },
+                ],
+              });
+            } else if (
+              typeof layoutEntry.jsValue === 'string' &&
+              layoutEntry.jsValue !== '' &&
+              !containsLiquid(layoutEntry.jsValue)
+            ) {
+              await checkLayoutExists(layoutEntry.jsValue, layoutEntry, context);
+            }
+          }
+        }
+
+        // 6. Authorization policy association validation (Page)
+        if (fileType === PlatformOSFileType.Page) {
+          await checkNotificationArray(
+            doc,
+            bodyOffset,
+            'authorization_policies',
+            `app/${FRONTMATTER_ASSOCIATION_DIRS['authorization_policies']}`,
+            'Authorization policy',
+            context,
+          );
+        }
+
+        // 7. Notification association validation (FormConfiguration)
+        if (fileType === PlatformOSFileType.FormConfiguration) {
+          for (const [field, dir] of Object.entries(FRONTMATTER_ASSOCIATION_DIRS)) {
+            if (field === 'authorization_policies') continue; // only on Page, handled above
+            await checkNotificationArray(
+              doc,
+              bodyOffset,
+              field,
+              `app/${dir}`,
+              fieldLabel(field),
+              context,
+            );
+          }
+        }
+      },
+    };
+  },
+};
+
+/**
+ * Checks each string item of a YAML sequence field against the filesystem.
+ *
+ * App-level items (e.g. `require_login`) are looked up at `{dir}/{name}.liquid`.
+ * Module-prefixed items (e.g. `modules/community/require_login`) are looked up
+ * at modules/{mod}/{public|private}/{moduleDir}/{name}.liquid where moduleDir
+ * is derived from dir by stripping the leading `app/` segment.
+ */
+async function checkNotificationArray(
+  doc: ReturnType<typeof parseDocument>,
+  bodyOffset: number,
+  fieldName: string,
+  dir: string,
+  label: string,
+  context: Parameters<LiquidCheckDefinition['create']>[0],
+) {
+  if (!isMap(doc.contents)) return;
+  const pair = doc.contents.items.find((p) => isScalar(p.key) && p.key.value === fieldName);
+  if (!pair || !isSeq(pair.value)) return;
+
+  // Module-relative dir: strip leading 'app/' (e.g. 'app/authorization_policies' → 'authorization_policies')
+  const moduleDir = dir.slice('app/'.length);
+
+  for (const item of pair.value.items) {
+    if (!isScalar(item) || typeof item.value !== 'string') continue;
+    const name = item.value;
+    if (containsLiquid(name)) continue;
+    const [is = 0, ie = 0] = item.range ?? [];
+
+    let exists: boolean;
+    if (name.startsWith('modules/')) {
+      const match = name.match(/^modules\/([^/]+)\/(.+)$/);
+      if (!match) {
+        exists = false;
+      } else {
+        const [, mod, rest] = match;
+        exists =
+          (await doesFileExist(
+            context,
+            `modules/${mod}/public/${moduleDir}/${rest}.liquid` as RelativePath,
+          )) ||
+          (await doesFileExist(
+            context,
+            `modules/${mod}/private/${moduleDir}/${rest}.liquid` as RelativePath,
+          ));
+      }
+    } else {
+      exists = await doesFileExist(context, `${dir}/${name}.liquid` as RelativePath);
+    }
+
+    if (!exists) {
+      context.report({
+        message: `${label} '${name}' does not exist`,
+        startIndex: bodyOffset + is,
+        endIndex: bodyOffset + ie,
+      });
+    }
+  }
+}
+
+/**
+ * Tries both `{base}.liquid` and `{base}.html.liquid` since layout files may
+ * carry a format extension (e.g. `application.html.liquid`).
+ */
+async function layoutFileExists(
+  context: Parameters<LiquidCheckDefinition['create']>[0],
+  base: string,
+): Promise<boolean> {
+  return (
+    (await doesFileExist(context, `${base}.liquid` as RelativePath)) ||
+    (await doesFileExist(context, `${base}.html.liquid` as RelativePath))
+  );
+}
+
+async function checkLayoutExists(
+  layoutName: string,
+  entry: { absStart: number; absEnd: number },
+  context: Parameters<LiquidCheckDefinition['create']>[0],
+) {
+  let exists: boolean;
+
+  if (layoutName.startsWith('modules/')) {
+    // modules/{mod}/rest → modules/{mod}/{public,private}/views/layouts/{rest}.{html.}liquid
+    const match = layoutName.match(/^modules\/([^/]+)\/(.+)$/);
+    if (!match) return;
+    const [, mod, rest] = match;
+    exists =
+      (await layoutFileExists(context, `modules/${mod}/public/views/layouts/${rest}`)) ||
+      (await layoutFileExists(context, `modules/${mod}/private/views/layouts/${rest}`));
+  } else {
+    exists = await layoutFileExists(context, `app/views/layouts/${layoutName}`);
+  }
+
+  if (!exists) {
+    context.report({
+      message: `Layout '${layoutName}' does not exist`,
+      startIndex: entry.absStart,
+      endIndex: entry.absEnd,
+    });
+  }
+}
+
+function fieldLabel(field: string): string {
+  switch (field) {
+    case 'email_notifications':
+      return 'Email notification';
+    case 'sms_notifications':
+      return 'SMS notification';
+    case 'api_call_notifications':
+      return 'API call notification';
+    default:
+      return field;
+  }
+}

package/src/frontmatter/index.ts

@@ -1,344 +1,9 @@
-/**
- * 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 { PlatformOSFileType } from '@platformos/platformos-common';
-
-// ─── 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;
-}
-
-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.
-   */
-  fields: Record<string, FrontmatterFieldSchema>;
-  /**
-   * Whether fields not listed in `fields` are allowed without a warning.
-   * Defaults to true — schemas are additive and may not be exhaustive.
-   */
-  allowAdditionalFields?: boolean;
-}
-
-// ─── Schemas ──────────────────────────────────────────────────────────────────
-
-/**
- * Per-type frontmatter schemas.
- *
- * Only Liquid file types are present here — GraphQL, YAML, and Asset types
- * do not use frontmatter.
- *
- * Field lists are based on real-world usage in platformOS apps. Set
- * `allowAdditionalFields: true` (the default) everywhere so that apps using
- * custom/undocumented keys don't get false-positive warnings until the schemas
- * are finalised.
- */
-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 (get, post, put, patch, delete).',
-      },
-      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.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── Layout ───────────────────────────────────────────────────────────────────
-  [PlatformOSFileType.Layout]: {
-    name: 'Layout',
-    fields: {
-      name: {
-        type: 'string',
-        description: 'Identifier used to reference this layout from pages.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── 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.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── AuthorizationPolicy ──────────────────────────────────────────────────────
-  [PlatformOSFileType.Authorization]: {
-    name: 'AuthorizationPolicy',
-    fields: {
-      name: {
-        type: 'string',
-        required: true,
-        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.',
-      },
-      flash_notice: {
-        type: 'string',
-        description: 'Flash notice message shown after a failed authorization redirect.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── Email ────────────────────────────────────────────────────────────────────
-  [PlatformOSFileType.Email]: {
-    name: 'Email',
-    fields: {
-      to: {
-        type: 'string',
-        required: true,
-        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',
-        required: true,
-        description: 'Email subject line (may use Liquid).',
-      },
-      layout_path: {
-        type: 'string',
-        description: 'Layout partial to wrap the email body.',
-      },
-      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.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── ApiCall ──────────────────────────────────────────────────────────────────
-  [PlatformOSFileType.ApiCall]: {
-    name: 'ApiCall',
-    fields: {
-      to: {
-        type: 'string',
-        required: true,
-        description: 'Target URL for the HTTP request (may use Liquid).',
-      },
-      request_type: {
-        type: 'string',
-        required: true,
-        description: 'HTTP method: GET, POST, PUT, PATCH, or 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, …).',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── Sms ──────────────────────────────────────────────────────────────────────
-  [PlatformOSFileType.Sms]: {
-    name: 'SMS',
-    fields: {
-      to: {
-        type: 'string',
-        required: true,
-        description: 'Recipient phone number in E.164 format (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.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-
-  // ── Migration ────────────────────────────────────────────────────────────────
-  [PlatformOSFileType.Migration]: {
-    name: 'Migration',
-    fields: {},
-    allowAdditionalFields: true,
-  },
-
-  // ── FormConfiguration ────────────────────────────────────────────────────────
-  [PlatformOSFileType.FormConfiguration]: {
-    name: 'FormConfiguration',
-    fields: {
-      name: {
-        type: 'string',
-        required: true,
-        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.',
-      },
-      redirect_to: {
-        type: 'string',
-        description: 'URL to redirect to after a successful form submission.',
-      },
-      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.',
-      },
-    },
-    allowAdditionalFields: true,
-  },
-};
-
-// ─── 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 schemas and types live in platformos-common so they can be used
+// by other packages without depending on the full linting engine.
+export {
+  type FrontmatterFieldType,
+  type FrontmatterFieldSchema,
+  type FrontmatterSchema,
+  FRONTMATTER_SCHEMAS,
+  getFrontmatterSchema,
+} from '@platformos/platformos-common';