@polagram/core 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,625 @@
+import { z } from 'zod';
+
+/**
+ * Independent activation/deactivation not tied to a specific message line.
+ * e.g., Mermaid "activate A", PlantUML "activate A"
+ */
+export declare interface ActivationNode {
+    kind: 'activation';
+    participantId: string;
+    action: 'activate' | 'deactivate';
+    style?: StyleProps;
+}
+
+/**
+ * Apply a lens object to the AST.
+ * Facade for the TransformationEngine.
+ */
+export declare function applyLens(root: PolagramRoot, lens: Lens): PolagramRoot;
+
+/**
+ * Strategy Interface for Diagram Parsing.
+ * Implements the Strategy Pattern: different formats implement this interface.
+ */
+export declare interface DiagramParser {
+    parse(code: string): PolagramRoot;
+}
+
+export declare interface DividerNode {
+    kind: 'divider';
+    id: string;
+    text?: string;
+}
+
+export declare type EventNode = MessageNode | FragmentNode | NoteNode | DividerNode | ActivationNode | ReferenceNode | SpacerNode;
+
+export declare class FocusFilter extends Walker {
+    private layer;
+    private matcher;
+    private targetParticipantIds;
+    constructor(layer: FocusLayer);
+    transform(root: PolagramRoot): PolagramRoot;
+    private resolveTargetParticipants;
+    protected visitEvent(node: EventNode): EventNode[];
+    private isRelatedToParticipant;
+}
+
+export declare interface FocusLayer {
+    action: 'focus';
+    selector: ParticipantSelector;
+}
+
+export declare interface FragmentBranch {
+    id: string;
+    condition?: string;
+    events: EventNode[];
+}
+
+export declare interface FragmentNode {
+    kind: 'fragment';
+    id: string;
+    operator: FragmentOperator;
+    branches: FragmentBranch[];
+}
+
+export declare type FragmentOperator = 'alt' | 'opt' | 'loop' | 'par' | 'break' | 'critical' | 'rect' | 'group';
+
+export declare interface FragmentSelector {
+    kind?: 'fragment';
+    condition?: TextMatcher;
+    operator?: FragmentOperator | FragmentOperator[];
+}
+
+export declare interface GroupSelector {
+    kind?: 'group';
+    name?: TextMatcher;
+}
+
+export declare type Layer = ResolveLayer | FocusLayer | RemoveLayer;
+
+export declare interface Lens {
+    name?: string;
+    description?: string;
+    layers: Layer[];
+}
+
+export declare type LensConfig = z.infer<typeof LensSchema>;
+
+declare const LensSchema: z.ZodObject<{
+    name: z.ZodString;
+    suffix: z.ZodOptional<z.ZodString>;
+    layers: z.ZodArray<z.ZodObject<{
+        action: z.ZodEnum<{
+            resolve: "resolve";
+            focus: "focus";
+            remove: "remove";
+        }>;
+        selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"fragment">;
+            condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"participant">;
+            name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"message">;
+            text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+            to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"group">;
+            name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                pattern: z.ZodString;
+                flags: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>]>>;
+        }, z.core.$strip>], "kind">;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+export declare class Matcher {
+    matchBranch(branch: FragmentBranch, selector: FragmentSelector, parentOperator: FragmentOperator): boolean;
+    matchParticipant(node: Participant, selector: ParticipantSelector): boolean;
+    matchMessage(node: MessageNode, selector: MessageSelector): boolean;
+    matchGroup(node: ParticipantGroup, selector: GroupSelector): boolean;
+    private matchText;
+}
+
+/**
+ * Visitor implementation that generates Mermaid code.
+ */
+export declare class MermaidGeneratorVisitor implements PolagramVisitor {
+    private lines;
+    private indentLevel;
+    private traverser;
+    constructor();
+    generate(ast: PolagramRoot): string;
+    visitRoot(node: PolagramRoot): void;
+    visitParticipant(node: Participant): void;
+    visitParticipantGroup(node: ParticipantGroup): void;
+    visitMessage(node: MessageNode): void;
+    visitFragment(node: FragmentNode): void;
+    visitNote(node: NoteNode): void;
+    visitActivation(node: ActivationNode): void;
+    visitDivider(node: DividerNode): void;
+    visitSpacer(node: SpacerNode): void;
+    visitReference(node: ReferenceNode): void;
+    private add;
+    private indent;
+}
+
+export declare type MessageEndpoint = string | null;
+
+/**
+ * Represents a directional interaction.
+ * Includes standard sync/async calls, returns, and object creation/deletion.
+ */
+export declare interface MessageNode {
+    kind: 'message';
+    id: string;
+    from: MessageEndpoint;
+    to: MessageEndpoint;
+    text: string;
+    type: 'sync' | 'async' | 'reply' | 'create' | 'destroy';
+    style: {
+        line: 'solid' | 'dotted';
+        head: 'arrow' | 'async' | 'open' | 'cross';
+        color?: string;
+    };
+    lifecycle?: {
+        activateTarget?: boolean;
+        deactivateSource?: boolean;
+    };
+}
+
+export declare interface MessageSelector {
+    kind?: 'message';
+    text?: TextMatcher;
+    from?: TextMatcher;
+    to?: TextMatcher;
+}
+
+export declare interface MetaData {
+    version: string;
+    source: 'mermaid' | 'plantuml' | 'unknown';
+    title?: string;
+    theme?: Record<string, string>;
+}
+
+export declare interface NoteNode {
+    kind: 'note';
+    id: string;
+    text: string;
+    position: 'left' | 'right' | 'over';
+    participantIds: string[];
+    style?: StyleProps;
+}
+
+/**
+ * Parser Factory
+ * Centralizes retrieval of parser strategies.
+ */
+export declare class ParserFactory {
+    private static parsers;
+    static register(language: string, parser: DiagramParser): void;
+    static getParser(language: string): DiagramParser;
+}
+
+export declare interface Participant {
+    id: string;
+    name: string;
+    alias?: string;
+    type: ParticipantType;
+    stereotype?: string;
+    style?: StyleProps;
+}
+
+export declare interface ParticipantGroup {
+    kind: 'group';
+    id: string;
+    name?: string;
+    type?: string;
+    participantIds: string[];
+    style?: StyleProps;
+}
+
+export declare interface ParticipantSelector {
+    kind?: 'participant';
+    name?: TextMatcher;
+    id?: TextMatcher;
+    stereotype?: TextMatcher;
+}
+
+export declare type ParticipantType = 'participant' | 'actor' | 'boundary' | 'control' | 'entity' | 'database' | 'collections' | 'queue';
+
+/**
+ * Polagram Fluent API
+ *
+ * Provides a high-level, chainable interface for transformations.
+ *
+ * @example
+ * const result = Polagram.init(mermaidCode)
+ *   .focusParticipant('PaymentService')
+ *   .removeParticipant('DebugLogger')
+ *   .toMermaid();
+ */
+export declare class Polagram {
+    private constructor();
+    /**
+     * Initialize a new Polagram transformation pipeline.
+     * @param code Source diagram code
+     * @param format Input format (currently only 'mermaid' is supported)
+     */
+    static init(code: string, format?: 'mermaid'): PolagramBuilder;
+}
+
+/**
+ * Builder class for chaining transformations.
+ */
+export declare class PolagramBuilder {
+    private ast;
+    private layers;
+    constructor(ast: PolagramRoot);
+    /**
+     * Focus on specific participants.
+     * Keeps only interactions involving the matched participants.
+     * @param selector Name (string/RegExp) or detailed ParticipantSelector
+     */
+    focusParticipant(selector: TextMatcher | Partial<ParticipantSelector>): this;
+    /**
+     * Remove specific participants and their interactions.
+     * @param selector Name (string/RegExp) or detailed ParticipantSelector
+     */
+    removeParticipant(selector: TextMatcher | Partial<ParticipantSelector>): this;
+    /**
+     * Remove specific messages.
+     * @param selector Message text (string/RegExp) or detailed MessageSelector
+     */
+    removeMessage(selector: TextMatcher | Partial<MessageSelector>): this;
+    /**
+     * Remove specific groups (visual boxes).
+     * @param selector Group name (string/RegExp) or detailed GroupSelector
+     */
+    removeGroup(selector: TextMatcher | Partial<GroupSelector>): this;
+    /**
+     * Resolve (unwrap) specific fragments like 'alt', 'opt', 'loop'.
+     * Promotes the content of the matched branch and removes the wrapper.
+     * @param selector Condition text (string/RegExp) or detailed FragmentSelector
+     */
+    resolveFragment(selector: TextMatcher | Partial<FragmentSelector>): this;
+    /**
+     * Apply a Lens (a named set of transformation layers).
+     * @param lens Lens object containing layers
+     */
+    applyLens(lens: Lens): this;
+    /**
+     * Generate Mermaid code from the transformed AST.
+     */
+    toMermaid(): string;
+    /**
+     * Get the transformed AST (for advanced use cases).
+     */
+    toAST(): PolagramRoot;
+    private normalizeParticipantSelector;
+    private normalizeMessageSelector;
+    private normalizeGroupSelector;
+    private normalizeFragmentSelector;
+    private isTextMatcher;
+}
+
+export declare type PolagramConfig = z.infer<typeof PolagramConfigSchema>;
+
+export declare const PolagramConfigSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    targets: z.ZodArray<z.ZodObject<{
+        input: z.ZodArray<z.ZodString>;
+        outputDir: z.ZodString;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        lenses: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            suffix: z.ZodOptional<z.ZodString>;
+            layers: z.ZodArray<z.ZodObject<{
+                action: z.ZodEnum<{
+                    resolve: "resolve";
+                    focus: "focus";
+                    remove: "remove";
+                }>;
+                selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"fragment">;
+                    condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"participant">;
+                    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"message">;
+                    text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                    to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodLiteral<"group">;
+                    name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                        pattern: z.ZodString;
+                        flags: z.ZodOptional<z.ZodString>;
+                    }, z.core.$strip>]>>;
+                }, z.core.$strip>], "kind">;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+/**
+ * Polagram Abstract Syntax Tree (AST) Definitions
+ *
+ * Designed to be a lossless representation of Sequence Diagrams from:
+ * - Mermaid
+ * - PlantUML
+ *
+ * It captures structure, semantics (lifecycle, grouping), and necessary visual hints.
+ */
+export declare interface PolagramRoot {
+    kind: 'root';
+    meta: MetaData;
+    participants: Participant[];
+    groups: ParticipantGroup[];
+    events: EventNode[];
+}
+
+/**
+ * Visitor interface for traversing the Polagram AST.
+ * Implement this interface to create code generators, validators, etc.
+ */
+export declare interface PolagramVisitor {
+    visitRoot(node: PolagramRoot): void;
+    visitParticipant(node: Participant): void;
+    visitParticipantGroup(node: ParticipantGroup): void;
+    visitMessage(node: MessageNode): void;
+    visitFragment(node: FragmentNode): void;
+    visitNote(node: NoteNode): void;
+    visitActivation(node: ActivationNode): void;
+    visitDivider(node: DividerNode): void;
+    visitSpacer(node: SpacerNode): void;
+    visitReference(node: ReferenceNode): void;
+}
+
+/**
+ * Refers to another sequence diagram or a frame covering participants.
+ * e.g., PlantUML "ref over A, B : Init"
+ */
+export declare interface ReferenceNode {
+    kind: 'ref';
+    id: string;
+    text: string;
+    participantIds: string[];
+    link?: string;
+}
+
+export declare class RemoveFilter extends Walker {
+    private layer;
+    private matcher;
+    private removedParticipantIds;
+    constructor(layer: RemoveLayer);
+    transform(root: PolagramRoot): PolagramRoot;
+    protected visitEvent(node: EventNode): EventNode[];
+    private isRelatedToRemovedParticipant;
+}
+
+export declare interface RemoveLayer {
+    action: 'remove';
+    selector: ParticipantSelector | MessageSelector | GroupSelector;
+}
+
+export declare class ResolveFilter extends Walker {
+    private layer;
+    private matcher;
+    constructor(layer: ResolveLayer);
+    protected visitFragment(node: FragmentNode): EventNode[];
+}
+
+export declare interface ResolveLayer {
+    action: 'resolve';
+    selector: FragmentSelector;
+}
+
+export declare interface SpacerNode {
+    kind: 'spacer';
+    id: string;
+    height?: number;
+    text?: string;
+}
+
+/**
+ * Cleaner that removes empty fragments and branches from the AST.
+ * This runs after filters to ensure the AST structure remains valid/clean.
+ */
+export declare class StructureCleaner extends Walker {
+    protected visitFragment(node: FragmentNode): EventNode[];
+}
+
+export declare interface StyleProps {
+    color?: string;
+    backgroundColor?: string;
+    shape?: string;
+}
+
+export declare type TargetConfig = z.infer<typeof TargetConfigSchema>;
+
+declare const TargetConfigSchema: z.ZodObject<{
+    input: z.ZodArray<z.ZodString>;
+    outputDir: z.ZodString;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    lenses: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        suffix: z.ZodOptional<z.ZodString>;
+        layers: z.ZodArray<z.ZodObject<{
+            action: z.ZodEnum<{
+                resolve: "resolve";
+                focus: "focus";
+                remove: "remove";
+            }>;
+            selector: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"fragment">;
+                condition: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                operator: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"participant">;
+                name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                id: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                stereotype: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"message">;
+                text: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                from: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+                to: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>, z.ZodObject<{
+                kind: z.ZodLiteral<"group">;
+                name: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    pattern: z.ZodString;
+                    flags: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>]>>;
+            }, z.core.$strip>], "kind">;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+
+export declare type TextMatcher = string | RegExp | {
+    pattern: string;
+    flags?: string;
+};
+
+export declare class TransformationEngine {
+    transform(root: PolagramRoot, layers: Layer[]): PolagramRoot;
+}
+
+declare interface Transformer_2 {
+    transform(root: PolagramRoot): PolagramRoot;
+}
+export { Transformer_2 as Transformer }
+
+declare type TransformerFactory = (layer: Layer) => Transformer_2;
+
+declare class TransformerRegistry {
+    private factories;
+    constructor();
+    register(action: string, factory: TransformerFactory): void;
+    get(layer: Layer): Transformer_2 | null;
+}
+
+export declare const transformerRegistry: TransformerRegistry;
+
+/**
+ * Helper class to traverse AST nodes and dispatch to the visitor.
+ */
+export declare class Traverser {
+    private visitor;
+    constructor(visitor: PolagramVisitor);
+    traverse(root: PolagramRoot): void;
+    /**
+     * Dispatches a single event node to the appropriate visitor method.
+     * This is public so Visitors can call it recursively (e.g. inside Fragments/Groups).
+     */
+    dispatchEvent(node: EventNode): void;
+    /**
+     * Helper to iterate over a list of events.
+     */
+    dispatchEvents(events: EventNode[]): void;
+}
+
+export declare class UnusedCleaner {
+    transform(root: PolagramRoot): PolagramRoot;
+    private collectUsedParticipants;
+}
+
+/**
+ * Validates the input object against the Polagram Config Schema.
+ * Throws a formatted error message if validation fails.
+ */
+export declare function validateConfig(input: unknown): PolagramConfig;
+
+/**
+ * Type Guard to validate if an object is a valid Lens.
+ * Acts as an Anti-Corruption Layer.
+ */
+export declare function validateLens(lens: unknown): lens is Lens;
+
+/**
+ * Abstract base class for tree transformations.
+ * Implements the "Updating Visitor" pattern with Copy-on-Write immutability.
+ *
+ * Subclasses should override `visitEvent` to apply specific logic.
+ */
+declare abstract class Walker {
+    transform(root: PolagramRoot): PolagramRoot;
+    protected mapEvents(events: EventNode[]): EventNode[];
+    protected visitEvent(node: EventNode): EventNode[];
+    protected visitFragment(node: FragmentNode): EventNode[];
+    protected visitBranch(branch: FragmentBranch): FragmentBranch;
+}
+
+export { }