qualink 0.1.1 → 0.3.0

package/dist/cli/commands/meta.d.ts

@@ -1,63 +1,75 @@
 export declare const metaCommand: import("citty").CommandDef<{
-    input: {
+    readonly input: {
         readonly type: "string";
         readonly required: true;
     };
-    sink: {
+    readonly sink: {
         readonly type: "string";
         readonly default: "elastic";
     };
-    repo: {
+    readonly repo: {
         readonly type: "string";
     };
-    category: {
+    readonly category: {
         readonly type: "string";
     };
-    tags: {
+    readonly tags: {
         readonly type: "string";
     };
-    branch: {
+    readonly branch: {
         readonly type: "string";
     };
-    "commit-sha": {
+    readonly "commit-sha": {
         readonly type: "string";
     };
-    "pipeline-run-id": {
+    readonly "pipeline-run-id": {
         readonly type: "string";
     };
-    "pipeline-provider": {
+    readonly "pipeline-provider": {
         readonly type: "string";
     };
-    environment: {
+    readonly environment: {
         readonly type: "string";
         readonly default: "ci";
     };
-    package: {
+    readonly package: {
         readonly type: "string";
     };
-    project: {
+    readonly project: {
         readonly type: "string";
     };
-    "collector-version": {
+    readonly "collector-version": {
         readonly type: "string";
     };
-    "elastic-url": {
+    readonly "elastic-url": {
         readonly type: "string";
     };
-    "elastic-api-key": {
+    readonly "elastic-api-key": {
         readonly type: "string";
     };
-    "retry-max": {
+    readonly "loki-url": {
         readonly type: "string";
     };
-    "retry-backoff-ms": {
+    readonly "loki-username": {
         readonly type: "string";
     };
-    "allow-empty": {
+    readonly "loki-password": {
+        readonly type: "string";
+    };
+    readonly "loki-tenant-id": {
+        readonly type: "string";
+    };
+    readonly "retry-max": {
+        readonly type: "string";
+    };
+    readonly "retry-backoff-ms": {
+        readonly type: "string";
+    };
+    readonly "allow-empty": {
         readonly type: "boolean";
         readonly default: false;
     };
-    "dry-run": {
+    readonly "dry-run": {
         readonly type: "boolean";
         readonly default: false;
     };

package/dist/cli/commands/sarif.d.ts

@@ -1,63 +1,75 @@
 export declare const sarifCommand: import("citty").CommandDef<{
-    input: {
+    readonly input: {
         readonly type: "string";
         readonly required: true;
     };
-    sink: {
+    readonly sink: {
         readonly type: "string";
         readonly default: "elastic";
     };
-    repo: {
+    readonly repo: {
         readonly type: "string";
     };
-    category: {
+    readonly category: {
         readonly type: "string";
     };
-    tags: {
+    readonly tags: {
         readonly type: "string";
     };
-    branch: {
+    readonly branch: {
         readonly type: "string";
     };
-    "commit-sha": {
+    readonly "commit-sha": {
         readonly type: "string";
     };
-    "pipeline-run-id": {
+    readonly "pipeline-run-id": {
         readonly type: "string";
     };
-    "pipeline-provider": {
+    readonly "pipeline-provider": {
         readonly type: "string";
     };
-    environment: {
+    readonly environment: {
         readonly type: "string";
         readonly default: "ci";
     };
-    package: {
+    readonly package: {
         readonly type: "string";
     };
-    project: {
+    readonly project: {
         readonly type: "string";
     };
-    "collector-version": {
+    readonly "collector-version": {
         readonly type: "string";
     };
-    "elastic-url": {
+    readonly "elastic-url": {
         readonly type: "string";
     };
-    "elastic-api-key": {
+    readonly "elastic-api-key": {
         readonly type: "string";
     };
-    "retry-max": {
+    readonly "loki-url": {
         readonly type: "string";
     };
-    "retry-backoff-ms": {
+    readonly "loki-username": {
         readonly type: "string";
     };
-    "allow-empty": {
+    readonly "loki-password": {
+        readonly type: "string";
+    };
+    readonly "loki-tenant-id": {
+        readonly type: "string";
+    };
+    readonly "retry-max": {
+        readonly type: "string";
+    };
+    readonly "retry-backoff-ms": {
+        readonly type: "string";
+    };
+    readonly "allow-empty": {
         readonly type: "boolean";
         readonly default: false;
     };
-    "dry-run": {
+    readonly "dry-run": {
         readonly type: "boolean";
         readonly default: false;
     };

package/dist/cli/common-args.d.ts

@@ -15,6 +15,10 @@ export interface CommonArgs {
     collectorVersion?: unknown;
     elasticUrl?: unknown;
     elasticApiKey?: unknown;
+    lokiUrl?: unknown;
+    lokiUsername?: unknown;
+    lokiPassword?: unknown;
+    lokiTenantId?: unknown;
     retryMax?: unknown;
     retryBackoffMs?: unknown;
     allowEmpty?: unknown;
@@ -71,6 +75,18 @@ export declare const commonArgs: {
     readonly "elastic-api-key": {
         readonly type: "string";
     };
+    readonly "loki-url": {
+        readonly type: "string";
+    };
+    readonly "loki-username": {
+        readonly type: "string";
+    };
+    readonly "loki-password": {
+        readonly type: "string";
+    };
+    readonly "loki-tenant-id": {
+        readonly type: "string";
+    };
     readonly "retry-max": {
         readonly type: "string";
     };

package/dist/cli/common-args.js

@@ -37,6 +37,10 @@ export const commonArgs = {
     "collector-version": { type: "string" },
     "elastic-url": { type: "string" },
     "elastic-api-key": { type: "string" },
+    "loki-url": { type: "string" },
+    "loki-username": { type: "string" },
+    "loki-password": { type: "string" },
+    "loki-tenant-id": { type: "string" },
     "retry-max": { type: "string" },
     "retry-backoff-ms": { type: "string" },
     "allow-empty": { type: "boolean", default: false },

package/dist/cli/send-to-sink.js

@@ -27,26 +27,43 @@ export async function sendToSink(metricType, args, documents) {
         return;
     }
     const sinkKindRaw = (envOrArg(argValue(args, "sink"), "QUALINK_SINK") ?? "elastic").toLowerCase();
-    if (sinkKindRaw !== "elastic" && sinkKindRaw !== "stdout") {
-        throw new CliError(`Unsupported sink '${sinkKindRaw}'. Expected elastic|stdout`, 2);
+    if (sinkKindRaw !== "elastic" && sinkKindRaw !== "loki" && sinkKindRaw !== "stdout") {
+        throw new CliError(`Unsupported sink '${sinkKindRaw}'. Expected elastic|loki|stdout`, 2);
     }
-    const sinkKind = sinkKindRaw === "elastic" ? "elastic" : "stdout";
+    const sinkKind = sinkKindRaw;
     const retryMax = parseNumberInput(argValue(args, "retryMax", "retry-max"), 2);
     const retryBackoffMs = parseNumberInput(argValue(args, "retryBackoffMs", "retry-backoff-ms"), 500);
     const elasticUrl = envOrArg(argValue(args, "elasticUrl", "elastic-url"), "ELASTIC_URL");
     const elasticApiKey = envOrArg(argValue(args, "elasticApiKey", "elastic-api-key"), "ELASTIC_API_KEY");
+    const lokiUrl = envOrArg(argValue(args, "lokiUrl", "loki-url"), "LOKI_URL");
+    const lokiUsername = envOrArg(argValue(args, "lokiUsername", "loki-username"), "LOKI_USERNAME");
+    const lokiPassword = envOrArg(argValue(args, "lokiPassword", "loki-password"), "LOKI_PASSWORD");
+    const lokiTenantId = envOrArg(argValue(args, "lokiTenantId", "loki-tenant-id"), "LOKI_TENANT_ID");
     const sinkConfigBase = {
         kind: sinkKind,
         retryMax,
         retryBackoffMs,
     };
-    const sinkConfig = sinkKind === "elastic"
-        ? {
+    let sinkConfig;
+    if (sinkKind === "elastic") {
+        sinkConfig = {
             ...sinkConfigBase,
             ...(elasticUrl ? { elasticUrl } : {}),
             ...(elasticApiKey ? { elasticApiKey } : {}),
-        }
-        : sinkConfigBase;
+        };
+    }
+    else if (sinkKind === "loki") {
+        sinkConfig = {
+            ...sinkConfigBase,
+            ...(lokiUrl ? { lokiUrl } : {}),
+            ...(lokiUsername ? { lokiUsername } : {}),
+            ...(lokiPassword ? { lokiPassword } : {}),
+            ...(lokiTenantId ? { lokiTenantId } : {}),
+        };
+    }
+    else {
+        sinkConfig = sinkConfigBase;
+    }
     const sink = createSink(sinkConfig);
     await sink.send({
         metricType,

package/dist/collectors/eslint.d.ts

@@ -1,6 +1,7 @@
 import type { CommonMetadata, EslintMetricDocument, Language } from "../types.js";
 interface EslintMessage {
     ruleId: string | null;
+    severity?: number | undefined;
 }
 interface EslintFileResult {
     filePath: string;
@@ -9,6 +10,7 @@ interface EslintFileResult {
     fixableErrorCount: number;
     fixableWarningCount: number;
     messages: EslintMessage[];
+    suppressedMessages: EslintMessage[];
 }
 export interface EslintCollectorOptions {
     includeRules: boolean;

package/dist/collectors/eslint.js

@@ -12,16 +12,20 @@ function asEslintResults(input) {
         if (!Array.isArray(messagesRaw)) {
             throw new Error("Invalid ESLint messages array");
         }
-        const messages = messagesRaw.map((message) => {
+        const parseMessages = (raw) => raw.map((message) => {
             if (!isRecord(message)) {
                 return { ruleId: null };
             }
             const ruleValue = message.ruleId;
+            const severity = typeof message.severity === "number" ? message.severity : undefined;
             if (typeof ruleValue !== "string" && ruleValue !== null) {
-                return { ruleId: null };
+                return { ruleId: null, severity };
             }
-            return { ruleId: ruleValue };
+            return { ruleId: ruleValue, severity };
         });
+        const messages = parseMessages(messagesRaw);
+        const suppressedRaw = entry.suppressedMessages;
+        const suppressedMessages = Array.isArray(suppressedRaw) ? parseMessages(suppressedRaw) : [];
         return {
             filePath: typeof entry.filePath === "string" ? entry.filePath : "unknown",
             errorCount: typeof entry.errorCount === "number" ? entry.errorCount : 0,
@@ -29,6 +33,7 @@ function asEslintResults(input) {
             fixableErrorCount: typeof entry.fixableErrorCount === "number" ? entry.fixableErrorCount : 0,
             fixableWarningCount: typeof entry.fixableWarningCount === "number" ? entry.fixableWarningCount : 0,
             messages,
+            suppressedMessages,
         };
     });
 }
@@ -58,7 +63,10 @@ export function collectEslint(input, metadata, options) {
     let warnings = 0;
     let fixableErrors = 0;
     let fixableWarnings = 0;
+    let suppressedErrors = 0;
+    let suppressedWarnings = 0;
     const rules = new Map();
+    const suppressedRules = new Map();
     const files = [];
     for (const row of rows) {
         errors += row.errorCount;
@@ -81,6 +89,20 @@ export function collectEslint(input, metadata, options) {
             const existing = rules.get(message.ruleId) ?? 0;
             rules.set(message.ruleId, existing + 1);
         }
+        for (const message of row.suppressedMessages) {
+            // severity: 2 = error, 1 = warning
+            if (message.severity === 2) {
+                suppressedErrors++;
+            }
+            else {
+                suppressedWarnings++;
+            }
+            if (!message.ruleId) {
+                continue;
+            }
+            const existing = suppressedRules.get(message.ruleId) ?? 0;
+            suppressedRules.set(message.ruleId, existing + 1);
+        }
     }
     const languages = options.languages ?? detectEslintLanguages(rows);
     const doc = {
@@ -94,11 +116,18 @@ export function collectEslint(input, metadata, options) {
         warnings,
         fixable_errors: fixableErrors,
         fixable_warnings: fixableWarnings,
+        suppressed_errors: suppressedErrors,
+        suppressed_warnings: suppressedWarnings,
     };
     if (options.includeRules) {
         const sortedRules = [...rules.entries()].sort((a, b) => b[1] - a[1]);
         const slice = options.topRules > 0 ? sortedRules.slice(0, options.topRules) : sortedRules;
         doc.rules_violated = Object.fromEntries(slice);
+        if (suppressedRules.size > 0) {
+            const sortedSuppressed = [...suppressedRules.entries()].sort((a, b) => b[1] - a[1]);
+            const suppressedSlice = options.topRules > 0 ? sortedSuppressed.slice(0, options.topRules) : sortedSuppressed;
+            doc.suppressed_rules = Object.fromEntries(suppressedSlice);
+        }
     }
     if (files.length > 0 && (options.topFiles > 0 || options.includeAllFiles)) {
         const sortedFiles = [...files].sort((a, b) => {

package/dist/collectors/lighthouse.d.ts

@@ -1,2 +1,5 @@
 import type { CommonMetadata, LighthouseMetricDocument } from "../types.js";
-export declare function collectLighthouse(input: unknown, metadata: CommonMetadata, url: string): LighthouseMetricDocument[];
+export interface LighthouseCollectorOptions {
+    includeFilmstrip: boolean;
+}
+export declare function collectLighthouse(input: unknown, metadata: CommonMetadata, url: string, options?: LighthouseCollectorOptions): LighthouseMetricDocument[];

package/dist/collectors/lighthouse.js

@@ -12,7 +12,42 @@ function readCategoryScore(categories, key) {
     }
     return toPctFromUnitScore(score);
 }
-export function collectLighthouse(input, metadata, url) {
+function readAuditNumeric(audits, key) {
+    const audit = audits[key];
+    if (!isRecord(audit)) {
+        return undefined;
+    }
+    const value = audit.numericValue;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    return value;
+}
+function extractFilmstrip(audits) {
+    const thumbnail = audits["screenshot-thumbnails"];
+    if (!isRecord(thumbnail))
+        return undefined;
+    const details = thumbnail.details;
+    if (!isRecord(details))
+        return undefined;
+    if (details.type !== "filmstrip")
+        return undefined;
+    const items = details.items;
+    if (!Array.isArray(items))
+        return undefined;
+    const frames = [];
+    for (const item of items) {
+        if (!isRecord(item))
+            continue;
+        if (typeof item.timing !== "number" || !Number.isFinite(item.timing))
+            continue;
+        if (typeof item.data !== "string")
+            continue;
+        frames.push({ timing: item.timing, data: item.data });
+    }
+    return frames.length > 0 ? frames : undefined;
+}
+export function collectLighthouse(input, metadata, url, options) {
     if (!isRecord(input)) {
         throw new Error("Lighthouse input must be an object");
     }
@@ -33,5 +68,58 @@ export function collectLighthouse(input, metadata, url) {
         best_practices: readCategoryScore(categoriesUnknown, "best-practices"),
         seo: readCategoryScore(categoriesUnknown, "seo"),
     };
+    const audits = input.audits;
+    if (isRecord(audits)) {
+        const fcp = readAuditNumeric(audits, "first-contentful-paint");
+        const lcp = readAuditNumeric(audits, "largest-contentful-paint");
+        const tbt = readAuditNumeric(audits, "total-blocking-time");
+        const cls = readAuditNumeric(audits, "cumulative-layout-shift");
+        const si = readAuditNumeric(audits, "speed-index");
+        const tti = readAuditNumeric(audits, "interactive");
+        const ttfb = readAuditNumeric(audits, "server-response-time");
+        const totalByteWeight = readAuditNumeric(audits, "total-byte-weight");
+        const domSize = readAuditNumeric(audits, "dom-size");
+        if (fcp !== undefined)
+            doc.fcp = fcp;
+        if (lcp !== undefined)
+            doc.lcp = lcp;
+        if (tbt !== undefined)
+            doc.tbt = tbt;
+        if (cls !== undefined)
+            doc.cls = cls;
+        if (si !== undefined)
+            doc.si = si;
+        if (tti !== undefined)
+            doc.tti = tti;
+        if (ttfb !== undefined)
+            doc.ttfb = ttfb;
+        if (totalByteWeight !== undefined)
+            doc.total_byte_weight = totalByteWeight;
+        if (domSize !== undefined)
+            doc.dom_size = domSize;
+        const auditScores = {};
+        const auditValues = {};
+        for (const [id, raw] of Object.entries(audits)) {
+            if (!isRecord(raw))
+                continue;
+            if (typeof raw.score === "number" && Number.isFinite(raw.score)) {
+                auditScores[id] = toPctFromUnitScore(raw.score);
+            }
+            if (typeof raw.numericValue === "number" && Number.isFinite(raw.numericValue)) {
+                auditValues[id] = raw.numericValue;
+            }
+        }
+        if (Object.keys(auditScores).length > 0) {
+            doc.audit_scores = auditScores;
+        }
+        if (Object.keys(auditValues).length > 0) {
+            doc.audit_values = auditValues;
+        }
+        if (options?.includeFilmstrip) {
+            const filmstrip = extractFilmstrip(audits);
+            if (filmstrip)
+                doc.filmstrip = filmstrip;
+        }
+    }
     return [doc];
 }

package/dist/sinks/index.d.ts

@@ -1,9 +1,13 @@
 import type { Sink } from "./types.js";
-export type SinkKind = "elastic" | "stdout";
+export type SinkKind = "elastic" | "loki" | "stdout";
 export interface SinkConfig {
     kind: SinkKind;
     elasticUrl?: string;
     elasticApiKey?: string;
+    lokiUrl?: string;
+    lokiUsername?: string;
+    lokiPassword?: string;
+    lokiTenantId?: string;
     retryMax: number;
     retryBackoffMs: number;
 }

package/dist/sinks/index.js

@@ -1,9 +1,23 @@
 import { ElasticSink } from "./elastic.js";
+import { LokiSink } from "./loki.js";
 import { StdoutSink } from "./stdout.js";
 export function createSink(config) {
     if (config.kind === "stdout") {
         return new StdoutSink();
     }
+    if (config.kind === "loki") {
+        if (!config.lokiUrl) {
+            throw new Error("Loki sink requires LOKI_URL (or --loki-url)");
+        }
+        return new LokiSink({
+            url: config.lokiUrl,
+            username: config.lokiUsername,
+            password: config.lokiPassword,
+            tenantId: config.lokiTenantId,
+            retryMax: config.retryMax,
+            retryBackoffMs: config.retryBackoffMs,
+        });
+    }
     if (!config.elasticUrl || !config.elasticApiKey) {
         throw new Error("Elastic sink requires ELASTIC_URL and ELASTIC_API_KEY (or CLI overrides)");
     }

package/dist/sinks/loki.d.ts

@@ -0,0 +1,30 @@
+import type { NormalizedDocument } from "../types.js";
+import type { SendInput, Sink } from "./types.js";
+export interface LokiSinkOptions {
+    url: string;
+    username?: string | undefined;
+    password?: string | undefined;
+    tenantId?: string | undefined;
+    retryMax: number;
+    retryBackoffMs: number;
+}
+interface LokiStream {
+    stream: Record<string, string>;
+    values: [string, string][];
+}
+interface LokiPushPayload {
+    streams: LokiStream[];
+}
+export declare function toNanosecondEpoch(isoTimestamp: string): string;
+export declare function buildLokiPayload(documents: NormalizedDocument[]): LokiPushPayload;
+export declare class LokiSink implements Sink {
+    private readonly url;
+    private readonly username;
+    private readonly password;
+    private readonly tenantId;
+    private readonly retryMax;
+    private readonly retryBackoffMs;
+    constructor(options: LokiSinkOptions);
+    send(input: SendInput): Promise<void>;
+}
+export {};

package/dist/sinks/loki.js

@@ -0,0 +1,84 @@
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isRetryableStatus(status) {
+    return status === 429 || status >= 500;
+}
+function toLabelKey(doc) {
+    return `${doc.metric_type}|${doc.repo}|${doc.environment}`;
+}
+export function toNanosecondEpoch(isoTimestamp) {
+    const ms = new Date(isoTimestamp).getTime();
+    return `${ms}000000`;
+}
+export function buildLokiPayload(documents) {
+    const streamMap = new Map();
+    for (const doc of documents) {
+        const key = toLabelKey(doc);
+        let stream = streamMap.get(key);
+        if (!stream) {
+            stream = {
+                stream: {
+                    metric_type: doc.metric_type,
+                    repo: doc.repo,
+                    environment: doc.environment,
+                },
+                values: [],
+            };
+            streamMap.set(key, stream);
+        }
+        stream.values.push([toNanosecondEpoch(doc["@timestamp"]), JSON.stringify(doc)]);
+    }
+    return { streams: Array.from(streamMap.values()) };
+}
+export class LokiSink {
+    url;
+    username;
+    password;
+    tenantId;
+    retryMax;
+    retryBackoffMs;
+    constructor(options) {
+        this.url = options.url.replace(/\/$/, "");
+        this.username = options.username;
+        this.password = options.password;
+        this.tenantId = options.tenantId;
+        this.retryMax = options.retryMax;
+        this.retryBackoffMs = options.retryBackoffMs;
+    }
+    async send(input) {
+        if (input.documents.length === 0) {
+            return;
+        }
+        const payload = buildLokiPayload(input.documents);
+        const body = JSON.stringify(payload);
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.username && this.password) {
+            const encoded = btoa(`${this.username}:${this.password}`);
+            headers.Authorization = `Basic ${encoded}`;
+        }
+        if (this.tenantId) {
+            headers["X-Scope-OrgID"] = this.tenantId;
+        }
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            const response = await fetch(`${this.url}/loki/api/v1/push`, {
+                method: "POST",
+                headers,
+                body,
+            });
+            if (response.status === 204 || response.ok) {
+                return;
+            }
+            const responseText = await response.text();
+            if (!isRetryableStatus(response.status) || attempt > this.retryMax) {
+                process.stderr.write(`[qualink] Dead-letter payload:\n${body}\n`);
+                throw new Error(`Loki push failed (${response.status}): ${responseText}`);
+            }
+            await sleep(this.retryBackoffMs * attempt);
+        }
+    }
+}