@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/map_verify.ts

@@ -54,10 +54,49 @@ export interface MapRenderCheck {
         pageErrors: number;
         externalRequests: number;
         horizontalScroll: boolean;
-        views: Array<{ view: string; labels: number; outside: number; overlapping: number }>;
+        views: Array<{ view: string; labels: number; outside: number; overlapping: number; orb?: OrbSpread }>;
+        /** Area-list entries whose name is cut off, or whose colour dot sits on a line of its own. */
+        sidebar: { entries: number; clipped: number; orphanedDot: number };
     }>;
 }
 
+/**
+ * How the area bubbles of one orb view sit: overlapping near-side pairs, and how
+ * far they bunch into one cap — the length of the mean of their unit vectors on
+ * the sphere, 0 for an even spread and 1 for every bubble on one point.
+ */
+export interface OrbSpread {
+    bubbles: number;
+    concentration: number;
+    overlapping: number;
+}
+
+/** Near-side bubbles overlapping by more than a sliver count; far-side ones are seen through the near side. */
+export function orbSpread(nodes: ReadonlyArray<{ x: number; y: number; r: number; near: boolean; u?: number[] }>): OrbSpread {
+    const near = nodes.filter((n) => n.near);
+    let overlapping = 0;
+    for (let i = 0; i < near.length; i++)
+        for (let j = i + 1; j < near.length; j++) {
+            const a = near[i] as (typeof near)[number];
+            const b = near[j] as (typeof near)[number];
+            // The viewer shrinks a crowded bubble down to a dot (ORB_DOT px): two dots touching
+            // hide nothing, so only a pair where both still read as bubbles counts.
+            if (a.r <= ORB_DOT || b.r <= ORB_DOT) continue;
+            if (Math.hypot(a.x - b.x, a.y - b.y) < (a.r + b.r) * ORB_OVERLAP_TOLERANCE) overlapping += 1;
+        }
+    const sum = [0, 0, 0];
+    for (const n of nodes) for (let k = 0; k < 3; k++) sum[k] = (sum[k] as number) + (n.u?.[k] ?? 0);
+    const concentration = nodes.length ? Math.hypot(...(sum as [number, number, number])) / nodes.length : 0;
+    return { bubbles: nodes.length, concentration: Math.round(concentration * 100) / 100, overlapping };
+}
+
+/** The smallest radius the viewer shrinks a crowded orb bubble to (`viewer.js`). */
+const ORB_DOT = 2;
+/** Two bubbles overlap when their centres are closer than this share of their summed radii. */
+const ORB_OVERLAP_TOLERANCE = 0.9;
+/** Above this, the bubbles bunch into one cap. An even spread of 30 sits near 0.1; one hemisphere at 0.5. */
+export const ORB_MAX_CONCENTRATION = 0.35;
+
 interface Box {
     x: number;
     y: number;
@@ -112,23 +151,59 @@ export async function verifyMap(htmlPath: string): Promise<MapRenderCheck> {
             });
             await page.goto(url);
             await page.waitForFunction(() => (window as unknown as { __mapLabelBoxes?: unknown }).__mapLabelBoxes !== undefined);
