@relevate/katachi 0.1.0

package/dist/core/verify.d.ts

@@ -0,0 +1,25 @@
+export interface Fixture {
+    name: string;
+    source: string;
+    generated: string;
+}
+/**
+ * Canonicalizes Askama/HTML output enough to separate semantic regressions from
+ * serialization and formatting differences.
+ */
+export declare function normalizeAskama(source: string): string;
+/**
+ * Runs the Askama fixture comparison and sets a failing process exit code on
+ * functional mismatches.
+ */
+export interface VerifyAskamaOptions {
+    fixtures?: Fixture[];
+    logger?: Pick<Console, "log" | "error">;
+}
+export interface VerifyAskamaResult {
+    ok: string[];
+    formatOnly: string[];
+    failures: string[];
+    missing: string[];
+}
+export declare function verifyAskamaFixtures(options?: VerifyAskamaOptions): VerifyAskamaResult;

package/dist/core/verify.js

@@ -0,0 +1,270 @@
+import { existsSync, readFileSync } from "node:fs";
+/**
+ * Canonicalizes Askama/HTML output enough to separate semantic regressions from
+ * serialization and formatting differences.
+ */
+export function normalizeAskama(source) {
+    const input = source.replace(/\r\n/g, "\n");
+    const tokens = [];
+    let index = 0;
+    while (index < input.length) {
+        if (input.startsWith("{{", index)) {
+            const end = input.indexOf("}}", index);
+            tokens.push(normalizeAskamaPrint(input.slice(index, end + 2)));
+            index = end + 2;
+            continue;
+        }
+        if (input.startsWith("{%", index)) {
+            const end = input.indexOf("%}", index);
+            tokens.push(normalizeAskamaStatement(input.slice(index, end + 2)));
+            index = end + 2;
+            continue;
+        }
+        if (input[index] === "<") {
+            const { tag, nextIndex } = readHtmlTag(input, index);
+            tokens.push(normalizeHtmlTag(tag));
+            index = nextIndex;
+            continue;
+        }
+        let end = index;
+        while (end < input.length &&
+            !input.startsWith("{{", end) &&
+            !input.startsWith("{%", end) &&
+            input[end] !== "<") {
+            end += 1;
+        }
+        const text = input.slice(index, end).replace(/\s+/g, " ").trim();
+        if (text) {
+            tokens.push(text);
+        }
+        index = end;
+    }
+    let normalized = tokens.join("");
+    let previous = "";
+    normalized = normalized.replace(/<(img|input|br|hr|meta|link|source|track|wbr|area|base|col|embed|param)([^>]*?)(?<!\/)>/gi, "<$1$2/>");
+    while (previous !== normalized) {
+        previous = normalized;
+        normalized = normalized.replace(/<([A-Za-z][A-Za-z0-9:_-]*)([^>]*)><\/\1>/g, "<$1$2/>");
+    }
+    return normalized;
+}
+function readTemplateBlock(source, startIndex) {
+    const delimiter = source.startsWith("{%", startIndex)
+        ? "%}"
+        : source.startsWith("{{", startIndex)
+            ? "}}"
+            : null;
+    if (!delimiter) {
+        return null;
+    }
+    const end = source.indexOf(delimiter, startIndex);
+    if (end === -1) {
+        return {
+            block: source.slice(startIndex),
+            nextIndex: source.length,
+        };
+    }
+    return {
+        block: source.slice(startIndex, end + delimiter.length),
+        nextIndex: end + delimiter.length,
+    };
+}
+function readHtmlTag(source, startIndex) {
+    let index = startIndex;
+    let quote = null;
+    while (index < source.length) {
+        const templateBlock = readTemplateBlock(source, index);
+        if (templateBlock) {
+            index = templateBlock.nextIndex;
+            continue;
+        }
+        const char = source[index];
+        const next = source[index + 1];
+        if (quote) {
+            if (char === "\\" && next) {
+                index += 2;
+                continue;
+            }
+            if (char === quote) {
+                quote = null;
+            }
+            index += 1;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            index += 1;
+            continue;
+        }
+        if (char === ">") {
+            return {
+                tag: source.slice(startIndex, index + 1),
+                nextIndex: index + 1,
+            };
+        }
+        index += 1;
+    }
+    return {
+        tag: source.slice(startIndex),
+        nextIndex: source.length,
+    };
+}
+function normalizeAskamaPrint(token) {
+    return `{{${token.slice(2, -2).trim()}}}`;
+}
+function normalizeAskamaStatement(token) {
+    return `{%${token.slice(2, -2).trim()}%}`;
+}
+function normalizeAttributeValue(name, rawValue) {
+    let value = rawValue
+        .replace(/\r\n/g, "\n")
+        .replace(/\{\{\s*/g, "{{")
+        .replace(/\s*\}\}/g, "}}")
+        .replace(/\{%\s*/g, "{%")
+        .replace(/\s*%\}/g, "%}")
+        .replace(/\s+/g, " ")
+        .trim();
+    if (name === "class" || name === "className") {
+        value = value.replace(/%\}\s+\{%/g, "%}{%");
+    }
+    return value;
+}
+function normalizeHtmlTag(tag) {
+    const voidTags = new Set([
+        "area",
+        "base",
+        "br",
+        "col",
+        "embed",
+        "hr",
+        "img",
+        "input",
+        "link",
+        "meta",
+        "param",
+        "source",
+        "track",
+        "wbr",
+    ]);
+    const trimmed = tag.trim();
+    if (trimmed.startsWith("</")) {
+        const name = trimmed.slice(2, -1).trim();
+        return `</${name}>`;
+    }
+    const selfClosing = trimmed.endsWith("/>");
+    const body = trimmed.slice(1, trimmed.length - (selfClosing ? 2 : 1)).trim();
+    let cursor = 0;
+    let tagName = "";
+    while (cursor < body.length && !/\s/.test(body[cursor])) {
+        tagName += body[cursor];
+        cursor += 1;
+    }
+    const attrs = [];
+    const seenAttrs = new Set();
+    while (cursor < body.length) {
+        while (cursor < body.length && /\s/.test(body[cursor])) {
+            cursor += 1;
+        }
+        if (cursor >= body.length) {
+            break;
+        }
+        let name = "";
+        while (cursor < body.length && !/[\s=]/.test(body[cursor])) {
+            name += body[cursor];
+            cursor += 1;
+        }
+        while (cursor < body.length && /\s/.test(body[cursor])) {
+            cursor += 1;
+        }
+        let value = null;
+        if (body[cursor] === "=") {
+            cursor += 1;
+            while (cursor < body.length && /\s/.test(body[cursor])) {
+                cursor += 1;
+            }
+            if (body[cursor] === '"' || body[cursor] === "'") {
+                const quote = body[cursor];
+                cursor += 1;
+                let rawValue = "";
+                while (cursor < body.length) {
+                    const templateBlock = readTemplateBlock(body, cursor);
+                    if (templateBlock) {
+                        rawValue += templateBlock.block;
+                        cursor = templateBlock.nextIndex;
+                        continue;
+                    }
+                    if (body[cursor] === quote) {
+                        break;
+                    }
+                    rawValue += body[cursor];
+                    cursor += 1;
+                }
+                cursor += 1;
+                value = normalizeAttributeValue(name, rawValue);
+            }
+            else {
+                let rawValue = "";
+                while (cursor < body.length && !/\s/.test(body[cursor])) {
+                    rawValue += body[cursor];
+                    cursor += 1;
+                }
+                value = normalizeAttributeValue(name, rawValue);
+            }
+        }
+        if (seenAttrs.has(name)) {
+            continue;
+        }
+        seenAttrs.add(name);
+        attrs.push(value === null ? name : `${name}="${value}"`);
+    }
+    const joinedAttrs = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
+    const forceSelfClosing = selfClosing || voidTags.has(tagName);
+    return forceSelfClosing
+        ? `<${tagName}${joinedAttrs}/>`
+        : `<${tagName}${joinedAttrs}>`;
+}
+export function verifyAskamaFixtures(options = {}) {
+    const fixtureList = options.fixtures ?? [];
+    const logger = options.logger ?? console;
+    let hasFailure = false;
+    let hasFormatOnly = false;
+    const result = {
+        ok: [],
+        formatOnly: [],
+        failures: [],
+        missing: [],
+    };
+    for (const fixture of fixtureList) {
+        if (!existsSync(fixture.generated)) {
+            hasFailure = true;
+            result.missing.push(fixture.name);
+            logger.error(`missing generated: ${fixture.name}`);
+            continue;
+        }
+        const sourceRaw = readFileSync(fixture.source, "utf8").replace(/\r\n/g, "\n").trim();
+        const generatedRaw = readFileSync(fixture.generated, "utf8").replace(/\r\n/g, "\n").trim();
+        const source = normalizeAskama(sourceRaw);
+        const generated = normalizeAskama(generatedRaw);
+        if (sourceRaw === generatedRaw) {
+            result.ok.push(fixture.name);
+            logger.log(`ok: ${fixture.name}`);
+            continue;
+        }
+        if (source === generated) {
+            hasFormatOnly = true;
+            result.formatOnly.push(fixture.name);
+            logger.log(`format-only: ${fixture.name}`);
+            continue;
+        }
+        hasFailure = true;
+        result.failures.push(fixture.name);
+        logger.error(`functional mismatch: ${fixture.name}`);
+    }
+    if (hasFailure) {
+        process.exitCode = 1;
+    }
+    if (!hasFailure && hasFormatOnly) {
+        logger.log("no functional mismatches; only formatting/serialization differences remain");
+    }
+    return result;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { buildProject } from "./core/build.js";
+export type { BuildProjectOptions, BuildProjectResult } from "./core/build.js";
+export { parseTemplateFile } from "./core/parser.js";
+export { verifyAskamaFixtures, normalizeAskama } from "./core/verify.js";
+export * from "./api/index.js";
+export type { BuildTemplate, ComponentRegistration, ComponentRegistry, OutputTarget, ParsedTemplate, TargetOutputFile, TemplateImport, TemplateProp, } from "./core/types.js";
+export * from "./core/ast.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export { buildProject } from "./core/build.js";
+export { parseTemplateFile } from "./core/parser.js";
+export { verifyAskamaFixtures, normalizeAskama } from "./core/verify.js";
+export * from "./api/index.js";
+export * from "./core/ast.js";

package/dist/targets/askama.d.ts

@@ -0,0 +1,11 @@
+import type { Node } from "../core/ast.js";
+import type { BuildTemplate } from "../core/types.js";
+/**
+ * Emits portable AST nodes into Askama template source.
+ */
+export declare function emitAskama(node: Node, indent?: number, componentRegistry?: BuildTemplate["componentRegistry"]): string;
+/**
+ * Emits the Rust `Template` wrapper for Askama consumption.
+ */
+export declare function emitAskamaComponent(template: BuildTemplate): string;
+export declare function emitAskamaPartial(template: BuildTemplate): string;

package/dist/targets/askama.js

@@ -0,0 +1,122 @@
+import { emitAskamaExpr, escapeDoubleQuotes, toCamelCase, toRustType, wrapHtmlAttribute, } from "./shared.js";
+/**
+ * Emits an HTML attribute for Askama output.
+ */
+function emitAskamaAttr(name, value) {
+    switch (value.kind) {
+        case "text":
+            return `${name}=${wrapHtmlAttribute(value.value)}`;
+        case "expr":
+            return `${name}=${wrapHtmlAttribute(`{{ ${emitAskamaExpr(value.expr)} }}`)}`;
+        case "classList": {
+            const parts = [];
+            for (const item of value.items) {
+                if (item.kind === "static") {
+                    parts.push(item.value);
+                    continue;
+                }
+                parts.push(`{% if ${emitAskamaExpr(item.test)} %}${item.value}{% endif %}`);
+            }
+            return `${name}=${wrapHtmlAttribute(parts.join(" ").trim())}`;
+        }
+    }
+}
+/**
+ * Emits portable AST nodes into Askama template source.
+ */
+export function emitAskama(node, indent = 0, componentRegistry = {}) {
+    const pad = "  ".repeat(indent);
+    switch (node.kind) {
+        case "text":
+            return `${pad}${node.value}`;
+        case "slot":
+            return `${pad}{{ ${node.name}|safe }}`;
+        case "print":
+            return `${pad}{{ ${emitAskamaExpr(node.expr)}${node.safe ? "|safe" : ""} }}`;
+        case "if": {
+            const thenPart = node.then
+                .map((child) => emitAskama(child, indent + 1, componentRegistry))
+                .join("\n");
+            const elsePart = (node.else ?? [])
+                .map((child) => emitAskama(child, indent + 1, componentRegistry))
+                .join("\n");
+            if (elsePart) {
+                return `${pad}{% if ${emitAskamaExpr(node.test)} %}\n${thenPart}\n${pad}{% else %}\n${elsePart}\n${pad}{% endif %}`;
+            }
+            return `${pad}{% if ${emitAskamaExpr(node.test)} %}\n${thenPart}\n${pad}{% endif %}`;
+        }
+        case "for": {
+            const body = node.children
+                .map((child) => emitAskama(child, indent + 1, componentRegistry))
+                .join("\n");
+            return `${pad}{% for ${node.item} in ${emitAskamaExpr(node.each)} %}\n${body}\n${pad}{% endfor %}`;
+        }
+        case "element": {
+            const attrEntries = Object.entries(node.attrs ?? {});
+            const attrs = attrEntries.length
+                ? `\n${attrEntries
+                    .map(([name, value]) => `${pad}  ${emitAskamaAttr(name, value)}`)
+                    .join("\n")}\n${pad}`
+                : "";
+            const children = (node.children ?? []).map((child) => emitAskama(child, indent + 1, componentRegistry));
+            if (children.length === 0) {
+                return `${pad}<${node.tag}${attrs}/>`;
+            }
+            return `${pad}<${node.tag}${attrs}>\n${children.join("\n")}\n${pad}</${node.tag}>`;
+        }
+        case "component": {
+            const registration = componentRegistry[node.name];
+            if (!registration) {
+                throw new Error(`Missing Askama component registration for ${node.name}`);
+            }
+            const lines = [];
+            for (const [propName, propValue] of Object.entries(node.props ?? {})) {
+                if (propValue.kind === "text") {
+                    lines.push(`${pad}{% let ${propName} = "${escapeDoubleQuotes(propValue.value)}" %}`);
+                    continue;
+                }
+                if (propValue.kind === "expr") {
+                    lines.push(`${pad}{% let ${propName} = ${emitAskamaExpr(propValue.expr)} %}`);
+                    continue;
+                }
+                throw new Error(`Component prop ${propName} on ${node.name} must be text or expr for Askama include output`);
+            }
+            if ((node.children ?? []).length > 0) {
+                lines.push(`${pad}{% let children %}`);
+                lines.push(...(node.children ?? []).map((child) => emitAskama(child, indent + 1, componentRegistry)));
+                lines.push(`${pad}{% endlet %}`);
+            }
+            lines.push(`${pad}{% include "${registration.include}" %}`);
+            return lines.join("\n");
+        }
+    }
+}
+/**
+ * Emits the Rust `Template` wrapper for Askama consumption.
+ */
+export function emitAskamaComponent(template) {
+    const structName = `${template.name}Template`;
+    const props = template.props ?? [];
+    const needsLifetime = props.some((prop) => toRustType(prop.type).includes("'a"));
+    const lifetime = needsLifetime ? "<'a>" : "";
+    const fields = props
+        .map((prop) => `    pub ${toCamelCase(prop.name)}: ${toRustType(prop.type)},`)
+        .join("\n");
+    const source = emitAskama(template.template, 0, template.componentRegistry ?? {}).replace(/#"/g, '#\\"');
+    return `use askama::Template;
+
+#[derive(Template)]
+#[template(
+    ext = "html",
+    source = r#"
+${source}
+"#
+)]
+pub struct ${structName}${lifetime} {
+${fields}
+}
+`;
+}
+export function emitAskamaPartial(template) {
+    return `${emitAskama(template.template, 0, template.componentRegistry ?? {})}\n`;
+}

package/dist/targets/index.d.ts

@@ -0,0 +1,5 @@
+import type { OutputTarget } from "../core/types.js";
+/**
+ * Central registry for output formats. The build driver only depends on this interface.
+ */
+export declare const outputTargets: OutputTarget[];

package/dist/targets/index.js

@@ -0,0 +1,60 @@
+import { emitAskamaComponent, emitAskamaPartial } from "./askama.js";
+import { emitReactComponent } from "./react.js";
+import { emitStaticJsxComponent } from "./static-jsx.js";
+/**
+ * Central registry for output formats. The build driver only depends on this interface.
+ */
+export const outputTargets = [
+    {
+        id: "react",
+        outputSubdir: "react",
+        extension: ".tsx",
+        emitFiles(template) {
+            return [
+                {
+                    fileName: `${template.fileName}.tsx`,
+                    content: `${emitReactComponent(template)}\n`,
+                },
+            ];
+        },
+    },
+    {
+        id: "jsx-static",
+        outputSubdir: "jsx-static",
+        extension: ".tsx",
+        emitFiles(template) {
+            return [
+                {
+                    fileName: `${template.fileName}.tsx`,
+                    content: `${emitStaticJsxComponent(template)}\n`,
+                },
+            ];
+        },
+    },
+    {
+        id: "askama",
+        outputSubdir: "askama",
+        extension: ".rs",
+        emitFiles(template) {
+            return [
+                {
+                    fileName: `${template.fileName}.rs`,
+                    content: `${emitAskamaComponent(template)}\n`,
+                },
+            ];
+        },
+    },
+    {
+        id: "askama-includes",
+        outputSubdir: "askama/includes",
+        extension: ".html",
+        emitFiles(template) {
+            return [
+                {
+                    fileName: `${template.fileName}.html`,
+                    content: emitAskamaPartial(template),
+                },
+            ];
+        },
+    },
+];

package/dist/targets/react.d.ts

@@ -0,0 +1,4 @@
+import type { Node } from "../core/ast.js";
+import type { BuildTemplate } from "../core/types.js";
+export declare function emitReact(node: Node, indent?: number): string;
+export declare function emitReactComponent(template: BuildTemplate): string;

package/dist/targets/react.js

@@ -0,0 +1,28 @@
+import { buildTsxComponentSource, emitTsxExpr, emitTsxNode } from "./shared.js";
+/**
+ * Emits attributes for React-compatible TSX output.
+ */
+function emitReactAttr(name, value) {
+    const attrName = name === "class" ? "className" : name;
+    switch (value.kind) {
+        case "text":
+            return `${attrName}=${JSON.stringify(value.value)}`;
+        case "expr":
+            return `${attrName}={${emitTsxExpr(value.expr)}}`;
+        case "classList": {
+            const items = value.items.map((item) => {
+                if (item.kind === "static") {
+                    return JSON.stringify(item.value);
+                }
+                return `${emitTsxExpr(item.test)} ? ${JSON.stringify(item.value)} : null`;
+            });
+            return `${attrName}={[${items.join(", ")}].filter(Boolean).join(" ")}`;
+        }
+    }
+}
+export function emitReact(node, indent = 0) {
+    return emitTsxNode(node, emitReactAttr, indent);
+}
+export function emitReactComponent(template) {
+    return buildTsxComponentSource(template, emitReact(template.template, 2));
+}

package/dist/targets/shared.d.ts

@@ -0,0 +1,36 @@
+import type { AttrValue, Expr, Node } from "../core/ast.js";
+import type { BuildTemplate } from "../core/types.js";
+/**
+ * Escapes a string for insertion into Rust string literals used by Askama wrappers.
+ */
+declare function escapeDoubleQuotes(value: string): string;
+/**
+ * Chooses a stable quote style for generated HTML attributes so mixed template
+ * syntax stays readable and editor highlighting does not break.
+ */
+declare function wrapHtmlAttribute(value: string): string;
+/**
+ * Emits a portable expression into TSX/React-family output.
+ */
+export declare function emitTsxExpr(expr: Expr): string;
+/**
+ * Emits a portable expression into Askama syntax.
+ */
+export declare function emitAskamaExpr(expr: Expr): string;
+export type TsxAttrEmitter = (name: string, value: AttrValue) => string;
+/**
+ * Shared JSX/TSX tree emitter used by both React and static JSX targets.
+ */
+export declare function emitTsxNode(node: Node, emitAttr: TsxAttrEmitter, indent?: number): string;
+export declare function toCamelCase(value: string): string;
+export declare function toRustType(type: string): string;
+export declare function toTsType(type: string): string;
+/**
+ * Builds import lines for nested template components in TSX-family targets.
+ */
+export declare function buildTsxImportLines(template: BuildTemplate): string;
+/**
+ * Wraps an emitted TSX template body in a component module.
+ */
+export declare function buildTsxComponentSource(template: BuildTemplate, body: string): string;
+export { escapeDoubleQuotes, wrapHtmlAttribute };