@agent-scope/cli 1.9.0 → 1.11.0

package/dist/index.d.cts

@@ -89,6 +89,224 @@ declare function runInit(options: InitOptions): Promise<InitResult>;
 
 declare function createInitCommand(): Command;
 
+/**
+ * @agent-scope/cli — instrument hooks command
+ *
+ * Implements `scope instrument hooks <component>`.
+ *
+ * Renders the component via a Playwright page (same harness as render-commands),
+ * then extracts per-hook-instance profiling data from the live React fiber tree.
+ *
+ * Per-hook tracking (React Instrumentation Spec §4):
+ *   useState:    currentValue, updateCount, updateOrigins
+ *   useEffect:   dependencyValues, fireCount, lastDuration, cleanupPresence
+ *   useMemo:     dependencyValues, recomputeCount, cacheHitRate
+ *   useCallback: dependencyValues, recreationCount, cacheHitRate
+ *   useRef:      currentValue, readCountDuringRender
+ *   useContext:  contextType, valueAccessFrequency
+ *   useReducer:  actionTypesDispatched, stateTransitions
+ *
+ * Output: per-component hook inventory JSON, plus heuristic flags from §6.1.
+ */
+
+/**
+ * Heuristic flags from §6.1 that apply to hook-level analysis.
+ */
+type HookHeuristicFlag = "WASTED_RENDER" | "MEMO_INEFFECTIVE" | "EFFECT_EVERY_RENDER" | "MISSING_CLEANUP" | "STALE_CLOSURE" | "STATE_UPDATE_LOOP";
+/** Per-hook-instance profiling record. */
+interface HookProfile {
+    /** 0-based call-order index within the component. */
+    index: number;
+    /** Hook type inferred from fiber shape. */
+    type: string;
+    /** useState / useReducer: current state value (serialised). */
+    currentValue?: unknown;
+    /** useState / useReducer: number of state updates observed. */
+    updateCount?: number;
+    /** useEffect / useLayoutEffect: number of times the effect fired. */
+    fireCount?: number;
+    /** useEffect / useLayoutEffect: last measured run duration in ms (null when unavailable). */
+    lastDuration?: number | null;
+    /** useEffect / useLayoutEffect: whether a cleanup function was returned. */
+    cleanupPresence?: boolean;
+    /** useMemo / useCallback: number of times value was recomputed (deps changed). */
+    recomputeCount?: number;
+    /** useMemo / useCallback: ratio of cache hits to total checks (0-1). */
+    cacheHitRate?: number;
+    /** useRef: current value. */
+    currentRefValue?: unknown;
+    /** useRef: number of times .current was read during render (heuristic). */
+    readCountDuringRender?: number;
+    /** useContext: serialised context value. */
+    contextValue?: unknown;
+    /** useReducer: action type strings dispatched so far. */
+    actionTypesDispatched?: string[];
+    /** Dependency values serialised (for hooks that accept deps). */
+    dependencyValues?: unknown[] | null;
+}
+/** Profiling result for a single component. */
+interface ComponentHookProfile {
+    /** Component display name. */
+    name: string;
+    /** Source location (if available). */
+    source?: {
+        file: string;
+        line: number;
+    } | null;
+    /** Ordered list of hook profiles (one per hook call site). */
+    hooks: HookProfile[];
+    /** Heuristic flags detected for this component. */
+    flags: HookHeuristicFlag[];
+}
+/** Top-level result returned by runHooksProfiling(). */
+interface HooksProfilingResult {
+    /** Profiled component name passed on the CLI. */
+    component: string;
+    /** Per-component hook inventory. */
+    components: ComponentHookProfile[];
+    /** Global heuristic flags (union of all component flags). */
+    flags: HookHeuristicFlag[];
+}
+
+/**
+ * @agent-scope/cli — instrument profile command
+ *
+ * Implements `scope instrument profile <component> --interaction '...'`.
+ *
+ * Renders the component via a Playwright page, replays a structured interaction
+ * sequence, and captures a full interaction profile per React Instrumentation
+ * Spec §5:
+ *
+ *   - totalRenders       — total commit count during the interaction window
+ *   - uniqueComponents   — distinct component names that re-rendered
+ *   - wastedRenders      — re-renders where output was identical (heuristic)
+ *   - timing.js          — JS execution time (ms) measured via Performance API
+ *   - timing.layout      — Layout/reflow time (ms) measured via PerformanceObserver
+ *   - timing.paint       — Paint time (ms) measured via PerformanceObserver
+ *   - layoutShifts       — { count, cumulativeScore } via Layout Instability API
+ *
+ * Heuristic flags from §6.1 catalog: WASTED_RENDER, MEMO_INEFFECTIVE,
+ * EFFECT_EVERY_RENDER, etc.
+ */
+
+/** An interaction step definition (JSON format per spec). */
+interface InteractionStep$1 {
+    /** Playwright action: click, fill, hover, press, wait */
+    action: "click" | "fill" | "hover" | "press" | "wait";
+    /** CSS selector or descriptive target for the element */
+    target?: string;
+    /** Value to type (for fill) or key to press (for press) */
+    value?: string;
+    /** Delay in ms (for wait action) */
+    delay?: number;
+}
+/** Performance timing captured during the interaction window. */
+interface InteractionTiming {
+    /** JS execution time in ms (from performance.now() around interactions). */
+    js: number;
+    /** Layout time in ms (from PerformanceObserver layout entries). */
+    layout: number;
+    /** Paint time in ms (from PerformanceObserver paint entries). */
+    paint: number;
+}
+/** Layout shift data (Cumulative Layout Shift). */
+interface LayoutShiftData {
+    /** Number of layout shift events observed. */
+    count: number;
+    /** Cumulative layout shift score. */
+    cumulativeScore: number;
+}
+/**
+ * Heuristic flags from §6.1 catalog applicable to interaction profiling.
+ */
+type ProfileHeuristicFlag = "WASTED_RENDER" | "MEMO_INEFFECTIVE" | "EFFECT_EVERY_RENDER" | "MISSING_CLEANUP" | "HIGH_RENDER_COUNT" | "LAYOUT_SHIFT_DETECTED" | "SLOW_INTERACTION";
+/** Full interaction profile result per Spec §5. */
+interface InteractionProfile {
+    /** Component name profiled. */
+    component: string;
+    /** Total number of React commits (renders) during the interaction window. */
+    totalRenders: number;
+    /** Number of distinct component names that re-rendered during the window. */
+    uniqueComponents: number;
+    /** Estimated number of "wasted" renders (components that re-rendered without output change). */
+    wastedRenders: number;
+    /** Timing breakdown in ms. */
+    timing: InteractionTiming;
+    /** Layout shift metrics. */
+    layoutShifts: LayoutShiftData;
+    /** Heuristic flags from §6.1 catalog. */
+    flags: ProfileHeuristicFlag[];
+    /** Interaction steps that were replayed. */
+    interaction: InteractionStep$1[];
+}
+
+/** Root cause categories per Instrumentation Spec §2.1 */
+type RenderTrigger = "state_change" | "props_change" | "context_change" | "parent_rerender" | "force_update" | "hook_dependency";
+/** A single link in the causality chain from root cause to this render */
+interface CausalityLink {
+    component: string;
+    trigger: RenderTrigger;
+    propsChanged?: boolean;
+    stateChanged?: boolean;
+    contextChanged?: boolean;
+    origin?: string;
+    stateKey?: string;
+}
+/** Per-component render event with causality chain */
+interface RenderEvent {
+    component: string;
+    renderIndex: number;
+    trigger: RenderTrigger;
+    propsChanged: boolean;
+    stateChanged: boolean;
+    contextChanged: boolean;
+    memoized: boolean;
+    /** Wasted render: re-rendered with no changed inputs and not memoized */
+    wasted: boolean;
+    chain: CausalityLink[];
+    cascade: {
+        totalRendersTriggered: number;
+        uniqueComponents: number;
+        unchangedPropRenders: number;
+    };
+}
+/** Heuristic flag from Instrumentation Spec §6.1 */
+interface InstrumentFlag {
+    id: string;
+    severity: "error" | "warning" | "info";
+    component: string;
+    detail: string;
+    data: Record<string, unknown>;
+}
+/** Full output of the renders analysis */
+interface RendersAnalysisResult {
+    component: string;
+    interaction: InteractionStep[];
+    summary: {
+        totalRenders: number;
+        uniqueComponents: number;
+        wastedRenders: number;
+        interactionDurationMs: number;
+    };
+    renders: RenderEvent[];
+    flags: InstrumentFlag[];
+}
+/** Interaction step definition per Instrumentation Spec §5.1 */
+interface InteractionStep {
+    action: "click" | "type" | "wait" | "hover" | "blur" | "focus" | "scroll";
+    target?: string;
+    text?: string;
+    condition?: string;
+    timeout?: number;
+    x?: number;
+    y?: number;
+}
+/**
+ * Creates the `scope instrument` command group.
+ * Contains: `scope instrument renders`, `scope instrument hooks`, `scope instrument profile`
+ */
+declare function createInstrumentCommand(): Command;
+
 /**
  * @agent-scope/cli — manifest sub-commands
  *
@@ -155,4 +373,49 @@ declare function createProgram(options?: ScopeCLIOptions): Command;
  */
 declare function createTokensCommand(): Command;
 
