@atlassian/chippy 0.0.0-stage → 0.0.1-beta.1

package/lib/types/avalanche/internals.d.ts

@@ -0,0 +1,189 @@
+export type ComponentType = Function | symbol | {
+    $$typeof?: symbol;
+    render?: Function;
+    displayName?: string;
+    name?: string;
+};
+interface StoreCheck {
+    getSnapshot: () => unknown;
+    value: unknown;
+}
+export interface Fiber {
+    tag: number;
+    type: ComponentType;
+    alternate: Fiber | null;
+    return: Fiber | null;
+    child: Fiber | null;
+    sibling: Fiber | null;
+    flags: number;
+    subtreeFlags: number;
+    lanes: number;
+    memoizedState: Hook | null;
+    memoizedProps?: unknown;
+    pendingProps?: unknown;
+    updateQueue: {
+        stores: StoreCheck[] | null;
+    } | null;
+    /**
+     * React populates this array during the render phase with fibers that will be
+     * deleted in the commit phase. Present when subtreeFlags & ChildDeletion !== 0.
+     * Only available in React 18+ (replaces the older effectList pattern).
+     */
+    deletions?: Fiber[] | null;
+    elementType?: unknown;
+    _debugSource?: {
+        fileName: string;
+        lineNumber: number;
+    };
+    _debugStack?: unknown;
+    _debugHookTypes?: string[];
+}
+export interface Hook {
+    memoizedState: unknown;
+    baseState: unknown;
+    baseQueue: unknown;
+    queue: HookQueue | null;
+    next: Hook | null;
+}
+interface HookQueue {
+    dispatch?: Function;
+    value?: unknown;
+    getSnapshot?: Function;
+    lastRenderedState?: unknown;
+}
+export interface DepOrigin {
+    type: ComponentType;
+    hookIndex: number;
+    depth: number;
+    hookType: 'useCallback' | 'useMemo';
+}
+export interface ThrashInfo {
+    hookIndex: number;
+    hookType: 'effect' | 'callback' | 'memo';
+    deps: unknown[];
+    changedDepIndices: number[];
+    changedDepOrigins: (DepOrigin | null)[];
+    effectTag?: number;
+    memoValue?: unknown;
+    /** The hook body function (for useCallback) or memoized value (for useMemo) */
+    hookBody?: Function | unknown;
+}
+export type ChangedHook = {
+    prevValue: unknown;
+    currentValue: unknown;
+    info?: string;
+} | 'repeat';
+export interface StateChangeResult {
+    hasChange: boolean;
+    actionable: boolean;
+    changedIndices: number[];
+    changedHooks: ChangedHook[];
+    /** True if any of the changes came from useSyncExternalStore */
+    hasExternalStoreChange: boolean;
+}
+export interface ThrashingResult {
+    effects: ThrashInfo[];
+    callbacks: ThrashInfo[];
+    memos: ThrashInfo[];
+}
+export declare const PerformedWork = 1;
+export declare const Placement = 2;
+export declare const Hydrating = 4096;
+export declare const SuspenseTag = 13;
+export declare const ChildDeletion = 16;
+export declare const Update = 4;
+export declare const DidCapture = 128;
+export declare function isComponentFiber(tag: number): boolean;
+export declare function isContextProviderFiber(tag: number): boolean;
+export declare function isSuspenseFiber(tag: number): boolean;
+/**
+ * Detect whether a Suspense boundary transitioned between suspended/unsuspended states.
+ *
+ * Suspense memoizedState is:
+ *   null                → primary content is showing (not suspended)
+ *   non-null (object)   → boundary is showing the fallback (suspended/dehydrated)
+ *
+ * Returns:
+ *   { entered: true }  — boundary just entered fallback
+ *                        - null → non-null (update path)
+ *                        - no alternate + memoizedState non-null (first render directly to fallback)
+ *   { left: true }     — boundary just left fallback / revealed primary (non-null → null)
+ *   null               — no state change (both null, both non-null, or first render not suspended)
+ *
+ * A Suspense that renders without delay never enters fallback, so memoizedState stays
+ * null → returns null → correctly ignored by the detector.
+ */
+export declare function didSuspenseStateChange(fiber: Fiber): {
+    entered: boolean;
+    left: boolean;
+} | null;
+/**
+ * Check if a Context Provider's value changed.
+ */
+export declare function didContextValueChange(fiber: Fiber): boolean;
+export declare function isReactInternalComponentType(type: ComponentType): boolean;
+export declare function getComponentName(fiber: Fiber): string;
+/**
+ * Check if hook is a state hook (useState/useReducer/useSyncExternalStore).
+ *
+ * All hooks share a base shape. The reliable differentiators:
+ * - useState/useReducer: queue.dispatch is a function
+ * - useSyncExternalStore: queue has 'value' and 'getSnapshot' properties
+ */
+export declare function isStateHook(hook: Hook): boolean;
+/** True if the hook is a useSyncExternalStore-like hook. */
+export declare function isExternalStoreHook(hook: Hook): boolean;
+/**
+ * Compare hook chains to detect state changes.
+ *
+ * IMPORTANT: Hook indices are React internal memoizedState indices, NOT code order.
+ * `useContext` hooks are not in memoizedState, causing index misalignment.
+ */
+export declare function detectHookStateChanges(prevHookChain: Hook | null, currentHookChain: Hook | null): StateChangeResult;
+/**
+ * Detect thrashing for hooks with deps: useEffect/useLayoutEffect/useInsertionEffect,
+ * useCallback and useMemo.
+ */
+export declare function detectHookThrashing(prevHookChain: Hook | null, currentHookChain: Hook | null, mode?: 'non-primitive' | 'all', valueProvenance?: WeakMap<object | Function, DepOrigin> | null): ThrashingResult;
+export declare function didFiberUpdate(fiber: Fiber): boolean;
+/**
+ * Detect if fiber has actionable hook state changes by comparing with fiber.alternate.
+ *
+ * ┌─────────────────────────────────────────────────────────────────────────────┐
+ * │  ⚠️  WARNING: fiber.alternate COMPARISON IS UNRELIABLE                      │
+ * └─────────────────────────────────────────────────────────────────────────────┘
+ *
+ * This function compares fiber.memoizedState vs fiber.alternate.memoizedState.
+ *
+ * THE PROBLEM:
+ *   fiber.alternate is NOT always "state from the previous commit".
+ *   It's "state from last time this fiber was used as work-in-progress".
+ *
+ *   If a component re-renders due to parent/context changes (not self-update),
+ *   its alternate may be stale - from 1 commit ago, or 100 commits ago!
+ *
+ *   This causes FALSE POSITIVES: we detect "state changed" when it didn't
+ *   change in THIS commit - it changed in some PAST commit.
+ *
+ * WHEN THIS FUNCTION IS RELIABLE:
+ *   ✓ Component called setState (it IS the initiator)
+ *   ✓ Component has useSyncExternalStore that just triggered
+ *   ✓ Used alongside memoizedUpdaters validation
+ *
+ * WHEN THIS FUNCTION IS UNRELIABLE:
+ *   ✗ Component re-rendered due to parent update
+ *   ✗ Component re-rendered due to context change
+ *   ✗ Component was memoized and skipped N commits
+ *   ✗ Any scenario where alternate wasn't recently updated
+ *
+ * RECOMMENDED USAGE:
+ *   - In development: Use memoizedUpdaters to verify component is an initiator,
+ *     THEN use this function to get hook change details.
+ *   - In production: Use lastSeenHookState tracking (see detector.tsx)
+ *     instead of relying on fiber.alternate.
+ *
+ * See detector.tsx for the full explanation of the "swap" problem and solution.
+ */
+export declare function didFiberSelfUpdate(fiber: Fiber): StateChangeResult | null;
+export declare function isDevelopment(): boolean;
+export {};

