@wp-typia/project-tools 0.24.4 → 0.24.5

package/dist/runtime/workspace/workspace-inventory-parser-entries.js

@@ -0,0 +1,157 @@
+import ts from "typescript";
+import { getPropertyNameText } from "../shared/ts-property-names.js";
+import { assertParsedInventoryEntry, } from "./workspace-inventory-parser-validation.js";
+function findExportedArrayLiteral(sourceFile, exportName) {
+    for (const statement of sourceFile.statements) {
+        if (!ts.isVariableStatement(statement)) {
+            continue;
+        }
+        if (!statement.modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)) {
+            continue;
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (!ts.isIdentifier(declaration.name) ||
+                declaration.name.text !== exportName) {
+                continue;
+            }
+            if (declaration.initializer &&
+                ts.isArrayLiteralExpression(declaration.initializer)) {
+                return {
+                    array: declaration.initializer,
+                    found: true,
+                };
+            }
+            return {
+                array: null,
+                found: true,
+            };
+        }
+    }
+    return {
+        array: null,
+        found: false,
+    };
+}
+function getOptionalStringProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (ts.isStringLiteralLike(property.initializer)) {
+            return property.initializer.text;
+        }
+        throw new Error(`${entryName}[${elementIndex}] must use a string literal for "${key}" in scripts/block-config.ts.`);
+    }
+    return undefined;
+}
+function getOptionalStringArrayProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (!ts.isArrayLiteralExpression(property.initializer)) {
+            throw new Error(`${entryName}[${elementIndex}] must use an array literal for "${key}" in scripts/block-config.ts.`);
+        }
+        return property.initializer.elements.map((element, itemIndex) => {
+            if (!ts.isStringLiteralLike(element)) {
+                throw new Error(`${entryName}[${elementIndex}].${key}[${itemIndex}] must use a string literal in scripts/block-config.ts.`);
+            }
+            return element.text;
+        });
+    }
+    return undefined;
+}
+function getOptionalBooleanProperty(entryName, elementIndex, objectLiteral, key) {
+    for (const property of objectLiteral.properties) {
+        if (!ts.isPropertyAssignment(property)) {
+            continue;
+        }
+        const propertyName = getPropertyNameText(property.name);
+        if (propertyName !== key) {
+            continue;
+        }
+        if (property.initializer.kind === ts.SyntaxKind.TrueKeyword) {
+            return true;
+        }
+        if (property.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+            return false;
+        }
+        throw new Error(`${entryName}[${elementIndex}] must use a boolean literal for "${key}" in scripts/block-config.ts.`);
+    }
+    return undefined;
+}
+function parseInventoryEntries(arrayLiteral, descriptor) {
+    return arrayLiteral.elements.map((element, elementIndex) => {
+        if (!ts.isObjectLiteralExpression(element)) {
+            throw new Error(`${descriptor.entryName}[${elementIndex}] must be an object literal in scripts/block-config.ts.`);
+        }
+        const entry = {};
+        for (const field of descriptor.fields) {
+            const kind = field.kind ?? "string";
+            const value = kind === "stringArray"
+                ? getOptionalStringArrayProperty(descriptor.entryName, elementIndex, element, field.key)
+                : kind === "boolean"
+                    ? getOptionalBooleanProperty(descriptor.entryName, elementIndex, element, field.key)
+                    : getOptionalStringProperty(descriptor.entryName, elementIndex, element, field.key);
+            field.validate?.(value, {
+                elementIndex,
+                entryName: descriptor.entryName,
+                key: field.key,
+            });
+            entry[field.key] = value;
+        }
+        assertParsedInventoryEntry(entry, descriptor, elementIndex);
+        return entry;
+    });
+}
+/**
+ * Parse one descriptor-backed inventory section from a TypeScript source file.
+ *
+ * The generic `T` is the typed entry shape returned in `entries`. The
+ * `descriptor` supplies the exported array name, parser field metadata, and
+ * whether the section is required; this helper uses `findExportedArrayLiteral`
+ * and `parseInventoryEntries` to guarantee object-literal entries and literal
+ * field values. It returns parsed entries plus a `found` flag, and throws when
+ * required exports are missing, descriptors cannot resolve an export name, or
+ * exported values are not array literals.
+ */
+export function parseInventorySection(sourceFile, descriptor) {
+    if (!descriptor.parse) {
+        return {
+            entries: [],
+            found: false,
+        };
+    }
+    const exportName = descriptor.parse.exportName ?? descriptor.value?.name;
+    if (!exportName) {
+        throw new Error("Inventory parser descriptor is missing an export name.");
+    }
+    const exportedArray = findExportedArrayLiteral(sourceFile, exportName);
+    if (!exportedArray.found) {
+        if (descriptor.parse.required) {
+            throw new Error(`scripts/block-config.ts must export a ${exportName} array.`);
+        }
+        return {
+            entries: [],
+            found: false,
+        };
+    }
+    if (!exportedArray.array) {
+        if (descriptor.parse.required) {
+            throw new Error(`scripts/block-config.ts must export a ${exportName} array.`);
+        }
+        throw new Error(`scripts/block-config.ts must export ${exportName} as an array literal.`);
+    }
+    return {
+        entries: parseInventoryEntries(exportedArray.array, descriptor.parse.entry),
+        found: true,
+    };
+}

