@wpelevator/wp-release 0.16.0 → 0.17.0

package/dist/i18n/options.js

@@ -0,0 +1,156 @@
+import { ValidationError } from "../errors.js";
+export const DEFAULT_I18N_INCLUDE = [
+    '**/*.{php,js,jsx,ts,tsx,mjs,cjs,mts,cts}',
+    '**/block.json',
+    '**/theme.json',
+    'styles/**/*.json',
+];
+export const DEFAULT_I18N_EXCLUDE = [
+    '**/node_modules/**',
+    '**/vendor/**',
+    '**/.*/**',
+    '**/tests/**',
+    '**/test/**',
+    '**/__tests__/**',
+    '**/*.test.*',
+    '**/*.spec.*',
+    '**/*.min.*',
+    '**/*.{pot,po,mo}',
+    '**/*.l10n.php',
+];
+/**
+ * Validate external config independently of extraction and distribution file settings.
+ * @param input
+ * @param label
+ */
+export function validateI18nOptions(input, label = 'i18n') {
+    if (undefined === input) {
+        return;
+    }
+    if (!input || 'object' !== typeof input || Array.isArray(input)) {
+        throw new ValidationError(`${label} must be an object.`);
+    }
+    const options = input;
+    const allowed = [
+        'enabled',
+        'domain',
+        'allDomains',
+        'include',
+        'exclude',
+        'destination',
+        'headers',
+        'fileComment',
+        'references',
+        'strict',
+        'legacyGlobals',
+        'suppress',
+    ];
+    for (const key of Object.keys(options)) {
+        if (!allowed.includes(key)) {
+            throw new ValidationError(`${label}.${key} is not a supported extraction option.`);
+        }
+    }
+    for (const key of [
+        'enabled',
+        'allDomains',
+        'references',
+        'strict',
+        'legacyGlobals',
+    ]) {
+        if (undefined !== options[key] &&
+            'boolean' !== typeof options[key]) {
+            throw new ValidationError(`${label}.${key} must be a boolean.`);
+        }
+    }
+    for (const key of ['domain', 'destination']) {
+        if (undefined !== options[key] &&
+            ('string' !== typeof options[key] || !options[key]?.trim())) {
+            throw new ValidationError(`${label}.${key} must be a non-empty string.`);
+        }
+    }
+    if (undefined !== options.fileComment) {
+        validateI18nFileComment(options.fileComment, `${label}.fileComment`);
+    }
+    for (const key of ['include', 'exclude', 'suppress']) {
+        const value = options[key];
+        if (undefined !== value &&
+            (!Array.isArray(value) ||
+                value.some((entry) => 'string' !== typeof entry || !entry.trim()))) {
+            throw new ValidationError(`${label}.${key} must be a list of non-empty strings.`);
+        }
+    }
+    if (undefined !== options.headers) {
+        validateI18nHeaders(options.headers, `${label}.headers`);
+    }
+}
+/**
+ * Validate static text to prepend as a POT file comment.
+ * @param fileComment
+ * @param label
+ */
+export function validateI18nFileComment(fileComment, label = 'i18n.fileComment') {
+    if ('string' !== typeof fileComment ||
+        !fileComment.trim() ||
+        fileComment.includes('\0')) {
+        throw new ValidationError(`${label} must be a non-empty string without NUL characters.`);
+    }
+}
+/**
+ * Validate gettext header names and values independently of extraction options.
+ *
+ * @param  headers Header values, or `false` to remove a header.
+ * @param  label   Config path for error messages.
+ * @throws {ValidationError} For invalid names or values, or a removed Content-Type.
+ */
+export function validateI18nHeaders(headers, label = 'i18n.headers') {
+    if (!headers ||
+        'object' !== typeof headers ||
+        Array.isArray(headers) ||
+        Object.entries(headers).some(([key, value]) => !/^[A-Za-z][A-Za-z0-9-]*$/.test(key) ||
+            (false !== value &&
+                ('string' !== typeof value || /[\r\n\0]/.test(value))))) {
+        throw new ValidationError(`${label} must contain gettext header names with single-line string values, or false to remove a header.`);
+    }
+    if (Object.entries(headers).some(([key, value]) => false === value && 'content-type' === key.toLowerCase())) {
+        throw new ValidationError(`${label} can't remove Content-Type, which declares the UTF-8 charset of the catalog.`);
+    }
+}
+/**
+ * Scalars and lists replace inherited values; header dictionaries merge by key.
+ * @param layers Extraction settings in increasing precedence.
+ */
+export function resolveI18nOptions(...layers) {
+    let options = {
+        enabled: true,
+        include: DEFAULT_I18N_INCLUDE,
+        exclude: DEFAULT_I18N_EXCLUDE,
+        references: true,
+        legacyGlobals: true,
+    };
+    for (const layer of layers) {
+        validateI18nOptions(layer);
+        if (layer) {
+            options = {
+                ...options,
+                ...layer,
+                headers: mergeI18nHeaders(options.headers, layer.headers),
+            };
+        }
+    }
+    return options;
+}
+/**
+ * Merge gettext header names case-insensitively, preserving deliberate empty values and removals.
+ *
+ * @param layers Header values in increasing precedence.
+ * @return Merged headers, with `false` for removed headers so that later layers can still set them.
+ */
+export function mergeI18nHeaders(...layers) {
+    const headers = new Map();
+    for (const layer of layers) {
+        for (const [key, value] of Object.entries(layer ?? {})) {
+            headers.set(key.toLowerCase(), [key, value]);
+        }
+    }
+    return Object.fromEntries(headers.values());
+}