-            const read = async (view: string): Promise<{ view: string; labels: number; outside: number; overlapping: number }> => {
+            const read = async (view: string): Promise<{ view: string; labels: number; outside: number; overlapping: number; orb?: OrbSpread }> => {
                 const r = (await page.evaluate(() => (window as unknown as { __mapLabelBoxes: { boxes: Box[]; width: number; height: number } }).__mapLabelBoxes)) as {
                     boxes: Box[];
                     width: number;
                     height: number;
                 };
-                return { view, labels: r.boxes.length, ...labelProblems(r.boxes, r.width, r.height) };
+                const bubbles = await page.evaluate(
+                    () => (window as unknown as { __mapOrbNodes?: Array<{ x: number; y: number; r: number; near: boolean; u?: number[] }> }).__mapOrbNodes ?? [],
+                );
+                return { view, labels: r.boxes.length, ...labelProblems(r.boxes, r.width, r.height), ...(bubbles.length ? { orb: orbSpread(bubbles) } : {}) };
             };
+            const sidebar = await page.evaluate(() => {
+                const entries = [...document.querySelectorAll('#panel .plist button')].filter((b) => b.querySelector('.swatch'));
+                let clipped = 0;
+                let orphanedDot = 0;
+                for (const b of entries) {
+                    const name = (b.querySelector('.fname') ?? b) as HTMLElement | null;
+                    const dot = b.querySelector('.swatch') as HTMLElement | null;
+                    if (name && name.scrollWidth > name.clientWidth + 1) clipped += 1;
+                    if (name && dot && dot.getBoundingClientRect().top > name.getBoundingClientRect().bottom) orphanedDot += 1;
+                }
+                return { entries: entries.length, clipped, orphanedDot };
+            });
             const views = [await read('overview')];
+            // The orb, as it opens and turned half a revolution: the far side's labels
+            // must stay hidden and the near side's must still fit and not overlap.
+            const orb = page.locator('#dim');
+            if ((await orb.count()) > 0) {
+                await orb.click();
+                views.push(await read('overview-orb'));
+                await page.evaluate(() => {
+                    for (let i = 0; i < 21; i++) document.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowRight' }));
+                });
+                views.push(await read('overview-orb-turned'));
+                await orb.click();
+            }
             const firstArea = page.locator('#panel .plist button').first();
             if ((await firstArea.count()) > 0) {
                 await firstArea.click();
                 views.push(await read('largest-area'));
             }
             const horizontalScroll = await page.evaluate(() => document.documentElement.scrollWidth > window.innerWidth);
-            out.viewports.push({ name: vp.name, pageErrors, externalRequests, horizontalScroll, views });
-            if (pageErrors || externalRequests || horizontalScroll || views.some((v) => v.outside || v.overlapping)) {
+            out.viewports.push({ name: vp.name, pageErrors, externalRequests, horizontalScroll, views, sidebar });
+            const orbBad = (o: OrbSpread | undefined): boolean =>
+                !!o && (o.overlapping > 0 || (o.bubbles >= 6 && o.concentration > ORB_MAX_CONCENTRATION));
+            if (
+                pageErrors ||
+                externalRequests ||
+                horizontalScroll ||
+                sidebar.clipped ||
+                sidebar.orphanedDot ||
+                views.some((v) => v.outside || v.overlapping || orbBad(v.orb))
+            ) {
                 out.verification = 'failed';
             }
             await page.close();

package/src/scripts/code_graph/map_viewer/viewer.css

@@ -12,6 +12,8 @@
     --change: #d1495b;
     --good: #2e8b57;
     --contested: #d98b1d;
+    --orb-light: rgba(255, 255, 255, 0.95);
+    --orb-dark: rgba(214, 220, 232, 0.55);
 }
 @media (prefers-color-scheme: dark) {
     :root:not([data-theme='light']) {
@@ -28,6 +30,8 @@
         --change: #ff7a8a;
         --good: #5fd39a;
         --contested: #ffb347;
+        --orb-light: rgba(64, 72, 90, 0.55);
+        --orb-dark: rgba(20, 22, 26, 0.2);
     }
 }
 :root[data-theme='dark'] {
@@ -44,6 +48,8 @@
     --change: #ff7a8a;
     --good: #5fd39a;
     --contested: #ffb347;
+    --orb-light: rgba(64, 72, 90, 0.55);
+    --orb-dark: rgba(20, 22, 26, 0.2);
 }
 * {
     box-sizing: border-box;
@@ -203,6 +209,18 @@ aside h3 {
     background: transparent;
     padding: 2px 4px;
 }
+.plist button.aentry {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr);
+    column-gap: 6px;
+    align-items: start;
+}
+.aentry .swatch {
+    margin: 4px 0 0;
+}
+.alabel {
+    min-width: 0;
+}
 .plist button:hover {
     background: var(--bg);
 }

package/src/scripts/code_graph/map_viewer/viewer.js

@@ -29,6 +29,7 @@
             search: 'Search files and areas',
             files: function (n) { return n === 1 ? '1 file' : n + ' files'; },
             role: 'Role',
+            linkedBy: 'Linked by provider',
             area: 'Area',
             usedBy: 'Used by',
             uses: 'Uses',
@@ -56,6 +57,8 @@
             zoomIn: 'Zoom in',
             zoomOut: 'Zoom out',
             reset: 'Fit',
+            dim3d: '3D',
+            dimHint: 'Show the map as an orb. Drag to turn it, Shift+drag to move it, arrow keys turn it too.',
             none: 'none',
             hint: 'Click an area to open it. Click a file to inspect it. Esc goes back.',
             roles: {
@@ -75,6 +78,7 @@
             search: 'Dateien und Bereiche suchen',
             files: function (n) { return n === 1 ? '1 Datei' : n + ' Dateien'; },
             role: 'Rolle',
+            linkedBy: 'Verbunden durch Provider',
             area: 'Bereich',
             usedBy: 'Verwendet von',
             uses: 'Verwendet',
@@ -102,6 +106,8 @@
             zoomIn: 'Vergrößern',
             zoomOut: 'Verkleinern',
             reset: 'Einpassen',
+            dim3d: '3D',
+            dimHint: 'Karte als Kugel zeigen. Ziehen dreht sie, Shift+Ziehen verschiebt sie, die Pfeiltasten drehen ebenfalls.',
             none: 'keine',
             hint: 'Bereich anklicken zum Öffnen, Datei anklicken zum Ansehen. Esc geht zurück.',
             roles: {
@@ -168,6 +174,10 @@
     var searchInput = document.getElementById('search');
     var results = document.getElementById('results');
 
+    // The orb starts turned a little, so it reads as a sphere and not as a disc.
+    var ORB_YAW = 0.35;
+    var ORB_PITCH = -0.3;
+
     var state = {
         level: 'overview', // overview | area
         area: -1,
@@ -176,7 +186,9 @@
         showGuesses: false,
         showTests: true,
         lens: 'areas', // areas | folders
-        view: { scale: 1, x: 0, y: 0 }
+        view: { scale: 1, x: 0, y: 0 },
+        orb: false,
+        rot: { yaw: ORB_YAW, pitch: ORB_PITCH }
     };
     var drawn = []; // {kind, idx, x, y, r} in screen space, for hit tests
     window.__mapLabelBoxes = { boxes: [], width: 0, height: 0 };
@@ -202,6 +214,34 @@
         return [s.w / 2 + (x * k) + state.view.x, s.h / 2 + (y * k) + state.view.y];
     }
 
+    // The orb: the precomputed 2D layout wrapped onto a sphere with the inverse
+    // Lambert azimuthal equal-area projection — the layout's centre faces the
+    // viewer, its rim wraps to the back. A node's distance from the centre and
+    // its direction are both replaced by their RANK (`share`, `turn`, 0..1),
+    // order kept, so equal shares of nodes cover equal shares of the sphere.
+    // Raw coordinates put most areas on one cap: a force layout is dense in the
+    // middle and lopsided around it.
+    function orbPoint(share, turn) {
+        var rho = 2 * Math.sqrt(share) * 0.97;
+        var phi = turn * Math.PI * 2;
+        var f = Math.sqrt(Math.max(0, 1 - (rho * rho) / 4));
+        var px = Math.cos(phi) * rho * f;
+        var py = Math.sin(phi) * rho * f;
+        var pz = 1 - (rho * rho) / 2;
+        var cy = Math.cos(state.rot.yaw);
+        var sy = Math.sin(state.rot.yaw);
+        var x1 = px * cy + pz * sy;
+        var z1 = -px * sy + pz * cy;
+        var cp = Math.cos(state.rot.pitch);
+        var sp = Math.sin(state.rot.pitch);
+        return [x1, py * cp - z1 * sp, py * sp + z1 * cp];
+    }
+
+    function orbRadius() {
+        var s = size();
+        return (Math.min(s.w, s.h) / 2 - 48) * state.view.scale;
+    }
+
     // Visible nodes for the current level.
     function currentNodes() {
         var out = [];
@@ -231,12 +271,58 @@
         ctx.clearRect(0, 0, s.w, s.h);
         var nodes = currentNodes();
         var pos = Object.create(null);
-        nodes.forEach(function (n) {
-            var p = toScreen(n.x, n.y);
-            n.sx = p[0];
-            n.sy = p[1];
-            pos[n.kind + n.idx] = n;
-        });
+        if (state.orb) {
+            var byReach = nodes.slice().sort(function (a, b) {
+                return (a.x * a.x + a.y * a.y) - (b.x * b.x + b.y * b.y) || a.idx - b.idx;
+            });
+            var share = Object.create(null);
+            byReach.forEach(function (n, i) { share[n.kind + n.idx] = (i + 0.5) / byReach.length; });
+            var turn = Object.create(null);
+            nodes.slice().sort(function (a, b) { return Math.atan2(a.y, a.x) - Math.atan2(b.y, b.x) || a.idx - b.idx; })
+                .forEach(function (n, i) { turn[n.kind + n.idx] = i / nodes.length; });
+            var k = orbRadius();
+            // Bubble sizes are tuned for a 300 px orb; a phone's smaller orb shrinks them with it.
+            var fit = Math.min(1, k / 300);
+            var cx = s.w / 2 + state.view.x;
+            var cyy = s.h / 2 + state.view.y;
+            nodes.forEach(function (n) {
+                var p = orbPoint(share[n.kind + n.idx], turn[n.kind + n.idx]);
+                n.u = p;
+                n.sx = cx + p[0] * k;
+                n.sy = cyy + p[1] * k;
+                n.depth = p[2];
+                // Nearer is larger and opaque; the far side recedes.
+                n.r = n.r * fit * (0.6 + 0.4 * (p[2] + 1) / 2);
+                pos[n.kind + n.idx] = n;
+            });
+            // No two near-side bubbles may cover each other: each is capped at a
+            // share of the gap to its nearest near-side neighbour.
+            var nearNodes = nodes.filter(function (n) { return n.depth > 0; });
+            if (nearNodes.length <= 400) {
+                nearNodes.forEach(function (n) {
+                    var gap = Infinity;
+                    nearNodes.forEach(function (o) { if (o !== n) gap = Math.min(gap, Math.hypot(o.sx - n.sx, o.sy - n.sy)); });
+                    if (gap < Infinity) n.r = Math.max(2, Math.min(n.r, gap * 0.45));
+                });
+            }
+            nodes.sort(function (a, b) { return a.depth - b.depth || a.idx - b.idx; });
+            var glow = ctx.createRadialGradient(cx - k * 0.35, cyy - k * 0.35, k * 0.1, cx, cyy, k);
+            glow.addColorStop(0, cssVar('--orb-light'));
+            glow.addColorStop(1, cssVar('--orb-dark'));
+            ctx.fillStyle = glow;
+            ctx.beginPath();
+            ctx.arc(cx, cyy, k, 0, Math.PI * 2);
+            ctx.fill();
+        } else {
+            nodes.forEach(function (n) {
+                var p = toScreen(n.x, n.y);
+                n.sx = p[0];
+                n.sy = p[1];
+                pos[n.kind + n.idx] = n;
+            });
+        }
+        // 1 on the near side and in 2D, fading to 0.15 on the far side of the orb.
+        function nearness(a) { return state.orb ? 0.15 + 0.85 * (a.depth + 1) / 2 : 1; }
 
         // Edges first.
         var edge = cssVar('--edge');
@@ -252,11 +338,13 @@
                 var hot = state.area === e[0] || state.area === e[1];
                 ctx.strokeStyle = hot ? strong : edge;
                 ctx.lineWidth = 0.5 + 4 * Math.sqrt(e[2] / maxW);
+                ctx.globalAlpha = Math.min(nearness(a), nearness(b));
                 ctx.beginPath();
                 ctx.moveTo(a.sx, a.sy);
                 ctx.lineTo(b.sx, b.sy);
                 ctx.stroke();
             });
+            ctx.globalAlpha = 1;
         } else {
             var drawEdges = function (list, dashed) {
                 ctx.setLineDash(dashed ? [4, 4] : []);
@@ -267,11 +355,13 @@
                     var hot = state.file === e[0] || state.file === e[1];
                     ctx.strokeStyle = hot ? strong : edge;
                     ctx.lineWidth = hot ? 1.8 : 0.8;
+                    ctx.globalAlpha = Math.min(nearness(a), nearness(b));
                     ctx.beginPath();
                     ctx.moveTo(a.sx, a.sy);
                     ctx.lineTo(b.sx, b.sy);
                     ctx.stroke();
                 });