package/dist/runtime/workspace/workspace-inventory-parser-validation.d.ts

@@ -0,0 +1,104 @@
+import type { WorkspaceInventoryAppendOptionKey, WorkspaceInventoryEntriesKey, WorkspaceInventorySectionFlagKey } from "./workspace-inventory-types.js";
+/**
+ * Literal value shape accepted by descriptor-driven inventory entry fields.
+ */
+export type InventoryEntryFieldValue = string | string[] | boolean | undefined;
+/**
+ * Context passed to custom field validators while parsing one inventory entry.
+ */
+export type InventoryEntryFieldValidationContext = {
+    elementIndex: number;
+    entryName: string;
+    key: string;
+};
+type InventoryEntryFieldDescriptor = {
+    key: string;
+    kind?: "boolean" | "string" | "stringArray";
+    required?: boolean;
+    validate?: (value: InventoryEntryFieldValue, context: InventoryEntryFieldValidationContext) => void;
+};
+/**
+ * Runtime parser contract for one exported inventory array.
+ *
+ * `entryName` is used in diagnostics and `fields` defines the literal values,
+ * required flags, and custom validators accepted for each object entry.
+ */
+export type InventoryEntryParserDescriptor = {
+    entryName: string;
+    fields: readonly InventoryEntryFieldDescriptor[];
+};
+type RequiredInventoryEntryKey<T extends object> = Extract<{
+    [Key in keyof T]-?: undefined extends T[Key] ? never : Key;
+}[keyof T], string>;
+type TypedInventoryEntryFieldDescriptor<T extends object, TKey extends Extract<keyof T, string> = Extract<keyof T, string>> = TKey extends Extract<keyof T, string> ? Omit<InventoryEntryFieldDescriptor, "key" | "required"> & {
+    key: TKey;
+} & (TKey extends RequiredInventoryEntryKey<T> ? {
+    required: true;
+} : {
+    required?: boolean;
+}) : never;
+type RequiredInventoryEntryFieldDescriptor<T extends object> = Omit<InventoryEntryFieldDescriptor, "key" | "required"> & {
+    key: RequiredInventoryEntryKey<T>;
+    required: true;
+};
+type MissingRequiredInventoryEntryKeys<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = Exclude<RequiredInventoryEntryKey<T>, TFields[number]["key"]>;
+type RequiredInventoryEntryFieldsPresent<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = MissingRequiredInventoryEntryKeys<T, TFields> extends never ? unknown : {
+    missingRequiredInventoryEntryFields: MissingRequiredInventoryEntryKeys<T, TFields>;
+};
+type RequiredInventoryEntryFieldsMarkedRequired<T extends object, TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]> = Extract<TFields[number], {
+    key: RequiredInventoryEntryKey<T>;
+}> extends RequiredInventoryEntryFieldDescriptor<T> ? unknown : {
+    requiredInventoryEntryFieldsMustSetRequiredTrue: RequiredInventoryEntryKey<T>;
+};
+/**
+ * Shared descriptor contract for generated workspace inventory sections.
+ *
+ * Callers rely on `append` markers when inserting generated entries, `parse`
+ * metadata when reading exported arrays, and `interface`/`value` sections when
+ * repairing older `scripts/block-config.ts` files.
+ */
+export type InventorySectionDescriptor = {
+    /** Optional marker metadata used when appending generated entries. */
+    append?: {
+        marker: string;
+        optionKey: WorkspaceInventoryAppendOptionKey;
+    };
+    /** Optional exported interface that backs the inventory section entries. */
+    interface?: {
+        name: string;
+        section: string;
+    };
+    /** Optional parser metadata for descriptor-driven inventory reads. */
+    parse?: {
+        entriesKey: WorkspaceInventoryEntriesKey;
+        entry: InventoryEntryParserDescriptor;
+        exportName?: string;
+        hasSectionKey?: WorkspaceInventorySectionFlagKey;
+        required?: boolean;
+    };
+    /** Optional exported const array that stores the inventory section entries. */
+    value?: {
+        name: string;
+        section: string;
+    };
+};
+/**
+ * Define a typed inventory entry parser while enforcing required fields at
+ * compile time.
+ *
+ * The returned descriptor is consumed by `parseInventorySection` to extract
+ * literal field values and run runtime validators.
+ */
+export declare function defineInventoryEntryParser<T extends object>(): <const TFields extends readonly TypedInventoryEntryFieldDescriptor<T>[]>(descriptor: {
+    entryName: string;
+    fields: TFields;
+} & RequiredInventoryEntryFieldsPresent<T, TFields> & RequiredInventoryEntryFieldsMarkedRequired<T, TFields>) => InventoryEntryParserDescriptor;
+/**
+ * Assert that a parsed inventory entry contains every required descriptor
+ * field.
+ *
+ * Missing `undefined` values and empty strings throw with diagnostics tied to
+ * the original exported inventory array name and element index.
+ */
+export declare function assertParsedInventoryEntry<T extends object>(entry: Record<string, InventoryEntryFieldValue>, descriptor: InventoryEntryParserDescriptor, elementIndex: number): asserts entry is Record<string, InventoryEntryFieldValue> & T;
+export {};

