@nestia/editor 14.0.0 → 14.0.2

package/src/internal/NestiaEditorArchiver.ts

@@ -1,4 +1,6 @@
-import { strToU8, zipSync } from "fflate";
+import { Zip, ZipDeflate, strToU8 } from "fflate";
+
+import { NESTIA_EDITOR_DEFAULT_PACKAGE } from "./NestiaEditorDefaultPackage";
 
 /**
  * Archives a composed project into a zip file and hands it to the browser.
@@ -8,21 +10,74 @@ import { strToU8, zipSync } from "fflate";
  * WebContainer cannot execute. The editor therefore delivers the composed
  * project as a downloadable zip archive instead of an embedded StackBlitz
  * workspace.
+ *
+ * @evidence contracts/common.md#principled-implementation Packing is a synchronous zip of UTF-8 encoded entries through `fflate`, naming derives from the package name with a fixed character whitelist, and the download creates an object URL, clicks an anchor, and revokes the URL later.
+ * @evidence contracts/common.md#clear-and-simple-design Three operations, each one browser or zip concern, in one namespace with no shared state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The archive is built with the library's public functions and the download uses the standard anchor mechanism; nothing is patched.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose explains why the editor delivers a zip archive rather than an embedded workspace.
  */
 export namespace NestiaEditorArchiver {
-  /** Pack the composed project files into a zip archive. */
+  /**
+   * Pack the composed project files into a zip archive.
+   *
+   * @evidence contracts/common.md#principled-implementation Each own file key names a synchronous ZipDeflate stream added to Zip. Filenames are values rather than dictionary properties, preserving prototype-related names without changing an object's prototype. UTF-8 encoding preserves text; ending the archive emits its directory, including for an empty project.
+   * @evidence contracts/common.md#clear-and-simple-design One loop supplies files to the public synchronous compression streams; the callback collects chunks which are copied once into the returned archive.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It archives exactly the given files; no entry is added, filtered, or renamed.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the input and output.
+   */
   export const pack = (files: Record<string, string>): Uint8Array => {
-    const entries: Record<string, Uint8Array> = {};
-    for (const [key, value] of Object.entries(files))
-      entries[key] = strToU8(value);
-    return zipSync(entries);
+    const chunks: Uint8Array[] = [];
+    const archive = new Zip((error, chunk) => {
+      if (error) throw error;
+      chunks.push(chunk);
+    });
+    for (const [key, value] of Object.entries(files)) {
+      const entry = new ZipDeflate(key);
+      archive.add(entry);
+      entry.push(strToU8(value), true);
+    }
+    archive.end();
+    const output = new Uint8Array(
+      chunks.reduce((length, chunk) => length + chunk.length, 0),
+    );
+    let offset = 0;
+    for (const chunk of chunks) {
+      output.set(chunk, offset);
+      offset += chunk.length;
+    }
+    return output;
+  };
+
+  /**
+   * Compose a safe archive file name from a package name.
+   *
+   * A leading `@` is dropped and every run of characters outside letters,
+   * digits, `.`, `_`, and `-` becomes one `-`. A name with nothing left but
+   * dots, such as an empty package name, has no usable base for the archive, so
+   * the default package name is used instead. Other names retain their dots,
+   * including a leading dot.
+   *
+   * @evidence contracts/common.md#principled-implementation Dropping the `@` and replacing runs of characters outside the whitelist with one `-` yields a file name without path separators. Empty or dots-only bases use the default package name; otherwise dots are retained, so this is not a general rejection of hidden filenames or a validator of npm package names.
+   * @evidence contracts/common.md#clear-and-simple-design One private helper applies the character rule to the package name and to the default, so the rule exists once.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The rule applies to every input; the only special case is the empty-name guard, which follows from the safe-name requirement.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the character rule and the dots-only fallback.
+   */
+  export const name = (packageName: string): string => {
+    const base: string = compose(packageName);
+    return `${/^\.*$/.test(base) ? compose(NESTIA_EDITOR_DEFAULT_PACKAGE) : base}.zip`;
   };
 
-  /** Compose a safe archive file name from a package name. */
-  export const name = (packageName: string): string =>
-    `${packageName.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-")}.zip`;
+  const compose = (packageName: string): string =>
+    packageName.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-");
 
-  /** Trigger a browser download of the packed archive. */
+  /**
+   * Trigger a browser download of the packed archive.
+   *
+   * @evidence contracts/common.md#principled-implementation A Blob of the packed bytes is exposed through an object URL and an anchor with the `download` attribute is clicked, which is the browser's standard way to save generated content; the URL is revoked after 30 seconds so its memory is released.
+   * @evidence contracts/common.md#clear-and-simple-design One function, kept apart from `pack` so packing stays testable outside a browser.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses the standard DOM and URL APIs; the delayed revocation is not a retry or a compensation.
+   * @evidence contracts/common.md#meaningful-documentation The comment states that it triggers a browser download of the packed archive.
+   */
   export const download = (props: {
     name: string;
     files: Record<string, string>;

package/src/internal/NestiaEditorComposer.ts

@@ -11,26 +11,108 @@ 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.
+     *
+     * The CLI prints them; the editor reports them to its user, so a project
+     * lacking an operation never passes for a complete one.
+     */
+    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",
@@ -38,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",
@@ -59,6 +149,7 @@ export namespace NestiaEditorComposer {
             files: props.files,
             openFile: config.openFile,
             startScript: config.startScript,
+            skipped: [],
           },
         };
       const result: IValidation<NestiaMigrateApplication> =
@@ -83,6 +174,11 @@ export namespace NestiaEditorComposer {
           files,
           openFile: config.openFile,
           startScript: config.startScript,
+          skipped: app.getData().errors.map((error) => ({
+            method: error.method.toUpperCase(),
+            path: error.path,
+            messages: error.messages,
+          })),
         },
       } satisfies IValidation<IOutput>;
     };

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