arceus-s 1.6.4

package/dist/core/group/bridge-schema.js

@@ -0,0 +1,55 @@
+/**
+ * Bridge LadybugDB schema for cross-repo Contract Registry.
+ * Separate from per-repo schema in lbug/schema.ts.
+ */
+/**
+ * Version of the bridge.lbug schema below. `openBridgeDbReadOnly` compares
+ * this against `meta.json`'s version field and returns `null` on mismatch,
+ * which trips the caller into either the JSON fallback path or a fresh
+ * `group sync` that rebuilds `bridge.lbug` from scratch.
+ *
+ * Migration contract for contributors bumping this constant:
+ *   1. Bump the number (e.g. `1` → `2`).
+ *   2. Update the DDL below to match the new schema.
+ *   3. DO NOT attempt an online migration in this file — the version gate
+ *      is intentionally a "discard and re-sync" strategy for V1. An old
+ *      bridge.lbug whose version doesn't match is treated as opaque and
+ *      rebuilt by the next `group sync`.
+ *   4. If online migration becomes necessary (e.g. when groups accumulate
+ *      large amounts of embedding data), add a migration path as a
+ *      separate `bridge-migrations.ts` module rather than bloating this
+ *      file — keep schema and migration concerns separate.
+ */
+export const BRIDGE_SCHEMA_VERSION = 1;
+export const CONTRACT_SCHEMA = `
+CREATE NODE TABLE Contract (
+  id STRING,
+  contractId STRING,
+  type STRING,
+  role STRING,
+  repo STRING,
+  service STRING DEFAULT '',
+  symbolUid STRING DEFAULT '',
+  filePath STRING DEFAULT '',
+  symbolName STRING DEFAULT '',
+  confidence DOUBLE DEFAULT 0.0,
+  meta STRING DEFAULT '{}',
+  PRIMARY KEY (id)
+)`;
+export const REPO_SNAPSHOT_SCHEMA = `
+CREATE NODE TABLE RepoSnapshot (
+  id STRING,
+  indexedAt STRING DEFAULT '',
+  lastCommit STRING DEFAULT '',
+  PRIMARY KEY (id)
+)`;
+export const CONTRACT_LINK_SCHEMA = `
+CREATE REL TABLE ContractLink (
+  FROM Contract TO Contract,
+  matchType STRING,
+  confidence DOUBLE,
+  contractId STRING,
+  fromRepo STRING,
+  toRepo STRING
+)`;
+export const BRIDGE_SCHEMA_QUERIES = [CONTRACT_SCHEMA, REPO_SNAPSHOT_SCHEMA, CONTRACT_LINK_SCHEMA];

package/dist/core/group/config-parser.d.ts

@@ -0,0 +1,7 @@
+import type { GroupConfig } from './types.js';
+export declare function parseGroupConfig(yamlContent: string): GroupConfig;
+export declare class GroupNotFoundError extends Error {
+    readonly groupName: string;
+    constructor(groupName: string);
+}
+export declare function loadGroupConfig(groupDir: string): Promise<GroupConfig>;

package/dist/core/group/config-parser.js

