@shrkcrft/inspector 0.1.0-alpha.1

package/dist/spec/spec-cross-validate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cross-registry validation for a parsed `ISpecJson`.
+ *
+ * This is a thin shim that projects the spec.json view onto
+ * `IExtractedPlan` and delegates to the shared validator at
+ * `../grounding/validate-extracted-plan.ts`. The wire shape on the
+ * spec side is preserved verbatim so callers (`buildSpecReview`,
+ * the MCP `get_spec_review` tool) stay green.
+ */
+import { type ISpecJson, type ISpecValidationIssue } from '@shrkcrft/generator';
+import type { ISharkcraftInspection } from '../sharkcraft-inspector.js';
+export interface ISpecCrossValidation {
+    readonly errors: readonly ISpecValidationIssue[];
+    readonly warnings: readonly ISpecValidationIssue[];
+}
+export declare function validateSpecAgainstWorkspace(spec: ISpecJson, inspection: ISharkcraftInspection): ISpecCrossValidation;
+//# sourceMappingURL=spec-cross-validate.d.ts.map

package/dist/spec/spec-cross-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-cross-validate.d.ts","sourceRoot":"","sources":["../../src/spec/spec-cross-validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACpD;AAED,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,SAAS,EACf,UAAU,EAAE,qBAAqB,GAChC,oBAAoB,CAiCtB"}

package/dist/spec/spec-cross-validate.js

@@ -0,0 +1,53 @@
+/**
+ * Cross-registry validation for a parsed `ISpecJson`.
+ *
+ * This is a thin shim that projects the spec.json view onto
+ * `IExtractedPlan` and delegates to the shared validator at
+ * `../grounding/validate-extracted-plan.ts`. The wire shape on the
+ * spec side is preserved verbatim so callers (`buildSpecReview`,
+ * the MCP `get_spec_review` tool) stay green.
+ */
+import { EXTRACTED_PLAN_SCHEMA, } from '@shrkcrft/generator';
+import { validateExtractedPlan } from "../grounding/validate-extracted-plan.js";
+export function validateSpecAgainstWorkspace(spec, inspection) {
+    const extracted = {
+        schema: EXTRACTED_PLAN_SCHEMA,
+        source: spec.id,
+        extractorId: 'sharkcraft.spec/v1',
+        intent: spec.intent || undefined,
+        motivation: spec.motivation || undefined,
+        title: spec.title || undefined,
+        affectedFiles: spec.affectedAreas.files,
+        affectedPackages: spec.affectedAreas.packages,
+        acceptanceCriteria: spec.acceptanceCriteria.map((ac) => ({
+            id: ac.id,
+            text: ac.text,
+            verifiedBy: ac.verifiedBy,
+        })),
+        relevantRules: spec.relevantRules,
+        relevantKnowledge: spec.relevantKnowledge,
+        relevantPaths: spec.relevantPaths,
+        proposedTemplates: spec.proposedTemplates.map((t) => ({
+            templateId: t.templateId,
+            variables: t.variables,
+        })),
+        verificationCommandIds: spec.verificationCommands.map((v) => v.id),
+        raw: spec,
+    };
+    const result = validateExtractedPlan(extracted, inspection);
+    // The spec cross-validate emitted `verificationCommands[i].id` fields;
+    // the hoisted validator emits `verificationCommandIds[i]`. Project
+    // back so the spec wire shape is unchanged.
+    return {
+        errors: result.errors.map(remapVerificationField),
+        warnings: result.warnings.map(remapVerificationField),
+    };
+}
+function remapVerificationField(issue) {
+    if (!issue.field.startsWith('verificationCommandIds['))
+        return issue;
+    return {
+        ...issue,
+        field: issue.field.replace(/^verificationCommandIds\[(\d+)\]$/, 'verificationCommands[$1].id'),
+    };
+}

