@davidsouther/agathon 0.0.0-stage → 2026.11.1

package/src/tsabre/print.ts

@@ -0,0 +1,188 @@
+/**
+ * @fileoverview A small utility to create DOT-compatible string reprentations
+ * of graphs.
+ */
+
+import type { Edge, FullGraph, NodeId } from "../types.ts";
+
+import { CodeContentBuffer, DelimitationStrategy } from "./sourcebuilder/code_content_buffer.ts";
+import { Printable, PrintableString } from "./sourcebuilder/printable.ts";
+
+/**
+ * DigraphAttributeWriters allow clients to provide functions to return a map
+ * of attribute key:value pairs to include with each item.
+ */
+export interface DigraphAttributeWriters {
+  node: (id: NodeId) => Map<string, string>;
+  edge: (edge: Edge) => Map<string, string>;
+  graph: () => Map<string, string>;
+}
+
+function fillMissingWriters(
+  writers: Partial<DigraphAttributeWriters> = {},
+): DigraphAttributeWriters {
+  if (!writers.node) {
+    writers.node = () => new Map<string, string>();
+  }
+  if (!writers.edge) {
+    writers.edge = () => new Map<string, string>();
+  }
+  if (!writers.graph) {
+    writers.graph = () => new Map<string, string>();
+  }
+  return writers as DigraphAttributeWriters;
+}
+
+class Digraph extends Printable {
+  static fromGraph(g: FullGraph, partialWriters?: Partial<DigraphAttributeWriters>): Digraph {
+    const writers = fillMissingWriters(partialWriters);
+
+    const nodes = [...g.children()].map((id) =>
+      DigraphNode.fromGraphNode(g, id, (id) => AttributeWriter.fromMap(writers.node(id))),
+    );
+
+    const edges = [...g.allEdges].map((e) =>
+      DigraphEdge.fromGraphEdge(e, AttributeWriter.fromMap(writers.edge(e))),
+    );
+
+    const attributes = AttributeWriter.fromMap(writers.graph());
+
+    return new Digraph(nodes, edges, attributes);
+  }
+
+  private readonly nodes: DigraphNode[];
+  private readonly edges: DigraphEdge[];
+  private readonly attributes: AttributeWriter;
+  private constructor(nodes: DigraphNode[], edges: DigraphEdge[], attributes: AttributeWriter) {
+    super();
+    this.nodes = nodes;
+    this.edges = edges;
+    this.attributes = attributes;
+  }
+
+  print(buffer: CodeContentBuffer) {
+    buffer.write("digraph {").indentOnce();
+    if (this.attributes.hasAttributes) {
+      buffer.newline().write(this.attributes).newline();
+    }
+    buffer
+      .repeatedNewlineWrite(this.nodes)
+      .repeatedNewlineWrite(this.edges)
+      .unindentOnce()
+      .removeTrailingSpaces()
+      .write("}");
+  }
+}
+
+/**
+ * Given a Node, possibly with children, print the tree of children:
+ * ```
+ * a {
+ *   b {
+ *     c;
+ *   };
+ * };
+ * ```
+ *
+ */
+class DigraphNode extends Printable {
+  static fromGraphNode(
+    g: FullGraph,
+    id: NodeId,
+    attributeWriter: (id: NodeId) => AttributeWriter,
+  ): DigraphNode {
+    return new DigraphNode(
+      id,
+      [...g.children(id)].map((n) => DigraphNode.fromGraphNode(g, n, attributeWriter)),
+      attributeWriter(id),
+    );
+  }
+
+  private readonly id: NodeId;
+  private readonly children: DigraphNode[];
+  private readonly attributes: AttributeWriter;
+  private constructor(id: NodeId, children: DigraphNode[], attributes: AttributeWriter) {
+    super();
+    this.id = id;
+    this.children = children;
+    this.attributes = attributes;
+  }
+
+  print(buffer: CodeContentBuffer) {
+    buffer.write(this.id);
+    if (this.attributes.hasAttributes) {
+      buffer.write(" ").write(this.attributes);
+    }
+    if (this.children.length > 0) {
+      buffer.write(" {").indentOnce().repeatedNewlineWrite(this.children).unindentOnce().write("}");
+    }
+    buffer.write(";");
+  }
+}
+
+/**
+ * Printable for DigraphEdge; given an edge print the link `id1 -> id2;`.
+ */
+class DigraphEdge extends Printable {
+  static fromGraphEdge(e: Edge, attributes: AttributeWriter): DigraphEdge {
+    return new DigraphEdge(e, attributes);
+  }
+
+  private readonly edge: Edge;
+  private readonly attributes: AttributeWriter;
+  private constructor(edge: Edge, attributes: AttributeWriter) {
+    super();
+    this.edge = edge;
+    this.attributes = attributes;
+  }
+
+  print(buffer: CodeContentBuffer) {
+    buffer.write(this.edge.source).write(" -> ").write(this.edge.target);
+    if (this.attributes.hasAttributes) {
+      buffer.write(" ").write(this.attributes);
+    }
+    buffer.write(";");
+  }
+}
+
+/**
+ * An AttributeWriter creates an attribute list in the written DOT file. It is
+ * created from a map of key/value strings, and writes the key unquoted and the
+ * value in quotes. No validation is performed on the key.
+ */
+class AttributeWriter extends Printable {
+  static fromMap(map: Map<string, string>): AttributeWriter {
+    return new AttributeWriter(map);
+  }
+
+  get hasAttributes(): boolean {
+    return this.attributes.size > 0;
+  }
+
+  private readonly attributes: Map<string, string>;
+  private constructor(attributes: Map<string, string>) {
+    super();
+    this.attributes = attributes;
+  }
+
+  print(buffer: CodeContentBuffer) {
+    if (this.attributes.size === 0) return;
+    buffer
+      .write("[")
+      .repeatedWrite(
+        [...this.attributes].map(([k, v]) => `${k}="${v}";`).map(PrintableString.from),
+        " ",
+        DelimitationStrategy.ALL_BUT_LAST,
+      )
+      .write("]");
+  }
+}
+
+/**
+ * Create a DOT text for a graph. The opposite of `builder.parse`.
+ */
+export function stringGraph(g: FullGraph, writers?: Partial<DigraphAttributeWriters>): string {
+  const buffer = new CodeContentBuffer();
+  const digraph = Digraph.fromGraph(g, writers);
+  return buffer.write(digraph).content;
+}