@@ -0,0 +1,122 @@
+import { createRequire } from 'node:module';
+const _require = createRequire(import.meta.url);
+const yaml = _require('js-yaml');
+const VALID_CONTRACT_TYPES = [
+    'http',
+    'grpc',
+    'thrift',
+    'topic',
+    'lib',
+    'custom',
+    'include',
+];
+const VALID_ROLES = ['provider', 'consumer'];
+// Defaults matter for backward compatibility: any group.yaml that omits a
+// `detect.<type>` key inherits its value from this constant. Adding a new
+// extractor that defaults to `true` silently changes the behavior of every
+// existing group on the next sync. New extractors must default to `false`
+// (opt-in) so operators consciously enable them via group.yaml.
+//
+// `includes`: opt-in. The C/C++ IncludeExtractor (PR #1156) ships disabled by
+// default; enable with `detect.includes: true` for groups containing C/C++
+// repos that need cross-repo header tracking.
+const DEFAULT_DETECT = {
+    http: true,
+    grpc: true,
+    thrift: true,
+    topics: true,
+    shared_libs: true,
+    embedding_fallback: true,
+    includes: false,
+    workspace_deps: false,
+};
+const DEFAULT_MATCHING = {
+    bm25_threshold: 0.7,
+    embedding_threshold: 0.65,
+    max_candidates_per_step: 3,
+    exclude_links_paths: [],
+    exclude_links_param_only_paths: false,
+};
+export function parseGroupConfig(yamlContent) {
+    const raw = yaml.load(yamlContent, { schema: yaml.JSON_SCHEMA });
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Invalid YAML: expected an object');
+    }
+    if (raw.version === undefined)
+        throw new Error('version is required in group.yaml');
+    if (raw.version !== 1) {
+        throw new Error(`Unsupported group.yaml version: ${raw.version}. Expected 1.`);
+    }
+    if (!raw.name || typeof raw.name !== 'string')
+        throw new Error('name is required in group.yaml');
+    if (!raw.repos || typeof raw.repos !== 'object' || Array.isArray(raw.repos)) {
+        throw new Error('repos is required in group.yaml (must be a mapping)');
+    }
+    const repos = raw.repos;
+    const repoPaths = new Set(Object.keys(repos));
+    const rawLinks = raw.links || [];
+    const links = rawLinks.map((l, i) => {
+        const link = l;
+        if (!link.from || !repoPaths.has(link.from)) {
+            throw new Error(`links[${i}].from "${link.from}" does not match any repo path in group`);
+        }
+        if (!link.to || !repoPaths.has(link.to)) {
+            throw new Error(`links[${i}].to "${link.to}" does not match any repo path in group`);
+        }
+        if (!VALID_CONTRACT_TYPES.includes(link.type)) {
+            throw new Error(`links[${i}].type "${link.type}" is invalid. Expected: ${VALID_CONTRACT_TYPES.join(', ')}`);
+        }
+        if (!VALID_ROLES.includes(link.role)) {
+            throw new Error(`links[${i}].role "${link.role}" is invalid. Expected: provider | consumer`);
+        }
+        if (link.contract === undefined ||
+            link.contract === null ||
+            String(link.contract).trim() === '') {
+            throw new Error(`links[${i}].contract is required`);
+        }
+        return {
+            from: link.from,
+            to: link.to,
+            type: link.type,
+            contract: String(link.contract),
+            role: link.role,
+        };
+    });
+    const detect = { ...DEFAULT_DETECT, ...(raw.detect || {}) };
+    const matching = { ...DEFAULT_MATCHING, ...(raw.matching || {}) };
+    const packages = raw.packages || {};
+    return {
+        version: 1,
+        name: raw.name,
+        description: raw.description || '',
+        repos,
+        links,
+        packages,
+        detect,
+        matching,
+    };
+}
+export class GroupNotFoundError extends Error {
+    groupName;
+    constructor(groupName) {
+        super(`Group "${groupName}" not found`);
+        this.groupName = groupName;
+        this.name = 'GroupNotFoundError';
+    }
+}
+export async function loadGroupConfig(groupDir) {
+    const fsp = await import('node:fs/promises');
+    const path = await import('node:path');
+    const yamlPath = path.join(groupDir, 'group.yaml');
+    let content;
+    try {
+        content = await fsp.readFile(yamlPath, 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new GroupNotFoundError(path.basename(groupDir));
+        }
+        throw err;
+    }
+    return parseGroupConfig(content);
+}

package/dist/core/group/contract-extractor.d.ts

@@ -0,0 +1,7 @@
+import type { ContractType, ExtractedContract, RepoHandle } from './types.js';
+export interface ContractExtractor {
+    type: ContractType;
+    canExtract(repo: RepoHandle): Promise<boolean>;
+    extract(dbExecutor: CypherExecutor | null, repoPath: string, repo: RepoHandle): Promise<ExtractedContract[]>;
+}
+export type CypherExecutor = (query: string, params?: Record<string, unknown>) => Promise<Record<string, unknown>[]>;

package/dist/core/group/contract-extractor.js

