@skillsmith/core 0.1.0

package/dist/src/telemetry/tracer.js

@@ -0,0 +1,391 @@
+/**
+ * SMI-739: OpenTelemetry Tracer Setup
+ * SMI-755: Graceful fallback when OpenTelemetry unavailable
+ *
+ * Provides distributed tracing for Skillsmith operations:
+ * - MCP tool calls
+ * - Database queries
+ * - Cache operations
+ * - External API calls
+ *
+ * Configuration:
+ * - OTEL_EXPORTER_OTLP_ENDPOINT: OTLP endpoint for trace export
+ * - OTEL_SERVICE_NAME: Service name (default: skillsmith)
+ * - SKILLSMITH_TELEMETRY_ENABLED: Master switch for all telemetry (default: auto)
+ * - SKILLSMITH_TRACING_ENABLED: Enable/disable tracing (default: true if endpoint set)
+ *
+ * Graceful Fallback:
+ * - If OpenTelemetry packages are not installed, uses NoOp implementations
+ * - Logs warning on fallback (unless SKILLSMITH_TELEMETRY_ENABLED=false)
+ * - All tracing APIs remain functional (just don't record)
+ */
+// Lazy import to avoid loading OTEL if not needed
+// SMI-755: Use 'unknown' types to avoid compile-time dependency on OTEL packages
+let api = null;
+let sdk = null;
+let resources = null;
+let semanticConventions = null;
+function getApi() {
+    return api;
+}
+function getSdk() {
+    return sdk;
+}
+function getResources() {
+    return resources;
+}
+function getSemanticConventions() {
+    return semanticConventions;
+}
+/** Whether OpenTelemetry packages are available */
+let otelAvailable = null;
+/**
+ * Dynamic import helper that bypasses TypeScript type checking (SMI-755)
+ * This allows the code to compile even when @opentelemetry packages aren't installed
+ */
+async function dynamicImport(moduleName) {
+    try {
+        // Use Function constructor to bypass TypeScript's static analysis
+        const importFn = new Function('m', 'return import(m)');
+        return await importFn(moduleName);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if OpenTelemetry is available (SMI-755)
+ */
+async function checkOTelAvailability() {
+    if (otelAvailable !== null)
+        return otelAvailable;
+    const result = await dynamicImport('@opentelemetry/api');
+    otelAvailable = result !== null;
+    return otelAvailable;
+}
+/**
+ * No-op span wrapper for when tracing is disabled
+ */
+class NoOpSpanWrapper {
+    setAttributes(_attributes) { }
+    setStatus(_code, _message) { }
+    recordException(_error) { }
+    addEvent(_name, _attributes) { }
+    end() { }
+    getSpan() {
+        return null;
+    }
+}
+/**
+ * Active span wrapper with real OTEL span
+ */
+class ActiveSpanWrapper {
+    span;
+    constructor(span) {
+        this.span = span;
+    }
+    setAttributes(attributes) {
+        // Filter out undefined values
+        const filtered = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined) {
+                filtered[key] = value;
+            }
+        }
+        this.span.setAttributes(filtered);
+    }
+    setStatus(code, message) {
+        const statusCode = code === 'ok' ? 1 : 2; // SpanStatusCode.OK = 1, ERROR = 2
+        this.span.setStatus({ code: statusCode, message });
+    }
+    recordException(error) {
+        this.span.recordException(error);
+    }
+    addEvent(name, attributes) {
+        // Filter out undefined values
+        const filtered = {};
+        if (attributes) {
+            for (const [key, value] of Object.entries(attributes)) {
+                if (value !== undefined) {
+                    filtered[key] = value;
+                }
+            }
+        }
+        this.span.addEvent(name, filtered);
+    }
+    end() {
+        this.span.end();
+    }
+    getSpan() {
+        return this.span;
+    }
+}
+/**
+ * Skillsmith Tracer - Wrapper for OpenTelemetry tracing
+ */
+export class SkillsmithTracer {
+    tracer = null;
+    initialized = false;
+    enabled = false;
+    config;
+    sdkInstance = null;
+    constructor(config = {}) {
+        this.config = {
+            serviceName: config.serviceName ?? process.env.OTEL_SERVICE_NAME ?? 'skillsmith',
+            endpoint: config.endpoint ?? process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? '',
+            autoInstrument: config.autoInstrument ?? true,
+            consoleExport: config.consoleExport ?? false,
+            sampleRate: config.sampleRate ?? 1.0,
+        };
+        // SMI-755: Check master telemetry switch first
+        const telemetryDisabled = process.env.SKILLSMITH_TELEMETRY_ENABLED === 'false';
+        if (telemetryDisabled) {
+            this.enabled = false;
+            return;
+        }
+        // Check if tracing should be enabled
+        const explicitlyEnabled = process.env.SKILLSMITH_TRACING_ENABLED === 'true';
+        const explicitlyDisabled = process.env.SKILLSMITH_TRACING_ENABLED === 'false';
+        if (explicitlyDisabled) {
+            this.enabled = false;
+        }
+        else if (explicitlyEnabled || this.config.endpoint || this.config.consoleExport) {
+            this.enabled = true;
+        }
+    }
+    /**
+     * Initialize the tracer
+     * Must be called before creating spans
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        if (!this.enabled) {
+            this.initialized = true;
+            return;
+        }
+        // SMI-755: Check if OpenTelemetry is available before attempting to load
+        const isAvailable = await checkOTelAvailability();
+        if (!isAvailable) {
+            console.warn('[Skillsmith Telemetry] OpenTelemetry packages not installed. ' +
+                'Tracing disabled. Install @opentelemetry/api and related packages to enable.');
+            this.enabled = false;
+            this.initialized = true;
+            return;
+        }
+        try {
+            // SMI-755: Lazy load OTEL modules with error handling
+            // Use dynamicImport to bypass TypeScript type checking
+            api = await dynamicImport('@opentelemetry/api');
+            sdk = await dynamicImport('@opentelemetry/sdk-node');
+            resources = await dynamicImport('@opentelemetry/resources');
+            semanticConventions = await dynamicImport('@opentelemetry/semantic-conventions');
+            // If any core module failed to load, disable tracing
+            if (!api || !sdk || !resources || !semanticConventions) {
+                console.warn('[Skillsmith Telemetry] Some OpenTelemetry packages missing. Tracing disabled.');
+                this.enabled = false;
+                this.initialized = true;
+                return;
+            }
+            // Get typed accessors
+            const otelApi = getApi();
+            const otelSdk = getSdk();
+            const otelResources = getResources();
+            const otelSemConv = getSemanticConventions();
+            if (!otelApi || !otelSdk || !otelResources || !otelSemConv) {
+                this.enabled = false;
+                this.initialized = true;
+                return;
+            }
+            // Build SDK configuration
+            const sdkConfig = {};
+            // Create resource with service info
+            const Resource = otelResources.Resource;
+            sdkConfig.resource = new Resource({
+                [otelSemConv['ATTR_SERVICE_NAME'] ?? 'service.name']: this.config.serviceName,
+                [otelSemConv['ATTR_SERVICE_VERSION'] ?? 'service.version']: '0.1.0',
+            });
+            // Add auto-instrumentation if enabled
+            if (this.config.autoInstrument) {
+                try {
+                    const autoInst = (await dynamicImport('@opentelemetry/auto-instrumentations-node'));
+                    if (autoInst?.getNodeAutoInstrumentations) {
+                        sdkConfig.instrumentations = [
+                            autoInst.getNodeAutoInstrumentations({
+                                // Customize instrumentations
+                                '@opentelemetry/instrumentation-fs': { enabled: false },
+                                '@opentelemetry/instrumentation-dns': { enabled: false },
+                                '@opentelemetry/instrumentation-net': { enabled: false },
+                            }),
+                        ];
+                    }
+                }
+                catch {
+                    // Auto-instrumentation optional, continue without it
+                }
+            }
+            // Initialize SDK
+            const NodeSDK = otelSdk.NodeSDK;
+            this.sdkInstance = new NodeSDK(sdkConfig);
+            await this.sdkInstance.start();
+            // Get tracer
+            this.tracer = otelApi.trace.getTracer(this.config.serviceName, '0.1.0');
+            this.initialized = true;
+        }
+        catch (error) {
+            // SMI-755: Graceful fallback - disable tracing on error
+            console.warn('[Skillsmith Telemetry] Failed to initialize OpenTelemetry tracing:', error);
+            this.enabled = false;
+            this.initialized = true;
+        }
+    }
+    /**
+     * Check if tracing is enabled
+     */
+    isEnabled() {
+        return this.enabled && this.initialized;
+    }
+    /**
+     * Start a new span
+     *
+     * @param name - Span name (e.g., 'mcp.tool.search', 'db.query')
+     * @param options - Span options
+     * @returns SpanWrapper for manipulating the span
+     */
+    startSpan(name, options) {
+        if (!this.isEnabled() || !this.tracer) {
+            return new NoOpSpanWrapper();
+        }
+        const span = this.tracer.startSpan(name, options);
+        return new ActiveSpanWrapper(span);
+    }
+    /**
+     * Execute a function within a span context
+     *
+     * @param name - Span name
+     * @param fn - Function to execute
+     * @param options - Span options
+     * @returns Result of the function
+     */
+    async withSpan(name, fn, options) {
+        const spanWrapper = this.startSpan(name, options);
+        try {
+            const result = await fn(spanWrapper);
+            spanWrapper.setStatus('ok');
+            return result;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                spanWrapper.recordException(error);
+            }
+            spanWrapper.setStatus('error', error instanceof Error ? error.message : 'Unknown error');
+            throw error;
+        }
+        finally {
+            spanWrapper.end();
+        }
+    }
+    /**
+     * Execute a synchronous function within a span context
+     */
+    withSpanSync(name, fn, options) {
+        const spanWrapper = this.startSpan(name, options);
+        try {
+            const result = fn(spanWrapper);
+            spanWrapper.setStatus('ok');
+            return result;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                spanWrapper.recordException(error);
+            }
+            spanWrapper.setStatus('error', error instanceof Error ? error.message : 'Unknown error');
+            throw error;
+        }
+        finally {
+            spanWrapper.end();
+        }
+    }
+    /**
+     * Get the current active span (if any)
+     */
+    getCurrentSpan() {
+        const otelApi = getApi();
+        if (!otelApi) {
+            return new NoOpSpanWrapper();
+        }
+        const span = otelApi.trace.getActiveSpan();
+        if (!span) {
+            return new NoOpSpanWrapper();
+        }
+        return new ActiveSpanWrapper(span);
+    }
+    /**
+     * Shutdown the tracer and flush pending spans
+     */
+    async shutdown() {
+        if (this.sdkInstance) {
+            await this.sdkInstance.shutdown();
+            this.sdkInstance = null;
+        }
+        this.tracer = null;
+        this.initialized = false;
+    }
+}
+// Default tracer instance
+let defaultTracer = null;
+/**
+ * Get the default tracer instance
+ */
+export function getTracer() {
+    if (!defaultTracer) {
+        defaultTracer = new SkillsmithTracer();
+    }
+    return defaultTracer;
+}
+/**
+ * Initialize the default tracer
+ * Should be called at application startup
+ */
+export async function initializeTracing(config) {
+    if (defaultTracer) {
+        await defaultTracer.shutdown();
+    }
+    defaultTracer = new SkillsmithTracer(config);
+    await defaultTracer.initialize();
+    return defaultTracer;
+}
+/**
+ * Shutdown the default tracer
+ * Should be called at application shutdown
+ */
+export async function shutdownTracing() {
+    if (defaultTracer) {
+        await defaultTracer.shutdown();
+        defaultTracer = null;
+    }
+}
+/**
+ * Decorator for tracing async methods
+ */
+export function traced(spanName) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        if (!originalMethod)
+            return descriptor;
+        descriptor.value = async function (...args) {
+            const tracer = getTracer();
+            const name = spanName ?? `${target.constructor.name}.${propertyKey}`;
+            const boundMethod = originalMethod.bind(this);
+            return tracer.withSpan(name, async (span) => {
+                span.setAttributes({
+                    'code.function': propertyKey,
+                    'code.namespace': target.constructor.name,
+                });
+                return boundMethod(...args);
+            });
+        };
+        return descriptor;
+    };
+}
+//# sourceMappingURL=tracer.js.map

