@shrkcrft/inspector 0.1.0-alpha.2

package/dist/changed-scope.js

@@ -0,0 +1,172 @@
+/**
+ * Changed-scope quality model v2.
+ *
+ * Generalised classification of any finding (boundary violation, policy
+ * failure, drift entry, quality issue, doctor warning…) against a set of
+ * changed files plus an optional baseline.
+ *
+ * Each finding falls into one of seven buckets:
+ *
+ *   new-in-changed-file        — finding lives in a changed file and was NOT
+ *                                in the baseline.
+ *   existing-touched           — finding exists in baseline AND the finding's
+ *                                file is in the changed set.
+ *   existing-untouched-hidden  — finding exists in baseline AND finding's file
+ *                                is not changed; suppressed from the
+ *                                "introduced by this change" view.
+ *   resolved                   — finding existed in baseline but is no longer
+ *                                present in the current result.
+ *   unknown                    — finding has no file path, so we cannot bucket
+ *                                it against changed files.
+ *   unchanged                  — baseline and current both report this finding
+ *                                in an unchanged file. Same as
+ *                                existing-untouched-hidden but logically
+ *                                preserved as "no change".
+ *   out-of-scope               — finding lives outside any explicit scope the
+ *                                caller passed (e.g. a non-relevant package).
+ *
+ * Inputs are pure data — this module does not run git, does not read files,
+ * does not call out to language servers. Callers pre-compute the changed-file
+ * set with `resolveChangedFiles` from `boundaries-changed-only.ts` (or pass
+ * an explicit list), then feed everything in.
+ *
+ * Schema: sharkcraft.changed-scope/v1
+ */
+import { resolve } from 'node:path';
+export const CHANGED_SCOPE_SCHEMA = 'sharkcraft.changed-scope/v1';
+export var ChangedFindingBucket;
+(function (ChangedFindingBucket) {
+    ChangedFindingBucket["NewInChangedFile"] = "new-in-changed-file";
+    ChangedFindingBucket["ExistingTouched"] = "existing-touched";
+    ChangedFindingBucket["ExistingUntouchedHidden"] = "existing-untouched-hidden";
+    ChangedFindingBucket["Resolved"] = "resolved";
+    ChangedFindingBucket["Unknown"] = "unknown";
+    ChangedFindingBucket["Unchanged"] = "unchanged";
+    ChangedFindingBucket["OutOfScope"] = "out-of-scope";
+})(ChangedFindingBucket || (ChangedFindingBucket = {}));
+function normalisePath(input, projectRoot) {
+    if (!input)
+        return '';
+    if (input.startsWith('/') || /^[A-Za-z]:[\\/]/.test(input)) {
+        const rel = resolve(input).replace(resolve(projectRoot), '').replace(/^[\\/]+/, '');
+        return rel.split(/[\\/]/).join('/');
+    }
+    return input.split(/[\\/]/).join('/');
+}
+function isInSet(file, set) {
+    if (set.size === 0)
+        return false;
+    if (set.has(file))
+        return true;
+    for (const candidate of set) {
+        if (candidate && (file === candidate || file.endsWith('/' + candidate)))
+            return true;
+    }
+    return false;
+}
+export function classifyChangedScope(opts) {
+    const changedSet = new Set(opts.changedFiles.map((f) => f.split(/[\\/]/).join('/')));
+    const scopeSet = new Set((opts.scopeFiles ?? []).map((f) => f.split(/[\\/]/).join('/')));
+    const baselineKeys = new Set((opts.baseline ?? []).map((b) => b.key));
+    const baselineByKey = new Map();
+    for (const b of opts.baseline ?? [])
+        baselineByKey.set(b.key, b);
+    const currentKeys = new Set(opts.current.map((c) => c.key));
+    const classified = [];
+    const newIssues = [];
+    const existingTouched = [];
+    const hiddenBaseline = [];
+    const resolved = [];
+    for (const finding of opts.current) {
+        const file = normalisePath(finding.file, opts.projectRoot);
+        if (!file) {
+            classified.push({ finding, bucket: ChangedFindingBucket.Unknown });
+            continue;
+        }
+        if (scopeSet.size > 0 && !isInSet(file, scopeSet)) {
+            classified.push({ finding, bucket: ChangedFindingBucket.OutOfScope });
+            continue;
+        }
+        const inChanged = isInSet(file, changedSet);
+        const inBaseline = baselineKeys.has(finding.key);
+        if (inChanged && inBaseline) {
+            classified.push({ finding, bucket: ChangedFindingBucket.ExistingTouched });
+            existingTouched.push(finding);
+            continue;
+        }
+        if (inChanged && !inBaseline) {
+            classified.push({ finding, bucket: ChangedFindingBucket.NewInChangedFile });
+            newIssues.push(finding);
+            continue;
+        }
+        if (!inChanged && inBaseline) {
+            classified.push({ finding, bucket: ChangedFindingBucket.Unchanged });
+            hiddenBaseline.push(finding);
+            continue;
+        }
+        // not in changed, not in baseline — pre-existing in untouched file.
+        classified.push({ finding, bucket: ChangedFindingBucket.ExistingUntouchedHidden });
+        hiddenBaseline.push(finding);
+    }
+    for (const b of opts.baseline ?? []) {
+        if (!currentKeys.has(b.key)) {
+            classified.push({ finding: b, bucket: ChangedFindingBucket.Resolved });
+            resolved.push(b);
+        }
+    }
+    const counts = {
+        newInChangedFile: 0,
+        existingTouched: 0,
+        existingUntouchedHidden: 0,
+        resolved: 0,
+        unknown: 0,
+        unchanged: 0,
+        outOfScope: 0,
+    };
+    for (const c of classified) {
+        switch (c.bucket) {
+            case ChangedFindingBucket.NewInChangedFile:
+                counts.newInChangedFile += 1;
+                break;
+            case ChangedFindingBucket.ExistingTouched:
+                counts.existingTouched += 1;
+                break;
+            case ChangedFindingBucket.ExistingUntouchedHidden:
+                counts.existingUntouchedHidden += 1;
+                break;
+            case ChangedFindingBucket.Resolved:
+                counts.resolved += 1;
+                break;
+            case ChangedFindingBucket.Unknown:
+                counts.unknown += 1;
+                break;
+            case ChangedFindingBucket.Unchanged:
+                counts.unchanged += 1;
+                break;
+            case ChangedFindingBucket.OutOfScope:
+                counts.outOfScope += 1;
+                break;
+        }
+    }
+    return {
+        schema: CHANGED_SCOPE_SCHEMA,
+        changedFiles: opts.changedFiles,
+        classified,
+        counts,
+        newIssues,
+        existingTouched,
+        hiddenBaseline,
+        resolved,
+    };
+}
+/**
+ * Convenience helper for callers that want the headline numbers in
+ * one line of text.
+ */
+export function summariseChangedScope(classification) {
+    const c = classification.counts;
+    return (`New issues introduced: ${c.newInChangedFile} | ` +
+        `Existing touched: ${c.existingTouched} | ` +
+        `Existing hidden baseline: ${c.existingUntouchedHidden + c.unchanged} | ` +
+        `Resolved: ${c.resolved}`);
+}

