@testmo/testmo-link 1.0.0-beta.0

package/dist/core/controller.js

@@ -0,0 +1,50 @@
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Controller = void 0;
+const logger_1 = require("../lib/logger");
+const errors_1 = require("../lib/errors");
+const validator_1 = __importDefault(require("validator"));
+const lodash_1 = __importDefault(require("lodash"));
+class Controller {
+    logControllerOptions(options) {
+        let debugOptions = lodash_1.default.clone(options);
+        if (debugOptions.testmoApiToken !== undefined) {
+            debugOptions.testmoApiToken = debugOptions.testmoApiToken.replace(/./g, '*');
+        }
+        logger_1.logger.debug('Controller options', debugOptions);
+    }
+    validateAndTruncateInstanceAddress(address) {
+        if (validator_1.default.isEmpty(address)) {
+            throw new errors_1.ValidationError('The Testmo instance address cannot be empty');
+        }
+        if (!validator_1.default.isURL(address, { require_tld: false, require_protocol: true })) {
+            throw new errors_1.ValidationError('The Testmo instance address must be a valid URL');
+        }
+        const isLocalhost = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?(\/.*)?$/.test(address);
+        if (!isLocalhost && !validator_1.default.isURL(address, { protocols: ['https'] })) {
+            throw new errors_1.ValidationError('The Testmo instance address must use HTTPS');
+        }
+        return new URL(address).origin;
+    }
+    validateProxy(proxy) {
+        if (proxy === undefined) {
+            return;
+        }
+        if (!validator_1.default.isURL(proxy, {
+            protocols: ['http', 'https'],
+            require_tld: false,
+            require_protocol: true,
+        })) {
+            throw new errors_1.ValidationError('The proxy address must be a valid HTTP/HTTPS address');
+        }
+    }
+}
+exports.Controller = Controller;