+                ctx.globalAlpha = 1;
                 ctx.setLineDash([]);
             };
             drawEdges(model.edges, false);
@@ -299,7 +389,7 @@
                 var f = files[n.idx];
                 color = f.role === 'test' ? areaColor(state.area, 0.45) : f.role === 'infra' ? grey : areaColor(state.area, 1);
             }
-            ctx.globalAlpha = dim ? 0.35 : 1;
+            ctx.globalAlpha = (dim ? 0.35 : 1) * nearness(n);
             ctx.fillStyle = color;
             ctx.beginPath();
             ctx.arc(n.sx, n.sy, r, 0, Math.PI * 2);
@@ -324,10 +414,15 @@
                 ctx.setLineDash([]);
             }
             ctx.globalAlpha = 1;
-            drawn.push({ kind: n.kind, idx: n.idx, x: n.sx, y: n.sy, r: Math.max(r, 8) });
+            // The far side of the orb is seen through the near side: never a click target.
+            if (!state.orb || n.depth > 0) drawn.push({ kind: n.kind, idx: n.idx, x: n.sx, y: n.sy, r: Math.max(r, 8) });
         });
 
-        drawLabels(nodes, s);
+        drawLabels(state.orb ? nodes.filter(function (n) { return n.depth > 0.15; }) : nodes, s);
+        // For the render check: the bubbles as drawn, with their side of the orb.
+        window.__mapOrbNodes = state.orb
+            ? nodes.map(function (n) { return { x: n.sx, y: n.sy, r: n.r, near: n.depth > 0, u: n.u }; })
+            : [];
     }
 
     // Labels: biggest first, placed only where they fit, flipped near the right
