dsh-composition-doctor 0.1.0

package/dist/core/diff.js

@@ -0,0 +1,69 @@
+function formatChange(change) {
+    const before = change.before === undefined ? '' : ` before=${JSON.stringify(change.before)}`;
+    const after = change.after === undefined ? '' : ` after=${JSON.stringify(change.after)}`;
+    return `- **${change.kind}** \`${change.key}\`${before}${after}`;
+}
+/** Renders the semantic diff without hiding the evidence in a summary-only line. */
+export function renderSnapshotDiffMarkdown(diff) {
+    const sections = [
+        ['Plugins', diff.pluginChanges],
+        ['Cordis rows', diff.rowChanges],
+        ['Tool hooks', diff.hookChanges],
+        ['UI claims', diff.uiConflictChanges],
+        ['Peer requirements', diff.peerChanges],
+        ['Platform requirements', diff.platformChanges]
+    ];
+    const body = sections.map(([title, values]) => `## ${title}\n\n${values.length === 0 ? 'No changes.' : values.map(formatChange).join('\n')}`).join('\n\n');
+    const riskItems = diff.upgradeRisk.items.length === 0 ? '- None.' : diff.upgradeRisk.items.map((item) => `- ${item}`).join('\n');
+    return `# DSH Composition Doctor Snapshot Diff\n\n${diff.upgradeRisk.summary}\n\n## Upgrade risk items\n\n${riskItems}\n\n${body}\n`;
+}
+function compareVersions(left, right) {
+    if (left === undefined || right === undefined)
+        return undefined;
+    const parse = (value) => /^(\d+)\.(\d+)\.(\d+)/.exec(value)?.slice(1).map(Number);
+    const a = parse(left);
+    const b = parse(right);
+    if (a === undefined || b === undefined)
+        return undefined;
+    for (let index = 0; index < 3; index += 1)
+        if (a[index] !== b[index])
+            return a[index] < b[index] ? -1 : 1;
+    return 0;
+}
+function changes(before, after, key) {
+    const previous = new Map(before.map((item) => [key(item), item]));
+    const next = new Map(after.map((item) => [key(item), item]));
+    const result = [];
+    for (const itemKey of [...new Set([...previous.keys(), ...next.keys()])].sort()) {
+        const left = previous.get(itemKey);
+        const right = next.get(itemKey);
+        if (left === undefined)
+            result.push({ kind: 'added', key: itemKey, after: right });
+        else if (right === undefined)
+            result.push({ kind: 'removed', key: itemKey, before: left });
+        else if (JSON.stringify(left) !== JSON.stringify(right))
+            result.push({ kind: 'changed', key: itemKey, before: left, after: right });
+    }
+    return result;
+}
+export function diffSnapshots(before, after) {
+    const pluginChanges = changes(before.plugins, after.plugins, (item) => item.name).map((change) => {
+        if (change.kind !== 'changed')
+            return { ...change, name: change.key };
+        const comparison = compareVersions(change.before?.version, change.after?.version);
+        return { ...change, name: change.key, kind: comparison === undefined ? 'changed' : comparison < 0 ? 'upgraded' : comparison > 0 ? 'downgraded' : 'changed' };
+    });
+    const rowChanges = changes(before.rows, after.rows, (item) => `${item.source}:${item.id ?? item.name ?? ''}`);
+    const hookChanges = changes(before.hooks, after.hooks, (item) => `${item.source}:${item.hook}:${item.packageName ?? ''}`);
+    const uiConflictChanges = changes(before.uiClaims, after.uiClaims, (item) => `${item.kind}:${item.value}:${item.source}`);
+    const peerChanges = changes(before.peers, after.peers, (item) => `${item.source}:${item.packageName}`);
+    const platformChanges = changes(before.platforms, after.platforms, (item) => `${item.source}:${item.packageName}`);
+    const items = pluginChanges.filter((change) => change.kind === 'downgraded' || change.kind === 'upgraded').map((change) => `${change.kind} plugin ${change.name}`);
+    if (hookChanges.length > 0)
+        items.push('hook registrations changed; verify runtime ordering in an isolated fixture');
+    if (uiConflictChanges.length > 0)
+        items.push('UI claims changed; verify ownership conflicts before upgrade');
+    if (peerChanges.length > 0 || platformChanges.length > 0)
+        items.push('peer or platform requirements changed; verify supported runtime facts');
+    return { pluginChanges, rowChanges, hookChanges, uiConflictChanges, peerChanges, platformChanges, upgradeRisk: { summary: items.length === 0 ? 'No upgrade risks detected from snapshot metadata.' : `Upgrade risk: ${items.join('; ')}. No migration was executed.`, items } };
+}

