@tiden/reporter-commons 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## 0.3.0
+
+- **`resolveFilePath` and `isUsableFilePath` on the `/internal` entry point.** The rule behind
+  every reporter's `fields.file_path`, which is the key the server joins a requirement's
+  repo-relative `repo_file` anchors against. Deliberately NOT `normalizeSpecPath`: that one
+  returns a path outside the root unchanged, which is right for a signature segment and wrong
+  for a join key — an absolute machine path or a virtual module id can never match an anchor,
+  so it would be a field that looks like a join key and silently never joins. `undefined`
+  means omit; omitting is not fabricating.
+- **`resolveFilePath` resolves the root rather than trusting the string.** A relative root
+  (`..`, `.`, or `''` from a config file) matched no absolute test path, so every file was
+  omitted for the whole run while the warning told the user to set the variable they had just
+  set. Relative roots now resolve against cwd, `.`/`..` segments are collapsed on both sides,
+  and a symlinked root — `/tmp/x` while the runner emits `/private/tmp/x/...` on macOS — is
+  compared again via `realpath`, memoized and only after the plain comparison fails.
+  `tiden-phpunit-reporter`'s `FilePathResolver` already did this for the same macOS reason.
+- **`normalizeSpecPath` and `resolveRootDir` are deliberately unchanged.** They feed the case
+  SIGNATURE, and changing how a root resolves would change the file segment of every signature
+  computed under a relative or symlinked root — forking the history of every case already
+  reported under the old spelling. A join key can be corrected; an identity cannot.
+
+## 0.2.0
+
+- **`rootDir` / `TIDEN_ROOT_DIR` option**, plus `normalizeSpecPath` and `resolveRootDir` on the
+  `/internal` entry point: the base a case signature's spec-file segment is resolved against,
+  defaulting to `process.cwd()`. Consumed by `@tiden/vitest-reporter` and `@tiden/jest-reporter`.
+  Env is read directly by `resolveRootDir` rather than through `OptionsResolver`, whose composed
+  result never reaches a framework reporter — resolving it any other way leaves `TIDEN_ROOT_DIR`
+  silently ignored while looking configured.
+- **Fixed a polynomial ReDoS in `normalizeSpecPath`.** The root's trailing slashes were trimmed
+  with `/\/+$/`, which backtracks quadratically on a root of repeated slashes — and the root is
+  configurable (`rootDir` / `TIDEN_ROOT_DIR`). Measured at 546ms for a 40k-character root against
+  0ms for the scan that replaces it. Caught by CodeQL (`js/polynomial-redos`) before release; same
+  class as the step-marker parser fixed in 0.1.1.
+- **Fixed: `TIDEN_FALLBACK` was silently ignored.** It was declared in `EnvEnum`, `EnvType` and the
+  env validation schema, but `envToConfig` never mapped it into `ConfigType` — so the value
+  validated and was then dropped. It decides what happens when `tiden` mode cannot start, which is
+  the disable path below.
+- **A reporter that stops MID-RUN says so too.** `FallbackCoordinator.disable()` turned reporting
+  off after an upstream (and fallback) failure while logging only the error, not the consequence:
+  the suite carried on, every later result went nowhere, and the run ended green. A present-but-
+  rejected token reached the same silent failure as a missing one by a different path.
+- **The credential list is no longer appended to every disabled message.** It is stated where a
+  missing setting is a live suspect, and omitted where the error above is the answer — a message
+  padded with the same tail every time stops being read.
+- **`buildReporters` says why it disabled the reporter.** Both disabling paths — a config
+  `mode`/`fallback` of `off`, and a `tiden` mode that cannot start because one of the four
+  required settings is missing — used to set `disabled = true` with no output. A disabled reporter
+  is indistinguishable from a working one, which cost a user an hour. Each branch now announces
+  itself through `logReporterDisabled`, naming the reason, the remedy, and the credentials
+  `createRunReporter` requires. Deliberately `logger.log`, not `logDebug`.
+
 ## 0.1.1
 
 - **Fixed a polynomial ReDoS in `extractAndCleanStep`** (CodeQL `js/polynomial-redos`, high).

package/dist/config/config-validation-schema.d.ts

@@ -32,6 +32,10 @@ export declare const configValidationSchema: {
             type: string;
             nullable: boolean;
         };
