@wpelevator/wp-release 0.16.0 → 0.17.0

package/dist/i18n/atomic-output.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve missing destinations through their existing ancestors, including directory symlinks.
+ * @param file
+ */
+export declare function canonicalI18nPath(file: string): Promise<string>;
+/**
+ * Validate a complete output set before writes, with optional forbidden source paths.
+ * @param paths
+ * @param sources
+ */
+export declare function validateI18nDestinations(paths: string[], sources?: string[]): Promise<void>;
+/**
+ * Configured package-relative destinations must remain contained through symlink ancestors.
+ * @param root
+ * @param file
+ */
+export declare function validateI18nContainment(root: string, file: string): Promise<void>;
+/**
+ * Stage bytes beside the target, then replace it; failed writes preserve previous output.
+ * @param file
+ * @param bytes
+ */
+export declare function writeI18nOutput(file: string, bytes: Buffer): Promise<void>;

package/dist/i18n/atomic-output.js

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, realpath, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { ValidationError } from "../errors.js";
+/**
+ * Resolve missing destinations through their existing ancestors, including directory symlinks.
+ * @param file
+ */
+export async function canonicalI18nPath(file) {
+    let ancestor = resolve(file);
+    const missing = [];
+    let canonical;
+    while (!canonical) {
+        try {
+            canonical = await realpath(ancestor);
+        }
+        catch (error) {
+            if ('ENOENT' !== error.code) {
+                throw error;
+            }
+            missing.unshift(basename(ancestor));
+            ancestor = dirname(ancestor);
+        }
+    }
+    if (missing.length && !(await stat(ancestor)).isDirectory()) {
+        throw new ValidationError(`Output ancestor is not a directory: ${ancestor}.`);
+    }
+    return resolve(canonical, ...missing);
+}
+/**
+ * Validate a complete output set before writes, with optional forbidden source paths.
+ * @param paths
+ * @param sources
+ */
+export async function validateI18nDestinations(paths, sources = []) {
+    const seen = new Set();
+    const comparisonKey = (path) => ['darwin', 'win32'].includes(process.platform)
+        ? path.toLowerCase()
+        : path;
+    const forbidden = new Set(await Promise.all(sources.map(async (source) => comparisonKey(await canonicalI18nPath(source)))));
+    for (const file of paths) {
+        const canonical = await canonicalI18nPath(file);
+        const key = comparisonKey(canonical);
+        if (seen.has(key) || forbidden.has(key)) {
+            throw new ValidationError(`Output collision or attempted source overwrite: ${file}.`);
+        }
+        seen.add(key);
+        const exists = await stat(canonical).catch((error) => {
+            if ('ENOENT' !== error.code) {
+                throw error;
+            }
+            return undefined;
+        });
+        if (exists && !exists.isFile()) {
+            throw new ValidationError(`Output is not a file: ${file}.`);
+        }
+    }
+}
+/**
+ * Configured package-relative destinations must remain contained through symlink ancestors.
+ * @param root
+ * @param file
+ */
+export async function validateI18nContainment(root, file) {
+    const parent = await canonicalI18nPath(root);
+    const output = await canonicalI18nPath(file);
+    const path = relative(parent, output);
+    if (isAbsolute(path) ||
+        '..' === path ||
+        path.startsWith('../') ||
+        path.startsWith('..\\')) {
+        throw new ValidationError(`The i18n destination must stay inside the package directory: ${file}.`);
+    }
+}
+/**
+ * Stage bytes beside the target, then replace it; failed writes preserve previous output.
+ * @param file
+ * @param bytes
+ */
+export async function writeI18nOutput(file, bytes) {
+    await mkdir(dirname(file), { recursive: true });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, bytes, { flag: 'wx' });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}

package/dist/i18n/audit.d.ts

@@ -0,0 +1,7 @@
+import type { Catalog, I18nDiagnostic } from './catalog.ts';
+/**
+ * Read-only findings. Suppression applies to audit rules, never extraction failures.
+ * @param catalog
+ * @param suppress
+ */
+export declare function auditCatalog(catalog: Catalog, suppress?: string[]): I18nDiagnostic[];

