@wpelevator/wp-release 0.15.0 → 0.17.0

package/dist/i18n/javascript.js

@@ -0,0 +1,143 @@
+import { parse } from '@babel/parser';
+import traverseModule from '@babel/traverse';
+import { extractCalls, syntaxFailure } from "./extraction.js";
+// Babel traverse publishes CommonJS; Node's ESM default is its module object.
+const traverse = traverseModule.default;
+const signatures = {
+    __: { id: 0, domain: 1, parameters: [] },
+    _x: { id: 0, context: 1, domain: 2, parameters: [] },
+    _n: { id: 0, plural: 1, domain: 3, parameters: [] },
+    _nx: { id: 0, plural: 1, context: 3, domain: 4, parameters: [] },
+};
+function staticString(node) {
+    if ('StringLiteral' === node?.type) {
+        return node.value;
+    }
+    if ('TemplateLiteral' === node?.type && !node.expressions.length) {
+        return node.quasis
+            .map((part) => part.value.cooked ?? part.value.raw)
+            .join('');
+    }
+    if ('BinaryExpression' === node?.type && '+' === node.operator) {
+        const left = staticString(node.left);
+        const right = staticString(node.right);
+        return undefined !== left && undefined !== right
+            ? left + right
+            : undefined;
+    }
+    if (node &&
+        [
+            'TSAsExpression',
+            'TSSatisfiesExpression',
+            'TSNonNullExpression',
+            'ParenthesizedExpression',
+        ].includes(node.type)) {
+        return staticString(node.expression);
+    }
+    return undefined;
+}
+function importedName(path, name) {
+    const binding = path.scope.getBinding(name);
+    const declaration = binding?.path.parentPath;
+    if (binding?.constant &&
+        declaration?.isImportDeclaration() &&
+        'type' !== declaration.node.importKind &&
+        '@wordpress/i18n' === declaration.node.source.value &&
+        binding.path.isImportSpecifier() &&
+        'type' !== binding.path.node.importKind) {
+        const imported = binding.path.node.imported;
+        return 'Identifier' === imported.type ? imported.name : imported.value;
+    }
+    return undefined;
+}
+function memberName(node) {
+    return !node.computed && 'Identifier' === node.property.type
+        ? node.property.name
+        : undefined;
+}
+function functionName(path, legacyGlobals) {
+    const callee = path.node.callee;
+    if ('Identifier' === callee.type) {
+        return (importedName(path, callee.name) ??
+            (legacyGlobals && !path.scope.getBinding(callee.name)
+                ? callee.name
+                : undefined));
+    }
+    if ('MemberExpression' === callee.type) {
+        const object = callee.object;
+        if ('Identifier' === object.type) {
+            const binding = path.scope.getBinding(object.name);
+            const declaration = binding?.path.parentPath;
+            if (binding?.constant &&
+                binding.path.isImportNamespaceSpecifier() &&
+                declaration?.isImportDeclaration() &&
+                'type' !== declaration.node.importKind &&
+                '@wordpress/i18n' === declaration.node.source.value) {
+                return memberName(callee);
+            }
+        }
+        if ('MemberExpression' === object.type &&
+            'i18n' === memberName(object) &&
+            'Identifier' === object.object.type &&
+            'wp' === object.object.name &&
+            !path.scope.getBinding('wp')) {
+            return memberName(callee);
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse JS/JSX/TS/TSX with lexical scope resolution and untouched source positions.
+ * @param input
+ */
+export function parseJavascriptTranslations(input) {
+    try {
+        const typescript = /\.[cm]?tsx?$/.test(input.file);
+        const jsx = /\.(jsx|tsx|js|mjs|cjs)$/.test(input.file);
+        const ast = parse(input.contents, {
+            sourceType: 'unambiguous',
+            plugins: [
+                ...(typescript ? ['typescript'] : []),
+                ...(jsx ? ['jsx'] : []),
+            ],
+        });
+        const calls = [];
+        traverse(ast, {
+            CallExpression(path) {
+                const name = functionName(path, input.legacyGlobals ?? true);
+                const signature = name && Object.hasOwn(signatures, name)
+                    ? signatures[name]
+                    : undefined;
+                if (name && signature) {
+                    const statement = path.getStatementParent();
+                    const commentAnchors = [];
+                    let ancestor = path;
+                    while (ancestor && ancestor !== statement) {
+                        commentAnchors.push(ancestor.node.start ?? 0);
+                        ancestor = ancestor.parentPath;
+                    }
+                    commentAnchors.push(statement?.node.start ?? 0);
+                    calls.push({
+                        name,
+                        signature,
+                        commentAnchors,
+                        arguments: path.node.arguments.map(staticString),
+                        file: input.file,
+                        line: path.node.loc?.start.line,
+                        column: (path.node.loc?.start.column ?? 0) + 1,
+                        start: path.node.start ?? 0,
+                        statementStart: statement?.node.start ?? path.node.start ?? 0,
+                    });
+                }
+            },
+        });
+        return extractCalls(input, calls, (ast.comments ?? []).map((comment) => ({
+            start: comment.start ?? 0,
+            end: comment.end ?? 0,
+            value: comment.value,
+        })));
+    }
+    catch (error) {
+        return syntaxFailure(input.file, error);
+    }
+}

package/dist/i18n/metadata.d.ts

@@ -0,0 +1,16 @@
+import type { PackageMeta } from '../package-meta.ts';
+import type { ExtractedMessage, ExtractionResult } from './catalog.ts';
+import type { ParseSourceInput } from './extraction.ts';
+/**
+ * Extract only the actual WordPress main file's translatable header values.
+ * @param meta
+ * @param contents
+ * @param domain
+ */
+export declare function extractHeaderTranslations(meta: PackageMeta, contents: string, domain: string): ExtractedMessage[];
+/**
+ * Walk versioned WordPress metadata tables, including array and wildcard fields.
+ * @param input
+ * @param kind
+ */
+export declare function parseMetadataTranslations(input: ParseSourceInput, kind: 'block' | 'theme'): ExtractionResult;

package/dist/i18n/metadata.js

@@ -0,0 +1,117 @@
+import { findFileHeaderLine } from "../package-meta.js";
+import { syntaxFailure } from "./extraction.js";
+const blockFields = {
+    title: 'block title',
+    description: 'block description',
+    keywords: ['block keyword'],
+    styles: [{ label: 'block style label' }],
+    variations: [
+        {
+            title: 'block variation title',
+            description: 'block variation description',
+            keywords: ['block variation keyword'],
+        },
+    ],
+};
+const presetFields = {
+    typography: {
+        fontSizes: [{ name: 'Font size name' }],
+        fontFamilies: [{ name: 'Font family name' }],
+    },
+    color: {
+        palette: [{ name: 'Color name' }],
+        gradients: [{ name: 'Gradient name' }],
+        duotone: [{ name: 'Duotone name' }],
+    },
+    spacing: { spacingSizes: [{ name: 'Space size name' }] },
+    dimensions: { aspectRatios: [{ name: 'Aspect ratio name' }] },
+};
+const themeFields = {
+    title: 'Style variation name',
+    description: 'Style variation description',
+    settings: {
+        ...presetFields,
+        shadow: { presets: [{ name: 'Shadow name' }] },
+        blocks: { '*': presetFields },
+    },
+    customTemplates: [{ title: 'Custom template name' }],
+    templateParts: [{ title: 'Template part name' }],
+};
+function message(id, domain, file, context, label, line) {
+    return {
+        id,
+        domain,
+        ...(context ? { context } : {}),
+        translations: [],
+        flags: [],
+        comments: label ? [label] : [],
+        references: [{ file, ...(line ? { line } : {}) }],
+    };
+}
+/**
+ * Extract only the actual WordPress main file's translatable header values.
+ * @param meta
+ * @param contents
+ * @param domain
+ */
+export function extractHeaderTranslations(meta, contents, domain) {
+    const fields = [
+        'plugin' === meta.type ? 'Plugin Name' : 'Theme Name',
+        'plugin' === meta.type ? 'Plugin URI' : 'Theme URI',
+        'Description',
+        'Author',
+        'Author URI',
+    ];
+    return fields
+        .filter((field) => meta.headers[field])
+        .map((field) => message(meta.headers[field] ?? '', domain, meta.mainFile, undefined, `${field} of the ${meta.type}`, findFileHeaderLine(contents, field) ?? undefined));
+}
+/**
+ * Walk versioned WordPress metadata tables, including array and wildcard fields.
+ * @param input
+ * @param kind
+ */
+export function parseMetadataTranslations(input, kind) {
+    try {
+        const data = JSON.parse(input.contents);
+        if (!data || 'object' !== typeof data || Array.isArray(data)) {
+            throw new Error('WordPress metadata must be a JSON object.');
+        }
+        const domain = 'block' === kind
+            ? data.textdomain ??
+                input.domain
+            : input.domain;
+        if ('string' !== typeof domain) {
+            throw new Error('Block textdomain must be a string.');
+        }
+        const messages = [];
+        function visit(value, table) {
+            if ('string' === typeof table && 'string' === typeof value) {
+                messages.push(message(value, domain, input.file, table));
+            }
+            else if (Array.isArray(table) &&
+                Array.isArray(value) &&
+                table[0]) {
+                value.forEach((item) => visit(item, table[0]));
+            }
+            else if (table &&
+                'object' === typeof table &&
+                !Array.isArray(table) &&
+                value &&
+                'object' === typeof value &&
+                !Array.isArray(value)) {
+                for (const [key, child] of Object.entries(value)) {
+                    const schema = table[key] ?? table['*'];
+                    if (schema) {
+                        visit(child, schema);
+                    }
+                }
+            }
+        }
+        visit(data, 'block' === kind ? blockFields : themeFields);
+        return { messages, diagnostics: [] };
+    }
+    catch (error) {
+        return syntaxFailure(input.file, error);
+    }
+}

package/dist/i18n/options.d.ts

@@ -0,0 +1,52 @@
+/** Gettext header values by name; `false` removes a header set by the defaults or an earlier layer. */
+export type I18nHeaders = Record<string, string | false>;
+export interface I18nOptions {
+    enabled?: boolean;
+    domain?: string;
+    allDomains?: boolean;
+    include?: string[];
+    exclude?: string[];
+    /** Package-relative directory; Domain Path or languages by default. */
+    destination?: string;
+    headers?: I18nHeaders;
+    /** Static comment lines to prepend to the POT; no year is generated. */
+    fileComment?: string;
+    references?: boolean;
+    strict?: boolean;
+    legacyGlobals?: boolean;
+    suppress?: string[];
+}
+export declare const DEFAULT_I18N_INCLUDE: string[];
+export declare const DEFAULT_I18N_EXCLUDE: string[];
+/**
+ * Validate external config independently of extraction and distribution file settings.
+ * @param input
+ * @param label
+ */
+export declare function validateI18nOptions(input: unknown, label?: string): asserts input is I18nOptions | undefined;
+/**
+ * Validate static text to prepend as a POT file comment.
+ * @param fileComment
+ * @param label
+ */
+export declare function validateI18nFileComment(fileComment: unknown, label?: string): asserts fileComment is string;
+/**
+ * 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 declare function validateI18nHeaders(headers: unknown, label?: string): asserts headers is I18nHeaders;
+/**
+ * Scalars and lists replace inherited values; header dictionaries merge by key.
+ * @param layers Extraction settings in increasing precedence.
+ */
+export declare function resolveI18nOptions(...layers: Array<I18nOptions | undefined>): I18nOptions;
+/**
+ * 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 declare function mergeI18nHeaders(...layers: Array<I18nHeaders | undefined>): I18nHeaders;

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;