pi-weave 0.1.7 → 0.1.9

package/src/core/view/links.ts

@@ -0,0 +1,105 @@
+/**
+ * Link and tag derivations over vault/graph data (weave-workspace §3, §4.3).
+ */
+
+import type { GraphEdge } from "../graph/model";
+import type { NoteMeta } from "../types";
+
+/** Map each node id → its incoming `links-to` sources (backlinks). */
+export function deriveBacklinks(edges: readonly GraphEdge[]): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  for (const e of edges) {
+    if (e.kind !== "links-to") continue;
+    const list = out.get(e.target);
+    if (list) list.push(e.source);
+    else out.set(e.target, [e.source]);
+  }
+  return out;
+}
+
+/**
+ * One tag and every note carrying it (weave-workspace §4.3).
+ *
+ * `slugs` rather than node ids: `note:` is a graph-internal prefix, and every
+ * consumer of this index — the note column's tag chips, `GraphPayload.tags` —
+ * addresses notes by slug.
+ */
+export interface TagIndex {
+  tag: string;
+  slugs: string[];
+}
+
+/**
+ * The minimum a note has to expose to be tag-indexed: its identity and its
+ * tags.
+ *
+ * Declared structurally instead of taking `NoteSummary` outright so the
+ * function accepts a `Note` (which has a `body` and no `bodyLength`) just as
+ * happily as a `NoteSummary`. §4.3 specifies `NoteSummary[]`; this is that
+ * signature widened to its actual requirement rather than narrowed past it,
+ * and `NoteSummary` still satisfies it exactly.
+ */
+export type TaggedNote = Pick<NoteMeta, "tags"> & { slug: string };
+
+/**
+ * Invert `note → tags` into `tag → notes` (weave-workspace §4.3).
+ *
+ * ## Why this takes notes and not a `GraphModel`
+ *
+ * The obvious alternative is deriving from the graph, since every other
+ * function in this directory does. It is the wrong source here, and the
+ * reason is worth stating because "derive everything from the graph" is
+ * otherwise a good rule.
+ *
+ * `buildGraph` flattens tags into `detail.tags`, a comma-joined **display**
+ * string (`build.ts`: `note.tags.join(", ")`). Recovering an array from it
+ * means splitting on `", "` — which is re-parsing a display string into
+ * structure, precisely what §4.2/§4.3 forbid `detail` from being used for,
+ * and it is lossy besides: a tag containing a comma round-trips wrong, and
+ * the tag is simply absent when a note has none. The alternative is to make
+ * `GraphNode` carry a real `tags: string[]` alongside the display string,
+ * which puts the same fact on the node twice and grows the wire model for
+ * every note whether or not anything reads it.
+ *
+ * Notes are the upstream source of truth. Both callers already hold them —
+ * `buildCurrentGraph` and `WorkspaceCache` each read the vault before they
+ * build a graph — so deriving here costs no extra I/O and keeps one
+ * representation of a tag: the array on the note. The graph's display string
+ * stays a projection of that, never an input to it.
+ *
+ * ## Ordering
+ *
+ * Count descending, then tag ascending, per §4.3 — the popular tags surface
+ * first and ties are alphabetical rather than insertion-ordered. Each `slugs`
+ * list is sorted ascending too, so the whole structure is a pure function of
+ * the tag/slug *set*: two vaults with the same tags in a different note order
+ * produce byte-identical JSON, which is what lets this ride the ETag.
+ *
+ * The tiebreak is **codepoint** order, not `localeCompare`, which is the one
+ * place this file departs from the habit elsewhere in core. `localeCompare`
+ * reads the host's default locale and the runtime's ICU build — a Node
+ * compiled with small-icu can order `"Arch"` against `"arch"` differently
+ * from one with full-icu. Everywhere else that is a cosmetic difference in a
+ * list a human is about to read; here the output is hashed into a cache key
+ * (§5.3), so an ordering that varies by machine is a correctness bug rather
+ * than a preference. Codepoint order is total, locale-free and matches the
+ * bare `.sort()` used for `slugs` just below.
+ *
+ * Duplicate tags within one note collapse (front matter is hand-editable and
+ * `tags: [a, a]` is a typo, not two memberships).
+ */
+export function deriveTagIndex(notes: readonly TaggedNote[]): TagIndex[] {
+  const bySlug = new Map<string, Set<string>>();
+  for (const note of notes) {
+    for (const tag of note.tags) {
+      const slugs = bySlug.get(tag);
+      if (slugs) slugs.add(note.slug);
+      else bySlug.set(tag, new Set([note.slug]));
+    }
+  }
+  return [...bySlug]
+    .map(([tag, slugs]): TagIndex => ({ tag, slugs: [...slugs].sort() }))
+    // Tags come from a Map's keys, so no two are equal and the comparator
+    // never needs to return 0 for the tiebreak — `< ? -1 : 1` is total here.
+    .sort((a, b) => b.slugs.length - a.slugs.length || (a.tag < b.tag ? -1 : 1));
+}

