ccqa 1.1.0 → 1.2.0

package/dist/bin/ccqa.mjs

@@ -429,26 +429,6 @@ async function removeLegacyPerspectivesFiles(cwd) {
 	for (const path of candidates) if (await unlink(path).then(() => true).catch(() => false)) removed.push(path);
 	return removed;
 }
-/**
-* Replace (or insert) the `relatedPaths` key in the spec. Preserves every
-* other top-level field and the entire steps array. Returns the absolute
-* path that was written, or null if the spec file does not exist.
-*/
-async function updateSpecRelatedPaths(featureName, specName, relatedPaths, cwd) {
-	const specPath = join(getSpecDir(featureName, specName, cwd), SPEC_FILE);
-	const existing = await readFile(specPath, "utf-8").catch(() => null);
-	if (existing === null) return null;
-	await writeFile(specPath, stringify(stripUndefined({
-		...parseTestSpec(existing, specPath),
-		relatedPaths: relatedPaths.length > 0 ? relatedPaths : void 0
-	}), { lineWidth: 0 }), "utf-8");
-	return specPath;
-}
-function stripUndefined(obj) {
-	const out = {};
-	for (const [k, v] of Object.entries(obj)) if (v !== void 0) out[k] = v;
-	return out;
-}
 const LEGACY_RECORDING_FILES = ["actions.json", "route.md"];
 async function saveRecording(featureName, specName, actions, cwd) {
 	const specDir = getSpecDir(featureName, specName, cwd);
@@ -1891,7 +1871,7 @@ ${formatBlockList(blocks)}
 
 1. Read the codebase under cwd to find concrete strings: routes, button labels, aria-labels, page titles, placeholders. Use those exact strings in \`expected\`.
 2. If you use \`include:\` steps, verify each \`params\` key matches a declared param of the block (see the Available blocks list above).
-3. Populate \`relatedPaths\` with **provisional** glob patterns pointing at the source files this spec touches: the route/page file for each URL the spec visits, plus the component files (or their parent feature directory) that render the aria-labels, placeholders, or visible texts the spec asserts on. Prefer directory globs (e.g. \`src/features/tasks/**\`) when several files in one area are involved. Be conservative — include a path if you're unsure rather than omit it. \`ccqa trace\` will refine this list later from real browser observations.
+3. Populate \`relatedPaths\` with glob patterns pointing at the source files this spec depends on — this is the spec's final, authoritative list (nothing else updates it later, so get it right here): the route/page file for each URL the spec visits, plus the component files (or their parent feature directory) that render the aria-labels, placeholders, or visible texts the spec asserts on. Prefer directory globs (e.g. \`src/features/tasks/**\`) when several files in one area are involved. Confirm each path actually exists via \`Glob\`/\`Read\` before listing it — never guess a path by convention. Be conservative — when unsure whether a real path is relevant, include it rather than omit it (a missing path means a code change silently escapes \`drift --changed\`).
 4. Validate the (current or proposed) spec on four axes — emit one issue per finding:
    - **assertable**: each \`expected\` can be verified against a string/URL/state that exists in code.
    - **blocks**: every \`include\` resolves to a real block; every \`params\` key is declared on that block; every required param is provided.
@@ -5527,7 +5507,7 @@ async function runLiveSpecs(specs, opts) {
 	if (userPromptBundle !== null) meta("prompt", userPromptBundle.loaded.join(" + "));
 	const userPromptSuffix = userPromptBundle?.text ?? null;
 	const failureAnalysisEnabled = opts.failureAnalysis !== false;
-	const driftBySpec = failureAnalysisEnabled && opts.driftAudit !== false ? await runDriftAudit(specs, opts, cwd) : /* @__PURE__ */ new Map();
+	const driftAuditEnabled = failureAnalysisEnabled && opts.driftAudit !== false;
 	const auth = failureAnalysisEnabled ? driftAuthAvailable() : {
 		ok: false,
 		reason: "disabled"
@@ -5562,12 +5542,12 @@ async function runLiveSpecs(specs, opts) {
 				row: null
 			};
 			const row = await buildLiveReportRow(outcome, {
-				driftBySpec,
 				auth,
 				diff,
 				baseRef,
 				reportDir,
-				failureAnalysisEnabled
+				failureAnalysisEnabled,
+				driftAuditEnabled
 			}, opts, cwd);
 			await opts.report?.upsert(row);
 			return {
@@ -5587,13 +5567,13 @@ async function runLiveSpecs(specs, opts) {
 	};
 }
 /**
-* Build one spec's report row: the live-run base row plus drift findings and
-* (for a failed spec) the failure-analysis fields. Runs inside the pool worker
-* so the row can be upserted incrementally the moment the spec finishes.
+* Build one spec's report row: the live-run base row plus (for a failed spec)
+* the drift audit and failure-analysis fields. Runs inside the pool worker so
+* the row can be upserted incrementally the moment the spec finishes. The
+* drift audit only runs for failed specs — passing specs get no driftIssues,
+* matching the deterministic path.
 */
 async function buildLiveReportRow(r, ctx, opts, cwd) {
-	const key = `${r.featureName}/${r.specName}`;
-	const driftForSpec = ctx.driftBySpec.get(key) ?? null;
 	const base = await liveRunToReportResult({
 		featureName: r.featureName,
 		specName: r.specName,
@@ -5601,6 +5581,7 @@ async function buildLiveReportRow(r, ctx, opts, cwd) {
 		result: r.result,
 		reportDir: ctx.reportDir
 	});
+	const driftForSpec = ctx.driftAuditEnabled && r.result.status === "failed" ? await runDriftAuditOne(r, opts, cwd) : null;
 	const analysis = ctx.failureAnalysisEnabled && r.result.status === "failed" ? await analyzeOneLiveFailure(r, ctx.diff, ctx.baseRef, driftForSpec, ctx.auth, opts, cwd) : void 0;
 	return {
 		...base,
@@ -5624,39 +5605,31 @@ function analysisFieldsFor(a, status, failureAnalysisEnabled) {
 	return {};
 }
 /**
-* Run `analyzeDrift` against every spec and return a
-* `featureName/specName → driftIssues` map. This is a static spec↔code audit,
-* so it takes the spec list directly and runs before execution — each worker
-* then has its spec's drift context in hand for the failure-analysis prompt.
-* Drift findings are advisory — they show in the report (report.json / hub UI)
-* but do not change the live-run exit code.
+* Run `analyzeDrift` for one failed spec, used as evidence for its
+* failure-analysis prompt and shown in its report row. Mirrors the
+* deterministic path (src/run/pipeline.ts), which also scopes the audit to
+* failed specs only. Drift findings are advisory — they never change the
+* live-run exit code.
 */
-async function runDriftAudit(specs, opts, cwd) {
-	const targets = specs.map((s) => ({
-		featureName: s.featureName,
-		specName: s.specName
-	}));
-	const out = /* @__PURE__ */ new Map();
-	if (targets.length === 0) return out;
-	blank();
-	info(`drift audit: ${targets.length} spec${targets.length > 1 ? "s" : ""}`);
-	const results = await analyzeDrift({
-		targets,
+async function runDriftAuditOne(r, opts, cwd) {
+	const key = `${r.featureName}/${r.specName}`;
+	info(`drift audit: ${key}`);
+	const blocks = await loadAvailableBlocks(cwd);
+	const [result] = await analyzeDrift({
+		targets: [{
+			featureName: r.featureName,
+			specName: r.specName
+		}],
 		cwd,
-		blocks: await loadAvailableBlocks(cwd),
+		blocks,
 		...opts.model ? { model: opts.model } : {},
-		...opts.language ? { language: opts.language } : {},
-		onSpecStart: (t) => info(`  checking ${t.featureName}/${t.specName}`)
+		...opts.language ? { language: opts.language } : {}
 	});
-	for (const r of results) {
-		const key = `${r.target.featureName}/${r.target.specName}`;
-		if (r.ok) out.set(key, r.issues.length > 0 ? r.issues : null);
-		else {
-			warn(`drift audit failed for ${key}: ${r.error}`);
-			out.set(key, null);
-		}
+	if (!result || !result.ok) {
+		warn(`drift audit failed for ${key}: ${result?.error ?? "no result"}`);
+		return null;
 	}
-	return out;
+	return result.issues.length > 0 ? result.issues : null;
 }
 /**
 * Resolve `spec.session` names to a single state file to restore, fetching
@@ -10009,7 +9982,6 @@ function buildTraceSystemPrompt(input) {
 	const stepsText = input.steps.map((step) => `### ${step.id} [${step.source}]
 - **Instruction**: ${step.instruction}
 - **Expected**: ${step.expected}`).join("\n\n");
-	const relatedPathsBlock = buildRelatedPathsInstruction();
 	return `You are an expert QA engineer executing a browser E2E test. Execute each step precisely and record every browser action as a structured log line.
 
 ## Session
@@ -10279,6 +10251,9 @@ CCQA_STEP=<step-id> CCQA_ASSERT=url_contains:/dashboard agent-browser --session
 - A marked command that exits non-zero records nothing — fix the check and re-run it.
 - A marker that doesn't match its command (e.g. \`CCQA_ASSERT=1\` on a \`click\`) is ignored with a warning — never do that.
 - \`get count\` and \`get url\` exit 0 regardless of what they print. **Read the output**: if the printed count / URL contradicts the marker, the signal did NOT verify — treat it as a failed verification (emit \`ASSERTION_FAILED\` if the step cannot be confirmed another way).
+- **\`url_contains\` is opt-in, not a habit.** Emit it ONLY when a step's own \`expected\` explicitly asks about the URL or path. Do NOT add a \`url_contains\` to "prove" a login succeeded, a page loaded, or a navigation happened — confirm those with \`text_visible\` / \`element_visible\` on something the destination page renders. An unrequested URL assertion adds no coverage the visible-content assert doesn't already give, and is the single most common way an environment gets baked into a test.
+- **When you do assert a URL, the substring may come from ONE place only:** a \`\${VAR}\` URL that *this step's own instruction* opened, written as that \`\${VAR}\` followed by the literal tail after it. If the step opens \`\${APP_URL}/policies\`, assert \`\${APP_URL}/policies\` (or the tail \`/policies\`); the recorder resolves \`\${APP_URL}\` per environment. Never assert on a URL you merely *observed* — login redirects, identity-provider pages, and OAuth callbacks all live on a **different, environment-named origin** than the app, so any substring of them (host, origin, OR path) names the environment.
+- **A leading slash does NOT make a substring safe.** \`/auth-staging\`, \`/env-qa\`, \`/tenant-acme\` look like paths but are environment labels — the first segment of an identity-provider or tenant URL, not an application route. If a substring contains an environment name, a stage token (\`dev\`, \`stg\`, \`prod\`), a tenant/org name, or any fragment of a hostname, it is forbidden even with a leading slash. The only safe path substrings are stable *application* routes off the app's own origin (\`/dashboard\`, \`/policies/new\`), taken from a \`\${VAR}\` you opened — not from a redirect you watched.
 
 **Fallback text protocol** — ONLY for assert types the markers cannot express
 (\`element_enabled\`, \`element_disabled\`, \`element_checked\`,
@@ -10389,7 +10364,7 @@ RUN_COMPLETED|passed|<summary>
 RUN_COMPLETED|failed|<summary>
 \`\`\`
 
-${relatedPathsBlock}## Start
+## Start
 
 Begin by clearing cookies, then proceed straight to the first step's instruction.
 
@@ -10408,130 +10383,12 @@ AB_ACTION|cookies_clear
 Then emit \`STEP_START|step-01|...\` and execute the first step, prefixing
 every one of its agent-browser commands with \`CCQA_STEP=step-01\`. The first
 step is responsible for opening the initial URL.
-`;
-}
-function buildRelatedPathsInstruction() {
-	return `## Post-run: emit \`relatedPaths\` block
-
-After all steps are complete (regardless of pass/fail) and **before** \`RUN_COMPLETED\`, you MUST emit a single \`RELATED_PATHS\` block. The host (not you) writes these paths into the spec — your only job is to emit the block.
-
-\`relatedPaths\` is a list of glob patterns identifying the source files this spec depends on. CI uses them to decide whether a code change should trigger a drift check for this spec.
-
-**Do NOT modify any source files.** You have only \`Read\`, \`Grep\`, and \`Glob\` for source inspection. The block you emit is the only output the host uses to update the spec.
-
-**Inputs to consider:**
-- The URLs you opened (\`AB_ACTION|open|...\`)
-- The aria-labels, placeholders, and visible texts you clicked / filled / waited on
-- The component / page / route files that render those strings (find them with \`Grep\`/\`Read\`/\`Glob\`)
-
-**How to choose paths:**
-1. For each URL the test navigates to, locate the route/page file and include it (e.g. \`src/app/tasks/page.tsx\`, \`src/pages/tasks/index.tsx\`).
-2. For each unique aria-label / placeholder / visible text you interacted with, \`Grep\` the codebase, find the defining component, and include either the file or its parent feature directory.
-3. Prefer **directory globs** (e.g. \`src/features/tasks/**\`) over individual files when several related components live in the same area. Otherwise list specific files.
-4. Skip third-party files (\`node_modules/\`), build output (\`dist/\`, \`.next/\`), and generated code.
-5. Be conservative — false positives (extra paths) are fine; false negatives (missing paths) cause drift to be missed in CI. When unsure whether a path is relevant, include it.
-6. **Path base:** a path inside this working directory MUST be relative to it — the same base your \`Glob\`/\`Grep\` tools use (\`src/features/tasks/**\`, NOT the repo-root form \`apps/foo/src/features/tasks/**\`). For a file in a monorepo sibling package this spec genuinely depends on, use its **repo-root-relative** path (e.g. \`packages/ui-kit/src/FilePicker.tsx\`); never emit \`../\` forms.
-7. **Shared / design-system components:** include one only when the spec's checks depend on that component's specific behaviour (e.g. the flow exercises its file picker). Do NOT list generic primitives every screen uses (buttons, tags, dialogs, layout) — they would scope this spec into almost every UI change.
-
-**Output format (STRICT — one line per path, no leading dashes, no commentary inside the block):**
-
-\`\`\`
-RELATED_PATHS_BEGIN
-src/features/tasks/**
-src/app/tasks/page.tsx
-RELATED_PATHS_END
-\`\`\`
-
-Emit the block outside any other code block, on its own lines. If the test could not exercise the feature at all (e.g. blocked early), emit the block anyway with whatever paths you can identify; emit \`RELATED_PATHS_BEGIN\` immediately followed by \`RELATED_PATHS_END\` only if you genuinely could not identify any related file.
-
 `;
 }
 function buildTracePrompt(title) {
 	return `Execute the test for "${title}". Each step's instruction includes the URL or selector context it needs.`;
 }
 //#endregion