package/dist/spec/spec-discovery.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `shrk spec list` data layer.
+ *
+ * Walks `.sharkcraft/specs/` and returns summaries that the CLI / MCP
+ * tools render. Failure-soft: malformed specs surface as `error`
+ * entries with an inline reason rather than aborting the whole list.
+ */
+import { type SpecStatus } from '@shrkcrft/generator';
+export declare const SPEC_LIST_SCHEMA = "sharkcraft.spec-list/v1";
+export interface ISpecListEntrySummary {
+    readonly id: string;
+    readonly slug: string;
+    readonly title: string;
+    readonly status: SpecStatus | 'error';
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly hasPlan: boolean;
+    readonly hasVerification: boolean;
+    readonly error?: string;
+}
+export interface ISpecListReport {
+    readonly schema: typeof SPEC_LIST_SCHEMA;
+    readonly projectRoot: string;
+    readonly entries: readonly ISpecListEntrySummary[];
+}
+export declare function buildSpecList(projectRoot: string): ISpecListReport;
+//# sourceMappingURL=spec-discovery.d.ts.map

package/dist/spec/spec-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-discovery.d.ts","sourceRoot":"","sources":["../../src/spec/spec-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAQL,KAAK,UAAU,EAChB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,gBAAgB,4BAA4B,CAAC;AAE1D,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IACtC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,gBAAgB,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,SAAS,qBAAqB,EAAE,CAAC;CACpD;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAOlE"}

package/dist/spec/spec-discovery.js

@@ -0,0 +1,78 @@
+/**
+ * `shrk spec list` data layer.
+ *
+ * Walks `.sharkcraft/specs/` and returns summaries that the CLI / MCP
+ * tools render. Failure-soft: malformed specs surface as `error`
+ * entries with an inline reason rather than aborting the whole list.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { deriveSpecJson, listSpecIds, splitSpecMd, specMdPath, specPlanPath, specVerificationPath, } from '@shrkcrft/generator';
+export const SPEC_LIST_SCHEMA = 'sharkcraft.spec-list/v1';
+export function buildSpecList(projectRoot) {
+    const ids = listSpecIds(projectRoot);
+    const entries = [];
+    for (const id of ids) {
+        entries.push(loadSummary(projectRoot, id));
+    }
+    return { schema: SPEC_LIST_SCHEMA, projectRoot, entries };
+}
+function loadSummary(projectRoot, id) {
+    const mdPath = specMdPath(projectRoot, id);
+    if (!existsSync(mdPath)) {
+        return {
+            id,
+            slug: '',
+            title: '',
+            status: 'error',
+            createdAt: '',
+            updatedAt: '',
+            hasPlan: false,
+            hasVerification: false,
+            error: 'spec.md missing',
+        };
+    }
+    let parsed = null;
+    let errorMessage;
+    try {
+        const raw = readFileSync(mdPath, 'utf8');
+        const split = splitSpecMd(raw);
+        if (!split.ok) {
+            errorMessage = split.error.message;
+        }
+        else {
+            const derived = deriveSpecJson(split.value);
+            if (!derived.ok)
+                errorMessage = derived.error.message;
+            else
+                parsed = derived.value;
+        }
+    }
+    catch (e) {
+        errorMessage = e.message;
+    }
+    const hasPlan = existsSync(specPlanPath(projectRoot, id));
+    const hasVerification = existsSync(specVerificationPath(projectRoot, id));
+    if (!parsed) {
+        return {
+            id,
+            slug: '',
+            title: '',
+            status: 'error',
+            createdAt: '',
+            updatedAt: '',
+            hasPlan,
+            hasVerification,
+            error: errorMessage,
+        };
+    }
+    return {
+        id: parsed.id,
+        slug: parsed.slug,
+        title: parsed.title,
+        status: parsed.status,
+        createdAt: parsed.createdAt,
+        updatedAt: parsed.updatedAt,
+        hasPlan,
+        hasVerification,
+    };
+}

package/dist/spec/spec-review.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `shrk spec review` report assembly.
+ *
+ * Read-only. Combines structural validation (generator-side) with
+ * cross-registry validation (this package) and produces the
+ * `sharkcraft.spec-review/v1` envelope.
+ */
+import { type ISpecJson, type ISpecValidationIssue } from '@shrkcrft/generator';
+import type { ISharkcraftInspection } from '../sharkcraft-inspector.js';
+export declare const SPEC_REVIEW_SCHEMA = "sharkcraft.spec-review/v1";
+export interface ISpecReviewReport {
+    readonly schema: typeof SPEC_REVIEW_SCHEMA;
+    readonly specId: string;
+    readonly specPath: string;
+    readonly frontmatterHash: string;
+    readonly verdict: 'pass' | 'warn' | 'fail';
+    readonly errors: readonly ISpecValidationIssue[];
+    readonly warnings: readonly ISpecValidationIssue[];
+    readonly info: readonly ISpecValidationIssue[];
+    readonly predicted: {
+        readonly boundaryRisks: readonly {
+            from: string;
+            to: string;
+            reason: string;
+        }[];
+    };
+}
+export interface IBuildSpecReviewInput {
+    readonly spec: ISpecJson;
+    readonly specPath: string;
+    readonly body: string;
+    readonly inspection: ISharkcraftInspection;
+    readonly bodyMaxBytes?: number;
+}
+export declare function buildSpecReview(input: IBuildSpecReviewInput): ISpecReviewReport;
+//# sourceMappingURL=spec-review.d.ts.map

