@opensearch-project/agent-health 0.3.0 → 0.5.2

package/lib/dist/lib/telemetry/opensearchExporter.js

@@ -0,0 +1,217 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { ExportResultCode } from '@opentelemetry/core';
+import { SpanKind, SpanStatusCode } from '@opentelemetry/api';
+import { Client } from '@opensearch-project/opensearch';
+/**
+ * Convert OTel HrTime [seconds, nanoseconds] to ISO date string
+ */
+function hrTimeToDate(hrTime) {
+    const ms = hrTime[0] * 1000 + hrTime[1] / 1_000_000;
+    return new Date(ms).toISOString();
+}
+/**
+ * Convert OTel HrTime to nanoseconds
+ */
+function hrTimeToNanos(hrTime) {
+    return hrTime[0] * 1_000_000_000 + hrTime[1];
+}
+/**
+ * Convert duration between two HrTimes to nanoseconds
+ */
+function durationNanos(start, end) {
+    return hrTimeToNanos(end) - hrTimeToNanos(start);
+}
+/**
+ * Map OTel SpanKind to OSIS string format
+ */
+function spanKindToString(kind) {
+    switch (kind) {
+        case SpanKind.INTERNAL: return 'SPAN_KIND_INTERNAL';
+        case SpanKind.SERVER: return 'SPAN_KIND_SERVER';
+        case SpanKind.CLIENT: return 'SPAN_KIND_CLIENT';
+        case SpanKind.PRODUCER: return 'SPAN_KIND_PRODUCER';
+        case SpanKind.CONSUMER: return 'SPAN_KIND_CONSUMER';
+        default: return 'SPAN_KIND_INTERNAL';
+    }
+}
+/**
+ * Map OTel SpanStatusCode to OSIS integer
+ */
+function statusCodeToInt(code) {
+    switch (code) {
+        case SpanStatusCode.UNSET: return 0;
+        case SpanStatusCode.OK: return 1;
+        case SpanStatusCode.ERROR: return 2;
+        default: return 0;
+    }
+}
+/**
+ * Convert a ReadableSpan to an OSIS-compatible OpenSearch document
+ */
+function spanToDocument(span) {
+    const doc = {
+        traceId: span.spanContext().traceId,
+        spanId: span.spanContext().spanId,
+        parentSpanId: (span.parentSpanContext?.spanId && span.parentSpanContext.spanId !== '0000000000000000')
+            ? span.parentSpanContext.spanId : '',
+        name: span.name,
+        kind: spanKindToString(span.kind),
+        startTime: hrTimeToDate(span.startTime),
+        endTime: hrTimeToDate(span.endTime),
+        durationInNanos: durationNanos(span.startTime, span.endTime),
+        status: {
+            code: statusCodeToInt(span.status.code),
+            message: span.status.message || '',
+        },
+        traceState: '',
+        droppedAttributesCount: span.droppedAttributesCount,
+        droppedEventsCount: span.droppedEventsCount,
+        droppedLinksCount: span.droppedLinksCount,
+    };
+    // Span attributes: nested object keyed by literal dotted OTel names
+    // (Data Prepper trace-analytics-plain-raw / OTEL-faithful schema).
+    const spanAttributes = {};
+    for (const [key, value] of Object.entries(span.attributes)) {
+        if (value !== undefined) {
+            spanAttributes[key] = value;
+        }
+    }
+    doc.attributes = spanAttributes;
+    // Resource attributes: nested resource.attributes object, literal dotted keys.
+    const resource = span.resource;
+    const resourceAttributes = {};
+    if (resource?.attributes) {
+        for (const [key, value] of Object.entries(resource.attributes)) {
+            if (value !== undefined) {
+                resourceAttributes[key] = value;
+            }
+        }
+    }
+    doc.resource = { attributes: resourceAttributes };
+    // Set serviceName from resource
+    const serviceName = resource?.attributes?.['service.name'] || 'unknown';
+    doc.serviceName = serviceName;
+    // Instrumentation scope — nested object (runtime property is instrumentationScope).
+    const scope = span.instrumentationScope ?? span.instrumentationLibrary ?? {};
+    doc.instrumentationScope = {
+        name: scope.name || '',
+        ...(scope.version ? { version: scope.version } : {}),
+    };
+    // Events (nested array; attribute keys are literal dotted OTel names)
+    if (span.events.length > 0) {
+        doc.events = span.events.map(event => {
+            const eventDoc = {
+                name: event.name,
+                time: hrTimeToDate(event.time),
+                droppedAttributesCount: event.droppedAttributesCount || 0,
+            };
+            if (event.attributes) {
+                const attrs = {};
+                for (const [key, value] of Object.entries(event.attributes)) {
+                    if (value !== undefined) {
+                        attrs[key] = value;
+                    }
+                }
+                eventDoc.attributes = attrs;
+            }
+            return eventDoc;
+        });
+    }
+    else {
+        doc.events = [];
+    }
+    // Links
+    if (span.links.length > 0) {
+        doc.links = span.links.map(link => ({
+            traceId: link.context.traceId,
+            spanId: link.context.spanId,
+            traceState: link.context.traceState?.serialize() || '',
+            attributes: link.attributes || {},
+            droppedAttributesCount: link.droppedAttributesCount || 0,
+        }));
+    }
+    else {
+        doc.links = [];
+    }
+    // traceGroupFields (populated for root spans)
+    const hasRealParent = span.parentSpanContext?.spanId && span.parentSpanContext.spanId !== '0000000000000000';
+    if (!hasRealParent) {
+        doc.traceGroup = span.name;
+        doc.traceGroupFields = {
+            endTime: hrTimeToDate(span.endTime),
+            durationInNanos: durationNanos(span.startTime, span.endTime),
+            statusCode: statusCodeToInt(span.status.code),
+        };
+    }
+    return doc;
+}
+/**
+ * Custom SpanExporter that writes directly to OpenSearch.
+ *
+ * Formats spans in OSIS-compatible format so eval spans co-exist
+ * with agent spans in the same otel-v1-apm-span-* indices.
+ */
+export class OpenSearchSpanExporter {
+    constructor(config) {
+        this.shutdownRequested = false;
+        const auth = config.username && config.password
+            ? `${config.username}:${config.password}`
+            : undefined;
+        this.client = new Client({
+            node: config.endpoint,
+            auth: auth ? { username: config.username, password: config.password } : undefined,
+            ssl: {
+                rejectUnauthorized: config.tlsSkipVerify !== true,
+            },
+        });
+        this.indexName = config.indexName || 'otel-v1-apm-span-000001';
+        console.log(`[Telemetry] OpenSearch exporter initialized → ${config.endpoint} (index: ${this.indexName})`);
+    }
+    export(spans, resultCallback) {
+        if (this.shutdownRequested) {
+            resultCallback({ code: ExportResultCode.FAILED });
+            return;
+        }
+        this._export(spans)
+            .then(() => resultCallback({ code: ExportResultCode.SUCCESS }))
+            .catch((err) => {
+            console.error('[Telemetry] OpenSearch export failed:', err instanceof Error ? err.message : err);
+            resultCallback({ code: ExportResultCode.FAILED });
+        });
+    }
+    async _export(spans) {
+        if (spans.length === 0)
+            return;
+        // Use bulk API for efficiency
+        const body = [];
+        for (const span of spans) {
+            const doc = spanToDocument(span);
+            const docId = `${doc.traceId}/${doc.spanId}`;
+            body.push({ index: { _index: this.indexName, _id: docId } });
+            body.push(doc);
+        }
+        const response = await this.client.bulk({ body });
+        if (response.body.errors) {
+            const errors = response.body.items
+                .filter((item) => item.index?.error)
+                .map((item) => `${item.index.error.type}: ${item.index.error.reason}`);
+            if (errors.length > 0) {
+                console.warn(`[Telemetry] OpenSearch bulk write had ${errors.length} error(s):`, errors[0]);
+            }
+        }
+        else {
+            console.log(`[Telemetry] Exported ${spans.length} span(s) to OpenSearch`);
+        }
+    }
+    async shutdown() {
+        this.shutdownRequested = true;
+        await this.client.close();
+    }
+    async forceFlush() {
+        // No buffering — exports are immediate via bulk API
+    }
+}
+//# sourceMappingURL=opensearchExporter.js.map