package/dist/i18n/audit.js

@@ -0,0 +1,69 @@
+import { getPlaceholders } from "./placeholders.js";
+function signature(values) {
+    return values
+        .map((value, index) => `${value.position ?? index + 1}:${value.type}`)
+        .sort()
+        .join(',');
+}
+/**
+ * Read-only findings. Suppression applies to audit rules, never extraction failures.
+ * @param catalog
+ * @param suppress
+ */
+export function auditCatalog(catalog, suppress = []) {
+    const diagnostics = [];
+    for (const message of catalog.messages) {
+        const forms = [
+            message.id,
+            ...(undefined !== message.plural ? [message.plural] : []),
+        ];
+        const tokens = forms.map(getPlaceholders);
+        const codes = [];
+        if (tokens.some((values) => values.length) &&
+            !message.comments.some((comment) => /translators:/i.test(comment))) {
+            codes.push([
+                'placeholder-comment',
+                'Add a translators: comment explaining the placeholders.',
+            ]);
+        }
+        if (tokens.some((values) => values.length > 1 &&
+            values.some((value) => !value.position))) {
+            codes.push([
+                'unordered-placeholders',
+                'Use positional placeholders when a message contains multiple substitutions.',
+            ]);
+        }
+        if (tokens.length > 1 &&
+            signature(tokens[0] ?? []) !== signature(tokens[1] ?? [])) {
+            codes.push([
+                'plural-placeholders',
+                'Singular and plural placeholders must have compatible positions and types.',
+            ]);
+        }
+        if (forms.some((form) => !form.trim() ||
+            !form
+                .replace(/%%|%(?:\d+\$)?[-+ 0#]*(?:'[^\r\n])?\d*(?:\.\d+)?[bcdeEfFgGosuxX]/g, '')
+                .trim())) {
+            codes.push([
+                'empty-message',
+                'Avoid empty or placeholder-only translation messages.',
+            ]);
+        }
+        if (message.comments.filter((comment) => /translators:/i.test(comment)).length > 1) {
+            codes.push([
+                'conflicting-comments',
+                'Review different translator comments attached to the same message.',
+            ]);
+        }
+        for (const [code, description] of codes.filter(([findingCode]) => !suppress.includes(findingCode))) {
+            diagnostics.push({
+                file: '',
+                ...message.references[0],
+                code,
+                severity: 'warning',
+                message: `${description} Message: ${JSON.stringify(message.id)}`,
+            });
+        }
+    }
+    return diagnostics;
+}

package/dist/i18n/catalog.d.ts

@@ -0,0 +1,54 @@
+import type { I18nHeaders } from './options.ts';
+/** A location relative to the extraction root, with one-based line/column. */
+export interface SourceReference {
+    file: string;
+    line?: number;
+    column?: number;
+}
+export interface I18nDiagnostic extends SourceReference {
+    code: string;
+    severity: 'error' | 'warning';
+    message: string;
+}
+/** The shared gettext model; parser and serializer dependencies stay at the edges. */
+export interface CatalogMessage {
+    id: string;
+    plural?: string;
+    context?: string;
+    translations: string[];
+    comments: string[];
+    flags: string[];
+    references: SourceReference[];
+}
+export interface ExtractedMessage extends CatalogMessage {
+    domain: string;
+}
+export interface ExtractionResult {
+    messages: ExtractedMessage[];
+    diagnostics: I18nDiagnostic[];
+}
+export interface Catalog {
+    domain: string;
+    /** Header overrides; `false` removes a default header. */
+    headers: I18nHeaders;
+    messages: CatalogMessage[];
+}
+export interface CatalogResult {
+    catalog: Catalog;
+    diagnostics: I18nDiagnostic[];
+}
+/**
+ * Merge a selected domain in extraction order, diagnosing incompatible plural definitions.
+ * @param extracted
+ * @param domain
+ * @param headers
+ * @param allDomains
+ */
+export declare function aggregateCatalog(extracted: ExtractedMessage[], domain: string, headers?: I18nHeaders, allDomains?: boolean): CatalogResult;
+/**
+ * Locale-independent ordering, stable on every supported platform.
+ * @param a
+ * @param b
+ */
+export declare function compareText(a: string, b: string): number;
+export declare function hasFatalDiagnostics(diagnostics: I18nDiagnostic[], strict?: boolean): boolean;

package/dist/i18n/catalog.js

@@ -0,0 +1,86 @@
+/**
+ * Merge a selected domain in extraction order, diagnosing incompatible plural definitions.
+ * @param extracted
+ * @param domain
+ * @param headers
+ * @param allDomains
+ */
+export function aggregateCatalog(extracted, domain, headers = {}, allDomains = false) {
+    const entries = new Map();
+    const diagnostics = [];
+    for (const message of extracted.filter((entry) => allDomains || entry.domain === domain)) {
+        if (!message.id ||
+            /[\0\u0004]/.test(message.id) ||
+            /[\0\u0004]/.test(message.context ?? '')) {
+            diagnostics.push({
+                file: '',
+                ...message.references[0],
+                code: 'catalog-invalid-id',
+                severity: 'error',
+                message: 'Message IDs must be non-empty and must not contain reserved gettext separators.',
+            });
+        }
+        const key = JSON.stringify([message.context ?? '', message.id]);
+        const previous = entries.get(key);
+        if (previous) {
+            if (previous.plural !== message.plural) {
+                diagnostics.push({
+                    code: 'catalog-plural-conflict',
+                    severity: 'error',
+                    message: `Conflicting plurals for ${JSON.stringify(message.id)}.`,
+                    file: '',
+                    ...message.references[0],
+                });
+            }
+            previous.references.push(...message.references);
+            previous.comments.push(...message.comments);
+            previous.flags.push(...message.flags);
+        }
+        else {
+            entries.set(key, {
+                id: message.id,
+                ...(undefined !== message.plural
+                    ? { plural: message.plural }
+                    : {}),
+                ...(undefined !== message.context
+                    ? { context: message.context }
+                    : {}),
+                translations: [...message.translations],
+                comments: [...message.comments],
+                flags: [...message.flags],
+                references: [...message.references],
+            });
+        }
+    }
+    // Extraction order keeps related strings together and gives translators their context.
+    const messages = [...entries.values()];
+    for (const message of messages) {
+        message.comments = [...new Set(message.comments)];
+        message.flags = [...new Set(message.flags)].sort(compareText);
+        const references = message.references.map((reference) => ({
+            ...reference,
+            file: reference.file.replaceAll('\\', '/'),
+        }));
+        message.references = [
+            ...new Map(references.map((reference) => [
+                JSON.stringify(reference),
+                reference,
+            ])).values(),
+        ];
+    }
+    return {
+        catalog: { domain, headers: { ...headers }, messages },
+        diagnostics,
+    };
+}
+/**
+ * Locale-independent ordering, stable on every supported platform.
+ * @param a
+ * @param b
+ */
+export function compareText(a, b) {
+    return a < b ? -1 : Number(a > b);
+}
+export function hasFatalDiagnostics(diagnostics, strict = false) {
+    return diagnostics.some((diagnostic) => 'error' === diagnostic.severity || strict);
+}

package/dist/i18n/compile.d.ts

@@ -0,0 +1,27 @@
+import type { ScriptTranslationMap } from './translation-json.ts';
+export interface CompileTranslationsInput {
+    /** Absolute input PO path. */
+    sourcePath: string;
+    format: 'mo' | 'json' | 'php';
+    /** File for MO/PHP, directory for JSON; absolute when supplied. */
+    outputPath?: string;
+    domain?: string;
+    scriptMap?: ScriptTranslationMap;
+    check?: boolean;
+}
+export interface CompileTranslationsResult {
+    sourcePath: string;
+    locale: string;
+    messages: number;
+    outputs: Array<{
+        outputPath: string;
+        source?: string;
+        written: boolean;
+        current: boolean;
+    }>;
+}
+/**
+ * Parse/validate every proposed output before independently replacing completed files.
+ * @param input
+ */
+export declare function compileTranslations(input: CompileTranslationsInput): Promise<CompileTranslationsResult>;

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);
+}