-export { type InitOptions, type InitResult, type ListRow, type QueryRow, type ReactScopeConfig, type ScopeCLIOptions, createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };
+/**
+ * @agent-scope/cli — tokens export sub-command
+ *
+ * Implements `scope tokens export --format <fmt>` which converts a resolved
+ * token set into one of six downstream formats:
+ *
+ *   css        — CSS custom properties (:root { --color-primary-500: … })
+ *   ts         — TypeScript const exports (export const colorPrimary500 = …)
+ *   scss       — SCSS variable declarations ($color-primary-500: …)
+ *   tailwind   — Tailwind CSS theme.extend object (module.exports = { … })
+ *   flat-json  — Flat key→value JSON { "color.primary.500": "#3B82F6" }
+ *   figma      — Figma Tokens JSON (nested value+type objects)
+ *
+ * Token file resolution priority:
+ *   1. `--file` flag
+ *   2. `tokens.file` field in `reactscope.config.json`
+ *   3. `reactscope.tokens.json` in cwd (default)
+ *
+ * Output defaults to stdout (pipe-friendly). Use `--out <path>` to write to
+ * a file instead.
+ *
+ * Theme-aware export: if the token file contains a `themes` block and
+ * `--theme <name>` is passed, theme overrides are included in formats that
+ * support them (css, ts, scss, tailwind, figma).
+ */
+
+/**
+ * Resolve the path to the token file.
+ *
+ * Priority:
+ *  1. Explicit `--file` flag value
+ *  2. `tokens.file` in `reactscope.config.json`
+ *  3. `reactscope.tokens.json` in cwd
+ */
+declare function resolveTokenFilePath(fileFlag?: string): string;
+/**
+ * Create and return the `tokens export` sub-command.
+ *
+ * Intended to be registered on the parent `tokens` Command:
+ * ```ts
+ * tokensCmd.addCommand(createTokensExportCommand());
+ * ```
+ */
+declare function createTokensExportCommand(): Command;
+
+export { type CausalityLink, type ComponentHookProfile, type HookHeuristicFlag, type HookProfile, type HooksProfilingResult, type InitOptions, type InitResult, type InteractionProfile, type InteractionStep$1 as InteractionStep, type InteractionTiming, type LayoutShiftData, type ListRow, type ProfileHeuristicFlag, type QueryRow, type ReactScopeConfig, type RenderEvent, type RenderTrigger, type RendersAnalysisResult, type ScopeCLIOptions, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, isTTY, matchGlob, resolveTokenFilePath, runInit };

