@wpelevator/wp-release 0.15.0 → 0.17.0

package/dist/i18n/compile.js

@@ -0,0 +1,71 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { ValidationError } from "../errors.js";
+import { parseTranslatedPo, compileMo } from "./po.js";
+import { compileScriptTranslations } from "./translation-json.js";
+import { compilePhpTranslations } from "./translation-php.js";
+import { writeI18nOutput, validateI18nDestinations } from "./atomic-output.js";
+/**
+ * Parse/validate every proposed output before independently replacing completed files.
+ * @param input
+ */
+export async function compileTranslations(input) {
+    const sourcePath = resolve(input.sourcePath);
+    if (!sourcePath.endsWith('.po')) {
+        throw new ValidationError('Translation compilation requires an input .po file.');
+    }
+    if ('json' !== input.format && input.scriptMap) {
+        throw new ValidationError('Script mapping only applies to WordPress JSON compilation.');
+    }
+    const catalog = parseTranslatedPo(await readFile(sourcePath), input.domain ?? '');
+    if ('json' === input.format && !input.domain) {
+        throw new ValidationError('WordPress JSON compilation requires an explicit text domain.');
+    }
+    const proposed = 'json' === input.format
+        ? compileScriptTranslations(catalog, input.scriptMap).map((output) => ({
+            outputPath: join(input.outputPath ?? dirname(sourcePath), output.file),
+            source: output.source,
+            bytes: output.bytes,
+        }))
+        : [
+            {
+                outputPath: input.outputPath ??
+                    sourcePath.replace(/\.po$/, 'mo' === input.format ? '.mo' : '.l10n.php'),
+                bytes: 'mo' === input.format
+                    ? compileMo(catalog)
+                    : compilePhpTranslations(catalog),
+            },
+        ];
+    proposed.forEach((output) => {
+        output.outputPath = resolve(output.outputPath);
+    });
+    await validateI18nDestinations(proposed.map((output) => output.outputPath), [sourcePath]);
+    const result = {
+        sourcePath,
+        locale: catalog.locale,
+        messages: catalog.messages.length,
+        outputs: [],
+    };
+    for (const output of proposed) {
+        const previous = await readFile(output.outputPath).catch((error) => {
+            if ('ENOENT' !== error.code) {
+                throw error;
+            }
+            return undefined;
+        });
+        let current = previous?.equals(output.bytes) ?? false;
+        if (!input.check) {
+            await writeI18nOutput(output.outputPath, output.bytes);
+            current = true;
+        }
+        result.outputs.push({
+            outputPath: output.outputPath,
+            ...('source' in output
+                ? { source: output.source }
+                : {}),
+            written: !input.check,
+            current,
+        });
+    }
+    return result;
+}

package/dist/i18n/extraction.d.ts

@@ -0,0 +1,45 @@
+import type { ExtractionResult, SourceReference } from './catalog.ts';
+export interface ParseSourceInput {
+    contents: string;
+    file: string;
+    /** Domain being selected. Omitted domain arguments use WordPress's `default`. */
+    domain: string;
+    allDomains?: boolean;
+    /** Accept unbound canonical JS names in legacy source (default true). */
+    legacyGlobals?: boolean;
+}
+export interface CallSignature {
+    id: number;
+    plural?: number;
+    context?: number;
+    domain: number;
+    parameters: string[];
+}
+export interface LexicalComment {
+    start: number;
+    end: number;
+    value: string;
+}
+export interface TranslationCall extends SourceReference {
+    start: number;
+    /** Start of the nearest containing statement. */
+    statementStart: number;
+    /** Starts of containing expressions, up to the nearest statement. */
+    commentAnchors?: number[];
+    name: string;
+    arguments: Array<string | undefined>;
+    signature: CallSignature;
+}
+/**
+ * Attach each adjacent translators comment only to the first translation call in a statement, before domain filtering.
+ * @param input
+ * @param calls
+ * @param comments
+ */
+export declare function extractCalls(input: ParseSourceInput, calls: TranslationCall[], comments: LexicalComment[]): ExtractionResult;
+/**
+ * Syntax failures are data, never printed by a parser.
+ * @param file
+ * @param error
+ */
+export declare function syntaxFailure(file: string, error: unknown): ExtractionResult;

