@progen-labs/spectra 0.0.0-stage → 0.1.0

package/src/components/FindingsList.jsx

@@ -0,0 +1,381 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { SEVERITY, SEVERITY_RANK, groupFindings } from '../culprits.js';
+import { fmtMs, splitPath } from '../format.js';
+import CodeRef from './CodeRef.jsx';
+import { ChevronIcon } from './Icons.jsx';
+
+const FILTERS = [
+  { id: 'all', label: 'All' },
+  { id: 'critical', label: 'Critical' },
+  { id: 'warning', label: 'Warnings' },
+  { id: 'info', label: 'Notes' },
+];
+
+function CulpritTable({ culprits, onOpenFile }) {
+  const maxMs = Math.max(1, ...culprits.map(c => c.ms || 0));
+  return (
+    <table className="data culprit-table">
+      <thead>
+        <tr>
+          <th>Function</th>
+          <th>Where</th>
+          <th className="num">Time</th>
+        </tr>
+      </thead>
+      <tbody>
+        {culprits.map(c => (
+          <tr key={`${c.fn}|${c.file}|${c.line}`}>
+            <td>
+              <code className="fn">{c.fn || '(unknown)'}()</code>
+              {c.note && <div className="muted small">{c.note}</div>}
+            </td>
+            <td>
+              <CodeRef
+                file={c.file}
+                line={c.line}
+                lineKind={c.lineKind}
+                abs={c.abs}
+                onOpenFile={onOpenFile}
+              />
+            </td>
+            <td className="num">
+              {c.ms > 0 && (
+                <>
+                  {fmtMs(c.ms)}
+                  <div className="bar">
+                    <span style={{ width: `${(c.ms / maxMs) * 100}%` }} />
+                  </div>
+                </>
+              )}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+
+function FixCallout({ fix }) {
+  if (!fix) return null;
+  return (
+    <div className="fix-callout">
+      <span className="fix-label">What to do</span>
+      <p>{fix}</p>
+    </div>
+  );
+}
+
+function FindingBody({ finding, onOpenFile }) {
+  return (
+    <div className="fbody">
+      <FixCallout fix={finding.fix} />
+      {finding.detail && (
+        <p className="fdetail">
+          <b>Why it matters</b>
+          {finding.detail}
+        </p>
+      )}
+      {finding.culprits?.length > 0 && (
+        <CulpritTable culprits={finding.culprits} onOpenFile={onOpenFile} />
+      )}
+      {!finding.culprits?.length && finding.file && (
+        <button type="button" onClick={() => onOpenFile(finding.file)}>
+          Open {finding.file}
+        </button>
+      )}
+    </div>
+  );
+}
+
+function RowHead({
+  severity,
+  title,
+  chips,
+  impactMs,
+  maxImpact,
+  isOpen,
+  onToggle,
+  subtitle,
+}) {
+  const sev = SEVERITY[severity];
+  return (
+    <button
+      type="button"
+      className="frow-head"
+      aria-expanded={isOpen}
+      onClick={onToggle}
+    >
+      <span className="sev-badge" aria-label={sev.label} title={sev.label}>
+        {sev.icon}
+      </span>
+      <span className="frow-main">
+        <span className="frow-title">{title}</span>
+        {subtitle && <span className="frow-sub muted">{subtitle}</span>}
+      </span>
+      <span className="frow-chips">
+        {chips.map(c => (
+          <span key={c} className="chip">
+            {c}
+          </span>
+        ))}
+      </span>
+      <span className="impact">
+        {impactMs > 0 ? (
+          <>
+            <span className="impact-bar">
+              <span
+                style={{
+                  width: `${Math.max(4, (impactMs / maxImpact) * 100)}%`,
+                }}
+              />
+            </span>
+            <span className="impact-ms">{fmtMs(impactMs)}</span>
+          </>
+        ) : (
+          <span className="muted">–</span>
+        )}
+      </span>
+      <ChevronIcon isUp={isOpen} />
+    </button>
+  );
+}
+
+function SingleRow({
+  finding,
+  maxImpact,
+  isOpen,
+  onToggle,
+  onOpenFile,
+  rowRef,
+}) {
+  return (
+    <li
+      ref={rowRef}
+      className={`frow sev-${finding.severity} ${isOpen ? 'open' : ''}`}
+    >
+      <RowHead
+        severity={finding.severity}
+        title={finding.title}
+        subtitle={finding.file ? splitPath(finding.file).name : ''}
+        chips={[finding.category]}
+        impactMs={finding.impactMs}
+        maxImpact={maxImpact}
+        isOpen={isOpen}
+        onToggle={onToggle}
+      />
+      {isOpen && <FindingBody finding={finding} onOpenFile={onOpenFile} />}
+    </li>
+  );
+}
+
+function GroupRow({
+  group,
+  maxImpact,
+  openIds,
+  onToggle,
+  onOpenFile,
+  rowRefs,
+}) {
+  const isOpen = openIds.has(group.id);
+  const count = group.members.length;
+  const name = `${group.culprit.fn || '(unknown)'}()`;
+  return (
+    <li
+      ref={el => rowRefs.current.set(group.id, el)}
+      className={`frow group sev-${group.severity} ${isOpen ? 'open' : ''}`}
+    >
+      <RowHead
+        severity={group.severity}
+        title={`${name} is behind ${count} findings`}
+        subtitle={splitPath(group.culprit.file).name}
+        chips={[...new Set(group.members.map(m => m.category))]}
+        impactMs={group.impactMs}
+        maxImpact={maxImpact}
+        isOpen={isOpen}
+        onToggle={() => onToggle(group.id)}
+      />
+      {isOpen && (
+        <div className="fbody">
+          <FixCallout fix={group.lead.fix} />
+          <CulpritTable culprits={[group.culprit]} onOpenFile={onOpenFile} />
+          <h4 className="members-title">Findings it causes</h4>
+          <ul className="members">
+            {group.members.map(m => (
+              <SingleRow
+                key={m.id}
+                finding={m}
+                maxImpact={group.impactMs}
+                isOpen={openIds.has(m.id)}
+                onToggle={() => onToggle(m.id)}
+                onOpenFile={onOpenFile}
+                rowRef={el => rowRefs.current.set(m.id, el)}
+              />
+            ))}
+          </ul>
+        </div>
+      )}
+    </li>
+  );
+}
+
+/**
+ * Findings as a scannable list: root causes grouped, one line each, details
+ * (what to do first, then why, then the exact code) only when expanded.
+ */
+export default function FindingsList({ findings, onOpenFile, focus }) {
+  const [severity, setSeverity] = useState('all');
+  const [category, setCategory] = useState('all');
+  const items = useMemo(
+    () =>
+      groupFindings(
+        findings.filter(
+          f =>
+            (severity === 'all' || f.severity === severity) &&
+            (category === 'all' || f.category === category),
+        ),
+      ),
+    [findings, severity, category],
+  );
+  const [openIds, setOpenIds] = useState(() => {
+    const first = groupFindings(findings)[0];
+    return new Set(first ? [first.id] : []);
+  });
+  const rowRefs = useRef(new Map());
+  const pendingScroll = useRef(null);
+
+  const categories = useMemo(
+    () => [...new Set(findings.map(f => f.category))].sort(),
+    [findings],
+  );
+  const counts = useMemo(
+    () => ({
+      all: findings.length,
+      ...Object.fromEntries(
+        Object.keys(SEVERITY_RANK).map(s => [
+          s,
+          findings.filter(f => f.severity === s).length,
+        ]),
+      ),
+    }),
+    [findings],
+  );
+  const maxImpact = Math.max(1, ...items.map(i => i.impactMs));
+
+  const toggle = id =>
+    setOpenIds(prev => {
+      const next = new Set(prev);
+      if (!next.delete(id)) next.add(id);
+      return next;
+    });
+
+  useEffect(() => {
+    if (!focus) return;
+    const target = groupFindings(findings).find(
+      i => i.id === focus.id || i.members?.some(m => m.id === focus.id),
+    );
+    if (!target) return;
+    setSeverity('all');
+    setCategory('all');
+    setOpenIds(prev => new Set([...prev, target.id, focus.id]));
+    pendingScroll.current = focus.id;
+    // Only a new jump request should re-run this.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [focus?.tick]);
+
+  useEffect(() => {
+    const id = pendingScroll.current;
+    if (!id) return;
+    const el = rowRefs.current.get(id);
+    if (el) {
+      pendingScroll.current = null;
+      el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+    }
+  });
+
+  return (
+    <div className="findings-list">
+      <div className="findings-toolbar">
+        <div className="segmented" role="group" aria-label="Filter by severity">
+          {FILTERS.map(f => (
+            <button
+              key={f.id}
+              type="button"
+              aria-pressed={severity === f.id}
+              onClick={() => setSeverity(f.id)}
+            >
+              {f.label} <span className="muted">{counts[f.id]}</span>
+            </button>
+          ))}
+        </div>
+        {categories.length > 1 && (
+          <select
+            aria-label="Filter by category"
+            value={category}
+            onChange={e => setCategory(e.target.value)}
+          >
+            <option value="all">All categories</option>
+            {categories.map(c => (
+              <option key={c} value={c}>
+                {c}
+              </option>
+            ))}
+          </select>
+        )}
+        <span className="spacer" />
+        <button
+          type="button"
+          className="ghost"
+          onClick={() =>
+            setOpenIds(
+              new Set(
+                items.flatMap(i =>
+                  i.kind === 'group'
+                    ? [i.id, ...i.members.map(m => m.id)]
+                    : [i.id],
+                ),
+              ),
+            )
+          }
+        >
+          Expand all
+        </button>
+        <button
+          type="button"
+          className="ghost"
+          onClick={() => setOpenIds(new Set())}
+        >
+          Collapse all
+        </button>
+      </div>
+      {items.length === 0 ? (
+        <p className="muted pad">Nothing matches these filters.</p>
+      ) : (
+        <ul className="frows">
+          {items.map(item =>
+            item.kind === 'group' ? (
+              <GroupRow
+                key={item.id}
+                group={item}
+                maxImpact={maxImpact}
+                openIds={openIds}
+                onToggle={toggle}
+                onOpenFile={onOpenFile}
+                rowRefs={rowRefs}
+              />
+            ) : (
+              <SingleRow
+                key={item.id}
+                finding={item.finding}
+                maxImpact={maxImpact}
+                isOpen={openIds.has(item.id)}
+                onToggle={() => toggle(item.id)}
+                onOpenFile={onOpenFile}
+                rowRef={el => rowRefs.current.set(item.id, el)}
+              />
+            ),
+          )}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/components/HeatTrees.jsx

@@ -0,0 +1,222 @@
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+  FILE_METRICS,
+  ancestorIds,
+  buildFileTree,
+  decorateCallNode,
+  decorateFileNode,
+  defaultCallExpanded,
+  defaultExpanded,
+  formatMetric,
+} from '../heat.js';
+import { fmtMs } from '../format.js';
+import { layoutTree } from '../layout.js';
+import TreeView from './TreeView.jsx';
+
+function Legend({ extra }) {
+  return (
+    <div className="legend">
+      <span className="ramp" aria-hidden="true" /> low → high heat (share of the
+      total)
+      <span>
+        <i className="ring" /> library code (node_modules)
+      </span>
+      {extra}
+    </div>
+  );
+}
+
+/** Directory tree of profiled files, heat-coloured by the chosen metric. */
+export function FileHeatTree({
+  report,
+  hideVendor,
+  selectedPath,
+  revealTick,
+  onSelectFile,
+}) {
+  const [metricId, setMetricId] = useState('selfMs');
+  const [expanded, setExpanded] = useState(null);
+  const [centerTick, setCenterTick] = useState(0);
+  const metric = FILE_METRICS.find(m => m.id === metricId);
+
+  const tree = useMemo(
+    () =>
+      buildFileTree(report.files, metric, {
+        hideVendor,
+        rootName: report?.meta?.title || report?.meta?.url || 'target-frontend',
+      }),
+    [report, metric, hideVendor],
+  );
+  // A new tree (report, metric, filter) restarts from its hottest paths.
+  useEffect(() => {
+    setExpanded(null);
+    setCenterTick(t => t + 1);
+  }, [tree]);
+  const expandedSet = useMemo(
+    () => expanded || defaultExpanded(tree),
+    [expanded, tree],
+  );
+
+  // Reveal a file chosen elsewhere (findings, React table, search).
+  useEffect(() => {
+    if (!selectedPath || !tree.byId.has(selectedPath)) return;
+    setExpanded(
+      prev =>
+        new Set([
+          ...(prev || defaultExpanded(tree)),
+          ...ancestorIds(tree, selectedPath),
+        ]),
+    );
+    setCenterTick(t => t + 1);
+  }, [revealTick, selectedPath, tree]);
+
+  const layout = useMemo(
+    () =>
+      layoutTree(
+        tree.root,
+        n => (n.isDir && expandedSet.has(n.id) ? n.children : null),
+        n => `${n.name}${n.isDir ? '/' : ''}  ${formatMetric(metric, n.value)}`,
+        n => decorateFileNode(n, tree, metric),
+      ),
+    [tree, expandedSet, metric],
+  );
+  const toggle = useCallback(
+    node => {
+      setExpanded(prev => {
+        const next = new Set(prev || expandedSet);
+        if (next.has(node.data.id)) next.delete(node.data.id);
+        else next.add(node.data.id);
+        return next;
+      });
+    },
+    [expandedSet],
+  );
+
+  const activate = useCallback(
+    node => {
+      if (node.data.isDir) toggle(node);
+      else onSelectFile(node.data.id);
+    },
+    [toggle, onSelectFile],
+  );
+
+  return (
+    <div className="tree-pane">
+      <div className="tree-toolbar">
+        <label>
+          Colour and size by
+          <select value={metricId} onChange={e => setMetricId(e.target.value)}>
+            {FILE_METRICS.map(m => (
+              <option key={m.id} value={m.id}>
+                {m.label}
+              </option>
+            ))}
+          </select>
+        </label>
+        <span className="muted">{metric.hint}</span>
+        <span className="spacer" />
+        <button
+          type="button"
+          onClick={() => setExpanded(new Set([tree.root.id]))}
+        >
+          Collapse all
+        </button>
+        <button
+          type="button"
+          onClick={() => setExpanded(new Set(tree.byId.keys()))}
+        >
+          Expand all
+        </button>
+      </div>
+      {tree.total === 0 ? (
+        <div className="empty">
+          No files have any “{metric.label}” in this recording.
+        </div>
+      ) : (
+        <TreeView
+          layout={layout}
+          selectedKey={selectedPath}
+          centerKey={selectedPath}
+          centerTick={centerTick}
+          onActivate={activate}
+          onToggle={toggle}
+        />
+      )}
+      <Legend />
+    </div>
+  );
+}
+
+/** Top-down call tree: hot paths are expanded, colour = self time. */
+export function CallHeatTree({ report, onSelectFile }) {
+  const root = report.callTree;
+  const [expanded, setExpanded] = useState(() =>
+    root ? defaultCallExpanded(root) : new Set(),
+  );
+  const [centerTick, setCenterTick] = useState(0);
+  useEffect(() => {
+    setExpanded(root ? defaultCallExpanded(root) : new Set());
+    setCenterTick(t => t + 1);
+  }, [root]);
+
+  const layout = useMemo(
+    () =>
+      root &&
+      layoutTree(
+        root,
+        n => (expanded.has(n.id) || n === root ? n.children : null),
+        n => `${n.name}  ${fmtMs(n.totalMs)} · self ${fmtMs(n.selfMs)}`,
+        n => decorateCallNode(n, root.totalMs),
+      ),
+    [root, expanded],
+  );
+
+  // Open the view on the function with the most self time among the visible nodes.
+  const hottestKey = useMemo(() => {
+    if (!layout) return undefined;
+    return layout.nodes.reduce(
+      (best, n) => (n.data.selfMs > (best?.data.selfMs ?? -1) ? n : best),
+      null,
+    )?.data.id;
+  }, [layout]);
+
+  const toggle = useCallback(node => {
+    setExpanded(prev => {
+      const next = new Set(prev);
+      if (next.has(node.data.id)) next.delete(node.data.id);
+      else next.add(node.data.id);
+      return next;
+    });
+  }, []);
+  const activate = useCallback(
+    node => {
+      const { file } = node.data;
+      if (file && !file.startsWith('(')) onSelectFile(file);
+      else if (node.view.expandable) toggle(node);
+    },
+    [toggle, onSelectFile],
+  );
+
+  if (!layout)
+    return <div className="empty">No CPU samples were captured.</div>;
+  return (
+    <div className="tree-pane">
+      <div className="tree-toolbar">
+        <span className="muted">
+          Each node is a function call path: total time, then self time. Click a
+          circle to expand/collapse; click a label to open its file.
+        </span>
+      </div>
+      <TreeView
+        layout={layout}
+        selectedKey={null}
+        centerKey={hottestKey}
+        centerTick={centerTick}
+        anchor={0.55}
+        onActivate={activate}
+        onToggle={toggle}
+      />
+      <Legend extra={<span>colour = self time · size = total time</span>} />
+    </div>
+  );
+}

package/src/components/Icons.jsx

@@ -0,0 +1,58 @@
+const Svg = ({ children, size = 14 }) => (
+  <svg
+    className="icon"
+    viewBox="0 0 16 16"
+    width={size}
+    height={size}
+    aria-hidden="true"
+    fill="none"
+    stroke="currentColor"
+    strokeWidth="1.6"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+  >
+    {children}
+  </svg>
+);
+
+export const ChevronIcon = ({ isUp = false }) => (
+  <Svg size={12}>
+    <path d={isUp ? 'M3.5 10 8 5.5l4.5 4.5' : 'M3.5 6 8 10.5 12.5 6'} />
+  </Svg>
+);
+
+export const RecordIcon = () => (
+  <svg
+    className="icon"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+  >
+    <circle cx="8" cy="8" r="5.5" fill="currentColor" />
+  </svg>
+);
+
+export const StopIcon = () => (
+  <svg
+    className="icon"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+  >
+    <rect x="3" y="3" width="10" height="10" rx="2" fill="currentColor" />
+  </svg>
+);
+
+export const PageLoadIcon = () => (
+  <Svg>
+    <path d="M13.5 8a5.5 5.5 0 1 1-1.6-3.9M13.5 2.5v3h-3" />
+  </Svg>
+);
+
+export const DownloadIcon = () => (
+  <Svg>
+    <path d="M8 2.5v8M4.5 7.5 8 11l3.5-3.5M3 13.5h10" />
+  </Svg>
+);