@goodbones/browser 0.1.0-beta.1

package/src/app/components/architecture/ManifestPane.tsx

@@ -0,0 +1,178 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+
+import type { Atlas, AtlasNode, AtlasPosition } from "../../../model/atlas.js";
+
+// The manifest, rendered as it was written — every file `include` pulled in
+// under its own tab — with each node's lines addressable: the line a node
+// starts on is its anchor, the lines down to the next node are its own. A
+// node's allowance no import uses is marked where it was written.
+
+type Props = {
+  readonly atlas: Atlas;
+  readonly activeNode: string | null;
+  readonly chain: ReadonlyArray<string>;
+  readonly scrollTo: AtlasPosition | null;
+  readonly selectedNode: string | null;
+  readonly onHoverNode: (id: string | null) => void;
+  readonly onSelectNode: (id: string | null) => void;
+};
+
+type Anchored = {
+  readonly node: AtlasNode;
+  readonly line: number;
+  // The last line that is this node's own, before the next node begins.
+  readonly end: number;
+};
+
+const anchorsOf = (
+  nodes: ReadonlyArray<AtlasNode>,
+  file: string,
+  lines: number,
+): ReadonlyArray<Anchored> => {
+  const here = nodes
+    .filter((node) => node.position?.file === file)
+    .map((node) => ({ node, line: node.position?.line ?? 0 }))
+    .sort((a, b) => (a.line !== b.line ? a.line - b.line : a.node.depth - b.node.depth));
+  return here.map((one, index) => {
+    const next = here.slice(index + 1).find((other) => other.line > one.line);
+    return { node: one.node, line: one.line, end: next === undefined ? lines : next.line - 1 };
+  });
+};
+
+const escapeRegExp = (literal: string): string => literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+export const ManifestPane = ({
+  activeNode,
+  atlas,
+  chain,
+  onHoverNode,
+  onSelectNode,
+  scrollTo,
+  selectedNode,
+}: Props): React.JSX.Element => {
+  const files = atlas.manifest.files;
+  const [tab, setTab] = useState(files[0]?.path ?? "");
+  const wanted = scrollTo?.file ?? null;
+  useEffect(() => {
+    if (wanted !== null && files.some((file) => file.path === wanted)) setTab(wanted);
+  }, [wanted, files]);
+  useEffect(() => {
+    if (!files.some((file) => file.path === tab)) setTab(files[0]?.path ?? "");
+  }, [files, tab]);
+
+  const active = files.find((file) => file.path === tab) ?? files[0];
+  const lines = useMemo(() => (active === undefined ? [] : active.text.split("\n")), [active]);
+  const anchors = useMemo(
+    () => (active === undefined ? [] : anchorsOf(atlas.manifest.nodes, active.path, lines.length)),
+    [active, atlas, lines.length],
+  );
+  const byLine = useMemo(() => new Map(anchors.map((one) => [one.line, one] as const)), [anchors]);
+  const own = anchors.find((one) => one.node.id === activeNode) ?? null;
+  const chainLines = useMemo(
+    () => new Set(anchors.filter((one) => chain.includes(one.node.id)).map((one) => one.line)),
+    [anchors, chain],
+  );
+
+  // The unused allowances, found where they were written.
+  const slackLines = useMemo(() => {
+    const found = new Map<number, string>();
+    for (const anchor of anchors) {
+      const unused = (anchor.node.imports?.allowances ?? []).filter((one) => !one.used);
+      if (unused.length === 0) continue;
+      for (let line = anchor.line; line <= anchor.end; line += 1) {
+        const text = lines[line - 1] ?? "";
+        for (const allowance of unused) {
+          if (
+            new RegExp(`(^|[\\s\\[,"'])${escapeRegExp(allowance.entry)}(["',\\]\\s]|$)`).test(text)
+          ) {
+            found.set(line, allowance.entry);
+          }
+        }
+      }
+    }
+    return found;
+  }, [anchors, lines]);
+
+  // Bring the focused node's anchor into view when the focus moves.
+  const listRef = useRef<HTMLOListElement | null>(null);
+  const targetLine = scrollTo !== null && scrollTo.file === active?.path ? scrollTo.line : null;
+  useEffect(() => {
+    if (targetLine === null || listRef.current === null) return;
+    const element = listRef.current.querySelector<HTMLElement>(
+      `[data-line="${String(targetLine)}"]`,
+    );
+    element?.scrollIntoView({ block: "center", behavior: "smooth" });
+  }, [targetLine, tab]);
+
+  // The innermost node whose lines include this one.
+  const nodeAtLine = (line: number): AtlasNode | null => {
+    let best: Anchored | null = null;
+    for (const anchor of anchors) {
+      if (anchor.line <= line && (best === null || anchor.line >= best.line)) best = anchor;
+    }
+    return best?.node ?? null;
+  };
+
+  return (
+    <div
+      className="manifest"
+      onMouseLeave={() => {
+        onHoverNode(null);
+      }}
+    >
+      <div className="pane-head tabs-row">
+        {files.map((file) => (
+          <button
+            key={file.path}
+            type="button"
+            className={file.path === active?.path ? "tab active" : "tab"}
+            onClick={() => {
+              setTab(file.path);
+            }}
+            title={file.path}
+          >
+            {file.path.split("/").slice(-2).join("/")}
+          </button>
+        ))}
+      </div>
+      <ol className="source" ref={listRef}>
+        {lines.map((text, index) => {
+          const line = index + 1;
+          const anchor = byLine.get(line);
+          const classes = ["line"];
+          if (anchor !== undefined) classes.push("anchor");
+          if (own !== null && line >= own.line && line <= own.end) classes.push("own");
+          if (chainLines.has(line)) classes.push("chain");
+          if (anchor?.node.id === selectedNode) classes.push("selected");
+          const slack = slackLines.get(line);
+          if (slack !== undefined) classes.push("slack");
+          return (
+            <li
+              key={line}
+              data-line={line}
+              className={classes.join(" ")}
+              onMouseEnter={() => {
+                onHoverNode(nodeAtLine(line)?.id ?? null);
+              }}
+              onClick={() => {
+                const node = nodeAtLine(line);
+                onSelectNode(node === null ? null : node.id);
+              }}
+              title={
+                slack !== undefined
+                  ? `No import uses "${slack}": this allowance is slack.`
+                  : anchor === undefined
+                    ? undefined
+                    : `${anchor.node.id} — ${String(anchor.node.files)} file(s) governed`
+              }
+            >
+              <span className="ln">{line}</span>
+              <span className="code">{text === "" ? " " : text}</span>
+              {anchor !== undefined ? <span className="node-tag">{anchor.node.id}</span> : null}
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+};

package/src/app/components/architecture/Tree.tsx

@@ -0,0 +1,205 @@
+import type { AtlasEdge } from "../../../model/atlas.js";
+import type { Arc, Relation, Row } from "./rows.js";
+
+// The tree and its arcs: one row per visible file or folder, the edges drawn
+// in a lane beside them. Every arc is there, greyed; the ones touching the
+// focus come forward — out of it in the accent, into it in ink, refused in
+// red — so a file's whole neighbourhood reads at a glance.
+
+export const ROW = 24;
+const LANE = 150;
+
+type Props = {
+  readonly rows: ReadonlyArray<Row>;
+  readonly arcs: ReadonlyArray<Arc>;
+  readonly focus: string | null;
+  readonly focusIsFolder: boolean;
+  readonly relations: ReadonlyMap<string, Relation>;
+  readonly governedBy: string | null;
+  readonly selected: string | null;
+  readonly onHover: (path: string | null) => void;
+  readonly onToggle: (folder: string) => void;
+  readonly onSelect: (row: Row) => void;
+};
+
+type ArcClass = "out" | "in" | "within" | "dim";
+
+const classify = (arc: Arc, focus: string | null, focusIsFolder: boolean): ArcClass => {
+  if (focus === null) return "dim";
+  const inside = (path: string): boolean =>
+    focusIsFolder ? path === focus || path.startsWith(`${focus}/`) : path === focus;
+  let out = false;
+  let into = false;
+  let within = false;
+  for (const edge of arc.edges) {
+    const fromIn = inside(edge.from);
+    const toIn = inside(edge.to);
+    if (fromIn && toIn) within = true;
+    else if (fromIn) out = true;
+    else if (toIn) into = true;
+  }
+  if (out) return "out";
+  if (into) return "in";
+  if (within) return "within";
+  return "dim";
+};
+
+const ORDER: Readonly<Record<ArcClass, number>> = { dim: 0, within: 1, in: 2, out: 3 };
+
+const arcPath = (from: number, to: number): string => {
+  const y1 = from * ROW + ROW / 2;
+  const y2 = to * ROW + ROW / 2;
+  const span = Math.abs(from - to);
+  const bulge = Math.min(LANE - 12, 18 + span * 5);
+  return `M6 ${String(y1)} C ${String(6 + bulge)} ${String(y1)}, ${String(6 + bulge)} ${String(y2)}, 10 ${String(y2)}`;
+};
+
+const rowRelation = (row: Row, relations: ReadonlyMap<string, Relation>): Relation => {
+  const own = relations.get(row.path);
+  if (own !== undefined) return own;
+  if (row.kind === "folder" && !row.expanded) {
+    // A collapsed folder carries the strongest relation of what it hides.
+    let best: Relation = null;
+    for (const [path, relation] of relations) {
+      if (!path.startsWith(`${row.path}/`)) continue;
+      if (relation === "dep" || relation === "importer") return relation;
+      best ??= relation;
+    }
+    return best;
+  }
+  return null;
+};
+
+const isGoverned = (row: Row, governedBy: string | null): boolean =>
+  governedBy !== null &&
+  (row.kind === "file"
+    ? row.file.chain.includes(governedBy)
+    : row.folder.node === governedBy || row.folder.declares.includes(governedBy));
+
+export const Tree = ({
+  arcs,
+  focus,
+  focusIsFolder,
+  governedBy,
+  onHover,
+  onSelect,
+  onToggle,
+  relations,
+  rows,
+  selected,
+}: Props): React.JSX.Element => {
+  const height = Math.max(rows.length, 1) * ROW;
+  const classified = arcs
+    .map((arc) => ({ arc, kind: classify(arc, focus, focusIsFolder) }))
+    .sort((a, b) => ORDER[a.kind] - ORDER[b.kind]);
+  return (
+    <div
+      className="tree"
+      onMouseLeave={() => {
+        onHover(null);
+      }}
+    >
+      <ol className="rows" style={{ height }}>
+        {rows.map((row) => {
+          const relation = rowRelation(row, relations);
+          const classes = ["row", row.kind];
+          if (relation !== null) classes.push(relation);
+          if (isGoverned(row, governedBy)) classes.push("governed");
+          if (selected === row.path) classes.push("selected");
+          const violations = row.kind === "file" ? row.file.violations : row.violations;
+          return (
+            <li
+              key={row.path}
+              className={classes.join(" ")}
+              style={{ paddingLeft: 8 + row.depth * 14, height: ROW }}
+              onMouseEnter={() => {
+                onHover(row.path);
+              }}
+              onClick={() => {
+                onSelect(row);
+              }}
+              title={row.path}
+            >
+              {row.kind === "folder" ? (
+                <button
+                  type="button"
+                  className="chevron"
+                  aria-label={row.expanded ? "collapse" : "expand"}
+                  onClick={(event) => {
+                    event.stopPropagation();
+                    onToggle(row.path);
+                  }}
+                >
+                  {row.expanded ? "▾" : "▸"}
+                </button>
+              ) : (
+                <span className="chevron spacer" />
+              )}
+              <span className={`name ${row.kind === "file" && !row.file.walked ? "outside" : ""}`}>
+                {row.name}
+                {row.kind === "folder" ? "/" : ""}
+              </span>
+              {row.kind === "folder" && row.folder.declares.length > 0 ? (
+                <span className="node-mark" title={`node: ${row.folder.declares.join(", ")}`}>
+                  §
+                </span>
+              ) : null}
+              {row.kind === "folder" && !row.expanded ? (
+                <span className="meta">{row.files}</span>
+              ) : null}
+              {violations > 0 ? (
+                <span className="badge refused" title={`${String(violations)} violation(s)`}>
+                  {violations}
+                </span>
+              ) : null}
+            </li>
+          );
+        })}
+      </ol>
+      <svg
+        className="arcs"
+        width={LANE}
+        height={height}
+        viewBox={`0 0 ${String(LANE)} ${String(height)}`}
+        aria-hidden="true"
+      >
+        <defs>
+          {(["dim", "within", "in", "out", "refused"] as const).map((kind) => (
+            <marker
+              key={kind}
+              id={`head-${kind}`}
+              viewBox="0 0 10 10"
+              refX="9"
+              refY="5"
+              markerWidth="6"
+              markerHeight="6"
+              orient="auto-start-reverse"
+            >
+              <path d="M0,0 L10,5 L0,10 z" className={`head ${kind}`} />
+            </marker>
+          ))}
+        </defs>
+        {classified.map(({ arc, kind }) => {
+          const refused = arc.refused && kind !== "dim";
+          const marker = refused ? "refused" : kind;
+          return (
+            <path
+              key={`${String(arc.from)}>${String(arc.to)}`}
+              d={arcPath(arc.from, arc.to)}
+              className={`arc ${kind} ${arc.refused ? "refused" : ""}`}
+              markerEnd={`url(#head-${marker})`}
+            >
+              <title>{describe(arc.edges)}</title>
+            </path>
+          );
+        })}
+      </svg>
+    </div>
+  );
+};
+
+const describe = (edges: ReadonlyArray<AtlasEdge>): string =>
+  edges
+    .slice(0, 6)
+    .map((edge) => `${edge.from} → ${edge.to}${edge.status === "refused" ? " (refused)" : ""}`)
+    .join("\n") + (edges.length > 6 ? `\n… ${String(edges.length - 6)} more` : "");

package/src/app/components/architecture/rows.ts

@@ -0,0 +1,181 @@
+import type { Atlas, AtlasEdge, AtlasFile, AtlasFolder } from "../../../model/atlas.js";
+
+// The tree as rows, and the edges as arcs between rows. A folder collapsed
+// stands in for everything under it: an edge into a hidden file lands on the
+// nearest visible ancestor, and edges between two files of one collapsed
+// folder are not drawn. Pure, so the drawing can be tested without a DOM.
+
+export type Row =
+  | {
+      readonly kind: "folder";
+      readonly path: string;
+      readonly name: string;
+      readonly depth: number;
+      readonly expanded: boolean;
+      readonly folder: AtlasFolder;
+      readonly files: number;
+      readonly violations: number;
+    }
+  | {
+      readonly kind: "file";
+      readonly path: string;
+      readonly name: string;
+      readonly depth: number;
+      readonly file: AtlasFile;
+    };
+
+export type Arc = {
+  readonly from: number;
+  readonly to: number;
+  readonly edges: ReadonlyArray<AtlasEdge>;
+  readonly refused: boolean;
+};
+
+type Tree = {
+  readonly folders: ReadonlyMap<string, ReadonlyArray<AtlasFolder>>;
+  readonly files: ReadonlyMap<string, ReadonlyArray<AtlasFile>>;
+  readonly filesUnder: ReadonlyMap<string, number>;
+  readonly violationsUnder: ReadonlyMap<string, number>;
+};
+
+const parentOf = (path: string): string => {
+  const at = path.lastIndexOf("/");
+  return at === -1 ? "" : path.slice(0, at);
+};
+
+export const treeOf = (atlas: Atlas): Tree => {
+  const folders = new Map<string, Array<AtlasFolder>>();
+  for (const folder of atlas.folders) {
+    const key = folder.parent ?? "";
+    const held = folders.get(key) ?? [];
+    held.push(folder);
+    folders.set(key, held);
+  }
+  const files = new Map<string, Array<AtlasFile>>();
+  const filesUnder = new Map<string, number>();
+  const violationsUnder = new Map<string, number>();
+  for (const file of atlas.files) {
+    const held = files.get(file.folder) ?? [];
+    held.push(file);
+    files.set(file.folder, held);
+    let folder = file.folder;
+    while (folder !== "") {
+      filesUnder.set(folder, (filesUnder.get(folder) ?? 0) + 1);
+      violationsUnder.set(folder, (violationsUnder.get(folder) ?? 0) + file.violations);
+      folder = parentOf(folder);
+    }
+  }
+  for (const held of folders.values()) held.sort((a, b) => a.name.localeCompare(b.name));
+  for (const held of files.values()) held.sort((a, b) => a.name.localeCompare(b.name));
+  return { folders, files, filesUnder, violationsUnder };
+};
+
+// Folders first, then files, each alphabetically; a folder is walked into
+// only when expanded.
+export const rowsOf = (atlas: Atlas, expanded: ReadonlySet<string>): ReadonlyArray<Row> => {
+  const tree = treeOf(atlas);
+  const rows: Array<Row> = [];
+  const visit = (folder: string, depth: number): void => {
+    for (const child of tree.folders.get(folder) ?? []) {
+      const isExpanded = expanded.has(child.path);
+      rows.push({
+        kind: "folder",
+        path: child.path,
+        name: child.name,
+        depth,
+        expanded: isExpanded,
+        folder: child,
+        files: tree.filesUnder.get(child.path) ?? 0,
+        violations: tree.violationsUnder.get(child.path) ?? 0,
+      });
+      if (isExpanded) visit(child.path, depth + 1);
+    }
+    for (const file of tree.files.get(folder) ?? []) {
+      rows.push({ kind: "file", path: file.path, name: file.name, depth, file });
+    }
+  };
+  visit("", 0);
+  return rows;
+};
+
+// The row a file lands on: its own, or the nearest visible ancestor's.
+export const rowIndexOf = (
+  rows: ReadonlyArray<Row>,
+  expanded: ReadonlySet<string>,
+): ((file: string) => number) => {
+  const index = new Map(rows.map((row, i) => [row.path, i] as const));
+  return (file) => {
+    let path = file;
+    while (path !== "") {
+      const found = index.get(path);
+      if (found !== undefined && (path === file || !expanded.has(path))) return found;
+      path = parentOf(path);
+    }
+    return -1;
+  };
+};
+
+export const arcsOf = (
+  atlas: Atlas,
+  rows: ReadonlyArray<Row>,
+  expanded: ReadonlySet<string>,
+): ReadonlyArray<Arc> => {
+  const at = rowIndexOf(rows, expanded);
+  const arcs = new Map<string, { from: number; to: number; edges: Array<AtlasEdge> }>();
+  for (const edge of atlas.edges) {
+    const from = at(edge.from);
+    const to = at(edge.to);
+    if (from === -1 || to === -1 || from === to) continue;
+    const key = `${String(from)}>${String(to)}`;
+    const held = arcs.get(key);
+    if (held === undefined) arcs.set(key, { from, to, edges: [edge] });
+    else held.edges.push(edge);
+  }
+  return [...arcs.values()].map((arc) => ({
+    ...arc,
+    refused: arc.edges.some((edge) => edge.status === "refused"),
+  }));
+};
+
+// Every folder, for a tree that opens fully; or the folders down to a depth,
+// for one too large to.
+export const initiallyExpanded = (atlas: Atlas): ReadonlySet<string> => {
+  const open = atlas.files.length <= 600;
+  return new Set(
+    atlas.folders.filter((folder) => open || folder.depth < 2).map((folder) => folder.path),
+  );
+};
+
+// What a focus on one row means for every other: the files it reaches, the
+// files that reach it, the siblings it owes, and the files under it.
+export type Relation = "focus" | "dep" | "importer" | "sibling" | "within" | null;
+
+export const relationsOf = (
+  atlas: Atlas,
+  focus: string | null,
+  isFolder: boolean,
+): ReadonlyMap<string, Relation> => {
+  const relations = new Map<string, Relation>();
+  if (focus === null) return relations;
+  const inside = (path: string): boolean =>
+    isFolder ? path.startsWith(`${focus}/`) : path === focus;
+  relations.set(focus, "focus");
+  for (const edge of atlas.edges) {
+    const fromIn = inside(edge.from);
+    const toIn = inside(edge.to);
+    if (fromIn && toIn) {
+      if (isFolder) {
+        relations.set(edge.from, "within");
+        relations.set(edge.to, "within");
+      }
+    } else if (fromIn && !relations.has(edge.to)) relations.set(edge.to, "dep");
+    else if (toIn && !relations.has(edge.from)) relations.set(edge.from, "importer");
+  }
+  if (!isFolder) {
+    const file = atlas.files.find((one) => one.path === focus);
+    for (const owed of file?.requires ?? []) {
+      if (!relations.has(owed.sibling)) relations.set(owed.sibling, "sibling");
+    }
+  }
+  return relations;
+};

package/src/app/components/architecture/selection.ts

@@ -0,0 +1,6 @@
+// What the Architecture Browser can hold: a file or folder of the tree, or a
+// node of the manifest. In the hash as the path, or `node:<id>`.
+export type Selection =
+  | { readonly kind: "file"; readonly path: string }
+  | { readonly kind: "folder"; readonly path: string }
+  | { readonly kind: "node"; readonly id: string };