@platformos/platformos-check-node 0.0.2

package/dist/backfill-docs/doc-generator.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateParamLine = generateParamLine;
+exports.generateDocTag = generateDocTag;
+/**
+ * Generate a single @param line for a doc tag.
+ *
+ * @param name - The parameter name
+ * @param type - The inferred type
+ * @param isOptional - Whether to mark as optional with brackets
+ * @returns A formatted @param line like "@param {string} [name]" or "@param {string} name"
+ */
+function generateParamLine(name, type, isOptional = true) {
+    const paramName = isOptional ? `[${name}]` : name;
+    return `@param {${type}} ${paramName}`;
+}
+/**
+ * Generate a complete doc tag with param lines.
+ *
+ * @param params - Array of param line strings (without leading whitespace)
+ * @param indentation - The indentation to use for each line (default: 2 spaces)
+ * @returns A complete doc tag string
+ */
+function generateDocTag(params, indentation = '  ') {
+    if (params.length === 0) {
+        return `{% doc %}\n{% enddoc %}\n`;
+    }
+    const paramLines = params.map((p) => `${indentation}${p}`).join('\n');
+    return `{% doc %}\n${paramLines}\n{% enddoc %}\n`;
+}
+//# sourceMappingURL=doc-generator.js.map

package/dist/backfill-docs/doc-updater.d.ts

@@ -0,0 +1,13 @@
+import { ExistingParam } from './types';
+/**
+ * Update or insert a doc tag in a file's source code.
+ *
+ * @param source - The file source content
+ * @param paramsToAdd - Array of param line strings to add
+ * @returns The updated source content, or null if no changes needed
+ */
+export declare function updateDocInSource(source: string, paramsToAdd: string[]): Promise<string | null>;
+/**
+ * Get the list of existing parameter names from a file.
+ */
+export declare function getExistingParams(source: string): Promise<ExistingParam[]>;

package/dist/backfill-docs/doc-updater.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.updateDocInSource = updateDocInSource;
+exports.getExistingParams = getExistingParams;
+const liquid_html_parser_1 = require("@platformos/liquid-html-parser");
+const platformos_check_common_1 = require("@platformos/platformos-check-common");
+const liquid_html_parser_2 = require("@platformos/liquid-html-parser");
+const doc_generator_1 = require("./doc-generator");
+/**
+ * Parse a file to extract information about existing doc tags.
+ */
+async function parseDocTag(source) {
+    const result = {
+        exists: false,
+        startIndex: 0,
+        endIndex: 0,
+        existingParams: [],
+        lastParamEndIndex: 0,
+        docContent: '',
+    };
+    try {
+        const ast = (0, liquid_html_parser_1.toLiquidHtmlAST)(source);
+        if (!(0, liquid_html_parser_2.isLiquidHtmlNode)(ast)) {
+            return result;
+        }
+        await (0, platformos_check_common_1.visit)(ast, {
+            async LiquidRawTag(node) {
+                if (node.name !== 'doc')
+                    return;
+                result.exists = true;
+                result.startIndex = node.position.start;
+                result.endIndex = node.position.end;
+                result.docContent = node.body.value;
+            },
+            async LiquidDocParamNode(node) {
+                result.existingParams.push({
+                    name: node.paramName.value,
+                    type: node.paramType?.value ?? null,
+                    description: node.paramDescription?.value ?? null,
+                    required: node.required,
+                });
+                // Track the end position of the last @param line
+                result.lastParamEndIndex = node.position.end;
+            },
+        });
+    }
+    catch {
+        // Parse error - treat as no doc tag
+    }
+    return result;
+}
+/**
+ * Find the correct insertion point for new @param lines within an existing doc tag.
+ * Inserts after the last @param line, or at the beginning if no params exist.
+ */
+function findInsertionPoint(docContent, existingParams) {
+    if (existingParams.length === 0) {
+        // No existing params, insert at the beginning of the doc content
+        // Find the first non-whitespace position after {% doc %}
+        const match = docContent.match(/^\s*/);
+        return match ? match[0].length : 0;
+    }
+    // Find the position after the last @param line
+    const lines = docContent.split('\n');
+    let lastParamLineIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim().startsWith('@param')) {
+            lastParamLineIndex = i;
+        }
+    }
+    if (lastParamLineIndex === -1) {
+        return 0;
+    }
+    // Calculate the character offset to the end of the last @param line
+    let offset = 0;
+    for (let i = 0; i <= lastParamLineIndex; i++) {
+        offset += lines[i].length + 1; // +1 for newline
+    }
+    return offset - 1; // Position at the end of the last @param line
+}
+/**
+ * Detect the indentation used in an existing doc tag.
+ */
+function detectIndentation(docContent) {
+    const lines = docContent.split('\n');
+    for (const line of lines) {
+        const match = line.match(/^(\s*)@param/);
+        if (match) {
+            return match[1];
+        }
+    }
+    return '  '; // Default to 2 spaces
+}
+/**
+ * Update or insert a doc tag in a file's source code.
+ *
+ * @param source - The file source content
+ * @param paramsToAdd - Array of param line strings to add
+ * @returns The updated source content, or null if no changes needed
+ */
+async function updateDocInSource(source, paramsToAdd) {
+    if (paramsToAdd.length === 0) {
+        return null;
+    }
+    const docInfo = await parseDocTag(source);
+    if (!docInfo.exists) {
+        // No doc tag exists - create one at the start of the file
+        const newDocTag = (0, doc_generator_1.generateDocTag)(paramsToAdd);
+        return newDocTag + source;
+    }
+    // Doc tag exists - insert new params
+    const existingParamNames = new Set(docInfo.existingParams.map((p) => p.name));
+    // Filter out params that already exist
+    const newParams = paramsToAdd.filter((paramLine) => {
+        const match = paramLine.match(/@param\s+\{[^}]+\}\s+\[?(\w+)\]?/);
+        if (match) {
+            return !existingParamNames.has(match[1]);
+        }
+        return true;
+    });
+    if (newParams.length === 0) {
+        return null; // No new params to add
+    }
+    const indentation = detectIndentation(docInfo.docContent);
+    const insertionPoint = findInsertionPoint(docInfo.docContent, docInfo.existingParams);
+    // Build the new doc content
+    const newParamLines = newParams.map((p) => `${indentation}${p}`).join('\n');
+    // Insert the new params into the doc content
+    let newDocContent;
+    if (docInfo.existingParams.length === 0) {
+        // No existing params - add at the beginning with proper formatting
+        newDocContent = '\n' + newParamLines + docInfo.docContent;
+    }
+    else {
+        // Has existing params - insert after the last one
+        const before = docInfo.docContent.slice(0, insertionPoint);
+        const after = docInfo.docContent.slice(insertionPoint);
+        newDocContent = before + '\n' + newParamLines + after;
+    }
+    // Reconstruct the doc tag
+    const newDocTag = `{% doc %}${newDocContent}{% enddoc %}`;
+    // Replace the old doc tag with the new one
+    return (source.slice(0, docInfo.startIndex) +
+        newDocTag +
+        source.slice(docInfo.endIndex));
+}
+/**
+ * Get the list of existing parameter names from a file.
+ */
+async function getExistingParams(source) {
+    const docInfo = await parseDocTag(source);
+    return docInfo.existingParams;
+}
+//# sourceMappingURL=doc-updater.js.map

