@wp-typia/project-tools 0.24.4 → 0.24.5

package/dist/runtime/shared/package-versions.js

@@ -0,0 +1,259 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { getOptionalNodeErrorCode } from './fs-async.js';
+import { safeJsonParse } from './json-utils.js';
+import { PROJECT_TOOLS_PACKAGE_ROOT } from '../templates/template-registry.js';
+const require = createRequire(import.meta.url);
+const DEFAULT_VERSION_RANGE = '^0.0.0';
+const DEFAULT_EXACT_VERSION = '0.0.0';
+const DEFAULT_TSX_PACKAGE_VERSION = '^4.20.5';
+const DEFAULT_TYPIA_UNPLUGIN_PACKAGE_VERSION = '^12.0.1';
+/**
+ * Explicit fallback ranges for managed WordPress-facing workspace dependencies.
+ *
+ * These remain centralized here even when individual scaffold flows resolve a
+ * fresher local or installed manifest version first, so add-command defaults do
+ * not drift across runtime modules.
+ */
+export const DEFAULT_WORDPRESS_ABILITIES_VERSION = '^0.10.0';
+export const DEFAULT_WORDPRESS_CORE_ABILITIES_VERSION = '^0.9.0';
+export const DEFAULT_WORDPRESS_CORE_DATA_VERSION = '~7.46.0';
+export const DEFAULT_WORDPRESS_DATA_VERSION = '~10.46.0';
+export const DEFAULT_WORDPRESS_DATAVIEWS_VERSION = '~14.3.0';
+export const DEFAULT_WORDPRESS_ENV_VERSION = '^11.2.0';
+export const DEFAULT_WP_TYPIA_DATAVIEWS_VERSION = '^0.1.1';
+let cachedPackageVersions = null;
+function normalizeVersionRange(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return DEFAULT_VERSION_RANGE;
+    }
+    if (trimmed.startsWith('workspace:')) {
+        return DEFAULT_VERSION_RANGE;
+    }
+    return /^[~^<>=]/.test(trimmed) ? trimmed : `^${trimmed}`;
+}
+function normalizeExactVersion(value) {
+    const trimmed = value?.trim();
+    if (!trimmed) {
+        return DEFAULT_EXACT_VERSION;
+    }
+    if (trimmed.startsWith('workspace:')) {
+        return DEFAULT_EXACT_VERSION;
+    }
+    return trimmed.replace(/^[~^<>=]+/, '');
+}
+function normalizeVersionRangeWithFallback(value, fallback) {
+    const normalized = normalizeVersionRange(value);
+    return normalized === DEFAULT_VERSION_RANGE ? fallback : normalized;
+}
+function createContentFingerprint(source) {
+    let hash = 2166136261;
+    for (let index = 0; index < source.length; index += 1) {
+        hash ^= source.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0).toString(16);
+}
+function readPackageManifestFile(packageJsonPath) {
+    const fileDescriptor = fs.openSync(packageJsonPath, 'r');
+    try {
+        // Keep cache metadata and manifest contents tied to one opened file, so a
+        // concurrent path replacement cannot mix stats from one manifest with
+        // contents from another. The content fingerprint remains the final guard.
+        const stats = fs.fstatSync(fileDescriptor);
+        const source = fs.readFileSync(fileDescriptor, 'utf8');
+        return { source, stats };
+    }
+    finally {
+        fs.closeSync(fileDescriptor);
+    }
+}
+function resolvePackageManifestLocation(packageJsonPath) {
+    try {
+        const { source, stats } = readPackageManifestFile(packageJsonPath);
+        return {
+            cacheKey: `file:${packageJsonPath}:${stats.ino}:${stats.mtimeMs}:${stats.ctimeMs}:${stats.size}:${createContentFingerprint(source)}`,
+            packageJsonPath,
+            source,
+        };
+    }
+    catch (error) {
+        if (getOptionalNodeErrorCode(error) === 'ENOENT') {
+            return {
+                cacheKey: `missing-file:${packageJsonPath}`,
+                packageJsonPath: null,
+                source: null,
+            };
+        }
+        throw error;
+    }
+}
+function readPackageManifest(location) {
+    if (!location.packageJsonPath || location.source === null) {
+        return null;
+    }
+    return safeJsonParse(location.source, {
+        context: 'package version manifest',
+        filePath: location.packageJsonPath,
+    });
+}
+function tryReadPackageManifest(location) {
+    if (!location) {
+        return null;
+    }
+    try {
+        return readPackageManifest(location);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveInstalledPackageManifestLocation(packageName) {
+    try {
+        return resolvePackageManifestLocation(require.resolve(`${packageName}/package.json`));
+    }
+    catch (error) {
+        if (getOptionalNodeErrorCode(error) === 'MODULE_NOT_FOUND') {
+            return {
+                cacheKey: `missing-module:${packageName}`,
+                packageJsonPath: null,
+                source: null,
+            };
+        }
+        throw error;
+    }
+}
+function composePackageVersionsCacheKey(locations) {
+    return locations.map((location) => location.cacheKey).join('|');
+}
+/**
+ * Resolve a managed package version range from linked workspace packages first,
+ * then installed package manifests, while preserving the shared normalization
+ * and manifest fingerprinting rules used by `getPackageVersions()`.
+ *
+ * @param packageName npm package whose manifest version should be consulted.
+ * @param fallback Canonical range to use when no usable manifest version exists.
+ * @param workspacePackageDirName Optional sibling monorepo package directory name.
+ * @returns A normalized semver range suitable for generated dependency entries.
+ */
+export function resolveManagedPackageVersionRange(options) {
+    const workspaceManifestLocation = options.workspacePackageDirName
+        ? resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', options.workspacePackageDirName, 'package.json'))
+        : null;
+    const installedManifestLocation = resolveInstalledPackageManifestLocation(options.packageName);
+    const workspaceManifest = tryReadPackageManifest(workspaceManifestLocation);
+    const installedManifest = tryReadPackageManifest(installedManifestLocation);
+    return normalizeVersionRangeWithFallback(workspaceManifest?.version ?? installedManifest?.version, options.fallback);
+}
+/**
+ * Clears the in-memory cache used by `getPackageVersions()`.
+ *
+ * Long-lived processes can call this after regenerating or updating package
+ * manifests when they want the next lookup to recompute version metadata
+ * synchronously from disk.
+ */
+export function clearPackageVersionsCache() {
+    cachedPackageVersions = null;
+}
+/**
+ * Backwards-compatible alias for integrations that adopted the original
+ * internal invalidation name before the public cache policy was documented.
+ */
+export function invalidatePackageVersionsCache() {
+    clearPackageVersionsCache();
+}
+/**
+ * Resolve package versions used in generated manifests and onboarding text.
+ *
+ * The lookup keeps a process-local cached result while recomputing manifest
+ * fingerprints on each call. When the relevant package metadata changes on
+ * disk, the cache key changes and the returned version object is refreshed.
+ */
+export function getPackageVersions() {
+    const createManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, 'package.json'));
+    const monorepoManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', '..', 'package.json'));
+    const blockRuntimeManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia-block-runtime', 'package.json'));
+    const blockTypesManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia-block-types', 'package.json'));
+    const wpTypiaManifestLocation = resolvePackageManifestLocation(path.join(PROJECT_TOOLS_PACKAGE_ROOT, '..', 'wp-typia', 'package.json'));
+    const installedProjectToolsManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/project-tools');
+    const installedApiClientManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/api-client');
+    const installedBlockRuntimeManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/block-runtime');
+    const installedBlockTypesManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/block-types');
+    const installedRestManifestLocation = resolveInstalledPackageManifestLocation('@wp-typia/rest');
+    const installedTsxManifestLocation = resolveInstalledPackageManifestLocation('tsx');
+    const installedTypiaManifestLocation = resolveInstalledPackageManifestLocation('typia');
+    const installedTypiaUnpluginManifestLocation = resolveInstalledPackageManifestLocation('@typia/unplugin');
+    const installedTypescriptManifestLocation = resolveInstalledPackageManifestLocation('typescript');
+    const installedWpTypiaManifestLocation = resolveInstalledPackageManifestLocation('wp-typia');
+    const cacheKey = composePackageVersionsCacheKey([
+        createManifestLocation,
+        monorepoManifestLocation,
+        blockRuntimeManifestLocation,
+        blockTypesManifestLocation,
+        wpTypiaManifestLocation,
+        installedProjectToolsManifestLocation,
+        installedApiClientManifestLocation,
+        installedBlockRuntimeManifestLocation,
+        installedBlockTypesManifestLocation,
+        installedRestManifestLocation,
+        installedTsxManifestLocation,
+        installedTypiaManifestLocation,
+        installedTypiaUnpluginManifestLocation,
+        installedTypescriptManifestLocation,
+        installedWpTypiaManifestLocation,
+    ]);
+    if (cachedPackageVersions?.cacheKey === cacheKey) {
+        return cachedPackageVersions.versions;
+    }
+    const createManifest = readPackageManifest(createManifestLocation) ??
+        readPackageManifest(installedProjectToolsManifestLocation) ??
+        {};
+    const monorepoManifest = readPackageManifest(monorepoManifestLocation) ?? {};
+    const blockRuntimeManifest = readPackageManifest(blockRuntimeManifestLocation) ??
+        readPackageManifest(installedBlockRuntimeManifestLocation) ??
+        {};
+    const blockTypesManifest = readPackageManifest(blockTypesManifestLocation) ??
+        readPackageManifest(installedBlockTypesManifestLocation) ??
+        {};
+    const wpTypiaManifest = readPackageManifest(wpTypiaManifestLocation) ??
+        readPackageManifest(installedWpTypiaManifestLocation) ??
+        {};
+    const blockRuntimeDependencyVersion = normalizeVersionRange(createManifest.dependencies?.['@wp-typia/block-runtime']);
+    const blockTypesDependencyVersion = normalizeVersionRange(createManifest.dependencies?.['@wp-typia/block-types']);
+    const versions = {
+        apiClientPackageVersion: normalizeVersionRange(createManifest.dependencies?.['@wp-typia/api-client'] ??
+            readPackageManifest(installedApiClientManifestLocation)?.version),
+        blockRuntimePackageVersion: blockRuntimeDependencyVersion !== DEFAULT_VERSION_RANGE
+            ? blockRuntimeDependencyVersion
+            : normalizeVersionRange(blockRuntimeManifest.version),
+        blockTypesPackageVersion: blockTypesDependencyVersion !== DEFAULT_VERSION_RANGE
+            ? blockTypesDependencyVersion
+            : normalizeVersionRange(blockTypesManifest.version),
+        projectToolsPackageVersion: normalizeVersionRange(createManifest.version),
+        restPackageVersion: normalizeVersionRange(createManifest.dependencies?.['@wp-typia/rest'] ??
+            readPackageManifest(installedRestManifestLocation)?.version),
+        tsxPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.tsx ??
+            monorepoManifest.devDependencies?.tsx ??
+            readPackageManifest(installedTsxManifestLocation)?.version, DEFAULT_TSX_PACKAGE_VERSION),
+        typiaPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.typia ??
+            monorepoManifest.devDependencies?.typia ??
+            createManifest.dependencies?.typia ??
+            readPackageManifest(installedTypiaManifestLocation)?.version, DEFAULT_VERSION_RANGE),
+        typiaUnpluginPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.['@typia/unplugin'] ??
+            monorepoManifest.devDependencies?.['@typia/unplugin'] ??
+            readPackageManifest(installedTypiaUnpluginManifestLocation)?.version, DEFAULT_TYPIA_UNPLUGIN_PACKAGE_VERSION),
+        typescriptPackageVersion: normalizeVersionRangeWithFallback(monorepoManifest.dependencies?.typescript ??
+            monorepoManifest.devDependencies?.typescript ??
+            createManifest.dependencies?.typescript ??
+            readPackageManifest(installedTypescriptManifestLocation)?.version, DEFAULT_VERSION_RANGE),
+        wpTypiaPackageExactVersion: normalizeExactVersion(wpTypiaManifest.version),
+        wpTypiaPackageVersion: normalizeVersionRange(wpTypiaManifest.version),
+    };
+    cachedPackageVersions = {
+        cacheKey,
+        versions,
+    };
+    return versions;
+}

