@diagrammo/dgmo 0.2.19 → 0.2.21

package/src/er/layout.ts

@@ -153,17 +153,59 @@ export function layoutERDiagram(parsed: ParsedERDiagram): ERLayoutResult {
     };
   });
 
-  // Compute total dimensions
-  let totalWidth = 0;
-  let totalHeight = 0;
+  // Compute total dimensions from nodes, edge points, and labels
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = 0;
+  let maxY = 0;
   for (const node of layoutNodes) {
+    const left = node.x - node.width / 2;
     const right = node.x + node.width / 2;
+    const top = node.y - node.height / 2;
     const bottom = node.y + node.height / 2;
-    if (right > totalWidth) totalWidth = right;
-    if (bottom > totalHeight) totalHeight = bottom;
+    if (left < minX) minX = left;
+    if (right > maxX) maxX = right;
+    if (top < minY) minY = top;
+    if (bottom > maxY) maxY = bottom;
   }
-  totalWidth += 40;
-  totalHeight += 40;
+  for (const edge of layoutEdges) {
+    for (const pt of edge.points) {
+      if (pt.x < minX) minX = pt.x;
+      if (pt.x > maxX) maxX = pt.x;
+      if (pt.y < minY) minY = pt.y;
+      if (pt.y > maxY) maxY = pt.y;
+    }
+    // Edge labels extend ~50px from midpoint
+    if (edge.label && edge.points.length > 0) {
+      const midPt = edge.points[Math.floor(edge.points.length / 2)];
+      const labelHalfW = (edge.label.length * 7 + 8) / 2;
+      if (midPt.x + labelHalfW > maxX) maxX = midPt.x + labelHalfW;
+      if (midPt.x - labelHalfW < minX) minX = midPt.x - labelHalfW;
+    }
+  }
+
+  // Padding for cardinality markers (~25px) + edge labels
+  const EDGE_MARGIN = 60;
+  const HALF_MARGIN = EDGE_MARGIN / 2;
+
+  // Shift all nodes and edges so content starts at HALF_MARGIN (breathing room on all sides)
+  const shiftX = -minX + HALF_MARGIN;
+  const shiftY = -minY + HALF_MARGIN;
+  for (const node of layoutNodes) {
+    node.x += shiftX;
+    node.y += shiftY;
+  }
+  for (const edge of layoutEdges) {
+    for (const pt of edge.points) {
+      pt.x += shiftX;
+      pt.y += shiftY;
+    }
+  }
+  maxX += shiftX;
+  maxY += shiftY;
+
+  const totalWidth = maxX + HALF_MARGIN;
+  const totalHeight = maxY + HALF_MARGIN;
 
   return {
     nodes: layoutNodes,

package/src/er/parser.ts

@@ -1,5 +1,6 @@
 import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes';
+import { makeDgmoError, formatDgmoError, suggest } from '../diagnostics';
 import type {
   ParsedERDiagram,
   ERTable,
@@ -155,6 +156,14 @@ export function parseERDiagram(
     options: {},
     tables: [],
     relationships: [],
+    diagnostics: [],
+  };
+
+  const fail = (line: number, message: string): ParsedERDiagram => {
+    const diag = makeDgmoError(line, message);
+    result.diagnostics.push(diag);
+    result.error = formatDgmoError(diag);
+    return result;
   };
 
   const tableMap = new Map<string, ERTable>();
@@ -200,8 +209,11 @@ export function parseERDiagram(
 
       if (key === 'chart') {
         if (value.toLowerCase() !== 'er') {
-          result.error = `Line ${lineNumber}: Expected chart type "er", got "${value}"`;
-          return result;
+          const allTypes = ['er', 'class', 'flowchart', 'sequence', 'org', 'bar', 'line', 'pie', 'scatter', 'sankey', 'venn', 'timeline', 'arc', 'slope'];
+          let msg = `Expected chart type "er", got "${value}"`;
+          const hint = suggest(value.toLowerCase(), allTypes);
+          if (hint) msg += `. ${hint}`;
+          return fail(lineNumber, msg);
         }
         continue;
       }
@@ -278,8 +290,23 @@ export function parseERDiagram(
 
   // Validation
   if (result.tables.length === 0 && !result.error) {
-    result.error =
-      'No tables found. Add table declarations like "users" or "orders (blue)".';
+    const diag = makeDgmoError(1, 'No tables found. Add table declarations like "users" or "orders (blue)".');
+    result.diagnostics.push(diag);
+    result.error = formatDgmoError(diag);
+  }
+
+  // Warn about isolated tables (not in any relationship)
+  if (result.tables.length >= 2 && result.relationships.length >= 1 && !result.error) {
+    const connectedIds = new Set<string>();
+    for (const rel of result.relationships) {
+      connectedIds.add(rel.source);
+      connectedIds.add(rel.target);
+    }
+    for (const table of result.tables) {
+      if (!connectedIds.has(table.id)) {
+        result.diagnostics.push(makeDgmoError(table.lineNumber, `Table "${table.name}" is not connected to any other table`, 'warning'));
+      }
+    }
   }
 
   return result;

package/src/er/renderer.ts

@@ -17,6 +17,7 @@ import { layoutERDiagram } from './layout';
 // ============================================================
 
 const DIAGRAM_PADDING = 20;
+const MAX_SCALE = 3;
 const TABLE_FONT_SIZE = 13;
 const COLUMN_FONT_SIZE = 11;
 const EDGE_LABEL_FONT_SIZE = 11;
@@ -227,7 +228,7 @@ export function renderERDiagram(
   const availH = height - titleHeight;
   const scaleX = (width - DIAGRAM_PADDING * 2) / diagramW;
   const scaleY = (availH - DIAGRAM_PADDING * 2) / diagramH;
-  const scale = Math.min(1, scaleX, scaleY);
+  const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   const scaledW = diagramW * scale;
   const scaledH = diagramH * scale;

package/src/er/types.ts

@@ -29,6 +29,8 @@ export interface ERRelationship {
   lineNumber: number;
 }
 
+import type { DgmoError } from '../diagnostics';
+
 export interface ParsedERDiagram {
   type: 'er';
   title?: string;
@@ -36,5 +38,6 @@ export interface ParsedERDiagram {
   options: Record<string, string>;
   tables: ERTable[];
   relationships: ERRelationship[];
+  diagnostics: DgmoError[];
   error?: string;
 }

package/src/graph/flowchart-parser.ts

@@ -1,5 +1,6 @@
 import { resolveColor } from '../colors';
 import type { PaletteColors } from '../palettes';
+import { makeDgmoError, formatDgmoError, suggest } from '../diagnostics';
 import type {
   ParsedGraph,
   GraphNode,
@@ -236,6 +237,15 @@ export function parseFlowchart(
     direction: 'TB',
     nodes: [],
     edges: [],
+    options: {},
+    diagnostics: [],
+  };
+
+  const fail = (line: number, message: string): ParsedGraph => {
+    const diag = makeDgmoError(line, message);
+    result.diagnostics.push(diag);
+    result.error = formatDgmoError(diag);
+    return result;
   };
 
   const nodeMap = new Map<string, GraphNode>();
@@ -428,8 +438,11 @@ export function parseFlowchart(
 
       if (key === 'chart') {
         if (value.toLowerCase() !== 'flowchart') {
-          result.error = `Line ${lineNumber}: Expected chart type "flowchart", got "${value}"`;
-          return result;
+          const allTypes = ['flowchart', 'sequence', 'class', 'er', 'org', 'bar', 'line', 'pie', 'scatter', 'sankey', 'venn', 'timeline', 'arc', 'slope'];
+          let msg = `Expected chart type "flowchart", got "${value}"`;
+          const hint = suggest(value.toLowerCase(), allTypes);
+          if (hint) msg += `. ${hint}`;
+          return fail(lineNumber, msg);
         }
         continue;
       }
@@ -448,7 +461,8 @@ export function parseFlowchart(
         continue;
       }
 
-      // Unknown metadata — skip
+      // Store other options (e.g., color: off)
+      result.options[key] = value;
       continue;
     }
 
@@ -460,7 +474,23 @@ export function parseFlowchart(
 
   // Validation: no nodes found
   if (result.nodes.length === 0 && !result.error) {
-    result.error = 'No nodes found. Add flowchart content with shape syntax like [Process] or (Start).';
+    const diag = makeDgmoError(1, 'No nodes found. Add flowchart content with shape syntax like [Process] or (Start).');
+    result.diagnostics.push(diag);
+    result.error = formatDgmoError(diag);
+  }
+
+  // Warn about orphaned nodes (not referenced in any edge)
+  if (result.nodes.length >= 2 && result.edges.length >= 1 && !result.error) {
+    const connectedIds = new Set<string>();
+    for (const edge of result.edges) {
+      connectedIds.add(edge.source);
+      connectedIds.add(edge.target);
+    }
+    for (const node of result.nodes) {
+      if (!connectedIds.has(node.id)) {
+        result.diagnostics.push(makeDgmoError(node.lineNumber, `Node "${node.label}" is not connected to any other node`, 'warning'));
+      }
+    }
   }
 
   return result;

package/src/graph/flowchart-renderer.ts

@@ -16,6 +16,7 @@ import { layoutGraph } from './layout';
 // ============================================================
 
 const DIAGRAM_PADDING = 20;
+const MAX_SCALE = 3;
 const NODE_FONT_SIZE = 13;
 const EDGE_LABEL_FONT_SIZE = 11;
 const GROUP_LABEL_FONT_SIZE = 11;
@@ -43,7 +44,8 @@ function mix(a: string, b: string, pct: number): string {
   return `#${c(ar,br)}${c(ag,bg)}${c(ab,bb)}`;
 }
 
-function shapeDefaultColor(shape: GraphShape, palette: PaletteColors, isEndTerminal?: boolean): string {
+function shapeDefaultColor(shape: GraphShape, palette: PaletteColors, isEndTerminal?: boolean, colorOff?: boolean): string {
+  if (colorOff) return palette.textMuted;
   switch (shape) {
     case 'terminal':   return isEndTerminal ? palette.colors.red : palette.colors.green;
     case 'process':    return palette.colors.blue;
@@ -54,13 +56,13 @@ function shapeDefaultColor(shape: GraphShape, palette: PaletteColors, isEndTermi
   }
 }
 
-function nodeFill(palette: PaletteColors, isDark: boolean, shape: GraphShape, nodeColor?: string, isEndTerminal?: boolean): string {
-  const color = nodeColor ?? shapeDefaultColor(shape, palette, isEndTerminal);
+function nodeFill(palette: PaletteColors, isDark: boolean, shape: GraphShape, nodeColor?: string, isEndTerminal?: boolean, colorOff?: boolean): string {
+  const color = nodeColor ?? shapeDefaultColor(shape, palette, isEndTerminal, colorOff);
   return mix(color, isDark ? palette.surface : palette.bg, 25);
 }
 
-function nodeStroke(palette: PaletteColors, shape: GraphShape, nodeColor?: string, isEndTerminal?: boolean): string {
-  return nodeColor ?? shapeDefaultColor(shape, palette, isEndTerminal);
+function nodeStroke(palette: PaletteColors, shape: GraphShape, nodeColor?: string, isEndTerminal?: boolean, colorOff?: boolean): string {
+  return nodeColor ?? shapeDefaultColor(shape, palette, isEndTerminal, colorOff);
 }
 
 // ============================================================
@@ -69,7 +71,7 @@ function nodeStroke(palette: PaletteColors, shape: GraphShape, nodeColor?: strin
 
 type GSelection = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
 
-function renderTerminal(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, isEnd: boolean): void {
+function renderTerminal(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, isEnd: boolean, colorOff?: boolean): void {
   const w = node.width;
   const h = node.height;
   const rx = h / 2;
@@ -80,12 +82,12 @@ function renderTerminal(g: GSelection, node: LayoutNode, palette: PaletteColors,
     .attr('height', h)
     .attr('rx', rx)
     .attr('ry', rx)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, isEnd))
-    .attr('stroke', nodeStroke(palette, node.shape, node.color, isEnd))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, isEnd, colorOff))
+    .attr('stroke', nodeStroke(palette, node.shape, node.color, isEnd, colorOff))
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderProcess(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean): void {
+function renderProcess(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, colorOff?: boolean): void {
   const w = node.width;
   const h = node.height;
   g.append('rect')
@@ -95,12 +97,12 @@ function renderProcess(g: GSelection, node: LayoutNode, palette: PaletteColors,
     .attr('height', h)
     .attr('rx', 3)
     .attr('ry', 3)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color))
-    .attr('stroke', nodeStroke(palette, node.shape, node.color))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, undefined, colorOff))
+    .attr('stroke', nodeStroke(palette, node.shape, node.color, undefined, colorOff))
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderDecision(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean): void {
+function renderDecision(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, colorOff?: boolean): void {
   const w = node.width / 2;
   const h = node.height / 2;
   const points = [
@@ -111,12 +113,12 @@ function renderDecision(g: GSelection, node: LayoutNode, palette: PaletteColors,
   ].join(' ');
   g.append('polygon')
     .attr('points', points)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color))
-    .attr('stroke', nodeStroke(palette, node.shape, node.color))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, undefined, colorOff))
+    .attr('stroke', nodeStroke(palette, node.shape, node.color, undefined, colorOff))
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderIO(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean): void {
+function renderIO(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, colorOff?: boolean): void {
   const w = node.width / 2;
   const h = node.height / 2;
   const sk = IO_SKEW;
@@ -128,15 +130,15 @@ function renderIO(g: GSelection, node: LayoutNode, palette: PaletteColors, isDar
   ].join(' ');
   g.append('polygon')
     .attr('points', points)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color))
-    .attr('stroke', nodeStroke(palette, node.shape, node.color))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, undefined, colorOff))
+    .attr('stroke', nodeStroke(palette, node.shape, node.color, undefined, colorOff))
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderSubroutine(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean): void {
+function renderSubroutine(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, colorOff?: boolean): void {
   const w = node.width;
   const h = node.height;
-  const s = nodeStroke(palette, node.shape, node.color);
+  const s = nodeStroke(palette, node.shape, node.color, undefined, colorOff);
   // Outer rectangle
   g.append('rect')
     .attr('x', -w / 2)
@@ -145,7 +147,7 @@ function renderSubroutine(g: GSelection, node: LayoutNode, palette: PaletteColor
     .attr('height', h)
     .attr('rx', 3)
     .attr('ry', 3)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, undefined, colorOff))
     .attr('stroke', s)
     .attr('stroke-width', NODE_STROKE_WIDTH);
   // Left inner border
@@ -166,7 +168,7 @@ function renderSubroutine(g: GSelection, node: LayoutNode, palette: PaletteColor
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderDocument(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean): void {
+function renderDocument(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, colorOff?: boolean): void {
   const w = node.width;
   const h = node.height;
   const waveH = DOC_WAVE_HEIGHT;
@@ -186,30 +188,30 @@ function renderDocument(g: GSelection, node: LayoutNode, palette: PaletteColors,
 
   g.append('path')
     .attr('d', d)
-    .attr('fill', nodeFill(palette, isDark, node.shape, node.color))
-    .attr('stroke', nodeStroke(palette, node.shape, node.color))
+    .attr('fill', nodeFill(palette, isDark, node.shape, node.color, undefined, colorOff))
+    .attr('stroke', nodeStroke(palette, node.shape, node.color, undefined, colorOff))
     .attr('stroke-width', NODE_STROKE_WIDTH);
 }
 
-function renderNodeShape(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, endTerminalIds: Set<string>): void {
+function renderNodeShape(g: GSelection, node: LayoutNode, palette: PaletteColors, isDark: boolean, endTerminalIds: Set<string>, colorOff?: boolean): void {
   switch (node.shape) {
     case 'terminal':
-      renderTerminal(g, node, palette, isDark, endTerminalIds.has(node.id));
+      renderTerminal(g, node, palette, isDark, endTerminalIds.has(node.id), colorOff);
       break;
     case 'process':
-      renderProcess(g, node, palette, isDark);
+      renderProcess(g, node, palette, isDark, colorOff);
       break;
     case 'decision':
-      renderDecision(g, node, palette, isDark);
+      renderDecision(g, node, palette, isDark, colorOff);
       break;
     case 'io':
-      renderIO(g, node, palette, isDark);
+      renderIO(g, node, palette, isDark, colorOff);
       break;
     case 'subroutine':
-      renderSubroutine(g, node, palette, isDark);
+      renderSubroutine(g, node, palette, isDark, colorOff);
       break;
     case 'document':
-      renderDocument(g, node, palette, isDark);
+      renderDocument(g, node, palette, isDark, colorOff);
       break;
   }
 }
@@ -251,7 +253,7 @@ export function renderFlowchart(
   const availH = height - titleHeight;
   const scaleX = (width - DIAGRAM_PADDING * 2) / diagramW;
   const scaleY = (availH - DIAGRAM_PADDING * 2) / diagramH;
-  const scale = Math.min(1, scaleX, scaleY);
+  const scale = Math.min(MAX_SCALE, scaleX, scaleY);
 
   // Center the diagram in the area below the title
   const scaledW = diagramW * scale;
@@ -443,6 +445,7 @@ export function renderFlowchart(
   }
 
   // Render nodes (top layer)
+  const colorOff = graph.options?.color === 'off';
   for (const node of layout.nodes) {
     const nodeG = contentG
       .append('g')
@@ -458,7 +461,7 @@ export function renderFlowchart(
     }
 
     // Shape
-    renderNodeShape(nodeG as GSelection, node, palette, isDark, endTerminalIds);
+    renderNodeShape(nodeG as GSelection, node, palette, isDark, endTerminalIds, colorOff);
 
     // Label
     nodeG

package/src/graph/types.ts

@@ -33,6 +33,8 @@ export interface GraphGroup {
   lineNumber: number;
 }
 
+import type { DgmoError } from '../diagnostics';
+
 export interface ParsedGraph {
   type: 'flowchart';
   title?: string;
@@ -41,5 +43,7 @@ export interface ParsedGraph {
   nodes: GraphNode[];
   edges: GraphEdge[];
   groups?: GraphGroup[];
+  options: Record<string, string>;
+  diagnostics: DgmoError[];
   error?: string;
 }

package/src/index.ts

@@ -1,3 +1,10 @@
+// ============================================================
+// Diagnostics
+// ============================================================
+
+export { makeDgmoError, formatDgmoError } from './diagnostics';
+export type { DgmoError, DgmoSeverity } from './diagnostics';
+
 // ============================================================
 // Unified API
 // ============================================================
@@ -11,6 +18,7 @@ export { render } from './render';
 export {
   parseDgmoChartType,
   getDgmoFramework,
+  parseDgmo,
   DGMO_CHART_TYPE_MAP,
 } from './dgmo-router';
 export type { DgmoFramework } from './dgmo-router';
@@ -136,9 +144,23 @@ export type {
 
 export { renderOrg, renderOrgForExport } from './org/renderer';
 
+export { parseKanban } from './kanban/parser';
+export type {
+  ParsedKanban,
+  KanbanColumn,
+  KanbanCard,
+  KanbanTagGroup,
+  KanbanTagEntry,
+} from './kanban/types';
+export { computeCardMove, computeCardArchive, isArchiveColumn } from './kanban/mutations';
+export { renderKanban, renderKanbanForExport } from './kanban/renderer';
+
 export { collapseOrgTree } from './org/collapse';
 export type { CollapsedOrgResult } from './org/collapse';
 
+export { resolveOrgImports } from './org/resolver';
+export type { ReadFileFn, ResolveImportsResult } from './org/resolver';
+
 export { layoutGraph } from './graph/layout';
 export type {
   LayoutResult,

package/src/kanban/mutations.ts

@@ -0,0 +1,183 @@
+import type { ParsedKanban, KanbanCard, KanbanColumn } from './types';
+
+const ARCHIVE_COLUMN_NAME = 'archive';
+
+// ============================================================
+// computeCardMove — pure function for source text mutation
+// ============================================================
+
+/**
+ * Compute new file content after moving a card to a different position.
+ *
+ * @param content     - original file content string
+ * @param parsed      - parsed kanban board
+ * @param cardId      - id of the card to move
+ * @param targetColumnId - id of the destination column
+ * @param targetIndex - position within target column (0 = first card)
+ * @returns new content string, or null if move is invalid
+ */
+export function computeCardMove(
+  content: string,
+  parsed: ParsedKanban,
+  cardId: string,
+  targetColumnId: string,
+  targetIndex: number
+): string | null {
+  // Find source card and column
+  let sourceCard: KanbanCard | null = null;
+  let sourceColumn: KanbanColumn | null = null;
+
+  for (const col of parsed.columns) {
+    for (const card of col.cards) {
+      if (card.id === cardId) {
+        sourceCard = card;
+        sourceColumn = col;
+        break;
+      }
+    }
+    if (sourceCard) break;
+  }
+
+  if (!sourceCard || !sourceColumn) return null;
+
+  const targetColumn = parsed.columns.find((c) => c.id === targetColumnId);
+  if (!targetColumn) return null;
+
+  const lines = content.split('\n');
+
+  // Extract the card's lines (0-based indices)
+  const startIdx = sourceCard.lineNumber - 1;
+  const endIdx = sourceCard.endLineNumber - 1;
+  const cardLines = lines.slice(startIdx, endIdx + 1);
+
+  // Remove the card lines from content
+  const withoutCard = [
+    ...lines.slice(0, startIdx),
+    ...lines.slice(endIdx + 1),
+  ];
+
+  // Compute insertion point (0-based index in withoutCard)
+  let insertIdx: number;
+
+  // Adjust target column and card line numbers after removal
+  // Lines after the removed range shift up by the number of removed lines
+  const removedCount = endIdx - startIdx + 1;
+  const adjustLine = (ln: number): number => {
+    // ln is 1-based
+    if (ln > endIdx + 1) return ln - removedCount;
+    return ln;
+  };
+
+  if (targetIndex === 0) {
+    // Insert right after column header line
+    const adjColLine = adjustLine(targetColumn.lineNumber);
+    insertIdx = adjColLine; // 0-based: insert after the column header line
+  } else {
+    // Insert after the preceding card's last line
+    // Get the cards in the target column, excluding the moved card
+    const targetCards = targetColumn.cards.filter((c) => c.id !== cardId);
+    const clampedIdx = Math.min(targetIndex, targetCards.length);
+    const precedingCard = targetCards[clampedIdx - 1];
+    if (!precedingCard) {
+      // Fallback: after column header
+      const adjColLine = adjustLine(targetColumn.lineNumber);
+      insertIdx = adjColLine;
+    } else {
+      const adjEndLine = adjustLine(precedingCard.endLineNumber);
+      insertIdx = adjEndLine; // 0-based: insert after this line
+    }
+  }
+
+  // Splice the card lines into the new position
+  const result = [
+    ...withoutCard.slice(0, insertIdx),
+    ...cardLines,
+    ...withoutCard.slice(insertIdx),
+  ];
+
+  return result.join('\n');
+}
+
+// ============================================================
+// computeCardArchive — move card to an Archive section
+// ============================================================
+
+/**
+ * Move a card to the Archive section at the end of the file.
+ * Creates `== Archive ==` if it doesn't exist.
+ *
+ * @returns new content string, or null if the card is not found
+ */
+export function computeCardArchive(
+  content: string,
+  parsed: ParsedKanban,
+  cardId: string
+): string | null {
+  let sourceCard: KanbanCard | null = null;
+  for (const col of parsed.columns) {
+    for (const card of col.cards) {
+      if (card.id === cardId) {
+        sourceCard = card;
+        break;
+      }
+    }
+    if (sourceCard) break;
+  }
+  if (!sourceCard) return null;
+
+  const lines = content.split('\n');
+
+  // Extract card lines
+  const startIdx = sourceCard.lineNumber - 1;
+  const endIdx = sourceCard.endLineNumber - 1;
+  const cardLines = lines.slice(startIdx, endIdx + 1);
+
+  // Remove card from its current position
+  const withoutCard = [
+    ...lines.slice(0, startIdx),
+    ...lines.slice(endIdx + 1),
+  ];
+
+  // Check if an Archive column already exists
+  const archiveCol = parsed.columns.find(
+    (c) => c.name.toLowerCase() === ARCHIVE_COLUMN_NAME
+  );
+
+  if (archiveCol) {
+    // Append to existing archive column
+    // Find the last line of the archive column (after removal adjustment)
+    const removedCount = endIdx - startIdx + 1;
+    let archiveEndLine = archiveCol.lineNumber;
+    if (archiveCol.cards.length > 0) {
+      const lastCard = archiveCol.cards[archiveCol.cards.length - 1];
+      archiveEndLine = lastCard.endLineNumber;
+    }
+    // Adjust for removed lines
+    if (archiveEndLine > endIdx + 1) {
+      archiveEndLine -= removedCount;
+    }
+    // Insert after the archive end (0-based in withoutCard)
+    const insertIdx = archiveEndLine; // archiveEndLine is 1-based, so this is after that line
+    return [
+      ...withoutCard.slice(0, insertIdx),
+      ...cardLines,
+      ...withoutCard.slice(insertIdx),
+    ].join('\n');
+  } else {
+    // Create archive section at end of file
+    // Ensure trailing newline before the new section
+    const trimmedEnd = withoutCard.length > 0 && withoutCard[withoutCard.length - 1].trim() === ''
+      ? withoutCard
+      : [...withoutCard, ''];
+    return [
+      ...trimmedEnd,
+      '== Archive ==',
+      ...cardLines,
+    ].join('\n');
+  }
+}
+
+/** Check if a column name is the archive column (case-insensitive). */
+export function isArchiveColumn(name: string): boolean {
+  return name.toLowerCase() === ARCHIVE_COLUMN_NAME;
+}