@platformos/platformos-check-common 0.0.11 → 0.0.12

package/dist/doc-generator/DocBlockGenerator.js

@@ -0,0 +1,464 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocBlock = generateDocBlock;
+const liquid_html_parser_1 = require("@platformos/liquid-html-parser");
+const utils_1 = require("../utils");
+const visitor_1 = require("../visitor");
+const utils_2 = require("../liquid-doc/utils");
+/**
+ * Generate a doc block for a partial/block based on detected parameters and inferred types.
+ */
+async function generateDocBlock(ast, uri, themeDocset) {
+    if ((0, utils_1.isError)(ast)) {
+        return {
+            parameters: [],
+            hasExistingDocBlock: false,
+            docBlockText: '',
+        };
+    }
+    // Check for existing doc block
+    const hasExistingDocBlock = await hasDocBlock(ast);
+    // Get global objects that should not be treated as parameters
+    const globalObjectNames = await getGlobalObjectNames(themeDocset);
+    // Get contextual objects based on file path
+    const contextualObjectNames = getContextualObjects(uri);
+    // Collect all variable usages and definitions
+    const { usages, definedVariables, docParamNames } = await collectVariableInfo(ast);
+    // Detect parameters: variables used but not defined (excluding globals/contextuals)
+    const excludedNames = new Set([
+        ...globalObjectNames,
+        ...contextualObjectNames,
+        ...definedVariables,
+        ...docParamNames,
+    ]);
+    const parameterUsages = new Map();
+    for (const usage of usages) {
+        if (!usage.name || excludedNames.has(usage.name))
+            continue;
+        // Group usages by parameter name
+        if (!parameterUsages.has(usage.name)) {
+            parameterUsages.set(usage.name, []);
+        }
+        parameterUsages.get(usage.name).push(usage);
+    }
+    // Infer types and detect optional parameters
+    const parameters = [];
+    for (const [name, usageList] of parameterUsages) {
+        const type = inferTypeFromUsages(usageList);
+        const isOptional = detectOptional(usageList);
+        parameters.push({ name, type, isOptional });
+    }
+    // Sort parameters: required first, then by name
+    parameters.sort((a, b) => {
+        if (a.isOptional !== b.isOptional) {
+            return a.isOptional ? 1 : -1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    // Generate doc block text
+    const docBlockText = formatDocBlock(parameters);
+    return {
+        parameters,
+        hasExistingDocBlock,
+        docBlockText,
+    };
+}
+/**
+ * Check if the AST already has a {% doc %} block.
+ */
+async function hasDocBlock(ast) {
+    let found = false;
+    await (0, visitor_1.visit)(ast, {
+        async LiquidRawTag(node) {
+            if (node.name === 'doc') {
+                found = true;
+            }
+        },
+    });
+    return found;
+}
+/**
+ * Get global object names from the theme docset.
+ */
+async function getGlobalObjectNames(themeDocset) {
+    if (!themeDocset)
+        return new Set();
+    const objects = await themeDocset.objects();
+    const globalObjects = objects.filter(({ access }) => {
+        return !access || access.global === true || access.template.length > 0;
+    });
+    return new Set(globalObjects.map((obj) => obj.name));
+}
+/**
+ * Get contextual objects based on file path.
+ */
+function getContextualObjects(uri) {
+    if (uri.includes('layout/checkout.liquid')) {
+        return [
+            'locale',
+            'direction',
+            'skip_to_content_link',
+            'checkout_html_classes',
+            'checkout_stylesheets',
+            'checkout_scripts',
+            'content_for_logo',
+            'breadcrumb',
+            'order_summary_toggle',
+            'content_for_order_summary',
+            'alternative_payment_methods',
+            'content_for_footer',
+            'tracking_code',
+        ];
+    }
+    if (uri.includes('/sections/')) {
+        return ['section', 'predictive_search', 'recommendations', 'comment'];
+    }
+    if (uri.includes('/blocks/')) {
+        return ['app', 'section', 'recommendations', 'block'];
+    }
+    if (uri.includes('views/partials/') || uri.includes('/lib/')) {
+        return ['app'];
+    }
+    return [];
+}
+/**
+ * Collect all variable usages and defined variables from the AST.
+ */
+async function collectVariableInfo(ast) {
+    const scopedVariables = new Map();
+    const fileScopedVariables = new Set();
+    const usages = [];
+    const docParamNames = new Set();
+    function indexVariableScope(variableName, scope) {
+        if (!variableName)
+            return;
+        const indexedScope = scopedVariables.get(variableName) ?? [];
+        scopedVariables.set(variableName, indexedScope.concat(scope));
+    }
+    await (0, visitor_1.visit)(ast, {
+        async LiquidDocParamNode(node) {
+            const paramName = node.paramName?.value;
+            if (paramName) {
+                fileScopedVariables.add(paramName);
+                docParamNames.add(paramName);
+            }
+        },
+        async LiquidTag(node, ancestors) {
+            if (isLiquidTagAssign(node) || isLiquidTagGraphQL(node)) {
+                indexVariableScope(node.markup.name, {
+                    start: node.blockStartPosition.end,
+                });
+            }
+            if (isLiquidTagHashAssign(node) && node.markup.target.name) {
+                indexVariableScope(node.markup.target.name, {
+                    start: node.blockStartPosition.end,
+                });
+            }
+            if (isLiquidTagCapture(node)) {
+                indexVariableScope(node.markup.name, {
+                    start: node.blockEndPosition?.end,
+                });
+            }
+            if (['form', 'paginate'].includes(node.name)) {
+                indexVariableScope(node.name, {
+                    start: node.blockStartPosition.end,
+                    end: node.blockEndPosition?.start,
+                });
+            }
+            if (node.name === 'function') {
+                indexVariableScope(node.markup.name, {
+                    start: node.position.end,
+                });
+            }
+            if (node.name === 'layout') {
+                indexVariableScope('none', {
+                    start: node.position.start,
+                    end: node.position.end,
+                });
+            }
+            if ((isLiquidTagIncrement(node) || isLiquidTagDecrement(node)) &&
+                node.markup.name !== null) {
+                indexVariableScope(node.markup.name, {
+                    start: node.position.start,
+                });
+            }
+            if (isLiquidForTag(node) || isLiquidTableRowTag(node)) {
+                indexVariableScope(node.markup.variableName, {
+                    start: node.blockStartPosition.end,
+                    end: node.blockEndPosition?.start,
+                });
+                indexVariableScope(node.name === 'for' ? 'forloop' : 'tablerowloop', {
+                    start: node.blockStartPosition.end,
+                    end: node.blockEndPosition?.start,
+                });
+            }
+            if (isLiquidTagBackground(node)) {
+                indexVariableScope(node.markup.jobId.name, {
+                    start: node.blockEndPosition?.end,
+                });
+            }
+        },
+        async LiquidVariable(node, ancestors) {
+            // Collect variable usages from LiquidVariable nodes
+            const expression = node.expression;
+            if (expression.type === liquid_html_parser_1.NodeTypes.VariableLookup && expression.name) {
+                usages.push({
+                    name: expression.name,
+                    lookup: expression,
+                    filters: node.filters,
+                });
+            }
+        },
+        async VariableLookup(node, ancestors) {
+            const parent = (0, utils_1.last)(ancestors);
+            // Skip if inside capture tag markup (being defined, not used)
+            if (isLiquidTag(parent) && isLiquidTagCapture(parent))
+                return;
+            // Skip the jobId variable in background tag markup
+            if (isBackgroundInlineMarkup(parent) && parent.jobId === node)
+                return;
+            // Skip if this is a LiquidVariable's expression (already collected above)
+            if (parent &&
+                'expression' in parent &&
+                parent.expression === node) {
+                return;
+            }
+            if (node.name) {
+                usages.push({
+                    name: node.name,
+                    lookup: node,
+                    filters: [],
+                });
+            }
+        },
+    });
+    // Filter usages to only those that are undefined at their usage point
+    const undefinedUsages = usages.filter((usage) => {
+        if (!usage.name)
+            return false;
+        return !isDefined(usage.name, usage.lookup.position, fileScopedVariables, scopedVariables);
+    });
+    // Get all defined variables (both file-scoped and scoped)
+    const definedVariables = new Set([
+        ...fileScopedVariables,
+        ...scopedVariables.keys(),
+    ]);
+    return { usages: undefinedUsages, definedVariables, docParamNames };
+}
+/**
+ * Check if a variable is defined at a given position.
+ */
+function isDefined(variableName, variablePosition, fileScopedVariables, scopedVariables) {
+    if (fileScopedVariables.has(variableName)) {
+        return true;
+    }
+    const scopes = scopedVariables.get(variableName);
+    if (!scopes) {
+        return false;
+    }
+    return scopes.some((scope) => isDefinedInScope(variablePosition, scope));
+}
+function isDefinedInScope(variablePosition, scope) {
+    const start = variablePosition.start;
+    const isVariableAfterScopeStart = !scope.start || start > scope.start;
+    const isVariableBeforeScopeEnd = !scope.end || start < scope.end;
+    return isVariableAfterScopeStart && isVariableBeforeScopeEnd;
+}
+/**
+ * Infer type from variable usages.
+ */
+function inferTypeFromUsages(usages) {
+    // Analyze all usages to determine the most likely type
+    const typeVotes = new Map();
+    for (const usage of usages) {
+        const inferredType = inferTypeFromUsage(usage);
+        if (inferredType) {
+            const currentVotes = typeVotes.get(inferredType) || 0;
+            typeVotes.set(inferredType, currentVotes + 1);
+        }
+    }
+    // Return the type with most votes, or 'object' as default
+    let bestType = null;
+    let maxVotes = 0;
+    for (const [type, votes] of typeVotes) {
+        if (votes > maxVotes) {
+            maxVotes = votes;
+            bestType = type;
+        }
+    }
+    // If no specific type was inferred, check if it has property access (object)
+    if (!bestType) {
+        for (const usage of usages) {
+            if (usage.lookup.lookups.length > 0) {
+                return utils_2.BasicParamTypes.Object;
+            }
+        }
+    }
+    return bestType;
+}
+/**
+ * Infer type from a single variable usage.
+ */
+function inferTypeFromUsage(usage) {
+    const { lookup, filters } = usage;
+    // Check filters for type hints
+    for (const filter of filters) {
+        const typeFromFilter = inferTypeFromFilter(filter.name);
+        if (typeFromFilter) {
+            return typeFromFilter;
+        }
+    }
+    // Check property access for object type
+    if (lookup.lookups.length > 0) {
+        return utils_2.BasicParamTypes.Object;
+    }
+    return null;
+}
+/**
+ * Infer type from filter name.
+ */
+function inferTypeFromFilter(filterName) {
+    // Filters that suggest string input
+    const stringFilters = [
+        'append',
+        'prepend',
+        'capitalize',
+        'downcase',
+        'upcase',
+        'strip',
+        'lstrip',
+        'rstrip',
+        'strip_html',
+        'strip_newlines',
+        'newline_to_br',
+        'escape',
+        'escape_once',
+        'url_encode',
+        'url_decode',
+        'md5',
+        'sha1',
+        'sha256',
+        'base64_encode',
+        'base64_decode',
+        'hmac_sha1',
+        'hmac_sha256',
+        'truncate',
+        'truncatewords',
+        'split',
+        'replace',
+        'replace_first',
+        'remove',
+        'remove_first',
+        'slice',
+        'pluralize',
+    ];
+    // Filters that suggest number input
+    const numberFilters = [
+        'plus',
+        'minus',
+        'times',
+        'divided_by',
+        'modulo',
+        'floor',
+        'ceil',
+        'round',
+        'abs',
+        'at_least',
+        'at_most',
+    ];
+    // Filters that suggest array input
+    const arrayFilters = [
+        'join',
+        'first',
+        'last',
+        'size',
+        'reverse',
+        'sort',
+        'sort_natural',
+        'uniq',
+        'compact',
+        'map',
+        'where',
+        'concat',
+    ];
+    if (stringFilters.includes(filterName)) {
+        return utils_2.BasicParamTypes.String;
+    }
+    if (numberFilters.includes(filterName)) {
+        return utils_2.BasicParamTypes.Number;
+    }
+    if (arrayFilters.includes(filterName)) {
+        // Array implies object type in LiquidDoc context
+        return utils_2.BasicParamTypes.Object;
+    }
+    return null;
+}
+/**
+ * Detect if a parameter is optional (has default filter usage).
+ */
+function detectOptional(usages) {
+    for (const usage of usages) {
+        for (const filter of usage.filters) {
+            if (filter.name === 'default') {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Format the doc block text.
+ */
+function formatDocBlock(parameters) {
+    if (parameters.length === 0) {
+        return '{% doc %}\n{% enddoc %}';
+    }
+    const lines = ['{% doc %}'];
+    for (const param of parameters) {
+        const typeStr = param.type ? `{${param.type}}` : '{object}';
+        const nameStr = param.isOptional ? `[${param.name}]` : param.name;
+        lines.push(`  @param ${typeStr} ${nameStr} -`);
+    }
+    lines.push('{% enddoc %}');
+    return lines.join('\n');
+}
+// Type guard functions
+function isLiquidTag(node) {
+    return node?.type === liquid_html_parser_1.NodeTypes.LiquidTag;
+}
+function isLiquidTagCapture(node) {
+    return node.name === liquid_html_parser_1.NamedTags.capture;
+}
+function isLiquidTagAssign(node) {
+    return node.name === liquid_html_parser_1.NamedTags.assign && typeof node.markup !== 'string';
+}
+function isLiquidTagHashAssign(node) {
+    return node.name === liquid_html_parser_1.NamedTags.hash_assign && typeof node.markup !== 'string';
+}
+function isLiquidTagGraphQL(node) {
+    return node.name === liquid_html_parser_1.NamedTags.graphql && typeof node.markup !== 'string';
+}
+function isLiquidForTag(node) {
+    return node.name === liquid_html_parser_1.NamedTags.for && typeof node.markup !== 'string';
+}
+function isLiquidTableRowTag(node) {
+    return node.name === liquid_html_parser_1.NamedTags.tablerow && typeof node.markup !== 'string';
+}
+function isLiquidTagIncrement(node) {
+    return node.name === liquid_html_parser_1.NamedTags.increment && typeof node.markup !== 'string';
+}
+function isLiquidTagDecrement(node) {
+    return node.name === liquid_html_parser_1.NamedTags.decrement && typeof node.markup !== 'string';
+}
+function isLiquidTagBackground(node) {
+    return (node.name === liquid_html_parser_1.NamedTags.background &&
+        typeof node.markup !== 'string' &&
+        node.markup.type === liquid_html_parser_1.NodeTypes.BackgroundInlineMarkup);
+}
+function isBackgroundInlineMarkup(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        'type' in node &&
+        node.type === liquid_html_parser_1.NodeTypes.BackgroundInlineMarkup);
+}
+//# sourceMappingURL=DocBlockGenerator.js.map

package/dist/doc-generator/DocBlockGenerator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DocBlockGenerator.js","sourceRoot":"","sources":["../../src/doc-generator/DocBlockGenerator.ts"],"names":[],"mappings":"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"}

package/dist/doc-generator/index.d.ts

@@ -0,0 +1 @@
+export { generateDocBlock, DetectedParameter, DocBlockResult, } from './DocBlockGenerator';

package/dist/doc-generator/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDocBlock = void 0;
+var DocBlockGenerator_1 = require("./DocBlockGenerator");
+Object.defineProperty(exports, "generateDocBlock", { enumerable: true, get: function () { return DocBlockGenerator_1.generateDocBlock; } });
+//# sourceMappingURL=index.js.map

package/dist/doc-generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/doc-generator/index.ts"],"names":[],"mappings":";;;AAAA,yDAI6B;AAH3B,qHAAA,gBAAgB,OAAA"}

package/dist/frontmatter/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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';
+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;
+}
+/**
+ * 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 declare const FRONTMATTER_SCHEMAS: Partial<Record<PlatformOSFileType, FrontmatterSchema>>;
+/**
+ * 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 declare function getFrontmatterSchema(fileType: PlatformOSFileType | undefined): FrontmatterSchema | undefined;