-//#region src/drift/parse-related-paths.ts
-/**
-* Pull a `RELATED_PATHS_BEGIN ... RELATED_PATHS_END` block out of the trace
-* agent's combined text output. Lines inside the block become entries; blank
-* lines, bullet markers, and code fences are tolerated. Returns null when the
-* agent did not emit a block at all so the caller can warn instead of silently
-* clearing the spec's existing relatedPaths.
-*/
-function parseRelatedPathsBlock(text) {
-	const match = text.match(/RELATED_PATHS_BEGIN\s*\n?([\s\S]*?)\n?RELATED_PATHS_END/);
-	if (!match || match[1] === void 0) return null;
-	const seen = /* @__PURE__ */ new Set();
-	const out = [];
-	for (const raw of match[1].split("\n")) {
-		const line = raw.replace(/^```.*$/, "").trim();
-		if (!line) continue;
-		const cleaned = line.replace(/^[-*]\s+/, "").trim();
-		if (!cleaned || seen.has(cleaned)) continue;
-		seen.add(cleaned);
-		out.push(cleaned);
-	}
-	return out;
-}
-/**
-* Normalize parsed entries to the canonical bases the drift matcher expects:
-* app-relative for files inside the working directory, repo-root-relative
-* for files outside it. Models sometimes emit an in-app path in repo-root
-* form (`apps/foo/src/...`) or an outside-package path in `../` form — both
-* would silently never match.
-*
-* `cwdPrefix` is the working directory's path relative to the repo root
-* ("" when they coincide, unknown → pass `null` to skip prefix handling).
-*/
-function normalizeRelatedPaths(paths, cwdPrefix) {
-	const out = [];
-	const warnings = [];
-	const seen = /* @__PURE__ */ new Set();
-	const push = (p) => {
-		if (!seen.has(p)) {
-			seen.add(p);
-			out.push(p);
-		}
-	};
-	for (const raw of paths) {
-		const p = raw.replace(/^\.\//, "");
-		if (cwdPrefix !== null && cwdPrefix !== "" && p.startsWith(`${cwdPrefix}/`)) {
-			push(p.slice(cwdPrefix.length + 1));
-			continue;
-		}
-		if (p.startsWith("../")) {
-			if (cwdPrefix === null || cwdPrefix === "") {
-				warnings.push(`dropped relatedPaths entry "${raw}" — it points outside the repository`);
-				continue;
-			}
-			const segments = [...cwdPrefix.split("/"), ...p.split("/")];
-			const resolved = [];
-			let escaped = false;
-			for (const seg of segments) {
-				if (seg === "" || seg === ".") continue;
-				if (seg === "..") {
-					if (resolved.length === 0) {
-						escaped = true;
-						break;
-					}
-					resolved.pop();
-				} else resolved.push(seg);
-			}
-			if (escaped || resolved.length === 0) {
-				warnings.push(`dropped relatedPaths entry "${raw}" — it points outside the repository`);
-				continue;
-			}
-			push(resolved.join("/"));
-			continue;
-		}
-		push(p);
-	}
-	return {
-		paths: out,
-		warnings
-	};
-}
-//#endregion
 //#region src/runtime/replay-validate.ts
 function isPollCheck(x) {
 	return x !== null && !Array.isArray(x) && x.kind === "poll-present";
@@ -11036,7 +10893,11 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	const expanded = expandSpec(spec, { blocks: await loadAllBlocks(opts.cwd) });
 	const envScrub = buildSpecEnvScrub(spec, expanded);
 	const envScrubMap = envScrub.map;
-	if (envScrub.unresolved.length > 0) warn(`spec references env var(s) with empty/unset values: ${envScrub.unresolved.join(", ")} — their literal trace-time values will be baked into ir.json`);
+	if (envScrub.unresolved.length > 0) {
+		warn(`spec references env var(s) that are unset at record time: ${envScrub.unresolved.join(", ")}`);
+		warn("their concrete trace-time values (e.g. navigate URLs) will be baked into ir.json instead of kept as ${VAR}, so the recording won't switch across environments.");
+		hint("load these vars before recording — pass --profile <name> (hub) or define them in .env — then re-record.");
+	}
 	meta("spec", spec.title);
 	meta("steps", expanded.length);
 	const includes = collectIncludedBlockNames(spec);
@@ -11058,7 +10919,6 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	let overallStatus = "passed";
 	const traceActions = [];
 	const stepTracker = createStepTracker();
-	let relatedPathsBuffer = null;
 	const withStepId = (action, stepId) => {
 		if (!action) return null;
 		return stepId ? {
@@ -11105,13 +10965,7 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 		if (msg.type !== "assistant") return;
 		for (const block of msg.message.content ?? []) {
 			if (block.type !== "text" || !block.text) continue;
-			const text = block.text;
-			if (relatedPathsBuffer !== null) relatedPathsBuffer += text + "\n";
-			else {
-				const idx = text.indexOf("RELATED_PATHS_BEGIN");
-				if (idx !== -1) relatedPathsBuffer = text.slice(idx) + "\n";
-			}
-			for (const line of text.split("\n")) {
+			for (const line of block.text.split("\n")) {
 				const trimmed = line.trim();
 				const status = parseStatusLine(line);
 				if (status) {
@@ -11136,13 +10990,6 @@ async function runTrace(featureName, specName, model, validationMode = "lenient"
 	meta("saved", recordingPath);
 	meta("actions", validatedActions.length);
 	meta("status", overallStatus.toUpperCase());
-	const parsedRelatedPaths = relatedPathsBuffer !== null ? parseRelatedPathsBlock(relatedPathsBuffer) : null;
-	if (parsedRelatedPaths !== null) {
-		const { paths: relatedPaths, warnings } = normalizeRelatedPaths(parsedRelatedPaths, await resolveCwdPrefix(opts.cwd));
-		for (const w of warnings) warn(w);
-		const written = await updateSpecRelatedPaths(featureName, specName, relatedPaths, opts.cwd);
-		if (written) meta("relatedPaths", `${relatedPaths.length} path(s) written to ${written}`);
-	} else warn("trace did not emit a RELATED_PATHS block; drift --changed cannot scope this spec");
 	hint(`run 'ccqa generate ${featureName}/${specName}' to generate a test script`);
 	return {
 		status: overallStatus,
@@ -11436,23 +11283,6 @@ function parseStatusLine(text) {
 	}
 	return null;
 }
-/**
-* The working directory's path relative to the git repo root ("" when they
-* coincide), used to pin relatedPaths bases. Null when git is unavailable —
-* normalization then skips prefix handling rather than guessing.
-*/
-async function resolveCwdPrefix(cwd) {
-	const { execFile } = await import("node:child_process");
-	const { promisify } = await import("node:util");
-	const { relative, resolve } = await import("node:path");
-	const dir = resolve(cwd ?? process.cwd());
-	try {
-		const { stdout } = await promisify(execFile)("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
-		return relative(stdout.trim(), dir);
-	} catch {
-		return null;
-	}
-}
 //#endregion
 //#region src/prompts/perspectives.ts
 /**

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ccqa",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "Browser test recorder powered by Claude Code and agent-browser",
   "repository": {