@qanalyzer/forge-commons 1.1.1

package/dist/qanalyzer/options-resolver.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OptionsResolver = void 0;
+exports.createDefaultConfig = createDefaultConfig;
+const env_1 = require("../env");
+const options_1 = require("../options");
+class OptionsResolver {
+    resolve(options = {}) {
+        const composed = (0, options_1.composeOptions)(createDefaultConfig(), options, (0, env_1.envToConfig)());
+        return {
+            effectiveMode: composed.mode ?? options_1.ModeEnum.off,
+            effectiveFallback: composed.fallback ?? options_1.ModeEnum.off,
+            composed,
+        };
+    }
+}
+exports.OptionsResolver = OptionsResolver;
+function createDefaultConfig() {
+    return {
+        mode: options_1.ModeEnum.off,
+        fallback: options_1.ModeEnum.off,
+        debug: false,
+        ingest: {
+            timeoutMs: 30_000,
+            maxPayloadBytes: 4_500_000,
+        },
+        file: {
+            path: './qanalyzer-results.json',
+        },
+    };
+}

package/dist/qanalyzer/reporter-factory.d.ts

@@ -0,0 +1,11 @@
+import type { ConfigType } from '../config';
+import { ModeEnum, type OptionsType } from '../options';
+import { type InternalReporterInterface } from '../reporters';
+import { type LoggerInterface } from '../utils';
+export declare class ReporterFactory {
+    private readonly logger;
+    constructor(logger: LoggerInterface);
+    create(mode: ModeEnum, options: ConfigType & OptionsType): InternalReporterInterface;
+    private createIngest;
+    private createFile;
+}

package/dist/qanalyzer/reporter-factory.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReporterFactory = void 0;
+const client_1 = require("../client");
+const env_1 = require("../env");
+const options_1 = require("../options");
+const reporters_1 = require("../reporters");
+const utils_1 = require("../utils");
+const writer_1 = require("../writer");
+class ReporterFactory {
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    create(mode, options) {
+        switch (mode) {
+            case options_1.ModeEnum.ingest:
+                return this.createIngest(options);
+            case options_1.ModeEnum.file:
+                return this.createFile(options);
+            case options_1.ModeEnum.off:
+                throw new utils_1.DisabledException('QAnalyzer reporter is disabled (mode=off)');
+            default:
+                throw new Error(`Unknown mode: ${String(mode)}`);
+        }
+    }
+    createIngest(options) {
+        if (!options.ingest?.token) {
+            throw new Error(`Either "ingest.token" or "${env_1.EnvIngestEnum.token}" is required in ingest mode`);
+        }
+        if (!options.ingest?.url) {
+            throw new Error(`Either "ingest.url" or "${env_1.EnvIngestEnum.url}" is required in ingest mode`);
+        }
+        if (!options.projectKey) {
+            throw new Error('projectKey is required in ingest mode');
+        }
+        const client = new client_1.IngestClient({
+            ...options.ingest,
+            logger: this.logger,
+        });
+        return new reporters_1.IngestReporter(this.logger, client);
+    }
+    createFile(options) {
+        if (!options.projectKey) {
+            throw new Error('projectKey is required in file mode');
+        }
+        const writer = new writer_1.FsWriter(options.file);
+        return new reporters_1.FileReporter(this.logger, writer);
+    }
+}
+exports.ReporterFactory = ReporterFactory;

package/dist/qanalyzer.d.ts

@@ -0,0 +1,29 @@
+import type { ConfigType } from './config';
+import { type IngestPayload, type JestVitestJsonReport } from './models';
+import { type OptionsType } from './options';
+export type PublishReportOptions = {
+    projectKey?: string;
+    launchName?: string;
+    format?: IngestPayload['format'];
+    planId?: string;
+    planKey?: string;
+    planName?: string;
+    fixVersion?: string;
+    sprintName?: string;
+};
+/**
+ * Thin orchestrator over OptionsResolver, ReporterFactory, and FallbackCoordinator.
+ * Framework adapters call `publishReport` with runner JSON at end of test run.
+ */
+export declare class QAnalyzerReporter {
+    private static instance;
+    private readonly options;
+    private readonly logger;
+    private readonly fallback;
+    private constructor();
+    static getInstance(options?: OptionsType): QAnalyzerReporter;
+    static resetInstance(): void;
+    getConfig(): ConfigType & OptionsType;
+    publishReport(report: JestVitestJsonReport, overrides?: PublishReportOptions): Promise<IngestPayload | undefined>;
+    private buildReporters;
+}

