@hominis/fireforge 0.9.0

package/dist/src/core/patch-export.js

@@ -0,0 +1,314 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText, removeFile, writeText } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+import { PATCH_CATEGORIES } from '../utils/validation.js';
+import { discoverPatches, isNewFilePatch, withPatchDirectoryLock } from './patch-apply.js';
+import { addPatchToManifest, loadPatchesManifest, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest.js';
+/**
+ * Gets the next patch number for a new patch.
+ * @param patchesDir - Path to the patches directory
+ * @returns Next patch number (e.g., "005" for 4 existing patches)
+ */
+export async function getNextPatchNumber(patchesDir) {
+    const patches = await discoverPatches(patchesDir);
+    if (patches.length === 0) {
+        return '001';
+    }
+    const finitePatches = patches.filter((p) => Number.isFinite(p.order));
+    if (finitePatches.length === 0)
+        return '001';
+    const maxOrder = finitePatches.reduce((max, p) => Math.max(max, p.order), 0);
+    const nextNumber = maxOrder + 1;
+    return String(nextNumber).padStart(Math.max(3, String(nextNumber).length), '0');
+}
+/**
+ * Sanitizes a string for use in a filename.
+ */
+function sanitizeName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+/**
+ * Generates the next patch filename with category.
+ * @param patchesDir - Path to the patches directory
+ * @param category - Patch category
+ * @param name - Human-readable name
+ * @returns Filename like "001-ui-sidebar.patch"
+ */
+export async function getNextPatchFilename(patchesDir, category, name) {
+    const patchNumber = await getNextPatchNumber(patchesDir);
+    const sanitizedName = sanitizeName(name);
+    return `${patchNumber}-${category}-${sanitizedName}.patch`;
+}
+/**
+ * Commits a freshly generated patch file and manifest update under an exclusive
+ * patch directory lock so concurrent exports cannot allocate the same number.
+ */
+export async function commitExportedPatch(input) {
+    return withPatchDirectoryLock(input.patchesDir, async () => {
+        const patchFilename = await getNextPatchFilename(input.patchesDir, input.category, input.name);
+        const patchPath = join(input.patchesDir, patchFilename);
+        const metadata = {
+            filename: patchFilename,
+            order: parseInt(patchFilename.split('-')[0] ?? '0', 10),
+            category: input.category,
+            name: input.name,
+            description: input.description,
+            createdAt: new Date().toISOString(),
+            sourceEsrVersion: input.sourceEsrVersion,
+            filesAffected: input.filesAffected,
+        };
+        const superseded = await findAllPatchesForFiles(input.patchesDir, input.filesAffected, patchFilename);
+        const supersededFilenames = superseded.map((patch) => patch.filename);
+        const originalManifest = await loadPatchesManifest(input.patchesDir);
+        const originalPatchContent = (await pathExists(patchPath)) ? await readText(patchPath) : null;
+        const removedPatchContents = new Map();
+        for (const oldPatch of superseded) {
+            if (await pathExists(oldPatch.path)) {
+                removedPatchContents.set(oldPatch.path, await readText(oldPatch.path));
+            }
+        }
+        try {
+            await writeText(patchPath, input.diff);
+            await addPatchToManifest(input.patchesDir, metadata, supersededFilenames);
+            for (const oldPatch of superseded) {
+                await removeFile(oldPatch.path);
+            }
+        }
+        catch (error) {
+            // Best-effort rollback: wrap each operation so a secondary failure
+            // never masks the original failure.
+            try {
+                if (originalPatchContent === null) {
+                    await removeFile(patchPath);
+                }
+                else {
+                    await writeText(patchPath, originalPatchContent);
+                }
+            }
+            catch (error) {
+                warn(`Rollback warning: could not restore patch file: ${toError(error).message}`);
+            }
+            for (const [oldPatchPath, oldPatchContent] of removedPatchContents) {
+                try {
+                    await writeText(oldPatchPath, oldPatchContent);
+                }
+                catch (error) {
+                    warn(`Rollback warning: could not restore ${oldPatchPath}: ${toError(error).message}`);
+                }
+            }
+            try {
+                if (originalManifest) {
+                    await savePatchesManifest(input.patchesDir, originalManifest);
+                }
+                else {
+                    await removeFile(join(input.patchesDir, PATCHES_MANIFEST));
+                }
+            }
+            catch (error) {
+                warn(`Rollback warning: could not restore manifest: ${toError(error).message}`);
+            }
+            throw error;
+        }
+        return {
+            patchFilename,
+            metadata,
+            superseded,
+        };
+    });
+}
+/**
+ * Parses a patch filename to extract order, category, and name.
+ * Supports both new format (001-category-name.patch) and legacy (001-name.patch).
+ */
+export function parseFilename(filename) {
+    // New format: 001-ui-sidebar.patch
+    const newMatch = /^(\d+)-([a-z]+)-(.+)\.patch$/.exec(filename);
+    if (newMatch?.[1] && newMatch[2] && newMatch[3]) {
+        const orderStr = newMatch[1];
+        const category = newMatch[2];
+        const name = newMatch[3];
+        if (PATCH_CATEGORIES.includes(category)) {
+            return {
+                order: parseInt(orderStr, 10),
+                category: category,
+                name,
+            };
+        }
+    }
+    // Legacy format: 001-name.patch
+    const legacyMatch = /^(\d+)-(.+)\.patch$/.exec(filename);
+    if (legacyMatch?.[1] && legacyMatch[2]) {
+        return {
+            order: parseInt(legacyMatch[1], 10),
+            category: null,
+            name: legacyMatch[2],
+        };
+    }
+    return { order: Infinity, category: null, name: filename };
+}
+/**
+ * Finds an existing patch that contains the specified file.
+ * Returns the most recent (highest order) patch if multiple exist.
+ * @param patchesDir - Path to the patches directory
+ * @param filePath - File path to search for
+ * @returns The patch info and metadata, or null if not found
+ */
+export async function findExistingPatchForFile(patchesDir, filePath) {
+    const { findPatchesAffectingFile } = await import('./patch-manifest.js');
+    const affectingPatches = await findPatchesAffectingFile(patchesDir, filePath);
+    if (affectingPatches.length === 0) {
+        return null;
+    }
+    // Return the most recent (highest order) patch
+    return affectingPatches[affectingPatches.length - 1] ?? null;
+}
+/**
+ * Updates the content of a patch file.
+ * @param patchPath - Path to the patch file
+ * @param newContent - New patch content
+ */
+export async function updatePatch(patchPath, newContent) {
+    await writeText(patchPath, newContent);
+}
+/**
+ * Updates metadata for a patch in the manifest.
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename
+ * @param updates - Partial metadata updates
+ */
+export async function updatePatchMetadata(patchesDir, filename, updates) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const manifest = await loadPatchesManifest(patchesDir);
+        if (!manifest)
+            return;
+        const patchIndex = manifest.patches.findIndex((p) => p.filename === filename);
+        if (patchIndex === -1)
+            return;
+        const existingPatch = manifest.patches[patchIndex];
+        if (existingPatch) {
+            manifest.patches[patchIndex] = { ...existingPatch, ...updates };
+            await savePatchesManifest(patchesDir, manifest);
+        }
+    });
+}
+/**
+ * Finds patches that are completely superseded by newer patches.
+ * A patch is superseded if all its affected files are covered by newer patches.
+ * @param patchesDir - Path to the patches directory
+ * @param newPatchFiles - Files affected by the new patch
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Superseded patches
+ */
+export async function findSupersededPatches(patchesDir, newPatchFiles, excludeFilename) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const superseded = [];
+    for (const metadata of manifest.patches) {
+        // Skip the new patch itself
+        if (excludeFilename && metadata.filename === excludeFilename)
+            continue;
+        // Check if this is a "new file" patch (single file, created from scratch)
+        // A patch is superseded if it's a single-file new-file patch and
+        // the new patch covers the same file
+        if (metadata.filesAffected.length === 1) {
+            const affectedFile = metadata.filesAffected[0];
+            if (affectedFile && newPatchFiles.includes(affectedFile)) {
+                const patch = patches.find((p) => p.filename === metadata.filename);
+                if (patch && (await isNewFilePatch(patch.path))) {
+                    superseded.push(patch);
+                }
+            }
+        }
+    }
+    return superseded;
+}
+/**
+ * Deletes a patch file and removes it from the manifest.
+ * @param patchesDir - Path to the patches directory
+ * @param filename - Patch filename to delete
+ */
+export async function deletePatch(patchesDir, filename) {
+    await withPatchDirectoryLock(patchesDir, async () => {
+        const patchPath = join(patchesDir, filename);
+        const manifest = await loadPatchesManifest(patchesDir);
+        const updatedManifest = manifest
+            ? {
+                ...manifest,
+                patches: manifest.patches.filter((patch) => patch.filename !== filename),
+            }
+            : null;
+        // Update manifest first so interrupted deletions leave an explicit repairable
+        // extra patch file rather than silently dropping metadata for an absent file.
+        if (updatedManifest) {
+            await savePatchesManifest(patchesDir, updatedManifest);
+        }
+        if (!(await pathExists(patchPath))) {
+            return;
+        }
+        try {
+            await unlink(patchPath);
+        }
+        catch (error) {
+            if (manifest) {
+                try {
+                    await savePatchesManifest(patchesDir, manifest);
+                }
+                catch (error) {
+                    warn(`Failed to restore manifest after patch deletion error for "${filename}": ${toError(error).message}`);
+                }
+            }
+            throw error;
+        }
+    });
+}
+/**
+ * Checks whether a patch is fully covered by a new export.
+ * A patch is fully covered when every file it affects is present in the new export.
+ * @param patchFiles - Files affected by the existing patch
+ * @param targetFiles - Files affected by the new export
+ * @returns True when the existing patch is fully covered
+ */
+export function isPatchFullyCovered(patchFiles, targetFiles) {
+    if (patchFiles.length === 0) {
+        return false;
+    }
+    const targetFileSet = new Set(targetFiles);
+    return patchFiles.every((file) => targetFileSet.has(file));
+}
+/**
+ * Finds patches whose filesAffected entries are fully covered by the specified files.
+ * Used for complete supersession when exporting full-file patches.
+ * @param patchesDir - Path to the patches directory
+ * @param targetFiles - Files affected by the new export
+ * @param excludeFilename - Filename to exclude from results (the new patch itself)
+ * @returns Patches that are fully covered by the new export
+ */
+export async function findAllPatchesForFiles(patchesDir, targetFiles, excludeFilename) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return [];
+    const patches = await discoverPatches(patchesDir);
+    const superseded = [];
+    for (const metadata of manifest.patches) {
+        // Skip the new patch itself
+        if (excludeFilename && metadata.filename === excludeFilename)
+            continue;
+        if (isPatchFullyCovered(metadata.filesAffected, targetFiles)) {
+            const patch = patches.find((p) => p.filename === metadata.filename);
+            if (patch) {
+                superseded.push(patch);
+            }
+        }
+    }
+    return superseded;
+}
+//# sourceMappingURL=patch-export.js.map

