@wpelevator/wp-release 0.4.0 → 0.5.0

package/dist/errors.d.ts

@@ -1,9 +1,27 @@
+/**
+ * One failed check, with the file and line it's about when there is one.
+ */
+export interface Problem {
+    /** Description of the problem. */
+    message: string;
+    /** File the problem is in, absolute or relative to the working directory. */
+    file?: string | null;
+    /** Line in the file, starting at 1. */
+    line?: number | null;
+    /** Short title of the kind of problem, like "Version mismatch". */
+    title?: string;
+}
 /**
  * Invalid options or failed release checks, reported with exit code 2.
+ * Failed checks can list their problems, so that each one is reported on its
+ * own file and line.
  */
 export declare class ValidationError extends Error {
     name: string;
     exitCode: number;
+    /** Each failed check, empty when the message is all there is. */
+    readonly problems: Problem[];
+    constructor(message: string, problems?: Problem[]);
 }
 /**
  * Missing SVN credentials or a failed login or permission check, reported

package/dist/errors.js

@@ -1,9 +1,17 @@
 /**
  * Invalid options or failed release checks, reported with exit code 2.
+ * Failed checks can list their problems, so that each one is reported on its
+ * own file and line.
  */
 export class ValidationError extends Error {
     name = 'ValidationError';
     exitCode = 2;
+    /** Each failed check, empty when the message is all there is. */
+    problems;
+    constructor(message, problems = []) {
+        super(message);
+        this.problems = problems;
+    }
 }
 /**
  * Missing SVN credentials or a failed login or permission check, reported

package/dist/github-actions-writer.d.ts

@@ -0,0 +1,52 @@
+import type { Annotation, LogEntry, LogWriter, OutputStream, SummaryBuilder } from './logger.ts';
+export interface GitHubActionsWriterOptions {
+    /** Stream for regular output. */
+    stdout?: OutputStream;
+    /** Stream for warnings and errors. */
+    stderr?: OutputStream;
+    /**
+     * Directory that annotation and summary paths are relative to, defaults
+     * to GITHUB_WORKSPACE or the working directory.
+     */
+    workspace?: string;
+    /**
+     * File that summaries are appended to, defaults to GITHUB_STEP_SUMMARY.
+     * Null turns summaries off.
+     */
+    summaryPath?: string | null;
+}
+/**
+ * Writer that prints GitHub Actions workflow commands, so that notices,
+ * warnings and errors are annotations on the run and on the files they're
+ * about, and appends summaries to the job summary.
+ */
+export declare class GitHubActionsWriter implements LogWriter {
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    readonly workspace: string;
+    readonly summaryPath: string | null;
+    constructor({ stdout, stderr, workspace, summaryPath, }?: GitHubActionsWriterOptions);
+    write({ level, message, annotation }: LogEntry): void;
+    startGroup(title: string): void;
+    endGroup(): void;
+    summary(build: SummaryBuilder): void;
+    /**
+     * Format a workflow command like
+     * "::error file=my-plugin.php,line=3,title=Version mismatch::message".
+     *
+     * @param name       Command name.
+     * @param message    Message.
+     * @param annotation File, line and title of the annotation.
+     * @return Workflow command with a line break.
+     */
+    formatCommand(name: string, message: string, annotation?: Annotation): string;
+    /**
+     * Get the path of an annotation file relative to the workspace. GitHub
+     * only links files of the repository, so files outside the workspace,
+     * like an extracted ZIP in a temporary directory, get no file.
+     *
+     * @param file File path, absolute or relative to the working directory.
+     * @return Path with forward slashes, or null when it's outside the workspace.
+     */
+    getAnnotationFile(file?: string | null): string | null;
+}

package/dist/github-actions-writer.js

