agency-lang 0.12.0 → 0.13.0

package/dist/lib/backends/agencyGenerator.d.ts

@@ -1,8 +1,25 @@
-import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, Comprehension, DebuggerStatement, Hole, InterruptStatement, Literal, NewLine, ObjectTypeTrivia, ParallelBlock, Scope, SeqBlock, TypeAlias, VariableType } from "../types.js";
+import { AgencyComment, AgencyMultiLineComment, AgencyNode, AgencyProgram, Assignment, Comprehension, DebuggerStatement, Hole, InterruptStatement, Literal, NewLine, ParallelBlock, Scope, SeqBlock, TypeAlias, VariableType } from "../types.js";
+import { LineComment } from "../types/base.js";
+import { ListTrivia, TriviaNode } from "../types/dataStructures.js";
+/** One rendered list item. `leadingLines` are whole lines that print above
+ *  it (an object-type property's `@validate` tags); the shared renderer
+ *  indents them, so callers hand back plain text. */
+type RenderedListItem = {
+    leadingLines?: string[];
+    code: string;
+};
+type RenderListWithTriviaOptions<T> = {
+    items: T[];
+    trivia: ListTrivia[] | undefined;
+    open: string;
+    close: string;
+    renderItem: (item: T, index: number) => RenderedListItem;
+    separator: (index: number, itemCount: number) => string;
+};
 import { AccessChainElement, ValueAccess } from "../types/access.js";
 import { CodeLiteral } from "../types/codeLiteral.js";
 import { BlockArgument } from "../types/blockArgument.js";
-import { AgencyArray, AgencyObject, Trivia } from "../types/dataStructures.js";
+import { AgencyArray, AgencyObject } from "../types/dataStructures.js";
 import { FunctionCall, FunctionDefinition } from "../types/function.js";
 import { GraphNodeDefinition } from "../types/graphNode.js";
 import { IfElse } from "../types/ifElse.js";
@@ -25,6 +42,7 @@ import { GuardBlock } from "../types/guardBlock.js";
 import { Tag } from "../types/tag.js";
 import { NewExpression } from "../types/newExpression.js";
 import { BindingPattern, MatchPattern } from "../types/pattern.js";