package/dist/src/core/patch-files.d.ts

@@ -0,0 +1,11 @@
+import type { PatchInfo } from '../types/commands/index.js';
+/** Discovers patch files in a directory and returns them in apply order. */
+export declare function discoverPatches(patchesDir: string): Promise<PatchInfo[]>;
+/** Counts the patch files currently present in a patch directory. */
+export declare function countPatches(patchesDir: string): Promise<number>;
+/** Checks whether a patch creates a new file rather than modifying an existing one. */
+export declare function isNewFilePatch(patchPath: string): Promise<boolean>;
+/** Returns the first target file path referenced by a patch, if any. */
+export declare function getTargetFileFromPatch(patchPath: string): Promise<string | null>;
+/** Returns all target file paths referenced by a multi-file patch. */
+export declare function getAllTargetFilesFromPatch(patchPath: string): Promise<string[]>;

package/dist/src/core/patch-files.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { extractOrder } from './patch-parse.js';
+/** Discovers patch files in a directory and returns them in apply order. */
+export async function discoverPatches(patchesDir) {
+    if (!(await pathExists(patchesDir))) {
+        return [];
+    }
+    const entries = await readdir(patchesDir, { withFileTypes: true });
+    const patches = entries
+        .filter((entry) => entry.isFile() && extname(entry.name) === '.patch')
+        .map((entry) => ({
+        path: join(patchesDir, entry.name),
+        filename: entry.name,
+        order: extractOrder(entry.name),
+    }));
+    patches.sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    return patches;
+}
+/** Counts the patch files currently present in a patch directory. */
+export async function countPatches(patchesDir) {
+    const patches = await discoverPatches(patchesDir);
+    return patches.length;
+}
+/** Checks whether a patch creates a new file rather than modifying an existing one. */
+export async function isNewFilePatch(patchPath) {
+    const content = await readText(patchPath);
+    return content.includes('new file mode') && content.includes('--- /dev/null');
+}
+/** Returns the first target file path referenced by a patch, if any. */
+export async function getTargetFileFromPatch(patchPath) {
+    const content = await readText(patchPath);
+    const match = /^\+\+\+ b\/(.+)$/m.exec(content);
+    return match?.[1] ?? null;
+}
+/** Returns all target file paths referenced by a multi-file patch. */
+export async function getAllTargetFilesFromPatch(patchPath) {
+    const content = await readText(patchPath);
+    const files = [];
+    const regex = /^\+\+\+ b\/(.+)$/gm;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        if (match[1]) {
+            files.push(match[1]);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=patch-files.js.map

package/dist/src/core/patch-lint.d.ts

@@ -0,0 +1,72 @@
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type CommentStyle } from './license-headers.js';
+/**
+ * Detects comment style from file extension for license header checks.
+ */
+export declare function commentStyleForFile(file: string): CommentStyle | null;
+/**
+ * Extracts new-file paths from a unified diff by scanning for `new file mode` markers.
+ */
+export declare function detectNewFilesInDiff(diffContent: string): Set<string>;
+/**
+ * Lints patched CSS files for raw color values and non-tokenized custom properties.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @returns Array of lint issues found
+ */
+export declare function lintPatchedCss(repoDir: string, affectedFiles: string[]): Promise<PatchLintIssue[]>;
+/**
+ * Checks new files for required license headers.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param newFiles - New file paths (relative to repoDir)
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export declare function lintNewFileHeaders(repoDir: string, newFiles: string[], config: FireForgeConfig): Promise<PatchLintIssue[]>;
+/**
+ * Lints patched JS/MJS files for import conventions, file size, JSDoc, and
+ * observer topic naming.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param affectedFiles - File paths (relative to repoDir)
+ * @param newFiles - Set of files that are newly created in this patch
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export declare function lintPatchedJs(repoDir: string, affectedFiles: string[], newFiles: Set<string>, config: FireForgeConfig): Promise<PatchLintIssue[]>;
+/**
+ * Checks that modifications to existing (non-new) JS/MJS files include at
+ * least one `// BINARYNAME:` comment in the added lines.
+ *
+ * @param diffContent - Raw unified diff string
+ * @param config - Project configuration
+ * @returns Array of lint issues
+ */
+export declare function lintModificationComments(diffContent: string, config: FireForgeConfig): PatchLintIssue[];
+/**
+ * Checks patch size and emits advisory warnings.
+ */
+export declare function lintPatchSize(filesAffected: string[], lineCount: number): PatchLintIssue[];
+/**
+ * Checks that modified (non-new) files with a supported extension still
+ * start with a recognized license header.
+ *
+ * @param repoDir - Engine root directory
+ * @param affectedFiles - All files affected by the patch
+ * @param newFiles - Set of newly created files (excluded from this check)
+ * @returns Warning-level lint issues for files missing any recognized header
+ */
+export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles: string[], newFiles: Set<string>): Promise<PatchLintIssue[]>;
+/**
+ * Runs all patch lint checks and returns combined issues.
+ *
+ * @param repoDir - Absolute path to the engine directory
+ * @param affectedFiles - File paths (relative to repoDir) affected by the patch
+ * @param diffContent - Raw unified diff string
+ * @param config - Project configuration
+ * @returns Array of all lint issues found
+ */
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig): Promise<PatchLintIssue[]>;