@wp-typia/project-tools 0.23.0 → 0.24.0

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

@@ -0,0 +1,157 @@
+import ts from "typescript";
+import { getPropertyNameText } from "./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-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-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-inventory-parser.d.ts

@@ -1,47 +1,6 @@
-import type { WorkspaceInventory, WorkspaceInventoryAppendOptionKey, WorkspaceInventoryEntriesKey, WorkspaceInventorySectionFlagKey } from "./workspace-inventory-types.js";
-type InventoryEntryFieldValue = string | string[] | boolean | undefined;
-type InventoryEntryFieldValidationContext = {
-    elementIndex: number;
-    entryName: string;
-    key: string;
-};
-type InventoryEntryFieldDescriptor = {
-    key: string;
-    kind?: "boolean" | "string" | "stringArray";
-    required?: boolean;
-    validate?: (value: InventoryEntryFieldValue, context: InventoryEntryFieldValidationContext) => void;
-};
-type InventoryEntryParserDescriptor = {
-    entryName: string;
-    fields: readonly InventoryEntryFieldDescriptor[];
-};
-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;
-    };
-};
-export declare const BLOCK_INVENTORY_SECTION: InventorySectionDescriptor;
-export declare const INVENTORY_SECTIONS: readonly InventorySectionDescriptor[];
+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`.
  *
@@ -50,4 +9,3 @@ export declare const INVENTORY_SECTIONS: readonly InventorySectionDescriptor[];
  * @throws {Error} When `BLOCKS` is missing or any inventory entry is malformed.
  */
 export declare function parseWorkspaceInventorySource(source: string): Omit<WorkspaceInventory, "blockConfigPath">;
-export {};