Reduce public API surface and implement API Extractor

.gitignore

@@ -2,4 +2,5 @@ node_modules
 .tmp
 .nyc_output
 coverage
-dist
+dist
+temp

api-extractor.jsonc

@@ -0,0 +1,95 @@
+{
+    "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+
+    /**
+     * The entry point that api-extractor analyzes. Everything reachable from here is a candidate
+     * for the public API; we then use release tags (@public / @internal) to decide what's actually exposed.
+     */
+    "mainEntryPointFilePath": "<projectFolder>/dist/index.d.ts",
+
+    "projectFolder": ".",
+
+    "compiler": {
+        "tsconfigFilePath": "<projectFolder>/tsconfig.json"
+    },
+
+    /**
+     * The API report (.api.md) is the committed contract describing our public surface.
+     * Both scripts regenerate the trimmed dist/index.d.ts rollup; the difference is what they do with
+     * this report file:
+     *   - `npm run api:build-and-validate` (api-extractor run, no --local): CI gate — compares against the
+     *     committed report and FAILS if the public API drifted.
+     *   - `npm run api:build-and-update` (api-extractor run --local): OVERWRITES the committed report to
+     *     accept an intentional API change (does not fail).
+     */
+    "apiReport": {
+        "enabled": true,
+        "reportFolder": "<projectFolder>/api",
+        "reportFileName": "logger.api.md"
+    },
+
+    /**
+     * Roll all of the per-file .d.ts files up into a single index.d.ts, trimming out everything
+     * that is NOT marked @public. This trimmed file is what we ship to consumers (see "typings" in package.json),
+     * so consumers only ever see the API we deliberately marked @public.
+     */
+    "dtsRollup": {
+        "enabled": true,
+        "untrimmedFilePath": "<projectFolder>/.tmp/index.untrimmed.d.ts",
+        "publicTrimmedFilePath": "<projectFolder>/dist/index.d.ts"
+    },
+
+    "docModel": {
+        "enabled": false
+    },
+
+    "tsdocMetadata": {
+        "enabled": false
+    },
+
+    "messages": {
+        "compilerMessageReporting": {
+            "default": {
+                "logLevel": "warning"
+            }
+        },
+
+        "extractorMessageReporting": {
+            "default": {
+                "logLevel": "warning"
+            },
+
+            /**
+             * Make an untagged export a hard error. Combined with our "private by default" policy, this forces
+             * every exported symbol to be explicitly classified: @public to expose it, or @internal to hide it.
+             * Nothing can leak into the public API by accident.
+             */
+            "ae-missing-release-tag": {
+                "logLevel": "error",
+                "addToApiReportFile": false
+            },
+
+            /**
+             * It's expected and intended that @public symbols reference @internal ones (e.g. the public Logger
+             * exposes an @internal options type internally); we don't want that to be an error.
+             */
+            "ae-incompatible-release-tags": {
+                "logLevel": "none"
+            },
+
+            /**
+             * We intentionally keep internal symbols un-rolled-up rather than forwarding them; silence the
+             * "forgotten export" noise for symbols we've deliberately marked @internal.
+             */
+            "ae-forgotten-export": {
+                "logLevel": "none"
+            }
+        },
+
+        "tsdocMessageReporting": {
+            "default": {
+                "logLevel": "warning"
+            }
+        }
+    }
+}

api/logger.api.md