package/lib/dist/lib/telemetry/opensearchExporter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"opensearchExporter.js","sourceRoot":"","sources":["../../../telemetry/opensearchExporter.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/telemetry/provider.d.ts

@@ -0,0 +1,55 @@
+/**
+ * OTel TracerProvider management for evaluation telemetry.
+ *
+ * Manages a singleton TracerProvider that exports evaluation spans
+ * via OTLP/HTTP to a collector, or directly to OpenSearch when an
+ * observability data source is configured.
+ */
+import { type Tracer } from '@opentelemetry/api';
+import { type OpenSearchExporterConfig } from './opensearchExporter.js';
+/**
+ * Configuration for evaluation telemetry
+ */
+export interface EvalTelemetryConfig {
+    /** Whether evaluation telemetry is enabled */
+    enabled: boolean;
+    /** OTLP exporter endpoint (e.g., http://localhost:4318/v1/traces) */
+    exporterEndpoint: string;
+    /** Optional headers for the OTLP exporter (e.g., auth) */
+    exporterHeaders?: Record<string, string>;
+    /** Service name for resource attributes */
+    serviceName?: string;
+    /** OpenSearch direct export config (derived from observability data source) */
+    opensearch?: OpenSearchExporterConfig;
+}
+/**
+ * Resolve telemetry config from environment variables and optional user config
+ */
+export declare function resolveEvalTelemetryConfig(userConfig?: Partial<EvalTelemetryConfig>): EvalTelemetryConfig;
+/**
+ * Initialize the evaluation TracerProvider.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ *
+ * When an OpenSearch config is provided (from observability data source),
+ * spans are written directly to OpenSearch in OSIS-compatible format.
+ * Otherwise, falls back to OTLP/HTTP exporter.
+ */
+export declare function initEvalTracerProvider(config: EvalTelemetryConfig): void;
+/**
+ * Get the evaluation tracer. Returns a no-op tracer if telemetry is disabled.
+ */
+export declare function getEvalTracer(): Tracer;
+/**
+ * Check if evaluation telemetry is enabled
+ */
+export declare function isEvalTelemetryEnabled(): boolean;
+/**
+ * Force-flush any buffered spans to the exporter.
+ * Call after emitting spans to ensure they are exported promptly.
+ */
+export declare function flushEvalTracer(): Promise<void>;
+/**
+ * Flush pending spans and shut down the TracerProvider.
+ */
+export declare function shutdownEvalTracer(): Promise<void>;
+//# sourceMappingURL=provider.d.ts.map

package/lib/dist/lib/telemetry/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../telemetry/provider.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AAEH,OAAO,EAAS,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAKxD,OAAO,EAA0B,KAAK,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAEhG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,wBAAwB,CAAC;CACvC;AAKD;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,CAwBzG;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAqDxE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC,CAQrD;AAED;;GAEG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAOxD"}

package/lib/dist/lib/telemetry/provider.js

@@ -0,0 +1,140 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * OTel TracerProvider management for evaluation telemetry.
+ *
+ * Manages a singleton TracerProvider that exports evaluation spans
+ * via OTLP/HTTP to a collector, or directly to OpenSearch when an
+ * observability data source is configured.
+ */
+import { trace } from '@opentelemetry/api';
+import { NodeTracerProvider, BatchSpanProcessor, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { EVAL_TRACER_NAME } from './constants.js';
+import { OpenSearchSpanExporter } from './opensearchExporter.js';
+let provider = null;
+let telemetryEnabled = false;
+/**
+ * Resolve telemetry config from environment variables and optional user config
+ */
+export function resolveEvalTelemetryConfig(userConfig) {
+    const enabled = userConfig?.enabled
+        ?? process.env.OTEL_EVAL_ENABLED === 'true';
+    const exporterEndpoint = userConfig?.exporterEndpoint
+        ?? process.env.OTEL_EVAL_EXPORTER_ENDPOINT
+        ?? 'http://localhost:4318/v1/traces';
+    let exporterHeaders = userConfig?.exporterHeaders;
+    if (!exporterHeaders && process.env.OTEL_EVAL_EXPORTER_HEADERS) {
+        try {
+            exporterHeaders = JSON.parse(process.env.OTEL_EVAL_EXPORTER_HEADERS);
+        }
+        catch {
+            console.warn('[Telemetry] Failed to parse OTEL_EVAL_EXPORTER_HEADERS as JSON');
+        }
+    }
+    // Use a dedicated env var for eval service name — do NOT fall back to
+    // OTEL_SERVICE_NAME which belongs to the agent's own telemetry (e.g. claude-code-agent).
+    const serviceName = userConfig?.serviceName
+        ?? process.env.OTEL_EVAL_SERVICE_NAME
+        ?? 'agent-health';
+    return { enabled, exporterEndpoint, exporterHeaders, serviceName, opensearch: userConfig?.opensearch };
+}
+/**
+ * Initialize the evaluation TracerProvider.
+ * Safe to call multiple times — subsequent calls are no-ops.
+ *
+ * When an OpenSearch config is provided (from observability data source),
+ * spans are written directly to OpenSearch in OSIS-compatible format.
+ * Otherwise, falls back to OTLP/HTTP exporter.
+ */
+export function initEvalTracerProvider(config) {
+    if (provider) {
+        return; // Already initialized
+    }
+    if (!config.enabled) {
+        telemetryEnabled = false;
+        console.log('[Telemetry] Evaluation telemetry disabled (OTEL_EVAL_ENABLED != true)');
+        return;
+    }
+    const resource = resourceFromAttributes({
+        'service.name': config.serviceName ?? 'agent-health',
+        'telemetry.sdk.name': 'agent-health',
+        'telemetry.sdk.language': 'nodejs',
+    });
+    // Choose exporter priority:
+    //   1. OTLP/HTTP when exporterEndpoint is explicitly configured (e.g., OSIS pipeline)
+    //   2. OpenSearch direct when observability data source is configured
+    //   3. OTLP/HTTP with default endpoint as last resort
+    const spanProcessors = [];
+    const hasExplicitOtlpEndpoint = config.exporterEndpoint !== 'http://localhost:4318/v1/traces';
+    if (hasExplicitOtlpEndpoint) {
+        // User explicitly configured an OTLP endpoint (e.g., OSIS pipeline) — prefer it
+        const otlpExporter = new OTLPTraceExporter({
+            url: config.exporterEndpoint,
+            headers: config.exporterHeaders,
+        });
+        spanProcessors.push(new BatchSpanProcessor(otlpExporter));
+        console.log(`[Telemetry] Evaluation telemetry enabled → OTLP (${config.exporterEndpoint})`);
+    }
+    else if (config.opensearch) {
+        const osExporter = new OpenSearchSpanExporter(config.opensearch);
+        // Use SimpleSpanProcessor for immediate export (eval spans are infrequent)
+        spanProcessors.push(new SimpleSpanProcessor(osExporter));
+        console.log(`[Telemetry] Evaluation telemetry enabled → OpenSearch direct (${config.opensearch.endpoint})`);
+    }
+    else {
+        const otlpExporter = new OTLPTraceExporter({
+            url: config.exporterEndpoint,
+            headers: config.exporterHeaders,
+        });
+        spanProcessors.push(new BatchSpanProcessor(otlpExporter));
+        console.log(`[Telemetry] Evaluation telemetry enabled → OTLP (${config.exporterEndpoint})`);
+    }
+    provider = new NodeTracerProvider({
+        resource,
+        spanProcessors,
+    });
+    provider.register();
+    telemetryEnabled = true;
+}
+/**
+ * Get the evaluation tracer. Returns a no-op tracer if telemetry is disabled.
+ */
+export function getEvalTracer() {
+    return trace.getTracer(EVAL_TRACER_NAME);
+}
+/**
+ * Check if evaluation telemetry is enabled
+ */
+export function isEvalTelemetryEnabled() {
+    return telemetryEnabled;
+}
+/**
+ * Force-flush any buffered spans to the exporter.
+ * Call after emitting spans to ensure they are exported promptly.
+ */
+export async function flushEvalTracer() {
+    if (provider) {
+        try {
+            await provider.forceFlush();
+        }
+        catch (err) {
+            console.warn('[Telemetry] forceFlush failed:', err instanceof Error ? err.message : err);
+        }
+    }
+}
+/**
+ * Flush pending spans and shut down the TracerProvider.
+ */
+export async function shutdownEvalTracer() {
+    if (provider) {
+        await provider.shutdown();
+        provider = null;
+        telemetryEnabled = false;
+        console.log('[Telemetry] Evaluation telemetry shut down');
+    }
+}
+//# sourceMappingURL=provider.js.map

package/lib/dist/lib/telemetry/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../../telemetry/provider.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/testCaseLabels.d.ts

@@ -0,0 +1,34 @@
+export type DifficultyLabel = 'Easy' | 'Medium' | 'Hard';
+/**
+ * Extract the category from a labels array, or undefined when not present.
+ * If multiple `category:` labels are present, the first one wins.
+ */
+export declare function getCategoryFromLabels(labels?: string[]): string | undefined;
+/**
+ * Extract the difficulty from a labels array, or undefined when not present.
+ * Values are normalized to the canonical `Easy | Medium | Hard` form when
+ * possible; non-canonical values are returned as-is.
+ */
+export declare function getDifficultyFromLabels(labels?: string[]): DifficultyLabel | string | undefined;
+/**
+ * Extract the subcategory from a labels array, or undefined when not present.
+ */
+export declare function getSubcategoryFromLabels(labels?: string[]): string | undefined;
+/**
+ * Build a labels array from the legacy top-level `category` / `difficulty`
+ * fields, preserving any existing labels and refusing to add a duplicate
+ * facet (e.g. won't add `category:RCA` if a `category:` label is already
+ * present).
+ */
+export declare function migrateLegacyFieldsToLabels(input: {
+    category?: string;
+    difficulty?: string;
+    subcategory?: string;
+    labels?: string[];
+}): string[];
+/**
+ * Returns true when the labels array contains a structured facet for the
+ * given prefix. Useful in migrations to avoid double-applying.
+ */
+export declare function hasLabelPrefix(labels: string[] | undefined, prefix: string): boolean;
+//# sourceMappingURL=testCaseLabels.d.ts.map

package/lib/dist/lib/testCaseLabels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testCaseLabels.d.ts","sourceRoot":"","sources":["../../testCaseLabels.ts"],"names":[],"mappings":"AAwBA,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEzD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAI3E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,eAAe,GAAG,MAAM,GAAG,SAAS,CAU/F;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAI9E;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,GAAG,MAAM,EAAE,CAYX;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAIpF"}

package/lib/dist/lib/testCaseLabels.js

@@ -0,0 +1,88 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Helpers for the unified `labels` tagging system that replaces the legacy
+ * top-level `category` and `difficulty` fields on TestCase.
+ *
+ * Convention: structured labels use a `prefix:value` form so we can extract
+ * specific facets (e.g. category, difficulty) when the UI needs them.
+ *
+ *   'category:RCA'
+ *   'difficulty:Medium'
+ *   'team:platform'
+ *   'tier:p0'
+ *
+ * Free-form labels without a prefix are also allowed for human tagging.
+ */
+const CATEGORY_PREFIX = 'category:';
+const DIFFICULTY_PREFIX = 'difficulty:';
+const SUBCATEGORY_PREFIX = 'subcategory:';
+/**
+ * Extract the category from a labels array, or undefined when not present.
+ * If multiple `category:` labels are present, the first one wins.
+ */
+export function getCategoryFromLabels(labels) {
+    if (!labels || labels.length === 0)
+        return undefined;
+    const hit = labels.find(l => l.startsWith(CATEGORY_PREFIX));
+    return hit ? hit.slice(CATEGORY_PREFIX.length) || undefined : undefined;
+}
+/**
+ * Extract the difficulty from a labels array, or undefined when not present.
+ * Values are normalized to the canonical `Easy | Medium | Hard` form when
+ * possible; non-canonical values are returned as-is.
+ */
+export function getDifficultyFromLabels(labels) {
+    if (!labels || labels.length === 0)
+        return undefined;
+    const hit = labels.find(l => l.startsWith(DIFFICULTY_PREFIX));
+    if (!hit)
+        return undefined;
+    const raw = hit.slice(DIFFICULTY_PREFIX.length).trim();
+    const normalized = raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+    if (normalized === 'Easy' || normalized === 'Medium' || normalized === 'Hard') {
+        return normalized;
+    }
+    return raw || undefined;
+}
+/**
+ * Extract the subcategory from a labels array, or undefined when not present.
+ */
+export function getSubcategoryFromLabels(labels) {
+    if (!labels || labels.length === 0)
+        return undefined;
+    const hit = labels.find(l => l.startsWith(SUBCATEGORY_PREFIX));
+    return hit ? hit.slice(SUBCATEGORY_PREFIX.length) || undefined : undefined;
+}
+/**
+ * Build a labels array from the legacy top-level `category` / `difficulty`
+ * fields, preserving any existing labels and refusing to add a duplicate
+ * facet (e.g. won't add `category:RCA` if a `category:` label is already
+ * present).
+ */
+export function migrateLegacyFieldsToLabels(input) {
+    const out = [...(input.labels ?? [])];
+    if (input.category && !out.some(l => l.startsWith(CATEGORY_PREFIX))) {
+        out.push(`${CATEGORY_PREFIX}${input.category}`);
+    }
+    if (input.difficulty && !out.some(l => l.startsWith(DIFFICULTY_PREFIX))) {
+        out.push(`${DIFFICULTY_PREFIX}${input.difficulty}`);
+    }
+    if (input.subcategory && !out.some(l => l.startsWith(SUBCATEGORY_PREFIX))) {
+        out.push(`${SUBCATEGORY_PREFIX}${input.subcategory}`);
+    }
+    return out;
+}
+/**
+ * Returns true when the labels array contains a structured facet for the
+ * given prefix. Useful in migrations to avoid double-applying.
+ */
+export function hasLabelPrefix(labels, prefix) {
+    if (!labels)
+        return false;
+    const normalized = prefix.endsWith(':') ? prefix : `${prefix}:`;
+    return labels.some(l => l.startsWith(normalized));
+}
+//# sourceMappingURL=testCaseLabels.js.map

package/lib/dist/lib/testCaseLabels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testCaseLabels.js","sourceRoot":"","sources":["../../testCaseLabels.ts"],"names":[],"mappings":"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"}