upstream-radar 0.34.0 → 0.36.0

package/README.md

@@ -4,27 +4,74 @@
 [![npm](https://img.shields.io/npm/v/upstream-radar)](https://www.npmjs.com/package/upstream-radar)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 
-**Dependency evidence and upstream-change monitoring for [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugins.**
+**The upstream dependency radar built into [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) plugins.**
 
-Upstream Radar answers a practical question before a plugin enters a DSH profile:
+Upstream Radar is not another package-name vulnerability scanner. It follows one DSH plugin from admission to maintenance:
 
-> Which exact dependency versions does this plugin bring in, which vulnerability or upstream release changed them, and which other plugins will be affected?
+| Product job | What Radar establishes |
+| --- | --- |
+| **DSH compatibility / admission** | Whether the exact published bundle can be registered and loaded by the DSH releases you care about. |
+| **Real dependency graph** | Which exact package versions and physical paths the plugin brings into the DSH profile, including unresolved edges. |
+| **Continuous upstream monitoring** | Whether an advisory, npm release, DSH/Cordis change, or breaking signal changes the old → new situation. |
+| **Author-facing repair** | Which plugin, dependency path, version, lockfile, or DSH declaration gives the author a concrete next fix. |
+
+The deterministic scanner establishes package, graph, advisory, and compatibility facts. Only a meaningful affected change is handed to the DSH Agent for read-only, project-specific analysis; the model does not guess version matches or replace the evidence.
+
+## The product loop
+
+```mermaid
+flowchart TD
+  A["DSH plugin source or exact npm artifact"] --> B["DSH compatibility / admission check"]
+  B --> C["Build the real plugin → dependency graph"]
+  C --> D["Monitor advisories, npm, DSH and Cordis changes"]
+  D --> E{"Meaningful affected change?"}
+  E -- "No" --> F["Update observation point and stay quiet"]
+  E -- "Yes" --> G["Calculate exact old → new impact paths"]
+  G --> H["Send bounded evidence to the DSH Agent"]
+  H --> I["Return a repairable action to the plugin author"]
+```
+
+This is the boundary: Radar decides **what changed and which exact path is involved**; DSH decides **what that means for the project**. A later website can visualize the saved graph, but the evidence and impact index are already useful without one.
+
+## The upstream/downstream alignment IR
+
+Every observer snapshot now carries a small, machine-readable alignment record:
+
+```text
+upstream:   Git commit + package.json coordinate
+downstream: npm coordinate + lockfile graph root + graph coverage
+result:     aligned | mismatch | unknown
+```
+
+This catches a class of problems that a vulnerability scanner cannot: the source
+package, published package, and dependency graph may no longer describe the
+same thing. For example, the public DSH/Feishu target currently reports:
 
-It reads source trees, lockfiles, exact npm artifacts, saved DSH reports, and public advisory feeds. It does not install a plugin or execute its business code during static review.
+```text
+source:    dsh-lark-bot@0.15.8
+published: dsh-feishu-bot@0.15.8
+graph root: dsh-lark-bot@0.15.8
+result:    mismatch
+```
+
+That is not a claim of malware or runtime incompatibility. It is an evidence
+gap: Radar cannot safely say that the source it watched produced the artifact
+users install. The IR is stored in `observations.json`, rendered in the first
+baseline report, and defined in [`schemas/upstream-downstream-ir.schema.json`](schemas/upstream-downstream-ir.schema.json).
 
 ## Try it in 60 seconds
 
 ```bash
 # No DSH profile, API key, or network state required
-npx --yes upstream-radar@0.34.0 demo
+npx --yes upstream-radar@0.36.0 demo
 
 # Scan a public DSH plugin repository without installing it
-npx --yes upstream-radar@0.34.0 scan \
+npx --yes upstream-radar@0.36.0 scan \
   https://github.com/PlutoKeating/dsh-lark-bot \
   --fail-on never
 
-# Review the exact package users would install, then check two DSH releases
-npx --yes upstream-radar@0.34.0 review dsh-plugin dsh-feishu-bot@0.15.8 \
+# Review a real browser plugin users would install, then check two DSH releases
+npx --yes upstream-radar@0.36.0 review dsh-plugin dsh-cloudflare-browser-run@0.1.1 \
   --dsh-version 0.1.0-rc.6,0.1.0-rc.7
 ```
 
@@ -36,6 +83,7 @@ These are real, reproducible cases in this repository—not synthetic “vulnera
 
 | Case | Finding | Why it matters |
 | --- | --- | --- |
+| [`dsh-cloudflare-browser-run@0.1.1`](examples/reports/dsh-cloudflare-browser-run-0.1.1.txt) | 18 resolved packages, 2 unresolved optional Cordis edges, 0 known vulnerabilities, and DSH rc.6/rc.7 both loaded the bundle | A real browser plugin demonstrates the DSH admission boundary and why incomplete edges stay visible. |
 | [50-plugin batch](examples/dsh/reports/dsh-batch-50-2026-08-17.md) | 0 confirmed runtime dependency vulnerabilities; 3 lockfile root-version mismatches | Monitoring can be wrong even when the vulnerability count is zero. |
 | [`dsh-feishu-bot@0.15.8`](examples/dsh/reports/dsh-feishu-bot-0.15.8-review-2026-08-18.md) | 89-package graph, 12 unresolved optional edges, reachable `protobufjs` `postinstall`, DSH rc.6/rc.7 compatible | “No known CVE” is not the same as “no installation trust boundary.” |
 | [DSH-TUI source vs npm](examples/dsh/reports/dsh-tui-source-vs-npm-2026-08-18.md) | Source has `prepare`; published artifact does not | Source-only and artifact-only reviews answer different questions. |
@@ -43,30 +91,27 @@ These are real, reproducible cases in this repository—not synthetic “vulnera
 
 We report a confirmed vulnerability only when the affected exact version and runtime path are supported by the available evidence. Development-only hits, missing data, and advisory-source outages remain visibly different states.
 
-## The core workflow
+## The dependency graph behind every alert
 
 ```text
-DSH plugin source / npm artifact
-          ↓
-exact dependency graph + DSH compatibility evidence
-          ↓
-saved observation point
-          ↓
-upstream commit, package, or advisory changes
-          ↓
-affected-plugin paths and author-facing next action
-          ↓
-optional DSH Agent analysis only when a meaningful change exists
+plugin@1.0.0
+├── framework@2.4.7
+│   ├── parser@3.2.1
+│   └── archive@1.8.0
+└── logger@4.0.2
+    └── parser@2.9.0  ← the affected physical node
 ```
 
+Two copies of `parser` are different nodes. An alert names the exact version and path that entered the DSH profile; it does not page every plugin that happens to use the same package name.
+
 For a collection of saved reports, build the reverse index that turns an upstream package update into affected plugins:
 
 ```bash
-npx --yes upstream-radar@0.34.0 graph reverse ./reports \
+npx --yes upstream-radar@0.36.0 graph reverse ./reports \
   --output reverse-dependency-index.json
 
 # Ask: which plugins currently depend on this exact package?
-npx --yes upstream-radar@0.34.0 graph reverse ./reports \
+npx --yes upstream-radar@0.36.0 graph reverse ./reports \
   --package parser@2.9.0
 ```
 
@@ -78,12 +123,30 @@ plugin@1.0.0 → logger@4.0.2 → parser@2.9.0
 
 It also preserves whether the graph is complete or has unresolved optional/peer edges. A later website can visualize this index; the index and evidence remain the product foundation.
 
+To route an upstream old → new change to that index, pass it to the always-on
+observer:
+
+```bash
+npx --yes upstream-radar@0.36.0 observe ./targets.yml \
+  --reverse-index ./reverse-dependency-index.json \
+  --state ./observations.json \
+  --report ./upstream-radar-observer.md
+```
+
+The observer matches by package name, not only by the new exact version. If
+`parser@1.0.0` becomes `parser@2.0.0` upstream while a downstream plugin still
+uses `parser@1.0.0`, the report names that plugin and its path as a possible
+impact. `complete` or `incomplete` coverage stays attached to the result; this
+is an evidence-based routing signal, not a claim that the plugin is already
+broken. See the persisted index definition in
+[`schemas/reverse-dependency-index.schema.json`](schemas/reverse-dependency-index.schema.json).
+
 ## GitHub Action
 
 The repository already contains a reusable, composite Action in [`action.yml`](action.yml). It runs the same frozen Radar check in CI and writes a short Job Summary.
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.34.0
+- uses: MicroMilo/upstream-radar@v0.36.0
   with:
     config: upstream-radar.config.json
     fail-on: high
@@ -107,7 +170,7 @@ See the [consumer workflow](examples/github-actions/consumer/README.md) for conf
 pnpm add upstream-radar
 
 # Generate a reviewable DSH profile inventory from the installed profile
-npx --yes upstream-radar@0.34.0 setup
+npx --yes upstream-radar@0.36.0 setup
 ```
 
 For Feishu/webhook routing, DSH Agent handoff, observer state, report schemas, and troubleshooting, use the [full Chinese guide](docs/README.zh-CN.md). The [architecture notes](docs/architecture.md) explain the boundaries and evidence model.

package/dist/src/cli.js

@@ -14,7 +14,7 @@ import { checkDshProfile, renderDshProfileCheck, renderDshProfileCheckSummary }
 import { createDemoReport, renderDemo } from './demo.js';
 import { GitHubReleaseClient } from './github-release.js';
 import { parseNpmLockGraph, parsePnpmLockGraph } from './graph.js';
-import { buildReverseDependencyIndex, findReverseDependencyEntry, parseReverseDependencyObservations } from './dependency-index.js';
+import { buildReverseDependencyIndex, findReverseDependencyEntry, parseReverseDependencyIndex, parseReverseDependencyObservations } from './dependency-index.js';
 import { createRadarConfigFromDshProfile, createRadarConfigFromNpmLock, createRadarConfigFromPnpmLock, discoverDshProfiles, refreshRadarConfigFromConfiguredProfile, resolveDshProfileDirectory, writeDshPatch, writeRadarConfig } from './init.js';
 import { parsePackageManifestSnapshot, parseRadarConfig } from './inventory.js';
 import { inspectNpmPackage } from './npm.js';
@@ -202,6 +202,7 @@ should remain visible without failing CI.
 Usage:
   upstream-radar observe <targets.yml|github-url> [--state <observations.json>]
     [--report <report.md>] [--dsh-version <v1>,<v2>,...]
+    [--reverse-index <index.json>]
     [--dsh-agent-command <executable>]
     [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending]
     [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>]
@@ -462,7 +463,7 @@ Usage:
   upstream-radar doctor [config.json] [options]
   upstream-radar scan <directory-or-github-url> [--json] [--fail-on <warn|review|block|never>]
   upstream-radar inspect [npm:]<package>@<exact-version> [--deep] [--json] [--fail-on <warn|review|block|never>]
-  upstream-radar observe <targets.yml|github-url> [--state <observations.json>] [--report <report.md>] [--dsh-version <v1>,<v2>,...] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>] [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>] [--ref <branch>] [--json]
+  upstream-radar observe <targets.yml|github-url> [--state <observations.json>] [--report <report.md>] [--dsh-version <v1>,<v2>,...] [--reverse-index <index.json>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>] [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>] [--ref <branch>] [--json]
   upstream-radar graph <npm-lock|pnpm-lock> <lockfile> [--root <package>@<exact-version>] [--json]
   upstream-radar graph reverse <reports-directory> [--package <name>@<exact-version>] [--output <index.json>] [--json]
   upstream-radar profile-check [profile-directory] [--patch <path>] [--report <path>] [--summary] [--json]
@@ -1749,6 +1750,7 @@ async function runObserve(args) {
     let agentCommand;
     let agentArgs = [];
     let llmEnvFile;
+    let reverseIndexPath;
     let registry;
     let retryPending = false;
     let json = false;
@@ -1769,7 +1771,7 @@ async function runObserve(args) {
         else if (argument === '--retry-pending') {
             retryPending = true;
         }
-        else if (argument === '--ecosystem' || argument === '--id' || argument === '--package' || argument === '--package-path' || argument === '--lockfile' || argument === '--lockfile-type' || argument === '--ref' || argument === '--dsh-version' || argument === '--state' || argument === '--report' || argument === '--dsh-agent-command' || argument === '--dsh-agent-arg' || argument === '--llm-env-file' || argument === '--registry') {
+        else if (argument === '--ecosystem' || argument === '--id' || argument === '--package' || argument === '--package-path' || argument === '--lockfile' || argument === '--lockfile-type' || argument === '--ref' || argument === '--dsh-version' || argument === '--state' || argument === '--report' || argument === '--reverse-index' || argument === '--dsh-agent-command' || argument === '--dsh-agent-arg' || argument === '--llm-env-file' || argument === '--registry') {
             const value = args[index + 1];
             if (value === undefined || (value.startsWith('-') && argument !== '--dsh-agent-arg'))
                 throw new Error(`${argument} requires a value`);
@@ -1793,6 +1795,8 @@ async function runObserve(args) {
                 statePath = value;
             else if (argument === '--report')
                 reportPath = value;
+            else if (argument === '--reverse-index')
+                reverseIndexPath = value;
             else if (argument === '--dsh-agent-command')
                 agentCommand = value;
             else if (argument === '--dsh-agent-arg')
@@ -1801,7 +1805,7 @@ async function runObserve(args) {
                 llmEnvFile = value;
             else
                 registry = value;
-            if (argument !== '--state' && argument !== '--report' && argument !== '--dsh-agent-command' && argument !== '--dsh-agent-arg' && argument !== '--llm-env-file' && argument !== '--registry')
+            if (argument !== '--state' && argument !== '--report' && argument !== '--reverse-index' && argument !== '--dsh-agent-command' && argument !== '--dsh-agent-arg' && argument !== '--llm-env-file' && argument !== '--registry')
                 inlineOptionsUsed = true;
             index += 1;
         }
@@ -1839,6 +1843,9 @@ async function runObserve(args) {
         config = parseObserverConfigText(targetText);
     }
     const previousState = await loadObservationState(statePath);
+    const reverseDependencyIndex = reverseIndexPath === undefined
+        ? undefined
+        : parseReverseDependencyIndex(await readJson(reverseIndexPath), reverseIndexPath);
     const source = new UpstreamObserverClient({
         ...(process.env.GITHUB_TOKEN === undefined ? {} : { githubToken: process.env.GITHUB_TOKEN }),
         ...(registry === undefined ? {} : { registry }),
@@ -1855,6 +1862,7 @@ async function runObserve(args) {
     }
     const result = await runObserver(config, previousState, {
         source,
+        ...(reverseDependencyIndex === undefined ? {} : { reverseDependencyIndex }),
         retryPending,
         artifactReviewer: async (spec, target) => reviewObserverArtifact(spec, target, registry),
         ...(agentOptions === undefined ? {} : {