@@ -0,0 +1 @@
+export {};

package/dist/core/group/cross-impact.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Cross-repo impact (Phase 1 local walk + Phase 2 bridge fan-out).
+ * All bridge Cypher for this feature lives in this module.
+ */
+import type { GroupImpactResult } from './types.js';
+import type { GroupToolPort } from './service.js';
+/** Cross-boundary hops beyond this value are clamped (multi-hop reserved for future work). */
+export declare const MAX_SUPPORTED_CROSS_DEPTH = 1;
+/** Default wall-clock budget for the Phase 1 `impact` leg when callers omit `timeoutMs`. */
+export declare const DEFAULT_LOCAL_IMPACT_TIMEOUT_MS = 30000;
+export interface RunGroupImpactDeps {
+    port: GroupToolPort;
+    arcDir: string;
+}
+/**
+ * Clamp the impact timeout to a sane bounded range. Callers can feed this
+ * via tool params, so an unclamped value lets a single request hold a
+ * timer slot for an arbitrarily long duration (CodeQL js/resource-
+ * exhaustion). 100ms lower bound preserves test-suite scenarios that
+ * exercise tight timeouts; 5min upper bound is well above any legitimate
+ * single-impact compute. Applied at the validate boundary so the
+ * downstream `deadline` (Date.now() + timeoutMs) and the local-leg
+ * `setTimeout` see the same clamped value — earlier shapes had a 1hr
+ * outer cap and a 5min inner clamp that disagreed.
+ */
+export declare const IMPACT_TIMEOUT_MIN_MS = 100;
+export declare const IMPACT_TIMEOUT_MAX_MS: number;
+export declare function clampTimeout(timeoutMs: number): number;
+export declare function validateGroupImpactParams(params: Record<string, unknown>): {
+    ok: true;
+    name: string;
+    repoPath: string;
+    target: string;
+    direction: 'upstream' | 'downstream';
+    maxDepth: number;
+    crossDepth: number;
+    crossDepthWarning?: string;
+    relationTypes?: string[];
+    includeTests: boolean;
+    minConfidence: number;
+    service?: string;
+    subgroup?: string;
+    timeoutMs: number;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Race a single Phase-2 `impactByUid` call against a remaining-budget
+ * timer. The Codex adversarial review on PR #1331 surfaced that the
+ * fanout loop only checked `Date.now() > deadline` *between* neighbor
+ * calls — once `await port.impactByUid(...)` was reached, a hung
+ * neighbor could pin the request indefinitely, and slow neighbors
+ * could compound past the 5-min `IMPACT_TIMEOUT_MAX_MS` cap.
+ *
+ * This helper wraps each call: a `setTimeout(remainingMs)` aborts an
+ * `AbortController` whose signal is forwarded to `impactByUid`, and a
+ * `Promise.race` resolves to `{ timedOut: true }` when the timer
+ * fires before the call completes. Implementors that ignore the
+ * signal (current local backend) still see their await resolved by
+ * the race; full cooperative cancellation inside the BFS is a future
+ * follow-up. On rejection, the value is `null` (matching the
+ * fanout's existing `if (fan == null)` truncation contract).
+ *
+ * Exported for direct unit testing — the helper IS the load-bearing
+ * mitigation surface, so the U3 regression test pins it directly
+ * rather than driving the full `runGroupImpact` path.
+ */
+export declare function safeNeighborImpact(port: GroupToolPort, repoId: string, uid: string, direction: string, opts: {
+    maxDepth: number;
+    relationTypes: string[];
+    minConfidence: number;
+    includeTests: boolean;
+}, remainingMs: number): Promise<{
+    value: unknown;
+    timedOut: boolean;
+}>;
+export declare function collectImpactSymbolUids(local: unknown, servicePrefix: string | undefined): {
+    uids: string[];
+    targetFilePath?: string;
+};
+export declare function runGroupImpact(deps: RunGroupImpactDeps, params: Record<string, unknown>): Promise<GroupImpactResult | {
+    error: string;
+}>;
+export { normalizeServicePrefix, fileMatchesServicePrefix } from './group-path-utils.js';