+type TypeRenderPolicy = "source" | "display";
 export declare function escapeStringText(s: string, delim: '"' | "'" | "`"): string;
 export declare class AgencyGenerator {
     protected graphNodes: GraphNodeDefinition[];
@@ -111,13 +129,34 @@ export declare class AgencyGenerator {
     private increaseIndent;
     private decreaseIndent;
     private indentStr;
+    /** `renderItems` is a callback, not an array, because a multi-line item has
+     *  to be built at the depth it will actually print at. Rewriting an
+     *  already-rendered item's lines instead would reach inside triple-quoted
+     *  strings, whose newlines are data rather than layout, and silently change
+     *  the program. So the items are rendered once to measure, and rendered
+     *  again after the indent increases if the list turns out to wrap. */
     private wrapList;
     private renderParams;
+    private renderTypeSource;
+    private renderTypeDisplay;
+    private objectTypeHasPropertyMetadata;
+    private renderType;
     private stringifyProp;
-    protected emitTriviaAt(trivia: (ObjectTypeTrivia | Trivia)[] | undefined, anchorIndex: number, lines: string[]): void;
-    protected aliasedTypeToString(aliasedType: VariableType): string;
+    /** One trivia node as its own source line. */
+    protected renderTriviaNode(node: TriviaNode): string;
+    /** Comments that print on their own line ABOVE item `anchorIndex`. */
+    protected beforeTriviaAt(trivia: ListTrivia[] | undefined, anchorIndex: number): TriviaNode[];
+    /** Comments that print at the END of item `anchorIndex`'s line. */
+    protected trailingTriviaAt(trivia: ListTrivia[] | undefined, anchorIndex: number): LineComment[];
+    /** Render one multiline list, owning indentation and both comment
+     *  placements. Callers supply how to render an item and where separators
+     *  go; they must not place comments themselves. */
+    protected renderListWithTrivia<T>(args: RenderListWithTriviaOptions<T>): string;
+    protected aliasedTypeToString(aliasedType: VariableType, policy: TypeRenderPolicy): string;
+    private renderObjectTypeSource;
     protected processEffectDeclaration(node: EffectDeclaration): string;
     protected processTypeAlias(node: TypeAlias): string;
+    private composeTypeAliasAssignment;
     /**
      * Format the `<T, U = string, ...>` chunk of a generic alias declaration.
      * Returns an empty string when there are no type params.
@@ -181,13 +220,32 @@ export declare class AgencyGenerator {
      *  node and stripping keywords, so all three kinds share one canonical
      *  signature path. */
     signatureOf(node: FunctionDefinition | GraphNodeDefinition | TypeAlias): string;
+    /** Render the annotations that precede a type alias declaration. */
+    declarationAnnotationPrefixOf(node: TypeAlias): string;
     protected processFunctionDefinition(node: FunctionDefinition): string;
     protected processFunctionCall(node: FunctionCall): string;
     protected renderArgs(args: FunctionCall["arguments"], block?: BlockArgument): string[];
-    protected renderArgList(args: FunctionCall["arguments"], block?: BlockArgument): string;
+    /** A list of already-rendered items laid out across lines with its
+     *  comments, or `undefined` when there are none. Callers keep their own
+     *  inline or wrapping behavior for the no-comment case, so trivia-free
+     *  output is untouched; a comment cannot share a line with what follows
+     *  it, so its presence forces the multiline form. */
+    protected renderListIfTrivia(rendered: string[], trivia: ListTrivia[] | undefined, open: string, close: string): string | undefined;
+    /** The one way a parenthesized `( ... )` list is printed. Without trivia
+     *  it keeps `wrapList`'s compact/wrapping behavior exactly; with trivia it
+     *  goes multiline. `rendered` must already be in canonical print order —
+     *  for a call that means `renderArgs` has appended any inline block last,
+     *  matching how `extractInlineBlock` remapped the anchors. */
+    protected renderParenList(renderItems: () => string[], trivia: ListTrivia[] | undefined, prefix: string, suffix: string): string;
+    /** A parenthesized argument list that normally stays on one line
+     *  (access chains, `interrupt`, `guard`). Trivia forces the multiline
+     *  form, since a `//` comment cannot share a line with what follows it. */
+    protected renderArgList(args: FunctionCall["arguments"], block?: BlockArgument, trivia?: ListTrivia[]): string;
     protected generateFunctionCallExpression(node: FunctionCall, context: "valueAccess" | "functionArg" | "topLevelStatement"): string;
     protected processAgencyArray(node: AgencyArray): string;
+    private renderArrayItem;
     protected processAgencyObject(node: AgencyObject): string;
+    private renderObjectEntry;
     private addQuotesToKey;
     protected processValueAccess(node: ValueAccess): string;
     /** Print `[| ... |]`. An expr-kind body that fits one line prints
@@ -200,6 +258,10 @@ export declare class AgencyGenerator {
     protected processCodeLiteral(node: CodeLiteral): string;
     protected asyncAwaitPrefix(code: string, async?: boolean): string;
     protected processMatchBlock(node: MatchBlock): string;
+    /** One arm, without its final newline — a complete construct an
+     *  attached comment can follow. */
+    private renderInlineMatchArm;
+    private renderBlockMatchArm;
     /** Whether a one-statement arm body may print inline (`=> stmt`)
      *  rather than as a `{ ... }` block.
      *
@@ -223,12 +285,21 @@ export declare class AgencyGenerator {
     protected formatIfExpression(node: IfElse): string;
     protected processGotoStatement(node: GotoStatement): string;
     protected processDebuggerStatement(node: DebuggerStatement): string;
+    /** The sole owner of line-comment source text. Do not rebuild
+     *  `//${content}` anywhere else. */
+    protected commentText(comment: LineComment): string;
     protected processComment(node: AgencyComment): string;
+    /** Place an attached comment after already-rendered code. Empty code has
+     *  no construct to attach to, so the comment is left to its owner. */
+    protected appendTrailingComment(code: string, comment: LineComment | undefined): string;
     protected processMultiLineComment(node: AgencyMultiLineComment): string;
     protected formatDocComment(node: {
         docComment?: AgencyMultiLineComment;
     }): string;
     protected processImportStatement(node: ImportStatement): string;
+    /** The names inside an import's `{ ... }`, with their aliases and
+     *  retry-safety markers. Shared by the sole-named and mixed paths. */
+    private renderImportNames;
     protected processImportNameType(node: ImportNameType): string;
     /** Render an imported/re-exported name with its `destructive` or
      *  `idempotent` prefix. A name carries at most one marker. */
@@ -280,3 +351,4 @@ export declare function generateAgency(program: AgencyProgram, opts?: {
  * NOT `expressionToString` (lib/utils/node.ts), which drops string quotes.
  */
 export declare function generateExpression(expr: AgencyNode): string;
+export {};