package/dist/runtime/shared/php-utils.d.ts

@@ -0,0 +1,32 @@
+export type PhpFunctionRange = {
+    end: number;
+    source: string;
+    start: number;
+};
+export type PhpFunctionRangeOptions = {
+    includeTrailingNewlines?: boolean;
+};
+export type ReplacePhpFunctionDefinitionOptions = PhpFunctionRangeOptions & {
+    trimReplacementStart?: boolean;
+};
+export declare function escapeRegex(value: string): string;
+export declare function quotePhpString(value: string): string;
+export declare function hasPhpFunctionDefinition(source: string, functionName: string): boolean;
+/**
+ * Detect a PHP function call outside strings, comments, heredoc, and nowdoc blocks.
+ *
+ * @param source PHP source to scan.
+ * @param functionName Literal PHP function identifier to find.
+ * @returns Whether `source` contains a code-mode call to `functionName`.
+ */
+export declare function hasPhpFunctionCall(source: string, functionName: string): boolean;
+/**
+ * Locate a PHP function body without counting braces in non-code regions.
+ *
+ * @param source PHP source to scan.
+ * @param functionName Literal PHP function identifier to locate.
+ * @param options Range options such as trailing newline inclusion.
+ * @returns The matched {@link PhpFunctionRange}, or `null` when no safe range exists.
+ */
+export declare function findPhpFunctionRange(source: string, functionName: string, options?: PhpFunctionRangeOptions): PhpFunctionRange | null;
+export declare function replacePhpFunctionDefinition(source: string, functionName: string, replacement: string, options?: ReplacePhpFunctionDefinitionOptions): string | null;

