@vibesdotdev/logging 0.0.1 → 1.0.0-rc.4

package/src/core/namespace.ts

@@ -1,195 +0,0 @@
-/**
- * Namespace Filtering
- *
- * Controls which log entries are emitted based on namespace patterns.
- */
-
-import { type LogLevel, LOG_LEVEL_ORDER } from '../schemas/entry.ts';
-
-const DEFAULT_LEVEL: LogLevel = 'info';
-const REGEX_SPECIAL_CHARS = /[\\^$+?.()|[\]{}]/g;
-
-/**
- * A compiled namespace selector.
- */
-export interface NamespaceSelector {
-	raw: string;
-	regex: RegExp;
-	isExclusion: boolean;
-}
-
-/**
- * Namespace selectors (includes and excludes).
- */
-export interface NamespaceSelectors {
-	includes: NamespaceSelector[];
-	excludes: NamespaceSelector[];
-}
-
-/**
- * Full namespace settings with level.
- */
-export interface NamespaceSettings extends NamespaceSelectors {
-	defaultLevel: LogLevel;
-}
-
-type EnvRecord = Record<string, string | undefined>;
-
-/**
- * Compile a glob pattern to regex.
- */
-function compilePattern(pattern: string): RegExp {
-	const escaped = pattern.replace(REGEX_SPECIAL_CHARS, '\\$&').replace(/\*/g, '.*');
-	return new RegExp(`^${escaped}$`);
-}
-
-/**
- * Parse a selector string into includes/excludes.
- * Format: "namespace1,namespace2,-excluded1,-excluded2"
- */
-function parseSelectors(raw: string): NamespaceSelectors {
-	const selectors: NamespaceSelectors = { includes: [], excludes: [] };
-
-	for (const token of raw.split(',').map((value) => value.trim())) {
-		if (!token) continue;
-
-		const isExclusion = token.startsWith('-');
-		const normalized = isExclusion ? token.slice(1) : token;
-		if (!normalized) continue;
-
-		const selector: NamespaceSelector = {
-			raw: normalized,
-			regex: compilePattern(normalized),
-			isExclusion
-		};
-
-		if (isExclusion) {
-			selectors.excludes.push(selector);
-		} else {
-			selectors.includes.push(selector);
-		}
-	}
-
-	return selectors;
-}
-
-/**
- * Normalize a level string to LogLevel.
- */
-function normalizeLevel(level?: string | null): LogLevel {
-	switch ((level || '').toLowerCase()) {
-		case 'debug':
-			return 'debug';
-		case 'warn':
-			return 'warn';
-		case 'error':
-			return 'error';
-		default:
-			return 'info';
-	}
-}
-
-/**
- * Parse namespace settings from input string.
- */
-export function parseNamespaceSettings({
-	input,
-	defaultLevel
-}: {
-	input?: string | null;
-	defaultLevel?: string | null;
-}): NamespaceSettings {
-	const selectors = input ? parseSelectors(input) : { includes: [], excludes: [] };
-	return {
-		...selectors,
-		defaultLevel: normalizeLevel(defaultLevel)
-	};
-}
-
-/**
- * Parse namespace settings from environment variables.
- */
-export function parseNamespaceSettingsFromEnv(env: EnvRecord): NamespaceSettings {
-	const logSelectors = env.VIBES_LOG ?? env.vibes_log ?? undefined;
-	const level =
-		env.VIBES_LOG_LEVEL ?? env.vibes_log_level ?? env.LOG_LEVEL ?? env.log_level ?? undefined;
-
-	return parseNamespaceSettings({
-		input: logSelectors,
-		defaultLevel: level
-	});
-}
-
-/**
- * Check if a namespace matches a selector.
- */
-export function matchesSelector(namespace: string, selector: NamespaceSelector): boolean {
-	return selector.regex.test(namespace);
-}
-
-/**
- * Check if a namespace is included by settings.
- */
-export function isNamespaceIncluded(namespace: string, settings: NamespaceSelectors): boolean {
-	const included =
-		settings.includes.length === 0 ||
-		settings.includes.some((selector) => matchesSelector(namespace, selector));
-	if (!included) return false;
-	return !settings.excludes.some((selector) => matchesSelector(namespace, selector));
-}
-
-/**
- * Determine if a log entry should be emitted.
- */
-export function shouldLog({
-	namespace,
-	level,
-	settings
-}: {
-	namespace: string;
-	level: LogLevel;
-	settings: NamespaceSettings;
-}): boolean {
-	const defaultLevel = settings.defaultLevel ?? DEFAULT_LEVEL;
-	const levelIndex = LOG_LEVEL_ORDER[level];
-	const baselineIndex = LOG_LEVEL_ORDER[defaultLevel] ?? LOG_LEVEL_ORDER[DEFAULT_LEVEL];
-
-	if (levelIndex >= baselineIndex) {
-		return !settings.excludes.some((selector) => matchesSelector(namespace, selector));
-	}
-
-	return settings.includes.some((selector) => matchesSelector(namespace, selector));
-}
-
-/**
- * Default namespace settings.
- */
-export const defaultNamespaceSettings: NamespaceSettings = {
-	includes: [],
-	excludes: [],
-	defaultLevel: DEFAULT_LEVEL
-};
-
-/**
- * Global active namespace settings.
- * Updated from environment or explicit configuration.
- *
- * Initialization is lazy: defaults are used until explicitly configured
- * via updateNamespaceSettings(). The logging-fs plugin initializes
- * settings from the host environment at startup automatically.
- */
-let activeNamespaceSettings: NamespaceSettings = defaultNamespaceSettings;
-
-/**
- * Update the active namespace settings.
- */
-export function updateNamespaceSettings(settings: NamespaceSettings): void {
-	activeNamespaceSettings = settings;
-}
-
-/**
- * Get the current active namespace settings.
- */
-export function getNamespaceSettings(): NamespaceSettings {
-	return activeNamespaceSettings;
-}

