specweave 1.0.31 → 1.0.33

package/dist/src/core/living-docs/scaffolding/scaffold.js

@@ -0,0 +1,346 @@
+/**
+ * Living Docs Scaffold - Creates documentation structure for user projects
+ *
+ * This module creates the .specweave/docs/ directory structure for ANY user project.
+ * It's project-agnostic and uses templates with variable substitution.
+ *
+ * CRITICAL: This runs during `specweave init` to set up the docs structure.
+ *
+ * @module core/living-docs/scaffolding/scaffold
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { consoleLogger } from '../../../utils/logger.js';
+import { TemplateEngine, createDefaultContext } from './template-engine.js';
+/**
+ * Living Docs directory structure
+ * This is the canonical structure for all user projects.
+ */
+const DOCS_STRUCTURE = [
+    {
+        path: 'internal',
+        readme: '# Internal Documentation\n\nInternal project documentation - not for public consumption.\n',
+        children: [
+            {
+                path: 'specs',
+                readme: '# Specifications\n\nFeature specifications and user stories.\n\nEach project has its own folder: `{project}/FS-XXX/`\n',
+            },
+            {
+                path: 'architecture',
+                readme: '# Architecture Documentation\n\nSystem architecture, design decisions, and technical documentation.\n',
+                children: [
+                    {
+                        path: 'adr',
+                        readme: '# Architecture Decision Records\n\nDocumented architecture decisions using ADR format.\n\nFormat: `XXXX-decision-title.md` (4-digit number, NO adr- prefix)\n',
+                    },
+                    {
+                        path: 'diagrams',
+                        readme: '# Architecture Diagrams\n\nMermaid diagrams for system architecture visualization.\n',
+                    },
+                ],
+            },
+            {
+                path: 'modules',
+                readme: '# Module Documentation\n\nPer-module documentation generated from codebase analysis.\n',
+            },
+            {
+                path: 'organization',
+                readme: '# Organization Structure\n\nTeam structure, microservices, and domain groupings.\n',
+                children: [
+                    { path: 'teams' },
+                    { path: 'microservices' },
+                    { path: 'domains' },
+                ],
+            },
+            {
+                path: 'delivery',
+                readme: '# Delivery Documentation\n\nRelease history, CI/CD pipelines, and deployment guides.\n',
+            },
+            {
+                path: 'operations',
+                readme: '# Operations Documentation\n\nRunbooks, monitoring, and operational procedures.\n',
+            },
+            {
+                path: 'strategy',
+                readme: '# Strategy Documentation\n\nProduct requirements, business cases, and strategic planning.\n',
+            },
+            {
+                path: 'review-needed',
+                readme: '# Review Needed\n\nIssues and inconsistencies that need attention.\n',
+            },
+        ],
+    },
+    {
+        path: 'public',
+        readme: '# Public Documentation\n\nUser-facing documentation.\n',
+        children: [
+            {
+                path: 'overview',
+                readme: '# Project Overview\n\nHigh-level project documentation and getting started guides.\n',
+            },
+            {
+                path: 'api',
+                readme: '# API Documentation\n\nAPI reference and usage guides.\n',
+            },
+            {
+                path: 'guides',
+                readme: '# User Guides\n\nHow-to guides and tutorials.\n',
+            },
+        ],
+    },
+];
+/**
+ * Scaffold class - creates living docs structure
+ */
+export class LivingDocsScaffold {
+    constructor(options) {
+        this.projectPath = options.projectPath;
+        this.projectId = options.projectId || this.detectProjectId();
+        this.logger = options.logger ?? consoleLogger;
+        this.templateEngine = new TemplateEngine({ logger: this.logger });
+        this.overwrite = options.overwrite ?? false;
+        this.dryRun = options.dryRun ?? false;
+        // Create context
+        this.context = {
+            ...createDefaultContext(this.projectId),
+            projectName: options.projectName || this.projectId,
+            ...options.additionalContext,
+        };
+    }
+    /**
+     * Detect project ID from git remote or directory name
+     */
+    detectProjectId() {
+        // Try to get from git remote
+        try {
+            const gitConfigPath = path.join(this.projectPath, '.git', 'config');
+            if (fs.existsSync(gitConfigPath)) {
+                const gitConfig = fs.readFileSync(gitConfigPath, 'utf-8');
+                const match = gitConfig.match(/url\s*=\s*.*[\/:]([^\/]+?)(?:\.git)?$/m);
+                if (match) {
+                    return match[1].toLowerCase();
+                }
+            }
+        }
+        catch {
+            // Ignore errors
+        }
+        // Fall back to directory name
+        return path.basename(this.projectPath).toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    }
+    /**
+     * Create the full living docs structure
+     */
+    async scaffold() {
+        const result = {
+            success: true,
+            filesCreated: [],
+            filesSkipped: [],
+            dirsCreated: [],
+            errors: [],
+            context: this.context,
+        };
+        const docsBase = path.join(this.projectPath, '.specweave', 'docs');
+        this.logger.info('Scaffolding living docs structure...');
+        this.logger.info('  Project ID: ' + this.projectId);
+        this.logger.info('  Docs path: ' + docsBase);
+        try {
+            // Create base docs directory
+            await this.ensureDir(docsBase, result);
+            // Create root README
+            await this.createRootReadme(docsBase, result);
+            // Recursively create structure
+            await this.createStructure(docsBase, DOCS_STRUCTURE, result);
+            // Create project-specific specs folder
+            await this.createProjectSpecsFolder(docsBase, result);
+            // Create SUGGESTIONS.md placeholder
+            await this.createSuggestionsFile(docsBase, result);
+            this.logger.info('Scaffold complete!');
+            this.logger.info('  Directories created: ' + result.dirsCreated.length);
+            this.logger.info('  Files created: ' + result.filesCreated.length);
+            this.logger.info('  Files skipped: ' + result.filesSkipped.length);
+        }
+        catch (error) {
+            result.success = false;
+            result.errors.push(String(error));
+            this.logger.error('Scaffold failed: ' + error);
+        }
+        return result;
+    }
+    /**
+     * Create directory structure recursively
+     */
+    async createStructure(basePath, structure, result) {
+        for (const dir of structure) {
+            const dirPath = path.join(basePath, dir.path);
+            // Create directory
+            await this.ensureDir(dirPath, result);
+            // Create README if defined
+            if (dir.readme) {
+                const readmePath = path.join(dirPath, 'README.md');
+                await this.createFile(readmePath, dir.readme, result);
+            }
+            // Process children
+            if (dir.children) {
+                await this.createStructure(dirPath, dir.children, result);
+            }
+        }
+    }
+    /**
+     * Create root README.md
+     */
+    async createRootReadme(docsBase, result) {
+        const content = `# ${this.context.projectName} - Living Documentation
+
+This directory contains the living documentation for **${this.context.projectName}**.
+
+## Structure
+
+- \`internal/\` - Internal documentation (specs, architecture, operations)
+  - \`specs/\` - Feature specifications and user stories
+  - \`architecture/\` - System architecture and ADRs
+  - \`modules/\` - Per-module documentation
+  - \`organization/\` - Team and domain structure
+  - \`delivery/\` - Release and deployment docs
+  - \`operations/\` - Runbooks and monitoring
+
+- \`public/\` - User-facing documentation
+  - \`overview/\` - Project overview and getting started
+  - \`api/\` - API documentation
+  - \`guides/\` - How-to guides
+
+## Quick Start
+
+1. **Create a feature spec**: \`/sw:increment "my feature"\`
+2. **Sync to living docs**: \`/sw:sync-specs\`
+3. **View documentation**: \`/sw-docs:view\`
+
+## Generated by SpecWeave
+
+This documentation structure was created by [SpecWeave](https://github.com/specweave/specweave).
+
+Last updated: ${this.context.lastUpdatedDate}
+`;
+        await this.createFile(path.join(docsBase, 'README.md'), content, result);
+    }
+    /**
+     * Create project-specific specs folder
+     */
+    async createProjectSpecsFolder(docsBase, result) {
+        const projectSpecsPath = path.join(docsBase, 'internal', 'specs', this.projectId);
+        await this.ensureDir(projectSpecsPath, result);
+        const content = `# ${this.context.projectName} - Specifications
+
+Feature specifications for **${this.context.projectName}**.
+
+## Features
+
+Features are organized by ID: \`FS-XXX/\`
+
+Each feature folder contains:
+- \`FEATURE.md\` - Feature overview and implementation history
+- \`us-XXX-*.md\` - User story files
+
+## Creating Features
+
+Features are automatically created when you sync increments:
+
+\`\`\`bash
+/sw:sync-specs
+\`\`\`
+
+Or sync a specific increment:
+
+\`\`\`bash
+/sw:sync-specs 0001
+\`\`\`
+
+---
+
+Last updated: ${this.context.lastUpdatedDate}
+`;
+        await this.createFile(path.join(projectSpecsPath, 'README.md'), content, result);
+    }
+    /**
+     * Create SUGGESTIONS.md placeholder
+     */
+    async createSuggestionsFile(docsBase, result) {
+        const content = `# Documentation Suggestions
+
+This file will be populated with documentation improvement suggestions after running the Living Docs Builder.
+
+## How to Generate Suggestions
+
+Run the living docs analysis:
+
+\`\`\`bash
+/sw:living-docs
+\`\`\`
+
+Or with specific options:
+
+\`\`\`bash
+/sw:living-docs --depth standard --priority auth,payments
+\`\`\`
+
+## What Gets Analyzed
+
+- **Codebase structure** - Modules, dependencies, patterns
+- **Existing documentation** - READMEs, JSDoc, inline comments
+- **Specifications** - User stories, acceptance criteria
+- **Architecture** - Detected patterns and decisions
+
+---
+
+*Generated by SpecWeave Living Docs Builder*
+`;
+        await this.createFile(path.join(docsBase, 'SUGGESTIONS.md'), content, result);
+    }
+    /**
+     * Ensure directory exists
+     */
+    async ensureDir(dirPath, result) {
+        if (this.dryRun) {
+            if (!fs.existsSync(dirPath)) {
+                result.dirsCreated.push(dirPath);
+            }
+            return;
+        }
+        if (!fs.existsSync(dirPath)) {
+            fs.mkdirSync(dirPath, { recursive: true });
+            result.dirsCreated.push(dirPath);
+        }
+    }
+    /**
+     * Create a file with content
+     */
+    async createFile(filePath, content, result) {
+        if (fs.existsSync(filePath) && !this.overwrite) {
+            result.filesSkipped.push(filePath);
+            return;
+        }
+        if (this.dryRun) {
+            result.filesCreated.push(filePath + ' (dry-run)');
+            return;
+        }
+        // Render template if it has variables
+        const rendered = this.templateEngine.render(content, this.context);
+        fs.writeFileSync(filePath, rendered, 'utf-8');
+        result.filesCreated.push(filePath);
+    }
+}
+/**
+ * Scaffold living docs structure (convenience function)
+ */
+export async function scaffoldLivingDocs(options) {
+    const scaffold = new LivingDocsScaffold(options);
+    return scaffold.scaffold();
+}
+/**
+ * Check if living docs structure exists
+ */
+export function hasLivingDocsStructure(projectPath) {
+    const docsPath = path.join(projectPath, '.specweave', 'docs');
+    return fs.existsSync(docsPath) && fs.existsSync(path.join(docsPath, 'internal'));
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/src/core/living-docs/scaffolding/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../../../../../src/core/living-docs/scaffolding/scaffold.ts"],"names":[],"mappings":"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"}

package/dist/src/core/living-docs/scaffolding/template-engine.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Template Engine for Living Docs Scaffolding
+ *
+ * Provides variable substitution for .md.template files.
+ * Works with ANY user project - no hardcoded paths or project names.
+ *
+ * Supports:
+ * - Simple variables: ${variableName}
+ * - Conditional blocks: ${if:condition}...${endif} (supports nesting)
+ * - Loop blocks: ${each:items}...${endeach} (supports nesting)
+ * - Default values: ${variableName:defaultValue}
+ * - Nested conditionals and loops (recursive processing)
+ *
+ * @module core/living-docs/scaffolding/template-engine
+ */
+import { Logger } from '../../../utils/logger.js';
+/**
+ * Template variables context
+ */
+export interface TemplateContext {
+    projectId: string;
+    projectName: string;
+    projectDescription?: string;
+    createdDate: string;
+    lastUpdatedDate: string;
+    featureId?: string;
+    featureTitle?: string;
+    featureStatus?: string;
+    featurePriority?: string;
+    incrementId?: string;
+    incrementsRelativePath?: string;
+    userStories?: Array<{
+        id: string;
+        title: string;
+        fileName: string;
+        status?: string;
+    }>;
+    increments?: Array<{
+        id: string;
+        link: string;
+        status: string;
+        statusEmoji: string;
+        date: string;
+    }>;
+    overview?: string;
+    [key: string]: unknown;
+}
+/**
+ * Default template context values
+ */
+export declare function createDefaultContext(projectId: string): TemplateContext;
+/**
+ * Template Engine class
+ *
+ * Supports deeply nested conditionals and loops through recursive processing.
+ */
+export declare class TemplateEngine {
+    private logger;
+    constructor(options?: {
+        logger?: Logger;
+    });
+    /**
+     * Render a template with the given context
+     *
+     * Processes nested structures by recursively rendering until no more
+     * template syntax remains (up to MAX_RECURSION_DEPTH iterations).
+     */
+    render(template: string, context: TemplateContext): string;
+    /**
+     * Process conditional blocks with proper nesting support
+     *
+     * Uses a non-greedy innermost-first approach to handle nesting:
+     * ${if:outer}${if:inner}...${endif}${endif}
+     */
+    private processConditionals;
+    /**
+     * Process loop blocks with proper nesting support
+     *
+     * Uses a non-greedy innermost-first approach to handle nesting:
+     * ${each:outer}${each:inner}...${endeach}${endeach}
+     */
+    private processLoops;
+    /**
+     * Check if a value is truthy for template conditionals
+     */
+    private isTruthy;
+    /**
+     * Get a nested value from an object using dot notation
+     * Supports: item.user.name, item.tags.0, etc.
+     */
+    private getNestedValue;
+    private processVariables;
+    private getContextValue;
+    /**
+     * Validate template syntax for common errors
+     *
+     * Checks for:
+     * - Mismatched if/endif blocks
+     * - Mismatched each/endeach blocks
+     * - Detects potential infinite loops (self-referencing)
+     */
+    validateTemplate(template: string): string[];
+}
+export declare function getTemplateEngine(options?: {
+    logger?: Logger;
+}): TemplateEngine;
+export declare function renderTemplate(template: string, context: TemplateContext): string;
+//# sourceMappingURL=template-engine.d.ts.map

package/dist/src/core/living-docs/scaffolding/template-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-engine.d.ts","sourceRoot":"","sources":["../../../../../src/core/living-docs/scaffolding/template-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAiB,MAAM,0BAA0B,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,eAAe;IAE9B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAG5B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IAGxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;IAGzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAGhC,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IAEH,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IAGH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CASvE;AAOD;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO;IAI7C;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM;IAuB1D;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAW3B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IA0BpB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,eAAe;IAUvB;;;;;;;OAOG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE;CA2B7C;AAID,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,cAAc,CAK/E;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,MAAM,CAEjF"}

package/dist/src/core/living-docs/scaffolding/template-engine.js

@@ -0,0 +1,204 @@
+/**
+ * Template Engine for Living Docs Scaffolding
+ *
+ * Provides variable substitution for .md.template files.
+ * Works with ANY user project - no hardcoded paths or project names.
+ *
+ * Supports:
+ * - Simple variables: ${variableName}
+ * - Conditional blocks: ${if:condition}...${endif} (supports nesting)
+ * - Loop blocks: ${each:items}...${endeach} (supports nesting)
+ * - Default values: ${variableName:defaultValue}
+ * - Nested conditionals and loops (recursive processing)
+ *
+ * @module core/living-docs/scaffolding/template-engine
+ */
+import { consoleLogger } from '../../../utils/logger.js';
+/**
+ * Default template context values
+ */
+export function createDefaultContext(projectId) {
+    const today = new Date().toISOString().split('T')[0];
+    return {
+        projectId,
+        projectName: projectId.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' '),
+        createdDate: today,
+        lastUpdatedDate: today,
+        incrementsRelativePath: '../../../../increments',
+    };
+}
+/**
+ * Maximum recursion depth for nested templates (prevents infinite loops)
+ */
+const MAX_RECURSION_DEPTH = 10;
+/**
+ * Template Engine class
+ *
+ * Supports deeply nested conditionals and loops through recursive processing.
+ */
+export class TemplateEngine {
+    constructor(options = {}) {
+        this.logger = options.logger ?? consoleLogger;
+    }
+    /**
+     * Render a template with the given context
+     *
+     * Processes nested structures by recursively rendering until no more
+     * template syntax remains (up to MAX_RECURSION_DEPTH iterations).
+     */
+    render(template, context) {
+        let result = template;
+        let depth = 0;
+        // Process recursively until stable (handles nested blocks)
+        let previousResult = '';
+        while (previousResult !== result && depth < MAX_RECURSION_DEPTH) {
+            previousResult = result;
+            result = this.processConditionals(result, context);
+            result = this.processLoops(result, context);
+            depth++;
+        }
+        // Final pass for variables (after all conditionals/loops are resolved)
+        result = this.processVariables(result, context);
+        if (depth >= MAX_RECURSION_DEPTH) {
+            this.logger.warn('Template engine reached max recursion depth. Possible infinite loop in template.');
+        }
+        return result;
+    }
+    /**
+     * Process conditional blocks with proper nesting support
+     *
+     * Uses a non-greedy innermost-first approach to handle nesting:
+     * ${if:outer}${if:inner}...${endif}${endif}
+     */
+    processConditionals(template, context) {
+        // Match innermost conditionals first (non-greedy, no nested ${if:} inside)
+        const innermostPattern = /\$\{if:(\w+)\}((?:(?!\$\{if:)[\s\S])*?)\$\{endif\}/g;
+        return template.replace(innermostPattern, (_match, varName, content) => {
+            const value = this.getContextValue(context, varName);
+            const isTruthy = this.isTruthy(value);
+            return isTruthy ? content : '';
+        });
+    }
+    /**
+     * Process loop blocks with proper nesting support
+     *
+     * Uses a non-greedy innermost-first approach to handle nesting:
+     * ${each:outer}${each:inner}...${endeach}${endeach}
+     */
+    processLoops(template, context) {
+        // Match innermost loops first (non-greedy, no nested ${each:} inside)
+        const innermostPattern = /\$\{each:(\w+)\}((?:(?!\$\{each:)[\s\S])*?)\$\{endeach\}/g;
+        return template.replace(innermostPattern, (_match, arrayName, content) => {
+            const array = this.getContextValue(context, arrayName);
+            if (!Array.isArray(array) || array.length === 0)
+                return '';
+            return array.map((item, index) => {
+                let itemContent = content;
+                // Replace item properties (supports nested paths like item.user.name)
+                const itemPattern = /\$\{item\.([.\w]+)\}/g;
+                itemContent = itemContent.replace(itemPattern, (_m, prop) => {
+                    const value = this.getNestedValue(item, prop);
+                    return value !== undefined ? String(value) : '';
+                });
+                // Replace index
+                itemContent = itemContent.replace(/\$\{index\}/g, String(index));
+                return itemContent;
+            }).join('');
+        });
+    }
+    /**
+     * Check if a value is truthy for template conditionals
+     */
+    isTruthy(value) {
+        return value !== undefined &&
+            value !== null &&
+            value !== false &&
+            value !== '' &&
+            value !== 0 &&
+            !(Array.isArray(value) && value.length === 0);
+    }
+    /**
+     * Get a nested value from an object using dot notation
+     * Supports: item.user.name, item.tags.0, etc.
+     */
+    getNestedValue(obj, path) {
+        const parts = path.split('.');
+        let current = obj;
+        for (const part of parts) {
+            if (current === null || current === undefined)
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    processVariables(template, context) {
+        const variablePattern = /\$\{(\w+)(?::([^}]*))?\}/g;
+        return template.replace(variablePattern, (_match, varName, defaultValue) => {
+            // Skip template keywords
+            if (['if', 'endif', 'each', 'endeach', 'item', 'index'].includes(varName)) {
+                return _match;
+            }
+            const value = this.getContextValue(context, varName);
+            if (value === undefined || value === null || value === '') {
+                return defaultValue !== undefined ? defaultValue : '';
+            }
+            if (Array.isArray(value))
+                return value.join(', ');
+            if (typeof value === 'object')
+                return JSON.stringify(value);
+            return String(value);
+        });
+    }
+    getContextValue(context, path) {
+        const parts = path.split('.');
+        let current = context;
+        for (const part of parts) {
+            if (current === null || current === undefined)
+                return undefined;
+            current = current[part];
+        }
+        return current;
+    }
+    /**
+     * Validate template syntax for common errors
+     *
+     * Checks for:
+     * - Mismatched if/endif blocks
+     * - Mismatched each/endeach blocks
+     * - Detects potential infinite loops (self-referencing)
+     */
+    validateTemplate(template) {
+        const errors = [];
+        // Check balanced conditionals
+        const ifCount = (template.match(/\$\{if:\w+\}/g) || []).length;
+        const endifCount = (template.match(/\$\{endif\}/g) || []).length;
+        if (ifCount !== endifCount) {
+            errors.push('Mismatched conditionals: ' + ifCount + ' if blocks but ' + endifCount + ' endif');
+        }
+        // Check balanced loops
+        const eachCount = (template.match(/\$\{each:\w+\}/g) || []).length;
+        const endeachCount = (template.match(/\$\{endeach\}/g) || []).length;
+        if (eachCount !== endeachCount) {
+            errors.push('Mismatched loops: ' + eachCount + ' each blocks but ' + endeachCount + ' endeach');
+        }
+        // Check for common mistakes
+        if (template.includes('${endif}${endif}') && ifCount < 2) {
+            errors.push('Suspicious double endif - check nesting structure');
+        }
+        if (template.includes('${endeach}${endeach}') && eachCount < 2) {
+            errors.push('Suspicious double endeach - check nesting structure');
+        }
+        return errors;
+    }
+}
+let defaultEngine = null;
+export function getTemplateEngine(options) {
+    if (!defaultEngine) {
+        defaultEngine = new TemplateEngine(options);
+    }
+    return defaultEngine;
+}
+export function renderTemplate(template, context) {
+    return getTemplateEngine().render(template, context);
+}
+//# sourceMappingURL=template-engine.js.map