@wpelevator/wp-release 0.15.0 → 0.17.0

package/dist/i18n/php.js

@@ -0,0 +1,238 @@
+import { Engine } from 'php-parser';
+import { extractCalls, syntaxFailure } from "./extraction.js";
+const simple = {
+    id: 0,
+    domain: 1,
+    parameters: ['text', 'domain'],
+};
+const contextual = {
+    id: 0,
+    context: 1,
+    domain: 2,
+    parameters: ['text', 'context', 'domain'],
+};
+const plural = {
+    id: 0,
+    plural: 1,
+    domain: 3,
+    parameters: ['single', 'plural', 'number', 'domain'],
+};
+const contextualPlural = {
+    id: 0,
+    plural: 1,
+    context: 3,
+    domain: 4,
+    parameters: ['single', 'plural', 'number', 'context', 'domain'],
+};
+/** PHP argument names and positions follow the WordPress l10n.php signatures. */
+export const PHP_TRANSLATION_FUNCTIONS = {
+    __: simple,
+    _e: simple,
+    esc_attr__: simple,
+    esc_attr_e: simple,
+    esc_html__: simple,
+    esc_html_e: simple,
+    _x: contextual,
+    _ex: contextual,
+    esc_attr_x: contextual,
+    esc_html_x: contextual,
+    _n: plural,
+    _nx: contextualPlural,
+    _n_noop: {
+        id: 0,
+        plural: 1,
+        domain: 2,
+        parameters: ['singular', 'plural', 'domain'],
+    },
+    _nx_noop: {
+        id: 0,
+        plural: 1,
+        context: 2,
+        domain: 3,
+        parameters: ['singular', 'plural', 'context', 'domain'],
+    },
+};
+function nodes(node) {
+    return Object.entries(node)
+        .filter(([key]) => ![
+        'loc',
+        'comments',
+        'leadingComments',
+        'trailingComments',
+    ].includes(key))
+        .flatMap(([, value]) => {
+        const values = Array.isArray(value) ? value : [value];
+        return values.filter((child) => !!child && 'object' === typeof child && 'kind' in child);
+    });
+}
+function nameOf(node) {
+    if ('string' === typeof node?.name) {
+        return node.name;
+    }
+    return 'string' === typeof node?.name?.name ? node.name.name : '';
+}
+function staticString(node) {
+    if (node &&
+        ['string', 'nowdoc'].includes(node.kind) &&
+        'string' === typeof node.value) {
+        return node.value;
+    }
+    if ('bin' === node?.kind && '.' === node.type) {
+        const left = staticString(node.left);
+        const right = staticString(node.right);
+        return undefined !== left && undefined !== right
+            ? left + right
+            : undefined;
+    }
+    if ('encapsed' === node?.kind &&
+        'heredoc' === node.type &&
+        Array.isArray(node.value)) {
+        const parts = node.value.map((part) => staticString(part.expression));
+        return parts.every((part) => undefined !== part)
+            ? parts.join('')
+            : undefined;
+    }
+    return undefined;
+}
+function bindingsFor(root) {
+    const imports = new Map();
+    const functions = new Set();
+    function collect(node) {
+        if ('function' === node.kind) {
+            functions.add(nameOf(node).toLowerCase());
+        }
+        if ('usegroup' === node.kind) {
+            for (const item of node.items ?? []) {
+                if ('function' === (item.type ?? node.type)) {
+                    const imported = [nameOf(node), nameOf(item)]
+                        .filter(Boolean)
+                        .join('\\')
+                        .replace(/^\\/, '')
+                        .toLowerCase();
+                    imports.set((nameOf(item.alias) ||
+                        imported.split('\\').at(-1) ||
+                        '').toLowerCase(), imported);
+                }
+            }
+        }
+        if ('namespace' !== node.kind || node === root) {
+            nodes(node).forEach(collect);
+        }
+    }
+    collect(root);
+    return { imports, functions };
+}
+function resolveFunction(node, bindings, globalFunctions) {
+    if ('name' !== node?.kind) {
+        return undefined;
+    }
+    const name = nameOf(node).toLowerCase();
+    if (name.startsWith('\\')) {
+        return globalFunctions.has(name.slice(1))
+            ? undefined
+            : name.slice(1);
+    }
+    if (name.includes('\\') || 'rn' === node.resolution) {
+        return undefined;
+    }
+    if (bindings.imports.has(name)) {
+        const imported = bindings.imports.get(name);
+        return imported && !globalFunctions.has(imported)
+            ? imported
+            : undefined;
+    }
+    return bindings.functions.has(name) || globalFunctions.has(name)
+        ? undefined
+        : name;
+}
+/**
+ * Parse PHP without executing it; namespaced fallback calls follow known file-local bindings.
+ * @param input
+ */
+export function parsePhpTranslations(input) {
+    try {
+        const parser = new Engine({
+            parser: { extractDoc: true, version: '8.3' },
+            ast: { withPositions: true },
+        });
+        const ast = parser.parseCode(input.contents, input.file);
+        const declarations = new Map();
+        function collectDeclarations(node, namespace) {
+            const currentNamespace = 'namespace' === node.kind
+                ? nameOf(node).toLowerCase()
+                : namespace;
+            if ('function' === node.kind) {
+                const names = declarations.get(currentNamespace) ?? new Set();
+                names.add(nameOf(node).toLowerCase());
+                declarations.set(currentNamespace, names);
+            }
+            nodes(node).forEach((child) => collectDeclarations(child, currentNamespace));
+        }
+        collectDeclarations(ast, '');
+        const globalFunctions = declarations.get('') ?? new Set();
+        const calls = [];
+        function visit(node, bindings, statementStart, anchors) {
+            const current = 'namespace' === node.kind
+                ? {
+                    ...bindingsFor(node),
+                    functions: declarations.get(nameOf(node).toLowerCase()) ?? new Set(),
+                }
+                : bindings;
+            const start = node.loc?.start.offset ?? statementStart;
+            const statement = [
+                'expressionstatement',
+                'echo',
+                'return',
+                'throw',
+                'if',
+                'while',
+                'for',
+                'foreach',
+            ].includes(node.kind)
+                ? start
+                : statementStart;
+            const currentAnchors = statement === start ? [start] : [start, ...anchors];
+            if ('call' === node.kind) {
+                const name = resolveFunction(node.what, current, globalFunctions);
+                const signature = name && Object.hasOwn(PHP_TRANSLATION_FUNCTIONS, name)
+                    ? PHP_TRANSLATION_FUNCTIONS[name]
+                    : undefined;
+                if (name && signature) {
+                    const args = [];
+                    for (const [index, argument] of (node.arguments ?? []).entries()) {
+                        const position = 'namedargument' === argument.kind
+                            ? signature.parameters.indexOf(nameOf(argument))
+                            : index;
+                        if (position >= 0) {
+                            args[position] = staticString('namedargument' === argument.kind
+                                ? argument.value
+                                : argument);
+                        }
+                    }
+                    calls.push({
+                        name,
+                        signature,
+                        arguments: args,
+                        file: input.file,
+                        line: node.loc?.start.line,
+                        column: (node.loc?.start.column ?? 0) + 1,
+                        start,
+                        statementStart: statement,
+                        commentAnchors: currentAnchors,
+                    });
+                }
+            }
+            nodes(node).forEach((child) => visit(child, current, statement, currentAnchors));
+        }
+        visit(ast, bindingsFor(ast), 0, []);
+        const comments = (ast.comments ?? []).map((comment) => ({
+            start: comment.loc?.start.offset ?? 0,
+            end: comment.loc?.end.offset ?? 0,
+            value: String(comment.value ?? ''),
+        }));
+        return extractCalls(input, calls, comments);
+    }
+    catch (error) {
+        return syntaxFailure(input.file, error);
+    }
+}

