testdossier 0.3.0 → 0.3.2

package/README.md

@@ -8,7 +8,7 @@ Upload a completed test report from a developer laptop, test machine, or CI
 job. Run these commands in the project containing your automated tests:
 
 1. Install the latest CLI in the project. To pin a release instead, replace
-   `@latest` with an exact version such as `@0.3.0`:
+   `@latest` with an exact version such as `@0.3.2`:
 
 ```bash
 npm install --save-dev testdossier@latest
@@ -95,6 +95,74 @@ Before sending anything, inspect what the CLI detected:
 npx testdossier upload playwright-results.json --dry-run
 ```
 
+### Optional source context
+
+Source snippets are opt-in. Add this to the committed `testdossier.json` when
+the checked-out CI workspace may be read for evidence:
+
+```json
+{
+  "report": "playwright-results.json",
+  "source": {
+    "enabled": true,
+    "root": ".",
+    "before": 20,
+    "after": 80
+  }
+}
+```
+
+Only files identified by uploaded test records are considered. Paths must stay
+inside the real, non-symlink source root; binary, invalid UTF-8, symlinked,
+missing, and files over 2 MiB are skipped. Each persisted snippet is limited to
+240 lines and 16 KiB, common credential literals are masked, and the digest is
+computed after masking. Source is evidence only: the CLI never executes,
+formats, or infers test steps from it. `--dry-run` prints counts, safe relative
+paths, ranges, hashes, truncation, and redaction counts—never source contents.
+
+If a Playwright report records files relative to `testDir`, set `source.root`
+to that directory (for example `"tests/e2e"`). An unchanged CI snippet keeps
+its provenance; a new digest becomes a Review queue proposal and never silently
+overwrites an approved case or an older run snapshot.
+
+## Automatic source context (opt in once)
+
+The uploader can attach the repository source around each test declaration as
+read-only execution evidence. Enable it in the committed `testdossier.json`:
+
+```json
+{
+  "report": "playwright-results.json",
+  "source": {
+    "enabled": true,
+    "root": ".",
+    "before": 20,
+    "after": 80
+  }
+}
+```
+
+After that one-time opt-in, the same `npx testdossier` command captures source
+locally, in GitHub Actions, and in GitLab CI. No TestDossier ID is required in
+each `test()` or `it()` block: existing ID, alias, and report-signature matching
+still apply. An explicit TestDossier ID, when present, remains the strongest
+identity signal; disagreement with the report signature is quarantined for a
+reviewer instead of being attached silently.
+
+Capture is framework-neutral and best effort. It uses the source file and line
+reported by Playwright, Cypress, Cucumber, or JUnit-compatible runners. Files
+must resolve inside `source.root`; symlinks, binary files, files over 2 MiB, and
+paths outside that root are skipped. Each persisted snippet is bounded, common
+credential literals are redacted, and the CLI prints every captured path and
+digest during `--dry-run` so the upload can be inspected before it is sent.
+
+The Editor holds the current, editable source reference. Every Test Run keeps
+the source uploaded for that execution as an immutable snapshot. When a later
+upload changes a source digest, Review queue shows the incoming version for
+comparison; accepting it updates the Editor reference without rewriting the
+completed run. Editing in TestDossier never changes the repository or what CI
+executes.
+
 ## Supported reports
 
 | Runner or format | Example |
