gitnexus 1.6.3-rc.8 → 1.6.3

package/dist/core/group/cross-impact.js

@@ -0,0 +1,441 @@
+/**
+ * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
+ * All bridge Cypher for this feature lives in this module.
+ */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { GroupNotFoundError, loadGroupConfig } from './config-parser.js';
+import { fileMatchesServicePrefix, normalizeServicePrefix, repoInSubgroup, } from './group-path-utils.js';
+import { getGroupDir } from './storage.js';
+import { closeBridgeDb, openBridgeDbReadOnly, queryBridge, readBridgeMeta } from './bridge-db.js';
+import { BRIDGE_SCHEMA_VERSION } from './bridge-schema.js';
+/** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
+export const MAX_SUPPORTED_CROSS_DEPTH = 1;
+/** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
+export const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30_000;
+const CY_NEIGHBORS_UPSTREAM = `
+MATCH (consumer:Contract)-[l:ContractLink]->(provider:Contract)
+WHERE provider.repo = $localRepo
+  AND provider.symbolUid IN $uids
+  AND provider.role = 'provider'
+RETURN consumer.repo AS neighborRepo,
+       consumer.symbolUid AS neighborUid,
+       consumer.filePath AS neighborFilePath,
+       l.matchType AS matchType,
+       l.confidence AS confidence,
+       l.contractId AS contractId,
+       consumer.type AS contractType
+`;
+const CY_NEIGHBORS_DOWNSTREAM = `
+MATCH (consumer:Contract)-[l:ContractLink]->(provider:Contract)
+WHERE consumer.repo = $localRepo
+  AND consumer.symbolUid IN $uids
+  AND consumer.role = 'consumer'
+RETURN provider.repo AS neighborRepo,
+       provider.symbolUid AS neighborUid,
+       provider.filePath AS neighborFilePath,
+       l.matchType AS matchType,
+       l.confidence AS confidence,
+       l.contractId AS contractId,
+       provider.type AS contractType
+`;
+function parseDirection(raw) {
+    if (raw === 'upstream' || raw === 'downstream')
+        return raw;
+    return null;
+}
+function clampCrossDepth(raw) {
+    const n = typeof raw === 'number' && Number.isFinite(raw) ? Math.floor(raw) : 1;
+    const d = n < 1 ? 1 : n;
+    if (d > MAX_SUPPORTED_CROSS_DEPTH) {
+        return {
+            depth: MAX_SUPPORTED_CROSS_DEPTH,
+            warning: `crossDepth was ${d}; multi-hop cross-boundary traversal beyond ${MAX_SUPPORTED_CROSS_DEPTH} is not implemented yet. Using crossDepth ${MAX_SUPPORTED_CROSS_DEPTH}.`,
+        };
+    }
+    return { depth: d };
+}
+export function validateGroupImpactParams(params) {
+    const name = String(params.name ?? '').trim();
+    const repoPath = String(params.repo ?? '').trim();
+    const target = String(params.target ?? '').trim();
+    if (!name)
+        return { ok: false, error: 'name is required' };
+    if (!repoPath)
+        return { ok: false, error: 'repo is required (group repo path, e.g. app/backend)' };
+    if (!target)
+        return { ok: false, error: 'target is required' };
+    if (params.service !== undefined &&
+        params.service !== null &&
+        String(params.service).trim() === '') {
+        return { ok: false, error: 'service must not be an empty string' };
+    }
+    const direction = parseDirection(params.direction);
+    if (!direction)
+        return { ok: false, error: 'direction must be upstream or downstream' };
+    let maxDepth = typeof params.maxDepth === 'number' && params.maxDepth > 0 ? params.maxDepth : 3;
+    if (maxDepth > 32)
+        maxDepth = 32;
+    const { depth: crossDepth, warning: crossDepthWarning } = clampCrossDepth(params.crossDepth);
+    const relationTypes = Array.isArray(params.relationTypes)
+        ? params.relationTypes.filter((t) => typeof t === 'string')
+        : undefined;
+    const includeTests = Boolean(params.includeTests);
+    let minConfidence = typeof params.minConfidence === 'number' ? params.minConfidence : 0;
+    if (minConfidence < 0)
+        minConfidence = 0;
+    if (minConfidence > 1)
+        minConfidence = 1;
+    const service = normalizeServicePrefix(params.service);
+    const subgroup = typeof params.subgroup === 'string' ? params.subgroup : undefined;
+    let timeoutMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0
+        ? params.timeoutMs
+        : typeof params.timeout === 'number' && params.timeout > 0
+            ? params.timeout
+            : DEFAULT_LOCAL_IMPACT_TIMEOUT_MS;
+    if (timeoutMs > 3_600_000)
+        timeoutMs = 3_600_000;
+    return {
+        ok: true,
+        name,
+        repoPath,
+        target,
+        direction,
+        maxDepth,
+        crossDepth,
+        crossDepthWarning,
+        relationTypes,
+        includeTests,
+        minConfidence,
+        service,
+        subgroup,
+        timeoutMs,
+    };
+}
+async function resolveGroupRepo(port, config, repoPath) {
+    const registryName = config.repos[repoPath];
+    if (!registryName) {
+        return { error: `Unknown repo path "${repoPath}" in this group.` };
+    }
+    try {
+        return await port.resolveRepo(registryName);
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+}
+async function safeLocalImpact(port, repo, impactParams, timeoutMs) {
+    let timer;
+    const impactP = port.impact(repo, impactParams).catch((err) => ({
+        error: err instanceof Error ? err.message : String(err),
+    }));
+    const timeoutP = new Promise((resolve) => {
+        timer = setTimeout(() => resolve('timeout'), timeoutMs);
+    });
+    const won = await Promise.race([
+        impactP.then((v) => ({ tag: 'impact', v })),
+        timeoutP.then(() => ({ tag: 'timeout' })),
+    ]);
+    if (timer !== undefined)
+        clearTimeout(timer);
+    if (won.tag === 'timeout') {
+        return {
+            value: { error: 'Local impact timed out', partial: true },
+            timedOut: true,
+        };
+    }
+    return { value: won.v, timedOut: false };
+}
+export function collectImpactSymbolUids(local, servicePrefix) {
+    const uids = new Set();
+    let targetFilePath;
+    const obj = local;
+    if (!obj || typeof obj !== 'object')
+        return { uids: [], targetFilePath };
+    const target = obj.target;
+    if (target?.id) {
+        targetFilePath = typeof target.filePath === 'string' ? target.filePath : undefined;
+        if (fileMatchesServicePrefix(targetFilePath, servicePrefix)) {
+            uids.add(String(target.id));
+        }
+    }
+    const byDepth = obj.byDepth;
+    if (byDepth && typeof byDepth === 'object') {
+        for (const items of Object.values(byDepth)) {
+            if (!Array.isArray(items))
+                continue;
+            for (const it of items) {
+                const row = it;
+                if (row?.id && fileMatchesServicePrefix(row.filePath, servicePrefix)) {
+                    uids.add(String(row.id));
+                }
+            }
+        }
+    }
+    return { uids: [...uids], targetFilePath };
+}
+function extractProcessNames(impact) {
+    const o = impact;
+    if (!o?.affected_processes)
+        return [];
+    return o.affected_processes.map((p) => String(p.name ?? '')).filter(Boolean);
+}
+function mergeRisk(localRisk, cross) {
+    const highConf = cross.some((c) => c.contract.confidence >= 0.85);
+    if (localRisk === 'CRITICAL')
+        return 'CRITICAL';
+    if (cross.length >= 3)
+        return 'CRITICAL';
+    if (highConf)
+        return 'HIGH';
+    if (cross.length > 0 && (localRisk === 'LOW' || localRisk === 'UNKNOWN'))
+        return 'MEDIUM';
+    return localRisk;
+}
+async function ensureBridgeReady(groupDir) {
+    const meta = await readBridgeMeta(groupDir);
+    if (meta.version > 0 && meta.version !== BRIDGE_SCHEMA_VERSION) {
+        return {
+            error: `Bridge schema version mismatch (meta.json has ${meta.version}, expected ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync for this group.`,
+        };
+    }
+    const dbPath = path.join(groupDir, 'bridge.lbug');
+    try {
+        await fsp.access(dbPath);
+    }
+    catch {
+        return {
+            error: `No bridge.lbug in this group directory. Run gitnexus group sync (schema ${BRIDGE_SCHEMA_VERSION}).`,
+        };
+    }
+    const handle = await openBridgeDbReadOnly(groupDir);
+    if (!handle) {
+        return {
+            error: `Could not open bridge.lbug read-only (schema ${BRIDGE_SCHEMA_VERSION}). Run gitnexus group sync.`,
+        };
+    }
+    return { handle };
+}
+function rowToNeighbor(r) {
+    const neighborRepo = String(r.neighborRepo ?? r[0] ?? '');
+    const neighborUid = String(r.neighborUid ?? r[1] ?? '');
+    if (!neighborRepo || !neighborUid)
+        return null;
+    return {
+        neighborRepo,
+        neighborUid,
+        neighborFilePath: r.neighborFilePath !== undefined ? String(r.neighborFilePath) : String(r[2] ?? ''),
+        matchType: String(r.matchType ?? r[3] ?? 'exact'),
+        confidence: Number(r.confidence ?? r[4] ?? 0),
+        contractId: String(r.contractId ?? r[5] ?? ''),
+        contractType: String(r.contractType ?? r[6] ?? 'custom'),
+    };
+}
+export async function runGroupImpact(deps, params) {
+    const parsed = validateGroupImpactParams(params);
+    if (parsed.ok === false)
+        return { error: parsed.error };
+    const { name, repoPath, target, direction, maxDepth, crossDepth: _crossDepth, crossDepthWarning, relationTypes, includeTests, minConfidence, service: servicePrefix, subgroup, timeoutMs, } = parsed;
+    const groupDir = getGroupDir(deps.gitnexusDir, name);
+    let config;
+    try {
+        config = await loadGroupConfig(groupDir);
+    }
+    catch (e) {
+        if (e instanceof GroupNotFoundError)
+            return { error: `Group "${name}" not found. Run group_list to see configured groups.` };
+        return { error: e instanceof Error ? e.message : String(e) };
+    }
+    const resolved = await resolveGroupRepo(deps.port, config, repoPath);
+    if ('error' in resolved)
+        return { error: resolved.error };
+    const impactParams = {
+        target,
+        direction,
+        maxDepth,
+        relationTypes: relationTypes && relationTypes.length > 0 ? relationTypes : undefined,
+        includeTests,
+        minConfidence,
+    };
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    const { value: local, timedOut: localTimedOut } = await safeLocalImpact(deps.port, resolved, impactParams, timeoutMs);
+    if (localTimedOut) {
+        const _base = local;
+        return {
+            local,
+            group: name,
+            cross: [],
+            outOfScope: [],
+            truncated: true,
+            truncatedRepos: [],
+            summary: {
+                direct: 0,
+                processes_affected: 0,
+                modules_affected: 0,
+                cross_repo_hits: 0,
+            },
+            risk: 'UNKNOWN',
+            timeoutMs,
+            truncationReason: 'timeout',
+            crossDepthWarning,
+        };
+    }
+    const localObj = local;
+    if (localObj?.error && typeof localObj.error === 'string') {
+        // Fail closed: the local-impact phase errored (missing symbol, graph-load
+        // failure, thrown exception wrapped by safeLocalImpact, or port-returned
+        // `{ error }`). Do NOT wrap it into a zero-hit success payload — callers
+        // branch on top-level `error`, and a blast-radius tool reporting "no
+        // impact" on the failure path is a false negative on a safety-critical
+        // signal. Bubble the error so consumers treat it as a failure.
+        return { error: `Local impact failed for ${repoPath}: ${localObj.error}` };
+    }
+    if (servicePrefix) {
+        const tf = localObj?.target?.filePath;
+        if (!fileMatchesServicePrefix(tf, servicePrefix)) {
+            return {
+                local: {},
+                group: name,
+                cross: [],
+                outOfScope: [],
+                truncated: false,
+                truncatedRepos: [],
+                summary: {
+                    direct: 0,
+                    processes_affected: 0,
+                    modules_affected: 0,
+                    cross_repo_hits: 0,
+                },
+                risk: 'LOW',
+                timeoutMs,
+                crossDepthWarning,
+            };
+        }
+    }
+    const { uids } = collectImpactSymbolUids(local, servicePrefix);
+    if (uids.length === 0) {
+        const s = local?.summary || {};
+        return {
+            local,
+            group: name,
+            cross: [],
+            outOfScope: [],
+            truncated: Boolean(local.partial),
+            truncatedRepos: [],
+            summary: {
+                direct: s.direct ?? 0,
+                processes_affected: s.processes_affected ?? 0,
+                modules_affected: s.modules_affected ?? 0,
+                cross_repo_hits: 0,
+            },
+            risk: String(local.risk ?? 'LOW'),
+            timeoutMs,
+            truncationReason: local.partial ? 'partial' : undefined,
+            crossDepthWarning,
+        };
+    }
+    const bridgePrep = await ensureBridgeReady(groupDir);
+    if ('error' in bridgePrep)
+        return { error: bridgePrep.error };
+    const handle = bridgePrep.handle;
+    const cross = [];
+    const outOfScope = [];
+    const truncatedRepos = [];
+    try {
+        const cypher = direction === 'upstream' ? CY_NEIGHBORS_UPSTREAM : CY_NEIGHBORS_DOWNSTREAM;
+        const rows = await queryBridge(handle, cypher, {
+            localRepo: repoPath,
+            uids,
+        });
+        const neighbors = [];
+        for (const raw of rows) {
+            const n = rowToNeighbor(raw);
+            if (n)
+                neighbors.push(n);
+        }
+        neighbors.sort((a, b) => b.confidence - a.confidence);
+        const seen = new Set();
+        for (const n of neighbors) {
+            if (servicePrefix && !fileMatchesServicePrefix(n.neighborFilePath, servicePrefix)) {
+                continue;
+            }
+            if (!repoInSubgroup(n.neighborRepo, subgroup)) {
+                outOfScope.push({
+                    from: direction === 'upstream' ? n.neighborRepo : repoPath,
+                    to: direction === 'upstream' ? repoPath : n.neighborRepo,
+                    contractId: n.contractId,
+                    confidence: n.confidence,
+                });
+                continue;
+            }
+            const key = `${n.neighborRepo}\0${n.neighborUid}\0${n.contractId}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            if (Date.now() > deadline) {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            const regName = config.repos[n.neighborRepo];
+            if (!regName)
+                continue;
+            let neighborHandle;
+            try {
+                neighborHandle = await deps.port.resolveRepo(regName);
+            }
+            catch {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            const fan = await deps.port.impactByUid(neighborHandle.id, n.neighborUid, direction, {
+                maxDepth,
+                relationTypes: relationTypes ?? [],
+                minConfidence,
+                includeTests,
+            });
+            if (fan == null) {
+                truncatedRepos.push(n.neighborRepo);
+                continue;
+            }
+            cross.push({
+                repo: regName,
+                repo_path: n.neighborRepo,
+                contract: {
+                    id: n.contractId,
+                    type: n.contractType,
+                    match_type: n.matchType || 'exact',
+                    confidence: n.confidence,
+                },
+                by_depth: (fan.byDepth ?? {}),
+                affected_processes: extractProcessNames(fan),
+            });
+        }
+    }
+    finally {
+        await closeBridgeDb(handle);
+    }
+    const localSum = local?.summary || {};
+    const localRisk = String(local.risk ?? 'LOW');
+    const localPartial = Boolean(local.partial);
+    const truncated = truncatedRepos.length > 0 || localPartial;
+    const result = {
+        local,
+        group: name,
+        cross,
+        outOfScope,
+        truncated,
+        truncatedRepos: [...new Set(truncatedRepos)],
+        summary: {
+            direct: localSum.direct ?? 0,
+            processes_affected: localSum.processes_affected ?? 0,
+            modules_affected: localSum.modules_affected ?? 0,
+            cross_repo_hits: cross.length,
+        },
+        risk: mergeRisk(localRisk, cross),
+        timeoutMs,
+        truncationReason: truncated ? 'partial' : undefined,
+        crossDepthWarning,
+    };
+    return result;
+}
+export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';

package/dist/core/group/extractors/http-patterns/php.js

@@ -1,27 +1,71 @@
 import PHP from 'tree-sitter-php';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
 /**
- * PHP HTTP plugin — Laravel `Route::get/post/...` declarations.
+ * PHP HTTP plugin.
+ *
+ * Providers:
+ *   - Laravel `Route::get/post/...`
+ *
+ * Consumers (string-literal URLs only):
+ *   - Laravel HTTP client: `Http::get/post/put/delete/patch($url)`
+ *   - Guzzle / generic object method: `$client->get/post/...($url)`
+ *   - `file_get_contents($url)`
  *
  * The pipeline already uses `PHP.php_only` for ingesting plain `.php`
  * files (see `core/tree-sitter/parser-loader.ts`), and we do the same
  * here so Laravel route files are parsed with the right grammar dialect.
+ *
+ * Scope notes: consumer patterns match string literals only. URLs built
+ * via binary concatenation (`$base . '/path'`), `sprintf`, or config
+ * lookup (`config('services.foo.base').'/path'`) are intentionally left
+ * for a follow-up — they require constant-folding the surrounding
+ * scope to be meaningful.
  */