package/dist/qanalyzer.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QAnalyzerReporter = void 0;
+const env_1 = require("./env");
+const models_1 = require("./models");
+const options_1 = require("./options");
+const reporters_1 = require("./reporters");
+const utils_1 = require("./utils");
+const options_resolver_1 = require("./qanalyzer/options-resolver");
+const reporter_factory_1 = require("./qanalyzer/reporter-factory");
+/**
+ * Thin orchestrator over OptionsResolver, ReporterFactory, and FallbackCoordinator.
+ * Framework adapters call `publishReport` with runner JSON at end of test run.
+ */
+class QAnalyzerReporter {
+    static instance = null;
+    options;
+    logger;
+    fallback;
+    constructor(options = {}) {
+        const resolved = new options_resolver_1.OptionsResolver().resolve(options);
+        this.options = resolved.composed;
+        this.logger = new utils_1.Logger(Boolean(this.options.debug));
+        this.logger.logDebug(`Config: ${JSON.stringify((0, utils_1.sanitizeOptionsForLog)(resolved.composed))}`);
+        const factory = new reporter_factory_1.ReporterFactory(this.logger);
+        const { upstream, fallback, disabled } = this.buildReporters(factory, resolved.effectiveMode, resolved.effectiveFallback);
+        this.fallback = new reporters_1.FallbackCoordinator(this.logger, upstream, fallback);
+        if (disabled) {
+            this.fallback.setDisabled(true);
+        }
+    }
+    static getInstance(options = {}) {
+        if (!QAnalyzerReporter.instance) {
+            QAnalyzerReporter.instance = new QAnalyzerReporter(options);
+        }
+        return QAnalyzerReporter.instance;
+    }
+    static resetInstance() {
+        QAnalyzerReporter.instance = null;
+    }
+    getConfig() {
+        return this.options;
+    }
+    async publishReport(report, overrides = {}) {
+        const projectKey = overrides.projectKey ?? this.options.projectKey;
+        if (!projectKey) {
+            throw new Error('projectKey is required to publish a report');
+        }
+        const payload = (0, models_1.buildIngestPayload)({
+            projectKey,
+            report,
+            launchName: overrides.launchName ?? this.options.launchName,
+            format: overrides.format,
+            planId: overrides.planId ?? this.options.planId,
+            planKey: overrides.planKey ?? this.options.planKey,
+            planName: overrides.planName ?? this.options.planName,
+            fixVersion: overrides.fixVersion ?? this.options.fixVersion,
+            sprintName: overrides.sprintName ?? this.options.sprintName,
+            ci: (0, env_1.detectCiEnvironment)(),
+        });
+        if (this.fallback.isDisabled()) {
+            return undefined;
+        }
+        await this.fallback.run((reporter) => reporter.publishPayload(payload), 'publish report');
+        return payload;
+    }
+    buildReporters(factory, mode, fallbackMode) {
+        let upstream;
+        let fallback;
+        let disabled = false;
+        try {
+            upstream = factory.create(mode, this.options);
+        }
+        catch (error) {
+            if (error instanceof utils_1.DisabledException) {
+                disabled = true;
+            }
+            else {
+                this.logger.logError('Unable to create upstream reporter', error);
+            }
+        }
+        if (fallbackMode !== options_1.ModeEnum.off && fallbackMode !== mode) {
+            try {
+                fallback = factory.create(fallbackMode, this.options);
+            }
+            catch (error) {
+                this.logger.logError('Unable to create fallback reporter', error);
+            }
+        }
+        if (!upstream && !fallback) {
+            disabled = true;
+        }
+        return { upstream, fallback, disabled };
+    }
+}
+exports.QAnalyzerReporter = QAnalyzerReporter;

package/dist/reporters/fallback-coordinator.d.ts

@@ -0,0 +1,24 @@
+import type { LoggerInterface } from '../utils';
+import type { InternalReporterInterface } from './reporter-interface';
+export type FallbackCoordinatorCallbacks = {
+    onUpstreamFailure?: () => void;
+    onFallbackFailure?: () => void;
+    onFallbackActivated?: () => void;
+    onDisabled?: () => void;
+};
+/** Upstream ingest → fallback file cascade. */
+export declare class FallbackCoordinator {
+    private readonly logger;
+    private readonly upstream;
+    private readonly fallback;
+    private readonly callbacks;
+    private useFallback;
+    private disabled;
+    private onDisabledFired;
+    constructor(logger: LoggerInterface, upstream: InternalReporterInterface | undefined, fallback: InternalReporterInterface | undefined, callbacks?: FallbackCoordinatorCallbacks);
+    isDisabled(): boolean;
+    setDisabled(value: boolean): void;
+    run<T>(op: (reporter: InternalReporterInterface) => Promise<T>, opName: string): Promise<T | undefined>;
+    private disable;
+    private runOnFallback;
+}

