@peasant-labs/fairtrade 0.0.3 → 0.0.4

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

@@ -0,0 +1,579 @@
+/**
+ * Classification of a map node within the path-derived tree.
+ * pkg/schema/map_api.go — MapNodeKind constants.
+ * @typedef {'module' | 'package' | 'file'} MapNodeKind
+ */
+/** Canonical MapNodeKind values, in schema order. @type {readonly MapNodeKind[]} */
+export const MAP_NODE_KINDS: readonly MapNodeKind[];
+/**
+ * How strongly a recorded session is bound to a change.
+ * pkg/schema/map_api.go — ChangeBinding constants.
+ * @typedef {'bound' | 'candidate'} ChangeBinding
+ */
+/** Canonical ChangeBinding values. @type {readonly ChangeBinding[]} */
+export const CHANGE_BINDINGS: readonly ChangeBinding[];
+/**
+ * Kind of structural violation on the map.
+ * pkg/schema/map_api.go — EdgeViolationKind constants.
+ * @typedef {'cycle' | 'wrong_way'} EdgeViolationKind
+ */
+/** Canonical EdgeViolationKind values. @type {readonly EdgeViolationKind[]} */
+export const EDGE_VIOLATION_KINDS: readonly EdgeViolationKind[];
+/**
+ * Per-file change status (branch vs merge-base). Git rename detection strips the
+ * similarity score, so "R100"/"R087" normalize to "R".
+ * Grounded in internal/gitops/repo.go — FileStatus{Modified,Added,Deleted,Renamed}
+ * ("M"/"A"/"D"/"R"); carried verbatim onto FileChange.Status / ChangeDiffPayload.Status
+ * in pkg/schema/map_api.go.
+ * @typedef {'M' | 'A' | 'D' | 'R'} FileChangeStatus
+ */
+/** Canonical FileChangeStatus values, in schema order. @type {readonly FileChangeStatus[]} */
+export const FILE_CHANGE_STATUSES: readonly FileChangeStatus[];
+/**
+ * Classification of one line within a unified-diff hunk.
+ * Grounded in internal/gitops/repo.go — DiffLine{Context,Added,Removed}
+ * ("context"/"add"/"del"); carried onto DiffLine.Kind in pkg/schema/map_api.go.
+ * @typedef {'context' | 'add' | 'del'} DiffLineKind
+ */
+/** Canonical DiffLineKind values, in schema order. @type {readonly DiffLineKind[]} */
+export const DIFF_LINE_KINDS: readonly DiffLineKind[];
+/**
+ * Classification of a map node within the path-derived tree.
+ * pkg/schema/map_api.go — MapNodeKind constants.
+ */
+export type MapNodeKind = "module" | "package" | "file";
+/**
+ * How strongly a recorded session is bound to a change.
+ * pkg/schema/map_api.go — ChangeBinding constants.
+ */
+export type ChangeBinding = "bound" | "candidate";
+/**
+ * Kind of structural violation on the map.
+ * pkg/schema/map_api.go — EdgeViolationKind constants.
+ */
+export type EdgeViolationKind = "cycle" | "wrong_way";
+/**
+ * Per-file change status (branch vs merge-base). Git rename detection strips the
+ * similarity score, so "R100"/"R087" normalize to "R".
+ * Grounded in internal/gitops/repo.go — FileStatus{Modified,Added,Deleted,Renamed}
+ * ("M"/"A"/"D"/"R"); carried verbatim onto FileChange.Status / ChangeDiffPayload.Status
+ * in pkg/schema/map_api.go.
+ */
+export type FileChangeStatus = "M" | "A" | "D" | "R";
+/**
+ * Classification of one line within a unified-diff hunk.
+ * Grounded in internal/gitops/repo.go — DiffLine{Context,Added,Removed}
+ * ("context"/"add"/"del"); carried onto DiffLine.Kind in pkg/schema/map_api.go.
+ */
+export type DiffLineKind = "context" | "add" | "del";
+/**
+ * Lightweight commit reference used in the time strip and unrecorded commits.
+ * Mirrors CommitRef from pkg/schema/map_api.go.
+ */
+export type CommitRefPayload = {
+    /**
+     * commit SHA
+     */
+    hash: string;
+    /**
+     * first line of the commit message
+     */
+    subject: string;
+    /**
+     * committer date, Unix millis; absent when unknown
+     */
+    timeMs?: number | null;
+    /**
+     * true when a recorded session is bound to this commit
+     */
+    hasSession: boolean;
+};
+/**
+ * A structure (import) dependency edge between two map nodes.
+ * Mirrors MapEdge from pkg/schema/map_api.go.
+ */
+export type MapEdgePayload = {
+    /**
+     * source node ID (repo-relative path)
+     */
+    from: string;
+    /**
+     * target node ID
+     */
+    to: string;
+    /**
+     * underlying import count (aggregated)
+     */
+    count: number;
+};
+/**
+ * A co-edit (activity) observation edge: two nodes repeatedly edited by the
+ * same tasks. DISTINCT from MapEdgePayload — the count channel is `taskCount`
+ * (distinct tasks that edited both endpoints), NOT the import `count`.
+ * Mirrors ActivityEdge from pkg/schema/map_api.go.
+ */
+export type ActivityEdgePayload = {
+    /**
+     * source node ID
+     */
+    from: string;
+    /**
+     * target node ID
+     */
+    to: string;
+    /**
+     * distinct tasks that edited both endpoints
+     */
+    taskCount: number;
+};
+/**
+ * A structural violation — a cycle or wrong-way import — on the map.
+ * Mirrors EdgeViolation from pkg/schema/map_api.go.
+ */
+export type EdgeViolationPayload = {
+    kind: EdgeViolationKind;
+    /**
+     * source node ID
+     */
+    from: string;
+    /**
+     * target node ID
+     */
+    to: string;
+};
+/**
+ * One node on the code map (module, package, or file). Topology-only: the
+ * lifted <CodeMap> component derives pixel positions from layer/order using
+ * layout.ts internally; consumers supply raw topology.
+ * Mirrors MapNode from pkg/schema/map_api.go (field-for-field).
+ */
+export type MapNodePayload = {
+    /**
+     * repo-relative path, e.g. "internal/ingest" or "web/src/lib/api.ts"
+     */
+    id: string;
+    /**
+     * ID of parent node; absent for top-level modules
+     */
+    parent?: string;
+    kind: MapNodeKind;
+    /**
+     * display leaf, e.g. "ingest"
+     */
+    name: string;
+    /**
+     * e.g. "go" or "typescript"; absent for activity-only nodes
+     */
+    language?: string;
+    /**
+     * 0 = top row; deterministic, server-assigned
+     */
+    layer: number;
+    /**
+     * stable sort within layer; server-assigned
+     */
+    order: number;
+    /**
+     * size metric (lines of code)
+     */
+    loc: number;
+    /**
+     * 1 for file nodes
+     */
+    fileCount: number;
+    /**
+     * files whose last edit traces to a recorded session
+     */
+    recordedFiles: number;
+    totalFiles: number;
+    /**
+     * recorded edits in the activity window (activity size metric)
+     */
+    touchCount: number;
+    /**
+     * 0..1 per-file re-edit/error density rollup (0 when unknown)
+     */
+    effortDensity: number;
+};
+/**
+ * A scoped sub-map: the touched nodes plus their one-hop neighborhood, with
+ * layer/order preserved from the full map. Used inside ChangeDetailPayload.
+ * Mirrors MapSlice from pkg/schema/map_api.go.
+ */
+export type MapSlicePayload = {
+    /**
+     * topology-only; layer/order from the full map
+     */
+    nodes: MapNodePayload[];
+    /**
+     * parsed import edges within the slice (count = import count)
+     */
+    structureEdges: MapEdgePayload[];
+    /**
+     * co-edit observations within the slice (taskCount, NOT count)
+     */
+    activityEdges: ActivityEdgePayload[];
+};
+/**
+ * One row in the Changes list: a local branch measured against the default
+ * branch. Graph anchors (baseHash/tipCommitMs/mergeCommitHash) tie this row
+ * to the time strip lane.
+ * Mirrors ChangeSummary from pkg/schema/map_api.go.
+ */
+export type ChangeSummaryPayload = {
+    branch: string;
+    /**
+     * commits ahead of the default branch
+     */
+    aheadCount: number;
+    behindCount: number;
+    filesChanged: number;
+    /**
+     * recorded sessions bound to this change
+     */
+    sessionCount: number;
+    /**
+     * distinct tasks across bound sessions
+     */
+    taskCount: number;
+    /**
+     * new import edges introduced
+     */
+    newEdges: number;
+    removedEdges: number;
+    /**
+     * count of structural violations introduced
+     */
+    violations: number;
+    /**
+     * most-recent recorded-session activity, Unix millis
+     */
+    lastWorkMs?: number | null;
+    merged: boolean;
+    mergedAtMs?: number | null;
+    /**
+     * true when this merged change was later git-reverted
+     */
+    reverted?: boolean;
+    /**
+     * graph anchor: merge-base commit hash (fork point; open branches)
+     */
+    baseHash?: string;
+    /**
+     * graph anchor: branch tip committer time (row position; open branches)
+     */
+    tipCommitMs?: number | null;
+    /**
+     * graph anchor: merge commit hash (join point; merged rows)
+     */
+    mergeCommitHash?: string;
+};
+/**
+ * The Changes surface prop payload. The adapter maps ReviewListPayload (CLEAN)
+ * onto this shape — field-for-field, no reshaping required.
+ */
+export type ChangesPayload = {
+    /**
+     * false when the project root is not a git repo
+     */
+    repoFound: boolean;
+    defaultBranch?: string;
+    /**
+     * open branches first, then merged (reverse-chron within each)
+     */
+    changes: ChangeSummaryPayload[];
+    /**
+     * default-branch commits for the time strip, cap 200
+     */
+    recentCommits: CommitRefPayload[];
+};
+/**
+ * One task within a change's bound sessions.
+ * Mirrors TaskSummary from pkg/schema/map_api.go.
+ */
+export type TaskSummaryPayload = {
+    sessionId: string;
+    /**
+     * depth-0 user-turn index (task identity)
+     */
+    entryIndex: number;
+    /**
+     * first ~80 chars of the user turn
+     */
+    title: string;
+    /**
+     * task start, Unix millis
+     */
+    startMs?: number | null;
+    /**
+     * session-level outcome string
+     */
+    outcome?: string;
+    /**
+     * repo-relative paths touched by this task
+     */
+    editedFiles: string[];
+    /**
+     * reads within this task's range
+     */
+    readCount: number;
+    /**
+     * true when an error streak ≥2 occurs inside this task
+     */
+    retryLoop: boolean;
+    /**
+     * effective auto/manual annotation values
+     */
+    labels: string[];
+};
+/**
+ * One recorded session bound to a change, with its tasks.
+ * Mirrors ChangeSession from pkg/schema/map_api.go.
+ */
+export type ChangeSessionPayload = {
+    sessionId: string;
+    title: string;
+    harness: string;
+    startMs?: number | null;
+    /**
+     * "bound" = commit-in-branch AND file overlap; "candidate" = one arm only
+     */
+    binding: ChangeBinding;
+    tasks: TaskSummaryPayload[];
+};
+/**
+ * One neutral rate-elevation observation: a metric that runs above the project
+ * baseline for this change. Factual, never a grade.
+ * Mirrors UnusualSignal from pkg/schema/map_api.go.
+ */
+export type UnusualSignalPayload = {
+    /**
+     * stable slug, e.g. "retryLoops"
+     */
+    kind: string;
+    /**
+     * plain, neutral description
+     */
+    label: string;
+    /**
+     * this change's per-conversation rate
+     */
+    perChange: number;
+    /**
+     * project baseline rate
+     */
+    perProject: number;
+};
+/**
+ * A neutral count of a recurring friction signal keyed to a file.
+ * Mirrors FrictionCluster from pkg/schema/map_api.go.
+ */
+export type FrictionClusterPayload = {
+    /**
+     * signal slug, e.g. "retryLoop"
+     */
+    kind: string;
+    /**
+     * plain, neutral, e.g. "retry loops"
+     */
+    label: string;
+    /**
+     * repo-relative path
+     */
+    file: string;
+    /**
+     * occurrences (retry-loop tasks touching this file)
+     */
+    count: number;
+    /**
+     * distinct conversations the occurrences span
+     */
+    sessions: number;
+};
+/**
+ * One changed file within a branch (branch vs its merge-base).
+ * Mirrors FileChange from pkg/schema/map_api.go.
+ */
+export type FileChangePayload = {
+    path: string;
+    /**
+     * modified / added / deleted / renamed
+     */
+    status: FileChangeStatus;
+    /**
+     * present for renames
+     */
+    oldPath?: string | null;
+    /**
+     * 0 for binary files or when numstat is unavailable
+     */
+    linesAdded: number;
+    linesRemoved: number;
+};
+/**
+ * The ChangeDetail surface prop payload. The adapter maps the wire
+ * ChangeDetailPayload (CLEAN) onto this shape — field-for-field.
+ * The lazy per-file diff (ChangeDiffPayload) is fetched separately and wired
+ * via a callback/slot on the ChangeDetail surface; it is NOT embedded here.
+ */
+export type ChangeDetailPayload = {
+    branch: string;
+    /**
+     * merge-base commit hash
+     */
+    baseRef: string;
+    defaultBranch: string;
+    /**
+     * changed files (branch vs merge-base)
+     */
+    files: FileChangePayload[];
+    /**
+     * touched nodes + 1-hop neighborhood
+     */
+    slice: MapSlicePayload;
+    /**
+     * new import edges introduced
+     */
+    newEdges: MapEdgePayload[];
+    removedEdges: MapEdgePayload[];
+    /**
+     * new node IDs
+     */
+    newNodes: string[];
+    removedNodes: string[];
+    /**
+     * structural violations INTRODUCED by this change
+     */
+    violations: EdgeViolationPayload[];
+    /**
+     * bound sessions, with tasks (each = one "conversation"; count = work.length)
+     */
+    work: ChangeSessionPayload[];
+    /**
+     * commits on the branch with no recorded session
+     */
+    unrecordedCommits: CommitRefPayload[];
+    /**
+     * neutral rate-elevation observations
+     */
+    unusual: UnusualSignalPayload[];
+    /**
+     * neutral recurring-friction counts
+     */
+    frictions: FrictionClusterPayload[];
+    /**
+     * authoritative changed-file count (from the matching ChangeSummary; files[] may be capped)
+     */
+    filesChanged: number;
+    linesAdded: number;
+    linesRemoved: number;
+    /**
+     * SUM of output_tokens over bound sessions (the "ai wrote ≈N tokens" stat)
+     */
+    outputTokens: number;
+    costUsd?: number | null;
+};
+/**
+ * One line within a diff hunk. `kind` uses the unified-diff convention.
+ * Mirrors DiffLine from pkg/schema/map_api.go.
+ */
+export type DiffLinePayload = {
+    /**
+     * context / add / del
+     */
+    kind: DiffLineKind;
+    /**
+     * line text, WITHOUT the leading +/-/space marker
+     */
+    text: string;
+};
+/**
+ * One unified-diff hunk (the `-old +new` range line). May carry conversation
+ * attribution when the hunk's added lines trace to a recorded session via git blame.
+ * Mirrors DiffHunk from pkg/schema/map_api.go.
+ */
+export type DiffHunkPayload = {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    /**
+     * hunk range header line, when present
+     */
+    header?: string;
+    lines: DiffLinePayload[];
+    /**
+     * conversation attribution: recorded session that wrote most of the hunk's new lines
+     */
+    sessionId?: string;
+    sessionTitle?: string;
+};
+/**
+ * The lazy per-file diff payload — fetched on demand when the user opens a
+ * file's diff inside the ChangeDetail surface. Adapter maps the wire
+ * ChangeDiffPayload (CLEAN) onto this shape — field-for-field.
+ */
+export type ChangeDiffPayload = {
+    branch: string;
+    /**
+     * the new (or only) file path
+     */
+    file: string;
+    /**
+     * present for renames
+     */
+    oldPath?: string | null;
+    /**
+     * modified / added / deleted / renamed
+     */
+    status: FileChangeStatus;
+    /**
+     * true for binary files (no hunks)
+     */
+    binary: boolean;
+    /**
+     * true when the file exceeds the size cap
+     */
+    truncated: boolean;
+    hunks: DiffHunkPayload[];
+    /**
+     * HOST-SIDE error sentinel — NOT a wire field. The adapter
+     *       must never map this from the REST payload; the host sets it
+     *       (with empty `hunks`) when its lazy diff fetch FAILED, so the
+     *       surface renders an error row instead of a perpetual spinner.
+     */
+    error?: string;
+};
+/**
+ * The CodeMap surface prop payload. The adapter maps MapGraphPayload
+ * (TRANSFORM) onto this shape: topology passes through field-for-field via
+ * mapGraphToData() (web/src/app/map/lib/mapData.ts); the lifted <CodeMap>
+ * component derives pixel geometry (x/y + width) from layer/order internally
+ * using layout.ts — geometry is NOT a field in this payload.
+ *
+ * activityEdges are excluded here: they feed the node-detail rail's
+ * "often edited with" rows, not the canvas. The surface slice wires them
+ * separately as a node-detail prop.
+ *
+ * Interaction-parity props (onExpand, highlightedIds, zoom, onZoomChange,
+ * Review changed-slice overlays, effort overlay, keyboard) are component-level
+ * props defined in the surface slice, not data fields in this payload.
+ */
+export type CodeMapPayload = {
+    /**
+     * false when the project root is not a git repo; the component degrades to activity-only
+     */
+    repoFound: boolean;
+    /**
+     * topology nodes for all zoom levels; parent links form the tree
+     */
+    nodes: MapNodePayload[];
+    /**
+     * parsed import edges (aggregated per node pair)
+     */
+    structureEdges: MapEdgePayload[];
+    /**
+     * structural violations (cycles + wrong-way imports)
+     */
+    violations: EdgeViolationPayload[];
+};

