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

package/dist/pack-doctor-verdict.d.ts

@@ -0,0 +1,29 @@
+import { type IVerdictCoverage } from '@shrkcrft/core';
+import type { IPackDoctorVerdict } from './i-pack-doctor-verdict.js';
+import type { IPackDoctorReport } from './pack-doctor.js';
+import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+/**
+ * What a pack-doctor run examined, as coverage records:
+ *
+ *   - `packs` — the discovered packs. ZERO is an empty selection: "nothing to
+ *     examine", never a pass. `emptyAcceptance` is the CLI verb's
+ *     `--allow-empty` valve (`allowEmptyValve(args, discovered)`); every other
+ *     reader passes nothing.
+ *   - `compiled artifacts` — a pack's compiled build with no build record was
+ *     never compared to its source (the doctor derives this from the one
+ *     freshness authority).
+ */
+export declare function packDoctorCoverage(report: Pick<IPackDoctorReport, 'compiledArtifactCoverage'>, inspection: ISharkcraftInspection, emptyAcceptance?: Pick<IVerdictCoverage, 'acceptedBy'>): IVerdictCoverage[];
+/**
+ * THE settlement of one pack-doctor run, next to `doctorVerdict`:
+ * `IPackDoctorReport.passed` stays errors-only (its long-standing meaning);
+ * the verdict is core's `settleVerdict` over {@link packDoctorCoverage}.
+ *
+ * `shrk packs doctor`, MCP `doctor_packs`, the quality packs gate (`shrk
+ * quality`, MCP `get_quality_report`, the dashboard, the report site) and bare
+ * `shrk check` read this — round 11 review: the 0-packs / compiled-artifact
+ * settlement lived inline in the verb, and the other four read `passed: true`
+ * over ZERO packs.
+ */
+export declare function packDoctorVerdict(report: Pick<IPackDoctorReport, 'passed' | 'compiledArtifactCoverage'>, inspection: ISharkcraftInspection, emptyAcceptance?: Pick<IVerdictCoverage, 'acceptedBy'>): IPackDoctorVerdict;
+//# sourceMappingURL=pack-doctor-verdict.d.ts.map

package/dist/pack-doctor-verdict.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-doctor-verdict.d.ts","sourceRoot":"","sources":["../src/pack-doctor-verdict.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACtE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AACrE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAEvE;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,0BAA0B,CAAC,EAC3D,UAAU,EAAE,qBAAqB,EACjC,eAAe,GAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAM,GACzD,gBAAgB,EAAE,CAcpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,QAAQ,GAAG,0BAA0B,CAAC,EACtE,UAAU,EAAE,qBAAqB,EACjC,eAAe,GAAE,IAAI,CAAC,gBAAgB,EAAE,YAAY,CAAM,GACzD,kBAAkB,CAKpB"}

package/dist/pack-doctor-verdict.js

@@ -0,0 +1,45 @@
+import { settleVerdict } from '@shrkcrft/core';
+/**
+ * What a pack-doctor run examined, as coverage records:
+ *
+ *   - `packs` — the discovered packs. ZERO is an empty selection: "nothing to
+ *     examine", never a pass. `emptyAcceptance` is the CLI verb's
+ *     `--allow-empty` valve (`allowEmptyValve(args, discovered)`); every other
+ *     reader passes nothing.
+ *   - `compiled artifacts` — a pack's compiled build with no build record was
+ *     never compared to its source (the doctor derives this from the one
+ *     freshness authority).
+ */
+export function packDoctorCoverage(report, inspection, emptyAcceptance = {}) {
+    const discovered = inspection.packs.discoveredPacks.length;
+    const coverage = [
+        {
+            unit: 'packs',
+            expected: discovered,
+            examined: discovered,
+            root: inspection.projectRoot,
+            reason: 'no installed package declares a `sharkcraft` field in its package.json',
+            ...emptyAcceptance,
+        },
+    ];
+    if (report.compiledArtifactCoverage)
+        coverage.push(report.compiledArtifactCoverage);
+    return coverage;
+}
+/**
+ * THE settlement of one pack-doctor run, next to `doctorVerdict`:
+ * `IPackDoctorReport.passed` stays errors-only (its long-standing meaning);
+ * the verdict is core's `settleVerdict` over {@link packDoctorCoverage}.
+ *
+ * `shrk packs doctor`, MCP `doctor_packs`, the quality packs gate (`shrk
+ * quality`, MCP `get_quality_report`, the dashboard, the report site) and bare
+ * `shrk check` read this — round 11 review: the 0-packs / compiled-artifact
+ * settlement lived inline in the verb, and the other four read `passed: true`
+ * over ZERO packs.
+ */
+export function packDoctorVerdict(report, inspection, emptyAcceptance = {}) {
+    const coverage = packDoctorCoverage(report, inspection, emptyAcceptance);
+    const settled = settleVerdict(report.passed ? 0 : 1, coverage);
+    const packsDiscovered = inspection.packs.discoveredPacks.length;
+    return { ...settled, coverage, packsDiscovered, examinedNothing: packsDiscovered === 0 };
+}

