dsh-composition-doctor 0.3.0 → 0.4.0

package/dist/core/preflight/npm-artifact.js

@@ -1,5 +1,5 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { basename, resolve } from 'node:path';
 import { gunzipSync } from 'node:zlib';
 function text(bytes) {
@@ -56,7 +56,23 @@ async function atomicWrite(path, bytes) {
     const temporaryPath = `${path}.${randomBytes(12).toString('hex')}.partial`;
     try {
         await writeFile(temporaryPath, bytes, { flag: 'wx' });
-        await rename(temporaryPath, path);
+        try {
+            await rename(temporaryPath, path);
+        }
+        catch (error) {
+            // Windows can refuse a competing rename after another downloader has
+            // already published this exact artifact. Accept only identical regular
+            // files; never unlink an existing cache entry to work around the race.
+            const code = error.code;
+            if (code !== 'EPERM' && code !== 'EEXIST')
+                throw error;
+            const existing = await lstat(path).catch(() => undefined);
+            if (!existing?.isFile() || existing.isSymbolicLink())
+                throw error;
+            const published = await readFile(path).catch(() => undefined);
+            if (published === undefined || !published.equals(Buffer.from(bytes)))
+                throw error;
+        }
     }
     finally {
         await rm(temporaryPath, { force: true }).catch(() => undefined);

package/dist/core/rules.js

@@ -30,6 +30,8 @@ function satisfiesRange(version, range) {
     if (parseVersion(version) === undefined || range.trim().length === 0)
         return undefined;
     try {
+        if (['workspace:^', 'workspace:~', 'workspace:*'].includes(range))
+            return true;
         return semverSatisfies(version, range, { includePrerelease: true });
     }
     catch {
@@ -47,7 +49,8 @@ function peerDiagnostics(model) {
             if (range === undefined)
                 continue;
             const actual = runtime[fact];
-            const item = evidence(peer.source, `${peer.packageName}:${fact}`, `requires ${fact} ${range}; observed ${actual ?? 'unknown'}`, peer.evidenceKind, peer.packageName);
+            const label = fact === 'dsh' ? peer.dshPackage ?? fact : fact;
+            const item = evidence(peer.source, `${peer.packageName}:${fact}`, `requires ${label} ${range}; observed ${actual ?? 'unknown'}`, peer.evidenceKind, peer.packageName);
             if (actual === undefined) {
                 diagnostics.push(diagnostic('peer-version-facts-unavailable', 'warning', 'Runtime version fact is unavailable', [item], `The ${fact} version needed to evaluate ${peer.packageName} was not supplied.`, 'Provide the selected runtime version or treat this static compatibility finding as unproven.'));
                 continue;
@@ -86,12 +89,16 @@ function rowKeys(row) {
 function rowDiagnostics(rows) {
     const diagnostics = [];
     for (const [id, group] of groups(rows.filter((row) => row.id !== undefined), (row) => row.id)) {
+        const inserts = group.filter((row) => row.operation === 'insert' || row.operation === 'declare');
+        if (inserts.length > 1) {
+            diagnostics.push(diagnostic('duplicate-loader-declarations', 'warning', 'Multiple loader declarations introduce the same row id', inserts.map((row) => evidence(row.source, id, 'An independent declaration introduces this loader id.', row.evidenceKind, row.name)), 'Separate insertion declarations share a loader id; static evidence does not prove the final loader outcome.', 'Review the bundle and profile insertion paths; retain the intended declaration and configuration manually.'));
+        }
         const layers = groups(group, (row) => row.layer ?? row.source);
         if (layers.size === 1 && group.length > 1) {
             diagnostics.push(diagnostic('duplicate-row-in-same-layer', 'warning', 'Duplicate composition row id in one layer', group.map((row) => evidence(row.source, id, `row id ${id} is declared more than once in the same layer`, row.evidenceKind, row.name)), `The DSH public row semantics do not establish which declaration should win within one layer for ${id}.`, 'Give the row a unique id or verify the final resolved tree with a public dump provider.'));
             continue;
         }
-        if (layers.size < 2)
+        if (layers.size < 2 || inserts.length === group.length)
             continue;
         const ordered = [...group].sort((left, right) => (left.layerOrder ?? Number.MAX_SAFE_INTEGER) - (right.layerOrder ?? Number.MAX_SAFE_INTEGER));
         const previous = ordered[ordered.length - 2];

package/dist/core/snapshot.js

@@ -53,7 +53,7 @@ function snapshotFromModel(model, input) {
     const hashes = Object.fromEntries((input?.files ?? []).filter((file) => ['package.json', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'].includes(file.relativePath)).map((file) => [file.relativePath, file.sha256]));
     return {
         schemaVersion: 2,
-        doctorVersion: '0.1.3',
+        doctorVersion: '0.4.0',
         runtime: { ...(model.runtime?.dsh === undefined ? {} : { dsh: model.runtime.dsh }), ...(model.runtime?.cordis === undefined ? {} : { cordis: model.runtime.cordis }), node: model.runtime?.node ?? process.versions.node, platform: model.runtime?.platform ?? process.platform },
         profile: { ...(profileName === undefined ? {} : { name: profileName }), ...(manifest === undefined ? {} : { manifestHash: manifest.sha256 }) },
         packages: sortJson(packages),

package/dist/reports/failure.js

@@ -0,0 +1,23 @@
+export function renderFailure(result, markdown = false) {
+    const lines = [markdown ? '# DSH Composition Doctor — Failure Explanation' : 'DSH Composition Doctor — Failure Explanation', '',
+        `Profile: ${result.profile}; runtime: ${result.runtime}`, ''];
+    if (result.explanations.length === 0)
+        lines.push(result.outcome === 'no-match'
+            ? 'No supported failure signature matched. Cause: unknown.' : result.outcome === 'unknown' ? 'Selected metadata could not be fully inspected. Cause: unknown.' : 'No supported composition issue was observed. Runtime health: unknown.', '');
+    for (const item of result.explanations.slice(0, markdown ? 50 : 3)) {
+        lines.push(`${markdown ? '## ' : ''}${item.detectedFailure}`, `${item.origin}; evidence: ${item.evidenceLevel}`, '', `Cause: ${item.observableCause}`, '');
+        for (const [index, path] of item.provenancePaths.entries()) {
+            lines.push(`Path ${index + 1}: ${path.packageName === undefined ? '' : `bundle ${path.packageName} → `}${path.source}`, `  ${path.layer === undefined ? 'layer: unknown' : `layer: ${path.layer}`}${path.rowId === undefined ? '' : ` → row: ${path.rowId}`}`);
+            if (path.provenance.length > (markdown ? 0 : 1))
+                lines.push(`  provenance: ${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(' → ')}`);
+        }
+        const unknown = markdown ? item.unknowns.join(' ') : `runtime not observed / not-run${item.evidenceLevel === 'static' ? '; final composition unknown' : ''}${item.causeStatus === 'unknown' ? '; cause unproven' : ''}.`;
+        lines.push('', `Unknown: ${unknown}`, `Next: ${item.manualRemediation}`, '');
+    }
+    if (!markdown && result.explanations.length > 3)
+        lines.push(`${result.explanations.length - 3} more explanation(s); use --format json or markdown.`, '');
+    if (markdown || result.explanations.length === 0 || result.input.log === 'not-provided')
+        lines.push(result.nextStep);
+    lines.push('Doctor did not modify your profile.', '');
+    return lines.join('\n');
+}

package/dist/reports/markdown.js

@@ -1,3 +1,4 @@
+import { renderFailure } from './failure.js';
 function formatEvidence(item) {
     const subject = item.subject === undefined ? '' : ` — ${item.subject}`;
     const packageLabel = item.packageName === undefined ? '' : ` (${item.packageName}${item.version === undefined ? '' : `@${item.version}`})`;
@@ -9,7 +10,8 @@ function formatDiagnostic(item) {
 }
 export function renderMarkdown(report) {
     const summary = ['error', 'warning', 'info'].map((severity) => `${severity}: ${report.diagnostics.filter((item) => item.severity === severity).length}`).join(', ');
-    const body = report.diagnostics.length === 0 ? 'No diagnostics were produced.' : report.diagnostics.map(formatDiagnostic).join('\n\n');
+    const diagnosticBody = report.diagnostics.length === 0 ? 'No diagnostics were produced.' : report.diagnostics.map(formatDiagnostic).join('\n\n');
+    const body = report.failureExplanation === undefined ? diagnosticBody : `${renderFailure(report.failureExplanation, true)}\n${diagnosticBody}`;
     const coverage = report.metadataCoverage === undefined ? '' : `\nMetadata coverage: ${report.metadataCoverage.mode}; unscanned: ${report.metadataCoverage.unscannedSurfaces.join('; ')}\n`;
     return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}; evidence schema: ${report.evidenceSchemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nEvidence mode: ${report.evidenceMode}; runtime observed: ${report.runtimeObserved ? 'yes' : 'no'}\n${coverage}\nSummary: ${summary}\n\n${body}\n`;
 }

package/dist/reports/schema.js

@@ -12,6 +12,34 @@ export const analysisReportJsonSchema = {
         evidenceMode: { enum: ['static', 'composed', 'runtime-observed', 'mixed'] },
         runtimeObserved: { type: 'boolean' },
         unverifiedFindings: { type: 'array', items: { type: 'string' } },
+        failureExplanation: {
+            type: 'object', required: ['schemaVersion', 'outcome', 'profile', 'runtime', 'input', 'explanations', 'unknowns', 'nextStep'],
+            properties: {
+                schemaVersion: { const: 1 }, outcome: { enum: ['explained', 'unknown', 'no-match', 'no-supported-issues'] },
+                profile: { const: '<PROFILE>' }, runtime: { const: 'not-observed' },
+                input: { type: 'object', required: ['log', 'recognizedSignatures', 'truncated'], properties: {
+                        log: { enum: ['not-provided', 'reported-by-log'] }, recognizedSignatures: { type: 'integer', minimum: 0 }, truncated: { type: 'boolean' }
+                    }, additionalProperties: false },
+                explanations: { type: 'array', items: {
+                        type: 'object', required: ['pattern', 'detectedFailure', 'origin', 'causeStatus', 'observableCause', 'provenancePaths', 'evidenceLevel', 'unknowns', 'manualRemediation', 'relatedDiagnostics'],
+                        properties: {
+                            pattern: { enum: ['duplicate-loader-entry', 'bundle-unavailable', 'bundle-patch-unavailable', 'patch-target-missing', 'peer-incompatible', 'config-replacement'] },
+                            detectedFailure: { type: 'string' }, origin: { enum: ['reported-by-log', 'observed-from-composition'] },
+                            matchedEntity: { type: 'object', required: ['kind', 'id'], properties: { kind: { enum: ['row', 'package'] }, id: { type: 'string' } }, additionalProperties: false },
+                            causeStatus: { enum: ['observable-condition', 'unknown'] }, observableCause: { type: 'string' },
+                            provenancePaths: { type: 'array', items: { type: 'object', required: ['source', 'provenance', 'evidence'], properties: {
+                                        source: { type: 'string' }, layer: { type: 'string' }, packageName: { type: 'string' }, rowId: { type: 'string' }, rowKey: { type: 'string' },
+                                        provenance: { type: 'array', items: { type: 'object', required: ['source', 'sourceBasis', 'relation', 'basis'], properties: { source: { type: 'string' }, sourceBasis: { const: 'observed' }, relation: { enum: ['introduced', 'patched-by'] }, basis: { enum: ['observed', 'derived'] } }, additionalProperties: false } },
+                                        evidence: { enum: ['static', 'composed', 'runtime-observed'] }
+                                    }, additionalProperties: false } },
+                            evidenceLevel: { enum: ['static', 'composed', 'runtime-observed', 'unknown'] },
+                            unknowns: { type: 'array', items: { type: 'string' } }, manualRemediation: { type: 'string' },
+                            relatedDiagnostics: { type: 'array', items: { type: 'object' } }
+                        }, additionalProperties: false
+                    } },
+                unknowns: { type: 'array', items: { type: 'string' } }, nextStep: { type: 'string' }
+            }, additionalProperties: false
+        },
         compositionFacts: {
             type: 'object',
             required: ['schemaVersion', 'evidenceMode', 'nodes', 'edges', 'rows', 'unknownSurfaces'],
@@ -39,6 +67,7 @@ export const analysisReportJsonSchema = {
                         type: 'object', required: ['entity', 'key', 'source', 'sourceBasis', 'provenance', 'replacement', 'configKeys', 'configKeysBasis', 'evidenceMode', 'relatedDiagnosticIds', 'unknown'],
                         properties: {
                             entity: { const: 'row' }, key: { type: 'string' }, id: { type: 'string' }, name: { type: 'string' },
+                            operation: { enum: ['insert', 'update', 'declare'] },
                             source: { type: 'string' }, sourceBasis: { const: 'observed' }, layer: { type: 'string' }, layerOrder: { type: 'number' },
                             provenance: { type: 'array', items: { type: 'object', required: ['source', 'sourceBasis', 'relation', 'basis'], properties: { source: { type: 'string' }, sourceBasis: { const: 'observed' }, relation: { enum: ['introduced', 'patched-by'] }, basis: { enum: ['observed', 'derived'] } }, additionalProperties: false } },
                             replacement: { type: 'object', required: ['state', 'basis'], properties: { state: { enum: ['yes', 'no', 'unknown'] }, basis: { enum: ['observed', 'derived', 'unknown'] } }, additionalProperties: false },

package/package.json

@@ -1,66 +1,67 @@
-{
-  "name": "dsh-composition-doctor",
-  "version": "0.3.0",
-  "private": false,
-  "description": "Read-only DSH and Cordis composition diagnostics, snapshots, diffs, and isolated preflight.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/lemonxiny55/dsh-composition-doctor.git"
-  },
-  "main": "./dist/plugin/index.js",
-  "bin": {
-    "dsh-doctor": "./dist/cli/main.js"
-  },
-  "exports": {
-    ".": "./dist/plugin/index.js",
-    "./client": "./dist/client.js",
-    "./cli": "./dist/cli/main.js",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "cordis.patch.yml",
-    "README.md",
-    "README.zh.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-runtime",
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins",
-        "@deepseek-ai/dsh-client-locale"
-      ],
-      "immediately": false
-    }
-  },
-  "type": "module",
-  "engines": {
-    "node": ">=20"
-  },
-  "packageManager": "pnpm@10.17.1",
-  "scripts": {
-    "test": "pnpm build && vitest run",
-    "typecheck": "tsc --noEmit",
-    "build": "tsc && node scripts/build-client.mjs",
-    "dsh-doctor": "node dist/cli/main.js"
-  },
-  "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1",
-    "semver": "^7.7.2",
-    "yaml": "^2.8.1"
-  },
-  "devDependencies": {
-    "@types/node": "^24.3.0",
-    "esbuild": "^0.28.2",
-    "typescript": "^5.9.2",
-    "vitest": "^3.2.4"
-  }
-}
+{
+  "name": "dsh-composition-doctor",
+  "version": "0.4.0",
+  "private": false,
+  "description": "Explain DSH plugin failures through observable composition paths. Read-only, offline by default, with snapshots and upgrade preflight.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lemonxiny55/dsh-composition-doctor.git"
+  },
+  "main": "./dist/plugin/index.js",
+  "bin": {
+    "dsh-doctor": "./dist/cli/main.js"
+  },
+  "exports": {
+    ".": "./dist/plugin/index.js",
+    "./client": "./dist/client.js",
+    "./cli": "./dist/cli/main.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "immediately": false
+    }
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "semver": "^7.7.2",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "esbuild": "^0.28.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "pnpm build && vitest run",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc && node scripts/build-client.mjs",
+    "dsh-doctor": "node dist/cli/main.js",
+    "smoke:pack": "node scripts/pack-smoke.mjs",
+    "demo:failure": "node scripts/failure-demo.mjs"
+  }
+}