package/src/tsabre/sourcebuilder/code_content_buffer.ts

@@ -0,0 +1,275 @@
+import type { Printable } from "./printable.ts";
+
+const INDENT = "  "; // Two spaces
+const NEWLINE = "\n";
+
+/**
+ * Used to specify how a list should be delimited.
+ *
+ * <p>example: If the delimiter was a comma, then this would be the result of
+ * delimiting the list [1, 2, 3].
+ *
+ * <p>All: 1,2,3, All_BUT_LAST: 1,2,3
+ */
+export const DelimitationStrategy = {
+  ALL: 0,
+  ALL_BUT_LAST: 1,
+} as const;
+export type DelimitationStrategy = (typeof DelimitationStrategy)[keyof typeof DelimitationStrategy];
+
+/** Used to specify where leading and trailing new lines should be placed. */
+const NewlineStrategyEnum = {
+  BETWEEN_ITEMS_ONLY: 0,
+  LEADING: 1,
+  TRAILING: 2,
+  LEADING_AND_TRAILING: 3,
+} as const;
+type NewlineStrategyEnum = (typeof NewlineStrategyEnum)[keyof typeof NewlineStrategyEnum];
+
+/**
+ * NewlineStrategy describes where to place newlines around repeated sections of
+ * code in a CodeContentBuffer.
+ */
+export class NewlineStrategy {
+  static BETWEEN_ITEMS_ONLY = new NewlineStrategy(NewlineStrategyEnum.BETWEEN_ITEMS_ONLY);
+  static LEADING = new NewlineStrategy(NewlineStrategyEnum.LEADING);
+  static TRAILING = new NewlineStrategy(NewlineStrategyEnum.TRAILING);
+  static LEADING_AND_TRAILING = new NewlineStrategy(NewlineStrategyEnum.LEADING_AND_TRAILING);
+
+  private readonly strategy: NewlineStrategyEnum;
+  private constructor(strategy: NewlineStrategyEnum) {
+    this.strategy = strategy;
+  }
+
+  get leading(): boolean {
+    return (
+      this.strategy === NewlineStrategyEnum.LEADING ||
+      this.strategy === NewlineStrategyEnum.LEADING_AND_TRAILING
+    );
+  }
+
+  get trailing(): boolean {
+    return (
+      this.strategy === NewlineStrategyEnum.TRAILING ||
+      this.strategy === NewlineStrategyEnum.LEADING_AND_TRAILING
+    );
+  }
+}
+
+/**
+ * For sertain operations, we do a lot of removing at the end of a string. This
+ * Buffer class handled that in an efficient way.
+ */
+class Buffer {
+  readonly strings: string[] = [""];
+
+  get tail(): string {
+    return this.strings[this.strings.length - 1];
+  }
+  set tail(value: string) {
+    this.strings[this.strings.length - 1] = value;
+  }
+
+  get isLastCharNewLine() {
+    this.shrink();
+    return this.tail.substr(-1) === NEWLINE;
+  }
+
+  get isLastCharSpace() {
+    this.shrink();
+    return [" ", "\t"].indexOf(this.tail.substr(-1)) > -1;
+  }
+
+  get isLastCharWhitespace() {
+    this.shrink();
+    return [" ", "\t", "\n"].indexOf(this.tail.substr(-1)) > -1;
+  }
+
+  append(s: string) {
+    if (this.tail.length > this.bufferSize) {
+      this.strings.push(s);
+    } else {
+      this.tail += s;
+    }
+  }
+
+  toString(): string {
+    return this.strings.join("");
+  }
+
+  removeTrailingNewlines() {
+    while (this.isLastCharNewLine) {
+      this.tail = this.tail.slice(0, -1);
+    }
+  }
+
+  removeTrailingSpaces() {
+    while (this.isLastCharSpace) {
+      this.tail = this.tail.slice(0, -1);
+    }
+  }
+
+  removeTrailingWhitespace() {
+    while (this.isLastCharWhitespace) {
+      this.tail = this.tail.slice(0, -1);
+    }
+  }
+
+  private shrink() {
+    while (this.tail.length === 0 && this.strings.length > 1) {
+      this.strings.pop();
+    }
+  }
+
+  private readonly bufferSize = 1024;
+}
+
+/**
+ * CodeContentBuffer provides a clean wrapper around a string that maintains an
+ * understanding of internal lines and its current indentation leve.
+ */
+export class CodeContentBuffer {
+  private indentLevel = 0;
+  private newlinePrefix = "";
+  private readonly stringBuilder = new Buffer();
+
+  get content(): string {
+    return this.stringBuilder.toString();
+  }
+
+  indentOnce(): CodeContentBuffer {
+    this.indentLevel += 1;
+    return this;
+  }
+
+  unindentOnce(): CodeContentBuffer {
+    this.indentLevel -= 1;
+    return this;
+  }
+
+  indentTwice(): CodeContentBuffer {
+    return this.indentOnce().indentOnce();
+  }
+
+  unindentTwice(): CodeContentBuffer {
+    return this.unindentOnce().unindentOnce();
+  }
+
+  setNewlinePrefix(prefix: string): CodeContentBuffer {
+    this.newlinePrefix = prefix;
+    return this;
+  }
+
+  removeNewlinePrefix(): CodeContentBuffer {
+    this.newlinePrefix = "";
+    return this;
+  }
+
+  removeTrailingNewlines(): CodeContentBuffer {
+    this.stringBuilder.removeTrailingNewlines();
+    return this;
+  }
+
+  removeTrailingSpaces(): CodeContentBuffer {
+    this.stringBuilder.removeTrailingSpaces();
+    return this;
+  }
+
+  removeTrailingWhitespace(): CodeContentBuffer {
+    this.stringBuilder.removeTrailingWhitespace();
+    return this;
+  }
+
+  newline(n = 1): CodeContentBuffer {
+    while (--n >= 0) {
+      this.stringBuilder.removeTrailingSpaces();
+      this.append(NEWLINE);
+      this.write(this.newlinePrefix);
+    }
+    return this;
+  }
+
+  write(printable: string | Printable | null): CodeContentBuffer {
+    if (printable == null) {
+      return this;
+    }
+    if (typeof printable === "string") {
+      this.applyIndent().append(printable);
+    } else {
+      printable.print(this);
+    }
+    return this;
+  }
+
+  repeatedNewlineWrite<T extends Printable>(
+    printables: T[] | null,
+    newlineCount = 1,
+    newlineStrategy = NewlineStrategy.LEADING_AND_TRAILING,
+    delimiter = "",
+    deliminationStrategy: DelimitationStrategy = DelimitationStrategy.ALL,
+  ): CodeContentBuffer {
+    return this.repeatedWrite(
+      printables,
+      delimiter,
+      deliminationStrategy,
+      newlineCount,
+      newlineStrategy,
+    );
+  }
+
+  repeatedWrite<T extends Printable>(
+    printables: T[] | null,
+    delimiter = "",
+    deliminationStrategy: DelimitationStrategy = DelimitationStrategy.ALL,
+    newlineCount = 0,
+    newlineStrategy = NewlineStrategy.BETWEEN_ITEMS_ONLY,
+  ): CodeContentBuffer {
+    if (printables == null) {
+      return this;
+    }
+    const size = printables.length;
+    if (size === 0) return this; // Bail early.
+
+    if (newlineCount > 0 && newlineStrategy.leading) {
+      this.newline();
+    }
+
+    let i = 0;
+    for (const t of printables) {
+      t.print(this);
+
+      if (i < size - 1) {
+        this.write(delimiter);
+        this.newline(newlineCount);
+      } else if (DelimitationStrategy.ALL === deliminationStrategy) {
+        this.write(delimiter);
+      }
+
+      i++;
+    }
+
+    if (newlineCount > 0 && newlineStrategy.trailing) {
+      this.newline().removeTrailingSpaces();
+    }
+
+    return this;
+  }
+
+  toString(): string {
+    return this.content;
+  }
+
+  private append(value: string): CodeContentBuffer {
+    this.stringBuilder.append(value);
+    return this;
+  }
+
+  private applyIndent(): CodeContentBuffer {
+    if (this.stringBuilder.isLastCharNewLine) {
+      for (let i = 0; i < this.indentLevel; i++) {
+        this.append(INDENT);
+      }
+    }
+    return this;
+  }
+}

