feat(migrate): filter branches by last-analysis date (#583)

[okorach-sonar]

Summary

• Adds --branch_analyzed_after YYYY-MM-DD to extract, migrate, and transfer, plus a matching branch_analyzed_after config-file field with top-level/source/target precedence (a phase block, even set to "", always wins over the top-level value). Only branches whose last analysis is on or after the cutoff are selected.
• The project's main branch is always selected, regardless: when the date filter would otherwise exclude every branch of a project, main is force-included and a warning is logged — surfaced in migration_summary.md/PDF as a new "Force-Included Main Branches" table.
• Warns (non-fatally) when the cutoff is more than 730 days (2 years) old.
• On transfer, the two phases resolve independently rather than being merged/OR'd (unlike migrate_history) — the issue's own examples require extract and migrate to be able to use different cutoffs. The single CLI flag sets both sides identically; the config file is the only way to differ them.
• Composes with a future --branches/regexp filter (Provide a means to chose branches that will be migrated, based on the branch name #582, not yet implemented) via an independent, chainable predicate — nothing from Provide a means to chose branches that will be migrated, based on the branch name #582 is implemented here.
• Updates the mandatory live smoke suite (flag registration, exit-code matrix with real-binary-verified error text, live pipeline args, report-accuracy check) and documentation (ADVANCED-CONFIG.md + 5 other docs, JSON schema, example config) per this repo's CLAUDE.md.

Test plan

• go build ./... && go vet ./... && go test ./... — all green
• make smoke-fast (Tier 0) — 40/40 passed
• make smoke (Tiers 0/1/3) — 41/41 passed
• SMOKE_ALLOW_DESTRUCTIVE=1 make smoke-full (Tier 2, destructive) — not run in this environment (no staging SonarQube Server/Cloud credentials available); please run before merging
• Manually verified bad-date-format error text and the >730-day staleness warning against the real binary for extract, migrate, and transfer
• Added unit tests covering: nil-cutoff passthrough, on-or-after boundary semantics, main-branch force-inclusion (including a never-analyzed main), config-file tri-state precedence (including explicit-empty override), chaining with the existing --exclude_branches filter, and transfer's no-cross-side-leakage guarantee

Closes #583.

🤖 Generated with Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
1 Accepted issue
0 New dependency risks

Measures
0 Security Hotspots
96.5% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[okorach-sonar]

gitar auto-apply:on

[gitar-bot]

Code Review ✅ No issues found 3 closed / 3 findings

🟡 Medium risk · Branch-selection filters alter extract, migrate, and transfer behavior across phases

Adds --branch_analyzed_after flag and config field to filter branches by last-analysis date across extract, migrate, and transfer commands, with main branch force-inclusion and staleness warnings. Resolves extract-side force-main warning surfacing in reports, duplicate staleness advisory logging in transfer, and TROUBLESHOOTING.md sample documentation issue.

✅ 3 closed

✅ Bug: Extract-side force-main warning never reaches the report

📄 go/internal/common/branch_analyzed_after.go:21-28 📄 go/internal/extract/tasks_projectdata.go:718-732 📄 go/internal/report/summary/collect_runtime.go:409-423 📄 docs/TROUBLESHOOTING.md:473
common.ForcedMainBranchLogMessage is documented (go/internal/common/branch_analyzed_after.go:21-28) as being emitted by "extract's buildBranchMap, migrate's filterBranchesByAnalyzedAfter" and consumed by "the report pipeline that parses run logs (report/summary's eventAggregator)", and TROUBLESHOOTING.md promises the operator that "the generated migration_summary.md / PDF report gets a 'Force-Included Main Branches' table". Only the migrate side actually reaches the report: eventAggregator.applyForcedMainBranch is driven by collectRunEvents, which reads run_events.jsonl (collect_runtime.go:509), and that file is written exclusively by the migrate package (migrate/eventlog.go:238, called from migrate.go:643 via the newEventHandler tee installed at migrate.go:312-314). Extract's e.Logger is plain slog.Default() (extract/extract.go:371) with no event collector, so buildBranchMap's warning goes to stderr only. Consequence: an extract-only run, or a transfer/config that sets only source.branch_analyzed_after, silently narrows the extracted branch set and force-includes main branches with no row in the report table the docs point the operator to. Either tee extract's force-main events into an artefact the report collects, or correct the comment and docs to scope the table to the migrate phase.

✅ Quality: transfer logs the staleness advisory twice, unlabeled

📄 go/cmd/branch_analyzed_after.go:20-30 📄 go/cmd/transfer.go:550-557
validateBranchAnalyzedAfter is documented as emitting "a one-time advisory" and is "shared by extract, migrate, and transfer's cmd-layer config builders so the warning is only ever logged from one place". validateTransferConfig calls it twice — once per resolved side — so a transfer whose source and target cutoffs are both older than 730 days (the common case, since a single --branch_analyzed_after sets both sides identically via applyFlagStringBothSides) prints the identical warning twice, and because the log attr is just "branch_analyzed_after", raw with no side label the operator cannot tell the two apart or which phase each refers to. Pass a side label through so each advisory identifies its phase, or hoist the staleness check so it fires once.

✅ Quality: TROUBLESHOOTING.md sample shows a report heading that never renders

📄 docs/TROUBLESHOOTING.md:476-483 📄 go/internal/report/summary/markdown.go:426
The new TROUBLESHOOTING.md block illustrates the report output with a ## Warnings section heading, but renderMarkdownWarnings emits ## Warnings, Retries & Skips (markdown.go:426) — the PR's own smoke assertion and TestRenderMarkdownForcedMainBranches both key off that exact text. An operator searching migration_summary.md for the documented ## Warnings heading will not find it. The sample's separator row is also mis-sized (the Analysis Date column separator has one more dash than its header cell), which the PR's mdSeparatorCellRE-based table checks would not accept.

Review coverage

🧪 Functional validation 9 of 9 objectives covered

📋 Rules No rules evaluated

🤖 Auto-approval Not enabled · Set up

Implementation Status ✅ 9 of 9 objectives covered

✅ #583 - 9 of 9 objectives covered

This PR implements filtering branches by last-analysis date across extract, migrate, and transfer via CLI flags and configuration files, including main-branch force-inclusion reporting, format validation, and staleness warnings.

✅ 9 covered here

• ✅ If both --branch_analyzed_after and --branches are specified, only branches that meet BOTH conditions are selected
• ✅ The migration tool extract, migrate and transfer command should accept a parameter --branch_analyzed_after that will only select branches that were analyzed on or after the given date
• ✅ The date should be specified in ISO YYYY-MM-DD format and abort with an explicit error if incorrect
• ✅ If --branch_analyzed_after is not specified, all branches are selected for extract, transfer or migrate
• ✅ The branch_analyzed_after can be specified differently in extract and migrate
• ✅ --branch_analyzed_after can also be specified in the configuration file either at top level or in source and target config sections separately
• ✅ When --branch_analyzed_after selects no branch, the project main branch should still be selected and mentioned in reports
• ✅ If branch_analyzed_after specifies a date more than 2 years (730 days) in the past, a warning should be displayed in the logs
• ✅ The branch_analyzed_after CLI and config file option should be documented

Options ✅ Auto-apply

✅ Auto-apply is on → Gitar will commit updates to this branch.
Display: compact → Counting what did not apply, without listing it.

Comment with these commands to change the behavior for this request:

✅ Auto-apply	Compact
gitar auto-apply:off	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}