package/src/core/view/time.ts

@@ -0,0 +1,47 @@
+/**
+ * Time formatting for the portable view-models (weave-workspace §3).
+ */
+
+import type { TreeMeta } from "./types";
+
+/** Relative human time, mirroring the page's `relTime`. `now` is epoch ms. */
+export function relTime(iso: string | undefined, now: number): string {
+  if (!iso) return "";
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return "";
+  const s = Math.max(0, Math.floor((now - t) / 1000));
+  if (s < 60) return "just now";
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ago`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ago`;
+  const d = Math.floor(h / 24);
+  if (d < 30) return `${d}d ago`;
+  const mo = Math.floor(d / 30);
+  if (mo < 12) return `${mo}mo ago`;
+  return `${Math.floor(mo / 12)}y ago`;
+}
+
+/** Short-sha length used when abbreviating a commit for display. */
+const SHORT_SHA_LEN = 7;
+
+/**
+ * Render a `TreeMeta` as a single plain-text annotation.
+ *
+ * This reproduces the strings the TUI printed when `TreeRow.meta` was itself a
+ * string, so terminal output is unchanged by the structuring. Richer renderers
+ * (the browser workspace) should switch on the union instead of calling this.
+ */
+export function formatTreeMeta(meta: TreeMeta, now: number): string {
+  if (meta === null) return "";
+  switch (meta.kind) {
+    case "relTime":
+      return relTime(meta.iso, now);
+    case "count":
+      return meta.phrasing === "attribute" ? `${meta.unit}=${meta.n}` : `${meta.n} ${meta.unit}`;
+    case "commit":
+      return meta.sha.slice(0, SHORT_SHA_LEN);
+    case "text":
+      return meta.text;
+  }
+}

package/src/core/view/tree.ts

