@postxl/generator 0.74.2 → 1.0.1

package/dist/utils/logger.class.d.ts

@@ -0,0 +1,25 @@
+export type LogFunction = (logMessage: string) => void;
+type Severity = 'info' | 'debug' | 'log' | 'warn' | 'error';
+type Message = {
+    severity: Severity;
+    message: string;
+};
+/**
+ * A small logger wrapper class.
+ *
+ * This is meant to simplify testing and logging.
+ */
+export declare class Logger {
+    private readonly useConsole;
+    private messages;
+    constructor(useConsole?: boolean);
+    log(logMessage: string): void;
+    warn(logMessage: string): void;
+    error(logMessage: string): void;
+    debug(logMessage: string): void;
+    info(logMessage: string): void;
+    getMessages(): Message[];
+    clearMessages(): void;
+    getMessagesAsString(): string;
+}
+export {};

package/dist/utils/logger.class.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+/**
+ * A small logger wrapper class.
+ *
+ * This is meant to simplify testing and logging.
+ */
+class Logger {
+    useConsole;
+    messages = [];
+    constructor(useConsole = true) {
+        this.useConsole = useConsole;
+    }
+    log(logMessage) {
+        if (this.useConsole) {
+            console.log(logMessage);
+        }
+        this.messages.push({ severity: 'log', message: logMessage });
+    }
+    warn(logMessage) {
+        if (this.useConsole) {
+            console.warn(logMessage);
+        }
+        this.messages.push({ severity: 'warn', message: logMessage });
+    }
+    error(logMessage) {
+        if (this.useConsole) {
+            console.error(logMessage);
+        }
+        this.messages.push({ severity: 'error', message: logMessage });
+    }
+    debug(logMessage) {
+        if (this.useConsole) {
+            console.debug(logMessage);
+        }
+        this.messages.push({ severity: 'debug', message: logMessage });
+    }
+    info(logMessage) {
+        if (this.useConsole) {
+            console.info(logMessage);
+        }
+        this.messages.push({ severity: 'info', message: logMessage });
+    }
+    getMessages() {
+        return this.messages;
+    }
+    clearMessages() {
+        this.messages = [];
+    }
+    getMessagesAsString() {
+        return this.messages.map((m) => m.message).join('\n');
+    }
+}
+exports.Logger = Logger;

package/dist/utils/merge-conflict.d.ts

@@ -0,0 +1,55 @@
+import { FileContent } from './fs-utils';
+/**
+ * Standard merge conflict markers used by git and our generator
+ */
+export declare const mergeConflictMarkers: {
+    readonly start: "<<<<<<<";
+    readonly separator: "=======";
+    readonly end: ">>>>>>>";
+};
+/**
+ * Checks if file content contains unresolved merge conflict markers.
+ *
+ * @param content - The file content to check
+ * @returns true if the content contains merge conflict markers, false otherwise
+ */
+export declare function hasMergeConflictMarkers(content: FileContent): boolean;
+/**
+ * Generates a merged output with conflict markers between two file contents.
+ *
+ * @param contentSource - The content of the first file as a string.
+ * @param contentIncoming - The content of the second file as a string.
+ * @param labelSource - Optional label for the first file in conflict markers.
+ * @param labelIncoming - Optional label for the second file in conflict markers.
+ * @returns The merged content with conflict markers as a string.
+ */
+export declare function generateMergeConflict({ contentSource, contentIncoming, labelSource, labelIncoming, }: {
+    contentSource: FileContent;
+    contentIncoming: FileContent;
+    labelSource?: string;
+    labelIncoming?: string;
+}): FileContent;
+/**
+ * Generates a summary of the differences between two files: For each conflict,
+ * it will show the first 3 lines of each conflict with line counters, i.e.:
+ * ```
+ * in Red:
+ * -X1: [line X1]
+ * -X1+1: [line X1+1]
+ * -X1-Y1 Z additional lines
+ * in Green
+ * +X2: [line X2]
+ * +X2+1: [line X2+1]
+ * +X2-Y2 Z additional lines
+ * ```
+ *
+ * For same content, it will not show anything.
+ *
+ * @param contentSource - The content of the first file as a string.
+ * @param contentIncoming - The content of the second file as a string.
+ * @returns Summary of the diff as a string.
+ */
+export declare function generateDiffSummary({ contentSource, contentIncoming, }: {
+    contentSource: FileContent;
+    contentIncoming: FileContent;
+}): string;

package/dist/utils/merge-conflict.js

