busy-cli 0.1.2

package/README.md

@@ -0,0 +1,129 @@
+# @busy/parser
+
+TypeScript library + CLI that parses Busy markdown workspaces into a typed graph.
+
+## Features
+
+- ✅ Parse Busy markdown files with YAML frontmatter
+- ✅ Build hierarchical section trees
+- ✅ Extract Local Definitions with inheritance
+- ✅ Resolve reference-style imports
+- ✅ Create typed edge graph (ref, calls, extends, imports)
+- ✅ Build minimal execution contexts for operations
+- ✅ Export to JSON and DOT graph formats
+
+## Installation
+
+```bash
+npm install @busy/parser
+```
+
+## CLI Usage
+
+### Load and validate workspace
+
+```bash
+busyctx load "busy-v2/**/*.busy.md" --dump repo.json
+```
+
+### Build operation context
+
+```bash
+busyctx context "Document#evaluatedocument" -o context.json --maxDefChars 2000
+```
+
+### Export graph
+
+```bash
+busyctx graph --format dot > repo.dot
+```
+
+## API Usage
+
+```typescript
+import { loadRepo, buildContext } from '@busy/parser';
+
+// Load workspace
+const repo = await loadRepo(['busy-v2/**/*.busy.md']);
+
+console.log(`Loaded ${repo.docs.length} documents`);
+console.log(`Found ${Object.keys(repo.localdefs).length} local definitions`);
+console.log(`Created ${repo.edges.length} edges`);
+
+// Build execution context for an operation
+const context = buildContext(repo, 'Document#evaluatedocument', {
+  maxDefChars: 2000,
+  includeChildren: true
+});
+
+console.log(`Operation: ${context.operation.title}`);
+console.log(`Definitions: ${context.defs.length}`);
+console.log(`Calls: ${context.calls.length}`);
+```
+
+## Data Model
+
+### Documents & Sections
+
+- **BusyDocument**: Top-level markdown file with frontmatter
+- **Section**: Hierarchical heading structure (`#` - `######`)
+- **LocalDef**: Definitions under "Local Definitions" section
+
+### Edges
+
+- **imports**: Document imports another document
+- **calls**: Section/operation calls another operation
+- **extends**: LocalDef extends another definition
+- **ref**: General reference link
+
+### Context Payload
+
+Minimal execution context for an operation:
+- Operation section (ref, title, content)
+- Required local definitions (with transitive closure)
+- Callable sub-operations
+- Symbol table for imports
+
+## Frontmatter Support
+
+Handles both plain strings and markdown link syntax:
+
+```yaml
+---
+Name: Document
+Type: [Concept]
+Description: The core document type
+Tags: [core, foundation]
+Extends: [ConceptBase]
+---
+```
+
+Automatically strips brackets: `[Concept]` → `Concept`
+
+## File Extensions
+
+Supports both `.md` and `.busy.md` extensions. Import references to `.md` files automatically resolve to `.busy.md` files.
+
+## Example Output
+
+For `busy-v2/**/*.busy.md`:
+- ✓ 15 documents loaded
+- ✓ 45 local definitions
+- ✓ 137 imports resolved
+- ✓ 173 edges created
+  - 137 import edges
+  - 26 call edges
+  - 10 ref edges
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run dev  # watch mode
+npm test
+```
+
+## License
+
+ISC

package/dist/builders/context.d.ts

@@ -0,0 +1,50 @@
+import { Repo, ContextPayload, Section, LocalDef, Operation, ConceptBase } from '../types/schema.js';
+export interface BuildOpts {
+    includeChildren?: boolean;
+    maxDefChars?: number;
+}
+/**
+ * Build minimal execution context for an operation
+ */
+export declare function buildContext(repo: Repo, opRef: string, opts?: BuildOpts): ContextPayload;
+/**
+ * Lookup helpers
+ */
+export declare function get(repo: Repo, ref: string): Section | LocalDef | Operation | ConceptBase | undefined;
+export declare function parentsOf(repo: Repo, nameOrRef: string): string[];
+export declare function childrenOf(repo: Repo, nameOrRef: string): string[];
+/**
+ * Context for a specific concept
+ */
+export interface ConceptContext {
+    concept: Section | LocalDef | Operation | ConceptBase;
+    calls: string[];
+    extends: string[];
+    imports: string[];
+    refs: string[];
+    calledBy: string[];
+    extendedBy: string[];
+    importedBy: string[];
+    referencedBy: string[];
+    allEdges: {
+        outgoing: Array<{
+            to: string;
+            role: string;
+        }>;
+        incoming: Array<{
+            from: string;
+            role: string;
+        }>;
+    };
+    contentMap: Record<string, string>;
+}
+/**
+ * Get comprehensive context for any concept by ID
+ * Returns all relationships (calls, extends, imports, refs) both outgoing and incoming
+ */
+export declare function getConceptContext(repo: Repo, conceptId: string): ConceptContext;
+/**
+ * Write context to JSON file
+ */
+export declare function writeContext(file: string, ctx: ContextPayload): Promise<void>;
+//# sourceMappingURL=context.d.ts.map

package/dist/builders/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/builders/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGrG,MAAM,WAAW,SAAS;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,SAAc,GACnB,cAAc,CA2EhB;AA4BD;;GAEG;AACH,wBAAgB,GAAG,CACjB,IAAI,EAAE,IAAI,EACV,GAAG,EAAE,MAAM,GACV,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAE1D;AAED,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAKjE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,CAKlE;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,CAAC;IAEtD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IAEf,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;IAEvB,QAAQ,EAAE;QACR,QAAQ,EAAE,KAAK,CAAC;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;QAC9C,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACjD,CAAC;IAEF,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,GAChB,cAAc,CA4GhB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,IAAI,CAAC,CAIf"}

package/dist/builders/context.js

@@ -0,0 +1,190 @@
+import { debug } from '../utils/logger.js';
+/**
+ * Build minimal execution context for an operation
+ */
+export function buildContext(repo, opRef, opts = {}) {
+    debug.context('Building context for operation: %s', opRef);
+    const { includeChildren = false, maxDefChars } = opts;
+    // 1. Seed: resolve opRef to a Section or Operation
+    const opNode = repo.byId[opRef];
+    if (!opNode || (opNode.kind !== 'section' && opNode.kind !== 'operation')) {
+        throw new Error(`Operation not found: ${opRef}`);
+    }
+    // Get the full Operation object
+    let operation;
+    if (opNode.kind === 'operation') {
+        operation = opNode;
+    }
+    else {
+        // If it's a section, we need to find the operation or throw
+        throw new Error(`Expected operation but got section: ${opRef}`);
+    }
+    // 2. Collect outgoing edges from the operation section
+    const edges = repo.edges.filter((edge) => {
+        if (edge.from === opNode.id) {
+            return true;
+        }
+        // Optionally include edges from child sections
+        if (includeChildren) {
+            return edge.from.startsWith(`${opNode.docId}#`);
+        }
+        return false;
+    });
+    debug.context('Found %d outgoing edges', edges.length);
+    // 3. Calls (just array of concept IDs)
+    const calls = [];
+    for (const edge of edges) {
+        if (edge.role === 'calls') {
+            calls.push(edge.to);
+        }
+    }
+    debug.context('Found %d calls', calls.length);
+    // 4. Symbols
+    // Get the document's import symbol table
+    const fileInfo = repo.byFile[opNode.docId];
+    const docImports = repo.imports.filter((imp) => imp.docId === opNode.docId);
+    const symbols = {};
+    for (const imp of docImports) {
+        if (imp.resolved) {
+            // Parse ConceptId string back to { docId, slug }
+            const parts = imp.resolved.split('#');
+            symbols[imp.label] = {
+                docId: parts[0],
+                slug: parts[1],
+            };
+        }
+    }
+    const payload = {
+        operation,
+        calls,
+        symbols,
+    };
+    debug.context('Context built successfully');
+    return payload;
+}
+/**
+ * Trim content to max characters, preserving structure
+ */
+function trimContent(content, maxChars) {
+    if (content.length <= maxChars) {
+        return content;
+    }
+    // Try to preserve headings and code fences
+    const lines = content.split('\n');
+    let result = '';
+    let charCount = 0;
+    for (const line of lines) {
+        if (charCount + line.length > maxChars) {
+            result += '\n\n[... trimmed ...]';
+            break;
+        }
+        result += line + '\n';
+        charCount += line.length + 1;
+    }
+    return result.trim();
+}
+/**
+ * Lookup helpers
+ */
+export function get(repo, ref) {
+    return repo.byId[ref];
+}
+export function parentsOf(repo, nameOrRef) {
+    const edges = repo.edges.filter((edge) => edge.from === nameOrRef && edge.role === 'extends');
+    return edges.map((edge) => edge.to);
+}
+export function childrenOf(repo, nameOrRef) {
+    const edges = repo.edges.filter((edge) => edge.to === nameOrRef && edge.role === 'extends');
+    return edges.map((edge) => edge.from);
+}
+/**
+ * Get comprehensive context for any concept by ID
+ * Returns all relationships (calls, extends, imports, refs) both outgoing and incoming
+ */
+export function getConceptContext(repo, conceptId) {
+    debug.context('Building concept context for: %s', conceptId);
+    // 1. Get the concept
+    const concept = repo.byId[conceptId];
+    if (!concept) {
+        throw new Error(`Concept not found: ${conceptId}`);
+    }
+    // 2. Get all outgoing edges
+    // For operations and localdefs, also include edges from their parent section and document
+    let edgeSources = [conceptId];
+    if (concept.kind === 'operation' || concept.kind === 'localdef') {
+        // Add the section
+        if ('sectionRef' in concept && concept.sectionRef) {
+            edgeSources.push(concept.sectionRef);
+        }
+        // Add the document
+        if ('docId' in concept && concept.docId) {
+            edgeSources.push(concept.docId);
+        }
+    }
+    const outgoingEdges = repo.edges.filter((edge) => edgeSources.includes(edge.from));
+    // 3. Get all incoming edges
+    const incomingEdges = repo.edges.filter((edge) => edge.to === conceptId);
+    // 4. Group outgoing edges by role
+    const calls = outgoingEdges
+        .filter((e) => e.role === 'calls')
+        .map((e) => e.to);
+    const extendsEdges = outgoingEdges
+        .filter((e) => e.role === 'extends')
+        .map((e) => e.to);
+    const importsEdges = outgoingEdges
+        .filter((e) => e.role === 'imports')
+        .map((e) => e.to);
+    const refs = outgoingEdges
+        .filter((e) => e.role === 'ref')
+        .map((e) => e.to);
+    // 5. Group incoming edges by role
+    const calledBy = incomingEdges
+        .filter((e) => e.role === 'calls')
+        .map((e) => e.from);
+    const extendedBy = incomingEdges
+        .filter((e) => e.role === 'extends')
+        .map((e) => e.from);
+    const importedBy = incomingEdges
+        .filter((e) => e.role === 'imports')
+        .map((e) => e.from);
+    const referencedBy = incomingEdges
+        .filter((e) => e.role === 'ref')
+        .map((e) => e.from);
+    debug.context('Found: %d calls, %d extends, %d imports, %d refs (outgoing)', calls.length, extendsEdges.length, importsEdges.length, refs.length);
+    debug.context('Found: %d calledBy, %d extendedBy, %d importedBy, %d referencedBy (incoming)', calledBy.length, extendedBy.length, importedBy.length, referencedBy.length);
+    // 6. Build content map for imports and refs
+    const contentMap = {};
+    const contentConceptIds = new Set([...importsEdges, ...refs]);
+    for (const id of contentConceptIds) {
+        const relatedConcept = repo.byId[id];
+        if (relatedConcept && 'content' in relatedConcept) {
+            contentMap[id] = relatedConcept.content;
+        }
+    }
+    debug.context('Built content map with %d entries', Object.keys(contentMap).length);
+    return {
+        concept,
+        calls,
+        extends: extendsEdges,
+        imports: importsEdges,
+        refs,
+        calledBy,
+        extendedBy,
+        importedBy,
+        referencedBy,
+        allEdges: {
+            outgoing: outgoingEdges.map((e) => ({ to: e.to, role: e.role })),
+            incoming: incomingEdges.map((e) => ({ from: e.from, role: e.role })),
+        },
+        contentMap,
+    };
+}
+/**
+ * Write context to JSON file
+ */
+export async function writeContext(file, ctx) {
+    const { writeFile } = await import('fs/promises');
+    await writeFile(file, JSON.stringify(ctx, null, 2), 'utf-8');
+    debug.context('Context written to %s', file);
+}
+//# sourceMappingURL=context.js.map

