@aperant/framework 0.13.0 → 0.15.0

package/src/cli/commands/merge-integrate.mjs

@@ -0,0 +1,392 @@
+/**
+ * commands/merge-integrate.mjs — `apt-tools merge integrate` (GitHub issue #397).
+ *
+ * The fan-out PR-integration phase. After a fan-out run, N workers each opened
+ * an independent PR against the same base; nothing ordered or reconciled them.
+ * This command SERIALIZES that batch: it resolves the task → branch/PR set,
+ * computes a deterministic merge order (topological when `depends_on` edges
+ * exist, else stable by task id), and probes each branch's mergeability against
+ * the CURRENT base via the EXACT same `git merge-tree` detection the `detect`
+ * subcommand uses (#395). It emits a structured integration report the
+ * conductor renders and the `apt:merge-conflict-resolution` flow consumes for
+ * any conflicted branch.
+ *
+ * READ-ONLY, like `detect`/`markers`: NO `git merge`, NO `git rebase`, NO index
+ * mutation, NO `gh pr merge`. The SKILL.md prose owns every state change; this
+ * primitive only OBSERVES and ORDERS. Conflict resolution stays agent-inline —
+ * the framework CLI is self-contained ESM and MUST NOT import @aperant/core
+ * (see GitHub issue #390 for the architecture decision). When a branch probes
+ * `mergeable: false`, this command surfaces the conflict envelope (the worker's
+ * worktree + base ref + conflicts_preview) and the agent resolves it inline via
+ * `/apt:merge-conflict-resolution`, then re-runs `integrate` to re-probe.
+ *
+ * Reuse, not reinvent (#397):
+ *   - detection            → `gitTry` / `parseConflictPaths` / `isGitVersionTooOld`
+ *                            promoted in audit-branch-current.mjs (#395).
+ *   - batch resolution     → the same `--tasks`/`--batch` shape fan-out.mjs uses;
+ *                            task records read from the shared `.aperant/state.json`
+ *                            board (resolveMainRepoRoot — state-fork-fix).
+ *   - dependency graph     → `buildDependsOnMap` (graph/depends-on.mjs), which
+ *                            already normalizes `depends_on` edges to bare ids.
+ *
+ *   apt-tools merge integrate <project-dir> --tasks <id,id,...> [--base <ref>]
+ *   apt-tools merge integrate <project-dir> --batch <batch-id>  [--base <ref>]
+ *
+ * --tasks   Explicit canonical task-id list (what `fan-out resolve` returns and
+ *           the conductor already holds). Primary form.
+ * --batch   Recover the task-id list from the batch's worker rows
+ *           `.aperant/team-status/fanout-<batch>-<task>.json` (the agent-id
+ *           format fan-out.mjs spawns workers with: `fanout-${batch}-${task}`).
+ * --base    Override the base ref every branch is probed against. When omitted,
+ *           each task is probed against `origin/<its base_branch>` (falling back
+ *           to `origin/main` when the record carries no base_branch).
+ *
+ * @internal
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { buildDependsOnMap } from '../graph/depends-on.mjs'
+import { parseFlags } from '../util/args.mjs'
+import { err, ok } from '../util/result.mjs'
+import { resolveMainRepoRoot } from '../util/state-paths.mjs'
+import { gitTry, isGitVersionTooOld, parseConflictPaths } from './audit-branch-current.mjs'
+
+/**
+ * Parse a PR number from a `pr_url` string (full GitHub URL or `#123` short
+ * form). Returns null if not parseable. Incidental metadata for the report —
+ * the integration order/probe never depends on it.
+ *
+ * @param {unknown} url
+ * @returns {number | null}
+ */
+function extractPrNumber(url) {
+	if (typeof url !== 'string') return null
+	const m1 = url.match(/\/pull\/(\d+)(?:[?#/]|$)/)
+	if (m1) return Number.parseInt(m1[1], 10)
+	const m2 = url.match(/#(\d+)$/)
+	if (m2) return Number.parseInt(m2[1], 10)
+	const m3 = url.match(/^(\d+)$/)
+	if (m3) return Number.parseInt(m3[1], 10)
+	return null
+}
+
+/**
+ * Read the shared ephemeral board (`state.json`). Anchors to the MAIN repo so
+ * it resolves identically from any worktree (state-fork-fix), matching how
+ * fan-out.mjs reads it.
+ *
+ * @param {string} targetDir
+ * @returns {object | null}
+ */
+function readState(targetDir) {
+	const statePath = join(resolveMainRepoRoot(targetDir), '.aperant', 'state.json')
+	if (!existsSync(statePath)) return null
+	try {
+		return JSON.parse(readFileSync(statePath, 'utf-8'))
+	} catch {
+		return null
+	}
+}
+
+/**
+ * Recover a batch's task-id list from its worker rows. Fan-out spawns each
+ * worker with `APT_AGENT_ID=fanout-<batch>-<task>`, which materializes one
+ * `.aperant/team-status/fanout-<batch>-<task>.json` per worker. We list that
+ * directory and strip the shared prefix to recover the task ids.
+ *
+ * @param {string} targetDir
+ * @param {string} batchId
+ * @returns {string[]}
+ */
+function recoverBatchTaskIds(targetDir, batchId) {
+	const statusDir = join(resolveMainRepoRoot(targetDir), '.aperant', 'team-status')
+	if (!existsSync(statusDir)) return []
+	const prefix = `fanout-${batchId}-`
+	const ids = []
+	let entries
+	try {
+		entries = readdirSync(statusDir)
+	} catch {
+		return []
+	}
+	for (const name of entries) {
+		if (!name.endsWith('.json')) continue
+		const base = name.slice(0, -'.json'.length)
+		if (base.startsWith(prefix)) {
+			const taskId = base.slice(prefix.length)
+			if (taskId) ids.push(taskId)
+		}
+	}
+	return ids
+}
+
+/**
+ * Order the batch's task ids. Topological (Kahn) over the batch SUBSET when any
+ * member has a `depends_on` edge to another member, else a stable alphabetical
+ * sort by task id (deterministic). A dependency cycle (or any unresolvable
+ * ordering) falls back to the stable order with a warning rather than throwing.
+ *
+ * Reuses `buildDependsOnMap` so the edge normalization matches the rest of the
+ * framework's graph handling exactly.
+ *
+ * @param {string[]} taskIds
+ * @param {object | null} state
+ * @returns {{ order: string[], strategy: 'topological' | 'stable', warnings: string[] }}
+ */
+function orderTasks(taskIds, state) {
+	const stable = [...taskIds].sort()
+	const inBatch = new Set(taskIds)
+	const warnings = []
+
+	const depMap = buildDependsOnMap(state || {})
+	// Restrict edges to within-batch dependencies — cross-batch deps don't gate
+	// the integration order (those PRs aren't part of this serialization).
+	const deps = new Map()
+	let edgeCount = 0
+	for (const id of taskIds) {
+		// buildDependsOnMap already normalizes deps to bare task_ids, so the
+		// entries are consumed directly (no re-parse — a re-parse would split a
+		// colon-bearing id and drop the constraint). De-dupe so a task that lists
+		// the same dependency twice doesn't overcount its Kahn indegree (which
+		// would strand it below zero-indegree and mis-flag a valid graph as a
+		// cycle).
+		const within = []
+		const seen = new Set()
+		for (const depId of depMap.get(id) || []) {
+			if (inBatch.has(depId) && depId !== id && !seen.has(depId)) {
+				seen.add(depId)
+				within.push(depId)
+				edgeCount++
+			}
+		}
+		deps.set(id, within)
+	}
+
+	if (edgeCount === 0) {
+		return { order: stable, strategy: 'stable', warnings }
+	}
+
+	// Kahn's algorithm — a task lands AFTER its dependencies (deps merge first).
+	const indegree = new Map(taskIds.map((id) => [id, 0]))
+	for (const id of taskIds) {
+		for (const _dep of deps.get(id) || []) {
+			indegree.set(id, (indegree.get(id) || 0) + 1)
+		}
+	}
+	// Ready = zero remaining unmet deps. Process in stable order for determinism.
+	const ready = taskIds.filter((id) => (indegree.get(id) || 0) === 0).sort()
+	const order = []
+	while (ready.length > 0) {
+		const id = ready.shift()
+		order.push(id)
+		// Decrement indegree of every task that depends on `id`.
+		const newlyReady = []
+		for (const other of taskIds) {
+			if ((deps.get(other) || []).includes(id)) {
+				const d = (indegree.get(other) || 0) - 1
+				indegree.set(other, d)
+				if (d === 0) newlyReady.push(other)
+			}
+		}
+		for (const r of newlyReady) ready.push(r)
+		// Re-sort the whole queue (not just the newly-ready tail) so ties across
+		// rounds resolve in strict alphabetical order — fully deterministic.
+		ready.sort()
+	}
+
+	if (order.length !== taskIds.length) {
+		// Cycle or unresolvable ordering — fall back to stable, deterministic.
+		warnings.push(
+			'dependency cycle detected among batch tasks — falling back to stable task-id order',
+		)
+		return { order: stable, strategy: 'stable', warnings }
+	}
+	return { order, strategy: 'topological', warnings }
+}
+
+/**
+ * Probe one task's branch against the base. Mirrors the `detect` subcommand's
+ * merge-tree semantics exactly (#395) — same gitTry call, same exit-code
+ * branching — so the integrate report and a standalone `merge detect` agree.
+ *
+ * @param {string} worktreeDir
+ * @param {string} base
+ * @param {string} head
+ * @returns {{ mergeable: boolean | null, conflicts_preview?: string[], audit_warning?: string }}
+ */
+function probeBranch(worktreeDir, base, head) {
+	const probe = gitTry(worktreeDir, ['merge-tree', '--write-tree', '--no-messages', head, base])
+	if (probe.ok) return { mergeable: true }
+	if (probe.code === 1 && probe.stdout.trim().length > 0) {
+		return { mergeable: false, conflicts_preview: parseConflictPaths(probe.stdout) }
+	}
+	if (isGitVersionTooOld(probe.stderr)) {
+		return { mergeable: null, audit_warning: 'git-version-too-old' }
+	}
+	return { mergeable: null, audit_warning: 'merge-tree-probe-failed' }
+}
+
+/**
+ * `apt-tools merge integrate` — serialize a fan-out batch into base.
+ *
+ * @param {string} targetDir
+ * @param {string[]} extraArgs
+ * @returns {import('../util/result.mjs').CommandResult}
+ */
+export function mergeIntegrate(targetDir, extraArgs) {
+	const flags = parseFlags(extraArgs)
+	const hasTasks = flags.has('tasks')
+	const hasBatch = flags.has('batch')
+
+	if (!hasTasks && !hasBatch) {
+		return err('One of --tasks <id,id,...> or --batch <batch-id> is required for merge integrate')
+	}
+	if (hasTasks && hasBatch) {
+		return err('Pass only one of --tasks or --batch to merge integrate')
+	}
+
+	const state = readState(targetDir)
+
+	let taskIds = []
+	let source = ''
+	if (hasTasks) {
+		taskIds = String(flags.get('tasks') || '')
+			.split(',')
+			.map((s) => s.trim())
+			.filter(Boolean)
+		source = 'tasks'
+		if (taskIds.length === 0) {
+			return err('--tasks resolved to an empty list')
+		}
+	} else {
+		const batchId = String(flags.get('batch') || '').trim()
+		if (!batchId) return err('--batch requires a batch id')
+		taskIds = recoverBatchTaskIds(targetDir, batchId)
+		source = 'batch'
+		if (taskIds.length === 0) {
+			return err(`No worker rows found for batch "${batchId}" — nothing to integrate`)
+		}
+	}
+
+	// parseFlags yields `true` for a bare `--base` with no following value; reject
+	// it rather than silently probing against the ref literal "true".
+	let baseOverride = null
+	if (flags.has('base')) {
+		const raw = flags.get('base')
+		if (raw === true || String(raw).trim() === '') {
+			return err('--base requires a ref value (e.g. --base origin/main)')
+		}
+		baseOverride = String(raw).trim()
+	}
+
+	const { order, strategy, warnings } = orderTasks(taskIds, state)
+
+	const tasks = []
+	let merged = 0
+	let conflicted = 0
+	let needsHuman = 0
+
+	for (const id of order) {
+		const task = state?.active_tasks?.[id] || null
+
+		// Tasks with no shipped branch can't be integrated — record them so the
+		// conductor sees why, but never block the rest of the batch.
+		if (!task) {
+			needsHuman++
+			tasks.push({ task_id: id, status: 'unknown', reason: 'task not found in state.json' })
+			continue
+		}
+		const branch = typeof task.branch === 'string' ? task.branch : null
+		const prUrl = typeof task.pr_url === 'string' ? task.pr_url : null
+		const worktree =
+			typeof task.worktree_path === 'string' && existsSync(task.worktree_path)
+				? resolve(task.worktree_path)
+				: null
+
+		if (!prUrl) {
+			needsHuman++
+			tasks.push({
+				task_id: id,
+				branch,
+				status: 'skipped',
+				reason: 'no pr_url on task record (not shipped) — nothing to integrate',
+			})
+			continue
+		}
+		if (!worktree) {
+			needsHuman++
+			tasks.push({
+				task_id: id,
+				branch,
+				pr_url: prUrl,
+				pr_number: extractPrNumber(prUrl),
+				status: 'needs-human',
+				reason: 'worktree_path missing or no longer on disk — cannot probe mergeability',
+			})
+			continue
+		}
+
+		const taskBaseBranch =
+			typeof task.base_branch === 'string' && task.base_branch ? task.base_branch : 'main'
+		const base = baseOverride || `origin/${taskBaseBranch}`
+		const probe = probeBranch(worktree, base, 'HEAD')
+
+		const entry = {
+			task_id: id,
+			branch,
+			pr_url: prUrl,
+			pr_number: extractPrNumber(prUrl),
+			worktree_path: worktree,
+			base,
+			mergeable: probe.mergeable,
+		}
+		if (probe.conflicts_preview && probe.conflicts_preview.length > 0) {
+			entry.conflicts_preview = probe.conflicts_preview
+		}
+		if (probe.audit_warning) entry.audit_warning = probe.audit_warning
+
+		if (probe.mergeable === true) {
+			merged++
+			entry.status = 'mergeable'
+			entry.action = 'advance'
+		} else if (probe.mergeable === false) {
+			conflicted++
+			entry.status = 'conflicted'
+			// Hand-off envelope for /apt:merge-conflict-resolution — the agent
+			// resolves these markers inline then re-runs `integrate` to re-probe.
+			entry.action = 'resolve-conflict'
+			entry.resolution = {
+				skill: 'apt:merge-conflict-resolution',
+				worktree_path: worktree,
+				base,
+			}
+		} else {
+			needsHuman++
+			entry.status = 'needs-human'
+			entry.action = 'probe-failed'
+		}
+		tasks.push(entry)
+	}
+
+	const envelope = {
+		status: 'ok',
+		command: 'merge-integrate',
+		projectDir: targetDir,
+		source,
+		order_strategy: strategy,
+		order,
+		summary: {
+			total: tasks.length,
+			mergeable: merged,
+			conflicted,
+			needs_human: needsHuman,
+		},
+		tasks,
+	}
+	if (warnings.length > 0) envelope.warnings = warnings
+	return ok(envelope)
+}
+
+// Test-only export for unit-level coverage of the ordering core.
+export { orderTasks as __orderTasksForTests }

package/src/cli/commands/pr-review/__fixtures__/android-strings/app/src/main/res/values-fr/strings.xml

@@ -0,0 +1,3 @@
+<resources>
+  <string name="hello">Bonjour</string>
+</resources>

package/src/cli/commands/pr-review/__fixtures__/babel-js/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "webapp",
+  "devDependencies": { "@babel/core": "^7.0.0", "babel-loader": "^9.0.0" }
+}

package/src/cli/commands/pr-review/__fixtures__/c-ifdef/src/main.c

@@ -0,0 +1,4 @@
+#include <stdio.h>
+#ifdef _WIN32
+void f() {}
+#endif

package/src/cli/commands/pr-review/__fixtures__/ci-matrix/.github/workflows/ci.yml

@@ -0,0 +1,10 @@
+name: ci
+on: [push]
+jobs:
+  test:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - run: echo hi

package/src/cli/commands/pr-review/__fixtures__/cmake-win/CMakeLists.txt

@@ -0,0 +1,5 @@
+cmake_minimum_required(VERSION 3.10)
+project(demo)
+if(WIN32)
+  message("win")
+endif()

package/src/cli/commands/pr-review/__fixtures__/diffs/add-arb.patch

@@ -0,0 +1,9 @@
+diff --git a/lib/l10n/app_fr.arb b/lib/l10n/app_fr.arb
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/lib/l10n/app_fr.arb
+@@ -0,0 +1,3 @@
++{
++  "hello": "Bonjour"
++}

package/src/cli/commands/pr-review/__fixtures__/diffs/ci-single-os-dep.patch

@@ -0,0 +1,13 @@
+diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
+new file mode 100644
+index 0000000..1111111
+--- /dev/null
++++ b/.github/workflows/ci.yml
+@@ -0,0 +1,6 @@
++name: ci
++on: [push]
++jobs:
++  build:
++    runs-on: ubuntu-latest
++    steps:
++      - run: npm install windows-build-tools

package/src/cli/commands/pr-review/__fixtures__/diffs/ci-single-os-list-item-dep.patch

@@ -0,0 +1,17 @@
+diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
+new file mode 100644
+index 0000000..2222222
+--- /dev/null
++++ b/.github/workflows/ci.yml
+@@ -0,0 +1,11 @@
++name: ci
++on: [push]
++jobs:
++  build:
++    runs-on: ubuntu-latest
++    steps:
++      - uses: actions/setup-node@v4
++      - run: npm install
++    packages:
++      - windows-build-tools
++      - macos-codesign-helper

package/src/cli/commands/pr-review/__fixtures__/diffs/lone-weak-t.patch

@@ -0,0 +1,8 @@
+diff --git a/src/app.ts b/src/app.ts
+index 1111111..2222222 100644
+--- a/src/app.ts
++++ b/src/app.ts
+@@ -1,2 +1,3 @@
+ export function greet() {
++  return t('hello');
+ }

package/src/cli/commands/pr-review/__fixtures__/diffs/monorepo-b.patch

@@ -0,0 +1,7 @@
+diff --git a/packages/b/src/index.ts b/packages/b/src/index.ts
+index 1111111..2222222 100644
+--- a/packages/b/src/index.ts
++++ b/packages/b/src/index.ts
+@@ -1,1 +1,2 @@
+ export const x = 1;
++export const y = 2;

package/src/cli/commands/pr-review/__fixtures__/diffs/two-weak-xpl.patch

@@ -0,0 +1,12 @@
+diff --git a/scripts/build.js b/scripts/build.js
+index 1111111..2222222 100644
+--- a/scripts/build.js
++++ b/scripts/build.js
+@@ -1,1 +1,2 @@
++if (process.platform === 'win32') {}
+diff --git a/scripts/postinstall.js b/scripts/postinstall.js
+index 3333333..4444444 100644
+--- a/scripts/postinstall.js
++++ b/scripts/postinstall.js
+@@ -1,1 +1,2 @@
++const p = os.platform();

package/src/cli/commands/pr-review/__fixtures__/dropped-underscore/src/app.js

@@ -0,0 +1,2 @@
+const x = _(value).map(f);
+const y = __name__;

package/src/cli/commands/pr-review/__fixtures__/electron-app/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "myapp",
+  "dependencies": { "electron": "^30.0.0" }
+}

package/src/cli/commands/pr-review/__fixtures__/i18n-locale-file/src/locales/fr.json

@@ -0,0 +1 @@
+{"hello":"Bonjour"}

package/src/cli/commands/pr-review/__fixtures__/monorepo/packages/a/locales/fr.json

@@ -0,0 +1 @@
+{"hi":"salut"}

package/src/cli/commands/pr-review/__fixtures__/monorepo/packages/b/src/index.ts

@@ -0,0 +1 @@
+export const x = 1;

package/src/cli/commands/pr-review/__fixtures__/py-babel/pyproject.toml

@@ -0,0 +1,3 @@
+[project]
+name = "myflaskapp"
+dependencies = ["flask", "flask-babel"]

package/src/cli/commands/pr-review/__fixtures__/qt-i18n-dir/i18n/app_fr.ts

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE TS>
+<TS version="2.1" language="fr_FR">
+<context>
+    <name>MainWindow</name>
+    <message>
+        <source>Hello</source>
+        <translation>Bonjour</translation>
+    </message>
+</context>
+</TS>

package/src/cli/commands/pr-review/__fixtures__/rust-cli/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "mycli"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+clap = "4"

package/src/cli/commands/pr-review/__fixtures__/rust-cli/src/main.rs

@@ -0,0 +1 @@
+fn main() { println!("hello"); }

package/src/cli/commands/pr-review/__fixtures__/ts-dir/ts/foo.ts

@@ -0,0 +1,3 @@
+export function foo(): string {
+	return 'plain typescript, not a Qt translation'
+}