@shrkcrft/inspector 0.1.0-alpha.2

package/dist/docs-check.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `shrk docs check` — verify the docs / README content.
+ *
+ * Read-only. Verifies:
+ *  - required docs exist (`docs/<canonical>.md`)
+ *  - README contains required sections (heading keywords)
+ *  - relative docs links in README point to files that exist
+ *  - safety statement is present in README
+ *  - no obvious stale command references (when a catalog is provided)
+ *
+ * The check is intentionally minimal — it answers "would a new reader find
+ * the runnable bits?", not "are the docs prose-quality".
+ */
+export declare const DOCS_CHECK_SCHEMA = "sharkcraft.docs-check/v1";
+export interface IDocsCheckFinding {
+    code: 'required-doc-missing' | 'readme-section-missing' | 'readme-link-broken' | 'safety-statement-missing' | 'mcp-readonly-statement-missing' | 'stale-command-reference';
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    file?: string;
+    suggestion?: string;
+}
+export interface IDocsCheckReport {
+    schema: typeof DOCS_CHECK_SCHEMA;
+    generatedAt: string;
+    projectRoot: string;
+    findings: readonly IDocsCheckFinding[];
+    readmePresent: boolean;
+    docsFolderPresent: boolean;
+    requiredDocsPresent: number;
+    requiredDocsExpected: number;
+    ok: boolean;
+}
+export interface IBuildDocsCheckOptions {
+    /** Known CLI subcommand strings (e.g. ['shrk doctor', 'shrk brief']).
+     *  Used to detect stale references. */
+    knownCommands?: readonly string[];
+}
+export declare function buildDocsCheck(projectRoot: string, options?: IBuildDocsCheckOptions): IDocsCheckReport;
+export declare function renderDocsCheckText(report: IDocsCheckReport): string;
+//# sourceMappingURL=docs-check.d.ts.map

package/dist/docs-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-check.d.ts","sourceRoot":"","sources":["../src/docs-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EACA,sBAAsB,GACtB,wBAAwB,GACxB,oBAAoB,GACpB,0BAA0B,GAC1B,gCAAgC,GAChC,yBAAyB,CAAC;IAC9B,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACvC,aAAa,EAAE,OAAO,CAAC;IACvB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,EAAE,EAAE,OAAO,CAAC;CACb;AAwCD,MAAM,WAAW,sBAAsB;IACrC;2CACuC;IACvC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,sBAA2B,GACnC,gBAAgB,CA+IlB;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAepE"}

package/dist/docs-check.js

