@wp-typia/project-tools 0.24.3 → 0.24.5

package/dist/runtime/add/compound-inner-blocks.js

@@ -0,0 +1,88 @@
+/**
+ * Stable preset ids exposed to scaffold and UI consumers for compound
+ * InnerBlocks authoring behavior.
+ */
+export const COMPOUND_INNER_BLOCKS_PRESET_IDS = [
+    "freeform",
+    "ordered",
+    "horizontal",
+    "locked-structure",
+];
+/**
+ * Default preset applied when callers do not provide an explicit compound
+ * InnerBlocks mode.
+ */
+export const DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID = "freeform";
+/**
+ * Canonical preset registry used by the CLI, generated scaffolds, and TUI
+ * forms.
+ */
+export const COMPOUND_INNER_BLOCKS_PRESET_REGISTRY = {
+    freeform: {
+        description: "Unlocked nested authoring with the default inserter and starter child template.",
+        directInsert: false,
+        label: "freeform",
+        orientation: "vertical",
+        templateLock: false,
+    },
+    ordered: {
+        description: "Vertical ordered flow that keeps starter structure fixed while allowing new sibling inserts.",
+        directInsert: true,
+        label: "ordered",
+        orientation: "vertical",
+        templateLock: "insert",
+    },
+    horizontal: {
+        description: "Horizontal nested layout with one-click direct inserts for row or tab style containers.",
+        directInsert: true,
+        label: "horizontal",
+        orientation: "horizontal",
+        templateLock: false,
+    },
+    "locked-structure": {
+        description: "Locked starter structure for guided document shells where authors should only edit seeded children.",
+        directInsert: false,
+        label: "locked-structure",
+        orientation: "vertical",
+        templateLock: "all",
+    },
+};
+/**
+ * Returns whether a string matches one of the supported compound preset ids.
+ */
+export function isCompoundInnerBlocksPresetId(value) {
+    return COMPOUND_INNER_BLOCKS_PRESET_IDS.includes(value);
+}
+/**
+ * Parses a raw CLI or config value into a supported preset id.
+ *
+ * Returns `undefined` for non-string or empty input, and throws when the input
+ * is a non-empty unsupported preset id.
+ */
+export function parseCompoundInnerBlocksPreset(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const normalizedValue = value.trim();
+    if (normalizedValue.length === 0) {
+        return undefined;
+    }
+    if (!isCompoundInnerBlocksPresetId(normalizedValue)) {
+        throw new Error(`Unsupported InnerBlocks preset "${value}". Expected one of: ${COMPOUND_INNER_BLOCKS_PRESET_IDS.join(", ")}.`);
+    }
+    return normalizedValue;
+}
+/**
+ * Resolves an optional preset id to a concrete preset, defaulting to
+ * `DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID`.
+ */
+export function resolveCompoundInnerBlocksPreset(value) {
+    return value ?? DEFAULT_COMPOUND_INNER_BLOCKS_PRESET_ID;
+}
+/**
+ * Looks up the preset definition for the provided preset id, applying the
+ * default preset when the input is omitted.
+ */
+export function getCompoundInnerBlocksPresetDefinition(value) {
+    return COMPOUND_INNER_BLOCKS_PRESET_REGISTRY[resolveCompoundInnerBlocksPreset(value)];
+}

package/dist/runtime/add/contract-artifacts.d.ts

@@ -0,0 +1,14 @@
+interface SyncStandaloneContractArtifactsOptions {
+    projectDir: string;
+    schemaFile: string;
+    sourceTypeName: string;
+    typesFile: string;
+}
+/**
+ * Generate the JSON Schema artifact for a standalone TypeScript contract.
+ *
+ * @param options Workspace-relative type/schema paths plus the exported source
+ * type name.
+ */
+export declare function syncStandaloneContractArtifacts({ projectDir, schemaFile, sourceTypeName, typesFile, }: SyncStandaloneContractArtifactsOptions): Promise<void>;
+export {};