package/dist/lib/types/index.d.ts

@@ -53,3 +53,4 @@ export { default as SignInProviders, HandleClaim, OnboardingCard } from "./SignI
 export { default as CliSteps, CommandBlock, GettingStarted } from "./CliOnboard.jsx";
 export { StatTile, StatGrid, GovTile, ProviderBars } from "./StatTiles.jsx";
 export { default as VisibilitySegmented, VisibilityEye, ScopeChip, FocusedModeToggle } from "./VisibilityControl.jsx";
+export { default as InUseShell, GraphAppShell, GraphSectionNav, IN_USE_APPS, GRAPH_APP_SECTIONS } from "./inuse/InUseShell.jsx";

package/dist/lib/types/inuse/InUseShell.d.ts

@@ -0,0 +1,50 @@
+export default function InUseShell({ apps, defaultApp, activeApp, onAppChange, renderApp, brand, ariaLabel, }: {
+    apps?: readonly {
+        id: string;
+        mark: string;
+        icon: react.ForwardRefExoticComponent<any>;
+    }[];
+    defaultApp: any;
+    activeApp: any;
+    onAppChange: any;
+    renderApp: any;
+    brand?: string;
+    ariaLabel?: string;
+}): any;
+export function GraphAppShell({ sections, activeId, activePrimaryId, onSectionChange, backTo, onBack, children, ariaLabel, }: {
+    sections?: readonly {
+        id: string;
+        label: string;
+    }[];
+    activeId: any;
+    activePrimaryId: any;
+    onSectionChange: any;
+    backTo: any;
+    onBack: any;
+    children: any;
+    ariaLabel?: string;
+}): any;
+export function GraphSectionNav({ sections, activeId, hrefFor, LinkComponent, onSectionChange, className, itemClassName, activeItemClassName, activeMarker, ariaLabel, }: {
+    sections?: readonly {
+        id: string;
+        label: string;
+    }[];
+    activeId?: any;
+    hrefFor?: any;
+    LinkComponent?: any;
+    onSectionChange?: any;
+    className?: string;
+    itemClassName?: string;
+    activeItemClassName?: string;
+    activeMarker?: any;
+    ariaLabel?: string;
+}): any;
+export const IN_USE_APPS: readonly {
+    id: string;
+    mark: string;
+    icon: react.ForwardRefExoticComponent<any>;
+}[];
+export const GRAPH_APP_SECTIONS: readonly {
+    id: string;
+    label: string;
+}[];