@cueloop/schema 0.1.0-alpha.63 → 0.1.0-alpha.65

package/src/path-view.ts

@@ -0,0 +1,85 @@
+/**
+ * The linear view of a session's active path. Every client reads the artifact
+ * text, the working copy, and the comments straight off the record, so the
+ * record keeps them materialized; this module recomputes them from the path
+ * whenever a tip moves. Comments the path does not reach are shelved, never
+ * dropped, so a later move can show them again.
+ */
+
+import { derivePath, followBranch, MAIN_BRANCH, pathOf, type SessionHistory } from "./history";
+import type { Annotation, ReviewSession } from "./types";
+
+export interface PathView {
+  /** The last agent revision on the path: what the artifact shows. */
+  content: string;
+  /** The reviewer's edits over it, when the path's head is a reviewer revision. */
+  workingCopy: string | undefined;
+  /** The comments open on the path, in path order. */
+  annotations: Annotation[];
+  /** Every other comment the session knows. */
+  shelvedAnnotations: Annotation[];
+}
+
+/**
+ * Fold the active path over every comment the session holds, on or off the
+ * path. Comments on the path whose objects are gone stay gone.
+ */
+export function viewOfPath(history: SessionHistory, known: Annotation[]): PathView {
+  const derived = derivePath(history);
+  const agentHead = pathOf(history)
+    .filter((entry) => entry.type === "revision" && entry.by === "agent")
+    .at(-1);
+  const content = agentHead?.type === "revision" ? agentHead.content : derived.head.content;
+  const byId = new Map(known.map((annotation) => [annotation.id, annotation]));
+  const annotations: Annotation[] = [];
+
+  for (const id of derived.annotationIds) {
+    const annotation = byId.get(id);
+
+    if (annotation) {
+      annotations.push(annotation);
+      byId.delete(id);
+    }
+  }
+
+  return {
+    content,
+    workingCopy: derived.head.content === content ? undefined : derived.head.content,
+    annotations,
+    shelvedAnnotations: [...byId.values()],
+  };
+}
+
+/** Write a path view back into a record, in place; absent fields are removed. */
+export function applyPathView(session: ReviewSession, view: PathView): void {
+  session.artifact = { ...session.artifact, content: view.content };
+  session.annotations = view.annotations;
+  if (view.workingCopy === undefined) delete session.workingCopy;
+  else session.workingCopy = view.workingCopy;
+  if (view.shelvedAnnotations.length === 0) delete session.shelvedAnnotations;
+  else session.shelvedAnnotations = view.shelvedAnnotations;
+}
+
+/**
+ * The record as a share carries it: the followed branch's path and what it
+ * shows, with no other branch, no shelved comment, and no working copy of the
+ * owner's. A followed branch that no longer exists falls back to main. A record
+ * without a history travels as it is.
+ */
+export function viewFollowing(session: ReviewSession, branch?: string): ReviewSession {
+  const asked = branch ?? session.shareBranch ?? MAIN_BRANCH;
+  // a branch that no longer exists falls back to main, matching the daemon
+  const followed =
+    session.history && session.history.tips[asked] === undefined ? MAIN_BRANCH : asked;
+  const shared: ReviewSession = { ...session, shareBranch: followed };
+
+  if (!session.history) return shared;
+  const history = followBranch(session.history, followed);
+  const known = [...session.annotations, ...(session.shelvedAnnotations ?? [])];
+
+  shared.history = history;
+  applyPathView(shared, viewOfPath(history, known));
+  delete shared.shelvedAnnotations;
+
+  return shared;
+}

package/src/types.ts

@@ -1,9 +1,11 @@
 /**
  * The ReviewSession primitive. Everything in cueloop renders, annotates, or
  * resolves this one noun. This module is pure data shapes - no IO, no
- * dependencies.
+ * dependencies beyond the history shapes.
  */
 
+import type { SessionHistory } from "./history";
+
 export const SCHEMA_VERSION = "1";
 
 /** A workspace is a repo/branch context holding review sessions. */