@@ -0,0 +1,264 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeConflictMarkers = void 0;
+exports.hasMergeConflictMarkers = hasMergeConflictMarkers;
+exports.generateMergeConflict = generateMergeConflict;
+exports.generateDiffSummary = generateDiffSummary;
+const Diff = __importStar(require("diff"));
+const utils_1 = require("@postxl/utils");
+/**
+ * Standard merge conflict markers used by git and our generator
+ */
+exports.mergeConflictMarkers = {
+    start: '<<<<<<<',
+    separator: '=======',
+    end: '>>>>>>>',
+};
+/**
+ * Checks if file content contains unresolved merge conflict markers.
+ *
+ * @param content - The file content to check
+ * @returns true if the content contains merge conflict markers, false otherwise
+ */
+function hasMergeConflictMarkers(content) {
+    // Binary content cannot have merge conflict markers
+    if (typeof content !== 'string') {
+        return false;
+    }
+    // Check for all three markers - a proper merge conflict must have all of them
+    const hasStart = content.includes(exports.mergeConflictMarkers.start);
+    const hasSeparator = content.includes(exports.mergeConflictMarkers.separator);
+    const hasEnd = content.includes(exports.mergeConflictMarkers.end);
+    return hasStart && hasSeparator && hasEnd;
+}
+/**
+ * Normalizes whitespace in a string by:
+ * - Normalizing all line endings to Unix format (LF)
+ * - Trimming trailing whitespace from each line
+ * - Removing empty lines at the end
+ * - Removing BOM markers
+ */
+function normalizeWhitespace(content) {
+    const normalized = content
+        .replaceAll('\r\n', '\n') // Normalize Windows line endings to Unix
+        .replaceAll('\n\r', '\n') // Normalize Mac line endings to Unix
+        .replaceAll('\r', '\n') // Normalize Mac line endings to Unix
+        .replaceAll('\uFEFF', ''); // Remove BOM
+    const lines = normalized.split('\n').map((line) => line.trimEnd()); // Trim trailing whitespace from each line
+    // Remove trailing empty lines
+    while (lines.length > 0 && lines.at(-1) === '') {
+        lines.pop();
+    }
+    return lines.join('\n');
+}
+/**
+ * Checks if two arrays of lines differ only in whitespace/spacing
+ */
+function isWhitespaceOnlyDifference(sourceLines, incomingLines) {
+    const sourceNormalized = normalizeWhitespace(sourceLines.join('\n'));
+    const incomingNormalized = normalizeWhitespace(incomingLines.join('\n'));
+    return sourceNormalized === incomingNormalized;
+}
+/**
+ * Generates a merged output with conflict markers between two file contents.
+ *
+ * @param contentSource - The content of the first file as a string.
+ * @param contentIncoming - The content of the second file as a string.
+ * @param labelSource - Optional label for the first file in conflict markers.
+ * @param labelIncoming - Optional label for the second file in conflict markers.
+ * @returns The merged content with conflict markers as a string.
+ */
+function generateMergeConflict({ contentSource, contentIncoming, labelSource = 'Manual', labelIncoming = 'Generated', }) {
+    // In case the content is binary, we just return the incoming content
+    if (typeof contentSource !== 'string' || typeof contentIncoming !== 'string') {
+        return contentIncoming;
+    }
+    // Check if the ENTIRE file differs only in whitespace
+    // If so, just return the incoming content to preserve its exact formatting
+    const sourceNormalized = normalizeWhitespace(contentSource);
+    const incomingNormalized = normalizeWhitespace(contentIncoming);
+    if (sourceNormalized === incomingNormalized) {
+        return contentIncoming;
+    }
+    const blocks = new Blocks({ source: contentSource, incoming: contentIncoming });
+    let result = '';
+    for (const block of blocks.blocks) {
+        if (block.type === 'Same') {
+            result += block.lines.join('\n') + '\n';
+            continue;
+        }
+        // Check if this conflict is only due to whitespace differences
+        if (isWhitespaceOnlyDifference(block.source, block.incoming)) {
+            // If only whitespace differs, use the incoming (generated) version without conflict markers
+            // Handle empty incoming array (removed content) - don't add anything
+            if (block.incoming.length > 0) {
+                result += block.incoming.join('\n') + '\n';
+            }
+            continue;
+        }
+        // Real content difference - create conflict markers
+        result += `${exports.mergeConflictMarkers.start} ${labelSource}\n`;
+        result += block.source.join('\n') + '\n';
+        result += `${exports.mergeConflictMarkers.separator}\n`;
+        result += block.incoming.join('\n') + '\n';
+        result += `${exports.mergeConflictMarkers.end} ${labelIncoming}\n`;
+    }
+    return result;
+}
+/**
+ * Generates a summary of the differences between two files: For each conflict,
+ * it will show the first 3 lines of each conflict with line counters, i.e.:
+ * ```
+ * in Red:
+ * -X1: [line X1]
+ * -X1+1: [line X1+1]
+ * -X1-Y1 Z additional lines
+ * in Green
+ * +X2: [line X2]
+ * +X2+1: [line X2+1]
+ * +X2-Y2 Z additional lines
+ * ```
+ *
+ * For same content, it will not show anything.
+ *
+ * @param contentSource - The content of the first file as a string.
+ * @param contentIncoming - The content of the second file as a string.
+ * @returns Summary of the diff as a string.
+ */
+function generateDiffSummary({ contentSource, contentIncoming, }) {
+    if (typeof contentSource !== 'string' || typeof contentIncoming !== 'string') {
+        return 'Binary content, diff not possible';
+    }
+    let result = '';
+    const blocks = new Blocks({ source: contentSource, incoming: contentIncoming });
+    let isFirstConflict = true;
+    for (const block of blocks.blocks) {
+        if (block.type === 'Same') {
+            continue;
+        }
+        result += summarizeConflictBlock(block, isFirstConflict);
+        isFirstConflict = false;
+    }
+    return result;
+}
+class Blocks {
+    blocks = [];
+    #currentBlock = undefined;
+    constructor({ source, incoming }) {
+        const diff = Diff.diffLines(source, incoming);
+        for (const part of diff) {
+            const lines = part.value.trimEnd().split('\n');
+            if (part.added) {
+                this.#addIncomingDelta(lines);
+            }
+            else if (part.removed) {
+                this.#addSourceDelta(lines);
+            }
+            else {
+                this.#addSame(lines);
+            }
+        }
+    }
+    #addIncomingDelta(lines) {
+        const block = this.#ensureConflictBlock();
+        block.incoming.push(...lines);
+    }
+    #addSourceDelta(lines) {
+        const block = this.#ensureConflictBlock();
+        block.source.push(...lines);
+    }
+    #addSame(lines) {
+        const block = this.#ensureSameBlock();
+        block.lines.push(...lines);
+    }
+    #ensureSameBlock() {
+        if (this.#currentBlock && this.#currentBlock.type === 'Same') {
+            return this.#currentBlock;
+        }
+        this.#currentBlock = { type: 'Same', lines: [], counters: this.#getNextBlockLineCounters() };
+        this.blocks.push(this.#currentBlock);
+        return this.#currentBlock;
+    }
+    #getNextBlockLineCounters() {
+        if (!this.#currentBlock) {
+            return { incoming: 1, source: 1 };
+        }
+        const block = this.#currentBlock;
+        const incomingLines = block.type === 'Same' ? block.lines.length : block.incoming.length;
+        const sourceLines = block.type === 'Same' ? block.lines.length : block.source.length;
+        return {
+            incoming: block.counters.incoming + incomingLines,
+            source: block.counters.source + sourceLines,
+        };
+    }
+    #ensureConflictBlock() {
+        if (this.#currentBlock && this.#currentBlock.type === 'Conflict') {
+            return this.#currentBlock;
+        }
+        this.#currentBlock = {
+            type: 'Conflict',
+            source: [],
+            incoming: [],
+            isFirstConflict: true,
+            counters: this.#getNextBlockLineCounters(),
+        };
+        this.blocks.push(this.#currentBlock);
+        return this.#currentBlock;
+    }
+}
+function summarizeConflictBlock({ incoming, source, counters }, isFirstConflict) {
+    return ((isFirstConflict ? '' : (0, utils_1.gray)('...') + '\n') +
+        summarizeChange('-', utils_1.red, source, counters.source) +
+        summarizeChange('+', utils_1.green, incoming, counters.incoming));
+}
+function summarizeChange(prefix, colorFn, lines, startLineCounter) {
+    if (lines.length === 0) {
+        return '';
+    }
+    let result = '';
+    let lineCounter = 0;
+    for (const line of lines) {
+        lineCounter++;
+        if (lineCounter < 3 || lines.length === 3) {
+            result += colorFn(`${prefix}${startLineCounter + lineCounter - 1}: ${line}`) + '\n';
+        }
+        else if (lineCounter === 3) {
+            result +=
+                colorFn(`${prefix}${startLineCounter + lineCounter - 1}-${startLineCounter + lines.length - 1} additional lines`) + '\n';
+        }
+    }
+    return result;
+}

