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

package/dist/knowledge-stale.d.ts

@@ -1,23 +1,51 @@
 /**
- * Knowledge stale-check.
+ * Knowledge stale-check — THE staleness engine (every consumer reads it).
  *
- * Walks every knowledge entry's `references[]` + `anchors[]` and checks
- * whether each target still resolves against the current workspace.
+ * Walks every knowledge entry's `references[]` + `anchors[]` — and the
+ * references boundary rules and policy checks declare — and checks whether each
+ * target still resolves against the current workspace, and (with `contains` /
+ * `matches` / `count`) still says what the asset claims.
  *
- * Pure file-system + registry lookups — no network, no AST compilation.
- * Symbol checks are deterministic best-effort text scans so the doctor
- * stays cheap.
+ * It classifies every entry in scope into ONE of three buckets: `verified`,
+ * `stale`, `unverifiable`. An entry with nothing checkable used to contribute
+ * nothing and read as healthy — the less verifiable a corpus, the healthier it
+ * looked. The buckets make that shortfall a number the verdict can refuse on.
  *
- * Schema: sharkcraft.knowledge-stale/v1
+ * Callers MUST `await warmReferenceRegistries(inspection)` first: the
+ * playbook / policy / construct / helper registries are async-filled, and an
+ * unwarmed registry is reported `unknown` (NOT VERIFIED) here — never `stale`
+ * against a correct id.
+ *
+ * Pure file-system + registry lookups — no network, no whole-program
+ * compilation. Symbol checks use the single-file AST index.
+ *
+ * Schema: sharkcraft.knowledge-stale/v1 (additive fields since round 11)
  */
-import type { IKnowledgeAnchor, IKnowledgeReference } from '@shrkcrft/knowledge';
+import { type IKnowledgeAnchor, type IKnowledgeReference } from '@shrkcrft/knowledge';
 import type { ISharkcraftInspection } from './sharkcraft-inspector.js';
+import { ReferenceFailure } from './reference-failure.js';
+import type { IKnowledgeEntryVerdictRecord } from './knowledge-entry-verdict-record.js';
+import type { IKnowledgeStaleCoverage } from './knowledge-stale-coverage.js';
+import type { IKnowledgeKindBucket } from './knowledge-kind-bucket.js';
+import type { IKnowledgeReferenceKindBucket } from './knowledge-reference-kind-bucket.js';
+import type { IKnowledgeStaleAdvisory } from './knowledge-stale-advisory.js';
+import type { IKnowledgeAgedEntry } from './knowledge-aged-entry.js';
+import { ReferenceAssetKind } from './reference-asset-kind.js';
 export declare const KNOWLEDGE_STALE_SCHEMA = "sharkcraft.knowledge-stale/v1";
 export declare enum ReferenceCheckOutcome {
     Ok = "ok",
     Stale = "stale",
     Missing = "missing",
-    Unknown = "unknown"
+    /** Well-formed, but the check cannot evaluate it (a `url`, an unwarmed registry). */
+    Unknown = "unknown",
+    /**
+     * MALFORMED — a kind outside the vocabulary, or the field its kind cannot be
+     * checked without is missing (a symbol reference with no `symbol`). It
+     * verifies nothing; it used to share `unknown` with an unfetched url and
+     * count toward a green run. Now it is a coverage shortfall on the verdict
+     * (not verified) and fails under `--fail-on invalid`.
+     */
+    Invalid = "invalid"
 }
 export declare enum SymbolConfidence {
     Exact = "exact",
@@ -87,26 +115,92 @@ export interface IKnowledgeReferenceCheck {
     suggestion?: string;
     /** Structured replacement when the engine can identify the new location. */
     replaceWith?: IReferenceReplacement;
+    /**
+     * WHY a non-ok check did not pass — additive to {@link outcome}, which keeps
+     * its historical values. Lets `--fail-on path-missing|anchor-missing|content|count`
+     * gate each failure mode separately.
+     */
+    failure?: ReferenceFailure;
+    /** For a content / count assertion: what the asset claims. */
+    expected?: string | number;
+    /** For a content / count assertion: what the tree holds now. */
+    actual?: string | number;
+    /** Which asset kind declared the reference. Absent on knowledge checks (the historical shape). */
+    assetKind?: ReferenceAssetKind;
+    /** True for an IMPLICIT reference derived from a scope glob — advisory unless `--fail-on implicit`. */
+    implicit?: boolean;
 }
 export interface IKnowledgeAnchorCheck {
     entryId: string;
     anchor: IKnowledgeAnchor;
     outcome: ReferenceCheckOutcome;
     message: string;
+    /** WHY a non-ok anchor did not pass. */
+    failure?: ReferenceFailure;
 }
 export interface IKnowledgeStaleReport {
     schema: typeof KNOWLEDGE_STALE_SCHEMA;
+    /** Knowledge entries in the CORPUS. A scoped run examines {@link entriesInScope}. */
     entries: number;
     totalReferences: number;
     totalAnchors: number;
+    /**
+     * Knowledge-reference outcomes (anchors and other assets' references are
+     * counted elsewhere). `invalid` = malformed references, never checked.
+     */
     counts: {
         ok: number;
         stale: number;
         missing: number;
         unknown: number;
+        invalid: number;
     };
     referenceChecks: ReadonlyArray<IKnowledgeReferenceCheck>;
     anchorChecks: ReadonlyArray<IKnowledgeAnchorCheck>;
+    /** Knowledge entries the sweep examined — `changedFiles` narrows this, never {@link entries}. */
+    entriesInScope: number;
+    /** The three entry buckets over {@link entriesInScope}. */
+    coverage: IKnowledgeStaleCoverage;
+    /** One verdict per knowledge entry in scope, in corpus order. */
+    entryVerdicts: ReadonlyArray<IKnowledgeEntryVerdictRecord>;
+    /** Every unverifiable entry id in scope (renderers cap; this never does). */
+    unverifiableIds: ReadonlyArray<string>;
+    /** Non-ok checks per {@link ReferenceFailure} — knowledge references, anchors and other assets. */
+    failureCounts: Readonly<Record<ReferenceFailure, number>>;
+    /** Per asset kind. `scanned: 0` means NOT IN SWEEP — say so, never render it as clean zeros. */
+    byAssetKind: Readonly<Record<ReferenceAssetKind, IKnowledgeKindBucket>>;
+    /** Per knowledge entry `type` (rules and paths are where unreferenced entries cluster). */
+    byEntryType: Readonly<Record<string, IKnowledgeKindBucket>>;
+    /** Per reference kind, knowledge and other assets together. */
+    byReferenceKind: Readonly<Record<string, IKnowledgeReferenceKindBucket>>;
+    /**
+     * References declared by boundary rules and policy checks, plus IMPLICIT
+     * boundary references (`implicit: true`). Kept apart from
+     * {@link referenceChecks} so the nine consumers that map a check back to a
+     * knowledge entry never meet a rule id.
+     */
+    assetReferenceChecks: ReadonlyArray<IKnowledgeReferenceCheck>;
+    /** Reported, never gating on their own. */
+    advisories: ReadonlyArray<IKnowledgeStaleAdvisory>;
+    /**
+     * Policy checks keep their scope inside `evaluate()`; only declared
+     * references can verify them. `loaded: false` = the policy cache was not
+     * warm, so policies were NOT IN SWEEP.
+     */
+    policySweep: {
+        readonly loaded: boolean;
+        readonly declared: number;
+        readonly withReferences: number;
+    };
+    /** Set when `staleAfterDays` was requested. */
+    age?: {
+        readonly asOf: string;
+        readonly staleAfterDays: number;
+        /** Oldest first. */
+        readonly aged: ReadonlyArray<IKnowledgeAgedEntry>;
+        /** In scope with no (valid) `verifiedOn`. */
+        readonly neverVerified: ReadonlyArray<string>;
+    };
 }
 /**
  * Minimal structural view of the code graph's symbol index.
@@ -142,6 +236,25 @@ export interface IKnowledgeStaleCheckOptions {
      * single-file AST scan when the graph cannot answer.
      */
     graph?: ISymbolGraphResolver;
+    /**
+     * `--stale-after`, in days: list entries whose `verifiedOn` is older than
+     * this (and those with none). Author attestation — it never changes a
+     * reference outcome.
+     */
+    staleAfterDays?: number;
+    /** The date ages are measured to (`YYYY-MM-DD`). Default: today, UTC — echoed in `age.asOf`. */
+    asOf?: string;
+    /** Sweep boundary-rule and policy references too. Default `true`. */
+    includeAssets?: boolean;
+    /** Directories a `count` source never walks (e.g. the sharkcraft dir). */
+    excludeDirs?: readonly string[];
 }