package/dist/reporters/fallback-coordinator.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackCoordinator = void 0;
+/** Upstream ingest → fallback file cascade. */
+class FallbackCoordinator {
+    logger;
+    upstream;
+    fallback;
+    callbacks;
+    useFallback = false;
+    disabled = false;
+    onDisabledFired = false;
+    constructor(logger, upstream, fallback, callbacks = {}) {
+        this.logger = logger;
+        this.upstream = upstream;
+        this.fallback = fallback;
+        this.callbacks = callbacks;
+    }
+    isDisabled() {
+        return this.disabled;
+    }
+    setDisabled(value) {
+        this.disabled = value;
+    }
+    async run(op, opName) {
+        if (this.disabled)
+            return undefined;
+        if (this.useFallback) {
+            return this.runOnFallback(op, opName);
+        }
+        if (!this.upstream) {
+            if (!this.fallback)
+                return undefined;
+            this.useFallback = true;
+            return this.runOnFallback(op, opName);
+        }
+        try {
+            return await op(this.upstream);
+        }
+        catch (error) {
+            this.logger.logError(`Unable to ${opName} in the upstream reporter`, error);
+            this.callbacks.onUpstreamFailure?.();
+            if (!this.fallback) {
+                this.disable();
+                return undefined;
+            }
+            this.useFallback = true;
+            this.callbacks.onFallbackActivated?.();
+            return this.runOnFallback(op, opName);
+        }
+    }
+    disable() {
+        if (this.disabled)
+            return;
+        this.disabled = true;
+        if (!this.onDisabledFired) {
+            this.onDisabledFired = true;
+            this.callbacks.onDisabled?.();
+        }
+    }
+    async runOnFallback(op, opName) {
+        if (!this.fallback) {
+            this.disable();
+            return undefined;
+        }
+        try {
+            return await op(this.fallback);
+        }
+        catch (error) {
+            this.logger.logError(`Unable to ${opName} in the fallback reporter`, error);
+            this.callbacks.onFallbackFailure?.();
+            this.disable();
+            return undefined;
+        }
+    }
+}
+exports.FallbackCoordinator = FallbackCoordinator;

package/dist/reporters/file-reporter.d.ts

@@ -0,0 +1,10 @@
+import type { IngestPayload } from '../models';
+import { FsWriter } from '../writer';
+import type { LoggerInterface } from '../utils';
+import type { InternalReporterInterface } from './reporter-interface';
+export declare class FileReporter implements InternalReporterInterface {
+    private readonly writer;
+    private readonly logger;
+    constructor(logger: LoggerInterface, writer: FsWriter);
+    publishPayload(payload: IngestPayload): Promise<void>;
+}

package/dist/reporters/file-reporter.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileReporter = void 0;
+class FileReporter {
+    writer;
+    logger;
+    constructor(logger, writer) {
+        this.logger = logger;
+        this.writer = writer;
+    }
+    async publishPayload(payload) {
+        const path = this.writer.writePayload(payload);
+        this.logger.log(`Wrote ingest payload to ${path}`);
+    }
+}
+exports.FileReporter = FileReporter;

package/dist/reporters/index.d.ts

@@ -0,0 +1,4 @@
+export type { InternalReporterInterface } from './reporter-interface';
+export { IngestReporter } from './ingest-reporter';
+export { FileReporter } from './file-reporter';
+export { FallbackCoordinator, type FallbackCoordinatorCallbacks } from './fallback-coordinator';

package/dist/reporters/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackCoordinator = exports.FileReporter = exports.IngestReporter = void 0;
+var ingest_reporter_1 = require("./ingest-reporter");
+Object.defineProperty(exports, "IngestReporter", { enumerable: true, get: function () { return ingest_reporter_1.IngestReporter; } });
+var file_reporter_1 = require("./file-reporter");
+Object.defineProperty(exports, "FileReporter", { enumerable: true, get: function () { return file_reporter_1.FileReporter; } });
+var fallback_coordinator_1 = require("./fallback-coordinator");
+Object.defineProperty(exports, "FallbackCoordinator", { enumerable: true, get: function () { return fallback_coordinator_1.FallbackCoordinator; } });

