tessl/npm-autorest--common

AutoRest common utilities for logging, configuration merging, exceptions, and styling

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Logging System

Name: tessl/npm-autorest--common
Author: tessl

Comprehensive logging infrastructure providing multi-sink logging with processors, formatters, source enhancement, and progress tracking capabilities. Supports both synchronous and asynchronous logging patterns with configurable filtering and output formatting.

Capabilities

Core Logger Interface

Basic logger interface providing standard logging methods and diagnostic tracking.

interface IAutorestLogger {
  debug(message: string): void;
  verbose(message: string): void;
  info(message: string): void;
  fatal(message: string): void;
  trackError(error: AutorestError): void;
  trackWarning(error: AutorestWarning): void;
  log(log: LogInfo): void;
  startProgress(initialName?: string): ProgressTracker;
}

interface AutorestLogger extends IAutorestLogger {
  with(...processors: LoggerProcessor[]): AutorestLogger;
  diagnostics: AutorestDiagnostic[];
}

Logger Base Class

Abstract base class for AutoRest logger implementations providing common functionality.

abstract class AutorestLoggerBase<T> implements AutorestLogger {
  public diagnostics: AutorestDiagnostic[];
  constructor(options: AutorestLoggerBaseOptions<T>);
  debug(message: string): void;
  verbose(message: string): void;
  info(message: string): void;
  fatal(message: string): void;
  trackWarning(warning: AutorestWarning): void;
  trackError(error: AutorestError): void;
  startProgress(initialName?: string): ProgressTracker;
  protected emitLog(log: LogInfo): void;
  abstract with(...processors: LoggerProcessor[]): AutorestLogger;
  abstract trackDiagnostic(diagnostic: AutorestDiagnostic): void;
  abstract log(log: LogInfo): void;
}

interface AutorestLoggerBaseOptions<T> {
  processors?: T[];
  sinks: LoggerSink[];
}

Synchronous Logger

Synchronous logger implementation with processor support.

class AutorestSyncLogger extends AutorestLoggerBase<LoggerProcessor> {
  constructor(options: AutorestLoggerOptions);
  with(...processors: LoggerProcessor[]): AutorestSyncLogger;
  trackDiagnostic(diagnostic: AutorestDiagnostic): void;
  log(log: LogInfo): void;
  protected process(log: LogInfo): LogInfo | undefined;
}

interface AutorestLoggerOptions extends AutorestLoggerBaseOptions<LoggerProcessor> {}

Usage Example:

import { AutorestSyncLogger, ConsoleLoggerSink, FilterLogger } from "@autorest/common";

const logger = new AutorestSyncLogger({
  sinks: [new ConsoleLoggerSink({ format: "regular", color: true })],
  processors: [new FilterLogger({ level: "information" })]
});

logger.info("Processing started");
logger.trackError({ code: "E001", message: "Configuration error" });

// Add additional processors
const enhancedLogger = logger.with(new CustomProcessor());

Asynchronous Logger

Asynchronous logger implementation for handling async processing workflows.

class AutorestAsyncLogger extends AutorestLoggerBase<LoggerProcessor | LoggerAsyncProcessor> {
  constructor(options: AutorestAsyncLoggerOptions);
  with(...processors: Array<LoggerProcessor | LoggerAsyncProcessor>): AutorestAsyncLogger;
  log(log: LogInfo): void;
  trackDiagnostic(diagnostic: AutorestDiagnostic): void;
  protected process(log: LogInfo): Promise<LogInfo | undefined>;
}

interface AutorestAsyncLoggerOptions extends AutorestLoggerBaseOptions<LoggerProcessor | LoggerAsyncProcessor> {
  asyncSession: LoggingSession;
}

Logger Processors

Processors for filtering and transforming log messages.

Filter Logger Processor

Filters log messages based on level and suppression rules.

class FilterLogger implements LoggerProcessor {
  constructor(options: FilterLoggerOptions);
  process(log: LogInfo): LogInfo | undefined;
}

interface FilterLoggerOptions {
  level: LogLevel;
  suppressions?: LogSuppression[];
}

interface LogSuppression {
  code: string;
  from?: string[] | string;
  where?: string[] | string;
}

function shouldLogLevel(log: LogInfo, level: LogLevel): boolean;

Usage Example:

import { FilterLogger } from "@autorest/common";

const filter = new FilterLogger({
  level: "warning",
  suppressions: [
    { code: "W001", from: ["legacy-plugin"] },
    { code: "W002", where: ["src/deprecated/"] }
  ]
});

