pi-weave 0.1.7 → 0.1.9

package/src/core/graph/mentions.ts

@@ -0,0 +1,170 @@
+/**
+ * `mentions` edges: a note body that names a repository path → note → node
+ * (weave-workspace §4.4, §15.5).
+ *
+ * `EdgeKind` has declared `"mentions"` since the graph model was written and
+ * `buildGraph` had never emitted one, so every consumer carried a branch that
+ * could not be taken and the legend advertised a relationship the product did
+ * not have. This module is the implementation side of that choice.
+ *
+ * Pure and I/O-free, like its sibling `wikilinks.ts`: a regex over a string
+ * and a lookup in a map built from the repo index. No parsing, no LLM, no
+ * new dependency (§4.4 is explicit about all three).
+ */
+
+import type { RepoStructure } from "../types";
+
+/**
+ * A repo-relative path candidate: two or more `/`-joined segments of word
+ * characters, dots and dashes.
+ *
+ * The lookbehind is the part doing real work. `(?<![\w/.@:-])` refuses to
+ * start a match immediately after a character that would make this the *tail*
+ * of something longer, which is what keeps `https://github.com/org/repo/src`
+ * and `user@host.com/path` from being read as repo paths. Without it every
+ * URL in every note becomes a candidate, and since candidates are only kept
+ * when they hit a real node the damage would be invisible until the day
+ * someone's repo happened to contain `org/repo`.
+ *
+ * At least one slash is required, so prose words are not candidates. Trailing
+ * sentence punctuation is stripped by {@link extractPathMentions} rather than
+ * excluded here, because `src/core.` at the end of a sentence should match
+ * `src/core` and a regex that refuses the dot cannot also accept
+ * `src/core/vault.ts`.
+ */
+const PATH_RE = /(?<![\w/.@:-])([\w.-]+(?:\/[\w.-]+)+)/g;
+
+/** Punctuation that ends a sentence rather than a path. */
+const TRAILING_PUNCT_RE = /[.,;:!?)\]}'"]+$/;
+
+/**
+ * Repo path → graph node id, for every path-addressable node the builder
+ * emits.
+ *
+ * Deliberately built from {@link RepoStructure} rather than by scanning the
+ * finished node list: both are derived from the same arrays, so mirroring the
+ * id construction here keeps the invariant that *every* value in this map is
+ * a node that exists, while reading it back off `GraphNode.detail.path` would
+ * mean re-parsing a display-only field (§4.2) to recover something structured
+ * we already had.
+ */
+export type PathIndex = ReadonlyMap<string, string>;
+
+/**
+ * Index the path-bearing nodes of a repository, exactly mirroring the ids
+ * `buildRepositorySide` emits.
+ *
+ * Insertion order is modules, then entry points, then packages, then `.okf`
+ * files. Later kinds do **not** overwrite earlier ones: a path that is both a
+ * module and an entry point resolves to the module, which is the coarser and
+ * more navigable of the two. The choice only has to be *stable*, and pinning
+ * it here is what makes it so.
+ *
+ * `(root)` is skipped. It is a display label for "files directly in the repo
+ * root", not a path, and no note body can spell it in a way that reaches
+ * here anyway.
+ */
+export function buildPathIndex(structure: RepoStructure): PathIndex {
+  const index = new Map<string, string>();
+  const put = (path: string, id: string): void => {
+    if (path.length > 0 && !index.has(path)) index.set(path, id);
+  };
+  for (const mod of structure.modules) {
+    if (mod.path === "(root)") continue;
+    put(mod.path, `module:${mod.path}`);
+  }
+  for (const entry of structure.entryPoints) put(entry, `entryPoint:${entry}`);
+  for (const pkg of structure.packages) put(pkg.manifestPath, `package:${pkg.manifestPath}`);
+  // `.okf` files are addressed by their repo-relative path (".okf/…"), while
+  // their node ids drop the prefix — the same rename `buildRepositorySide`
+  // performs.
+  for (const file of structure.okFiles ?? []) {
+    put(file, `okf:${file.replace(/^\.okf\//, "")}`);
+  }
+  return index;
+}
+
+/**
+ * Every distinct path-like token in a note body, in order of first
+ * appearance, with trailing sentence punctuation and trailing slashes
+ * removed.
+ *
+ * Exported for its own tests: the regex is the part of this feature most
+ * likely to be wrong, and testing it through `buildGraph` alone would mean
+ * every false-positive case needed a whole repo fixture.
+ */
+export function extractPathMentions(body: string): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const match of body.matchAll(PATH_RE)) {
+    // `?? ""` rather than an `undefined` guard: the group is mandatory, so it
+    // always participates and a guard would be a branch no input can take.
+    // An empty string falls out at the `includes("/")` check just below.
+    const path = (match[1] ?? "").replace(TRAILING_PUNCT_RE, "").replace(/\/+$/, "");
+    if (!path.includes("/") || seen.has(path)) continue;
+    seen.add(path);
+    out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Resolve the repo nodes a note body mentions, as node ids in first-appearance
+ * order, deduplicated.
+ *
+ * ## Granularity: exact match, else the longest **enclosing** module
+ *
+ * This is the decision that keeps the edge count sane, and it runs in exactly
+ * one direction.
+ *
+ * *Never downward.* A note saying "see `src/core`" produces **one** edge, to
+ * `module:src/core`. It does not fan out to the files beneath it. Expanding a
+ * prefix downward is how a three-word sentence turns into forty edges and the
+ * graph column becomes unreadable — the explicit failure mode §4.4 warns
+ * about.
+ *
+ * *Upward, at most one step.* A note saying `src/core/vault.ts` is making a
+ * genuine reference, but most repository files are not graph nodes (only
+ * modules, entry points, packages and `.okf` files are), so an exact-match-only
+ * rule would silently drop the majority of real mentions and leave the feature
+ * looking broken. The fallback walks the path's ancestors longest-first and
+ * takes the first that is a **module**, so the mention lands on the nearest
+ * indexed container: `src/core/graph/build.ts` → `module:src/core`.
+ *
+ * The asymmetry is what makes this safe. Each distinct mentioned path resolves
+ * to **at most one** node, so the edges a note can contribute are bounded by
+ * the number of distinct paths it names, and the collapse only ever reduces
+ * that further — two files in the same module fold into a single edge because
+ * the result is deduplicated by target.
+ *
+ * The ancestor walk is restricted to modules on purpose: an entry point or a
+ * manifest is a *file*, and "this note mentions a path inside `package.json`"
+ * is not a relationship that exists.
+ */
+export function resolveMentions(body: string, paths: PathIndex): string[] {
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const path of extractPathMentions(body)) {
+    const id = paths.get(path) ?? enclosingModule(path, paths);
+    if (id === null || id === undefined || seen.has(id)) continue;
+    seen.add(id);
+    out.push(id);
+  }
+  return out;
+}
+
+/**
+ * The nearest ancestor directory of `path` that is an indexed module, or
+ * `null`. Longest first, so `src/core/graph/x.ts` prefers `src/core/graph`
+ * over `src/core` when both are modules.
+ */
+function enclosingModule(path: string, paths: PathIndex): string | null {
+  const segments = path.split("/");
+  for (let cut = segments.length - 1; cut > 0; cut--) {
+    const ancestor = segments.slice(0, cut).join("/");
+    const id = paths.get(ancestor);
+    // Only a module may absorb a mention of something inside it.
+    if (id !== undefined && id.startsWith("module:")) return id;
+  }
+  return null;
+}