package/dist/reporters/ingest-reporter.d.ts

@@ -0,0 +1,9 @@
+import { IngestClient } from '../client';
+import type { IngestPayload } from '../models';
+import type { LoggerInterface } from '../utils';
+import type { InternalReporterInterface } from './reporter-interface';
+export declare class IngestReporter implements InternalReporterInterface {
+    private readonly client;
+    constructor(logger: LoggerInterface, client: IngestClient);
+    publishPayload(payload: IngestPayload): Promise<void>;
+}

package/dist/reporters/ingest-reporter.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IngestReporter = void 0;
+class IngestReporter {
+    client;
+    constructor(logger, client) {
+        this.client = client;
+        void logger;
+    }
+    async publishPayload(payload) {
+        await this.client.send(payload);
+    }
+}
+exports.IngestReporter = IngestReporter;

package/dist/reporters/reporter-interface.d.ts

@@ -0,0 +1,4 @@
+import type { IngestPayload } from '../models';
+export interface InternalReporterInterface {
+    publishPayload(payload: IngestPayload): Promise<void>;
+}

package/dist/reporters/reporter-interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/disabled-exception.d.ts

@@ -0,0 +1,2 @@
+export declare class DisabledException extends Error {
+}

package/dist/utils/disabled-exception.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisabledException = void 0;
+class DisabledException extends Error {
+}
+exports.DisabledException = DisabledException;

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export { DisabledException } from './disabled-exception';
+export { Logger, type LoggerInterface } from './logger';
+export { maskToken, sanitizeOptionsForLog } from './token-masker';
+export { extractIssueKeys, firstIssueKey, projectKeyFromIssueKey, } from './issue-keys';
+export { uploadAttachmentForQa, EnvAttachEnum, type UploadAttachParams, type UploadAttachOutcome, } from './upload-attachment';

package/dist/utils/index.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvAttachEnum = exports.uploadAttachmentForQa = exports.projectKeyFromIssueKey = exports.firstIssueKey = exports.extractIssueKeys = exports.sanitizeOptionsForLog = exports.maskToken = exports.Logger = exports.DisabledException = void 0;
+var disabled_exception_1 = require("./disabled-exception");
+Object.defineProperty(exports, "DisabledException", { enumerable: true, get: function () { return disabled_exception_1.DisabledException; } });
+var logger_1 = require("./logger");
+Object.defineProperty(exports, "Logger", { enumerable: true, get: function () { return logger_1.Logger; } });
+var token_masker_1 = require("./token-masker");
+Object.defineProperty(exports, "maskToken", { enumerable: true, get: function () { return token_masker_1.maskToken; } });
+Object.defineProperty(exports, "sanitizeOptionsForLog", { enumerable: true, get: function () { return token_masker_1.sanitizeOptionsForLog; } });
+var issue_keys_1 = require("./issue-keys");
+Object.defineProperty(exports, "extractIssueKeys", { enumerable: true, get: function () { return issue_keys_1.extractIssueKeys; } });
+Object.defineProperty(exports, "firstIssueKey", { enumerable: true, get: function () { return issue_keys_1.firstIssueKey; } });
+Object.defineProperty(exports, "projectKeyFromIssueKey", { enumerable: true, get: function () { return issue_keys_1.projectKeyFromIssueKey; } });
+var upload_attachment_1 = require("./upload-attachment");
+Object.defineProperty(exports, "uploadAttachmentForQa", { enumerable: true, get: function () { return upload_attachment_1.uploadAttachmentForQa; } });
+Object.defineProperty(exports, "EnvAttachEnum", { enumerable: true, get: function () { return upload_attachment_1.EnvAttachEnum; } });

package/dist/utils/issue-keys.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Extract Jira issue keys from titles / tags (FR43) — shared with reporters for attach target.
+ */
+export declare function extractIssueKeys(...sources: Array<string | null | undefined>): string[];
+export declare function firstIssueKey(...sources: Array<string | null | undefined>): string | null;
+/** Project key prefix from AUTH-101 → AUTH. */
+export declare function projectKeyFromIssueKey(issueKey: string): string | null;

