@shrkcrft/inspector 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/recommend-recipes.js

@@ -0,0 +1,106 @@
+/**
+ * The recommender's built-in keyword recipes, matched through THE term
+ * matcher. The old table was unanchored regex alternations — `/review|pr|…/`
+ * matched `pr` inside "pricing", `/pack/` matched "package"/"packet",
+ * `/publish|release|tag|…/` matched "stage"/"vintage" — and a recipe that
+ * fired on a word fragment put a bogus row (and a bogus conflict note) into
+ * the headline.
+ */
+import { matchTerm } from "./match-terms.js";
+export const RECOMMEND_RECIPES = [
+    {
+        id: 'review',
+        terms: ['review', 'pr', 'prs'],
+        phrases: ['pull request'],
+        recommendations: [
+            { command: 'shrk review packet --v3 --since main', why: 'Generate an agent-ready PR review packet.' },
+            { command: 'shrk impact --since main', why: 'See what changed and what depends on it.' },
+            { command: 'shrk report site --output .sharkcraft/reports/site', why: 'Render the local read-only review site.' },
+        ],
+    },
+    {
+        id: 'start',
+        terms: ['start', 'begin', 'feature'],
+        phrases: ['new task'],
+        recommendations: [
+            { command: 'shrk brief "<task>"', why: 'Pre-work brief for the agent.' },
+            { command: 'shrk dev start "<task>"', why: 'Start a tracked dev session.' },
+            { command: 'shrk risk "<task>"', why: 'Classify the change intent and its risk first.' },
+        ],
+    },
+    {
+        id: 'release',
+        terms: ['publish', 'release', 'tag', 'alpha', 'beta'],
+        recommendations: [
+            { command: 'shrk release readiness --strict', why: 'Confirm release gates.' },
+            { command: 'shrk release smoke --scenario all', why: 'Validate the release smoke matrix.' },
+            { command: 'bun run release:preflight', why: 'Run the full preflight.' },
+        ],
+    },
+    {
+        id: 'packs',
+        terms: ['pack'],
+        recommendations: [
+            { command: 'shrk packs doctor --release --require-signatures', why: 'Validate discovered packs.' },
+            { command: 'shrk packs compat <pack> --consumer-root .', why: 'Detect helper/symbol-missing issues.' },
+            { command: 'shrk packs release-check <path>', why: 'Check the pack is release-ready.' },
+        ],
+    },
+    {
+        id: 'architecture',
+        terms: ['boundary', 'architecture', 'layer'],
+        recommendations: [
+            { command: 'shrk architecture map', why: 'Layered architecture summary.' },
+            { command: 'shrk check boundaries', why: 'Boundary scan.' },
+            { command: 'shrk drift', why: 'Drift report.' },
+        ],
+    },
+    {
+        id: 'code-intel',
+        terms: [],
+        regex: /\b(?:code[-\s]?intel|code intelligence|code graph|graph status|graph health|import cycle|unresolved import|blast radius|callers|dependents|who calls|who uses|where is .*\bused|find usages|usages? of|is .*\bwired|wired (?:up|to)|wire[ds]? .*\bto\b|path (?:from|between)|reach(?:es|able)|connected to|who implements|implementations? of|subclass|subtype|load[-\s]?bearing|hubs?\b|most[-\s](?:depended|imported|referenced)|what.*change carefully|important.*\b(?:code|files?|symbols?)|what breaks if|what calls|call sites?|trace .*\b(?:symbol|function|usage))/i,
+        recommendations: [
+            { command: 'shrk graph callers <symbol>', why: 'Who calls / references a symbol, as path:line — the grep replacement for "who calls X / where is X used".' },
+            { command: 'shrk graph path <from> <to>', why: 'Is code A actually wired to code B? Shortest import/call/implements path between two files or symbols — the deterministic answer to "is X wired to Y".' },
+            { command: 'shrk graph hubs', why: 'The most-depended-on symbols/files (biggest blast radius) — what to change carefully or understand first when onboarding.' },
+            { command: 'shrk graph context <file-or-symbol>', why: 'Inspect one file or symbol with imports, callers, subtypes/supertypes, bridge context, and framework hits — answers "is X wired".' },
+            { command: 'shrk graph impact <file-or-symbol> --full', why: 'What breaks if you change it: graph-backed dependents, caller files, rules, and likely tests.' },
+            { command: 'shrk code-intel', why: 'One-shot health view across the code graph, bridge, and quality gates.' },
+            { command: 'shrk graph status', why: 'Check whether the code graph is present, fresh, and internally consistent.' },
+            { command: 'shrk graph unresolved', why: 'Find unresolved imports that undercut graph accuracy.' },
+        ],
+    },
+    {
+        id: 'delegate',
+        terms: [],
+        regex: /\b(?:delegate|mechanical (?:edit|task|change|refactor)|grunt (?:work|task)|boilerplate|repetitive edit|hand (?:this|it|off) (?:off |over )?to (?:a |the )?(?:local |worker|model)|add (?:a |an )?(?:barrel )?(?:export|import)\b|local (?:llm|model) (?:do|handle|make))/i,
+        recommendations: [
+            { command: 'shrk delegate list', why: 'See the MECHANICAL task recipes a local-LLM worker can handle (the engine verifies the result + auto-reverts on failure). Each is fenced to specific files + op kinds.' },
+            { command: 'shrk delegate run "<task>" --recipe <id> --apply', why: 'Hand a mechanical, deterministically-verifiable edit to the LOCAL worker — you pay for a compact brief + result instead of reading the whole file and writing the edit. The edit lands only if it passes the recipe verification.' },
+            { command: 'shrk delegate explain <id>', why: 'Audit a recipe before trusting it: the allowed ops, guardrail globs, and whether its verification is bound.' },
+        ],
+    },
+];
+/**
+ * The evidence a recipe matched on — its matched terms and phrases, plus the
+ * regex's matched text — distinct. Empty = the recipe does not apply.
+ */
+export function matchRecommendRecipe(recipe, query, text) {
+    const out = [];
+    const add = (s) => {
+        if (!out.includes(s))
+            out.push(s);
+    };
+    for (const t of recipe.terms)
+        if (matchTerm(query, t))
+            add(t);
+    for (const p of recipe.phrases ?? [])
+        if (matchTerm(query, p))
+            add(p);
+    if (recipe.regex) {
+        const m = recipe.regex.exec(text);
+        if (m)
+            add(m[0].trim().toLowerCase());
+    }
+    return out;
+}