package/dist/index.js

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander = __importStar(require("commander"));
+const chalk_1 = __importDefault(require("chalk"));
+const logger_1 = require("./lib/logger");
+const errors_1 = require("./lib/errors");
+const automationLink_1 = require("./controller/automationLink");
+// @ts-ignore
+const packageInfo = __importStar(require("../package.json"));
+let ansi = !!process.stdout.isTTY && !(process.env.CI === 'true');
+logger_1.logger.ansi = ansi;
+function printError(err) {
+    if (err instanceof errors_1.ConfigError) {
+        logger_1.logger.error(err.message);
+        return;
+    }
+    if (err instanceof errors_1.PatternError) {
+        logger_1.logger.error(`Pattern configuration error: ${err.message}`);
+        return;
+    }
+    if (err instanceof errors_1.AnnotationError) {
+        const loc = err.line !== null ? `:${err.line}` : '';
+        logger_1.logger.error(`Annotation error in ${err.file}${loc}: ${err.message}`);
+        logger_1.logger.debug(`  Raw text: ${err.rawText}`);
+        return;
+    }
+    if (err instanceof errors_1.ApiError) {
+        logger_1.logger.error(`API error (${err.statusCode}): ${err.message}`);
+        return;
+    }
+    const printApiError = (apiError) => {
+        if (apiError.body && apiError.status) {
+            const message = apiError.body.message || '[none]';
+            logger_1.logger.error(`Server response (${apiError.status}): ${message}`);
+            if (apiError.status === 401) {
+                logger_1.logger.error('Please verify your Testmo API token');
+            }
+            else if (apiError.status === 422 && 'errors' in apiError.body) {
+                for (const field in apiError.body.errors) {
+                    const errs = apiError.body.errors[field];
+                    if (Array.isArray(errs) && errs.length > 0) {
+                        logger_1.logger.error(`Validation: ${errs[0]}`);
+                    }
+                }
+            }
+            logger_1.logger.stack(apiError.error);
+        }
+        else {
+            logger_1.logger.exception(apiError.error);
+        }
+    };
+    if (err instanceof Error) {
+        logger_1.logger.exception(err);
+    }
+    else if (err instanceof Object && 'response' in err && 'error' in err) {
+        printApiError(err);
+    }
+    else if (err instanceof Object && 'error' in err &&
+        err.error instanceof Error) {
+        err.error.message = `Connection error: ${err.error.message}`;
+        logger_1.logger.exception(err.error);
+    }
+    else {
+        logger_1.logger.error(err);
+    }
+}
+const program = new commander.Command();
+program.name('testmo-link');
+program.version(packageInfo.version, '-V, --version', 'Output the version number');
+program.description('Link automation test results to repository test cases in Testmo.\n\n' +
+    'Set TESTMO_TOKEN environment variable to your API token.');
+program.helpOption('-h, --help', 'Display help');
+program.option('--ansi', 'Force ANSI console output (colors)');
+program.option('--no-ansi', 'Do not use ANSI console output (colors)');
+program.option('--verbose', 'Enable detailed output');
+program.requiredOption('--instance <url>', 'Required: The full address of your Testmo instance (https://***.testmo.net)');
+program.requiredOption('--project-id <id>', 'Required: The ID of the project');
+program.requiredOption('--run-id <id>', 'Required: The ID of the automation run to link');
+program.option('--config <file>', 'Path to a YAML or JSON configuration file with linking rules');
+program.option('--dry-run', 'Preview what links would be created without making any changes');
+program.option('--force', 'Re-link tests that are already linked to a repository case');
+program.option('--fail-on-unmatched', 'Exit with code 1 if any tests could not be matched to a repository case');
+program.option('--conflict-resolution <mode>', 'How to handle conflicts between linking methods: error, warn, silent (default: error)');
+program.option('--proxy <address>', 'An optional HTTP(S) proxy server to use for all connections');
+program.option('--output <file>', 'Write all log output to a file (always includes debug detail regardless of --verbose flag)');
+program.addHelpText('after', '\nExamples:\n\n' +
+    '  $ TESTMO_TOKEN=**** testmo-link \\\n' +
+    '      --instance https://my-company.testmo.net \\\n' +
+    '      --project-id 1 \\\n' +
+    '      --run-id 123 \\\n' +
+    '      --config linking.yml\n\n' +
+    '  $ TESTMO_TOKEN=**** testmo-link \\\n' +
+    '      --instance https://my-company.testmo.net \\\n' +
+    '      --project-id 1 \\\n' +
+    '      --run-id 123 \\\n' +
+    '      --config linking.yml \\\n' +
+    '      --dry-run\n\n' +
+    'Documentation:\n\n' +
+    '  https://docs.testmo.com/automation-linking');
+program.on('option:verbose', () => {
+    logger_1.logger.level = logger_1.LogLevel.Debug;
+    logger_1.logger.debug(`Testmo Link/${packageInfo.version}`);
+    logger_1.logger.debug('ANSI output', ansi);
+});
+program.on('option:output', (file) => {
+    logger_1.logger.outputFile = file.trim();
+});
+program.on('option:ansi', () => {
+    ansi = true;
+    logger_1.logger.ansi = true;
+});
+program.on('option:no-ansi', () => {
+    ansi = false;
+    logger_1.logger.ansi = false;
+});
+program.configureOutput({
+    outputError: (str, write) => {
+        if (ansi) {
+            write(chalk_1.default.red(str));
+        }
+        else {
+            write(str);
+        }
+    }
+});
+program.action(async (options) => {
+    var _a, _b, _c, _d, _e, _f, _g;
+    try {
+        const controller = new automationLink_1.AutomationLink();
+        const exitCode = await controller.run({
+            testmoInstanceAddress: (_b = (_a = options.instance) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '',
+            testmoApiToken: (_c = process.env.TESTMO_TOKEN) === null || _c === void 0 ? void 0 : _c.trim(),
+            projectId: (_e = (_d = options.projectId) === null || _d === void 0 ? void 0 : _d.trim()) !== null && _e !== void 0 ? _e : '',
+            runId: (_g = (_f = options.runId) === null || _f === void 0 ? void 0 : _f.trim()) !== null && _g !== void 0 ? _g : '',
+            configFile: options.config ? options.config.trim() : undefined,
+            dryRun: options.dryRun === true,
+            force: options.force === true,
+            failOnUnmatched: options.failOnUnmatched === true,
+            conflictResolution: options.conflictResolution
+                ? options.conflictResolution.trim()
+                : undefined,
+            proxy: options.proxy ? options.proxy.trim() : undefined,
+        });
+        if (exitCode !== 0) {
+            logger_1.logger.debug(`Exiting with exit code ${exitCode}`);
+            process.exit(exitCode);
+        }
+    }
+    catch (err) {
+        printError(err);
+        process.exit(1);
+    }
+});
+try {
+    program.parse(process.argv);
+}
+catch (error) {
+    logger_1.logger.exception(error);
+    throw error;
+}

package/dist/lib/errors.js

@@ -0,0 +1,68 @@
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = exports.AnnotationError = exports.PatternError = exports.ConfigError = exports.ValidationError = void 0;
+class ValidationError extends Error {
+    constructor(m) {
+        super(m);
+        Object.setPrototypeOf(this, ValidationError.prototype);
+    }
+}
+exports.ValidationError = ValidationError;
+/**
+ * Thrown when a config file cannot be found, read, or parsed.
+ * Extends ValidationError so existing `instanceof ValidationError` guards still match.
+ */
+class ConfigError extends ValidationError {
+    constructor(message, filePath) {
+        super(message);
+        this.filePath = filePath;
+        Object.setPrototypeOf(this, ConfigError.prototype);
+    }
+}
+exports.ConfigError = ConfigError;
+/**
+ * Thrown when a regex annotation pattern is unsafe or fails to compile.
+ * Extends ValidationError so it is treated as a startup validation failure.
+ */
+class PatternError extends ValidationError {
+    constructor(pattern, compilationError) {
+        super(`Invalid pattern "${pattern}": ${compilationError}`);
+        this.pattern = pattern;
+        this.compilationError = compilationError;
+        Object.setPrototypeOf(this, PatternError.prototype);
+    }
+}
+exports.PatternError = PatternError;
+/**
+ * Thrown when an annotation in a source file cannot be parsed.
+ * Carries the file path, line number, and raw annotation text for context.
+ */
+class AnnotationError extends Error {
+    constructor(message, file, line, rawText) {
+        super(message);
+        this.file = file;
+        this.line = line;
+        this.rawText = rawText;
+        Object.setPrototypeOf(this, AnnotationError.prototype);
+    }
+}
+exports.AnnotationError = AnnotationError;
+/**
+ * Thrown when an API call fails with a specific HTTP error that provides
+ * enough context to surface a targeted message to the user (e.g. 404 on a
+ * case ID that no longer exists).
+ */
+class ApiError extends Error {
+    constructor(message, statusCode, context = {}) {
+        super(message);
+        this.statusCode = statusCode;
+        this.context = context;
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+exports.ApiError = ApiError;

package/dist/lib/logger.js

@@ -0,0 +1,117 @@
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.Logger = exports.LogLevel = void 0;
+/* eslint-disable no-unused-vars, no-shadow, no-console */
+const chalk_1 = __importDefault(require("chalk"));
+const fs_1 = __importDefault(require("fs"));
+var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["Debug"] = 0] = "Debug";
+    LogLevel[LogLevel["Info"] = 1] = "Info";
+    LogLevel[LogLevel["Warning"] = 2] = "Warning";
+    LogLevel[LogLevel["Error"] = 3] = "Error";
+    LogLevel[LogLevel["Silent"] = 4] = "Silent";
+})(LogLevel || (exports.LogLevel = LogLevel = {}));
+// Strip ANSI escape codes for plain-text file output
+function stripAnsi(s) {
+    // eslint-disable-next-line no-control-regex
+    return s.replace(/\x1B\[[0-9;]*m/g, '');
+}
+class Logger {
+    constructor(level = LogLevel.Info, ansi = false) {
+        this.outputFile = null;
+        this.level = level;
+        this.ansi = ansi;
+    }
+    writeToFile(message, ...args) {
+        if (!this.outputFile)
+            return;
+        try {
+            const parts = [message, ...args.map((a) => typeof a === 'object' ? JSON.stringify(a) : String(a))];
+            fs_1.default.appendFileSync(this.outputFile, stripAnsi(parts.join(' ')) + '\n', 'utf8');
+        }
+        catch (_a) {
+            // Silently ignore file write errors to avoid masking real output
+        }
+    }
+    debug(message, ...args) {
+        if (this.level <= LogLevel.Debug) {
+            if (this.ansi) {
+                console.log(chalk_1.default.yellow(message), ...args);
+            }
+            else {
+                console.log(message, ...args);
+            }
+        }
+        // Always write debug to file when output is set (even if not shown on terminal)
+        this.writeToFile(`[debug] ${message}`, ...args);
+    }
+    info(message, ...args) {
+        if (this.level <= LogLevel.Info) {
+            console.log(message, ...args);
+        }
+        if (this.outputFile)
+            this.writeToFile(message, ...args);
+    }
+    warn(message, ...args) {
+        if (this.level <= LogLevel.Warning) {
+            if (this.ansi) {
+                console.warn(chalk_1.default.yellow(message), ...args);
+            }
+            else {
+                console.warn(message, ...args);
+            }
+        }
+        if (this.outputFile)
+            this.writeToFile(`[warn] ${message}`, ...args);
+    }
+    error(message, ...args) {
+        if (this.level <= LogLevel.Error) {
+            if (this.ansi) {
+                console.error(chalk_1.default.red(message), ...args);
+            }
+            else {
+                console.error(message, ...args);
+            }
+        }
+        if (this.outputFile)
+            this.writeToFile(`[error] ${message}`, ...args);
+    }
+    stack(error) {
+        if (this.level <= LogLevel.Debug) {
+            if (this.ansi) {
+                console.error(chalk_1.default.gray(error instanceof Error ? error.stack : error));
+            }
+            else {
+                console.error(error instanceof Error ? error.stack : error);
+            }
+        }
+        if (this.outputFile) {
+            this.writeToFile(`[debug] ${error instanceof Error ? error.stack : String(error)}`);
+        }
+    }
+    exception(error) {
+        if (this.level <= LogLevel.Error) {
+            if (this.ansi) {
+                console.error(chalk_1.default.red(error instanceof Error ? error.message : error));
+            }
+            else {
+                console.error(error instanceof Error ? error.message : error);
+            }
+        }
+        if (this.outputFile) {
+            this.writeToFile(`[error] ${error instanceof Error ? error.message : String(error)}`);
+        }
+        this.stack(error);
+    }
+}
+exports.Logger = Logger;
+exports.logger = new Logger();

package/dist/lib/retry.js

@@ -0,0 +1,67 @@
+"use strict";
+/*
+ * Copyright (c) Testmo GmbH (Berlin, Germany)
+ * All rights reserved.
+ * contact@testmo.com - www.testmo.com
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const logger_1 = require("./logger");
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 1000;
+const MAX_RATE_LIMIT_RETRIES = 5;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+function getStatus(err) {
+    var _a, _b;
+    return (_b = (_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.status) !== null && _b !== void 0 ? _b : err === null || err === void 0 ? void 0 : err.status;
+}
+function isRetryable(status) {
+    // Retry on network errors (no status) or 5xx server errors
+    return status === undefined || (status >= 500 && status < 600);
+}
+/**
+ * Wraps an async API call with retry logic including exponential backoff
+ * and automatic 429 rate-limit detection.
+ *
+ * - 429 responses: respects the Retry-After header (defaults to 60s),
+ *   retried up to MAX_RATE_LIMIT_RETRIES times without counting against
+ *   the normal retry budget.
+ * - 5xx / network errors: retried up to maxRetries times with exponential
+ *   backoff starting at 1s (1s, 2s, 4s, …).
+ * - 4xx (except 429): not retried — these indicate caller errors.
+ */
+async function withRetry(fn, maxRetries = MAX_RETRIES) {
+    var _a, _b;
+    let attempt = 0;
+    let rateLimitAttempt = 0;
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            const status = getStatus(err);
+            if (status === 429) {
+                rateLimitAttempt++;
+                if (rateLimitAttempt > MAX_RATE_LIMIT_RETRIES) {
+                    throw err;
+                }
+                const retryAfterHeader = (_b = (_a = err === null || err === void 0 ? void 0 : err.response) === null || _a === void 0 ? void 0 : _a.headers) === null || _b === void 0 ? void 0 : _b['retry-after'];
+                const parsed = retryAfterHeader ? parseInt(retryAfterHeader, 10) : NaN;
+                const waitMs = isNaN(parsed) ? 60000 : parsed * 1000;
+                logger_1.logger.warn(`Rate limited by API. Waiting ${Math.round(waitMs / 1000)}s before retrying ` +
+                    `(rate-limit attempt ${rateLimitAttempt}/${MAX_RATE_LIMIT_RETRIES})...`);
+                await sleep(waitMs);
+                continue;
+            }
+            attempt++;
+            if (attempt > maxRetries || !isRetryable(status)) {
+                throw err;
+            }
+            const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1); // 1s, 2s, 4s
+            logger_1.logger.debug(`API call failed (attempt ${attempt}/${maxRetries}), retrying in ${delay}ms...`);
+            await sleep(delay);
+        }
+    }
+}