package/lib/types/avalanche/report-serializer.d.ts

@@ -0,0 +1,283 @@
+/**
+ * Report Serializer - Converts Report to serializable DTO.
+ *
+ * PROBLEM:
+ * The Report interface contains non-serializable data (Fiber references, ComponentType functions)
+ * which makes it unsuitable for JSON.stringify(), IPC, or network transmission.
+ *
+ * SOLUTION:
+ * Strip non-serializable fields (fiber, type). Keep only what's needed:
+ * - sourceId already contains component name (e.g., "MyComponent#1@5")
+ * - Metrics and numerical data
+ * - No need to convert anything - just omit problematic fields
+ *
+ * USAGE:
+ * ```typescript
+ * const report = detector.report(50);
+ * const dto = serializeReport(report);
+ *
+ * // Now safe to serialize
+ * const json = JSON.stringify(dto);
+ *
+ * // Send over IPC/network
+ * postMessage({ type: 'report', data: dto });
+ * ```
+ *
+ * DESIGN:
+ * - Minimal DTO - only what you need for metrics/analysis
+ * - sourceId already has component name - no conversion needed
+ * - Drop fiber and type fields completely
+ *
+ * The serializer is also the trust boundary between page-side React objects
+ * and helper/offline consumers. A DTO must remain stable after the page is
+ * gone, so it carries evidence and summaries rather than live object identity.
+ */
+import type { CommitMetricsDelta, IntegrationMode } from './commit-metrics-adapter.js';
+/**
+ * Commit stats tuple: [collateral, sources, restarts, performedWork, effects, memos, callbacks,
+ * contextUpdates, unmountedComponents, unmountedSubtrees]. Mirrors CommitStats in reporter.tsx.
+ */
+export type CommitStatsDTO = [
+    collateral: number,
+    sources: number,
+    restarts: number,
+    performedWork: number,
+    effects: number,
+    memos: number,
+    callbacks: number,
+    contextUpdates: number,
+    unmountedComponents: number,
+    unmountedSubtrees: number
+];
+/**
+ * Per-commit counter deltas from the commit metrics adapter, keyed by counter
+ * name. The counters depend on the adapter (see `meta.metricsAdapter`).
+ */
+export type CommitMetricsDeltaDTO = CommitMetricsDelta;
+/** @deprecated Use CommitMetricsDeltaDTO. Kept for one release. */
+export type ATLCommitDeltaDTO = CommitMetricsDeltaDTO;
+/**
+ * Commit timing data - measures React commit duration and detector overhead.
+ */
+export interface CommitTimingDTO {
+    timeSinceLastCommit: number;
+    detectorOverhead: number;
+}
+/**
+ * Report metadata - profiling context and overhead metrics.
+ */
+export interface ReportMetaDTO {
+    version: number;
+    commits: number;
+    config: {
+        detectionLevel: 'stats' | 'sources' | 'amplifierMetrics' | 'amplifiers' | 'full';
+        effectThrashMode: 'non-primitive' | 'all';
+        captureFibers: boolean;
+        historySize: number;
+    };
+    memoizedUpdatersSupport: {
+        available: boolean;
+        commitsWithData: number;
+        coverage: string;
+    };
+    /** Commit-hook integration model; older reports used `'atl'` for `'adapter:atl'`. */
+    integrationMode?: IntegrationMode | 'atl';
+    /** Id of the commit metrics adapter that drove the report, or null. */
+    metricsAdapter?: string | null;
+    /** Per-field availability for commitStats indices and metricsByCommit. */
+    dataAvailability?: Record<string, boolean>;
+    amplifiersMetrics?: {
+        totalHookThrashes: number;
+        affectedComponentCount: number;
+    };
+    timing: {
+        totalDetectorOverhead: number;
+        avgDetectorOverhead: number;
+        totalTimeSpan: number;
+        avgTimeBetweenCommits: number;
+    };
+}
+/**
+ * Minimal serializable source - just the metrics, no functions/fibers.
+ * sourceId already contains component name (e.g., "MyComponent#1@5")
+ */
+export interface SourceDTO {
+    sourceId: string;
+    depth: number;
+    collateralUpdates: number;
+    maxCollateralUpdates: number;
+    maxPenetrationDepth: number;
+    causedUpdates: number;
+    restartWaste?: number;
+    maxRestartWaste?: number;
+}
+/**
+ * Source entry in sourcesByCommit - which sources fired in each commit.
+ */
+export interface SourceByCommitDTO {
+    sourceId: string;
+    depth: number;
+    collateral: number;
+    rank: number | null;
+    sourceIndex: number | null;
+    trashers?: Array<{
+        index: number;
+        prevValue: unknown;
+        currentValue: unknown;
+    }>;
+    isRepeat?: boolean;
+}
+/**
+ * Serializable Report - minimal data for metrics and analysis.
+ * All non-serializable fields (fiber, type) are omitted.
+ */
+export interface SuspenseBoundaryEventDTO {
+    depth: number;
+    entered: boolean;
+    left: boolean;
+}
+export interface UnmountSampleDTO {
+    name: string;
+    key: string | null;
+    depth: number | null;
+    count: number;
+    source?: {
+        fileName?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+    } | null;
+}
+export type PropChangeKindDTO = 'same' | 'ref-changed' | 'scalar-changed' | 'added' | 'removed';
+export interface PropValueSummaryDTO {
+    type: string;
+    isArray: boolean;
+    isFunction: boolean;
+    isNull: boolean;
+    preview: string;
+    display?: string;
+    length?: number;
+    keysTop?: string[];
+    sample?: unknown[];
+}
+export interface PropChangeEvidenceDTO {
+    name: string;
+    kind: PropChangeKindDTO;
+    prev: PropValueSummaryDTO;
+    current: PropValueSummaryDTO;
+}
+export interface RenderedComponentEvidenceDTO {
+    sourceId: string;
+    name: string;
+    depth: number;
+    parentSourceId: string | null;
+    ownerSourceId: string | null;
+    isSelfSource: boolean;
+    propChanges: PropChangeEvidenceDTO[];
+    hasPropChanges: boolean;
+    trasherCounts: {
+        effects: number;
+        callbacks: number;
+        memos: number;
+    };
+}
+export interface CommitInteractionActionDTO {
+    id: number;
+    lastCommitId: number;
+    deltaTime: number;
+    action: string;
+    location: {
+        dom: {
+            tag: string | null;
+            text: string;
+            nearestTestId: string | null;
+        };
+        targetFiber: {
+            name: string | null;
+            key: string | null;
+            source: {
+                fileName?: string;
+                lineNumber?: number;
+                columnNumber?: number;
+            } | null;
+            ownerStackKind: 'owners' | 'parents';
+            ownerStack: Array<{
+                name: string | null;
+                key: string | null;
+                props: string[];
+                hookCount: number;
+                hookCountTruncated: boolean;
+                hookCountMax: number;
+                source: {
+                    fileName?: string;
+                    lineNumber?: number;
+                    columnNumber?: number;
+                } | null;
+            }>;
+        } | null;
+    };
+}
+export interface ReportDTO {
+    meta: ReportMetaDTO;
+    sources: SourceDTO[];
+    commitStats: Record<number, CommitStatsDTO>;
+    suspenseByCommit: Record<number, SuspenseBoundaryEventDTO[]>;
+    sourcesByCommit?: Record<number, SourceByCommitDTO[]>;
+    interactionsByCommit?: Record<number, CommitInteractionActionDTO[]>;
+    renderedByCommit?: Record<number, RenderedComponentEvidenceDTO[]>;
+    metricsByCommit?: Record<number, CommitMetricsDeltaDTO>;
+    /** @deprecated Alias of `metricsByCommit`, kept for one release. */
+    atlByCommit?: Record<number, CommitMetricsDeltaDTO>;
+    timing?: Record<number, CommitTimingDTO>;
+}
+/**
+ * Convert Report to serializable DTO.
+ *
+ * Strips non-serializable fields (fiber, type) and keeps only essential metrics.
+ *
+ * @param report - Full Report from detector.report()
+ * @returns Minimal serializable ReportDTO safe for JSON.stringify()
+ */
+export declare function serializeReport(report: {
+    meta: ReportMetaDTO;
+    sources: Array<{
+        sourceId: string;
+        depth: number;
+        causedUpdates: number;
+        collateralUpdates: number;
+        maxCollateralUpdates: number;
+        maxPenetrationDepth: number;
+        restartWaste?: number;
+        maxRestartWaste?: number;
+    }>;
+    commitStats: Record<number, CommitStatsDTO>;
+    sourcesByCommit?: Record<number, Array<{
+        sourceId: string;
+        depth: number;
+        collateral: number;
+        rank: number | null;
+        sourceIndex: number | null;
+        hooks?: Array<{
+            index: number;
+            prevValue: unknown;
+            currentValue: unknown;
+        }>;
+        trashers?: Array<{
+            index: number;
+            prevValue: unknown;
+            currentValue: unknown;
+        }>;
+        isRepeat?: boolean;
+    }>>;
+    suspenseByCommit?: Record<number, Array<{
+        depth: number;
+        entered: boolean;
+        left: boolean;
+        fiber?: unknown;
+    }>>;
+    interactionsByCommit?: Record<number, CommitInteractionActionDTO[]>;
+    renderedByCommit?: Record<number, RenderedComponentEvidenceDTO[]>;
+    metricsByCommit?: Record<number, CommitMetricsDeltaDTO>;
+    /** @deprecated Alias of `metricsByCommit`, kept for one release. */
+    atlByCommit?: Record<number, CommitMetricsDeltaDTO>;
+    timing?: Record<number, CommitTimingDTO>;
+}): ReportDTO;