busy-cli 0.1.2

package/src/parsers/frontmatter.ts

@@ -0,0 +1,135 @@
+import matter from 'gray-matter';
+import { FrontMatter, FrontMatterSchema, ConceptBase } from '../types/schema.js';
+import { normalizeDocId, getBasename } from '../utils/slugify.js';
+import { debug, warn } from '../utils/logger.js';
+
+export interface ParsedFrontMatter {
+  frontmatter: FrontMatter;
+  content: string;
+  docId: string;
+  kind: ConceptBase['kind'];
+  types: string[];
+  extends: string[];
+}
+
+/**
+ * Parse front-matter from markdown content
+ */
+export function parseFrontMatter(
+  fileContent: string,
+  filePath: string
+): ParsedFrontMatter {
+  let data: any;
+  let content: string;
+
+  // Extract only the first frontmatter block to avoid "multiple documents" error
+  // when the body contains --- horizontal rules
+  const frontmatterMatch = fileContent.match(/^---\n([\s\S]*?)\n---/);
+  if (frontmatterMatch) {
+    try {
+      const parsed = matter(frontmatterMatch[0]);
+      data = parsed.data;
+      content = fileContent.slice(frontmatterMatch[0].length);
+    } catch (err) {
+      warn(`Failed to parse YAML frontmatter in ${filePath}: ${err}`, { file: filePath });
+      data = {};
+      content = fileContent;
+    }
+  } else {
+    // No frontmatter found
+    data = {};
+    content = fileContent;
+  }
+
+  debug.frontmatter('Parsing frontmatter for %s', filePath);
+
+  // Validate frontmatter
+  let frontmatter: FrontMatter;
+  try {
+    frontmatter = FrontMatterSchema.parse(data);
+  } catch (err) {
+    warn(`Invalid frontmatter schema in ${filePath}`, { file: filePath });
+    // Provide defaults if validation fails
+    frontmatter = {
+      Name: getBasename(filePath),
+      Type: [],
+      Description: undefined,
+      Tags: [],
+      Extends: [],
+    };
+  }
+
+  // Normalize docId from Name or filename
+  const docId = frontmatter.Name
+    ? normalizeDocId(frontmatter.Name)
+    : normalizeDocId(getBasename(filePath));
+
+  // Normalize types - strip markdown link brackets like [Document] -> Document
+  const types = (frontmatter.Type ?? []).map(stripMarkdownBrackets);
+
+  // Infer kind from types
+  const kind = inferKind(types);
+
+  // Normalize extends - also strip brackets
+  const extendsFromFm = (frontmatter.Extends ?? []).map(stripMarkdownBrackets);
+  const extendsFromTypes = inferExtendsFromTypes(types);
+  const extends_ = Array.from(new Set([...extendsFromFm, ...extendsFromTypes]));
+
+  // Normalize tags
+  const tags = (frontmatter.Tags ?? []).map(stripMarkdownBrackets);
+
+  debug.frontmatter(
+    'Parsed: docId=%s, kind=%s, types=%o, extends=%o',
+    docId,
+    kind,
+    types,
+    extends_
+  );
+
+  return {
+    frontmatter: {
+      ...frontmatter,
+      Type: types,
+      Extends: extends_,
+      Tags: tags,
+    },
+    content,
+    docId,
+    kind,
+    types,
+    extends: extends_,
+  };
+}
+
+/**
+ * Strip markdown link brackets from a string
+ * [Document] -> Document
+ * [[Document]] -> Document
+ */
+function stripMarkdownBrackets(str: string): string {
+  return str.replace(/^\[+|\]+$/g, '');
+}
+
+/**
+ * Infer kind from types array
+ */
+function inferKind(types: string[]): ConceptBase['kind'] {
+  const typesLower = types.map((t) => t.toLowerCase());
+
+  if (typesLower.includes('document')) return 'document';
+  if (typesLower.includes('operation')) return 'operation';
+  if (typesLower.includes('checklist')) return 'checklist';
+  if (typesLower.includes('tool')) return 'tool';
+  if (typesLower.includes('playbook')) return 'playbook';
+
+  return 'concept';
+}
+
+/**
+ * Infer extends from types
+ * All Type references should be included in extends
+ */
+function inferExtendsFromTypes(types: string[]): string[] {
+  // All types are also extends - they define what this concept is based on
+  return types;
+}

package/src/parsers/imports.ts

