@wpelevator/wp-release 0.16.0 → 0.17.0

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;

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;