@shrkcrft/inspector 0.1.0-alpha.2

package/dist/rounds.js

@@ -0,0 +1,172 @@
+/**
+ * Round snapshots and round-to-round diff.
+ *
+ * Each round captures a snapshot of the engine surface at HEAD:
+ *   - registered CLI commands (from COMMAND_CATALOG, name + description)
+ *   - registered MCP tools (from the audit list, name + description)
+ *   - docs/ filenames (top-level only)
+ *
+ * Snapshots live under `.sharkcraft/rounds/<id>/snapshot.json` plus a
+ * sibling `meta.json` with the round title and capture timestamp. The
+ * `diffRounds` helper loads two snapshots and renders the added /
+ * removed deltas — the actual answer to "what shipped in R<n> vs
+ * R<n-1>".
+ *
+ * Schemas:
+ *   `sharkcraft.round-snapshot/v1`
+ *   `sharkcraft.rounds-diff/v1`
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from 'node:fs';
+import * as nodePath from 'node:path';
+export const ROUND_SNAPSHOT_SCHEMA = 'sharkcraft.round-snapshot/v1';
+export const ROUNDS_DIFF_SCHEMA = 'sharkcraft.rounds-diff/v1';
+function roundsRoot(projectRoot) {
+    return nodePath.join(projectRoot, '.sharkcraft', 'rounds');
+}
+function roundDir(projectRoot, id) {
+    return nodePath.join(roundsRoot(projectRoot), id);
+}
+function collectTopLevelDocs(projectRoot) {
+    const docsDir = nodePath.join(projectRoot, 'docs');
+    if (!existsSync(docsDir))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(docsDir)) {
+        if (entry.startsWith('.'))
+            continue;
+        const abs = nodePath.join(docsDir, entry);
+        try {
+            const st = statSync(abs);
+            if (st.isFile() && entry.endsWith('.md'))
+                out.push(entry);
+        }
+        catch {
+            // skip
+        }
+    }
+    return out.sort();
+}
+export function captureRoundSnapshot(input) {
+    const snapshot = {
+        schema: ROUND_SNAPSHOT_SCHEMA,
+        id: input.id,
+        ...(input.title ? { title: input.title } : {}),
+        capturedAt: new Date().toISOString(),
+        commands: [...input.commands].sort((a, b) => a.name.localeCompare(b.name)),
+        mcpTools: [...input.mcpTools].sort((a, b) => a.name.localeCompare(b.name)),
+        docs: collectTopLevelDocs(input.projectRoot),
+    };
+    return snapshot;
+}
+export function writeRoundSnapshot(projectRoot, snapshot) {
+    const dir = roundDir(projectRoot, snapshot.id);
+    mkdirSync(dir, { recursive: true });
+    const snapshotFile = nodePath.join(dir, 'snapshot.json');
+    const metaFile = nodePath.join(dir, 'meta.json');
+    writeFileSync(snapshotFile, JSON.stringify(snapshot, null, 2) + '\n', 'utf8');
+    const meta = {
+        id: snapshot.id,
+        ...(snapshot.title ? { title: snapshot.title } : {}),
+        capturedAt: snapshot.capturedAt,
+    };
+    writeFileSync(metaFile, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+    return { snapshotFile, metaFile };
+}
+export function loadRoundSnapshot(projectRoot, id) {
+    const snapshotFile = nodePath.join(roundDir(projectRoot, id), 'snapshot.json');
+    if (!existsSync(snapshotFile))
+        return null;
+    try {
+        return JSON.parse(readFileSync(snapshotFile, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function listRoundIds(projectRoot) {
+    const root = roundsRoot(projectRoot);
+    if (!existsSync(root))
+        return [];
+    return readdirSync(root)
+        .filter((name) => {
+        try {
+            return statSync(nodePath.join(root, name)).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    })
+        .sort();
+}
+function diffByName(from, to) {
+    const fromNames = new Set(from.map((e) => e.name));
+    const toNames = new Set(to.map((e) => e.name));
+    return {
+        added: to.filter((e) => !fromNames.has(e.name)),
+        removed: from.filter((e) => !toNames.has(e.name)),
+    };
+}
+function diffStringSets(from, to) {
+    const fromSet = new Set(from);
+    const toSet = new Set(to);
+    return {
+        added: to.filter((e) => !fromSet.has(e)),
+        removed: from.filter((e) => !toSet.has(e)),
+    };
+}
+export function diffRounds(fromSnapshot, toSnapshot) {
+    const cmd = diffByName(fromSnapshot.commands, toSnapshot.commands);
+    const mcp = diffByName(fromSnapshot.mcpTools, toSnapshot.mcpTools);
+    const docs = diffStringSets(fromSnapshot.docs, toSnapshot.docs);
+    return {
+        schema: ROUNDS_DIFF_SCHEMA,
+        fromId: fromSnapshot.id,
+        toId: toSnapshot.id,
+        commandsAdded: cmd.added,
+        commandsRemoved: cmd.removed,
+        mcpToolsAdded: mcp.added,
+        mcpToolsRemoved: mcp.removed,
+        docsAdded: docs.added,
+        docsRemoved: docs.removed,
+    };
+}
+export function renderRoundsDiffMarkdown(diff) {
+    const lines = [];
+    lines.push(`# Rounds diff: ${diff.fromId} → ${diff.toId}`);
+    lines.push('');
+    lines.push(`schema: ${diff.schema}`);
+    lines.push('');
+    const section = (title, names) => {
+        lines.push(`## ${title} (${names.length})`);
+        lines.push('');
+        if (names.length === 0) {
+            lines.push('  (none)');
+        }
+        else {
+            for (const n of names)
+                lines.push(`  - \`${n.name}\` — ${n.description}`);
+        }
+        lines.push('');
+    };
+    section('Commands added', diff.commandsAdded);
+    section('Commands removed', diff.commandsRemoved);
+    section('MCP tools added', diff.mcpToolsAdded);
+    section('MCP tools removed', diff.mcpToolsRemoved);
+    lines.push(`## Docs added (${diff.docsAdded.length})`);
+    lines.push('');
+    if (diff.docsAdded.length === 0)
+        lines.push('  (none)');
+    else
+        for (const d of diff.docsAdded)
+            lines.push(`  - ${d}`);
+    lines.push('');
+    lines.push(`## Docs removed (${diff.docsRemoved.length})`);
+    lines.push('');
+    if (diff.docsRemoved.length === 0)
+        lines.push('  (none)');
+    else
+        for (const d of diff.docsRemoved)
+            lines.push(`  - ${d}`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/rule-drift.d.ts

@@ -0,0 +1,42 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+export declare const RULE_DRIFT_SCHEMA = "sharkcraft.rule-drift/v1";
+export declare enum RuleEnforcementState {
+    Enforced = "enforced",
+    PartiallyEnforced = "partially-enforced",
+    ManualOnly = "manual-only",
+    Aspirational = "aspirational",
+    Stale = "stale",
+    Unknown = "unknown"
+}
+export interface IRuleDriftEntry {
+    readonly id: string;
+    readonly title: string;
+    readonly type: string;
+    readonly priority: string;
+    readonly state: RuleEnforcementState;
+    /** Short, deterministic reason for the classification. */
+    readonly reason: string;
+    /** Verification commands declared on the rule. */
+    readonly declaredVerificationCommands: readonly string[];
+    /** Verification commands that are wired in `sharkcraft.config.ts`. */
+    readonly enforcedVerificationCommands: readonly string[];
+    /** True if the rule declares CLI/MCP action hints (used for ManualOnly). */
+    readonly hasActionHints: boolean;
+    /** True if the rule is `advisory:true` in its action hints / definition. */
+    readonly advisory: boolean;
+    /** Source: local file vs. pack name. */
+    readonly source: {
+        readonly type: 'local' | 'pack';
+        readonly packageName?: string;
+    };
+}
+export interface IRuleDriftReport {
+    readonly schema: typeof RULE_DRIFT_SCHEMA;
+    readonly generatedAt: string;
+    readonly entries: readonly IRuleDriftEntry[];
+    readonly summary: Readonly<Record<RuleEnforcementState, number>>;
+    /** Rule ids the caller can copy-paste into focus filters. */
+    readonly nextCommands: readonly string[];
+}
+export declare function classifyRuleDrift(inspection: ISharkcraftInspection): IRuleDriftReport;
+//# sourceMappingURL=rule-drift.d.ts.map

