@wp-typia/project-tools 0.23.0 → 0.23.1

package/dist/runtime/cli-core.d.ts

@@ -30,7 +30,7 @@
  * `getTemplateSelectOptions`, `listTemplates`, and `isBuiltInTemplateId` for
  * template inspection flows.
  */
-export { getDoctorChecks, runDoctor, type DoctorCheck } from "./cli-doctor.js";
+export { createDoctorRunSummary, getDoctorChecks, getDoctorExitFailureChecks, getDoctorExitFailureDetailLines, runDoctor, type DoctorCheck, type DoctorCheckScope, type DoctorExitPolicy, type DoctorFailureSummary, type DoctorRunSummary, } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export type { CliDiagnosticCode, CliDiagnosticCodeError, CliDiagnosticMessage, } from "./cli-diagnostics.js";
 export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";

package/dist/runtime/cli-core.js

@@ -30,7 +30,7 @@
  * `getTemplateSelectOptions`, `listTemplates`, and `isBuiltInTemplateId` for
  * template inspection flows.
  */
-export { getDoctorChecks, runDoctor } from "./cli-doctor.js";
+export { createDoctorRunSummary, getDoctorChecks, getDoctorExitFailureChecks, getDoctorExitFailureDetailLines, runDoctor, } from "./cli-doctor.js";
 export { createCliCommandError, createCliDiagnosticCodeError, CliDiagnosticError, CLI_DIAGNOSTIC_CODE_METADATA, CLI_DIAGNOSTIC_CODES, formatCliDiagnosticError, formatDoctorCheckLine, formatDoctorSummaryLine, getCliDiagnosticCodeMetadata, getDoctorFailureDetailLines, getFailingDoctorChecks, isCliDiagnosticError, } from "./cli-diagnostics.js";
 export { EDITOR_PLUGIN_SLOT_IDS, formatAddHelpText, getWorkspaceBlockSelectOptions, getWorkspaceBlockSelectOptionsAsync, runAddAdminViewCommand, runAddAbilityCommand, runAddBindingSourceCommand, runAddAiFeatureCommand, runAddBlockCommand, runAddBlockStyleCommand, runAddBlockTransformCommand, runAddContractCommand, runAddEditorPluginCommand, runAddHookedBlockCommand, runAddPatternCommand, runAddPostMetaCommand, runAddRestResourceCommand, runAddVariationCommand, seedWorkspaceMigrationProject, } from "./cli-add.js";
 export { COMPOUND_INNER_BLOCKS_PRESET_IDS, getCompoundInnerBlocksPresetDefinition, } from "./compound-inner-blocks.js";

package/dist/runtime/cli-diagnostics.d.ts