package/dist/core/preflight.js

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { resolveComposition } from './composition-adapter.js';
+import { readProfile } from './profile-reader.js';
+import { redact } from './redaction.js';
+import { analyseComposition } from './rules.js';
+const yamlFiles = new Set(['cordis.yml', 'cordis.patch.yml']);
+const lockFiles = new Set(['pnpm-lock.yaml', 'package-lock.json', 'yarn.lock']);
+const packageNamePattern = /^(?:@[a-z0-9_.-]+\/)?[a-z0-9_.-]+$/i;
+const versionPattern = /^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9a-z.-]+)?(?:\+[0-9a-z.-]+)?$/i;
+function evidence(source, subject, detail, severity) {
+    return { source, subject, detail, ...(severity === undefined ? {} : { severity }) };
+}
+/** A digest of the allow-listed metadata surface; file contents are never returned. */
+export function profileFingerprint(input) {
+    const surface = input.files
+        .map((file) => `${file.relativePath}\u0000${file.sha256}`)
+        .sort()
+        .join('\u0001');
+    return createHash('sha256').update(surface, 'utf8').digest('hex');
+}
+function safeCandidate(value) {
+    const at = value.lastIndexOf('@');
+    if (at <= 0 || at === value.length - 1)
+        return false;
+    const name = value.slice(0, at);
+    const version = value.slice(at + 1);
+    return packageNamePattern.test(name) && versionPattern.test(version);
+}
+function safeMetadataText(relativePath, text) {
+    try {
+        if (relativePath === 'package.json') {
+            return `${JSON.stringify(redact(JSON.parse(text)), null, 2)}\n`;
+        }
+        if (yamlFiles.has(relativePath)) {
+            return stringify(redact(parse(text)));
+        }
+    }
+    catch {
+        // Invalid metadata is reported by the composition adapter; it is not copied
+        // because copying an unparseable source could carry an undiscovered secret.
+    }
+    return undefined;
+}
+async function prepareIsolatedProfile(input, directory, evidenceItems) {
+    for (const file of input.files) {
+        if (lockFiles.has(file.relativePath)) {
+            evidenceItems.push(evidence(file.relativePath, 'lockfile-not-copied', 'Lockfile content is excluded from the rehearsal directory; its source hash remains available in snapshots.'));
+            continue;
+        }
+        const safeText = safeMetadataText(file.relativePath, file.text);
+        if (safeText === undefined) {
+            evidenceItems.push(evidence(file.relativePath, 'metadata-not-copied', 'Metadata was not copied because it could not be safely parsed.'));
+            continue;
+        }
+        await writeFile(join(directory, file.relativePath), safeText, { encoding: 'utf8', flag: 'wx' });
+    }
+}
+function runtimeForTarget(model, targetDsh) {
+    const runtime = {
+        ...(model.runtime ?? {}),
+        dsh: targetDsh,
+        node: model.runtime?.node ?? process.versions.node,
+        platform: model.runtime?.platform ?? process.platform
+    };
+    return { ...model, runtime };
+}
+function outcomeFor(smoke, diagnostics, extraWarning) {
+    if (smoke === 'fail' || diagnostics.some((item) => item.severity === 'error'))
+        return 'fail';
+    if (smoke === 'warning' || extraWarning || diagnostics.some((item) => item.severity === 'warning'))
+        return 'warning';
+    return 'pass';
+}
+/**
+ * Builds a redacted rehearsal profile in the OS temp directory and performs
+ * parse/adapter analysis there. It never invokes a package manager or a
+ * third-party lifecycle; --allow-build is recorded as an explicit plan gate.
+ */
+export async function runPreflight(options) {
+    const requestedProfile = resolve(options.profileDir);
+    const evidenceItems = [];
+    let before;
+    let after;
+    let tempDirectory;
+    let smokeOutcome = 'pass';
+    let smokeDetail = 'No isolated smoke test was run.';
+    let diagnostics = [];
+    let profileDir = requestedProfile;
+    let extraWarning = false;
+    try {
+        if (!versionPattern.test(options.targetDsh)) {
+            evidenceItems.push(evidence(requestedProfile, 'target-dsh-invalid', 'Target DSH version must be an explicit semantic version.', 'error'));
+            return {
+                schemaVersion: 1, outcome: 'fail', profileDir: requestedProfile, targetDsh: options.targetDsh,
+                candidates: [], evidence: evidenceItems, diagnostics, smokeTest: { outcome: 'fail', detail: 'The target DSH version was rejected before rehearsal.' }
+            };
+        }
+        const input = await readProfile({ profileDir: requestedProfile });
+        profileDir = input.profileDir;
+        before = profileFingerprint(input);
+        evidenceItems.push(evidence(profileDir, 'profile-fingerprint-before', `Allow-listed metadata fingerprint recorded: ${before}`));
+        const invalidCandidates = options.candidates.filter((candidate) => !safeCandidate(candidate));
+        if (invalidCandidates.length > 0) {
+            extraWarning = true;
+            evidenceItems.push(evidence(profileDir, 'candidate-validation', `${invalidCandidates.length} candidate value(s) were omitted because they are not a simple package@version reference.`, 'warning'));
+        }
+        const candidates = options.candidates.filter(safeCandidate);
+        evidenceItems.push(evidence(profileDir, 'target-dsh', `Rehearsal target is DSH ${options.targetDsh}.`));
+        evidenceItems.push(evidence(profileDir, 'candidate-plugins', `${candidates.length} validated candidate plugin reference(s) supplied; values are not copied into the real profile.`));
+        evidenceItems.push(evidence(profileDir, 'network-policy', options.online ? 'Online mode was requested, but this adapter performs no network operation.' : 'Offline mode enforced; no network operation was attempted.'));
+        if (options.online)
+            extraWarning = true;
+        tempDirectory = await mkdtemp(join(tmpdir(), 'dsh-doctor-'));
+        await prepareIsolatedProfile(input, tempDirectory, evidenceItems);
+        evidenceItems.push(evidence(tempDirectory, 'isolated-profile', 'Only redacted, allow-listed composition metadata was copied into the temporary profile.'));
+        try {
+            const isolatedInput = await readProfile({ profileDir: tempDirectory });
+            const isolatedModel = runtimeForTarget(await resolveComposition(isolatedInput), options.targetDsh);
+            const report = analyseComposition(isolatedModel);
+            diagnostics = report.diagnostics;
+            const errors = diagnostics.filter((item) => item.severity === 'error').length;
+            const warnings = diagnostics.filter((item) => item.severity === 'warning').length;
+            smokeOutcome = errors > 0 ? 'fail' : warnings > 0 ? 'warning' : 'pass';
+            smokeDetail = `Static composition parse and public-adapter resolution completed in isolation (${errors} error(s), ${warnings} warning(s)).`;
+            evidenceItems.push(evidence(tempDirectory, 'smoke-test', smokeDetail, smokeOutcome === 'fail' ? 'error' : smokeOutcome === 'warning' ? 'warning' : undefined));
+        }
+        catch (error) {
+            smokeOutcome = 'fail';
+            smokeDetail = error instanceof Error ? error.message : String(error);
+            evidenceItems.push(evidence(tempDirectory, 'smoke-test', `Isolated composition smoke test failed: ${smokeDetail}`, 'error'));
+        }
+        evidenceItems.push(evidence(profileDir, 'build-plan', options.allowBuild ? 'Build execution was explicitly allowed, but no public build runner is configured; no third-party lifecycle was invoked.' : 'Build candidates would be rehearsed here only after explicit --allow-build.'));
+        evidenceItems.push(evidence(profileDir, 'build-not-executed', 'No package-manager install or build script was executed by this preflight.', options.allowBuild ? 'warning' : undefined));
+        if (options.allowBuild)
+            extraWarning = true;
+    }
+    catch (error) {
+        smokeOutcome = 'fail';
+        smokeDetail = error instanceof Error ? error.message : String(error);
+        evidenceItems.push(evidence(requestedProfile, 'preflight-error', smokeDetail, 'error'));
+    }
+    finally {
+        try {
+            const afterInput = await readProfile({ profileDir: requestedProfile });
+            after = profileFingerprint(afterInput);
+            const unchanged = before === undefined || before === after;
+            evidenceItems.push(evidence(profileDir, 'profile-unchanged', unchanged ? `Allow-listed metadata fingerprint is unchanged: ${after}` : `Allow-listed metadata fingerprint changed from ${before} to ${after}`, unchanged ? undefined : 'error'));
+            if (!unchanged)
+                smokeOutcome = 'fail';
+        }
+        catch (error) {
+            smokeOutcome = 'fail';
+            evidenceItems.push(evidence(requestedProfile, 'profile-fingerprint-after', `Could not verify the selected profile after rehearsal: ${error instanceof Error ? error.message : String(error)}`, 'error'));
+        }
+        if (tempDirectory !== undefined && !options.keepTemp) {
+            await rm(tempDirectory, { recursive: true, force: true });
+            evidenceItems.push(evidence(tempDirectory, 'temp-cleanup', 'Temporary rehearsal directory was removed.'));
+            tempDirectory = undefined;
+        }
+    }
+    const outcome = outcomeFor(smokeOutcome, diagnostics, extraWarning);
+    return {
+        schemaVersion: 1,
+        outcome,
+        profileDir,
+        targetDsh: options.targetDsh,
+        candidates: options.candidates.filter(safeCandidate),
+        evidence: evidenceItems,
+        diagnostics,
+        smokeTest: { outcome: smokeOutcome, detail: smokeDetail },
+        ...(before === undefined ? {} : { realProfileFingerprintBefore: before }),
+        ...(after === undefined ? {} : { realProfileFingerprintAfter: after }),
+        ...(tempDirectory === undefined ? {} : { tempDirectory })
+    };
+}