package/dist/i18n/extraction.js

@@ -0,0 +1,105 @@
+import { getPlaceholders } from "./placeholders.js";
+/**
+ * Attach each adjacent translators comment only to the first translation call in a statement, before domain filtering.
+ * @param input
+ * @param calls
+ * @param comments
+ */
+export function extractCalls(input, calls, comments) {
+    const result = { messages: [], diagnostics: [] };
+    const used = new Set();
+    for (const call of calls.sort((a, b) => a.start - b.start)) {
+        const signature = call.signature;
+        const domainValue = call.arguments[signature.domain];
+        // An omitted domain defaults to WordPress's own domain; an unresolved supplied value doesn't.
+        const domain = call.arguments.length <= signature.domain ? 'default' : domainValue;
+        const reference = {
+            file: call.file,
+            line: call.line,
+            column: call.column,
+        };
+        const adjacent = comments.filter((comment) => (call.commentAnchors ?? [call.start, call.statementStart]).some((anchor) => {
+            let offset = comment.end;
+            let gap = '';
+            for (const next of comments
+                .filter((candidate) => candidate.start >= comment.end &&
+                candidate.end <= anchor)
+                .sort((a, b) => a.start - b.start)) {
+                gap += input.contents.slice(offset, next.start);
+                offset = next.end;
+            }
+            gap += input.contents.slice(offset, anchor);
+            return comment.end <= anchor && /^[\s?:]*$/.test(gap);
+        }));
+        const translatorComments = adjacent.filter((comment) => !used.has(comment.start) &&
+            /translators:/i.test(comment.value));
+        translatorComments.forEach((comment) => used.add(comment.start));
+        if (undefined === domain ||
+            input.allDomains ||
+            input.domain === domain) {
+            const required = [
+                signature.id,
+                signature.plural,
+                signature.context,
+            ].filter((index) => undefined !== index);
+            if (undefined === domain ||
+                required.some((index) => undefined === call.arguments[index])) {
+                result.diagnostics.push({
+                    ...reference,
+                    code: 'dynamic-argument',
+                    severity: 'warning',
+                    message: `${call.name} requires static message IDs, context and domain; use string literals or static concatenation.`,
+                });
+            }
+            else {
+                const message = {
+                    id: call.arguments[signature.id] ?? '',
+                    domain,
+                    ...(undefined !== signature.plural
+                        ? { plural: call.arguments[signature.plural] }
+                        : {}),
+                    ...(undefined !== signature.context
+                        ? { context: call.arguments[signature.context] }
+                        : {}),
+                    translations: [],
+                    flags: [],
+                    references: [reference],
+                    comments: translatorComments.map((comment) => comment.value
+                        .replace(/^\s*(?:\/\*+|\/\/|#)/, '')
+                        .replace(/\*\/\s*$/, '')
+                        .replace(/^\s*\*\s?/gm, '')
+                        .trim()),
+                };
+                if ([message.id, message.plural ?? ''].some((form) => getPlaceholders(form).length)) {
+                    message.flags.push(input.file.endsWith('.php')
+                        ? 'php-format'
+                        : 'js-format');
+                }
+                result.messages.push(message);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Syntax failures are data, never printed by a parser.
+ * @param file
+ * @param error
+ */
+export function syntaxFailure(file, error) {
+    const failure = error;
+    const column = failure.loc?.column ?? failure.columnNumber;
+    return {
+        messages: [],
+        diagnostics: [
+            {
+                code: 'invalid-syntax',
+                severity: 'error',
+                file,
+                message: failure.message ?? String(error),
+                line: failure.loc?.line ?? failure.lineNumber,
+                column: undefined !== column ? column + 1 : undefined,
+            },
+        ],
+    };
+}

package/dist/i18n/files.d.ts

@@ -0,0 +1,7 @@
+import type { I18nOptions } from './options.ts';
+/**
+ * Select source files with package-relative minimatch globs, never distribution rules.
+ * @param root
+ * @param input
+ */
+export declare function discoverI18nFiles(root: string, input?: I18nOptions): Promise<string[]>;

package/dist/i18n/files.js

@@ -0,0 +1,45 @@
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { minimatch } from 'minimatch';
+import { ValidationError } from "../errors.js";
+import { compareText } from "./catalog.js";
+import { resolveI18nOptions } from "./options.js";
+/**
+ * Select source files with package-relative minimatch globs, never distribution rules.
+ * @param root
+ * @param input
+ */
+export async function discoverI18nFiles(root, input = {}) {
+    const options = resolveI18nOptions(input);
+    const includes = options.include ?? [];
+    const excludes = options.exclude ?? [];
+    const matches = (file, patterns) => patterns.some((pattern) => minimatch(file, pattern, {
+        dot: true,
+        nocase: false,
+        nonegate: true,
+    }));
+    const files = [];
+    async function visit(prefix) {
+        const entries = await readdir(join(root, prefix), {
+            withFileTypes: true,
+        });
+        for (const entry of entries.sort((a, b) => compareText(a.name, b.name))) {
+            const file = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isSymbolicLink() &&
+                matches(file, includes) &&
+                !matches(file, excludes)) {
+                throw new ValidationError(`Selected source symlinks are unsupported: ${file}.`);
+            }
+            if (entry.isDirectory() && !matches(`${file}/`, excludes)) {
+                await visit(file);
+            }
+            else if (entry.isFile() &&
+                matches(file, includes) &&
+                !matches(file, excludes)) {
+                files.push(file);
+            }
+        }
+    }
+    await visit('');
+    return files.sort(compareText);
+}

package/dist/i18n/generate.d.ts

@@ -0,0 +1,49 @@
+import type { PackageMeta } from '../package-meta.ts';
+import type { CatalogResult, I18nDiagnostic } from './catalog.ts';
+import type { I18nOptions } from './options.ts';
+export interface ExtractCatalogInput {
+    sourceDir: string;
+    options?: I18nOptions;
+    /** Exact output paths excluded even when include globs select them. */
+    outputPaths?: string[];
+}
+export interface ExtractCatalogResult extends CatalogResult {
+    /** Unique files consulted, including the main metadata file if excluded by source globs. */
+    files: number;
+}
+export interface PackagePotInput extends ExtractCatalogInput {
+    /** Absolute output path (CLI resolves explicit paths against cwd). */
+    outputPath?: string;
+    check?: boolean;
+}
+export interface PackagePotResult {
+    outputPath: string;
+    messages: number;
+    /** Unique files consulted, including the main metadata file if excluded by source globs. */
+    files: number;
+    diagnostics: I18nDiagnostic[];
+    written: boolean;
+    current: boolean;
+}
+/**
+ * Read source files and collect all failures before reporting completion.
+ * @param input
+ */
+export declare function extractCatalog(input: ExtractCatalogInput): Promise<ExtractCatalogResult>;
+/**
+ * Resolve a package-relative destination, treating /languages like WordPress Domain Path.
+ * @param sourceDir
+ * @param meta
+ * @param options
+ */
+export declare function resolvePotPath(sourceDir: string, meta: PackageMeta | null, options?: I18nOptions): string;
+/**
+ * Validate destinations before any writes, including collisions through existing symlinks.
+ * @param paths
+ */
+export declare function validatePotDestinations(paths: string[]): Promise<void>;
+/**
+ * Each package replaces its output atomically only after successful extraction and serialization.
+ * @param input
+ */
+export declare function generatePackagePot(input: PackagePotInput): Promise<PackagePotResult>;

package/dist/i18n/generate.js

@@ -0,0 +1,240 @@
+import { readFile } from 'node:fs/promises';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { ValidationError } from "../errors.js";
+import { readPackageMeta } from "../package-meta.js";
+import { aggregateCatalog, compareText, hasFatalDiagnostics, } from "./catalog.js";
+import { discoverI18nFiles } from "./files.js";
+import { parsePhpTranslations } from "./php.js";
+import { parseJavascriptTranslations } from "./javascript.js";
+import { extractHeaderTranslations, parseMetadataTranslations, } from "./metadata.js";
+import { mergeI18nHeaders, resolveI18nOptions } from "./options.js";
+import { serializePot } from "./pot.js";
+import { writeI18nOutput, validateI18nDestinations, validateI18nContainment, } from "./atomic-output.js";
+/**
+ * Group sources by type: PHP, then JavaScript, then block.json, then other WordPress JSON.
+ *
+ * @param file Package-relative source file.
+ * @return Sort rank of the file.
+ */
+function sourceRank(file) {
+    if (file.endsWith('.php')) {
+        return 0;
+    }
+    if (!file.endsWith('.json')) {
+        return 1;
+    }
+    return file.endsWith('/block.json') || 'block.json' === file ? 2 : 3;
+}
+/**
+ * Order the messages of one file by their position, keeping the parser order for equal positions.
+ *
+ * @param messages Messages extracted from one file.
+ * @return Messages in source order.
+ */
+function sortBySourcePosition(messages) {
+    const position = (message) => message.references[0];
+    return [...messages].sort((a, b) => (position(a)?.line ?? 0) - (position(b)?.line ?? 0) ||
+        (position(a)?.column ?? 0) - (position(b)?.column ?? 0));
+}
+/**
+ * Read source files and collect all failures before reporting completion.
+ * @param input
+ */
+export async function extractCatalog(input) {
+    const sourceDir = resolve(input.sourceDir);
+    const options = resolveI18nOptions(input.options);
+    const diagnostics = [];
+    let meta = null;
+    try {
+        meta = await readPackageMeta({
+            dir: sourceDir,
+            slug: basename(sourceDir),
+        });
+    }
+    catch (error) {
+        diagnostics.push({
+            file: '.',
+            code: 'unreadable-file',
+            severity: 'error',
+            message: String(error),
+        });
+    }
+    const domain = options.domain ??
+        meta?.headers['Text Domain'] ??
+        basename(sourceDir);
+    const excluded = new Set((input.outputPaths ?? []).map((file) => resolve(file)));
+    let files = [];
+    try {
+        files = (await discoverI18nFiles(sourceDir, options))
+            .filter((file) => !excluded.has(resolve(sourceDir, file)))
+            .sort((a, b) => sourceRank(a) - sourceRank(b) || compareText(a, b));
+    }
+    catch (error) {
+        diagnostics.push({
+            file: '.',
+            code: 'source-discovery-failed',
+            severity: 'error',
+            message: String(error),
+        });
+    }
+    const messages = [];
+    if (meta) {
+        try {
+            messages.push(...extractHeaderTranslations(meta, await readFile(join(sourceDir, meta.mainFile), 'utf8'), domain));
+        }
+        catch (error) {
+            diagnostics.push({
+                file: meta.mainFile,
+                code: 'unreadable-file',
+                severity: 'error',
+                message: String(error),
+            });
+        }
+    }
+    for (const file of files) {
+        try {
+            const contents = await readFile(join(sourceDir, file), 'utf8');
+            const parseInput = {
+                contents,
+                file,
+                domain,
+                allDomains: options.allDomains,
+                legacyGlobals: options.legacyGlobals,
+            };
+            let parsed;
+            if (file.endsWith('.php')) {
+                parsed = parsePhpTranslations(parseInput);
+            }
+            else if (file.endsWith('.json')) {
+                parsed = parseMetadataTranslations(parseInput, file.endsWith('/block.json') || 'block.json' === file
+                    ? 'block'
+                    : 'theme');
+            }
+            else {
+                parsed = parseJavascriptTranslations(parseInput);
+            }
+            messages.push(...sortBySourcePosition(parsed.messages));
+            diagnostics.push(...parsed.diagnostics);
+        }
+        catch (error) {
+            diagnostics.push({
+                file,
+                code: 'unreadable-file',
+                severity: 'error',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const result = aggregateCatalog(messages, domain, mergeI18nHeaders({
+        'Project-Id-Version': `${meta?.headers['Plugin Name'] ??
+            meta?.headers['Theme Name'] ??
+            domain}${meta?.version ? ` ${meta.version}` : ''}`,
+    }, options.headers), options.allDomains);
+    return {
+        ...result,
+        diagnostics: [...diagnostics, ...result.diagnostics],
+        files: files.length +
+            (meta && !files.includes(meta.mainFile) ? 1 : 0),
+    };
+}
+/**
+ * Resolve a package-relative destination, treating /languages like WordPress Domain Path.
+ * @param sourceDir
+ * @param meta
+ * @param options
+ */
+export function resolvePotPath(sourceDir, meta, options = {}) {
+    const domain = options.domain ??
+        meta?.headers['Text Domain'] ??
+        basename(sourceDir);
+    if (!domain ||
+        /[\\/\0:*?"<>|]/.test(domain) ||
+        ['.', '..'].includes(domain)) {
+        throw new ValidationError('The text domain must be a safe filename component.');
+    }
+    const destination = (options.destination ??
+        meta?.headers['Domain Path'] ??
+        'languages').replace(/^\/+/, '');
+    const directory = resolve(sourceDir, destination);
+    const path = relative(resolve(sourceDir), directory);
+    if (isAbsolute(path) ||
+        '..' === path ||
+        path.startsWith('../') ||
+        /[\\\0:]/.test(destination)) {
+        throw new ValidationError('The i18n destination must stay inside the package directory.');
+    }
+    return join(directory, `${domain}.pot`);
+}
+/**
+ * Validate destinations before any writes, including collisions through existing symlinks.
+ * @param paths
+ */
+export async function validatePotDestinations(paths) {
+    if (paths.some((file) => !file.endsWith('.pot'))) {
+        throw new ValidationError('POT outputs must use the .pot extension.');
+    }
+    await validateI18nDestinations(paths);
+}
+/**
+ * Each package replaces its output atomically only after successful extraction and serialization.
+ * @param input
+ */
+export async function generatePackagePot(input) {
+    const sourceDir = resolve(input.sourceDir);
+    const options = resolveI18nOptions(input.options);
+    const meta = await readPackageMeta({
+        dir: sourceDir,
+        slug: basename(sourceDir),
+    });
+    const outputPath = resolve(input.outputPath ?? resolvePotPath(sourceDir, meta, options));
+    await validatePotDestinations([outputPath]);
+    if (!input.outputPath) {
+        await validateI18nContainment(sourceDir, outputPath);
+    }
+    const extracted = await extractCatalog({
+        ...input,
+        outputPaths: [outputPath, ...(input.outputPaths ?? [])],
+    });
+    const result = {
+        outputPath,
+        messages: extracted.catalog.messages.length,
+        files: extracted.files,
+        diagnostics: extracted.diagnostics,
+        written: false,
+        current: false,
+    };
+    if (!hasFatalDiagnostics(result.diagnostics, options.strict)) {
+        try {
+            const bytes = serializePot(extracted.catalog, options);
+            const previous = await readFile(outputPath).catch((error) => {
+                if ('ENOENT' !== error.code) {
+                    throw error;
+                }
+                return undefined;
+            });
+            result.current = previous?.equals(bytes) ?? false;
+            if (!input.check) {
+                await writeI18nOutput(outputPath, bytes);
+                result.written = true;
+                result.current = true;
+            }
+            if (input.check && !result.current) {
+                result.diagnostics.push({
+                    file: outputPath,
+                    code: 'stale-pot',
+                    severity: 'error',
+                    message: 'POT is missing or stale; regenerate it with i18n-pot.',
+                });
+            }
+        }
+        catch (error) {
+            result.diagnostics.push({
+                file: outputPath,
+                code: 'output-failed',
+                severity: 'error',
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return result;
+}

package/dist/i18n/javascript.d.ts

@@ -0,0 +1,7 @@
+import type { ParseSourceInput } from './extraction.ts';
+import type { ExtractionResult } from './catalog.ts';
+/**
+ * Parse JS/JSX/TS/TSX with lexical scope resolution and untouched source positions.
+ * @param input
+ */
+export declare function parseJavascriptTranslations(input: ParseSourceInput): ExtractionResult;