@platformos/platformos-check-common 0.0.11 → 0.0.13

package/src/checks/unused-assign/index.spec.ts

@@ -56,7 +56,7 @@ describe('Module: UnusedAssign', () => {
       {{ usedVar }}
     `;
 
-    expect(suggestions).to.include(expectedFixedCode);
+    expect(suggestions).to.deep.equal([expectedFixedCode]);
   });
 
   it('should not report unused assigns for things used in a capture tag', async () => {
@@ -127,4 +127,78 @@ describe('Module: UnusedAssign', () => {
     const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
     expect(offenses).to.have.lengthOf(1);
   });
+
+  it('should not report an offense for hash mutation via assign with lookup target', async () => {
+    const sourceCode = `
+      {% assign errors = {} %}
+      {% assign errors[field] = 'value' %}
+      {{ errors }}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not track assign with lookup as a new variable definition', async () => {
+    const sourceCode = `
+      {% assign errors[field_name] = field_errors %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via subscript', async () => {
+    // assign errors = contract.errors creates a reference; mutations on errors
+    // have side effects on the original, so they count as "using" errors.
+    const sourceCode = `
+      {% assign errors = contract.errors %}
+      {% assign errors[field_name] = field_errors %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via dot notation', async () => {
+    const sourceCode = `
+      {% assign data = response.data %}
+      {% assign data.status = 'ok' %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should not report when a reference alias is mutated via array push', async () => {
+    const sourceCode = `
+      {% assign items = cart.items %}
+      {% assign items << new_item %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(0);
+  });
+
+  it('should still report when a fresh literal hash is mutated but never used', async () => {
+    const sourceCode = `
+      {% assign x = {} %}
+      {% assign x['key'] = 'value' %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(1);
+    expect(offenses[0].message).to.equal("The variable 'x' is assigned but not used");
+  });
+
+  it('should still report when a fresh literal array is pushed to but never used', async () => {
+    const sourceCode = `
+      {% assign arr = [] %}
+      {% assign arr << item %}
+    `;
+
+    const offenses = await runLiquidCheck(UnusedAssign, sourceCode);
+    expect(offenses).to.have.lengthOf(1);
+    expect(offenses[0].message).to.equal("The variable 'arr' is assigned but not used");
+  });
 });

package/src/checks/unused-assign/index.ts

@@ -26,6 +26,10 @@ export const UnusedAssign: LiquidCheckDefinition = {
 
   create(context) {
     const assignedVariables: Map<string, LiquidTagAssign | LiquidTagCapture> = new Map();
+    // Variables assigned from a pure variable lookup (no filters, no literals).
+    // e.g. `assign errors = contract.errors` — mutations on `errors` have side
+    // effects on the original, so they count as "using" the variable.
+    const referenceAssignedVariables: Set<string> = new Set();
     const usedVariables: Set<string> = new Set();
 
     function checkVariableUsage(node: any) {
@@ -38,7 +42,28 @@ export const UnusedAssign: LiquidCheckDefinition = {
       async LiquidTag(node, ancestors) {
         if (isWithinRawTagThatDoesNotParseItsContents(ancestors)) return;
         if (isLiquidTagAssign(node)) {
-          assignedVariables.set(node.markup.name, node);
+          if (node.markup.lookups.length === 0 && node.markup.operator === '=') {
+            // Simple assignment: register as a new variable
+            assignedVariables.set(node.markup.name, node);
+            // Track pure reference assignments (VariableLookup with no filters)
+            if (
+              node.markup.value.type === NodeTypes.LiquidVariable &&
+              node.markup.value.expression.type === NodeTypes.VariableLookup &&
+              node.markup.value.filters.length === 0
+            ) {
+              referenceAssignedVariables.add(node.markup.name);
+            }
+          } else {
+            // Hash/array mutation: assign x[key]=val, assign x.key=val, assign x<<val
+            // Counts as "using" x only when x is external (not locally assigned here)
+            // or was assigned as a reference alias to another variable.
+            if (
+              !assignedVariables.has(node.markup.name) ||
+              referenceAssignedVariables.has(node.markup.name)
+            ) {
+              usedVariables.add(node.markup.name);
+            }
+          }
         } else if (isLiquidTagCapture(node) && node.markup.name) {
           assignedVariables.set(node.markup.name, node);
         }

package/src/checks/unused-doc-param/index.spec.ts

@@ -51,14 +51,16 @@ describe('Module: UnusedDocParam', () => {
     const offenses = await runLiquidCheck(UnusedDocParam, sourceCode);
     const suggestions = applySuggestions(sourceCode, offenses[0]);
 
-    expect(suggestions).to.include(`
+    expect(suggestions).to.deep.equal([
+      `
       {% doc %}
         @param param1 - Example param
         
       {% enddoc %}
 
       {{ param1 }}
-    `);
+    `,
+    ]);
   });
 
   LoopNamedTags.forEach((tag) => {

package/src/checks/valid-doc-param-types/index.spec.ts

@@ -69,7 +69,7 @@ describe('Module: ValidDocParamTypes', () => {
       expect(offenses).to.have.length(1);
       const suggestions = applySuggestions(source, offenses[0]);
 
-      expect(suggestions).to.include(`{% doc %} @param param1 - Example param {% enddoc %}`);
+      expect(suggestions).to.deep.equal([`{% doc %} @param param1 - Example param {% enddoc %}`]);
     }
   });
 });

package/src/checks/valid-render-partial-argument-types/index.spec.ts

@@ -34,7 +34,7 @@ describe('Module: ValidRenderPartialParamTypes', () => {
           { value: "'hello'", actualType: BasicParamTypes.String },
           { value: '123', actualType: BasicParamTypes.Number },
           { value: 'true', actualType: BasicParamTypes.Boolean },
-          { value: 'empty', actualType: BasicParamTypes.Boolean },
+          { value: 'empty', actualType: BasicParamTypes.String },
         ],
       },
     ];
@@ -142,6 +142,29 @@ describe('Module: ValidRenderPartialParamTypes', () => {
       expect(offenses).toHaveLength(0);
     });
 
+    it('should not report null/nil as type mismatch for any type', async () => {
+      for (const type of ['string', 'number', 'object', 'boolean']) {
+        for (const literal of ['nil', 'null']) {
+          const sourceCode = `{% render 'card', param: ${literal} %}`;
+          const offenses = await runLiquidCheck(
+            ValidRenderPartialArgumentTypes,
+            sourceCode,
+            undefined,
+            {},
+            {
+              'app/views/partials/card.liquid': `
+                {% doc %}
+                  @param {${type}} param - Description
+                {% enddoc %}
+                <div>{{ param }}</div>
+              `,
+            },
+          );
+          expect(offenses, `${literal} should be valid for ${type}`).toHaveLength(0);
+        }
+      }
+    });
+
     it('should not enforce unsupported types', async () => {
       const sourceCode = `{% render 'card', title: 123 %}`;
       const offenses = await runLiquidCheck(

package/src/checks/valid-render-partial-argument-types/index.ts

@@ -1,7 +1,7 @@
 import { LiquidCheckDefinition, Severity, SourceCodeType } from '../../types';
 import { NodeTypes, RenderMarkup } from '@platformos/liquid-html-parser';
 import { LiquidDocParameter } from '../../liquid-doc/liquidDoc';
-import { inferArgumentType, isTypeCompatible } from '../../liquid-doc/utils';
+import { inferArgumentType, isNullLiteral, isTypeCompatible } from '../../liquid-doc/utils';
 import {
   findTypeMismatchParams,
   generateTypeMismatchSuggestions,
@@ -41,7 +41,8 @@ export const ValidRenderPartialArgumentTypes: LiquidCheckDefinition = {
       if (
         node.alias &&
         node.variable?.name &&
-        node.variable.name.type !== NodeTypes.VariableLookup
+        node.variable.name.type !== NodeTypes.VariableLookup &&
+        !isNullLiteral(node.variable.name)
       ) {
         const paramIsDefinedWithType = liquidDocParameters
           .get(node.alias.value)

package/src/checks/variable-name/index.spec.ts

@@ -40,7 +40,16 @@ describe('Module: VariableName', () => {
 
     const expectedFixedCode = `{% assign variable_name = "value" %}`;
 
-    expect(suggestions).to.include(expectedFixedCode);
+    expect(suggestions).to.deep.equal([expectedFixedCode]);
+  });
+
+  it('should not report an error for variables starting with underscore', async () => {
+    const varNames = [`_`, `_errors`, `_temp_var`, `_myPrivateVar`];
+    for (const varName of varNames) {
+      const sourceCode = `{% assign ${varName} = "value" %}`;
+      const offenses = await runLiquidCheck(VariableName, sourceCode);
+      expect(offenses).to.be.empty;
+    }
   });
 
   // It's impossible to make an idempotent rule that works for all cases. We

package/src/checks/variable-name/index.ts

@@ -65,6 +65,11 @@ export const VariableName: LiquidCheckDefinition<typeof schema> = {
         };
       }
 
+      // Variables starting with _ are valid (used as throwaway/private variables)
+      if (node.markup.name.startsWith('_')) {
+        return { valid: true };
+      }
+
       const formatter = formatTypes[context.settings.format as FormatTypes];
       const suggestion = formatter(node.markup.name);
 

package/src/context-utils.ts

@@ -3,6 +3,7 @@ import {
   AbstractFileSystem,
   FileTuple,
   FileType,
+  RouteTable,
   TranslationProvider,
   UriString,
 } from '@platformos/platformos-common';
@@ -131,6 +132,31 @@ function getDefaultTranslationsFromBuffer(app: App): Translations | undefined {
   }
 }
 
+export function makeGetRouteTable(
+  fs: AbstractFileSystem,
+  rootUri: string,
+  existingTable?: RouteTable,
+): () => Promise<RouteTable> {
+  const table = existingTable ?? new RouteTable(fs);
+  let buildPromise: Promise<RouteTable> | null = null;
+  return () => {
+    if (!buildPromise) {
+      if (table.isBuilt()) {
+        buildPromise = Promise.resolve(table);
+      } else {
+        buildPromise = table
+          .build(URI.parse(rootUri))
+          .then(() => table)
+          .catch((err) => {
+            buildPromise = null;
+            throw err;
+          });
+      }
+    }
+    return buildPromise;
+  };
+}
+
 function cached<T>(fn: () => Promise<T>): () => Promise<T>;
 function cached<T>(fn: (...args: any[]) => Promise<T>): (...args: any[]) => Promise<T> {
   let cachedPromise: Promise<T>;
@@ -145,7 +171,13 @@ export async function recursiveReadDirectory(
   uri: string,
   filter: (fileTuple: FileTuple) => boolean,
 ): Promise<UriString[]> {
-  const allFiles = await fs.readDirectory(uri);
+  let allFiles: FileTuple[];
+  try {
+    allFiles = await fs.readDirectory(uri);
+  } catch (err: any) {
+    if (err?.code === 'ENOENT') return [];
+    throw err;
+  }
   const files = allFiles.filter((ft) => !isIgnored(ft) && (isDirectory(ft) || filter(ft)));
 
   const results = await Promise.all(

package/src/frontmatter/index.ts

@@ -0,0 +1,344 @@
+/**
+ * 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];
+}

package/src/index.ts

@@ -5,6 +5,7 @@ import {
   makeFileSize,
   makeGetDefaultLocale,
   makeGetDefaultTranslations,
+  makeGetRouteTable,
   makeGetTranslationsForBase,
 } from './context-utils';
 import { createDisabledChecksModule } from './disabled-checks';
@@ -56,6 +57,8 @@ export {
   isApiCall,
   isAuthorization,
   isEmail,
+  isFormConfiguration,
+  isKnownGraphQLFile,
   isKnownLiquidFile,
   isLayout,
   isMigration,
@@ -64,6 +67,7 @@ export {
   isSms,
   PlatformOSFileType,
 } from '@platformos/platformos-common';
+export * from './frontmatter';
 export * from './json';
 export * from './JSONValidator';
 export * as path from './path';
@@ -77,6 +81,7 @@ export * from './utils/object';
 export * from './visitor';
 export * from './liquid-doc/liquidDoc';
 export * from './liquid-doc/utils';
+export * from './url-helpers';
 
 const defaultErrorHandler = (_error: Error): void => {
   // Silently ignores errors by default.
@@ -98,6 +103,7 @@ export async function check(
     getDefaultLocale: makeGetDefaultLocale(fs, rootUri),
     getDefaultTranslations: makeGetDefaultTranslations(fs, app, rootUri),
     getTranslationsForBase: makeGetTranslationsForBase(fs, app),
+    getRouteTable: makeGetRouteTable(fs, rootUri, injectedDependencies.routeTable),
   };
 
   const { DisabledChecksVisitor, isDisabled } = createDisabledChecksModule();