package/dist/recommendation-candidate.d.ts

@@ -0,0 +1,30 @@
+import type { RecommendationSource } from './recommendation-source.js';
+import type { RecommendationSuppression } from './recommendation-suppression.js';
+/** One candidate command in THE recommendation ranking. */
+export interface IRecommendationCandidate {
+    readonly command: string;
+    readonly why: string;
+    readonly safetyLevel: 'read-only' | 'writes-drafts' | 'writes-session' | 'writes-source' | 'runs-shell';
+    readonly source: RecommendationSource;
+    /** Hint id, recipe id, template/pipeline id, diagnostic code, plan verb, or change-intent kind. */
+    readonly sourceId?: string;
+    /** The source's own score (hint score, rankAll score, 2 × recipe terms, …). */
+    readonly rawScore: number;
+    /** The source's own floor (`RECOMMEND_SOURCE_FLOORS`). */
+    readonly sourceFloor: number;
+    /** rawScore / sourceFloor, 2 decimals: 1.0 = "just strong enough" for any source. */
+    readonly normalisedScore: number;
+    /** The evidence: matched query terms (ranker, recipe) or hint reasons. */
+    readonly matchedTerms: readonly string[];
+    readonly writesSource: boolean;
+    /** Below the confidence floor — a guess, never a route. */
+    readonly weak: boolean;
+    /** Set when the candidate is kept out of the list (see {@link RecommendationSuppression}). */
+    readonly suppressedReason?: RecommendationSuppression;
+    /** One-line attribution, e.g. `routing hint "billing-refactor" (score 7, floor 3)`. */
+    readonly attribution: string;
+    /** Attributions of other sources that proposed the same command (deduped into this row). */
+    readonly alsoProposedBy?: readonly string[];
+    readonly docsLink?: string;
+}
+//# sourceMappingURL=recommendation-candidate.d.ts.map

package/dist/recommendation-candidate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-candidate.d.ts","sourceRoot":"","sources":["../src/recommendation-candidate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iCAAiC,CAAC;AAEjF,2DAA2D;AAC3D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,eAAe,GAAG,gBAAgB,GAAG,eAAe,GAAG,YAAY,CAAC;IACxG,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,mGAAmG;IACnG,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,8FAA8F;IAC9F,QAAQ,CAAC,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;IACtD,uFAAuF;IACvF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/dist/recommendation-candidate.js