package/dist/core/profile-reader.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+const allowedFiles = [
+    'cordis.yml',
+    'cordis.patch.yml',
+    'package.json',
+    'pnpm-lock.yaml',
+    'package-lock.json',
+    'yarn.lock'
+];
+export class ProfileDirectoryError extends Error {
+    code = 'PROFILE_DIRECTORY_INVALID';
+    constructor(profileDir, reason) {
+        super(`Profile directory ${reason}: ${profileDir}`);
+        this.name = 'ProfileDirectoryError';
+    }
+}
+export async function readProfile({ profileDir }) {
+    const requestedRoot = resolve(profileDir);
+    let rootStats;
+    try {
+        rootStats = await stat(requestedRoot);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new ProfileDirectoryError(profileDir, 'missing');
+        }
+        throw error;
+    }
+    if (!rootStats.isDirectory()) {
+        throw new ProfileDirectoryError(profileDir, 'not-directory');
+    }
+    const resolvedRoot = await realpath(requestedRoot);
+    const files = [];
+    for (const relativePath of allowedFiles) {
+        const candidate = resolve(requestedRoot, relativePath);
+        try {
+            const candidateStats = await lstat(candidate);
+            if (candidateStats.isSymbolicLink() || !candidateStats.isFile())
+                continue;
+            const text = await readFile(candidate, 'utf8');
+            files.push({
+                relativePath,
+                sha256: createHash('sha256').update(text, 'utf8').digest('hex'),
+                text
+            });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+    }
+    return { profileDir: resolvedRoot, files };
+}