package/src/tsabre/sourcebuilder/printable.ts

@@ -0,0 +1,33 @@
+import { CodeContentBuffer } from "./code_content_buffer.ts";
+
+/** Represents something that will write to a passed in {@link codeBuffer}. */
+export abstract class Printable {
+  /** Write this Printable into a CodeContentBuffer. */
+  abstract print(codeBuffer: CodeContentBuffer): void;
+
+  toString(): string {
+    const codeBuffer = new CodeContentBuffer();
+    this.print(codeBuffer);
+    return codeBuffer.content;
+  }
+}
+
+/** Converts a String to a {@link Printable}. */
+export class PrintableString extends Printable {
+  static from(s: string | Printable): Printable {
+    if (typeof s === "string") {
+      s = new PrintableString(s);
+    }
+    return s;
+  }
+
+  readonly value: string;
+  private constructor(value: string) {
+    super();
+    this.value = value;
+  }
+
+  print(codeBuffer: CodeContentBuffer): void {
+    codeBuffer.write(this.value);
+  }
+}

package/src/tsabre.ts

@@ -0,0 +1,6 @@
+export * from "./tsabre/algo.ts";
+export * from "./tsabre/builder.ts";
+export * from "./tsabre/compress.ts";
+export * from "./tsabre/graph.ts";
+export * from "./tsabre/parse.ts";
+export * from "./tsabre/print.ts";