package/dist/index.d.ts

@@ -89,6 +89,224 @@ declare function runInit(options: InitOptions): Promise<InitResult>;
 
 declare function createInitCommand(): Command;
 
+/**
+ * @agent-scope/cli — instrument hooks command
+ *
+ * Implements `scope instrument hooks <component>`.
+ *
+ * Renders the component via a Playwright page (same harness as render-commands),
+ * then extracts per-hook-instance profiling data from the live React fiber tree.
+ *
+ * Per-hook tracking (React Instrumentation Spec §4):
+ *   useState:    currentValue, updateCount, updateOrigins
+ *   useEffect:   dependencyValues, fireCount, lastDuration, cleanupPresence
+ *   useMemo:     dependencyValues, recomputeCount, cacheHitRate
+ *   useCallback: dependencyValues, recreationCount, cacheHitRate
+ *   useRef:      currentValue, readCountDuringRender
+ *   useContext:  contextType, valueAccessFrequency
+ *   useReducer:  actionTypesDispatched, stateTransitions
+ *
+ * Output: per-component hook inventory JSON, plus heuristic flags from §6.1.
+ */
+
+/**
+ * Heuristic flags from §6.1 that apply to hook-level analysis.
+ */
+type HookHeuristicFlag = "WASTED_RENDER" | "MEMO_INEFFECTIVE" | "EFFECT_EVERY_RENDER" | "MISSING_CLEANUP" | "STALE_CLOSURE" | "STATE_UPDATE_LOOP";
+/** Per-hook-instance profiling record. */
+interface HookProfile {
+    /** 0-based call-order index within the component. */
+    index: number;
+    /** Hook type inferred from fiber shape. */
+    type: string;
+    /** useState / useReducer: current state value (serialised). */
+    currentValue?: unknown;
+    /** useState / useReducer: number of state updates observed. */
+    updateCount?: number;
+    /** useEffect / useLayoutEffect: number of times the effect fired. */
+    fireCount?: number;
+    /** useEffect / useLayoutEffect: last measured run duration in ms (null when unavailable). */
+    lastDuration?: number | null;
+    /** useEffect / useLayoutEffect: whether a cleanup function was returned. */
+    cleanupPresence?: boolean;
+    /** useMemo / useCallback: number of times value was recomputed (deps changed). */
+    recomputeCount?: number;
+    /** useMemo / useCallback: ratio of cache hits to total checks (0-1). */
+    cacheHitRate?: number;
+    /** useRef: current value. */
+    currentRefValue?: unknown;
+    /** useRef: number of times .current was read during render (heuristic). */
+    readCountDuringRender?: number;
+    /** useContext: serialised context value. */
+    contextValue?: unknown;
+    /** useReducer: action type strings dispatched so far. */
+    actionTypesDispatched?: string[];
+    /** Dependency values serialised (for hooks that accept deps). */
+    dependencyValues?: unknown[] | null;
+}
+/** Profiling result for a single component. */
+interface ComponentHookProfile {
+    /** Component display name. */
+    name: string;
+    /** Source location (if available). */
+    source?: {
+        file: string;
+        line: number;
+    } | null;
+    /** Ordered list of hook profiles (one per hook call site). */
+    hooks: HookProfile[];
+    /** Heuristic flags detected for this component. */
+    flags: HookHeuristicFlag[];
+}
+/** Top-level result returned by runHooksProfiling(). */
+interface HooksProfilingResult {
+    /** Profiled component name passed on the CLI. */
+    component: string;
+    /** Per-component hook inventory. */
+    components: ComponentHookProfile[];
+    /** Global heuristic flags (union of all component flags). */
+    flags: HookHeuristicFlag[];
+}
+
+/**
+ * @agent-scope/cli — instrument profile command
+ *
+ * Implements `scope instrument profile <component> --interaction '...'`.
+ *
+ * Renders the component via a Playwright page, replays a structured interaction
+ * sequence, and captures a full interaction profile per React Instrumentation
+ * Spec §5:
+ *
+ *   - totalRenders       — total commit count during the interaction window
+ *   - uniqueComponents   — distinct component names that re-rendered
+ *   - wastedRenders      — re-renders where output was identical (heuristic)
+ *   - timing.js          — JS execution time (ms) measured via Performance API
+ *   - timing.layout      — Layout/reflow time (ms) measured via PerformanceObserver
+ *   - timing.paint       — Paint time (ms) measured via PerformanceObserver
+ *   - layoutShifts       — { count, cumulativeScore } via Layout Instability API
+ *
+ * Heuristic flags from §6.1 catalog: WASTED_RENDER, MEMO_INEFFECTIVE,
+ * EFFECT_EVERY_RENDER, etc.
+ */
+
+/** An interaction step definition (JSON format per spec). */
+interface InteractionStep$1 {
+    /** Playwright action: click, fill, hover, press, wait */
+    action: "click" | "fill" | "hover" | "press" | "wait";
+    /** CSS selector or descriptive target for the element */
+    target?: string;
+    /** Value to type (for fill) or key to press (for press) */
+    value?: string;
+    /** Delay in ms (for wait action) */
+    delay?: number;
+}
+/** Performance timing captured during the interaction window. */
+interface InteractionTiming {
+    /** JS execution time in ms (from performance.now() around interactions). */
+    js: number;
+    /** Layout time in ms (from PerformanceObserver layout entries). */
+    layout: number;
+    /** Paint time in ms (from PerformanceObserver paint entries). */
+    paint: number;
+}
+/** Layout shift data (Cumulative Layout Shift). */
+interface LayoutShiftData {
+    /** Number of layout shift events observed. */
+    count: number;
+    /** Cumulative layout shift score. */
+    cumulativeScore: number;
+}
+/**
+ * Heuristic flags from §6.1 catalog applicable to interaction profiling.
+ */
+type ProfileHeuristicFlag = "WASTED_RENDER" | "MEMO_INEFFECTIVE" | "EFFECT_EVERY_RENDER" | "MISSING_CLEANUP" | "HIGH_RENDER_COUNT" | "LAYOUT_SHIFT_DETECTED" | "SLOW_INTERACTION";
+/** Full interaction profile result per Spec §5. */
+interface InteractionProfile {
+    /** Component name profiled. */
+    component: string;
+    /** Total number of React commits (renders) during the interaction window. */
+    totalRenders: number;
+    /** Number of distinct component names that re-rendered during the window. */
+    uniqueComponents: number;
+    /** Estimated number of "wasted" renders (components that re-rendered without output change). */
+    wastedRenders: number;
+    /** Timing breakdown in ms. */
+    timing: InteractionTiming;
+    /** Layout shift metrics. */
+    layoutShifts: LayoutShiftData;
+    /** Heuristic flags from §6.1 catalog. */
+    flags: ProfileHeuristicFlag[];
+    /** Interaction steps that were replayed. */
+    interaction: InteractionStep$1[];
+}
+
+/** Root cause categories per Instrumentation Spec §2.1 */
+type RenderTrigger = "state_change" | "props_change" | "context_change" | "parent_rerender" | "force_update" | "hook_dependency";
+/** A single link in the causality chain from root cause to this render */
+interface CausalityLink {
+    component: string;
+    trigger: RenderTrigger;
+    propsChanged?: boolean;
+    stateChanged?: boolean;
+    contextChanged?: boolean;
+    origin?: string;
+    stateKey?: string;
+}
+/** Per-component render event with causality chain */
+interface RenderEvent {
+    component: string;
+    renderIndex: number;
+    trigger: RenderTrigger;
+    propsChanged: boolean;
+    stateChanged: boolean;
+    contextChanged: boolean;
+    memoized: boolean;
+    /** Wasted render: re-rendered with no changed inputs and not memoized */
+    wasted: boolean;
+    chain: CausalityLink[];
+    cascade: {
+        totalRendersTriggered: number;
+        uniqueComponents: number;
+        unchangedPropRenders: number;
+    };
+}
+/** Heuristic flag from Instrumentation Spec §6.1 */
+interface InstrumentFlag {
+    id: string;
+    severity: "error" | "warning" | "info";
+    component: string;
+    detail: string;
+    data: Record<string, unknown>;
+}
+/** Full output of the renders analysis */
+interface RendersAnalysisResult {
+    component: string;
+    interaction: InteractionStep[];
+    summary: {
+        totalRenders: number;
+        uniqueComponents: number;
+        wastedRenders: number;
+        interactionDurationMs: number;
+    };
+    renders: RenderEvent[];
+    flags: InstrumentFlag[];
+}
+/** Interaction step definition per Instrumentation Spec §5.1 */
+interface InteractionStep {
+    action: "click" | "type" | "wait" | "hover" | "blur" | "focus" | "scroll";
+    target?: string;
+    text?: string;
+    condition?: string;
+    timeout?: number;
+    x?: number;
+    y?: number;
+}
+/**
+ * Creates the `scope instrument` command group.
+ * Contains: `scope instrument renders`, `scope instrument hooks`, `scope instrument profile`
+ */
+declare function createInstrumentCommand(): Command;
+
 /**
  * @agent-scope/cli — manifest sub-commands
  *
@@ -155,4 +373,49 @@ declare function createProgram(options?: ScopeCLIOptions): Command;
  */
 declare function createTokensCommand(): Command;
 