package/dist/utils/path.d.ts

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+export declare const zPosixPath: z.ZodBranded<z.ZodString, "PXL.PosixPath">;
+/**
+ * A path string that has been normalized to use the unix path separator.
+ */
+export type PosixPath = z.infer<typeof zPosixPath>;
+export declare const POSIX_ROOT: string & z.BRAND<"PXL.PosixPath">;
+/**
+ * Normalizes a unix or Windows path to use the unix path separator. Additionally,
+ * it normalizes the path so that every path is considered absolute.
+ */
+export declare function normalize(path: string): PosixPath;
+/**
+ * Joins two paths together appending the second path to the first.
+ */
+export declare function join(dir: PosixPath, path: PosixPath | string): PosixPath;
+/**
+ * Returns the file name of the given path.
+ */
+export declare function fileName(path: PosixPath): string;
+/**
+ * Parses a given string into a path array.
+ */
+export declare function parse(path: PosixPath): PosixPath[];
+/**
+ * Tells whether a given dir contains a given target. It expects that both paths are absolute and normalized.
+ *
+ * @example
+ *
+ * ```ts
+ * contains('/foo/bar', '/foo/bar/baz') // true
+ * ```
+ */
+export declare function contains(dir: PosixPath, target: PosixPath): boolean;
+/**
+ * Changes the directory of a given path. If a path is not in the given directory,
+ * it will return an unchanged path.
+ */
+export declare function cd(dir: PosixPath, path: PosixPath): PosixPath;
+export declare function isPackageName(name: string): boolean;
+/**
+ * Returns the relative path from one file (e.g. current file) to another file
+ * assuming that both files have the same starting point (e.g. from `/a` to `/b/c` is `./b/c`).
+ *
+ * To indicate a folder instead of a file, the path should end with a slash (e.g. `/a/` to `/b/c/` is `../b/c/`).
+ *
+ * If the referenced file is a package, then we return the package reference (e.g. `@lib/package`).
+ */
+export declare function getRelativePath({ from, to }: {
+    from: string;
+    to: string;
+}): string;

