@gtkx/codegen 1.0.0 → 1.2.0

package/src/writer/module.ts

@@ -1,30 +1,109 @@
 import { ImportsBuilder } from "./imports.js";
 
-type DeclaredType = {
+type Declaration = {
     name: string;
-    owner: string;
+    code: string;
+    owner?: string | undefined;
 };
 
+type ExportedDeclaration = {
+    name: string;
+    spaces: string[];
+};
+
+const EXPORTED_DECLARATION = /^export (?:abstract )?(class|const|enum|function|interface|type) ([A-Za-z_$][\w$]*)/mu;
+
+const SPACES_BY_KEYWORD: Map<string, string[]> = new Map([
+    ["class", ["value", "type"]],
+    ["const", ["value"]],
+    ["enum", ["value", "type"]],
+    ["function", ["value"]],
+    ["interface", []],
+    ["type", ["type"]],
+]);
+
+const getExportedDeclaration = (code: string): ExportedDeclaration | undefined => {
+    const match = EXPORTED_DECLARATION.exec(code);
+    const spaces = SPACES_BY_KEYWORD.get(match?.[1] ?? "");
+    const name = match?.[2];
+
+    return spaces === undefined || name === undefined ? undefined : { name, spaces };
+};
+
+const exportedNameText = (exported: ExportedDeclaration | undefined): string =>
+    exported === undefined ? "no name at all" : `'${exported.name}'`;
+
 class ModuleBuilder {
     private bindings: string[] = [];
     private bindingNames: Set<string> = new Set();
     private hoistedDescriptors: Map<string, string> = new Map();
+    private claimedSpaces: Set<string> = new Set();
     private declarations: string[] = [];
+    private declaredNames: Set<string> = new Set();
     private declaredTypes: Map<string, string> = new Map();
     private registrations: string[] = [];
+    private requiredNames: Set<string> = new Set();
     public imports: ImportsBuilder = new ImportsBuilder();
 
-    private claimTypeName(declared: DeclaredType): void {
-        const owner = this.declaredTypes.get(declared.name);
+    private claimSpace(name: string, space: string): void {
+        const key = `${space} ${name}`;
+
+        if (this.claimedSpaces.has(key)) {
+            throw new Error(
+                `The generated module declares '${name}' twice in its ${space} space. ` +
+                "A module may declare each exported name once per declaration space.",
+            );
+        }
+
+        this.claimedSpaces.add(key);
+    }
+
+    private claimExportedName(declaration: Declaration): void {
+        const exported = getExportedDeclaration(declaration.code);
+        const spaces = exported?.name === declaration.name ? exported.spaces : undefined;
+
+        if (spaces === undefined) {
+            throw new Error(
+                `The declaration recorded as '${declaration.name}' exports ${exportedNameText(exported)}. ` +
+                "A declaration may only be recorded under the name its own code exports.",
+            );
+        }
+
+        for (const space of spaces) {
+            this.claimSpace(declaration.name, space);
+        }
+    }
+
+    private claimTypeName(declaration: Declaration): void {
+        const { name, owner } = declaration;
+
+        if (owner === undefined) {
+            return;
+        }
+
+        const previous = this.declaredTypes.get(name);
 
-        if (owner !== undefined && owner !== declared.owner) {
+        if (previous !== undefined && previous !== owner) {
             throw new Error(
-                `The generated type '${declared.name}' is declared for both ${owner} and ${declared.owner}. ` +
+                `The generated type '${name}' is declared for both ${previous} and ${owner}. ` +
                 "Rename one of them, or drop the namespace from the configuration.",
             );
         }
 
-        this.declaredTypes.set(declared.name, declared.owner);
+        this.declaredTypes.set(name, owner);
+    }
+
+    private verifyRegistrations(): void {
+        const missing = [...this.requiredNames].filter((name) => !this.declaredNames.has(name));
+
+        if (missing.length === 0) {
+            return;
+        }
+
+        throw new Error(
+            `The generated module registers ${missing.join(", ")}, which it never declares. ` +
+            "A registration may only name a symbol whose declaration the same module emits.",
+        );
     }
 
     appendBinding(code: string, name?: string): void {
@@ -53,19 +132,27 @@ class ModuleBuilder {
         return name;
     }
 
-    appendDeclaration(code: string, declared?: DeclaredType): void {
-        if (declared !== undefined) {
-            this.claimTypeName(declared);
-        }
+    appendDeclaration(declaration: Declaration): void {
+        this.claimExportedName(declaration);
+        this.claimTypeName(declaration);
+        this.declaredNames.add(declaration.name);
+        this.declarations.push(declaration.code);
+    }
 
-        this.declarations.push(code);
+    hasExports(): boolean {
+        return this.declaredNames.size > 0;
     }
 
-    appendRegistration(code: string): void {
+    appendRegistration(code: string, requires: string[] = []): void {
+        for (const name of requires) {
+            this.requiredNames.add(name);
+        }
+
         this.registrations.push(code);
     }
 
     toSource(): string {
+        this.verifyRegistrations();
         const sections: string[] = [];
         const importsBlock = this.imports.toSource();
 
@@ -89,4 +176,4 @@ class ModuleBuilder {
     }
 }
 
-export { type DeclaredType, ModuleBuilder };
+export { type Declaration, ModuleBuilder };

package/src/xml.ts

@@ -1,4 +1,17 @@
+import { errorMessage, isRecord } from "@gtkx/utils";
 import { type X2jOptions, XMLParser } from "fast-xml-parser";
+import { SyntaxValidator } from "fast-xml-validator";
+import { readFileSync } from "node:fs";
+
+type XmlFileInput = {
+    parser: XMLParser;
+    label: string;
+    path: string;
+    malformedRemedy?: string;
+};
+
+const HIGHEST_CONTROL_CODE = 0x1F;
+const LEGAL_CONTROL_CODES: Set<number> = new Set([0x09, 0x0A, 0x0D]);
 
 const createXmlParser = (options: Partial<X2jOptions>): XMLParser =>
     new XMLParser({
@@ -9,4 +22,93 @@ const createXmlParser = (options: Partial<X2jOptions>): XMLParser =>
         ...options,
     });
 
-export { createXmlParser };
+const xmlFileError = (input: XmlFileInput, action: string, error: unknown): Error =>
+    new Error(`Cannot ${action} the ${input.label} at ${input.path}: ${errorMessage(error)}`, { cause: error });
+
+const readXmlFile = (input: XmlFileInput): string => {
+    try {
+        return readFileSync(input.path, "utf8");
+    } catch (error) {
+        throw xmlFileError(input, "read", error);
+    }
+};
+
+const isLocated = (line: unknown, col: unknown): boolean =>
+    typeof line === "number" && typeof col === "number" && (line > 1 || col > 1);
+
+const positionSuffix = (error: unknown): string => {
+    if (!isRecord(error)) {
+        return "";
+    }
+
+    const { line, col } = error;
+
+    if (!isLocated(line, col)) {
+        return "";
+    }
+
+    return ` (line ${String(line)}, column ${String(col)})`;
+};
+
+const isIllegalControlCode = (code: number): boolean =>
+    code <= HIGHEST_CONTROL_CODE && !LEGAL_CONTROL_CODES.has(code);
+
+const escapedCode = (code: number): string => `[U+${code.toString(16).toUpperCase().padStart(4, "0")}]`;
+
+const escapeControlCodes = (text: string): string => {
+    let escaped = "";
+
+    for (const character of text) {
+        const code = character.codePointAt(0) ?? 0;
+        escaped += isIllegalControlCode(code) ? escapedCode(code) : character;
+    }
+
+    return escaped;
+};
+
+const offendingLine = (xml: string, error: unknown): string => {
+    const line = isRecord(error) ? error.line : undefined;
+
+    if (typeof line !== "number") {
+        return "";
+    }
+
+    const text = xml.split("\n")[line - 1];
+
+    if (text === undefined) {
+        return "";
+    }
+
+    return `\n    ${escapeControlCodes(text.replace(/^[ \t]+/, "").replace(/\r$/, ""))}`;
+};
+
+const remedySuffix = (input: XmlFileInput, xml: string, error: unknown): string => {
+    const remedy = input.malformedRemedy;
+
+    return remedy === undefined ? "" : `${offendingLine(xml, error)}\n${remedy}`;
+};
+
+const assertWellFormed = (input: XmlFileInput, xml: string): void => {
+    try {
+        SyntaxValidator.validate(xml);
+    } catch (error) {
+        throw new Error(
+            `The ${input.label} at ${input.path} is not well-formed XML: ` +
+            `${errorMessage(error)}${positionSuffix(error)}${remedySuffix(input, xml, error)}`,
+            { cause: error },
+        );
+    }
+};
+
+const parseXmlFile = (input: XmlFileInput): unknown => {
+    const xml = readXmlFile(input);
+    assertWellFormed(input, xml);
+
+    try {
+        return input.parser.parse(xml);
+    } catch (error) {
+        throw xmlFileError(input, "parse", error);
+    }
+};
+
+export { createXmlParser, parseXmlFile };