@wpelevator/wp-release 0.15.0 → 0.17.0

package/dist/commands/zip.js

@@ -1,108 +1,15 @@
-import { basename, resolve } from 'node:path';
+import { checksumSigningArgs, getArtifactSigning } from "./artifact-signing.js";
 import { ValidationError } from "../errors.js";
-import { resolveFileSelection } from "../file-selection.js";
+import { basename, dirname, resolve, sep } from 'node:path';
+import { loadChangesetConfig } from "../changeset-config.js";
+import { resolveManifestCodec, checkChecksumsFile } from "../integrity.js";
+import { getPackageArg, getPackageSource, getDirectorySource, } from "./package-source.js";
 import { FILENAME_FORMAT, formatFilename } from "../filename.js";
-import { getPackageFiles } from "../package-deploy.js";
-import { readPackageMeta } from "../package-meta.js";
 import { getChecksumsPath, zipPackage } from "../package-zip.js";
-import { SIGNING_KEY_ENV, checkSigningInput, signFiles } from "../signing.js";
+import { SIGNING_KEY_ENV, signFiles, getSignaturePath } from "../signing.js";
 import { getSignSummary, getZipSummary } from "../summary.js";
-import { checkDirectory, fileSelectionArgs, getFileSelectionInput, getSourceDirArg, parseSignatureFormats, resolveOutput, sourceDirArgs, } from "./args.js";
+import { fileSelectionArgs, parseSignatureFormats, resolveOutput, sourceDirArgs, } from "./args.js";
 import { getBoolean, getString, getStrings } from "./command.js";
-/** Options of a source directory and its files, which --package takes from the config. */
-const SOURCE_FLAGS = [
-    'source-dir',
-    'distignore',
-    'no-distignore',
-    'exclude',
-    'exclude-gitattributes',
-];
-/**
- * Get the configured package to zip, failing for the options that set the
- * source directory and the files instead.
- *
- * @param  values      Parsed CLI values.
- * @param  positionals Positional arguments.
- * @return The package identifier or path, or undefined without --package.
- * @throws {ValidationError} For an empty --package, or --package with a source directory or file selection option.
- */
-function getPackageArg(values, positionals) {
-    const name = getString(values, 'package')?.trim();
-    const conflicts = SOURCE_FLAGS.filter((flag) => undefined !== getString(values, flag) ||
-        getBoolean(values, flag) ||
-        getStrings(values, flag).length);
-    if ('' === name) {
-        throw new ValidationError('--package <name> must not be empty.');
-    }
-    if (name && (positionals.length || conflicts.length)) {
-        throw new ValidationError(`--package takes the directory and files of the package from the config, so it can't be combined with ${positionals.length
-            ? 'a source directory'
-            : conflicts.map((flag) => `--${flag}`).join(', ')}.`);
-    }
-    return name;
-}
-/**
- * Describe the files of a directory with the slug and the version from the
- * options, or from the plugin or theme headers.
- *
- * @param values    Parsed CLI values.
- * @param sourceDir Directory to zip.
- * @param selection File selection.
- * @param slug      Default slug.
- * @return Source directory, file selection, slug, version and type.
- */
-async function describeSource(values, sourceDir, selection, slug) {
-    const name = getString(values, 'slug') ?? slug;
-    const meta = await readPackageMeta({ dir: sourceDir, slug: name });
-    return {
-        sourceDir,
-        selection,
-        slug: name,
-        version: getString(values, 'version') ?? meta?.version ?? null,
-        ...(meta ? { type: meta.type } : {}),
-    };
-}
-/**
- * Get the files of a source directory from the CLI options.
- *
- * @param values      Parsed CLI values.
- * @param positionals Positional arguments.
- * @param cwd         Working directory.
- * @return Source directory, file selection, slug and version.
- */
-async function getDirectorySource(values, positionals, cwd) {
-    const sourceDir = resolve(cwd, getSourceDirArg(values, positionals));
-    await checkDirectory(sourceDir);
-    return describeSource(values, sourceDir, resolveFileSelection({
-        cwd,
-        sourceDir,
-        ...getFileSelectionInput(values),
-    }), basename(cwd));
-}
-/**
- * Get the directory of a configured package with the files config of its
- * package group, which its deploys use too.
- *
- * @param  values     Parsed CLI values.
- * @param  cwd        Repository root with the wp-release config.
- * @param  name       Package identifier or path under the configured root.
- * @param  configFile Config file, instead of the conventional one.
- * @return Source directory, file selection, slug, version and package.
- * @throws {ValidationError} Without a config or for an unknown package.
- */
-async function getPackageSource(values, cwd, name, configFile) {
-    const pkg = await getPackageFiles({
-        cwd,
-        package: name,
-        ...(configFile ? { configFile } : {}),
-    });
-    const source = await describeSource(values, pkg.directory, resolveFileSelection({
-        cwd,
-        sourceDir: pkg.directory,
-        ...pkg.files,
-    }), basename(pkg.directory));
-    return { ...source, package: pkg.name };
-}
 export default {
     name: 'zip',
     usage: 'zip [<source-dir>] [options] | zip --package <name> [options]',
@@ -135,18 +42,24 @@ Options:
   --checksums                 Also write the checksums manifest of the archived
                               files next to the ZIP, with .checksums.json
                               instead of .zip
-  --sign                      Also sign the ZIP and the checksums manifest with
-                              the ${SIGNING_KEY_ENV} key, like
-                              "wp-release sign", writing a WordPress .sig next
-                              to each
+  --checksums-file <file>      Relative manifest filename; implies checksums.
+                              Beside the ZIP, or inside its package root with
+                              --embed-checksums. No absolute paths or dot segments.
+  --checksums-format <format>  wordpress-json (default) or sha256sum
+  --checksums-algorithms <names> md5,sha256 (default), comma-separated or repeated
+  --embed-checksums            Embed manifest instead of writing it beside ZIP
+  --no-embed-checksums         Override embedding configured in integrity
+  --sign-checksums             Sign the manifest only, before embedding it
+  --no-sign-checksums          Override configured manifest signing
+  --sign                      Sign only the ZIP with the ${SIGNING_KEY_ENV} key
   --sign-format <names>       Signature formats of --sign, comma-separated or
                               repeated, like wordpress,minisign,ssh, as the
                               --format of "wp-release sign" (default:
-                              wordpress); implies --sign
+                              wordpress); requires --sign or --sign-checksums
   --force                     Overwrite existing output files
 
