@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/dependency.js

@@ -66,6 +66,7 @@ const suggestWithDependency = Symbol.for("@optique/core/dependency/suggestWithDe
 * // Create a derived parser that depends on the directory
 * const branchParser = cwdParser.derive({
 *   metavar: "BRANCH",
+*   mode: "sync",
 *   factory: (dir) => gitBranch({ dir }),
 *   defaultValue: () => process.cwd(),
 * });
@@ -79,14 +80,15 @@ function dependency(parser) {
 		[dependencySourceMarker]: true,
 		[dependencyId]: id,
 		derive(options) {
-			return createDerivedValueParser(id, parser, options);
+			if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("derive() requires an explicit mode field (\"sync\" or \"async\").");
+			return createDerivedValueParser(id, parser, options, options.mode);
 		},
 		deriveSync(options) {
 			if (parser.$mode === "async") return createAsyncDerivedParserFromSyncFactory(id, options);
 			return createSyncDerivedParser(id, options);
 		},
 		deriveAsync(options) {
-			return createDerivedValueParser(id, parser, options);
+			return createAsyncDerivedParserFromAsyncFactory(id, options);
 		}
 	};
 	return result;
@@ -132,6 +134,7 @@ function isDerivedValueParser(parser) {
 *
 * const configParser = deriveFrom({
 *   metavar: "CONFIG",
+*   mode: "sync",
 *   dependencies: [dirParser, modeParser] as const,
 *   factory: (dir, mode) =>
 *     choice(mode === "dev"
@@ -140,12 +143,14 @@ function isDerivedValueParser(parser) {
 *   defaultValues: () => ["/config", "dev"],
 * });
 * ```
+* @throws {TypeError} If the `mode` field is missing or invalid.
 * @since 0.10.0
 */
 function deriveFrom(options) {
+	if (options.mode !== "sync" && options.mode !== "async") throw new TypeError("deriveFrom() requires an explicit mode field (\"sync\" or \"async\").");
 	const depsAsync = options.dependencies.some((dep) => dep.$mode === "async");
-	const factoryReturnsAsync = determineFactoryModeForDeriveFrom(options);
 	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
+	const factoryReturnsAsync = options.mode === "async";
 	const isAsync = depsAsync || factoryReturnsAsync;
 	if (isAsync) {
 		if (factoryReturnsAsync) return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
@@ -191,14 +196,6 @@ function deriveFromAsync(options) {
 	const sourceId = options.dependencies.length > 0 ? options.dependencies[0][dependencyId] : Symbol();
 	return createAsyncDerivedFromParserFromAsyncFactory(sourceId, options);
 }
-/**
-* Determines if the factory returns an async parser for deriveFrom options.
-*/
-function determineFactoryModeForDeriveFrom(options) {
-	const defaultValues$1 = options.defaultValues();
-	const parser = options.factory(...defaultValues$1);
-	return parser.$mode === "async";
-}
 function isAsyncModeParser(parser) {
 	return parser.$mode === "async";
 }
@@ -212,8 +209,17 @@ function createSyncDerivedFromParser(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+			}
 			if (isAsyncModeParser(derivedParser)) return {
 				success: false,
 				error: message`Factory returned an async parser where a sync parser is required.`
@@ -238,14 +244,25 @@ function createSyncDerivedFromParser(sourceId, options) {
 			return derivedParser.parse(input);
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		*suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
@@ -259,7 +276,8 @@ function createSyncDerivedFromParser(sourceId, options) {
 					return;
 				}
 			}
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		}
 	};
 }
@@ -277,9 +295,18 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
-			return derivedParser.parse(input);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				});
+			}
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
 			let derivedParser;
@@ -292,16 +319,26 @@ function createAsyncDerivedFromParserFromAsyncFactory(sourceId, options) {
 					error: message`Factory error: ${msg}`
 				});
 			}
-			return derivedParser.parse(input);
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		},
 		async *[suggestWithDependency](prefix, dependencyValue) {
@@ -334,8 +371,17 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 		[dependencyIds]: alldependencyIds,
 		[defaultValues]: options.defaultValues,
 		parse(input) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				});
+			}
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -352,13 +398,23 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValues = options.defaultValues();
-			const derivedParser = options.factory(...sourceValues);
+			let derivedParser;
+			try {
+				const sourceValues = options.defaultValues();
+				derivedParser = options.factory(...sourceValues);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
@@ -377,8 +433,8 @@ function createAsyncDerivedFromParserFromSyncFactory(sourceId, options) {
 		}
 	};
 }
-function createDerivedValueParser(sourceId, sourceParser, options) {
-	const factoryReturnsAsync = determineFactoryMode(options);
+function createDerivedValueParser(sourceId, sourceParser, options, factoryMode) {
+	const factoryReturnsAsync = factoryMode === "async";
 	const isAsync = sourceParser.$mode === "async" || factoryReturnsAsync;
 	if (isAsync) {
 		if (factoryReturnsAsync) return createAsyncDerivedParserFromAsyncFactory(sourceId, options);
@@ -386,15 +442,6 @@ function createDerivedValueParser(sourceId, sourceParser, options) {
 	}
 	return createSyncDerivedParser(sourceId, options);
 }
-/**
-* Determines if the factory returns an async parser by calling it with
-* the default value and checking the mode.
-*/
-function determineFactoryMode(options) {
-	const defaultValue = options.defaultValue();
-	const parser = options.factory(defaultValue);
-	return parser.$mode === "async";
-}
 function createSyncDerivedParser(sourceId, options) {
 	return {
 		$mode: "sync",
@@ -402,8 +449,17 @@ function createSyncDerivedParser(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return {
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				};
+			}
 			if (isAsyncModeParser(derivedParser)) return {
 				success: false,
 				error: message`Factory returned an async parser where a sync parser is required.`
@@ -428,14 +484,25 @@ function createSyncDerivedParser(sourceId, options) {
 			return derivedParser.parse(input);
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		*suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {
 			let derivedParser;
@@ -448,7 +515,8 @@ function createSyncDerivedParser(sourceId, options) {
 					return;
 				}
 			}
-			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
+			if (isAsyncModeParser(derivedParser) || !derivedParser.suggest) return;
+			yield* derivedParser.suggest(prefix);
 		}
 	};
 }
@@ -463,9 +531,18 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
-			return derivedParser.parse(input);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				});
+			}
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
 			let derivedParser;
@@ -478,16 +555,26 @@ function createAsyncDerivedParserFromAsyncFactory(sourceId, options) {
 					error: message`Factory error: ${msg}`
 				});
 			}
-			return derivedParser.parse(input);
+			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) for await (const suggestion of derivedParser.suggest(prefix)) yield suggestion;
 		},
 		async *[suggestWithDependency](prefix, dependencyValue) {
@@ -516,8 +603,17 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 		[derivedValueParserMarker]: true,
 		[dependencyId]: sourceId,
 		parse(input) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				return Promise.resolve({
+					success: false,
+					error: message`Derived parser error: ${msg}`
+				});
+			}
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		[parseWithDependency](input, dependencyValue) {
@@ -534,13 +630,23 @@ function createAsyncDerivedParserFromSyncFactory(sourceId, options) {
 			return Promise.resolve(derivedParser.parse(input));
 		},
 		format(value) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return String(value);
+			}
 			return derivedParser.format(value);
 		},
 		async *suggest(prefix) {
-			const sourceValue = options.defaultValue();
-			const derivedParser = options.factory(sourceValue);
+			let derivedParser;
+			try {
+				const sourceValue = options.defaultValue();
+				derivedParser = options.factory(sourceValue);
+			} catch {
+				return;
+			}
 			if (derivedParser.suggest) yield* derivedParser.suggest(prefix);
 		},
 		*[suggestWithDependency](prefix, dependencyValue) {

package/dist/doc.cjs

@@ -3,6 +3,39 @@ const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* Scores a section for the default smart sort.  Untitled sections receive
+* a bonus of `-1` so that the main (untitled) section appears before titled
+* sections of a similar classification.
+*/
+function scoreSection(section) {
+	return classifySection(section) + (section.title == null ? -1 : 0);
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Untitled sections
+* receive a score bonus of -1 via {@link scoreSection} so that untitled
+* command-only sections naturally sort before titled command-only sections.
+* Sections with the same score preserve their original relative order
+* (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return scoreSection(a) - scoreSection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -14,6 +47,8 @@ const require_usage = require('./usage.cjs');
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
+* @throws {TypeError} If `programName` or any non-empty section's title
+* contains a CR or LF character.
 *
 * @example
 * ```typescript
@@ -34,6 +69,7 @@ const require_usage = require('./usage.cjs');
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
+	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	let output = "";
@@ -64,11 +100,20 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		return a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
+			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/doc.d.cts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -241,6 +263,8 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
+ * @throws {TypeError} If `programName` or any non-empty section's title
+ * contains a CR or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.d.ts

@@ -228,6 +228,28 @@ interface DocPageFormatOptions {
    * ```
    */
   showChoices?: boolean | ShowChoicesOptions;
+  /**
+   * A custom comparator function to control the order of sections in the
+   * help output.  When provided, it is used instead of the default smart
+   * sort (command-only sections first, then mixed, then option/argument-only
+   * sections).  Sections that compare equal (return `0`) preserve their
+   * original relative order (stable sort).
+   *
+   * @param a The first section to compare.
+   * @param b The second section to compare.
+   * @returns A negative number if `a` should appear before `b`, a positive
+   *   number if `a` should appear after `b`, or `0` if they are equal.
+   * @since 1.0.0
+   *
+   * @example
+   * ```typescript
+   * // Sort sections alphabetically by title
+   * {
+   *   sectionOrder: (a, b) => (a.title ?? "").localeCompare(b.title ?? "")
+   * }
+   * ```
+   */
+  sectionOrder?: (a: DocSection, b: DocSection) => number;
 }
 /**
  * Formats a documentation page into a human-readable string.
@@ -241,6 +263,8 @@ interface DocPageFormatOptions {
  * @param page The documentation page to format
  * @param options Formatting options to customize the output
  * @returns A formatted string representation of the documentation page
+ * @throws {TypeError} If `programName` or any non-empty section's title
+ * contains a CR or LF character.
  *
  * @example
  * ```typescript

package/dist/doc.js

@@ -3,6 +3,39 @@ import { formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
 /**
+* Classifies a {@link DocSection} by its content type for use in the
+* default smart sort.
+*
+* @returns `0` for command-only sections, `1` for mixed sections, `2` for
+*   option/argument/passthrough-only sections.
+*/
+function classifySection(section) {
+	const hasCommand = section.entries.some((e) => e.term.type === "command");
+	const hasNonCommand = section.entries.some((e) => e.term.type !== "command");
+	if (hasCommand && !hasNonCommand) return 0;
+	if (hasCommand && hasNonCommand) return 1;
+	return 2;
+}
+/**
+* Scores a section for the default smart sort.  Untitled sections receive
+* a bonus of `-1` so that the main (untitled) section appears before titled
+* sections of a similar classification.
+*/
+function scoreSection(section) {
+	return classifySection(section) + (section.title == null ? -1 : 0);
+}
+/**
+* The default section comparator: command-only sections come first, then
+* mixed sections, then option/argument-only sections.  Untitled sections
+* receive a score bonus of -1 via {@link scoreSection} so that untitled
+* command-only sections naturally sort before titled command-only sections.
+* Sections with the same score preserve their original relative order
+* (stable sort).
+*/
+function defaultSectionOrder(a, b) {
+	return scoreSection(a) - scoreSection(b);
+}
+/**
 * Formats a documentation page into a human-readable string.
 *
 * This function takes a structured {@link DocPage} and converts it into
@@ -14,6 +47,8 @@ import { formatUsage, formatUsageTerm } from "./usage.js";
 * @param page The documentation page to format
 * @param options Formatting options to customize the output
 * @returns A formatted string representation of the documentation page
+* @throws {TypeError} If `programName` or any non-empty section's title
+* contains a CR or LF character.
 *
 * @example
 * ```typescript
@@ -34,6 +69,7 @@ import { formatUsage, formatUsageTerm } from "./usage.js";
 * ```
 */
 function formatDocPage(programName, page, options = {}) {
+	if (/[\r\n]/.test(programName)) throw new TypeError("Program name must not contain newlines.");
 	const termIndent = options.termIndent ?? 2;
 	const termWidth = options.termWidth ?? 26;
 	let output = "";
@@ -64,11 +100,20 @@ function formatDocPage(programName, page, options = {}) {
 		});
 		output += "\n";
 	}
-	const sections = page.sections.toSorted((a, b) => a.title == null && b.title == null ? 0 : a.title == null ? -1 : 1);
+	const comparator = options.sectionOrder ?? defaultSectionOrder;
+	const sections = page.sections.map((s, i) => ({
+		section: s,
+		index: i
+	})).toSorted((a, b) => {
+		const cmp = comparator(a.section, b.section);
+		if (cmp !== 0) return cmp;
+		return a.index - b.index;
+	}).map(({ section }) => section);
 	for (const section of sections) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
+			if (/[\r\n]/.test(section.title)) throw new TypeError("Section title must not contain newlines.");
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}