@shrkcrft/inspector 0.1.0-alpha.1

package/dist/coverage-report.js

@@ -0,0 +1,190 @@
+import { hasActionHints } from '@shrkcrft/knowledge';
+import { resolvePreset, resolvePresetReferences } from '@shrkcrft/presets';
+import { inspectionReferenceLookup } from "./reference-lookup.js";
+function pct(covered, total) {
+    if (total === 0)
+        return 100;
+    return Math.round((covered / total) * 100);
+}
+/**
+ * Deterministic coverage report. Different from AI-readiness — focuses on
+ * **relationships**: do entries link to each other in a way that lets an
+ * agent traverse the project intelligence?
+ */
+export function buildCoverageReport(inspection) {
+    const suggestions = [];
+    const categories = [];
+    // 1. Templates with description ≥ 5 chars.
+    {
+        const total = inspection.templates.length;
+        const missing = [];
+        let covered = 0;
+        for (const t of inspection.templates) {
+            if (typeof t.description === 'string' && t.description.trim().length >= 5) {
+                covered += 1;
+            }
+            else {
+                missing.push(`${t.id} — description missing or too short`);
+            }
+        }
+        categories.push({
+            id: 'template-descriptions',
+            title: 'Templates have a meaningful description',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 2. Templates with related rules / paths.
+    {
+        const total = inspection.templates.length;
+        const missing = [];
+        let covered = 0;
+        for (const t of inspection.templates) {
+            const related = t.related ?? [];
+            if (related.length > 0)
+                covered += 1;
+            else
+                missing.push(`${t.id} — no related rules/paths declared`);
+        }
+        categories.push({
+            id: 'template-related',
+            title: 'Templates declare related rules/paths',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 3. Critical/high knowledge entries with action hints.
+    {
+        const eligible = inspection.knowledgeEntries.filter((e) => {
+            const p = String(e.priority);
+            return p === 'critical' || p === 'high';
+        });
+        const total = eligible.length;
+        const missing = [];
+        let covered = 0;
+        for (const e of eligible) {
+            if (hasActionHints(e))
+                covered += 1;
+            else
+                missing.push(`${e.id} — no actionHints`);
+        }
+        categories.push({
+            id: 'hint-coverage',
+            title: 'Critical/high entries carry actionHints',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 4. Pipelines whose steps reference existing templates/rules/paths.
+    {
+        const total = inspection.pipelines.length;
+        const missing = [];
+        let covered = 0;
+        for (const p of inspection.pipelines) {
+            const refs = [];
+            for (const step of p.steps ?? []) {
+                for (const ref of step.references ?? [])
+                    refs.push(ref);
+            }
+            if (refs.length === 0) {
+                missing.push(`${p.id} — no step references`);
+                continue;
+            }
+            const allResolve = refs.every((id) => inspection.templates.some((t) => t.id === id) ||
+                inspection.knowledgeEntries.some((e) => e.id === id));
+            if (allResolve)
+                covered += 1;
+            else
+                missing.push(`${p.id} — some step references unknown ids`);
+        }
+        categories.push({
+            id: 'pipeline-step-refs',
+            title: 'Pipelines reference resolvable templates/rules',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 5. Presets — references resolve.
+    {
+        const refLookup = inspectionReferenceLookup(inspection);
+        const presets = inspection.presetRegistry.list();
+        const total = presets.length;
+        const missing = [];
+        let covered = 0;
+        for (const p of presets) {
+            const resolved = resolvePreset(inspection.presetRegistry, p.id);
+            const refs = resolvePresetReferences(resolved, refLookup);
+            if (refs.totalMissing === 0 && resolved.issues.length === 0) {
+                covered += 1;
+            }
+            else {
+                missing.push(`${p.id} — ${resolved.issues.length} composition issues, ${refs.totalMissing} missing refs`);
+            }
+        }
+        categories.push({
+            id: 'preset-references',
+            title: 'Presets compose + reference assets that resolve',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 6. Boundary rules — suggested fix present.
+    {
+        const rules = inspection.boundaryRegistry.list();
+        const total = rules.length;
+        const missing = [];
+        let covered = 0;
+        for (const r of rules) {
+            if (typeof r.suggestedFix === 'string' && r.suggestedFix.trim().length > 0)
+                covered += 1;
+            else
+                missing.push(`${r.id} — no suggestedFix`);
+        }
+        categories.push({
+            id: 'boundary-fixes',
+            title: 'Boundary rules ship a suggestedFix',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    // 7. Packs — at least one doc.
+    {
+        const packs = inspection.packs.discoveredPacks.filter((p) => p.valid);
+        const total = packs.length;
+        const missing = [];
+        let covered = 0;
+        for (const p of packs) {
+            const docs = p.manifest?.contributions.docsFiles ?? [];
+            if (docs.length > 0)
+                covered += 1;
+            else
+                missing.push(`${p.packageName} — no docsFiles`);
+        }
+        categories.push({
+            id: 'pack-docs',
+            title: 'Packs ship at least one doc',
+            total,
+            covered,
+            score: pct(covered, total),
+            missing,
+        });
+    }
+    const overall = Math.round(categories.reduce((s, c) => s + c.score, 0) / Math.max(categories.length, 1));
+    if (overall < 60)
+        suggestions.push('Pair every critical rule with action hints + verification commands.');
+    if (overall < 80)
+        suggestions.push('Make templates declare related rules/paths (`template.related`).');
+    return { categories, overall, suggestions };
+}

package/dist/custom-checks.d.ts

@@ -0,0 +1,146 @@
+import { type IKnowledgeEntry } from '@shrkcrft/knowledge';
+export declare const CUSTOM_CHECK_REPORT_SCHEMA = "sharkcraft.custom-check/v1";
+export declare const CUSTOM_CHECKS_REGISTRY_SCHEMA = "sharkcraft.custom-checks-registry/v1";
+export declare enum CustomCheckScope {
+    ChangedOnly = "changed-only",
+    Staged = "staged",
+    All = "all"
+}
+export declare enum CustomCheckKind {
+    ImportGraph = "import-graph",
+    AstShape = "ast-shape",
+    TextShape = "text-shape",
+    ProjectScript = "project-script",
+    ExternalTool = "external-tool"
+}
+export declare enum CustomCheckSafety {
+    ReadOnly = "read-only",
+    WritesReport = "writes-report",
+    WritesPreview = "writes-preview"
+}
+export declare enum CustomCheckOutput {
+    Json = "json",
+    Text = "text",
+    ExitCode = "exit-code"
+}
+export declare enum CustomCheckStatus {
+    Pass = "pass",
+    Warn = "warn",
+    Fail = "fail",
+    Skipped = "skipped"
+}
+export interface ICustomCheckDescriptor {
+    /** Stable id (must be unique across the registry). */
+    id: string;
+    /** The rule that owns this check. The engine fills this in from context. */
+    ownerRuleId?: string;
+    /** Shell command to run (never executed unless --execute). */
+    command: string;
+    /** Where the script writes its report (relative to repo root). */
+    reportPath?: string;
+    /** Optional human description. */
+    description?: string;
+    scope?: CustomCheckScope;
+    kind?: CustomCheckKind;
+    safety?: CustomCheckSafety;
+    output?: CustomCheckOutput;
+    /** Tags for filtering. */
+    tags?: readonly string[];
+}
+export interface ICustomCheckFinding {
+    severity: 'error' | 'warning' | 'info';
+    file?: string;
+    message: string;
+    suggestedAction?: string;
+    safeToAutoFix?: boolean;
+}
+export interface ICustomCheckReport {
+    schema: typeof CUSTOM_CHECK_REPORT_SCHEMA;
+    checkId: string;
+    ruleId?: string;
+    generatedAt: string;
+    status: CustomCheckStatus;
+    findings: readonly ICustomCheckFinding[];
+    /** Free-form metadata copied verbatim from the script. */
+    metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ICustomCheckRegistryEntry {
+    descriptor: ICustomCheckDescriptor;
+    ruleId: string;
+    /** Validation findings about the descriptor itself. */
+    warnings: readonly string[];
+}
+export interface ICustomCheckRegistry {
+    schema: typeof CUSTOM_CHECKS_REGISTRY_SCHEMA;
+    generatedAt: string;
+    entries: readonly ICustomCheckRegistryEntry[];
+    duplicates: readonly {
+        id: string;
+        ruleIds: readonly string[];
+    }[];
+    invalid: readonly {
+        ruleId: string;
+        reason: string;
+    }[];
+}
+/** Read the descriptors a rule declares under `metadata.checks`. */
+export declare function readDescriptorsFromRule(rule: IKnowledgeEntry): readonly ICustomCheckDescriptor[];
+export declare function buildCustomChecksRegistry(entries: readonly IKnowledgeEntry[]): ICustomCheckRegistry;
+export interface ICustomCheckDoctorReport {
+    schema: 'sharkcraft.custom-checks-doctor/v1';
+    generatedAt: string;
+    totalChecks: number;
+    warnings: number;
+    errors: number;
+    details: readonly {
+        ruleId: string;
+        checkId: string;
+        severity: 'error' | 'warning' | 'info';
+        message: string;
+    }[];
+}
+export declare function doctorCustomChecks(registry: ICustomCheckRegistry): ICustomCheckDoctorReport;
+/**
+ * Parse a custom-check report from a known location. Supports the JSON
+ * convention (preferred), and a text fallback that turns each line into
+ * a `severity:warning, message: line` finding.
+ */
+export declare function parseCustomCheckReportFromFile(filePath: string, expectedCheckId?: string): {
+    ok: true;
+    report: ICustomCheckReport;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function parseCustomCheckReport(raw: string, expectedCheckId?: string): {
+    ok: true;
+    report: ICustomCheckReport;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface IRunCustomCheckOptions {
+    cwd: string;
+    /** When false (default) the runner prints the command and exits without spawning. */
+    execute?: boolean;
+    /** Override the descriptor reportPath. */
+    reportPath?: string;
+    /** Optional environment additions. */
+    env?: Record<string, string>;
+    /** Maximum runtime in ms. */
+    timeoutMs?: number;
+}
+export interface IRunCustomCheckResult {
+    schema: 'sharkcraft.custom-check-run/v1';
+    checkId: string;
+    ownerRuleId?: string;
+    command: string;
+    executed: boolean;
+    exitCode: number | null;
+    stderr?: string;
+    stdoutSummary?: string;
+    report?: ICustomCheckReport;
+    reason?: string;
+}
+export declare function runCustomCheck(descriptor: ICustomCheckDescriptor, options: IRunCustomCheckOptions): IRunCustomCheckResult;
+//# sourceMappingURL=custom-checks.d.ts.map

package/dist/custom-checks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"custom-checks.d.ts","sourceRoot":"","sources":["../src/custom-checks.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,KAAK,eAAe,EAAiB,MAAM,qBAAqB,CAAC;AAE1E,eAAO,MAAM,0BAA0B,+BAA+B,CAAC;AACvE,eAAO,MAAM,6BAA6B,yCAAyC,CAAC;AAEpF,oBAAY,gBAAgB;IAC1B,WAAW,iBAAiB;IAC5B,MAAM,WAAW;IACjB,GAAG,QAAQ;CACZ;AAED,oBAAY,eAAe;IACzB,WAAW,iBAAiB;IAC5B,QAAQ,cAAc;IACtB,SAAS,eAAe;IACxB,aAAa,mBAAmB;IAChC,YAAY,kBAAkB;CAC/B;AAED,oBAAY,iBAAiB;IAC3B,QAAQ,cAAc;IACtB,YAAY,kBAAkB;IAC9B,aAAa,mBAAmB;CACjC;AAED,oBAAY,iBAAiB;IAC3B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,QAAQ,cAAc;CACvB;AAED,oBAAY,iBAAiB;IAC3B,IAAI,SAAS;IACb,IAAI,SAAS;IACb,IAAI,SAAS;IACb,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,0BAA0B;IAC1B,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,0BAA0B,CAAC;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,sBAAsB,CAAC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,uDAAuD;IACvD,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,OAAO,6BAA6B,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAC9C,UAAU,EAAE,SAAS;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IAClE,OAAO,EAAE,SAAS;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxD;AAID,oEAAoE;AACpE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,sBAAsB,EAAE,CAKhG;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,SAAS,eAAe,EAAE,GAClC,oBAAoB,CA8CtB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,oCAAoC,CAAC;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,SAAS;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;QACvC,OAAO,EAAE,MAAM,CAAC;KACjB,EAAE,CAAC;CACL;AAED,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,oBAAoB,GAC7B,wBAAwB,CA+B1B;AAED;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,MAAM,EAChB,eAAe,CAAC,EAAE,MAAM,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAM1E;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,eAAe,CAAC,EAAE,MAAM,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAgE1E;AAED,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,gCAAgC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,cAAc,CAC5B,UAAU,EAAE,sBAAsB,EAClC,OAAO,EAAE,sBAAsB,GAC9B,qBAAqB,CAiCvB"}

package/dist/custom-checks.js

@@ -0,0 +1,260 @@
+/**
+ * Custom checks registry and report convention.
+ *
+ * A "custom check" is a deterministic, project-script-style validation a
+ * rule wants attached to it. The engine never executes the script unless
+ * the user explicitly opts in (`shrk checks run --execute`). The report
+ * convention is `sharkcraft.custom-check/v1`.
+ *
+ * Custom-check metadata lives on the rule entry under
+ * `metadata.checks: ICustomCheckDescriptor[]`. The engine never invents
+ * a check; we only inventory what authors declare.
+ *
+ * Hard rules:
+ *   - No spawning a process by default.
+ *   - Read-only inventory unless `--execute` is set explicitly.
+ *   - Three input formats supported: JSON-report (preferred), text
+ *     output, command-only (exit-code = signal).
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { KnowledgeType } from '@shrkcrft/knowledge';
+export const CUSTOM_CHECK_REPORT_SCHEMA = 'sharkcraft.custom-check/v1';
+export const CUSTOM_CHECKS_REGISTRY_SCHEMA = 'sharkcraft.custom-checks-registry/v1';
+export var CustomCheckScope;
+(function (CustomCheckScope) {
+    CustomCheckScope["ChangedOnly"] = "changed-only";
+    CustomCheckScope["Staged"] = "staged";
+    CustomCheckScope["All"] = "all";
+})(CustomCheckScope || (CustomCheckScope = {}));
+export var CustomCheckKind;
+(function (CustomCheckKind) {
+    CustomCheckKind["ImportGraph"] = "import-graph";
+    CustomCheckKind["AstShape"] = "ast-shape";
+    CustomCheckKind["TextShape"] = "text-shape";
+    CustomCheckKind["ProjectScript"] = "project-script";
+    CustomCheckKind["ExternalTool"] = "external-tool";
+})(CustomCheckKind || (CustomCheckKind = {}));
+export var CustomCheckSafety;
+(function (CustomCheckSafety) {
+    CustomCheckSafety["ReadOnly"] = "read-only";
+    CustomCheckSafety["WritesReport"] = "writes-report";
+    CustomCheckSafety["WritesPreview"] = "writes-preview";
+})(CustomCheckSafety || (CustomCheckSafety = {}));
+export var CustomCheckOutput;
+(function (CustomCheckOutput) {
+    CustomCheckOutput["Json"] = "json";
+    CustomCheckOutput["Text"] = "text";
+    CustomCheckOutput["ExitCode"] = "exit-code";
+})(CustomCheckOutput || (CustomCheckOutput = {}));
+export var CustomCheckStatus;
+(function (CustomCheckStatus) {
+    CustomCheckStatus["Pass"] = "pass";
+    CustomCheckStatus["Warn"] = "warn";
+    CustomCheckStatus["Fail"] = "fail";
+    CustomCheckStatus["Skipped"] = "skipped";
+})(CustomCheckStatus || (CustomCheckStatus = {}));
+const ID_RE = /^[a-z][a-z0-9.-]+$/;
+/** Read the descriptors a rule declares under `metadata.checks`. */
+export function readDescriptorsFromRule(rule) {
+    const md = rule.metadata;
+    const raw = md?.['checks'];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map((r) => ({ ...r, ownerRuleId: rule.id }));
+}
+export function buildCustomChecksRegistry(entries) {
+    const out = [];
+    const idIndex = new Map();
+    const invalid = [];
+    for (const e of entries) {
+        if (String(e.type) !== KnowledgeType.Rule)
+            continue;
+        const descriptors = readDescriptorsFromRule(e);
+        for (const d of descriptors) {
+            const warnings = [];
+            if (!d.id || typeof d.id !== 'string') {
+                invalid.push({ ruleId: e.id, reason: 'check entry missing string id' });
+                continue;
+            }
+            if (!ID_RE.test(d.id)) {
+                warnings.push(`id "${d.id}" should match ${ID_RE.source}`);
+            }
+            if (!d.command || typeof d.command !== 'string') {
+                invalid.push({ ruleId: e.id, reason: `check "${d.id}" missing command` });
+                continue;
+            }
+            if (d.output === CustomCheckOutput.Json && !d.reportPath) {
+                warnings.push(`check "${d.id}" declares JSON output but has no reportPath`);
+            }
+            if (d.safety === undefined) {
+                warnings.push(`check "${d.id}" did not declare safety; defaulting to read-only`);
+            }
+            const list = idIndex.get(d.id) ?? [];
+            list.push(e.id);
+            idIndex.set(d.id, list);
+            out.push({ descriptor: d, ruleId: e.id, warnings });
+        }
+    }
+    const duplicates = [];
+    for (const [id, ruleIds] of idIndex) {
+        if (ruleIds.length > 1)
+            duplicates.push({ id, ruleIds });
+    }
+    return {
+        schema: CUSTOM_CHECKS_REGISTRY_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        entries: out,
+        duplicates,
+        invalid,
+    };
+}
+export function doctorCustomChecks(registry) {
+    const details = [];
+    for (const inv of registry.invalid) {
+        details.push({ ruleId: inv.ruleId, checkId: '(invalid)', severity: 'error', message: inv.reason });
+    }
+    for (const dup of registry.duplicates) {
+        details.push({
+            ruleId: dup.ruleIds.join(','),
+            checkId: dup.id,
+            severity: 'error',
+            message: `duplicate check id "${dup.id}" declared by rules ${dup.ruleIds.join(', ')}`,
+        });
+    }
+    for (const e of registry.entries) {
+        for (const w of e.warnings) {
+            details.push({
+                ruleId: e.ruleId,
+                checkId: e.descriptor.id,
+                severity: 'warning',
+                message: w,
+            });
+        }
+    }
+    return {
+        schema: 'sharkcraft.custom-checks-doctor/v1',
+        generatedAt: new Date().toISOString(),
+        totalChecks: registry.entries.length,
+        warnings: details.filter((d) => d.severity === 'warning').length,
+        errors: details.filter((d) => d.severity === 'error').length,
+        details,
+    };
+}
+/**
+ * Parse a custom-check report from a known location. Supports the JSON
+ * convention (preferred), and a text fallback that turns each line into
+ * a `severity:warning, message: line` finding.
+ */
+export function parseCustomCheckReportFromFile(filePath, expectedCheckId) {
+    if (!existsSync(filePath)) {
+        return { ok: false, reason: `report file does not exist: ${filePath}` };
+    }
+    const raw = readFileSync(filePath, 'utf8');
+    return parseCustomCheckReport(raw, expectedCheckId);
+}
+export function parseCustomCheckReport(raw, expectedCheckId) {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0)
+        return { ok: false, reason: 'empty report' };
+    if (trimmed.startsWith('{')) {
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch (e) {
+            return { ok: false, reason: `JSON parse failed: ${e.message}` };
+        }
+        if (parsed['schema'] !== CUSTOM_CHECK_REPORT_SCHEMA) {
+            return {
+                ok: false,
+                reason: `report schema mismatch — got "${String(parsed['schema'])}" expected "${CUSTOM_CHECK_REPORT_SCHEMA}"`,
+            };
+        }
+        if (typeof parsed['checkId'] !== 'string') {
+            return { ok: false, reason: 'report missing checkId' };
+        }
+        if (expectedCheckId && parsed['checkId'] !== expectedCheckId) {
+            return {
+                ok: false,
+                reason: `report checkId "${String(parsed['checkId'])}" does not match expected "${expectedCheckId}"`,
+            };
+        }
+        const findingsRaw = Array.isArray(parsed['findings']) ? parsed['findings'] : [];
+        const findings = findingsRaw.map((f) => ({
+            severity: f['severity'] ?? 'warning',
+            file: typeof f['file'] === 'string' ? f['file'] : undefined,
+            message: typeof f['message'] === 'string' ? f['message'] : '(no message)',
+            suggestedAction: typeof f['suggestedAction'] === 'string' ? f['suggestedAction'] : undefined,
+            safeToAutoFix: typeof f['safeToAutoFix'] === 'boolean' ? f['safeToAutoFix'] : false,
+        }));
+        const status = parsed['status'] ?? CustomCheckStatus.Pass;
+        return {
+            ok: true,
+            report: {
+                schema: CUSTOM_CHECK_REPORT_SCHEMA,
+                checkId: parsed['checkId'],
+                ruleId: typeof parsed['ruleId'] === 'string' ? parsed['ruleId'] : undefined,
+                generatedAt: typeof parsed['generatedAt'] === 'string' ? parsed['generatedAt'] : new Date().toISOString(),
+                status,
+                findings,
+                metadata: parsed['metadata'] ?? undefined,
+            },
+        };
+    }
+    // Text fallback: every non-empty line becomes a finding.
+    const findings = trimmed
+        .split('\n')
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0)
+        .map((l) => ({ severity: 'warning', message: l }));
+    return {
+        ok: true,
+        report: {
+            schema: CUSTOM_CHECK_REPORT_SCHEMA,
+            checkId: expectedCheckId ?? '(text)',
+            generatedAt: new Date().toISOString(),
+            status: findings.length > 0 ? CustomCheckStatus.Warn : CustomCheckStatus.Pass,
+            findings,
+        },
+    };
+}
+export function runCustomCheck(descriptor, options) {
+    const result = {
+        schema: 'sharkcraft.custom-check-run/v1',
+        checkId: descriptor.id,
+        ownerRuleId: descriptor.ownerRuleId,
+        command: descriptor.command,
+        executed: false,
+        exitCode: null,
+    };
+    if (!options.execute) {
+        result.reason = 'execute flag not set; printing command only';
+        return result;
+    }
+    const child = spawnSync(descriptor.command, {
+        cwd: options.cwd,
+        shell: true,
+        encoding: 'utf8',
+        env: { ...process.env, ...(options.env ?? {}) },
+        timeout: options.timeoutMs ?? 60_000,
+        maxBuffer: 8 * 1024 * 1024,
+    });
+    result.executed = true;
+    result.exitCode = child.status ?? null;
+    if (child.stderr)
+        result.stderr = String(child.stderr).slice(0, 4_000);
+    if (child.stdout)
+        result.stdoutSummary = String(child.stdout).slice(0, 4_000);
+    const reportPath = options.reportPath ?? descriptor.reportPath;
+    if (reportPath) {
+        const abs = nodePath.isAbsolute(reportPath) ? reportPath : nodePath.resolve(options.cwd, reportPath);
+        const parsed = parseCustomCheckReportFromFile(abs, descriptor.id);
+        if (parsed.ok)
+            result.report = parsed.report;
+        else
+            result.reason = `parse failed: ${parsed.reason}`;
+    }
+    return result;
+}

package/dist/dashboard/dashboard-data.d.ts

@@ -0,0 +1,59 @@
+import type { IDashboardAdoptionResponse, IDashboardArchitectureResponse, IDashboardBoundaryResponse, IDashboardCapabilitiesResponse, IDashboardCommandsResponse, IDashboardCoverageResponse, IDashboardDoctorResponse, IDashboardDriftResponse, IDashboardGraphNodeResponse, IDashboardGraphPathResponse, IDashboardGraphResponse, IDashboardHealthResponse, IDashboardMcpResponse, IDashboardOnboardingResponse, IDashboardOverviewResponse, IDashboardPacksResponse, IDashboardPipelinesResponse, IDashboardPresetsResponse, IDashboardQualityResponse, IDashboardReportsResponse, IDashboardReviewResponse, IDashboardSafetyResponse, IDashboardScaffoldsResponse, IDashboardSchemasResponse, IDashboardSessionDetailResponse, IDashboardSessionsResponse, IDashboardStatsResponse } from '@shrkcrft/dashboard-api';
+import type { ISharkcraftInspection } from '../sharkcraft-inspector.js';
+import { type IQualityConfig } from '../quality-report.js';
+export declare function buildDashboardOverview(inspection: ISharkcraftInspection): Promise<IDashboardOverviewResponse>;
+export declare function buildDashboardDoctor(inspection: ISharkcraftInspection): IDashboardDoctorResponse;
+export declare function buildDashboardQuality(inspection: ISharkcraftInspection, options?: {
+    qualityConfig?: IQualityConfig;
+}): Promise<IDashboardQualityResponse>;
+export declare function buildDashboardSafety(inspection: ISharkcraftInspection, catalog: ReadonlyArray<{
+    command: string;
+    description: string;
+    category: string;
+    safetyLevel: string;
+    writesFiles: boolean;
+    writesSource: boolean;
+    runsShell: boolean;
+    requiresReview: boolean;
+    mcpAvailable: boolean;
+}>, mcpTools: ReadonlyArray<{
+    name: string;
+    description: string;
+}>): IDashboardSafetyResponse;
+export declare function buildDashboardCommands(catalog: ReadonlyArray<{
+    command: string;
+    description: string;
+    category: string;
+    safetyLevel: string;
+}>): IDashboardCommandsResponse;
+export declare function buildDashboardPacks(inspection: ISharkcraftInspection): IDashboardPacksResponse;
+export declare function buildDashboardPresets(inspection: ISharkcraftInspection): IDashboardPresetsResponse;
+export declare function buildDashboardPipelines(inspection: ISharkcraftInspection): IDashboardPipelinesResponse;
+export declare function buildDashboardSessions(projectRoot: string): IDashboardSessionsResponse;
+export declare function buildDashboardSessionDetail(projectRoot: string, sessionId: string): IDashboardSessionDetailResponse;
+export declare function buildDashboardArchitecture(inspection: ISharkcraftInspection): IDashboardArchitectureResponse;
+export declare function buildDashboardBoundaries(inspection: ISharkcraftInspection): IDashboardBoundaryResponse;
+export declare function buildDashboardDrift(inspection: ISharkcraftInspection): IDashboardDriftResponse;
+export declare function buildDashboardCoverage(inspection: ISharkcraftInspection): IDashboardCoverageResponse;
+export declare function buildDashboardGraph(inspection: ISharkcraftInspection): IDashboardGraphResponse;
+export declare function buildDashboardGraphNode(inspection: ISharkcraftInspection, id: string): IDashboardGraphNodeResponse;
+export declare function buildDashboardGraphPath(inspection: ISharkcraftInspection, from: string, to: string): IDashboardGraphPathResponse;
+export declare function buildDashboardOnboarding(inspection: ISharkcraftInspection): IDashboardOnboardingResponse;
+export declare function buildDashboardAdoption(inspection: ISharkcraftInspection): IDashboardAdoptionResponse;
+export declare function buildDashboardReports(inspection: ISharkcraftInspection): IDashboardReportsResponse;
+export declare function buildDashboardReview(_inspection: ISharkcraftInspection, options?: {
+    packetPath?: string;
+}): IDashboardReviewResponse;
+export declare function buildDashboardScaffolds(inspection: ISharkcraftInspection): Promise<IDashboardScaffoldsResponse>;
+export declare function buildDashboardSchemas(): IDashboardSchemasResponse;
+export declare function buildDashboardMcpSummary(toolNames: ReadonlyArray<{
+    name: string;
+    description?: string;
+}>): IDashboardMcpResponse;
+export declare function buildDashboardHealth(uptimeSeconds: number): IDashboardHealthResponse;
+export declare function buildDashboardStats(cwd: string, opts?: {
+    maxTopFiles?: number;
+    language?: string;
+}): Promise<IDashboardStatsResponse>;
+export declare function buildDashboardCapabilities(availability?: Partial<IDashboardCapabilitiesResponse>): IDashboardCapabilitiesResponse;
+//# sourceMappingURL=dashboard-data.d.ts.map

package/dist/dashboard/dashboard-data.d.ts.map

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