package/dist/pack-doctor.d.ts

@@ -1,9 +1,26 @@
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import type { IVerdictCoverage } from '@shrkcrft/core';
+import type { IDeclaredXrefReport } from './i-declared-xref-report.js';
 import { type IPackReleaseCheck } from './pack-release-check.js';
+import { type IContributionLoadFailure } from './contribution-load-failures.js';
+import { ContributionKind } from './contribution-kind.js';
+import type { IRegistryOutcomes } from './i-registry-outcomes.js';
+import { type IUnregisteredExport } from './unregistered-exports.js';
+import type { ITypecheckFilesResult } from './typecheck-files.js';
 export interface IPackDoctorIssue {
     severity: 'error' | 'warning' | 'info';
     packageName: string;
-    code: 'invalid-manifest' | 'missing-contribution-file' | 'empty-resolved-contributions' | 'duplicate-id-local' | 'duplicate-id-pack-internal' | 'template-no-description' | 'pipeline-no-steps' | 'critical-rule-no-hints' | 'docs-file-missing' | 'unsigned-pack' | 'tampered-pack' | 'signature-unverifiable' | 'dev-signature-not-trusted' | 'preset-composition-cycle' | 'preset-composed-not-found' | 'preset-missing-ref' | 'preset-no-includes' | 'pack-verification-pm-mismatch' | 'release-manifest-issue' | 'release-contribution-issue' | 'release-signature-issue' | 'release-files-issue' | 'release-readiness-issue';
+    code: 'invalid-manifest' | 'missing-contribution-file' | 'empty-resolved-contributions' | 'duplicate-id-local' | 'duplicate-id-pack-internal' | 'template-no-description' | 'pipeline-no-steps' | 'critical-rule-no-hints' | 'docs-file-missing' | 'unsigned-pack' | 'tampered-pack' | 'signature-unverifiable' | 'dev-signature-not-trusted' | 'preset-composition-cycle' | 'preset-composed-not-found' | 'preset-missing-ref' | 'preset-no-includes' | 'pack-verification-pm-mismatch' | 'release-manifest-issue' | 'release-contribution-issue' | 'release-signature-issue' | 'release-files-issue' | 'release-readiness-issue' | 'contribution-load-failed'
+    /** Round 12 (12.1): entries a contribution file declares that its loader refused. */
+     | 'contribution-entries-rejected' | 'partially-resolved-contributions' | 'compiled-artifacts-stale' | 'compiled-artifacts-unrecorded' | 'unregistered-export' | 'typecheck-error' | 'typecheck-not-run'
+    /** A pack-contributed asset names a cross-reference id no registry has. */
+     | 'pack-xref-dangling'
+    /** …names an id that resolves only in a kind the field does not accept. */
+     | 'pack-xref-wrong-kind'
+    /** …names ids that could not be looked up (registry not warmed / empty). */
+     | 'pack-xref-unverified'
+    /** A declaration problem: unknown facet kind, supersession cycle / chain, malformed field. */
+     | 'pack-xref-invalid';
     message: string;
     /** Free-form suggestion. */
     suggestion?: string;
@@ -21,6 +38,20 @@ export interface IPackDoctorReport {
     };
     /** Optional release-check payload per pack (populated when --release was passed). */
     releaseChecks?: readonly IPackReleaseCheck[];
+    /** Per-pack typecheck results when the opt-in `--typecheck` ran (callers derive coverage from them). */
+    typecheckResults?: readonly {
+        readonly packageName: string;
+        readonly result: ITypecheckFilesResult;
+    }[];
+    /**
+     * Compiled contribution artifacts that HAVE a source, and how many of them a
+     * build record (source-map `sourcesContent` or signed digests) let the
+     * freshness authority compare. An `unrecorded` artifact was never examined,
+     * so a verdict over it is NOT VERIFIED. Absent when no pack ships a compiled
+     * artifact with a source. Derived from the same `detectPackAssetFreshness`
+     * call that emits the compiled-artifacts-* issues.
+     */
+    compiledArtifactCoverage?: IVerdictCoverage;
 }
 export interface IPackDoctorOptions {
     /** When true, unsigned packs surface as `unsigned-pack` warnings. */
@@ -36,7 +67,40 @@ export interface IPackDoctorOptions {
     release?: boolean;
     /** When true, release-check warnings escalate to errors. */
     strict?: boolean;
+    /**
+     * Load failures the async registry loaders reported (helpers, conventions,
+     * routing hints, …) — {@link buildPackDoctorReportAsync} gathers them. The
+     * inspection-time loader failures are always read from the inspection.
+     */
+    registryLoadFailures?: readonly IContributionLoadFailure[];
+    /**
+     * What EVERY registry loader reported in one run (`collectRegistryOutcomes`)
+     * — {@link buildPackDoctorReportAsync} gathers it. Its rejections feed
+     * `contribution-entries-rejected` (round 12, 12.1); without it only the
+     * inspection-time loaders' rejections are seen.
+     */
+    registryOutcomes?: IRegistryOutcomes;
+    /** Pack entries exported by a group module but never registered (see `detectUnregisteredExports`). */
+    unregisteredExports?: readonly IUnregisteredExport[];
+    /** Per-pack `typecheckPackAssets` results (the opt-in `--typecheck`). */
+    typecheckResults?: readonly {
+        readonly packageName: string;
+        readonly result: ITypecheckFilesResult;
+    }[];
+    /**
+     * THE declared cross-reference report (`buildDeclaredXrefReport`, warmed) —
+     * {@link buildPackDoctorReportAsync} gathers it. Without it the sync doctor
+     * collects on the caller's warm state: a cold cache yields `unverified`
+     * rows, never a false dangling id.
+     */
+    declaredXrefs?: IDeclaredXrefReport;
 }
+/**
+ * THE build-time pointer printed next to a rejected entry (round 12, 12.1f):
+ * the runtime validator caught it; an annotated asset makes `--typecheck`
+ * catch it before the pack ships.
+ */
+export declare function rejectedEntryTypecheckHint(kind: ContributionKind, pack: string): string;
 /**
  * Full structural + quality audit of every discovered pack. Returns a list of
  * issues (error / warning / info) plus an aggregated pass flag.
@@ -46,6 +110,15 @@ export interface IPackDoctorOptions {
  * else is a warning — useful for pack authors, not fatal.
  */
 export declare function buildPackDoctorReport(inspection: ISharkcraftInspection, options?: IPackDoctorOptions): IPackDoctorReport;
+/**
+ * The pack doctor with every ASYNC input gathered first: the registry loaders'
+ * load failures, unregistered group-module exports, and (opt-in) a typecheck
+ * of each pack's TS assets. `packs doctor` and the MCP doctor tools share it,
+ * so both report the same issues.
+ */
+export declare function buildPackDoctorReportAsync(inspection: ISharkcraftInspection, options?: IPackDoctorOptions & {
+    readonly typecheck?: boolean;
+}): Promise<IPackDoctorReport>;
 /** Run pack-release-check for every valid discovered pack and return the
  *  results. Async because contribution loading uses dynamic imports. */
 export declare function runPackReleaseChecksForReport(inspection: ISharkcraftInspection): Promise<IPackReleaseCheck[]>;

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

@@ -1 +1 @@
-{"version":3,"file":"pack-doctor.d.ts","sourceRoot":"","sources":["../src/pack-doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAWvE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEtF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EACA,kBAAkB,GAClB,2BAA2B,GAC3B,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,yBAAyB,GACzB,mBAAmB,GACnB,wBAAwB,GACxB,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,2BAA2B,GAC3B,oBAAoB,GACpB,oBAAoB,GACpB,+BAA+B,GAC/B,wBAAwB,GACxB,4BAA4B,GAC5B,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,CAAC;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,qFAAqF;IACrF,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAmED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAoRnB;AAgBD;wEACwE;AACxE,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAa9B;AAED;8CAC8C;AAC9C,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,iBAAiB,CAoCnB"}
+{"version":3,"file":"pack-doctor.d.ts","sourceRoot":"","sources":["../src/pack-doctor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAkBvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAAuB,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAKL,KAAK,wBAAwB,EAC9B,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAA6B,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAEhG,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EACA,kBAAkB,GAClB,2BAA2B,GAC3B,8BAA8B,GAC9B,oBAAoB,GACpB,4BAA4B,GAC5B,yBAAyB,GACzB,mBAAmB,GACnB,wBAAwB,GACxB,mBAAmB,GACnB,eAAe,GACf,eAAe,GACf,wBAAwB,GACxB,2BAA2B,GAC3B,0BAA0B,GAC1B,2BAA2B,GAC3B,oBAAoB,GACpB,oBAAoB,GACpB,+BAA+B,GAC/B,wBAAwB,GACxB,4BAA4B,GAC5B,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,GACzB,0BAA0B;IAC5B,qFAAqF;OACnF,+BAA+B,GAC/B,kCAAkC,GAClC,0BAA0B,GAC1B,+BAA+B,GAC/B,qBAAqB,GACrB,iBAAiB,GACjB,mBAAmB;IACrB,2EAA2E;OACzE,oBAAoB;IACtB,2EAA2E;OACzE,sBAAsB;IACxB,4EAA4E;OAC1E,sBAAsB;IACxB,8FAA8F;OAC5F,mBAAmB,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3B,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,qFAAqF;IACrF,aAAa,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC7C,wGAAwG;IACxG,gBAAgB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;KAAE,EAAE,CAAC;IACvG;;;;;;;OAOG;IACH,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;CAC7C;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,qFAAqF;IACrF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,SAAS,wBAAwB,EAAE,CAAC;IAC3D;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC,sGAAsG;IACtG,mBAAmB,CAAC,EAAE,SAAS,mBAAmB,EAAE,CAAC;IACrD,yEAAyE;IACzE,gBAAgB,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;KAAE,EAAE,CAAC;IACvG;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;CACrC;AAuCD;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOvF;AAsDD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAqfnB;AAED;;;;;GAKG;AACH,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAO,GAClE,OAAO,CAAC,iBAAiB,CAAC,CAqB5B;AAgBD;wEACwE;AACxE,wBAAsB,6BAA6B,CACjD,UAAU,EAAE,qBAAqB,GAChC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAa9B;AAED;8CAC8C;AAC9C,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,qBAAqB,EACjC,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,SAAS,iBAAiB,EAAE,EAC3C,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GACjC,iBAAiB,CAoCnB"}

package/dist/pack-doctor.js

@@ -3,8 +3,16 @@ import { PackageManager, WorkspaceProfile, } from '@shrkcrft/workspace';
 import { PipelineStepType } from '@shrkcrft/pipelines';
 import { resolvePreset, resolvePresetReferences } from '@shrkcrft/presets';
 import { PACK_SECRET_ENV, verifyPackManifest } from '@shrkcrft/plugin-api';
+import * as nodePath from 'node:path';
 import { inspectionReferenceLookup } from "./reference-lookup.js";
+import { buildDeclaredXrefReport, collectDeclaredXrefs, isBrokenXref, } from "./declared-cross-references.js";
+import { DeclaredXrefStatus } from "./declared-xref-status.js";
 import { runPackReleaseCheck } from "./pack-release-check.js";
+import { collectContributionLoadFailures, collectContributionRejections, collectRegistryOutcomes, formatEntryRejection, } from "./contribution-load-failures.js";
+import { ContributionKind } from "./contribution-kind.js";
+import { describePackAssetFreshness, detectPackAssetFreshness } from "./pack-asset-freshness.js";
+import { detectUnregisteredExports } from "./unregistered-exports.js";
+import { typecheckPackAssets } from "./pack-typecheck.js";
 const GEN_KEYWORDS = ['generate', 'create', 'add', 'refactor', 'test', 'review'];
 function appliesToGeneration(e) {
     for (const a of e.appliesWhen ?? []) {
@@ -18,6 +26,42 @@ function isCriticalOrHigh(e) {
     const p = String(e.priority);
     return p === 'critical' || p === 'high';
 }
+/**
+ * The `@shrkcrft/plugin-api` authoring type an asset of each kind can be
+ * annotated with (`satisfies I<Kind>[]`), so `--typecheck` fails a missing
+ * required field at build time. A kind with no published type is absent.
+ */
+const ASSET_TYPE_BY_KIND = {
+    [ContributionKind.Knowledge]: 'IKnowledgeEntry',
+    [ContributionKind.Rule]: 'IKnowledgeEntry',
+    [ContributionKind.Path]: 'IKnowledgeEntry',
+    [ContributionKind.PathConvention]: 'IKnowledgeEntry',
+    [ContributionKind.Template]: 'ITemplateDefinition',
+    [ContributionKind.Convention]: 'IConvention',
+    [ContributionKind.Helper]: 'IPackHelper',
+    [ContributionKind.TaskRoutingHint]: 'ITaskRoutingHint',
+    [ContributionKind.RegistrationHint]: 'IRegistrationHint',
+    [ContributionKind.Playbook]: 'IPlaybookInput',
+    [ContributionKind.Construct]: 'IConstructInput',
+    [ContributionKind.ConstructFacet]: 'IConstructFacetInput',
+    [ContributionKind.SearchTuning]: 'ISearchTuning',
+    [ContributionKind.ScaffoldPattern]: 'IScaffoldPattern',
+    [ContributionKind.Policy]: 'IPackPolicyCheck',
+    [ContributionKind.DelegateRecipe]: 'IDelegateRecipe',
+};
+/**
+ * THE build-time pointer printed next to a rejected entry (round 12, 12.1f):
+ * the runtime validator caught it; an annotated asset makes `--typecheck`
+ * catch it before the pack ships.
+ */
+export function rejectedEntryTypecheckHint(kind, pack) {
+    const type = ASSET_TYPE_BY_KIND[kind];
+    if (!type) {
+        // No published authoring type for this kind: the runtime loader is the check.
+        return `\`shrk packs test ${pack} --load\` runs this loader at build time and fails on the entry — run it before publishing.`;
+    }
+    return `Annotate the asset with a type-only import and \`satisfies ${type}[]\` (from @shrkcrft/plugin-api) — see docs/pack-authoring.md — then \`shrk packs test ${pack} --typecheck\` catches this at build time.`;
+}
 /** A leading package-manager / runner literal a pack verification command may
  *  bake in. Order longest-first is not required — these tokens are disjoint. */
 const PM_LITERAL_MANAGERS = [
@@ -78,6 +122,28 @@ export function buildPackDoctorReport(inspection, options = {}) {
         .filter((e) => inspection.entrySources.get(e.id)?.type === 'local')
         .map((e) => e.id));
     const detectedPm = detectedProjectManager(inspection.workspace);
+    const loadFailures = collectContributionLoadFailures(inspection, options.registryLoadFailures ?? options.registryOutcomes?.loadFailures ?? []);
+    // THE rejection channel, and each file's accepted count (the loader's own):
+    // `N of M entries rejected` is accepted + rejected = declared.
+    const rejections = collectContributionRejections(inspection, options.registryOutcomes?.rejections ?? []);
+    const acceptedByFile = new Map();
+    for (const a of options.registryOutcomes?.accepted ?? []) {
+        acceptedByFile.set(a.file, (acceptedByFile.get(a.file) ?? 0) + 1);
+    }
+    for (const d of inspection.loaderDiagnostics ?? []) {
+        if (d.status !== 'ok')
+            continue;
+        const abs = nodePath.resolve(d.filePath);
+        acceptedByFile.set(abs, (acceptedByFile.get(abs) ?? 0) + d.count);
+    }
+    const rejectedFiles = new Set(rejections.map((r) => r.file));
+    // Files the inspection-time loaders imported AND that produced ≥ 1 entry.
+    // Compiled artifacts with a source, and those no build record covers.
+    let compiledWithSource = 0;
+    const unrecordedArtifacts = [];
+    const producingFiles = new Set((inspection.loaderDiagnostics ?? [])
+        .filter((d) => d.status === 'ok' && d.count > 0)
+        .map((d) => nodePath.resolve(d.filePath)));
     for (const pack of inspection.packs.invalidPacks) {
         issues.push({
             severity: 'error',
@@ -112,10 +178,137 @@ export function buildPackDoctorReport(inspection, options = {}) {
                 severity: 'error',
                 packageName: pack.packageName,
                 code: 'empty-resolved-contributions',
-                message: 'Pack declared contribution files but nothing loaded — every file is missing, empty, or duplicates local entries.',
+                message: 'Pack declared contribution files but nothing loaded — every file is missing, empty, failed to load, or duplicates local entries.',
                 suggestion: 'Run `shrk packs get <pack>` and check the listed contribution files.',
             });
         }
+        // A contribution file the module loader could not import: nothing in it
+        // takes effect, whatever a regex scrape of it might list. One error per file.
+        const packRootPrefix = nodePath.resolve(pack.packageRoot) + nodePath.sep;
+        const packFailures = [...loadFailures.values()].filter((f) => f.packageName === pack.packageName || f.file.startsWith(packRootPrefix));
+        for (const f of packFailures) {
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'contribution-load-failed',
+                message: `${nodePath.relative(pack.packageRoot, f.file) || f.file} (${f.kind}) failed to load — ${f.message}. Nothing in it takes effect.`,
+                suggestion: 'Fix the syntax / import error in that file; release-check reproduces the load.',
+                suggestedCommand: `shrk packs release-check ${pack.packageRoot}`,
+            });
+        }
+        // Entries a contribution file DECLARES that its loader REFUSED (round 12,
+        // 12.1): one error per file. A file with 8 of 10 entries used to read as
+        // healthy here — only a file producing ZERO entries was ever flagged.
+        const packRejections = rejections.filter((r) => r.packageName === pack.packageName || r.file.startsWith(packRootPrefix));
+        const byFile = new Map();
+        for (const r of packRejections)
+            byFile.set(r.file, [...(byFile.get(r.file) ?? []), r]);
+        for (const [file, list] of byFile) {
+            const declared = (acceptedByFile.get(file) ?? 0) + list.length;
+            const kind = list[0].kind;
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'contribution-entries-rejected',
+                message: `${nodePath.relative(pack.packageRoot, file) || file} (${kind}): ${list.length} of ${declared} ${declared === 1 ? 'entry' : 'entries'} rejected — ${list.map((r) => formatEntryRejection(r)).join('; ')}. A rejected entry does not take effect.`,
+                suggestion: `Fix the field(s) the loader names. ${options.typecheckResults ? '' : rejectedEntryTypecheckHint(kind, nodePath.relative(inspection.projectRoot, pack.packageRoot) || pack.packageRoot)}`.trim(),
+                suggestedCommand: `shrk packs contributions --pack ${pack.packageName}`,
+            });
+        }
+        // Declared knowledge-family files that LOADED but produced no entry: the
+        // pack prints `k=2` next to `entries=1` and that pair used to go unread.
+        if (declaredAny && resolvedAny) {
+            const familyRels = [
+                ...(manifest.contributions.knowledgeFiles ?? []),
+                ...(manifest.contributions.ruleFiles ?? []),
+                ...(manifest.contributions.pathFiles ?? []),
+                ...(manifest.contributions.pathConventionFiles ?? []),
+                ...(manifest.contributions.templateFiles ?? []),
+                ...(manifest.contributions.pipelineFiles ?? []),
+                ...(manifest.contributions.docsFiles ?? []),
+            ];
+            const familyAbs = [...new Set(familyRels.map((rel) => nodePath.resolve(pack.packageRoot, rel)))];
+            const silent = familyAbs.filter((abs) => !producingFiles.has(abs) &&
+                !loadFailures.has(abs) &&
+                // Every entry rejected: `contribution-entries-rejected` says why.
+                !rejectedFiles.has(abs) &&
+                !inspection.warnings.includes(`pack ${pack.packageName}: missing contribution file ${nodePath.relative(pack.packageRoot, abs)}`));
+            if (silent.length > 0) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'partially-resolved-contributions',
+                    message: `${silent.length} of ${familyAbs.length} declared contribution file(s) loaded but produced no entries: ${silent
+                        .map((abs) => nodePath.relative(pack.packageRoot, abs))
+                        .join(', ')}.`,
+                    suggestion: 'Each file must export entry-shaped values (an array default export, or named entries); check the export shape and the required fields.',
+                });
+            }
+        }
+        // Compiled contributions vs their source — THE freshness authority
+        // (content, never mtime). A stale build means shrk serves the previous one.
+        const freshness = detectPackAssetFreshness(pack);
+        const saidBuild = describePackAssetFreshness(freshness).build;
+        if (freshness.build.state === 'stale' && saidBuild) {
+            issues.push({
+                severity: options.strict || options.release ? 'error' : 'warning',
+                packageName: pack.packageName,
+                code: 'compiled-artifacts-stale',
+                message: saidBuild,
+                ...(freshness.build.rebuildCommand
+                    ? { suggestedCommand: `(cd ${pack.packageRoot} && ${freshness.build.rebuildCommand})` }
+                    : {}),
+            });
+        }
+        else if (freshness.build.state === 'unrecorded' && saidBuild) {
+            // Never compared (no build record): NOT VERIFIED by default — the
+            // verdict settles it through `compiledArtifactCoverage` — and, like a
+            // stale build, an error under --strict / --release.
+            issues.push({
+                severity: options.strict || options.release ? 'error' : 'warning',
+                packageName: pack.packageName,
+                code: 'compiled-artifacts-unrecorded',
+                message: saidBuild,
+            });
+        }
+        for (const a of freshness.build.artifacts) {
+            if (a.source === null)
+                continue; // no source → nothing to compare it to
+            compiledWithSource += 1;
+            if (a.state === 'unrecorded')
+                unrecordedArtifacts.push(`${pack.packageName}:${a.artifact}`);
+        }
+        for (const u of options.unregisteredExports ?? []) {
+            if (u.packageName !== pack.packageName)
+                continue;
+            issues.push({
+                severity: 'error',
+                packageName: pack.packageName,
+                code: 'unregistered-export',
+                message: `${u.group}${u.line > 0 ? `:${u.line}` : ''} ${u.message}`,
+            });
+        }
+        for (const t of options.typecheckResults ?? []) {
+            if (t.packageName !== pack.packageName)
+                continue;
+            if (!t.result.ran) {
+                issues.push({
+                    severity: 'warning',
+                    packageName: pack.packageName,
+                    code: 'typecheck-not-run',
+                    message: `--typecheck examined 0 TS files (${t.result.note ?? 'nothing to check'}) — NOT verified.`,
+                });
+                continue;
+            }
+            for (const e of t.result.errors) {
+                issues.push({
+                    severity: 'error',
+                    packageName: pack.packageName,
+                    code: 'typecheck-error',
+                    message: `${nodePath.relative(pack.packageRoot, e.file) || e.file}:${e.line}:${e.column} TS${e.code} ${e.message}`,
+                });
+            }
+        }
         // Templates contributed by this pack — require a non-trivial description.
         for (const t of inspection.templates) {
             const src = inspection.templateSources.get(t.id);
@@ -323,6 +516,51 @@ export function buildPackDoctorReport(inspection, options = {}) {
             });
         }
     }