package/dist/changes-summary.d.ts

@@ -0,0 +1,87 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const CHANGES_SUMMARY_SCHEMA = "sharkcraft.changes-summary/v1";
+export declare enum ChangeArea {
+    Cli = "cli",
+    McpServer = "mcp-server",
+    Inspector = "inspector",
+    Knowledge = "knowledge",
+    Templates = "templates",
+    Paths = "paths",
+    Pipelines = "pipelines",
+    Presets = "presets",
+    Boundaries = "boundaries",
+    Packs = "packs",
+    Core = "core",
+    Workspace = "workspace",
+    Config = "config",
+    PluginApi = "plugin-api",
+    Importer = "importer",
+    Generator = "generator",
+    PackContrib = "pack-contributions",
+    PackManifest = "pack-manifest",
+    Docs = "docs",
+    Tests = "tests",
+    Examples = "examples",
+    Scripts = "scripts",
+    E2E = "e2e",
+    Sharkcraft = "sharkcraft-self-config",
+    Reports = "reports",
+    Unknown = "unknown"
+}
+export interface IChangedFileSummary {
+    path: string;
+    area: ChangeArea;
+    isTest: boolean;
+    isDoc: boolean;
+    isMcpTool: boolean;
+    isCliCommand: boolean;
+    isSchema: boolean;
+    isPackAsset: boolean;
+    isSafetyRelevant: boolean;
+}
+export interface IChangesSummaryReport {
+    schema: typeof CHANGES_SUMMARY_SCHEMA;
+    generatedAt: string;
+    source: 'since' | 'staged' | 'files' | 'working-tree';
+    ref?: string;
+    /** Optional round / label that this diff represents. */
+    roundLabel?: string;
+    totalFiles: number;
+    filesByArea: Record<string, readonly string[]>;
+    files: readonly IChangedFileSummary[];
+    /** Touched CLI command files (relative). */
+    touchedCommands: readonly string[];
+    /** Touched MCP tool files. */
+    touchedMcpTools: readonly string[];
+    /** Touched JSON schema or schema-like files. */
+    touchedSchemas: readonly string[];
+    /** Touched docs files. */
+    touchedDocs: readonly string[];
+    /** Touched test files. */
+    touchedTests: readonly string[];
+    /** Touched pack manifest / pack assets. */
+    touchedPackAssets: readonly string[];
+    /** Touched safety-relevant files. */
+    safetyRelevantFiles: readonly string[];
+    /** Risk verdict — low | medium | high. */
+    risk: 'low' | 'medium' | 'high';
+    /** Reasons backing the risk verdict. */
+    riskReasons: readonly string[];
+    /** Suggested validation commands. */
+    suggestedValidationCommands: readonly string[];
+    /** Likely PR-title-style summary. */
+    likelyPrSummary: string;
+}
+export interface IChangesSummaryOptions {
+    /** Diff base (used with --since). */
+    since?: string;
+    /** Use git diff --cached. */
+    staged?: boolean;
+    /** Explicit file list, bypasses git. */
+    files?: readonly string[];
+    /** Optional round / label captured into the report (no behavioural effect). */
+    roundLabel?: string;
+}
+export declare function buildChangesSummary(inspection: ISharkcraftInspection, options?: IChangesSummaryOptions): Promise<IChangesSummaryReport>;
+export declare function renderChangesSummaryMarkdown(report: IChangesSummaryReport): string;
+//# sourceMappingURL=changes-summary.d.ts.map

