Doc: the new CFG (#1631)

* doc(cfg): up to the discussion of vertex types

* doc(cfg): basic blocks how to

* doc(cfg): basic traversal, sructure

* doc(cfg): basic expl for the syntax aware visitor

* doc(dfg): improve general documentation

* perf(cfg): minor improvements to manipulation functions

* doc(dfg): origin function

* feat(cfg): semantic visitor draft

* feat(cfg): semantic visitor

Author: EagleoutIce

src/cli/repl/commands/repl-cfg.ts

@@ -5,6 +5,10 @@ import { fileProtocol, requestFromInput } from '../../../r-bridge/retriever';
 import { cfgToMermaid, cfgToMermaidUrl } from '../../../util/mermaid/cfg';
 import type { KnownParser } from '../../../r-bridge/parser';
 import { ColorEffect, Colors, FontStyles } from '../../../util/text/ansi';
+import type { ControlFlowInformation } from '../../../control-flow/control-flow-graph';
+import type { NormalizedAst } from '../../../r-bridge/lang-4.x/ast/model/processing/decorate';
+import type { CfgSimplificationPassName } from '../../../control-flow/cfg-simplification';
+import { DefaultCfgSimplificationOrder } from '../../../control-flow/cfg-simplification';
 
 async function controlflow(parser: KnownParser, remainingLine: string) {
 	return await createDataflowPipeline(parser, {
@@ -20,40 +24,60 @@ function formatInfo(out: ReplOutput, type: string): string {
 	return out.formatter.format(`Copied ${type} to clipboard.`, { color: Colors.White, effect: ColorEffect.Foreground, style: FontStyles.Italic });
 }
 
+
+async function produceAndPrintCfg(shell: KnownParser, remainingLine: string, output: ReplOutput, simplifications: readonly CfgSimplificationPassName[], cfgConverter: (cfg: ControlFlowInformation, ast: NormalizedAst) => string) {
+	const result = await controlflow(shell, handleString(remainingLine));
+
+	const cfg = extractCFG(result.normalize, result.dataflow.graph, [...DefaultCfgSimplificationOrder, ...simplifications]);
+	const mermaid = cfgConverter(cfg, result.normalize);
+	output.stdout(mermaid);
+	try {
+		const clipboard = await import('clipboardy');
+		clipboard.default.writeSync(mermaid);
+		output.stdout(formatInfo(output, 'mermaid code'));
+	} catch{ /* do nothing this is a service thing */
+	}
+}
+
 export const controlflowCommand: ReplCommand = {
 	description:  `Get mermaid code for the control-flow graph of R code, start with '${fileProtocol}' to indicate a file`,
 	usageExample: ':controlflow',
 	aliases:      [ 'cfg', 'cf' ],
 	script:       false,
 	fn:           async(output, shell, remainingLine) => {
-		const result = await controlflow(shell, handleString(remainingLine));
-
-		const cfg = extractCFG(result.normalize, result.dataflow.graph);
-		const mermaid = cfgToMermaid(cfg, result.normalize);
-		output.stdout(mermaid);
-		try {
-			const clipboard = await import('clipboardy');
-			clipboard.default.writeSync(mermaid);
-			output.stdout(formatInfo(output, 'mermaid code'));
-		} catch{ /* do nothing this is a service thing */ }
+		await produceAndPrintCfg(shell, remainingLine, output, [], cfgToMermaid);
 	}
 };
 
+
 export const controlflowStarCommand: ReplCommand = {
 	description:  'Returns the URL to mermaid.live',
 	usageExample: ':controlflow*',
 	aliases:      [ 'cfg*', 'cf*' ],
 	script:       false,
 	fn:           async(output, shell, remainingLine) => {
-		const result = await controlflow(shell, handleString(remainingLine));
-
-		const cfg = extractCFG(result.normalize, result.dataflow.graph);
-		const mermaid = cfgToMermaidUrl(cfg, result.normalize);
-		output.stdout(mermaid);
-		try {
-			const clipboard = await import('clipboardy');
-			clipboard.default.writeSync(mermaid);
-			output.stdout(formatInfo(output, 'mermaid url'));
-		} catch{ /* do nothing this is a service thing */ }
+		await produceAndPrintCfg(shell, remainingLine, output, [], cfgToMermaidUrl);
+	}
+};
+
+
+export const controlflowBBCommand: ReplCommand = {
+	description:  `Get mermaid code for the control-flow graph with basic blocks, start with '${fileProtocol}' to indicate a file`,
+	usageExample: ':controlflowbb',
+	aliases:      [ 'cfgb', 'cfb' ],
+	script:       false,
+	fn:           async(output, shell, remainingLine) => {
+		await produceAndPrintCfg(shell, remainingLine, output, ['to-basic-blocks'], cfgToMermaid);
+	}
+};
+
+
+export const controlflowBBStarCommand: ReplCommand = {
+	description:  'Returns the URL to mermaid.live',
+	usageExample: ':controlflowbb*',
+	aliases:      [ 'cfgb*', 'cfb*' ],
+	script:       false,
+	fn:           async(output, shell, remainingLine) => {
+		await produceAndPrintCfg(shell, remainingLine, output, ['to-basic-blocks' ], cfgToMermaidUrl);
 	}
 };

src/cli/repl/commands/repl-commands.ts

@@ -12,7 +12,7 @@ import {
 	dataflowSimplifiedCommand,
 	dataflowStarCommand
 } from './repl-dataflow';
-import { controlflowCommand, controlflowStarCommand } from './repl-cfg';
+import { controlflowBBCommand, controlflowBBStarCommand, controlflowCommand, controlflowStarCommand } from './repl-cfg';
 import type { OutputFormatter } from '../../../util/text/ansi';
 import { italic , bold } from '../../../util/text/ansi';
 import { splitAtEscapeSensitive } from '../../../util/text/args';
@@ -93,6 +93,8 @@ const _commands: Record<string, ReplCommand> = {
 	'dataflowsimple*': dataflowSimpleStarCommand,
 	'controlflow':     controlflowCommand,
 	'controlflow*':    controlflowStarCommand,
+	'controlflowbb':   controlflowBBCommand,
+	'controlflowbb*':  controlflowBBStarCommand,
 	'lineage':         lineageCommand,
 	'query':           queryCommand,
 	'query*':          queryStarCommand

src/cli/repl/commands/repl-dataflow.ts

@@ -23,7 +23,7 @@ function formatInfo(out: ReplOutput, type: string, timing: number): string {
 }
 
 export const dataflowCommand: ReplCommand = {
-	description:  `Get mermaid code for the dataflow graph of R code, start with '${fileProtocol}' to indicate a file`,
+	description:  `Get mermaid code for the dataflow graph, start with '${fileProtocol}' to indicate a file`,
 	usageExample: ':dataflow',
 	aliases:      [ 'd', 'df' ],
 	script:       false,
@@ -58,7 +58,7 @@ export const dataflowStarCommand: ReplCommand = {
 
 
 export const dataflowSimplifiedCommand: ReplCommand = {
-	description:  `Get simplified mermaid code for the dataflow graph of R code, start with '${fileProtocol}' to indicate a file`,
+	description:  `Get mermaid code for the simplified dataflow graph, start with '${fileProtocol}' to indicate a file`,
 	usageExample: ':dataflowsimple',
 	aliases:      [ 'ds', 'dfs' ],
 	script:       false,

src/control-flow/cfg-properties.ts

@@ -4,6 +4,9 @@ import { setMinus } from '../util/collections/set';
 import { log } from '../util/log';
 import { visitCfgInOrder, visitCfgInReverseOrder } from './simple-visitor';
 
+/**
+ * The collection of properties that can be checked on a control flow graph.
+ */
 const CfgProperties = {
 	'single-entry-and-exit': checkSingleEntryAndExit,
 	'has-entry-and-exit':    hasEntryAndExit,

src/control-flow/cfg-simplification.ts

@@ -15,7 +15,7 @@ export type CfgSimplificationPassName = keyof typeof CfgSimplificationPasses;
 
 export const DefaultCfgSimplificationOrder = [
 	'unique-cf-sets',
-	'remove-dead-code'
+	// 'remove-dead-code' // way too expensive for conventional use!
 	// basic blocks must be requested
 ] as const satisfies CfgSimplificationPassName[];
 

src/control-flow/cfg-to-basic-blocks.ts

@@ -17,7 +17,7 @@ function singleOutgoingFd(outgoing: ReadonlyMap<NodeId, CfgEdge> | undefined): N
 }
 
 /**
- * Take a control flow graph without any basic blocks and convert it to a graph with basic blocks.
+ * Take a control flow information of a graph without any basic blocks and convert it to a graph with basic blocks.
  */
 export function convertCfgToBasicBlocks(cfInfo: ControlFlowInformation): ControlFlowInformation {
 	const newCfg = wrapEveryVertexInBasicBlock(cfInfo.graph);

src/control-flow/control-flow-graph.ts

@@ -33,10 +33,18 @@ export function edgeTypeToString(type: CfgEdgeType): string {
 	}
 }
 
+/**
+ * A plain vertex in the {@link ControlFlowGraph}.
+ * Please use {@link CfgSimpleVertex} to refer to all potential vertex types within the graph.
+ */
 interface CfgBaseVertex extends MergeableRecord {
+	/** the type of the vertex */
 	type:         CfgVertexType,
+	/** the id of the vertex, for non-blocks this should directly relate to the AST node */
 	id:           NodeId,
+	/** child nodes attached to this one */
 	children?:    NodeId[],
+	/** if the vertex calls a function, this links all targets of this call */
 	callTargets?: Set<NodeId>,
 }
 
@@ -55,18 +63,19 @@ export interface CfgExpressionVertex extends CfgWithMarker {
 	type: CfgVertexType.Expression
 }
 
-export interface CfgMidMarkerVertex extends CfgBaseVertex {
+export interface CfgWithRoot extends CfgBaseVertex {
+	/** the vertex for which this is a marker */
+	root: NodeId
+}
+
+export interface CfgMidMarkerVertex extends CfgWithRoot {
 	type: CfgVertexType.MidMarker
 	// describing the separation performed by this marker
 	kind: string
-	/** the vertex for which this is a mid-marker */
-	root: NodeId
 }
 
-export interface CfgEndMarkerVertex extends CfgBaseVertex {
+export interface CfgEndMarkerVertex extends CfgWithRoot {
 	type: CfgVertexType.EndMarker
-	/** the vertex for which this is an end-marker */
-	root: NodeId,
 }
 
 export interface CfgBasicBlockVertex extends CfgBaseVertex {
@@ -101,6 +110,7 @@ interface CfgControlDependencyEdge extends MergeableRecord {
     label:  CfgEdgeType.Cd
     /** the id which caused the control dependency */
     caused: NodeId,
+	/** is the control dependency satisfied with a true condition or is it negated (e.g., else-branch)? */
     when:   typeof RTrue | typeof RFalse
 }
 
@@ -141,26 +151,28 @@ export class ControlFlowGraph<Vertex extends CfgSimpleVertex = CfgSimpleVertex>
 	addVertex(vertex: Vertex, rootVertex = true): this {
 		if(this.vertexInformation.has(vertex.id)) {
 			throw new Error(`Node with id ${vertex.id} already exists`);
-		} else if(vertex.type === CfgVertexType.Block && vertex.elems.some(e => this.bbChildren.has(e.id) || this.rootVertices.has(e.id))) {
-			throw new Error(`Vertex ${vertex.id} contains vertices that are already part of the graph`);
-		}
-		this.vertexInformation.set(vertex.id, vertex);
-		if(vertex.type === CfgVertexType.Block) {
+		} else if(vertex.type === CfgVertexType.Block) {
+			if(vertex.elems.some(e => this.bbChildren.has(e.id) || this.rootVertices.has(e.id))) {
+				throw new Error(`Vertex ${vertex.id} contains vertices that are already part of the graph`);
+			}
 			for(const elem of vertex.elems) {
 				this.bbChildren.set(elem.id, vertex.id);
 			}
 		}
+		this.vertexInformation.set(vertex.id, vertex);
+
 		if(rootVertex) {
 			this.rootVertices.add(vertex.id);
 		}
 		return this;
 	}
 
 	addEdge(from: NodeId, to: NodeId, edge: CfgEdge): this {
+		const edgesFrom = this.edgeInformation.get(from) ?? new Map<NodeId, CfgEdge>();
 		if(!this.edgeInformation.has(from)) {
-			this.edgeInformation.set(from, new Map<NodeId, CfgEdge>());
+			this.edgeInformation.set(from, edgesFrom);
 		}
-		this.edgeInformation.get(from)?.set(to, edge);
+		edgesFrom.set(to, edge);
 		return this;
 	}
 
@@ -319,14 +331,19 @@ export class ControlFlowGraph<Vertex extends CfgSimpleVertex = CfgSimpleVertex>
 	}
 }
 
+/** Summarizes the control information of a program */
 export interface ControlFlowInformation<Vertex extends CfgSimpleVertex = CfgSimpleVertex> extends MergeableRecord {
+	/** all active 'return'(-like) unconditional jumps */
     returns:     NodeId[],
+	/** all active 'break'(-like) unconditional jumps */
     breaks:      NodeId[],
+	/** all active 'next'(-like) unconditional jumps */
     nexts:       NodeId[],
     /** intended to construct a hammock graph, with 0 exit points representing a block that should not be part of the CFG (like a comment) */
     entryPoints: NodeId[],
     /** See {@link ControlFlowInformation#entryPoints|entryPoints} */
     exitPoints:  NodeId[],
+	/** the control flow graph summarizing the flow information */
     graph:       ControlFlowGraph<Vertex>
 }
 

src/control-flow/dfg-cfg-guided-visitor.ts

@@ -1,37 +1,94 @@
-import type { ControlFlowInformation } from './control-flow-graph';
+import type { CfgExpressionVertex, CfgStatementVertex, ControlFlowInformation } from './control-flow-graph';
 import type { NodeId } from '../r-bridge/lang-4.x/ast/model/processing/node-id';
-import type {
-	NormalizedAst
-} from '../r-bridge/lang-4.x/ast/model/processing/decorate';
+
 import type { DataflowInformation } from '../dataflow/info';
-import type { SyntaxCfgGuidedVisitorConfiguration } from './syntax-cfg-guided-visitor';
-import { SyntaxGuidedCfgGuidedVisitor } from './syntax-cfg-guided-visitor';
-import type { DataflowGraphVertexArgument } from '../dataflow/graph/vertex';
+import type {
+	DataflowGraphVertexArgument, DataflowGraphVertexFunctionCall, DataflowGraphVertexFunctionDefinition,
+	DataflowGraphVertexUse,
+	DataflowGraphVertexValue, DataflowGraphVertexVariableDefinition } from '../dataflow/graph/vertex';
+import { VertexType
+} from '../dataflow/graph/vertex';
+import type { BasicCfgGuidedVisitorConfiguration } from './basic-cfg-guided-visitor';
+import { BasicCfgGuidedVisitor } from './basic-cfg-guided-visitor';
+import { assertUnreachable } from '../util/assert';
 
 export interface DataflowCfgGuidedVisitorConfiguration<
 	Cfg extends ControlFlowInformation = ControlFlowInformation,
-	Ast extends NormalizedAst          = NormalizedAst,
 	Dfg extends DataflowInformation    = DataflowInformation
-> extends SyntaxCfgGuidedVisitorConfiguration<Cfg, Ast> {
+> extends BasicCfgGuidedVisitorConfiguration<Cfg> {
 	readonly dataflow: Dfg;
 }
 
 /**
- * This visitor extends on the {@link SyntaxGuidedCfgGuidedVisitor} by dispatching visitors based on the AST type of the node.
+ * This visitor extends on the {@link BasicCfgGuidedVisitor} by dispatching visitors based on the dataflow graph.
  *
  * Use {@link BasicCfgGuidedVisitor#start} to start the traversal.
  */
 export class DataflowAwareCfgGuidedVisitor<
     Cfg extends ControlFlowInformation = ControlFlowInformation,
-	Ast extends NormalizedAst          = NormalizedAst,
 	Dfg extends DataflowInformation    = DataflowInformation,
-	Config extends DataflowCfgGuidedVisitorConfiguration<Cfg, Ast, Dfg> = DataflowCfgGuidedVisitorConfiguration<Cfg, Ast, Dfg>
-> extends SyntaxGuidedCfgGuidedVisitor<Cfg, Ast, Config> {
+	Config extends DataflowCfgGuidedVisitorConfiguration<Cfg, Dfg> = DataflowCfgGuidedVisitorConfiguration<Cfg, Dfg>
+> extends BasicCfgGuidedVisitor<Cfg, Config> {
 
 	/**
-	 * Get the normalized AST node for the given id or fail if it does not exist.
+	 * Get the dataflow graph vertex for the given id
 	 */
 	protected getDataflowGraph(id: NodeId): DataflowGraphVertexArgument | undefined {
 		return this.config.dataflow.graph.getVertex(id);
 	}
+
+
+	protected override onStatementNode(node: CfgStatementVertex): void {
+		super.onStatementNode(node);
+		this.onExprOrStmtNode(node);
+	}
+
+	protected override onExpressionNode(node: CfgExpressionVertex): void {
+		super.onExpressionNode(node);
+		this.onExprOrStmtNode(node);
+	}
+
+	private onExprOrStmtNode(node: CfgStatementVertex | CfgExpressionVertex): void {
+		const dfgVertex = this.getDataflowGraph(node.id);
+		if(!dfgVertex) {
+			return;
+		}
+
+		const tag = dfgVertex.tag;
+		switch(tag) {
+			case VertexType.Use:
+				this.visitVariableUse(dfgVertex);
+				break;
+			case VertexType.VariableDefinition:
+				this.visitVariableDefinition(dfgVertex);
+				break;
+			case VertexType.FunctionDefinition:
+				this.visitFunctionDefinition(dfgVertex);
+				break;
+			case VertexType.FunctionCall:
+				this.visitFunctionCall(dfgVertex);
+				break;
+			case VertexType.Value:
+				this.visitValue(dfgVertex);
+				break;
+			default:
+				assertUnreachable(tag);
+		}
+	}
+
+	protected visitValue(_val: DataflowGraphVertexValue): void {
+	}
+
+	protected visitVariableUse(_use: DataflowGraphVertexUse): void {
+	}
+
+	protected visitVariableDefinition(_def: DataflowGraphVertexVariableDefinition): void {
+	}
+
+	protected visitFunctionDefinition(_def: DataflowGraphVertexFunctionDefinition): void {
+	}
+
+	protected visitFunctionCall(_call: DataflowGraphVertexFunctionCall): void {
+	}
+
 }