@@ -0,0 +1 @@
+export {};

package/dist/recommendation-confidence.d.ts

@@ -0,0 +1,27 @@
+import type { MatchConfidenceVerdict } from '@shrkcrft/core';
+import type { RecommendationSource } from './recommendation-source.js';
+import type { IUncertaintySignalDetail } from './uncertainty-report.js';
+/**
+ * `deriveRecommendationConfidence`'s answer — THE confidence for recommend,
+ * MCP `recommend_commands` and `shrk context`, derived from the same scores
+ * the list is ranked by. Carries the shared vocabulary (`confident`,
+ * `verdict`, `floor`, `bestScore`) reuse and playbooks use too.
+ */
+export interface IRecommendationConfidence {
+    /** Some eligible candidate from a counting source cleared the floor. */
+    readonly confident: boolean;
+    readonly verdict: MatchConfidenceVerdict;
+    /** The floor multiplier, in normalised units (1.0 = each source's own floor). */
+    readonly floor: number;
+    /** The best eligible counting candidate's normalised score; 0 when there is none. */
+    readonly bestScore: number;
+    readonly bestSource?: RecommendationSource;
+    readonly bestSourceId?: string;
+    readonly level: 'high' | 'medium' | 'low' | 'unknown';
+    readonly reasons: readonly string[];
+    readonly missingSignals: readonly IUncertaintySignalDetail[];
+    readonly conflictingSignals: readonly IUncertaintySignalDetail[];
+    readonly whatWouldIncreaseConfidence: readonly string[];
+    readonly warnings: readonly string[];
+}
+//# sourceMappingURL=recommendation-confidence.d.ts.map

package/dist/recommendation-confidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-confidence.d.ts","sourceRoot":"","sources":["../src/recommendation-confidence.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAExE;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,iFAAiF;IACjF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,qFAAqF;IACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC7D,QAAQ,CAAC,kBAAkB,EAAE,SAAS,wBAAwB,EAAE,CAAC;IACjE,QAAQ,CAAC,2BAA2B,EAAE,SAAS,MAAM,EAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC"}

package/dist/recommendation-confidence.js

@@ -0,0 +1 @@
+export {};

package/dist/recommendation-ranking-options.d.ts

@@ -0,0 +1,24 @@
+import type { ICommandSafety } from './i-command-safety.js';
+/** Options for `rankRecommendationCandidates`. */
+export interface IRecommendationRankingOptions {
+    /** A stderr blob: diagnostics matching it become candidates. */
+    readonly fromError?: string;
+    /**
+     * Floor multiplier (> 0), in normalised units: 1.0 = each source's own
+     * floor. Beats config `recommend.minScore`; defaults to 1.
+     */
+    readonly minScore?: number;
+    /** Override config `recommend.scaffoldRequiresCreateIntent` (default true). */
+    readonly scaffoldRequiresCreateIntent?: boolean;
+    /**
+     * THE declared safety of a command — injected by the CLI from its command
+     * catalog (the inspector cannot import it), exactly as the command resolver
+     * is injected into the reference registry. Wins over the `commandSafetyLevel`
+     * regex, which stays only the fallback (`undefined` = uncatalogued). Round 11
+     * review: the regex alone called `generated update`, `baseline update`,
+     * `check wiring --fix` and 12 other catalog writers read-only, so the
+     * not-confident withhold gate never withheld them.
+     */
+    readonly safetyOf?: (command: string) => ICommandSafety | undefined;
+}
+//# sourceMappingURL=recommendation-ranking-options.d.ts.map

package/dist/recommendation-ranking-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-ranking-options.d.ts","sourceRoot":"","sources":["../src/recommendation-ranking-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,kDAAkD;AAClD,MAAM,WAAW,6BAA6B;IAC5C,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,4BAA4B,CAAC,EAAE,OAAO,CAAC;IAChD;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;CACrE"}

package/dist/recommendation-ranking-options.js

@@ -0,0 +1 @@
+export {};

package/dist/recommendation-ranking.d.ts