@@ -0,0 +1,221 @@
+/**
+ * `shrk docs check` — verify the docs / README content.
+ *
+ * Read-only. Verifies:
+ *  - required docs exist (`docs/<canonical>.md`)
+ *  - README contains required sections (heading keywords)
+ *  - relative docs links in README point to files that exist
+ *  - safety statement is present in README
+ *  - no obvious stale command references (when a catalog is provided)
+ *
+ * The check is intentionally minimal — it answers "would a new reader find
+ * the runnable bits?", not "are the docs prose-quality".
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const DOCS_CHECK_SCHEMA = 'sharkcraft.docs-check/v1';
+const REQUIRED_DOCS = [
+    'overview.md',
+    'philosophy.md',
+    'safety-model.md',
+    'testing.md',
+];
+const README_REQUIRED_KEYWORDS = ['quick demo', 'onboard', 'safety'];
+const README_SAFETY_KEYWORDS = ['mcp', 'read-only', 'never writes', 'safety'];
+function readSafe(file) {
+    if (!existsSync(file))
+        return null;
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function extractMarkdownLinks(body) {
+    const out = [];
+    const re = /\[([^\]]+)\]\(([^)]+)\)/g;
+    let m;
+    while ((m = re.exec(body))) {
+        out.push({ text: m[1], href: m[2] });
+    }
+    return out;
+}
+function safeReaddir(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+export function buildDocsCheck(projectRoot, options = {}) {
+    const findings = [];
+    const readmeFile = nodePath.join(projectRoot, 'README.md');
+    const readmeBody = readSafe(readmeFile);
+    const readmePresent = readmeBody !== null;
+    const docsDir = nodePath.join(projectRoot, 'docs');
+    const docsFolderPresent = existsSync(docsDir);
+    let requiredDocsPresent = 0;
+    for (const rel of REQUIRED_DOCS) {
+        const file = nodePath.join(docsDir, rel);
+        if (existsSync(file)) {
+            requiredDocsPresent += 1;
+        }
+        else {
+            findings.push({
+                code: 'required-doc-missing',
+                severity: 'error',
+                message: `Required doc missing: docs/${rel}`,
+                file: `docs/${rel}`,
+                suggestion: 'Add the canonical doc; release-readiness checks for it.',
+            });
+        }
+    }
+    if (readmePresent) {
+        const lower = readmeBody.toLowerCase();
+        for (const keyword of README_REQUIRED_KEYWORDS) {
+            if (!lower.includes(keyword)) {
+                findings.push({
+                    code: 'readme-section-missing',
+                    severity: 'warning',
+                    message: `README does not mention "${keyword}".`,
+                    file: 'README.md',
+                    suggestion: `Add a section that includes the word "${keyword}".`,
+                });
+            }
+        }
+        const safetyHits = README_SAFETY_KEYWORDS.filter((k) => lower.includes(k));
+        if (safetyHits.length < 2) {
+            findings.push({
+                code: 'safety-statement-missing',
+                severity: 'warning',
+                message: 'README does not include a clear safety statement.',
+                file: 'README.md',
+                suggestion: 'Add a paragraph that says MCP never writes and the CLI is the only write path.',
+            });
+        }
+        if (!lower.includes('mcp') || !lower.includes('read-only')) {
+            findings.push({
+                code: 'mcp-readonly-statement-missing',
+                severity: 'warning',
+                message: 'README does not explicitly state that MCP is read-only.',
+                file: 'README.md',
+                suggestion: 'Include the phrase "MCP is read-only" so adopters can scan-find it.',
+            });
+        }
+        // Validate internal links.
+        for (const link of extractMarkdownLinks(readmeBody)) {
+            if (/^https?:/.test(link.href) || link.href.startsWith('#'))
+                continue;
+            const target = link.href.split('#')[0];
+            const abs = nodePath.resolve(projectRoot, target);
+            if (!existsSync(abs)) {
+                findings.push({
+                    code: 'readme-link-broken',
+                    severity: 'warning',
+                    message: `README links to ${target} but that file does not exist.`,
+                    file: 'README.md',
+                    suggestion: `Either create ${target} or update the link.`,
+                });
+            }
+        }
+        // Detect stale `shrk …` references when a catalog is supplied.
+        if (options.knownCommands && options.knownCommands.length > 0) {
+            const knownSet = new Set(options.knownCommands);
+            const re = /\bshrk\s+([\w-]+(?:\s+[\w-]+)?)/g;
+            let m;
+            while ((m = re.exec(readmeBody))) {
+                const command = `shrk ${m[1].trim()}`;
+                // Allow partial prefix matches (some commands have arguments after).
+                let known = false;
+                for (const k of knownSet) {
+                    if (k === command || k.startsWith(command) || command.startsWith(k)) {
+                        known = true;
+                        break;
+                    }
+                }
+                if (!known) {
+                    findings.push({
+                        code: 'stale-command-reference',
+                        severity: 'info',
+                        message: `README references "${command}" which is not in the command catalog.`,
+                        file: 'README.md',
+                        suggestion: 'Check whether the command was renamed or removed.',
+                    });
+                }
+            }
+        }
+    }
+    else {
+        findings.push({
+            code: 'required-doc-missing',
+            severity: 'error',
+            message: 'README.md is missing at the project root.',
+            file: 'README.md',
+        });
+    }
+    // Cross-check docs/ for broken intra-doc links.
+    if (docsFolderPresent) {
+        for (const entry of safeReaddir(docsDir)) {
+            if (!entry.endsWith('.md'))
+                continue;
+            const file = nodePath.join(docsDir, entry);
+            try {
+                if (!statSync(file).isFile())
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            const body = readSafe(file);
+            if (!body)
+                continue;
+            for (const link of extractMarkdownLinks(body)) {
+                if (/^https?:/.test(link.href) || link.href.startsWith('#'))
+                    continue;
+                const target = link.href.split('#')[0];
+                const abs = nodePath.resolve(docsDir, target);
+                if (!existsSync(abs)) {
+                    findings.push({
+                        code: 'readme-link-broken',
+                        severity: 'info',
+                        message: `docs/${entry} links to ${target} but it does not exist.`,
+                        file: `docs/${entry}`,
+                        suggestion: `Either create ${target} or update the link.`,
+                    });
+                }
+            }
+        }
+    }
+    const ok = findings.filter((f) => f.severity === 'error').length === 0;
+    return {
+        schema: DOCS_CHECK_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        findings,
+        readmePresent,
+        docsFolderPresent,
+        requiredDocsPresent,
+        requiredDocsExpected: REQUIRED_DOCS.length,
+        ok,
+    };
+}
+export function renderDocsCheckText(report) {
+    const lines = [];
+    lines.push('# Docs check');
+    lines.push(`OK: ${report.ok ? 'yes' : 'no'}  · README present: ${report.readmePresent}`);
+    lines.push(`Required docs: ${report.requiredDocsPresent}/${report.requiredDocsExpected}`);
+    if (report.findings.length === 0) {
+        lines.push('No findings.');
+    }
+    else {
+        lines.push('Findings:');
+        for (const f of report.findings) {
+            lines.push(`  [${f.severity}] ${f.code}: ${f.message}`);
+            if (f.suggestion)
+                lines.push(`     → ${f.suggestion}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/doctor-acknowledgements.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Doctor acknowledgements.
+ *
+ * Thin layer on top of the suppression system: an "acknowledgement" is a
+ * suppression that REQUIRES a non-empty `reason` and an explicit expiry.
+ * The on-disk format is the same `sharkcraft/doctor.suppressions.json`, so
+ * existing tooling continues to work.
+ *
+ * Provides:
+ *   - `parseExpiresIn(value)` — `7d` / `48h` / `2w` → ISO date string.
+ *   - `buildAcknowledgement(input)` — validates reason + expiry and returns
+ *     a suppression entry that the existing save path accepts.
+ *   - `summarizeAcknowledgements(suppressions, now)` — splits live / expired
+ *     / suppression-only entries so a "doctor --fail-on-expired-acknowledgement"
+ *     run can decide the exit code.
+ *
+ * Read-only: no file mutation here; the CLI persistence calls
+ * `saveDoctorSuppressions` from the suppressions module.
+ */
+import type { IDoctorSuppressionEntry } from './doctor-suppressions.js';
+export declare const DOCTOR_ACKNOWLEDGEMENT_SCHEMA = "sharkcraft.doctor-acknowledgements/v1";
+export interface IBuildAcknowledgementInput {
+    /** Finding id (preferred) — matches the stable id from doctor-suppressions. */
+    id?: string;
+    /** Finding code/category (`actionhints-...`). */
+    code?: string;
+    /** Category bucket (`action-hint-quality`). */
+    category?: string;
+    /** Required free-form reason. */
+    reason: string;
+    /** Either `expiresAt` (ISO date) or `expiresIn` (`7d`, `48h`, `2w`). */
+    expiresAt?: string;
+    expiresIn?: string;
+    /** Permit acknowledging an error finding. Default false. */
+    allowError?: boolean;
+    /** Used to evaluate `expiresIn` against a reference clock. Defaults to now. */
+    now?: Date;
+}
+export interface IBuildAcknowledgementResult {
+    ok: boolean;
+    entry?: IDoctorSuppressionEntry;
+    error?: string;
+}
+/**
+ * Parse `7d`, `48h`, `2w` style relative durations into an ISO date string
+ * computed from `now`. Returns null if the value is unparsable.
+ */
+export declare function parseExpiresIn(value: string, now?: Date): string | null;
+export declare function buildAcknowledgement(input: IBuildAcknowledgementInput): IBuildAcknowledgementResult;
+export interface IAcknowledgementSummary {
+    /** Entries that look like acknowledgements (have reason + expiresAt). */
+    acknowledgements: ReadonlyArray<IDoctorSuppressionEntry>;
+    /** Entries with no expiry — bare suppressions, not acknowledgements. */
+    bareSuppressions: ReadonlyArray<IDoctorSuppressionEntry>;
+    /** Acknowledgements whose expiry already passed. */
+    expired: ReadonlyArray<IDoctorSuppressionEntry>;
+    /** Acknowledgements expiring within `expiringSoonDays`. */
+    expiringSoon: ReadonlyArray<IDoctorSuppressionEntry>;
+    /** Total active (non-expired) acknowledgement count. */
+    activeCount: number;
+}
+export interface ISummarizeOptions {
+    now?: Date;
+    /** Default 7. Acknowledgements within this window are flagged expiring soon. */
+    expiringSoonDays?: number;
+}
+export declare function summarizeAcknowledgements(entries: ReadonlyArray<IDoctorSuppressionEntry>, options?: ISummarizeOptions): IAcknowledgementSummary;
+export declare function renderAcknowledgementsText(summary: IAcknowledgementSummary): string;
+//# sourceMappingURL=doctor-acknowledgements.d.ts.map