package/dist/runtime/add/contract-artifacts.js

@@ -0,0 +1,15 @@
+import { syncTypeSchemas, } from "@wp-typia/block-runtime/metadata-core";
+/**
+ * Generate the JSON Schema artifact for a standalone TypeScript contract.
+ *
+ * @param options Workspace-relative type/schema paths plus the exported source
+ * type name.
+ */
+export async function syncStandaloneContractArtifacts({ projectDir, schemaFile, sourceTypeName, typesFile, }) {
+    await syncTypeSchemas({
+        jsonSchemaFile: schemaFile,
+        projectRoot: projectDir,
+        sourceTypeName,
+        typesFile,
+    });
+}

package/dist/runtime/add/hooked-blocks.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared hooked-block metadata primitives used by add flows, doctor checks,
+ * and interactive prompts.
+ */
+export declare const HOOKED_BLOCK_POSITION_IDS: readonly ["before", "after", "firstChild", "lastChild"];
+/**
+ * Union of valid `blockHooks` positions accepted by wp-typia workspace flows.
+ */
+export type HookedBlockPositionId = (typeof HOOKED_BLOCK_POSITION_IDS)[number];
+/**
+ * Fast lookup set for validating hooked-block positions across runtime surfaces.
+ */
+export declare const HOOKED_BLOCK_POSITION_SET: Set<string>;
+/**
+ * Canonical `namespace/slug` block name format required for hooked-block anchors.
+ */
+export declare const HOOKED_BLOCK_ANCHOR_PATTERN: RegExp;

package/dist/runtime/add/hooked-blocks.js

@@ -0,0 +1,13 @@
+/**
+ * Shared hooked-block metadata primitives used by add flows, doctor checks,
+ * and interactive prompts.
+ */
+export const HOOKED_BLOCK_POSITION_IDS = ["before", "after", "firstChild", "lastChild"];
+/**
+ * Fast lookup set for validating hooked-block positions across runtime surfaces.
+ */
+export const HOOKED_BLOCK_POSITION_SET = new Set(HOOKED_BLOCK_POSITION_IDS);
+/**
+ * Canonical `namespace/slug` block name format required for hooked-block anchors.
+ */
+export const HOOKED_BLOCK_ANCHOR_PATTERN = /^[a-z0-9-]+\/[a-z0-9-]+$/;

package/dist/runtime/add/pattern-catalog-section-roles.d.ts

