@tiden/reporter-commons 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 0.4.0
+
+- **Test identity parts.** A result can carry `identity`: `{ language, repository, scope, name }`,
+  sent next to the unchanged legacy `signature`. The server builds the identity key from these
+  parts, so a reporter never normalizes titles itself. `ResultCreate.identity` is added to the
+  hand-written DTOs and mapped by `ResultTransformer`; `TestResultType.identity` carries it.
+- **Repository resolution on the `/internal` entry point:** `resolveRepositoryContext`,
+  `buildTestIdentity`. The repository is `TIDEN_REPOSITORY`, then the CI variables
+  (`GITHUB_SERVER_URL`+`GITHUB_REPOSITORY`, `CI_SERVER_URL`+`CI_PROJECT_PATH`,
+  `BITBUCKET_GIT_HTTP_ORIGIN`, `BUILD_REPOSITORY_URI`), then the `origin` URL in the `.git/config`
+  of the nearest ancestor holding `.git` (a directory, or a file that points to the git directory:
+  worktrees and submodules). No subprocess, resolved once per process, sent raw: the server
+  normalizes it. The same ancestor is the root the test file is made relative to. No repository, or
+  a file outside that root, means no `identity` and one warning per process; the legacy
+  `signature` still identifies the test.
+- **`clientMeta.gitRepository`** on the run, when a repository resolves.
+- **Fallback for an older server.** A 400 whose body contains the gateway's
+  `unknown field "identity"` error makes the client resend the same batch (same result ids, so the
+  server still deduplicates) without `identity`, and stop sending it. Any other 400 is still a real
+  error.
+- `CreateTestRunBody` gains `intentSessionId` and `intentBranch` in the hand-written DTO, which
+  the generated model already had.
+
+## 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

package/dist/client/reporter-api-models.d.ts