@@ -28,7 +30,7 @@ export type ArtifactType = (typeof ARTIFACT_TYPES)[number];
 
 /** Trust-boundary guard: is this string one of the artifact primitives? */
 export function isArtifactType(value: string): value is ArtifactType {
-  return (ARTIFACT_TYPES as readonly string[]).includes(value);
+  return ARTIFACT_TYPES.some((candidate) => candidate === value);
 }
 
 /**
@@ -61,6 +63,17 @@ export interface ArtifactMeta {
 /** How a file changed, so curation emits the right create/delete headers. */
 export type DiffFileStatus = "added" | "modified" | "deleted";
 
+/**
+ * One reject decision of a diff review: a whole hunk, or one change block of
+ * it when `changeIndex` is set. The daemon curates the working copy from the
+ * full set, so every client sees the same patch.
+ */
+export interface HunkRejection {
+  path: string;
+  hunkIndex: number;
+  changeIndex?: number;
+}
+
 export interface DiffFileContents {
   path: string;
   oldContents: string;
@@ -91,9 +104,11 @@ export interface Anchor {
   quote: string;
   prefix: string;
   suffix: string;
-  /** Index of the block the anchor was made in (hint). */
+  /** Index of the block the anchor starts in (hint). */
   blockIndex?: number;
-  /** Character offsets within that block's text (hint). */
+  /** Last block of a quote that spans blocks (hint); absent for one block. */
+  endBlockIndex?: number;
+  /** Character offsets: `start` within the first block, `end` within the last (hint). */
   start?: number;
   end?: number;
   /** Prototype anchors: the CSS selector of the annotated element (authority). */
@@ -127,6 +142,11 @@ export interface Annotation {
    * planner can tell whose note is whose and never overwrite a collaborator's.
    */
   author?: string;
+  /**
+   * The root comment this one replies to. Absent on a root. A reply shares its
+   * root's anchor, so a discussion stays one conversation when the text moves.
+   */
+  replyTo?: string;
   /**
    * Set when a revision addressed this annotation: the agent reported the id
    * on resubmit ("agent"), or the quoted text disappeared from the revised
@@ -190,6 +210,15 @@ export interface ReviewSession {
   /** Revision history; artifact.content always equals the latest revision. */
   revisions: Revision[];
   annotations: Annotation[];
+  /**
+   * The session's history as a tree of entries with named branches; the
+   * artifact text and the open comments derive from the active path. Absent
+   * only on records written before histories existed; the store migrates
+   * those on read.
+   */
+  history?: SessionHistory;
+  /** A diff review's reject decisions; the working copy is the patch they leave. */
+  curation?: HunkRejection[];
   /**
    * The reviewer's working copy of the artifact source (plan edits).
    * Serializes as ONE unified diff against the submitted revision.
@@ -205,8 +234,18 @@ export interface ReviewSession {
   verdict: Verdict | null;
   status: SessionStatus;
   createdAt: string;
+  /**
+   * Comments off the active path - removed, or made on a segment a tip moved
+   * away from. Nothing is deleted: a navigate or switch that brings their
+   * entries back onto the path shows them again.
+   */
+  shelvedAnnotations?: Annotation[];
+  /** The session this one was forked from. */
+  parentSessionId?: string;
   /** Share id once published; lets the planner pull collaborator notes back. */
   shareId?: string;
+  /** The branch the share follows and shows collaborators; `main` when absent. */
+  shareBranch?: string;
   /** SSH fingerprint that created the share; the gateway stamps it to gate pulls. */
   owner?: string;
   /**

package/src/working-copy.ts

@@ -41,6 +41,20 @@ function signature(text: string): string {
     .join("\0");
 }
 
+/**
+ * Whether a base block is missing from the working source: the working copy
+ * holds fewer blocks with its kind and text than the base does. Only such a
+ * block can be restored without duplicating content.
+ */
+export function isBlockCut(base: string, working: string, block: Block): boolean {
+  const matches = (text: string) =>
+    parseBlocks(text).filter(
+      (candidate) => candidate.kind === block.kind && candidate.text === block.text,
+    ).length;
+
+  return matches(working) < matches(base);
+}
+
 /**
  * Re-insert a cut base block into the working source before `beforeLine`.
  * Returns undefined when the block structure round-trips to the base content