+    // Declared cross-references on pack-contributed assets (round 11, 4.2): the
+    // SAME rows the self-config doctor reports, scoped to the pack that owns the
+    // source asset — never a second walker over the fields.
+    const xrefs = options.declaredXrefs ?? collectDeclaredXrefs(inspection);
+    const packNames = new Set(inspection.packs.discoveredPacks.map((p) => p.packageName));
+    const unverifiedByPack = new Map();
+    for (const row of xrefs.rows) {
+        if (!row.packageName || !packNames.has(row.packageName))
+            continue;
+        if (row.status === DeclaredXrefStatus.Unverified) {
+            unverifiedByPack.set(row.packageName, (unverifiedByPack.get(row.packageName) ?? 0) + 1);
+            continue;
+        }
+        if (!isBrokenXref(row))
+            continue;
+        issues.push({
+            severity: row.severity === 'error' ? 'error' : 'warning',
+            packageName: row.packageName,
+            code: row.status === DeclaredXrefStatus.Dangling ? 'pack-xref-dangling' : 'pack-xref-wrong-kind',
+            message: `${row.message}${row.file ? ` (${row.file})` : ''}`,
+            suggestion: row.didYouMean.length > 0
+                ? `Did you mean "${row.didYouMean[0]}"? Fix the id in the pack source, then re-sign the pack.`
+                : 'Fix or remove the id in the pack source, then re-sign the pack.',
+            suggestedCommand: `shrk self-config resolve ${row.targetId}`,
+        });
+    }
+    for (const issue of xrefs.issues) {
+        if (!issue.packageName || !packNames.has(issue.packageName))
+            continue;
+        issues.push({
+            severity: issue.severity,
+            packageName: issue.packageName,
+            code: 'pack-xref-invalid',
+            message: `[${issue.code}] ${issue.message}${issue.file ? ` (${issue.file})` : ''}`,
+        });
+    }
+    for (const [packageName, n] of unverifiedByPack) {
+        issues.push({
+            severity: 'info',
+            packageName,
+            code: 'pack-xref-unverified',
+            message: `${n} declared cross-reference id(s) NOT VERIFIED — the registry they resolve against was not warmed, or is empty.`,
+            suggestedCommand: 'shrk self-config xrefs --json',
+        });
+    }
     const summary = {
         errors: issues.filter((i) => i.severity === 'error').length,
         warnings: issues.filter((i) => i.severity === 'warning').length,
@@ -333,8 +571,50 @@ export function buildPackDoctorReport(inspection, options = {}) {
         packsChecked: inspection.packs.discoveredPacks.length,
         issues,
         summary,
+        ...(options.typecheckResults ? { typecheckResults: options.typecheckResults } : {}),
+        ...(compiledWithSource > 0
+            ? {
+                compiledArtifactCoverage: {
+                    unit: 'compiled artifacts',
+                    expected: compiledWithSource,
+                    examined: compiledWithSource - unrecordedArtifacts.length,
+                    reason: 'have no build record (source-map sourcesContent or signed content digests) to compare their source against',
+                    ...(unrecordedArtifacts.length > 0
+                        ? { unexamined: unrecordedArtifacts.slice(0, 20), unexaminedTotal: unrecordedArtifacts.length }
+                        : {}),
+                },
+            }
+            : {}),
     };
 }