@@ -0,0 +1,50 @@
+import type { IQueryIntentResult } from './query-intent-result.js';
+import type { IRankedRecommendations } from './ranked-recommendations.js';
+import type { IRecommendationCandidate } from './recommendation-candidate.js';
+import type { IRecommendationConfidence } from './recommendation-confidence.js';
+import type { IRecommendationRankingOptions } from './recommendation-ranking-options.js';
+import { RecommendationSource } from './recommendation-source.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * Each source's own floor, in its own raw units — the ONE table that replaced
+ * the inspector's 6/8 promote thresholds and the CLI's 3 (hint promote) and
+ * 3/3 (engine match) thresholds.
+ */
+export declare const RECOMMEND_SOURCE_FLOORS: Readonly<Record<RecommendationSource, number>>;
+/** Planning and the intent fallback never make an answer confident. */
+export declare function countsTowardConfidence(source: RecommendationSource): boolean;
+/** The floor multiplier: explicit (CLI `--min-score` / MCP `minScore`) > config `recommend.minScore` > 1. */
+export declare function resolveRecommendFloor(inspection: ISharkcraftInspection, explicit?: number): number;
+/** THE one-line attribution of a candidate, e.g. `routing hint "billing-refactor" (score 7, floor 3)`. */
+export declare function describeRecommendationSource(c: Pick<IRecommendationCandidate, 'source' | 'sourceId' | 'rawScore' | 'sourceFloor'>): string;
+/** THE wording of why a candidate was kept out of the list. */
+export declare function describeSuppression(c: IRecommendationCandidate, intent?: IQueryIntentResult): string;
+/**
+ * THE confidence authority for recommend, MCP `recommend_commands` and
+ * `shrk context` — a function of the ranked scores, never of which code path
+ * produced a row:
+ *   - no eligible counting candidate at or above the floor → `confident:
+ *     false`; verdict `no-confident-match` (or `no-match` when no source
+ *     produced anything), level `low` / `unknown`;
+ *   - the top is the shared ranker and a built-in recipe also cleared its
+ *     floor → `medium`, `conflict-recipe-vs-ranker` and a `review:` warning;
+ *   - a different-command runner-up from another source within 25% of the
+ *     top → `medium` with a conflicting signal;
+ *   - otherwise `high`.
+ */
+export declare function deriveRecommendationConfidence(candidates: readonly IRecommendationCandidate[], floor: number): IRecommendationConfidence;
+/**
+ * THE "what do I run first?" pick, over the FINAL rendered rows (the CLI calls
+ * it again after surface gating): when confident, the first non-weak row;
+ * otherwise the read-only planning / intent-fallback row, else
+ * `shrk start-here` — never a writes-source guess.
+ */
+export declare function pickNextCommand(rows: readonly {
+    readonly command: string;
+    readonly weak?: boolean;
+    readonly safetyLevel: string;
+    readonly source?: string;
+}[], confident: boolean): string;
+/** Build THE ranked recommendation list for a query. See the module comment. */
+export declare function rankRecommendationCandidates(inspection: ISharkcraftInspection, query: string, opts?: IRecommendationRankingOptions): Promise<IRankedRecommendations>;
+//# sourceMappingURL=recommendation-ranking.d.ts.map

package/dist/recommendation-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recommendation-ranking.d.ts","sourceRoot":"","sources":["../src/recommendation-ranking.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAE1E,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAC9E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,qCAAqC,CAAC;AACzF,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAAC,CAYlF,CAAC;AA6BF,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAE5E;AAED,6GAA6G;AAC7G,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,qBAAqB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAKlG;AAqBD,0GAA0G;AAC1G,wBAAgB,4BAA4B,CAC1C,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC,GACpF,MAAM,CAYR;AAED,+DAA+D;AAC/D,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,wBAAwB,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAapG;AA0GD;;;;;;;;;;;;GAYG;AACH,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,SAAS,wBAAwB,EAAE,EAC/C,KAAK,EAAE,MAAM,GACZ,yBAAyB,CAwG3B;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,SAAS;IACb,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,EAAE,EACH,SAAS,EAAE,OAAO,GACjB,MAAM,CAWR;AAED,gFAAgF;AAChF,wBAAsB,4BAA4B,CAChD,UAAU,EAAE,qBAAqB,EACjC,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,6BAAkC,GACvC,OAAO,CAAC,sBAAsB,CAAC,CAgMjC"}