@@ -0,0 +1,196 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import { visit } from 'unist-util-visit';
+import type { Root, Definition } from 'mdast';
+import { ImportDef, DocId, Import } from '../types/schema.js';
+import { debug } from '../utils/logger.js';
+
+// =============================================================================
+// NEW PARSER FUNCTIONS - busy-python compatible
+// =============================================================================
+
+/**
+ * Parse reference-style imports from markdown content
+ * Matches busy-python format: [ConceptName]: path/to/file.md[#anchor]
+ *
+ * @returns Object with imports array and symbols table
+ */
+export function parseImports(
+  content: string
+): { imports: Import[]; symbols: Record<string, { docId?: string; slug?: string }> } {
+  const imports: Import[] = [];
+  const symbols: Record<string, { docId?: string; slug?: string }> = {};
+
+  // Regex pattern matching busy-python: r"\[([^\]]+)\]:\s*([^\s#]+)(?:#([^\s]+))?"
+  const importPattern = /^\[([^\]]+)\]:\s*([^\s#]+)(?:#([^\s]+))?$/gm;
+
+  let match;
+  while ((match = importPattern.exec(content)) !== null) {
+    const [, conceptName, path, anchor] = match;
+
+    const importDef: Import = {
+      conceptName,
+      path,
+      anchor: anchor || undefined,
+    };
+
+    imports.push(importDef);
+
+    // Add to symbol table for later resolution
+    symbols[conceptName] = {
+      docId: undefined,
+      slug: anchor || undefined,
+    };
+  }
+
+  return { imports, symbols };
+}
+
+/**
+ * Resolve an import path to docId and optional slug
+ * Used for import resolution against a file map
+ */
+export function resolveImportTarget(
+  target: string,
+  fileMap: Map<string, { docId: string; path: string }>
+): { docId?: string; slug?: string } {
+  // Parse target: "file.md", "./file.md", "../core/file.md", or "file.md#slug"
+  const hashIndex = target.indexOf('#');
+  let filePath = target;
+  let slug: string | undefined;
+
+  if (hashIndex !== -1) {
+    filePath = target.slice(0, hashIndex);
+    slug = target.slice(hashIndex + 1);
+  }
+
+  // Remove leading ./ if present
+  filePath = filePath.replace(/^\.\//, '');
+
+  // Try multiple resolution strategies:
+  // 1. Full path as provided
+  let fileInfo = fileMap.get(filePath);
+
+  // 2. Try just the basename
+  if (!fileInfo) {
+    const basename = filePath.split('/').pop() || filePath;
+    fileInfo = fileMap.get(basename);
+  }
+
+  // 3. Try without extension
+  if (!fileInfo) {
+    const basename = filePath.split('/').pop() || filePath;
+    const withoutExt = basename.replace(/\.busy\.md$/, '').replace(/\.md$/, '');
+    fileInfo = fileMap.get(withoutExt);
+  }
+
+  if (!fileInfo) {
+    return slug ? { slug } : {};
+  }
+
+  return {
+    docId: fileInfo.docId,
+    slug,
+  };
+}
+
+// =============================================================================
+// LEGACY FUNCTIONS - kept for backward compatibility
+// =============================================================================
+
+/**
+ * Extract reference-style imports from markdown content (LEGACY)
+ * Returns ImportDef objects for graph-based representation
+ */
+export function extractImports(
+  content: string,
+  docId: DocId
+): { imports: ImportDef[]; symbols: Record<string, { docId?: string; slug?: string }> } {
+  debug.imports('Extracting imports for %s', docId);
+
+  const processor = unified().use(remarkParse).use(remarkFrontmatter, ['yaml']);
+
+  const tree = processor.parse(content) as Root;
+
+  const imports: ImportDef[] = [];
+  const symbols: Record<string, { docId?: string; slug?: string }> = {};
+
+  // Visit definition nodes (reference-style links)
+  visit(tree, 'definition', (node: Definition) => {
+    const label = node.label ?? node.identifier;
+    const target = node.url;
+
+    debug.imports('Found import: [%s]: %s', label, target);
+
+    const importDef: ImportDef = {
+      kind: 'importdef',
+      id: `${docId}::import::${label}`,
+      docId,
+      slug: label.toLowerCase(),
+      name: label,
+      content: '', // Imports don't have content
+      types: [],
+      extends: [],
+      sectionRef: '', // Imports don't belong to a section
+      label,
+      target,
+      resolved: undefined, // Will be resolved later
+    };
+
+    imports.push(importDef);
+
+    // Add to symbol table (will be fully resolved later)
+    symbols[label] = {
+      docId: undefined,
+      slug: undefined,
+    };
+  });
+
+  debug.imports('Found %d imports', imports.length);
+
+  return { imports, symbols };
+}
+
+/**
+ * Resolve an import target to {docId, slug} (LEGACY)
+ * This version requires currentDocId parameter for backward compatibility
+ */
+export function legacyResolveImportTarget(
+  target: string,
+  currentDocId: DocId,
+  fileMap: Map<string, { docId: string; path: string }>
+): { docId?: string; slug?: string } {
+  // Parse target: "./file.md", "../core/file.md", or "./file.md#slug"
+  const match = target.match(/^\.{1,2}\/(.+?)(#(.+))?$/);
+
+  if (!match) {
+    debug.imports('Invalid import target: %s', target);
+    return {};
+  }
+
+  const [, filePath, , slug] = match;
+
+  // Try multiple resolution strategies:
+  // 1. Full relative path
+  // 2. Just the basename
+  // 3. Basename with different extensions
+
+  let fileInfo = fileMap.get(filePath);
+
+  if (!fileInfo) {
+    // Try just the basename
+    const basename = filePath.split('/').pop() || filePath;
+    fileInfo = fileMap.get(basename);
+  }
+
+  if (!fileInfo) {
+    debug.imports('File not found in map: %s', filePath);
+    return { slug };
+  }
+
+  return {
+    docId: fileInfo.docId,
+    slug,
+  };
+}

package/src/parsers/links.ts

@@ -0,0 +1,108 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import { visit } from 'unist-util-visit';
+import type { Root, Link, LinkReference } from 'mdast';
+import { Section, Edge, EdgeRole } from '../types/schema.js';
+import { debug } from '../utils/logger.js';
+
+
+/**
+ * Extract links from a section and create edges
+ */
+export function extractLinksFromSection(
+  section: Section,
+  content: string,
+  symbols: Record<string, { docId?: string; slug?: string }>,
+  fileMap: Map<string, { docId: string; path: string }>
+): Edge[] {
+  debug.links('Extracting links from section %s', section.id);
+
+  const processor = unified().use(remarkParse).use(remarkFrontmatter, ['yaml']);
+
+  const tree = processor.parse(content) as Root;
+
+  const edges: Edge[] = [];
+
+  // Visit link nodes
+  visit(tree, 'link', (node: Link) => {
+    const href = node.url;
+
+    const resolved = resolveLink(href, section.docId, fileMap);
+
+    if (resolved) {
+      // Temporarily mark as 'ref', will be reclassified in loader
+      edges.push({
+        from: section.id,
+        to: resolved,
+        role: 'ref',
+      });
+    }
+  });
+
+  // Visit link reference nodes
+  visit(tree, 'linkReference', (node: LinkReference) => {
+    const label = node.label ?? node.identifier;
+
+    // Resolve via symbol table
+    const symbol = symbols[label];
+    if (symbol) {
+      let resolved: string | undefined;
+
+      if (symbol.docId && symbol.slug) {
+        resolved = `${symbol.docId}#${symbol.slug}`;
+      } else if (symbol.docId) {
+        resolved = symbol.docId;
+      }
+
+      if (resolved) {
+        // Temporarily mark as 'ref', will be reclassified in loader
+        edges.push({
+          from: section.id,
+          to: resolved,
+          role: 'ref',
+        });
+      }
+    }
+  });
+
+  debug.links('Found %d edges from section', edges.length);
+
+  return edges;
+}
+
+/**
+ * Resolve a link href to a node ID
+ */
+function resolveLink(
+  href: string,
+  currentDocId: string,
+  fileMap: Map<string, { docId: string; path: string }>
+): string | undefined {
+  // Handle internal anchors: #slug
+  if (href.startsWith('#')) {
+    const slug = href.slice(1);
+    return `${currentDocId}#${slug}`;
+  }
+
+  // Handle relative file links: ./file.md or ./file.md#slug
+  const match = href.match(/^\.\/(.+?)(#(.+))?$/);
+  if (match) {
+    const [, filePath, , slug] = match;
+
+    const fileInfo = fileMap.get(filePath);
+    if (!fileInfo) {
+      debug.links('File not found: %s', filePath);
+      return undefined;
+    }
+
+    if (slug) {
+      return `${fileInfo.docId}#${slug}`;
+    }
+
+    return fileInfo.docId;
+  }
+
+  // External link - return as-is or skip
+  return href.startsWith('http') ? href : undefined;
+}

package/src/parsers/localdefs.ts

@@ -0,0 +1,166 @@
+import { Section, LocalDef, DocId } from '../types/schema.js';
+import { createSlug } from '../utils/slugify.js';
+import { findSection, getAllSections, getSectionExtends } from './sections.js';
+import { debug } from '../utils/logger.js';
+
+const LOCAL_DEFS_ALIASES = [
+  'local definitions',
+  'definitions',
+  'glossary',
+  'local-definitions-section',
+];
+
+/**
+ * Extract Local Definitions from sections
+ */
+export function extractLocalDefs(
+  sections: Section[],
+  docId: DocId,
+  filePath: string
+): LocalDef[] {
+  debug.localdefs('Extracting local definitions for %s', docId);
+
+  // Find the Local Definitions section
+  const localDefsSection = findLocalDefinitionsSection(sections);
+
+  if (!localDefsSection) {
+    debug.localdefs('No Local Definitions section found');
+    return [];
+  }
+
+  debug.localdefs(
+    'Found Local Definitions section: %s',
+    localDefsSection.title
+  );
+
+  // Extract all subheadings as LocalDefs
+  const localdefs: LocalDef[] = [];
+
+  for (const child of getAllSections(localDefsSection.children)) {
+    const localdef = createLocalDef(child, docId, filePath);
+    localdefs.push(localdef);
+  }
+
+  debug.localdefs('Extracted %d local definitions', localdefs.length);
+
+  return localdefs;
+}
+
+/**
+ * Find the Local Definitions section (case-insensitive)
+ */
+function findLocalDefinitionsSection(sections: Section[]): Section | undefined {
+  for (const alias of LOCAL_DEFS_ALIASES) {
+    const section = findSection(sections, alias);
+    if (section) {
+      return section;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Create a LocalDef from a section
+ */
+function createLocalDef(
+  section: Section,
+  docId: DocId,
+  filePath: string
+): LocalDef {
+  const slug = section.slug;
+  const id = `${docId}::${slug}`;
+
+  // Parse extends from content
+  const { extends: extendsFromContent } = parseLocalDefAttrs(section.content);
+
+  // Get extends from section heading (e.g., ## [MyDef][Type])
+  const extendsFromHeading = getSectionExtends(section.id);
+
+  // Combine both sources of extends
+  const extends_ = Array.from(new Set([...extendsFromContent, ...extendsFromHeading]));
+
+  return {
+    kind: 'localdef',
+    id,
+    docId,
+    slug,
+    name: section.title,
+    content: section.content,
+    types: [],
+    extends: extends_,
+    sectionRef: section.id,
+  };
+}
+
+/**
+ * Parse attributes from local def content
+ * Looks for:
+ * 1. Fenced blocks with "yaml busy" or "json busy"
+ * 2. Inline patterns like "Extends: [...]" or "_Extends:_"
+ */
+function parseLocalDefAttrs(content: string): {
+  attrs: Record<string, unknown>;
+  extends: string[];
+} {
+  const attrs: Record<string, unknown> = {};
+  let extends_: string[] = [];
+
+  // Check for fenced blocks first
+  const yamlBusyMatch = content.match(/```(?:yaml|json)\s+busy\s*\n([\s\S]*?)```/);
+  if (yamlBusyMatch) {
+    try {
+      // Simple parsing - just look for key: value pairs
+      const block = yamlBusyMatch[1];
+      const lines = block.split('\n');
+
+      for (const line of lines) {
+        const match = line.match(/^\s*(\w+):\s*(.+)$/);
+        if (match) {
+          const [, key, value] = match;
+          // Try to parse as JSON
+          try {
+            attrs[key] = JSON.parse(value);
+          } catch {
+            attrs[key] = value.trim();
+          }
+        }
+      }
+
+      if (attrs.Extends) {
+        extends_ = Array.isArray(attrs.Extends)
+          ? attrs.Extends
+          : [attrs.Extends];
+      }
+    } catch (err) {
+      debug.localdefs('Failed to parse fenced block: %s', err);
+    }
+  }
+
+  // Look for inline Extends patterns
+  const extendsPatterns = [
+    /^Extends:\s*\[(.*?)\]/im,
+    /^_Extends:_\s*\[(.*?)\]/im,
+    /^Extends:\s*(.+)$/im,
+  ];
+
+  for (const pattern of extendsPatterns) {
+    const match = content.match(pattern);
+    if (match) {
+      const value = match[1].trim();
+      // Parse as comma-separated list or JSON array
+      try {
+        const parsed = JSON.parse(`[${value}]`);
+        extends_ = [...extends_, ...parsed];
+      } catch {
+        // Try comma-separated
+        extends_ = [
+          ...extends_,
+          ...value.split(',').map((s) => s.trim().replace(/['"]/g, '')),
+        ];
+      }
+      break;
+    }
+  }
+
+  return { attrs, extends: Array.from(new Set(extends_)) };
+}