@tailor-platform/sdk-codemod 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @tailor-platform/sdk-codemod
 
+## 0.8.0
+
+### Minor Changes
+
+- [#2136](https://github.com/tailor-platform/sdk/pull/2136) [`6fba096`](https://github.com/tailor-platform/sdk/commit/6fba09676fc20e08e3325c26c0e72dc9ed4fd8f6) Thanks [@toiroakr](https://github.com/toiroakr)! - `.relation()`'s `toward.type` option is renamed to `toward.table`, since it names a target table rather than a TypeScript/GraphQL type — matching the `db.type()` → `db.table()` rename. The old spelling keeps working as a deprecated alias until v3; `tailor upgrade` offers the `v3/relation-toward-table` codemod to rewrite `toward: { type: ... }` to `toward: { table: ... }` across TypeScript/JavaScript sources. The relation's own `type` (its cardinality, e.g. `"n-1"`) is unchanged.
+
+### Patch Changes
+
+- [#2135](https://github.com/tailor-platform/sdk/pull/2135) [`5b7b676`](https://github.com/tailor-platform/sdk/commit/5b7b676740350dfe35ae479aa73da1f67c4d4f2f) Thanks [@renovate](https://github.com/apps/renovate)! - fix(deps): update dependency politty to v0.11.9
+
+## 0.7.0
+
+### Minor Changes
+
+- [#2088](https://github.com/tailor-platform/sdk/pull/2088) [`c9f91d9`](https://github.com/tailor-platform/sdk/commit/c9f91d944e4b041250979ec4438c36cabf818e14) Thanks [@dqn](https://github.com/dqn)! - The `--branch` option of `tailor setup branch` is renamed to `--target`, so it no longer collides with the subcommand name. The old spelling keeps working as a deprecated alias until v3 and prints a deprecation warning when used; `tailor upgrade` offers the `v3/setup-branch-flag-rename` codemod to rewrite `setup branch --branch` invocations across package.json scripts, shell and Windows scripts, YAML, Markdown, and JavaScript/TypeScript sources. The `--branch` option of `setup tag`, `setup preview`, and `setup coordinate` is unchanged.
+
+### Patch Changes
+
+- [#2137](https://github.com/tailor-platform/sdk/pull/2137) [`d38497a`](https://github.com/tailor-platform/sdk/commit/d38497ac214f547483028e2622d53dbf1414ecb2) Thanks [@dqn](https://github.com/dqn)! - Keep LLM review detection working in multi-major upgrades: each codemod's review detector and suspicious patterns now inspect the file as of that codemod's position in the transform chain, so a later codemod's rewrite can no longer silently hide an earlier codemod's review findings.
+
+- [#2138](https://github.com/tailor-platform/sdk/pull/2138) [`870c8cd`](https://github.com/tailor-platform/sdk/commit/870c8cdaa007adcbb8f565fe9b4d238d98c00e6d) Thanks [@dqn](https://github.com/dqn)! - Stop exporting internal declarations that were only used within their own module.
+
+- [#2089](https://github.com/tailor-platform/sdk/pull/2089) [`90948e6`](https://github.com/tailor-platform/sdk/commit/90948e6f6e1f3624a9c30595b3ff3a46ffbbced0) Thanks [@toiroakr](https://github.com/toiroakr)! - Add a targeted hint to the `Remote schema drift detected` error when every reported drift is a missing script hash — the pattern left by an environment last deployed with the pre-v2 CLI, which never wrote script hashes. The hint points at `migration sync <N>`, which is already listed as one of the general resolution options. The v2 migration guide (`docs/migration/v2.md`) now also documents that the first `tailor deploy` against such an environment needs a `migration sync` first.
+
 ## 0.6.0
 
 ### Minor Changes

package/dist/codemods/v3/relation-toward-table/scripts/transform.js

@@ -0,0 +1,233 @@
+import { l as stringValue } from "../../../ast-grep-helpers-CXtWn3RB.js";
+import { Lang, parse } from "@ast-grep/napi";
+//#region codemods/v3/relation-toward-table/scripts/transform.ts
+const LEGACY_KEY = "type";
+const NEW_KEY = "table";
+function sourceLang(filePath, source) {
+	const lowerPath = filePath.toLowerCase();
+	if (/\.(?:ts|mts|cts)$/u.test(lowerPath)) return Lang.TypeScript;
+	if (/\.(?:tsx|jsx|js)$/u.test(lowerPath)) return Lang.Tsx;
+	return source.includes("</") ? Lang.Tsx : Lang.TypeScript;
+}
+function relationBindingName(pattern) {
+	if (pattern.kind() !== "object_pattern") return null;
+	for (const child of pattern.children()) {
+		if (child.kind() === "shorthand_property_identifier_pattern" && child.text() === "relation") return child.text();
+		if (child.kind() === "pair_pattern" && stringValue(child.field("key")) === "relation") {
+			const value = child.field("value");
+			return value?.kind() === "identifier" ? value.text() : null;
+		}
+		if (child.kind() === "object_assignment_pattern") {
+			const binding = child.children().find((node) => node.kind() === "shorthand_property_identifier_pattern");
+			if (binding?.text() === "relation") return binding.text();
+		}
+	}
+	return null;
+}
+function relationAliases(root) {
+	const aliases = /* @__PURE__ */ new Set();
+	for (const pattern of root.findAll({ rule: { kind: "object_pattern" } })) {
+		const name = relationBindingName(pattern);
+		if (name) aliases.add(name);
+	}
+	return aliases;
+}
+function isRelationCall(call, aliases) {
+	const callee = call.children()[0];
+	if (!callee) return false;
+	if (callee.kind() === "identifier") return aliases.has(callee.text());
+	if (callee.kind() === "subscript_expression") {
+		const property = literalStringValue(callee.field("index"));
+		return property === null || property === "relation";
+	}
+	if (callee.kind() !== "member_expression") return false;
+	return callee.children().findLast((child) => child.kind() === "property_identifier" || child.kind() === "identifier")?.text() === "relation";
+}
+function callArgument(call) {
+	const args = call.children().find((child) => child.kind() === "arguments");
+	if (!args) return null;
+	const values = args.children().filter((child) => {
+		const kind = child.kind();
+		return kind !== "(" && kind !== ")" && kind !== "," && kind !== "comment";
+	});
+	return values.length === 1 ? values[0] : null;
+}
+function pairKey(pair) {
+	const key = pair.children()[0];
+	return stringValue(key ?? null);
+}
+function pairValue(pair) {
+	const children = pair.children();
+	const colonIndex = children.findIndex((child) => child.kind() === ":");
+	if (colonIndex === -1) return null;
+	return children.slice(colonIndex + 1).find((child) => child.kind() !== "comment") ?? null;
+}
+function objectPair(object, key) {
+	return object.children().find((child) => child.kind() === "pair" && pairKey(child) === key) ?? null;
+}
+function literalStringValue(node) {
+	if (node?.kind() !== "string") return null;
+	return stringValue(node);
+}
+function hasDynamicProperties(object) {
+	return object.children().some((child) => {
+		const kind = child.kind();
+		if (kind === "{" || kind === "}" || kind === "," || kind === "comment") return false;
+		if (kind !== "pair") return true;
+		const keyKind = child.children()[0]?.kind();
+		return keyKind !== "property_identifier" && keyKind !== "string";
+	});
+}
+/**
+* Same as {@link hasDynamicProperties}, but for a `toward` object
+* specifically: a bare `{ type }` shorthand is a safe, rewritable spelling
+* (only the key moves, matching `renameEdit`'s shorthand handling), not a
+* sign of an unsafe/computed key.
+*/
+function hasUnsafeTowardProperties(towardObject) {
+	return towardObject.children().some((child) => {
+		const kind = child.kind();
+		if (kind === "{" || kind === "}" || kind === "," || kind === "comment") return false;
+		if (kind === "shorthand_property_identifier") return false;
+		if (kind !== "pair") return true;
+		const keyKind = child.children()[0]?.kind();
+		return keyKind !== "property_identifier" && keyKind !== "string";
+	});
+}
+function findLegacyEntry(towardObject) {
+	for (const child of towardObject.children()) {
+		if (child.kind() === "shorthand_property_identifier" && child.text() === LEGACY_KEY) return {
+			node: child,
+			shorthand: true
+		};
+		if (child.kind() !== "pair") continue;
+		const key = child.children()[0];
+		if (!key) continue;
+		if (key.kind() !== "property_identifier" && key.kind() !== "string") continue;
+		if (stringValue(key) !== LEGACY_KEY) continue;
+		return {
+			node: key,
+			shorthand: false
+		};
+	}
+	return null;
+}
+function renameEdit(entry) {
+	if (entry.shorthand) return entry.node.replace(`${NEW_KEY}: ${LEGACY_KEY}`);
+	const text = entry.node.text();
+	if (entry.node.kind() !== "string") return entry.node.replace(NEW_KEY);
+	const quote = text.startsWith("'") ? "'" : text.startsWith("`") ? "`" : "\"";
+	return entry.node.replace(`${quote}${NEW_KEY}${quote}`);
+}
+function parseRoot(source, filePath) {
+	try {
+		return parse(sourceLang(filePath, source), source).root();
+	} catch {
+		return null;
+	}
+}
+/**
+* Rename `.relation()`'s `toward.type` option to `toward.table`.
+* @param source - File contents
+* @param filePath - Path to the file being transformed
+* @returns Transformed source, or null when nothing matched
+*/
+function transform(source, filePath = "") {
+	if (!source.includes("relation")) return null;
+	const root = parseRoot(source, filePath);
+	if (!root) return null;
+	const aliases = relationAliases(root);
+	const edits = [];
+	for (const call of root.findAll({ rule: { kind: "call_expression" } })) {
+		if (!isRelationCall(call, aliases)) continue;
+		const config = callArgument(call);
+		if (config?.kind() !== "object") continue;
+		if (hasDynamicProperties(config)) continue;
+		if (!objectPair(config, "type")) continue;
+		const toward = objectPair(config, "toward");
+		if (!toward) continue;
+		const towardConfig = pairValue(toward);
+		if (towardConfig?.kind() !== "object") continue;
+		if (hasUnsafeTowardProperties(towardConfig)) continue;
+		if (objectPair(towardConfig, NEW_KEY)) continue;
+		const entry = findLegacyEntry(towardConfig);
+		if (!entry) continue;
+		edits.push(renameEdit(entry));
+	}
+	return edits.length > 0 ? root.commitEdits(edits) : null;
+}
+function lineOf(node) {
+	return node.range().start.line + 1;
+}
+function excerptOf(node) {
+	return node.text().split("\n", 1)[0].trim();
+}
+/**
+* Report `.relation()` calls this transform cannot safely rewrite: a
+* non-object call argument, a computed/spread key on the config or `toward`
+* object, or a `toward` reached through something other than a literal
+* object (e.g. a shared variable).
+* @param source - File contents
+* @param filePath - Path to the file being reviewed
+* @param relativePath - Repository-relative path reported to the user
+* @returns Findings for occurrences needing a manual rename
+*/
+function reviewFindings(source, filePath, relativePath) {
+	if (!source.includes("relation")) return [];
+	const root = parseRoot(source, filePath);
+	if (!root) return [];
+	const aliases = relationAliases(root);
+	const findings = [];
+	for (const call of root.findAll({ rule: { kind: "call_expression" } })) {
+		if (!isRelationCall(call, aliases)) continue;
+		const config = callArgument(call);
+		if (config?.kind() !== "object") {
+			if (config) findings.push({
+				file: relativePath,
+				line: lineOf(call),
+				message: "This .relation() call's config isn't a literal object; check its toward.type manually.",
+				excerpt: excerptOf(call)
+			});
+			continue;
+		}
+		if (hasDynamicProperties(config)) {
+			findings.push({
+				file: relativePath,
+				line: lineOf(config),
+				message: "A computed/spread key on this .relation() config may hide toward.type.",
+				excerpt: excerptOf(config)
+			});
+			continue;
+		}
+		const toward = objectPair(config, "toward");
+		if (!toward) continue;
+		const towardConfig = pairValue(toward);
+		if (towardConfig?.kind() !== "object") {
+			findings.push({
+				file: relativePath,
+				line: lineOf(toward),
+				message: "This .relation() call's toward isn't a literal object; rename type to table by hand.",
+				excerpt: excerptOf(toward)
+			});
+			continue;
+		}
+		if (hasUnsafeTowardProperties(towardConfig)) {
+			findings.push({
+				file: relativePath,
+				line: lineOf(towardConfig),
+				message: "A computed/spread key on this toward object may hide type.",
+				excerpt: excerptOf(towardConfig)
+			});
+			continue;
+		}
+		if (objectPair(towardConfig, NEW_KEY) && findLegacyEntry(towardConfig)) findings.push({
+			file: relativePath,
+			line: lineOf(towardConfig),
+			message: "This toward object has both table and type; remove the deprecated type by hand instead of automatically renaming it (would produce a duplicate key).",
+			excerpt: excerptOf(towardConfig)
+		});
+	}
+	return findings;
+}
+//#endregion
+export { transform as default, reviewFindings };

package/dist/codemods/v3/setup-branch-flag-rename/scripts/transform.js

@@ -0,0 +1,76 @@
+import * as path from "pathe";
+//#region codemods/v3/setup-branch-flag-rename/scripts/transform.ts
+const TOKEN_SEPARATOR = "(?:[ \\t]|\\\\\\r?\\n)+";
+const COMMAND_START = new RegExp(`(?<![\\w.-])tailor(?:-sdk)?(?:\\.(?:cmd|ps1|exe))?${TOKEN_SEPARATOR}setup${TOKEN_SEPARATOR}branch(?![\\w.-])`, "g");
+const NEXT_TOKEN = new RegExp(`${TOKEN_SEPARATOR}("[^"\\n]*"|'[^'\\n]*'|[^\\s;&|]+)`, "y");
+function replaceCommand(value) {
+	let result = "";
+	let cursor = 0;
+	COMMAND_START.lastIndex = 0;
+	for (let match = COMMAND_START.exec(value); match; match = COMMAND_START.exec(value)) {
+		let pos = COMMAND_START.lastIndex;
+		result += value.slice(cursor, pos);
+		NEXT_TOKEN.lastIndex = pos;
+		for (let token = NEXT_TOKEN.exec(value); token; token = NEXT_TOKEN.exec(value)) {
+			const chunk = token[0];
+			const word = token[1];
+			if (word.startsWith("#")) break;
+			const quoted = /^(['"])(--branch(?:=.*)?)\1$/.exec(word);
+			const quote = quoted ? quoted[1] : "";
+			const bare = quoted ? quoted[2] : word;
+			if (bare === "--branch" || bare.startsWith("--branch=")) {
+				const separator = chunk.slice(0, chunk.length - word.length);
+				result += `${separator}${quote}--target${bare.slice(8)}${quote}`;
+			} else result += chunk;
+			pos = NEXT_TOKEN.lastIndex;
+			if (/\$\(|`|<\(|>\(/.test(word)) break;
+		}
+		cursor = pos;
+		COMMAND_START.lastIndex = pos;
+	}
+	result += value.slice(cursor);
+	return result;
+}
+function transformText(source) {
+	const updated = replaceCommand(source);
+	return updated === source ? null : updated;
+}
+function transformPackageJson(source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(source);
+	} catch {
+		return null;
+	}
+	let modified = false;
+	const scripts = parsed.scripts;
+	if (typeof scripts === "object" && scripts != null && !Array.isArray(scripts)) for (const [name, value] of Object.entries(scripts)) {
+		if (typeof value !== "string") continue;
+		const updated = replaceCommand(value);
+		if (updated !== value) {
+			scripts[name] = updated;
+			modified = true;
+		}
+	}
+	if (!modified) return null;
+	const trailing = source.endsWith("\n") ? "\n" : "";
+	return JSON.stringify(parsed, null, 2) + trailing;
+}
+/**
+* Rename the `--branch` option of `tailor setup branch` invocations to
+* `--target`.
+*
+* `--branch` remains as a deprecated alias until v3, where only
+* `--target` is recognized. `setup tag`, `setup preview`, and
+* `setup coordinate` keep their own `--branch` option unchanged.
+* @param source - File contents
+* @param filePath - Absolute path to the file (used to dispatch package.json vs text)
+* @returns Transformed source or null when nothing matched.
+*/
+function transform(source, filePath) {
+	if (!source.includes("--branch")) return null;
+	if (path.extname(filePath).toLowerCase() === ".json") return transformPackageJson(source);
+	return transformText(source);
+}
+//#endregion
+export { transform as default };

package/dist/index.js

@@ -123,6 +123,7 @@ const V2_NEXT_6 = "2.0.0-next.6";
 const V2_NEXT_7 = "2.0.0-next.7";
 const V2_NEXT_9 = "2.0.0-next.9";
 const V2_NEXT_11 = "2.0.0-next.11";
+const SETUP_BRANCH_RESIDUAL_FLAG = /(?:(?<![\w.-])tailor(?:-sdk)?(?:\.(?:cmd|ps1|exe))?|@tailor-platform\/sdk(?:@\S{1,32})?)[\s\\^`]{1,16}setup[\s\\^`]{1,16}branch\b(?:'[^'\n]*'|"[^"\n]*"|[^\n;&|'"#]|[\\^`]\r?\n)*(?:[ \t]|[\\^`]\r?\n)--branch(?![\w-])/;
 /** All registered codemods, in registration order. */
 const allCodemods = [
 	{
@@ -671,7 +672,7 @@ const allCodemods = [
 			after: [
 				"ownerId: db.uuid().relation({",
 				"  type: \"n-1\",",
-				"  toward: { type: user, as: \"user\" },",
+				"  toward: { table: user, as: \"user\" },",
 				"}),"
 			].join("\n")
 		}],
@@ -816,7 +817,11 @@ const allCodemods = [
 			"  them to StartWorkflowOptions / ExecJobFunctionOptions.",
 			"- An invoker option passed via a variable or spread (not a literal object) —",
 			"  the codemod only inspects literal object arguments; rename the invoker key",
-			"  to authInvoker in the options object's own definition."
+			"  to authInvoker in the options object's own definition.",
+			"- A renamed triggerJobFunction call whose target is another workflow job —",
+			"  rewrite it further to that job's own .start() method (e.g. worker.start(args)).",
+			"  Calling execJobFunction directly is not detected as a build-time dependency",
+			"  and fails the build."
 		].join("\n")
 	},
 	{
@@ -849,7 +854,45 @@ const allCodemods = [
 			"- mockWorkflow().startJobFunction in tests — assert on the execJobFunction vi.fn",
 			"  instead; the alias was the same mock function.",
 			"- A file that already imports ExecJobFunctionOptions alongside the removed type —",
-			"  rename the remaining references by hand and drop the duplicate specifier."
+			"  rename the remaining references by hand and drop the duplicate specifier.",
+			"- A renamed call whose target is another workflow job — rewrite it further to",
+			"  that job's own .start() method (e.g. worker.start(args)). Calling",
+			"  execJobFunction directly is not detected as a build-time dependency and fails",
+			"  the build."
+		].join("\n")
+	},
+	{
+		id: "v3/remove-workflow-exec-job-function",
+		name: "workflow.execJobFunction (imported) removed — use job.start()",
+		description: "`execJobFunction` on the `workflow` value imported from @tailor-platform/sdk/runtime(/workflow) is removed in v3. Calling it directly from a workflow job body to reach another job is not detected as a build-time dependency and has no working use; the target job's own `.start()` method is the only supported way to call it. This does not affect the ambient `tailor.workflow.execJobFunction` global — that's what `.start()` itself compiles down to at build time, and it remains fully supported.",
+		since: "1.0.0",
+		until: "3.0.0",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		suspiciousPatterns: ["execJobFunction"],
+		examples: [{
+			before: "import { workflow } from \"@tailor-platform/sdk/runtime\";\n\nawait workflow.execJobFunction(\"worker\", { id: 1 });",
+			after: "import { worker } from \"./jobs/worker\";\n\nawait worker.start({ id: 1 });"
+		}],
+		prompt: [
+			"workflow.execJobFunction — the value imported from",
+			"@tailor-platform/sdk/runtime or @tailor-platform/sdk/runtime/workflow — is",
+			"removed in v3. Replace each call with the target job's own .start() method:",
+			"import the WorkflowJob the call names and call <job>.start(args, options)",
+			"instead of workflow.execJobFunction(\"<job-name>\", args, options).",
+			"",
+			"This only removes the re-export from @tailor-platform/sdk/runtime. It does",
+			"not affect the ambient tailor.workflow.execJobFunction global, which stays",
+			"fully supported and is what .start() itself compiles down to at build time.",
+			"This codemod does not rewrite ambient tailor.workflow.execJobFunction(...)",
+			"call sites, since removing the import re-export does not affect them — but",
+			"if such a call site sits inside workflow job source and calls another job",
+			"by name, a separate build-time check already rejects it; migrate that call",
+			"to the target job's own .start() method too.",
+			"",
+			"If the job name passed to execJobFunction is not a string literal (a truly",
+			"dynamic dispatch), there is currently no supported replacement — .start()",
+			"only targets a statically known job. Flag this case for a human instead of",
+			"guessing a rewrite."
 		].join("\n")
 	},
 	{
@@ -1036,6 +1079,15 @@ const allCodemods = [
 		prereleaseUntil: V2_NEXT_1,
 		notice: true
 	},
+	{
+		id: "v2/tailordb-timestamps-required",
+		name: "`db.fields.timestamps()`: `updatedAt` becomes required",
+		description: "The `updatedAt` field from `db.fields.timestamps()` changes from optional to required (non-null): it defaults to the current time and keeps refreshing automatically on every update, though a value you provide explicitly is still respected. Applying this change to a table that already has rows with `updatedAt: null` makes `deploy` fail with `field \"updatedAt\" cannot be updated from non-required to required when records with null values exist`. Backfill those rows first, e.g. `UPDATE <table> SET \"updatedAt\" = \"createdAt\" WHERE \"updatedAt\" IS NULL` for each affected table — see [TailorDB migrations](../services/tailordb-migration.md#performance-and-large-tables) for splitting a large backfill across primary-key ranges if a single `UPDATE` times out.",
+		since: "1.0.0",
+		until: "2.0.0",
+		prereleaseUntil: V2_NEXT_2,
+		notice: true
+	},
 	{
 		id: "v2/rename-bin",
 		name: "tailor-sdk binary → tailor",
@@ -1450,7 +1502,7 @@ const allCodemods = [
 	{
 		id: "v2/node-minimum-22-15-0",
 		name: "Node.js minimum version raised to 22.15.0",
-		description: "v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. The actual floor is now **22.18.0**: Node 22.15.0–22.17.x has a bug ([nodejs/node#58607](https://github.com/nodejs/node/issues/58607)) that crashes `tailor seed validate` when requiring `node:`-scheme-only builtins such as `node:sqlite`, fixed upstream in 22.18.0. No source change is required; ensure your environment runs Node.js 22.18.0+.",
+		description: "v2 requires Node.js **22.15.0** or later. This is the first version that includes `module.registerHooks()`, which the SDK uses to register its TypeScript loader hook synchronously in the main thread. The actual floor is now **22.18.0**: Node 22.15.0–22.17.x has a bug that crashes `tailor seed validate` when requiring `node:`-scheme-only builtins such as `node:sqlite`, fixed upstream by [nodejs/node#58612](https://github.com/nodejs/node/pull/58612) in 22.18.0. No source change is required; ensure your environment runs Node.js 22.18.0+.",
 		since: "1.0.0",
 		until: "2.0.0",
 		notice: true
@@ -1463,6 +1515,14 @@ const allCodemods = [
 		until: "2.0.0",
 		notice: true
 	},
+	{
+		id: "v2/tailordb-script-hash-migration-sync",
+		name: "First v2 deploy to a v1-deployed environment needs migration sync",
+		description: "The pre-v2 CLI never wrote a script hash into deployed schemas, so the first `tailor deploy` against an environment last deployed with it reports `Remote schema drift detected` with every scripted type showing `has no script hash on remote`. Run `tailor tailordb migration sync <current migration number>` once for that environment to write the missing hashes, then `tailor deploy` as usual. Preview/PR workspaces don't hit this, since they're built with v2 from the start. No source change is required.",
+		since: "1.0.0",
+		until: "2.0.0",
+		notice: true
+	},
 	{
 		id: "v2/dts-env-value-types",
 		name: "tailor.d.ts Env uses value types instead of literal values",
@@ -1525,6 +1585,68 @@ const allCodemods = [
 			"`function run`. Leave prose that merely mentions the old subcommand name",
 			"unchanged unless it documents a command to type."
 		].join("\n")
+	},
+	{
+		id: "v3/setup-branch-flag-rename",
+		name: "setup branch --branch → --target",
+		description: "Rename the `--branch` option of `tailor setup branch` invocations to `--target`. `--branch` remains as a deprecated alias until it is removed in v3. The `--branch` option of `setup tag`, `setup preview`, and `setup coordinate` is unchanged.",
+		since: "1.72.0",
+		until: "3.0.0",
+		scriptPath: "v3/setup-branch-flag-rename/scripts/transform.js",
+		filePatterns: [
+			"**/package.json",
+			"**/*.{sh,bash,zsh,ps1,cmd,bat,yml,yaml}",
+			"**/*.md",
+			"**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+		],
+		legacyPatterns: [SETUP_BRANCH_RESIDUAL_FLAG],
+		sourceStringLegacyPatterns: [SETUP_BRANCH_RESIDUAL_FLAG],
+		examples: [{
+			lang: "sh",
+			before: "tailor setup branch --name my-app-stg --branch main",
+			after: "tailor setup branch --name my-app-stg --target main"
+		}],
+		prompt: [
+			"The `--branch` option of `tailor setup branch` is renamed to `--target`;",
+			"the old spelling is removed in v3. Replace any remaining `--branch` options of",
+			"`setup branch` invocations the codemod did not rewrite (e.g. wrapped across",
+			"lines or invoked through a package runner such as `npx @tailor-platform/sdk`)",
+			"with `--target`. Do not touch the `--branch` option of `setup tag`,",
+			"`setup preview`, or `setup coordinate`, which keeps its name, and leave prose",
+			"that merely mentions the option unchanged unless it documents a command to type."
+		].join("\n")
+	},
+	{
+		id: "v3/relation-toward-table",
+		name: "relation() toward.type → toward.table",
+		description: "Rename the `.relation()` option `toward.type` to `toward.table`, matching the `db.type()` → `db.table()` rename. The relation's own `type` (its cardinality, e.g. `\"n-1\"`) is unchanged — only the target-table reference nested under `toward` moves.",
+		since: "1.0.0",
+		until: "3.0.0",
+		scriptPath: "v3/relation-toward-table/scripts/transform.js",
+		filePatterns: ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"],
+		examples: [{
+			before: [
+				"customerId: db.uuid().relation({",
+				"  type: \"n-1\",",
+				"  toward: { type: customer },",
+				"}),"
+			].join("\n"),
+			after: [
+				"customerId: db.uuid().relation({",
+				"  type: \"n-1\",",
+				"  toward: { table: customer },",
+				"}),"
+			].join("\n")
+		}],
+		prompt: [
+			"In Tailor SDK v3, `.relation()`'s `toward.type` option is renamed to",
+			"`toward.table` (it names a target table, not a TypeScript/GraphQL type).",
+			"Rename any remaining `toward.type` the codemod did not rewrite (e.g. a",
+			"`toward` object reached through a shared variable, spread, or computed",
+			"key) to `toward.table`. Do not touch the relation's own outer `type`",
+			"property, which is the relation's cardinality (e.g. \"n-1\", \"1-1\",",
+			"\"keyOnly\") and keeps its name."
+		].join("\n")
 	}
 ];
 /**
@@ -2025,6 +2147,27 @@ function legacyPatternWarnings(relative, content, sourceStringContent, sourceTex
 		return [`${relative}: contains ${Array.from(found).join(", ")} but was not migrated automatically (rule: ${lt.id}). Manual migration may be needed.`];
 	});
 }
+function lineRemapper(before, after) {
+	const hunks = structuredPatch("", "", before, after, "", "", { context: 0 }).hunks;
+	const lastLine = Math.max(1, after.split("\n").length - (after.endsWith("\n") ? 1 : 0));
+	const map = (line) => {
+		let offset = 0;
+		for (const hunk of hunks) {
+			if (line < hunk.oldStart) break;
+			if (hunk.oldLines === 0) {
+				offset += hunk.newLines;
+				continue;
+			}
+			if (line < hunk.oldStart + hunk.oldLines) {
+				if (hunk.newLines === 0) return hunk.newStart;
+				return Math.min(hunk.newStart + (line - hunk.oldStart), hunk.newStart + hunk.newLines - 1);
+			}
+			offset += hunk.newLines - hunk.oldLines;
+		}
+		return line + offset;
+	};
+	return (line) => Math.min(lastLine, Math.max(1, map(line)));
+}
 function compareReviewFindings(a, b) {
 	return a.file.localeCompare(b.file) || a.line - b.line || a.message.localeCompare(b.message) || a.excerpt.localeCompare(b.excerpt);
 }
@@ -2032,6 +2175,9 @@ function compareReviewFindings(a, b) {
 * Run multiple codemods on a project directory using in-memory chaining.
 * Each file is processed through all transforms whose filePatterns match it.
 * Later transforms see earlier transforms' output — even in dry-run mode.
+* Review detection (reviewFindings and suspicious patterns) runs against each
+* codemod's own position in the transform chain, so a later codemod's rewrite
+* cannot hide an earlier codemod's findings.
 *
 * In dry-run mode, colorized diffs are printed to stderr.
 * @param codemods - Codemod packages to run (with resolved script paths)
@@ -2077,25 +2223,41 @@ async function runCodemods(codemods, targetPath, dryRun) {
 			continue;
 		}
 		let current = original;
+		const reviewTargets = [];
 		for (const lt of matchedTransforms) {
-			if (!lt.transform) continue;
-			const result = await lt.transform(current, absolute);
-			if (result != null) {
-				current = result;
-				appliedCodemodIds.add(lt.id);
+			if (lt.transform) {
+				const result = await lt.transform(current, absolute);
+				if (result != null) {
+					current = result;
+					appliedCodemodIds.add(lt.id);
+				}
 			}
+			if (lt.prompt) reviewTargets.push({
+				lt,
+				snapshot: current
+			});
 		}
 		if (current !== original) {
 			filesModified.push(absolute);
 			if (dryRun) printDiff(absolute, original, current);
 			else await fs.promises.writeFile(absolute, current, "utf-8");
 		}
-		const residualContent = contentForResidualMatching(relative, current);
-		const sourceStringContent = sourceStringContentForResidualMatching(relative, current);
+		const residualBySnapshot = /* @__PURE__ */ new Map();
+		const residualFor = (content) => {
+			let entry = residualBySnapshot.get(content);
+			if (!entry) {
+				entry = {
+					residual: contentForResidualMatching(relative, content),
+					sourceString: sourceStringContentForResidualMatching(relative, content)
+				};
+				residualBySnapshot.set(content, entry);
+			}
+			return entry;
+		};
+		const { residual: residualContent, sourceString: sourceStringContent } = residualFor(current);
 		const sourceTextContent = sourceTextContentForResidualMatching(relative, current);
 		warnings.push(...legacyPatternWarnings(relative, residualContent, sourceStringContent, sourceTextContent, matchedTransforms));
-		for (const lt of matchedTransforms) {
-			if (!lt.prompt) continue;
+		for (const { lt, snapshot } of reviewTargets) {
 			const filesForReview = () => {
 				let files = suspiciousByCodemod.get(lt.id);
 				if (!files) {
@@ -2105,7 +2267,14 @@ async function runCodemods(codemods, targetPath, dryRun) {
 				return files;
 			};
 			if (lt.reviewFindings) {
-				const findings = await lt.reviewFindings(current, absolute, relative);
+				let findings = await lt.reviewFindings(snapshot, absolute, relative);
+				if (snapshot !== current && findings.length > 0) {
+					const remap = lineRemapper(snapshot, current);
+					findings = findings.map((finding) => ({
+						...finding,
+						line: remap(finding.line)
+					}));
+				}
 				if (findings.length > 0) {
 					const files = filesForReview();
 					for (const finding of findings) files.add(finding.file);
@@ -2117,7 +2286,9 @@ async function runCodemods(codemods, targetPath, dryRun) {
 					existing.push(...findings);
 				}
 			}
-			if (lt.suspiciousPatterns.some((p) => matchResidualPattern(residualContent, p) !== null) || sourceStringContent != null && lt.sourceStringSuspiciousPatterns.some((p) => matchResidualPattern(sourceStringContent, p) !== null)) filesForReview().add(relative);
+			if (lt.suspiciousPatterns.length === 0 && lt.sourceStringSuspiciousPatterns.length === 0) continue;
+			const { residual, sourceString } = residualFor(snapshot);
+			if (lt.suspiciousPatterns.some((p) => matchResidualPattern(residual, p) !== null) || sourceString != null && lt.sourceStringSuspiciousPatterns.some((p) => matchResidualPattern(sourceString, p) !== null)) filesForReview().add(relative);
 		}
 	}
 	const llmReviews = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailor-platform/sdk-codemod",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Codemod runner for Tailor Platform SDK upgrades",
   "license": "MIT",
   "repository": {
@@ -21,7 +21,7 @@
     "pathe": "2.0.3",
     "picomatch": "4.0.5",
     "pkg-types": "2.3.1",
-    "politty": "0.11.6",
+    "politty": "0.11.9",
     "semver": "7.8.5",
     "zod": "4.4.3"
   },
@@ -30,7 +30,8 @@
     "@types/picomatch": "4.0.3",
     "@types/semver": "7.8.0",
     "eslint-plugin-zod": "4.9.1",
-    "oxlint": "1.76.0",
+    "oxlint": "1.78.0",
+    "oxlint-tsgolint": "7.0.2001",
     "tsdown": "0.22.14",
     "typescript": "6.0.3",
     "vitest": "4.1.10",
@@ -42,11 +43,11 @@
   },
   "scripts": {
     "build": "tsdown",
-    "lint": "oxlint .",
-    "lint:fix": "oxlint . --fix",
+    "lint": "oxlint --type-aware .",
+    "lint:fix": "oxlint --type-aware . --fix",
+    "knip": "knip",
     "typecheck": "tsc --noEmit",
     "test": "vitest",
-    "prepublish": "pnpm run build",
     "publint": "publint --strict"
   },
   "bin": {