package/dist/rule-drift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-drift.d.ts","sourceRoot":"","sources":["../src/rule-drift.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE,eAAO,MAAM,iBAAiB,6BAA6B,CAAC;AAE5D,oBAAY,oBAAoB;IAC9B,QAAQ,aAAa;IACrB,iBAAiB,uBAAuB;IACxC,UAAU,gBAAgB;IAC1B,YAAY,iBAAiB;IAC7B,KAAK,UAAU;IACf,OAAO,YAAY;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;IACrC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,QAAQ,CAAC,4BAA4B,EAAE,SAAS,MAAM,EAAE,CAAC;IACzD,sEAAsE;IACtE,QAAQ,CAAC,4BAA4B,EAAE,SAAS,MAAM,EAAE,CAAC;IACzD,4EAA4E;IAC5E,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACrF;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAiDD,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,qBAAqB,GAChC,gBAAgB,CAuFlB"}

package/dist/rule-drift.js

@@ -0,0 +1,148 @@
+/**
+ * Rule enforcement classification.
+ *
+ * Answers the question maintainers can't otherwise answer: "which rules
+ * are actually enforced, and which are aspirational documentation?"
+ *
+ * The classification is deterministic — derived from each rule's
+ * `actionHints.verificationCommands`, the project's
+ * `sharkcraft.config.ts verificationCommands[]`, and existing drift
+ * (stale references) signals. No AI; no probabilistic scoring.
+ */
+import { KnowledgeType } from '@shrkcrft/knowledge';
+export const RULE_DRIFT_SCHEMA = 'sharkcraft.rule-drift/v1';
+export var RuleEnforcementState;
+(function (RuleEnforcementState) {
+    RuleEnforcementState["Enforced"] = "enforced";
+    RuleEnforcementState["PartiallyEnforced"] = "partially-enforced";
+    RuleEnforcementState["ManualOnly"] = "manual-only";
+    RuleEnforcementState["Aspirational"] = "aspirational";
+    RuleEnforcementState["Stale"] = "stale";
+    RuleEnforcementState["Unknown"] = "unknown";
+})(RuleEnforcementState || (RuleEnforcementState = {}));
+function configuredVerificationCommandIds(inspection) {
+    const cfg = inspection.config;
+    const ids = new Set();
+    for (const entry of cfg?.verificationCommands ?? []) {
+        if (entry?.id)
+            ids.add(entry.id);
+    }
+    return ids;
+}
+function isRule(entry) {
+    return entry.type === KnowledgeType.Rule;
+}
+function hasMeaningfulActionHints(entry) {
+    const a = entry.actionHints;
+    if (!a)
+        return false;
+    return Boolean((a.commands && a.commands.length) ||
+        (a.mcpTools && a.mcpTools.length) ||
+        (a.forbiddenActions && a.forbiddenActions.length) ||
+        (a.preferredFlow && a.preferredFlow.length));
+}
+function isAdvisory(entry) {
+    const flagged = entry.advisory === true;
+    if (flagged)
+        return true;
+    // Some packs encode advisory state through priority='low' + no verification.
+    return entry.priority === 'low' && !hasMeaningfulActionHints(entry);
+}
+function staleReason(entry, inspection) {
+    // Re-use the validation issues attached to the inspection — anything
+    // matching this entry id (broken anchor / missing reference / etc.) makes
+    // the rule stale.
+    for (const issue of inspection.validationIssues) {
+        if (issue.entryId === entry.id && issue.severity === 'error') {
+            return issue.message;
+        }
+    }
+    return null;
+}
+export function classifyRuleDrift(inspection) {
+    const wiredIds = configuredVerificationCommandIds(inspection);
+    const entries = [];
+    for (const entry of inspection.knowledgeEntries) {
+        if (!isRule(entry))
+            continue;
+        const declared = entry.actionHints?.verificationCommands ?? [];
+        const enforced = declared.filter((id) => wiredIds.has(id));
+        const advisory = isAdvisory(entry);
+        const stale = staleReason(entry, inspection);
+        const hasHints = hasMeaningfulActionHints(entry);
+        let state;
+        let reason;
+        if (stale) {
+            state = RuleEnforcementState.Stale;
+            reason = `stale reference: ${stale}`;
+        }
+        else if (advisory) {
+            state = RuleEnforcementState.Aspirational;
+            reason = 'advisory rule — no enforcement expected';
+        }
+        else if (declared.length > 0 && enforced.length === declared.length) {
+            state = RuleEnforcementState.Enforced;
+            reason = `all ${declared.length} verification command(s) wired in sharkcraft.config.ts`;
+        }
+        else if (declared.length > 0 && enforced.length > 0) {
+            state = RuleEnforcementState.PartiallyEnforced;
+            reason = `${enforced.length}/${declared.length} verification command(s) wired in sharkcraft.config.ts`;
+        }
+        else if (declared.length > 0) {
+            state = RuleEnforcementState.PartiallyEnforced;
+            reason = `${declared.length} verification command(s) declared but none wired in sharkcraft.config.ts`;
+        }
+        else if (hasHints) {
+            state = RuleEnforcementState.ManualOnly;
+            reason = 'has action hints (commands/mcpTools/forbiddenActions) but no verificationCommands';
+        }
+        else {
+            state = RuleEnforcementState.Aspirational;
+            reason = 'no verificationCommands and no action hints — documentation-only rule';
+        }
+        const sourceInfo = inspection.entrySources.get(entry.id);
+        entries.push({
+            id: entry.id,
+            title: entry.title,
+            type: entry.type,
+            priority: entry.priority,
+            state,
+            reason,
+            declaredVerificationCommands: declared,
+            enforcedVerificationCommands: enforced,
+            hasActionHints: hasHints,
+            advisory,
+            source: {
+                type: sourceInfo?.type ?? 'local',
+                ...(sourceInfo?.packageName ? { packageName: sourceInfo.packageName } : {}),
+            },
+        });
+    }
+    const summary = {
+        [RuleEnforcementState.Enforced]: 0,
+        [RuleEnforcementState.PartiallyEnforced]: 0,
+        [RuleEnforcementState.ManualOnly]: 0,
+        [RuleEnforcementState.Aspirational]: 0,
+        [RuleEnforcementState.Stale]: 0,
+        [RuleEnforcementState.Unknown]: 0,
+    };
+    for (const e of entries)
+        summary[e.state] += 1;
+    const nextCommands = [];
+    if (summary[RuleEnforcementState.PartiallyEnforced] > 0) {
+        nextCommands.push(`# Wire the missing verification commands in sharkcraft/sharkcraft.config.ts (verificationCommands[]).`);
+    }
+    if (summary[RuleEnforcementState.Stale] > 0) {
+        nextCommands.push(`shrk knowledge stale-check --ci`);
+    }
+    if (summary[RuleEnforcementState.Aspirational] > 0) {
+        nextCommands.push(`shrk rules doctor --strict`);
+    }
+    return {
+        schema: RULE_DRIFT_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        entries,
+        summary,
+        nextCommands,
+    };
+}