@@ -0,0 +1,177 @@
+## API Report File for "@rokucommunity/logger"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import Chalk = require('chalk');
+import type { ChalkFunction } from 'chalk';
+
+// Warning: (ae-internal-missing-underscore) The name "chalk" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal
+export const chalk: Chalk.Chalk;
+
+// @public
+export class ConsoleTransport {
+    // (undocumented)
+    pipe(message: LogMessage): void;
+}
+
+// @public
+export const createLogger: {
+    (): Logger;
+    (prefix: string): Logger;
+    (options: Partial<LoggerOptions>): Logger;
+};
+
+// @public
+export class FileTransport extends QueuedTransport {
+    constructor(logFilePath?: string);
+    // (undocumented)
+    setLogFilePath(logfilePath?: string): void;
+}
+
+// @public
+export class Logger {
+    constructor(prefix?: string);
+    constructor(options?: Partial<LoggerOptions>);
+    addTransport(transport: Transport): () => void;
+    buildLogMessage(logLevel: LogLevel | LogLevelNumeric, ...args: unknown[]): LogMessage;
+    get consistentLogLevelWidth(): boolean;
+    set consistentLogLevelWidth(value: boolean);
+    createLogger(): Logger;
+    // (undocumented)
+    createLogger(prefix: string): Logger;
+    // (undocumented)
+    createLogger(options: Partial<LoggerOptions>): Logger;
+    // (undocumented)
+    debug(...messages: unknown[]): void;
+    // (undocumented)
+    destroy(): void;
+    get enableColor(): boolean;
+    set enableColor(value: boolean);
+    // (undocumented)
+    error(...messages: unknown[]): void;
+    formatLeadingMessageParts(message: LogMessage, enableColor?: boolean): string;
+    formatMessage(message: LogMessage, enableColor?: boolean): string;
+    // (undocumented)
+    formatTimestamp(date: Date): string;
+    getLogLevelNumeric(logLevel: LogLevel | LogLevelNumeric): LogLevelNumeric;
+    getLogLevelText(logLevel: LogLevel | LogLevelNumeric): LogLevel;
+    // (undocumented)
+    info(...messages: unknown[]): void;
+    isLogLevelEnabled(targetLogLevel: LogLevel | LogLevelNumeric): boolean;
+    // (undocumented)
+    log(...messages: unknown[]): void;
+    get logLevel(): LogLevel | LogLevelNumeric;
+    set logLevel(value: LogLevel | LogLevelNumeric);
+    // (undocumented)
+    get parent(): Logger | undefined;
+    set parent(value: Logger | undefined);
+    get prefix(): string | undefined;
+    set prefix(value: string | undefined);
+    get printLogLevel(): boolean;
+    set printLogLevel(value: boolean);
+    get printTimestamp(): boolean;
+    set printTimestamp(value: boolean);
+    removeTransport(transport: Transport): void;
+    stringifyArgs(args: unknown[]): string;
+    subscribe(subscriber: MessageHandler): () => void;
+    time<T>(logLevel: LogLevel | LogLevelNumeric, messages: any[], action: (pause: () => void, resume: () => void) => T): T;
+    get timestampFormat(): string;
+    set timestampFormat(value: string | undefined);
+    timeStart(logLevel: LogLevel | LogLevelNumeric, ...messages: unknown[]): (status?: string) => void;
+    // (undocumented)
+    trace(...messages: unknown[]): void;
+    // (undocumented)
+    get transports(): Transport[];
+    set transports(value: Transport[]);
+    useLogger<T>(prefix: string, callback: (logger: Logger) => T): T;
+    // (undocumented)
+    useLogger<T>(options: Partial<LoggerOptions>, callback: (logger: Logger) => T): T;
+    // (undocumented)
+    warn(...messages: unknown[]): void;
+    write(logLevel: LogLevel | LogLevelNumeric, ...args: unknown[]): void;
+}
+
+// @public
+const logger: Logger;
+export default logger;
+export { logger }
+
+// @public
+export interface LoggerOptions {
+    consistentLogLevelWidth?: boolean;
+    enableColor?: boolean;
+    logLevel: LogLevel | LogLevelNumeric;
+    parent?: Logger;
+    prefix: string | undefined;
+    printLogLevel?: boolean;
+    printTimestamp?: boolean;
+    timestampFormat?: string;
+    transports: Transport[];
+}
+
+// @public
+export type LogLevel = 'off' | 'error' | 'warn' | 'log' | 'info' | 'debug' | 'trace';
+
+// Warning: (ae-internal-missing-underscore) The name "LogLevelColor" should be prefixed with an underscore because the declaration is marked as @internal
+//
+// @internal
+export const LogLevelColor: Record<string, ChalkFunction>;
+
+// @public
+export enum LogLevelNumeric {
+    // (undocumented)
+    debug = 5,
+    // (undocumented)
+    error = 1,
+    // (undocumented)
+    info = 4,
+    // (undocumented)
+    log = 3,
+    // (undocumented)
+    off = 0,
+    // (undocumented)
+    trace = 6,
+    // (undocumented)
+    warn = 2
+}
+
+// @public
+export const LogLevelPriority: Record<string, number>;
+
+// @public
+export interface LogMessage {
+    args: unknown[];
+    argsText: string;
+    date: Date;
+    logger: Logger;
+    logLevel: LogLevel;
+    prefixes: string[];
+    timestamp: string;
+}
+
+// @public
+export type MessageHandler = (message: LogMessage) => void;
+
+// @public
+export class QueuedTransport {
+    constructor(
+    writer?: MessageHandler);
+    // (undocumented)
+    pipe(message: LogMessage): void;
+    // (undocumented)
+    setWriter(writer: MessageHandler | undefined): void;
+}
+
+// @public
+export interface Transport {
+    destroy?(): void;
+    pipe(message: LogMessage): void;
+}
+
+// (No @packageDocumentation comment for this package)
+
+```