@peasant-labs/fairtrade 0.0.7 → 0.0.9

package/dist/lib/types/graph/ranking.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Comprehension-debt state resolution over MapNode scalars only (no per-hunk
+ * wire data required; the formula is pure over ReadState plus the three
+ * region-coverage counts).
+ * @param {RankInputNode} node
+ * @returns {DebtState}
+ */
+export function debtState(node: RankInputNode): DebtState;
+/**
+ * Comprehension-debt magnitude. `state` must be the value `debtState(node)` returned for
+ * the SAME node (kept as a parameter, not recomputed, so callers that already
+ * branched on `debtState` never pay for or risk re-deriving it differently).
+ * @param {RankInputNode} node @param {DebtState} state
+ * @returns {number}
+ */
+export function debt(node: RankInputNode, state: DebtState): number;
+/** `coverage`: an unattributable hunk caps it strictly below 1 (COVERAGE_CAP). @param {RankInputNode} node */
+export function coverage(node: RankInputNode): number;
+/** `hunkClears`: the named state gate, never shadowed by a fallback. @param {RankInputNode} node */
+export function hunkClears(node: RankInputNode): boolean;
+/**
+ * The path-conditioned partial-read hover copy. Returns null
+ * for every non-`partial-read` state. Callers only call this after checking
+ * `debtState(node) === 'partial-read'`.
+ * @param {RankInputNode} node
+ * @returns {string|null}
+ */
+export function partialReadHoverText(node: RankInputNode): string | null;
+/**
+ * State-specific honesty copy for every visible debt tag. The copy describes
+ * recorded evidence and always remains a prompt, never a claim about a person.
+ * @param {RankInputNode} node
+ * @param {DebtState} state
+ * @returns {string|null}
+ */
+export function debtHoverText(node: RankInputNode, state: DebtState): string | null;
+/**
+ * Up to two scent tags per row, including the softened `viewed`
+ * treatment and the multi-state debt vocabulary. The `partial-read` state
+ * reuses the strong/softened tag with the path-conditioned hover. No new
+ * tag for the partial state.
+ * @param {RankInputNode} node @param {DebtState} state @param {{focusId?:string|null, parentOf?:Map<string,string|null>, distanceToFocus?:number|null, maxTouch?:number, hoveredOrSelectedSessionId?:string|null}} [context]
+ * @returns {string[]}
+ */
+export function scentTagsFor(node: RankInputNode, state: DebtState, context?: {
+    focusId?: string | null;
+    parentOf?: Map<string, string | null>;
+    distanceToFocus?: number | null;
+    maxTouch?: number;
+    hoveredOrSelectedSessionId?: string | null;
+}): string[];
+/**
+ * Computes only payload/rank-mode intrinsic terms. A caller can memoize this
+ * object by node-array identity and rank mode; focus, filter, hover and session
+ * selection belong exclusively to `deriveRankedRows` below.
+ * @param {RankInputNode[]} nodes
+ * @param {{rankMode?: RankMode, nowMs?: number}} [options]
+ * @returns {IntrinsicRanking}
+ */
+export function rankMapNodesIntrinsic(nodes: RankInputNode[], options?: {
+    rankMode?: RankMode;
+    nowMs?: number;
+}): IntrinsicRanking;
+/**
+ * Applies focus distance, active-session scent, sort, and filter to memoized
+ * intrinsic terms. Ties break by node id; all-equal intrinsic terms stay 0.
+ * @param {IntrinsicRanking} intrinsicRanking
+ * @param {{focusId?: string|null, scentFilter?: string|null, hoveredOrSelectedSessionId?: string|null}} [options]
+ * @returns {RankedRow[]}
+ */
+export function deriveRankedRows(intrinsicRanking: IntrinsicRanking, options?: {
+    focusId?: string | null;
+    scentFilter?: string | null;
+    hoveredOrSelectedSessionId?: string | null;
+}): RankedRow[];
+/** Compatibility composition of the public two-phase ranking API.
+ * @param {RankInputNode[]} nodes
+ * @param {{rankMode?: RankMode, focusId?: string|null, scentFilter?: string|null, hoveredOrSelectedSessionId?: string|null, nowMs?: number}} [options]
+ */
+export function rankMapNodes(nodes: RankInputNode[], options?: {
+    rankMode?: RankMode;
+    focusId?: string | null;
+    scentFilter?: string | null;
+    hoveredOrSelectedSessionId?: string | null;
+    nowMs?: number;
+}): RankedRow[];
+/**
+ * Threshold gating: show `DOI >= max(0.25, 0.5*maxDOI)`, floor 5, cap 25,
+ * then a single "show all N files" expander. Deterministic, fixture-pinnable.
+ * In debt mode, known debt is included before thresholded unknown/clear rows,
+ * so threshold and cap gating cannot hide actionable evidence behind unknowns.
+ * @param {RankedRow[]} rows @param {{expanded?: boolean, rankMode?:RankMode}} [options]
+ * @returns {{visible: RankedRow[], total: number, overflowCount: number}}
+ */
+export function gateRankedRows(rows: RankedRow[], options?: {
+    expanded?: boolean;
+    rankMode?: RankMode;
+}): {
+    visible: RankedRow[];
+    total: number;
+    overflowCount: number;
+};
+/** @typedef {import('@peasant-labs/schema').ReadAttributionState} ReadAttributionState */
+/** @typedef {import('@peasant-labs/schema').ReadStateGrade} ReadStateGrade */
+/** @typedef {'relevance'|'debt'|'churn'} RankMode */
+/** @typedef {'unknown'|'none'|'reviewed'|'partial-read'|'viewed'|'no-recorded-read'} DebtState */
+/**
+ * One node's ranking-relevant scalars. Every field is read-only input; nothing
+ * here is mutated. `lastTouchMs` and `parent` are optional client-side hints
+ * hints. An absent value means "no recency/tree-focus
+ * signal", never a fabricated 0.
+ * @typedef {object} RankInputNode
+ * @property {string} id
+ * @property {string} name
+ * @property {number} touchCount
+ * @property {number} effortDensity - 0..1
+ * @property {number} agentEditedCount
+ * @property {number} readCount
+ * @property {ReadAttributionState} readAttribution
+ * @property {ReadStateGrade} readState - composed effective read-state grade for the CURRENT content version
+ * @property {number} changedRegionCount - total changed regions (Hall)
+ * @property {number} attributedRegionCount - attributed regions (H, M)
+ * @property {number} reviewedRegionCount - reviewed-of-attributed regions (N)
+ * @property {number} [lastTouchMs]
+ * @property {string|null} [parent]
+ * @property {string|null} [recentSessionId] - the session that most recently edited this node, if known
+ */
+/** @typedef {{id:string, name:string, doi:number, debtState:DebtState, debt:number, coverage:number, hunkClears:boolean, scentTags:string[], hoverText:string|null}} RankedRow */
+/** @typedef {{node:RankInputNode, intrinsic:number, debtState:DebtState, debt:number, coverage:number, hunkClears:boolean, hoverText:string|null}} IntrinsicRankedNode */
+/** @typedef {{rankMode:RankMode, rows:IntrinsicRankedNode[], parentOf:Map<string,string|null>, maxTouch:number}} IntrinsicRanking */
+/** DOI (degree-of-interest) term weights. Sum to 1.0 and are fixture-pinned. */
+export const DOI_WEIGHTS: Readonly<{
+    touch: 0.35;
+    effortDensity: 0.25;
+    debt: 0.25;
+    recency: 0.15;
+}>;
+/** Comprehension-debt constants, declared beside DOI_WEIGHTS per the frozen contract. */
+export const DEBT_VIEWED: 0.5;
+export const COVERAGE_CAP: 0.9;
+/** Recency half-life, days. */
+export const RECENCY_HALF_LIFE_DAYS: 14;
+/** Threshold-gating constants. */
+export const RANK_FLOOR: 5;
+export const RANK_CAP: 25;
+/**
+ * The seven-member scent-tag closed set. Exhaustiveness is enforced by
+ * `code-map-ranking.yaml`'s guard: every member must have at least one
+ * derivation case, so a future eighth tag without a case reddens.
+ * @type {readonly string[]}
+ */
+export const SCENT_TAGS: readonly string[];
+export type ReadAttributionState = import("@peasant-labs/schema").ReadAttributionState;
+export type ReadStateGrade = import("@peasant-labs/schema").ReadStateGrade;
+export type RankMode = "relevance" | "debt" | "churn";
+export type DebtState = "unknown" | "none" | "reviewed" | "partial-read" | "viewed" | "no-recorded-read";
+/**
+ * One node's ranking-relevant scalars. Every field is read-only input; nothing
+ * here is mutated. `lastTouchMs` and `parent` are optional client-side hints
+ * hints. An absent value means "no recency/tree-focus
+ * signal", never a fabricated 0.
+ */
+export type RankInputNode = {
+    id: string;
+    name: string;
+    touchCount: number;
+    /**
+     * - 0..1
+     */
+    effortDensity: number;
+    agentEditedCount: number;
+    readCount: number;
+    readAttribution: ReadAttributionState;
+    /**
+     * - composed effective read-state grade for the CURRENT content version
+     */
+    readState: ReadStateGrade;
+    /**
+     * - total changed regions (Hall)
+     */
+    changedRegionCount: number;
+    /**
+     * - attributed regions (H, M)
+     */
+    attributedRegionCount: number;
+    /**
+     * - reviewed-of-attributed regions (N)
+     */
+    reviewedRegionCount: number;
+    lastTouchMs?: number;
+    parent?: string | null;
+    /**
+     * - the session that most recently edited this node, if known
+     */
+    recentSessionId?: string | null;
+};
+export type RankedRow = {
+    id: string;
+    name: string;
+    doi: number;
+    debtState: DebtState;
+    debt: number;
+    coverage: number;
+    hunkClears: boolean;
+    scentTags: string[];
+    hoverText: string | null;
+};
+export type IntrinsicRankedNode = {
+    node: RankInputNode;
+    intrinsic: number;
+    debtState: DebtState;
+    debt: number;
+    coverage: number;
+    hunkClears: boolean;
+    hoverText: string | null;
+};
+export type IntrinsicRanking = {
+    rankMode: RankMode;
+    rows: IntrinsicRankedNode[];
+    parentOf: Map<string, string | null>;
+    maxTouch: number;
+};