package/dist/utils/path.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POSIX_ROOT = exports.zPosixPath = void 0;
+exports.normalize = normalize;
+exports.join = join;
+exports.fileName = fileName;
+exports.parse = parse;
+exports.contains = contains;
+exports.cd = cd;
+exports.isPackageName = isPackageName;
+exports.getRelativePath = getRelativePath;
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+exports.zPosixPath = zod_1.z.string().brand('PXL.PosixPath');
+const toPosixPath = (input) => exports.zPosixPath.parse(input);
+exports.POSIX_ROOT = normalize('/');
+/**
+ * Normalizes a unix or Windows path to use the unix path separator. Additionally,
+ * it normalizes the path so that every path is considered absolute.
+ */
+function normalize(path) {
+    const unixPath = path.replace(/\\/g, '/');
+    if (/^[A-Za-z]:\//.test(unixPath)) {
+        // NOTE: The RegEx also checks that the path starts with a slash,
+        //      which we don't remove.
+        return toPosixPath(unixPath.slice(2));
+    }
+    if (!unixPath.startsWith('/')) {
+        return toPosixPath(`/${unixPath}`);
+    }
+    return toPosixPath(unixPath);
+}
+/**
+ * Joins two paths together appending the second path to the first.
+ */
+function join(dir, path) {
+    return normalize(node_path_1.default.posix.join(dir, path));
+}
+/**
+ * Returns the file name of the given path.
+ */
+function fileName(path) {
+    const parts = normalize(path).split('/');
+    const lastEntry = parts[parts.length - 1];
+    if (!lastEntry || lastEntry === '') {
+        throw new Error(`Path ${path} does not contain a file name!`);
+    }
+    return lastEntry;
+}
+/**
+ * Parses a given string into a path array.
+ */
+function parse(path) {
+    const parts = normalize(path).split('/');
+    if (parts.length === 0) {
+        return [];
+    }
+    // Remove the first empty string if the path starts with a slash.
+    if (parts[0] === '' || parts[0] === '.') {
+        parts.shift();
+    }
+    const resolved = [];
+    while (parts.length > 0) {
+        // We can safely force unwrap here because we check the length of the array.
+        const part = parts.shift();
+        if (part === '..') {
+            resolved.pop();
+            continue;
+        }
+        if (part === '.') {
+            continue;
+        }
+        if (part === '') {
+            if (parts.length > 0) {
+                console.warn(`Empty subpath in path: ${path}`);
+            }
+            continue;
+        }
+        resolved.push(normalize(part));
+    }
+    return resolved;
+}
+/**
+ * Tells whether a given dir contains a given target. It expects that both paths are absolute and normalized.
+ *
+ * @example
+ *
+ * ```ts
+ * contains('/foo/bar', '/foo/bar/baz') // true
+ * ```
+ */
+function contains(dir, target) {
+    // NOTE: We use the name `dir` because it better portrays the intent of the function, but you can also pass in the filename.
+    const dirParts = parse(dir);
+    const targetParts = parse(target);
+    if (dirParts.length > targetParts.length) {
+        // Parent (i.e. a directory) cannot be inside of the target file or directory.
+        return false;
+    }
+    for (let i = 0; i < dirParts.length; i++) {
+        if (dirParts[i] !== targetParts[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Changes the directory of a given path. If a path is not in the given directory,
+ * it will return an unchanged path.
+ */
+function cd(dir, path) {
+    if (!contains(dir, path)) {
+        return path;
+    }
+    const chunks = parse(path);
+    const dirChunks = parse(dir);
+    for (const _ of dirChunks) {
+        chunks.shift();
+    }
+    return normalize(node_path_1.default.posix.join(...chunks));
+}
+function isPackageName(name) {
+    //check that name does not include any dots, slashes, backslashes, or spaces
+    return !/[./\\\s]/.test(name);
+}
+/**
+ * Returns the relative path from one file (e.g. current file) to another file
+ * assuming that both files have the same starting point (e.g. from `/a` to `/b/c` is `./b/c`).
+ *
+ * To indicate a folder instead of a file, the path should end with a slash (e.g. `/a/` to `/b/c/` is `../b/c/`).
+ *
+ * If the referenced file is a package, then we return the package reference (e.g. `@lib/package`).
+ */
+function getRelativePath({ from, to }) {
+    if (to.startsWith('@') || isPackageName(to)) {
+        return to;
+    }
+    if (from.startsWith('@')) {
+        throw new Error(`Cannot resolve relative path from a package (${from}) to a file (${to})!`);
+    }
+    const fromParts = resolvePath(from);
+    const toParts = resolvePath(to);
+    // We expect that from value references a file of a file in a given folder.
+    // Relative to that file, we need to remove it.
+    fromParts.pop();
+    // Remove common parts.
+    while (fromParts.length > 0 && toParts.length > 0 && fromParts[0] === toParts[0]) {
+        fromParts.shift();
+        toParts.shift();
+    }
+    // Add ../ for each remaining part in fromParts.
+    const relativePath = fromParts
+        .map(() => '..')
+        .concat(toParts)
+        .join('/');
+    if (relativePath.startsWith('.')) {
+        return relativePath;
+    }
+    return `./${relativePath}`;
+}
+/**
+ * Returns a list of folders leading from the root to the referenced file or folder and removes
+ * any positional paths.
+ */
+function resolvePath(path) {
+    const chunks = path.split('/');
+    const resolved = [];
+    while (chunks.length > 0) {
+        const chunk = chunks.shift();
+        if (chunk === '..') {
+            resolved.pop();
+            continue;
+        }
+        if (chunk === '.') {
+            continue;
+        }
+        resolved.push(chunk);
+    }
+    return resolved;
+}

package/dist/utils/prettier-config.d.ts

@@ -0,0 +1,2 @@
+import type { Options } from 'prettier';
+export declare const prettierConfig: Options;

package/dist/utils/prettier-config.js

@@ -0,0 +1,13 @@
+"use strict";
+// IMPORTANT: To ensure consistency between generated code and repo code,
+//            make sure that this file is kept in sync with
+//            `./prettier-config.ts`!
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prettierConfig = void 0;
+exports.prettierConfig = {
+    semi: false,
+    trailingComma: 'all',
+    singleQuote: true,
+    tabWidth: 2,
+    printWidth: 120,
+};

package/dist/utils/prettier.d.ts

@@ -0,0 +1,5 @@
+import { FileContent } from './fs-utils';
+export declare function format({ path, content }: {
+    path: string;
+    content: FileContent;
+}): Promise<FileContent>;