upstream-radar 0.34.0 → 0.36.0

package/dist/src/upstream-observer.js

@@ -2,8 +2,10 @@ import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import { dirname, resolve } from 'node:path';
+import { findReverseDependencyImpacts } from './dependency-index.js';
 import { parseNpmLockGraph, parsePnpmLockGraph } from './graph.js';
 import { parsePackageManifestSnapshot } from './inventory.js';
+import { buildUpstreamDownstreamIR, parseUpstreamDownstreamIR } from './upstream-alignment.js';
 export const OBSERVER_TARGETS_SCHEMA = 'upstream-radar.observer-targets/v1alpha1';
 export const OBSERVATION_STATE_SCHEMA = 'upstream-radar.observation-state/v1alpha1';
 export const UPSTREAM_CHANGE_TASK_SCHEMA = 'upstream-radar.upstream-change-task/v1alpha1';
@@ -421,6 +423,7 @@ function parseSnapshot(value, label) {
         : Array.isArray(source.warnings) && source.warnings.length <= 100
             ? source.warnings.map((item, index) => boundedString(item, `${label}.warnings[${index}]`, 2_048))
             : (() => { throw new Error(`${label}.warnings must be a bounded string array`); })();
+    const alignment = source.alignment === undefined ? undefined : parseUpstreamDownstreamIR(source.alignment, `${label}.alignment`);
     return {
         targetId,
         ecosystem,
@@ -431,6 +434,7 @@ function parseSnapshot(value, label) {
         ...(source.graph === undefined ? {} : { graph: source.graph }),
         ...(graphError === undefined ? {} : { graphError }),
         ...(warnings === undefined ? {} : { warnings }),
+        ...(alignment === undefined ? {} : { alignment }),
     };
 }
 function parseTask(value, label) {
@@ -921,6 +925,24 @@ export class UpstreamObserverClient {
                 graphError = safeError(error);
             }
         }
+        const alignment = buildUpstreamDownstreamIR({
+            targetId: targetValue.id,
+            ecosystem: targetValue.ecosystem,
+            source: {
+                repository: targetRepository.fullName,
+                commit,
+                packagePath,
+            },
+            manifest,
+            ...(packageObservation === undefined ? {} : {
+                package: {
+                    name: packageObservation.name,
+                    version: packageObservation.version,
+                },
+            }),
+            ...(graph === undefined ? {} : { graph }),
+            ...(graphError === undefined ? {} : { graphError }),
+        });
         return {
             targetId: targetValue.id,
             ecosystem: targetValue.ecosystem,
@@ -940,6 +962,7 @@ export class UpstreamObserverClient {
             ...(graph === undefined ? {} : { graph }),
             ...(graphError === undefined ? {} : { graphError }),
             ...(warnings.length === 0 ? {} : { warnings }),
+            alignment,
         };
     }
     async compare(repositoryValue, beforeCommit, afterCommit) {
@@ -1028,8 +1051,22 @@ function summary(snapshot) {
         }),
         ...(snapshot.graphError === undefined ? {} : { graphError: snapshot.graphError }),
         ...(snapshot.warnings === undefined ? {} : { warnings: [...snapshot.warnings] }),
+        ...(snapshot.alignment === undefined ? {} : { alignment: structuredClone(snapshot.alignment) }),
     };
 }
+function alignmentSignature(value) {
+    if (value === undefined)
+        return '';
+    return JSON.stringify({
+        status: value.status,
+        checks: value.checks.map(check => ({
+            code: check.code,
+            status: check.status,
+            upstream: check.upstream,
+            downstream: check.downstream,
+        })),
+    });
+}
 function manifestChanges(before, after) {
     const fields = ['type', 'main', 'exports', 'engines', 'dependencies', 'optionalDependencies', 'peerDependencies', 'peerDependenciesMeta', 'dsh']
         .filter(field => JSON.stringify(before[field]) !== JSON.stringify(after[field]));
@@ -1076,6 +1113,38 @@ function graphChanges(before, after) {
         removedUnresolved: [...beforeUnresolved].filter(edge => !afterUnresolved.has(edge)).sort(),
     };
 }