@@ -0,0 +1,101 @@
+import { type ParsedBlockPatternBlock } from "@wp-typia/block-runtime/metadata-core";
+import type { PatternCatalogDiagnostic, PatternCatalogEntry } from "./pattern-catalog.js";
+/**
+ * Validates section role slugs used by pattern manifests and content markers.
+ */
+export declare const PATTERN_SECTION_ROLE_PATTERN: RegExp;
+/**
+ * Convention used to discover section role markers in serialized pattern
+ * content. Defaults target `core/group` wrappers with a `section` base class,
+ * `section--{role}` role class tokens, and `metadata.sectionRole` attributes.
+ */
+export type PatternCatalogSectionRoleConvention = {
+    /**
+     * Serialized block name used as the section wrapper. Defaults to
+     * `core/group`.
+     */
+    wrapperBlockName?: string;
+    /**
+     * Optional class that marks a wrapper block as section-like even when the
+     * role marker is missing. Defaults to `section`.
+     */
+    baseClassName?: string;
+    /**
+     * Class token pattern where exactly one `{role}` placeholder is replaced by
+     * the section role slug. Defaults to `section--{role}`.
+     */
+    roleClassNamePattern?: string;
+    /**
+     * Dot-separated block attribute paths that can carry role slugs. Defaults to
+     * `metadata.sectionRole`.
+     */
+    roleAttributePaths?: readonly string[];
+    /**
+     * Warn when a full pattern repeats the same section role marker. Defaults to
+     * `false`.
+     */
+    requireUniqueFullPatternRoles?: boolean;
+};
+/**
+ * Section wrapper match extracted from a parsed WordPress block tree.
+ */
+export type PatternCatalogSectionRoleMatch = {
+    blockName: string;
+    blockPath: string;
+    roles: readonly string[];
+};
+/**
+ * Fully resolved section-role marker convention with its compiled class matcher.
+ */
+export type NormalizedPatternCatalogSectionRoleConvention = Required<PatternCatalogSectionRoleConvention> & {
+    /**
+     * Compiled matcher for role class tokens produced from `roleClassNamePattern`.
+     */
+    roleClassNamePatternRegExp: RegExp;
+};
+/**
+ * Resolve a section-role convention and compile its class-token matcher.
+ *
+ * @param convention Optional marker convention override.
+ * @returns A fully populated convention ready for repeated block traversal.
+ * @throws When `roleClassNamePattern` does not contain exactly one `{role}` placeholder.
+ */
+export declare function normalizePatternCatalogSectionRoleConvention(convention?: PatternCatalogSectionRoleConvention): NormalizedPatternCatalogSectionRoleConvention;
+/**
+ * Extract section role slugs from serialized block attributes using the
+ * configured class and metadata marker convention.
+ *
+ * @param attributes Parsed block attributes from serialized pattern content.
+ * @param convention Optional marker convention override.
+ * @returns Unique role marker values in discovery order.
+ */
+export declare function extractPatternSectionRolesFromAttributes(attributes: Record<string, unknown>, convention?: PatternCatalogSectionRoleConvention): string[];
+/**
+ * Find section wrapper blocks and their role markers in parsed pattern content.
+ *
+ * @param blocks Parsed block tree returned by `validateBlockPatternContentNesting`.
+ * @param convention Optional marker convention override.
+ * @returns Section wrapper matches with serialized block paths.
+ */
+export declare function extractPatternSectionRoleMatches(blocks: readonly ParsedBlockPatternBlock[], convention?: PatternCatalogSectionRoleConvention): PatternCatalogSectionRoleMatch[];
+/**
+ * Build the known valid section-role set from pattern catalog entries.
+ *
+ * @param patterns Catalog entries that may declare a `sectionRole`.
+ * @returns Valid section role slugs declared by the catalog.
+ */
+export declare function collectKnownPatternSectionRoles(patterns: readonly Pick<PatternCatalogEntry, "sectionRole">[]): ReadonlySet<string>;
+/**
+ * Validate serialized pattern content against the catalog section-role rules.
+ *
+ * @param options Pattern content, marker convention, known roles, and diagnostic context.
+ * @returns Diagnostics for invalid, missing, mismatched, unknown, or duplicate section-role markers.
+ */
+export declare function validatePatternContentSectionRoles({ content, contentFile, convention, knownSectionRoles, label, pattern, }: {
+    content: string;
+    contentFile: string;
+    convention: NormalizedPatternCatalogSectionRoleConvention;
+    knownSectionRoles: ReadonlySet<string>;
+    label: string;
+    pattern: PatternCatalogEntry;
+}): PatternCatalogDiagnostic[];

package/dist/runtime/add/pattern-catalog-section-roles.js

