@shrkcrft/inspector 0.1.0-alpha.1

package/dist/impact-graph-render.d.ts

@@ -0,0 +1,51 @@
+import type { ImpactGraphFormat } from './impact-graph.js';
+export declare const IMPACT_GRAPH_RENDER_SCHEMA = "sharkcraft.impact-graph-render/v1";
+export interface IImpactGraphRenderResult {
+    schema: typeof IMPACT_GRAPH_RENDER_SCHEMA;
+    format: ImpactGraphFormat;
+    /** Whether the renderer actually produced an SVG. */
+    rendered: boolean;
+    /** Renderer binary used (when `rendered === true`). */
+    renderer: 'mmdc' | 'dot' | null;
+    /** Absolute path to the SVG when rendered. */
+    svgFile: string | null;
+    /** Reason for skipping the render, if any. */
+    reason?: 'renderer-missing' | 'renderer-failed' | 'source-missing' | 'disabled';
+    /** Captured stderr/stdout when the renderer failed (truncated). */
+    stderr?: string;
+}
+interface IRunOptions {
+    /** Override the renderer binary path (test injection). */
+    override?: {
+        mmdc?: string | null;
+        dot?: string | null;
+    };
+    /** Timeout per render in milliseconds. Default: 30s. */
+    timeoutMs?: number;
+}
+export interface IRenderImpactGraphSvgInput {
+    /** Absolute path to the source file (`.mmd` or `.dot`). */
+    sourceFile: string;
+    /** Absolute path where the SVG should be written. */
+    svgFile: string;
+    format: ImpactGraphFormat;
+}
+/**
+ * Render an existing graph source file to SVG. Returns a result struct;
+ * never throws. If the renderer binary is missing, returns
+ * `{ rendered: false, reason: 'renderer-missing' }`.
+ */
+export declare function renderImpactGraphSvg(input: IRenderImpactGraphSvgInput, options?: IRunOptions): Promise<IImpactGraphRenderResult>;
+/**
+ * Write the graph source to disk and then attempt to render it. Convenience
+ * helper for the report-site path where we already have the source body.
+ */
+export declare function writeAndRenderImpactGraph(input: {
+    sourceBody: string;
+    sourceFile: string;
+    svgFile: string;
+    format: ImpactGraphFormat;
+    options?: IRunOptions;
+}): Promise<IImpactGraphRenderResult>;
+export {};
+//# sourceMappingURL=impact-graph-render.d.ts.map

package/dist/impact-graph-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-graph-render.d.ts","sourceRoot":"","sources":["../src/impact-graph-render.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,eAAO,MAAM,0BAA0B,sCAAsC,CAAC;AAE9E,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,MAAM,EAAE,iBAAiB,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAAC;IAChC,8CAA8C;IAC9C,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8CAA8C;IAC9C,MAAM,CAAC,EAAE,kBAAkB,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAChF,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,WAAW;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IACzD,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmCD,MAAM,WAAW,0BAA0B;IACzC,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE,WAAgB,GACxB,OAAO,CAAC,wBAAwB,CAAC,CAyEnC;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAOpC"}

package/dist/impact-graph-render.js