package/dist/backfill-docs/index.d.ts

@@ -0,0 +1,14 @@
+import { BackfillOptions, BackfillResult } from './types';
+export { BackfillOptions, BackfillResult } from './types';
+/**
+ * Run the doc tag backfill process.
+ *
+ * This scans the project for function, render, and include tag usages,
+ * collects the arguments passed to each partial, and updates/creates
+ * doc tags in the corresponding partial files.
+ */
+export declare function backfillDocs(options: BackfillOptions, log?: (message: string) => void): Promise<BackfillResult>;
+/**
+ * CLI entry point for the backfill-docs command.
+ */
+export declare function runBackfillDocsCLI(args: string[]): Promise<void>;

package/dist/backfill-docs/index.js

@@ -0,0 +1,233 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.backfillDocs = backfillDocs;
+exports.runBackfillDocsCLI = runBackfillDocsCLI;
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const vscode_uri_1 = require("vscode-uri");
+const platformos_common_1 = require("@platformos/platformos-common");
+const platformos_check_common_1 = require("@platformos/platformos-check-common");
+const liquid_html_parser_1 = require("@platformos/liquid-html-parser");
+const index_1 = require("../index");
+const NodeFileSystem_1 = require("../NodeFileSystem");
+const argument_collector_1 = require("./argument-collector");
+const doc_generator_1 = require("./doc-generator");
+const doc_updater_1 = require("./doc-updater");
+/**
+ * Extract the set of variable names used in a Liquid source file.
+ * Only looks at top-level variable lookups (the root name, not nested properties).
+ */
+async function getUsedVariables(source) {
+    const usedVars = new Set();
+    try {
+        const ast = (0, liquid_html_parser_1.toLiquidHtmlAST)(source);
+        if (!(0, liquid_html_parser_1.isLiquidHtmlNode)(ast)) {
+            return usedVars;
+        }
+        await (0, platformos_check_common_1.visit)(ast, {
+            async VariableLookup(node) {
+                if (node.name) {
+                    usedVars.add(node.name);
+                }
+            },
+        });
+    }
+    catch {
+        // Parse error - return empty set
+    }
+    return usedVars;
+}
+/**
+ * Run the doc tag backfill process.
+ *
+ * This scans the project for function, render, and include tag usages,
+ * collects the arguments passed to each partial, and updates/creates
+ * doc tags in the corresponding partial files.
+ */
+async function backfillDocs(options, log = console.log) {
+    const { rootPath, dryRun = false, markRequired = false, verbose = false } = options;
+    const result = {
+        modified: [],
+        skipped: [],
+        errors: [],
+    };
+    log('Scanning for partial usages (function, render, include)...');
+    // Load theme configuration
+    const config = await (0, index_1.loadConfig)(undefined, rootPath);
+    const theme = await (0, index_1.getTheme)(config);
+    // Collect all partial usages from the theme
+    const usageMap = await (0, argument_collector_1.collectPartialUsages)(theme, verbose, log);
+    const totalCalls = Array.from(usageMap.values()).reduce((sum, usage) => sum + Array.from(usage.arguments.values()).reduce((s, a) => s + a.usageCount, 0), 0);
+    log(`Found ${totalCalls} partial calls referencing ${usageMap.size} partials\n`);
+    if (usageMap.size === 0) {
+        log('No partial usages found.');
+        return result;
+    }
+    log('Processing:');
+    // Create a DocumentsLocator for resolving partial paths
+    const documentsLocator = new platformos_common_1.DocumentsLocator(NodeFileSystem_1.NodeFileSystem);
+    const rootUri = vscode_uri_1.URI.file(rootPath);
+    // Process each partial
+    for (const usage of usageMap.values()) {
+        const { partialPath, tagType, arguments: args } = usage;
+        try {
+            // Resolve the partial file path
+            const resolvedUri = await documentsLocator.locate(rootUri, tagType, partialPath);
+            if (!resolvedUri) {
+                log(`  [!] ${partialPath} - File not found`);
+                result.errors.push({
+                    file: partialPath,
+                    error: 'File not found',
+                });
+                continue;
+            }
+            // Convert URI to filesystem path
+            const filePath = platformos_check_common_1.path.fsPath(resolvedUri);
+            // Read the file content
+            let source;
+            try {
+                source = await promises_1.default.readFile(filePath, 'utf8');
+            }
+            catch (err) {
+                log(`  [!] ${partialPath} - Failed to read file`);
+                result.errors.push({
+                    file: partialPath,
+                    error: `Failed to read file: ${err}`,
+                });
+                continue;
+            }
+            // Get existing params to filter out duplicates
+            const existingParams = await (0, doc_updater_1.getExistingParams)(source);
+            const existingParamNames = new Set(existingParams.map((p) => p.name));
+            // Get variables actually used in the partial
+            const usedVariables = await getUsedVariables(source);
+            // Generate param lines for new arguments only (if they're actually used)
+            const newParamLines = [];
+            const addedParams = [];
+            for (const [argName, argInfo] of args) {
+                if (existingParamNames.has(argName)) {
+                    continue; // Skip params that already exist
+                }
+                if (!usedVariables.has(argName)) {
+                    if (verbose) {
+                        log(`    [skip] ${argName} - not used in partial`);
+                    }
+                    continue; // Skip params that aren't used in the partial
+                }
+                newParamLines.push((0, doc_generator_1.generateParamLine)(argName, argInfo.inferredType, !markRequired));
+                addedParams.push(argName);
+            }
+            if (newParamLines.length === 0) {
+                if (verbose) {
+                    log(`  [=] ${partialPath} - No changes needed`);
+                }
+                result.skipped.push(partialPath);
+                continue;
+            }
+            // Update the source with new params
+            const updatedSource = await (0, doc_updater_1.updateDocInSource)(source, newParamLines);
+            if (!updatedSource) {
+                if (verbose) {
+                    log(`  [=] ${partialPath} - No changes needed`);
+                }
+                result.skipped.push(partialPath);
+                continue;
+            }
+            // Write the updated content (unless dry run)
+            if (!dryRun) {
+                await promises_1.default.writeFile(filePath, updatedSource, 'utf8');
+            }
+            const relativePath = node_path_1.default.relative(rootPath, filePath);
+            log(`  [+] ${relativePath} - Added: ${addedParams.join(', ')}`);
+            result.modified.push(partialPath);
+        }
+        catch (err) {
+            log(`  [!] ${partialPath} - Error: ${err}`);
+            result.errors.push({
+                file: partialPath,
+                error: String(err),
+            });
+        }
+    }
+    // Print summary
+    log('');
+    log(`Modified: ${result.modified.length} files | Skipped: ${result.skipped.length} | Errors: ${result.errors.length}`);
+    if (dryRun && result.modified.length > 0) {
+        log('\n(Dry run - no files were actually modified)');
+    }
+    return result;
+}
+/**
+ * CLI entry point for the backfill-docs command.
+ */
+async function runBackfillDocsCLI(args) {
+    const options = {
+        rootPath: process.cwd(),
+        dryRun: false,
+        markRequired: false,
+        verbose: false,
+    };
+    // Parse command line arguments
+    const positionalArgs = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--dry-run' || arg === '-n') {
+            options.dryRun = true;
+        }
+        else if (arg === '--required' || arg === '-r') {
+            options.markRequired = true;
+        }
+        else if (arg === '--verbose' || arg === '-v') {
+            options.verbose = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            printHelp();
+            return;
+        }
+        else if (!arg.startsWith('-')) {
+            positionalArgs.push(arg);
+        }
+        else {
+            console.error(`Unknown option: ${arg}`);
+            printHelp();
+            process.exit(1);
+        }
+    }
+    // First positional argument is the path
+    if (positionalArgs.length > 0) {
+        options.rootPath = node_path_1.default.resolve(positionalArgs[0]);
+    }
+    try {
+        await backfillDocs(options);
+    }
+    catch (err) {
+        console.error('Error:', err);
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+Usage: theme-check backfill-docs [path] [options]
+
+Scans a platformOS project for partial usages (function, render, include tags)
+and backfills or updates {% doc %} tags in the corresponding partial files.
+
+Arguments:
+  path              Path to the project root (default: current directory)
+
+Options:
+  --dry-run, -n     Preview changes without writing files
+  --required, -r    Mark new params as required (default: optional)
+  --verbose, -v     Show detailed progress
+  --help, -h        Show this help message
+
+Examples:
+  theme-check backfill-docs
+  theme-check backfill-docs ./my-project --dry-run
+  theme-check backfill-docs --verbose --required
+`);
+}
+//# sourceMappingURL=index.js.map

package/dist/backfill-docs/types.d.ts

@@ -0,0 +1,32 @@
+import { BasicParamTypes } from '@platformos/platformos-check-common';
+export type TagType = 'function' | 'render' | 'include';
+export interface ArgumentInfo {
+    name: string;
+    inferredType: BasicParamTypes;
+    usageCount: number;
+}
+export interface PartialUsage {
+    partialPath: string;
+    tagType: TagType;
+    arguments: Map<string, ArgumentInfo>;
+}
+export interface BackfillOptions {
+    rootPath: string;
+    dryRun?: boolean;
+    markRequired?: boolean;
+    verbose?: boolean;
+}
+export interface BackfillResult {
+    modified: string[];
+    skipped: string[];
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+export interface ExistingParam {
+    name: string;
+    type: string | null;
+    description: string | null;
+    required: boolean;
+}

package/dist/backfill-docs/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_1 = require("./index");
+const backfill_docs_1 = require("./backfill-docs");
+const node_path_1 = __importDefault(require("node:path"));
+async function runThemeCheck(args) {
+    const root = node_path_1.default.resolve(args[0] || '.');
+    const configPath = args[1] ? node_path_1.default.resolve(args[1]) : undefined;
+    const { theme, config, offenses } = await (0, index_1.themeCheckRun)(root, configPath, console.error.bind(console));
+    console.log(JSON.stringify(offenses, null, 2));
+    console.log(JSON.stringify(config, null, 2));
+    console.log(JSON.stringify(theme.map((x) => x.uri), null, 2));
+}
+function printUsage() {
+    console.log(`
+Usage: theme-check [command] [options]
+
+Commands:
+  <path>              Run theme checks on the specified path (default)
+  backfill-docs       Backfill doc tags in partial files based on usage
+
+Run 'theme-check <command> --help' for more information on a command.
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        printUsage();
+        process.exit(1);
+    }
+    const command = args[0];
+    if (command === '--help' || command === '-h') {
+        printUsage();
+        return;
+    }
+    if (command === 'backfill-docs') {
+        await (0, backfill_docs_1.runBackfillDocsCLI)(args.slice(1));
+        return;
+    }
+    // Default: run theme check
+    await runThemeCheck(args);
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/commands/generate-docs.d.ts

@@ -0,0 +1,24 @@
+export interface GenerateDocsOptions {
+    dryRun?: boolean;
+    output?: 'inline' | 'stdout' | 'json';
+}
+export interface GenerateDocsResult {
+    uri: string;
+    relativePath: string;
+    parameters: Array<{
+        name: string;
+        type: string | null;
+        isOptional: boolean;
+    }>;
+    docBlockText: string;
+    hasExistingDocBlock: boolean;
+    updated: boolean;
+}
+/**
+ * Generate doc blocks for all partials and blocks in a theme.
+ */
+export declare function generateDocsCommand(root: string, options?: GenerateDocsOptions): Promise<GenerateDocsResult[]>;
+/**
+ * Generate doc block for a single file.
+ */
+export declare function generateDocForFile(absolutePath: string, options?: GenerateDocsOptions): Promise<GenerateDocsResult | null>;