@@ -0,0 +1,94 @@
+import { appendFileSync } from 'node:fs';
+import { getWorkspacePath } from "./summary.js";
+/**
+ * Escape the message of a workflow command, so that a multi-line message
+ * stays one annotation.
+ *
+ * @param text Message.
+ * @return Escaped message.
+ */
+function escapeData(text) {
+    return text
+        .replaceAll('%', '%25')
+        .replaceAll('\r', '%0D')
+        .replaceAll('\n', '%0A');
+}
+/**
+ * Escape a workflow command property like a file path or title.
+ *
+ * @param text Property value.
+ * @return Escaped value.
+ */
+function escapeProperty(text) {
+    return escapeData(text).replaceAll(':', '%3A').replaceAll(',', '%2C');
+}
+/**
+ * Writer that prints GitHub Actions workflow commands, so that notices,
+ * warnings and errors are annotations on the run and on the files they're
+ * about, and appends summaries to the job summary.
+ */
+export class GitHubActionsWriter {
+    stdout;
+    stderr;
+    workspace;
+    summaryPath;
+    constructor({ stdout = process.stdout, stderr = process.stderr, workspace = process.env.GITHUB_WORKSPACE || process.cwd(), summaryPath = process.env.GITHUB_STEP_SUMMARY || null, } = {}) {
+        this.stdout = stdout;
+        this.stderr = stderr;
+        this.workspace = workspace;
+        this.summaryPath = summaryPath;
+    }
+    write({ level, message, annotation }) {
+        const stream = 'warning' === level || 'error' === level
+            ? this.stderr
+            : this.stdout;
+        stream.write('info' === level
+            ? `${message}\n`
+            : this.formatCommand(level, message, annotation));
+    }
+    startGroup(title) {
+        this.stdout.write(`::group::${escapeData(title)}\n`);
+    }
+    endGroup() {
+        this.stdout.write('::endgroup::\n');
+    }
+    summary(build) {
+        if (this.summaryPath) {
+            // A blank line keeps the Markdown of separate summaries apart.
+            appendFileSync(this.summaryPath, `${build({ workspace: this.workspace }).trimEnd()}\n\n`);
+        }
+    }
+    /**
+     * Format a workflow command like
+     * "::error file=my-plugin.php,line=3,title=Version mismatch::message".
+     *
+     * @param name       Command name.
+     * @param message    Message.
+     * @param annotation File, line and title of the annotation.
+     * @return Workflow command with a line break.
+     */
+    formatCommand(name, message, annotation = {}) {
+        const file = this.getAnnotationFile(annotation.file);
+        const properties = [
+            file ? `file=${escapeProperty(file)}` : '',
+            file && annotation.line ? `line=${annotation.line}` : '',
+            annotation.title
+                ? `title=${escapeProperty(annotation.title)}`
+                : '',
+        ]
+            .filter(Boolean)
+            .join(',');
+        return `::${name}${properties ? ` ${properties}` : ''}::${escapeData(message)}\n`;
+    }
+    /**
+     * Get the path of an annotation file relative to the workspace. GitHub
+     * only links files of the repository, so files outside the workspace,
+     * like an extracted ZIP in a temporary directory, get no file.
+     *
+     * @param file File path, absolute or relative to the working directory.
+     * @return Path with forward slashes, or null when it's outside the workspace.
+     */
+    getAnnotationFile(file) {
+        return file ? getWorkspacePath(this.workspace, file) : null;
+    }
+}

package/dist/index.d.ts

@@ -1,17 +1,19 @@
 export { run, execute, commands, getHelp, getCommandHelp } from './cli.ts';
+export { logError, logProblems } from './report.ts';
 export { getDeployInputFromArgs } from './commands/deploy-svn.ts';
 export { ValidationError, CredentialsError } from './errors.ts';
