codebaseiq 0.1.0 → 0.2.0

package/ui/view/api.js

@@ -0,0 +1,450 @@
+// Shared client foundation: fetch wrappers for the viewer API, the DOM builders
+// every view uses (text only, never markup), route helpers, and adapters that
+// tolerate optional or renamed fields in server payloads.
+
+const TOKEN_META = 'codebaseiq-token';
+const EDITOR_PREFIX = 'vscode://file/';
+const SAFE_HREF = /^(?:\?|\/(?!\/)|vscode:\/\/file\/)/;
+const REFERENCES = 'references';
+const IMPORTS = 'imports';
+const HEALTHY_WATCHER_STATES = new Set(['idle', 'waiting', 'indexing', 'cooldown', 'ready', 'watching']);
+const STALE_MESSAGE = 'File changed since the index was built — lines may be off.';
+
+export class ApiError extends Error {
+  constructor(message, status, payload) {
+    super(message);
+    this.name = 'ApiError';
+    this.status = status;
+    this.payload = payload;
+  }
+}
+
+export function isAbort(error) {
+  return error?.name === 'AbortError';
+}
+
+function describeFailure(response, payload) {
+  if (payload && typeof payload.error === 'string' && payload.error) return payload.error;
+  const detail = response.statusText ? ` ${response.statusText}` : '';
+  return `Request failed (${response.status}${detail}).`;
+}
+
+async function request(path, { method = 'GET', params, body, headers, signal } = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params ?? {})) {
+    if (value !== undefined && value !== null) query.set(key, String(value));
+  }
+  const queryText = query.toString();
+  const target = queryText ? `${path}?${queryText}` : path;
+  let response;
+  try {
+    response = await fetch(target, { method, headers, body, signal, credentials: 'same-origin', cache: 'no-store' });
+  } catch (error) {
+    if (isAbort(error)) throw error;
+    throw new ApiError('Cannot reach the codebaseiq server. Is `codebaseiq view` still running?', 0, null);
+  }
+  const text = await response.text();
+  let payload = null;
+  if (text) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = null;
+    }
+  }
+  if (!response.ok) throw new ApiError(describeFailure(response, payload), response.status, payload);
+  if (payload === null) throw new ApiError('The server returned an unreadable response.', response.status, null);
+  return payload;
+}
+
+function sessionToken() {
+  return document.querySelector(`meta[name="${TOKEN_META}"]`)?.getAttribute('content') ?? '';
+}
+
+export function getMeta(options) {
+  return request('/api/meta', options);
+}
+
+export function getScope(path, basis, options) {
+  return request('/api/scope', { ...options, params: { path, basis } });
+}
+
+export function getFile(path, basis, options) {
+  return request('/api/file', { ...options, params: { path, basis } });
+}
+
+export function getSymbol({ symbol, focus, statements }, options) {
+  return request('/api/symbol', {
+    ...options,
+    params: { symbol, focus, statements: statements ? '1' : undefined },
+  });
+}
+
+export function getSource({ file, start, end }, options) {
+  return request('/api/source', { ...options, params: { file, start, end } });
+}
+
+export function postBuilder(payload, options) {
+  return request('/api/builder', {
+    ...options,
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', 'X-CodeBaseIQ-Token': sessionToken() },
+    body: JSON.stringify(payload),
+  });
+}
+
+// ── Routes ────────────────────────────────────────────────
+
+/** Exactly one target wins: symbol, then focus, then file, then scope; the default is the project root. */
+export function parseRoute(search) {
+  const params = new URLSearchParams(search);
+  const route = { basis: params.get('basis') === IMPORTS ? IMPORTS : REFERENCES };
+  const symbol = params.get('symbol');
+  const focus = params.get('focus');
+  const file = params.get('file');
+  const scope = params.get('scope');
+  if (symbol) route.symbol = symbol;
+  else if (focus) route.focus = focus;
+  else if (file) route.file = file;
+  else if (scope) route.scope = scope;
+  return route;
+}
+
+export function routeToSearch(route) {
+  const params = new URLSearchParams();
+  if (route.symbol) params.set('symbol', route.symbol);
+  else if (route.focus) params.set('focus', route.focus);
+  else if (route.file) params.set('file', route.file);
+  else if (route.scope) params.set('scope', route.scope);
+  if (route.basis === IMPORTS) params.set('basis', IMPORTS);
+  const text = params.toString();
+  return text ? `?${text}` : '';
+}
+
+/** An anchor that navigates in place on a plain click and keeps native behavior for new-tab clicks. */
+export function routeLink(nav, route, children, props = {}, onActivate) {
+  return el(
+    'a',
+    {
+      ...props,
+      href: nav.href(route),
+      on: {
+        click: (event) => {
+          if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey) return;
+          event.preventDefault();
+          onActivate?.();
+          nav.go(route);
+        },
+      },
+    },
+    children,
+  );
+}
+
+// ── Paths and text ────────────────────────────────────────
+
+export function dirname(path) {
+  const index = path.lastIndexOf('/');
+  return index < 0 ? '' : path.slice(0, index);
+}
+
+export function basename(path) {
+  return path.slice(path.lastIndexOf('/') + 1);
+}
+
+/** A path as a dimmed directory part and a bold file name. */
+export function pathLabel(path) {
+  const folder = dirname(path);
+  return [
+    folder ? el('span', { class: 'path-dir' }, `${folder}/`) : null,
+    el('span', { class: 'path-base' }, basename(path)),
+  ];
+}
+
+/** Cumulative directories of a path: `a/b/c` gives `a`, `a/b`, `a/b/c`. */
+export function pathPrefixes(path) {
+  const parts = path.split('/').filter(Boolean);
+  return parts.map((part, index) => ({ name: part, path: parts.slice(0, index + 1).join('/') }));
+}
+
+export function plural(count, noun) {
+  return `${count} ${noun}${count === 1 ? '' : 's'}`;
+}
+
+export function formatLocation(file, line) {
+  if (!file) return '';
+  return line ? `${file}:${line}` : file;
+}
+
+function safeEditorUri(uri) {
+  return typeof uri === 'string' && uri.startsWith(EDITOR_PREFIX) ? uri : null;
+}
+
+export function titleCase(text) {
+  return text ? text[0].toUpperCase() + text.slice(1) : text;
+}
+
+// ── DOM builders ──────────────────────────────────────────
+
+/**
+ * Build an element. Values are always set as text or as attributes; markup
+ * strings are never parsed. `false`, `null`, and `undefined` props are skipped,
+ * so ARIA states are passed as the strings 'true' and 'false'.
+ */
+export function el(tag, props, ...children) {
+  const node = document.createElement(tag);
+  for (const [name, value] of Object.entries(props ?? {})) applyProp(node, name, value);
+  appendChildren(node, children);
+  return node;
+}
+
+function applyProp(node, name, value) {
+  if (value === undefined || value === null || value === false) return;
+  if (name === 'class') node.className = value;
+  else if (name === 'text') node.textContent = value;
+  else if (name === 'on') {
+    for (const [type, handler] of Object.entries(value)) node.addEventListener(type, handler);
+  } else if (name === 'data') {
+    for (const [key, item] of Object.entries(value)) {
+      if (item !== undefined && item !== null) node.dataset[key] = String(item);
+    }
+  } else if (/^on/i.test(name) || name === 'style' || name === 'srcdoc') return;
+  else if (name === 'href' && !SAFE_HREF.test(value)) return;
+  else node.setAttribute(name, value === true ? '' : String(value));
+}
+
+function appendChildren(parent, children) {
+  for (const child of children) {
+    if (child === null || child === undefined || child === false) continue;
+    if (Array.isArray(child)) appendChildren(parent, child);
+    else parent.append(typeof child === 'object' ? child : document.createTextNode(String(child)));
+  }
+}
+
+/** Replace a node's children; unlike `replaceChildren`, nested arrays flatten and null children are skipped. */
+export function fill(node, ...children) {
+  node.replaceChildren();
+  appendChildren(node, children);
+  return node;
+}
+
+export function chip(text, className = '') {
+  return el('span', { class: `chip ${className}`.trim() }, text);
+}
+
+export function editorLink(uri, label, className = 'editor-link') {
+  const href = safeEditorUri(uri);
+  return href ? el('a', { class: className, href }, label) : null;
+}
+
+export function notice(kind, ...children) {
+  return el('div', { class: `notice ${kind}`, role: kind === 'error' ? 'alert' : 'status' }, ...children);
+}
+
+export function staleNotice() {
+  return notice('warn', STALE_MESSAGE);
+}
+
+/** Only a live watcher doing normal work (including debounce and cooldown waits) is healthy; every other state warns. */
+export function watcherTone(state) {
+  return HEALTHY_WATCHER_STATES.has(String(state).toLowerCase()) ? 'ok' : 'warn';
+}
+
+/** A list that renders `limit` rows and reveals the rest on request. */
+export function expandableList(items, renderItem, { limit = 30, className = 'plain-list' } = {}) {
+  const list = el('ul', { class: className });
+  const append = (from, to) => {
+    for (const item of items.slice(from, to)) list.append(renderItem(item));
+  };
+  append(0, limit);
+  if (items.length > limit) {
+    const row = el('li', { class: 'more-row' });
+    const reveal = () => {
+      row.remove();
+      append(limit, items.length);
+      list.children[limit]?.querySelector('a, button')?.focus();
+    };
+    row.append(
+      el(
+        'button',
+        { type: 'button', class: 'link-button', on: { click: reveal } },
+        `Show ${items.length - limit} more`,
+      ),
+    );
+    list.append(row);
+  }
+  return list;
+}
+
+// ── Payload adapters ──────────────────────────────────────
+
+export function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function str(value) {
+  return typeof value === 'string' ? value : '';
+}
+
+function count(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+function sampleOf(sample) {
+  return sample && typeof sample.from === 'string' && typeof sample.to === 'string'
+    ? { from: sample.from, to: sample.to }
+    : null;
+}
+
+/**
+ * Reduce a scope payload to what the viewer draws. Nodes are directories,
+ * files, and external nodes (the payload's separate `external` list); each
+ * external node records whether it stands for one file or a directory so a
+ * click can open the right view. Edges to unknown nodes are dropped.
+ */
+export function normalizeScope(raw, requestedPath = '') {
+  const nodes = [];
+  const ids = new Set();
+  const add = (item, forcedKind) => {
+    const path = str(item?.path) || str(item?.id);
+    const id = str(item?.id) || path;
+    if (!id || ids.has(id)) return;
+    ids.add(id);
+    const kind = forcedKind ?? (item.kind === 'dir' || item.kind === 'directory' ? 'directory' : 'file');
+    nodes.push({
+      id,
+      kind,
+      path,
+      name: forcedKind === 'external' ? path : str(item.name) || basename(path) || id,
+      fileCount: kind === 'directory' ? count(item.files) : null,
+      internalEdges: count(item.internalEdges) ?? 0,
+      cycle: count(item.cycle),
+      isFile: false,
+    });
+  };
+  for (const item of asArray(raw?.nodes)) add(item);
+  for (const item of asArray(raw?.external)) add(item, 'external');
+
+  const edges = [];
+  for (const item of asArray(raw?.edges)) {
+    const source = str(item?.from);
+    const target = str(item?.to);
+    if (!ids.has(source) || !ids.has(target)) continue;
+    edges.push({
+      id: `edge-${edges.length}`,
+      source,
+      target,
+      count: count(item.count) || 1,
+      cycle: item.cycle === true,
+      samples: asArray(item.samples).map(sampleOf).filter(Boolean),
+    });
+  }
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  for (const edge of edges) {
+    for (const node of [byId.get(edge.source), byId.get(edge.target)]) {
+      if (node.kind === 'external' && edge.samples.some((pair) => pair.from === node.path || pair.to === node.path)) {
+        node.isFile = true;
+      }
+    }
+  }
+  return {
+    path: str(raw?.scope) || requestedPath,
+    basis: raw?.basis === IMPORTS ? IMPORTS : REFERENCES,
+    nodes,
+    edges,
+    totals: { files: count(raw?.totals?.files), edges: count(raw?.totals?.edges) },
+  };
+}
+
+/** Region labels arrive as `root:<path>`; show the directory the way the map does. */
+function regionLabel(label) {
+  const path = label.replace(/^root(?::|$)/, '').replace(/\/+$/, '');
+  return path ? `${path}/` : 'project root';
+}
+
+function laneLabel(kind, label, file, line) {
+  if (kind === 'region' && label) return regionLabel(label);
+  if (kind === 'location' && file) return formatLocation(file, line);
+  if (kind === 'symbol' && file) return symbolDisplayName(label);
+  return label;
+}
+
+/**
+ * A symbol label is its shortened identity (`src:queries:graph:value-flow:valueFlow()`); the file is
+ * already shown beside it, so only the member path after the module segment is kept (`valueFlow()`).
+ */
+function symbolDisplayName(label) {
+  const parts = label.split(':');
+  return parts.length > 1 ? parts[parts.length - 1] : label;
+}
+
+/** One lane entry; `symbol`, the location, and `strength` may each be absent. */
+export function normalizeLaneItem(item) {
+  const kind = str(item?.kind) || null;
+  const file = str(item?.file) || null;
+  const line = count(item?.line);
+  return {
+    kind,
+    label: laneLabel(kind, str(item?.label), file, line) || str(item?.symbol) || file || '(unnamed)',
+    symbol: str(item?.symbol) || null,
+    file,
+    line,
+    reference: item?.reference === true,
+    local: item?.local === true,
+    editorUri: safeEditorUri(item?.editorUri),
+    subtypes: asArray(item?.subtypes).filter((subtype) => typeof subtype === 'string' && subtype),
+    count: count(item?.count),
+    strength: str(item?.strength) || null,
+  };
+}
+
+function statementEndpoint(node) {
+  const location = node?.location;
+  return {
+    label: str(node?.label) || str(node?.symbol) || str(node?.id),
+    symbol: str(node?.symbol) || null,
+    place: location && typeof location.file === 'string' ? formatLocation(location.file, count(location.line)) : '',
+  };
+}
+
+/**
+ * The statements payload is an inventory of relationship counts plus the
+ * relationship edges; edges are grouped by family for display.
+ */
+export function normalizeStatements(statements) {
+  const groups = new Map();
+  for (const edge of asArray(statements?.edges)) {
+    const family = str(edge?.family) || 'other';
+    if (!groups.has(family)) groups.set(family, []);
+    groups.get(family).push({
+      subtype: str(edge?.subtype),
+      from: statementEndpoint(edge?.from),
+      to: statementEndpoint(edge?.to),
+      strength: str(edge?.strength),
+    });
+  }
+  return {
+    inventory: asArray(statements?.inventory).map((row) => ({
+      family: str(row?.family),
+      subtype: str(row?.subtype),
+      incoming: count(row?.incoming) ?? 0,
+      outgoing: count(row?.outgoing) ?? 0,
+      both: count(row?.both) ?? 0,
+    })),
+    groups: [...groups].map(([name, rows]) => ({ name, rows })),
+  };
+}
+
+/** One line for a focus coverage object (`status`, `omittedEdges`); anything but `accounted` is flagged. */
+export function describeCoverage(coverage) {
+  const status = str(coverage?.status);
+  if (!status) return null;
+  const omitted = count(coverage.omittedEdges) ?? 0;
+  return [
+    status,
+    omitted > 0 ? `${plural(omitted, 'edge')} omitted` : null,
+    status === 'accounted' ? null : 'an empty lane is not proof of absence',
+  ]
+    .filter(Boolean)
+    .join(' · ');
+}