dsh-composition-doctor 0.2.2 → 0.4.0

package/dist/cli/main.js

@@ -1,18 +1,140 @@
+#!/usr/bin/env node
 import { fileURLToPath } from 'node:url';
 import { readFileSync, realpathSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { lstat, mkdir, readFile, realpath, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 import { resolveComposition } from '../core/composition-adapter.js';
 import { diffSnapshots, renderSnapshotDiffMarkdown } from '../core/diff.js';
 import { readProfile } from '../core/profile-reader.js';
 import { createSnapshot, isSnapshotV1, isSnapshotV2 } from '../core/snapshot.js';
 import { analyseComposition } from '../core/rules.js';
+import { compositionBundleImpact, findCompositionRow } from '../core/composition-provenance.js';
 import { renderJson } from '../reports/json.js';
 import { renderMarkdown } from '../reports/markdown.js';
 import { resolveReportDirectory } from '../reports/location.js';
 import { runPreflight } from '../core/preflight.js';
-const usage = 'Usage: dsh-doctor <scan | snapshot | diff | preflight>';
-const commands = new Set(['scan', 'snapshot', 'diff', 'preflight']);
+import { explainFailures, maxFailureLogBytes } from '../core/failure-explainer.js';
+import { readFailureComposition } from '../core/failure-profile.js';
+import { renderFailure } from '../reports/failure.js';
+const usage = 'Usage: dsh-doctor <diagnose | check | scan | snapshot | diff | preflight | why | impact>';
+const commands = new Set(['diagnose', 'check', 'scan', 'snapshot', 'diff', 'preflight', 'why', 'impact']);
+async function stdinLog() {
+    if (process.stdin.isTTY)
+        return undefined;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > maxFailureLogBytes)
+            throw new Error('Log exceeds the 1 MiB limit; provide a minimized error log.');
+        chunks.push(buffer);
+    }
+    return chunks.length === 0 ? undefined : Buffer.concat(chunks).toString('utf8');
+}
+async function fileLog(filename) {
+    const path = await realpath(resolve(filename));
+    if (!/\.(?:log|txt|out)$/i.test(path) || /(?:^|[\\/])(?:\.env[^\\/]*|[^\\/]*(?:credential|token|secret|password)[^\\/]*|sessions?|chats?|workspace)(?:[\\/]|$)/i.test(path)) {
+        throw new Error('--log accepts explicit .log/.txt/.out error logs; secret, session and workspace paths are forbidden.');
+    }
+    const metadata = await lstat(path);
+    if (!metadata.isFile() || metadata.size > maxFailureLogBytes)
+        throw new Error('Log must be a regular file of at most 1 MiB.');
+    const text = await readFile(path, 'utf8');
+    if (Buffer.byteLength(text) > maxFailureLogBytes)
+        throw new Error('Log exceeds the 1 MiB limit.');
+    return text;
+}
+async function diagnose(argv, io, check = false) {
+    if (argv.includes('--help')) {
+        io.write('Usage: dsh-doctor diagnose --profile <dir> [--log <file> | --log -] [--format human|json|markdown|both] [--output <dir>] [--report-dir <dir> | --publish] [--dsh-version <version>] [--composed]\nPiped stdin is detected automatically. Default: read-only static metadata, no DSH execution. check is the same bounded entry point; --profile is required.');
+        return 0;
+    }
+    const valued = new Set(['--profile', '--log', '--format', '--output', '--report-dir', '--dsh-version']);
+    const flags = new Set(['--publish', '--composed']);
+    const seen = new Set();
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if ((!valued.has(value) && !flags.has(value)) || seen.has(value))
+            return invalid(io, 'diagnose has an unknown or repeated option');
+        seen.add(value);
+        if (valued.has(value)) {
+            if (argv[index + 1] === undefined || argv[index + 1].startsWith('--'))
+                return invalid(io, `${value} requires a value`);
+            index += 1;
+        }
+    }
+    const profile = option(argv, '--profile');
+    if (profile === undefined)
+        return invalid(io, `${check ? 'check' : 'diagnose'} requires --profile <dir>; no profile is guessed`);
+    const format = option(argv, '--format') ?? 'human';
+    if (!['human', 'json', 'markdown', 'both'].includes(format))
+        return invalid(io, '--format must be human, json, markdown, or both');
+    const dshVersion = option(argv, '--dsh-version');
+    if (dshVersion !== undefined && !/^\d+\.\d+\.\d+(?:-[a-z0-9.-]+)?(?:\+[a-z0-9.-]+)?$/i.test(dshVersion))
+        return invalid(io, '--dsh-version requires an exact semantic version');
+    let log;
+    const logPath = option(argv, '--log');
+    try {
+        log = logPath !== undefined && logPath !== '-' ? await fileLog(logPath) : await io.readStdin?.();
+    }
+    catch {
+        io.write('Could not read permitted log input. Use a minimized .log/.txt/.out file or stdin, at most 1 MiB; secret/session/workspace paths are forbidden.');
+        return 1;
+    }
+    if (logPath === '-' && log === undefined)
+        return invalid(io, '--log - requires piped input');
+    if (log !== undefined && Buffer.byteLength(log) > maxFailureLogBytes)
+        return invalid(io, 'log exceeds 1 MiB');
+    const input = await readProfile({ profileDir: resolve(profile) });
+    let model = await readFailureComposition(input, argv.includes('--composed'));
+    if (dshVersion !== undefined)
+        model = { ...model, runtime: { ...model.runtime, dsh: dshVersion } };
+    const report = analyseComposition(model);
+    const result = explainFailures({ report, log });
+    report.failureExplanation = result;
+    const output = option(argv, '--output');
+    const reportDir = option(argv, '--report-dir');
+    const destinations = [...(output === undefined ? [] : [resolve(output)]),
+        ...(argv.includes('--publish') || reportDir !== undefined ? [resolveReportDirectory(reportDir)] : [])];
+    // Prevent report output from mutating the selected profile, including symlink parents.
+    for (const directory of destinations) {
+        let parent = directory;
+        let canonical;
+        for (;;) {
+            try {
+                canonical = await realpath(parent);
+                break;
+            }
+            catch {
+                const next = dirname(parent);
+                if (next === parent)
+                    break;
+                parent = next;
+            }
+        }
+        const root = input.profileDir.toLowerCase().replaceAll('\\', '/');
+        const normalized = (canonical ?? directory).toLowerCase().replaceAll('\\', '/');
+        if (normalized === root || normalized.startsWith(`${root}/`))
+            return invalid(io, 'diagnose output/report directory must be outside the selected profile');
+    }
+    for (const directory of new Set(destinations)) {
+        await mkdir(directory, { recursive: true });
+        for (const filename of ['report.json', 'report.md']) {
+            try {
+                const metadata = await lstat(resolve(directory, filename));
+                if (metadata.isSymbolicLink() || metadata.nlink > 1)
+                    return invalid(io, 'report destination must not be a symbolic or hard link');
+            }
+            catch { /* new file */ }
+        }
+        await writeFile(resolve(directory, 'report.json'), renderJson(report), 'utf8');
+        await writeFile(resolve(directory, 'report.md'), renderFailure(result, true), 'utf8');
+    }
+    io.write(format === 'json' ? `${JSON.stringify(result, null, 2)}\n` : format === 'both'
+        ? `${JSON.stringify(result, null, 2)}\n${renderFailure(result, true)}` : renderFailure(result, format === 'markdown'));
+    return 0;
+}
 function packageVersion() {
     try {
         const manifest = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf8'));
@@ -146,7 +268,69 @@ async function preflight(argv, io) {
     }
     return result.outcome === 'fail' ? 1 : 0;
 }
-export async function runCli(argv, io = { write: (line) => console.log(line) }) {
+async function why(argv, io) {
+    if (argv[0] !== 'row' || argv[1] === undefined || argv[1].startsWith('--'))
+        return invalid(io, 'why requires: why row <id> --profile <dir>');
+    const profile = option(argv, '--profile');
+    if (profile === undefined)
+        return invalid(io, 'why row requires --profile');
+    const model = await resolveComposition(await readProfile({ profileDir: resolve(profile) }));
+    const report = analyseComposition(model);
+    const row = findCompositionRow(report.compositionFacts, argv[1]);
+    if (row === undefined) {
+        io.write(`${JSON.stringify({ schemaVersion: 1, query: { entity: 'row', id: argv[1] }, outcome: 'not-found', evidenceMode: report.evidenceMode, unknown: ['No row with this id was present in the selected profile evidence.'] }, null, 2)}\n`);
+        return 0;
+    }
+    const relatedDiagnostics = report.diagnostics.filter((item) => row.relatedDiagnosticIds.includes(item.id));
+    const unknown = [...row.unknown];
+    if (row.replacement.state === 'yes' && row.removedConfigKeys === undefined)
+        unknown.push('removed config keys are unknown; prior layer config was not fully observed');
+    io.write(`${JSON.stringify({
+        schemaVersion: 1,
+        query: { entity: 'row', id: argv[1] },
+        outcome: 'found',
+        evidenceMode: report.evidenceMode,
+        row: {
+            id: row.id,
+            ...(row.name === undefined ? {} : { name: row.name }),
+            effectiveObservedStructure: { configKeys: row.configKeys, values: 'not included; values may contain sensitive or runtime-dependent data' },
+            source: row.source,
+            sourceBasis: row.sourceBasis,
+            ...(row.layer === undefined ? {} : { layer: row.layer }),
+            ...(row.layerOrder === undefined ? {} : { layerOrder: row.layerOrder }),
+            provenance: row.provenance,
+            replacement: row.replacement,
+            configKeysBasis: row.configKeysBasis,
+            ...(row.removedConfigKeys === undefined ? {} : { removedConfigKeys: row.removedConfigKeys }),
+            ...(row.packageName === undefined ? {} : { package: { name: row.packageName, ...(row.packageVersion === undefined ? {} : { version: row.packageVersion }) } }),
+            evidenceMode: row.evidenceMode
+        },
+        relatedDiagnostics,
+        unknown: [...new Set(unknown)].sort()
+    }, null, 2)}\n`);
+    return 0;
+}
+async function impact(argv, io) {
+    if (argv[0] !== 'bundle' || argv[1] === undefined || argv[1].startsWith('--'))
+        return invalid(io, 'impact requires: impact bundle <name> --profile <dir>');
+    const profile = option(argv, '--profile');
+    if (profile === undefined)
+        return invalid(io, 'impact bundle requires --profile');
+    const model = await resolveComposition(await readProfile({ profileDir: resolve(profile) }));
+    const report = analyseComposition(model);
+    const result = compositionBundleImpact(report, argv[1]);
+    const known = report.compositionFacts?.nodes.some((node) => node.entity === 'bundle' && node.label === argv[1]) === true;
+    io.write(`${JSON.stringify({
+        ...result,
+        outcome: known ? (result.rows.length > 0 ? 'observed-contributions' : 'no-observable-rows') : 'bundle-not-observed',
+        observed: known,
+        patchContributions: result.rows.filter((row) => row.provenance.some((item) => item.source === argv[1] && item.relation === 'patched-by')),
+        overrides: result.rows.filter((row) => row.replacement.state === 'yes' && row.provenance.some((item) => item.source === argv[1] && item.relation === 'patched-by')),
+        unknown: [...new Set(result.unknown)]
+    }, null, 2)}\n`);
+    return 0;
+}
+export async function runCli(argv, io = { write: (line) => console.log(line), readStdin: stdinLog }) {
     const command = argv[0];
     if (argv.length === 0 || command === '--help') {
         io.write(usage);
@@ -161,15 +345,25 @@ export async function runCli(argv, io = { write: (line) => console.log(line) })
         return 2;
     }
     try {
+        if (command === 'diagnose' || command === 'check')
+            return await diagnose(argv.slice(1), io, command === 'check');
         if (command === 'scan')
             return await scan(argv.slice(1), io);
         if (command === 'snapshot')
             return await snapshot(argv.slice(1), io);
         if (command === 'diff')
             return await diff(argv.slice(1), io);
-        return await preflight(argv.slice(1), io);
+        if (command === 'preflight')
+            return await preflight(argv.slice(1), io);
+        if (command === 'why')
+            return await why(argv.slice(1), io);
+        return await impact(argv.slice(1), io);
     }
     catch (error) {
+        if (command === 'diagnose' || command === 'check') {
+            io.write('Could not inspect selected profile metadata. Check --profile directory, metadata syntax and file access.');
+            return 1;
+        }
         io.write(error instanceof Error ? error.message : String(error));
         return 1;
     }

package/dist/client/report-view.js

@@ -35,7 +35,55 @@ export function toReportViewModel(report) {
     const counts = { info: 0, warning: 0, error: 0 };
     for (const diagnostic of report.diagnostics)
         counts[diagnostic.severity] += 1;
-    return { report, counts, graph: buildConflictGraph(report) };
+    return {
+        report, counts, graph: buildConflictGraph(report),
+        compositionGraph: { nodes: report.compositionFacts?.nodes ?? [], edges: report.compositionFacts?.edges ?? [] }
+    };
+}
+export function compositionNodeDetail(report, nodeId) {
+    const facts = report.compositionFacts;
+    const node = facts?.nodes.find((candidate) => candidate.id === nodeId);
+    if (facts === undefined || node === undefined)
+        return undefined;
+    const relatedRows = facts.rows.filter((candidate) => {
+        if (node.rowKey !== undefined)
+            return candidate.key === node.rowKey;
+        if (node.entity === 'bundle')
+            return candidate.packageName === node.packageName || candidate.provenance.some((step) => step.source === node.label);
+        if (node.entity === 'source')
+            return candidate.source === node.source || candidate.provenance.some((step) => step.source === node.source);
+        if (node.entity === 'layer')
+            return candidate.layer === node.layer && (node.layerOrder === undefined || candidate.layerOrder === node.layerOrder);
+        if (node.entity === 'diagnostic')
+            return node.diagnosticId !== undefined && candidate.relatedDiagnosticIds.includes(node.diagnosticId);
+        return false;
+    });
+    const fields = [
+        { label: 'entity', value: node.entity },
+        { label: 'source', value: node.source ?? node.label },
+        { label: 'evidence', value: node.evidenceMode ?? 'unknown' }
+    ];
+    if (node.layer !== undefined)
+        fields.push({ label: 'layer', value: node.layer });
+    if (node.layerOrder !== undefined)
+        fields.push({ label: 'layer order', value: String(node.layerOrder) });
+    if (node.packageName !== undefined)
+        fields.push({ label: 'package', value: `${node.packageName}${node.packageVersion === undefined ? '' : `@${node.packageVersion}`}` });
+    if (relatedRows.length > 0) {
+        fields.push({ label: 'related rows', value: relatedRows.map((row) => row.id ?? row.name ?? row.key).join(', ') });
+        fields.push({ label: 'config keys', value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.configKeys.length === 0 ? '(none observed)' : row.configKeys.join(', ')}`).join('\n') });
+        fields.push({ label: 'replacement', value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.replacement.state} (${row.replacement.basis})`).join('\n') });
+        fields.push({ label: 'provenance', value: relatedRows.map((row) => `${row.id ?? row.key}: ${row.provenance.length === 0 ? 'unknown' : row.provenance.map((item) => `${item.relation}: ${item.source} (${item.basis})`).join(' → ')}`).join('\n') });
+    }
+    const relatedDiagnosticIds = new Set(relatedRows.flatMap((row) => row.relatedDiagnosticIds));
+    const rowDiagnostics = report.diagnostics.filter((item) => relatedDiagnosticIds.has(item.id));
+    const nodeDiagnostic = node.diagnosticId === undefined ? [] : report.diagnostics.filter((item) => item.id === node.diagnosticId);
+    return {
+        title: node.label,
+        fields,
+        diagnostics: [...new Map([...rowDiagnostics, ...nodeDiagnostic].map((item) => [item.id, item])).values()],
+        unknown: [...new Set([...relatedRows.flatMap((row) => row.unknown), ...facts.unknownSurfaces])]
+    };
 }
 function renderConflictGraph(document, graph) {
     const section = document.createElement('section');
@@ -59,6 +107,141 @@ function renderConflictGraph(document, graph) {
     section.append(list);
     return section;
 }
+export function createFailureExplanation(document, report) {
+    const section = document.createElement('section');
+    section.dataset.failureExplanation = 'true';
+    const heading = document.createElement('h3');
+    heading.textContent = 'Failure Explanation';
+    section.append(heading);
+    const result = report.failureExplanation;
+    if (result === undefined) {
+        const message = document.createElement('p');
+        message.textContent = 'No failure explanation in this report. Run dsh-doctor diagnose --profile <dir> --report-dir <doctor-reports> to create one.';
+        section.append(message);
+        return section;
+    }
+    const status = document.createElement('p');
+    status.textContent = `Outcome: ${result.outcome}; runtime: ${result.runtime}. Log signatures are reported claims, not composition evidence.`;
+    section.append(status);
+    for (const explanation of result.explanations) {
+        const details = document.createElement('details');
+        const summary = document.createElement('summary');
+        summary.textContent = `${explanation.detectedFailure} (${explanation.origin}; ${explanation.evidenceLevel})`;
+        const cause = document.createElement('p');
+        cause.textContent = explanation.observableCause;
+        const paths = document.createElement('pre');
+        paths.textContent = explanation.provenancePaths.map((path) => `${path.packageName ?? 'profile'} → ${path.source} → ${path.layer ?? 'unknown layer'} → ${path.rowId ?? 'unknown row'}\n${path.provenance.map((step) => `${step.relation}: ${step.source} (${step.basis})`).join(' → ')}`).join('\n\n');
+        const unknown = document.createElement('p');
+        unknown.textContent = `Unknown: ${explanation.unknowns.join(' ')}`;
+        const diagnostics = document.createElement('p');
+        diagnostics.textContent = `Related diagnostics: ${explanation.relatedDiagnostics.map((item) => item.id).join(', ') || 'none observed'}`;
+        const remediation = document.createElement('p');
+        remediation.textContent = `Manual next step: ${explanation.manualRemediation}`;
+        details.append(summary, cause, paths, diagnostics, unknown, remediation);
+        section.append(details);
+    }
+    const next = document.createElement('p');
+    next.textContent = `${result.nextStep} Doctor did not modify your profile.`;
+    section.append(next);
+    return section;
+}
+export function createCompositionExplorer(document, report) {
+    const section = document.createElement('section');
+    section.setAttribute('aria-labelledby', 'dsh-composition-doctor-explorer');
+    const heading = document.createElement('h3');
+    heading.id = 'dsh-composition-doctor-explorer';
+    heading.textContent = 'Composition Explorer';
+    section.append(heading);
+    const facts = report.compositionFacts;
+    const graph = facts === undefined ? { nodes: [], edges: [] } : { nodes: facts.nodes, edges: facts.edges };
+    if (graph.nodes.length === 0) {
+        const message = document.createElement('p');
+        message.textContent = 'Composition provenance is unavailable in this legacy report.';
+        section.append(message);
+    }
+    else {
+        const list = document.createElement('ul');
+        for (const node of graph.nodes.filter((value) => value.entity !== 'diagnostic')) {
+            const item = document.createElement('li');
+            const select = button(document, `${node.entity}: ${node.label}`, () => {
+                const detail = compositionNodeDetail(report, node.id);
+                if (detail === undefined)
+                    return;
+                const panel = section.querySelector('[data-composition-detail]');
+                if (panel === null)
+                    return;
+                panel.replaceChildren();
+                const title = document.createElement('h4');
+                title.textContent = detail.title;
+                panel.append(title);
+                const fields = document.createElement('dl');
+                for (const field of detail.fields) {
+                    const term = document.createElement('dt');
+                    term.textContent = field.label;
+                    const value = document.createElement('dd');
+                    value.textContent = field.value;
+                    fields.append(term, value);
+                }
+                panel.append(fields);
+                const diagnostics = document.createElement('ul');
+                for (const diagnostic of detail.diagnostics) {
+                    const entry = document.createElement('li');
+                    entry.textContent = `[${diagnostic.severity}] ${diagnostic.title}: ${diagnostic.explanation}`;
+                    diagnostics.append(entry);
+                }
+                if (detail.diagnostics.length > 0)
+                    panel.append(diagnostics);
+                const unknown = document.createElement('ul');
+                for (const value of detail.unknown) {
+                    const entry = document.createElement('li');
+                    entry.textContent = value;
+                    unknown.append(entry);
+                }
+                if (detail.unknown.length > 0) {
+                    const unknownTitle = document.createElement('h4');
+                    unknownTitle.textContent = 'Unknown / not modelled';
+                    panel.append(unknownTitle, unknown);
+                }
+            });
+            select.dataset.compositionNode = node.id;
+            if (report.failureExplanation?.explanations.some((item) => item.provenancePaths.some((path) => path.rowKey === node.rowKey && node.rowKey !== undefined || path.packageName === node.packageName && node.packageName !== undefined))) {
+                select.dataset.failureRelated = 'true';
+                select.textContent = `${node.entity}: ${node.label} [failure evidence]`;
+            }
+            item.append(select);
+            const outgoing = graph.edges.filter((edge) => edge.from === node.id);
+            if (outgoing.length > 0) {
+                const relationships = document.createElement('ul');
+                for (const edge of outgoing) {
+                    const target = graph.nodes.find((candidate) => candidate.id === edge.to);
+                    if (target === undefined || target.entity === 'diagnostic')
+                        continue;
+                    const relationship = document.createElement('li');
+                    relationship.textContent = `${edge.relation} → ${target.label} (${edge.basis}; ${edge.evidenceMode})`;
+                    relationships.append(relationship);
+                }
+                item.append(relationships);
+            }
+            list.append(item);
+        }
+        section.append(list);
+        const detail = document.createElement('section');
+        detail.dataset.compositionDetail = 'true';
+        detail.setAttribute('aria-live', 'polite');
+        detail.textContent = 'Select a bundle, source, layer, or row to inspect its evidence.';
+        section.append(detail);
+        const unknownList = document.createElement('ul');
+        for (const value of facts?.unknownSurfaces ?? []) {
+            const entry = document.createElement('li');
+            entry.textContent = value;
+            unknownList.append(entry);
+        }
+        const unknownTitle = document.createElement('h4');
+        unknownTitle.textContent = 'Other surfaces';
+        section.append(unknownTitle, unknownList);
+    }
+    return section;
+}
 function isReport(value) {
     if (value === null || typeof value !== 'object')
         return false;
@@ -145,6 +328,8 @@ export function createReportView(document = globalThis.document, translate = (ke
         status.textContent = `Generated: ${report.generatedAt}. Profile: ${report.profileDir}. Diagnostics: ${model.counts.error} error, ${model.counts.warning} warning, ${model.counts.info} info.`;
         status.append(document.createTextNode(' '), badge);
         root.append(renderConflictGraph(document, model.graph));
+        root.append(createFailureExplanation(document, report));
+        root.append(createCompositionExplorer(document, report));
         const list = document.createElement('ul');
         for (const diagnostic of report.diagnostics) {
             const item = document.createElement('li');