@@ -0,0 +1,139 @@
+/**
+ * Optional static SVG rendering for impact graphs.
+ *
+ * SharkCraft never invokes a renderer unless the user passes
+ * `--render-impact-graphs` / `--render-svg` — and even then the renderer
+ * runs as a local subprocess against locally-generated source files,
+ * never against remote input.
+ *
+ * Supported renderers (best-effort, neither required):
+ * - Mermaid: `mmdc` (mermaid-cli). Reads stdin or a `.mmd` file, writes `.svg`.
+ * - DOT:     `dot` (graphviz). Reads `.dot`, writes `.svg`.
+ *
+ * If the renderer binary is missing, this module degrades gracefully and
+ * returns `{ rendered: false, reason: 'renderer-missing', renderer: null }`
+ * so callers can keep the source-only behaviour.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export const IMPACT_GRAPH_RENDER_SCHEMA = 'sharkcraft.impact-graph-render/v1';
+async function which(binary) {
+    try {
+        const cmd = process.platform === 'win32' ? 'where' : 'which';
+        const result = await execFileAsync(cmd, [binary], { timeout: 5000 });
+        const path = result.stdout.toString().trim().split(/\r?\n/)[0];
+        if (path && path.length > 0)
+            return path;
+    }
+    catch {
+        /* not on PATH */
+    }
+    return null;
+}
+async function resolveRenderer(format, options) {
+    if (format === 'mermaid') {
+        if (options.override?.mmdc === null)
+            return null;
+        if (options.override?.mmdc)
+            return { binary: 'mmdc', path: options.override.mmdc };
+        const path = await which('mmdc');
+        if (path)
+            return { binary: 'mmdc', path };
+        return null;
+    }
+    if (format === 'dot') {
+        if (options.override?.dot === null)
+            return null;
+        if (options.override?.dot)
+            return { binary: 'dot', path: options.override.dot };
+        const path = await which('dot');
+        if (path)
+            return { binary: 'dot', path };
+        return null;
+    }
+    return null;
+}
+/**
+ * Render an existing graph source file to SVG. Returns a result struct;
+ * never throws. If the renderer binary is missing, returns
+ * `{ rendered: false, reason: 'renderer-missing' }`.
+ */
+export async function renderImpactGraphSvg(input, options = {}) {
+    if (!existsSync(input.sourceFile)) {
+        return {
+            schema: IMPACT_GRAPH_RENDER_SCHEMA,
+            format: input.format,
+            rendered: false,
+            renderer: null,
+            svgFile: null,
+            reason: 'source-missing',
+        };
+    }
+    const resolved = await resolveRenderer(input.format, options);
+    if (!resolved) {
+        return {
+            schema: IMPACT_GRAPH_RENDER_SCHEMA,
+            format: input.format,
+            rendered: false,
+            renderer: null,
+            svgFile: null,
+            reason: 'renderer-missing',
+        };
+    }
+    // Make sure the parent directory exists.
+    mkdirSync(nodePath.dirname(input.svgFile), { recursive: true });
+    const timeout = options.timeoutMs ?? 30_000;
+    try {
+        if (resolved.binary === 'mmdc') {
+            // `mmdc -i <in> -o <out>`. We always pass file paths — never stdin —
+            // so the renderer never sees data the user didn't already have on disk.
+            await execFileAsync(resolved.path, ['-i', input.sourceFile, '-o', input.svgFile, '-q'], { timeout });
+        }
+        else {
+            // `dot -Tsvg <in> -o <out>`.
+            await execFileAsync(resolved.path, ['-Tsvg', input.sourceFile, '-o', input.svgFile], { timeout });
+        }
+        if (!existsSync(input.svgFile)) {
+            return {
+                schema: IMPACT_GRAPH_RENDER_SCHEMA,
+                format: input.format,
+                rendered: false,
+                renderer: resolved.binary,
+                svgFile: null,
+                reason: 'renderer-failed',
+            };
+        }
+        return {
+            schema: IMPACT_GRAPH_RENDER_SCHEMA,
+            format: input.format,
+            rendered: true,
+            renderer: resolved.binary,
+            svgFile: input.svgFile,
+        };
+    }
+    catch (e) {
+        const err = e;
+        const stderr = typeof err.stderr === 'string' ? err.stderr : err.stderr?.toString('utf8') ?? err.message;
+        return {
+            schema: IMPACT_GRAPH_RENDER_SCHEMA,
+            format: input.format,
+            rendered: false,
+            renderer: resolved.binary,
+            svgFile: null,
+            reason: 'renderer-failed',
+            stderr: stderr.slice(0, 4000),
+        };
+    }
+}
+/**
+ * Write the graph source to disk and then attempt to render it. Convenience
+ * helper for the report-site path where we already have the source body.
+ */
+export async function writeAndRenderImpactGraph(input) {
+    mkdirSync(nodePath.dirname(input.sourceFile), { recursive: true });
+    writeFileSync(input.sourceFile, input.sourceBody, 'utf8');
+    return renderImpactGraphSvg({ sourceFile: input.sourceFile, svgFile: input.svgFile, format: input.format }, input.options ?? {});
+}

package/dist/impact-graph.d.ts