@@ -0,0 +1,269 @@
+/**
+ * treeRows — the portable Explore/tree view-model (weave-workspace §3).
+ *
+ * Ported 1:1 from the retired browser page's `listTree`. Pure: it takes a
+ * `GraphModel` plus a `TreeState` and returns rows. No renderer concepts —
+ * no widths, no truncation, no escape codes. Both the TUI and the browser
+ * workspace build their tree column from this.
+ */
+
+import type { GraphModel, GraphNode, NodeKind } from "../graph/model";
+import type { NoteSource } from "../types";
+import type { SelectableRow, TreeMeta } from "./types";
+
+/** One row in the Explore tree. */
+export interface TreeRow extends SelectableRow {
+  depth: number;
+  hasKids: boolean;
+  expanded: boolean;
+  label: string;
+  kind: NodeKind;
+  provenance: NoteSource | null;
+  /** Structured trailing annotation; renderers format it (see formatTreeMeta). */
+  meta: TreeMeta;
+}
+
+export interface TreeState {
+  /** Expanded node ids (when no filter is active). */
+  expanded: ReadonlySet<string>;
+  /** Reveal repo plumbing (gitState/external/package/entryPoint). */
+  showInternals: boolean;
+  /** Provenance filter (null = all). */
+  provFilter: NoteSource | null;
+  /** Substring filter on node labels (case-insensitive). */
+  query: string;
+}
+
+/** Disambiguate labels that would otherwise read as the same entry twice
+ *  (a remote URL whose tail matches the repo name, an npm package named
+ *  after the repo). Mirrors the page's `listLabel`. */
+export function listLabel(node: GraphNode): string {
+  if (node.kind === "external" && node.detail.url) {
+    const u = node.detail.url
+      .replace(/^[a-z]+:\/\//, "")
+      .replace(/^[^@\/]+@/, "")
+      .replace(/\.git$/, "")
+      .replace(/\/+$/, "");
+    if (u) return u;
+  }
+  if (node.kind === "package" && node.detail.manifest) {
+    return `${node.label} (${node.detail.manifest})`;
+  }
+  return node.label;
+}
+
+/** Build the contains/anchored-at nesting + entry-point-to-module map. */
+interface TreeIndex {
+  byId: Map<string, GraphNode>;
+  /** strict contains (used for entry-point → module placement). */
+  contains: Map<string, string[]>;
+  /** contains + anchored-at (the nesting hierarchy). */
+  tree: Map<string, string[]>;
+  /** node id → true when it has an incoming contains/anchored-at edge. */
+  incoming: Set<string>;
+  /** module id → entry-point ids nested under it (by path prefix). */
+  moduleEntries: Map<string, string[]>;
+  /** roots (nodes with no incoming edge), in node-input order. */
+  roots: string[];
+}
+
+function indexTree(model: GraphModel): TreeIndex {
+  const byId = new Map<string, GraphNode>();
+  for (const n of model.nodes) byId.set(n.id, n);
+
+  const contains = new Map<string, string[]>();
+  const tree = new Map<string, string[]>();
+  const incoming = new Set<string>();
+  for (const e of model.edges) {
+    if (e.kind === "contains") {
+      const list = contains.get(e.source);
+      if (list) list.push(e.target);
+      else contains.set(e.source, [e.target]);
+    }
+    if (e.kind === "contains" || e.kind === "anchored-at") {
+      const list = tree.get(e.source);
+      if (list) list.push(e.target);
+      else tree.set(e.source, [e.target]);
+      incoming.add(e.target);
+    }
+  }
+
+  // Entry points nest under the module whose path is the entry's directory prefix.
+  // The caller only invokes this for entryPoint nodes, so the path guard suffices.
+  const moduleFor = (entry: GraphNode): string | null => {
+    if (!entry.detail.path) return null;
+    const p = entry.detail.path;
+    let best: string | null = null;
+    let bestLen = 0;
+    const repoKids = contains.get("repository") ?? [];
+    for (const cid of repoKids) {
+      const c = byId.get(cid);
+      if (c && c.kind === "module" && c.detail.path) {
+        const mp = c.detail.path;
+        if (p.startsWith(mp + "/") && mp.length > bestLen) {
+          best = cid;
+          bestLen = mp.length;
+        }
+      }
+    }
+    return best;
+  };
+
+  const moduleEntries = new Map<string, string[]>();
+  for (const n of model.nodes) {
+    if (n.kind !== "entryPoint") continue;
+    const m = moduleFor(n);
+    if (m) {
+      const list = moduleEntries.get(m);
+      if (list) list.push(n.id);
+      else moduleEntries.set(m, [n.id]);
+    }
+  }
+
+  const roots = model.nodes.filter((n) => !incoming.has(n.id)).map((n) => n.id);
+  return { byId, contains, tree, incoming, moduleEntries, roots };
+}
+
+/** The roots of a graph (nodes with no incoming contains/anchored-at edge). */
+export function graphRoots(model: GraphModel): string[] {
+  const incoming = new Set<string>();
+  for (const e of model.edges) {
+    if (e.kind === "contains" || e.kind === "anchored-at") incoming.add(e.target);
+  }
+  return model.nodes.filter((n) => !incoming.has(n.id)).map((n) => n.id);
+}
+
+/** Knowledge-first default: hide repo plumbing unless showInternals. */
+function hiddenInternalKind(kind: NodeKind): boolean {
+  return kind === "gitState" || kind === "external" || kind === "package" || kind === "entryPoint";
+}
+
+function sortKids(ids: string[], byId: Map<string, GraphNode>): string[] {
+  return ids
+    .slice()
+    .sort((a, b) => {
+      const la = listLabel(byId.get(a)!);
+      const lb = listLabel(byId.get(b)!);
+      return la.localeCompare(lb);
+    });
+}
+
+/** A `count` meta when the detail value is numeric, else a verbatim `text`
+ *  meta — so a hand-built or corrupt graph still displays what it holds. */
+function countMeta(raw: string, unit: string, phrasing: "attribute" | "prose"): TreeMeta {
+  const n = Number(raw);
+  if (!Number.isFinite(n)) {
+    return { kind: "text", text: phrasing === "attribute" ? `${unit}=${raw}` : `${raw} ${unit}` };
+  }
+  return { kind: "count", n, unit, phrasing };
+}
+
+function metaFor(node: GraphNode): TreeMeta {
+  switch (node.kind) {
+    case "note":
+      return node.detail.updated ? { kind: "relTime", iso: node.detail.updated } : null;
+    case "module":
+      return node.detail.files ? countMeta(node.detail.files, "files", "attribute") : null;
+    case "gitState":
+      return node.detail.commit ? { kind: "commit", sha: node.detail.commit } : null;
+    case "repository":
+      return node.detail.files ? countMeta(node.detail.files, "files", "prose") : null;
+    case "package":
+      return node.detail.kind ? { kind: "text", text: node.detail.kind } : null;
+    case "entryPoint":
+      return node.detail.summary ? { kind: "text", text: "summary" } : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Build the Explore tree rows (port of the page's `listTree`).
+ *
+ * - Roots: `vault`, `repository` (nodes with no incoming containment edge).
+ * - Entry points nest under their prefix module.
+ * - Internals hidden by default; the caller toggles `showInternals`.
+ * - Filter (query and/or provenance): prune to matches + ancestors, auto-expanding ancestors.
+ * - Default expansion (no filter): controlled by `state.expanded`.
+ */
+export function treeRows(model: GraphModel, state: TreeState): TreeRow[] {
+  const idx = indexTree(model);
+  const { byId, tree, moduleEntries, roots } = idx;
+
+  const children = (id: string): string[] => {
+    const kids = tree.get(id) ?? [];
+    // Drop entry points that have a claiming module (they re-nest under it).
+    const filtered = kids.filter((kid) => {
+      const n = byId.get(kid);
+      if (!n || n.kind !== "entryPoint") return true;
+      for (const [, entries] of moduleEntries) {
+        if (entries.includes(kid)) return false;
+      }
+      return true;
+    });
+    let all = filtered.concat(moduleEntries.get(id) ?? []);
+    // Skip kids absent from the node set (corrupt/hand-built graphs): the page
+    // never produces these, but a defensive filter keeps the tree robust.
+    all = all.filter((k) => byId.has(k));
+    if (!state.showInternals) {
+      all = all.filter((k) => {
+        const n = byId.get(k);
+        return !(n && hiddenInternalKind(n.kind));
+      });
+    }
+    return sortKids(all, byId);
+  };
+
+  const filtering = state.provFilter !== null || state.query.length > 0;
+
+  const matches = (node: GraphNode): boolean => {
+    if (state.provFilter !== null && node.provenance !== state.provFilter) return false;
+    if (state.query.length > 0 && !listLabel(node).toLowerCase().includes(state.query.toLowerCase())) return false;
+    return true;
+  };
+
+  // Pass 1: mark visible nodes (self-match or a visible descendant).
+  const visible = new Set<string>();
+  const mark = (id: string): boolean => {
+    const node = byId.get(id)!;
+    let any = false;
+    for (const k of children(id)) if (mark(k)) any = true;
+    const show = matches(node) || any;
+    if (show) visible.add(id);
+    return show;
+  };
+  for (const r of roots) mark(r);
+
+  const rows: TreeRow[] = [];
+  const walk = (id: string, depth: number): void => {
+    if (!visible.has(id)) return;
+    const node = byId.get(id)!;
+    const kids = children(id);
+    const visibleKids = kids.filter((k) => visible.has(k));
+    const expanded = filtering ? visibleKids.length > 0 : state.expanded.has(id);
+    rows.push({
+      id,
+      depth,
+      hasKids: kids.length > 0,
+      expanded,
+      label: listLabel(node),
+      kind: node.kind,
+      provenance: node.provenance,
+      meta: metaFor(node),
+    });
+    if (expanded) for (const k of visibleKids) walk(k, depth + 1);
+  };
+  for (const r of roots) walk(r, 0);
+  return rows;
+}
+
+/** Empty-state hint for the tree surface (weave-view-tui-design §5.1). */
+export function treeEmptyHint(model: GraphModel): string | null {
+  const vault = model.nodes.find((n) => n.kind === "vault");
+  if (!vault) return null;
+  // no notes and no repository
+  const hasNotes = model.nodes.some((n) => n.kind === "note");
+  const hasRepo = model.nodes.some((n) => n.kind === "repository");
+  if (!hasNotes && !hasRepo) return "no notes yet — add one with the weave_note tool";
+  return null;
+}

package/src/core/view/types.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared row/meta types for the portable view-models (weave-workspace §3).
+ *
+ * These are *renderer-agnostic*: no terminal widths, no pre-truncation, no
+ * DOM. The TUI and the browser workspace both consume them and each applies
+ * its own formatting.
+ */
+
+/** A selectable row in any surface. `target` (when set) is the node id a row
+ *  jumps to on activation (a link / neighbor). */
+export interface SelectableRow {
+  id: string;
+  /** Node id this row jumps to on activation (links/backlinks/neighbors). */
+  target?: string;
+}
+
+/**
+ * The dim trailing annotation on a tree row, as structured data.
+ *
+ * Deliberately *not* a formatted string: a terminal column, an HTML `<span>`,
+ * and a `<time>` element each want something different, and a relative time
+ * has to be re-derived as the clock moves. `formatTreeMeta` (view/time.ts)
+ * reproduces the terminal phrasing; other renderers are free to ignore it.
+ */
+export type TreeMeta =
+  /** Relative timestamp, e.g. a note's `updated`. Rendered against a clock. */
+  | { kind: "relTime"; iso: string }
+  /**
+   * A counted quantity. `phrasing` is a display hint, not a hard rule:
+   * `"attribute"` reads as `unit=n` (a property of the row), `"prose"` reads
+   * as `n unit` (a description of it).
+   */
+  | { kind: "count"; n: number; unit: string; phrasing: "attribute" | "prose" }
+  /** A full commit sha; renderers abbreviate to taste. */
+  | { kind: "commit"; sha: string }
+  /** An opaque, already-human string (a package kind, a marker word). */
+  | { kind: "text"; text: string }
+  /** No annotation. */
+  | null;

package/src/core/workspace.ts

@@ -49,10 +49,10 @@ export async function getWorkspaceStatus(cwd: string, options: WorkspaceOptions
 /** One-line status string for footers/status bars. */
 export function formatStatusLine(status: WorkspaceStatus): string {
   const vault = `vault:${status.vault.noteCount}`;
-  if (!status.repository) return `🧵 ${vault}`;
-  if (!status.repository.indexed) return `🧵 ${vault} · repo:unindexed`;
+  if (!status.repository) return `🕸️ ${vault}`;
+  if (!status.repository.indexed) return `🕸️ ${vault} · repo:unindexed`;
   const mark = status.repository.staleness.state === "fresh" ? "ok" : status.repository.staleness.state;
-  return `🧵 ${vault} · ${status.repository.name}:${mark}`;
+  return `🕸️ ${vault} · ${status.repository.name}:${mark}`;
 }
 
 /** Multi-line dashboard used by the /weave command and notifications. */