package/dist/i18n/placeholders.d.ts

@@ -0,0 +1,9 @@
+export interface Placeholder {
+    position?: number;
+    type: string;
+}
+/**
+ * PHP sprintf and JS sprintf-compatible forms; literal %% consumes no argument.
+ * @param text
+ */
+export declare function getPlaceholders(text: string): Placeholder[];

package/dist/i18n/placeholders.js

@@ -0,0 +1,13 @@
+/**
+ * PHP sprintf and JS sprintf-compatible forms; literal %% consumes no argument.
+ * @param text
+ */
+export function getPlaceholders(text) {
+    const matches = text.matchAll(/%%|%(?:(\d+)\$)?[-+ 0#]*(?:'[^\r\n])?\d*(?:\.\d+)?([bcdeEfFgGosuxX])/g);
+    return [...matches]
+        .filter((match) => '%%' !== match[0])
+        .map((match) => ({
+        ...(match[1] ? { position: Number(match[1]) } : {}),
+        type: match[2] ?? '',
+    }));
+}

package/dist/i18n/po.d.ts

@@ -0,0 +1,24 @@
+import type { Catalog, CatalogMessage } from './catalog.ts';
+export interface TranslatedCatalog extends Catalog {
+    /** Headers parsed from the PO, always with string values. */
+    headers: Record<string, string>;
+    locale: string;
+    pluralForms: string;
+    nplurals: number;
+}
+/**
+ * Parse translated PO as data, filtering fuzzy, obsolete and untranslated entries.
+ * @param contents
+ * @param domain
+ */
+export declare function parseTranslatedPo(contents: Buffer | string, domain: string): TranslatedCatalog;
+/**
+ * WordPress/Jed lookup key uses context + EOT + singular, even for plural messages.
+ * @param message
+ */
+export declare function translationKey(message: CatalogMessage): string;
+/**
+ * Compile MO through gettext-parser; never write or mutate the input PO.
+ * @param catalog
+ */
+export declare function compileMo(catalog: TranslatedCatalog): Buffer;

package/dist/i18n/po.js

@@ -0,0 +1,180 @@
+import { po, mo } from 'gettext-parser';
+import postfixModule from '@tannin/postfix';
+import { ValidationError } from "../errors.js";
+import { compareText } from "./catalog.js";
+const postfix = postfixModule;
+/**
+ * Validate gettext plural expressions with Tannin's parser, without eval or Function.
+ * @param header
+ */
+function validatePluralForms(header) {
+    const match = /^\s*nplurals\s*=\s*([1-9]\d*)\s*;\s*plural\s*=\s*([^;]+)\s*;?\s*$/.exec(header);
+    if (!match || Number(match[1]) > 100) {
+        throw new ValidationError('PO requires a valid Plural-Forms header with nplurals and a plural expression.');
+    }
+    const expression = match[2] ?? '';
+    if (/[^\dn\s!%*/+<>=&|?:()\-]/.test(expression)) {
+        throw new ValidationError('Plural-Forms contains an unsupported expression token.');
+    }
+    try {
+        let depth = 0;
+        for (const term of postfix(expression)) {
+            if ('n' === term || /^\d+$/.test(String(term))) {
+                depth++;
+            }
+            else {
+                if (![
+                    '!',
+                    '*',
+                    '/',
+                    '%',
+                    '+',
+                    '-',
+                    '<',
+                    '<=',
+                    '>',
+                    '>=',
+                    '==',
+                    '!=',
+                    '&&',
+                    '||',
+                    '?:',
+                ].includes(term)) {
+                    throw new Error('Unsupported plural operator.');
+                }
+                let arity = 2;
+                if ('!' === term) {
+                    arity = 1;
+                }
+                if ('?:' === term) {
+                    arity = 3;
+                }
+                if (depth < arity) {
+                    throw new Error('Invalid operand count.');
+                }
+                depth -= arity - 1;
+            }
+        }
+        if (1 !== depth) {
+            throw new Error('Incomplete expression.');
+        }
+    }
+    catch (error) {
+        throw new ValidationError(`Malformed Plural-Forms expression: ${String(error)}`);
+    }
+    return Number(match[1]);
+}
+/**
+ * Parse translated PO as data, filtering fuzzy, obsolete and untranslated entries.
+ * @param contents
+ * @param domain
+ */
+export function parseTranslatedPo(contents, domain) {
+    let parsed;
+    try {
+        parsed = po.parse(contents, {
+            validation: true,
+            defaultCharset: 'UTF-8',
+        });
+    }
+    catch (error) {
+        throw new ValidationError(`Malformed PO catalog: ${String(error)}`);
+    }
+    if (!parsed.headers || !parsed.translations) {
+        throw new ValidationError('Malformed PO catalog: missing gettext headers or translations.');
+    }
+    const headers = Object.fromEntries(Object.entries(parsed.headers).map(([key, value]) => [
+        key.toLowerCase(),
+        value,
+    ]));
+    const locale = headers.language;
+    if (!locale || !/^[A-Za-z][A-Za-z0-9_@.-]*$/.test(locale)) {
+        throw new ValidationError('PO requires a non-empty valid Language header.');
+    }
+    const pluralForms = headers['plural-forms'] ?? '';
+    const nplurals = validatePluralForms(pluralForms);
+    const messages = [];
+    for (const entry of Object.values(parsed.translations).flatMap((context) => Object.values(context))) {
+        const flags = (entry.comments?.flag ?? '')
+            .split(',')
+            .map((flag) => flag.trim())
+            .filter(Boolean);
+        if (entry.msgid &&
+            !entry.obsolete &&
+            !flags.includes('fuzzy') &&
+            entry.msgstr.every((translation) => !!translation)) {
+            if (entry.msgstr.length !==
+                (undefined !== entry.msgid_plural ? nplurals : 1) ||
+                /[\0\u0004]/.test(entry.msgid) ||
+                /[\0\u0004]/.test(entry.msgctxt ?? '') ||
+                entry.msgstr.some((value) => value.includes('\0'))) {
+                throw new ValidationError(`Invalid translation forms or reserved separators for ${JSON.stringify(entry.msgid)}.`);
+            }
+            const references = (entry.comments?.reference ?? '')
+                .split(/\s+/)
+                .filter(Boolean)
+                .map((reference) => {
+                const location = /^(.*?)(?::(\d+))?$/.exec(reference);
+                return {
+                    file: location?.[1] ?? reference,
+                    ...(location?.[2]
+                        ? { line: Number(location[2]) }
+                        : {}),
+                };
+            });
+            messages.push({
+                id: entry.msgid,
+                ...(undefined !== entry.msgid_plural
+                    ? { plural: entry.msgid_plural }
+                    : {}),
+                ...(undefined !== entry.msgctxt
+                    ? { context: entry.msgctxt }
+                    : {}),
+                translations: [...entry.msgstr],
+                flags,
+                references,
+                comments: (entry.comments?.extracted ?? '')
+                    .split('\n')
+                    .filter(Boolean),
+            });
+        }
+    }
+    messages.sort((a, b) => compareText(translationKey(a), translationKey(b)));
+    return { domain, headers, messages, locale, pluralForms, nplurals };
+}
+/**
+ * WordPress/Jed lookup key uses context + EOT + singular, even for plural messages.
+ * @param message
+ */
+export function translationKey(message) {
+    return (message.context ? `${message.context}\u0004` : '') + message.id;
+}
+/**
+ * Compile MO through gettext-parser; never write or mutate the input PO.
+ * @param catalog
+ */
+export function compileMo(catalog) {
+    const table = {
+        charset: 'UTF-8',
+        headers: {
+            ...catalog.headers,
+            'content-type': 'text/plain; charset=UTF-8',
+        },
+        translations: Object.create(null),
+    };
+    for (const message of catalog.messages) {
+        const context = message.context ?? '';
+        table.translations[context] ??= Object.create(null);
+        table.translations[context][message.id] = {
+            msgid: message.id,
+            ...(undefined !== message.context
+                ? { msgctxt: message.context }
+                : {}),
+            ...(undefined !== message.plural
+                ? { msgid_plural: message.plural }
+                : {}),
+            msgstr: [...message.translations],
+        };
+    }
+    return mo.compile(table);
+}

package/dist/i18n/pot.d.ts

@@ -0,0 +1,16 @@
+import type { Catalog } from './catalog.ts';
+/**
+ * Serialize deterministic UTF-8 POT bytes in the gettext layout, with no wall-clock data.
+ *
+ * Messages keep the catalog order, and each entry lists extracted comments, references and flags before its strings.
+ *
+ * @param catalog             Catalog to serialize.
+ * @param options             Serialization options.
+ * @param options.references  Whether to include source references (default true).
+ * @param options.fileComment Static text to prepend as gettext comments.
+ * @return POT file contents.
+ */
+export declare function serializePot(catalog: Catalog, options?: {
+    references?: boolean;
+    fileComment?: string;
+}): Buffer;

package/dist/i18n/pot.js

@@ -0,0 +1,119 @@
+import { mergeI18nHeaders, validateI18nFileComment, validateI18nHeaders, } from "./options.js";
+const ESCAPES = {
+    '\\': '\\\\',
+    '"': '\\"',
+    '\x07': '\\a',
+    '\b': '\\b',
+    '\f': '\\f',
+    '\n': '\\n',
+    '\r': '\\r',
+    '\t': '\\t',
+    '\v': '\\v',
+};
+/**
+ * Serialize deterministic UTF-8 POT bytes in the gettext layout, with no wall-clock data.
+ *
+ * Messages keep the catalog order, and each entry lists extracted comments, references and flags before its strings.
+ *
+ * @param catalog             Catalog to serialize.
+ * @param options             Serialization options.
+ * @param options.references  Whether to include source references (default true).
+ * @param options.fileComment Static text to prepend as gettext comments.
+ * @return POT file contents.
+ */
+export function serializePot(catalog, options = {}) {
+    validateI18nHeaders(catalog.headers);
+    if (undefined !== options.fileComment) {
+        validateI18nFileComment(options.fileComment);
+    }
+    const fileComment = undefined === options.fileComment
+        ? ''
+        : options.fileComment
+            .split(/\r\n|\r|\n/)
+            .map((line) => `# ${line}\n`)
+            .join('');
+    const entries = catalog.messages.map((message) => serializeMessage(message, false !== options.references));
+    return Buffer.from(fileComment + [serializeHeaders(catalog), ...entries].join('\n'));
+}
+/**
+ * Serialize the header entry: the default headers in a fixed order, overridden in place or removed with `false`, then custom headers in the given order.
+ *
+ * @param catalog Catalog with the domain and header overrides.
+ * @return Header entry.
+ */
+function serializeHeaders(catalog) {
+    const defaults = {
+        'Project-Id-Version': catalog.domain,
+        'Report-Msgid-Bugs-To': '',
+        'Last-Translator': '',
+        'Language-Team': '',
+        'MIME-Version': '1.0',
+        'Content-Type': 'text/plain; charset=UTF-8',
+        'Content-Transfer-Encoding': '8bit',
+        'POT-Creation-Date': '',
+        'PO-Revision-Date': '',
+        'X-Domain': catalog.domain,
+    };
+    const headers = Object.entries(mergeI18nHeaders(defaults, catalog.headers))
+        .filter(([, value]) => false !== value)
+        .map(([name, value]) => `"${escape(`${name}: ${value}\n`)}"\n`);
+    return `msgid ""\nmsgstr ""\n${headers.join('')}`;
+}
+/**
+ * Serialize one message entry.
+ *
+ * @param message    Catalog message.
+ * @param references Whether to include source references.
+ * @return Message entry.
+ */
+function serializeMessage(message, references) {
+    const lines = [
+        ...message.comments.flatMap((comment) => comment.split(/\r\n|\r|\n/).map((line) => `#. ${line}`)),
+        ...(references
+            ? [
+                ...new Set(message.references.map((reference) => `#: ${reference.file}${reference.line ? `:${reference.line}` : ''}`)),
+            ]
+            : []),
+        ...(message.flags.length
+            ? [`#, ${message.flags.join(', ')}`]
+            : []),
+        ...(undefined !== message.context
+            ? [poString('msgctxt', message.context)]
+            : []),
+        poString('msgid', message.id),
+    ];
+    if (undefined === message.plural) {
+        lines.push('msgstr ""');
+    }
+    else {
+        lines.push(poString('msgid_plural', message.plural), 'msgstr[0] ""', 'msgstr[1] ""');
+    }
+    return lines.join('\n') + '\n';
+}
+/**
+ * Format a gettext keyword and string, splitting strings with newlines into one line per segment.
+ *
+ * @param keyword Gettext keyword, like msgid.
+ * @param value   String value.
+ * @return Serialized keyword lines.
+ */
+function poString(keyword, value) {
+    if (!value.includes('\n')) {
+        return `${keyword} "${escape(value)}"`;
+    }
+    return [
+        `${keyword} ""`,
+        ...value
+            .split(/(?<=\n)/)
+            .map((segment) => `"${escape(segment)}"`),
+    ].join('\n');
+}
+/**
+ * Escape a string for a quoted gettext string.
+ *
+ * @param value Raw string.
+ * @return Escaped string.
+ */
+function escape(value) {
+    return value.replace(/[\\"\x07\b\f\n\r\t\v]/g, (character) => ESCAPES[character] ?? character);
+}

package/dist/i18n/translation-json.d.ts

@@ -0,0 +1,14 @@
+import type { TranslatedCatalog } from './po.ts';
+/** Many-to-many source references to runtime scripts, both relative to the package. */
+export type ScriptTranslationMap = Record<string, string[]>;
+export interface ScriptTranslationOutput {
+    file: string;
+    source: string;
+    bytes: Buffer;
+}
+/**
+ * Compile deterministic Jed catalogs using explicit source/build mapping or unbundled identity paths.
+ * @param catalog
+ * @param mapping
+ */
+export declare function compileScriptTranslations(catalog: TranslatedCatalog, mapping?: ScriptTranslationMap): ScriptTranslationOutput[];