@@ -0,0 +1,276 @@
+import { validateBlockPatternContentNesting, } from "@wp-typia/block-runtime/metadata-core";
+/**
+ * Validates section role slugs used by pattern manifests and content markers.
+ */
+export const PATTERN_SECTION_ROLE_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const DEFAULT_SECTION_ROLE_CONVENTION = {
+    baseClassName: "section",
+    requireUniqueFullPatternRoles: false,
+    roleAttributePaths: ["metadata.sectionRole"],
+    roleClassNamePattern: "section--{role}",
+    wrapperBlockName: "core/group",
+};
+function createPatternCatalogDiagnostic(diagnostic) {
+    return diagnostic;
+}
+function normalizeSectionRoleConventionInput(convention = {}) {
+    return {
+        baseClassName: convention.baseClassName ??
+            DEFAULT_SECTION_ROLE_CONVENTION.baseClassName,
+        requireUniqueFullPatternRoles: convention.requireUniqueFullPatternRoles ??
+            DEFAULT_SECTION_ROLE_CONVENTION.requireUniqueFullPatternRoles,
+        roleAttributePaths: convention.roleAttributePaths ??
+            DEFAULT_SECTION_ROLE_CONVENTION.roleAttributePaths,
+        roleClassNamePattern: convention.roleClassNamePattern ??
+            DEFAULT_SECTION_ROLE_CONVENTION.roleClassNamePattern,
+        wrapperBlockName: convention.wrapperBlockName ??
+            DEFAULT_SECTION_ROLE_CONVENTION.wrapperBlockName,
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+function createRoleClassNamePattern(pattern) {
+    const parts = pattern.split("{role}");
+    if (parts.length !== 2) {
+        throw new Error(`roleClassNamePattern must contain exactly one "{role}" placeholder.`);
+    }
+    return new RegExp(`^${escapeRegExp(parts[0] ?? "")}(?<role>\\S*)${escapeRegExp(parts[1] ?? "")}$`, "u");
+}
+/**
+ * Resolve a section-role convention and compile its class-token matcher.
+ *
+ * @param convention Optional marker convention override.
+ * @returns A fully populated convention ready for repeated block traversal.
+ * @throws When `roleClassNamePattern` does not contain exactly one `{role}` placeholder.
+ */
+export function normalizePatternCatalogSectionRoleConvention(convention = {}) {
+    const normalized = normalizeSectionRoleConventionInput(convention);
+    return {
+        ...normalized,
+        roleClassNamePatternRegExp: createRoleClassNamePattern(normalized.roleClassNamePattern),
+    };
+}
+function getClassNameTokens(attributes) {
+    const className = attributes.className;
+    if (typeof className !== "string") {
+        return [];
+    }
+    return className.split(/\s+/u).filter((token) => token.length > 0);
+}
+function getAttributePathValue(attributes, pathName) {
+    return pathName.split(".").reduce((current, segment) => {
+        if (current !== null &&
+            typeof current === "object" &&
+            !Array.isArray(current) &&
+            Object.prototype.hasOwnProperty.call(current, segment)) {
+            return current[segment];
+        }
+        return undefined;
+    }, attributes);
+}
+function collectStringValues(value) {
+    if (typeof value === "string") {
+        return [value];
+    }
+    if (Array.isArray(value)) {
+        return value.filter((item) => typeof item === "string");
+    }
+    return [];
+}
+function uniqueValues(values) {
+    return [...new Set(values)];
+}
+function formatRoleList(roles) {
+    if (roles.length === 0) {
+        return "none";
+    }
+    return roles.map((role) => `"${role}"`).join(", ");
+}
+function formatBlockPaths(paths) {
+    return paths.map((blockPath) => `at ${blockPath}`).join(", ");
+}
+function describeRoleMarkerConvention(convention) {
+    return `${convention.wrapperBlockName} wrappers with class "${convention.roleClassNamePattern}" or attributes ${convention.roleAttributePaths.join(", ")}`;
+}
+function isSectionWrapperCandidate(block, roles, convention) {
+    if (block.blockName !== convention.wrapperBlockName) {
+        return false;
+    }
+    if (roles.length > 0) {
+        return true;
+    }
+    return getClassNameTokens(block.attributes).includes(convention.baseClassName);
+}
+function collectSectionRoleMatches(blocks, convention, pathSegments = []) {
+    return blocks.flatMap((block, index) => {
+        const blockPathSegments = [
+            ...pathSegments,
+            `${block.blockName}[${index}]`,
+        ];
+        const blockPath = blockPathSegments.join(" > ");
+        const roles = extractPatternSectionRolesFromNormalizedAttributes(block.attributes, convention);
+        const matches = isSectionWrapperCandidate(block, roles, convention)
+            ? [
+                {
+                    blockName: block.blockName,
+                    blockPath,
+                    roles,
+                },
+            ]
+            : [];
+        return [
+            ...matches,
+            ...collectSectionRoleMatches(block.innerBlocks, convention, blockPathSegments),
+        ];
+    });
+}
+function unescapeSerializedBlockCommentJsonQuotes(content) {
+    return content.replace(/<!--([\s\S]*?)-->/gu, (comment, body) => {
+        const source = body.trim();
+        if (!source.startsWith("wp:") && !source.startsWith("/wp:")) {
+            return comment;
+        }
+        return `<!--${body.replace(/\\"/gu, '"')}-->`;
+    });
+}
+/**
+ * Extract section role slugs from serialized block attributes using the
+ * configured class and metadata marker convention.
+ *
+ * @param attributes Parsed block attributes from serialized pattern content.
+ * @param convention Optional marker convention override.
+ * @returns Unique role marker values in discovery order.
+ */
+export function extractPatternSectionRolesFromAttributes(attributes, convention = {}) {
+    const normalized = normalizePatternCatalogSectionRoleConvention(convention);
+    return extractPatternSectionRolesFromNormalizedAttributes(attributes, normalized);
+}
+function extractPatternSectionRolesFromNormalizedAttributes(attributes, normalized) {
+    const classRoles = getClassNameTokens(attributes)
+        .map((token) => normalized.roleClassNamePatternRegExp.exec(token)?.groups?.role)
+        .filter((role) => typeof role === "string");
+    const attributeRoles = normalized.roleAttributePaths.flatMap((pathName) => collectStringValues(getAttributePathValue(attributes, pathName)));
+    return uniqueValues([...classRoles, ...attributeRoles]);
+}
+/**
+ * Find section wrapper blocks and their role markers in parsed pattern content.
+ *
+ * @param blocks Parsed block tree returned by `validateBlockPatternContentNesting`.
+ * @param convention Optional marker convention override.
+ * @returns Section wrapper matches with serialized block paths.
+ */
+export function extractPatternSectionRoleMatches(blocks, convention = {}) {
+    return collectSectionRoleMatches(blocks, normalizePatternCatalogSectionRoleConvention(convention));
+}
+/**
+ * Build the known valid section-role set from pattern catalog entries.
+ *
+ * @param patterns Catalog entries that may declare a `sectionRole`.
+ * @returns Valid section role slugs declared by the catalog.
+ */
+export function collectKnownPatternSectionRoles(patterns) {
+    return new Set(patterns
+        .map((pattern) => pattern.sectionRole)
+        .filter((sectionRole) => typeof sectionRole === "string" &&
+        PATTERN_SECTION_ROLE_PATTERN.test(sectionRole)));
+}
+/**
+ * Validate serialized pattern content against the catalog section-role rules.
+ *
+ * @param options Pattern content, marker convention, known roles, and diagnostic context.
+ * @returns Diagnostics for invalid, missing, mismatched, unknown, or duplicate section-role markers.
+ */
+export function validatePatternContentSectionRoles({ content, contentFile, convention, knownSectionRoles, label, pattern, }) {
+    const diagnostics = [];
+    const parsed = validateBlockPatternContentNesting(content, {
+        allowExternalBlockNames: true,
+        nesting: {},
+        patternFile: contentFile,
+    });
+    let matches = collectSectionRoleMatches(parsed.blocks, convention);
+    const unescapedContent = unescapeSerializedBlockCommentJsonQuotes(content);
+    if (unescapedContent !== content) {
+        const unescapedParsed = validateBlockPatternContentNesting(unescapedContent, {
+            allowExternalBlockNames: true,
+            nesting: {},
+            patternFile: contentFile,
+        });
+        const unescapedMatches = collectSectionRoleMatches(unescapedParsed.blocks, convention);
+        if (unescapedMatches.some((match) => match.roles.length > 0) ||
+            matches.length === 0) {
+            matches = unescapedMatches;
+        }
+    }
+    const locatedRoles = matches.flatMap((match) => match.roles.map((role) => ({
+        blockPath: match.blockPath,
+        role,
+    })));
+    const invalidRoles = locatedRoles.filter(({ role }) => !PATTERN_SECTION_ROLE_PATTERN.test(role));
+    for (const invalidRole of uniqueValues(invalidRoles.map(({ role }) => role))) {
+        const paths = invalidRoles
+            .filter(({ role }) => role === invalidRole)
+            .map(({ blockPath }) => blockPath);
+        diagnostics.push(createPatternCatalogDiagnostic({
+            code: "invalid-pattern-section-role-marker",
+            message: `${label}: section role marker "${invalidRole}" in ${contentFile} must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens (${formatBlockPaths(paths)}).`,
+            patternSlug: pattern.slug,
+            severity: "error",
+        }));
+    }
+    const validLocatedRoles = locatedRoles.filter(({ role }) => PATTERN_SECTION_ROLE_PATTERN.test(role));
+    const validRoles = validLocatedRoles.map(({ role }) => role);
+    const uniqueValidRoles = uniqueValues(validRoles);
+    const unknownRoles = uniqueValidRoles.filter((role) => !knownSectionRoles.has(role));
+    for (const unknownRole of unknownRoles) {
+        const paths = validLocatedRoles
+            .filter(({ role }) => role === unknownRole)
+            .map(({ blockPath }) => blockPath);
+        diagnostics.push(createPatternCatalogDiagnostic({
+            code: "unknown-pattern-section-role-marker",
+            message: `${label}: section role marker "${unknownRole}" in ${contentFile} is not declared by any PATTERNS sectionRole (${formatBlockPaths(paths)}).`,
+            patternSlug: pattern.slug,
+            severity: "warning",
+        }));
+    }
+    const scope = pattern.scope ?? "full";
+    const expectedSectionRole = typeof pattern.sectionRole === "string" &&
+        PATTERN_SECTION_ROLE_PATTERN.test(pattern.sectionRole)
+        ? pattern.sectionRole
+        : undefined;
+    if (scope === "section" && expectedSectionRole) {
+        if (validRoles.length === 0) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-section-role-marker",
+                message: `${label}: section-scoped pattern content in ${contentFile} must include section role marker "${expectedSectionRole}" using ${describeRoleMarkerConvention(convention)}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        else if (!validRoles.includes(expectedSectionRole)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "mismatched-pattern-section-role",
+                message: `${label}: manifest sectionRole "${expectedSectionRole}" was not found in ${contentFile}; found ${formatRoleList(uniqueValidRoles)}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+    }
+    if (scope === "full" && convention.requireUniqueFullPatternRoles) {
+        for (const role of uniqueValidRoles) {
+            const paths = validLocatedRoles
+                .filter((locatedRole) => locatedRole.role === role)
+                .map(({ blockPath }) => blockPath);
+            if (paths.length <= 1) {
+                continue;
+            }
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "duplicate-pattern-section-role-marker",
+                message: `${label}: full pattern content in ${contentFile} repeats section role marker "${role}" (${formatBlockPaths(paths)}).`,
+                patternSlug: pattern.slug,
+                severity: "warning",
+            }));
+        }
+    }
+    return diagnostics;
+}