package/dist/doctor-acknowledgements.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-acknowledgements.d.ts","sourceRoot":"","sources":["../src/doctor-acknowledgements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAExE,eAAO,MAAM,6BAA6B,0CAA0C,CAAC;AAErF,MAAM,WAAW,0BAA0B;IACzC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+EAA+E;IAC/E,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,MAAM,WAAW,2BAA2B;IAC1C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,uBAAuB,CAAC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,GAAG,IAAI,CAYnF;AAED,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,0BAA0B,GAChC,2BAA2B,CAgD7B;AAED,MAAM,WAAW,uBAAuB;IACtC,yEAAyE;IACzE,gBAAgB,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IACzD,wEAAwE;IACxE,gBAAgB,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IACzD,oDAAoD;IACpD,OAAO,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IAChD,2DAA2D;IAC3D,YAAY,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;IACrD,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,aAAa,CAAC,uBAAuB,CAAC,EAC/C,OAAO,GAAE,iBAAsB,GAC9B,uBAAuB,CAgCzB;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAwCnF"}

package/dist/doctor-acknowledgements.js

@@ -0,0 +1,150 @@
+export const DOCTOR_ACKNOWLEDGEMENT_SCHEMA = 'sharkcraft.doctor-acknowledgements/v1';
+const DURATION_RE = /^(\d+)\s*(d|day|days|h|hour|hours|w|week|weeks|m|min|minute|minutes)$/i;
+/**
+ * Parse `7d`, `48h`, `2w` style relative durations into an ISO date string
+ * computed from `now`. Returns null if the value is unparsable.
+ */
+export function parseExpiresIn(value, now = new Date()) {
+    const m = DURATION_RE.exec(value.trim());
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    if (!Number.isFinite(n) || n <= 0)
+        return null;
+    const unit = (m[2] ?? 'd').toLowerCase();
+    let ms;
+    if (unit.startsWith('w'))
+        ms = n * 7 * 24 * 60 * 60 * 1000;
+    else if (unit.startsWith('h'))
+        ms = n * 60 * 60 * 1000;
+    else if (unit.startsWith('m') && !unit.startsWith('mo'))
+        ms = n * 60 * 1000;
+    else
+        ms = n * 24 * 60 * 60 * 1000;
+    return new Date(now.getTime() + ms).toISOString();
+}
+export function buildAcknowledgement(input) {
+    const reason = (input.reason ?? '').trim();
+    if (reason.length === 0) {
+        return { ok: false, error: 'reason is required and must be non-empty' };
+    }
+    if (reason.toUpperCase().startsWith('TODO')) {
+        return {
+            ok: false,
+            error: 'reason starts with TODO; acknowledgements need a justification, not a placeholder',
+        };
+    }
+    if (!input.id && !input.code && !input.category) {
+        return { ok: false, error: 'one of id / code / category is required' };
+    }
+    let expiresAt = input.expiresAt;
+    if (!expiresAt && input.expiresIn) {
+        const parsed = parseExpiresIn(input.expiresIn, input.now ?? new Date());
+        if (!parsed) {
+            return {
+                ok: false,
+                error: `expiresIn "${input.expiresIn}" is not a duration (try 7d / 48h / 2w)`,
+            };
+        }
+        expiresAt = parsed;
+    }
+    if (!expiresAt) {
+        return {
+            ok: false,
+            error: 'an acknowledgement requires either --expires-at or --expires-in',
+        };
+    }
+    // Sanity-check the expiry is in the future (and not in the distant past).
+    const ts = new Date(expiresAt).getTime();
+    if (!Number.isFinite(ts)) {
+        return { ok: false, error: `expiresAt "${expiresAt}" is not a valid ISO date` };
+    }
+    const now = input.now ?? new Date();
+    if (ts <= now.getTime()) {
+        return { ok: false, error: `expiresAt "${expiresAt}" is already in the past` };
+    }
+    const entry = { reason };
+    if (input.id)
+        entry.id = input.id;
+    if (input.code)
+        entry.code = input.code;
+    if (input.category)
+        entry.category = input.category;
+    entry.expiresAt = expiresAt;
+    if (input.allowError)
+        entry.allowError = input.allowError;
+    return { ok: true, entry };
+}
+export function summarizeAcknowledgements(entries, options = {}) {
+    const now = options.now ?? new Date();
+    const window = (options.expiringSoonDays ?? 7) * 24 * 60 * 60 * 1000;
+    const acknowledgements = [];
+    const bareSuppressions = [];
+    const expired = [];
+    const expiringSoon = [];
+    for (const e of entries) {
+        if (!e.expiresAt) {
+            bareSuppressions.push(e);
+            continue;
+        }
+        const ts = new Date(e.expiresAt).getTime();
+        if (!Number.isFinite(ts)) {
+            bareSuppressions.push(e);
+            continue;
+        }
+        if (ts < now.getTime()) {
+            expired.push(e);
+            continue;
+        }
+        acknowledgements.push(e);
+        if (ts - now.getTime() <= window)
+            expiringSoon.push(e);
+    }
+    return {
+        acknowledgements,
+        bareSuppressions,
+        expired,
+        expiringSoon,
+        activeCount: acknowledgements.length,
+    };
+}
+export function renderAcknowledgementsText(summary) {
+    const lines = [];
+    lines.push('=== Doctor acknowledgements ===');
+    lines.push(`  active        ${summary.acknowledgements.length}`);
+    lines.push(`  expiringSoon  ${summary.expiringSoon.length}`);
+    lines.push(`  expired       ${summary.expired.length}`);
+    lines.push(`  bare-suppressions (no expiry) ${summary.bareSuppressions.length}`);
+    if (summary.acknowledgements.length > 0) {
+        lines.push('');
+        lines.push('Active:');
+        for (const e of summary.acknowledgements) {
+            lines.push(`  • ${describeKey(e)} [until ${e.expiresAt}] — ${e.reason}`);
+        }
+    }
+    if (summary.expiringSoon.length > 0) {
+        lines.push('');
+        lines.push('Expiring soon:');
+        for (const e of summary.expiringSoon) {
+            lines.push(`  • ${describeKey(e)} [until ${e.expiresAt}]`);
+        }
+    }
+    if (summary.expired.length > 0) {
+        lines.push('');
+        lines.push('Expired (re-evaluate):');
+        for (const e of summary.expired) {
+            lines.push(`  • ${describeKey(e)} [expired ${e.expiresAt}] — ${e.reason}`);
+        }
+    }
+    if (summary.bareSuppressions.length > 0) {
+        lines.push('');
+        lines.push('Bare suppressions (no expiry — consider converting to acknowledgements):');
+        for (const e of summary.bareSuppressions) {
+            lines.push(`  • ${describeKey(e)} — ${e.reason}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function describeKey(e) {
+    return e.id ?? e.code ?? e.category ?? '(unknown)';
+}

package/dist/doctor-result.d.ts

@@ -0,0 +1,51 @@
+export declare enum DoctorSeverity {
+    Ok = "ok",
+    Info = "info",
+    Warning = "warning",
+    Error = "error"
+}
+export interface IDoctorCheck {
+    id: string;
+    title: string;
+    severity: DoctorSeverity;
+    message: string;
+    fix?: string;
+    /**
+     * Optional warning-quality fields. Backwards compatible: every
+     * field is optional and existing checks render unchanged when absent.
+     *
+     *   - `category`: stable bucket (e.g. `action-hint-quality`,
+     *     `pack-doctor`, `boundary`). Used by `--hide` and acknowledgements.
+     *   - `code`: stable per-finding code (e.g. `missing-verification`).
+     *     Distinguishes related findings inside the same category.
+     *   - `recommendedFix`: a copy-pasteable command that addresses the
+     *     finding (e.g. `shrk fix preview --action-hints --target <id>`).
+     *   - `whyThisMatters`: a one-line explanation of the consequence of
+     *     ignoring the finding. Designed to fight "permanent yellow noise".
+     *   - `advisory`: true if the finding is for an advisory rule and
+     *     should be presented as informational rather than actionable.
+     */
+    category?: string;
+    code?: string;
+    recommendedFix?: string;
+    whyThisMatters?: string;
+    advisory?: boolean;
+}
+export interface IDoctorResult {
+    passed: boolean;
+    checks: readonly IDoctorCheck[];
+    summary: {
+        ok: number;
+        info: number;
+        warnings: number;
+        errors: number;
+        /**
+         * Count of checks marked `advisory: true` OR `severity: info`.
+         * These are the findings the default text render collapses behind
+         * `--show-advisory`. JSON consumers see the same count
+         * here without needing to re-derive it from `checks[]`.
+         */
+        advisoryCount?: number;
+    };
+}
+//# sourceMappingURL=doctor-result.d.ts.map

package/dist/doctor-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-result.d.ts","sourceRoot":"","sources":["../src/doctor-result.ts"],"names":[],"mappings":"AAAA,oBAAY,cAAc;IACxB,EAAE,OAAO;IACT,IAAI,SAAS;IACb,OAAO,YAAY;IACnB,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE;QACP,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,MAAM,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf;;;;;WAKG;QACH,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;CACH"}

package/dist/doctor-result.js

@@ -0,0 +1,7 @@
+export var DoctorSeverity;
+(function (DoctorSeverity) {
+    DoctorSeverity["Ok"] = "ok";
+    DoctorSeverity["Info"] = "info";
+    DoctorSeverity["Warning"] = "warning";
+    DoctorSeverity["Error"] = "error";
+})(DoctorSeverity || (DoctorSeverity = {}));

package/dist/doctor-suppressions.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Doctor warning noise control.
+ *
+ * Reads `sharkcraft/doctor.suppressions.json` (and, optionally, a
+ * `doctorSuppressions` field on `sharkcraft.config.ts`) and lets callers
+ * mark specific findings as suppressed.
+ *
+ * Rules:
+ *  - Suppressed findings are counted, not deleted. Renderers know to hide
+ *    them from the headline output but include the count in summary.
+ *  - Expired suppressions surface as a warning so authors notice.
+ *  - Errors are NOT suppressed unless the suppression explicitly marks
+ *    `allowError: true`. The aggregate output also tells the user that
+ *    one or more errors were force-suppressed.
+ *
+ * Schema: sharkcraft.doctor-suppressions/v1
+ */
+import type { IDoctorCheck, IDoctorResult } from './doctor-result.js';
+export declare const DOCTOR_SUPPRESSIONS_SCHEMA = "sharkcraft.doctor-suppressions/v1";
+export interface IDoctorSuppressionEntry {
+    /** Stable id of the finding (preferred match). */
+    id?: string;
+    /** Optional code/category — any finding with this code matches. */
+    code?: string;
+    /** Optional category bucket — matches against the derived category. */
+    category?: string;
+    /** Required reason for suppression — surfaces in audit output. */
+    reason: string;
+    /** Optional ISO date after which the suppression no longer applies. */
+    expiresAt?: string;
+    /** Set true to allow suppressing errors. Default false. */
+    allowError?: boolean;
+}
+export interface IDoctorSuppressionsConfig {
+    schema?: typeof DOCTOR_SUPPRESSIONS_SCHEMA;
+    doctorSuppressions: ReadonlyArray<IDoctorSuppressionEntry>;
+}
+export interface IDoctorFindingWithStableId extends IDoctorCheck {
+    /** Stable id derived from `id` + a hash slug for repeated rows. */
+    stableId: string;
+    /** Best-effort category derived from the id prefix. */
+    category: string;
+}
+export interface IDoctorFilteredResult {
+    schema: 'sharkcraft.doctor-filtered/v1';
+    passed: boolean;
+    checks: ReadonlyArray<IDoctorFindingWithStableId>;
+    suppressedChecks: ReadonlyArray<IDoctorFindingWithStableId>;
+    expiredSuppressions: ReadonlyArray<IDoctorSuppressionEntry>;
+    appliedSuppressions: ReadonlyArray<{
+        entry: IDoctorSuppressionEntry;
+        matched: number;
+    }>;
+    summary: {
+        ok: number;
+        info: number;
+        warnings: number;
+        errors: number;
+        suppressedWarnings: number;
+        suppressedInfo: number;
+        suppressedErrors: number;
+    };
+}
+export interface IDoctorFilterOptions {
+    focus?: ReadonlyArray<'errors' | 'warnings' | 'warnings-new' | 'info' | 'ok' | 'all'>;
+    hide?: ReadonlyArray<string>;
+    quietKnown?: boolean;
+    suppressions?: ReadonlyArray<IDoctorSuppressionEntry>;
+}
+/** Default file path for doctor suppressions. */
+export declare function doctorSuppressionsFile(projectRoot: string): string;
+export declare function loadDoctorSuppressions(projectRoot: string): IDoctorSuppressionsConfig;
+export declare function saveDoctorSuppressions(projectRoot: string, config: IDoctorSuppressionsConfig): string;
+/**
+ * Derive a stable id for a finding so the same warning can be suppressed
+ * across runs even when the message text shifts slightly.
+ */
+export declare function deriveStableId(check: IDoctorCheck): string;
+export declare function deriveCategory(check: IDoctorCheck): string;
+export declare function filterDoctorResult(doctor: IDoctorResult, options?: IDoctorFilterOptions): IDoctorFilteredResult;
+export interface IBuildSuppressionEntryInput {
+    /** Pass a stableId or finding code. */
+    id?: string;
+    code?: string;
+    category?: string;
+    reason: string;
+    expiresAt?: string;
+    allowError?: boolean;
+}
+export declare function buildSuppressionEntry(input: IBuildSuppressionEntryInput): IDoctorSuppressionEntry;
+//# sourceMappingURL=doctor-suppressions.d.ts.map

package/dist/doctor-suppressions.d.ts.map

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