-Entries are sorted and use a fixed timestamp and file mode, so the same files
-always give the same ZIP.
+Entries are sorted and use a fixed timestamp and file mode. Embedded minisign
+signatures include their signing time; other built-in metadata is deterministic.
 
 Examples:
   wp-release zip dist --slug my-plugin --checksums
@@ -163,9 +76,14 @@ Examples:
         ...sourceDirArgs,
         ...fileSelectionArgs,
         package: { type: 'string' },
-        checksums: { type: 'boolean' },
+        ...checksumSigningArgs,
+        'checksums-file': { type: 'string' },
+        'checksums-format': { type: 'string' },
+        'checksums-algorithms': { type: 'string', multiple: true },
+        'embed-checksums': { type: 'boolean' },
+        'no-embed-checksums': { type: 'boolean' },
+        'no-sign-checksums': { type: 'boolean' },
         sign: { type: 'boolean' },
-        'sign-format': { type: 'string', multiple: true },
         force: { type: 'boolean' },
     },
     async run({ values, positionals, cwd, configFile, logger, }) {
@@ -179,21 +97,68 @@ Examples:
             output: getString(values, 'output'),
             filename: `${filename}.zip`,
         });
+        const loaded = await loadChangesetConfig({ cwd, configFile });
+        const configured = loaded?.config.integrity;
+        const algorithms = getStrings(values, 'checksums-algorithms').flatMap((value) => value.split(','));
+        const integrity = {
+            ...configured,
+            codec: getString(values, 'checksums-format') ?? configured?.codec,
+            ...(algorithms.length
+                ? { algorithms: algorithms }
+                : {}),
+        };
+        const codec = resolveManifestCodec(integrity.codec);
+        const embed = !getBoolean(values, 'no-embed-checksums') &&
+            (getBoolean(values, 'embed-checksums') ||
+                Boolean(configured?.embed));
+        const checksumsFile = checkChecksumsFile(getString(values, 'checksums-file') ??
+            configured?.file ??
+            (codec.id === 'wordpress-json'
+                ? basename(getChecksumsPath(zipPath))
+                : codec.filename));
+        const manifestSign = !getBoolean(values, 'no-sign-checksums') &&
+            (getBoolean(values, 'sign-checksums') ||
+                Boolean(configured?.sign));
+        const checksums = getBoolean(values, 'checksums') ||
+            embed ||
+            manifestSign ||
+            Boolean(getString(values, 'checksums-file') ?? configured?.file);
         const signFormats = getStrings(values, 'sign-format');
