upstream-radar 0.43.4 → 0.44.0

package/dist/src/upstream-observer.js

@@ -404,6 +404,13 @@ function parsePackageObservation(value, label) {
     const distTag = optionalBoundedString(source.distTag, `${label}.distTag`, 128);
     if (distTag !== undefined && !SAFE_NPM_DIST_TAG.test(distTag))
         throw new Error(`${label}.distTag is invalid`);
+    const rawMigration = source.migration === undefined ? undefined : asRecord(source.migration);
+    if (source.migration !== undefined && rawMigration === undefined)
+        throw new Error(`${label}.migration must be an object`);
+    const migrationTo = rawMigration === undefined ? undefined : boundedString(rawMigration.to, `${label}.migration.to`, 214);
+    if (migrationTo !== undefined && !EXACT_NPM_PACKAGE_NAME.test(migrationTo))
+        throw new Error(`${label}.migration.to is not an npm package name`);
+    const migrationSince = rawMigration === undefined ? undefined : optionalBoundedString(rawMigration.since, `${label}.migration.since`, 128);
     return {
         name,
         version,
@@ -412,6 +419,12 @@ function parsePackageObservation(value, label) {
         ...(optionalBoundedString(source.tarball, `${label}.tarball`, 4_096) === undefined ? {} : { tarball: source.tarball }),
         ...(optionalBoundedString(source.repository, `${label}.repository`, 4_096) === undefined ? {} : { repository: source.repository }),
         ...(optionalBoundedString(source.publishedAt, `${label}.publishedAt`, 128) === undefined ? {} : { publishedAt: source.publishedAt }),
+        ...(migrationTo === undefined ? {} : {
+            migration: {
+                to: migrationTo,
+                ...(migrationSince === undefined ? {} : { since: migrationSince }),
+            },
+        }),
     };
 }
 function parseSnapshot(value, label) {
@@ -836,7 +849,10 @@ export class UpstreamObserverClient {
     async fetchNpmObservation(name, distTag = 'latest') {
         const url = new URL(encodeURIComponent(name), this.registry);
         const response = await this.fetchWithRetry(url, {
-            headers: { accept: 'application/vnd.npm.install-v1+json, application/json', 'user-agent': 'upstream-radar/upstream-observer' },
+            // The abbreviated install-v1 packument deliberately drops custom DSH
+            // metadata such as dsh.migrate. The observer needs the published package
+            // contract so package moves become explicit Agent evidence.
+            headers: { accept: 'application/json', 'user-agent': 'upstream-radar/upstream-observer' },
             redirect: 'follow',
         });
         if (response.status === 404)
@@ -854,6 +870,13 @@ export class UpstreamObserverClient {
         const repository = typeof manifest.repository === 'string'
             ? manifest.repository
             : typeof asRecord(manifest.repository)?.url === 'string' ? asRecord(manifest.repository)?.url : undefined;
+        const rawMigration = asRecord(asRecord(manifest.dsh)?.migrate);
+        const migrationTo = typeof rawMigration?.to === 'string' && EXACT_NPM_PACKAGE_NAME.test(rawMigration.to)
+            ? rawMigration.to
+            : undefined;
+        const migrationSince = typeof rawMigration?.since === 'string' && rawMigration.since.length <= 128
+            ? rawMigration.since
+            : undefined;
         return {
             name,
             version: selectedVersion,
@@ -862,6 +885,12 @@ export class UpstreamObserverClient {
             ...(typeof dist?.tarball === 'string' ? { tarball: dist.tarball } : {}),
             ...(repository === undefined ? {} : { repository: repository.slice(0, 4_096) }),
             ...(typeof times?.[selectedVersion] === 'string' ? { publishedAt: times[selectedVersion] } : {}),
+            ...(migrationTo === undefined ? {} : {
+                migration: {
+                    to: migrationTo,
+                    ...(migrationSince === undefined ? {} : { since: migrationSince }),
+                },
+            }),
         };
     }
     async observe(targetValue, now) {
@@ -1180,7 +1209,8 @@ function reverseDependencyChanges(before, after) {
 function packageChanged(before, after) {
     if (before.package?.name !== after.package?.name || before.package?.version !== after.package?.version)
         return true;
-    return before.package?.integrity !== after.package?.integrity;
+    return before.package?.integrity !== after.package?.integrity
+        || JSON.stringify(before.package?.migration) !== JSON.stringify(after.package?.migration);
 }
 function sourcePublishedVersionDrift(snapshot) {
     if (snapshot.package === undefined || snapshot.manifest.version === snapshot.package.version)
@@ -1203,8 +1233,14 @@ function graphChanged(before, after) {
 function meaningfulChange(sourceChange, before, after) {
     const reasons = [];
     const manifest = manifestChanges(before.manifest, after.manifest);
-    if (packageChanged(before, after))
+    if (before.package?.name !== after.package?.name
+        || before.package?.version !== after.package?.version
+        || before.package?.integrity !== after.package?.integrity) {
         reasons.push('npm package version or integrity changed');
+    }
+    if (JSON.stringify(before.package?.migration) !== JSON.stringify(after.package?.migration) && after.package?.migration !== undefined) {
+        reasons.push(`npm package migration declared: ${after.package.name} → ${after.package.migration.to}${after.package.migration.since === undefined ? '' : ` since ${after.package.migration.since}`}`);
+    }
     if (graphChanged(before, after))
         reasons.push('dependency graph changed or became unavailable');
     if (manifest.fields.length > 0)
@@ -1490,55 +1526,96 @@ export async function runOpenAiCompatibleAgent(task, prompt, options) {
         };
     }
     const endpoints = llmCompletionEndpoints(baseUrl);
-    for (let index = 0; index < endpoints.length; index += 1) {
+    const systemPrompt = [
+        '只返回一个严格 JSON 对象。不要输出 Markdown、解释、前缀或后缀；输出必须以 { 开始并以 } 结束。',
+        'Every response must contain exactly the eight fields shown below and no others.',
+        'EXAMPLE JSON OUTPUT:',
+        JSON.stringify({
+            impact: 'unknown',
+            confidence: 'low',
+            evidence: ['State an exact repository path or explicitly name the missing evidence.'],
+            breaking_change: 'unknown',
+            dependency_risk: 'unknown',
+            recommended_action: 'Review the changed runtime paths before upgrading.',
+            urgency: 'monitor',
+            reasoning_summary: 'Separate observed facts from model judgment.',
+        }, null, 2),
+    ].join('\n');
+    endpointLoop: for (let index = 0; index < endpoints.length; index += 1) {
         const endpoint = endpoints[index];
-        try {
-            const response = await fetch(endpoint, {
-                method: 'POST',
-                headers: {
-                    authorization: `Bearer ${apiKey}`,
-                    'content-type': 'application/json',
-                },
-                body: JSON.stringify({
-                    model,
-                    messages: [
-                        { role: 'system', content: '只返回一个严格 JSON 对象。不要输出 Markdown、解释、前缀或后缀；输出必须以 { 开始并以 } 结束。' },
-                        { role: 'user', content: prompt },
-                    ],
-                    temperature: 0,
-                    // DeepSeek V4 enables thinking by default. For this machine-readable
-                    // contract, disable it so the output budget is reserved for the JSON
-                    // conclusion instead of an optional reasoning stream.
-                    ...(isDeepSeekJsonModel(baseUrl, model) ? { thinking: { type: 'disabled' } } : {}),
-                    response_format: { type: 'json_object' },
-                    // Keep an explicit output budget so the JSON conclusion is not
-                    // truncated by a provider default.
-                    max_tokens: DEFAULT_LLM_MAX_TOKENS,
-                }),
-                signal: AbortSignal.timeout(timeoutMs),
-            });
-            if (response.status === 404)
-                continue;
-            if (!response.ok) {
+        for (let attempt = 0; attempt < 2; attempt += 1) {
+            const repairAttempt = attempt === 1;
+            try {
+                const response = await fetch(endpoint, {
+                    method: 'POST',
+                    headers: {
+                        authorization: `Bearer ${apiKey}`,
+                        'content-type': 'application/json',
+                    },
+                    body: JSON.stringify({
+                        model,
+                        messages: [
+                            {
+                                role: 'system',
+                                content: repairAttempt
+                                    ? `The previous JSON-mode response was empty or invalid. Return the example shape now.\n\n${systemPrompt}`
+                                    : systemPrompt,
+                            },
+                            { role: 'user', content: prompt },
+                        ],
+                        temperature: 0,
+                        // DeepSeek V4 enables thinking by default. For this machine-readable
+                        // contract, disable it so the output budget is reserved for the JSON
+                        // conclusion instead of an optional reasoning stream.
+                        ...(isDeepSeekJsonModel(baseUrl, model) ? { thinking: { type: 'disabled' } } : {}),
+                        // DeepSeek documents that JSON Output may occasionally return an
+                        // empty content field. Retry once without provider JSON mode; the
+                        // same exact local schema validator still gates the conclusion.
+                        ...(repairAttempt ? {} : { response_format: { type: 'json_object' } }),
+                        // Keep an explicit output budget so the JSON conclusion is not
+                        // truncated by a provider default.
+                        max_tokens: DEFAULT_LLM_MAX_TOKENS,
+                    }),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (response.status === 404)
+                    continue endpointLoop;
+                if (!response.ok) {
+                    return {
+                        taskId: task.id,
+                        status: 'failed',
+                        error: `LLM endpoint returned HTTP ${response.status}: ${safeLlmEndpoint(endpoint)}`,
+                    };
+                }
+                const body = await response.json();
+                const content = body.choices?.[0]?.message?.content;
+                let conclusionError;
+                if (typeof content !== 'string') {
+                    conclusionError = 'LLM response had no message content';
+                }
+                else {
+                    try {
+                        const parsed = parseAgentOutput(extractJsonObject(content));
+                        if (parsed.value !== undefined) {
+                            return { taskId: task.id, status: 'succeeded', parsedOutput: parsed.value };
+                        }
+                        conclusionError = parsed.error ?? 'LLM returned an invalid conclusion';
+                    }
+                    catch (error) {
+                        conclusionError = safeError(error);
+                    }
+                }
+                if (!repairAttempt)
+                    continue;
                 return {
                     taskId: task.id,
                     status: 'failed',
-                    error: `LLM endpoint returned HTTP ${response.status}: ${safeLlmEndpoint(endpoint)}`,
+                    error: `LLM returned no valid conclusion after JSON-mode and plain-text attempts at ${safeLlmEndpoint(endpoint)}: ${conclusionError}`,
                 };
             }
-            const body = await response.json();
-            const content = body.choices?.[0]?.message?.content;
-            if (typeof content !== 'string') {
-                return { taskId: task.id, status: 'failed', error: `LLM response had no message content: ${safeLlmEndpoint(endpoint)}` };
-            }
-            const parsed = parseAgentOutput(extractJsonObject(content));
-            if (parsed.value === undefined) {
-                return { taskId: task.id, status: 'failed', error: parsed.error ?? 'LLM returned an invalid conclusion' };
+            catch (error) {
+                return { taskId: task.id, status: 'failed', error: `LLM request failed at ${safeLlmEndpoint(endpoint)}: ${safeError(error)}` };
             }
-            return { taskId: task.id, status: 'succeeded', parsedOutput: parsed.value };
-        }
-        catch (error) {
-            return { taskId: task.id, status: 'failed', error: `LLM request failed at ${safeLlmEndpoint(endpoint)}: ${safeError(error)}` };
         }
     }
     return {
@@ -1621,92 +1698,94 @@ export async function runObserver(config, previousState, options = {}) {
     const alignmentFindings = [];
     const errors = [];
     const newTasks = [];
-    for (const configuredTarget of config.targets) {
-        try {
-            const current = await source.observe(configuredTarget, checkedAt);
-            const before = previousState.targets[configuredTarget.id];
-            if (before === undefined) {
-                nextTargets[configuredTarget.id] = current;
-                baselineTargets.push(configuredTarget.id);
-                if (current.alignment !== undefined)
-                    alignmentFindings.push({ targetId: configuredTarget.id, alignment: structuredClone(current.alignment) });
-                continue;
-            }
-            // checkedAt belongs in the run report. Keep the durable observation point
-            // byte-stable when its evidence did not change, so a no-op cron run does
-            // not manufacture a commit from a fresh timestamp alone.
-            nextTargets[configuredTarget.id] = snapshotEvidenceSignature(before) === snapshotEvidenceSignature(current)
-                ? before
-                : current;
-            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,
-                    afterCommit: current.source.commit,
-                    comparison: 'complete',
-                    changedFiles: [],
-                    runtimeFiles: [],
-                    nonRuntimeFiles: [],
+    if (options.retryPendingOnly !== true) {
+        for (const configuredTarget of config.targets) {
+            try {
+                const current = await source.observe(configuredTarget, checkedAt);
+                const before = previousState.targets[configuredTarget.id];
+                if (before === undefined) {
+                    nextTargets[configuredTarget.id] = current;
+                    baselineTargets.push(configuredTarget.id);
+                    if (current.alignment !== undefined)
+                        alignmentFindings.push({ targetId: configuredTarget.id, alignment: structuredClone(current.alignment) });
+                    continue;
                 }
-                : await source.compare(current.source.repository, before.source.commit, current.source.commit);
-            const change = createChange(configuredTarget, before, current, sourceChange, options.reverseDependencyIndex);
-            if (change.reasons.length === 0)
-                continue;
-            let reviewedChange = change;
-            if (change.meaningful && current.package !== undefined && options.artifactReviewer !== undefined) {
-                const packageSpec = `npm:${current.package.name}@${current.package.version}`;
-                try {
-                    reviewedChange = {
-                        ...change,
-                        artifactReview: await options.artifactReviewer(packageSpec, configuredTarget),
-                    };
+                // checkedAt belongs in the run report. Keep the durable observation point
+                // byte-stable when its evidence did not change, so a no-op cron run does
+                // not manufacture a commit from a fresh timestamp alone.
+                nextTargets[configuredTarget.id] = snapshotEvidenceSignature(before) === snapshotEvidenceSignature(current)
+                    ? before
+                    : current;
+                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) });
                 }
-                catch (error) {
-                    // Artifact review is useful evidence, but it must not turn a valid
-                    // source observation into a source-observation error. Keep the
-                    // change and make the incomplete review explicit for the author and
-                    // for a later retry of the whole scheduled run.
-                    reviewedChange = {
-                        ...change,
-                        artifactReview: {
-                            spec: packageSpec,
-                            verdict: 'review',
-                            riskVerdict: 'review',
-                            coverageVerdict: 'incomplete',
-                            artifactIntegrity: 'not-checked',
-                            registrySignature: 'not-checked',
-                            provenance: 'not-checked',
-                            dependencyResolution: 'manifest-only',
-                            dependencyAuditStatus: 'failed',
-                            packages: null,
-                            unresolved: 0,
-                            vulnerabilities: null,
-                            installScriptPackages: [],
-                            installScriptDetails: [],
-                            findings: [],
-                            error: safeError(error),
-                        },
-                    };
+                const sourceChange = before.source.commit === current.source.commit
+                    ? {
+                        beforeCommit: before.source.commit,
+                        afterCommit: current.source.commit,
+                        comparison: 'complete',
+                        changedFiles: [],
+                        runtimeFiles: [],
+                        nonRuntimeFiles: [],
+                    }
+                    : await source.compare(current.source.repository, before.source.commit, current.source.commit);
+                const change = createChange(configuredTarget, before, current, sourceChange, options.reverseDependencyIndex);
+                if (change.reasons.length === 0)
+                    continue;
+                let reviewedChange = change;
+                if (change.meaningful && current.package !== undefined && options.artifactReviewer !== undefined) {
+                    const packageSpec = `npm:${current.package.name}@${current.package.version}`;
+                    try {
+                        reviewedChange = {
+                            ...change,
+                            artifactReview: await options.artifactReviewer(packageSpec, configuredTarget),
+                        };
+                    }
+                    catch (error) {
+                        // Artifact review is useful evidence, but it must not turn a valid
+                        // source observation into a source-observation error. Keep the
+                        // change and make the incomplete review explicit for the author and
+                        // for a later retry of the whole scheduled run.
+                        reviewedChange = {
+                            ...change,
+                            artifactReview: {
+                                spec: packageSpec,
+                                verdict: 'review',
+                                riskVerdict: 'review',
+                                coverageVerdict: 'incomplete',
+                                artifactIntegrity: 'not-checked',
+                                registrySignature: 'not-checked',
+                                provenance: 'not-checked',
+                                dependencyResolution: 'manifest-only',
+                                dependencyAuditStatus: 'failed',
+                                packages: null,
+                                unresolved: 0,
+                                vulnerabilities: null,
+                                installScriptPackages: [],
+                                installScriptDetails: [],
+                                findings: [],
+                                error: safeError(error),
+                            },
+                        };
+                    }
                 }
+                changes.push(reviewedChange);
+                if (!reviewedChange.meaningful || reviewedChange.taskId === undefined)
+                    continue;
+                const task = createUpstreamChangeTask(configuredTarget, reviewedChange, checkedAt);
+                newTasks.push(task);
+                if (!taskAlreadyPending(pendingTasks, task.id))
+                    pendingTasks.push(task);
+            }
+            catch (error) {
+                errors.push({ targetId: configuredTarget.id, message: safeError(error) });
             }
-            changes.push(reviewedChange);
-            if (!reviewedChange.meaningful || reviewedChange.taskId === undefined)
-                continue;
-            const task = createUpstreamChangeTask(configuredTarget, reviewedChange, checkedAt);
-            newTasks.push(task);
-            if (!taskAlreadyPending(pendingTasks, task.id))
-                pendingTasks.push(task);
-        }
-        catch (error) {
-            errors.push({ targetId: configuredTarget.id, message: safeError(error) });
         }
     }
-    const pendingToRetry = options.retryPending === true
+    const pendingToRetry = options.retryPending === true || options.retryPendingOnly === true
         ? pendingTasks.filter(task => !newTasks.some(current => current.id === task.id))
         : [];
     const tasksToInvoke = [...newTasks, ...pendingToRetry];
@@ -1721,7 +1800,7 @@ export async function runObserver(config, previousState, options = {}) {
     const report = {
         schema: OBSERVER_REPORT_SCHEMA,
         checkedAt,
-        targetsChecked: config.targets.length,
+        targetsChecked: options.retryPendingOnly === true ? 0 : config.targets.length,
         baselineTargets,
         alignmentFindings,
         ...(options.reverseDependencyIndex === undefined ? {} : {
@@ -1764,7 +1843,7 @@ export function observerExitCode(report) {
 function displayPackage(value) {
     return value === undefined
         ? 'not observed'
-        : `${value.name}@${value.version}${value.distTag === undefined ? '' : ` via npm tag ${value.distTag}`}`;
+        : `${value.name}@${value.version}${value.distTag === undefined ? '' : ` via npm tag ${value.distTag}`}${value.migration === undefined ? '' : `; migrates to ${value.migration.to}${value.migration.since === undefined ? '' : ` since ${value.migration.since}`}`}`;
 }
 function displayGraph(value) {
     return value === undefined ? 'not observed' : `${value.nodes} nodes, ${value.edges} edges${value.unresolved === 0 ? '' : `, ${value.unresolved} unresolved`}`;