package/dist/core/redaction.js

@@ -0,0 +1,25 @@
+const secretProperty = /key|token|secret|password|credential|authorization/i;
+export function redact(value) {
+    const seen = new WeakMap();
+    const visit = (current) => {
+        if (current === null || typeof current !== 'object')
+            return current;
+        const existing = seen.get(current);
+        if (existing !== undefined)
+            return existing;
+        if (Array.isArray(current)) {
+            const copy = [];
+            seen.set(current, copy);
+            for (const item of current)
+                copy.push(visit(item));
+            return copy;
+        }
+        const copy = {};
+        seen.set(current, copy);
+        for (const property of Object.keys(current)) {
+            copy[property] = secretProperty.test(property) ? '[REDACTED]' : visit(current[property]);
+        }
+        return copy;
+    };
+    return visit(value);
+}

package/dist/core/rules.js

@@ -0,0 +1,110 @@
+import { satisfies as semverSatisfies } from 'semver';
+function evidence(source, subject, detail, evidenceKind, packageName, version) {
+    return { source, subject, detail, evidenceKind, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) };
+}
+function diagnostic(id, severity, title, items, explanation, remediation) {
+    return { id, severity, title, evidence: [...items], explanation, remediation };
+}
+function groups(values, key) {
+    const result = new Map();
+    for (const value of values) {
+        const groupKey = key(value);
+        const group = result.get(groupKey);
+        if (group === undefined)
+            result.set(groupKey, [value]);
+        else
+            group.push(value);
+    }
+    return result;
+}
+function parseVersion(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(value);
+    return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+/**
+ * Evaluate a package-manager semver range without any network access. The
+ * includePrerelease option matters for the verified DSH preview range.
+ */
+function satisfiesRange(version, range) {
+    if (parseVersion(version) === undefined || range.trim().length === 0)
+        return undefined;
+    try {
+        return semverSatisfies(version, range, { includePrerelease: true });
+    }
+    catch {
+        return undefined;
+    }
+}
+function patchEvidence(write) {
+    return evidence(write.source, write.path, `patch write to ${write.path}`, write.evidenceKind, write.packageName, write.version);
+}
+function peerDiagnostics(model) {
+    const diagnostics = [];
+    const runtime = model.runtime ?? {};
+    for (const peer of model.peerRequirements ?? []) {
+        for (const [fact, range] of [['dsh', peer.dsh], ['cordis', peer.cordis], ['node', peer.node]]) {
+            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);
+            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;
+            }
+            if (satisfiesRange(actual, range) === false) {
+                diagnostics.push(diagnostic('peer-version-mismatch', 'warning', 'Declared peer range does not match runtime fact', [item], `${peer.packageName} declares ${fact} ${range}, but the supplied runtime fact is ${actual}. Static analysis cannot prove the runtime load outcome.`, `Use a ${fact} version within ${range}, or update the package peer declaration after testing the supported combination.`));
+            }
+            else if (satisfiesRange(actual, range) === undefined) {
+                diagnostics.push(diagnostic('peer-range-unrecognized', 'warning', 'Peer dependency range could not be evaluated', [item], `The declared ${fact} range ${range} is not understood by the offline semver adapter, so compatibility is unproven.`, `Verify ${peer.packageName} against ${fact} ${actual} using the package manager's resolver.`));
+            }
+        }
+    }
+    return diagnostics;
+}
+function bundleDiagnostics(bundles) {
+    const diagnostics = [];
+    for (const bundle of bundles) {
+        if (bundle.gitRef !== undefined && bundle.gitRef.length > 0)
+            continue;
+        diagnostics.push(diagnostic('missing-provenance', 'warning', 'Bundle provenance is unavailable', [evidence(bundle.source, bundle.name, 'No Git ref or immutable provenance was declared.', bundle.evidenceKind, bundle.name, bundle.version)], `The origin of ${bundle.name} cannot be verified from the selected metadata.`, 'Record an immutable Git ref, registry integrity hash, or other package provenance in the selected profile metadata.'));
+    }
+    for (const [name, group] of groups(bundles.filter((bundle) => bundle.profile !== undefined), (bundle) => bundle.name)) {
+        if (new Set(group.map((bundle) => bundle.version ?? 'unknown')).size < 2)
+            continue;
+        diagnostics.push(diagnostic('cross-profile-bundle-drift', 'warning', 'Bundle versions drift across profiles', group.map((bundle) => evidence(bundle.source, name, `profile ${bundle.profile ?? 'unknown'} declares ${bundle.version ?? 'unknown'}`, bundle.evidenceKind, bundle.name, bundle.version)), `${name} has different declared versions across compared profile metadata.`, 'Align the intended bundle version, or keep the profiles intentionally divergent and document why.'));
+    }
+    return diagnostics;
+}
+export function analyseComposition(model) {
+    const diagnostics = [...model.adapterDiagnostics];
+    for (const [id, rows] of groups(model.rows.filter((row) => row.id !== undefined), (row) => row.id)) {
+        if (rows.length < 2)
+            continue;
+        diagnostics.push(diagnostic('duplicate-row-id', 'error', 'Duplicate composition row id', rows.map((row) => evidence(row.source, id, `row id ${id}`, row.evidenceKind, row.name)), `Multiple concrete composition rows claim the id ${id}.`, 'Give one row a unique id or remove the duplicate declaration.'));
+    }
+    for (const [claim, values] of groups(model.uiClaims ?? [], (value) => `${value.kind}:${value.value}`)) {
+        if (values.length < 2)
+            continue;
+        diagnostics.push(diagnostic('ui-ownership-conflict', 'error', 'Duplicate UI ownership claim', values.map((value) => evidence(value.source, claim, `${value.kind} ${value.value}`, value.evidenceKind, value.packageName, value.version)), `Multiple concrete declarations claim the same ${claim} UI surface.`, 'Assign the UI surface to one package or give each declaration a distinct slot, layout, sidebar entry, or route.'));
+    }
+    for (const [hook, values] of groups((model.hooks ?? []).filter((value) => value.hook === 'tools/pre-execute' || value.hook === 'tools/execute' || value.hook === 'tools/post-execute'), (value) => value.hook)) {
+        if (values.length < 2)
+            continue;
+        diagnostics.push(diagnostic('hook-order-risk', 'warning', 'Multiple tool waterfall registrations', values.map((value) => evidence(value.source, hook, `registered ${hook}`, value.evidenceKind, value.packageName, value.version)), `Multiple listeners register ${hook}; static metadata does not establish their runtime order.`, 'Declare explicit ordering where the public DSH API supports it, then verify the resolved hook order in an isolated fixture.'));
+    }
+    for (const [path, writes] of groups(model.patchWrites ?? [], (write) => write.path)) {
+        if (writes.length < 2)
+            continue;
+        diagnostics.push(diagnostic('patch-field-overlap', 'warning', 'Patch fields overlap', writes.map(patchEvidence), `Multiple patches write ${path}; the winning value depends on resolution order not established by static evidence.`, 'Merge the writes into one owner or document and verify the intentional precedence.'));
+    }
+    diagnostics.push(...peerDiagnostics(model), ...bundleDiagnostics(model.bundles ?? []));
+    const platform = model.runtime?.platform;
+    for (const requirement of model.platforms ?? []) {
+        const item = evidence(requirement.source, requirement.packageName, `supports ${requirement.supported.join(', ')}; observed ${platform ?? 'unknown'}`, requirement.evidenceKind, requirement.packageName);
+        if (platform === undefined || !requirement.supported.includes(platform)) {
+            diagnostics.push(diagnostic('platform-mismatch', 'warning', 'Declared platform does not include selected runtime', [item], platform === undefined ? `No runtime platform was supplied for ${requirement.packageName}.` : `${requirement.packageName} declares ${requirement.supported.join(', ')}, not ${platform}.`, 'Use a supported platform or verify an intentional override in an isolated fixture.'));
+        }
+    }
+    diagnostics.sort((left, right) => left.id.localeCompare(right.id) || left.title.localeCompare(right.title) || left.evidence[0]?.source.localeCompare(right.evidence[0]?.source ?? '') || 0);
+    return { schemaVersion: 1, generatedAt: new Date().toISOString(), profileDir: model.profileDir, diagnostics };
+}

