oxfmt 0.41.0 → 0.42.0

package/configuration_schema.json

@@ -63,6 +63,15 @@
       "type": "boolean",
       "markdownDescription": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`"
     },
+    "jsdoc": {
+      "description": "Enable JSDoc comment formatting.\n\nWhen enabled, JSDoc comments are normalized and reformatted:\ntag aliases are canonicalized, descriptions are capitalized,\nlong lines are wrapped, and short comments are collapsed to single-line.\n\nPass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.\n\n- Default: Disabled",
+      "allOf": [
+        {
+          "$ref": "#/definitions/JsdocConfig"
+        }
+      ],
+      "markdownDescription": "Enable JSDoc comment formatting.\n\nWhen enabled, JSDoc comments are normalized and reformatted:\ntag aliases are canonicalized, descriptions are capitalized,\nlong lines are wrapped, and short comments are collapsed to single-line.\n\nPass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.\n\n- Default: Disabled"
+    },
     "jsxSingleQuote": {
       "description": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`",
       "type": "boolean",
@@ -291,6 +300,15 @@
           "type": "boolean",
           "markdownDescription": "Whether to insert a final newline at the end of the file.\n\n- Default: `true`\n- Overrides `.editorconfig.insert_final_newline`"
         },
+        "jsdoc": {
+          "description": "Enable JSDoc comment formatting.\n\nWhen enabled, JSDoc comments are normalized and reformatted:\ntag aliases are canonicalized, descriptions are capitalized,\nlong lines are wrapped, and short comments are collapsed to single-line.\n\nPass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.\n\n- Default: Disabled",
+          "allOf": [
+            {
+              "$ref": "#/definitions/JsdocConfig"
+            }
+          ],
+          "markdownDescription": "Enable JSDoc comment formatting.\n\nWhen enabled, JSDoc comments are normalized and reformatted:\ntag aliases are canonicalized, descriptions are capitalized,\nlong lines are wrapped, and short comments are collapsed to single-line.\n\nPass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.\n\n- Default: Disabled"
+        },
         "jsxSingleQuote": {
           "description": "Use single quotes instead of double quotes in JSX.\n\n- Default: `false`",
           "type": "boolean",
@@ -408,6 +426,66 @@
         "ignore"
       ]
     },