@@ -157,7 +225,7 @@ npm install --save-dev testdossier@latest
 npx testdossier init
 ```
 
-Use `npm install --save-dev testdossier@0.3.0` when the repository should pin
+Use `npm install --save-dev testdossier@0.3.2` when the repository should pin
 that exact release. In either case, subsequent commands remain
 `npx testdossier ...`; the version selector belongs only to installation.
 

package/assets/mark.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="TestDossier">
   <title>TestDossier</title>
-  <path fill="#006b61" fill-rule="evenodd" d="M20 6h14c17 0 28 10 28 26S51 58 34 58H20V6Zm14 14v24c9 0 14-4 14-12s-5-12-14-12Z"/>
-  <path fill="#006b61" d="M2 6h32v14H2z"/>
+  <path fill="#4335de" fill-rule="evenodd" d="M20 6h14c17 0 28 10 28 26S51 58 34 58H20V6Zm14 14v24c9 0 14-4 14-12s-5-12-14-12Z"/>
+  <path fill="#4335de" d="M2 6h32v14H2z"/>
 </svg>

package/lib/source-context.mjs

@@ -0,0 +1,212 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, extname, isAbsolute, relative, resolve, sep } from "node:path";
+
+export const SOURCE_ENVELOPE_VERSION = 1;
+export const MAX_SOURCE_CONTEXT_BYTES = 16 * 1024;
+export const MAX_SOURCE_CONTEXT_LINES = 240;
+const MAX_SOURCE_FILE_BYTES = 2 * 1024 * 1024;
+const LANGUAGE_BY_EXTENSION = new Map([
+  [".js", "javascript"], [".jsx", "jsx"], [".mjs", "javascript"], [".cjs", "javascript"],
+  [".ts", "typescript"], [".tsx", "tsx"], [".py", "python"], [".rb", "ruby"],
+  [".java", "java"], [".kt", "kotlin"], [".kts", "kotlin"], [".cs", "csharp"],
+  [".go", "go"], [".rs", "rust"], [".php", "php"], [".feature", "gherkin"],
+  [".xml", "xml"], [".json", "json"], [".yaml", "yaml"], [".yml", "yaml"],
+  [".sh", "shell"], [".bash", "shell"], [".zsh", "shell"],
+]);
+
+function object(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function parseSourceConfig(value) {
+  if (value === undefined) return null;
+  if (!object(value)) throw new Error('testdossier.json "source" must be an object.');
+  if (value.enabled !== true && value.enabled !== false) {
+    throw new Error('testdossier.json "source.enabled" must be true or false.');
+  }
+  if (!value.enabled) return null;
+  const root = value.root === undefined ? "." : value.root;
+  if (typeof root !== "string" || !root.trim() || isAbsolute(root) || root.split(/[\\/]/).includes("..")) {
+    throw new Error('testdossier.json "source.root" must be a relative path inside the project.');
+  }
+  const integer = (field, fallback, max) => {
+    const n = value[field];
+    if (n === undefined) return fallback;
+    if (!Number.isInteger(n) || n < 0 || n > max) throw new Error(`testdossier.json "source.${field}" must be an integer from 0 to ${max}.`);
+    return n;
+  };
+  return { enabled: true, root: root.trim(), before: integer("before", 20, 200), after: integer("after", 80, 200) };
+}
+
+export function redactSourceText(value) {
+  let content = String(value);
+  let redactions = 0;
+  const replace = (pattern, replacement) => {
+    content = content.replace(pattern, (...args) => {
+      redactions += 1;
+      return typeof replacement === "function" ? replacement(...args) : replacement;
+    });
+  };
+  replace(
+    /(\b(?:password|passwd|secret|api[_-]?key|access[_-]?token|auth(?:orization)?|cookie)\b\s*[:=]\s*)(?:(["'`])[^\r\n]*?\2|[^\s,;]+)/gi,
+    (_match, prefix, quote) => `${prefix}${quote || ""}[REDACTED]${quote || ""}`,
+  );
+  replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{8,}\b/gi, "Bearer [REDACTED]");
+  replace(/\btd_[A-Za-z0-9_-]{8,}\b/g, "td_[REDACTED]");
+  replace(/(https?:\/\/)([^\s/@:]+):([^\s/@]+)@/gi, (_match, scheme) => `${scheme}[REDACTED]@`);
+  replace(/-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g,
+    "-----BEGIN PRIVATE KEY-----\n[REDACTED]\n-----END PRIVATE KEY-----");
+  return { content, redactions };
+}
+
+function utf8Bound(value, maxBytes) {
+  const bytes = Buffer.from(value, "utf8");
+  if (bytes.byteLength <= maxBytes) return { content: value, truncated: false };
+  let content = bytes.subarray(0, maxBytes).toString("utf8").replace(/\uFFFD$/, "");
+  return { content, truncated: true };
+}
+
+function sourceTargets(format, bodyText) {
+  if (format === "junit") {
+    const targets = [];
+    const open = /<testcase\b((?:[^>"']|"[^"]*"|'[^']*')*?)(?:\/?)>/gi;
+    let match;
+    while ((match = open.exec(bodyText))) {
+      const attr = (name) => {
+        const found = match[1].match(new RegExp(`\\b${name}\\s*=\\s*("[^"]*"|'[^']*')`, "i"));
+        return found ? found[1].slice(1, -1) : "";
+      };
+      targets.push({ path: attr("file"), line: Number(attr("line")) || undefined });
+    }
+    return targets;
+  }
+  let doc;
+  try { doc = JSON.parse(bodyText.replace(/^\uFEFF/, "")); } catch { return []; }
+  if (format === "generic") return (Array.isArray(doc?.tests) ? doc.tests : []).map((test) => ({
+    path: typeof test?.file === "string" ? test.file : "",
+    line: Number(test?.line ?? test?.location?.line) || undefined,
+  }));
+  if (format === "cypress") return (Array.isArray(doc?.runs) ? doc.runs : []).flatMap((run) => {
+    const path = run?.spec?.relative || run?.spec?.name || "";
+    return (Array.isArray(run?.tests) ? run.tests : []).map((test) => ({
+      path,
+      line: Number(test?.line ?? test?.location?.line) || undefined,
+    }));
+  });
+  if (format === "cucumber") return (Array.isArray(doc) ? doc : []).flatMap((feature) =>
+    (Array.isArray(feature?.elements) ? feature.elements : [])
+      .filter((element) => String(element?.type || "scenario").toLowerCase() === "scenario")
+      .map((element) => ({ path: feature?.uri || "", line: Number(element?.line) || undefined })));
+  const targets = [];
+  const visit = (suites) => {
+    for (const suite of Array.isArray(suites) ? suites : []) {
+      for (const spec of Array.isArray(suite?.specs) ? suite.specs : []) {
+        for (const test of Array.isArray(spec?.tests) ? spec.tests : []) {
+          targets.push({ path: spec.file || "", line: Number(spec.line) || undefined });
+        }
+      }
+      visit(suite?.suites);
+    }
+  };
+  visit(doc?.suites);
+  return targets;
+}
+
+function inside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel));
+}
+
+async function hasSymlink(root, candidate) {
+  const rel = relative(root, candidate);
+  let cursor = root;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    cursor = resolve(cursor, part);
+    if ((await lstat(cursor)).isSymbolicLink()) return true;
+  }
+  return false;
+}
+
+async function readOneSource(root, target, config, commit) {
+  if (!target.path || typeof target.path !== "string") return { reason: "report has no source path" };
+  const candidate = isAbsolute(target.path) ? resolve(target.path) : resolve(root, target.path);
+  if (!inside(root, candidate)) return { reason: "path is outside source root", path: target.path };
+  try {
+    if (await hasSymlink(root, candidate)) return { reason: "symlink paths are not captured", path: target.path };
+    const candidateReal = await realpath(candidate);
+    if (!inside(root, candidateReal)) return { reason: "resolved path is outside source root", path: target.path };
+    const info = await stat(candidateReal);
+    if (!info.isFile()) return { reason: "source path is not a file", path: target.path };
+    if (info.size <= 0 || info.size > MAX_SOURCE_FILE_BYTES) return { reason: "source file is empty or over 2 MiB", path: target.path };
+    const bytes = await readFile(candidateReal);
+    if (bytes.includes(0)) return { reason: "binary source is not captured", path: target.path };
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes).replace(/\r\n?/g, "\n");
+    const allLines = decoded.split("\n");
+    const focus = Number.isInteger(target.line) && target.line > 0 ? Math.min(target.line, allLines.length) : undefined;
+    const start = focus ? Math.max(1, focus - config.before) : 1;
+    const requestedEnd = focus ? Math.min(allLines.length, focus + config.after) : Math.min(allLines.length, MAX_SOURCE_CONTEXT_LINES);
+    const end = Math.min(requestedEnd, start + MAX_SOURCE_CONTEXT_LINES - 1);
+    const selected = allLines.slice(start - 1, end).join("\n");
+    const redacted = redactSourceText(selected);
+    const bounded = utf8Bound(redacted.content, MAX_SOURCE_CONTEXT_BYTES);
+    const relativePath = relative(root, candidateReal).split(sep).join("/");
+    const context = {
+      schema_version: SOURCE_ENVELOPE_VERSION,
+      origin: "ci",
+      content: bounded.content,
+      language: LANGUAGE_BY_EXTENSION.get(extname(relativePath).toLowerCase()) || "text",
+      digest: `sha256:${createHash("sha256").update(bounded.content).digest("hex")}`,
+      path: relativePath,
+      start_line: start,
+      end_line: start + bounded.content.split("\n").length - 1,
+      ...(focus ? { focus_line: focus } : {}),
+      ...(commit ? { commit: String(commit).slice(0, 80) } : {}),
+      ...((bounded.truncated || end < requestedEnd || requestedEnd < allLines.length || start > 1) ? { truncated: true } : {}),
+      ...(redacted.redactions ? { redactions: redacted.redactions } : {}),
+    };
+    return { context };
+  } catch (error) {
+    return { reason: error?.code === "ENOENT" ? "source file was not found" : "source file could not be read", path: target.path };
+  }
+}
+
+export async function collectSourceContexts({ format, body, cwd, config, commit = "" }) {
+  if (!config) return { carriers: [], captured: [], skipped: [] };
+  const configuredRoot = resolve(cwd, config.root);
+  let root;
+  try {
+    if (!inside(resolve(cwd), configuredRoot)) throw new Error("outside");
+    if (await hasSymlink(resolve(cwd), configuredRoot)) throw new Error("symlink");
+    root = await realpath(configuredRoot);
+    if (!inside(await realpath(cwd), root)) throw new Error("outside");
+  } catch {
+    throw new Error('testdossier.json "source.root" must resolve to a real, non-symlink directory inside the project.');
+  }
+  const targets = sourceTargets(format, Buffer.from(body).toString("utf8"));
+  const carriers = [];
+  const captured = [];
+  const skipped = [];
+  for (let testIndex = 0; testIndex < targets.length; testIndex += 1) {
+    const found = await readOneSource(root, targets[testIndex], config, commit);
+    if (found.context) {
+      carriers.push({ test_index: testIndex, ...found.context });
+      captured.push(found.context);
+    } else {
+      skipped.push({ test_index: testIndex, path: found.path || "", reason: found.reason });
+    }
+  }
+  return { carriers, captured, skipped };
+}
+
+export function wrapSourceEnvelope(format, body, carriers) {
+  if (!carriers?.length) return Buffer.from(body);
+  const text = Buffer.from(body).toString("utf8");
+  const report = format === "junit" ? text : JSON.parse(text.replace(/^\uFEFF/, ""));
+  return Buffer.from(JSON.stringify({
+    schema_version: SOURCE_ENVELOPE_VERSION,
+    format,
+    report,
+    source_contexts: carriers,
+  }));
+}