+/**
+ * ok / stale / missing are real checks; unknown and invalid (malformed) proved
+ * nothing either way. THE predicate — the stale-check's entry buckets, its
+ * verdict fold (`declaredReferenceCoverage`) and the `shrk gate`
+ * knowledge-symbol gate all read it.
+ */
+export declare function isCheckableOutcome(o: ReferenceCheckOutcome): boolean;
 export declare function buildKnowledgeStaleReport(inspection: ISharkcraftInspection, options?: IKnowledgeStaleCheckOptions): IKnowledgeStaleReport;
 //# sourceMappingURL=knowledge-stale.d.ts.map

package/dist/knowledge-stale.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-stale.d.ts","sourceRoot":"","sources":["../src/knowledge-stale.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,gBAAgB,EAEhB,mBAAmB,EAEpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAKvE,eAAO,MAAM,sBAAsB,kCAAkC,CAAC;AAEtE,oBAAY,qBAAqB;IAC/B,EAAE,OAAO;IACT,KAAK,UAAU;IACf,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED,oBAAY,gBAAgB;IAC1B,KAAK,UAAU;IACf,QAAQ,aAAa;IACrB,OAAO,YAAY;IACnB,OAAO,YAAY;CACpB;AAED;;;;;;;;;GASG;AACH,oBAAY,cAAc;IACxB,MAAM,WAAW;IACjB,IAAI,SAAS;CACd;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE,MAAM,CAAC;IAClB,uDAAuD;IACvD,UAAU,CAAC,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAC9C,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,qBAAqB,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,qBAAqB,CAAC;IAC/B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,eAAe,EAAE,aAAa,CAAC,wBAAwB,CAAC,CAAC;IACzD,YAAY,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CACpD;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,oBAAoB;IACnC,yEAAyE;IACzE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAAC;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3E;AAED,MAAM,WAAW,2BAA2B;IAC1C,8EAA8E;IAC9E,YAAY,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACrC;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC;;;;;OAKG;IACH,KAAK,CAAC,EAAE,oBAAoB,CAAC;CAC9B;AAmYD,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,qBAAqB,EACjC,OAAO,GAAE,2BAAgC,GACxC,qBAAqB,CAgJvB"}
+{"version":3,"file":"knowledge-stale.d.ts","sourceRoot":"","sources":["../src/knowledge-stale.ts"],"names":[],"mappings":"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"}