package/dist/runtime/workspace/workspace-inventory-parser-validation.js

@@ -0,0 +1,34 @@
+/**
+ * Define a typed inventory entry parser while enforcing required fields at
+ * compile time.
+ *
+ * The returned descriptor is consumed by `parseInventorySection` to extract
+ * literal field values and run runtime validators.
+ */
+export function defineInventoryEntryParser() {
+    return (descriptor) => descriptor;
+}
+function isMissingRequiredInventoryValue(value) {
+    return (value === undefined || (typeof value === "string" && value.length === 0));
+}
+function formatMissingRequiredInventoryFields(keys) {
+    return keys.length === 1
+        ? `required "${keys[0]}"`
+        : `required fields ${keys.map((key) => `"${key}"`).join(", ")}`;
+}
+/**
+ * Assert that a parsed inventory entry contains every required descriptor
+ * field.
+ *
+ * Missing `undefined` values and empty strings throw with diagnostics tied to
+ * the original exported inventory array name and element index.
+ */
+export function assertParsedInventoryEntry(entry, descriptor, elementIndex) {
+    const missingRequiredKeys = descriptor.fields
+        .filter((field) => field.required === true &&
+        isMissingRequiredInventoryValue(entry[field.key]))
+        .map((field) => field.key);
+    if (missingRequiredKeys.length > 0) {
+        throw new Error(`${descriptor.entryName}[${elementIndex}] is missing ${formatMissingRequiredInventoryFields(missingRequiredKeys)} in scripts/block-config.ts.`);
+    }
+}

package/dist/runtime/workspace/workspace-inventory-parser.d.ts

