@nestia/editor 14.0.1 → 14.0.3

package/src/internal/NestiaEditorComposer.ts

@@ -11,24 +11,72 @@ import * as prettierTsPlugin from "prettier/plugins/typescript";
 import { format } from "prettier/standalone";
 import { IValidation } from "typia";
 
+/**
+ * Composes the files of a project from an OpenAPI document.
+ *
+ * It validates and converts the document with `@nestia/migrate`, then formats
+ * the TypeScript files with Prettier's standalone build.
+ *
+ * @evidence contracts/common.md#principled-implementation The composer delegates conversion to `NestiaMigrateApplication`, which owns the OpenAPI semantics, and formats each `.ts` output with Prettier; a file that fails to format keeps its unformatted text.
+ * @evidence contracts/common.md#clear-and-simple-design One namespace with two public entry points that select the migration mode and retain the legacy workspace launch metadata; the shared flow is one private curried function.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts Conversion and formatting use the public APIs of `@nestia/migrate` and Prettier; a formatting failure is logged and the file is kept as generated.
+ * @evidence contracts/common.md#meaningful-documentation The comment states what the composer produces and which libraries do the work.
+ */
 export namespace NestiaEditorComposer {
+  /**
+   * Input of the composer: the OpenAPI document, the generator options, and the
+   * package name.
+   *
+   * The internal `files` member bypasses conversion and returns the given files
+   * unchanged.
+   *
+   * @evidence contracts/common.md#principled-implementation The fields are the migrate options the editor exposes plus the document, and `files` lets a caller supply an already composed project.
+   * @evidence contracts/common.md#clear-and-simple-design A flat property record; the document type is the union of the supported OpenAPI and Swagger versions.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts No field is defaulted here; the callers own the defaults.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the inputs and the internal member.
+   */
   export interface IProps {
+    /** OpenAPI or Swagger source to validate before conversion. */
     document:
       | SwaggerV2.IDocument
       | OpenApiV3.IDocument
       | OpenApiV3_1.IDocument
       | OpenApiV3_2.IDocument;
+
+    /** Include generated E2E functions. */
     e2e: boolean;
+
+    /** Group generated parameters into a keyword object. */
     keyword: boolean;
+
+    /** Include SDK mockup simulators. */
     simulate: boolean;
+
+    /** Package identity passed to the migration generator. */
     package?: string;
+
     /** @internal */
     files?: Record<string, string>;
   }
+  /**
+   * Output of the composer: the files, the files to open, the start script, and
+   * the skipped operations.
+   *
+   * @evidence contracts/common.md#principled-implementation The files carry the downloadable project and skipped exposes incomplete conversion. openFile and startScript are legacy workspace metadata with no reader in the current zip UI.
+   * @evidence contracts/common.md#clear-and-simple-design A flat property record without behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Every member is produced by the composer or the migrate application; none is a fixture value.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the members and the `skipped` member documents itself.
+   */
   export interface IOutput {
+    /** Relative project paths mapped to UTF-8 text. */
     files: Record<string, string>;
+
+    /** Legacy comma-separated workspace editor entry paths. */
     openFile: string;
+
+    /** Legacy workspace launch commands; zip downloads do not execute them. */
     startScript: string[];
+
     /**
      * Operations `@nestia/migrate` could not convert, left out of the files.
      *
@@ -37,12 +85,34 @@ export namespace NestiaEditorComposer {
      */
     skipped: ISkipped[];
   }
+  /**
+   * An operation that could not be converted: its upper-case HTTP method, its
+   * path, and the reasons.
+   *
+   * @evidence contracts/common.md#principled-implementation The migrate application reports errors by method, path, and messages, and the composer normalizes the method to upper case for display.
+   * @evidence contracts/common.md#clear-and-simple-design Three fields with no behavior.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The values are copied from the migrate errors.
+   * @evidence contracts/common.md#meaningful-documentation The comment states each field.
+   */
   export interface ISkipped {
+    /** Upper-case HTTP method identifying the omitted operation. */
     method: string;
+
+    /** OpenAPI path identifying the omitted operation. */
     path: string;
+
+    /** Conversion diagnostics supplied by the migrate application. */
     messages: string[];
   }
 
+  /**
+   * Composes a NestJS project from an OpenAPI document.
+   *
+   * @evidence contracts/common.md#principled-implementation It runs the shared flow with the migrate application's `nest` output, the `README.md,test/start.ts` files to open, and the `build:test,test` start script.
+   * @evidence contracts/common.md#clear-and-simple-design A one-expression binding of the shared flow.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The mode selects the public migrate operation. Returned launch metadata comes from the former embedded workspace flow; zip delivery does not read or execute it.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the project kind produced.
+   */
   export const nest = (props: IProps): Promise<IValidation<IOutput>> =>
     compose({
       openFile: "README.md,test/start.ts",
@@ -50,6 +120,14 @@ export namespace NestiaEditorComposer {
       migrate: (app) => app.nest(props),
     })(props);
 
+  /**
+   * Composes a software development kit project from an OpenAPI document.
+   *
+   * @evidence contracts/common.md#principled-implementation It runs the shared flow with the migrate application's `sdk` output, the `README.md,test/start.ts` files to open, and the `swagger` and `hello` start scripts.
+   * @evidence contracts/common.md#clear-and-simple-design A one-expression binding of the shared flow.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The mode selects the public migrate operation. Returned launch metadata comes from the former embedded workspace flow; zip delivery does not read or execute it.
+   * @evidence contracts/common.md#meaningful-documentation The comment names the project kind produced.
+   */
   export const sdk = async (props: IProps): Promise<IValidation<IOutput>> =>
     compose({
       openFile: "README.md,test/start.ts",

package/src/internal/NestiaEditorFileUploader.tsx

@@ -3,6 +3,18 @@ import { load } from "js-yaml";
 import React from "react";
 import FileUpload, { type ExtendedFileProps } from "react-mui-fileuploader";
 
+/**
+ * A file picker that reads an OpenAPI document from a JSON or YAML file.
+ *
+ * The last chosen file is read and parsed by its extension, and the result is passed to `onChange` with the parsed document, or with an error message when the content does not parse. Clearing the selection reports `null` for both.
+ *
+ * A file-reading failure rejects the uploader callback before parsing; it is not reported through `onChange`. Parsing reports content without validating its OpenAPI shape; the composer performs that validation.
+ *
+ * @evidence contracts/common.md#principled-implementation The file is decoded as UTF-8 text and parsed with `JSON.parse` for a `json` extension and with `js-yaml` otherwise; a parse failure is reported with the message for the format, and only the last chosen file is kept, matching the single-file picker.
+ * @evidence contracts/common.md#clear-and-simple-design One component wraps the third-party uploader and owns only reading and parsing; the form around it belongs to `NestiaEditorUploader`.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The parser is chosen by the file extension alone; no document name or content is special-cased.
+ * @evidence contracts/common.md#meaningful-documentation The comment states which file is read, how it is parsed, and what `onChange` receives in each case.
+ */
 export function NestiaEditorFileUploader(
   props: NestiaEditorFileUploader.IProps,
 ) {
@@ -51,8 +63,17 @@ export function NestiaEditorFileUploader(
     />
   );
 }
+/**
+ * Properties of {@link NestiaEditorFileUploader}.
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace holds the property type of the component with the same name.
+ * @evidence contracts/common.md#clear-and-simple-design It contains one interface with one callback.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It adds no behavior.
+ * @evidence contracts/common.md#meaningful-documentation The comment names the component the properties belong to.
+ */
 export namespace NestiaEditorFileUploader {
   export interface IProps {
+    /** Receives parsed file content, parse failures, or null/null when cleared. */
     onChange: (
       swagger:
         | SwaggerV2.IDocument