@wp-typia/project-tools 0.22.5 → 0.22.6

package/dist/runtime/fs-async.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Return whether a filesystem path exists without blocking the event loop.
+ *
+ * @param filePath Absolute or relative path to check.
+ * @returns `true` when the path can be accessed, otherwise `false`.
+ */
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Read a UTF-8 file when it exists and otherwise return `null`.
+ *
+ * @param filePath Absolute or relative file path to read.
+ * @returns The UTF-8 source, or `null` when the file is missing.
+ */
+export declare function readOptionalUtf8File(filePath: string): Promise<string | null>;
+/**
+ * Extract a Node.js error code from an unknown thrown value.
+ *
+ * @param error Unknown error value.
+ * @returns The string error code, or an empty string when unavailable.
+ */
+export declare function getNodeErrorCode(error: unknown): string;
+/**
+ * Return whether an unknown error represents a missing filesystem path.
+ *
+ * @param error Unknown error value.
+ * @returns `true` when the error has Node.js code `ENOENT`.
+ */
+export declare function isFileNotFoundError(error: unknown): boolean;

package/dist/runtime/fs-async.js

@@ -0,0 +1,53 @@
+import { promises as fsp } from "node:fs";
+/**
+ * Return whether a filesystem path exists without blocking the event loop.
+ *
+ * @param filePath Absolute or relative path to check.
+ * @returns `true` when the path can be accessed, otherwise `false`.
+ */
+export async function pathExists(filePath) {
+    try {
+        await fsp.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a UTF-8 file when it exists and otherwise return `null`.
+ *
+ * @param filePath Absolute or relative file path to read.
+ * @returns The UTF-8 source, or `null` when the file is missing.
+ */
+export async function readOptionalUtf8File(filePath) {
+    try {
+        return await fsp.readFile(filePath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+/**
+ * Extract a Node.js error code from an unknown thrown value.
+ *
+ * @param error Unknown error value.
+ * @returns The string error code, or an empty string when unavailable.
+ */
+export function getNodeErrorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+}
+/**
+ * Return whether an unknown error represents a missing filesystem path.
+ *
+ * @param error Unknown error value.
+ * @returns `true` when the error has Node.js code `ENOENT`.
+ */
+export function isFileNotFoundError(error) {
+    return getNodeErrorCode(error) === "ENOENT";
+}

package/dist/runtime/package-managers.js

@@ -12,7 +12,7 @@ const PACKAGE_MANAGER_DATA = [
         id: "npm",
         label: "npm",
         packageManagerField: "npm@11.6.1",
-        installCommand: "npm install",
+        installCommand: "npm install --no-audit",
         frozenInstallCommand: "npm ci",
     },
     {

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

@@ -12,5 +12,21 @@ export type ReplacePhpFunctionDefinitionOptions = PhpFunctionRangeOptions & {
 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/php-utils.js

@@ -7,6 +7,243 @@ export function quotePhpString(value) {
 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] === "(";
+}
+/**
+ * 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) {
+    let mode = "code";
+    let heredocDelimiter = "";
+    let index = 0;
+    while (index < source.length) {
+        const character = source[index];
+        if (mode === "heredoc") {
+            const closingEnd = findPhpHeredocClosingEnd(source, index, heredocDelimiter);
+            if (closingEnd !== null) {
+                mode = "code";
+                heredocDelimiter = "";
+                index = closingEnd;
+                continue;
+            }
+            const nextLineStart = findPhpLineBoundary(source, index).nextStart;
+            if (nextLineStart <= index) {
+                return false;
+            }
+            index = nextLineStart;
+            continue;
+        }
+        if (mode === "single-quoted" || mode === "double-quoted") {
+            const quote = mode === "single-quoted" ? "'" : '"';
+            if (character === "\\") {
+                index += 2;
+                continue;
+            }
+            if (character === quote) {
+                mode = "code";
+            }
+            index += 1;
+            continue;
+        }
+        if (mode === "line-comment") {
+            if (character === "\r" || character === "\n") {
+                mode = "code";
+            }
+            index += 1;
+            continue;
+        }
+        if (mode === "block-comment") {
+            if (character === "*" && source[index + 1] === "/") {
+                mode = "code";
+                index += 2;
+                continue;
+            }
+            index += 1;
+            continue;
+        }
+        if (character === "'") {
+            mode = "single-quoted";
+            index += 1;
+            continue;
+        }
+        if (character === '"') {
+            mode = "double-quoted";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && source[index + 1] === "/") {
+            mode = "line-comment";
+            index += 2;
+            continue;
+        }
+        if (character === "#" && source[index + 1] !== "[") {
+            mode = "line-comment";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && source[index + 1] === "*") {
+            mode = "block-comment";
+            index += 2;
+            continue;
+        }
+        if (character === "<") {
+            const heredocStart = parsePhpHeredocStart(source, index);
+            if (heredocStart) {
+                mode = "heredoc";
+                heredocDelimiter = heredocStart.delimiter;
+                index = heredocStart.contentStart;
+                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);
@@ -20,13 +257,95 @@ export function findPhpFunctionRange(source, functionName, options = {}) {
     }
     const openBraceIndex = functionStart + openBraceOffset;
     let depth = 0;
-    for (let index = openBraceIndex; index < source.length; index += 1) {
+    let mode = "code";
+    let heredocDelimiter = "";
+    let index = openBraceIndex;
+    while (index < source.length) {
         const character = source[index];
+        if (mode === "heredoc") {
+            const closingEnd = findPhpHeredocClosingEnd(source, index, heredocDelimiter);
+            if (closingEnd !== null) {
+                mode = "code";
+                heredocDelimiter = "";
+                index = closingEnd;
+                continue;
+            }
+            const nextLineStart = findPhpLineBoundary(source, index).nextStart;
+            if (nextLineStart <= index) {
+                return null;
+            }
+            index = nextLineStart;
+            continue;
+        }
+        if (mode === "single-quoted" || mode === "double-quoted") {
+            const quote = mode === "single-quoted" ? "'" : '"';
+            if (character === "\\") {
+                index += 2;
+                continue;
+            }
+            if (character === quote) {
+                mode = "code";
+            }
+            index += 1;
+            continue;
+        }
+        if (mode === "line-comment") {
+            if (character === "\r" || character === "\n") {
+                mode = "code";
+            }
+            index += 1;
+            continue;
+        }
+        if (mode === "block-comment") {
+            if (character === "*" && source[index + 1] === "/") {
+                mode = "code";
+                index += 2;
+                continue;
+            }
+            index += 1;
+            continue;
+        }
+        if (character === "'") {
+            mode = "single-quoted";
+            index += 1;
+            continue;
+        }
+        if (character === '"') {
+            mode = "double-quoted";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && source[index + 1] === "/") {
+            mode = "line-comment";
+            index += 2;
+            continue;
+        }
+        if (character === "#" && source[index + 1] !== "[") {
+            mode = "line-comment";
+            index += 1;
+            continue;
+        }
+        if (character === "/" && source[index + 1] === "*") {
+            mode = "block-comment";
+            index += 2;
+            continue;
+        }
+        if (character === "<") {
+            const heredocStart = parsePhpHeredocStart(source, index);
+            if (heredocStart) {
+                mode = "heredoc";
+                heredocDelimiter = heredocStart.delimiter;
+                index = heredocStart.contentStart;
+                continue;
+            }
+        }
         if (character === "{") {
             depth += 1;
+            index += 1;
             continue;
         }
         if (character !== "}") {
+            index += 1;
             continue;
         }
         depth -= 1;
@@ -43,6 +362,7 @@ export function findPhpFunctionRange(source, functionName, options = {}) {
                 start: functionStart,
             };
         }
+        index += 1;
     }
     return null;
 }

package/dist/runtime/scaffold-apply-utils.js

@@ -1,4 +1,3 @@
-import fs from "node:fs";
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
@@ -12,6 +11,7 @@ import { formatNonEmptyTargetDirectoryError, } from "./scaffold-bootstrap.js";
 import { stringifyBuiltInBlockJsonDocument, } from "./built-in-block-artifacts.js";
 import { copyInterpolatedDirectory } from "./template-render.js";
 import { formatInstallCommand, transformPackageManagerText, } from "./package-managers.js";
+import { pathExists, readOptionalUtf8File, } from "./fs-async.js";
 import { normalizePackageJson } from "./scaffold-package-manager-files.js";
 export { applyWorkspaceMigrationCapability, isOfficialWorkspaceProject, } from "./scaffold-bootstrap.js";
 import { replaceRepositoryReferencePlaceholders, resolveScaffoldRepositoryReference, } from "./scaffold-repository-reference.js";
@@ -28,10 +28,7 @@ const LOCKFILES = {
     yarn: ["yarn.lock"],
 };
 export async function ensureDirectory(targetDir, allowExisting = false) {
-    if (!fs.existsSync(targetDir)) {
-        await fsp.mkdir(targetDir, { recursive: true });
-        return;
-    }
+    await fsp.mkdir(targetDir, { recursive: true });
     if (allowExisting) {
         return;
     }
@@ -68,7 +65,7 @@ async function writeBuiltInCodeArtifacts(targetDir, codeArtifacts) {
         await fsp.writeFile(destinationPath, artifact.source, "utf8");
     }
 }
-function resolveScaffoldGeneratorNodeModulesPath() {
+async function resolveScaffoldGeneratorNodeModulesPath() {
     const projectToolsPackageRoot = path.resolve(__dirname, "..", "..");
     const candidates = [
         path.join(projectToolsPackageRoot, "node_modules"),
@@ -76,7 +73,7 @@ function resolveScaffoldGeneratorNodeModulesPath() {
         path.resolve(projectToolsPackageRoot, "..", "..", "node_modules"),
     ];
     for (const candidate of candidates) {
-        if (fs.existsSync(path.join(candidate, "typia", "package.json"))) {
+        if (await pathExists(path.join(candidate, "typia", "package.json"))) {
             return candidate;
         }
     }
@@ -84,11 +81,11 @@ function resolveScaffoldGeneratorNodeModulesPath() {
 }
 async function withEphemeralScaffoldNodeModules(targetDir, callback) {
     const targetNodeModulesPath = path.join(targetDir, "node_modules");
-    if (fs.existsSync(targetNodeModulesPath)) {
+    if (await pathExists(targetNodeModulesPath)) {
         await callback();
         return;
     }
-    const sourceNodeModulesPath = resolveScaffoldGeneratorNodeModulesPath();
+    const sourceNodeModulesPath = await resolveScaffoldGeneratorNodeModulesPath();
     if (!sourceNodeModulesPath) {
         throw new Error("Unable to resolve a node_modules directory with typia for scaffold-time REST artifact generation.");
     }
@@ -134,9 +131,7 @@ export async function normalizePackageManagerFiles(targetDir, packageManagerId)
         await fsp.writeFile(yarnRcPath, "nodeLinker: node-modules\n", "utf8");
         return;
     }
-    if (fs.existsSync(yarnRcPath)) {
-        await fsp.rm(yarnRcPath, { force: true });
-    }
+    await fsp.rm(yarnRcPath, { force: true });
 }
 export async function removeQueryLoopPlaceholderFiles(projectDir, templateId) {
     if (templateId !== "query-loop") {
@@ -153,10 +148,7 @@ export async function removeUnexpectedLockfiles(targetDir, packageManagerId) {
         if (keep.has(filename)) {
             return;
         }
-        const filePath = path.join(targetDir, filename);
-        if (fs.existsSync(filePath)) {
-            await fsp.rm(filePath, { force: true });
-        }
+        await fsp.rm(path.join(targetDir, filename), { force: true });
     }));
 }
 /**
@@ -251,7 +243,7 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
         title: "Finalizing scaffold output",
     });
     const readmePath = path.join(projectDir, "README.md");
-    if (!fs.existsSync(readmePath)) {
+    if (!(await pathExists(readmePath))) {
         await fsp.writeFile(readmePath, readmeContent ??
             buildReadme(templateId, variables, packageManager, {
                 withMigrationUi,
@@ -260,9 +252,7 @@ export async function applyBuiltInScaffoldProjectFiles({ projectDir, templateDir
             }), "utf8");
     }
     const gitignorePath = path.join(projectDir, ".gitignore");
-    const existingGitignore = fs.existsSync(gitignorePath)
-        ? await fsp.readFile(gitignorePath, "utf8")
-        : "";
+    const existingGitignore = await readOptionalUtf8File(gitignorePath) ?? "";
     await fsp.writeFile(gitignorePath, mergeTextLines(gitignoreContent ?? buildGitignore(), existingGitignore), "utf8");
     await normalizePackageJson(projectDir, packageManager);
     await applyGeneratedProjectDxPackageJson({

package/dist/runtime/scaffold-bootstrap.js

@@ -8,6 +8,7 @@ import { getPackageVersions } from "./package-versions.js";
 import { getStarterManifestFiles, stringifyStarterManifest } from "./starter-manifests.js";
 import { OFFICIAL_WORKSPACE_TEMPLATE_PACKAGE, PROJECT_TOOLS_PACKAGE_ROOT, } from "./template-registry.js";
 import { getScaffoldTemplateVariableGroups } from "./scaffold-template-variable-groups.js";
+import { pathExists } from "./fs-async.js";
 const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junction" : "dir";
 /**
  * Ensures the scaffold target directory exists and is empty unless explicitly allowed.
@@ -17,10 +18,7 @@ const EPHEMERAL_NODE_MODULES_LINK_TYPE = process.platform === "win32" ? "junctio
  * @returns A promise that resolves once the directory precondition is satisfied.
  */
 export async function ensureScaffoldDirectory(targetDir, allowExisting = false) {
-    if (!fs.existsSync(targetDir)) {
-        await fsp.mkdir(targetDir, { recursive: true });
-        return;
-    }
+    await fsp.mkdir(targetDir, { recursive: true });
     if (allowExisting) {
         return;
     }
@@ -165,14 +163,14 @@ export async function applyWorkspaceMigrationCapability(projectDir, packageManag
  *
  * @returns The first matching path, or `null` when no candidate contains `typia`.
  */
-function resolveScaffoldGeneratorNodeModulesPath() {
+async function resolveScaffoldGeneratorNodeModulesPath() {
     const candidates = [
         path.join(PROJECT_TOOLS_PACKAGE_ROOT, "node_modules"),
         path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", ".."),
         path.resolve(PROJECT_TOOLS_PACKAGE_ROOT, "..", "..", "node_modules"),
     ];
     for (const candidate of candidates) {
-        if (fs.existsSync(path.join(candidate, "typia", "package.json"))) {
+        if (await pathExists(path.join(candidate, "typia", "package.json"))) {
             return candidate;
         }
     }
@@ -193,11 +191,11 @@ function resolveScaffoldGeneratorNodeModulesPath() {
  */
 async function withEphemeralScaffoldNodeModules(targetDir, callback) {
     const targetNodeModulesPath = path.join(targetDir, "node_modules");
-    if (fs.existsSync(targetNodeModulesPath)) {
+    if (await pathExists(targetNodeModulesPath)) {
         await callback();
         return;
     }
-    const sourceNodeModulesPath = resolveScaffoldGeneratorNodeModulesPath();
+    const sourceNodeModulesPath = await resolveScaffoldGeneratorNodeModulesPath();
     if (!sourceNodeModulesPath) {
         throw new Error("Unable to resolve a node_modules directory with typia for scaffold-time REST artifact generation.");
     }

package/dist/runtime/scaffold-compatibility.d.ts

@@ -32,6 +32,16 @@ export interface ScaffoldCompatibilityConfig {
     requiredFeatures: string[];
     runtimeGates: string[];
 }
+/**
+ * Optional hooks for surfacing user-authored compatibility header repairs.
+ */
+export interface UpdatePluginHeaderCompatibilityOptions {
+    /**
+     * Receives warnings when a malformed existing plugin header value is
+     * replaced by the resolved policy floor.
+     */
+    onWarning?: (warning: string) => void;
+}
 /**
  * Baseline headers used by scaffold output before optional features are added.
  */
@@ -61,7 +71,9 @@ export declare function renderScaffoldCompatibilityConfig(policy: ScaffoldCompat
 /**
  * Patch a generated plugin bootstrap header without lowering custom floors.
  *
- * Preserves the original header line endings while replacing empty or invalid
- * version strings with the policy values.
+ * Preserves the original header line endings while replacing empty version
+ * strings with policy values. Malformed user-authored values are reported
+ * through `options.onWarning`; without a warning handler they throw instead of
+ * falling back silently.
  */
-export declare function updatePluginHeaderCompatibility(source: string, policy: ScaffoldCompatibilityPolicy): string;
+export declare function updatePluginHeaderCompatibility(source: string, policy: ScaffoldCompatibilityPolicy, options?: UpdatePluginHeaderCompatibilityOptions): string;