+function addObservedPackageVersion(versions, side, name, version) {
+    if (name === undefined || version === undefined || name === '' || version === '')
+        return;
+    const entry = versions.get(name) ?? { before: new Set(), after: new Set() };
+    entry[side].add(version);
+    versions.set(name, entry);
+}
+function addSnapshotPackages(versions, side, snapshot) {
+    addObservedPackageVersion(versions, side, snapshot.manifest.name, snapshot.manifest.version);
+    addObservedPackageVersion(versions, side, snapshot.package?.name, snapshot.package?.version);
+    for (const node of snapshot.graph?.nodes ?? [])
+        addObservedPackageVersion(versions, side, node.name, node.version);
+}
+/** Convert two complete snapshots into package-name changes for downstream lookup. */
+function reverseDependencyChanges(before, after) {
+    const versions = new Map();
+    addSnapshotPackages(versions, 'before', before);
+    addSnapshotPackages(versions, 'after', after);
+    return [...versions.entries()]
+        .filter(([, value]) => {
+        const beforeVersions = [...value.before].sort();
+        const afterVersions = [...value.after].sort();
+        return JSON.stringify(beforeVersions) !== JSON.stringify(afterVersions);
+    })
+        .map(([name, value]) => ({
+        ecosystem: 'npm',
+        name,
+        beforeVersions: [...value.before].sort(),
+        afterVersions: [...value.after].sort(),
+    }))
+        .sort((left, right) => left.name.localeCompare(right.name));
+}
 function packageChanged(before, after) {
     if (before.package?.name !== after.package?.name || before.package?.version !== after.package?.version)
         return true;
@@ -1109,6 +1178,13 @@ function meaningfulChange(sourceChange, before, after) {
     if (after.package !== undefined && after.manifest.version !== after.package.version) {
         reasons.push(`source/published version drift: source ${after.manifest.name}@${after.manifest.version}, npm ${after.package.name}@${after.package.version}`);
     }
+    // Legacy observation files predate the IR. Populate the new field on the
+    // next run without manufacturing a fake upstream change; only compare two
+    // already-established alignment records.
+    if (before.alignment !== undefined && after.alignment !== undefined
+        && alignmentSignature(before.alignment) !== alignmentSignature(after.alignment)) {
+        reasons.push(`upstream/downstream alignment changed: ${after.alignment?.status ?? 'not observed'}`);
+    }
     if (sourceChange.beforeCommit !== sourceChange.afterCommit) {
         if (sourceChange.comparison === 'unavailable')
             reasons.push('source commit changed and file comparison was unavailable');
@@ -1122,10 +1198,13 @@ function meaningfulChange(sourceChange, before, after) {
 function createTaskId(targetId, beforeCommit, afterCommit, packageVersion, graphDigest) {
     return `upstream-task-${hash([targetId, beforeCommit, afterCommit, packageVersion ?? '', graphDigest ?? ''].join('\0'))}`;
 }
-function createChange(target, before, after, sourceChange) {
+function createChange(target, before, after, sourceChange, reverseDependencyIndex) {
     const manifest = manifestChanges(before.manifest, after.manifest);
     const graph = graphChanges(before.graph, after.graph);
     const decision = meaningfulChange(sourceChange, before, after);
+    const reverseDependencyImpacts = reverseDependencyIndex === undefined
+        ? []
+        : findReverseDependencyImpacts(reverseDependencyIndex, reverseDependencyChanges(before, after));
     const taskId = decision.meaningful
         ? createTaskId(target.id, before.source.commit, after.source.commit, after.package?.version, after.graph?.digest)
         : undefined;
@@ -1140,6 +1219,7 @@ function createChange(target, before, after, sourceChange) {
         ...(graph === undefined ? {} : { graph }),
         reasons: decision.reasons,
         meaningful: decision.meaningful,
+        ...(reverseDependencyImpacts.length === 0 ? {} : { reverseDependencyImpacts }),
         ...(taskId === undefined ? {} : { taskId }),
     };
 }
@@ -1184,7 +1264,8 @@ export function renderUpstreamChangeAgentPrompt(task) {
 3. 如果需要项目代码证据，只读取当前项目已经存在的文件；不要为了验证结论安装包或执行上游代码。
 4. 区分源码变化、发布包变化、依赖图变化和模型判断。只有明确指出文件、配置、符号或“不知道缺少什么证据”，结论才算完整。
 5. breaking_change 只能在有明确入口、导出、DSH bundle、peer/API 或发布说明证据时判断；不因为版本号变化就直接断言。
-6. 返回严格 JSON 对象，字段只能是 impact、confidence、evidence、breaking_change、dependency_risk、recommended_action、urgency、reasoning_summary。
+6. 如果 change_json.reverseDependencyImpacts 存在，它表示静态反向索引找到的下游插件和依赖路径；把它当作影响范围证据，不要把“可能受影响”写成“已经损坏”。
+7. 返回严格 JSON 对象，字段只能是 impact、confidence、evidence、breaking_change、dependency_risk、recommended_action、urgency、reasoning_summary。
 
 expected_output:
 ${JSON.stringify(task.expectedOutput, null, 2)}
@@ -1485,6 +1566,7 @@ export async function runObserver(config, previousState, options = {}) {
     let pendingTasks = [...previousState.pendingTasks];
     const changes = [];
     const baselineTargets = [];
+    const alignmentFindings = [];
     const errors = [];
     const newTasks = [];
     for (const configuredTarget of config.targets) {
@@ -1494,8 +1576,16 @@ export async function runObserver(config, previousState, options = {}) {
             nextTargets[configuredTarget.id] = current;
             if (before === undefined) {
                 baselineTargets.push(configuredTarget.id);
+                if (current.alignment !== undefined)
+                    alignmentFindings.push({ targetId: configuredTarget.id, alignment: structuredClone(current.alignment) });
                 continue;
             }
+            if (before.alignment === undefined && current.alignment !== undefined) {
+                // Upgrade legacy state into the IR and show its first finding once.
+                // This is evidence for the author, not a fake upstream change and not
+                // a reason to wake the Agent on every subsequent scheduled run.
+                alignmentFindings.push({ targetId: configuredTarget.id, alignment: structuredClone(current.alignment) });
+            }
             const sourceChange = before.source.commit === current.source.commit
                 ? {
                     beforeCommit: before.source.commit,
@@ -1506,7 +1596,7 @@ export async function runObserver(config, previousState, options = {}) {
                     nonRuntimeFiles: [],
                 }
                 : await source.compare(current.source.repository, before.source.commit, current.source.commit);
-            const change = createChange(configuredTarget, before, current, sourceChange);
+            const change = createChange(configuredTarget, before, current, sourceChange, options.reverseDependencyIndex);
             if (change.reasons.length === 0)
                 continue;
             let reviewedChange = change;
@@ -1575,6 +1665,17 @@ export async function runObserver(config, previousState, options = {}) {
         checkedAt,
         targetsChecked: config.targets.length,
         baselineTargets,
+        alignmentFindings,
+        ...(options.reverseDependencyIndex === undefined ? {} : {
+            reverseDependencyIndex: {
+                observations: options.reverseDependencyIndex.observations,
+                plugins: options.reverseDependencyIndex.plugins.length,
+                dependencies: options.reverseDependencyIndex.dependencies.length,
+                completeObservations: options.reverseDependencyIndex.coverage.completeObservations,
+                incompleteObservations: options.reverseDependencyIndex.coverage.incompleteObservations,
+                unresolvedEdges: options.reverseDependencyIndex.coverage.unresolvedEdges,
+            },
+        }),
         changes,
         pendingTasks: pendingTasks.map(task => task.id),
         pendingTaskDetails: pendingTasks.map(summarizePendingTask),
@@ -1640,13 +1741,46 @@ function summarizePendingTask(task) {
         removedEdges: (change.graph?.removedEdges ?? []).slice(0, 24),
         addedUnresolved: (change.graph?.addedUnresolved ?? []).slice(0, 24),
         removedUnresolved: (change.graph?.removedUnresolved ?? []).slice(0, 24),
+        ...(change.reverseDependencyImpacts === undefined ? {} : { reverseDependencyImpacts: structuredClone(change.reverseDependencyImpacts) }),
         ...(change.artifactReview === undefined ? {} : { artifactReview: structuredClone(change.artifactReview) }),
     };
 }
+function renderAlignment(lines, alignment, label) {
+    lines.push(`${label}: ${alignment.status.toUpperCase()}`);
+    for (const check of alignment.checks.filter(item => item.status !== 'aligned')) {
+        lines.push(`${label} ${check.status}: ${check.code} — ${check.summary}`);
+        if (check.upstream !== undefined || check.downstream !== undefined) {
+            lines.push(`  Upstream: ${check.upstream ?? 'unknown'}; downstream: ${check.downstream ?? 'unknown'}`);
+        }
+        if (check.remediation !== undefined)
+            lines.push(`  Alignment next step: ${check.remediation}`);
+    }
+}
+function renderReverseDependencyImpacts(lines, impacts, label = 'Downstream impact') {
+    for (const impact of impacts.slice(0, 32)) {
+        const from = impact.changedFrom.length === 0 ? 'not observed' : impact.changedFrom.join(', ');
+        const to = impact.changedTo.length === 0 ? 'not observed' : impact.changedTo.join(', ');
+        lines.push(`${label}: ${impact.dependency.name} (${from} → ${to}); ${impact.dependents.length}${impact.truncated ? '+' : ''} downstream plugin(s); coverage ${impact.coverage}`);
+        for (const dependent of impact.dependents.slice(0, 8)) {
+            const project = dependent.project === undefined ? '' : ` [${dependent.project.name}]`;
+            lines.push(`  ${dependent.plugin.name}@${dependent.plugin.version}${project} (${dependent.coverage})`);
+            for (const path of dependent.paths.slice(0, 2))
+                lines.push(`    ${path.nodes.join(' → ')}`);
+            if (dependent.paths.length > 2)
+                lines.push(`    ... ${dependent.paths.length - 2} more path(s)`);
+        }
+        if (impact.truncated)
+            lines.push('  ... additional downstream plugins omitted from this bounded report');
+    }
+}
 export function renderObserverReport(report) {
     const lines = [];
-    if (report.changes.length === 0 && report.errors.length === 0 && report.pendingTasks.length === 0) {
+    const alignmentFindings = report.alignmentFindings.filter(item => item.alignment.status !== 'aligned');
+    if (report.changes.length === 0 && report.errors.length === 0 && report.pendingTasks.length === 0 && alignmentFindings.length === 0) {
         lines.push(`No meaningful upstream changes. Checked ${report.targetsChecked} target(s); DSH Agent was not called.`);
+        if (report.reverseDependencyIndex !== undefined) {
+            lines.push(`Loaded downstream reverse index: ${report.reverseDependencyIndex.plugins} plugin(s), ${report.reverseDependencyIndex.dependencies} dependency coordinate(s); coverage ${report.reverseDependencyIndex.completeObservations} complete / ${report.reverseDependencyIndex.incompleteObservations} incomplete.`);
+        }
         if (report.baselineTargets.length > 0)
             lines.push(`Created baseline for: ${report.baselineTargets.join(', ')}.`);
         return `${lines.join('\n')}\n`;
@@ -1655,11 +1789,23 @@ export function renderObserverReport(report) {
     lines.push('');
     lines.push(`Checked at: ${report.checkedAt}`);
     lines.push(`Targets: ${report.targetsChecked}; baselines: ${report.baselineTargets.length}; changes: ${report.changes.length}`);
+    if (report.reverseDependencyIndex !== undefined) {
+        lines.push(`Downstream reverse index: ${report.reverseDependencyIndex.plugins} plugin(s), ${report.reverseDependencyIndex.dependencies} dependency coordinate(s); coverage ${report.reverseDependencyIndex.completeObservations} complete / ${report.reverseDependencyIndex.incompleteObservations} incomplete.`);
+    }
     lines.push('');
     if (report.baselineTargets.length > 0) {
         lines.push(`Baseline created: ${report.baselineTargets.join(', ')}`);
         lines.push('');
     }
+    if (alignmentFindings.length > 0) {
+        lines.push('## Upstream/downstream alignment findings');
+        lines.push('');
+        for (const item of alignmentFindings) {
+            lines.push(`### ${item.targetId}`);
+            renderAlignment(lines, item.alignment, 'Alignment');
+            lines.push('');
+        }
+    }
     for (const change of report.changes) {
         lines.push(`## ${change.targetId} (${change.ecosystem})`);
         lines.push('');
@@ -1668,6 +1814,8 @@ export function renderObserverReport(report) {
         lines.push(`Package: ${displayPackage(change.previous.package)} → ${displayPackage(change.current.package)}`);
         lines.push(`Graph: ${displayGraph(change.previous.graph)} → ${displayGraph(change.current.graph)}`);
         lines.push(`Meaningful: ${change.meaningful ? 'yes' : 'no'}`);
+        if (change.current.alignment !== undefined)
+            renderAlignment(lines, change.current.alignment, 'Upstream/downstream alignment');
         for (const warning of change.current.warnings ?? [])
             lines.push(`Warning: ${warning}`);
         if (change.source.changedFiles.length > 0)
@@ -1691,6 +1839,8 @@ export function renderObserverReport(report) {
                 lines.push(`Coverage change: resolved dependency edges: ${removedUnresolved.slice(0, 8).join(', ')}`);
             }
         }
+        if (change.reverseDependencyImpacts !== undefined)
+            renderReverseDependencyImpacts(lines, change.reverseDependencyImpacts);
         if (change.reasons.length > 0)
             lines.push(`Reasons: ${change.reasons.join('; ')}`);
         if (change.current.package !== undefined) {
@@ -1757,6 +1907,8 @@ export function renderObserverReport(report) {
                 lines.push(`New unresolved dependency edges: ${task.addedUnresolved.join(', ')}`);
             if (task.removedUnresolved.length > 0)
                 lines.push(`Resolved dependency edges: ${task.removedUnresolved.join(', ')}`);
+            if (task.reverseDependencyImpacts !== undefined)
+                renderReverseDependencyImpacts(lines, task.reverseDependencyImpacts, 'Downstream impact');
             if (task.reasons.length > 0)
                 lines.push(`Reasons: ${task.reasons.join('; ')}`);
             if (task.artifactReview !== undefined) {