package/dist/core/snapshot.js

@@ -0,0 +1,59 @@
+import { resolveComposition } from './composition-adapter.js';
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function stringMap(value) {
+    if (!isRecord(value))
+        return [];
+    return Object.entries(value).flatMap(([name, version]) => typeof version === 'string' ? [[name, version]] : []);
+}
+function sortBySource(values) {
+    return [...values].sort((left, right) => left.source.localeCompare(right.source) || JSON.stringify(left).localeCompare(JSON.stringify(right)));
+}
+function manifestSnapshot(input) {
+    const file = input.files.find((candidate) => candidate.relativePath === 'package.json');
+    if (file === undefined)
+        return { plugins: [], peers: [], platforms: [] };
+    try {
+        const manifest = JSON.parse(file.text);
+        const packageName = typeof manifest.name === 'string' ? manifest.name : undefined;
+        const plugins = [...stringMap(manifest.dependencies), ...stringMap(manifest.devDependencies)]
+            .map(([name, version]) => ({ name, version, source: file.relativePath }))
+            .sort((left, right) => left.name.localeCompare(right.name) || left.version.localeCompare(right.version));
+        const peers = packageName === undefined ? [] : [{
+                packageName,
+                source: file.relativePath,
+                ...Object.fromEntries(stringMap(manifest.peerDependencies).filter(([name]) => name === '@deepseek-ai/dsh' || name === '@deepseek-ai/cordis' || name === 'node').map(([name, range]) => [name === '@deepseek-ai/dsh' ? 'dsh' : name === '@deepseek-ai/cordis' ? 'cordis' : 'node', range]))
+            }];
+        const platforms = packageName === undefined || !Array.isArray(manifest.os) ? [] : [{ packageName, source: file.relativePath, supported: manifest.os.filter((platform) => typeof platform === 'string').sort() }];
+        return { ...(packageName === undefined ? {} : { packageName }), plugins, peers, platforms };
+    }
+    catch {
+        return { plugins: [], peers: [], platforms: [] };
+    }
+}
+function snapshotFromModel(model, profile, hashes, plugins = []) {
+    return {
+        schemaVersion: 1,
+        profile,
+        plugins: [...plugins].sort((left, right) => left.name.localeCompare(right.name) || (left.version ?? '').localeCompare(right.version ?? '')),
+        rows: model.rows.map(({ id, name, source }) => ({ ...(id === undefined ? {} : { id }), ...(name === undefined ? {} : { name }), source })).sort((left, right) => left.source.localeCompare(right.source) || (left.id ?? '').localeCompare(right.id ?? '')),
+        hooks: sortBySource((model.hooks ?? []).map(({ hook, source, packageName, version }) => ({ hook, source, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) }))),
+        uiClaims: sortBySource((model.uiClaims ?? []).map(({ kind, value, source, packageName, version }) => ({ kind, value, source, ...(packageName === undefined ? {} : { packageName }), ...(version === undefined ? {} : { version }) }))),
+        peers: sortBySource((model.peerRequirements ?? []).map(({ packageName, source, dsh, cordis, node }) => ({ packageName, source, ...(dsh === undefined ? {} : { dsh }), ...(cordis === undefined ? {} : { cordis }), ...(node === undefined ? {} : { node }) }))),
+        platforms: sortBySource((model.platforms ?? []).map(({ packageName, source, supported }) => ({ packageName, source, supported: [...supported].sort() }))),
+        bundles: sortBySource((model.bundles ?? []).map(({ name, version, source, gitRef, profile: bundleProfile }) => ({ name, source, ...(version === undefined ? {} : { version }), ...(gitRef === undefined ? {} : { gitRef }), ...(bundleProfile === undefined ? {} : { profile: bundleProfile }) }))),
+        hashes
+    };
+}
+/** Creates a structural, redacted snapshot from already allow-listed profile input or a resolved model. */
+export async function createSnapshot(input) {
+    if ('files' in input) {
+        const manifest = manifestSnapshot(input);
+        const hashes = Object.fromEntries(input.files
+            .filter((file) => file.relativePath === 'package.json' || file.relativePath === 'pnpm-lock.yaml' || file.relativePath === 'package-lock.json' || file.relativePath === 'yarn.lock')
+            .map((file) => [file.relativePath, file.sha256]));
+        return snapshotFromModel(await resolveComposition(input), { path: input.profileDir, ...(manifest.packageName === undefined ? {} : { packageName: manifest.packageName }) }, hashes, manifest.plugins);
+    }
+    return snapshotFromModel(input, { path: input.profileDir }, {}, input.bundles?.map(({ name, version, source }) => ({ name, source, ...(version === undefined ? {} : { version }) })) ?? []);
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugin/index.js

@@ -0,0 +1,75 @@
+import { lstat, readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+export const name = 'dsh-composition-doctor';
+/** Public Cordis service dependency supplied by dsh-host-webserver. */
+export const inject = ['webServer'];
+export const Config = z.object({ reportDir: z.string() });
+export const latestReportPath = '/dsh-composition-doctor/reports/latest';
+function reportDirectory(config) {
+    return resolve(config.reportDir ?? '.dsh-composition-doctor/reports');
+}
+function send(response, status, body) {
+    response.statusCode = status;
+    response.setHeader('Content-Type', 'application/json; charset=utf-8');
+    response.setHeader('Cache-Control', 'no-store');
+    response.end(body);
+}
+async function latestReport(config) {
+    const directory = reportDirectory(config);
+    try {
+        const directoryStat = await lstat(directory);
+        if (!directoryStat.isDirectory())
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    // The CLI writes report.json. latest.json is accepted for integrations that
+    // copy a report into the plugin-owned directory under that conventional name.
+    for (const filename of ['report.json', 'latest.json']) {
+        try {
+            const candidate = resolve(directory, filename);
+            const fileStat = await lstat(candidate);
+            if (!fileStat.isFile())
+                continue;
+            const text = await readFile(candidate, 'utf8');
+            JSON.parse(text);
+            return text.endsWith('\n') ? text : `${text}\n`;
+        }
+        catch {
+            // A missing or malformed report is represented as 404 below. Details are
+            // not sent to the browser, so local paths and parser errors cannot leak.
+        }
+    }
+    return undefined;
+}
+function route(config) {
+    return {
+        kind: 'exact',
+        path: latestReportPath,
+        method: 'GET',
+        async handler(request, response) {
+            if (request.method !== undefined && request.method.toUpperCase() !== 'GET') {
+                response.statusCode = 405;
+                response.setHeader('Allow', 'GET');
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.end('{"error":"method_not_allowed"}\n');
+                return;
+            }
+            const report = await latestReport(config);
+            if (report === undefined) {
+                send(response, 404, '{"error":"latest_report_not_found"}\n');
+                return;
+            }
+            send(response, 200, report);
+        }
+    };
+}
+/** Registers the one read-only report route inside a Cordis effect scope. */
+export function apply(ctx, config = {}) {
+    if (ctx.webServer === undefined)
+        return undefined;
+    const register = () => ctx.webServer.register(route(config));
+    return ctx.effect === undefined ? register() : ctx.effect(register);
+}

package/dist/reports/json.js

@@ -0,0 +1,3 @@
+export function renderJson(report) {
+    return `${JSON.stringify(report, null, 2)}\n`;
+}

package/dist/reports/markdown.js

@@ -0,0 +1,14 @@
+function formatEvidence(item) {
+    const subject = item.subject === undefined ? '' : ` — ${item.subject}`;
+    const packageLabel = item.packageName === undefined ? '' : ` (${item.packageName}${item.version === undefined ? '' : `@${item.version}`})`;
+    return `- \`${item.source}\`${subject}${packageLabel}: ${item.detail}`;
+}
+function formatDiagnostic(item) {
+    const evidence = item.evidence.length === 0 ? '- No concrete source evidence was supplied.' : item.evidence.map(formatEvidence).join('\n');
+    return `## [${item.severity.toUpperCase()}] ${item.title}\n\n${item.explanation}\n\nEvidence:\n${evidence}\n\nRemediation: ${item.remediation}`;
+}
+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');
+    return `# DSH Composition Doctor Report\n\nSchema: ${report.schemaVersion}\n\nProfile: \`${report.profileDir}\`\n\nGenerated: ${report.generatedAt}\n\nSummary: ${summary}\n\n${body}\n`;
+}