package/dist/runtime/add/pattern-catalog.d.ts

@@ -0,0 +1,68 @@
+import type { PatternCatalogSectionRoleConvention } from "./pattern-catalog-section-roles.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, PATTERN_SECTION_ROLE_PATTERN, } from "./pattern-catalog-section-roles.js";
+export type { PatternCatalogSectionRoleConvention, PatternCatalogSectionRoleMatch, } from "./pattern-catalog-section-roles.js";
+export declare const PATTERN_CATALOG_SCOPE_IDS: readonly ["full", "section"];
+export type PatternCatalogScope = (typeof PATTERN_CATALOG_SCOPE_IDS)[number];
+export type PatternCatalogEntry = {
+    contentFile?: string;
+    file?: string;
+    scope?: string;
+    sectionRole?: string;
+    slug: string;
+    tags?: readonly string[];
+    thumbnailUrl?: string;
+    title?: string;
+};
+export type PatternCatalogDiagnosticSeverity = "error" | "warning";
+export type PatternCatalogDiagnosticCode = "duplicate-pattern-slug" | "invalid-pattern-content-file" | "invalid-pattern-scope" | "invalid-pattern-section-role" | "invalid-pattern-section-role-convention" | "invalid-pattern-section-role-marker" | "invalid-pattern-slug" | "invalid-pattern-tag" | "invalid-pattern-thumbnail-url" | "mismatched-pattern-section-role" | "missing-pattern-content-file" | "missing-pattern-section-role" | "missing-pattern-section-role-marker" | "duplicate-pattern-section-role-marker" | "unknown-pattern-section-role-marker";
+export type PatternCatalogDiagnostic = {
+    code: PatternCatalogDiagnosticCode;
+    message: string;
+    patternSlug?: string;
+    severity: PatternCatalogDiagnosticSeverity;
+};
+/**
+ * Options for validating typed pattern catalog entries and, when `projectDir`
+ * is provided, their serialized pattern content. Set `sectionRoleConvention` to
+ * `false` to keep file existence checks but opt out of section-role marker
+ * validation.
+ */
+export type PatternCatalogValidationOptions = {
+    projectDir?: string;
+    sectionRoleConvention?: PatternCatalogSectionRoleConvention | false;
+};
+export type PatternCatalogValidationResult = {
+    diagnostics: PatternCatalogDiagnostic[];
+    errors: PatternCatalogDiagnostic[];
+    warnings: PatternCatalogDiagnostic[];
+};
+export declare const PATTERN_TAG_PATTERN: RegExp;
+/**
+ * Validate pattern thumbnail references with the same URL/path rules used by
+ * catalog diagnostics and `wp-typia add pattern`.
+ *
+ * @param value Candidate thumbnail URL or relative project path.
+ * @returns Whether the value is an http(s) URL or safe relative project path.
+ */
+export declare function isValidPatternThumbnailUrl(value: string): boolean;
+export declare function resolvePatternCatalogContentFile(pattern: Pick<PatternCatalogEntry, "contentFile" | "file">): string | undefined;
+/**
+ * Validate typed pattern catalog metadata declared in `scripts/block-config.ts`.
+ *
+ * The validator checks catalog shape, duplicate slugs, optional section-role
+ * rules, safe content file paths, and missing files when a workspace root is
+ * provided. With a workspace root, it also parses serialized block markup and
+ * compares section role markers against the catalog manifest.
+ *
+ * @param patterns Pattern catalog entries to validate.
+ * @param options Optional project root and section role marker convention.
+ * @returns Structured diagnostics split into errors and warnings.
+ */
+export declare function validatePatternCatalog(patterns: readonly PatternCatalogEntry[], options?: PatternCatalogValidationOptions): PatternCatalogValidationResult;
+/**
+ * Render pattern catalog diagnostics for CLI, sync, and doctor output.
+ *
+ * @param diagnostics Diagnostics returned from {@link validatePatternCatalog}.
+ * @returns Human-readable lines with stable diagnostic codes.
+ */
+export declare function formatPatternCatalogDiagnostics(diagnostics: readonly PatternCatalogDiagnostic[]): string;