@wp-typia/project-tools 0.24.9 → 0.24.11

package/dist/runtime/doctor/cli-doctor-wordpress-version.js

@@ -4,6 +4,8 @@ import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { WORDPRESS_BLOCK_API_COMPATIBILITY } from "@wp-typia/block-types/blocks/compatibility";
 import { createDoctorCheck, resolveWorkspaceBootstrapPath, } from "./cli-doctor-workspace-shared.js";
 import { readJsonFileSync } from "../shared/json-utils.js";
+import { hasPhpFunctionCallWithAssignedStringPrefixArgument, hasPhpFunctionCallWithStringArgumentPrefix, } from "../shared/php-utils.js";
+import { hasExecutablePattern, hasUncommentedPattern, maskTypeScriptComments, maskTypeScriptCommentsAndLiterals, } from "../shared/ts-source-masking.js";
 import { compareVersionFloors, pickHigherVersionFloor, } from "../shared/version-floor.js";
 import { DEFAULT_SCAFFOLD_WORDPRESS_TARGET_VERSION } from "../templates/scaffold-compatibility.js";
 const WORDPRESS_VERSION_CHECK_CODES = {
@@ -15,9 +17,18 @@ const BLOCK_VARIATION_BLOCK_JSON_KEYS = {
     registrationBlockJsonMetadata: "variations",
     registrationMetadataFile: "variations",
 };
+const CORE_VARIATION_REGISTRY_IMPORT_PATTERN = /^\s*import\s*(?!type\b)\{[\s\S]*?\}\s*from\s*["']\.\/[^"']+\/[^"']+\/[^"']+["']\s*;?\s*$/mu;
+const REGISTER_BLOCK_VARIATION_CALL_PATTERN = /\bregisterBlockVariation\s*\(/u;
+const REGISTER_WORKSPACE_CORE_VARIATIONS_CALL_PATTERN = /^\s*registerWorkspaceCoreVariations\s*\(\s*\)\s*;?\s*$/mu;
+const REGISTER_BLOCK_BINDINGS_SOURCE_CALL_PATTERN = /\bregisterBlockBindingsSource\s*\(/gu;
+const GET_FIELDS_LIST_PROPERTY_PATTERN = /(?:async\s+)?\bgetFieldsList\s*\([^)]*\)|(?:async\s+)?["']getFieldsList["']\s*\([^)]*\)|\bgetFieldsList\s*:|["']getFieldsList["']\s*:|\bgetFieldsList\s*(?=,|\})/gu;
+const SUPPORTED_ATTRIBUTES_FILTER_PREFIX = "block_bindings_supported_attributes_";
 function isEnabledMetadataValue(value) {
     return value !== undefined && value !== false && value !== null;
 }
+function assertNeverBlockVariationFeature(feature) {
+    throw new Error(`Unhandled block variation metadata feature "${String(feature)}".`);
+}
 function isEnabledBlockVariationMetadataFeature(feature, value) {
     if (feature === "registrationBlockJsonMetadata") {
         return Array.isArray(value) && value.length > 0;
@@ -25,7 +36,7 @@ function isEnabledBlockVariationMetadataFeature(feature, value) {
     if (feature === "registrationMetadataFile") {
         return typeof value === "string" && value.trim().length > 0;
     }
-    return isEnabledMetadataValue(value);
+    return assertNeverBlockVariationFeature(feature);
 }
 function getNestedMetadataValue(object, key) {
     if (!object) {
@@ -80,6 +91,294 @@ function readExistingTextFile(filePath) {
     }
     return fs.readFileSync(filePath, "utf8");
 }
+function isTypeScriptIdentifierPart(character) {
+    return /^[A-Za-z0-9_$]$/u.test(character ?? "");
+}
+function skipTypeScriptWhitespace(source, index) {
+    let cursor = index;
+    while (/\s/u.test(source[cursor] ?? "")) {
+        cursor += 1;
+    }
+    return cursor;
+}
+function findClosingDelimiter(source, openIndex, openDelimiter, closeDelimiter) {
+    let depth = 0;
+    for (let cursor = openIndex; cursor < source.length; cursor += 1) {
+        const character = source[cursor];
+        if (character === openDelimiter) {
+            depth += 1;
+            continue;
+        }
+        if (character === closeDelimiter) {
+            depth -= 1;
+            if (depth === 0) {
+                return cursor;
+            }
+        }
+    }
+    return null;
+}
+function findTopLevelSatisfiesIndex(source) {
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let parenthesisDepth = 0;
+    for (let cursor = 0; cursor < source.length; cursor += 1) {
+        const character = source[cursor];
+        if (character === "{") {
+            braceDepth += 1;
+            continue;
+        }
+        if (character === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (character === "[") {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === "]") {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            continue;
+        }
+        if (character === "(") {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ")") {
+            parenthesisDepth = Math.max(0, parenthesisDepth - 1);
+            continue;
+        }
+        if (braceDepth === 0 &&
+            bracketDepth === 0 &&
+            parenthesisDepth === 0 &&
+            source.startsWith("satisfies", cursor) &&
+            !isTypeScriptIdentifierPart(source[cursor - 1]) &&
+            !isTypeScriptIdentifierPart(source[cursor + "satisfies".length])) {
+            return cursor;
+        }
+    }
+    return null;
+}
+function isTopLevelObjectPropertyStart(structureMaskedObjectSource, index) {
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let parenthesisDepth = 0;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        const character = structureMaskedObjectSource[cursor];
+        if (character === "{") {
+            braceDepth += 1;
+            continue;
+        }
+        if (character === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (character === "[") {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === "]") {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            continue;
+        }
+        if (character === "(") {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ")") {
+            parenthesisDepth = Math.max(0, parenthesisDepth - 1);
+        }
+    }
+    if (braceDepth !== 1 || bracketDepth !== 0 || parenthesisDepth !== 0) {
+        return false;
+    }
+    let previousCursor = index - 1;
+    while (previousCursor >= 0 &&
+        /\s/u.test(structureMaskedObjectSource[previousCursor] ?? "")) {
+        previousCursor -= 1;
+    }
+    const previousToken = structureMaskedObjectSource[previousCursor];
+    return previousToken === "{" || previousToken === ",";
+}
+function objectLiteralHasGetFieldsListProperty(commentMaskedObjectSource, structureMaskedObjectSource) {
+    GET_FIELDS_LIST_PROPERTY_PATTERN.lastIndex = 0;
+    let match;
+    while ((match = GET_FIELDS_LIST_PROPERTY_PATTERN.exec(commentMaskedObjectSource))) {
+        if (isTopLevelObjectPropertyStart(structureMaskedObjectSource, match.index)) {
+            GET_FIELDS_LIST_PROPERTY_PATTERN.lastIndex = 0;
+            return true;
+        }
+    }
+    GET_FIELDS_LIST_PROPERTY_PATTERN.lastIndex = 0;
+    return false;
+}
+function getRuntimeArgumentEnd(maskedCallArgumentsSource) {
+    return (findTopLevelSatisfiesIndex(maskedCallArgumentsSource) ??
+        maskedCallArgumentsSource.length);
+}
+function getFirstObjectArgumentSpan(structureMaskedRuntimeArgumentsSource, absoluteStart) {
+    const objectStartOffset = skipTypeScriptWhitespace(structureMaskedRuntimeArgumentsSource, 0);
+    if (structureMaskedRuntimeArgumentsSource[objectStartOffset] !== "{") {
+        return undefined;
+    }
+    const objectEndOffset = findClosingDelimiter(structureMaskedRuntimeArgumentsSource, objectStartOffset, "{", "}");
+    if (objectEndOffset === null) {
+        return undefined;
+    }
+    return {
+        end: absoluteStart + objectEndOffset + 1,
+        start: absoluteStart + objectStartOffset,
+    };
+}
+function getSimpleRuntimeArgumentIdentifier(structureMaskedRuntimeArgumentsSource) {
+    const trimmed = structureMaskedRuntimeArgumentsSource.trim();
+    const match = /^([A-Za-z_$][\w$]*)(?:\s+as\b[\s\S]*)?$/u.exec(trimmed);
+    return match?.[1];
+}
+function findObjectInitializerStart(structureMaskedSource, index) {
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let parenthesisDepth = 0;
+    for (let cursor = index; cursor < structureMaskedSource.length; cursor += 1) {
+        const character = structureMaskedSource[cursor];
+        if (character === "{") {
+            braceDepth += 1;
+            continue;
+        }
+        if (character === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (character === "[") {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === "]") {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            continue;
+        }
+        if (character === "(") {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ")") {
+            parenthesisDepth = Math.max(0, parenthesisDepth - 1);
+            continue;
+        }
+        if (braceDepth !== 0 || bracketDepth !== 0 || parenthesisDepth !== 0) {
+            continue;
+        }
+        if (character === ";") {
+            return null;
+        }
+        if (character !== "=" || structureMaskedSource[cursor + 1] === ">") {
+            continue;
+        }
+        const valueStart = skipTypeScriptWhitespace(structureMaskedSource, cursor + 1);
+        return structureMaskedSource[valueStart] === "{" ? valueStart : null;
+    }
+    return null;
+}
+function isTopLevelTypeScriptPosition(structureMaskedSource, index) {
+    let braceDepth = 0;
+    let bracketDepth = 0;
+    let parenthesisDepth = 0;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        const character = structureMaskedSource[cursor];
+        if (character === "{") {
+            braceDepth += 1;
+            continue;
+        }
+        if (character === "}") {
+            braceDepth = Math.max(0, braceDepth - 1);
+            continue;
+        }
+        if (character === "[") {
+            bracketDepth += 1;
+            continue;
+        }
+        if (character === "]") {
+            bracketDepth = Math.max(0, bracketDepth - 1);
+            continue;
+        }
+        if (character === "(") {
+            parenthesisDepth += 1;
+            continue;
+        }
+        if (character === ")") {
+            parenthesisDepth = Math.max(0, parenthesisDepth - 1);
+        }
+    }
+    return braceDepth === 0 && bracketDepth === 0 && parenthesisDepth === 0;
+}
+function variableObjectHasGetFieldsListProperty(identifier, commentMaskedSource, structureMaskedSource, beforeIndex) {
+    const variablePattern = /\b(?:export\s+)?(?:const|let|var)\s+([A-Za-z_$][\w$]*)\b/gu;
+    let match;
+    let nearestObjectSpan;
+    while ((match = variablePattern.exec(structureMaskedSource))) {
+        if (match.index >= beforeIndex) {
+            break;
+        }
+        if (match[1] !== identifier) {
+            continue;
+        }
+        if (!isTopLevelTypeScriptPosition(structureMaskedSource, match.index)) {
+            continue;
+        }
+        const objectStart = findObjectInitializerStart(structureMaskedSource, match.index + match[0].length);
+        if (objectStart === null || objectStart >= beforeIndex) {
+            continue;
+        }
+        const objectEnd = findClosingDelimiter(structureMaskedSource, objectStart, "{", "}");
+        if (objectEnd === null) {
+            continue;
+        }
+        nearestObjectSpan = {
+            end: objectEnd + 1,
+            start: objectStart,
+        };
+    }
+    return nearestObjectSpan
+        ? objectLiteralHasGetFieldsListProperty(commentMaskedSource.slice(nearestObjectSpan.start, nearestObjectSpan.end), structureMaskedSource.slice(nearestObjectSpan.start, nearestObjectSpan.end))
+        : false;
+}
+function hasRegisterBlockBindingsSourceGetFieldsList(source) {
+    const structureMaskedSource = maskTypeScriptCommentsAndLiterals(source);
+    const commentMaskedSource = maskTypeScriptComments(source);
+    REGISTER_BLOCK_BINDINGS_SOURCE_CALL_PATTERN.lastIndex = 0;
+    let match;
+    while ((match =
+        REGISTER_BLOCK_BINDINGS_SOURCE_CALL_PATTERN.exec(structureMaskedSource))) {
+        const openIndex = structureMaskedSource.indexOf("(", match.index);
+        if (openIndex === -1) {
+            continue;
+        }
+        const closeIndex = findClosingDelimiter(structureMaskedSource, openIndex, "(", ")");
+        if (closeIndex === null) {
+            continue;
+        }
+        const maskedCallArgumentsSource = structureMaskedSource.slice(openIndex + 1, closeIndex);
+        const runtimeArgumentEnd = getRuntimeArgumentEnd(maskedCallArgumentsSource);
+        const runtimeArgumentsStart = openIndex + 1;
+        const maskedRuntimeArgumentsSource = structureMaskedSource.slice(runtimeArgumentsStart, runtimeArgumentsStart + runtimeArgumentEnd);
+        const objectArgumentSpan = getFirstObjectArgumentSpan(maskedRuntimeArgumentsSource, runtimeArgumentsStart);
+        if (objectArgumentSpan &&
+            objectLiteralHasGetFieldsListProperty(commentMaskedSource.slice(objectArgumentSpan.start, objectArgumentSpan.end), structureMaskedSource.slice(objectArgumentSpan.start, objectArgumentSpan.end))) {
+            return true;
+        }
+        const runtimeArgumentIdentifier = getSimpleRuntimeArgumentIdentifier(maskedRuntimeArgumentsSource);
+        if (runtimeArgumentIdentifier &&
+            variableObjectHasGetFieldsListProperty(runtimeArgumentIdentifier, commentMaskedSource, structureMaskedSource, match.index)) {
+            return true;
+        }
+        REGISTER_BLOCK_BINDINGS_SOURCE_CALL_PATTERN.lastIndex = closeIndex + 1;
+    }
+    return false;
+}
+function hasSupportedAttributesFilterRegistration(source) {
+    return (hasPhpFunctionCallWithStringArgumentPrefix(source, "add_filter", SUPPORTED_ATTRIBUTES_FILTER_PREFIX) ||
+        hasPhpFunctionCallWithAssignedStringPrefixArgument(source, "add_filter", SUPPORTED_ATTRIBUTES_FILTER_PREFIX));
+}
 function collectBlockMetadataRequirements(workspace, inventory) {
     const issues = [];
     const requirements = [];
@@ -131,23 +430,16 @@ function collectBlockMetadataRequirements(workspace, inventory) {
         requirements,
     };
 }
-function hasGeneratedCoreVariationModule(directoryPath, isRootDirectory = true) {
-    if (!fs.existsSync(directoryPath)) {
+function hasGeneratedCoreVariationRegistry(projectDir) {
+    // Convention: generated core variation registries are rooted at this entrypoint.
+    const registryPath = path.join(projectDir, "src", "editor-plugins", "core-variations", "index.ts");
+    const source = readExistingTextFile(registryPath);
+    if (!source) {
         return false;
     }
-    for (const entry of fs.readdirSync(directoryPath, { withFileTypes: true })) {
-        const entryPath = path.join(directoryPath, entry.name);
-        if (entry.isDirectory() && hasGeneratedCoreVariationModule(entryPath, false)) {
-            return true;
-        }
-        if (!isRootDirectory &&
-            entry.isFile() &&
-            entry.name.endsWith(".ts") &&
-            entry.name !== "index.ts") {
-            return true;
-        }
-    }
-    return false;
+    return (hasUncommentedPattern(source, CORE_VARIATION_REGISTRY_IMPORT_PATTERN) &&
+        hasExecutablePattern(source, REGISTER_BLOCK_VARIATION_CALL_PATTERN) &&
+        hasExecutablePattern(source, REGISTER_WORKSPACE_CORE_VARIATIONS_CALL_PATTERN));
 }
 function collectVariationRequirements(workspace, inventory) {
     const requirements = [];
@@ -155,8 +447,7 @@ function collectVariationRequirements(workspace, inventory) {
     for (const variation of inventory.variations) {
         pushBlockApiRequirement(requirements, `Variation ${variation.block}/${variation.slug}`, variationEntries.editorRegistration);
     }
-    const coreVariationsDir = path.join(workspace.projectDir, "src", "editor-plugins", "core-variations");
-    if (hasGeneratedCoreVariationModule(coreVariationsDir)) {
+    if (hasGeneratedCoreVariationRegistry(workspace.projectDir)) {
         pushBlockApiRequirement(requirements, "Core variations editor plugin", variationEntries.editorRegistration);
     }
     return {
@@ -196,11 +487,14 @@ function collectBindingSourceRequirements(workspace, inventory) {
         pushBlockApiRequirement(requirements, `Binding source ${bindingSource.slug}`, bindingEntries.serverRegistration);
         pushBlockApiRequirement(requirements, `Binding source ${bindingSource.slug}`, bindingEntries.editorRegistration);
         const editorFilePath = path.join(workspace.projectDir, bindingSource.editorFile);
-        if (readExistingTextFile(editorFilePath)?.includes("getFieldsList")) {
+        const editorSource = readExistingTextFile(editorFilePath);
+        if (editorSource &&
+            hasRegisterBlockBindingsSourceGetFieldsList(editorSource)) {
             pushBlockApiRequirement(requirements, `Binding source ${bindingSource.slug}`, bindingEntries.editorFieldsList);
         }
         const serverFilePath = path.join(workspace.projectDir, bindingSource.serverFile);
-        if (readExistingTextFile(serverFilePath)?.includes("block_bindings_supported_attributes_")) {
+        const serverSource = readExistingTextFile(serverFilePath);
+        if (serverSource && hasSupportedAttributesFilterRegistration(serverSource)) {
             pushBlockApiRequirement(requirements, `Binding source ${bindingSource.slug}`, bindingEntries.supportedAttributesFilter);
         }
     }
@@ -247,6 +541,9 @@ function formatRequirementSummary(requirements, floor) {
         .map((requirement) => requirement.label);
     return labels.length > 0 ? labels.join(", ") : "generated workspace features";
 }
+function formatFeatureMinimumAction(floor) {
+    return `Update the plugin bootstrap \`Requires at least\` header to ${floor} or remove the features that require that floor.`;
+}
 function createFeatureMinimumCheck(workspace, inventory, headers) {
     const { issues, requirements } = collectWordPressVersionRequirements(workspace, inventory);
     const highestFloor = pickHighestRequirementFloor(requirements, issues);
@@ -257,11 +554,11 @@ function createFeatureMinimumCheck(workspace, inventory, headers) {
         return createDoctorCheck("WordPress feature minimum", "pass", "No generated workspace features declare an additional WordPress hard floor.", WORDPRESS_VERSION_CHECK_CODES.featureMinimum);
     }
     if (!headers.requiresAtLeast) {
-        return createDoctorCheck("WordPress feature minimum", "fail", `Plugin bootstrap is missing a Requires at least header but generated features require WordPress ${highestFloor}.`, WORDPRESS_VERSION_CHECK_CODES.featureMinimum);
+        return createDoctorCheck("WordPress feature minimum", "fail", `Plugin bootstrap is missing a Requires at least header but generated features require WordPress ${highestFloor}. ${formatFeatureMinimumAction(highestFloor)}`, WORDPRESS_VERSION_CHECK_CODES.featureMinimum);
     }
     try {
         if (compareVersionFloors(headers.requiresAtLeast, highestFloor) < 0) {
-            return createDoctorCheck("WordPress feature minimum", "fail", `Requires at least ${headers.requiresAtLeast} is below generated feature floor ${highestFloor} (${formatRequirementSummary(requirements, highestFloor)}).`, WORDPRESS_VERSION_CHECK_CODES.featureMinimum);
+            return createDoctorCheck("WordPress feature minimum", "fail", `Requires at least ${headers.requiresAtLeast} is below generated feature floor ${highestFloor} (${formatRequirementSummary(requirements, highestFloor)}). ${formatFeatureMinimumAction(highestFloor)}`, WORDPRESS_VERSION_CHECK_CODES.featureMinimum);
         }
     }
     catch {
@@ -275,7 +572,7 @@ function createTestedTargetCheck(headers, targetVersion) {
     }
     try {
         if (compareVersionFloors(headers.testedUpTo, targetVersion) < 0) {
-            return createDoctorCheck("WordPress tested target", "warn", `Tested up to ${headers.testedUpTo} is below the selected WordPress target ${targetVersion}.`, WORDPRESS_VERSION_CHECK_CODES.testedTarget);
+            return createDoctorCheck("WordPress tested target", "warn", `Tested up to ${headers.testedUpTo} is below the selected WordPress target ${targetVersion}. Update the plugin bootstrap \`Tested up to\` header when the workspace is verified against WordPress ${targetVersion}.`, WORDPRESS_VERSION_CHECK_CODES.testedTarget);
         }
     }
     catch {

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

@@ -20,6 +20,32 @@ export declare function hasPhpFunctionDefinition(source: string, functionName: s
  * @returns Whether `source` contains a code-mode call to `functionName`.
  */
 export declare function hasPhpFunctionCall(source: string, functionName: string): boolean;
+/**
+ * Detect a PHP function call whose first argument is a variable previously
+ * assigned from a literal string prefix in executable PHP code.
+ */
+export declare function hasPhpFunctionCallWithAssignedStringPrefixArgument(source: string, functionName: string, literalPrefix: string): boolean;
+/**
+ * Detect a PHP function call whose first argument is a literal string value.
+ *
+ * This uses the same code-mode scanner as {@link hasPhpFunctionCall}, so
+ * comments, quoted strings, heredoc, and nowdoc content cannot create matches.
+ */
+export declare function hasPhpFunctionCallWithStringArgument(source: string, functionName: string, literalArgument: string): boolean;
+/**
+ * Detect a PHP function call whose first argument starts with a literal string prefix.
+ *
+ * Concatenated expressions are accepted here so dynamic WordPress hooks such as
+ * `'block_bindings_supported_attributes_' . $block_type` remain detectable.
+ */
+export declare function hasPhpFunctionCallWithStringArgumentPrefix(source: string, functionName: string, literalPrefix: string): boolean;
+/**
+ * Detect a code-mode PHP string literal that starts with a literal prefix.
+ *
+ * This is useful for dynamic hook names stored in variables before a later
+ * global function call consumes the variable.
+ */
+export declare function hasPhpCodeStringLiteralPrefix(source: string, literalPrefix: string): boolean;
 /**
  * Locate a PHP function body without counting braces in non-code regions.
  *

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

@@ -132,6 +132,15 @@ function matchesPhpFunctionCallAt(source, index, functionName) {
     if (isPhpIdentifierPart(source[index - 1])) {
         return false;
     }
+    let previousCursor = index - 1;
+    while (previousCursor >= 0 && /\s/u.test(source[previousCursor] ?? "")) {
+        previousCursor -= 1;
+    }
+    const previousToken = source[previousCursor];
+    if ((previousToken === ">" && source[previousCursor - 1] === "-") ||
+        (previousToken === ":" && source[previousCursor - 1] === ":")) {
+        return false;
+    }
     const cursor = index + functionName.length;
     if (isPhpIdentifierPart(source[cursor])) {
         return false;
@@ -139,6 +148,60 @@ function matchesPhpFunctionCallAt(source, index, functionName) {
     const callStart = skipPhpCallTrivia(source, cursor);
     return callStart !== null && source[callStart] === "(";
 }
+function parsePhpQuotedStringLiteralAt(source, index) {
+    const quote = source[index];
+    if (quote !== "'" && quote !== '"') {
+        return null;
+    }
+    let cursor = index + 1;
+    let value = "";
+    while (cursor < source.length) {
+        const character = source[cursor];
+        if (character === "\\") {
+            const escapedCharacter = source[cursor + 1];
+            if (escapedCharacter === undefined) {
+                return null;
+            }
+            value += escapedCharacter;
+            cursor += 2;
+            continue;
+        }
+        if (character === quote) {
+            return {
+                end: cursor + 1,
+                value,
+            };
+        }
+        value += character;
+        cursor += 1;
+    }
+    return null;
+}
+function parsePhpVariableNameAt(source, index) {
+    if (source[index] !== "$") {
+        return null;
+    }
+    const nameStart = index + 1;
+    if (!isPhpIdentifierStart(source[nameStart])) {
+        return null;
+    }
+    let cursor = nameStart + 1;
+    while (isPhpIdentifierPart(source[cursor])) {
+        cursor += 1;
+    }
+    return {
+        end: cursor,
+        name: source.slice(nameStart, cursor),
+    };
+}
+function getPhpFunctionCallFirstArgumentStart(source, index, functionName) {
+    const cursor = index + functionName.length;
+    const callStart = skipPhpCallTrivia(source, cursor);
+    if (callStart === null || source[callStart] !== "(") {
+        return null;
+    }
+    return skipPhpCallTrivia(source, callStart + 1);
+}
 function createPhpScannerState() {
     return {
         heredocDelimiter: "",
@@ -309,6 +372,211 @@ export function hasPhpFunctionCall(source, functionName) {
     }
     return false;
 }
+function isPhpAssignmentOperatorAt(source, index) {
+    if (index === null || source[index] !== "=") {
+        return false;
+    }
+    const previousToken = source[index - 1];
+    const nextToken = source[index + 1];
+    return (previousToken !== "=" &&
+        previousToken !== "!" &&
+        previousToken !== "<" &&
+        previousToken !== ">" &&
+        previousToken !== "." &&
+        nextToken !== "=" &&
+        nextToken !== ">");
+}
+function isSupportedPhpAssignedStringSuffix(source, index) {
+    const nextTokenIndex = skipPhpCallTrivia(source, index);
+    const nextToken = nextTokenIndex === null ? undefined : source[nextTokenIndex];
+    return nextToken === "." || nextToken === ";" || nextToken === undefined;
+}
+function getPhpFunctionCallFirstVariableArgumentName(source, index, functionName) {
+    const argumentStart = getPhpFunctionCallFirstArgumentStart(source, index, functionName);
+    if (argumentStart === null) {
+        return undefined;
+    }
+    const variable = parsePhpVariableNameAt(source, argumentStart);
+    if (!variable) {
+        return undefined;
+    }
+    const argumentEnd = skipPhpCallTrivia(source, variable.end);
+    const nextToken = argumentEnd === null ? undefined : source[argumentEnd];
+    return nextToken === "," || nextToken === ")" || nextToken === undefined
+        ? variable.name
+        : undefined;
+}
+/**
+ * Detect a PHP function call whose first argument is a variable previously
+ * assigned from a literal string prefix in executable PHP code.
+ */
+export function hasPhpFunctionCallWithAssignedStringPrefixArgument(source, functionName, literalPrefix) {
+    const variablesWithPrefix = new Set();
+    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;
+        }
+        const variable = parsePhpVariableNameAt(source, index);
+        if (variable) {
+            const assignmentStart = skipPhpCallTrivia(source, variable.end);
+            if (assignmentStart !== null &&
+                isPhpAssignmentOperatorAt(source, assignmentStart)) {
+                const literalStart = skipPhpCallTrivia(source, assignmentStart + 1);
+                const literal = literalStart === null
+                    ? null
+                    : parsePhpQuotedStringLiteralAt(source, literalStart);
+                if (literal &&
+                    literal.value.startsWith(literalPrefix) &&
+                    isSupportedPhpAssignedStringSuffix(source, literal.end)) {
+                    variablesWithPrefix.add(variable.name);
+                    index = literal.end;
+                    continue;
+                }
+                variablesWithPrefix.delete(variable.name);
+            }
+        }
+        if (matchesPhpFunctionCallAt(source, index, functionName)) {
+            const variableArgumentName = getPhpFunctionCallFirstVariableArgumentName(source, index, functionName);
+            if (variableArgumentName &&
+                variablesWithPrefix.has(variableArgumentName)) {
+                return true;
+            }
+            index += functionName.length;
+            continue;
+        }
+        index += 1;
+    }
+    return false;
+}
+/**
+ * Detect a PHP function call whose first argument is a literal string value.
+ *
+ * This uses the same code-mode scanner as {@link hasPhpFunctionCall}, so
+ * comments, quoted strings, heredoc, and nowdoc content cannot create matches.
+ */
+export function hasPhpFunctionCallWithStringArgument(source, functionName, literalArgument) {
+    return hasPhpFunctionCallWithStringArgumentMatching(source, functionName, (value) => value === literalArgument, { allowConcatenatedPrefix: false });
+}
+/**
+ * Detect a PHP function call whose first argument starts with a literal string prefix.
+ *
+ * Concatenated expressions are accepted here so dynamic WordPress hooks such as
+ * `'block_bindings_supported_attributes_' . $block_type` remain detectable.
+ */
+export function hasPhpFunctionCallWithStringArgumentPrefix(source, functionName, literalPrefix) {
+    return hasPhpFunctionCallWithStringArgumentMatching(source, functionName, (value) => value.startsWith(literalPrefix), { allowConcatenatedPrefix: true });
+}
+/**
+ * Detect a code-mode PHP string literal that starts with a literal prefix.
+ *
+ * This is useful for dynamic hook names stored in variables before a later
+ * global function call consumes the variable.
+ */
+export function hasPhpCodeStringLiteralPrefix(source, literalPrefix) {
+    let index = 0;
+    while (index < source.length) {
+        if (source.startsWith("<?php", index)) {
+            index += 5;
+            continue;
+        }
+        if (source.startsWith("<?", index) || source.startsWith("?>", index)) {
+            index += 2;
+            continue;
+        }
+        if (source[index] === "/" && source[index + 1] === "*") {
+            const commentEnd = source.indexOf("*/", index + 2);
+            if (commentEnd === -1) {
+                return false;
+            }
+            index = commentEnd + 2;
+            continue;
+        }
+        const literal = parsePhpQuotedStringLiteralAt(source, index);
+        if (literal) {
+            if (literal.value.startsWith(literalPrefix)) {
+                return true;
+            }
+            index = literal.end;
+            continue;
+        }
+        if (source[index] === "/" && source[index + 1] === "/") {
+            index = findPhpLineBoundary(source, index + 2).nextStart;
+            continue;
+        }
+        if (source[index] === "#" && source[index + 1] !== "[") {
+            index = findPhpLineBoundary(source, index + 1).nextStart;
+            continue;
+        }
+        const heredoc = parsePhpHeredocStart(source, index);
+        if (heredoc) {
+            let cursor = heredoc.contentStart;
+            let closingEnd = null;
+            while (cursor < source.length) {
+                closingEnd = findPhpHeredocClosingEnd(source, cursor, heredoc.delimiter);
+                if (closingEnd !== null) {
+                    break;
+                }
+                cursor = findPhpLineBoundary(source, cursor).nextStart;
+            }
+            if (closingEnd === null) {
+                return false;
+            }
+            index = findPhpLineBoundary(source, closingEnd).nextStart;
+            continue;
+        }
+        index += 1;
+    }
+    return false;
+}
+function hasPhpFunctionCallWithStringArgumentMatching(source, functionName, matchesArgument, options) {
+    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)) {
+            index += 1;
+            continue;
+        }
+        const argumentStart = getPhpFunctionCallFirstArgumentStart(source, index, functionName);
+        if (argumentStart === null) {
+            index += functionName.length;
+            continue;
+        }
+        const argument = parsePhpQuotedStringLiteralAt(source, argumentStart);
+        if (!argument) {
+            index += functionName.length;
+            continue;
+        }
+        const argumentEnd = skipPhpCallTrivia(source, argument.end);
+        const nextToken = argumentEnd === null ? undefined : source[argumentEnd];
+        const isCompleteLiteralArgument = nextToken === "," || nextToken === ")" || nextToken === undefined;
+        const isSupportedPrefixExpression = options.allowConcatenatedPrefix && nextToken === ".";
+        if (!isCompleteLiteralArgument &&
+            !isSupportedPrefixExpression) {
+            index += functionName.length;
+            continue;
+        }
+        if (matchesArgument(argument.value)) {
+            return true;
+        }
+        index += functionName.length;
+    }
+    return false;
+}
 /**
  * Locate a PHP function body without counting braces in non-code regions.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wp-typia/project-tools",
-  "version": "0.24.9",
+  "version": "0.24.11",
   "description": "Project orchestration and programmatic tooling for wp-typia",
   "packageManager": "bun@1.3.11",
   "type": "module",