-export { Logger } from './logger.ts';
+export { Logger, TextWriter } from './logger.ts';
+export { GitHubActionsWriter } from './github-actions-writer.ts';
 export { SVN_URL, isPrerelease, normalizeTag, isTagRef, isValidSlug, isValidVersion, getDeployOptionErrors, getDeployOptionWarnings, resolveDeployOptions, } from './deploy-options.ts';
 export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules, selectFiles, } from './file-selection.ts';
 export { FILENAME_FORMAT, formatFilename } from './filename.ts';
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from './checksums.ts';
-export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from './package-meta.ts';
+export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findFileHeaderLine, findReadmeHeaderLine, findMainPluginFile, readPackageMeta, } from './package-meta.ts';
 export { SIGNATURE_EXTENSION, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, getPublicKey, getFileDigest, signFile, writeSignature, verifyFileSignature, } from './signing.ts';
 export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from './zip.ts';
 export { isUrl, downloadFile } from './download.ts';
 export { readZipEntries, getZipEntryErrors, extractZip } from './unzip.ts';
-export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from './version-check.ts';
+export { GIT_TAG_FORMAT, VersionMismatchError, getGitTagVersion, findConstantValues, findConstantDefinitions, findVersionMismatches, getVersionMismatchProblems, } from './version-check.ts';
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from './svn.ts';
 export { syncDirectory, copyFileIfChanged } from './sync.ts';
 export { ASSET_MIME_TYPES, SvnDeploy } from './svn-deploy.ts';
@@ -21,7 +23,9 @@ export type { SignResult } from './commands/sign.ts';
 export type { ZipResult } from './commands/zip.ts';
 export type { Command, CommandContext, CommandOutcome, ParsedValues, } from './commands/command.ts';
 export type { DeployArgsInput } from './commands/deploy-svn.ts';
-export type { LoggerOptions, OutputStream } from './logger.ts';
+export type { Annotation, LogEntry, LogLevel, LogWriter, LoggerOptions, OutputStream, SummaryBuilder, TextWriterOptions, } from './logger.ts';
+export type { GitHubActionsWriterOptions } from './github-actions-writer.ts';
+export type { Problem } from './errors.ts';
 export type { DeployInput, DeployOptions } from './deploy-options.ts';
 export type { FileRules, FileSelection, FileSelectionInput, } from './file-selection.ts';
 export type { FilenameValues } from './filename.ts';
@@ -32,4 +36,5 @@ export type { ExtractZipInput, ZipEntryInfo, ZipEntryType } from './unzip.ts';
 export type { FindVersionMismatchesInput, GitTagInput, VersionCheckResult, VersionMismatch, } from './version-check.ts';
 export type { SvnCheckoutInput, SvnCommandInput, SvnCommandOutput, SvnCommitInput, SvnCopyInput, SvnDepth, SvnOptions, SvnPathsInput, SvnPropsetInput, SvnRunner, SvnStatusEntry, SvnStatusType, SvnUpdateInput, } from './svn.ts';
 export type { SyncDirectoryInput, SyncResult } from './sync.ts';
+export type { SummaryContext } from './summary.ts';
 export type { CheckoutPath, DeployResult } from './svn-deploy.ts';

package/dist/index.js

@@ -1,17 +1,19 @@
 export { run, execute, commands, getHelp, getCommandHelp } from "./cli.js";
+export { logError, logProblems } from "./report.js";
 export { getDeployInputFromArgs } from "./commands/deploy-svn.js";
 export { ValidationError, CredentialsError } from "./errors.js";
-export { Logger } from "./logger.js";
+export { Logger, TextWriter } from "./logger.js";
+export { GitHubActionsWriter } from "./github-actions-writer.js";
 export { SVN_URL, isPrerelease, normalizeTag, isTagRef, isValidSlug, isValidVersion, getDeployOptionErrors, getDeployOptionWarnings, resolveDeployOptions, } from "./deploy-options.js";
 export { DISTIGNORE_FILENAME, parseExclude, resolveFileSelection, loadFileRules, selectFiles, } from "./file-selection.js";
 export { FILENAME_FORMAT, formatFilename } from "./filename.js";
 export { CHECKSUMS_EXTENSION, CHECKSUM_ALGORITHMS, hashFile, hashFiles, createChecksums, writeChecksums, readChecksums, parseChecksums, compareChecksums, verifyChecksums, } from "./checksums.js";
