@gate-forge/core 0.1.0

package/dist/mapping/resolve.d.ts

@@ -0,0 +1,177 @@
+import type { Location } from '../schemas/common.js';
+import { type Claim } from '../schemas/claim.js';
+import type { TestCatalog, TestKind } from '../schemas/test-catalog.js';
+import type { TestMap } from '../schemas/test-map.js';
+/** Why a mapping problem exists (plan §5.4 rows TEST_MAPPING_* + TEST_KIND_UNKNOWN). */
+export type MappingProblemCause = 'TEST_MAPPING_AMBIGUOUS' | 'TEST_MAPPING_STALE' | 'TEST_KIND_UNKNOWN';
+/** Where a resolved binding's declaration came from. `inferred` bindings never grade (§5.3). */
+export type MappingOrigin = 'native' | 'sidecar' | 'inferred' | 'prior-run';
+/**
+ * One prior-run observation (plan Phase 3 item 2): an earlier run bound
+ * this logical test to this obligation. A hint can SUGGEST a link but
+ * never satisfies new inputs, so hint bindings never grade.
+ */
+export interface PriorRunHint {
+    /** The catalog logical key the prior run observed. */
+    logicalKey: string;
+    /** The obligation the prior run bound it to. */
+    obligationId: string;
+}
+/** One runtime instance a resolved binding covers (from the catalog). */
+export interface TestInstanceRef {
+    /** Runner the instance executes under. */
+    runner: string;
+    /** Runner project, or null when no enumeration bound one. */
+    project: string | null;
+    /** Repo-root-relative posix file path. */
+    file: string;
+    /** Full title path (describe stack, then the test title). */
+    titlePath: string[];
+    /** Framework repeat/parameter identity, or null when not parameterized. */
+    parameterIdentity: string | null;
+}
+/** One resolved declaration binding an existing test to an obligation. */
+export interface ResolvedClaimBinding {
+    /** The logical test key the declaration resolves to. */
+    logicalKey: string;
+    /** Current catalog instances the binding covers (empty when stale). */
+    instances: TestInstanceRef[];
+    /** Declaration origin; only `native`/`sidecar` bindings grade. */
+    origin: MappingOrigin;
+    /** Catalog source digest of the bound test (stale-proof input, §5.2). */
+    sourceDigest: string | null;
+    /** Declared kind, when a sidecar entry declared one. */
+    declaredKind: TestKind | null;
+    /** Declared category labels (sorted, deduplicated). */
+    categories: string[];
+    /** The sidecar declaration's required reason, when present. */
+    reason: string | null;
+    /** Best known source location of the test (native claim or catalog row). */
+    sourceLocation: Location | null;
+}
+/** Every resolved binding for one obligation (sorted by origin, then key). */
+export interface ObligationBindings {
+    /** The obligation the bindings claim to cover. */
+    obligationId: string;
+    /** The resolved declarations (possibly empty — an unmapped obligation). */
+    bindings: ResolvedClaimBinding[];
+}
+/** One typed mapping problem (plan §5.4: actionable, both locations). */
+export interface MappingProblem {
+    /** Stable cause code. */
+    cause: MappingProblemCause;
+    /** The affected obligation id, when the problem is obligation-scoped. */
+    obligationId: string | null;
+    /** Single-cause human explanation naming both sides of a conflict. */
+    detail: string;
+    /** Known source locations (sorted) — both sides for conflicts. */
+    locations: Location[];
+}
+/** The resolved-mappings surface (plan §5.1 row 3): bindings + problems. */
+export interface ResolvedMappings {
+    /** One entry per known obligation id, sorted by id. */
+    obligations: ObligationBindings[];
+    /** Typed problems, sorted by (cause, obligationId, detail). */
+    problems: MappingProblem[];
+}
+/** Inputs of {@link resolveTestMappings}. */
+export interface ResolveMappingsInput {
+    /** The current derived test catalog (discovery output). */
+    catalog: TestCatalog;
+    /**
+     * Native per-test annotation claims exactly as the pipeline reports
+     * them today (validated Claim documents from the run-state
+     * claims.json).
+     */
+    nativeClaims: readonly Claim[];
+    /** The validated sidecar document (empty when no sidecar exists). */
+    sidecar: TestMap;
+    /** The obligation registry's ids (the obligations dump path). */
+    obligationIds: readonly string[];
+    /** Optional prior-run observations (suggestions only, never grading). */
+    priorRunHints?: readonly PriorRunHint[];
+}
+/**
+ * Resolves native claims, sidecar declarations, prior-run hints, and
+ * inference into the one resolved-mappings surface.
+ *
+ * Args:
+ *   input: catalog, native claims, validated sidecar, obligation ids,
+ *     and optional prior-run hints.
+ *
+ * Returns:
+ *   ResolvedMappings: per-obligation bindings plus typed problems, all
+ *   deterministically sorted.
+ */
+export declare function resolveTestMappings(input: ResolveMappingsInput): ResolvedMappings;
+/** Cause a mapping suggestion can carry (plan §5.4 mapping rows). */
+export type MappingSuggestionCause = 'TEST_MAPPING_MISSING' | 'TEST_KIND_UNKNOWN' | 'TEST_MAPPING_AMBIGUOUS' | 'TEST_MAPPING_STALE';
+/** One candidate existing test a suggestion proposes for reuse. */
+export interface SuggestionCandidate {
+    /** The catalog logical key of the candidate test. */
+    logicalKey: string;
+    /** The test's file (for quick human inspection). */
+    file: string;
+    /** Matched signals — the WHY, never an opaque confidence number. */
+    why: string[];
+}
+/** One per-obligation reuse suggestion (plan Phase 3 item 6). */
+export interface MappingSuggestion {
+    /** The obligation the suggestion is about. */
+    obligationId: string;
+    /** Why the obligation is not connected yet. */
+    cause: MappingSuggestionCause;
+    /** Candidate existing tests, ordered by reuse (declared bindings first). */
+    candidates: SuggestionCandidate[];
+    /** What evidence/declaration is missing (honest, single-cause). */
+    missingEvidence: string;
+    /** The plan §5.4 next action for the cause. */
+    nextAction: string;
+    /** True ONLY when no candidate exists after resolution. */
+    newTestNeeded: boolean;
+}
+/** Inputs of {@link mappingSuggestions}. */
+export interface MappingSuggestionsInput {
+    /** The current derived test catalog. */
+    catalog: TestCatalog;
+    /** The obligation ids to suggest for (already scoped by the caller). */
+    obligationIds: readonly string[];
+    /** The resolved-mappings surface from {@link resolveTestMappings}. */
+    resolution: ResolvedMappings;
+}
+/**
+ * Produces per-obligation reuse suggestions ordered by reuse (plan
+ * Phase 3 item 6). Obligations with a clean DECLARED mapping produce no
+ * suggestion (their remaining gap is executed proof, not mapping).
+ * `newTestNeeded` is true only when no candidate exists after resolution.
+ *
+ * Args:
+ *   input: catalog, scoped obligation ids, and the resolution.
+ *
+ * Returns:
+ *   MappingSuggestion[]: sorted by reuse rank, then obligation id.
+ */
+export declare function mappingSuggestions(input: MappingSuggestionsInput): MappingSuggestion[];
+/**
+ * Projects resolved bindings into declared grading claims (plan §5.3:
+ * both declaration paths normalize into existing claims). ONLY `native`
+ * and `sidecar` bindings project — inferred and prior-run bindings are
+ * suggestions and never grade. Exact duplicates of claims the run state
+ * already carries are dropped idempotently. The claims declare INTENT:
+ * they contain no evidence, so a mapped obligation with no witnessed
+ * records still grades EVIDENCE_NOT_COLLECTED (blocking), never satisfied.
+ *
+ * Phase 4 note (runtime selection): the suite fixture submits evidence
+ * per native annotations using the reporter's own testIds, so sidecar
+ * claims (whose testId is the logical key) cannot receive runtime
+ * evidence until Phase 4 wires claim injection through session open.
+ *
+ * Args:
+ *   resolution: the resolved-mappings surface.
+ *   existingClaims: the run-state claims (native annotations).
+ *
+ * Returns:
+ *   Claim[]: validated declared claims, sorted by (obligationId, testId).
+ */
+export declare function mappingGradingClaims(resolution: ResolvedMappings, existingClaims: readonly Claim[]): Claim[];
+//# sourceMappingURL=resolve.d.ts.map

package/dist/mapping/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/mapping/resolve.ts"],"names":[],"mappings":"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"}