-export { type InitOptions, type InitResult, type ListRow, type QueryRow, type ReactScopeConfig, type ScopeCLIOptions, createInitCommand, createManifestCommand, createProgram, createTokensCommand, isTTY, matchGlob, runInit };
+/**
+ * @agent-scope/cli — tokens export sub-command
+ *
+ * Implements `scope tokens export --format <fmt>` which converts a resolved
+ * token set into one of six downstream formats:
+ *
+ *   css        — CSS custom properties (:root { --color-primary-500: … })
+ *   ts         — TypeScript const exports (export const colorPrimary500 = …)
+ *   scss       — SCSS variable declarations ($color-primary-500: …)
+ *   tailwind   — Tailwind CSS theme.extend object (module.exports = { … })
+ *   flat-json  — Flat key→value JSON { "color.primary.500": "#3B82F6" }
+ *   figma      — Figma Tokens JSON (nested value+type objects)
+ *
+ * Token file resolution priority:
+ *   1. `--file` flag
+ *   2. `tokens.file` field in `reactscope.config.json`
+ *   3. `reactscope.tokens.json` in cwd (default)
+ *
+ * Output defaults to stdout (pipe-friendly). Use `--out <path>` to write to
+ * a file instead.
+ *
+ * Theme-aware export: if the token file contains a `themes` block and
+ * `--theme <name>` is passed, theme overrides are included in formats that
+ * support them (css, ts, scss, tailwind, figma).
+ */
+
+/**
+ * Resolve the path to the token file.
+ *
+ * Priority:
+ *  1. Explicit `--file` flag value
+ *  2. `tokens.file` in `reactscope.config.json`
+ *  3. `reactscope.tokens.json` in cwd
+ */
+declare function resolveTokenFilePath(fileFlag?: string): string;
+/**
+ * Create and return the `tokens export` sub-command.
+ *
+ * Intended to be registered on the parent `tokens` Command:
+ * ```ts
+ * tokensCmd.addCommand(createTokensExportCommand());
+ * ```
+ */
+declare function createTokensExportCommand(): Command;
+
+export { type CausalityLink, type ComponentHookProfile, type HookHeuristicFlag, type HookProfile, type HooksProfilingResult, type InitOptions, type InitResult, type InteractionProfile, type InteractionStep$1 as InteractionStep, type InteractionTiming, type LayoutShiftData, type ListRow, type ProfileHeuristicFlag, type QueryRow, type ReactScopeConfig, type RenderEvent, type RenderTrigger, type RendersAnalysisResult, type ScopeCLIOptions, createInitCommand, createInstrumentCommand, createManifestCommand, createProgram, createTokensCommand, createTokensExportCommand, isTTY, matchGlob, resolveTokenFilePath, runInit };