-export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findMainPluginFile, readPackageMeta, } from "./package-meta.js";
+export { HEADER_BYTES, PLUGIN_HEADERS, THEME_HEADERS, README_HEADERS, README_FILENAMES, parseFileHeaders, parseReadmeHeaders, readFileStart, findFileHeaderLine, findReadmeHeaderLine, findMainPluginFile, readPackageMeta, } from "./package-meta.js";
 export { SIGNATURE_EXTENSION, SIGNING_KEY_ENV, parseSigningKey, parsePublicKey, getPublicKey, getFileDigest, signFile, writeSignature, verifyFileSignature, } from "./signing.js";
 export { ZIP_MTIME, ZIP_FILE_MODE, createZip } from "./zip.js";
 export { isUrl, downloadFile } from "./download.js";
 export { readZipEntries, getZipEntryErrors, extractZip } from "./unzip.js";
-export { GIT_TAG_FORMAT, getGitTagVersion, findConstantValues, findVersionMismatches, } from "./version-check.js";
+export { GIT_TAG_FORMAT, VersionMismatchError, getGitTagVersion, findConstantValues, findConstantDefinitions, findVersionMismatches, getVersionMismatchProblems, } from "./version-check.js";
 export { Svn, SvnError, createSvnRunner, parseStatus, toSvnPath, } from "./svn.js";
 export { syncDirectory, copyFileIfChanged } from "./sync.js";
 export { ASSET_MIME_TYPES, SvnDeploy } from "./svn-deploy.js";

package/dist/logger.d.ts

@@ -1,36 +1,108 @@
+import type { SummaryContext } from './summary.ts';
 /**
  * Stream that output is written to, like process.stdout.
  */
 export interface OutputStream {
     write: (text: string) => unknown;
 }
