@wp-typia/project-tools 0.16.11 → 0.16.13

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

@@ -0,0 +1,18 @@
+import type { DoctorCheck } from "./cli-doctor.js";
+/**
+ * Collect workspace-scoped doctor checks for the given working directory.
+ *
+ * When the directory is not an official workspace, the function returns a
+ * "Doctor scope" row explaining that only environment checks ran, plus a
+ * failing workspace metadata row when a nearby candidate workspace is invalid.
+ * When workspace resolution or metadata parsing throws, the corresponding
+ * failing rows are returned early and the remaining checks are skipped.
+ * When an official workspace is detected, a passing "Doctor scope" row is
+ * emitted first so the remaining package metadata, inventory, source-tree
+ * drift, and optional migration hint rows are clearly framed as workspace
+ * diagnostics for that run.
+ *
+ * @param cwd Working directory expected to host an official workspace.
+ * @returns Ordered workspace check rows ready for CLI rendering.
+ */
+export declare function getWorkspaceDoctorChecks(cwd: string): DoctorCheck[];

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

@@ -0,0 +1,308 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parseScaffoldBlockMetadata } from "@wp-typia/block-runtime/blocks";
+import { HOOKED_BLOCK_ANCHOR_PATTERN, HOOKED_BLOCK_POSITION_SET, } from "./hooked-blocks.js";
+import { readWorkspaceInventory } from "./workspace-inventory.js";
+import { getInvalidWorkspaceProjectReason, parseWorkspacePackageJson, WORKSPACE_TEMPLATE_PACKAGE, tryResolveWorkspaceProject, } from "./workspace-project.js";
+const WORKSPACE_COLLECTION_IMPORT_LINE = "import '../../collection';";
+const WORKSPACE_COLLECTION_IMPORT_PATTERN = /^\s*import\s+["']\.\.\/\.\.\/collection["']\s*;?\s*$/m;
+const WORKSPACE_BINDING_SERVER_GLOB = "/src/bindings/*/server.php";
+const WORKSPACE_BINDING_EDITOR_SCRIPT = "build/bindings/index.js";
+const WORKSPACE_BINDING_EDITOR_ASSET = "build/bindings/index.asset.php";
+const WORKSPACE_GENERATED_BLOCK_ARTIFACTS = [
+    "block.json",
+    "typia.manifest.json",
+    "typia.schema.json",
+    "typia-validator.php",
+    "typia.openapi.json",
+];
+function createDoctorCheck(label, status, detail) {
+    return { detail, label, status };
+}
+function createDoctorScopeCheck(status, detail) {
+    return createDoctorCheck("Doctor scope", status, detail);
+}
+function getWorkspaceBootstrapRelativePath(packageName) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    return `${packageBaseName}.php`;
+}
+function checkExistingFiles(projectDir, label, filePaths) {
+    const missing = filePaths
+        .filter((filePath) => typeof filePath === "string")
+        .filter((filePath) => !fs.existsSync(path.join(projectDir, filePath)));
+    return createDoctorCheck(label, missing.length === 0 ? "pass" : "fail", missing.length === 0 ? "All referenced files exist" : `Missing: ${missing.join(", ")}`);
+}
+function checkWorkspacePackageMetadata(workspace, packageJson) {
+    const issues = [];
+    const packageName = packageJson.name;
+    const bootstrapRelativePath = getWorkspaceBootstrapRelativePath(typeof packageName === "string" && packageName.length > 0 ? packageName : workspace.packageName);
+    const wpTypia = packageJson.wpTypia;
+    if (typeof packageName !== "string" || packageName.length === 0) {
+        issues.push("package.json must define a string name for workspace bootstrap resolution");
+    }
+    if (wpTypia?.projectType !== "workspace") {
+        issues.push('wpTypia.projectType must be "workspace"');
+    }
+    if (wpTypia?.templatePackage !== WORKSPACE_TEMPLATE_PACKAGE) {
+        issues.push(`wpTypia.templatePackage must be "${WORKSPACE_TEMPLATE_PACKAGE}"`);
+    }
+    if (wpTypia?.namespace !== workspace.workspace.namespace) {
+        issues.push(`wpTypia.namespace must equal "${workspace.workspace.namespace}"`);
+    }
+    if (wpTypia?.textDomain !== workspace.workspace.textDomain) {
+        issues.push(`wpTypia.textDomain must equal "${workspace.workspace.textDomain}"`);
+    }
+    if (wpTypia?.phpPrefix !== workspace.workspace.phpPrefix) {
+        issues.push(`wpTypia.phpPrefix must equal "${workspace.workspace.phpPrefix}"`);
+    }
+    if (!fs.existsSync(path.join(workspace.projectDir, bootstrapRelativePath))) {
+        issues.push(`Missing bootstrap file ${bootstrapRelativePath}`);
+    }
+    return createDoctorCheck("Workspace package metadata", issues.length === 0 ? "pass" : "fail", issues.length === 0
+        ? `package.json metadata aligns with ${workspace.packageName} and ${bootstrapRelativePath}`
+        : issues.join("; "));
+}
+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(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
+    }
+    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(JSON.parse(fs.readFileSync(blockJsonPath, "utf8")));
+    }
+    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}`);
+}
+function checkWorkspacePatternBootstrap(projectDir, packageName) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    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 checkWorkspaceBindingBootstrap(projectDir, packageName) {
+    const packageBaseName = packageName.split("/").pop() ?? packageName;
+    const bootstrapPath = path.join(projectDir, `${packageBaseName}.php`);
+    if (!fs.existsSync(bootstrapPath)) {
+        return createDoctorCheck("Binding bootstrap", "fail", `Missing ${path.basename(bootstrapPath)}`);
+    }
+    const source = fs.readFileSync(bootstrapPath, "utf8");
+    const hasServerGlob = source.includes(WORKSPACE_BINDING_SERVER_GLOB);
+    const hasEditorEnqueueHook = source.includes("enqueue_block_editor_assets");
+    const hasEditorScript = source.includes(WORKSPACE_BINDING_EDITOR_SCRIPT);
+    const hasEditorAsset = source.includes(WORKSPACE_BINDING_EDITOR_ASSET);
+    return createDoctorCheck("Binding bootstrap", hasServerGlob && hasEditorEnqueueHook && hasEditorScript && hasEditorAsset ? "pass" : "fail", hasServerGlob && hasEditorEnqueueHook && hasEditorScript && hasEditorAsset
+        ? "Binding source PHP and editor bootstrap hooks are present"
+        : "Missing binding source PHP require glob or editor enqueue hook");
+}
+function checkWorkspaceBindingSourcesIndex(projectDir, bindingSources) {
+    const indexRelativePath = [path.join("src", "bindings", "index.ts"), path.join("src", "bindings", "index.js")].find((relativePath) => fs.existsSync(path.join(projectDir, relativePath)));
+    if (!indexRelativePath) {
+        return createDoctorCheck("Binding sources index", "fail", "Missing src/bindings/index.ts or src/bindings/index.js");
+    }
+    const indexPath = path.join(projectDir, indexRelativePath);
+    const source = fs.readFileSync(indexPath, "utf8");
+    const missingImports = bindingSources.filter((bindingSource) => !source.includes(`./${bindingSource.slug}/editor`));
+    return createDoctorCheck("Binding sources index", missingImports.length === 0 ? "pass" : "fail", missingImports.length === 0
+        ? "Binding source editor registrations are aggregated"
+        : `Missing editor imports for: ${missingImports.map((entry) => entry.slug).join(", ")}`);
+}
+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 = source.includes("./variations");
+    const hasCall = source.includes("registerWorkspaceVariations()");
+    return createDoctorCheck(`Variation entrypoint ${blockSlug}`, hasImport && hasCall ? "pass" : "fail", hasImport && hasCall
+        ? "Variations registration hook is present"
+        : "Missing ./variations import or registerWorkspaceVariations() call");
+}
+function checkMigrationWorkspaceHint(workspace, packageJson) {
+    const hasMigrationScript = typeof packageJson.scripts?.["migration:doctor"] === "string";
+    const migrationConfigRelativePath = path.join("src", "migrations", "config.ts");
+    const hasMigrationConfig = fs.existsSync(path.join(workspace.projectDir, migrationConfigRelativePath));
+    if (!hasMigrationScript && !hasMigrationConfig) {
+        return null;
+    }
+    return createDoctorCheck("Migration workspace", hasMigrationConfig ? "pass" : "fail", hasMigrationConfig
+        ? "Run `wp-typia migrate doctor --all` for migration target, snapshot, fixture, and generated artifact checks"
+        : `Missing ${migrationConfigRelativePath} for the configured migration workspace`);
+}
+/**
+ * Collect workspace-scoped doctor checks for the given working directory.
+ *
+ * When the directory is not an official workspace, the function returns a
+ * "Doctor scope" row explaining that only environment checks ran, plus a
+ * failing workspace metadata row when a nearby candidate workspace is invalid.
+ * When workspace resolution or metadata parsing throws, the corresponding
+ * failing rows are returned early and the remaining checks are skipped.
+ * When an official workspace is detected, a passing "Doctor scope" row is
+ * emitted first so the remaining package metadata, inventory, source-tree
+ * drift, and optional migration hint rows are clearly framed as workspace
+ * diagnostics for that run.
+ *
+ * @param cwd Working directory expected to host an official workspace.
+ * @returns Ordered workspace check rows ready for CLI rendering.
+ */
+export function getWorkspaceDoctorChecks(cwd) {
+    const checks = [];
+    let workspace = null;
+    let invalidWorkspaceReason = null;
+    try {
+        invalidWorkspaceReason = getInvalidWorkspaceProjectReason(cwd);
+        workspace = tryResolveWorkspaceProject(cwd);
+    }
+    catch (error) {
+        checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace discovery could not continue. Fix the nearby workspace package metadata and rerun `wp-typia doctor`."));
+        checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
+        return checks;
+    }
+    if (!workspace) {
+        if (invalidWorkspaceReason) {
+            checks.push(createDoctorScopeCheck("fail", "Environment checks ran, but workspace diagnostics could not continue because a nearby wp-typia workspace candidate is invalid. Fix the workspace package metadata and rerun `wp-typia doctor`."));
+            checks.push(createDoctorCheck("Workspace package metadata", "fail", invalidWorkspaceReason));
+        }
+        else {
+            checks.push(createDoctorScopeCheck("pass", "No official wp-typia workspace root was detected, so this run only covered environment readiness. Re-run `wp-typia doctor` from a workspace root if you expected package metadata, inventory, or generated artifact checks."));
+        }
+        return checks;
+    }
+    checks.push(createDoctorScopeCheck("pass", `Official workspace detected for ${workspace.workspace.namespace}; environment readiness checks ran and workspace-scoped diagnostics are enabled for the package metadata, inventory, source-tree drift, and any configured migration hint rows below.`));
+    let workspacePackageJson;
+    try {
+        workspacePackageJson = parseWorkspacePackageJson(workspace.projectDir);
+    }
+    catch (error) {
+        checks.push(createDoctorCheck("Workspace package metadata", "fail", error instanceof Error ? error.message : String(error)));
+        return checks;
+    }
+    checks.push(checkWorkspacePackageMetadata(workspace, workspacePackageJson));
+    try {
+        const inventory = readWorkspaceInventory(workspace.projectDir);
+        checks.push(createDoctorCheck("Workspace inventory", "pass", `${inventory.blocks.length} block(s), ${inventory.variations.length} variation(s), ${inventory.patterns.length} pattern(s), ${inventory.bindingSources.length} binding source(s)`));
+        for (const block of inventory.blocks) {
+            checks.push(checkExistingFiles(workspace.projectDir, `Block ${block.slug}`, getWorkspaceBlockRequiredFiles(block)));
+            checks.push(checkWorkspaceBlockMetadata(workspace.projectDir, workspace, block));
+            checks.push(checkWorkspaceBlockHooks(workspace.projectDir, block.slug));
+            checks.push(checkWorkspaceBlockCollectionImport(workspace.projectDir, block.slug));
+        }
+        const registeredBlockSlugs = new Set(inventory.blocks.map((block) => block.slug));
+        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 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]));
+        }
+        if (inventory.bindingSources.length > 0) {
+            checks.push(checkWorkspaceBindingBootstrap(workspace.projectDir, workspace.packageName));
+            checks.push(checkWorkspaceBindingSourcesIndex(workspace.projectDir, inventory.bindingSources));
+        }
+        for (const bindingSource of inventory.bindingSources) {
+            checks.push(checkExistingFiles(workspace.projectDir, `Binding source ${bindingSource.slug}`, [
+                bindingSource.serverFile,
+                bindingSource.editorFile,
+            ]));
+        }
+        const migrationWorkspaceCheck = checkMigrationWorkspaceHint(workspace, workspacePackageJson);
+        if (migrationWorkspaceCheck) {
+            checks.push(migrationWorkspaceCheck);
+        }
+    }
+    catch (error) {
+        checks.push(createDoctorCheck("Workspace inventory", "fail", error instanceof Error ? error.message : String(error)));
+    }
+    return checks;
+}

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

@@ -16,8 +16,10 @@ interface RunDoctorOptions {
 /**
  * Collect all runtime doctor checks for the current environment.
  *
- * The returned array includes command availability checks, directory
- * writability checks, and built-in template asset checks in display order.
+ * The returned array concatenates environment checks (command availability,
+ * directory writability, and built-in template assets) followed by
+ * workspace checks (package metadata, inventory, blocks, variations,
+ * patterns, bindings, and optional migration hints) in display order.
  *
  * @param cwd Working directory to validate for writability.
  * @returns Ordered doctor check rows ready for CLI rendering.