package/dist/src/telemetry/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../../src/telemetry/tracer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAgCH,kDAAkD;AAClD,iFAAiF;AACjF,IAAI,GAAG,GAAY,IAAI,CAAA;AACvB,IAAI,GAAG,GAAY,IAAI,CAAA;AACvB,IAAI,SAAS,GAAY,IAAI,CAAA;AAC7B,IAAI,mBAAmB,GAAY,IAAI,CAAA;AAqBvC,SAAS,MAAM;IACb,OAAO,GAAqB,CAAA;AAC9B,CAAC;AAED,SAAS,MAAM;IACb,OAAO,GAAsC,CAAA;AAC/C,CAAC;AAED,SAAS,YAAY;IACnB,OAAO,SAA8C,CAAA;AACvD,CAAC;AAED,SAAS,sBAAsB;IAC7B,OAAO,mBAAoD,CAAA;AAC7D,CAAC;AAED,mDAAmD;AACnD,IAAI,aAAa,GAAmB,IAAI,CAAA;AAExC;;;GAGG;AACH,KAAK,UAAU,aAAa,CAAC,UAAkB;IAC7C,IAAI,CAAC;QACH,kEAAkE;QAClE,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,GAAG,EAAE,kBAAkB,CAAoC,CAAA;QACzF,OAAO,MAAM,QAAQ,CAAC,UAAU,CAAC,CAAA;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,qBAAqB;IAClC,IAAI,aAAa,KAAK,IAAI;QAAE,OAAO,aAAa,CAAA;IAEhD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,oBAAoB,CAAC,CAAA;IACxD,aAAa,GAAG,MAAM,KAAK,IAAI,CAAA;IAC/B,OAAO,aAAa,CAAA;AACtB,CAAC;AA2CD;;GAEG;AACH,MAAM,eAAe;IACnB,aAAa,CAAC,WAA2B,IAAS,CAAC;IACnD,SAAS,CAAC,KAAqB,EAAE,QAAiB,IAAS,CAAC;IAC5D,eAAe,CAAC,MAAa,IAAS,CAAC;IACvC,QAAQ,CAAC,KAAa,EAAE,WAA4B,IAAS,CAAC;IAC9D,GAAG,KAAU,CAAC;IACd,OAAO;QACL,OAAO,IAAI,CAAA;IACb,CAAC;CACF;AAED;;GAEG;AACH,MAAM,iBAAiB;IACD;IAApB,YAAoB,IAAU;QAAV,SAAI,GAAJ,IAAI,CAAM;IAAG,CAAC;IAElC,aAAa,CAAC,UAA0B;QACtC,8BAA8B;QAC9B,MAAM,QAAQ,GAAgF,EAAE,CAAA;QAChG,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;YACtD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;YACvB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAA;IACnC,CAAC;IAED,SAAS,CAAC,IAAoB,EAAE,OAAgB;QAC9C,MAAM,UAAU,GAAmB,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA,CAAC,mCAAmC;QAC5F,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,CAAA;IACpD,CAAC;IAED,eAAe,CAAC,KAAY;QAC1B,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;IAClC,CAAC;IAED,QAAQ,CAAC,IAAY,EAAE,UAA2B;QAChD,8BAA8B;QAC9B,MAAM,QAAQ,GAAgF,EAAE,CAAA;QAChG,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;gBACtD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,QAAQ,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;gBACvB,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IACpC,CAAC;IAED,GAAG;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAA;IACjB,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAA;IAClB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,gBAAgB;IACnB,MAAM,GAAkB,IAAI,CAAA;IAC5B,WAAW,GAAG,KAAK,CAAA;IACnB,OAAO,GAAG,KAAK,CAAA;IACf,MAAM,CAAwB;IAC9B,WAAW,GAAiE,IAAI,CAAA;IAExF,YAAY,SAAuB,EAAE;QACnC,IAAI,CAAC,MAAM,GAAG;YACZ,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,YAAY;YAChF,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,OAAO,CAAC,GAAG,CAAC,2BAA2B,IAAI,EAAE;YAC1E,cAAc,EAAE,MAAM,CAAC,cAAc,IAAI,IAAI;YAC7C,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,KAAK;YAC5C,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,GAAG;SACrC,CAAA;QAED,+CAA+C;QAC/C,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,4BAA4B,KAAK,OAAO,CAAA;QAC9E,IAAI,iBAAiB,EAAE,CAAC;YACtB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;YACpB,OAAM;QACR,CAAC;QAED,qCAAqC;QACrC,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,KAAK,MAAM,CAAA;QAC3E,MAAM,kBAAkB,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,KAAK,OAAO,CAAA;QAE7E,IAAI,kBAAkB,EAAE,CAAC;YACvB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;QACtB,CAAC;aAAM,IAAI,iBAAiB,IAAI,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;YAClF,IAAI,CAAC,OAAO,GAAG,IAAI,CAAA;QACrB,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,WAAW;YAAE,OAAM;QAC5B,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;YACvB,OAAM;QACR,CAAC;QAED,yEAAyE;QACzE,MAAM,WAAW,GAAG,MAAM,qBAAqB,EAAE,CAAA;QACjD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,OAAO,CAAC,IAAI,CACV,+DAA+D;gBAC7D,8EAA8E,CACjF,CAAA;YACD,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;YACpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;YACvB,OAAM;QACR,CAAC;QAED,IAAI,CAAC;YACH,sDAAsD;YACtD,uDAAuD;YACvD,GAAG,GAAG,MAAM,aAAa,CAAC,oBAAoB,CAAC,CAAA;YAC/C,GAAG,GAAG,MAAM,aAAa,CAAC,yBAAyB,CAAC,CAAA;YACpD,SAAS,GAAG,MAAM,aAAa,CAAC,0BAA0B,CAAC,CAAA;YAC3D,mBAAmB,GAAG,MAAM,aAAa,CAAC,qCAAqC,CAAC,CAAA;YAEhF,qDAAqD;YACrD,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,mBAAmB,EAAE,CAAC;gBACvD,OAAO,CAAC,IAAI,CACV,+EAA+E,CAChF,CAAA;gBACD,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;gBACpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;gBACvB,OAAM;YACR,CAAC;YAED,sBAAsB;YACtB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAA;YACxB,MAAM,OAAO,GAAG,MAAM,EAAE,CAAA;YACxB,MAAM,aAAa,GAAG,YAAY,EAAE,CAAA;YACpC,MAAM,WAAW,GAAG,sBAAsB,EAAE,CAAA;YAE5C,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,IAAI,CAAC,aAAa,IAAI,CAAC,WAAW,EAAE,CAAC;gBAC3D,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;gBACpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;gBACvB,OAAM;YACR,CAAC;YAED,0BAA0B;YAC1B,MAAM,SAAS,GAA4B,EAAE,CAAA;YAE7C,oCAAoC;YACpC,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAA;YACvC,SAAS,CAAC,QAAQ,GAAG,IAAI,QAAQ,CAAC;gBAChC,CAAC,WAAW,CAAC,mBAAmB,CAAC,IAAI,cAAc,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW;gBAC7E,CAAC,WAAW,CAAC,sBAAsB,CAAC,IAAI,iBAAiB,CAAC,EAAE,OAAO;aACpE,CAAC,CAAA;YAEF,sCAAsC;YACtC,IAAI,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;gBAC/B,IAAI,CAAC;oBACH,MAAM,QAAQ,GAAG,CAAC,MAAM,aAAa,CAAC,2CAA2C,CAAC,CAE1E,CAAA;oBACR,IAAI,QAAQ,EAAE,2BAA2B,EAAE,CAAC;wBAC1C,SAAS,CAAC,gBAAgB,GAAG;4BAC3B,QAAQ,CAAC,2BAA2B,CAAC;gCACnC,6BAA6B;gCAC7B,mCAAmC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;gCACvD,oCAAoC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;gCACxD,oCAAoC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE;6BACzD,CAAC;yBACH,CAAA;oBACH,CAAC;gBACH,CAAC;gBAAC,MAAM,CAAC;oBACP,qDAAqD;gBACvD,CAAC;YACH,CAAC;YAED,iBAAiB;YACjB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;YAC/B,IAAI,CAAC,WAAW,GAAG,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;YACzC,MAAM,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;YAE9B,aAAa;YACb,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAA;YACvE,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACzB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,wDAAwD;YACxD,OAAO,CAAC,IAAI,CAAC,oEAAoE,EAAE,KAAK,CAAC,CAAA;YACzF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAA;YACpB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACzB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,CAAA;IACzC,CAAC;IAED;;;;;;OAMG;IACH,SAAS,CAAC,IAAY,EAAE,OAAqB;QAC3C,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACtC,OAAO,IAAI,eAAe,EAAE,CAAA;QAC9B,CAAC;QAED,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QACjD,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CACZ,IAAY,EACZ,EAAqC,EACrC,OAAqB;QAErB,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAEjD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,WAAW,CAAC,CAAA;YACpC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YAC3B,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,WAAW,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;YACpC,CAAC;YACD,WAAW,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAA;YACxF,MAAM,KAAK,CAAA;QACb,CAAC;gBAAS,CAAC;YACT,WAAW,CAAC,GAAG,EAAE,CAAA;QACnB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,YAAY,CAAI,IAAY,EAAE,EAA4B,EAAE,OAAqB;QAC/E,MAAM,WAAW,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;QAEjD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,EAAE,CAAC,WAAW,CAAC,CAAA;YAC9B,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,CAAA;YAC3B,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;gBAC3B,WAAW,CAAC,eAAe,CAAC,KAAK,CAAC,CAAA;YACpC,CAAC;YACD,WAAW,CAAC,SAAS,CAAC,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAA;YACxF,MAAM,KAAK,CAAA;QACb,CAAC;gBAAS,CAAC;YACT,WAAW,CAAC,GAAG,EAAE,CAAA;QACnB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,MAAM,OAAO,GAAG,MAAM,EAAE,CAAA;QACxB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,IAAI,eAAe,EAAE,CAAA;QAC9B,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,EAAE,CAAA;QAC1C,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,OAAO,IAAI,eAAe,EAAE,CAAA;QAC9B,CAAC;QACD,OAAO,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,QAAQ;QACZ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,CAAA;YACjC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAA;QACzB,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;QAClB,IAAI,CAAC,WAAW,GAAG,KAAK,CAAA;IAC1B,CAAC;CACF;AAED,0BAA0B;AAC1B,IAAI,aAAa,GAA4B,IAAI,CAAA;AAEjD;;GAEG;AACH,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,aAAa,GAAG,IAAI,gBAAgB,EAAE,CAAA;IACxC,CAAC;IACD,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,MAAqB;IAC3D,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,aAAa,CAAC,QAAQ,EAAE,CAAA;IAChC,CAAC;IACD,aAAa,GAAG,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAA;IAC5C,MAAM,aAAa,CAAC,UAAU,EAAE,CAAA;IAChC,OAAO,aAAa,CAAA;AACtB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,aAAa,CAAC,QAAQ,EAAE,CAAA;QAC9B,aAAa,GAAG,IAAI,CAAA;IACtB,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,MAAM,CAAC,QAAiB;IACtC,OAAO,UACL,MAAe,EACf,WAAmB,EACnB,UAAsC;QAEtC,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAA;QACvC,IAAI,CAAC,cAAc;YAAE,OAAO,UAAU,CAAA;QAEtC,UAAU,CAAC,KAAK,GAAG,KAAK,WAA0B,GAAG,IAAe;YAClE,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;YAC1B,MAAM,IAAI,GAAG,QAAQ,IAAI,GAAI,MAAiB,CAAC,WAAW,CAAC,IAAI,IAAI,WAAW,EAAE,CAAA;YAChF,MAAM,WAAW,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;YAE7C,OAAO,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;gBAC1C,IAAI,CAAC,aAAa,CAAC;oBACjB,eAAe,EAAE,WAAW;oBAC5B,gBAAgB,EAAG,MAAiB,CAAC,WAAW,CAAC,IAAI;iBACtD,CAAC,CAAA;gBACF,OAAO,WAAW,CAAC,GAAG,IAAI,CAAC,CAAA;YAC7B,CAAC,CAAC,CAAA;QACJ,CAAM,CAAA;QAEN,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;AACH,CAAC"}