package/dist/spec/spec-review.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec-review.d.ts","sourceRoot":"","sources":["../../src/spec/spec-review.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,kBAAkB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE;QAClB,QAAQ,CAAC,aAAa,EAAE,SAAS;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,EAAE,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;KACjF,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,qBAAqB,GAAG,iBAAiB,CA6B/E"}

package/dist/spec/spec-review.js

@@ -0,0 +1,37 @@
+/**
+ * `shrk spec review` report assembly.
+ *
+ * Read-only. Combines structural validation (generator-side) with
+ * cross-registry validation (this package) and produces the
+ * `sharkcraft.spec-review/v1` envelope.
+ */
+import { validateSpecStructural, } from '@shrkcrft/generator';
+import { validateSpecAgainstWorkspace } from "./spec-cross-validate.js";
+export const SPEC_REVIEW_SCHEMA = 'sharkcraft.spec-review/v1';
+export function buildSpecReview(input) {
+    const structural = validateSpecStructural(input.spec, input.body, {
+        bodyMaxBytes: input.bodyMaxBytes,
+    });
+    const cross = validateSpecAgainstWorkspace(input.spec, input.inspection);
+    const errors = [...structural.errors, ...cross.errors];
+    const warnings = [...structural.warnings, ...cross.warnings];
+    const info = [];
+    const verdict = errors.length > 0 ? 'fail' : warnings.length > 0 ? 'warn' : 'pass';
+    return {
+        schema: SPEC_REVIEW_SCHEMA,
+        specId: input.spec.id,
+        specPath: input.specPath,
+        frontmatterHash: input.spec.frontmatterHash,
+        verdict,
+        errors,
+        warnings,
+        info,
+        predicted: {
+            boundaryRisks: input.spec.boundariesCheck.predicted.map((p) => ({
+                from: p.from,
+                to: p.to,
+                reason: p.reason,
+            })),
+        },
+    };
+}

package/dist/stability-map.d.ts