+/**
+ * The pack doctor with every ASYNC input gathered first: the registry loaders'
+ * load failures, unregistered group-module exports, and (opt-in) a typecheck
+ * of each pack's TS assets. `packs doctor` and the MCP doctor tools share it,
+ * so both report the same issues.
+ */
+export async function buildPackDoctorReportAsync(inspection, options = {}) {
+    // ONE run of every registry loader: load failures, rejected and accepted entries.
+    const [registryOutcomes, unregisteredExports] = await Promise.all([
+        collectRegistryOutcomes(inspection),
+        detectUnregisteredExports(inspection).then((all) => all.filter((u) => u.packageName !== undefined)),
+    ]);
+    const registryLoadFailures = registryOutcomes.loadFailures;
+    const typecheckResults = options.typecheck
+        ? inspection.packs.validPacks.map((p) => ({
+            packageName: p.packageName,
+            result: typecheckPackAssets({ packageRoot: p.packageRoot, manifestPath: p.manifestPath, manifest: p.manifest ?? null }),
+        }))
+        : undefined;
+    return buildPackDoctorReport(inspection, {
+        ...options,
+        registryLoadFailures,
+        registryOutcomes,
+        unregisteredExports,
+        declaredXrefs: options.declaredXrefs ?? (await buildDeclaredXrefReport(inspection)),
+        ...(typecheckResults ? { typecheckResults } : {}),
+    });
+}
 /** Map a single release-check finding code to one of the four IPackDoctorIssue
  *  release-* bucket codes. */
 function releaseFindingBucket(code) {

package/dist/pack-helper-plan.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Render a pack/local helper's DECLARATIVE operations into a helper plan.
+ *
+ * `IPackHelperOperationInput` kinds existed only as a type — no code mapped
+ * them to plan ops, so a valid pack helper could never be planned. This is the
+ * one renderer; it never executes pack code (operations are data) and never
+ * writes. Placeholders go through the shared `substitutePlaceholders`.
+ */
+import type { IHelperPlan } from './helper-registry.js';
+import type { IHelperView } from './helper-view.js';
+/**
+ * Build the plan for one catalog helper with `vars`. Declared defaults apply
+ * first; a required variable with no value is a refusal (`ok: false`) naming
+ * every missing one — never a plan with blank snippets.
+ */
+export declare function buildPackHelperPlan(helper: IHelperView, vars: Readonly<Record<string, string>>): {
+    readonly ok: true;
+    readonly plan: IHelperPlan;
+} | {
+    readonly ok: false;
+    readonly missing: readonly string[];
+    readonly message: string;
+};
+//# sourceMappingURL=pack-helper-plan.d.ts.map

package/dist/pack-helper-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pack-helper-plan.d.ts","sourceRoot":"","sources":["../src/pack-helper-plan.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAKpD;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACrC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA8D3I"}

package/dist/pack-helper-plan.js

@@ -0,0 +1,77 @@
+import { substitutePlaceholders } from "./substitute-placeholders.js";
+const UNRESOLVED = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/;
+/**
+ * Build the plan for one catalog helper with `vars`. Declared defaults apply
+ * first; a required variable with no value is a refusal (`ok: false`) naming
+ * every missing one — never a plan with blank snippets.
+ */
+export function buildPackHelperPlan(helper, vars) {
+    const values = {};
+    for (const v of helper.variables)
+        if (v.defaultValue !== undefined)
+            values[v.name] = v.defaultValue;
+    Object.assign(values, vars);
+    const missing = helper.variables.filter((v) => v.required && !values[v.name]).map((v) => v.name);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            missing,
+            message: `Helper "${helper.id}" requires ${missing.map((m) => `--var ${m}=<value>`).join(' ')}.`,
+        };
+    }
+    const sub = (s) => (s === undefined ? '' : substitutePlaceholders(s, values));
+    const ops = [];
+    const manualSteps = [];
+    const conflicts = [];
+    const asChecklist = helper.outputKind === 'checklist';
+    helper.operations.forEach((op, i) => {
+        const at = `operations[${i}] (${op.kind})`;
+        const targetPath = sub(op.targetPath);
+        if (op.kind === 'manual-checklist') {
+            for (const item of op.checklist ?? [])
+                manualSteps.push({ kind: 'manual-checklist', description: sub(item) });
+            return;
+        }
+        if (asChecklist) {
+            manualSteps.push({ kind: op.kind, description: `${sub(op.description) || op.kind} — ${targetPath}` });
+            return;
+        }
+        let planned;
+        if (op.kind === 'append-line') {
+            planned = { kind: 'append', targetPath, snippet: sub(op.snippet) };
+        }
+        else if (op.kind === 'insert-before') {
+            planned = { kind: 'insert-before', targetPath, anchor: sub(op.anchor), snippet: sub(op.snippet) };
+        }
+        else if (op.kind === 'replace-line') {
+            planned = { kind: 'replace', targetPath, fromPattern: sub(op.find), snippet: sub(op.replaceWith) };
+        }
+        else {
+            // remove-line: a replace with an empty snippet.
+            planned = { kind: 'replace', targetPath, fromPattern: sub(op.find), snippet: '' };
+        }
+        ops.push(planned);
+        for (const [field, value] of Object.entries(planned)) {
+            if (typeof value !== 'string')
+                continue;
+            const m = UNRESOLVED.exec(value);
+            if (m)
+                conflicts.push(`${at}.${field} still contains {{${m[1]}}} — no value was supplied for "${m[1]}"`);
+        }
+    });
+    for (const item of helper.manualChecklist)
+        manualSteps.push({ kind: 'checklist', description: sub(item) });
+    return {
+        ok: true,
+        plan: {
+            schema: 'sharkcraft.helper-plan/v1',
+            helperId: helper.id,
+            generatedAt: new Date().toISOString(),
+            ops,
+            conflicts,
+            manualSteps,
+            destructive: helper.destructive,
+            requiresHumanReview: helper.requiresHumanReview,
+        },
+    };
+}