@tiden/reporter-commons 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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

package/dist/internal/index.d.ts

@@ -8,3 +8,5 @@ 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.resolveRootDir = exports.normalizeSpecPath = 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");
@@ -17,3 +17,7 @@ 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

@@ -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/package.json

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