package/lib/testdossier.mjs

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { collectSourceContexts, parseSourceConfig, wrapSourceEnvelope } from "./source-context.mjs";
 
-export const VERSION = "0.3.0";
+export const VERSION = "0.3.2";
 const DEFAULT_ORIGIN = "https://testdossier.com";
 const ENV_FILE_NAME = ".env.testdossier";
 const CONFIG_FILE_NAME = "testdossier.json";
@@ -712,6 +713,13 @@ export async function readProjectConfig(cwd) {
     }
     config.url = value.url;
   }
+  if (value.source !== undefined) {
+    try {
+      config.source = parseSourceConfig(value.source);
+    } catch (error) {
+      throw new CliError(error.message);
+    }
+  }
   return config;
 }
 
@@ -1330,6 +1338,42 @@ export async function runCli(
       pages = splitReportPages(format, report, MAX_TESTS_PER_PAGE, document);
     }
     const testCount = pages.reduce((sum, page) => sum + (page.testCount ?? page.tests), 0);
+    const metadata = inferredMetadata(options, env);
+    let sourceCaptured = 0;
+    let sourceSkipped = 0;
+    const sourcePaths = new Map();
+    if (config?.source) {
+      for (const page of pages) {
+        // The source mapper only needs the report structure. Playwright's
+        // failure screenshots remain lazily materialized at upload time.
+        const structuralBody = playwrightUpload
+          ? playwrightUploadPageBody(document, page.tests, playwrightUpload.evidenceByTest, new Map(), false)
+          : page.body;
+        const source = await collectSourceContexts({
+          format,
+          body: structuralBody,
+          cwd,
+          config: config.source,
+          commit: metadata.build,
+        });
+        page.sourceCarriers = source.carriers;
+        sourceCaptured += source.captured.length;
+        sourceSkipped += source.skipped.length;
+        for (const context of source.captured) {
+          const key = `${context.path}:${context.start_line}-${context.end_line}`;
+          if (!sourcePaths.has(key)) sourcePaths.set(key, context);
+        }
+      }
+      stdout(`Source capture: ${sourceCaptured} of ${testCount} test records captured (${sourcePaths.size} unique snippet${sourcePaths.size === 1 ? "" : "s"}); ${sourceSkipped} skipped.`);
+      const sourcePreviewLimit = 20;
+      for (const context of [...sourcePaths.values()].slice(0, sourcePreviewLimit)) {
+        stdout(`  ${context.path}:${context.start_line}-${context.end_line} · ${context.digest.slice(0, 23)}${context.truncated ? " · truncated" : ""}${context.redactions ? ` · ${context.redactions} redaction${context.redactions === 1 ? "" : "s"}` : ""}`);
+      }
+      if (sourcePaths.size > sourcePreviewLimit) {
+        stdout(`  … ${sourcePaths.size - sourcePreviewLimit} more safe snippet paths omitted from console output.`);
+      }
+      if (sourceSkipped) stderr(`Warning: ${sourceSkipped} test record${sourceSkipped === 1 ? " had" : "s had"} no safe, readable source file and will upload without source context.`);
+    }
     const validatedBytes = playwrightUpload
       ? pages.reduce((sum, page) => sum + page.estimatedBytes, 0)
       : report.byteLength;