@@ -0,0 +1,62 @@
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import type { IImportGraphAnalysis } from './import-graph-analysis.js';
+import { type IAreaMap } from './area-map.js';
+export declare const STABILITY_MAP_SCHEMA = "sharkcraft.stability-map/v1";
+export declare enum StabilityKind {
+    Stable = "stable",
+    Experimental = "experimental",
+    Deprecated = "deprecated",
+    Legacy = "legacy",
+    Generated = "generated",
+    Internal = "internal",
+    PublicApi = "public-api",
+    HighRisk = "high-risk"
+}
+export interface IStabilityArea {
+    id: string;
+    path: string;
+    kind: StabilityKind;
+    /** Confidence the classification is correct. */
+    confidence: 'high' | 'medium' | 'low';
+    /** Signals that led to the classification. */
+    signals: readonly string[];
+    /** Fan-in (number of importers) when available. */
+    fanIn?: number;
+    /** Number of files in the area. */
+    fileCount: number;
+    /** Free-form note. */
+    note?: string;
+}
+export interface IStabilityMap {
+    schema: typeof STABILITY_MAP_SCHEMA;
+    projectRoot: string;
+    areas: readonly IStabilityArea[];
+    /** Index by kind for cheap lookups. */
+    byKind: Readonly<Record<StabilityKind, readonly IStabilityArea[]>>;
+    /** Limitations / sampling notes. */
+    limitations: readonly string[];
+}
+export interface IBuildStabilityMapOptions {
+    inspection: ISharkcraftInspection;
+    areaMap?: IAreaMap;
+    importGraph?: IImportGraphAnalysis;
+    /** Names of generated roots (relative paths) — areas under these are marked Generated. */
+    generatedRoots?: readonly string[];
+    /** Fan-in threshold above which an area is also flagged HighRisk. */
+    highFanInThreshold?: number;
+    /** Scan file contents for `@deprecated` / `@experimental` / Java `@Deprecated` / C# `[Obsolete]` / Rust `#[deprecated]` / Go `Deprecated:` / Python `warnings.warn(..., DeprecationWarning)`. Off by default for speed; on at depth>=deep. */
+    scanAnnotations?: boolean;
+    /** Max files to scan when annotation scan is enabled. Default 1000. */
+    annotationScanLimit?: number;
+    /** Max bytes per file to scan for annotations. Default 8192. */
+    annotationScanBytes?: number;
+    /** Include git-age signal — files older than this many days bias toward Stable; newer than this many days bias toward Experimental. Optional. */
+    gitAgeOldDays?: number;
+    gitAgeNewDays?: number;
+}
+export declare function buildStabilityMap(options: IBuildStabilityMapOptions): IStabilityMap;
+export declare function renderStabilityMapText(map: IStabilityMap): string;
+export declare function renderStabilityMapMarkdown(map: IStabilityMap): string;
+export declare function renderStabilityMapJson(map: IStabilityMap): string;
+export declare function getStabilityArea(map: IStabilityMap, id: string): IStabilityArea | undefined;
+//# sourceMappingURL=stability-map.d.ts.map

package/dist/stability-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stability-map.d.ts","sourceRoot":"","sources":["../src/stability-map.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAExD,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,oBAAY,aAAa;IACvB,MAAM,WAAW;IACjB,YAAY,iBAAiB;IAC7B,UAAU,eAAe;IACzB,MAAM,WAAW;IACjB,SAAS,cAAc;IACvB,QAAQ,aAAa;IACrB,SAAS,eAAe;IACxB,QAAQ,cAAc;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,aAAa,CAAC;IACpB,gDAAgD;IAChD,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IACtC,8CAA8C;IAC9C,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;IACjC,uCAAuC;IACvC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,cAAc,EAAE,CAAC,CAAC,CAAC;IACnE,oCAAoC;IACpC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,qBAAqB,CAAC;IAClC,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,oBAAoB,CAAC;IACnC,0FAA0F;IAC1F,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,8OAA8O;IAC9O,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,iJAAiJ;IACjJ,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA0FD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,yBAAyB,GACjC,aAAa,CAoNf;AA8BD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CA6BjE;AAED,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAkCrE;AAED,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAEjE;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAE3F"}