docs: avoid typedoc warnings

Author: boneskull

.config/typedoc.js

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs';
+import { OptionDefaults } from 'typedoc';
 
 /**
  * @import {TypeDocOptions} from "typedoc"
@@ -12,6 +13,7 @@ const customFooterHtml = readFileSync(
 /** @type {Partial<TypeDocOptions>} */
 export default {
   basePath: process.env.GITHUB_ACTIONS ? '/bargs/' : '/',
+  blockTags: [...OptionDefaults.blockTags, '@knipignore'],
   customCss: '../site/media/bargs-theme.css',
   customFooterHtml,
   darkHighlightTheme: 'vitesse-dark',

package.json

@@ -41,7 +41,8 @@
   "scripts": {
     "build": "zshy",
     "commitlint": "commitlint",
-    "docs": "typedoc",
+    "docs": "typedoc --treatWarningsAsErrors",
+    "docs:dev": "typedoc --watch",
     "fix": "run-s -sl fix:*",
     "fix:eslint": "eslint --fix .",
     "fix:markdown": "markdownlint-cli2 --fix \"**/*.md\"",

src/bargs.ts

@@ -25,6 +25,19 @@ import { defaultTheme, getTheme, type Theme } from './theme.js';
 // INTERNAL TYPES
 // ═══════════════════════════════════════════════════════════════════════════════
 
+/**
+ * Transform fn type - can be sync or async.
+ *
+ * @knipignore
+ */
+export type TransformFn<
+  V1,
+  P1 extends readonly unknown[],
+  V2,
+  P2 extends readonly unknown[],
+> = (
+  result: ParseResult<V1, P1>,
+) => ParseResult<V2, P2> | Promise<ParseResult<V2, P2>>;
 // Type for commands that may have transforms
 type CommandWithTransform<V, P extends readonly unknown[]> = Command<V, P> & {
   __transform?: (
@@ -48,17 +61,6 @@ type ParserWithTransform<V, P extends readonly unknown[]> = Parser<V, P> & {
     r: ParseResult<unknown, readonly unknown[]>,
   ) => ParseResult<V, P>;
 };
-/**
- * Transform fn type - can be sync or async.
- */
-type TransformFn<
-  V1,
-  P1 extends readonly unknown[],
-  V2,
-  P2 extends readonly unknown[],
-> = (
-  result: ParseResult<V1, P1>,
-) => ParseResult<V2, P2> | Promise<ParseResult<V2, P2>>;
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // MERGE COMBINATOR

src/help.ts

@@ -27,8 +27,10 @@ import { readPackageInfoSync } from './version.js';
 
 /**
  * Minimal config shape for help generation.
+ *
+ * @knipignore
  */
-interface HelpConfig {
+export interface HelpConfig {
   commands?: Record<
     string,
     {

src/index.ts

@@ -25,15 +25,21 @@
 
 // Main API
 export { bargs, handle, map, merge } from './bargs.js';
+export type { TransformFn } from './bargs.js';
 
 // Errors
 export { BargsError, HelpError, ValidationError } from './errors.js';
 
 // Help generators
 export { generateCommandHelp, generateHelp } from './help.js';
+export type { HelpConfig } from './help.js';
 
 // Option and positional builders
 export { opt, pos } from './opt.js';
+export type {
+  CallableOptionsParser,
+  CallablePositionalsParser,
+} from './opt.js';
 
 // OSC utilities for terminal hyperlinks
 export { link, linkifyUrls, supportsHyperlinks } from './osc.js';

src/opt.ts

@@ -59,8 +59,10 @@ const validateAliasConflicts = (schema: OptionsSchema): void => {
  *
  * - First arg in pipe: used directly as a Parser
  * - Later arg in pipe: called as function to merge with incoming Parser
+ *
+ * @knipignore
  */
-type CallableOptionsParser<V> = (<V2, P2 extends readonly unknown[]>(
+export type CallableOptionsParser<V> = (<V2, P2 extends readonly unknown[]>(
   parser: Parser<V2, P2>,
 ) => Parser<V & V2, P2>) &
   Parser<V, readonly []>;
@@ -290,21 +292,16 @@ export const opt = {
  * - Later arg in pipe: called as function to merge with incoming Parser
  *
  * For positionals, we DON'T intersect values - we just pass through V2.
+ *
+ * @knipignore
  */
-type CallablePositionalsParser<P extends readonly unknown[]> = (<
+export type CallablePositionalsParser<P extends readonly unknown[]> = (<
   V2,
   P2 extends readonly unknown[],
 >(
   parser: Parser<V2, P2>,
 ) => Parser<V2, readonly [...P2, ...P]>) &
-  Parser<EmptyObject, P>;
-
-/**
- * Empty object type that works better with intersections than Record<string,
- * never>. {} & T = T, but Record<string, never> & T can be problematic.
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-type EmptyObject = {};
+  Parser<object, P>;
 
 /**
  * Create a Parser from positional definitions that can also merge with existing
@@ -341,12 +338,12 @@ const positionalsImpl = <T extends PositionalsSchema>(
 
   // Add Parser properties to the function
   // Use empty object {} instead of Record<string, never> for better intersection behavior
-  const parserProps: Parser<EmptyObject, InferPositionals<T>> = {
+  const parserProps: Parser<object, InferPositionals<T>> = {
     __brand: 'Parser',
     __optionsSchema: {},
     __positionals: [] as unknown as InferPositionals<T>,
     __positionalsSchema: positionals,
-    __values: {} as EmptyObject,
+    __values: {},
   };
 
   return Object.assign(merger, parserProps) as CallablePositionalsParser<