Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

feat(view): open the map layer by layer, with topics as columns

Eren61d2873d35d9
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 82bc269..4e6eba7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -15,8 +15,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- `codelineage session write --consume`: deletes the `--file` input once the record is saved and keeps it when the write fails. `gitPolicy=commit` now also ignores `.codelineage/inbox/`.
### Changed
+- Map opens like layers of an onion: sessions run down the page in time order, and inside the latest session only its top-level topics show, side by side as columns with an "N items inside" count; an opened topic lists its items down its column, nested ones indented, and any node with children expands and collapses on click (selecting a nested item in the outline opens every layer above it). Phases are labelled "topic", and collapsed session boxes are wide enough for their titles.
+- `/codelineage:lineage` skill: organizes nodes by topic instead of by time (topics and sub-topics at any depth, time order kept inside each), reuses existing topics and moves misplaced nodes by resending them with the right `parent`.
- The npm package and the plugin manifest now take their version from `VERSION` (the one `./release` bumps): `npm run build` and `npm pack` copy it through `scripts/sync-version.mjs`, and a test fails while they differ. Both move from 0.1.0 to 0.4.0, so the first release continues at 0.5.0.
-- Map: inside a session the nodes now read top to bottom, as an indented outline (phases in order along a left spine, their steps, decisions and questions indented below), so the map grows downwards instead of sideways.
- Map: the graph now spans the full window width and nearly its full height (the header and status card stay at a readable width), and a "Full screen" button expands it over the whole window, entering browser full screen when allowed; Esc or the button closes it.
- `commander`, `zod` and `@inquirer/prompts` moved to `devDependencies`: they are bundled into `dist/cli.js`, so installing the package pulls in no runtime dependencies.
diff --git a/packages/cli/skills/lineage/SKILL.md b/packages/cli/skills/lineage/SKILL.md
index 3ca846d..c498512 100644
--- a/packages/cli/skills/lineage/SKILL.md
+++ b/packages/cli/skills/lineage/SKILL.md
@@ -36,15 +36,31 @@ Build one JSON object:
- `pending`: `{ "text": "…", "needsUser": true }` for anything waiting on the
user, and `needsUser: false` for work that is simply not done yet.
- `next`: the next concrete step.
-- `nodes`: only new nodes, or existing ones whose title, summary or reason
- changed. Nodes you leave out are kept, and so are fields you leave out.
+- `nodes`: only new nodes, or existing ones whose title, summary, reason or
+ parent changed. Nodes you leave out are kept, and so are fields you leave out.
- `id`: a short, stable slug. Reuse an existing id to change that node.
- - `kind`: `phase` (a stretch of work), `step` (a concrete action within a
- phase), `decision` (a choice that was made, with the reason in `why`) or
- `question` (an open question).
- - `parent`: the id of the phase the node belongs to, or `null` for a phase.
+ - `kind`: `phase` (a topic), `step` (a concrete action), `decision` (a choice
+ that was made, with the reason in `why`) or `question` (an open question).
+ - `parent`: the id of the topic the node belongs to, or `null` for a
+ top-level topic.
- `title`: up to about ten words. `summary` and `why`: one or two sentences.
+## Organize the nodes by topic, not by time
+
+The map opens like layers of an onion: first the session's top-level topics,
+then a click reveals what is inside each one. Order within a layer is the order
+in which things were added, so time is kept inside every topic.
+
+- A topic (`phase`) names what the work is about, such as "Permissions" or "Map
+ layout", never when it happened ("First part", "Open decisions").
+- Put each new step, decision or question under the topic it belongs to. Open
+ a sub-topic (a `phase` whose parent is a topic) once a topic holds several
+ distinct threads; nest as deep as the work needs.
+- Reuse an existing topic before creating a new one. If an earlier node sits
+ under the wrong topic, send it again (with its `kind` and `title`) and the
+ right `parent`.
+- Keep the top level short: a handful of topics per session.
+
Write titles and text in the conversation's language when `language` is `"auto"`,
and in that language otherwise. JSON keys stay in English.
diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsx
index 901da57..8aa567a 100644
--- a/packages/template/src/Graph.tsx
+++ b/packages/template/src/Graph.tsx
@@ -23,7 +23,7 @@ import {
useState,
} from "react";
import type { LineageViewModel } from "../../cli/src/view/model.js";
-import { formatDate, formatTime } from "./format.js";
+import { formatDate, formatTime, kindLabel } from "./format.js";
import { useFullscreen } from "./fullscreen.js";
import {
defaultExpanded,
@@ -34,9 +34,8 @@ import {
type SessionFlowNode,
TREE_LEFT,
TREE_OUT,
- TREE_TOP,
} from "./graph.js";
-import { Outline, type OutlineTarget } from "./Outline.js";
+import { Outline, type OutlineTarget, outlinePath } from "./Outline.js";
import { DrillDown, type Selection } from "./SidePanel.js";
/** Toggle callback reaches the group headers without threading props through React Flow. */
@@ -67,17 +66,10 @@ function GroupToggle({
);
}
-/** Spine handles for the top-to-bottom outline inside a session (see placeSessionNodes). */
+/** Spine handles for the outline inside a topic column (see placeSessionNodes). */
function TreeHandles() {
return (
<>
- <Handle
- id={TREE_TOP}
- type="target"
- position={Position.Top}
- className="flow-handle tree-handle"
- isConnectable={false}
- />
<Handle
id={TREE_LEFT}
type="target"
@@ -142,15 +134,20 @@ function SessionNode({ id, data }: NodeProps<SessionFlowNode>) {
);
}
-function LineageBox({ data }: NodeProps<LineageFlowNode>) {
+function LineageBox({ id, data }: NodeProps<LineageFlowNode>) {
return (
<div className={`lineage-box kind-${data.kind}`}>
<TreeHandles />
<div className="lineage-head">
- <span className={`kind kind-${data.kind}`}>{data.kind}</span>
+ {data.hasChildren ? <GroupToggle id={id} data={data} /> : null}
+ <span className={`kind kind-${data.kind}`}>{kindLabel(data.kind)}</span>
<strong title={data.title}>{data.title}</strong>
</div>
- {data.at ? (
+ {data.hasChildren && !data.expanded ? (
+ <p className="lineage-count">
+ {data.count} item{data.count === 1 ? "" : "s"} inside
+ </p>
+ ) : data.at ? (
<time dateTime={data.at}>{formatTime(data.at)}</time>
) : data.summary ? (
<p title={data.summary}>{data.summary}</p>
@@ -282,10 +279,12 @@ function Flow({ model }: { model: LineageViewModel }) {
*/
const selectFromOutline = useCallback(
(target: OutlineTarget) => {
- const needsLayout = target.expand.some((id) => !expanded.has(id));
+ // Open every layer above the target, including topics it is nested in.
+ const reveal = [...target.expand, ...(outlinePath(model, target.focusId) ?? []).slice(0, -1)];
+ const needsLayout = reveal.some((id) => !expanded.has(id));
setExpanded((previous) => {
const next = new Set(previous);
- for (const id of target.expand) next.add(id);
+ for (const id of reveal) next.add(id);
return next;
});
setSelection(target.selection);
@@ -298,7 +297,7 @@ function Flow({ model }: { model: LineageViewModel }) {
scheduleFocus(target.focusId);
}
},
- [expanded, scheduleFocus],
+ [expanded, model, scheduleFocus],
);
let content: ReactNode;
diff --git a/packages/template/src/Outline.tsx b/packages/template/src/Outline.tsx
index 6cf4243..6a01ff2 100644
--- a/packages/template/src/Outline.tsx
+++ b/packages/template/src/Outline.tsx
@@ -1,5 +1,6 @@
import { useEffect, useMemo, useState } from "react";
import type { LineageViewModel, ViewNode, ViewSession } from "../../cli/src/view/model.js";
+import { kindLabel } from "./format.js";
import { countNodes, epochId, nodeId, sessionId, UNASSIGNED_EPOCH_ID } from "./graph.js";
import type { Selection } from "./SidePanel.js";
@@ -146,7 +147,7 @@ function NodeRows({
})
}
>
- <span className={`kind kind-${node.kind}`}>{node.kind}</span>
+ <span className={`kind kind-${node.kind}`}>{kindLabel(node.kind)}</span>
<span className="label">{node.title}</span>
</button>
</div>
diff --git a/packages/template/src/SidePanel.tsx b/packages/template/src/SidePanel.tsx
index 154dce7..431613e 100644
--- a/packages/template/src/SidePanel.tsx
+++ b/packages/template/src/SidePanel.tsx
@@ -1,13 +1,14 @@
import { useEffect, useRef, useState } from "react";
import type { LineageViewModel, ViewSession } from "../../cli/src/view/model.js";
import { resumeCommand } from "../../cli/src/view/resume.js";
-import { formatTime } from "./format.js";
+import { formatTime, kindLabel } from "./format.js";
import type { LineageData } from "./graph.js";
+/** What the drill-down shows of a node; the expand state stays in the graph. */
+export type NodeDetail = Omit<LineageData, "count" | "expanded" | "hasChildren">;
+
/** What the drill-down shows: a graph node or a whole session. */
-export type Selection =
- | { type: "node"; node: LineageData }
- | { type: "session"; sessionId: string };
+export type Selection = { type: "node"; node: NodeDetail } | { type: "session"; sessionId: string };
function findSession(model: LineageViewModel, sessionId: string): ViewSession | undefined {
for (const epoch of model.epochs) {
@@ -129,7 +130,7 @@ function SessionSummary({ model, session }: { model: LineageViewModel; session:
);
}
-function NodeDetails({ model, node }: { model: LineageViewModel; node: LineageData }) {
+function NodeDetails({ model, node }: { model: LineageViewModel; node: NodeDetail }) {
const session = findSession(model, node.sessionId);
return (
<>
@@ -231,7 +232,7 @@ export function DrillDown({
<aside className="drilldown" role="dialog" aria-label="Node details">
<header className="drilldown-head">
<div>
- <span className={`kind kind-${node.kind}`}>{node.kind}</span>
+ <span className={`kind kind-${node.kind}`}>{kindLabel(node.kind)}</span>
<h2>{node.title}</h2>
</div>
<button type="button" className="drilldown-close" aria-label="Close" onClick={onClose}>
diff --git a/packages/template/src/format.ts b/packages/template/src/format.ts
index 4b55c13..5df0639 100644
--- a/packages/template/src/format.ts
+++ b/packages/template/src/format.ts
@@ -13,3 +13,8 @@ export function formatDate(iso: string | null): string {
? iso
: date.toLocaleDateString(undefined, { month: "short", day: "numeric" });
}
+
+/** Phases are shown as topics: the map groups a session by what the work is about. */
+export function kindLabel(kind: string): string {
+ return kind === "phase" ? "topic" : kind;
+}
diff --git a/packages/template/src/graph.ts b/packages/template/src/graph.ts
index 0cbb1d2..d3b193e 100644
--- a/packages/template/src/graph.ts
+++ b/packages/template/src/graph.ts
@@ -23,13 +23,15 @@ const GROUP_HEADER = 44;
const ROOT_PADDING = 48;
-/** Inside a session nodes read top to bottom: phases in order, their items indented below. */
+/** Inside a topic column nodes read top to bottom, nested items indented below their topic. */
const INDENT = 32;
const ROW_GAP = 16;
+const COLUMN_GAP = 24;
+/** Wide enough that a collapsed session shows a readable title. */
+const SESSION_WIDTH = 380;
-/** Handle ids on lineage cards: the spine leaves at the bottom left, enters at the top left or the left side. */
+/** Handle ids on lineage cards: the spine leaves at the bottom left and enters at the left side. */
export const TREE_OUT = "tree-out";
-export const TREE_TOP = "tree-top";
export const TREE_LEFT = "tree-left";
export type EpochData = {
@@ -57,6 +59,10 @@ export type LineageData = {
at?: string;
/** Owning session, so the drill-down panel can show and resume it. */
sessionId: string;
+ /** Nodes nested below this one, at any depth. */
+ count: number;
+ expanded: boolean;
+ hasChildren: boolean;
};
export type EpochFlowNode = FlowNode<EpochData, "epoch">;
@@ -106,7 +112,10 @@ function groupOptions() {
};
}
-/** The map opens on the most recently updated session, with its epoch expanded. */
+/**
+ * The map opens on the most recently updated session, with its epoch expanded,
+ * showing only that session's top-level topics; deeper layers open on click.
+ */
export function defaultExpanded(model: LineageViewModel): Set<string> {
const candidates: { session: ViewSession; group: string }[] = [];
for (const epoch of model.epochs) {
@@ -171,39 +180,46 @@ function treeEdge(source: string, target: string, targetHandle: string): FlowEdg
}
/**
- * Places a session's nodes as an indented, top-to-bottom outline: one row per node
- * in recorded order. Phases are chained along the left spine and each item hangs
- * off its parent's spine, so the map grows downwards, never sideways.
+ * Places a session's nodes: top-level topics side by side as columns (they run in
+ * parallel, so their order matters little), and inside each column an indented,
+ * top-to-bottom outline of what the topic holds, in recorded order. Time runs
+ * down the map across sessions; topics run across.
*/
-export function placeSessionNodes(nodes: ViewNode[], sessionGroup: string): Placement {
+export function placeSessionNodes(
+ nodes: ViewNode[],
+ sessionGroup: string,
+ isOpen: (id: string) => boolean = () => true,
+): Placement {
const boxes = new Map<string, Sized>();
const edges: FlowEdge[] = [];
- let row = 0;
- let maxDepth = 0;
- const visit = (list: ViewNode[], parent: string | null, depth: number): void => {
- let previous: string | null = null;
- for (const node of list) {
+ const top = GROUP_HEADER + 8;
+ let columnX = GROUP_PADDING;
+ let maxRows = 0;
+ for (const root of nodes) {
+ let row = 0;
+ let columnWidth = NODE_WIDTH;
+ const visit = (node: ViewNode, parent: string | null, depth: number): void => {
const id = nodeId(sessionGroup, node.id);
boxes.set(id, {
- x: GROUP_PADDING + depth * INDENT,
- y: GROUP_HEADER + 8 + row * (NODE_HEIGHT + ROW_GAP),
+ x: columnX + depth * INDENT,
+ y: top + row * (NODE_HEIGHT + ROW_GAP),
width: NODE_WIDTH,
height: NODE_HEIGHT,
});
row += 1;
- maxDepth = Math.max(maxDepth, depth);
+ columnWidth = Math.max(columnWidth, depth * INDENT + NODE_WIDTH);
if (parent !== null) edges.push(treeEdge(parent, id, TREE_LEFT));
- else if (previous !== null) edges.push(treeEdge(previous, id, TREE_TOP));
- previous = id;
- visit(node.children, id, depth + 1);
- }
- };
- visit(nodes, null, 0);
+ if (isOpen(id)) for (const child of node.children) visit(child, id, depth + 1);
+ };
+ visit(root, null, 0);
+ maxRows = Math.max(maxRows, row);
+ columnX += columnWidth + COLUMN_GAP;
+ }
return {
boxes,
edges,
- width: GROUP_PADDING * 2 + maxDepth * INDENT + NODE_WIDTH,
- height: GROUP_HEADER + 8 + row * (NODE_HEIGHT + ROW_GAP) - ROW_GAP + GROUP_PADDING,
+ width: Math.max(columnX - COLUMN_GAP, GROUP_PADDING) + GROUP_PADDING,
+ height: top + maxRows * (NODE_HEIGHT + ROW_GAP) - ROW_GAP + GROUP_PADDING,
};
}
@@ -217,12 +233,12 @@ function buildSession(
const id = sessionId(session.sessionId);
meta.set(id, parentId);
const showChildren = expanded.has(id) && session.nodes.length > 0;
- if (!showChildren) return { id, width: GROUP_WIDTH, height: GROUP_HEIGHT };
+ if (!showChildren) return { id, width: SESSION_WIDTH, height: GROUP_HEIGHT };
// ELK sizes the session box; its contents are placed by hand.
- const placement = placeSessionNodes(session.nodes, id);
+ const placement = placeSessionNodes(session.nodes, id, (nodeKey) => expanded.has(nodeKey));
placements.set(id, placement);
- return { id, width: Math.max(GROUP_WIDTH, placement.width), height: placement.height };
+ return { id, width: Math.max(SESSION_WIDTH, placement.width), height: placement.height };
}
function buildEpoch(
@@ -371,7 +387,7 @@ export async function layoutGraph(
},
});
if (!sessionExpanded) continue;
- collectFlowNodes(session.nodes, id, session.sessionId, nodes, sizes);
+ collectFlowNodes(session.nodes, id, session.sessionId, nodes, sizes, expanded);
}
}
@@ -384,9 +400,11 @@ function collectFlowNodes(
sessionId: string,
out: GraphNode[],
sizes: Map<string, Sized>,
+ expanded: ReadonlySet<string>,
): void {
for (const node of nodes) {
const id = nodeId(parent, node.id);
+ const open = expanded.has(id);
const size = sizes.get(id) ?? { x: 0, y: 0, width: NODE_WIDTH, height: NODE_HEIGHT };
out.push({
id,
@@ -406,8 +424,11 @@ function collectFlowNodes(
...(node.why === undefined ? {} : { why: node.why }),
...(node.at === undefined ? {} : { at: node.at }),
sessionId,
+ count: countNodes(node.children),
+ expanded: open,
+ hasChildren: node.children.length > 0,
},
});
- collectFlowNodes(node.children, parent, sessionId, out, sizes);
+ if (open) collectFlowNodes(node.children, parent, sessionId, out, sizes, expanded);
}
}
diff --git a/packages/template/src/styles.css b/packages/template/src/styles.css
index adff39b..a49e664 100644
--- a/packages/template/src/styles.css
+++ b/packages/template/src/styles.css
@@ -455,6 +455,10 @@ body:has(.map-shell.is-expanded) {
text-overflow: ellipsis;
}
+.lineage-box p.lineage-count {
+ color: var(--accent);
+}
+
.lineage-box time {
display: block;
margin-top: 1px;
diff --git a/packages/template/test/format.test.ts b/packages/template/test/format.test.ts
index d219fcf..3a5bb00 100644
--- a/packages/template/test/format.test.ts
+++ b/packages/template/test/format.test.ts
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
-import { formatDate, formatTime } from "../src/format.js";
+import { formatDate, formatTime, kindLabel } from "../src/format.js";
describe("format", () => {
it("shows a placeholder for a missing time and an unparseable value as-is", () => {
@@ -19,3 +19,10 @@ describe("format", () => {
expect(formatDate(iso)).not.toContain(":");
});
});
+
+describe("kindLabel", () => {
+ it("shows phases as topics and keeps the other kinds", () => {
+ expect(kindLabel("phase")).toBe("topic");
+ expect(kindLabel("decision")).toBe("decision");
+ });
+});
diff --git a/packages/template/test/graph.test.ts b/packages/template/test/graph.test.ts
index 7873cd5..d46f201 100644
--- a/packages/template/test/graph.test.ts
+++ b/packages/template/test/graph.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import type { ViewNode } from "../../cli/src/view/model.js";
-import { placeSessionNodes, TREE_LEFT, TREE_TOP } from "../src/graph.js";
+import { placeSessionNodes, TREE_LEFT } from "../src/graph.js";
function node(id: string, children: ViewNode[] = []): ViewNode {
return { id, kind: "phase", title: id, children };
@@ -11,27 +11,39 @@ describe("placeSessionNodes", () => {
const { boxes, edges, width, height } = placeSessionNodes(tree, "s");
const box = (id: string) => boxes.get(`node:s:${id}`);
- it("puts every node on its own row in recorded order", () => {
- const order = ["a", "a1", "a2", "a2x", "b", "b1"].map((id) => box(id)?.y ?? -1);
- expect(order).toEqual([...order].sort((x, y) => x - y));
- expect(new Set(order).size).toBe(order.length);
+ it("puts top-level topics side by side in one row", () => {
+ expect(box("a")?.y).toBe(box("b")?.y);
+ expect(box("b")?.x).toBeGreaterThan((box("a2x")?.x ?? 0) + (box("a2x")?.width ?? 0));
});
- it("indents children under their parent and keeps phases in one column", () => {
- expect(box("a")?.x).toBe(box("b")?.x);
+ it("lists a topic's items below it in recorded order, indented by depth", () => {
+ const column = ["a", "a1", "a2", "a2x"].map((id) => box(id)?.y ?? -1);
+ expect(column).toEqual([...column].sort((x, y) => x - y));
+ expect(new Set(column).size).toBe(column.length);
expect(box("a1")?.x).toBeGreaterThan(box("a")?.x ?? 0);
expect(box("a2x")?.x).toBeGreaterThan(box("a2")?.x ?? 0);
- expect(width).toBeGreaterThanOrEqual((box("a2x")?.x ?? 0) + (box("a2x")?.width ?? 0));
- expect(height).toBeGreaterThan((box("b1")?.y ?? 0) + (box("b1")?.height ?? 0));
+ expect(width).toBeGreaterThan((box("b1")?.x ?? 0) + (box("b1")?.width ?? 0));
+ expect(height).toBeGreaterThan((box("a2x")?.y ?? 0) + (box("a2x")?.height ?? 0));
});
- it("chains phases along the spine and hangs items off their parent", () => {
+ it("hangs items off their parent and never links parallel topics", () => {
const link = (from: string, to: string) =>
edges.find((e) => e.source === `node:s:${from}` && e.target === `node:s:${to}`);
- expect(link("a", "b")?.targetHandle).toBe(TREE_TOP);
expect(link("a", "a1")?.targetHandle).toBe(TREE_LEFT);
expect(link("a2", "a2x")?.targetHandle).toBe(TREE_LEFT);
- expect(link("a1", "a2")).toBeUndefined();
- expect(edges).toHaveLength(5);
+ expect(link("a", "b")).toBeUndefined();
+ expect(edges).toHaveLength(4);
+ });
+
+ it("hides the children of a closed topic and narrows its column", () => {
+ const closed = placeSessionNodes(tree, "s", (id) => id !== "node:s:a");
+ expect(closed.boxes.has("node:s:a1")).toBe(false);
+ expect(closed.boxes.has("node:s:b1")).toBe(true);
+ expect(closed.boxes.get("node:s:b")?.x).toBeLessThan(box("b")?.x ?? 0);
+ expect(closed.edges.map((e) => e.target)).toEqual(["node:s:b1"]);
+ });
+
+ it("gives an empty session a minimal box", () => {
+ expect(placeSessionNodes([], "s").boxes.size).toBe(0);
});
});