package/dist/utils/issue-keys.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractIssueKeys = extractIssueKeys;
+exports.firstIssueKey = firstIssueKey;
+exports.projectKeyFromIssueKey = projectKeyFromIssueKey;
+const ISSUE_KEY_RE = /\b([A-Z][A-Z0-9]+-\d+)\b/g;
+/**
+ * Extract Jira issue keys from titles / tags (FR43) — shared with reporters for attach target.
+ */
+function extractIssueKeys(...sources) {
+    const seen = new Set();
+    const keys = [];
+    for (const source of sources) {
+        if (!source)
+            continue;
+        for (const match of source.matchAll(ISSUE_KEY_RE)) {
+            const key = match[1];
+            if (key && !seen.has(key)) {
+                seen.add(key);
+                keys.push(key);
+            }
+        }
+    }
+    return keys;
+}
+function firstIssueKey(...sources) {
+    return extractIssueKeys(...sources)[0] ?? null;
+}
+/** Project key prefix from AUTH-101 → AUTH. */
+function projectKeyFromIssueKey(issueKey) {
+    const m = /^([A-Z][A-Z0-9]+)-\d+$/.exec(issueKey.trim().toUpperCase());
+    return m?.[1] ?? null;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,12 @@
+export interface LoggerInterface {
+    log(message: string): void;
+    logError(message: string, error?: unknown): void;
+    logDebug(message: string): void;
+}
+export declare class Logger implements LoggerInterface {
+    private readonly debugEnabled;
+    constructor(debugEnabled?: boolean);
+    log(message: string): void;
+    logError(message: string, error?: unknown): void;
+    logDebug(message: string): void;
+}

package/dist/utils/logger.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+class Logger {
+    debugEnabled;
+    constructor(debugEnabled = false) {
+        this.debugEnabled = debugEnabled;
+    }
+    log(message) {
+        console.log(`[INFO] qanalyzer: ${message}`);
+    }
+    logError(message, error) {
+        console.error(`[ERROR] qanalyzer: ${message}`, error ?? '');
+    }
+    logDebug(message) {
+        if (!this.debugEnabled)
+            return;
+        console.debug(`[DEBUG] qanalyzer: ${message}`);
+    }
+}
+exports.Logger = Logger;

package/dist/utils/token-masker.d.ts

@@ -0,0 +1,2 @@
+export declare function maskToken(token: string): string;
+export declare function sanitizeOptionsForLog<T>(options: T): T;

package/dist/utils/token-masker.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskToken = maskToken;
+exports.sanitizeOptionsForLog = sanitizeOptionsForLog;
+function maskToken(token) {
+    if (token.length <= 7) {
+        return '*'.repeat(token.length);
+    }
+    return `${token.slice(0, 3)}****${token.slice(-4)}`;
+}
+function sanitizeOptionsForLog(options) {
+    const sanitized = JSON.parse(JSON.stringify(options));
+    if (sanitized.ingest?.token) {
+        sanitized.ingest.token = maskToken(sanitized.ingest.token);
+    }
+    return sanitized;
+}

package/dist/utils/upload-attachment.d.ts

@@ -0,0 +1,35 @@
+import type { QaMetaAttachmentWire } from '../models/meta-qa';
+export declare const EnvAttachEnum: {
+    /** @deprecated Prefer QANALYZER_INGEST_URL — attach uses the shared ingest webtrigger. */
+    readonly url: "QANALYZER_ATTACH_URL";
+    readonly maxBytes: "QANALYZER_ATTACH_MAX_BYTES";
+};
+export type UploadAttachParams = {
+    /** Explicit issue key override. */
+    issueKey?: string;
+    /** Sources used to discover issue key (test title, tags, …). */
+    issueKeySources?: Array<string | null | undefined>;
+    projectKey?: string;
+    fileName?: string;
+    mimeType?: string;
+    content?: Buffer | Uint8Array | string;
+    /** Read file from disk when content omitted. */
+    path?: string;
+    attachUrl?: string;
+    token?: string;
+    maxBytes?: number;
+};
+export type UploadAttachOutcome = {
+    uploaded: true;
+    attachment: QaMetaAttachmentWire;
+    issueKey: string;
+} | {
+    uploaded: false;
+    attachment: QaMetaAttachmentWire;
+    reason: string;
+};
+/**
+ * Attempt Forge→Jira upload. On missing config/key/content, returns metadata-only (never throws
+ * unless you want callers to catch — this helper swallows upload errors into `uploaded: false`).
+ */
+export declare function uploadAttachmentForQa(params: UploadAttachParams): Promise<UploadAttachOutcome>;