@@ -0,0 +1,17 @@
+import type { IImpactAnalysis } from './impact-analysis.js';
+export declare const IMPACT_GRAPH_SCHEMA = "sharkcraft.impact-graph/v1";
+export type ImpactGraphFormat = 'mermaid' | 'dot';
+export interface IImpactGraphOptions {
+    /** Max nodes per branch. */
+    width?: number;
+    /** Max depth of the tree. */
+    depth?: number;
+    /** Optional fallback label for the root when the impact has no targets. */
+    rootLabel?: string;
+}
+/** Build a Mermaid flowchart for an impact analysis dependency tree. */
+export declare function renderImpactMermaid(impact: IImpactAnalysis, options?: IImpactGraphOptions): string;
+/** Build a DOT graph for the dependency tree (use with graphviz). */
+export declare function renderImpactDot(impact: IImpactAnalysis, options?: IImpactGraphOptions): string;
+export declare function renderImpactGraph(impact: IImpactAnalysis, format: ImpactGraphFormat, options?: IImpactGraphOptions): string;
+//# sourceMappingURL=impact-graph.d.ts.map

package/dist/impact-graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-graph.d.ts","sourceRoot":"","sources":["../src/impact-graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,KAAK,CAAC;AAElD,MAAM,WAAW,mBAAmB;IAClC,4BAA4B;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA+BD,wEAAwE;AACxE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA4CR;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CA2CR;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,mBAAwB,GAChC,MAAM,CAER"}

package/dist/impact-graph.js

