@aperant/framework 0.13.0-next.0 → 0.15.0

package/dist/cli/commands/pr-review/detect-specialists.mjs

@@ -0,0 +1,980 @@
+/**
+ * commands/pr-review/detect-specialists.mjs — deterministic detector for the
+ * two CONDITIONAL /apt:pr-review specialists (i18n + cross-platform).
+ *
+ * Restores the 2.8 `i18n-reviewer` + `xplatform` perspectives but gates their
+ * Phase-3 spawn on a reproducible, language/platform/ecosystem-agnostic scan
+ * with a config override on top. The SKILL orchestrator NEVER decides
+ * engagement by reading the diff itself — it calls this detector and obeys the
+ * JSON (ID-01).
+ *
+ * Engagement model (spec ID-01/ID-01a/ID-02/ID-02a/ID-03/ID-03a/ID-03b):
+ *
+ *   1. Config check FIRST and short-circuit (ID-01a). `.aperant/config.json`
+ *      pr_review.specialists.{i18n,xplatform} ∈ {auto|always|never}, default
+ *      auto. `always` → engage (no scan); `never` → skip (no scan); only
+ *      `auto`/absent proceeds. Config is the TOP of the precedence chain — a
+ *      diff-introduced STRONG signal does NOT override `never`.
+ *   2. Collect signals from repo baseline ∪ PR diff (ID-02). A `--diff <path>`
+ *      flag (the orchestrator already writes diff.patch) adds changed-file
+ *      paths + added lines as diff-introduced signals.
+ *   3. Apply --scope (ID-02a). Default `repo`: baseline counts repo-wide.
+ *      `diff`: a baseline signal only counts when it shares an owning/top-level
+ *      directory with a diff-touched path; otherwise only diff signals count.
+ *   4. Decide engage via the STRONG/WEAK tier rule (ID-03a):
+ *          engage = (>= 1 STRONG signal) OR (>= 2 distinct WEAK signals)
+ *      A lone weak token never spawns a specialist.
+ *
+ * Each signal is `{ kind, detail, tier }` where `tier ∈ {strong, weak}` and
+ * `detail` names the exact match (file path / manifest dep / token + file) so
+ * the human-readable `reason` is traceable.
+ *
+ * The signal tables are CURATED + EXTENSIBLE — a new ecosystem is added by
+ * appending one entry; the engine logic is unchanged.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join, relative, resolve, sep } from 'node:path';
+import { parseFlags } from '../../util/args.mjs';
+import { err, ok } from '../../util/result.mjs';
+/**
+ * @typedef {{ kind: string, detail: string, tier: 'strong' | 'weak' }} Signal
+ *
+ * @typedef {{ engage: boolean, signals: Signal[], reason: string }} SpecialistDecision
+ */
+// Manifests scanned for dependency-substring i18n/xplatform library markers.
+// No YAML/TOML parse — substring/regex on the raw text, mirroring
+// toolchain-detect.mjs:isBerryNodeLinker (R2).
+const MANIFEST_FILES = [
+    'package.json',
+    'Cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'go.mod',
+    'Gemfile',
+    'composer.json',
+    'build.gradle',
+    'build.gradle.kts',
+    'Podfile',
+    'pubspec.yaml',
+];
+// CI workflow files scanned for a multi-OS matrix (substring of runs-on:/os:).
+const CI_FILES = ['.gitlab-ci.yml', 'azure-pipelines.yml'];
+// Directories never walked when collecting baseline file-pattern signals.
+const SKIP_DIRS = new Set([
+    '.git',
+    'node_modules',
+    '.aperant',
+    'dist',
+    'build',
+    'target',
+    '.next',
+    'vendor',
+    '.venv',
+    'venv',
+    '__pycache__',
+]);
+// Cap the baseline file walk so a huge repo can't make the detector slow.
+const MAX_WALK_FILES = 20000;
+/**
+ * Walk `root` collecting relative file paths (POSIX-normalized), skipping
+ * heavy/irrelevant dirs. Bounded by MAX_WALK_FILES.
+ *
+ * @param {string} root
+ * @returns {string[]} repo-relative paths using '/'
+ */
+function walkFiles(root) {
+    const out = [];
+    const stack = [root];
+    while (stack.length > 0 && out.length < MAX_WALK_FILES) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const abs = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name))
+                    continue;
+                stack.push(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(relative(root, abs).split(sep).join('/'));
+                if (out.length >= MAX_WALK_FILES)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+/** Read a file as UTF-8, returning '' on any error. */
+function readSafe(absPath) {
+    try {
+        if (!existsSync(absPath))
+            return '';
+        if (statSync(absPath).isDirectory())
+            return '';
+        return readFileSync(absPath, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+// ── i18n file-pattern matchers (STRONG) ─────────────────────────────────────
+// Locale/translation file EXTENSIONS that are unambiguous on their own.
+const I18N_LOCALE_EXTS = new Set([
+    '.po',
+    '.pot',
+    '.mo',
+    '.xliff',
+    '.xlf',
+    '.arb',
+    '.strings',
+    '.stringsdict',
+    '.resx',
+    '.resw',
+    '.xcstrings',
+    '.ftl',
+]);
+// Directory-name segments that mark a path as i18n/locale territory.
+const I18N_DIR_SEGMENTS = ['locales', 'i18n', 'translations'];
+/**
+ * Decide whether a repo-relative path is a STRONG i18n locale-file signal.
+ * Returns a `detail` string when it matches, else null. Encodes the ID-03 +
+ * ID-03b file-pattern rules (Android values-*, Java messages bundle, Qt *.ts
+ * disambiguation).
+ *
+ * @param {string} relPath POSIX-normalized repo-relative path
+ * @returns {string | null}
+ */
+function i18nLocaleFileDetail(relPath) {
+    const lower = relPath.toLowerCase();
+    const segments = lower.split('/');
+    const base = segments[segments.length - 1];
+    const ext = extname(lower);
+    // 1. Unambiguous locale-file extension.
+    if (I18N_LOCALE_EXTS.has(ext))
+        return `locale-file ${relPath}`;
+    // 2. Path lives under a locale/i18n/translations dir.
+    if (segments.some((s) => I18N_DIR_SEGMENTS.includes(s))) {
+        return `locale-dir file ${relPath}`;
+    }
+    // 3. lang/**/*.json
+    if (segments.includes('lang') && ext === '.json')
+        return `lang-json ${relPath}`;
+    // 4. messages.<locale>.json (e.g. messages.fr.json)
+    if (/^messages\.[a-z-]+\.json$/.test(base))
+        return `messages-json ${relPath}`;
+    // 5. Android string resources: res/values/strings.xml + res/values-*/strings.xml
+    if (base === 'strings.xml') {
+        const valuesIdx = segments.findIndex((s) => s === 'values' || s.startsWith('values-'));
+        if (valuesIdx >= 0 && segments[valuesIdx - 1] === 'res') {
+            return `android-strings ${relPath}`;
+        }
+    }
+    // 6. Java resource bundles: *_*.properties under a messages/i18n/resources dir.
+    if (/^[a-zA-Z0-9]+_[a-zA-Z]{2}(_[A-Za-z]+)?\.properties$/.test(base)) {
+        if (segments.some((s) => ['messages', 'i18n', 'resources'].includes(s))) {
+            return `java-bundle ${relPath}`;
+        }
+    }
+    // 7. Qt translation *.ts — ID-03b: ONLY under a translations/i18n dir
+    //    (a bare top-level *.ts is TypeScript and is NOT an i18n signal; a plain
+    //    source dir literally named `ts/` is the common false positive, so it is
+    //    NOT a translation-dir marker — real Qt Linguist files live under
+    //    translations/ or i18n/).
+    if (ext === '.ts') {
+        if (segments.some((s) => ['translations', 'i18n'].includes(s))) {
+            return `qt-translation ${relPath}`;
+        }
+    }
+    return null;
+}
+// ── i18n manifest-dependency matchers ───────────────────────────────────────
+// Unambiguous i18n libraries (STRONG) matched as substrings in ANY manifest
+// EXCEPT the Python-only Babel family (handled separately in
+// scanManifestForI18n because JS babel is a transpiler, NOT i18n — ID-03b).
+const I18N_LIB_SUBSTRINGS = [
+    'i18next',
+    'react-i18next',
+    'vue-i18n',
+    '@formatjs',
+    'intl-messageformat',
+    'lingui',
+    '@lingui',
+    'node-polyglot',
+    '@fluent',
+    'fluent-bundle',
+    'rust-i18n',
+    'go-i18n',
+    'gotext',
+    'symfony/translation',
+    'gettext',
+    'rails-i18n',
+];
+// Python-only Babel family (STRONG) — only counts in a Python manifest
+// (pyproject.toml / requirements.txt). ID-03b: a package.json babel* dep is
+// NEVER an i18n signal.
+const PY_BABEL_SUBSTRINGS = ['babel', 'flask-babel', 'pybabel'];
+// ACCEPTED LIMITATION (no-parse design, R2): this scans the manifest's RAW
+// text as a substring, NOT a parsed dependency graph. A library name that
+// appears in prose — e.g. `"description": "a gettext parser"` — can therefore
+// false-trigger an i18n signal. A real fix requires parsing the manifest
+// (YAML/TOML/JSON), which this detector DELIBERATELY avoids (see the file
+// header + the MANIFEST_FILES comment). The STRONG/WEAK tier model bounds the
+// blast radius for source TOKENS, but a manifest LIBRARY match is STRONG, so
+// this specific prose-substring false positive is knowingly tolerated.
+/**
+ * Scan a single manifest's raw text for i18n library substrings.
+ *
+ * @param {string} manifestName
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanManifestForI18n(manifestName, text) {
+    const found = [];
+    const lower = text.toLowerCase();
+    const isPythonManifest = manifestName === 'pyproject.toml' || manifestName === 'requirements.txt';
+    for (const lib of I18N_LIB_SUBSTRINGS) {
+        if (lower.includes(lib.toLowerCase())) {
+            found.push({ kind: 'i18n-lib', detail: `${lib} in ${manifestName}`, tier: 'strong' });
+        }
+    }
+    // Python Babel family — ID-03b. `flask-babel`/`pybabel` are unambiguous;
+    // bare `babel` only counts in a Python manifest context.
+    if (isPythonManifest) {
+        for (const lib of PY_BABEL_SUBSTRINGS) {
+            // Match `babel` as a token (word boundary) so we don't catch e.g.
+            // some unrelated `babelfish` substring; flask-babel/pybabel are
+            // matched as plain substrings.
+            const re = lib === 'babel' ? /\bbabel\b/i : new RegExp(lib.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i');
+            if (re.test(text)) {
+                found.push({
+                    kind: 'i18n-lib',
+                    detail: `python-${lib} in ${manifestName}`,
+                    tier: 'strong',
+                });
+            }
+        }
+    }
+    return found;
+}
+// ── i18n source-token matchers (WEAK unless corroborated by an i18n import) ──
+// An i18n import present in a source file makes a `t(`/`i18n.t(` token STRONG.
+const I18N_IMPORT_HINTS = [
+    'i18next',
+    'react-i18next',
+    'vue-i18n',
+    '@lingui',
+    '@formatjs',
+    'use-intl',
+    'next-intl',
+    'gettext',
+    '@fluent',
+];
+// Lone i18n source tokens (WEAK). `_(` is DROPPED entirely (ID-03b — too noisy).
+const I18N_WEAK_TOKEN_RES = [
+    { re: /\bi18n\.t\s*\(/, label: 'i18n.t(' },
+    { re: /(?<![\w.])t\s*\(\s*['"]/, label: 't(' },
+    { re: /\bgettext\s*\(/, label: 'gettext(' },
+    { re: /\bngettext\s*\(/, label: 'ngettext(' },
+    { re: /\bNSLocalizedString\s*\(/, label: 'NSLocalizedString(' },
+    { re: /\bR\.string\./, label: 'R.string.' },
+    { re: /\bString\.localized\b/, label: 'String.localized' },
+    { re: /#\[derive\(Localize\)\]/, label: '#[derive(Localize)]' },
+];
+/**
+ * Scan one source blob for i18n tokens. A `t(`/`i18n.t(` token is STRONG when
+ * an i18n import is present in the SAME blob; otherwise WEAK (ID-03b).
+ *
+ * @param {string} detailLabel  where the blob came from (file path or "diff")
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanSourceForI18nTokens(detailLabel, text) {
+    const found = [];
+    const hasI18nImport = I18N_IMPORT_HINTS.some((h) => text.includes(h));
+    for (const { re, label } of I18N_WEAK_TOKEN_RES) {
+        if (re.test(text)) {
+            const corroborated = (label === 't(' || label === 'i18n.t(') && hasI18nImport;
+            found.push({
+                kind: 'i18n-token',
+                detail: corroborated
+                    ? `${label} in ${detailLabel} (i18n import present)`
+                    : `${label} in ${detailLabel} (no i18n import)`,
+                tier: corroborated ? 'strong' : 'weak',
+            });
+        }
+    }
+    return found;
+}
+// ── xplatform matchers ──────────────────────────────────────────────────────
+// Cross-platform app frameworks (STRONG) matched as manifest substrings.
+const XPL_FRAMEWORK_SUBSTRINGS = [
+    'electron',
+    '@tauri-apps',
+    'react-native',
+    'flutter',
+    '@capacitor',
+    'nativescript',
+    'maui',
+    'xamarin',
+    'pyqt',
+    'pyside',
+    'kivy',
+];
+/**
+ * Scan a manifest for cross-platform framework substrings.
+ *
+ * @param {string} manifestName
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanManifestForXplatform(manifestName, text) {
+    const found = [];
+    const lower = text.toLowerCase();
+    for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+        if (lower.includes(fw)) {
+            found.push({
+                kind: 'xplatform-framework',
+                detail: `${fw} in ${manifestName}`,
+                tier: 'strong',
+            });
+        }
+    }
+    // Qt via a generic `qt` substring is too noisy for a manifest scan; PyQt /
+    // PySide above are the unambiguous Python Qt markers. (Qt C++ projects are
+    // caught by the compile-guard / *.ui paths instead.)
+    return found;
+}
+// Compile-time platform guards (STRONG) — source-token regexes spanning
+// Rust / Go / C/C++ / CMake / Swift.
+const XPL_COMPILE_GUARD_RES = [
+    { re: /#\[cfg\(target_os/, label: '#[cfg(target_os' },
+    { re: /\bcfg!\s*\(\s*windows\b/, label: 'cfg!(windows)' },
+    { re: /\/\/go:build\s+(windows|darwin|linux)/, label: '//go:build <os>' },
+    { re: /\bruntime\.GOOS\b/, label: 'runtime.GOOS' },
+    { re: /#ifdef\s+_WIN32/, label: '#ifdef _WIN32' },
+    { re: /#ifdef\s+__APPLE__/, label: '#ifdef __APPLE__' },
+    { re: /#ifdef\s+__linux__/, label: '#ifdef __linux__' },
+    { re: /\bif\s*\(\s*WIN32\s*\)/, label: 'if(WIN32)' },
+    { re: /\bif\s*\(\s*APPLE\s*\)/, label: 'if(APPLE)' },
+    { re: /\bif\s*\(\s*UNIX\s*\)/, label: 'if(UNIX)' },
+    { re: /#if\s+os\s*\(/, label: '#if os(' },
+];
+// Lone runtime platform checks (WEAK).
+const XPL_WEAK_TOKEN_RES = [
+    { re: /\bprocess\.platform\b/, label: 'process.platform' },
+    { re: /\bos\.platform\s*\(/, label: 'os.platform()' },
+    { re: /\bsys\.platform\b/, label: 'sys.platform' },
+    { re: /\bplatform\.system\s*\(/, label: 'platform.system()' },
+    { re: /\bRuntimeInformation\.IsOSPlatform\b/, label: 'RuntimeInformation.IsOSPlatform' },
+    { re: /System\.getProperty\s*\(\s*["']os\.name["']/, label: 'System.getProperty("os.name")' },
+    { re: /\bPlatform\.OS\b/, label: 'Platform.OS' },
+    { re: /\bPlatform\.isAndroid\b/, label: 'Platform.isAndroid' },
+];
+/**
+ * Scan one source blob for xplatform compile-guard (STRONG) + lone runtime
+ * (WEAK) tokens.
+ *
+ * @param {string} detailLabel
+ * @param {string} text
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function scanSourceForXplatformTokens(detailLabel, text) {
+    const found = [];
+    for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+        if (re.test(text)) {
+            found.push({
+                kind: 'xplatform-guard',
+                detail: `${label} in ${detailLabel}`,
+                tier: 'strong',
+            });
+        }
+    }
+    for (const { re, label } of XPL_WEAK_TOKEN_RES) {
+        if (re.test(text)) {
+            found.push({
+                kind: 'xplatform-runtime',
+                detail: `${label} in ${detailLabel}`,
+                tier: 'weak',
+            });
+        }
+    }
+    return found;
+}
+const OS_TOKEN_GROUPS = [
+    ['ubuntu', 'linux'],
+    ['macos', 'darwin', 'macos-latest'],
+    ['windows', 'windows-latest'],
+];
+// Per-family recognized RUNNER value regexes for a YAML list-item branch — these
+// must match the WHOLE list-item value (anchored), and stay INDEX-ALIGNED with
+// OS_TOKEN_GROUPS (linux, macos, windows). A list item like `- windows-build-tools`
+// or `- macos-codesign-helper` (e.g. under a `packages:` key) is NOT a recognized
+// runner and must NOT inflate the multi-OS family count, while real block-list
+// runners `- ubuntu-latest` / `- macos-latest` / `- windows-latest` / `- ubuntu-22.04`
+// still match.
+const OS_RUNNER_RES = [
+    /^(ubuntu(-(latest|\d[\w.-]*))?|linux)$/,
+    /^(macos(-(latest|\d[\w.-]*))?|darwin)$/,
+    /^(windows(-(latest|\d[\w.-]*))?)$/,
+];
+/**
+ * Detect a multi-OS CI matrix in a workflow's raw text. No YAML parse (R2) —
+ * substring scan of `runs-on:`/`os:` lines for >1 distinct OS family.
+ *
+ * @param {string} workflowName
+ * @param {string} text
+ * @returns {{kind:string, detail:string, tier:string} | null}
+ */
+function detectCiMatrix(workflowName, text) {
+    const lines = text.split('\n');
+    const osFamilies = new Set();
+    for (const line of lines) {
+        // R2: only OS-bearing config lines count — a `runs-on:` / `os:` key line,
+        // or a YAML list-item line (e.g. `- ubuntu-latest`) that sits under an
+        // `os:` matrix key without repeating the key. Scanning EVERY line would
+        // let an unrelated dep/comment/path mentioning an OS substring (e.g.
+        // `npm install windows-build-tools` under a single `runs-on: ubuntu`)
+        // inflate the family count into a phantom multi-OS matrix — exactly the
+        // false-positive the STRONG/WEAK tier model exists to prevent.
+        const isKeyLine = /\b(runs-on|os)\s*:/i.test(line);
+        const listItemMatch = line.match(/^\s*-\s+['"]?([\w.-]+)['"]?\s*$/);
+        if (!isKeyLine && !listItemMatch)
+            continue;
+        if (isKeyLine) {
+            // Key-line (`runs-on:` / `os:`) substring branch — UNCHANGED.
+            const lower = line.toLowerCase();
+            for (let gi = 0; gi < OS_TOKEN_GROUPS.length; gi++) {
+                if (OS_TOKEN_GROUPS[gi].some((tok) => lower.includes(tok)))
+                    osFamilies.add(gi);
+            }
+        }
+        else if (listItemMatch) {
+            // List-item branch — count an OS family ONLY when the WHOLE list-item
+            // value is a recognized runner token (anchored OS_RUNNER_RES). This
+            // stops a non-`os:` list like `- windows-build-tools` /
+            // `- macos-codesign-helper` (e.g. under a `packages:` key) from
+            // inflating the multi-OS family count.
+            const value = listItemMatch[1].toLowerCase();
+            for (let gi = 0; gi < OS_RUNNER_RES.length; gi++) {
+                if (OS_RUNNER_RES[gi].test(value))
+                    osFamilies.add(gi);
+            }
+        }
+    }
+    if (osFamilies.size > 1) {
+        return {
+            kind: 'xplatform-ci-matrix',
+            detail: `multi-OS CI matrix in ${workflowName} (${osFamilies.size} OS families)`,
+            tier: 'strong',
+        };
+    }
+    return null;
+}
+/**
+ * Detect platform-conditional directory siblings (STRONG) over a list of
+ * repo-relative paths: windows/ + macos/ + linux/ co-present, or
+ * *.xcodeproj + build.gradle co-presence.
+ *
+ * @param {string[]} relPaths POSIX-normalized
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function detectPlatformDirSiblings(relPaths) {
+    const found = [];
+    const hasWindowsDir = relPaths.some((p) => p.split('/').includes('windows'));
+    const hasMacosDir = relPaths.some((p) => p.split('/').includes('macos'));
+    const hasLinuxDir = relPaths.some((p) => p.split('/').includes('linux'));
+    if (hasWindowsDir && hasMacosDir && hasLinuxDir) {
+        found.push({
+            kind: 'xplatform-dir-siblings',
+            detail: 'platform dir siblings windows/ + macos/ + linux/ co-present',
+            tier: 'strong',
+        });
+    }
+    const hasXcodeproj = relPaths.some((p) => p.endsWith('.xcodeproj') || p.includes('.xcodeproj/'));
+    const hasGradle = relPaths.some((p) => {
+        const base = p.split('/').pop();
+        return base === 'build.gradle' || base === 'build.gradle.kts';
+    });
+    if (hasXcodeproj && hasGradle) {
+        found.push({
+            kind: 'xplatform-dir-siblings',
+            detail: '*.xcodeproj + build.gradle co-presence',
+            tier: 'strong',
+        });
+    }
+    return found;
+}
+/**
+ * Lone weak file signals over a path list: a *.plist or *.rc file.
+ *
+ * @param {string[]} relPaths
+ * @returns {Array<{kind:string, detail:string, tier:string}>}
+ */
+function detectWeakXplatformFiles(relPaths) {
+    const found = [];
+    for (const p of relPaths) {
+        const ext = extname(p.toLowerCase());
+        if (ext === '.plist')
+            found.push({ kind: 'xplatform-file', detail: `plist ${p}`, tier: 'weak' });
+        else if (ext === '.rc')
+            found.push({ kind: 'xplatform-file', detail: `rc ${p}`, tier: 'weak' });
+    }
+    return found;
+}
+// ── Diff parsing ─────────────────────────────────────────────────────────────
+/**
+ * Parse a unified diff into { touchedPaths: string[], addedText: string }.
+ * `touchedPaths` are POSIX-normalized repo-relative paths from the `+++ b/...`
+ * (and `--- a/...` for deletions) headers; `addedText` concatenates added
+ * lines (those starting with `+` but not `+++`).
+ *
+ * @param {string} patch
+ * @returns {{ touchedPaths: string[], addedText: string }}
+ */
+export function parseUnifiedDiff(patch) {
+    const touched = new Set();
+    const added = [];
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('+++ ')) {
+            const p = line.slice(4).trim();
+            if (p && p !== '/dev/null')
+                touched.add(stripDiffPrefix(p));
+        }
+        else if (line.startsWith('--- ')) {
+            const p = line.slice(4).trim();
+            if (p && p !== '/dev/null')
+                touched.add(stripDiffPrefix(p));
+        }
+        else if (line.startsWith('diff --git ')) {
+            // `diff --git a/x b/x` — capture both sides defensively.
+            const m = line.match(/^diff --git a\/(.+?) b\/(.+)$/);
+            if (m) {
+                touched.add(m[1]);
+                touched.add(m[2]);
+            }
+        }
+        else if (line.startsWith('+') && !line.startsWith('+++')) {
+            added.push(line.slice(1));
+        }
+    }
+    return { touchedPaths: [...touched], addedText: added.join('\n') };
+}
+function stripDiffPrefix(p) {
+    // Strip a/ b/ prefixes git emits, and any timestamp suffix after a tab.
+    let out = p.split('\t')[0];
+    if (out.startsWith('a/') || out.startsWith('b/'))
+        out = out.slice(2);
+    return out.split(sep).join('/');
+}
+// ── Engagement decision ──────────────────────────────────────────────────────
+/**
+ * Decide engage from a signal list + reason string per ID-03a, after scoping.
+ *
+ * @param {Signal[]} signals
+ * @returns {SpecialistDecision}
+ */
+function decideFromSignals(signals) {
+    const strong = signals.filter((s) => s.tier === 'strong');
+    const weak = signals.filter((s) => s.tier === 'weak');
+    if (strong.length >= 1) {
+        return {
+            engage: true,
+            signals,
+            reason: `strong: ${strong.map((s) => s.detail).join('; ')}`,
+        };
+    }
+    if (weak.length >= 2) {
+        return {
+            engage: true,
+            signals,
+            reason: `weak x${weak.length}: ${weak.map((s) => s.detail).join(' + ')}`,
+        };
+    }
+    if (weak.length === 1) {
+        return {
+            engage: false,
+            signals,
+            reason: `weak x1 uncorroborated: ${weak[0].detail} — not engaged`,
+        };
+    }
+    return { engage: false, signals, reason: 'no signals' };
+}
+// Common monorepo container dirs: a path under one of these is owned by its
+// SECOND segment (the package name), not the container itself — so
+// `packages/a/...` and `packages/b/...` are in DIFFERENT owning packages.
+const MONOREPO_CONTAINERS = new Set(['packages', 'apps', 'crates', 'libs', 'modules', 'services']);
+/**
+ * The owning directory of a repo-relative POSIX path. Used by the `--scope
+ * diff` rule to decide whether a baseline signal "shares an owning directory"
+ * with a diff-touched path. For a path under a monorepo container (e.g.
+ * `packages/a/...`) the owning dir is `packages/a` (the package), so two
+ * sibling packages don't collapse to the shared container. Otherwise it is the
+ * first path segment.
+ *
+ * @param {string} relPath
+ * @returns {string} owning dir, or '' for a top-level file
+ */
+function owningDir(relPath) {
+    const segments = relPath.split('/');
+    if (segments.length <= 1)
+        return '';
+    if (MONOREPO_CONTAINERS.has(segments[0]) && segments.length >= 3) {
+        return `${segments[0]}/${segments[1]}`;
+    }
+    return segments[0];
+}
+/**
+ * Extract a repo-relative path out of a signal `detail` string when one is
+ * present (locale files, tokens-in-file, weak files all embed a path). Returns
+ * null for path-less signals (manifest deps, CI matrices, dir-siblings) — those
+ * are treated as repo-wide and are NOT subject to diff-scoping path matching.
+ *
+ * @param {{detail:string}} signal
+ * @returns {string | null}
+ */
+function signalPath(signal) {
+    const d = signal.detail;
+    // All file/token details carry the path as the last whitespace-delimited
+    // token that contains a '/' or a recognized file extension, but we encode
+    // them as "<label> <path>" / "<label> in <path> (...)". Pull the path out.
+    const inMatch = d.match(/ in ([^\s(]+)/);
+    if (inMatch && inMatch[1].includes('/'))
+        return inMatch[1];
+    const tailMatch = d.match(/([^\s]+\/[^\s]+)$/);
+    if (tailMatch)
+        return tailMatch[1];
+    // "<label> <path>" form (e.g. "locale-file src/locales/fr.json").
+    const parts = d.split(' ');
+    const last = parts[parts.length - 1];
+    if (last?.includes('/'))
+        return last;
+    return null;
+}
+/**
+ * Apply --scope. Returns the signal subset that counts for engagement.
+ *
+ * @param {Array} baselineSignals
+ * @param {Array} diffSignals
+ * @param {string[]} diffTouchedPaths
+ * @param {'repo'|'diff'} scope
+ * @returns {{ counted: Array, scopingNote: string | null }}
+ */
+function applyScope(baselineSignals, diffSignals, diffTouchedPaths, scope) {
+    if (scope === 'repo') {
+        return { counted: [...baselineSignals, ...diffSignals], scopingNote: null };
+    }
+    // scope === 'diff': a baseline signal only counts when it shares an owning
+    // dir with a diff-touched path (or is path-less → repo-wide manifest/CI
+    // marker, which we conservatively still count). Otherwise drop it.
+    const touchedOwningDirs = new Set(diffTouchedPaths.map(owningDir));
+    const counted = [...diffSignals];
+    const dropped = [];
+    for (const sig of baselineSignals) {
+        const p = signalPath(sig);
+        if (p === null) {
+            // Path-less repo-wide marker (manifest dep / CI matrix / dir-sibling)
+            // — keep counting it; --scope diff only constrains path-bearing
+            // baseline signals.
+            counted.push(sig);
+            continue;
+        }
+        if (touchedOwningDirs.has(owningDir(p))) {
+            counted.push(sig);
+        }
+        else {
+            dropped.push(sig);
+        }
+    }
+    let scopingNote = null;
+    if (dropped.length > 0 && counted.length === diffSignals.length) {
+        // All baseline path-bearing signals were dropped as unrelated.
+        const first = dropped[0];
+        const fp = signalPath(first);
+        const touched = diffTouchedPaths.slice(0, 3).join(', ') || '(none)';
+        scopingNote = `baseline ${first.kind} signal in unrelated package ${fp}; diff touches only ${touched} (scope=diff)`;
+    }
+    return { counted, scopingNote };
+}
+/**
+ * Read `.aperant/config.json:pr_review.specialists` (best-effort).
+ *
+ * @param {string} root
+ * @returns {{ i18n?: string, xplatform?: string }}
+ */
+function readSpecialistConfig(root) {
+    try {
+        const path = join(resolve(root), '.aperant', 'config.json');
+        if (!existsSync(path))
+            return {};
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        const spec = parsed?.pr_review?.specialists;
+        return spec && typeof spec === 'object' ? spec : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Normalize a config value to auto|always|never (default auto for absent /
+ * invalid).
+ *
+ * @param {unknown} v
+ * @returns {'auto'|'always'|'never'}
+ */
+function normalizeMode(v) {
+    return v === 'always' || v === 'never' ? v : 'auto';
+}
+/**
+ * The core detector. Pure over its inputs (reads the filesystem at `root` and
+ * the supplied `diffText`); returns the full
+ * `{ i18n, xplatform }` decision object.
+ *
+ * @param {object} opts
+ * @param {string} opts.root            absolute project dir
+ * @param {string} [opts.diffText]      unified-diff text (optional)
+ * @param {'repo'|'diff'} [opts.scope]  default 'repo'
+ * @param {{i18n?:string, xplatform?:string}} [opts.config]  override config
+ *        (read from .aperant/config.json when omitted)
+ * @returns {{ i18n: SpecialistDecision, xplatform: SpecialistDecision }}
+ */
+export function detectSpecialists(opts) {
+    const root = resolve(opts.root);
+    const scope = opts.scope === 'diff' ? 'diff' : 'repo';
+    const config = opts.config ?? readSpecialistConfig(root);
+    const diffText = opts.diffText ?? '';
+    const i18nMode = normalizeMode(config.i18n);
+    const xplatformMode = normalizeMode(config.xplatform);
+    // Parse diff once (shared by both specialists).
+    const diff = diffText ? parseUnifiedDiff(diffText) : { touchedPaths: [], addedText: '' };
+    // ── i18n ──────────────────────────────────────────────────────────────
+    const i18n = decideSpecialist({
+        mode: i18nMode,
+        root,
+        diff,
+        scope,
+        collectBaseline: collectI18nBaseline,
+        collectDiff: collectI18nDiff,
+    });
+    // ── xplatform ───────────────────────────────────────────────────────────
+    const xplatform = decideSpecialist({
+        mode: xplatformMode,
+        root,
+        diff,
+        scope,
+        collectBaseline: collectXplatformBaseline,
+        collectDiff: collectXplatformDiff,
+    });
+    return { i18n, xplatform };
+}
+/**
+ * Run the full ordered decision for one specialist: config short-circuit (1) →
+ * collect baseline ∪ diff (2) → scope (3) → tier decision (4).
+ *
+ * @returns {SpecialistDecision}
+ */
+function decideSpecialist({ mode, root, diff, scope, collectBaseline, collectDiff }) {
+    // (1) Config check FIRST and absolute (ID-01a).
+    if (mode === 'always') {
+        return { engage: true, signals: [], reason: 'config override: always' };
+    }
+    if (mode === 'never') {
+        return { engage: false, signals: [], reason: 'config override: never' };
+    }
+    // (2) Collect baseline ∪ diff signals.
+    const baselineSignals = collectBaseline(root);
+    const diffSignals = collectDiff(diff);
+    // (3) Apply scope.
+    const { counted, scopingNote } = applyScope(baselineSignals, diffSignals, diff.touchedPaths, scope);
+    // (4) Tier decision.
+    const decision = decideFromSignals(counted);
+    if (!decision.engage && scopingNote && counted.length === 0) {
+        decision.reason = scopingNote;
+    }
+    else if (!decision.engage && scopingNote && decision.reason === 'no signals') {
+        decision.reason = scopingNote;
+    }
+    return decision;
+}
+// ── Per-specialist collectors ────────────────────────────────────────────────
+function collectI18nBaseline(root) {
+    const signals = [];
+    const files = walkFiles(root);
+    for (const rel of files) {
+        const detail = i18nLocaleFileDetail(rel);
+        if (detail)
+            signals.push({ kind: 'i18n-locale-file', detail, tier: 'strong' });
+    }
+    for (const manifest of MANIFEST_FILES) {
+        const abs = join(root, manifest);
+        if (!existsSync(abs))
+            continue;
+        const text = readSafe(abs);
+        if (text)
+            signals.push(...scanManifestForI18n(manifest, text));
+    }
+    return dedupeSignals(signals);
+}
+function collectI18nDiff(diff) {
+    const signals = [];
+    for (const rel of diff.touchedPaths) {
+        const detail = i18nLocaleFileDetail(rel);
+        if (detail)
+            signals.push({ kind: 'i18n-locale-file', detail: `${detail} (diff)`, tier: 'strong' });
+    }
+    if (diff.addedText) {
+        // A newly-added i18n library import counts as a manifest-equivalent
+        // strong signal when the added text mentions an unambiguous lib.
+        const lowerAdded = diff.addedText.toLowerCase();
+        for (const lib of I18N_LIB_SUBSTRINGS) {
+            if (lowerAdded.includes(lib.toLowerCase())) {
+                signals.push({ kind: 'i18n-lib', detail: `${lib} (diff added line)`, tier: 'strong' });
+            }
+        }
+        signals.push(...scanSourceForI18nTokens('diff', diff.addedText));
+    }
+    return dedupeSignals(signals);
+}
+function collectXplatformBaseline(root) {
+    const signals = [];
+    const files = walkFiles(root);
+    // Manifest frameworks.
+    for (const manifest of MANIFEST_FILES) {
+        const abs = join(root, manifest);
+        if (!existsSync(abs))
+            continue;
+        const text = readSafe(abs);
+        if (text)
+            signals.push(...scanManifestForXplatform(manifest, text));
+    }
+    // pubspec.yaml present → Flutter (its presence alone is the flutter marker).
+    if (existsSync(join(root, 'pubspec.yaml'))) {
+        signals.push({
+            kind: 'xplatform-framework',
+            detail: 'flutter (pubspec.yaml present)',
+            tier: 'strong',
+        });
+    }
+    // CI matrices — .github/workflows/*.yml + standalone CI files.
+    const workflowsDir = join(root, '.github', 'workflows');
+    if (existsSync(workflowsDir)) {
+        try {
+            for (const entry of readdirSync(workflowsDir)) {
+                if (!/\.ya?ml$/i.test(entry))
+                    continue;
+                const text = readSafe(join(workflowsDir, entry));
+                const m = detectCiMatrix(`.github/workflows/${entry}`, text);
+                if (m)
+                    signals.push(m);
+            }
+        }
+        catch {
+            /* unreadable */
+        }
+    }
+    for (const ci of CI_FILES) {
+        const abs = join(root, ci);
+        if (!existsSync(abs))
+            continue;
+        const m = detectCiMatrix(ci, readSafe(abs));
+        if (m)
+            signals.push(m);
+    }
+    // Compile-time guards in source files (scan a bounded set of source files).
+    for (const rel of files) {
+        const ext = extname(rel.toLowerCase());
+        if (['.rs', '.go', '.c', '.cc', '.cpp', '.h', '.hpp', '.swift', '.m', '.mm'].includes(ext) ||
+            rel.split('/').pop()?.toLowerCase() === 'cmakelists.txt') {
+            const text = readSafe(join(root, rel));
+            if (text) {
+                for (const { re, label } of XPL_COMPILE_GUARD_RES) {
+                    if (re.test(text)) {
+                        signals.push({ kind: 'xplatform-guard', detail: `${label} in ${rel}`, tier: 'strong' });
+                    }
+                }
+            }
+        }
+    }
+    // Platform dir siblings + weak files.
+    signals.push(...detectPlatformDirSiblings(files));
+    signals.push(...detectWeakXplatformFiles(files));
+    return dedupeSignals(signals);
+}
+function collectXplatformDiff(diff) {
+    const signals = [];
+    if (diff.addedText) {
+        const lowerAdded = diff.addedText.toLowerCase();
+        for (const fw of XPL_FRAMEWORK_SUBSTRINGS) {
+            if (lowerAdded.includes(fw)) {
+                signals.push({
+                    kind: 'xplatform-framework',
+                    detail: `${fw} (diff added line)`,
+                    tier: 'strong',
+                });
+            }
+        }
+        signals.push(...scanSourceForXplatformTokens('diff', diff.addedText));
+    }
+    // CI matrix introduced in the diff.
+    for (const rel of diff.touchedPaths) {
+        if (/\.ya?ml$/i.test(rel) && (rel.includes('.github/workflows/') || CI_FILES.includes(rel))) {
+            const m = detectCiMatrix(`${rel} (diff)`, diff.addedText);
+            if (m)
+                signals.push(m);
+        }
+    }
+    signals.push(...detectWeakXplatformFiles(diff.touchedPaths));
+    return dedupeSignals(signals);
+}
+/** De-dupe signals by `detail` (a path/token can match more than one rule). */
+function dedupeSignals(signals) {
+    const seen = new Set();
+    const out = [];
+    for (const s of signals) {
+        if (seen.has(s.detail))
+            continue;
+        seen.add(s.detail);
+        out.push(s);
+    }
+    return out;
+}
+/**
+ * CLI subcommand handler: `apt-tools pr-review detect-specialists <dir>
+ * [--diff <patch>] [--scope diff|repo]`.
+ *
+ * @param {string} projectDir
+ * @param {string[]} extraArgs
+ * @returns {import('../../util/result.mjs').CommandResult}
+ */
+export function cmdDetectSpecialists(projectDir, extraArgs = []) {
+    if (!projectDir) {
+        return err('Usage: apt-tools pr-review detect-specialists <project-dir> [--diff <patch>] [--scope diff|repo]');
+    }
+    const root = resolve(projectDir);
+    if (!existsSync(root))
+        return err(`Directory does not exist: ${root}`);
+    const flags = parseFlags(extraArgs);
+    const diffFlag = flags.get('diff');
+    let diffText = '';
+    if (typeof diffFlag === 'string') {
+        if (!existsSync(diffFlag))
+            return err(`Diff file not found: ${diffFlag}`);
+        diffText = readSafe(resolve(diffFlag));
+    }
+    const scopeFlag = flags.get('scope');
+    const scope = scopeFlag === 'diff' ? 'diff' : 'repo';
+    const result = detectSpecialists({ root, diffText, scope });
+    return ok({
+        status: 'ok',
+        command: 'pr-review-detect-specialists',
+        scope,
+        i18n: result.i18n,
+        xplatform: result.xplatform,
+    });
+}
+//# sourceMappingURL=detect-specialists.mjs.map