package/dist/runtime/shared/php-utils.js

@@ -0,0 +1,382 @@
+export function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+export function quotePhpString(value) {
+    return `'${value.replace(/\\/gu, "\\\\").replace(/'/gu, "\\'")}'`;
+}
+export function hasPhpFunctionDefinition(source, functionName) {
+    return new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\(`, "u").test(source);
+}
+function isPhpIdentifierStart(character) {
+    return /^[A-Za-z_]$/u.test(character ?? "");
+}
+function isPhpIdentifierPart(character) {
+    return /^[A-Za-z0-9_]$/u.test(character ?? "");
+}
+function isPhpLineStart(source, index) {
+    return index === 0 || source[index - 1] === "\n";
+}
+function isPhpHorizontalWhitespace(character) {
+    return character === " " || character === "\t";
+}
+function isPhpWhitespace(character) {
+    return typeof character === "string" && /\s/u.test(character);
+}
+function findPhpLineBoundary(source, index) {
+    const newlineIndex = source.indexOf("\n", index);
+    if (newlineIndex === -1) {
+        return {
+            contentEnd: source.endsWith("\r") ? source.length - 1 : source.length,
+            nextStart: source.length,
+        };
+    }
+    return {
+        contentEnd: source[newlineIndex - 1] === "\r" ? newlineIndex - 1 : newlineIndex,
+        nextStart: newlineIndex + 1,
+    };
+}
+function parsePhpHeredocStart(source, index) {
+    if (!source.startsWith("<<<", index)) {
+        return null;
+    }
+    let cursor = index + 3;
+    while (isPhpHorizontalWhitespace(source[cursor])) {
+        cursor += 1;
+    }
+    const quote = source[cursor] === "'" || source[cursor] === '"' ? source[cursor] : "";
+    if (quote) {
+        cursor += 1;
+    }
+    if (!isPhpIdentifierStart(source[cursor])) {
+        return null;
+    }
+    const delimiterStart = cursor;
+    cursor += 1;
+    while (isPhpIdentifierPart(source[cursor])) {
+        cursor += 1;
+    }
+    const delimiter = source.slice(delimiterStart, cursor);
+    if (quote) {
+        if (source[cursor] !== quote) {
+            return null;
+        }
+        cursor += 1;
+    }
+    const lineBoundary = findPhpLineBoundary(source, cursor);
+    if (source.slice(cursor, lineBoundary.contentEnd).trim() !== "") {
+        return null;
+    }
+    return {
+        contentStart: lineBoundary.nextStart,
+        delimiter,
+    };
+}
+function findPhpHeredocClosingEnd(source, index, delimiter) {
+    if (!isPhpLineStart(source, index)) {
+        return null;
+    }
+    let cursor = index;
+    while (isPhpHorizontalWhitespace(source[cursor])) {
+        cursor += 1;
+    }
+    if (!source.startsWith(delimiter, cursor)) {
+        return null;
+    }
+    cursor += delimiter.length;
+    if (isPhpIdentifierPart(source[cursor])) {
+        return null;
+    }
+    let continuationCursor = cursor;
+    while (isPhpHorizontalWhitespace(source[continuationCursor])) {
+        continuationCursor += 1;
+    }
+    const continuation = source[continuationCursor];
+    if (continuationCursor >= source.length ||
+        continuation === "\r" ||
+        continuation === "\n" ||
+        !isPhpIdentifierPart(continuation)) {
+        return cursor;
+    }
+    return null;
+}
+function skipPhpCallTrivia(source, index) {
+    let cursor = index;
+    while (cursor < source.length) {
+        while (isPhpWhitespace(source[cursor])) {
+            cursor += 1;
+        }
+        if (source[cursor] === "/" && source[cursor + 1] === "*") {
+            const commentEnd = source.indexOf("*/", cursor + 2);
+            if (commentEnd === -1) {
+                return null;
+            }
+            cursor = commentEnd + 2;
+            continue;
+        }
+        if (source[cursor] === "/" && source[cursor + 1] === "/") {
+            cursor = findPhpLineBoundary(source, cursor + 2).nextStart;
+            continue;
+        }
+        if (source[cursor] === "#" && source[cursor + 1] !== "[") {
+            cursor = findPhpLineBoundary(source, cursor + 1).nextStart;
+            continue;
+        }
+        return cursor;
+    }
+    return cursor;
+}
+function matchesPhpFunctionCallAt(source, index, functionName) {
+    if (!source.startsWith(functionName, index)) {
+        return false;
+    }
+    if (isPhpIdentifierPart(source[index - 1])) {
+        return false;
+    }
+    const cursor = index + functionName.length;
+    if (isPhpIdentifierPart(source[cursor])) {
+        return false;
+    }
+    const callStart = skipPhpCallTrivia(source, cursor);
+    return callStart !== null && source[callStart] === "(";
+}
+function createPhpScannerState() {
+    return {
+        heredocDelimiter: "",
+        interpolationComment: "",
+        interpolationDepth: 0,
+        interpolationQuote: "",
+        mode: "code",
+    };
+}
+function advancePhpScanner(source, index, state) {
+    const character = source[index];
+    if (state.mode === "heredoc") {
+        const closingEnd = findPhpHeredocClosingEnd(source, index, state.heredocDelimiter);
+        if (closingEnd !== null) {
+            state.mode = "code";
+            state.heredocDelimiter = "";
+            return { ambiguous: false, inCode: false, index: closingEnd };
+        }
+        const nextLineStart = findPhpLineBoundary(source, index).nextStart;
+        if (nextLineStart <= index) {
+            return { ambiguous: true, inCode: false, index };
+        }
+        return { ambiguous: false, inCode: false, index: nextLineStart };
+    }
+    if (state.mode === "single-quoted" || state.mode === "double-quoted") {
+        const quote = state.mode === "single-quoted" ? "'" : '"';
+        if (character === "\\") {
+            return { ambiguous: false, inCode: false, index: index + 2 };
+        }
+        if (state.mode === "double-quoted" &&
+            character === "{" &&
+            source[index + 1] === "$") {
+            state.mode = "double-quoted-interpolation";
+            state.interpolationComment = "";
+            state.interpolationDepth = 1;
+            state.interpolationQuote = "";
+            return { ambiguous: false, inCode: false, index: index + 2 };
+        }
+        if (character === quote) {
+            state.mode = "code";
+        }
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (state.mode === "double-quoted-interpolation") {
+        if (state.interpolationQuote) {
+            if (character === "\\") {
+                return { ambiguous: false, inCode: false, index: index + 2 };
+            }
+            if (character === state.interpolationQuote) {
+                state.interpolationQuote = "";
+            }
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (state.interpolationComment === "line") {
+            if (character === "\r" || character === "\n") {
+                state.interpolationComment = "";
+            }
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (state.interpolationComment === "block") {
+            if (character === "*" && source[index + 1] === "/") {
+                state.interpolationComment = "";
+                return { ambiguous: false, inCode: false, index: index + 2 };
+            }
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (character === "/" && source[index + 1] === "/") {
+            state.interpolationComment = "line";
+            return { ambiguous: false, inCode: false, index: index + 2 };
+        }
+        if (character === "#" && source[index + 1] !== "[") {
+            state.interpolationComment = "line";
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (character === "/" && source[index + 1] === "*") {
+            state.interpolationComment = "block";
+            return { ambiguous: false, inCode: false, index: index + 2 };
+        }
+        if (character === "'" || character === '"') {
+            state.interpolationQuote = character;
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (character === "{") {
+            state.interpolationDepth += 1;
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        if (character === "}") {
+            state.interpolationDepth -= 1;
+            if (state.interpolationDepth <= 0) {
+                state.interpolationComment = "";
+                state.interpolationDepth = 0;
+                state.mode = "double-quoted";
+            }
+            return { ambiguous: false, inCode: false, index: index + 1 };
+        }
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (state.mode === "line-comment") {
+        if (character === "\r" || character === "\n") {
+            state.mode = "code";
+        }
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (state.mode === "block-comment") {
+        if (character === "*" && source[index + 1] === "/") {
+            state.mode = "code";
+            return { ambiguous: false, inCode: false, index: index + 2 };
+        }
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (character === "'") {
+        state.mode = "single-quoted";
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (character === '"') {
+        state.mode = "double-quoted";
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (character === "/" && source[index + 1] === "/") {
+        state.mode = "line-comment";
+        return { ambiguous: false, inCode: false, index: index + 2 };
+    }
+    if (character === "#" && source[index + 1] !== "[") {
+        state.mode = "line-comment";
+        return { ambiguous: false, inCode: false, index: index + 1 };
+    }
+    if (character === "/" && source[index + 1] === "*") {
+        state.mode = "block-comment";
+        return { ambiguous: false, inCode: false, index: index + 2 };
+    }
+    if (character === "<") {
+        const heredocStart = parsePhpHeredocStart(source, index);
+        if (heredocStart) {
+            state.mode = "heredoc";
+            state.heredocDelimiter = heredocStart.delimiter;
+            return {
+                ambiguous: false,
+                inCode: false,
+                index: heredocStart.contentStart,
+            };
+        }
+    }
+    return { ambiguous: false, inCode: true, index };
+}
+/**
+ * Detect a PHP function call outside strings, comments, heredoc, and nowdoc blocks.
+ *
+ * @param source PHP source to scan.
+ * @param functionName Literal PHP function identifier to find.
+ * @returns Whether `source` contains a code-mode call to `functionName`.
+ */
+export function hasPhpFunctionCall(source, functionName) {
+    const scanner = createPhpScannerState();
+    let index = 0;
+    while (index < source.length) {
+        const scan = advancePhpScanner(source, index, scanner);
+        if (scan.ambiguous) {
+            return false;
+        }
+        if (!scan.inCode) {
+            index = scan.index;
+            continue;
+        }
+        if (matchesPhpFunctionCallAt(source, index, functionName)) {
+            return true;
+        }
+        index += 1;
+    }
+    return false;
+}
+/**
+ * Locate a PHP function body without counting braces in non-code regions.
+ *
+ * @param source PHP source to scan.
+ * @param functionName Literal PHP function identifier to locate.
+ * @param options Range options such as trailing newline inclusion.
+ * @returns The matched {@link PhpFunctionRange}, or `null` when no safe range exists.
+ */
+export function findPhpFunctionRange(source, functionName, options = {}) {
+    const signaturePattern = new RegExp(`function\\s+${escapeRegex(functionName)}\\s*\\([^)]*\\)\\s*(?::\\s*[^{};]+)?\\s*\\{`, "u");
+    const signatureMatch = signaturePattern.exec(source);
+    if (!signatureMatch) {
+        return null;
+    }
+    const functionStart = signatureMatch.index;
+    const openBraceOffset = signatureMatch[0].lastIndexOf("{");
+    if (openBraceOffset === -1) {
+        return null;
+    }
+    const openBraceIndex = functionStart + openBraceOffset;
+    let depth = 0;
+    const scanner = createPhpScannerState();
+    let index = openBraceIndex;
+    while (index < source.length) {
+        const scan = advancePhpScanner(source, index, scanner);
+        if (scan.ambiguous) {
+            return null;
+        }
+        if (!scan.inCode) {
+            index = scan.index;
+            continue;
+        }
+        const character = source[index];
+        if (character === "{") {
+            depth += 1;
+            index += 1;
+            continue;
+        }
+        if (character !== "}") {
+            index += 1;
+            continue;
+        }
+        depth -= 1;
+        if (depth === 0) {
+            let end = index + 1;
+            if (options.includeTrailingNewlines ?? true) {
+                while (end < source.length && /[\r\n]/u.test(source[end] ?? "")) {
+                    end += 1;
+                }
+            }
+            return {
+                end,
+                source: source.slice(functionStart, end),
+                start: functionStart,
+            };
+        }
+        index += 1;
+    }
+    return null;
+}
+export function replacePhpFunctionDefinition(source, functionName, replacement, options = {}) {
+    const functionRange = findPhpFunctionRange(source, functionName, options);
+    if (!functionRange) {
+        return null;
+    }
+    return [
+        source.slice(0, functionRange.start),
+        options.trimReplacementStart ? replacement.trimStart() : replacement,
+        source.slice(functionRange.end),
+    ].join("");
+}