-const LARAVEL_PATTERNS = compilePatterns({
-    name: 'php-laravel',
+const LARAVEL_ROUTE_SPEC = {
+    meta: {},
+    query: `
+    (scoped_call_expression
+      scope: (name) @scope (#eq? @scope "Route")
+      name: (name) @method (#match? @method "^(get|post|put|delete|patch)$")
+      arguments: (arguments . (argument (string) @path)))
+  `,
+};
+const HTTP_FACADE_SPEC = {
+    meta: {},
+    query: `
+    (scoped_call_expression
+      scope: (name) @scope (#eq? @scope "Http")
+      name: (name) @method (#match? @method "^(get|post|put|delete|patch)$")
+      arguments: (arguments . (argument (string) @path)))
+  `,
+};
+const GUZZLE_MEMBER_SPEC = {
+    meta: {},
+    query: `
+    (member_call_expression
+      name: (name) @method (#match? @method "^(get|post|put|delete|patch)$")
+      arguments: (arguments . (argument (string) @path)))
+  `,
+};
+const FILE_GET_CONTENTS_SPEC = {
+    meta: {},
+    query: `
+    (function_call_expression
+      function: (name) @fn (#eq? @fn "file_get_contents")
+      arguments: (arguments . (argument (string) @path)))
+  `,
+};
+const mk = (spec, suffix) => compilePatterns({
+    name: `php-${suffix}`,
     language: PHP.php_only,
-    patterns: [
-        {
-            meta: {},
-            query: `
-        (scoped_call_expression
-          scope: (name) @scope (#eq? @scope "Route")
-          name: (name) @method (#match? @method "^(get|post|put|delete|patch)$")
-          arguments: (arguments . (argument (string) @path)))
-      `,
-        },
-    ],
+    patterns: [spec],
 });
+const PHP_PATTERNS = {
+    laravelRoute: mk(LARAVEL_ROUTE_SPEC, 'laravel-route'),
+    httpFacade: mk(HTTP_FACADE_SPEC, 'http-facade'),
+    guzzleMember: mk(GUZZLE_MEMBER_SPEC, 'guzzle-member'),
+    fileGetContents: mk(FILE_GET_CONTENTS_SPEC, 'file-get-contents'),
+};
 /**
  * Extract the inner text of a PHP `string` node. The tree-sitter-php
  * grammar wraps single / double-quoted literals differently depending
@@ -30,12 +74,9 @@ const LARAVEL_PATTERNS = compilePatterns({
  * child nodes.
  */
 function phpStringText(node) {
-    // Most single-quoted strings expose their inner content through the
-    // full node text (including quotes), which unquoteLiteral strips.
     const direct = unquoteLiteral(node.text);
     if (direct !== null && direct !== node.text)
         return direct;
-    // Fall back to child string_content / string_value node if present.
     for (const child of node.children) {
         if (child.type === 'string_content' || child.type === 'string_value') {
             return child.text;
@@ -43,12 +84,29 @@ function phpStringText(node) {
     }
     return direct;
 }
+/**
+ * HTTP client helpers (`Http::`, Guzzle) are almost always called with
+ * a path relative to a configured base URL, or a full URL. File paths
+ * are rare. Accept both relative (`/api/...`) and absolute (`http(s)://`).
+ */
+function isHttpClientPath(path) {
+    return path.startsWith('/') || path.startsWith('http://') || path.startsWith('https://');
+}
+/**
+ * `file_get_contents` is used for both HTTP and filesystem reads. Only
+ * emit a consumer contract when the URL is an absolute HTTP(S) URL to
+ * avoid false positives for local file paths and stream wrappers
+ * (`php://input`, `file://`, `data:`, ...).
+ */
+function isHttpUrlLiteral(path) {
+    return path.startsWith('http://') || path.startsWith('https://');
+}
 export const PHP_HTTP_PLUGIN = {
     name: 'php-http',
     language: PHP.php_only,
     scan(tree) {
         const out = [];
-        for (const match of runCompiledPatterns(LARAVEL_PATTERNS, tree)) {
+        for (const match of runCompiledPatterns(PHP_PATTERNS.laravelRoute, tree)) {
             const methodNode = match.captures.method;
             const pathNode = match.captures.path;
             if (!methodNode || !pathNode)
@@ -65,6 +123,56 @@ export const PHP_HTTP_PLUGIN = {
                 confidence: 0.8,
             });
         }
+        for (const match of runCompiledPatterns(PHP_PATTERNS.httpFacade, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const path = phpStringText(pathNode);
+            if (path === null || !isHttpClientPath(path))
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'laravel-http',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        for (const match of runCompiledPatterns(PHP_PATTERNS.guzzleMember, tree)) {
+            const methodNode = match.captures.method;
+            const pathNode = match.captures.path;
+            if (!methodNode || !pathNode)
+                continue;
+            const path = phpStringText(pathNode);
+            if (path === null || !isHttpClientPath(path))
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'guzzle',
+                method: methodNode.text.toUpperCase(),
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
+        for (const match of runCompiledPatterns(PHP_PATTERNS.fileGetContents, tree)) {
+            const pathNode = match.captures.path;
+            if (!pathNode)
+                continue;
+            const path = phpStringText(pathNode);
+            if (path === null || !isHttpUrlLiteral(path))
+                continue;
+            out.push({
+                role: 'consumer',
+                framework: 'file-get-contents',
+                method: 'GET',
+                path,
+                name: null,
+                confidence: 0.7,
+            });
+        }
         return out;
     },
 };

package/dist/core/group/group-path-utils.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Shared service-path normalization for group tools (`service` monorepo filter)
+ * and subgroup membership checks.
+ *
+ * Inputs may originate from tree-sitter, the OS file API, or user-supplied
+ * MCP arguments, so both `\` and `/` separators are accepted. Internally we
+ * normalize to POSIX-style `/` for case-sensitive segment comparisons.
+ */
+export declare function normalizeServicePrefix(service: unknown): string | undefined;
+export declare function fileMatchesServicePrefix(filePath: string | undefined, prefix: string | undefined): boolean;
+/**
+ * True if `repoPath` is at or beneath `subgroup` (member-path prefix in
+ * `group.yaml`). Empty / missing `subgroup` matches every repo.
+ *
+ * @param exact When set, requires an exact equality match (no descendant repos).
+ */
+export declare function repoInSubgroup(repoPath: string, subgroup?: string, exact?: boolean): boolean;

package/dist/core/group/group-path-utils.js

@@ -0,0 +1,40 @@
+/**
+ * Shared service-path normalization for group tools (`service` monorepo filter)
+ * and subgroup membership checks.
+ *
+ * Inputs may originate from tree-sitter, the OS file API, or user-supplied
+ * MCP arguments, so both `\` and `/` separators are accepted. Internally we
+ * normalize to POSIX-style `/` for case-sensitive segment comparisons.
+ */
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+export function normalizeServicePrefix(service) {
+    if (service === undefined || service === null)
+        return undefined;
+    const s = toPosix(String(service)).trim().replace(/\/+$/, '');
+    return s.length > 0 ? s : undefined;
+}
+export function fileMatchesServicePrefix(filePath, prefix) {
+    if (!prefix)
+        return true;
+    if (!filePath)
+        return false;
+    const normalized = toPosix(filePath);
+    return normalized === prefix || normalized.startsWith(`${prefix}/`);
+}
+/**
+ * True if `repoPath` is at or beneath `subgroup` (member-path prefix in
+ * `group.yaml`). Empty / missing `subgroup` matches every repo.
+ *
+ * @param exact When set, requires an exact equality match (no descendant repos).
+ */
+export function repoInSubgroup(repoPath, subgroup, exact) {
+    if (!subgroup?.trim())
+        return true;
+    const s = toPosix(subgroup).replace(/\/+$/, '');
+    const r = toPosix(repoPath);
+    if (exact)
+        return r === s;
+    return r === s || r.startsWith(`${s}/`);
+}

package/dist/core/group/resolve-at-member.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Map MCP/CLI `@groupName` or `@groupName/memberPath` to a concrete member path in group.yaml.
+ */
+export declare function resolveAtGroupMemberRepoPath(groupName: string, explicitMemberPath: string | undefined): Promise<{
+    ok: true;
+    repoPath: string;
+} | {
+    ok: false;
+    error: string;
+}>;