@@ -15,6 +15,8 @@ export interface CreateTestRunBody {
     buildSha?: string;
     startedAt?: string;
     clientMeta?: Record<string, string>;
+    intentSessionId?: string;
+    intentBranch?: string;
 }
 export interface ReporterTestRun {
     seqNum?: number;
@@ -62,10 +64,22 @@ export interface SuiteSegment {
     title?: string;
     externalId?: string;
 }
+/**
+ * `ResultCreate.identity`: the parts of a test's identity. Optional; a server
+ * that predates it rejects the field, which the client handles by resending
+ * the batch without it (see `TidenApiClient`).
+ */
+export interface ResultIdentity {
+    language?: string;
+    repository?: string;
+    scope?: string[];
+    name?: string[];
+}
 export interface ResultCreate {
     id?: string;
     title?: string;
     signature?: string;
+    identity?: ResultIdentity;
     externalId?: string;
     testopsIds?: number[];
     execution?: ResultExecution;

package/dist/client/services/result-transformer.js

@@ -59,6 +59,16 @@ class ResultTransformer {
             fields: result.fields,
             defect: false,
             ...(result.signature != null ? { signature: result.signature } : {}),
+            ...(result.identity
+                ? {
+                    identity: {
+                        language: result.identity.language,
+                        repository: result.identity.repository,
+                        scope: [...result.identity.scope],
+                        name: [...result.identity.name],
+                    },
+                }
+                : {}),
         };
         if (result.tags && result.tags.length > 0) {
             model.fields = {

package/dist/client/tiden-client.d.ts

@@ -20,6 +20,11 @@ export declare class TidenApiClient implements IClient {
     private readonly runService;
     private readonly attachmentService;
     private readonly resultTransformer;
+    /**
+     * Set once the server has rejected `identity` as an unknown field. From then
+     * on this client sends results without it. See `postResultsWithRetry`.
+     */
+    private identityRejected;
     constructor(logger: LoggerInterface, config: TidenOptionsType, environment: string | undefined, rootSuite: string | undefined);
     createRun(): Promise<number>;
     completeRun(runId: number): Promise<void>;
@@ -27,8 +32,12 @@ export declare class TidenApiClient implements IClient {
     /** Public run report links have no Tiden equivalent in v1. */
     enablePublicReport(_runId: number): Promise<void>;
     uploadResults(runId: number, results: TestResultType[]): Promise<void>;
-    /** 429-only retry (Retry-After honored, exp backoff, 30s cap); 400 is
+    /** 429 is retried (Retry-After honored, exp backoff, 30s cap). A 400 is
      *  terminal — resending an identical batch fails identically, so log
-     *  every per-entry ReportError from details[] and re-throw. */
+     *  every per-entry ReportError from details[] and re-throw — with one
+     *  exception: a server that predates `identity` answers 400 with the
+     *  gateway's `unknown field "identity"` error. Then the same batch (same
+     *  result ids, so the server still deduplicates) is resent without it, and
+     *  this client stops sending it. Any other 400 is a real error. */
     private postResultsWithRetry;
 }

package/dist/client/tiden-client.js

@@ -26,6 +26,11 @@ class TidenApiClient {
     runService;
     attachmentService;
     resultTransformer;
+    /**
+     * Set once the server has rejected `identity` as an unknown field. From then
+     * on this client sends results without it. See `postResultsWithRetry`.
+     */
+    identityRejected = false;
     constructor(logger, config, environment, rootSuite) {
         this.logger = logger;
         this.config = config;
@@ -55,16 +60,21 @@ class TidenApiClient {
             const models = await Promise.all(results.map((result) => this.resultTransformer.transformWithDefect(result, (a) => this.attachmentService
                 .uploadAttachments(this.config.product, [a], this.config.uploadAttachments ?? true)
                 .then((hashes) => hashes[0] ?? ''), this.config.defect ?? false)));
-            await this.postResultsWithRetry(runId, models);
+            await this.postResultsWithRetry(runId, this.identityRejected ? models.map(withoutIdentity) : models);
         }
         catch (error) {
             throw (0, api_error_handler_1.processError)(error, 'Error on uploading results', results);
         }
     }
-    /** 429-only retry (Retry-After honored, exp backoff, 30s cap); 400 is
+    /** 429 is retried (Retry-After honored, exp backoff, 30s cap). A 400 is
      *  terminal — resending an identical batch fails identically, so log
-     *  every per-entry ReportError from details[] and re-throw. */
-    async postResultsWithRetry(runId, models, maxRetries = 5) {
+     *  every per-entry ReportError from details[] and re-throw — with one
+     *  exception: a server that predates `identity` answers 400 with the
+     *  gateway's `unknown field "identity"` error. Then the same batch (same
+     *  result ids, so the server still deduplicates) is resent without it, and
+     *  this client stops sending it. Any other 400 is a real error. */
+    async postResultsWithRetry(runId, batch, maxRetries = 5) {
+        let models = batch;
         let delay = 1000;
         for (let attempt = 0;; attempt++) {
             try {
@@ -83,6 +93,15 @@ class TidenApiClient {
                     delay = Math.min(delay * 2, 30_000);
                     continue;
                 }
+                if ((0, axios_1.isAxiosError)(error)
+                    && error.response?.status === 400
+                    && models.some((model) => model.identity !== undefined)
+                    && mentionsUnknownIdentityField(error.response.data)) {
+                    this.identityRejected = true;
+                    this.logger.log('The server does not accept test identity yet; reporting by signature only.');
+                    models = models.map(withoutIdentity);
+                    continue;
+                }
                 if ((0, axios_1.isAxiosError)(error) && error.response?.status === 400) {
                     const details = error.response.data?.details ?? [];
                     for (const d of details) {
@@ -97,3 +116,23 @@ class TidenApiClient {
     }
 }
 exports.TidenApiClient = TidenApiClient;
+/** The gateway's wording for a JSON field the API does not know. */
+const UNKNOWN_IDENTITY_FIELD = 'unknown field "identity"';
+function withoutIdentity(model) {
+    const { identity: _identity, ...rest } = model;
+    return rest;
+}
+/**
+ * Whether an error body carries the unknown-`identity` error. The text sits in
+ * `message`, but a JSON-serialized body escapes its quotes, so strings are
+ * collected from the parsed body instead of searching the serialized form.
+ */
+function mentionsUnknownIdentityField(body, depth = 0) {
+    if (typeof body === 'string') {
+        return body.includes(UNKNOWN_IDENTITY_FIELD);
+    }
+    if (depth > 4 || body === null || typeof body !== 'object') {
+        return false;
+    }
+    return Object.values(body).some((value) => mentionsUnknownIdentityField(value, depth + 1));
+}

package/dist/core/reporter-factory.js

@@ -7,6 +7,8 @@ const env_1 = require("../env");
 const disabled_exception_1 = require("../utils/disabled-exception");
 const tiden_client_1 = require("../client/tiden-client");
 const writer_1 = require("../writer");
+const repository_1 = require("../internal/repository");
+const spec_path_1 = require("../internal/spec-path");
 /**
  * Builds a mode-specific InternalReporterInterface. Throws DisabledException
  * for `ModeEnum.off` so callers can distinguish "disabled-by-config" from a
@@ -51,6 +53,13 @@ class ReporterFactory {
             os: this.hostData.system,
             node: this.hostData.language,
         };
+        // The raw remote of the repository under test, so the run itself is
+        // attributed even when no result carries identity parts. The server
+        // normalizes it. Omitted, not empty, when nothing resolves.
+        const gitRepository = (0, repository_1.resolveRepositoryContext)((0, spec_path_1.resolveRootDir)(options.rootDir)).repository;
+        if (gitRepository) {
+            tiden.clientMeta['gitRepository'] = gitRepository;
+        }
         const apiClient = new tiden_client_1.TidenApiClient(this.logger, tiden, options.environment, options.rootSuite);
         return new reporters_1.RunReporter(this.logger, apiClient, withState, tiden.product, tiden.batch?.size, tiden.run?.id);
     }

package/dist/internal/index.d.ts

@@ -8,3 +8,8 @@ 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';
+export { resolveRepositoryContext, resetRepositoryContext, REPOSITORY_ENV } from './repository';
+export type { RepositoryContext } from './repository';
+export { buildTestIdentity, resetIdentityWarning, JS_IDENTITY_LANGUAGE } from './test-identity';

package/dist/internal/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveRootDir = exports.normalizeSpecPath = exports.normalizeSuitePart = exports.filterPositiveIds = exports.parseTidenIdsFromString = exports.getFile = exports.extractAndCleanStep = exports.removeTidenIdsFromTitle = void 0;
+exports.JS_IDENTITY_LANGUAGE = exports.resetIdentityWarning = exports.buildTestIdentity = exports.REPOSITORY_ENV = exports.resetRepositoryContext = exports.resolveRepositoryContext = 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");
@@ -17,3 +17,15 @@ 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; } });
+var repository_1 = require("./repository");
+Object.defineProperty(exports, "resolveRepositoryContext", { enumerable: true, get: function () { return repository_1.resolveRepositoryContext; } });
+Object.defineProperty(exports, "resetRepositoryContext", { enumerable: true, get: function () { return repository_1.resetRepositoryContext; } });
+Object.defineProperty(exports, "REPOSITORY_ENV", { enumerable: true, get: function () { return repository_1.REPOSITORY_ENV; } });
+var test_identity_1 = require("./test-identity");
+Object.defineProperty(exports, "buildTestIdentity", { enumerable: true, get: function () { return test_identity_1.buildTestIdentity; } });
+Object.defineProperty(exports, "resetIdentityWarning", { enumerable: true, get: function () { return test_identity_1.resetIdentityWarning; } });
+Object.defineProperty(exports, "JS_IDENTITY_LANGUAGE", { enumerable: true, get: function () { return test_identity_1.JS_IDENTITY_LANGUAGE; } });

package/dist/internal/repository.d.ts

@@ -0,0 +1,31 @@
+/** Explicit override. Wins over every CI variable and over `.git/config`. */
+export declare const REPOSITORY_ENV = "TIDEN_REPOSITORY";
+export interface RepositoryContext {
+    /** The raw remote, exactly as found. The server normalizes it. */
+    repository: string | undefined;
+    /** The nearest ancestor of the start directory that contains `.git`. */
+    root: string | undefined;
+}
+/**
+ * The repository a test run belongs to and the directory its files are
+ * measured from.
+ *
+ * Repository, first match wins:
+ *   1. `TIDEN_REPOSITORY`
+ *   2. CI environment: `GITHUB_SERVER_URL` + `GITHUB_REPOSITORY`,
+ *      `CI_SERVER_URL` + `CI_PROJECT_PATH`, `BITBUCKET_GIT_HTTP_ORIGIN`,
+ *      `BUILD_REPOSITORY_URI`
+ *   3. the `origin` URL in the `.git/config` of the repository root
+ *
+ * Root: the nearest ancestor of `startDir` (default `process.cwd()`) that
+ * contains `.git`. A directory, or a file that points to the real git
+ * directory (worktrees and submodules).
+ *
+ * No subprocess: `git` may be missing from a CI image, and spawning it for
+ * every test run costs more than reading one small file. The value is not
+ * normalized here; the server owns that rule, so a reporter can never drift
+ * from it.
+ */
+export declare function resolveRepositoryContext(startDir?: string): RepositoryContext;
+/** Forget every resolved context. For tests; a real run never needs it. */
+export declare function resetRepositoryContext(): void;

package/dist/internal/repository.js

@@ -0,0 +1,210 @@
+"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.REPOSITORY_ENV = void 0;
+exports.resolveRepositoryContext = resolveRepositoryContext;
+exports.resetRepositoryContext = resetRepositoryContext;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/** Explicit override. Wins over every CI variable and over `.git/config`. */
+exports.REPOSITORY_ENV = 'TIDEN_REPOSITORY';
+const SLASH = '/'.charCodeAt(0);
+/**
+ * Resolved once per process and start directory. The answer cannot change
+ * while a test run is in flight, and every result of a run asks for it.
+ */
+const cache = new Map();
+/**
+ * The repository a test run belongs to and the directory its files are
+ * measured from.
+ *
+ * Repository, first match wins:
+ *   1. `TIDEN_REPOSITORY`
+ *   2. CI environment: `GITHUB_SERVER_URL` + `GITHUB_REPOSITORY`,
+ *      `CI_SERVER_URL` + `CI_PROJECT_PATH`, `BITBUCKET_GIT_HTTP_ORIGIN`,
+ *      `BUILD_REPOSITORY_URI`
+ *   3. the `origin` URL in the `.git/config` of the repository root
+ *
+ * Root: the nearest ancestor of `startDir` (default `process.cwd()`) that
+ * contains `.git`. A directory, or a file that points to the real git
+ * directory (worktrees and submodules).
+ *
+ * No subprocess: `git` may be missing from a CI image, and spawning it for
+ * every test run costs more than reading one small file. The value is not
+ * normalized here; the server owns that rule, so a reporter can never drift
+ * from it.
+ */
+function resolveRepositoryContext(startDir) {
+    const start = path.resolve(startDir ?? process.cwd());
+    const cached = cache.get(start);
+    if (cached) {
+        return cached;
+    }
+    const found = findGitEntry(start);
+    const context = {
+        repository: repositoryFromEnv(process.env) ?? (found ? repositoryFromGit(found.dotGit) : undefined),
+        root: found?.root,
+    };
+    cache.set(start, context);
+    return context;
+}
+/** Forget every resolved context. For tests; a real run never needs it. */
+function resetRepositoryContext() {
+    cache.clear();
+}
+function repositoryFromEnv(env) {
+    const value = (name) => {
+        const raw = env[name]?.trim();
+        return raw ? raw : undefined;
+    };
+    const explicit = value(exports.REPOSITORY_ENV);
+    if (explicit) {
+        return explicit;
+    }
+    const pairs = [
+        ['GITHUB_SERVER_URL', 'GITHUB_REPOSITORY'],
+        ['CI_SERVER_URL', 'CI_PROJECT_PATH'],
+    ];
+    for (const [serverName, repoName] of pairs) {
+        const server = value(serverName);
+        const repo = value(repoName);
+        if (server && repo) {
+            return `${trimTrailingSlashes(server)}/${repo}`;
+        }
+    }
+    return value('BITBUCKET_GIT_HTTP_ORIGIN') ?? value('BUILD_REPOSITORY_URI');
+}
+/** Scanned, not `/\/+$/`: that pattern backtracks quadratically (see spec-path.ts). */
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === SLASH) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function findGitEntry(start) {
+    let dir = start;
+    for (;;) {
+        const dotGit = path.join(dir, '.git');
+        if (exists(dotGit)) {
+            return { root: dir, dotGit };
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+            return undefined;
+        }
+        dir = parent;
+    }
+}
+function exists(candidate) {
+    try {
+        const stat = fs.statSync(candidate);
+        return stat.isDirectory() || stat.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function repositoryFromGit(dotGit) {
+    const gitDir = resolveGitDir(dotGit);
+    if (!gitDir) {
+        return undefined;
+    }
+    // A linked worktree keeps its own HEAD and index in `<main>/.git/worktrees/<n>`
+    // but shares the remotes with the main repository, named by `commondir`.
+    const commonDir = readTrimmed(path.join(gitDir, 'commondir'));
+    const configDir = commonDir ? path.resolve(gitDir, commonDir) : gitDir;
+    const config = readText(path.join(configDir, 'config'));
+    return config === undefined ? undefined : originUrl(config);
+}
+/** `.git` as a directory is the git directory; as a file it holds `gitdir: <path>`. */
+function resolveGitDir(dotGit) {
+    try {
+        if (fs.statSync(dotGit).isDirectory()) {
+            return dotGit;
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const content = readTrimmed(dotGit);
+    const prefix = 'gitdir:';
+    if (content === undefined || !content.startsWith(prefix)) {
+        return undefined;
+    }
+    const target = content.slice(prefix.length).trim();
+    return target ? path.resolve(path.dirname(dotGit), target) : undefined;
+}
+function readText(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+}
+function readTrimmed(file) {
+    const text = readText(file);
+    return text === undefined ? undefined : (text.split(/\r?\n/, 1)[0] ?? '').trim();
+}
+const ORIGIN_SECTION = /^\[\s*remote\s+"origin"\s*\]/i;
+/** The first `url` of `[remote "origin"]` in a git config file. */
+function originUrl(config) {
+    let inOrigin = false;
+    for (const raw of config.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (line.startsWith('[')) {
+            inOrigin = ORIGIN_SECTION.test(line);
+            continue;
+        }
+        if (!inOrigin || line.startsWith('#') || line.startsWith(';')) {
+            continue;
+        }
+        const eq = line.indexOf('=');
+        if (eq < 0 || line.slice(0, eq).trim().toLowerCase() !== 'url') {
+            continue;
+        }
+        const value = unquote(line.slice(eq + 1).trim());
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function unquote(value) {
+    return value.length >= 2 && value.startsWith('"') && value.endsWith('"')
+        ? value.slice(1, -1)
+        : value;
+}

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

@@ -10,3 +10,60 @@ export declare function normalizeSpecPath(fullPath: string, cwd?: string): strin
  * 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

@@ -1,7 +1,44 @@
 "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
@@ -53,3 +90,138 @@ 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/internal/test-identity.d.ts

@@ -0,0 +1,29 @@
+import type { TestIdentity } from '../models/test-identity';
+/** The language token of every JavaScript reporter. */
+export declare const JS_IDENTITY_LANGUAGE = "js";
+/** Forget that a warning was printed. For tests; a real run never needs it. */
+export declare function resetIdentityWarning(): void;
+/**
+ * The identity parts of one test: the repository, the repo-relative POSIX
+ * file as scope, and the raw describe titles plus the test title as name.
+ *
+ * Titles are not lowercased, underscored or otherwise rewritten: the server
+ * builds the key from them, and a reporter-side normalizer is exactly what
+ * made jest and vitest disagree about one test. The trailing
+ * `(Tiden ID: N)` marker is the one thing removed from the test title; it is
+ * an explicit id, not part of the name, and adding one must not fork the
+ * test's history.
+ *
+ * `undefined` means "send no identity": no repository could be resolved, or
+ * the file is not under the repository root, or the test has no title. The
+ * legacy `signature` still identifies the test then. One warning per process
+ * names the first cause; a warning per test would bury the run log.
+ *
+ * @param startDir where to start looking for `.git`; defaults to `process.cwd()`.
+ */
+export declare function buildTestIdentity(args: {
+    file: string | undefined;
+    describes: readonly string[];
+    title: string;
+    startDir?: string | undefined;
+}): TestIdentity | undefined;

package/dist/internal/test-identity.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JS_IDENTITY_LANGUAGE = void 0;
+exports.resetIdentityWarning = resetIdentityWarning;
+exports.buildTestIdentity = buildTestIdentity;
+const repository_1 = require("./repository");
+const spec_path_1 = require("./spec-path");
+const title_1 = require("./title");
+/** The language token of every JavaScript reporter. */
+exports.JS_IDENTITY_LANGUAGE = 'js';
+let warned = false;
+/** Forget that a warning was printed. For tests; a real run never needs it. */
+function resetIdentityWarning() {
+    warned = false;
+}
+/**
+ * The identity parts of one test: the repository, the repo-relative POSIX
+ * file as scope, and the raw describe titles plus the test title as name.
+ *
+ * Titles are not lowercased, underscored or otherwise rewritten: the server
+ * builds the key from them, and a reporter-side normalizer is exactly what
+ * made jest and vitest disagree about one test. The trailing
+ * `(Tiden ID: N)` marker is the one thing removed from the test title; it is
+ * an explicit id, not part of the name, and adding one must not fork the
+ * test's history.
+ *
+ * `undefined` means "send no identity": no repository could be resolved, or
+ * the file is not under the repository root, or the test has no title. The
+ * legacy `signature` still identifies the test then. One warning per process
+ * names the first cause; a warning per test would bury the run log.
+ *
+ * @param startDir where to start looking for `.git`; defaults to `process.cwd()`.
+ */
+function buildTestIdentity(args) {
+    const title = (0, title_1.removeTidenIdsFromTitle)(args.title);
+    if (title === '') {
+        return undefined;
+    }
+    const context = (0, repository_1.resolveRepositoryContext)(args.startDir);
+    if (!context.repository) {
+        warnOnce('no repository was found. Set TIDEN_REPOSITORY, run in CI with the standard '
+            + 'repository variables, or run inside a git checkout with an "origin" remote.');
+        return undefined;
+    }
+    if (!context.root) {
+        warnOnce('no .git directory was found above the working directory, so test files cannot be made repo-relative.');
+        return undefined;
+    }
+    const scope = args.file ? (0, spec_path_1.resolveFilePath)(args.file, context.root) : undefined;
+    if (scope === undefined) {
+        warnOnce(`${args.file ?? 'a test with no file'} is outside the repository root (${context.root}).`);
+        return undefined;
+    }
+    return {
+        language: exports.JS_IDENTITY_LANGUAGE,
+        repository: context.repository,
+        scope: [scope],
+        // An anonymous `describe('')` is not a level of the name. Playwright's
+        // own titlePath() drops it, and every framework must agree.
+        name: [...args.describes.filter((describe) => describe !== ''), title],
+    };
+}
+function warnOnce(reason) {
+    if (warned) {
+        return;
+    }
+    warned = true;
+    console.warn(`tiden: not sending test identity — ${reason} `
+        + 'Results are still reported, matched by their signature only. '
+        + '(Reported once per process.)');
+}

package/dist/models/index.d.ts

@@ -9,3 +9,4 @@ export type { Report } from './report';
 export { CompoundError } from './error';
 export type { ConfigurationGroup, ConfigurationItem, ConfigurationGroupResponse } from './configuration';
 export type { TidenOptionsType, TidenApiType, TidenRunType, TidenBatchType, TidenConfigurationType, TidenConfigurationValueType } from './config/TidenOptionsType';
+export type { TestIdentity } from './test-identity';

package/dist/models/test-identity.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The parts a test's identity is made of, as sent in `ResultCreate.identity`.
+ * The server builds the identity key from them; a reporter never does.
+ */
+export interface TestIdentity {
+    /** Language token (`[a-z0-9-]{1,20}`); always `js` for the JavaScript reporters. */
+    language: string;
+    /** Raw repository remote or `host/owner/repo`; the server normalizes it. */
+    repository: string;
+    /** Structural location: the repo-relative POSIX test file. */
+    scope: string[];
+    /** Test name path: describe titles, then the test title, all raw. */
+    name: string[];
+}

package/dist/models/test-identity.js

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

package/dist/models/test-result.d.ts

@@ -1,6 +1,7 @@
 import { TestStepType } from './test-step';
 import { Attachment } from './attachment';
 import { TestExecution } from './test-execution';
+import { TestIdentity } from './test-identity';
 /**
  * Project code to test case IDs mapping for multi-project support.
  * Key: project code (string), Value: array of test case IDs (numbers).
@@ -30,6 +31,12 @@ export declare class TestResultType {
     message: string | null;
     tags: string[];
     preparedAttachments?: string[];
+    /**
+     * Identity parts sent next to the legacy `signature`. Absent when the
+     * reporter could not resolve a repository or the test file is outside the
+     * repository root. Deliberately not set by the constructor.
+     */
+    identity?: TestIdentity | undefined;
     constructor(title: string);
 }
 export interface Relation {

package/dist/models/test-result.js

@@ -26,6 +26,12 @@ class TestResultType {
     message;
     tags;
     preparedAttachments;
+    /**
+     * Identity parts sent next to the legacy `signature`. Absent when the
+     * reporter could not resolve a repository or the test file is outside the
+     * repository root. Deliberately not set by the constructor.
+     */
+    identity;
     constructor(title) {
         this.id = '';
         this.title = title;

package/package.json

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