+    "JsdocConfig": {
+      "type": "object",
+      "properties": {
+        "addDefaultToDescription": {
+          "description": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Append default values to `@param` descriptions (e.g. \"Default is `value`\").\n\n- Default: `true`"
+        },
+        "bracketSpacing": {
+          "description": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Add spaces inside JSDoc type braces: `{string}` → `{ string }`.\n\n- Default: `false`"
+        },
+        "capitalizeDescriptions": {
+          "description": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`",
+          "type": "boolean",
+          "markdownDescription": "Capitalize the first letter of tag descriptions.\n\n- Default: `true`"
+        },
+        "commentLineStrategy": {
+          "description": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`",
+          "type": "string",
+          "markdownDescription": "How to format comment blocks.\n\n- `\"singleLine\"` — Convert to single-line `/** content */` when possible.\n- `\"multiline\"` — Always use multi-line format.\n- `\"keep\"` — Preserve original formatting.\n\n- Default: `\"singleLine\"`"
+        },
+        "descriptionTag": {
+          "description": "Emit `@description` tag instead of inline description.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Emit `@description` tag instead of inline description.\n\n- Default: `false`"
+        },
+        "descriptionWithDot": {
+          "description": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Add a trailing dot to the end of descriptions.\n\n- Default: `false`"
+        },
+        "keepUnparsableExampleIndent": {
+          "description": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Preserve indentation in unparsable `@example` code.\n\n- Default: `false`"
+        },
+        "lineWrappingStyle": {
+          "description": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`",
+          "type": "string",
+          "markdownDescription": "Strategy for wrapping description lines at print width.\n\n- `\"greedy\"` — Always re-wrap text to fit within print width.\n- `\"balance\"` — Preserve original line breaks if all lines fit within print width.\n\n- Default: `\"greedy\"`"
+        },
+        "preferCodeFences": {
+          "description": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.\n\n- Default: `false`"
+        },
+        "separateReturnsFromParam": {
+          "description": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Add a blank line between the last `@param` and `@returns`.\n\n- Default: `false`"
+        },
+        "separateTagGroups": {
+          "description": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`",
+          "type": "boolean",
+          "markdownDescription": "Add blank lines between different tag groups (e.g. between `@param` and `@returns`).\n\n- Default: `false`"
+        }
+      }
+    },
     "NewlinesBetweenMarker": {
       "description": "A marker object for overriding `newlinesBetween` at a specific group boundary.",
       "type": "object",

package/dist/{apis-CF7S9zfN.js → apis-B6IsFaEf.js}

@@ -3,6 +3,9 @@ let prettierCache;
 async function loadPrettier() {
 	if (prettierCache) return prettierCache;
 	prettierCache = await import("./prettier-DmvT5K0i.js");
+	const { formatOptionsHiddenDefaults } = prettierCache.__internal;
+	formatOptionsHiddenDefaults.parentParser = null;
+	formatOptionsHiddenDefaults.__onHtmlRoot = null;
 	return prettierCache;
 }
 /**
@@ -55,10 +58,15 @@ async function formatEmbeddedDoc({ texts, options }) {
 	const prettier = await loadPrettier();
 	await setupTailwindPlugin(options);
 	return Promise.all(texts.map(async (text) => {
+		const metadata = {};
+		if (options.parser === "html") {
+			options.parentParser = "OXFMT";
+			options.__onHtmlRoot = (root) => metadata.htmlHasMultipleRootElements = (root.children?.length ?? 0) > 1;
+		}
 		const doc = await prettier.__debug.printToDoc(text, options);
 		const symbolToNumber = /* @__PURE__ */ new Map();
 		let nextId = 1;
-		return JSON.stringify(doc, (_key, value) => {
+		return JSON.stringify([doc, metadata], (_key, value) => {
 			if (typeof value === "symbol") {
 				if (!symbolToNumber.has(value)) symbolToNumber.set(value, nextId++);
 				return symbolToNumber.get(value);
@@ -104,7 +112,7 @@ async function sortTailwindClasses({ classes, options }) {
 let oxfmtPluginCache;
 async function loadOxfmtPlugin() {
 	if (oxfmtPluginCache) return oxfmtPluginCache;
-	oxfmtPluginCache = await import("./prettier-plugin-oxfmt-BqWJLUOn.js");
+	oxfmtPluginCache = await import("./prettier-plugin-oxfmt-DkmSndQ0.js");
 	return oxfmtPluginCache;
 }
 /**

package/dist/cli-worker.js

@@ -1,2 +1,2 @@
-import { a as sortTailwindClasses, n as formatEmbeddedDoc, r as formatFile, t as formatEmbeddedCode } from "./apis-CF7S9zfN.js";
+import { a as sortTailwindClasses, n as formatEmbeddedDoc, r as formatFile, t as formatEmbeddedCode } from "./apis-B6IsFaEf.js";
 export { formatEmbeddedCode, formatEmbeddedDoc, formatFile, sortTailwindClasses };

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { r as runCli } from "./bindings-D6U4DxG3.js";
-import { i as resolvePlugins } from "./apis-CF7S9zfN.js";
+import { i as resolvePlugins } from "./apis-B6IsFaEf.js";
 import Tinypool from "tinypool";
 import { basename } from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/index.d.ts

@@ -98,6 +98,18 @@ interface Oxfmtrc {
    * - Overrides `.editorconfig.insert_final_newline`
    */
   insertFinalNewline?: boolean;
+  /**
+   * Enable JSDoc comment formatting.
+   *
+   * When enabled, JSDoc comments are normalized and reformatted:
+   * tag aliases are canonicalized, descriptions are capitalized,
+   * long lines are wrapped, and short comments are collapsed to single-line.
+   *
+   * Pass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.
+   *
+   * - Default: Disabled
+   */
+  jsdoc?: JsdocConfig;
   /**
    * Use single quotes instead of double quotes in JSX.
    *
@@ -224,6 +236,82 @@ interface Oxfmtrc {
   vueIndentScriptAndStyle?: boolean;
   [k: string]: unknown;
 }
+interface JsdocConfig {
+  /**
+   * Append default values to `@param` descriptions (e.g. "Default is `value`").
+   *
+   * - Default: `true`
+   */
+  addDefaultToDescription?: boolean;
+  /**
+   * Add spaces inside JSDoc type braces: `{string}` → `{ string }`.
+   *
+   * - Default: `false`
+   */
+  bracketSpacing?: boolean;
+  /**
+   * Capitalize the first letter of tag descriptions.
+   *
+   * - Default: `true`
+   */
+  capitalizeDescriptions?: boolean;
+  /**
+   * How to format comment blocks.
+   *
+   * - `"singleLine"` — Convert to single-line `/** content * /` when possible.
+   * - `"multiline"` — Always use multi-line format.
+   * - `"keep"` — Preserve original formatting.
+   *
+   * - Default: `"singleLine"`
+   */
+  commentLineStrategy?: string;
+  /**
+   * Emit `@description` tag instead of inline description.
+   *
+   * - Default: `false`
+   */
+  descriptionTag?: boolean;
+  /**
+   * Add a trailing dot to the end of descriptions.
+   *
+   * - Default: `false`
+   */
+  descriptionWithDot?: boolean;
+  /**
+   * Preserve indentation in unparsable `@example` code.
+   *
+   * - Default: `false`
+   */
+  keepUnparsableExampleIndent?: boolean;
+  /**
+   * Strategy for wrapping description lines at print width.
+   *
+   * - `"greedy"` — Always re-wrap text to fit within print width.
+   * - `"balance"` — Preserve original line breaks if all lines fit within print width.
+   *
+   * - Default: `"greedy"`
+   */
+  lineWrappingStyle?: string;
+  /**
+   * Use fenced code blocks (```` ``` ````) instead of 4-space indentation for code without a language tag.
+   *
+   * - Default: `false`
+   */
+  preferCodeFences?: boolean;
+  /**
+   * Add a blank line between the last `@param` and `@returns`.
+   *
+   * - Default: `false`
+   */
+  separateReturnsFromParam?: boolean;
+  /**
+   * Add blank lines between different tag groups (e.g. between `@param` and `@returns`).
+   *
+   * - Default: `false`
+   */
+  separateTagGroups?: boolean;
+  [k: string]: unknown;
+}
 interface OxfmtOverrideConfig {
   /**
    * Glob patterns to exclude from this override.
@@ -290,6 +378,18 @@ interface FormatConfig {
    * - Overrides `.editorconfig.insert_final_newline`
    */
   insertFinalNewline?: boolean;
+  /**
+   * Enable JSDoc comment formatting.
+   *
+   * When enabled, JSDoc comments are normalized and reformatted:
+   * tag aliases are canonicalized, descriptions are capitalized,
+   * long lines are wrapped, and short comments are collapsed to single-line.
+   *
+   * Pass an object (`jsdoc: {}`) to enable with defaults, or omit to disable.
+   *
+   * - Default: Disabled
+   */
+  jsdoc?: JsdocConfig;
   /**
    * Use single quotes instead of double quotes in JSX.
    *
@@ -639,7 +739,7 @@ interface SortTailwindcssConfig {
 }
 //#endregion
 //#region src-js/index.d.ts
-type OxfmtConfig = Oxfmtrc;
+interface OxfmtConfig extends Oxfmtrc {}
 /**
  * Configuration options for the `format()` API.
  *
@@ -673,4 +773,4 @@ declare function format(fileName: string, sourceText: string, options?: FormatCo
  */
 declare function jsTextToDoc(sourceExt: string, sourceText: string, oxfmtPluginOptionsJson: string, parentContext: string): Promise<string | null>;
 //#endregion
-export { type FormatConfig, FormatOptions, OxfmtConfig, SortImportsOptions, SortPackageJsonOptions, SortTailwindcssOptions, TailwindcssOptions, defineConfig, format, jsTextToDoc };
+export { ArrowParensConfig, CustomGroupItemConfig, EmbeddedLanguageFormattingConfig, EndOfLineConfig, FormatConfig, FormatOptions, HtmlWhitespaceSensitivityConfig, JsdocConfig, NewlinesBetweenMarker, ObjectWrapConfig, OxfmtConfig, OxfmtOverrideConfig, Oxfmtrc, ProseWrapConfig, QuotePropsConfig, SortGroupItemConfig, SortImportsConfig, SortImportsOptions, SortOrderConfig, SortPackageJsonConfig, SortPackageJsonOptions, SortPackageJsonUserConfig, SortTailwindcssConfig, SortTailwindcssOptions, TailwindcssOptions, TrailingCommaConfig, defineConfig, format, jsTextToDoc };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { n as jsTextToDoc$1, t as format$1 } from "./bindings-D6U4DxG3.js";
-import { a as sortTailwindClasses, i as resolvePlugins, n as formatEmbeddedDoc, r as formatFile, t as formatEmbeddedCode } from "./apis-CF7S9zfN.js";
+import { a as sortTailwindClasses, i as resolvePlugins, n as formatEmbeddedDoc, r as formatFile, t as formatEmbeddedCode } from "./apis-B6IsFaEf.js";
 //#region src-js/index.ts
 /**
 * Define an oxfmt configuration with type inference.

package/dist/{prettier-plugin-oxfmt-BqWJLUOn.js → prettier-plugin-oxfmt-DkmSndQ0.js}

@@ -1,5 +1,5 @@
 import "./bindings-D6U4DxG3.js";
-import "./apis-CF7S9zfN.js";
+import "./apis-B6IsFaEf.js";
 import { jsTextToDoc } from "./index.js";
 //#region src-js/libs/prettier-plugin-oxfmt/text-to-doc.ts
 const textToDoc = async (embeddedSourceText, textToDocOptions) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oxfmt",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Formatter for the JavaScript Oxidation Compiler",
   "keywords": [
     "formatter",
@@ -67,24 +67,24 @@
   },
   "preferUnplugged": true,
   "optionalDependencies": {
-    "@oxfmt/binding-darwin-arm64": "0.41.0",
-    "@oxfmt/binding-android-arm64": "0.41.0",
-    "@oxfmt/binding-win32-arm64-msvc": "0.41.0",
-    "@oxfmt/binding-linux-arm64-gnu": "0.41.0",
-    "@oxfmt/binding-linux-arm64-musl": "0.41.0",
-    "@oxfmt/binding-openharmony-arm64": "0.41.0",
-    "@oxfmt/binding-android-arm-eabi": "0.41.0",
-    "@oxfmt/binding-linux-arm-gnueabihf": "0.41.0",
-    "@oxfmt/binding-linux-arm-musleabihf": "0.41.0",
-    "@oxfmt/binding-win32-ia32-msvc": "0.41.0",
-    "@oxfmt/binding-linux-ppc64-gnu": "0.41.0",
-    "@oxfmt/binding-linux-riscv64-gnu": "0.41.0",
-    "@oxfmt/binding-linux-riscv64-musl": "0.41.0",
-    "@oxfmt/binding-linux-s390x-gnu": "0.41.0",
-    "@oxfmt/binding-darwin-x64": "0.41.0",
-    "@oxfmt/binding-win32-x64-msvc": "0.41.0",
-    "@oxfmt/binding-freebsd-x64": "0.41.0",
-    "@oxfmt/binding-linux-x64-gnu": "0.41.0",
-    "@oxfmt/binding-linux-x64-musl": "0.41.0"
+    "@oxfmt/binding-darwin-arm64": "0.42.0",
+    "@oxfmt/binding-android-arm64": "0.42.0",
+    "@oxfmt/binding-win32-arm64-msvc": "0.42.0",
+    "@oxfmt/binding-linux-arm64-gnu": "0.42.0",
+    "@oxfmt/binding-linux-arm64-musl": "0.42.0",
+    "@oxfmt/binding-openharmony-arm64": "0.42.0",
+    "@oxfmt/binding-android-arm-eabi": "0.42.0",
+    "@oxfmt/binding-linux-arm-gnueabihf": "0.42.0",
+    "@oxfmt/binding-linux-arm-musleabihf": "0.42.0",
+    "@oxfmt/binding-win32-ia32-msvc": "0.42.0",
+    "@oxfmt/binding-linux-ppc64-gnu": "0.42.0",
+    "@oxfmt/binding-linux-riscv64-gnu": "0.42.0",
+    "@oxfmt/binding-linux-riscv64-musl": "0.42.0",
+    "@oxfmt/binding-linux-s390x-gnu": "0.42.0",
+    "@oxfmt/binding-darwin-x64": "0.42.0",
+    "@oxfmt/binding-win32-x64-msvc": "0.42.0",
+    "@oxfmt/binding-freebsd-x64": "0.42.0",
+    "@oxfmt/binding-linux-x64-gnu": "0.42.0",
+    "@oxfmt/binding-linux-x64-musl": "0.42.0"
   }
 }