package/dist/rule-quality.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Rule quality doctor.
+ *
+ * Per-rule quality findings. Reuses `diagnoseActionHints` for the
+ * "missing-hints / missing-verification / missing-write-policy" axis,
+ * adds findings for:
+ *   - vague rules (very short content + no forbiddenActions + no examples)
+ *   - missing examples on style/architecture rules
+ *   - verificationCommands referencing scripts we cannot resolve
+ *   - rules tagged advisory but still missing the `metadata.advisory: true` marker
+ *
+ * Advisory rules (`metadata.advisory: true`) skip the
+ * "missing-verification" warning by design — that is the whole point.
+ */
+import { type IKnowledgeEntry } from '@shrkcrft/knowledge';
+export declare const RULE_QUALITY_SCHEMA = "sharkcraft.rule-quality/v1";
+export declare enum RuleQualityCode {
+    MissingHints = "missing-hints",
+    MissingCommandsOrMcp = "missing-commands-or-mcp",
+    MissingForbiddenActions = "missing-forbidden-actions",
+    MissingVerification = "missing-verification",
+    MissingWritePolicy = "missing-write-policy",
+    MissingExamples = "missing-examples",
+    MissingOwner = "missing-owner",
+    Vague = "vague-rule",
+    AdvisoryNotMarked = "advisory-not-marked",
+    AdvisoryHasUnusedVerification = "advisory-has-unused-verification",
+    VerificationReferencesUnknown = "verification-references-unknown-script"
+}
+export type RuleQualitySeverity = 'error' | 'warning' | 'info';
+export interface IRuleQualityFinding {
+    ruleId: string;
+    code: RuleQualityCode;
+    severity: RuleQualitySeverity;
+    message: string;
+    /** Suggested next action — either a CLI command or a free-form fix. */
+    recommendedFix?: string;
+    /** Why this matters — surfaces in the doctor output to fight noise. */
+    whyThisMatters: string;
+    /** Stable category so suppressions can target the family. */
+    category: 'rule-quality';
+    advisory: boolean;
+}
+export interface IRuleQualityReport {
+    schema: typeof RULE_QUALITY_SCHEMA;
+    generatedAt: string;
+    ruleCount: number;
+    evaluated: number;
+    findings: readonly IRuleQualityFinding[];
+    /**
+     * ids of rules with no findings — useful for "look at this concise list
+     * to see what's healthy" output.
+     */
+    cleanRules: readonly string[];
+    summary: {
+        errors: number;
+        warnings: number;
+        info: number;
+    };
+}
+export interface IRuleQualityOptions {
+    /** Limit the report to a single rule id. */
+    ruleId?: string;
+    /** Treat these rule ids as advisory (overrides metadata). */
+    advisoryRuleIds?: readonly string[];
+}
+export interface IRuleQualityContext {
+    /** ids registered in `sharkcraft.config.ts verificationCommands[]`. */
+    knownVerificationIds: ReadonlySet<string>;
+}
+export declare function diagnoseRuleQuality(rules: readonly IKnowledgeEntry[], options?: IRuleQualityOptions, context?: IRuleQualityContext): IRuleQualityReport;
+export declare function renderRuleQualityText(report: IRuleQualityReport): string;
+//# sourceMappingURL=rule-quality.d.ts.map

package/dist/rule-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule-quality.d.ts","sourceRoot":"","sources":["../src/rule-quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAG3E,eAAO,MAAM,mBAAmB,+BAA+B,CAAC;AAEhE,oBAAY,eAAe;IACzB,YAAY,kBAAkB;IAC9B,oBAAoB,4BAA4B;IAChD,uBAAuB,8BAA8B;IACrD,mBAAmB,yBAAyB;IAC5C,kBAAkB,yBAAyB;IAC3C,eAAe,qBAAqB;IACpC,YAAY,kBAAkB;IAC9B,KAAK,eAAe;IACpB,iBAAiB,wBAAwB;IACzC,6BAA6B,qCAAqC;IAClE,6BAA6B,2CAA2C;CACzE;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAE/D,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,cAAc,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACzC;;;OAGG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAoHD,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CAC3C;AAaD,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,eAAe,EAAE,EACjC,OAAO,GAAE,mBAAwB,EACjC,OAAO,GAAE,mBAAyD,GACjE,kBAAkB,CAyLpB;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAiCxE"}