package/src/core/graph/model.ts

@@ -60,4 +60,43 @@ export interface GraphModel {
   staleness: StalenessReport | null;
   nodes: GraphNode[];
   edges: GraphEdge[];
+  /**
+   * slug → wiki-link targets that resolved to no note in the graph
+   * (weave-workspace §4.2).
+   *
+   * A `[[target]]` that matches nothing is not an error — it is Obsidian's
+   * ghost node, the affordance that offers to create the missing note. The
+   * builder used to count these and throw the names away, leaving
+   * `detail["dangling links"] = "3"` as the only trace; a display string is
+   * not something a UI can navigate.
+   *
+   * Lives here rather than on {@link GraphNode} because `detail` is
+   * display-only by contract and must not grow structure (§4.2 is explicit
+   * about preferring the model-level map). Notes with nothing unresolved are
+   * absent rather than present-and-empty, so the common case costs no bytes.
+   *
+   * Keyed by **slug**, not by node id: the consumers of this map (the note
+   * column, the wire payload's `dangling` field) speak slugs, and `note:` is
+   * a graph-internal prefix.
+   *
+   * Insertion order follows note order and each target list follows
+   * first-appearance order in the body, so the JSON stays byte-stable for
+   * unchanged inputs.
+   */
+  danglingLinks: Record<string, string[]>;
+  /**
+   * Content fingerprint of the note bodies the graph was built from
+   * (SHA-256 over `slug\0body-digest` pairs in slug order, truncated to
+   * 128 bits of hex).
+   *
+   * Exists so the wire payload's stamp — the digest the ETag and the SSE
+   * dedupe both key on — is sensitive to a **body-only** edit. The payload
+   * itself carries only display excerpts of a note (`detail.preview`, the
+   * first 240 flattened characters), so an edit below the fold with
+   * unchanged front matter used to leave the payload byte-identical: the
+   * frame was deduped away and the open note stayed stale until a manual
+   * reload. The digest is a function of content only, so it keeps the
+   * byte-determinism contract.
+   */
+  contentDigest: string;
 }