@@ -407,6 +502,7 @@
             r.views.forEach(function (v) { parts.push(base(files[v].path)); });
             r.models.forEach(function (v) { parts.push(base(files[v].path)); });
             r.tables.forEach(function (tb) { parts.push('⊞ ' + tb); });
+            (r.inferredTables || []).forEach(function (tb) { parts.push('⊞ ' + tb + ' ?'); });
             li.appendChild(el('span', { class: 'fdir' }, parts.length ? '→ ' + parts.join(' → ') : '→ ' + t('none')));
             ul.appendChild(li);
         });
@@ -428,6 +524,7 @@
             kv([
                 [t('area'), f.area >= 0 ? areas[f.area].name : '—'],
                 [t('role'), STR[lang].roles[f.role]],
+                [t('linkedBy'), f.linkedBy ? f.linkedBy.join(', ') : '—'],
                 [t('guesses'), String(f.guesses)],
                 [t('outcome'), outcomeOf[state.file] === undefined ? '—' : String(outcomeOf[state.file])],
                 [t('state'), data.meta.state]
@@ -511,9 +608,13 @@
         panel.appendChild(el('h3', null, t('areas') + ' (' + areas.length + ')'));
         var list = el('ul', { class: 'plist' });
         areas.forEach(function (a, i) {
-            var b = el('button', { type: 'button' });
+            var b = el('button', { type: 'button', class: 'aentry', title: a.name + ' · ' + a.files.length });
             b.appendChild(swatch(i));
-            b.appendChild(document.createTextNode(a.name + ' · ' + a.files.length));
+            var label = el('span', { class: 'alabel' });
+            var path = a.kind === 'small-parts' ? null : a.name;
+            label.appendChild(el('span', { class: 'fname' }, (path ? base(path) : a.name) + ' · ' + a.files.length));
+            if (path && dir(path) !== '.') label.appendChild(el('span', { class: 'fdir' }, dir(path)));
+            b.appendChild(label);
             b.addEventListener('click', function () { openArea(i); });
             var li = el('li');
             li.appendChild(b);
@@ -615,7 +716,10 @@
         renderPanel();
         draw();
     }
-    function resetView() { state.view = { scale: 1, x: 0, y: 0 }; }
+    function resetView() {
+        state.view = { scale: 1, x: 0, y: 0 };
+        state.rot = { yaw: ORB_YAW, pitch: ORB_PITCH };
+    }
     function goHome() { state.level = 'overview'; state.area = -1; state.file = -1; resetView(); refresh(); }
     function openArea(i) { state.level = 'area'; state.area = i; state.file = -1; resetView(); refresh(); }
     function openFile(i) {
@@ -632,7 +736,10 @@
     // Input.
     var drag = null;
     canvas.addEventListener('pointerdown', function (e) {
-        drag = { x: e.clientX, y: e.clientY, vx: state.view.x, vy: state.view.y, moved: false };
+        drag = {
+            x: e.clientX, y: e.clientY, vx: state.view.x, vy: state.view.y,
+            yaw: state.rot.yaw, pitch: state.rot.pitch, turn: state.orb && !e.shiftKey, moved: false
+        };
         canvas.setPointerCapture(e.pointerId);
     });
     canvas.addEventListener('pointermove', function (e) {
@@ -640,8 +747,16 @@
         var dx = e.clientX - drag.x;
         var dy = e.clientY - drag.y;
         if (Math.abs(dx) + Math.abs(dy) > 3) drag.moved = true;
-        if (drag.moved) { state.view.x = drag.vx + dx; state.view.y = drag.vy + dy; draw(); }
+        if (!drag.moved) return;
+        if (drag.turn) turnTo(drag.yaw + dx * 0.008, drag.pitch - dy * 0.008);
+        else { state.view.x = drag.vx + dx; state.view.y = drag.vy + dy; draw(); }
     });
+    // Pitch stops short of the poles, so "up" never flips under the pointer.
+    function turnTo(yaw, pitch) {
+        state.rot.yaw = yaw;
+        state.rot.pitch = Math.max(-1.4, Math.min(1.4, pitch));
+        draw();
+    }
     canvas.addEventListener('pointerup', function (e) {
         var wasDrag = drag && drag.moved;
         drag = null;
@@ -660,7 +775,14 @@
         state.view.scale = Math.min(12, Math.max(0.3, state.view.scale * f));
         draw();
     }
+    var TURN_KEYS = { ArrowLeft: [-0.15, 0], ArrowRight: [0.15, 0], ArrowUp: [0, 0.15], ArrowDown: [0, -0.15] };
     document.addEventListener('keydown', function (e) {
+        var step = TURN_KEYS[e.key];
+        if (step && state.orb && document.activeElement !== searchInput) {
+            e.preventDefault();
+            turnTo(state.rot.yaw + step[0], state.rot.pitch + step[1]);
+            return;
+        }
         if (e.key === 'Escape') {
             if (document.activeElement === searchInput && searchInput.value) { searchInput.value = ''; clear(results); return; }
             if (state.file >= 0) { state.file = -1; refresh(); } else if (state.area >= 0) goHome();
@@ -710,6 +832,13 @@
     document.getElementById('z-in').addEventListener('click', function () { zoom(1.25); });
     document.getElementById('z-out').addEventListener('click', function () { zoom(1 / 1.25); });
     document.getElementById('z-fit').addEventListener('click', function () { resetView(); draw(); });
+    var dimButton = document.getElementById('dim');
+    dimButton.addEventListener('click', function () {
+        state.orb = !state.orb;
+        dimButton.setAttribute('aria-pressed', String(state.orb));
+        resetView();
+        draw();
+    });
 
     var themes = ['system', 'light', 'dark'];
     var theme = 'system';
@@ -744,6 +873,8 @@
         document.getElementById('z-in').setAttribute('aria-label', t('zoomIn'));
         document.getElementById('z-out').setAttribute('aria-label', t('zoomOut'));
         document.getElementById('z-fit').textContent = t('reset');
+        document.getElementById('dim').textContent = t('dim3d');
+        document.getElementById('dim').setAttribute('title', t('dimHint'));
         document.getElementById('lang').textContent = t('lang');
         applyTheme();
     }

package/src/scripts/code_graph/passes.ts

@@ -0,0 +1,173 @@
+/**
+ * The ordered post-extraction passes (ADR-298). The build runs this list and
+ * nothing else after resolution; a pass that throws is reported and skipped,
+ * and the build goes on.
+ *
+ * Order is meaning: convention providers contest base edges they prove false
+ * before anything is added on top, docs add their links, and SCIP last
+ * supersedes the name guesses it duplicates.
+ */
+import type { SourceFile } from './build.js';
+import { conventionsDefault } from './conventions_default.js';
+import { docsLayer } from './docs_layer.js';
+import { activeProviders, type ProjectProbe } from './providers/index.js';
+import type { ResolutionConfig } from './resolution_tiers.js';
+import { type ScipDocument, scipEdges, supersededByScip } from './scip_reader.js';
+import type { ActiveProviderRecord, CodeEdge, CodeNode } from './types.js';
+
+export interface PassContext {
+    files: readonly SourceFile[];
+    docs: readonly SourceFile[];
+    scip: readonly ScipDocument[];
+    resolution: ResolutionConfig;
+    probe: ProjectProbe;
+    /** The graph so far, read-only: a pass proposes, the orchestrator applies. */
+    nodes: readonly CodeNode[];
+    edges: readonly CodeEdge[];
+}
+
+export interface PassFailure {
+    pass: string;
+    reason: string;
+}
+
+export interface Contest {
+    /** Suppressed-edge counter the removed edges are reported under, if any. */
+    key?: string;
+    test: (e: CodeEdge) => boolean;
+}
+
+export interface PassResult {
+    nodes: CodeNode[];
+    edges: CodeEdge[];
+    /** Applied to the existing edges, in order, before this pass's own are added. */
+    contests?: Contest[];
+    /** Failures inside the pass that did not stop it (one provider of several). */
+    failures?: PassFailure[];
+    /** Convention providers that applied, for the graph's record. */
+    providers?: ActiveProviderRecord[];
+}
+
+export interface GraphPass {
+    id: string;
+    applies(ctx: PassContext): boolean;
+    run(ctx: PassContext): PassResult;
+}
+
+const conventionProviders: GraphPass = {
+    id: 'convention-providers',
+    applies: (ctx) => activeProviders(ctx.probe).length > 0,
+    run: (ctx) => {
+        const out: PassResult = { nodes: [], edges: [], contests: [], failures: [], providers: [] };
+        const known = new Set(ctx.nodes.map((n) => n.id));
+        const drawn = new Set<string>();
+        for (const { provider, roots } of activeProviders(ctx.probe)) {
+            out.providers?.push({ id: provider.id, roots });
+            try {
+                const under = (p: string): boolean => roots.includes('') || roots.some((r) => p.startsWith(`${r}/`));
+                const files = ctx.files.filter((f) => under(f.path));
+                const allPaths = ctx.probe.paths.length > 0 ? ctx.probe.paths : ctx.files.map((f) => f.path);
+                const r = provider.build({
+                    files,
+                    baseNodes: ctx.nodes,
+                    baseEdges: ctx.edges,
+                    paths: allPaths.filter(under),
+                    manifests: new Map([...ctx.probe.manifests].filter(([p]) => under(p))),
+                    resolution: ctx.resolution,
+                    roots,
+                });
+                if (r.nodes.length === 0 && r.edges.length === 0) continue;
+                if (r.contest) out.contests?.push({ key: provider.id, test: r.contest });
+                // Two providers may draw the same edge; the first keeps it.
+                for (const e of r.edges) {
+                    const key = `${e.source}\0${e.relation}\0${e.target}`;
+                    if (drawn.has(key)) continue;
+                    drawn.add(key);
+                    out.edges.push({ ...e, provider_id: provider.id });
+                }
+                // Two providers may declare the same table or template node; the first wins.
+                for (const n of r.nodes) {
+                    if (known.has(n.id)) continue;
+                    known.add(n.id);
+                    out.nodes.push(n);
+                }
+            } catch (e) {
+                out.failures?.push({ pass: `convention-providers:${provider.id}`, reason: (e as Error).message });
+            }
+        }
+        return out;
+    },
+};
+
+const defaults: GraphPass = {
+    id: 'conventions-default',
+    applies: (ctx) => ctx.files.length > 0,
+    run: (ctx) => {
+        const paths = ctx.probe.paths.length > 0 ? ctx.probe.paths : [...ctx.files, ...ctx.docs].map((f) => f.path).sort();
+        return conventionsDefault({ files: ctx.files, paths, nodes: ctx.nodes, edges: ctx.edges });
+    },
+};
+
+const docs: GraphPass = {
+    id: 'docs',
+    applies: (ctx) => ctx.docs.length > 0,
+    run: (ctx) => {
+        const allFiles = new Set([...ctx.files.map((f) => f.path), ...ctx.docs.map((d) => d.path)]);
+        const layer = docsLayer(ctx.docs, allFiles);
+        // An earlier pass may already have drawn a document as a link target.
+        const known = new Set(ctx.nodes.map((n) => n.id));
+        return { nodes: layer.nodes.filter((n) => !known.has(n.id)), edges: layer.edges };
+    },
+};
+
+const scip: GraphPass = {
+    id: 'scip',
+    applies: (ctx) => ctx.scip.length > 0,
+    run: (ctx) => {
+        const stated = scipEdges(ctx.scip, ctx.nodes);
+        return { nodes: [], edges: stated, contests: [{ test: supersededByScip(stated, ctx.nodes) }] };
+    },
+};
+
+export const PASSES: readonly GraphPass[] = [conventionProviders, defaults, docs, scip];
+
+export interface PassReport {
+    /** Edges removed by a keyed contest, per key (a provider id); only non-zero keys appear. */
+    suppressed: Record<string, number>;
+    failures: PassFailure[];
+    providers: ActiveProviderRecord[];
+}
+
+/** Run every applicable pass in order, mutating `nodes` / `edges` in place. */
+export function runPasses(
+    base: Omit<PassContext, 'nodes' | 'edges'>,
+    nodes: CodeNode[],
+    edges: CodeEdge[],
+    passes: readonly GraphPass[] = PASSES,
+): PassReport {
+    const report: PassReport = { suppressed: {}, failures: [], providers: [] };
+    for (const pass of passes) {
+        const ctx: PassContext = { ...base, nodes, edges };
+        let result: PassResult;
+        try {
+            if (!pass.applies(ctx)) continue;
+            result = pass.run(ctx);
+        } catch (e) {
+            report.failures.push({ pass: pass.id, reason: (e as Error).message });
+            continue;
+        }
+        report.failures.push(...(result.failures ?? []));
+        report.providers.push(...(result.providers ?? []));
+        for (const c of result.contests ?? []) {
+            const kept = edges.filter((e) => !c.test(e));
+            const removed = edges.length - kept.length;
+            if (c.key && removed > 0) report.suppressed[c.key] = (report.suppressed[c.key] ?? 0) + removed;
+            // Element-wise: a spread of ~200k edges overflows the call stack.
+            edges.length = 0;
+            for (const e of kept) edges.push(e);
+        }
+        for (const e of result.edges) edges.push(e);
+        for (const n of result.nodes) nodes.push(n);
+    }
+    return report;
+}

package/src/scripts/code_graph/project_ref.ts

@@ -0,0 +1,25 @@
+/**
+ * Turn a `project` argument — a repo id, a registered name or a registered
+ * path — into the root a graph verb runs against (ADR-299, step 5.1). Only a
+ * registered project resolves: an MCP caller cannot point a tool at an
+ * arbitrary directory, only at one the owner already worked in. A name two
+ * registered projects share is refused with both candidates, never guessed.
+ */
+import { findProjects, readRegistry } from '../_lib/project_registry.js';
+
+export type ProjectRef = { root: string } | { error: string; candidates: string[] };
+
+export function resolveProjectRef(ref: string): ProjectRef {
+    const reg = readRegistry();
+    const hits = findProjects(reg, ref);
+    if (hits.length === 1) return { root: (hits[0] as [string, { root: string }])[1].root };
+    if (hits.length > 1) {
+        return { error: `'${ref}' names ${hits.length} registered projects — pass an id`, candidates: hits.map(([id, e]) => `${id} ${e.root}`) };
+    }
+    return {
+        error: `no registered project matches '${ref}' — \`code-graph projects list\` shows them`,
+        candidates: Object.entries(reg.projects)
+            .slice(0, 10)
+            .map(([id, e]) => `${id} ${e.root}`),
+    };
+}