@@ -0,0 +1,119 @@
+import { buildImpactTree } from "./impact-render.js";
+export const IMPACT_GRAPH_SCHEMA = 'sharkcraft.impact-graph/v1';
+function escMermaidLabel(s) {
+    // Mermaid label chars to escape — wrap in quotes for special chars.
+    return s.replace(/"/g, '\\"');
+}
+function escDot(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+function safeId(s, used) {
+    const existing = used.get(s);
+    if (existing)
+        return existing;
+    const slug = `n${used.size}`;
+    used.set(s, slug);
+    return slug;
+}
+function riskClassFor(risk) {
+    switch (risk) {
+        case 'critical':
+            return 'risk-critical';
+        case 'high':
+        case 'medium':
+            return 'risk-warn';
+        default:
+            return 'risk-ok';
+    }
+}
+/** Build a Mermaid flowchart for an impact analysis dependency tree. */
+export function renderImpactMermaid(impact, options = {}) {
+    const treeOpts = {};
+    if (options.width !== undefined)
+        treeOpts.width = options.width;
+    if (options.depth !== undefined)
+        treeOpts.depth = options.depth;
+    const tree = buildImpactTree(impact, treeOpts);
+    const ids = new Map();
+    const lines = [];
+    lines.push('%% Generated by SharkCraft impact-analysis/v2 — Mermaid flowchart.');
+    lines.push('flowchart LR');
+    lines.push('  classDef risk-critical fill:#ffebe9,stroke:#cf222e,color:#cf222e');
+    lines.push('  classDef risk-warn fill:#fff8c5,stroke:#9a6700,color:#9a6700');
+    lines.push('  classDef risk-ok fill:#dafbe1,stroke:#1a7f37,color:#1a7f37');
+    lines.push('  classDef truncated stroke-dasharray: 4 2,color:#57606a');
+    if (tree.length === 0) {
+        const rootId = safeId('__root__', ids);
+        const label = options.rootLabel ?? impact.task ?? '(no targets)';
+        lines.push(`  ${rootId}["${escMermaidLabel(label)}"]`);
+        lines.push(`  class ${rootId} ${riskClassFor(impact.risk)};`);
+        return lines.join('\n') + '\n';
+    }
+    const visit = (node, depth) => {
+        const id = safeId(node.file, ids);
+        lines.push(`  ${id}["${escMermaidLabel(node.file)}"]`);
+        if (depth === 0) {
+            lines.push(`  class ${id} ${riskClassFor(impact.risk)};`);
+        }
+        for (const child of node.children) {
+            const childId = safeId(child.file, ids);
+            lines.push(`  ${id} --> ${childId}`);
+            visit(child, depth + 1);
+        }
+    };
+    for (const root of tree)
+        visit(root, 0);
+    // Truncation note when the analysis flagged truncated transitive list.
+    const truncated = impact.truncations.find((t) => t.list === 'transitiveDependents');
+    if (truncated) {
+        const noteId = safeId('__truncated__', ids);
+        lines.push(`  ${noteId}["… ${truncated.total - truncated.shown} more dependents omitted"]`);
+        lines.push(`  class ${noteId} truncated;`);
+    }
+    return lines.join('\n') + '\n';
+}
+/** Build a DOT graph for the dependency tree (use with graphviz). */
+export function renderImpactDot(impact, options = {}) {
+    const treeOpts = {};
+    if (options.width !== undefined)
+        treeOpts.width = options.width;
+    if (options.depth !== undefined)
+        treeOpts.depth = options.depth;
+    const tree = buildImpactTree(impact, treeOpts);
+    const ids = new Map();
+    const lines = [];
+    lines.push('// Generated by SharkCraft impact-analysis/v2 — Graphviz DOT.');
+    lines.push('digraph ImpactTree {');
+    lines.push('  rankdir=LR;');
+    lines.push('  node [shape=box, style="rounded,filled", fontname="Helvetica"];');
+    const rootColor = impact.risk === 'critical' ? '#ffebe9' : impact.risk === 'high' || impact.risk === 'medium' ? '#fff8c5' : '#dafbe1';
+    if (tree.length === 0) {
+        const id = safeId('__root__', ids);
+        const label = options.rootLabel ?? impact.task ?? '(no targets)';
+        lines.push(`  ${id} [label="${escDot(label)}", fillcolor="${rootColor}"];`);
+        lines.push('}');
+        return lines.join('\n') + '\n';
+    }
+    const visit = (node, depth) => {
+        const id = safeId(node.file, ids);
+        const fill = depth === 0 ? rootColor : '#ffffff';
+        lines.push(`  ${id} [label="${escDot(node.file)}", fillcolor="${fill}"];`);
+        for (const child of node.children) {
+            const childId = safeId(child.file, ids);
+            lines.push(`  ${id} -> ${childId};`);
+            visit(child, depth + 1);
+        }
+    };
+    for (const root of tree)
+        visit(root, 0);
+    const truncated = impact.truncations.find((t) => t.list === 'transitiveDependents');
+    if (truncated) {
+        const noteId = safeId('__truncated__', ids);
+        lines.push(`  ${noteId} [label="… ${truncated.total - truncated.shown} more dependents omitted", style="dashed,filled", fillcolor="#f6f8fa"];`);
+    }
+    lines.push('}');
+    return lines.join('\n') + '\n';
+}
+export function renderImpactGraph(impact, format, options = {}) {
+    return format === 'dot' ? renderImpactDot(impact, options) : renderImpactMermaid(impact, options);
+}

package/dist/impact-render.d.ts

@@ -0,0 +1,22 @@
+import type { IImpactAnalysis } from './impact-analysis.js';
+export interface IImpactRenderOptions {
+    /** When true, include the ASCII / `<details>` dependency tree. */
+    tree?: boolean;
+    /** Max nodes per branch / depth of the tree. */
+    treeDepth?: number;
+    treeWidth?: number;
+}
+interface ITreeNode {
+    file: string;
+    children: ITreeNode[];
+}
+/** Build a small dependency tree rooted at every normalized target. */
+export declare function buildImpactTree(impact: IImpactAnalysis, opts?: {
+    depth?: number;
+    width?: number;
+}): ITreeNode[];
+export declare function renderImpactText(impact: IImpactAnalysis, opts?: IImpactRenderOptions): string;
+export declare function renderImpactMarkdown(impact: IImpactAnalysis, opts?: IImpactRenderOptions): string;
+export declare function renderImpactHtml(impact: IImpactAnalysis, opts?: IImpactRenderOptions): string;
+export {};
+//# sourceMappingURL=impact-render.d.ts.map

package/dist/impact-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"impact-render.d.ts","sourceRoot":"","sources":["../src/impact-render.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,MAAM,WAAW,oBAAoB;IACnC,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6BD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,SAAS,EAAE,CAAC;CACvB;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAC7B,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,SAAS,EAAE,CAiDb;AAiCD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,oBAAyB,GAC9B,MAAM,CAgER;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,oBAAyB,GAC9B,MAAM,CAyGR;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,oBAAyB,GAC9B,MAAM,CAiIR"}