package/dist/i18n/packages.d.ts

@@ -0,0 +1,24 @@
+import type { I18nOptions } from './options.ts';
+export interface I18nPackageInput {
+    cwd: string;
+    configFile?: string;
+    package?: string;
+    all?: boolean;
+    sourceDir?: string;
+    /** An explicit absolute output path; only supported for one package. */
+    outputPath?: string;
+    options?: I18nOptions;
+    /** Audit selection need not validate output destinations. */
+    validateOutputs?: boolean;
+}
+export interface I18nPackage {
+    package?: string;
+    sourceDir: string;
+    outputPath: string;
+    options: I18nOptions;
+}
+/**
+ * The config adapter resolves package directories and options before invoking primitives.
+ * @param input
+ */
+export declare function resolveI18nPackages(input: I18nPackageInput): Promise<I18nPackage[]>;

package/dist/i18n/packages.js

@@ -0,0 +1,86 @@
+import { basename, resolve } from 'node:path';
+import { loadChangesetConfig } from "../changeset-config.js";
+import { discoverConfiguredPackages, findPackage, } from "../changeset-packages.js";
+import { ReleaseRepository } from "../release-repository.js";
+import { readPackageMeta } from "../package-meta.js";
+import { ValidationError } from "../errors.js";
+import { validateI18nContainment } from "./atomic-output.js";
+import { resolveI18nOptions } from "./options.js";
+import { resolvePotPath, validatePotDestinations } from "./generate.js";
+/**
+ * The config adapter resolves package directories and options before invoking primitives.
+ * @param input
+ */
+export async function resolveI18nPackages(input) {
+    if ((input.package && input.all) ||
+        ((input.package || input.all) && input.sourceDir) ||
+        (input.all && input.outputPath)) {
+        throw new ValidationError('Choose a source directory, --package, or --all. --output requires one package.');
+    }
+    if ('' === input.package?.trim()) {
+        throw new ValidationError('--package must not be empty.');
+    }
+    const packages = [];
+    if (input.package || input.all) {
+        const loaded = await loadChangesetConfig(input);
+        if (!loaded) {
+            throw new ValidationError('--package and --all require wp-release configuration.');
+        }
+        const repository = new ReleaseRepository({
+            cwd: input.cwd,
+        });
+        const configured = await discoverConfiguredPackages(repository, loaded.config);
+        let selected = configured;
+        if (input.package) {
+            const match = findPackage(configured, input.package);
+            if (!match) {
+                throw new ValidationError(`Unknown package: ${input.package}.`);
+            }
+            selected = [match];
+        }
+        for (const pkg of selected) {
+            const options = resolveI18nOptions(loaded.config.i18n, pkg.group.i18n, input.options);
+            const meta = await readPackageMeta({
+                dir: pkg.directory,
+                slug: basename(pkg.directory),
+            });
+            if (input.package && (!options.enabled || !meta)) {
+                throw new ValidationError(`Package ${pkg.name} is disabled for i18n or has no WordPress headers.`);
+            }
+            if (options.enabled && meta) {
+                packages.push({
+                    package: pkg.name,
+                    sourceDir: pkg.directory,
+                    options,
+                    outputPath: input.outputPath ??
+                        resolvePotPath(pkg.directory, meta, options),
+                });
+            }
+        }
+    }
+    else {
+        const sourceDir = resolve(input.cwd, input.sourceDir ?? '.');
+        const meta = await readPackageMeta({
+            dir: sourceDir,
+            slug: basename(sourceDir),
+        });
+        if (!meta) {
+            throw new ValidationError(`No WordPress plugin or theme headers found in ${sourceDir}.`);
+        }
+        const options = resolveI18nOptions(input.options);
+        packages.push({
+            sourceDir,
+            options,
+            outputPath: input.outputPath ?? resolvePotPath(sourceDir, meta, options),
+        });
+    }
+    if (false !== input.validateOutputs) {
+        await validatePotDestinations(packages.map((pkg) => pkg.outputPath));
+        if (!input.outputPath) {
+            for (const pkg of packages) {
+                await validateI18nContainment(pkg.sourceDir, pkg.outputPath);
+            }
+        }
+    }
+    return packages;
+}

package/dist/i18n/php.d.ts

@@ -0,0 +1,9 @@
+import type { CallSignature, ParseSourceInput } from './extraction.ts';
+import type { ExtractionResult } from './catalog.ts';
+/** PHP argument names and positions follow the WordPress l10n.php signatures. */
+export declare const PHP_TRANSLATION_FUNCTIONS: Record<string, CallSignature>;
+/**
+ * Parse PHP without executing it; namespaced fallback calls follow known file-local bindings.
+ * @param input
+ */
+export declare function parsePhpTranslations(input: ParseSourceInput): ExtractionResult;

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;