package/src/core/parsing.ts

@@ -1,21 +0,0 @@
-export function parseSize(size: string | undefined): number {
-	if (!size) return 10 * 1024 * 1024;
-	const units: Record<string, number> = { B: 1, KB: 1024, MB: 1024 ** 2, GB: 1024 ** 3 };
-	const match = size.match(/^(\d+(?:\.\d+)?)\s*(B|KB|MB|GB)$/i);
-	if (!match) return 10 * 1024 * 1024;
-	return Math.floor(parseFloat(match[1]) * (units[match[2].toUpperCase()] ?? 1));
-}
-
-export function parseDuration(duration: string | undefined): number {
-	if (!duration) return 7 * 24 * 60 * 60 * 1000;
-	const units: Record<string, number> = {
-		s: 1000,
-		m: 60 * 1000,
-		h: 60 * 60 * 1000,
-		d: 24 * 60 * 60 * 1000,
-		w: 7 * 24 * 60 * 60 * 1000
-	};
-	const match = duration.match(/^(\d+)\s*(s|m|h|d|w)$/i);
-	if (!match) return 7 * 24 * 60 * 60 * 1000;
-	return parseInt(match[1], 10) * (units[match[2].toLowerCase()] ?? 1);
-}

package/src/core/types.ts

@@ -1,82 +0,0 @@
-/**
- * Core Logger Types
- *
- * Interfaces for logger instances and factories.
- */
-
-import type {
-	LogLevel,
-	LogContext,
-	LoggerChildOptions,
-	RequestLogContext,
-	JobLogContext,
-	PerformanceTracker,
-	PerformanceTrackerParams
-} from '../schemas/entry.ts';
-import type { SinkImplementation } from '../kinds/sink.ts';
-
-/**
- * Base logger interface.
- */
-export interface Logger {
-	debug(message: string, context?: unknown): void;
-	info(message: string, context?: unknown): void;
-	warn(message: string, context?: unknown): void;
-	error(message: string, context?: unknown): void;
-	child?(options: LoggerChildOptions): Logger;
-	namespace?: string;
-}
-
-/**
- * Extended runtime logger with context helpers.
- */
-export interface RuntimeLogger extends Logger {
-	/** Create a child logger with additional context */
-	child(options: LoggerChildOptions): RuntimeLogger;
-	/** Add arbitrary context to this logger */
-	withContext(context: LogContext): RuntimeLogger;
-	/** Add request-specific context */
-	withRequestContext(context: RequestLogContext): RuntimeLogger;
-	/** Add job-specific context */
-	withJobContext(context: JobLogContext): RuntimeLogger;
-	/** Create a performance tracker for timing operations */
-	performanceTracker(params: PerformanceTrackerParams): PerformanceTracker;
-	/** Logger namespace */
-	namespace: string;
-	/** Full namespace path (including parent namespaces) */
-	fullNamespace: string;
-}
-
-/**
- * Runtime type identifier.
- */
-export type Runtime = 'server' | 'cli' | 'worker' | 'browser' | 'mcp';
-
-/**
- * Options for creating a runtime logger.
- */
-export interface RuntimeLoggerOptions {
-	/** Base namespace (e.g., 'vibes', 'pm') */
-	namespace: string;
-	/** Runtime environment */
-	runtime?: Runtime;
-	/** Override default log level */
-	level?: LogLevel;
-	/** Static metadata added to all entries */
-	staticMetadata?: LogContext;
-	/** Custom sink IDs for runtime resolution */
-	sinks?: string[];
-	/** Direct sink implementations (bypasses runtime resolution) */
-	sinkImpls?: SinkImplementation[];
-}
-
-/**
- * Internal logger configuration.
- */
-export interface RuntimeLoggerConfig {
-	namespace: string;
-	fullNamespace: string;
-	runtime: Runtime;
-	staticMetadata: LogContext;
-	sinkIds: string[];
-}