package/dist/changes-summary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"changes-summary.d.ts","sourceRoot":"","sources":["../src/changes-summary.ts"],"names":[],"mappings":"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"}

package/dist/changes-summary.js

@@ -0,0 +1,323 @@
+/**
+ * Changes summary.
+ *
+ * Generic "what changed and what should I check?" report. Generates a
+ * grouped summary over git --since / --staged / --files and surfaces:
+ *   - touched packages / areas
+ *   - touched commands / MCP tools / schemas / docs / tests / pack assets
+ *   - safety-relevant changes (boundaries, plan signing, MCP write surface)
+ *   - risk summary
+ *   - suggested validation commands
+ *
+ * Read-only; no AI; deterministic. Schema: sharkcraft.changes-summary/v1.
+ */
+import { getChangedFiles } from "./git-helpers.js";
+export const CHANGES_SUMMARY_SCHEMA = 'sharkcraft.changes-summary/v1';
+export var ChangeArea;
+(function (ChangeArea) {
+    ChangeArea["Cli"] = "cli";
+    ChangeArea["McpServer"] = "mcp-server";
+    ChangeArea["Inspector"] = "inspector";
+    ChangeArea["Knowledge"] = "knowledge";
+    ChangeArea["Templates"] = "templates";
+    ChangeArea["Paths"] = "paths";
+    ChangeArea["Pipelines"] = "pipelines";
+    ChangeArea["Presets"] = "presets";
+    ChangeArea["Boundaries"] = "boundaries";
+    ChangeArea["Packs"] = "packs";
+    ChangeArea["Core"] = "core";
+    ChangeArea["Workspace"] = "workspace";
+    ChangeArea["Config"] = "config";
+    ChangeArea["PluginApi"] = "plugin-api";
+    ChangeArea["Importer"] = "importer";
+    ChangeArea["Generator"] = "generator";
+    ChangeArea["PackContrib"] = "pack-contributions";
+    ChangeArea["PackManifest"] = "pack-manifest";
+    ChangeArea["Docs"] = "docs";
+    ChangeArea["Tests"] = "tests";
+    ChangeArea["Examples"] = "examples";
+    ChangeArea["Scripts"] = "scripts";
+    ChangeArea["E2E"] = "e2e";
+    ChangeArea["Sharkcraft"] = "sharkcraft-self-config";
+    ChangeArea["Reports"] = "reports";
+    ChangeArea["Unknown"] = "unknown";
+})(ChangeArea || (ChangeArea = {}));
+function classifyArea(file) {
+    if (file.startsWith('packages/cli/'))
+        return ChangeArea.Cli;
+    if (file.startsWith('packages/mcp-server/'))
+        return ChangeArea.McpServer;
+    if (file.startsWith('packages/inspector/'))
+        return ChangeArea.Inspector;
+    if (file.startsWith('packages/knowledge/'))
+        return ChangeArea.Knowledge;
+    if (file.startsWith('packages/templates/'))
+        return ChangeArea.Templates;
+    if (file.startsWith('packages/paths/'))
+        return ChangeArea.Paths;
+    if (file.startsWith('packages/pipelines/'))
+        return ChangeArea.Pipelines;
+    if (file.startsWith('packages/presets/'))
+        return ChangeArea.Presets;
+    if (file.startsWith('packages/boundaries/'))
+        return ChangeArea.Boundaries;
+    if (file.startsWith('packages/packs/'))
+        return ChangeArea.Packs;
+    if (file.startsWith('packages/core/'))
+        return ChangeArea.Core;
+    if (file.startsWith('packages/workspace/'))
+        return ChangeArea.Workspace;
+    if (file.startsWith('packages/config/'))
+        return ChangeArea.Config;
+    if (file.startsWith('packages/plugin-api/'))
+        return ChangeArea.PluginApi;
+    if (file.startsWith('packages/importer/'))
+        return ChangeArea.Importer;
+    if (file.startsWith('packages/generator/'))
+        return ChangeArea.Generator;
+    if (file.startsWith('docs/'))
+        return ChangeArea.Docs;
+    if (file.startsWith('e2e/'))
+        return ChangeArea.E2E;
+    if (file.startsWith('examples/'))
+        return ChangeArea.Examples;
+    if (file.startsWith('scripts/'))
+        return ChangeArea.Scripts;
+    if (file.startsWith('sharkcraft/'))
+        return ChangeArea.Sharkcraft;
+    if (file.startsWith('.sharkcraft/'))
+        return ChangeArea.Reports;
+    if (/(?:^|\/)[\w-]*sharkcraft-pack\//.test(file)) {
+        return ChangeArea.PackContrib;
+    }
+    return ChangeArea.Unknown;
+}
+function classifyFile(file) {
+    const area = classifyArea(file);
+    const lower = file.toLowerCase();
+    const isTest = lower.includes('__tests__/') ||
+        lower.endsWith('.test.ts') ||
+        lower.endsWith('.spec.ts') ||
+        lower.endsWith('.test.tsx') ||
+        lower.endsWith('.spec.tsx');
+    const isDoc = lower.endsWith('.md') || area === ChangeArea.Docs;
+    const isMcpTool = lower.startsWith('packages/mcp-server/src/tools/') && lower.endsWith('.ts');
+    const isCliCommand = lower.startsWith('packages/cli/src/commands/') && lower.endsWith('.ts');
+    const isSchema = lower.includes('schema') && (lower.endsWith('.json') || lower.endsWith('.ts'));
+    const isPackAsset = area === ChangeArea.PackContrib || area === ChangeArea.Packs;
+    const isSafetyRelevant = isMcpTool ||
+        lower.includes('safety-audit') ||
+        lower.includes('command-catalog') ||
+        lower.includes('plan-signing') ||
+        lower.includes('boundaries-changed-only') ||
+        lower.includes('apply.command') ||
+        lower.startsWith('packages/generator/src/plan');
+    return {
+        path: file,
+        area,
+        isTest,
+        isDoc,
+        isMcpTool,
+        isCliCommand,
+        isSchema,
+        isPackAsset,
+        isSafetyRelevant,
+    };
+}
+function groupByArea(files) {
+    const out = {};
+    for (const f of files) {
+        const key = f.area;
+        if (!out[key])
+            out[key] = [];
+        out[key].push(f.path);
+    }
+    for (const key of Object.keys(out))
+        out[key].sort();
+    return out;
+}
+function computeRisk(files) {
+    const reasons = [];
+    let score = 0;
+    const mcpCount = files.filter((f) => f.isMcpTool).length;
+    if (mcpCount > 0) {
+        reasons.push(`${mcpCount} MCP tool file(s) touched — run safety audit`);
+        score += 3;
+    }
+    const safetyCount = files.filter((f) => f.isSafetyRelevant).length;
+    if (safetyCount > 0) {
+        reasons.push(`${safetyCount} safety-relevant file(s) touched`);
+        score += 2;
+    }
+    const writeCmd = files.filter((f) => f.isCliCommand &&
+        (f.path.includes('apply') || f.path.includes('gen') || f.path.includes('init'))).length;
+    if (writeCmd > 0) {
+        reasons.push(`${writeCmd} write-path command file(s) touched`);
+        score += 2;
+    }
+    const packCount = files.filter((f) => f.isPackAsset).length;
+    if (packCount > 0) {
+        reasons.push(`${packCount} pack asset file(s) touched — re-sign before publish`);
+        score += 1;
+    }
+    if (files.length > 25) {
+        reasons.push(`${files.length} files changed — large diff`);
+        score += 1;
+    }
+    if (score >= 5)
+        return { risk: 'high', reasons };
+    if (score >= 2)
+        return { risk: 'medium', reasons };
+    return { risk: 'low', reasons };
+}
+function suggestValidationCommands(files) {
+    const out = new Set();
+    out.add('bun x tsc -p tsconfig.base.json --noEmit');
+    out.add('bun test');
+    if (files.some((f) => f.isMcpTool)) {
+        out.add('shrk safety audit --deep');
+        out.add('shrk commands doctor');
+    }
+    if (files.some((f) => f.isCliCommand)) {
+        out.add('shrk commands doctor');
+        out.add('shrk commands ux-check');
+    }
+    if (files.some((f) => f.area === ChangeArea.Knowledge || f.area === ChangeArea.Sharkcraft)) {
+        out.add('shrk doctor');
+        out.add('shrk knowledge stale-check --ci');
+    }
+    if (files.some((f) => f.area === ChangeArea.Templates || f.path.includes('templates'))) {
+        out.add('shrk templates drift --min-severity warning');
+    }
+    if (files.some((f) => f.area === ChangeArea.Boundaries || f.path.endsWith('boundaries.ts'))) {
+        out.add('shrk check boundaries --changed-only');
+    }
+    if (files.some((f) => f.isPackAsset)) {
+        out.add('shrk packs doctor');
+        out.add('shrk packs verify');
+    }
+    if (files.some((f) => f.area === ChangeArea.Inspector)) {
+        out.add('shrk product check');
+    }
+    return Array.from(out);
+}
+function buildPrSummary(files) {
+    const areaCounts = new Map();
+    for (const f of files)
+        areaCounts.set(f.area, (areaCounts.get(f.area) ?? 0) + 1);
+    const top = [...areaCounts.entries()].sort((a, b) => b[1] - a[1]).slice(0, 3);
+    if (top.length === 0)
+        return 'No changes';
+    return `Changes across: ${top.map(([a, c]) => `${a} (${c})`).join(', ')}`;
+}
+export async function buildChangesSummary(inspection, options = {}) {
+    const cwd = inspection.projectRoot;
+    let changedFiles = [];
+    let source = 'working-tree';
+    let ref;
+    if (options.files && options.files.length > 0) {
+        changedFiles = options.files;
+        source = 'files';
+    }
+    else if (options.staged) {
+        changedFiles = getChangedFiles(cwd, { staged: true });
+        source = 'staged';
+    }
+    else if (options.since) {
+        changedFiles = getChangedFiles(cwd, { since: options.since });
+        source = 'since';
+        ref = options.since;
+    }
+    else {
+        changedFiles = getChangedFiles(cwd, {});
+        source = 'working-tree';
+    }
+    const classified = changedFiles.map(classifyFile);
+    const filesByArea = groupByArea(classified);
+    const touchedCommands = classified.filter((c) => c.isCliCommand).map((c) => c.path);
+    const touchedMcpTools = classified.filter((c) => c.isMcpTool).map((c) => c.path);
+    const touchedSchemas = classified.filter((c) => c.isSchema).map((c) => c.path);
+    const touchedDocs = classified.filter((c) => c.isDoc).map((c) => c.path);
+    const touchedTests = classified.filter((c) => c.isTest).map((c) => c.path);
+    const touchedPackAssets = classified.filter((c) => c.isPackAsset).map((c) => c.path);
+    const safetyRelevantFiles = classified.filter((c) => c.isSafetyRelevant).map((c) => c.path);
+    const { risk, reasons } = computeRisk(classified);
+    return {
+        schema: CHANGES_SUMMARY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        source,
+        ...(ref ? { ref } : {}),
+        ...(options.roundLabel ? { roundLabel: options.roundLabel } : {}),
+        totalFiles: classified.length,
+        filesByArea,
+        files: classified,
+        touchedCommands,
+        touchedMcpTools,
+        touchedSchemas,
+        touchedDocs,
+        touchedTests,
+        touchedPackAssets,
+        safetyRelevantFiles,
+        risk,
+        riskReasons: reasons,
+        suggestedValidationCommands: suggestValidationCommands(classified),
+        likelyPrSummary: buildPrSummary(classified),
+    };
+}
+export function renderChangesSummaryMarkdown(report) {
+    const lines = [];
+    lines.push('# Changes summary');
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push(`Source: ${report.source}${report.ref ? ` (ref=${report.ref})` : ''}`);
+    lines.push('');
+    lines.push(`- total files: ${report.totalFiles}`);
+    lines.push(`- risk: **${report.risk}**`);
+    if (report.riskReasons.length > 0) {
+        lines.push('  - ' + report.riskReasons.join('\n  - '));
+    }
+    lines.push('');
+    lines.push('## Files by area');
+    for (const [area, files] of Object.entries(report.filesByArea)) {
+        lines.push(`### ${area} (${files.length})`);
+        for (const f of files)
+            lines.push(`- ${f}`);
+    }
+    if (report.touchedCommands.length > 0) {
+        lines.push('');
+        lines.push('## Touched CLI commands');
+        for (const c of report.touchedCommands)
+            lines.push(`- ${c}`);
+    }
+    if (report.touchedMcpTools.length > 0) {
+        lines.push('');
+        lines.push('## Touched MCP tools (read-only invariant — verify!)');
+        for (const t of report.touchedMcpTools)
+            lines.push(`- ${t}`);
+    }
+    if (report.touchedDocs.length > 0) {
+        lines.push('');
+        lines.push('## Touched docs');
+        for (const d of report.touchedDocs)
+            lines.push(`- ${d}`);
+    }
+    if (report.touchedTests.length > 0) {
+        lines.push('');
+        lines.push('## Touched tests');
+        for (const t of report.touchedTests)
+            lines.push(`- ${t}`);
+    }
+    if (report.touchedPackAssets.length > 0) {
+        lines.push('');
+        lines.push('## Touched pack assets (re-sign before publish)');
+        for (const p of report.touchedPackAssets)
+            lines.push(`- ${p}`);
+    }
+    lines.push('');
+    lines.push('## Suggested validation commands');
+    for (const c of report.suggestedValidationCommands)
+        lines.push(`- \`${c}\``);
+    lines.push('');
+    lines.push('## Likely PR summary');
+    lines.push(`> ${report.likelyPrSummary}`);
+    return lines.join('\n') + '\n';
+}