package/dist/cache/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Cache Manager for .libraries/
+ *
+ * Manages local cache of fetched packages.
+ */
+import type { ParsedURL } from '../providers/base.js';
+/**
+ * Result of saving a file to cache
+ */
+export interface CachedFile {
+    path: string;
+    fullPath: string;
+    integrity: string;
+}
+/**
+ * Calculate SHA256 integrity hash of content
+ */
+export declare function calculateIntegrity(content: string): string;
+/**
+ * Verify content matches integrity hash
+ */
+export declare function verifyIntegrity(content: string, integrity: string): boolean;
+/**
+ * Derive cache path from parsed URL
+ *
+ * For GitHub/GitLab: {repo}/{path-from-blob}
+ * For generic URLs: {domain}/{path}
+ */
+export declare function deriveCachePath(parsed: ParsedURL): string;
+/**
+ * Cache Manager
+ *
+ * Manages the .libraries/ cache directory.
+ */
+export declare class CacheManager {
+    private _workspaceRoot;
+    private _librariesPath;
+    constructor(workspaceRoot: string);
+    /**
+     * Get workspace root path
+     */
+    get workspaceRoot(): string;
+    /**
+     * Get .libraries path
+     */
+    get librariesPath(): string;
+    /**
+     * Initialize cache directory
+     */
+    init(): Promise<void>;
+    /**
+     * Save content to cache
+     */
+    save(cachePath: string, content: string): Promise<CachedFile>;
+    /**
+     * Read content from cache
+     */
+    read(cachePath: string): Promise<string>;
+    /**
+     * Check if file exists in cache
+     */
+    exists(cachePath: string): Promise<boolean>;
+    /**
+     * Delete file from cache
+     */
+    delete(cachePath: string): Promise<void>;
+    /**
+     * List all cached files
+     */
+    list(): Promise<string[]>;
+    /**
+     * Remove all cached files
+     */
+    clean(): Promise<number>;
+    /**
+     * Verify integrity of cached file
+     */
+    verifyIntegrity(cachePath: string, integrity: string): Promise<boolean>;
+    /**
+     * Get full filesystem path from cache path
+     */
+    getFullPath(cachePath: string): string;
+    /**
+     * Get cache path from full filesystem path
+     */
+    getCachePath(fullPath: string): string | null;
+    /**
+     * Walk directory recursively to collect files
+     */
+    private walkDir;
+    /**
+     * Clean up empty directories from a path up to .libraries
+     */
+    private cleanEmptyDirs;
+    /**
+     * Clean all empty directories under .libraries
+     */
+    private cleanAllEmptyDirs;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAO3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAoBzD;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAAS;gBAEnB,aAAa,EAAE,MAAM;IAKjC;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmBnE;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK9C;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUjD;;OAEG;IACG,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiB9C;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAgB/B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAkB9B;;OAEG;IACG,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAS7E;;OAEG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;IAItC;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAe7C;;OAEG;YACW,OAAO;IAiBrB;;OAEG;YACW,cAAc;IAkB5B;;OAEG;YACW,iBAAiB;CAwBhC"}