package/src/docs/levels.docs.descriptor.ts

@@ -1,344 +0,0 @@
-import type { DocsTopicDescriptor } from '@vibesdotdev/docs';
-
-const descriptor: DocsTopicDescriptor = {
-	kind: 'docs/topic',
-	id: 'logging.levels',
-	title: 'Log Levels',
-	summary: 'Log levels (debug, info, warn, error) and filtering',
-	body: {
-		type: 'markdown',
-		sourceType: 'raw',
-		source: `---
-title: Log Levels
-summary: Log levels (debug, info, warn, error) and filtering
-tags: [logging, levels, debug, info, warn, error, filtering]
-parent: logging
-order: 1
-surfaces: [cli, web, in-app]
-hardware: [consumer, cloud]
----
-
-# Log Levels
-
-Log levels categorize log entries by severity. The logging system provides five standard levels with automatic filtering based on configuration.
-
-## Level Hierarchy
-
-\`\`\`
-trace < debug < info < warn < error
-\`\`\`
-
-Each level includes all levels above it. Setting level to \`warn\` logs \`warn\` and \`error\` only.
-
-## Level Definitions
-
-### Trace (0)
-
-Fine-grained debugging information:
-
-\`\`\`ts
-logger.trace('Entering function', { fn: 'processUser', userId: '123' });
-\`\`\`
-
-**Use for:**
-- Function entry/exit
-- Variable values during debugging
-- Detailed execution flow
-
-**Typical output:**
-\`\`\`
-[TRACE] [app:user] Entering function {"fn":"processUser","userId":"123"}
-\`\`\`
-
-### Debug (1)
-
-Debugging information for development:
-
-\`\`\`ts
-logger.debug('Database query executed', {
-  query: 'SELECT * FROM users',
-  duration: 45
-});
-\`\`\`
-
-**Use for:**
-- SQL queries
-- API requests
-- Configuration values
-- Performance metrics
-
-**Typical output:**
-\`\`\`
-[DEBUG] [app:db] Database query executed {"query":"SELECT * FROM users","duration":45}
-\`\`\`
-
-### Info (2)
-
-General informational messages:
-
-\`\`\`ts
-logger.info('Server started', {
-  port: 3000,
-  environment: 'development'
-});
-\`\`\`
-
-**Use for:**
-- Application lifecycle events
-- User actions (login, logout)
-- System state changes
-- Successful operations
-
-**Typical output:**
-\`\`\`
-[INFO] [app:server] Server started {"port":3000,"environment":"development"}
-\`\`\`
-
-### Warn (3)
-
-Warning conditions:
-
-\`\`\`ts
-logger.warn('High memory usage detected', {
-  usage: '85%',
-  threshold: '80%'
-});
-\`\`\`
-
-**Use for:**
-- Resource warnings
-- Deprecated API usage
-- Recoverable errors
-- Performance degradation
-
-**Typical output:**
-\`\`\`
-[WARN] [app:monitor] High memory usage detected {"usage":"85%","threshold":"80%"}
-\`\`\`
-
-### Error (4)
-
-Error conditions:
-
-\`\`\`ts
-logger.error('Database connection failed', {
-  error: error.message,
-  host: config.db.host
-});
-\`\`\`
-
-**Use for:**
-- Unhandled exceptions
-- Failed operations
-- System errors
-- External service failures
-
-**Typical output:**
-\`\`\`
-[ERROR] [app:db] Database connection failed {"error":"ECONNREFUSED","host":"localhost"}
-\`\`\`
-
-## Setting Log Level
-
-### Environment Variable
-
-\`\`\`bash
-# Set minimum level
-export LOG_LEVEL=debug
-
-# Levels: trace, debug, info, warn, error
-\`\`\`
-
-### Programmatic Configuration
-
-\`\`\`ts
-import { logger } from '@vibesdotdev/logging';
-
-logger.setLevel('debug');
-
-// Only debug, info, warn, error will be logged
-// trace will be filtered out
-\`\`\`
-
-### Config Manifest
-
-\`\`\`ts
-const loggingConfig = await runtime.query('config/manifest')
-  .filter(d => d.id === 'logging')
-  .resolve();
-
-const config = await loggingConfig.loadWithDefaults(context);
-
-console.log(config.level);  // 'info'
-\`\`\`
-
-## Level Filtering
-
-### Filter by Level
-
-\`\`\`ts
-logger.setLevel('warn');
-
-logger.trace('Will NOT be logged');  // filtered
-logger.debug('Will NOT be logged');  // filtered
-logger.info('Will NOT be logged');   // filtered
-logger.warn('Will be logged');       // ✓
-logger.error('Will be logged');      // ✓
-\`\`\`
-
-### Filter by Namespace
-
-\`\`\`ts
-import { createLogger } from '@vibesdotdev/logging';
-
-// Create logger with namespace
-const dbLogger = createLogger('app:db');
-const authLogger = createLogger('app:auth');
-
-dbLogger.setLevel('debug');
-authLogger.setLevel('error');
-
-dbLogger.debug('Query executed');    // logged
-authLogger.debug('Token validated');  // filtered
-\`\`\`
-
-### Filter by Context
-
-\`\`\`ts
-logger.debug('Debug message', {
-  context: {
-    userId: '123',
-    requestId: 'req-456'
-  }
-});
-
-// Output includes context
-// [DEBUG] [app] Debug message {"userId":"123","requestId":"req-456"}
-\`\`\`
-
-## Namespace Patterns
-
-### Namespace Hierarchy
-
-\`\`\`ts
-// Namespace structure
-app:server
-app:database
-app:auth
-app:api:users
-app:api:posts
-
-// Set level for namespace pattern
-logger.setLevel('app:api:*', 'debug');  // All API logs
-\`\`\`
-
-### Wildcard Patterns
-
-\`\`\`ts
-// Wildcard matching
-logger.setLevel('app:*', 'info');       // All app logs
-logger.setLevel('app:api:*', 'debug');  // All API logs
-logger.setLevel('*', 'warn');           // All logs
-\`\`\`
-
-## Level-Specific Methods
-
-### Convenience Methods
-
-\`\`\`ts
-logger.trace('Trace message');
-logger.debug('Debug message');
-logger.info('Info message');
-logger.warn('Warning message');
-logger.error('Error message');
-\`\`\`
-
-### Structured Logging
-
-\`\`\`ts
-logger.info('User logged in', {
-  userId: '123',
-  email: 'user@example.com',
-  timestamp: new Date().toISOString()
-});
-
-logger.error('Payment failed', {
-  userId: '123',
-  amount: 99.99,
-  error: 'Insufficient funds',
-  code: 'PAYMENT_FAILED'
-});
-\`\`\`
-
-## Conditional Logging
-
-### Level Guards
-
-\`\`\`ts
-if (logger.isLevelEnabled('debug')) {
-  // Expensive operation only if debug logging enabled
-  const debugData = computeExpensiveDebugData();
-  logger.debug('Debug info', debugData);
-}
-\`\`\`
-
-### Dynamic Level Changes
-
-\`\`\`ts
-// Temporarily increase verbosity
-const previousLevel = logger.getLevel();
-logger.setLevel('trace');
-
-// ... debug-heavy operation ...
-
-logger.setLevel(previousLevel);  // restore
-\`\`\`
-
-## Audit Logging
-
-Audit logs use special level handling:
-
-\`\`\`ts
-import { auditLogger } from '@vibesdotdev/logging';
-
-// Audit logs always logged regardless of level
-auditLogger.authentication({
-  userId: '123',
-  action: 'login',
-  success: true,
-  ipAddress: '192.168.1.1'
-});
-
-auditLogger.authorization({
-  userId: '123',
-  resource: 'users/456',
-  action: 'delete',
-  allowed: false
-});
-\`\`\`
-
-## Best Practices
-
-1. **Use appropriate levels** — Don't log everything as error
-2. **Include context** — Help debugging with relevant data
-3. **Avoid sensitive data** — Never log passwords, tokens, PII
-4. **Consistent namespaces** — Use hierarchical naming
-5. **Production level** — Typically 'info' or 'warn'
-6. **Development level** — Typically 'debug'
-
-:::card{title="See also"}
-- [\`logging.transports\`](logging.transports) — Transport layers
-- [\`logging.structured\`](logging.structured) — Structured logging
-- [\`config.environment\`](config.environment) — Environment configuration
-:::
-`
-	},
-	parent: 'logging',
-	order: 1,
-	tags: ['logging', 'levels', 'debug', 'info', 'warn', 'error', 'filtering'],
-	surfaces: ['cli', 'web', 'in-app'],
-	hardware: ['consumer', 'cloud'],
-	enabled: true
-};
-
-export default descriptor;