package/src/core/graph/wikilinks.ts

@@ -12,6 +12,10 @@ const WIKILINK_RE = /\[\[([^\][|]+)(?:\|[^\]]*)?\]\]/g;
  * `[[some-note]]` and aliased `[[Some Note|alias]]` (alias ignored for
  * linking). Targets are slugified so `[[Release Plan]]` matches the note
  * `release-plan`. Duplicates are removed, order of first appearance kept.
+ *
+ * Path separators survive: a nested note's slug is its path relative to
+ * `notes/` (`sessions/foo`), so `[[sessions/foo]]` targets the session note,
+ * not a flattened name. Each path segment is slugified independently.
  */
 export function extractWikilinks(body: string): string[] {
   const out: string[] = [];
@@ -19,7 +23,7 @@ export function extractWikilinks(body: string): string[] {
   for (const match of body.matchAll(WIKILINK_RE)) {
     const raw = (match[1] ?? "").trim();
     if (raw.length === 0) continue;
-    const slug = slugify(raw);
+    const slug = raw.split("/").map((part) => slugify(part)).join("/");
     if (seen.has(slug)) continue;
     seen.add(slug);
     out.push(slug);

package/src/core/index.ts

@@ -13,13 +13,27 @@ export * from "./git";
 export * from "./vault";
 export * from "./repoIndex";
 export * from "./summaries";
+export * from "./sessions";
+export * from "./concurrency";
 export * from "./workspace";
+export * from "./openInEditor";
 export * from "./graph/model";
 export * from "./graph/wikilinks";
+export * from "./view";
 export { buildGraph, dataTimestamp, DEFAULT_MAX_NOTES, type BuildGraphInput } from "./graph/build";
 export {
   buildCurrentGraph,
   readNoteForView,
   readOkfFileForView,
+  readRepositorySide,
   type ViewNote,
 } from "./graph/current";
+export {
+  classifyPath,
+  DEFAULT_STALENESS_TTL_MS,
+  WorkspaceCache,
+  type CacheStats,
+  type InvalidationScope,
+  type WorkspaceCacheOptions,
+  type WorkspaceSnapshot,
+} from "./cache/workspace";

package/src/core/openInEditor.ts

@@ -0,0 +1,69 @@
+/**
+ * Open a vault note in the user's editor.
+ *
+ * Originally `src/pi/viewer/tui/openNote.ts`, promoted into core because the
+ * browser workspace needs it too and `src/web/server/**` may not import
+ * `src/pi` (weave-workspace §2). It belongs here on the merits regardless:
+ * it is a pure fan-out over `core/vault` plus one `execFile`, with no
+ * harness and no terminal concept in it, and the same reasoning that put
+ * `readNoteForView` in core applies unchanged.
+ *
+ * The old path re-exports these two names, so no TUI file changed.
+ *
+ * Security: the slug is validated against the vault (traversal-safe) before
+ * any shell-out, and the command is invoked with `execFile`, not a shell, so
+ * neither the slug nor a `$EDITOR` containing metacharacters can compose a
+ * command. `$EDITOR` itself is trusted — it is the user's own configuration,
+ * and a hostile one already has whatever the user has.
+ */
+
+import { execFile } from "node:child_process";
+import { platform } from "node:os";
+import { promisify } from "node:util";
+import { getNote, resolveNotePath } from "./vault";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * The OS command used to open a note file in the user's editor. Respects
+ * $EDITOR / $VISUAL (which may carry args, e.g. "code --wait"); falls back
+ * to the platform default opener. `env` and `os` are injectable so the
+ * mapping is unit-testable on any host without stubbing globals.
+ */
+export function openNoteCommand(
+  notePath: string,
+  env: NodeJS.ProcessEnv = process.env,
+  os: NodeJS.Platform = platform(),
+): { command: string; args: string[] } {
+  const editor = (env.EDITOR || env.VISUAL || "").trim();
+  if (editor) {
+    // editor is a trimmed non-empty string, so split+filter always yields a
+    // first segment — assert it rather than leave a dead `?? ""` branch.
+    const parts = editor.split(/\s+/).filter(Boolean);
+    const command = parts[0] as string;
+    return { command, args: [...parts.slice(1), notePath] };
+  }
+  if (os === "darwin") return { command: "open", args: [notePath] };
+  if (os === "win32") return { command: "cmd", args: ["/c", "start", "", notePath] };
+  return { command: "xdg-open", args: [notePath] };
+}
+
+/**
+ * Open a note in the OS editor. The slug is validated against the vault
+ * (traversal-safe) before any shell-out; returns false when the note does
+ * not exist or the slug is unsafe.
+ */
+export async function openNoteInEditor(
+  vaultRoot: string,
+  slug: string,
+  openCommand: (notePath: string) => { command: string; args: string[] } = openNoteCommand,
+): Promise<boolean> {
+  const path = resolveNotePath(vaultRoot, slug);
+  if (path === null) return false; // traversal-safe
+  const note = await getNote(vaultRoot, slug);
+  if (note === null) return false;
+  const { command, args } = openCommand(path);
+  if (!command) return false;
+  await execFileAsync(command, args);
+  return true;
+}

package/src/core/paths.ts

@@ -14,6 +14,13 @@ import { join } from "node:path";
 export const OKF_DIR = ".okf";
 export const OKF_MANIFEST = "okf.json";
 export const NOTES_DIR = "notes";
+/**
+ * Vault collection for generated session memory (docs/session-scan.md).
+ * A sibling of `notes/` rather than a subdirectory of it: session notes are
+ * machine-derived memory, not hand-curated knowledge, so they stay out of
+ * the note graph's flat listing — and out of its slug namespace.
+ */
+export const SESSIONS_DIR = "sessions";
 export const REPOSITORY_DIR = "repository";
 export const VAULT_ENV_VAR = "PI_WEAVE_VAULT";