@wp-typia/project-tools 0.23.1 → 0.24.1

package/dist/runtime/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/pattern-catalog.d.ts

@@ -0,0 +1,67 @@
+import type { PatternCatalogSectionRoleConvention } from "./pattern-catalog-section-roles.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, } 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[];
+};
+/**
+ * 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;

package/dist/runtime/pattern-catalog.js

@@ -0,0 +1,225 @@
+import fs from "node:fs";
+import path from "node:path";
+import { PATTERN_SECTION_ROLE_PATTERN, collectKnownPatternSectionRoles, normalizePatternCatalogSectionRoleConvention, validatePatternContentSectionRoles, } from "./pattern-catalog-section-roles.js";
+export { extractPatternSectionRoleMatches, extractPatternSectionRolesFromAttributes, } from "./pattern-catalog-section-roles.js";
+export const PATTERN_CATALOG_SCOPE_IDS = ["full", "section"];
+const PATTERN_SLUG_PATTERN = /^[a-z][a-z0-9-]*$/u;
+const PATTERN_TAG_PATTERN = /^[a-z0-9][a-z0-9-]*$/u;
+const PATTERN_CONTENT_FILE_ROOT = "src/patterns/";
+function createPatternCatalogDiagnostic(diagnostic) {
+    return diagnostic;
+}
+function isPatternCatalogScope(value) {
+    return PATTERN_CATALOG_SCOPE_IDS.includes(value);
+}
+function isSafeRelativePath(value) {
+    return (value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.includes("\\") &&
+        !value.split(/[\\/]+/u).includes("..") &&
+        !/[<>:"|?*\u0000-\u001F]/u.test(value));
+}
+function isPatternContentFilePath(value) {
+    if (!isSafeRelativePath(value) ||
+        !value.startsWith(PATTERN_CONTENT_FILE_ROOT) ||
+        !value.endsWith(".php")) {
+        return false;
+    }
+    const patternRelativePath = value.slice(PATTERN_CONTENT_FILE_ROOT.length);
+    const segments = patternRelativePath.split("/");
+    return ((segments.length === 1 || segments.length === 2) &&
+        segments.every((segment) => segment.length > 0));
+}
+/**
+ * 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 function isValidPatternThumbnailUrl(value) {
+    if (value.length === 0) {
+        return false;
+    }
+    try {
+        const url = new URL(value);
+        return url.protocol === "http:" || url.protocol === "https:";
+    }
+    catch {
+        return isSafeRelativePath(value);
+    }
+}
+export function resolvePatternCatalogContentFile(pattern) {
+    return pattern.contentFile ?? pattern.file;
+}
+/**
+ * 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 function validatePatternCatalog(patterns, options = {}) {
+    const diagnostics = [];
+    const seenSlugs = new Map();
+    let sectionRoleConvention = null;
+    if (options.sectionRoleConvention !== false) {
+        try {
+            sectionRoleConvention = normalizePatternCatalogSectionRoleConvention(options.sectionRoleConvention);
+        }
+        catch (error) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-section-role-convention",
+                message: `sectionRoleConvention.roleClassNamePattern is invalid: ${error instanceof Error ? error.message : String(error)}`,
+                severity: "error",
+            }));
+        }
+    }
+    const knownSectionRoles = collectKnownPatternSectionRoles(patterns);
+    for (const [index, pattern] of patterns.entries()) {
+        const label = pattern.slug || `PATTERNS[${index}]`;
+        if (!PATTERN_SLUG_PATTERN.test(pattern.slug)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-slug",
+                message: `${label}: slug must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        const previousIndex = seenSlugs.get(pattern.slug);
+        if (previousIndex !== undefined) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "duplicate-pattern-slug",
+                message: `${label}: duplicate slug already declared at PATTERNS[${previousIndex}].`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        else {
+            seenSlugs.set(pattern.slug, index);
+        }
+        const scope = pattern.scope ?? "full";
+        if (!isPatternCatalogScope(scope)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-scope",
+                message: `${label}: scope must be one of ${PATTERN_CATALOG_SCOPE_IDS.join(", ")}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        if (scope === "section" && !pattern.sectionRole) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-section-role",
+                message: `${label}: section-scoped patterns must declare sectionRole.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        if (pattern.sectionRole !== undefined &&
+            !PATTERN_SECTION_ROLE_PATTERN.test(pattern.sectionRole)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-section-role",
+                message: `${label}: sectionRole must start with a lowercase letter and contain only lowercase letters, numbers, and hyphens.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        for (const [tagIndex, tag] of (pattern.tags ?? []).entries()) {
+            if (!PATTERN_TAG_PATTERN.test(tag)) {
+                diagnostics.push(createPatternCatalogDiagnostic({
+                    code: "invalid-pattern-tag",
+                    message: `${label}: tags[${tagIndex}] must contain only lowercase letters, numbers, and hyphens.`,
+                    patternSlug: pattern.slug,
+                    severity: "error",
+                }));
+            }
+        }
+        if (pattern.thumbnailUrl !== undefined &&
+            !isValidPatternThumbnailUrl(pattern.thumbnailUrl)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-thumbnail-url",
+                message: `${label}: thumbnailUrl must be an http(s) URL or safe relative project path.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+        }
+        const contentFile = resolvePatternCatalogContentFile(pattern);
+        if (!contentFile) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-content-file",
+                message: `${label}: contentFile or legacy file must point at the pattern PHP file.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (!isPatternContentFilePath(contentFile)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "invalid-pattern-content-file",
+                message: `${label}: contentFile must be a safe relative project path directly under src/patterns/ or one nested directory under src/patterns/ and end in .php.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (!options.projectDir) {
+            continue;
+        }
+        const absoluteContentFile = path.join(options.projectDir, contentFile);
+        if (!fs.existsSync(absoluteContentFile)) {
+            diagnostics.push(createPatternCatalogDiagnostic({
+                code: "missing-pattern-content-file",
+                message: `${label}: missing pattern content file ${contentFile}.`,
+                patternSlug: pattern.slug,
+                severity: "error",
+            }));
+            continue;
+        }
+        if (sectionRoleConvention) {
+            let content;
+            try {
+                content = fs.readFileSync(absoluteContentFile, "utf8");
+            }
+            catch (error) {
+                diagnostics.push(createPatternCatalogDiagnostic({
+                    code: "invalid-pattern-content-file",
+                    message: `${label}: failed to read pattern content file ${contentFile}: ${error instanceof Error ? error.message : String(error)}.`,
+                    patternSlug: pattern.slug,
+                    severity: "error",
+                }));
+                continue;
+            }
+            diagnostics.push(...validatePatternContentSectionRoles({
+                content,
+                contentFile,
+                convention: sectionRoleConvention,
+                knownSectionRoles,
+                label,
+                pattern,
+            }));
+        }
+    }
+    const warnings = diagnostics.filter((diagnostic) => diagnostic.severity === "warning");
+    const errors = diagnostics.filter((diagnostic) => diagnostic.severity === "error");
+    return {
+        diagnostics,
+        errors,
+        warnings,
+    };
+}
+/**
+ * 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 function formatPatternCatalogDiagnostics(diagnostics) {
+    return diagnostics
+        .map((diagnostic) => `- [${diagnostic.code}] ${diagnostic.message}`)
+        .join("\n");
+}

package/dist/runtime/post-meta-binding-fields.d.ts

@@ -0,0 +1,46 @@
+import type { WorkspacePostMetaInventoryEntry } from "./workspace-inventory-types.js";
+/**
+ * Field metadata extracted from a typed post-meta schema for a generated block
+ * bindings source.
+ *
+ * @property fallbackValue Editor preview value used when live post meta is unavailable.
+ * @property label Human-readable label derived from the schema property name.
+ * @property name Top-level schema property name used as the binding `field` arg.
+ * @property required Whether the field is listed in the schema's required array.
+ * @property schemaType Resolved JSON Schema type used to choose a preview value.
+ */
+export interface PostMetaBindingField {
+    fallbackValue: string;
+    label: string;
+    name: string;
+    required: boolean;
+    schemaType: string;
+}
+/**
+ * Load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Promise resolving to the extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export declare function loadPostMetaBindingFields(projectDir: string, postMeta: WorkspacePostMetaInventoryEntry): Promise<PostMetaBindingField[]>;
+/**
+ * Synchronously load and extract binding fields from a post-meta JSON Schema artifact.
+ *
+ * @param projectDir Workspace root directory.
+ * @param postMeta Post-meta inventory entry that points to the schema file.
+ * @returns Extracted top-level binding fields.
+ * @throws If the schema cannot be read or does not expose object properties.
+ */
+export declare function loadPostMetaBindingFieldsSync(projectDir: string, postMeta: WorkspacePostMetaInventoryEntry): PostMetaBindingField[];
+/**
+ * Validate and resolve a top-level post-meta binding path.
+ *
+ * @param fields Binding fields extracted from the post-meta schema.
+ * @param postMetaSlug Post-meta contract slug used in diagnostics.
+ * @param metaPath User-provided field path to validate.
+ * @returns The matching binding field.
+ * @throws If the path is empty, nested, or missing from the schema fields.
+ */
+export declare function assertPostMetaBindingPath(fields: readonly PostMetaBindingField[], postMetaSlug: string, metaPath: string): PostMetaBindingField;