anchormd 0.1.0

package/src/entities.ts

@@ -0,0 +1,125 @@
+/**
+ * Entity extraction from plan content
+ *
+ * Extracts references to:
+ * - File paths (strings with / and common extensions)
+ * - Models (PascalCase words near model/schema/table/entity keywords)
+ * - Routes (HTTP method + path patterns)
+ * - Scripts (shell script filenames and npm run commands)
+ */
+
+import type { Entity } from './types.js';
+
+/**
+ * Extract file path references from content.
+ * Matches paths containing `/` with common source file extensions.
+ */
+function extractFilePaths(content: string): Entity[] {
+  const regex = /(?:^|\s|['"`(])([a-zA-Z0-9._\-/]+\.(?:ts|js|tsx|jsx|py|go|rs|sql|json|yaml|yml|md|css|html|sh|toml|env))\b/gm;
+  const entities: Entity[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    const value = match[1];
+    // Only include paths that contain a slash (to avoid bare filenames matching too broadly)
+    // Exception: script files like deploy.sh are handled by extractScripts
+    if (value.includes('/')) {
+      entities.push({ type: 'file', value });
+    }
+  }
+
+  return entities;
+}
+
+/**
+ * Extract model/schema references from content.
+ * Matches PascalCase words near model/schema/table/entity keywords.
+ */
+function extractModels(content: string): Entity[] {
+  const entities: Entity[] = [];
+
+  // Pattern: keyword followed by PascalCase name
+  const forwardRegex = /(?:model|schema|table|entity|Model|Schema)\s+([A-Z][a-zA-Z0-9]+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = forwardRegex.exec(content)) !== null) {
+    entities.push({ type: 'model', value: match[1] });
+  }
+
+  // Pattern: PascalCase name followed by keyword
+  const reverseRegex = /([A-Z][a-zA-Z0-9]+)\s+(?:model|schema|table|entity)/g;
+
+  while ((match = reverseRegex.exec(content)) !== null) {
+    entities.push({ type: 'model', value: match[1] });
+  }
+
+  return entities;
+}
+
+/**
+ * Extract HTTP route references from content.
+ * Matches HTTP methods followed by URL paths.
+ */
+function extractRoutes(content: string): Entity[] {
+  const regex = /\b(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/[a-zA-Z0-9/:._\-{}*]+)/g;
+  const entities: Entity[] = [];
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    entities.push({ type: 'route', value: `${match[1]} ${match[2]}` });
+  }
+
+  return entities;
+}
+
+/**
+ * Extract script references from content.
+ * Matches shell script filenames and npm run commands.
+ */
+function extractScripts(content: string): Entity[] {
+  const entities: Entity[] = [];
+
+  // Shell script filenames
+  const scriptRegex = /(?:^|\s|['"`(])([a-zA-Z0-9_\-]+\.(?:sh|bash|zsh))\b/gm;
+  let match: RegExpExecArray | null;
+
+  while ((match = scriptRegex.exec(content)) !== null) {
+    entities.push({ type: 'script', value: match[1] });
+  }
+
+  // npm run commands
+  const npmRegex = /npm\s+run\s+([a-zA-Z0-9_\-:]+)/g;
+
+  while ((match = npmRegex.exec(content)) !== null) {
+    entities.push({ type: 'script', value: `npm run ${match[1]}` });
+  }
+
+  return entities;
+}
+
+/**
+ * Extract all entities from plan content.
+ * Combines results from all extractors and deduplicates by type+value.
+ */
+export function extractEntities(content: string): Entity[] {
+  const all = [
+    ...extractFilePaths(content),
+    ...extractModels(content),
+    ...extractRoutes(content),
+    ...extractScripts(content),
+  ];
+
+  // Deduplicate by type+value
+  const seen = new Set<string>();
+  const unique: Entity[] = [];
+
+  for (const entity of all) {
+    const key = `${entity.type}:${entity.value}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      unique.push(entity);
+    }
+  }
+
+  return unique;
+}

package/src/format.ts

@@ -0,0 +1,134 @@
+/**
+ * Output formatting with ANSI colors
+ *
+ * Respects NO_COLOR environment variable (https://no-color.org/)
+ */
+
+import type { PlanFile, PlanStatus, SearchResult } from './types.js';
+
+const noColor = 'NO_COLOR' in process.env;
+
+function wrap(code: string, s: string): string {
+  return noColor ? s : `\x1b[${code}m${s}\x1b[0m`;
+}
+
+/** ANSI color helpers */
+export const color = {
+  bold: (s: string) => wrap('1', s),
+  dim: (s: string) => wrap('2', s),
+  green: (s: string) => wrap('32', s),
+  yellow: (s: string) => wrap('33', s),
+  cyan: (s: string) => wrap('36', s),
+  red: (s: string) => wrap('31', s),
+  blue: (s: string) => wrap('34', s),
+};
+
+/** Color a status string based on its value */
+function colorStatus(status: PlanStatus): string {
+  switch (status) {
+    case 'built':
+      return color.green(status);
+    case 'in-progress':
+      return color.yellow(status);
+    case 'planned':
+      return color.cyan(status);
+    case 'deprecated':
+      return color.red(status);
+    default:
+      return status;
+  }
+}
+
+/** Strip ANSI codes for length calculation */
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+/**
+ * Format a single plan as a table row
+ */
+export function formatPlanRow(plan: PlanFile): string {
+  const status = colorStatus(plan.frontmatter.status);
+  return `  ${color.bold(plan.frontmatter.name)}  ${status}  ${color.dim(plan.frontmatter.description)}`;
+}
+
+/**
+ * Format a list of plans as a columnar table
+ */
+export function formatPlanTable(plans: PlanFile[]): string {
+  if (plans.length === 0) {
+    return color.dim('  No plans found.');
+  }
+
+  // Calculate column widths
+  const nameWidth = Math.max(...plans.map(p => p.frontmatter.name.length), 4);
+  const statusWidth = Math.max(...plans.map(p => p.frontmatter.status.length), 6);
+
+  const lines: string[] = [];
+
+  // Header
+  const header = `  ${'NAME'.padEnd(nameWidth)}  ${'STATUS'.padEnd(statusWidth)}  DESCRIPTION`;
+  lines.push(color.dim(header));
+  lines.push(color.dim('  ' + '-'.repeat(nameWidth + statusWidth + 20)));
+
+  // Rows
+  for (const plan of plans) {
+    const name = color.bold(plan.frontmatter.name.padEnd(nameWidth));
+    const status = colorStatus(plan.frontmatter.status);
+    // Pad status accounting for ANSI codes
+    const statusPad = ' '.repeat(Math.max(0, statusWidth - plan.frontmatter.status.length));
+    const desc = color.dim(plan.frontmatter.description);
+    lines.push(`  ${name}  ${status}${statusPad}  ${desc}`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format search results as a numbered list
+ */
+export function formatSearchResults(results: SearchResult[]): string {
+  if (results.length === 0) {
+    return color.dim('  No results found.');
+  }
+
+  const lines: string[] = [];
+
+  for (let i = 0; i < results.length; i++) {
+    const r = results[i];
+    const num = color.dim(`${i + 1}.`);
+    const score = color.yellow(`[${r.score.toFixed(3)}]`);
+    const path = color.bold(r.path);
+    lines.push(`  ${num} ${score} ${path}`);
+
+    if (r.content) {
+      // Show a truncated preview of the content
+      const preview = r.content.substring(0, 120).replace(/\n/g, ' ').trim();
+      lines.push(`     ${color.dim(preview)}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Format project status information
+ */
+export function formatStatus(stats: {
+  planCount: number;
+  linkCount: number;
+  weakEdgeCount: number;
+  qmdEnabled: boolean;
+}): string {
+  const lines = [
+    color.bold('AnchorMD Status'),
+    '',
+    `  Plans:       ${color.cyan(String(stats.planCount))}`,
+    `  Links:       ${color.cyan(String(stats.linkCount))}`,
+    `  Weak edges:  ${color.cyan(String(stats.weakEdgeCount))}`,
+    `  QMD search:  ${stats.qmdEnabled ? color.green('enabled') : color.yellow('disabled')}`,
+    '',
+  ];
+
+  return lines.join('\n');
+}

package/src/index-graph.ts

@@ -0,0 +1,123 @@
+/**
+ * Index graph builder and I/O
+ *
+ * Builds a graph of plan relationships from:
+ * - Strong links: explicit [[plan]] references
+ * - Weak edges: shared entities between plans (same file, model, route, or script)
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { listPlans } from './plan.js';
+import { parseLinks, getStrongLinks } from './links.js';
+import { extractEntities } from './entities.js';
+import { getPlansDir, getAnchorDir } from './config.js';
+import type { IndexGraph, IndexGraphNode, Entity } from './types.js';
+
+/**
+ * Build the index graph from all plans in the plans directory.
+ *
+ * For each plan:
+ * 1. Extract strong links (explicit [[references]])
+ * 2. Extract entities (file paths, models, routes, scripts)
+ * 3. Compute weak edges (plans sharing the same entity)
+ */
+export function buildIndex(plansDir: string): IndexGraph {
+  const plans = listPlans(plansDir);
+
+  // Map of entityKey -> list of plan names that reference it
+  const entityToPlanMap = new Map<string, string[]>();
+
+  // Build initial nodes and populate the entity map
+  const nodes: Record<string, IndexGraphNode> = {};
+
+  for (const plan of plans) {
+    const name = plan.frontmatter.name;
+    const fullContent = plan.body;
+
+    // Extract strong links (target names)
+    const links = parseLinks(fullContent);
+    const strongLinks = getStrongLinks(links).map(l => l.target);
+
+    // Extract entities
+    const entities = extractEntities(fullContent);
+
+    // Register entities in the map
+    for (const entity of entities) {
+      const key = `${entity.type}:${entity.value}`;
+      const existing = entityToPlanMap.get(key) || [];
+      if (!existing.includes(name)) {
+        existing.push(name);
+        entityToPlanMap.set(key, existing);
+      }
+    }
+
+    nodes[name] = {
+      name,
+      links: strongLinks,
+      entities,
+      weakEdges: [], // Filled in below
+    };
+  }
+
+  // Compute weak edges from shared entities
+  for (const planNames of entityToPlanMap.values()) {
+    if (planNames.length < 2) continue;
+
+    // All plans sharing this entity get weak edges to each other
+    for (const planA of planNames) {
+      for (const planB of planNames) {
+        if (planA === planB) continue;
+        const node = nodes[planA];
+        if (node && !node.weakEdges.includes(planB)) {
+          node.weakEdges.push(planB);
+        }
+      }
+    }
+  }
+
+  return {
+    nodes,
+    lastBuilt: new Date().toISOString(),
+  };
+}
+
+/**
+ * Write the index graph to .anchor/index.json
+ */
+export function writeIndex(anchorDir: string, graph: IndexGraph): void {
+  mkdirSync(anchorDir, { recursive: true });
+  const indexPath = path.join(anchorDir, 'index.json');
+  writeFileSync(indexPath, JSON.stringify(graph, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * Read the index graph from .anchor/index.json
+ * Returns null if the file doesn't exist.
+ */
+export function readIndex(anchorDir: string): IndexGraph | null {
+  const indexPath = path.join(anchorDir, 'index.json');
+
+  if (!existsSync(indexPath)) {
+    return null;
+  }
+
+  try {
+    const raw = readFileSync(indexPath, 'utf-8');
+    return JSON.parse(raw) as IndexGraph;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Rebuild the index and write it to disk.
+ * Returns the built graph.
+ */
+export function rebuildAndWriteIndex(projectRoot: string): IndexGraph {
+  const plansDir = getPlansDir(projectRoot);
+  const anchorDir = getAnchorDir(projectRoot);
+  const graph = buildIndex(plansDir);
+  writeIndex(anchorDir, graph);
+  return graph;
+}

package/src/links.ts

@@ -0,0 +1,71 @@
+/**
+ * Link parser for [[wiki-style]] links in plan content
+ *
+ * Supports:
+ * - Strong links: [[target]]
+ * - Deep links: [[target#section]]
+ * - Multi-hash deep links: [[target#section#subsection]]
+ */
+
+import type { Link, StrongLink, DeepLink } from './types.js';
+
+const LINK_REGEX = /\[\[([^\]]+)\]\]/g;
+
+/**
+ * Type guard: returns true if the link has a section (is a DeepLink)
+ */
+export function isDeepLink(link: Link): link is DeepLink {
+  return 'section' in link;
+}
+
+/**
+ * Parse all [[wiki-style]] links from content.
+ * Returns deduplicated array of StrongLink and DeepLink objects.
+ */
+export function parseLinks(content: string): Link[] {
+  const seen = new Set<string>();
+  const links: Link[] = [];
+
+  let match: RegExpExecArray | null;
+  // Reset regex state
+  LINK_REGEX.lastIndex = 0;
+
+  while ((match = LINK_REGEX.exec(content)) !== null) {
+    const raw = match[1];
+    const hashIndex = raw.indexOf('#');
+
+    let link: Link;
+    let key: string;
+
+    if (hashIndex !== -1) {
+      const target = raw.substring(0, hashIndex);
+      const section = raw.substring(hashIndex + 1);
+      link = { target, section };
+      key = `${target}#${section}`;
+    } else {
+      link = { target: raw };
+      key = raw;
+    }
+
+    if (!seen.has(key)) {
+      seen.add(key);
+      links.push(link);
+    }
+  }
+
+  return links;
+}
+
+/**
+ * Filter links to only strong links (no section)
+ */
+export function getStrongLinks(links: Link[]): StrongLink[] {
+  return links.filter((link): link is StrongLink => !isDeepLink(link));
+}
+
+/**
+ * Filter links to only deep links (with section)
+ */
+export function getDeepLinks(links: Link[]): DeepLink[] {
+  return links.filter(isDeepLink);
+}

package/src/plan.ts

@@ -0,0 +1,142 @@
+/**
+ * Plan file parsing and I/O
+ *
+ * Plans are markdown files with YAML frontmatter:
+ * ---
+ * name: plan-name
+ * description: What this plan covers
+ * status: planned
+ * tags: [optional, tags]
+ * ---
+ * # Body content here
+ */
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { parse as yamlParse, stringify as yamlStringify } from 'yaml';
+import type { PlanFrontmatter, PlanFile, PlanStatus } from './types.js';
+import { VALID_STATUSES } from './types.js';
+
+/**
+ * Parse frontmatter and body from raw plan content.
+ * Expects content starting with `---` delimiter.
+ */
+export function parseFrontmatter(raw: string): { frontmatter: PlanFrontmatter; body: string } {
+  const trimmed = raw.trim();
+
+  if (!trimmed.startsWith('---')) {
+    throw new Error('Plan file must start with --- frontmatter delimiter');
+  }
+
+  // Find the closing --- delimiter
+  const secondDelimiter = trimmed.indexOf('---', 3);
+  if (secondDelimiter === -1) {
+    throw new Error('Plan file missing closing --- frontmatter delimiter');
+  }
+
+  const yamlContent = trimmed.substring(3, secondDelimiter).trim();
+  const body = trimmed.substring(secondDelimiter + 3).replace(/^\n/, '');
+
+  const parsed = yamlParse(yamlContent);
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('Invalid frontmatter YAML');
+  }
+
+  if (!parsed.name || typeof parsed.name !== 'string') {
+    throw new Error('Frontmatter missing required field: name');
+  }
+
+  if (!parsed.description || typeof parsed.description !== 'string') {
+    throw new Error('Frontmatter missing required field: description');
+  }
+
+  if (!parsed.status || typeof parsed.status !== 'string') {
+    throw new Error('Frontmatter missing required field: status');
+  }
+
+  if (!VALID_STATUSES.includes(parsed.status as PlanStatus)) {
+    throw new Error(
+      `Invalid status "${parsed.status}". Must be one of: ${VALID_STATUSES.join(', ')}`
+    );
+  }
+
+  const frontmatter: PlanFrontmatter = {
+    name: parsed.name,
+    description: parsed.description,
+    status: parsed.status as PlanStatus,
+  };
+
+  if (parsed.tags && Array.isArray(parsed.tags)) {
+    frontmatter.tags = parsed.tags;
+  }
+
+  return { frontmatter, body };
+}
+
+/**
+ * Serialize a plan to its string representation (frontmatter + body)
+ */
+export function serializePlan(frontmatter: PlanFrontmatter, body: string): string {
+  const yamlStr = yamlStringify(frontmatter);
+  return `---\n${yamlStr}---\n${body}`;
+}
+
+/**
+ * Read and parse a single plan file by name (without .md extension)
+ */
+export function readPlan(plansDir: string, name: string): PlanFile {
+  const filePath = path.join(plansDir, name + '.md');
+
+  if (!existsSync(filePath)) {
+    throw new Error(`Plan not found: ${name} (looked for ${filePath})`);
+  }
+
+  const raw = readFileSync(filePath, 'utf-8');
+  const { frontmatter, body } = parseFrontmatter(raw);
+
+  return {
+    frontmatter,
+    body,
+    filename: name + '.md',
+  };
+}
+
+/**
+ * Write plan content to a file in the plans directory
+ */
+export function writePlan(plansDir: string, name: string, content: string): void {
+  mkdirSync(plansDir, { recursive: true });
+  const filePath = path.join(plansDir, name + '.md');
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+/**
+ * List and parse all plan files in the plans directory
+ */
+export function listPlans(plansDir: string): PlanFile[] {
+  if (!existsSync(plansDir)) {
+    return [];
+  }
+
+  const files = readdirSync(plansDir).filter(f => f.endsWith('.md')).sort();
+  const plans: PlanFile[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(plansDir, file);
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const { frontmatter, body } = parseFrontmatter(raw);
+      plans.push({
+        frontmatter,
+        body,
+        filename: file,
+      });
+    } catch {
+      // Skip files that fail to parse (e.g., malformed frontmatter)
+      continue;
+    }
+  }
+
+  return plans;
+}