-export interface LoggerOptions {
-    /** Use GitHub Actions workflow commands. */
-    ci?: boolean;
-    /** Print errors only. */
-    quiet?: boolean;
-    /** Print debug messages. */
-    verbose?: boolean;
+/**
+ * Log levels, from the most to the least verbose.
+ */
+export type LogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error';
+/**
+ * File and title that a message is about, which writers like the GitHub
+ * Actions writer show as an annotation on the file.
+ */
+export interface Annotation {
+    /** File the message is about, absolute or relative to the working directory. */
+    file?: string | null;
+    /** Line in the file, starting at 1. */
+    line?: number | null;
+    /** Annotation title. */
+    title?: string;
+}
+/**
+ * A message passed from the logger to its writer.
+ */
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    annotation: Annotation;
+}
+/**
+ * Builds the Markdown of a summary for the context of a writer.
+ */
+export type SummaryBuilder = (context: SummaryContext) => string;
+/**
+ * Destination of the log, like a terminal or a CI system. The logger decides
+ * which messages to write, and the writer decides how they look.
+ */
+export interface LogWriter {
+    /** Write a message. */
+    write: (entry: LogEntry) => void;
+    /** Start a collapsible group of messages. */
+    startGroup: (title: string) => void;
+    /** End the group started last. */
+    endGroup: () => void;
+    /** Add to the summary of the run, for writers that have one. */
+    summary: (build: SummaryBuilder) => void;
+}
+export interface TextWriterOptions {
     /** Stream for regular output. */
     stdout?: OutputStream;
     /** Stream for warnings and errors. */
     stderr?: OutputStream;
 }
 /**
- * Logger that prints plain text locally and GitHub Actions workflow commands in CI.
+ * Writer that prints plain text, for terminals and CI systems without
+ * special log formats.
+ */
+export declare class TextWriter implements LogWriter {
+    readonly stdout: OutputStream;
+    readonly stderr: OutputStream;
+    constructor({ stdout, stderr, }?: TextWriterOptions);
+    write({ level, message }: LogEntry): void;
+    startGroup(title: string): void;
+    endGroup(): void;
+    summary(): void;
+}
+export interface LoggerOptions {
+    /** Writer for the messages, a TextWriter by default. */
+    writer?: LogWriter;
+    /** Print errors and warnings only. */
+    quiet?: boolean;
+    /** Print debug messages. */
+    verbose?: boolean;
+}
+/**
+ * Logger that filters messages by level and passes them to a writer, which
+ * formats them for a terminal or a CI system.
  */
 export declare class Logger {
-    readonly ci: boolean;
+    readonly writer: LogWriter;
     readonly quiet: boolean;
     readonly verbose: boolean;
-    readonly stdout: OutputStream;
-    readonly stderr: OutputStream;
-    constructor({ ci, quiet, verbose, stdout, stderr, }?: LoggerOptions);
-    info(message: string): void;
+    constructor({ writer, quiet, verbose, }?: LoggerOptions);
+    /**
+     * Write a message unless its level is filtered out.
+     *
+     * @param level      Log level.
+     * @param message    Message.
+     * @param annotation File, line and title the message is about.
+     */
+    log(level: LogLevel, message: string, annotation?: Annotation): void;
     debug(message: string): void;
-    notice(message: string): void;
-    warning(message: string): void;
-    error(message: string): void;
+    info(message: string): void;
+    notice(message: string, annotation?: Annotation): void;
+    warning(message: string, annotation?: Annotation): void;
+    error(message: string, annotation?: Annotation): void;
+    /**
+     * Add to the summary of the run. Only writers with a summary, like the
+     * GitHub Actions job summary, call the builder.
+     *
+     * @param build Builds the summary Markdown.
+     */
+    summary(build: SummaryBuilder): void;
     /**
      * Run a callback inside a collapsible log group.
      *

package/dist/logger.js

@@ -1,39 +1,85 @@
 /**
- * Logger that prints plain text locally and GitHub Actions workflow commands in CI.
+ * Writer that prints plain text, for terminals and CI systems without
+ * special log formats.
+ */
+export class TextWriter {
+    stdout;
+    stderr;
+    constructor({ stdout = process.stdout, stderr = process.stderr, } = {}) {
+        this.stdout = stdout;
+        this.stderr = stderr;
+    }
+    write({ level, message }) {
+        const prefixes = {
+            warning: 'Warning: ',
+            error: 'Error: ',
+        };
+        const stream = 'warning' === level || 'error' === level
+            ? this.stderr
+            : this.stdout;
+        stream.write(`${prefixes[level] ?? ''}${message}\n`);
+    }
+    startGroup(title) {
+        this.stdout.write(`== ${title}\n`);
+    }
+    endGroup() { }
+    summary() { }
+}
+/**
+ * Logger that filters messages by level and passes them to a writer, which
+ * formats them for a terminal or a CI system.
  */
 export class Logger {
-    ci;
+    writer;
     quiet;
     verbose;
-    stdout;
-    stderr;
-    constructor({ ci = 'true' === process.env.GITHUB_ACTIONS, quiet = false, verbose = false, stdout = process.stdout, stderr = process.stderr, } = {}) {
-        this.ci = ci;
+    constructor({ writer = new TextWriter(), quiet = false, verbose = false, } = {}) {
+        this.writer = writer;
         this.quiet = quiet;
         this.verbose = verbose;
-        this.stdout = stdout;
-        this.stderr = stderr;
     }
-    info(message) {
-        if (!this.quiet) {
-            this.stdout.write(`${message}\n`);
+    /**
+     * Write a message unless its level is filtered out.
+     *
+     * @param level      Log level.
+     * @param message    Message.
+     * @param annotation File, line and title the message is about.
+     */
+    log(level, message, annotation = {}) {
+        const shown = {
+            debug: this.verbose && !this.quiet,
+            info: !this.quiet,
+            notice: !this.quiet,
+            warning: true,
+            error: true,
+        }[level];
+        if (shown) {
+            this.writer.write({ level, message, annotation });
         }
     }
     debug(message) {
-        if (this.verbose && !this.quiet) {
-            this.stdout.write(this.ci ? `::debug::${message}\n` : `${message}\n`);
-        }
+        this.log('debug', message);
     }
-    notice(message) {
-        if (!this.quiet) {
-            this.stdout.write(this.ci ? `::notice::${message}\n` : `${message}\n`);
-        }
+    info(message) {
+        this.log('info', message);
     }
-    warning(message) {
-        this.stderr.write(this.ci ? `::warning::${message}\n` : `Warning: ${message}\n`);
+    notice(message, annotation = {}) {
+        this.log('notice', message, annotation);
     }
-    error(message) {
-        this.stderr.write(this.ci ? `::error::${message}\n` : `Error: ${message}\n`);
+    warning(message, annotation = {}) {
+        this.log('warning', message, annotation);
+    }
+    error(message, annotation = {}) {
+        this.log('error', message, annotation);
+    }
+    /**
+     * Add to the summary of the run. Only writers with a summary, like the
+     * GitHub Actions job summary, call the builder.
+     *
+     * @param build Builds the summary Markdown.
+     */
+    summary(build) {
+        this.writer.summary(build);
     }
     /**
      * Run a callback inside a collapsible log group.
@@ -43,13 +89,15 @@ export class Logger {
      * @return Callback result.
      */
     async group(title, callback) {
-        this.info(this.ci ? `::group::${title}` : `== ${title}`);
+        if (!this.quiet) {
+            this.writer.startGroup(title);
+        }
         try {
             return await callback();
         }
         finally {
-            if (this.ci) {
-                this.info('::endgroup::');
+            if (!this.quiet) {
+                this.writer.endGroup();
             }
         }
     }

package/dist/package-meta.d.ts

@@ -76,6 +76,23 @@ export interface ReadPackageMetaInput {
  * @return Non-empty header values.
  */
 export declare function parseFileHeaders(input: ParseFileHeadersInput): HeaderValues;
+/**
+ * Find the line of a file header like "Version: 1.2.0", matched the same way
+ * as parseFileHeaders().
+ *
+ * @param contents File contents.
+ * @param header   Header name.
+ * @return Line number starting at 1, or null when the header isn't there.
+ */
+export declare function findFileHeaderLine(contents: string, header: string): number | null;
+/**
+ * Get the line number of a position in a text.
+ *
+ * @param contents Text.
+ * @param index    Character position.
+ * @return Line number starting at 1.
+ */
+export declare function getLineNumber(contents: string, index: number): number;
 /**
  * Parse the headers of a readme.txt or readme.md, the "Key: value" lines
  * between the title and the first section. Markdown emphasis around the
@@ -85,6 +102,15 @@ export declare function parseFileHeaders(input: ParseFileHeadersInput): HeaderVa
  * @return Non-empty header values keyed by the names in README_HEADERS.
  */
 export declare function parseReadmeHeaders(contents: string): HeaderValues;
+/**
+ * Find the line of a readme header like "Stable tag: 1.2.0", the line that
+ * parseReadmeHeaders() reads the value from.
+ *
+ * @param contents Readme contents.
+ * @param header   Header name from README_HEADERS.
+ * @return Line number starting at 1, or null when the header isn't there.
+ */
+export declare function findReadmeHeaderLine(contents: string, header: string): number | null;
 /**
  * Read the start of a file, where WordPress looks for the headers.
  *

package/dist/package-meta.js

@@ -82,11 +82,36 @@ export function parseFileHeaders(input) {
     ]);
     return Object.fromEntries(entries.filter(([, value]) => value));
 }
+function getFileHeaderPattern(header) {
+    return new RegExp(`^(?:[ \\t]*<\\?php)?[ \\t/*#@]*${escapeRegExp(header)}:(.*)$`, 'mi');
+}
 function matchFileHeader(contents, header) {
-    const pattern = new RegExp(`^(?:[ \\t]*<\\?php)?[ \\t/*#@]*${escapeRegExp(header)}:(.*)$`, 'mi');
-    const value = pattern.exec(contents)?.[1] ?? '';
+    const value = getFileHeaderPattern(header).exec(contents)?.[1] ?? '';
     return value.replace(/\s*(?:\*\/|\?>).*/, '').trim();
 }
+/**
+ * Find the line of a file header like "Version: 1.2.0", matched the same way
+ * as parseFileHeaders().
+ *
+ * @param contents File contents.
+ * @param header   Header name.
+ * @return Line number starting at 1, or null when the header isn't there.
+ */
+export function findFileHeaderLine(contents, header) {
+    const normalized = contents.replace(/\r\n?/g, '\n');
+    const match = getFileHeaderPattern(header).exec(normalized);
+    return match ? getLineNumber(normalized, match.index) : null;
+}
+/**
+ * Get the line number of a position in a text.
+ *
+ * @param contents Text.
+ * @param index    Character position.
+ * @return Line number starting at 1.
+ */
+export function getLineNumber(contents, index) {
+    return contents.slice(0, index).split('\n').length;
+}
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -99,19 +124,49 @@ function escapeRegExp(text) {
  * @return Non-empty header values keyed by the names in README_HEADERS.
  */
 export function parseReadmeHeaders(contents) {
-    const lines = contents.replace(/\r\n?/g, '\n').split('\n');
-    const firstSection = lines.findIndex((line, index) => index > 0 && /^\s*(==|##)/.test(line));
-    const headerLines = lines.slice(0, -1 === firstSection ? lines.length : firstSection);
     const values = {};
-    headerLines.forEach((line) => {
-        const match = /^[\s*_-]*([^:*_]+?)[*_]*\s*:[*_]*\s*(.*?)\s*$/.exec(line);
-        const header = README_HEADERS.find((name) => name.toLowerCase() === match?.[1]?.toLowerCase());
-        if (header && match?.[2] && !Object.hasOwn(values, header)) {
-            values[header] = match[2];
+    getReadmeHeaderLines(contents).forEach((line) => {
+        const match = matchReadmeHeader(line);
+        if (match && !Object.hasOwn(values, match.header)) {
+            values[match.header] = match.value;
         }
     });
     return values;
 }
+/**
+ * Find the line of a readme header like "Stable tag: 1.2.0", the line that
+ * parseReadmeHeaders() reads the value from.
+ *
+ * @param contents Readme contents.
+ * @param header   Header name from README_HEADERS.
+ * @return Line number starting at 1, or null when the header isn't there.
+ */
+export function findReadmeHeaderLine(contents, header) {
+    const index = getReadmeHeaderLines(contents).findIndex((line) => header === matchReadmeHeader(line)?.header);
+    return -1 === index ? null : index + 1;
+}
+/**
+ * Get the readme lines before the first section, where the headers are.
+ *
+ * @param contents Readme contents.
+ * @return Lines from the first line.
+ */
+function getReadmeHeaderLines(contents) {
+    const lines = contents.replace(/\r\n?/g, '\n').split('\n');
+    const firstSection = lines.findIndex((line, index) => index > 0 && /^\s*(==|##)/.test(line));
+    return lines.slice(0, -1 === firstSection ? lines.length : firstSection);
+}
+/**
+ * Match a readme header line. Markdown emphasis around the name is ignored.
+ *
+ * @param line Readme line.
+ * @return Header name from README_HEADERS and its value, or null when the line isn't a non-empty header.
+ */
+function matchReadmeHeader(line) {
+    const match = /^[\s*_-]*([^:*_]+?)[*_]*\s*:[*_]*\s*(.*?)\s*$/.exec(line);
+    const header = README_HEADERS.find((name) => name.toLowerCase() === match?.[1]?.toLowerCase());
+    return header && match?.[2] ? { header, value: match[2] } : null;
+}
 /**
  * Read the start of a file, where WordPress looks for the headers.
  *