package/dist/src/triggers/ContextScorer.d.ts

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview Context Scoring System for ranking skill suggestion relevance
+ * @module @skillsmith/core/triggers/ContextScorer
+ * @see Phase 4: Trigger System Architecture
+ *
+ * Scores the relevance of skill suggestions based on:
+ * - Number and type of triggers fired
+ * - Confidence levels of triggers
+ * - Recency of trigger events
+ * - User feedback history
+ *
+ * @example
+ * const scorer = new ContextScorer();
+ * const score = scorer.scoreContext(triggers, codebaseContext);
+ * if (score.score >= 0.6) {
+ *   // High relevance - suggest skills
+ * }
+ */
+import type { DetectedTrigger } from './TriggerDetector.js';
+import type { CodebaseContext } from '../analysis/CodebaseAnalyzer.js';
+/**
+ * Context score result
+ */
+export interface ContextScore {
+    /** Overall relevance score (0-1) */
+    score: number;
+    /** Confidence in the suggestion (0-1) */
+    confidence: number;
+    /** Which triggers contributed to the score */
+    triggers: string[];
+    /** Human-readable explanation */
+    reason: string;
+    /** Recommended skill categories */
+    recommendedCategories: string[];
+}
+/**
+ * Weights for different trigger types in context scoring
+ */
+export interface ContextScoringWeights {
+    /** Weight for file pattern triggers (default: 0.4) */
+    fileWeight: number;
+    /** Weight for command triggers (default: 0.3) */
+    commandWeight: number;
+    /** Weight for error triggers (default: 0.2) */
+    errorWeight: number;
+    /** Weight for project structure triggers (default: 0.3) */
+    projectWeight: number;
+}
+/**
+ * Options for context scoring
+ */
+export interface ContextScorerOptions {
+    /** Custom weights for trigger types */
+    weights?: Partial<ContextScoringWeights>;
+    /** Boost score for multiple triggers (default: true) */
+    multiTriggerBoost?: boolean;
+    /** Boost multiplier for multiple triggers (default: 1.2) */
+    multiTriggerMultiplier?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * ContextScorer - Scores skill suggestion relevance
+ *
+ * Uses a weighted scoring algorithm to determine how relevant
+ * skill suggestions would be based on detected triggers.
+ */
+export declare class ContextScorer {
+    private readonly weights;
+    private readonly multiTriggerBoost;
+    private readonly multiTriggerMultiplier;
+    private readonly debug;
+    constructor(options?: ContextScorerOptions);
+    /**
+     * Score the context based on detected triggers
+     *
+     * @param triggers - Detected triggers from TriggerDetector
+     * @param codebaseContext - Optional codebase analysis
+     * @returns Context score with recommendations
+     */
+    scoreContext(triggers: DetectedTrigger[], codebaseContext?: CodebaseContext | null): ContextScore;
+    /**
+     * Group triggers by type
+     */
+    private groupTriggersByType;
+    /**
+     * Calculate score for a specific trigger type
+     */
+    private calculateTypeScore;
+    /**
+     * Calculate confidence in the suggestion
+     */
+    private calculateConfidence;
+    /**
+     * Extract recommended skill categories from triggers
+     */
+    private extractRecommendedCategories;
+    /**
+     * Generate human-readable reason for the score
+     */
+    private generateReason;
+    /**
+     * Determine if score meets threshold for suggestion
+     *
+     * @param score - Context score result
+     * @returns Whether to suggest skills
+     */
+    shouldSuggest(score: ContextScore): boolean;
+    /**
+     * Get suggestion urgency level
+     *
+     * @param score - Context score result
+     * @returns Urgency level
+     */
+    getUrgency(score: ContextScore): 'high' | 'medium' | 'low';
+}
+export default ContextScorer;
+//# sourceMappingURL=ContextScorer.d.ts.map

package/dist/src/triggers/ContextScorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContextScorer.d.ts","sourceRoot":"","sources":["../../../src/triggers/ContextScorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAKtE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,mCAAmC;IACnC,qBAAqB,EAAE,MAAM,EAAE,CAAA;CAChC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAA;IAClB,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAA;IACrB,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAA;IACxC,wDAAwD;IACxD,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,4DAA4D;IAC5D,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAYD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,OAAO,GAAE,oBAAyB;IAkB9C;;;;;;OAMG;IACH,YAAY,CACV,QAAQ,EAAE,eAAe,EAAE,EAC3B,eAAe,CAAC,EAAE,eAAe,GAAG,IAAI,GACvC,YAAY;IA6Ff;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAoB3B;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAY1B;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAiB3B;;OAEG;IACH,OAAO,CAAC,4BAA4B;IAYpC;;OAEG;IACH,OAAO,CAAC,cAAc;IAkDtB;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO;IAe3C;;;;;OAKG;IACH,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK;CAS3D;AAED,eAAe,aAAa,CAAA"}