+        rootDir: {
+            type: string;
+            nullable: boolean;
+        };
         statusMapping: {
             type: string;
             nullable: boolean;

package/dist/config/config-validation-schema.js

@@ -35,6 +35,10 @@ exports.configValidationSchema = {
             type: 'string',
             nullable: true,
         },
+        rootDir: {
+            type: 'string',
+            nullable: true,
+        },
         statusMapping: {
             type: 'object',
             nullable: true,

package/dist/env/env-enum.d.ts

@@ -8,6 +8,7 @@ export declare enum EnvEnum {
     environment = "TIDEN_ENVIRONMENT",
     captureLogs = "TIDEN_CAPTURE_LOGS",
     rootSuite = "TIDEN_ROOT_SUITE",
+    rootDir = "TIDEN_ROOT_DIR",
     statusMapping = "TIDEN_STATUS_MAPPING"
 }
 /**

package/dist/env/env-enum.js

@@ -12,6 +12,7 @@ var EnvEnum;
     EnvEnum["environment"] = "TIDEN_ENVIRONMENT";
     EnvEnum["captureLogs"] = "TIDEN_CAPTURE_LOGS";
     EnvEnum["rootSuite"] = "TIDEN_ROOT_SUITE";
+    EnvEnum["rootDir"] = "TIDEN_ROOT_DIR";
     EnvEnum["statusMapping"] = "TIDEN_STATUS_MAPPING";
 })(EnvEnum || (exports.EnvEnum = EnvEnum = {}));
 /**

package/dist/env/env-to-config.js

@@ -9,10 +9,16 @@ const writer_1 = require("../writer");
  */
 const envToConfig = (env) => ({
     mode: env[env_enum_1.EnvEnum.mode],
+    // TIDEN_FALLBACK was declared in EnvEnum, EnvType and the validation schema
+    // but never mapped here, so setting it did nothing: the value validated, then
+    // vanished. It decides what happens when `tiden` mode cannot start, which is
+    // exactly the silent-disable path the reporter now announces.
+    fallback: env[env_enum_1.EnvEnum.fallback],
     debug: env[env_enum_1.EnvEnum.debug],
     environment: env[env_enum_1.EnvEnum.environment],
     captureLogs: env[env_enum_1.EnvEnum.captureLogs],
     rootSuite: env[env_enum_1.EnvEnum.rootSuite],
+    rootDir: env[env_enum_1.EnvEnum.rootDir],
     statusMapping: env[env_enum_1.EnvEnum.statusMapping] ?
         Object.fromEntries(env[env_enum_1.EnvEnum.statusMapping].split(',').map(item => {
             const [from, to] = item.split('=');

package/dist/env/env-type.d.ts

@@ -8,6 +8,7 @@ export interface EnvType {
     [EnvEnum.environment]?: string;
     [EnvEnum.captureLogs]?: boolean;
     [EnvEnum.rootSuite]?: string;
+    [EnvEnum.rootDir]?: string;
     [EnvEnum.statusMapping]?: string;
     [EnvTidenEnum.product]?: string;
     [EnvTidenEnum.uploadAttachments]?: boolean;

package/dist/env/env-validation-schema.js

@@ -36,6 +36,10 @@ exports.envValidationSchema = {
             type: 'string',
             nullable: true,
         },
+        [env_enum_1.EnvEnum.rootDir]: {
+            type: 'string',
+            nullable: true,
+        },
         [env_enum_1.EnvEnum.statusMapping]: {
             type: 'string',
             nullable: true,

package/dist/internal/index.d.ts

@@ -6,3 +6,7 @@ export type { FileSuiteNode } from './suite-file';
 export { parseTidenIdsFromString } from './ids-parser';
 export { filterPositiveIds } from './filter-positive-ids';
 export { normalizeSuitePart } from './suite-normalizer';
+export { normalizeSpecPath } from './spec-path';
+export { resolveRootDir } from './spec-path';
+export { resolveFilePath } from './spec-path';
+export { isUsableFilePath } from './spec-path';

package/dist/internal/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeSuitePart = exports.filterPositiveIds = exports.parseTidenIdsFromString = exports.getFile = exports.extractAndCleanStep = exports.removeTidenIdsFromTitle = void 0;
+exports.isUsableFilePath = exports.resolveFilePath = exports.resolveRootDir = exports.normalizeSpecPath = exports.normalizeSuitePart = exports.filterPositiveIds = exports.parseTidenIdsFromString = exports.getFile = exports.extractAndCleanStep = exports.removeTidenIdsFromTitle = void 0;
 var title_1 = require("./title");
 Object.defineProperty(exports, "removeTidenIdsFromTitle", { enumerable: true, get: function () { return title_1.removeTidenIdsFromTitle; } });
 var step_parser_1 = require("./step-parser");
@@ -13,3 +13,11 @@ var filter_positive_ids_1 = require("./filter-positive-ids");
 Object.defineProperty(exports, "filterPositiveIds", { enumerable: true, get: function () { return filter_positive_ids_1.filterPositiveIds; } });
 var suite_normalizer_1 = require("./suite-normalizer");
 Object.defineProperty(exports, "normalizeSuitePart", { enumerable: true, get: function () { return suite_normalizer_1.normalizeSuitePart; } });
+var spec_path_1 = require("./spec-path");
+Object.defineProperty(exports, "normalizeSpecPath", { enumerable: true, get: function () { return spec_path_1.normalizeSpecPath; } });
+var spec_path_2 = require("./spec-path");
+Object.defineProperty(exports, "resolveRootDir", { enumerable: true, get: function () { return spec_path_2.resolveRootDir; } });
+var spec_path_3 = require("./spec-path");
+Object.defineProperty(exports, "resolveFilePath", { enumerable: true, get: function () { return spec_path_3.resolveFilePath; } });
+var spec_path_4 = require("./spec-path");
+Object.defineProperty(exports, "isUsableFilePath", { enumerable: true, get: function () { return spec_path_4.isUsableFilePath; } });

package/dist/internal/spec-path.d.ts

@@ -0,0 +1,69 @@
+export declare function normalizeSpecPath(fullPath: string, cwd?: string): string;
+/**
+ * The base a spec-file segment is resolved against, in precedence order:
+ * an explicit `rootDir` option, then `TIDEN_ROOT_DIR`, then undefined
+ * (meaning `normalizeSpecPath` falls back to `process.cwd()`).
+ *
+ * Env is read here rather than through the usual config pipeline because that
+ * pipeline merges env inside `OptionsResolver`, whose result never reaches a
+ * framework reporter — so a framework-side setting would silently ignore its
+ * own environment variable.
+ */
+export declare function resolveRootDir(explicit?: string | undefined): string | undefined;
+/**
+ * The repo-relative source file of a test, for the `file_path` result field.
+ *
+ * Held to a stricter standard than `normalizeSpecPath`, which returns a path
+ * outside the root unchanged. `file_path` is the key the server joins a
+ * requirement's repo-relative `repo_file` anchors against, so an absolute
+ * machine path — or a virtual module id — can never match one: reporting it
+ * yields a field that looks like a join key and silently never joins.
+ * `undefined` means "omit the field", and the caller warns. Omitting is not
+ * fabricating; it is what the Go CLI's filemap and the PHPUnit reporter's
+ * FilePathResolver already do.
+ *
+ * Unlike `normalizeSpecPath` this is NOT purely path-shaped, because the root
+ * is user-supplied and three plausible spellings of the same directory would
+ * otherwise turn the feature off for a whole run:
+ *   - a RELATIVE root (`..`, `.`, `''` from a config file) matches no absolute
+ *     test path, so every file is omitted and the warning tells the user to set
+ *     the variable they just set. Resolved against cwd.
+ *   - UNNORMALIZED segments (`/repo/tests/../src/a.ts`) pass through verbatim
+ *     and can never match an anchor. Collapsed.
+ *   - a SYMLINKED root — `/tmp/checkout` on macOS while the runner emits
+ *     `/private/tmp/checkout/...` — mismatches as a string. Compared again via
+ *     realpath, and only when the plain comparison already failed, so the happy
+ *     path touches the filesystem at most once per distinct root.
+ * `repos/phpunit`'s FilePathResolver calls realpath() on both sides for exactly
+ * the macOS /tmp reason; this brings the JS rule in line with it.
+ *
+ * Deliberately NOT applied to `normalizeSpecPath`/`resolveRootDir`: those feed
+ * the case SIGNATURE, and changing how a root resolves would change the file
+ * segment of every signature computed under a relative or symlinked root —
+ * forking the history of every case already reported under the old spelling.
+ * A join key can be corrected; an identity cannot.
+ *
+ * Note what this still cannot detect: a path that resolves cleanly against the
+ * WRONG root. Playwright run from `tests/api` with no `TIDEN_ROOT_DIR` yields
+ * `Tests/v1/x.api.spec.ts` — well-formed, matching no anchor. Set
+ * `rootDir`/`TIDEN_ROOT_DIR` to the repository root wherever the runner's cwd
+ * is not already it.
+ */
+export declare function resolveFilePath(fullPath: string, root?: string): string | undefined;
+/**
+ * Whether a `file_path` the TEST set for itself could ever match a requirement
+ * anchor.
+ *
+ * The reporters keep a test-provided `file_path` — it may deliberately name the
+ * source file under test rather than the spec's own location — but the value is
+ * held to the same standard a derived one is: anchors are repo-relative, so an
+ * absolute path, an empty string, or one that escapes the root is unlinkable by
+ * construction. Keeping such a value would let a hand-written field do the one
+ * thing the resolver refuses to do, which is fabricate a link that never joins.
+ *
+ * This deliberately does NOT decide the larger question of whether a test
+ * should be able to override `file_path` at all — `tiden-phpunit-reporter`'s
+ * AttributeReader drops a hand-written `#[Field('file_path')]` outright. That
+ * divergence is a product decision, recorded in the PR, not settled here.
+ */
+export declare function isUsableFilePath(value: string): boolean;

package/dist/internal/spec-path.js

@@ -0,0 +1,227 @@
+"use strict";
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSpecPath = normalizeSpecPath;
+exports.resolveRootDir = resolveRootDir;
+exports.resolveFilePath = resolveFilePath;
+exports.isUsableFilePath = isUsableFilePath;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const env_enum_1 = require("../env/env-enum");
+/**
+ * Normalizes an absolute spec-file path to a project-relative one, for use as
+ * the leading segment of a case signature.
+ *
+ * Kept as a SINGLE segment with its slashes intact — it is not split on `/`.
+ * That matches Playwright's `titlePath()` (which yields the spec file as one
+ * element) and the app-side vitest CI transform, so a case reported by the
+ * reporter and the same case reported by CI resolve to one identity.
+ *
+ * Path-shaped only: no filesystem access, and an id that does not live under
+ * `cwd` (a Vite virtual module, for instance) is returned unchanged rather
+ * than forced into a relative form.
+ */
+const SLASH = '/'.charCodeAt(0);
+function normalizeSpecPath(fullPath, cwd = process.cwd()) {
+    const normalized = fullPath.replace(/\\/g, '/');
+    const root = rootPrefix(cwd);
+    return normalized.startsWith(root) ? normalized.slice(root.length) : normalized;
+}
+/**
+ * The root as a `/`-terminated prefix, with any trailing slashes collapsed to
+ * exactly one.
+ *
+ * Trimmed by scanning rather than with `/\/+$/`: that pattern backtracks
+ * quadratically on a root of many slashes, and the root can come from
+ * configuration (`rootDir` / `TIDEN_ROOT_DIR`). Same class of defect as the
+ * step-marker parser fixed in commons 0.1.1 — keep this regex-free.
+ */
+function rootPrefix(cwd) {
+    const normalized = cwd.replace(/\\/g, '/');
+    let end = normalized.length;
+    while (end > 0 && normalized.charCodeAt(end - 1) === SLASH) {
+        end -= 1;
+    }
+    return normalized.slice(0, end) + '/';
+}
+/**
+ * The base a spec-file segment is resolved against, in precedence order:
+ * an explicit `rootDir` option, then `TIDEN_ROOT_DIR`, then undefined
+ * (meaning `normalizeSpecPath` falls back to `process.cwd()`).
+ *
+ * Env is read here rather than through the usual config pipeline because that
+ * pipeline merges env inside `OptionsResolver`, whose result never reaches a
+ * framework reporter — so a framework-side setting would silently ignore its
+ * own environment variable.
+ */
+function resolveRootDir(explicit) {
+    const fromEnv = process.env[env_enum_1.EnvEnum.rootDir];
+    return explicit ?? (fromEnv !== undefined && fromEnv !== '' ? fromEnv : undefined);
+}
+/**
+ * The repo-relative source file of a test, for the `file_path` result field.
+ *
+ * Held to a stricter standard than `normalizeSpecPath`, which returns a path
+ * outside the root unchanged. `file_path` is the key the server joins a
+ * requirement's repo-relative `repo_file` anchors against, so an absolute
+ * machine path — or a virtual module id — can never match one: reporting it
+ * yields a field that looks like a join key and silently never joins.
+ * `undefined` means "omit the field", and the caller warns. Omitting is not
+ * fabricating; it is what the Go CLI's filemap and the PHPUnit reporter's
+ * FilePathResolver already do.
+ *
+ * Unlike `normalizeSpecPath` this is NOT purely path-shaped, because the root
+ * is user-supplied and three plausible spellings of the same directory would
+ * otherwise turn the feature off for a whole run:
+ *   - a RELATIVE root (`..`, `.`, `''` from a config file) matches no absolute
+ *     test path, so every file is omitted and the warning tells the user to set
+ *     the variable they just set. Resolved against cwd.
+ *   - UNNORMALIZED segments (`/repo/tests/../src/a.ts`) pass through verbatim
+ *     and can never match an anchor. Collapsed.
+ *   - a SYMLINKED root — `/tmp/checkout` on macOS while the runner emits
+ *     `/private/tmp/checkout/...` — mismatches as a string. Compared again via
+ *     realpath, and only when the plain comparison already failed, so the happy
+ *     path touches the filesystem at most once per distinct root.
+ * `repos/phpunit`'s FilePathResolver calls realpath() on both sides for exactly
+ * the macOS /tmp reason; this brings the JS rule in line with it.
+ *
+ * Deliberately NOT applied to `normalizeSpecPath`/`resolveRootDir`: those feed
+ * the case SIGNATURE, and changing how a root resolves would change the file
+ * segment of every signature computed under a relative or symlinked root —
+ * forking the history of every case already reported under the old spelling.
+ * A join key can be corrected; an identity cannot.
+ *
+ * Note what this still cannot detect: a path that resolves cleanly against the
+ * WRONG root. Playwright run from `tests/api` with no `TIDEN_ROOT_DIR` yields
+ * `Tests/v1/x.api.spec.ts` — well-formed, matching no anchor. Set
+ * `rootDir`/`TIDEN_ROOT_DIR` to the repository root wherever the runner's cwd
+ * is not already it.
+ */
+function resolveFilePath(fullPath, root = process.cwd()) {
+    const file = collapse(fullPath);
+    const base = collapse(absoluteRoot(root));
+    const direct = relativeUnder(file, base);
+    if (direct !== undefined) {
+        return direct;
+    }
+    // Only now pay for the filesystem: a symlinked root (or file) is the one
+    // remaining way two spellings of the same location can differ as strings.
+    const realBase = collapse(realPathOrSelf(base));
+    const realFile = collapse(realPathOrSelf(file));
+    if (realBase === base && realFile === file) {
+        return undefined;
+    }
+    return relativeUnder(realFile, realBase);
+}
+/** `full` expressed relative to `base`, or undefined when it is not under it. */
+function relativeUnder(full, base) {
+    const prefix = rootPrefix(base);
+    if (!full.startsWith(prefix)) {
+        return undefined;
+    }
+    const relative = full.slice(prefix.length);
+    return relative === '' ? undefined : relative;
+}
+/**
+ * Backslashes to forward slashes, then `.`/`..` segments collapsed.
+ * `path.posix` regardless of host: the string is already slash-normalized, and
+ * a Windows path handed to a POSIX runner (or the reverse) must collapse the
+ * same way for the fixtures to mean anything.
+ */
+function collapse(value) {
+    return path.posix.normalize(value.replace(/\\/g, '/'));
+}
+/**
+ * A relative root resolved against cwd; an already-absolute one left alone.
+ *
+ * `path.resolve` is host-aware, so it cannot be applied unconditionally: on a
+ * POSIX runner it would turn the absolute Windows root `C:/repo` into
+ * `<cwd>/C:/repo`. The drive-letter test keeps that spelling absolute on both
+ * hosts. An empty root is relative by this test, so it resolves to cwd — which
+ * is what `normalizeSpecPath` already does with a falsy root, and closes the
+ * gap where `""` reported the absolute path minus its leading slash.
+ */
+function absoluteRoot(root) {
+    const slashed = root.replace(/\\/g, '/');
+    return isAbsoluteLike(slashed) ? slashed : path.resolve(root);
+}
+function isAbsoluteLike(value) {
+    return value.charCodeAt(0) === SLASH || /^[A-Za-z]:\//.test(value);
+}
+/** realpath, memoized per input; the input itself when it does not resolve. */
+const realPathCache = new Map();
+function realPathOrSelf(value) {
+    const cached = realPathCache.get(value);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let resolved = value;
+    try {
+        resolved = fs.realpathSync(value);
+    }
+    catch {
+        // Not on disk (a virtual module id, a deleted file, a root that does not
+        // exist). The raw string is the honest answer — same fall-back the PHP
+        // resolver takes when realpath() returns false.
+    }
+    realPathCache.set(value, resolved);
+    return resolved;
+}
+/**
+ * Whether a `file_path` the TEST set for itself could ever match a requirement
+ * anchor.
+ *
+ * The reporters keep a test-provided `file_path` — it may deliberately name the
+ * source file under test rather than the spec's own location — but the value is
+ * held to the same standard a derived one is: anchors are repo-relative, so an
+ * absolute path, an empty string, or one that escapes the root is unlinkable by
+ * construction. Keeping such a value would let a hand-written field do the one
+ * thing the resolver refuses to do, which is fabricate a link that never joins.
+ *
+ * This deliberately does NOT decide the larger question of whether a test
+ * should be able to override `file_path` at all — `tiden-phpunit-reporter`'s
+ * AttributeReader drops a hand-written `#[Field('file_path')]` outright. That
+ * divergence is a product decision, recorded in the PR, not settled here.
+ */
+function isUsableFilePath(value) {
+    const collapsed = collapse(value);
+    if (collapsed === '' || collapsed === '.' || collapsed === '..') {
+        return false;
+    }
+    if (isAbsoluteLike(collapsed)) {
+        return false;
+    }
+    return !collapsed.startsWith('../');
+}

package/dist/options/options-type.d.ts

@@ -25,6 +25,17 @@ export type OptionsType = {
     debug?: boolean | undefined;
     environment?: string | undefined;
     rootSuite?: string | undefined;
+    /**
+     * Base directory the spec-file segment of a case signature is resolved
+     * against. Defaults to `process.cwd()`.
+     *
+     * Set it when the runner's working directory is not the root you want that
+     * segment measured from — a monorepo running vitest from a sub-package, for
+     * instance. The signature is matched byte-for-byte server-side, so every
+     * producer reporting into one product must agree on this base or the same
+     * test lands as two cases.
+     */
+    rootDir?: string | undefined;
     statusMapping?: Record<string, string> | undefined;
     logging?: RecursivePartial<LoggingOptionsType> | undefined;
     tiden?: RecursivePartial<TidenOptionsType> | undefined;

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

@@ -41,6 +41,16 @@ export declare class FallbackCoordinator {
      * disabled or the operation produced no value.
      */
     run<T>(op: (reporter: InternalReporterInterface) => Promise<T>, opName: string): Promise<T | undefined>;
+    /**
+     * Turning the reporter off MID-RUN, after an upstream (and fallback) failure.
+     *
+     * The failure itself is logged by the caller, but the consequence was not:
+     * the suite carried on, every later result went nowhere, and the run ended
+     * green. That is the same silent-failure symptom the construction-time
+     * announcements in `tiden.ts` were added to remove, reached by a different
+     * path — a token that is present but rejected, rather than one that is
+     * missing. Guarded by `this.disabled`, so it says it once.
+     */
     private disable;
     private activateFallback;
     private runOnFallback;

package/dist/reporters/shared/fallback-coordinator.js

@@ -83,10 +83,22 @@ class FallbackCoordinator {
             return this.runOnFallback(op, opName);
         }
     }
+    /**
+     * Turning the reporter off MID-RUN, after an upstream (and fallback) failure.
+     *
+     * The failure itself is logged by the caller, but the consequence was not:
+     * the suite carried on, every later result went nowhere, and the run ended
+     * green. That is the same silent-failure symptom the construction-time
+     * announcements in `tiden.ts` were added to remove, reached by a different
+     * path — a token that is present but rejected, rather than one that is
+     * missing. Guarded by `this.disabled`, so it says it once.
+     */
     disable() {
         if (this.disabled)
             return;
         this.disabled = true;
+        this.logger.log('reporter disabled — the error above stopped it mid-run, and nothing further ' +
+            'from this suite will be reported to Tiden. Results already sent are unaffected.');
         if (!this.onDisabledFired) {
             this.onDisabledFired = true;
             this.callbacks.onDisabled?.();

package/dist/tiden.d.ts

@@ -31,6 +31,17 @@ export declare class TidenReporter implements ReporterInterface {
      */
     private constructor();
     private buildLogger;
+    /**
+     * Announces that this reporter will send nothing, and why.
+     *
+     * A disabled reporter is indistinguishable from a working one: the suite
+     * runs, the tests pass, and nothing is reported. A field user concluded the
+     * reporter was broken and spent an hour on it before finding `mode: 'off'`
+     * in their own jest.config.js — the reporter was merely inert, and had said
+     * so nowhere. This is deliberately `log`, not `logDebug`: a message only
+     * visible once you already suspect the problem does not solve it.
+     */
+    private logReporterDisabled;
     private buildReporters;
     private persistInitialState;
     static getInstance(options: OptionsType): TidenReporter;

package/dist/tiden.js

@@ -87,6 +87,28 @@ class TidenReporter {
         }
         return new logger_1.Logger(opts);
     }
+    /**
+     * Announces that this reporter will send nothing, and why.
+     *
+     * A disabled reporter is indistinguishable from a working one: the suite
+     * runs, the tests pass, and nothing is reported. A field user concluded the
+     * reporter was broken and spent an hour on it before finding `mode: 'off'`
+     * in their own jest.config.js — the reporter was merely inert, and had said
+     * so nowhere. This is deliberately `log`, not `logDebug`: a message only
+     * visible once you already suspect the problem does not solve it.
+     */
+    logReporterDisabled(reason, remedy, credentialsRelevant = false) {
+        // The credentials sentence is opt-in, not a suffix on every message. Telling
+        // someone who set `mode: "off"` on purpose that "tiden" mode needs an API
+        // token answers a question they did not ask, and padding every message with
+        // the same tail is how a message stops being read.
+        const credentials = credentialsRelevant
+            ? ' "tiden" mode also requires tiden.api.token, tiden.product and' +
+                ' tiden.api.baseUrl (TIDEN_API_TOKEN, TIDEN_PRODUCT_ID, TIDEN_BASE_URL).'
+            : '';
+        this.logger.log(`reporter disabled — nothing will be reported to Tiden, because ${reason}. ` +
+            `To enable it, ${remedy}.${credentials}`);
+    }
     buildReporters(factory, resolved) {
         let upstream;
         let fallbackReporter;
@@ -98,11 +120,15 @@ class TidenReporter {
         catch (error) {
             if (error instanceof disabled_exception_1.DisabledException) {
                 disabled = true;
+                this.logReporterDisabled(`mode is "${resolved.effectiveMode}"`, 'set mode to "tiden" (or TIDEN_MODE=tiden) to report this run', 
+                // Enabling it is the next thing they will do, and it needs all four.
+                true);
             }
             else {
                 this.logger.logError('Unable to create upstream reporter:', error);
                 if (resolved.composed.fallback === undefined) {
                     disabled = true;
+                    this.logReporterDisabled('the upstream reporter could not be created and no fallback is configured', 'fix the error above');
                     return { upstream, fallback: fallbackReporter, disabled, useFallbackFromStart: false };
                 }
                 upstreamFailed = true;
@@ -113,13 +139,18 @@ class TidenReporter {
         }
         catch (error) {
             if (error instanceof disabled_exception_1.DisabledException) {
-                if (upstreamFailed)
+                if (upstreamFailed) {
                     disabled = true;
+                    this.logReporterDisabled('the upstream reporter could not be created (see the error above) and ' +
+                        `fallback is "${resolved.effectiveFallback}"`, 'fix the error above, or set a fallback mode', true);
+                }
             }
             else {
                 this.logger.logError('Unable to create fallback reporter:', error);
-                if (upstreamFailed && upstream === undefined)
+                if (upstreamFailed && upstream === undefined) {
                     disabled = true;
+                    this.logReporterDisabled('neither the upstream nor the fallback reporter could be created', 'fix the errors above');
+                }
             }
         }
         const useFallbackFromStart = upstreamFailed && fallbackReporter !== undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiden/reporter-commons",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Tiden JS Reporters",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",