const logger = new AutorestSyncLogger({
  sinks: [new ConsoleLoggerSink()],
  processors: [filter]
});

Source Enhancement Processor

Enhances log messages with detailed source location information.

class AutorestLoggerSourceEnhancer implements LoggerAsyncProcessor {
  constructor(dataStore: DataStore);
  process(log: LogInfo): Promise<LogInfo | undefined>;
}

class LogSourceEnhancer {
  constructor(dataStore: DataStore);
  process(log: LogInfo): Promise<EnhancedLogInfo>;
}

Logger Sinks

Output destinations for log messages.

Console Logger Sink

Outputs log messages to console with configurable formatting.

class ConsoleLoggerSink implements LoggerSink {
  constructor(options?: ConsoleLoggerSinkOptions);
  log(log: LogInfo): void;
  startProgress(initialName?: string): ProgressTracker;
}

interface ConsoleLoggerSinkOptions {
  stream?: NodeJS.WritableStream;
  format?: "json" | "regular";
  color?: boolean;
  timestamp?: boolean;
  progressNoTTYOutput?: boolean;
}

class ConsoleLogger extends AutorestSyncLogger {
  constructor(options?: ConsoleLoggerSinkOptions);
}

Usage Examples:

import { ConsoleLoggerSink, ConsoleLogger } from "@autorest/common";

// Basic console sink
const sink = new ConsoleLoggerSink({
  format: "regular",
  color: true,
  timestamp: true
});

// Pre-configured console logger
const logger = new ConsoleLogger({
  format: "json",
  color: false
});

logger.info("Message with timestamp and no color");

Log Formatters

Formatters for converting log messages to different output formats.

interface LogFormatter {
  log(log: EnhancedLogInfo): string;
}

class PrettyLogFormatter implements LogFormatter {
  constructor(options?: FormatterOptions);
  log(log: EnhancedLogInfo): string;
}

class JsonLogFormatter implements LogFormatter {
  constructor(options: { timestamp?: boolean });
  log(log: EnhancedLogInfo): string;
}

function createLogFormatter(format: "json" | "regular" | undefined, options?: {}): LogFormatter;

interface FormatterOptions {
  color?: boolean;
  timestamp?: boolean;
}

Logging Session

Manages asynchronous logging message coordination.

class LoggingSession {
  registerLog(sendMessage: () => Promise<unknown>): void;
  waitForMessages(): Promise<void>;
}

Global Session:

const AutorestLoggingSession: LoggingSession;

Configuration

Configure logging for Azure libraries integration.

function configureLibrariesLogger(level: AzureLogLevel, log: (...args: unknown[]) => void): void;

// AzureLogLevel from @azure/logger dependency
type AzureLogLevel = "verbose" | "info" | "warning" | "error";

Core Types

type LogLevel = "debug" | "verbose" | "information" | "warning" | "error" | "fatal";

interface LogInfo {
  readonly level: LogLevel;
  readonly message: string;
  readonly code?: string;
  readonly source?: SourceLocation[];
  readonly details?: Error | unknown;
  readonly pluginName?: string;
  readonly extensionName?: string;
}

interface AutorestDiagnostic {
  level: Extract<LogLevel, "error" | "warning">;
  readonly code: string;
  readonly message: string;
  readonly source?: SourceLocation[];
  readonly details?: Error | unknown;
}

type AutorestError = Omit<AutorestDiagnostic, "level">;
type AutorestWarning = Omit<AutorestDiagnostic, "level">;

interface SourceLocation {
  readonly document: string;
  readonly position: Position | PathPosition;
}

interface EnhancedLogInfo extends Omit<LogInfo, "source"> {
  readonly source?: EnhancedSourceLocation[];
}

interface EnhancedSourceLocation {
  document: string;
  position: EnhancedPosition;
}

// Position types from @azure-tools/datastore dependency
type Position = {
  line: number;
  column: number;
};

type PathPosition = string | string[];

interface EnhancedPosition {
  line: number;
  column: number;
  path?: string[];
}

interface Progress {
  current: number;
  total: number;
  name?: string;
}

interface ProgressTracker {
  update(progress: Progress): void;
  stop(): void;
}

interface LoggerProcessor {
  process(log: LogInfo): LogInfo | undefined;
}

interface LoggerAsyncProcessor {
  process(log: LogInfo): Promise<LogInfo | undefined>;
}

interface LoggerSink {
  log(info: LogInfo): void;
  startProgress(initialName?: string): ProgressTracker;
}