@@ -0,0 +1,11 @@
+import type { WorkspaceInventory } from "./workspace-inventory-types.js";
+export { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
+export type { InventorySectionDescriptor } from "./workspace-inventory-parser-validation.js";
+/**
+ * Parse workspace inventory entries from the source of `scripts/block-config.ts`.
+ *
+ * @param source Raw TypeScript source from `scripts/block-config.ts`.
+ * @returns Parsed inventory sections without the resolved `blockConfigPath`.
+ * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
+ */
+export declare function parseWorkspaceInventorySource(source: string): Omit<WorkspaceInventory, "blockConfigPath">;

package/dist/runtime/workspace/workspace-inventory-parser.js

@@ -0,0 +1,54 @@
+import ts from "typescript";
+import { parseInventorySection } from "./workspace-inventory-parser-entries.js";
+import { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
+export { BLOCK_INVENTORY_SECTION, INVENTORY_SECTIONS, } from "./workspace-inventory-section-descriptors.js";
+/**
+ * Parse workspace inventory entries from the source of `scripts/block-config.ts`.
+ *
+ * @param source Raw TypeScript source from `scripts/block-config.ts`.
+ * @returns Parsed inventory sections without the resolved `blockConfigPath`.
+ * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
+ */
+export function parseWorkspaceInventorySource(source) {
+    const sourceFile = ts.createSourceFile("block-config.ts", source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const parsedInventory = {
+        abilities: [],
+        adminViews: [],
+        aiFeatures: [],
+        bindingSources: [],
+        blockStyles: [],
+        blockTransforms: [],
+        blocks: parseInventorySection(sourceFile, BLOCK_INVENTORY_SECTION).entries,
+        contracts: [],
+        editorPlugins: [],
+        hasAbilitiesSection: false,
+        hasAdminViewsSection: false,
+        hasAiFeaturesSection: false,
+        hasBindingSourcesSection: false,
+        hasBlockStylesSection: false,
+        hasBlockTransformsSection: false,
+        hasContractsSection: false,
+        hasEditorPluginsSection: false,
+        hasPatternsSection: false,
+        hasPostMetaSection: false,
+        hasRestResourcesSection: false,
+        hasVariationsSection: false,
+        patterns: [],
+        postMeta: [],
+        restResources: [],
+        source,
+        variations: [],
+    };
+    const mutableInventory = parsedInventory;
+    for (const section of INVENTORY_SECTIONS) {
+        if (!section.parse) {
+            continue;
+        }
+        const parsedSection = parseInventorySection(sourceFile, section);
+        mutableInventory[section.parse.entriesKey] = parsedSection.entries;
+        if (section.parse.hasSectionKey) {
+            mutableInventory[section.parse.hasSectionKey] = parsedSection.found;
+        }
+    }
+    return parsedInventory;
+}

package/dist/runtime/workspace/workspace-inventory-read.d.ts

@@ -0,0 +1,51 @@
+import type { WorkspaceBlockSelectOption, WorkspaceInventory } from "./workspace-inventory-types.js";
+/**
+ * Synchronously read and parse the canonical workspace inventory file.
+ *
+ * This compatibility helper is intentionally sync-only for callers that expose
+ * synchronous APIs. Prefer `readWorkspaceInventoryAsync()` from async command
+ * paths so workspace reads do not block the event loop.
+ *
+ * @deprecated Since 0.22.10. Use `readWorkspaceInventoryAsync()` from async
+ * command paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export declare function readWorkspaceInventory(projectDir: string): WorkspaceInventory;
+/**
+ * Asynchronously read and parse the canonical workspace inventory file.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export declare function readWorkspaceInventoryAsync(projectDir: string): Promise<WorkspaceInventory>;
+/**
+ * Synchronously return select options for the current workspace block inventory.
+ *
+ * The `description` field mirrors `block.typesFile`, while `name` and `value`
+ * both map to the block slug for use in interactive add flows.
+ *
+ * @deprecated Since 0.22.10. Use `getWorkspaceBlockSelectOptionsAsync()` from
+ * async command paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Block options for variation-target selection.
+ */
+export declare function getWorkspaceBlockSelectOptions(projectDir: string): WorkspaceBlockSelectOption[];
+/**
+ * Asynchronously return select options for the current workspace block inventory.
+ *
+ * The returned option shape matches `getWorkspaceBlockSelectOptions()` while
+ * avoiding synchronous inventory reads in interactive or async command paths.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Block options for variation-target selection.
+ */
+export declare function getWorkspaceBlockSelectOptionsAsync(projectDir: string): Promise<WorkspaceBlockSelectOption[]>;

package/dist/runtime/workspace/workspace-inventory-read.js

@@ -0,0 +1,98 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { isFileNotFoundError } from "../shared/fs-async.js";
+import { parseWorkspaceInventorySource } from "./workspace-inventory-parser.js";
+/**
+ * Synchronously read and parse the canonical workspace inventory file.
+ *
+ * This compatibility helper is intentionally sync-only for callers that expose
+ * synchronous APIs. Prefer `readWorkspaceInventoryAsync()` from async command
+ * paths so workspace reads do not block the event loop.
+ *
+ * @deprecated Since 0.22.10. Use `readWorkspaceInventoryAsync()` from async
+ * command paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export function readWorkspaceInventory(projectDir) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    let source;
+    try {
+        source = readFileSync(blockConfigPath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            throw new Error(`Workspace inventory file is missing at ${blockConfigPath}. Expected scripts/block-config.ts to exist.`);
+        }
+        throw error;
+    }
+    return {
+        blockConfigPath,
+        ...parseWorkspaceInventorySource(source),
+    };
+}
+/**
+ * Asynchronously read and parse the canonical workspace inventory file.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Parsed `WorkspaceInventory` including the resolved `blockConfigPath`.
+ * @throws {Error} When `scripts/block-config.ts` is missing or invalid.
+ */
+export async function readWorkspaceInventoryAsync(projectDir) {
+    const blockConfigPath = path.join(projectDir, "scripts", "block-config.ts");
+    let source;
+    try {
+        source = await readFile(blockConfigPath, "utf8");
+    }
+    catch (error) {
+        if (isFileNotFoundError(error)) {
+            throw new Error(`Workspace inventory file is missing at ${blockConfigPath}. Expected scripts/block-config.ts to exist.`);
+        }
+        throw error;
+    }
+    return {
+        blockConfigPath,
+        ...parseWorkspaceInventorySource(source),
+    };
+}
+function toWorkspaceBlockSelectOptions(blocks) {
+    return blocks.map((block) => ({
+        description: block.typesFile,
+        name: block.slug,
+        value: block.slug,
+    }));
+}
+/**
+ * Synchronously return select options for the current workspace block inventory.
+ *
+ * The `description` field mirrors `block.typesFile`, while `name` and `value`
+ * both map to the block slug for use in interactive add flows.
+ *
+ * @deprecated Since 0.22.10. Use `getWorkspaceBlockSelectOptionsAsync()` from
+ * async command paths. Removal target: not currently scheduled; this sync
+ * compatibility helper remains available until release notes announce a
+ * versioned target.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Block options for variation-target selection.
+ */
+export function getWorkspaceBlockSelectOptions(projectDir) {
+    return toWorkspaceBlockSelectOptions(readWorkspaceInventory(projectDir).blocks);
+}
+/**
+ * Asynchronously return select options for the current workspace block inventory.
+ *
+ * The returned option shape matches `getWorkspaceBlockSelectOptions()` while
+ * avoiding synchronous inventory reads in interactive or async command paths.
+ *
+ * @param projectDir Workspace root directory.
+ * @returns Block options for variation-target selection.
+ */
+export async function getWorkspaceBlockSelectOptionsAsync(projectDir) {
+    return toWorkspaceBlockSelectOptions((await readWorkspaceInventoryAsync(projectDir)).blocks);
+}

package/dist/runtime/workspace/workspace-inventory-section-descriptors.d.ts

@@ -0,0 +1,19 @@
+import { type InventorySectionDescriptor } from "./workspace-inventory-parser-validation.js";
+/**
+ * Descriptor for the required `BLOCKS` inventory section.
+ *
+ * Runtime readers use its `parse` contract to require the exported `BLOCKS`
+ * array and validate required block entry fields; mutation helpers use its
+ * `append` marker to insert generated block entries without duplicating section
+ * knowledge.
+ */
+export declare const BLOCK_INVENTORY_SECTION: InventorySectionDescriptor;
+/**
+ * Descriptors for optional workspace inventory sections beyond `BLOCKS`.
+ *
+ * Each descriptor centralizes append markers, exported interface/value repair
+ * sections, parser entry metadata such as `entriesKey` and `entryName`, and
+ * optional section flags so add, doctor, read, and mutation flows share one
+ * runtime contract when adding new inventory domains.
+ */
+export declare const INVENTORY_SECTIONS: readonly InventorySectionDescriptor[];