prolog-trace-viz 1.0.0

package/README.md

@@ -0,0 +1,148 @@
+# prolog-trace-viz
+
+Generate beautiful, educational Mermaid diagrams from Prolog execution traces.
+
+## Features
+
+- Custom Prolog tracer using SWI-Prolog's trace interception hook
+- Captures accurate unification information directly from execution
+- Generates colour-coded Mermaid diagrams
+- Produces complete markdown documentation with step-by-step breakdowns
+- Tracks pending goals, variable bindings, and clause usage
+- No external dependencies beyond SWI-Prolog
+
+## Prerequisites
+
+**SWI-Prolog 7.0 or later** - Install from https://www.swi-prolog.org/Download.html
+
+The tool uses a custom tracer built on SWI-Prolog's `prolog_trace_interception/4` hook, which requires version 7.0 or later. No additional packages are required.
+
+## Installation
+
+```
+npm install -g prolog-trace-viz
+```
+
+Or run directly with npx:
+
+```
+npx prolog-trace-viz <prolog-file> <query>
+```
+
+## Usage
+
+```
+prolog-trace-viz <prolog-file> <query> [options]
+```
+
+### Arguments
+
+- `<prolog-file>` - Path to your Prolog source file
+- `<query>` - Prolog query to trace (e.g., `"append([1,2], [3,4], X)"`)
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Write output to file instead of stdout |
+| `--verbose` | Display detailed processing information |
+| `--quiet` | Suppress all non-error output except final result |
+| `-h, --help` | Show help message |
+| `-v, --version` | Show version number |
+
+### Examples
+
+Basic usage:
+
+```
+prolog-trace-viz program.pl "append([1,2], [3,4], X)"
+```
+
+Save to file:
+
+```
+prolog-trace-viz program.pl "member(X, [a,b,c])" -o trace.md
+```
+
+With verbose output:
+
+```
+prolog-trace-viz program.pl "factorial(5, X)" --verbose
+```
+
+## Example Output
+
+Given a simple Prolog file `append.pl`:
+
+```prolog
+append([], L, L).
+append([H|T], L, [H|R]) :- append(T, L, R).
+```
+
+Running:
+
+```
+prolog-trace-viz append.pl "append([1,2], [3], X)"
+```
+
+Produces a markdown document with:
+
+1. **Query section** - The original query in a code block
+2. **Execution tree** - A Mermaid diagram showing the trace
+3. **Legend** - Explanation of visual elements
+4. **Step-by-step breakdown** - Detailed execution steps
+5. **Final answer** - The result bindings
+6. **Clauses used** - Summary of which clauses matched
+
+### Visual Elements
+
+| Symbol | Meaning |
+|--------|---------|
+| 🎯 | Initial query |
+| 🔄 | Currently solving |
+| ⏸️ | Pending (queued) |
+| ✅ | Solved |
+| 🎉 | Success |
+
+### Colour Scheme
+
+- **Blue** - Query nodes
+- **Yellow** - Solving nodes
+- **Grey** - Pending nodes
+- **Green** - Solved/Success nodes
+
+## Architecture
+
+The tool uses a custom Prolog tracer that leverages SWI-Prolog's `prolog_trace_interception/4` hook to capture execution events. This approach provides several advantages:
+
+- **Accurate unifications**: Direct access to variable bindings via `prolog_frame_attribute/3`
+- **No code instrumentation**: Your Prolog code runs unmodified
+- **Reliable clause tracking**: Clause numbers come from Prolog's internal tracking
+- **Structured output**: JSON-based trace format for easy parsing
+
+### Pipeline
+
+1. Parse user's Prolog file to extract clauses
+2. Generate wrapper that loads custom tracer
+3. Execute query with trace interception active
+4. Export trace events as JSON
+5. Build execution tree from trace events
+6. Analyze tree and generate visualization
+7. Render as Mermaid diagram in markdown
+
+## Development
+
+```
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+## Licence
+
+MIT

package/dist/analyzer.d.ts

@@ -0,0 +1,64 @@
+import { ExecutionNode, TraceEvent } from './parser.js';
+export interface VisualizationNode {
+    id: string;
+    type: 'query' | 'solving' | 'pending' | 'solved' | 'success' | 'clause-body' | 'match';
+    label: string;
+    emoji: string;
+    level: number;
+    clauseNumber?: number;
+}
+export interface VisualizationEdge {
+    id: string;
+    from: string;
+    to: string;
+    type: 'active' | 'queue' | 'activate';
+    label: string;
+    stepNumber: number;
+}
+export interface PendingGoal {
+    id: string;
+    goal: string;
+    queuedAt: string;
+    activatedAt?: string;
+}
+export interface ClauseUsage {
+    clauseNumber: number;
+    clauseText: string;
+    usageCount: number;
+    usedAtSteps: number[];
+}
+export interface ExecutionStep {
+    stepNumber: number;
+    description: string;
+    goal: string;
+    clauseMatched?: string;
+    bindings?: Record<string, string>;
+    newGoals?: string[];
+}
+export type DetailLevel = 'minimal' | 'standard' | 'detailed' | 'full';
+export interface AnalysisOptions {
+    detailLevel?: DetailLevel;
+}
+export interface AnalysisResult {
+    nodes: VisualizationNode[];
+    edges: VisualizationEdge[];
+    pendingGoals: Map<string, PendingGoal>;
+    executionOrder: string[];
+    clausesUsed: ClauseUsage[];
+    executionSteps: ExecutionStep[];
+    finalAnswer?: string;
+}
+import { Clause } from './clauses.js';
+/**
+ * Analyzes an execution tree and produces visualization data.
+ */
+export declare function analyzeTree(root: ExecutionNode, clauses?: Clause[], options?: AnalysisOptions, traceEvents?: TraceEvent[]): AnalysisResult;
+/**
+ * Assigns level-based variable names to avoid confusion in recursive calls.
+ */
+export declare function assignLevelVariables(node: ExecutionNode, level: number): void;
+/**
+ * Determines the execution order (left-to-right, depth-first).
+ */
+export declare function determineExecutionOrder(root: ExecutionNode): string[];
+//# sourceMappingURL=analyzer.d.ts.map

package/dist/analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACxD,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,aAAa,GAAG,OAAO,CAAC;IACvF,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAiCvE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,KAAK,EAAE,iBAAiB,EAAE,CAAC;IAC3B,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IACvC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,cAAc,EAAE,aAAa,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAYD,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAgHtC;;GAEG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,aAAa,EACnB,OAAO,GAAE,MAAM,EAAO,EACtB,OAAO,GAAE,eAAoB,EAC7B,WAAW,GAAE,UAAU,EAAO,GAC7B,cAAc,CA8EhB;AAisBD;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAe7E;AA8DD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,EAAE,CAYrE"}