@@ -160,7 +160,9 @@ export declare function getFailingDoctorChecks<TCheck extends DoctorCheckLike>(c
 /**
  * Format the final doctor summary row.
  */
-export declare function formatDoctorSummaryLine(checks: readonly DoctorCheckLike[]): string;
+export declare function formatDoctorSummaryLine(checks: readonly DoctorCheckLike[], options?: {
+    exitFailureChecks?: readonly DoctorCheckLike[];
+}): string;
 /**
  * Build detail lines for doctor failures so the non-interactive formatter can
  * restate the failed checks after the streaming rows.

package/dist/runtime/cli-diagnostics.js

@@ -228,9 +228,14 @@ export function createCliDiagnosticCodeError(code, message, options) {
 }
 /**
  * Compatibility-only fallback for legacy or third-party errors that have not
- * yet been tagged by their throw site. New user-facing failures should pass an
- * explicit code through `createCliDiagnosticCodeError()` or
- * `createCliCommandError({ code })` instead of relying on message matching.
+ * yet been tagged by their throw site.
+ *
+ * The regexes below intentionally couple this classifier to existing
+ * project-tools runtime validation messages. Treat them as compatibility shims:
+ * changing a validation message can silently change, downgrade, or remove the
+ * inferred diagnostic code. New user-facing runtime validation failures should
+ * pass an explicit code through `createCliDiagnosticCodeError()` or
+ * `createCliCommandError({ code })` instead of adding new message patterns.
  */
 function inferCliDiagnosticCode(options) {
     const inheritedCode = readCliDiagnosticCode(options.error);
@@ -362,12 +367,19 @@ export function getFailingDoctorChecks(checks) {
 /**
  * Format the final doctor summary row.
  */
-export function formatDoctorSummaryLine(checks) {
+export function formatDoctorSummaryLine(checks, options = {}) {
     const failedChecks = getFailingDoctorChecks(checks);
+    const exitFailureChecks = options.exitFailureChecks ?? failedChecks;
+    const advisoryFailureCount = failedChecks.length - exitFailureChecks.length;
     const warningCount = checks.filter((check) => check.status === "warn").length;
-    const summaryStatus = failedChecks.length > 0 ? "FAIL" : warningCount > 0 ? "WARN" : "PASS";
+    const summaryStatus = exitFailureChecks.length > 0
+        ? "FAIL"
+        : advisoryFailureCount > 0 || warningCount > 0
+            ? "WARN"
+            : "PASS";
     return formatWrappedPrefixedLine(`${summaryStatus} wp-typia doctor summary: `, [
         `${checks.length - failedChecks.length - warningCount}/${checks.length} checks passed`,
+        advisoryFailureCount > 0 ? `${advisoryFailureCount} advisory failure(s)` : null,
         warningCount > 0 ? `${warningCount} warning(s)` : null,
     ]
         .filter((detail) => detail !== null)

package/dist/runtime/cli-doctor-workspace-bindings.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
 import { checkExistingFiles, createDoctorCheck, resolveWorkspaceBootstrapPath, WORKSPACE_BINDING_EDITOR_ASSET, WORKSPACE_BINDING_EDITOR_SCRIPT, WORKSPACE_BINDING_SERVER_GLOB, } from "./cli-doctor-workspace-shared.js";
+import { readJsonFileSync } from "./json-utils.js";
 import { escapeRegex } from "./php-utils.js";
 function checkWorkspaceBindingBootstrap(projectDir, packageName) {
     const bootstrapPath = resolveWorkspaceBootstrapPath(projectDir, packageName);
@@ -45,7 +46,9 @@ function checkWorkspaceBindingTarget(projectDir, workspace, registeredBlockSlugs
     const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
     const issues = [];
     try {
-        const blockJson = parseScaffoldBlockMetadata(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
+        const blockJson = parseScaffoldBlockMetadata(readJsonFileSync(blockJsonPath, {
+            context: "workspace block metadata",
+        }));
         const attributes = blockJson.attributes;
         if (!attributes || typeof attributes !== "object" || Array.isArray(attributes)) {
             issues.push(`${blockJsonRelativePath} must define an attributes object`);

package/dist/runtime/cli-doctor-workspace-block-addons.d.ts

@@ -0,0 +1,12 @@
+import type { DoctorCheck } from "./cli-doctor.js";
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Collect variation, block style, transform, and pattern doctor checks.
+ *
+ * @param workspace Resolved workspace metadata and filesystem paths.
+ * @param inventory Parsed workspace inventory from `scripts/block-config.ts`.
+ * @param registeredBlockSlugs Block slugs already declared in the inventory.
+ * @returns Ordered add-on and pattern doctor checks.
+ */
+export declare function getWorkspaceBlockAddonDoctorChecks(workspace: WorkspaceProject, inventory: WorkspaceInventory, registeredBlockSlugs: ReadonlySet<string>): DoctorCheck[];

package/dist/runtime/cli-doctor-workspace-block-addons.js

@@ -0,0 +1,134 @@
+import fs from "node:fs";
+import path from "node:path";
+import { checkExistingFiles, createDoctorCheck, resolveWorkspaceBootstrapPath, WORKSPACE_FULL_BLOCK_NAME_PATTERN, } from "./cli-doctor-workspace-shared.js";
+import { hasExecutablePattern, hasUncommentedPattern, } from "./ts-source-masking.js";
+const WORKSPACE_VARIATIONS_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceVariations\s*\}\s*from\s*["']\.\/variations["']\s*;?\s*$/mu;
+const WORKSPACE_VARIATIONS_CALL_PATTERN = /registerWorkspaceVariations\s*\(\s*\)\s*;?/u;
+const WORKSPACE_BLOCK_STYLES_IMPORT_PATTERN = /^\s*import\s*\{\s*registerWorkspaceBlockStyles\s*\}\s*from\s*["']\.\/styles["']\s*;?\s*$/mu;
+const WORKSPACE_BLOCK_STYLES_CALL_PATTERN = /registerWorkspaceBlockStyles\s*\(\s*\)\s*;?/u;
+const WORKSPACE_BLOCK_TRANSFORMS_IMPORT_PATTERN = /^\s*import\s*\{\s*applyWorkspaceBlockTransforms\s*\}\s*from\s*["']\.\/transforms["']\s*;?\s*$/mu;
+const WORKSPACE_BLOCK_TRANSFORMS_CALL_PATTERN = /applyWorkspaceBlockTransforms\s*\(\s*registration\s*\.\s*settings\s*\)\s*;?/u;
+function checkWorkspacePatternBootstrap(projectDir, packageName) {
+    const bootstrapPath = resolveWorkspaceBootstrapPath(projectDir, packageName);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("Pattern bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const hasCategoryAnchor = source.includes("register_block_pattern_category");
+    const hasPatternGlob = source.includes("/src/patterns/*.php");
+    return createDoctorCheck("Pattern bootstrap", hasCategoryAnchor && hasPatternGlob ? "pass" : "fail", hasCategoryAnchor && hasPatternGlob
+        ? "Pattern category and loader hooks are present"
+        : "Missing pattern category registration or src/patterns loader hook");
+}
+function checkVariationEntrypoint(projectDir, blockSlug) {
+    const entryPath = path.join(projectDir, "src", "blocks", blockSlug, "index.tsx");
+    if (!fs.existsSync(entryPath)) {
+        return createDoctorCheck(`Variation entrypoint ${blockSlug}`, "fail", `Missing ${path.relative(projectDir, entryPath)}`);
+    }
+    const source = fs.readFileSync(entryPath, "utf8");
+    const hasImport = hasUncommentedPattern(source, WORKSPACE_VARIATIONS_IMPORT_PATTERN);
+    const hasCall = hasExecutablePattern(source, WORKSPACE_VARIATIONS_CALL_PATTERN);
+    return createDoctorCheck(`Variation entrypoint ${blockSlug}`, hasImport && hasCall ? "pass" : "fail", hasImport && hasCall
+        ? "Variations registration hook is present"
+        : "Missing ./variations import or registerWorkspaceVariations() call");
+}
+function checkBlockStyleEntrypoint(projectDir, blockSlug) {
+    const entryPath = path.join(projectDir, "src", "blocks", blockSlug, "index.tsx");
+    if (!fs.existsSync(entryPath)) {
+        return createDoctorCheck(`Block style entrypoint ${blockSlug}`, "fail", `Missing ${path.relative(projectDir, entryPath)}`);
+    }
+    const source = fs.readFileSync(entryPath, "utf8");
+    const hasImport = hasUncommentedPattern(source, WORKSPACE_BLOCK_STYLES_IMPORT_PATTERN);
+    const hasCall = hasExecutablePattern(source, WORKSPACE_BLOCK_STYLES_CALL_PATTERN);
+    return createDoctorCheck(`Block style entrypoint ${blockSlug}`, hasImport && hasCall ? "pass" : "fail", hasImport && hasCall
+        ? "Block style registration hook is present"
+        : "Missing ./styles import or registerWorkspaceBlockStyles() call");
+}
+function checkBlockTransformEntrypoint(projectDir, blockSlug) {
+    const entryPath = path.join(projectDir, "src", "blocks", blockSlug, "index.tsx");
+    if (!fs.existsSync(entryPath)) {
+        return createDoctorCheck(`Block transform entrypoint ${blockSlug}`, "fail", `Missing ${path.relative(projectDir, entryPath)}`);
+    }
+    const source = fs.readFileSync(entryPath, "utf8");
+    const hasImport = hasUncommentedPattern(source, WORKSPACE_BLOCK_TRANSFORMS_IMPORT_PATTERN);
+    const hasCall = hasExecutablePattern(source, WORKSPACE_BLOCK_TRANSFORMS_CALL_PATTERN);
+    return createDoctorCheck(`Block transform entrypoint ${blockSlug}`, hasImport && hasCall ? "pass" : "fail", hasImport && hasCall
+        ? "Block transform registration hook is present"
+        : "Missing ./transforms import or applyWorkspaceBlockTransforms(registration.settings) call");
+}
+function checkBlockTransformConfig(workspace, transform) {
+    const expectedTo = `${workspace.workspace.namespace}/${transform.block}`;
+    const issues = [];
+    if (!WORKSPACE_FULL_BLOCK_NAME_PATTERN.test(transform.from)) {
+        issues.push("from must use full namespace/block format");
+    }
+    if (transform.to !== expectedTo) {
+        issues.push(`to must equal "${expectedTo}" for workspace block "${transform.block}"`);
+    }
+    return createDoctorCheck(`Block transform config ${transform.block}/${transform.slug}`, issues.length === 0 ? "pass" : "fail", issues.length === 0
+        ? `${transform.from} transforms into ${transform.to}`
+        : issues.join("; "));
+}
+/**
+ * Collect variation, block style, transform, and pattern doctor checks.
+ *
+ * @param workspace Resolved workspace metadata and filesystem paths.
+ * @param inventory Parsed workspace inventory from `scripts/block-config.ts`.
+ * @param registeredBlockSlugs Block slugs already declared in the inventory.
+ * @returns Ordered add-on and pattern doctor checks.
+ */
+export function getWorkspaceBlockAddonDoctorChecks(workspace, inventory, registeredBlockSlugs) {
+    const checks = [];
+    const variationTargetBlocks = new Set();
+    for (const variation of inventory.variations) {
+        if (!registeredBlockSlugs.has(variation.block)) {
+            checks.push(createDoctorCheck(`Variation ${variation.block}/${variation.slug}`, "fail", `Variation references unknown block "${variation.block}"`));
+            continue;
+        }
+        variationTargetBlocks.add(variation.block);
+        checks.push(checkExistingFiles(workspace.projectDir, `Variation ${variation.block}/${variation.slug}`, [variation.file]));
+    }
+    for (const blockSlug of variationTargetBlocks) {
+        checks.push(checkVariationEntrypoint(workspace.projectDir, blockSlug));
+    }
+    const blockStyleTargetBlocks = new Set();
+    for (const blockStyle of inventory.blockStyles) {
+        if (!registeredBlockSlugs.has(blockStyle.block)) {
+            checks.push(createDoctorCheck(`Block style ${blockStyle.block}/${blockStyle.slug}`, "fail", `Block style references unknown block "${blockStyle.block}"`));
+            continue;
+        }
+        blockStyleTargetBlocks.add(blockStyle.block);
+        checks.push(checkExistingFiles(workspace.projectDir, `Block style ${blockStyle.block}/${blockStyle.slug}`, [blockStyle.file]));
+    }
+    for (const blockSlug of blockStyleTargetBlocks) {
+        checks.push(checkExistingFiles(workspace.projectDir, `Block style registry ${blockSlug}`, [
+            path.join("src", "blocks", blockSlug, "styles", "index.ts"),
+        ]));
+        checks.push(checkBlockStyleEntrypoint(workspace.projectDir, blockSlug));
+    }
+    const blockTransformTargetBlocks = new Set();
+    for (const blockTransform of inventory.blockTransforms) {
+        if (!registeredBlockSlugs.has(blockTransform.block)) {
+            checks.push(createDoctorCheck(`Block transform ${blockTransform.block}/${blockTransform.slug}`, "fail", `Block transform references unknown block "${blockTransform.block}"`));
+            continue;
+        }
+        blockTransformTargetBlocks.add(blockTransform.block);
+        checks.push(checkBlockTransformConfig(workspace, blockTransform));
+        checks.push(checkExistingFiles(workspace.projectDir, `Block transform ${blockTransform.block}/${blockTransform.slug}`, [blockTransform.file]));
+    }
+    for (const blockSlug of blockTransformTargetBlocks) {
+        checks.push(checkExistingFiles(workspace.projectDir, `Block transform registry ${blockSlug}`, [
+            path.join("src", "blocks", blockSlug, "transforms", "index.ts"),
+        ]));
+        checks.push(checkBlockTransformEntrypoint(workspace.projectDir, blockSlug));
+    }
+    const shouldCheckPatternBootstrap = inventory.patterns.length > 0 ||
+        fs.existsSync(path.join(workspace.projectDir, "src", "patterns"));
+    if (shouldCheckPatternBootstrap) {
+        checks.push(checkWorkspacePatternBootstrap(workspace.projectDir, workspace.packageName));
+    }
+    for (const pattern of inventory.patterns) {
+        checks.push(checkExistingFiles(workspace.projectDir, `Pattern ${pattern.slug}`, [pattern.file]));
+    }
+    return checks;
+}

package/dist/runtime/cli-doctor-workspace-block-iframe.d.ts

@@ -0,0 +1,9 @@
+import type { DoctorCheck } from "./cli-doctor.js";
+/**
+ * Collect iframe/API v3 compatibility checks for one workspace block.
+ *
+ * @param projectDir Absolute workspace project root.
+ * @param blockSlug Block slug from the workspace inventory.
+ * @returns Ordered iframe compatibility doctor checks.
+ */
+export declare function getWorkspaceBlockIframeCompatibilityChecks(projectDir: string, blockSlug: string): DoctorCheck[];

package/dist/runtime/cli-doctor-workspace-block-iframe.js

@@ -0,0 +1,228 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+import { createDoctorCheck } from "./cli-doctor-workspace-shared.js";
+import { readJsonFileSync } from "./json-utils.js";
+import { hasExecutablePattern, maskTypeScriptCommentsAndLiterals, } from "./ts-source-masking.js";
+const WORKSPACE_BLOCK_IFRAME_COMPATIBILITY_DOC_URL = "https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility/";
+const WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES = {
+    API_VERSION: "wp-typia.workspace.block.iframe.api-version",
+    BLOCK_PROPS: "wp-typia.workspace.block.iframe.block-props",
+    EDITOR_GLOBALS: "wp-typia.workspace.block.iframe.editor-globals",
+    EDITOR_STYLES: "wp-typia.workspace.block.iframe.editor-styles",
+};
+const WORKSPACE_BLOCK_EDITOR_SOURCE_FILE_PATTERN = /\.[cm]?[jt]sx?$/u;
+const WORKSPACE_BLOCK_EDITOR_SOURCE_BASENAMES = new Set([
+    "edit",
+    "editor",
+    "index",
+    "save",
+]);
+const WORKSPACE_BLOCK_EDITOR_SOURCE_DIRECTORIES = new Set([
+    "components",
+    "controls",
+    "editor",
+    "inspector",
+]);
+const WORKSPACE_BLOCK_LOCAL_STYLE_FILES = [
+    "editor.css",
+    "editor.scss",
+    "index.css",
+    "style.css",
+    "style.scss",
+];
+const WORKSPACE_BLOCK_IFRAME_GLOBAL_DOM_PATTERN = /\b(?:document|window)\b|\b(?:parent|top)\b(?!\s*:)/gu;
+const WORKSPACE_BLOCK_PROPS_PATTERN = /\buse(?:Block|InnerBlocks)Props(?:\.save)?\s*\(/u;
+function normalizePathSeparators(relativePath) {
+    return relativePath.split(path.sep).join("/");
+}
+function hasRegisteredBlockAsset(value) {
+    if (typeof value === "string") {
+        return value.trim().length > 0;
+    }
+    if (Array.isArray(value)) {
+        return value.some((entry) => hasRegisteredBlockAsset(entry));
+    }
+    return false;
+}
+function readWorkspaceBlockIframeMetadata(projectDir, blockSlug) {
+    const blockJsonRelativePath = path.join("src", "blocks", blockSlug, "block.json");
+    const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
+    if (!fs.existsSync(blockJsonPath)) {
+        return {
+            blockJsonRelativePath,
+            error: `Missing ${blockJsonRelativePath}`,
+        };
+    }
+    try {
+        const document = parseScaffoldBlockMetadata(readJsonFileSync(blockJsonPath, {
+            context: "workspace block metadata",
+        }));
+        return {
+            blockJsonRelativePath,
+            document,
+        };
+    }
+    catch (error) {
+        return {
+            blockJsonRelativePath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+function isWorkspaceBlockEditorSource(relativePath) {
+    if (!WORKSPACE_BLOCK_EDITOR_SOURCE_FILE_PATTERN.test(relativePath)) {
+        return false;
+    }
+    const normalizedRelativePath = normalizePathSeparators(relativePath);
+    const normalizedDirName = path.posix.dirname(normalizedRelativePath);
+    const normalizedBaseName = path.posix.basename(normalizedRelativePath, path.posix.extname(normalizedRelativePath));
+    if (WORKSPACE_BLOCK_EDITOR_SOURCE_BASENAMES.has(normalizedBaseName)) {
+        return true;
+    }
+    const pathSegments = normalizedDirName.split("/");
+    return pathSegments.some((segment) => WORKSPACE_BLOCK_EDITOR_SOURCE_DIRECTORIES.has(segment));
+}
+function isWorkspaceBlockSaveSource(relativePath) {
+    const normalizedBaseName = path.basename(relativePath, path.extname(relativePath));
+    return normalizedBaseName === "save";
+}
+function collectWorkspaceBlockEditorSources(projectDir, blockSlug) {
+    const blockDir = path.join(projectDir, "src", "blocks", blockSlug);
+    if (!fs.existsSync(blockDir)) {
+        return [];
+    }
+    const collected = [];
+    const queue = [blockDir];
+    while (queue.length > 0) {
+        const currentDir = queue.pop();
+        if (!currentDir) {
+            continue;
+        }
+        for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+            const absolutePath = path.join(currentDir, entry.name);
+            if (entry.isDirectory()) {
+                queue.push(absolutePath);
+                continue;
+            }
+            if (!entry.isFile()) {
+                continue;
+            }
+            const relativePath = path.relative(projectDir, absolutePath);
+            if (!isWorkspaceBlockEditorSource(relativePath)) {
+                continue;
+            }
+            collected.push({
+                relativePath: normalizePathSeparators(relativePath),
+                source: fs.readFileSync(absolutePath, "utf8"),
+            });
+        }
+    }
+    return collected.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function getSourceLineNumber(source, index) {
+    let line = 1;
+    for (let cursor = 0; cursor < index; cursor += 1) {
+        if (source[cursor] === "\n") {
+            line += 1;
+        }
+    }
+    return line;
+}
+function isGlobalDomAccessCandidate(source, index, identifier) {
+    const lineStart = source.lastIndexOf("\n", index - 1) + 1;
+    const lineEndCandidate = source.indexOf("\n", index);
+    const lineEnd = lineEndCandidate === -1 ? source.length : lineEndCandidate;
+    const lineSource = source.slice(lineStart, lineEnd);
+    const trimmedLine = lineSource.trimStart();
+    if (trimmedLine.startsWith("import ")) {
+        return false;
+    }
+    if (trimmedLine.startsWith("const ") ||
+        trimmedLine.startsWith("let ") ||
+        trimmedLine.startsWith("var ")) {
+        return false;
+    }
+    if (trimmedLine.startsWith("function ") || trimmedLine.startsWith("class ")) {
+        return false;
+    }
+    const precedingCharacter = index > 0 ? source[index - 1] : "";
+    if (precedingCharacter === "." || precedingCharacter === "'" || precedingCharacter === '"') {
+        return false;
+    }
+    return (identifier === "document" ||
+        identifier === "window" ||
+        identifier === "parent" ||
+        identifier === "top");
+}
+function findWorkspaceBlockGlobalDomAccesses(editorSources) {
+    return editorSources.flatMap(({ relativePath, source }) => {
+        const maskedSource = maskTypeScriptCommentsAndLiterals(source);
+        const matches = maskedSource.matchAll(WORKSPACE_BLOCK_IFRAME_GLOBAL_DOM_PATTERN);
+        const findings = [];
+        for (const match of matches) {
+            const identifier = match[0];
+            const matchIndex = match.index ?? -1;
+            if (matchIndex < 0) {
+                continue;
+            }
+            if (!isGlobalDomAccessCandidate(source, matchIndex, identifier)) {
+                continue;
+            }
+            findings.push(`${relativePath}:${getSourceLineNumber(source, matchIndex)}`);
+        }
+        return findings;
+    });
+}
+/**
+ * Collect iframe/API v3 compatibility checks for one workspace block.
+ *
+ * @param projectDir Absolute workspace project root.
+ * @param blockSlug Block slug from the workspace inventory.
+ * @returns Ordered iframe compatibility doctor checks.
+ */
+export function getWorkspaceBlockIframeCompatibilityChecks(projectDir, blockSlug) {
+    const metadataResult = readWorkspaceBlockIframeMetadata(projectDir, blockSlug);
+    if (!metadataResult.document) {
+        return [
+            createDoctorCheck(`Block iframe/API v3 ${blockSlug}`, "warn", metadataResult.error ?? `Unable to inspect ${metadataResult.blockJsonRelativePath}`, WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES.API_VERSION),
+        ];
+    }
+    const blockJson = metadataResult.document;
+    const apiVersion = typeof blockJson.apiVersion === "number" && Number.isFinite(blockJson.apiVersion)
+        ? blockJson.apiVersion
+        : null;
+    const blockDir = path.join(projectDir, "src", "blocks", blockSlug);
+    const localStyleFiles = WORKSPACE_BLOCK_LOCAL_STYLE_FILES.filter((fileName) => fs.existsSync(path.join(blockDir, fileName))).map((fileName) => normalizePathSeparators(path.join("src", "blocks", blockSlug, fileName)));
+    const hasRegisteredEditorStyles = hasRegisteredBlockAsset(blockJson.style) ||
+        hasRegisteredBlockAsset(blockJson.editorStyle);
+    const editorSources = collectWorkspaceBlockEditorSources(projectDir, blockSlug);
+    const editorWrapperSources = editorSources.filter((source) => !isWorkspaceBlockSaveSource(source.relativePath));
+    const globalDomAccesses = findWorkspaceBlockGlobalDomAccesses(editorSources);
+    const hasBlockPropsUsage = editorSources.some(({ source }) => hasExecutablePattern(source, WORKSPACE_BLOCK_PROPS_PATTERN));
+    const hasEditorBlockPropsUsage = editorWrapperSources.some(({ source }) => hasExecutablePattern(source, WORKSPACE_BLOCK_PROPS_PATTERN));
+    const blockWrapperStatus = editorWrapperSources.length === 0 || hasEditorBlockPropsUsage ? "pass" : "warn";
+    const blockWrapperDetail = editorSources.length === 0
+        ? "No editor-facing block source files found; general file checks will report missing entrypoints"
+        : editorWrapperSources.length === 0
+            ? "No editor wrapper source files found; general file checks will report missing entrypoints"
+            : hasEditorBlockPropsUsage
+                ? "Editor-facing sources use block wrapper props"
+                : hasBlockPropsUsage
+                    ? "Only save-facing useBlockProps.save() usage was detected. Confirm the editor wrapper also receives useBlockProps() or useInnerBlocksProps() before relying on iframe editor rendering."
+                    : "No useBlockProps(), useBlockProps.save(), or useInnerBlocksProps() usage was detected in editor-facing sources. Confirm the block wrapper receives WordPress block editor props before relying on iframe editor rendering.";
+    return [
+        createDoctorCheck(`Block iframe API version ${blockSlug}`, apiVersion !== null && apiVersion >= 3 ? "pass" : "warn", apiVersion !== null && apiVersion >= 3
+            ? "block.json declares apiVersion 3 for iframe editor readiness"
+            : `Set ${metadataResult.blockJsonRelativePath} apiVersion to 3 after testing the block in iframe-enabled Post Editor and Site Editor contexts. WordPress recommends API v3 for iframe editor compatibility. See ${WORKSPACE_BLOCK_IFRAME_COMPATIBILITY_DOC_URL}`, WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES.API_VERSION),
+        createDoctorCheck(`Block iframe styles ${blockSlug}`, localStyleFiles.length === 0 || hasRegisteredEditorStyles ? "pass" : "warn", localStyleFiles.length === 0
+            ? "No local block stylesheet source files found to register"
+            : hasRegisteredEditorStyles
+                ? "block.json registers block styles for iframe editor loading"
+                : `Found stylesheet source files (${localStyleFiles.join(", ")}) but block.json does not declare style or editorStyle. Register block content styles so iframe editors do not depend on parent admin styles.`, WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES.EDITOR_STYLES),
+        createDoctorCheck(`Block iframe globals ${blockSlug}`, globalDomAccesses.length === 0 ? "pass" : "warn", globalDomAccesses.length === 0
+            ? "No direct window/document/parent DOM access detected in editor-facing block sources"
+            : `Direct global DOM access detected at ${globalDomAccesses.join(", ")}. Prefer element.ownerDocument/defaultView via refs or useRefEffect for iframe editor content.`, WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES.EDITOR_GLOBALS),
+        createDoctorCheck(`Block iframe wrapper ${blockSlug}`, blockWrapperStatus, blockWrapperDetail, WORKSPACE_BLOCK_IFRAME_DIAGNOSTIC_CODES.BLOCK_PROPS),
+    ];
+}

package/dist/runtime/cli-doctor-workspace-block-metadata.d.ts

@@ -0,0 +1,11 @@
+import type { DoctorCheck } from "./cli-doctor.js";
+import type { WorkspaceInventory } from "./workspace-inventory.js";
+import type { WorkspaceProject } from "./workspace-project.js";
+/**
+ * Collect base file, metadata, hook, and collection-import checks for one block.
+ *
+ * @param workspace Resolved workspace metadata and filesystem paths.
+ * @param block Inventory row describing the generated block.
+ * @returns Ordered block core doctor checks.
+ */
+export declare function getWorkspaceBlockCoreDoctorChecks(workspace: WorkspaceProject, block: WorkspaceInventory["blocks"][number]): DoctorCheck[];

package/dist/runtime/cli-doctor-workspace-block-metadata.js

@@ -0,0 +1,111 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+import { checkExistingFiles, createDoctorCheck, WORKSPACE_GENERATED_BLOCK_ARTIFACTS, } from "./cli-doctor-workspace-shared.js";
+import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
+import { readJsonFileSync } from "./json-utils.js";
+const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
+const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
+function getWorkspaceBlockRequiredFiles(block) {
+    const blockDir = path.join("src", "blocks", block.slug);
+    return Array.from(new Set([
+        block.typesFile,
+        block.apiTypesFile,
+        block.openApiFile,
+        path.join(blockDir, "index.tsx"),
+        ...WORKSPACE_GENERATED_BLOCK_ARTIFACTS.map((fileName) => path.join(blockDir, fileName)),
+    ].filter((filePath) => typeof filePath === "string")));
+}
+function checkWorkspaceBlockMetadata(projectDir, workspace, block) {
+    const blockJsonRelativePath = path.join("src", "blocks", block.slug, "block.json");
+    const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
+    if (!fs.existsSync(blockJsonPath)) {
+        return createDoctorCheck(`Block metadata ${block.slug}`, "fail", `Missing ${blockJsonRelativePath}`);
+    }
+    let blockJson;
+    try {
+        blockJson = parseScaffoldBlockMetadata(readJsonFileSync(blockJsonPath, {
+            context: "workspace block metadata",
+        }));
+    }
+    catch (error) {
+        return createDoctorCheck(`Block metadata ${block.slug}`, "fail", error instanceof Error ? error.message : String(error));
+    }
+    const expectedName = `${workspace.workspace.namespace}/${block.slug}`;
+    const issues = [];
+    if (blockJson.name !== expectedName) {
+        issues.push(`block.json name must equal "${expectedName}"`);
+    }
+    if (blockJson.textdomain !== workspace.workspace.textDomain) {
+        issues.push(`block.json textdomain must equal "${workspace.workspace.textDomain}"`);
+    }
+    return createDoctorCheck(`Block metadata ${block.slug}`, issues.length === 0 ? "pass" : "fail", issues.length === 0
+        ? `block.json matches ${expectedName} and ${workspace.workspace.textDomain}`
+        : issues.join("; "));
+}
+function checkWorkspaceBlockHooks(projectDir, blockSlug) {
+    const blockJsonRelativePath = path.join("src", "blocks", blockSlug, "block.json");
+    const blockJsonPath = path.join(projectDir, blockJsonRelativePath);
+    if (!fs.existsSync(blockJsonPath)) {
+        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", `Missing ${blockJsonRelativePath}`);
+    }
+    let blockJson;
+    try {
+        blockJson = parseScaffoldBlockMetadata(readJsonFileSync(blockJsonPath, {
+            context: "workspace block metadata",
+        }));
+    }
+    catch (error) {
+        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", error instanceof Error ? error.message : String(error));
+    }
+    const blockHooks = blockJson.blockHooks;
+    if (blockHooks === undefined) {
+        return createDoctorCheck(`Block hooks ${blockSlug}`, "pass", "No blockHooks metadata configured");
+    }
+    if (!blockHooks || typeof blockHooks !== "object" || Array.isArray(blockHooks)) {
+        return createDoctorCheck(`Block hooks ${blockSlug}`, "fail", `${blockJsonRelativePath} must define blockHooks as an object when present.`);
+    }
+    const blockName = typeof blockJson.name === "string" && blockJson.name.trim().length > 0
+        ? blockJson.name.trim()
+        : null;
+    const invalidEntries = Object.entries(blockHooks).filter(([anchor, position]) => (blockName !== null && anchor.trim() === blockName) ||
+        anchor.trim().length === 0 ||
+        anchor !== anchor.trim() ||
+        !HOOKED_BLOCK_ANCHOR_PATTERN.test(anchor) ||
+        typeof position !== "string" ||
+        !HOOKED_BLOCK_POSITION_SET.has(position));
+    return createDoctorCheck(`Block hooks ${blockSlug}`, invalidEntries.length === 0 ? "pass" : "fail", invalidEntries.length === 0
+        ? `blockHooks metadata is valid${Object.keys(blockHooks).length > 0
+            ? ` (${Object.keys(blockHooks).join(", ")})`
+            : ""}`
+        : `Invalid blockHooks entries: ${invalidEntries
+            .map(([anchor, position]) => `${anchor || "<empty>"} => ${String(position)}`)
+            .join(", ")}`);
+}
+function checkWorkspaceBlockCollectionImport(projectDir, blockSlug) {
+    const entryRelativePath = path.join("src", "blocks", blockSlug, "index.tsx");
+    const entryPath = path.join(projectDir, entryRelativePath);
+    if (!fs.existsSync(entryPath)) {
+        return createDoctorCheck(`Block collection ${blockSlug}`, "fail", `Missing ${entryRelativePath}`);
+    }
+    const source = fs.readFileSync(entryPath, "utf8");
+    const hasCollectionImport = WORKSPACE_COLLECTION_IMPORT_PATTERN.test(source);
+    return createDoctorCheck(`Block collection ${blockSlug}`, hasCollectionImport ? "pass" : "fail", hasCollectionImport
+        ? "Shared block collection import is present"
+        : `Missing a shared collection import like ${WORKSPACE_COLLECTION_IMPORT_LINE}`);
+}
+/**
+ * Collect base file, metadata, hook, and collection-import checks for one block.
+ *
+ * @param workspace Resolved workspace metadata and filesystem paths.
+ * @param block Inventory row describing the generated block.
+ * @returns Ordered block core doctor checks.
+ */
+export function getWorkspaceBlockCoreDoctorChecks(workspace, block) {
+    return [
+        checkExistingFiles(workspace.projectDir, `Block ${block.slug}`, getWorkspaceBlockRequiredFiles(block)),
+        checkWorkspaceBlockMetadata(workspace.projectDir, workspace, block),
+        checkWorkspaceBlockHooks(workspace.projectDir, block.slug),
+        checkWorkspaceBlockCollectionImport(workspace.projectDir, block.slug),
+    ];
+}