-        const signing = getBoolean(values, 'sign') || signFormats.length
-            ? {
-                paths: [
-                    zipPath,
-                    ...(getBoolean(values, 'checksums')
-                        ? [getChecksumsPath(zipPath)]
-                        : []),
-                ],
-                formats: parseSignatureFormats(signFormats),
-                force: getBoolean(values, 'force'),
-            }
+        const configuredFormats = configured?.sign
+            ? configured.sign.formats ?? []
+            : [];
+        const formats = parseSignatureFormats(signFormats.length ? signFormats : configuredFormats);
+        if (signFormats.length &&
+            !manifestSign &&
+            !getBoolean(values, 'sign')) {
+            throw new ValidationError('--sign-format requires --sign or --sign-checksums; it does not enable signing.');
+        }
+        const signing = getBoolean(values, 'sign')
+            ? getArtifactSigning({
+                ...values,
+                'sign-checksums': false,
+                'sign-format': formats,
+            }, {
+                artifact: zipPath,
+                checksums: resolve(dirname(zipPath), checksumsFile),
+            })
             : undefined;
-        if (signing) {
-            checkSigningInput(signing);
+        const externalManifest = checksums && !embed
+            ? resolve(dirname(zipPath), checksumsFile)
+            : undefined;
+        const artifacts = [
+            zipPath,
+            ...(externalManifest ? [externalManifest] : []),
+            ...(signing
+                ? formats.map((format) => getSignaturePath(zipPath, format))
+                : []),
+            ...(externalManifest && manifestSign
+                ? formats.map((format) => getSignaturePath(externalManifest, format))
+                : []),
+        ];
+        if (new Set(artifacts).size !== artifacts.length ||
+            artifacts.some((path, index) => artifacts.some((other, otherIndex) => index !== otherIndex && other.startsWith(path + sep)))) {
+            throw new ValidationError('ZIP, manifest and signature destinations must be distinct.');
         }
         const zipped = await zipPackage({
             sourceDir: source.sourceDir,
@@ -205,7 +170,11 @@ Examples:
             slug: source.slug,
             version: source.version,
             ...(source.type ? { type: source.type } : {}),
-            checksums: getBoolean(values, 'checksums'),
+            checksums,
+            checksumsFile: checksums ? checksumsFile : undefined,
+            embedChecksums: embed,
+            integrity,
+            signChecksums: manifestSign ? formats : undefined,
             force: getBoolean(values, 'force'),
         });
         logger.debug(`Archived ${zipped.files} files from ${source.sourceDir}.`);
@@ -219,9 +188,18 @@ Examples:
         signed?.signatures.forEach((path) => logger.info(path));
         const result = {
             ...zipped,
+            ...(zipped.checksumsSigning
+                ? {
+                    signatures: zipped.checksumsSignatures,
+                    publicKey: zipped.checksumsSigning.publicKey,
+                }
+                : {}),
             ...(signed
                 ? {
-                    signatures: signed.signatures,
+                    signatures: [
+                        ...signed.signatures,
+                        ...(zipped.checksumsSignatures ?? []),
+                    ],
                     publicKey: signed.publicKey,
                 }
                 : {}),
@@ -230,6 +208,13 @@ Examples:
             ...(source.package ? { package: source.package } : {}),
         };
         logger.summary((context) => getZipSummary(context, result));
+        const checksumsSigning = zipped.checksumsSigning;
+        if (checksumsSigning) {
+            logger.summary((context) => getSignSummary(context, {
+                ...checksumsSigning,
+                formats,
+            }));
+        }
         if (signed) {
             logger.summary((context) => getSignSummary(context, signed));
         }

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>;