package/dist/check-result-v1.d.ts

@@ -0,0 +1,90 @@
+export declare const CHECK_RESULT_SCHEMA = "sharkcraft.check-result/v1";
+export declare const CHECK_AGGREGATE_SCHEMA = "sharkcraft.check-aggregate/v1";
+export declare enum CheckResultStatus {
+    Pass = "pass",
+    Warn = "warn",
+    Fail = "fail",
+    Unknown = "unknown"
+}
+export declare enum CheckFindingSeverity {
+    Error = "error",
+    Warning = "warning",
+    Info = "info"
+}
+export interface ICheckFinding {
+    severity: CheckFindingSeverity;
+    file?: string;
+    line?: number;
+    column?: number;
+    ruleId?: string;
+    message: string;
+    suggestedAction?: string;
+    safeToAutoFix?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ICheckResultSummary {
+    errors: number;
+    warnings: number;
+    infos: number;
+    total: number;
+}
+export interface ICheckResult {
+    schema: typeof CHECK_RESULT_SCHEMA;
+    tool: string;
+    command?: string;
+    generatedAt: string;
+    status: CheckResultStatus;
+    findings: readonly ICheckFinding[];
+    summary: ICheckResultSummary;
+    metadata?: Record<string, unknown>;
+    sourceReportPath?: string;
+}
+export interface IParseResultOk {
+    ok: true;
+    result: ICheckResult;
+}
+export interface IParseResultErr {
+    ok: false;
+    reason: string;
+}
+export type ParseCheckResult = IParseResultOk | IParseResultErr;
+export interface IBuildCheckResultInput {
+    tool: string;
+    command?: string;
+    findings: readonly ICheckFinding[];
+    sourceReportPath?: string;
+    metadata?: Record<string, unknown>;
+    /** Force a specific status (overrides the auto-derived one). */
+    status?: CheckResultStatus;
+}
+export declare function buildCheckResult(input: IBuildCheckResultInput): ICheckResult;
+export declare function parseCheckResult(raw: string): ParseCheckResult;
+export declare function parseCheckResultFromFile(path: string): ParseCheckResult;
+export declare function convertEslintToCheckResult(raw: string, sourceReportPath?: string): ParseCheckResult;
+/**
+ * Biome's JSON output is not a stable contract. We accept either:
+ *   - the adjacent shape: { diagnostics: [{ category, severity, description, location: { path, line?, column? } }] }
+ *   - native Biome `--reporter github`-ish: { diagnostics: [{ severity, description, location }] }
+ * Anything else returns a clear reason.
+ */
+export declare function convertBiomeToCheckResult(raw: string, sourceReportPath?: string): ParseCheckResult;
+export interface ICheckAggregateEntry {
+    tool: string;
+    status: CheckResultStatus;
+    summary: ICheckResultSummary;
+    sourceReportPath: string;
+}
+export interface ICheckAggregate {
+    schema: typeof CHECK_AGGREGATE_SCHEMA;
+    generatedAt: string;
+    overall: CheckResultStatus;
+    total: ICheckResultSummary;
+    entries: readonly ICheckAggregateEntry[];
+    /** Findings rolled up across every imported result. */
+    findings: readonly ICheckFinding[];
+}
+export declare function buildCheckAggregate(results: readonly {
+    result: ICheckResult;
+    sourceReportPath: string;
+}[]): ICheckAggregate;
+//# sourceMappingURL=check-result-v1.d.ts.map

package/dist/check-result-v1.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"check-result-v1.d.ts","sourceRoot":"","sources":["../src/check-result-v1.ts"],"names":[],"mappings":"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"}