@@ -1348,7 +1392,6 @@ export async function runCli(
     const token = await resolveToken(options, env, cwd, stdout, stderr);
     if (typeof fetchImpl !== "function") throw new CliError("Node 18 or newer is required (global fetch is unavailable).");
 
-    const metadata = inferredMetadata(options, env);
     const baseHeaders = {
       Authorization: `Bearer ${token}`,
       "Content-Type": format === "junit" ? "application/xml" : "application/json",
@@ -1382,16 +1425,26 @@ export async function runCli(
       if (materialized?.skipped) {
         stderr(`Warning: ${materialized.skipped} failure screenshot${materialized.skipped === 1 ? " was" : "s were"} no longer readable and were skipped.`);
       }
+      const rawBody = materialized ? materialized.body : page.body;
+      const uploadBody = wrapSourceEnvelope(format, rawBody, page.sourceCarriers);
+      if (uploadBody.byteLength > MAX_REPORT_BYTES) {
+        throw new CliError("one report page plus source context exceeds the 25 MiB request limit; reduce the source window or screenshot size.");
+      }
       const result = await postWithRetry({
         endpoint,
         headers: {
           ...baseHeaders,
+          ...(page.sourceCarriers?.length ? {
+            "Content-Type": "application/json",
+            "X-TD-Source-Envelope": "1",
+            "X-CI-Format": format,
+          } : {}),
           "X-CI-Page-Id": pages.length === 1 ? pageBase : `${pageBase}-${index + 1}`,
           "X-CI-Upload-Id": pageBase,
           "X-CI-Page-Index": String(index + 1),
           "X-CI-Page-Count": String(pages.length),
         },
-        body: materialized ? materialized.body : page.body,
+        body: uploadBody,
         env,
         fetchImpl,
         stderr,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testdossier",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Upload Playwright, Cypress, Cucumber, JUnit, and JSON test evidence to TestDossier.",
   "license": "MIT",
   "type": "module",