### Get Configuration Instance Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Example of how to retrieve the singleton configuration object and access its properties.

```typescript
const config = Configuration.getInstance();
console.log(config.diagramTool); // "graphviz"
console.log(config.mode);        // "json"
```

--------------------------------

### ArgumentProcessor - getConfig Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Example demonstrating how to instantiate ArgumentProcessor with custom configuration and retrieve the validated RuntimeConfig.

```typescript
const processor = new ArgumentProcessor({
  diagramTool: DiagramTool.MERMAID,
  mode: Mode.JSON,
  filePath: ["/path/to/flow.flow-meta.xml"],
  outputDirectory: "./output",
  outputFileName: "diagram",
});

const config = processor.getConfig();
// Returns validated RuntimeConfig
```

--------------------------------

### GitHub Actions Workflow Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

Example GitHub Actions workflow to generate and post flow diagrams during a pull request. This workflow requires checkout, Deno setup, and specific permissions.

```yaml
name: Generate Flow Diagrams

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  flow-diagrams:
    permissions: write-all
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 2
      
      - name: Set up Deno
        uses: denoland/setup-deno@v2
        with:
          deno-version: latest
      
      - name: Generate and post flow diagrams
        run: |
          deno run \
            --allow-read \
            --allow-write \
            --allow-env \
            --allow-net \
            --allow-run \
            jsr:@goog/flow-lens \
            --mode="github_action" \
            --diagramTool="mermaid" \
            --gitDiffFromHash="HEAD^1" \
            --gitDiffToHash="HEAD"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### FlowToUmlTransformer Constructor Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-transformer.md

Example of how to instantiate the FlowToUmlTransformer with necessary dependencies like UmlGeneratorContext and FlowFileChangeDetector.

```typescript
import { FlowToUmlTransformer } from "./flow_to_uml_transformer.ts";
import { UmlGeneratorContext } from "./uml_generator_context.ts";
import { DiagramTool } from "./argument_processor.ts";

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const changeDetector = new FlowFileChangeDetector();

const transformer = new FlowToUmlTransformer(
  ["/path/to/flow1.flow-meta.xml", "/path/to/flow2.flow-meta.xml"],
  context,
  changeDetector
);
```

--------------------------------

### Mermaid State Diagram Syntax Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Example of the output format for a Mermaid state diagram generated by MermaidGenerator. Includes definitions for classes, nodes, and transitions.

```mermaid
---
title: "Flow Label"
---
stateDiagram-v2

  classDef pink fill:#F9548A, color:white
  classDef orange fill:#DD7A00, color:white
  classDef navy fill:#344568, color:white
  classDef blue fill:#1B96FF, color:white
  classDef modified stroke-width: 5px, stroke: orange
  classDef added stroke-width: 5px, stroke: green
  classDef deleted stroke-width: 5px, stroke: red

  state "Node Label" as node_id
  class node_id pink
  node_id --> other_node_id
  other_node_id --> node_id : Label
```

--------------------------------

### GithubClient Constructor Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

Demonstrates how to instantiate the GithubClient. Requires a GitHub token for authentication. Optionally accepts a GitHub Actions context.

```typescript
import { GithubClient } from "./github_client.ts";

const client = new GithubClient(Deno.env.get("GITHUB_TOKEN") || "");
```

--------------------------------

### PlantUML Output Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

An example of the PlantUML syntax generated by PlantUmlGenerator for representing a flow diagram.

```plantuml
@startuml FlowName
!include <C4/C4_Component>

state "Node Label" as node_id #F9548A
state "Other Node" as other_node_id

node_id --> other_node_id
other_node_id --> node_id : Transition

@enduml
```

--------------------------------

### Accessing Runtime Configuration

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Demonstrates how to get a singleton instance of the Configuration class and access its properties at runtime.

```typescript
import { Configuration } from "./argument_processor.ts";

const config = Configuration.getInstance();
console.log(config.diagramTool);      // "mermaid"
console.log(config.mode);              // "json"
console.log(config.outputFileName);    // "diagrams"
console.log(config.filePath);          // ["/path/to/flow.xml"]
```

--------------------------------

### Flow Lens JSON Mode Usage Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Demonstrates how to run Flow Lens in JSON output mode using specific file paths. This example includes necessary Deno flags and CLI arguments for reading and writing files.

```typescript
// Command line
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  --mode="json" \
  --diagramTool="graphviz" \
  --filePath="/path/to/flow1.flow-meta.xml" \
  --filePath="/path/to/flow2.flow-meta.xml" \
  --outputDirectory="." \
  --outputFileName="diagrams"
```

--------------------------------

### transformToUmlDiagrams Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-transformer.md

Example demonstrating how to call transformToUmlDiagrams and iterate over the results, logging the file path and the lengths of the old and new diagrams.

```typescript
const transformer = new FlowToUmlTransformer(filePaths, context, changeDetector);
const results = await transformer.transformToUmlDiagrams();

for (const [filePath, difference] of results) {
  console.log(`File: ${filePath}`);
  console.log(`New diagram length: ${difference.new.length}`);
  if (difference.old) {
    console.log(`Old diagram length: ${difference.old.length}`);
  }
}
```

--------------------------------

### UmlGeneratorContext Example Usage

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

An example demonstrating how to instantiate UmlGeneratorContext and use its generate method to create a UML diagram.

```typescript
import { UmlGeneratorContext } from "./uml_generator_context.ts";
import { DiagramTool } from "./argument_processor.ts";

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const umlString = context.generate(parsedFlow);
```

--------------------------------

### Graphviz DOT Output Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

An example of the DOT language syntax generated by GraphvizGenerator for representing a flow diagram.

```dot
digraph FlowName {
  node [shape=box, style=filled, fontname=Courier];
  
  node_id [label="Node Label", fillcolor="#F9548A"];
  other_node_id [label="Other Node"];
  
  node_id -> other_node_id;
  other_node_id -> node_id [label="Transition"];
}
```

--------------------------------

### Flow Lens GitHub Action Mode Usage Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Illustrates how to execute Flow Lens within a GitHub Actions environment. This example uses relevant Deno flags and CLI arguments for integration into CI/CD pipelines.

```typescript
// Command line (in GitHub Actions)
deno run \
  --allow-read \
  --allow-write \
  --allow-env \
  --allow-net \
  --allow-run \
  jsr:@goog/flow-lens \
  --mode="github_action" \
  --diagramTool="mermaid" \
  --gitDiffFromHash="HEAD^1" \
  --gitDiffToHash="HEAD"
```

--------------------------------

### JSON Output Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/README.md

Example of the output when Flow Lens is run in JSON mode. This format is useful for programmatic consumption of flow differences.

```json
[
  {
    "path": "force-app/main/default/flows/MyFlow.flow-meta.xml",
    "difference": {
      "old": "stateDiagram-v2\n  state ...",
      "new": "stateDiagram-v2\n  state ..."
    }
  }
]
```

--------------------------------

### Generate Multiple UML Formats Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Demonstrates generating diagrams in both Mermaid and Graphviz formats using separate UmlGeneratorContext instances.

```typescript
const context_mermaid = new UmlGeneratorContext(DiagramTool.MERMAID);
const context_graphviz = new UmlGeneratorContext(DiagramTool.GRAPH_VIZ);

const mermaidDiagram = context_mermaid.generate(parsedFlow);
const graphvizDiagram = context_graphviz.generate(parsedFlow);

console.log("=== Mermaid ===");
console.log(mermaidDiagram);
console.log("\n=== Graphviz ===");
console.log(graphvizDiagram);
```

--------------------------------

### Instantiate and Execute Runner

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-main.md

Example of how to instantiate the Runner class and call its execute method to begin the flow-to-UML transformation process.

```typescript
const runner = new Runner();
await runner.execute();
```

--------------------------------

### FlowParser Constructor Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-flow-parser.md

Instantiates the FlowParser with the raw XML content of a Salesforce Flow definition.

```typescript
const xmlContent = `<?xml version="1.0"?>
<Flow>
  <label>My Flow</label>
  <fullName>My_Flow</fullName>
  ...
</Flow>`;

const parser = new FlowParser(xmlContent);
```

--------------------------------

### Process Multiple Flows with Mermaid Output

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-transformer.md

This example demonstrates how to process multiple flow files and generate Mermaid-formatted UML diagrams. Ensure necessary imports and context are set up.

```typescript
import { FlowToUmlTransformer } from "./flow_to_uml_transformer.ts";
import { UmlGeneratorContext } from "./uml_generator_context.ts";
import { DiagramTool } from "./argument_processor.ts";

const filePaths = [
  "./flows/Flow1.flow-meta.xml",
  "./flows/Flow2.flow-meta.xml",
];

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const changeDetector = new FlowFileChangeDetector();

const transformer = new FlowToUmlTransformer(
  filePaths,
  context,
  changeDetector
);

const results = await transformer.transformToUmlDiagrams();

// results is a Map<string, FlowDifference>
results.forEach((diff, path) => {
  console.log(`${path}:`);
  console.log(diff.new);
});
```

--------------------------------

### Type-Safe Flow Processing Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/types.md

Demonstrates how to use the defined flow types for type-safe processing of decisions and record lookups. This example shows iterating through decisions and their rules, and logging details of record lookups.

```typescript
import * as flowTypes from "./flow_types.ts";

function processDecisions(decisions: flowTypes.FlowDecision[] | undefined) {
  if (!decisions) return;
  
  for (const decision of decisions) {
    console.log(`Decision: ${decision.label}`);
    
    for (const rule of decision.rules) {
      console.log(`  Rule: ${rule.label}`);
      
      for (const condition of rule.conditions) {
        console.log(`    ${condition.leftValueReference} ${condition.operator} ...`);
      }
    }
  }
}

function processRecordLookups(lookups: flowTypes.FlowRecordLookup[] | undefined) {
  if (!lookups) return;
  
  for (const lookup of lookups) {
    console.log(`Lookup: ${lookup.label}`);
    console.log(`  Object: ${lookup.object}`);
    console.log(`  Fields: ${lookup.queriedFields.join(", ")}`);
  }
}
```

--------------------------------

### Generate Mermaid Diagram Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Example code for generating a Mermaid diagram from an XML flow definition using FlowParser and UmlGeneratorContext.

```typescript
import { FlowParser } from "./flow_parser.ts";
import { UmlGeneratorContext } from "./uml_generator_context.ts";
import { DiagramTool } from "./argument_processor.ts";

const xmlContent = Deno.readTextFileSync("./flow.flow-meta.xml");
const parsedFlow = await new FlowParser(xmlContent).generateFlowDefinition();

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const mermaidDiagram = context.generate(parsedFlow);

console.log(mermaidDiagram);
```

--------------------------------

### Flow Lens Markdown Mode with Git Diff Usage Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Shows how to use Flow Lens in Markdown output mode with Git diff capabilities. This example specifies Git commit hashes and a repository path for generating diagrams from changes.

```typescript
// Command line
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  --mode="markdown" \
  --diagramTool="mermaid" \
  --gitDiffFromHash="HEAD~1" \
  --gitDiffToHash="HEAD" \
  --gitRepo="/path/to/repo" \
  --outputDirectory="./flow-diagrams"
```

--------------------------------

### Markdown Output Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/README.md

Example of the output when Flow Lens is run in Markdown mode. Each flow generates a separate markdown file with embedded Mermaid diagrams for old and new versions.

```markdown
## Old Version

```mermaid
stateDiagram-v2
  [diagram]
```

## New Version

```mermaid
stateDiagram-v2
  [diagram]
```
```

--------------------------------

### JSON Mode Output Example

Source: https://github.com/google/flow-lens/blob/main/README.md

This JSON output details the paths of flows and their old/new UML strings when using JSON mode.

```json
[
  {
    "path": "force-app/main/default/flows/ArticleSubmissionStatus.flow-meta.xml",
    "difference": {
      "old": "UML_STRING_HERE",
      "new": "UML_STRING_HERE"
    }
  },
  {
    "path": "force-app/main/default/flows/LeadConversionScreen.flow-meta.xml",
    "difference": {
      "old": "UML_STRING_HERE",
      "new": "UML_STRING_HERE"
    }
  }
]
```

--------------------------------

### Specify Git Diff Start Commit

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Define the starting commit hash for a Git diff range. Must be used with `--gitDiffToHash` or `--to`. Special values like HEAD and commit SHAs are supported.

```bash
--gitDiffFromHash="HEAD~1"
# or
--from HEAD^1
```

--------------------------------

### Write Review Comment Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

Shows how to post a new review comment on the current pull request using the `writeComment` method. Ensure the `GITHUB_TOKEN` environment variable is set with write permissions.

```typescript
const comment: GithubComment = {
  commit_id: "abc123def456...",
  path: "force-app/main/default/flows/MyFlow.flow-meta.xml",
  subject_type: "file",
  body: "Check the flow diagram changes",
};

await client.writeComment(comment);
```

--------------------------------

### Configuration Singleton - Get Instance

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Provides access to the singleton RuntimeConfig instance. Creates a new instance on first call by invoking ArgumentProcessor.getConfig().

```typescript
class Configuration {
  static getInstance(): RuntimeConfig
}
```

--------------------------------

### Flow Start Node Type Definition

Source: https://github.com/google/flow-lens/blob/main/_autodocs/types.md

Defines the structure for the start node of a flow, including its trigger type, filters, and entry criteria.

```typescript
interface FlowStart extends FlowNode {
  capabilityTypes?: FlowCapability[];
  connector: FlowConnector;
  doesRequireRecordChangedToMeetCriteria?: boolean;
  entryType?: FlowEntryType;
  filterFormula?: string;
  filterLogic?: string;
  filters?: FlowRecordFilter[];
  flowRunAsUser?: string;
  form?: string;
  object?: string;
  publishSegment?: boolean;
  recordTriggerType?: RecordTriggerType;
  schedule?: FlowSchedule;
  scheduledPaths?: FlowScheduledPath[];
  segment?: string;
  timeZoneSidKey?: string;
  triggerType?: FlowTriggerType;
}

enum FlowTriggerType {
  CAPABILITY = "Capability",
  DATA_CLOUD_DATA_CHANGE = "DataCloudDataChange",
  EVENT_DRIVEN_JOURNEY = "EventDrivenJourney",
  PLATFORM_EVENT = "PlatformEvent",
  RECORD_AFTER_SAVE = "RecordAfterSave",
  RECORD_BEFORE_DELETE = "RecordBeforeDelete",
  RECORD_BEFORE_SAVE = "RecordBeforeSave",
  SCHEDULED = "Scheduled",
  SCHEDULED_JOURNEY = "ScheduledJourney",
  SEGMENT = "Segment",
}

enum RecordTriggerType {
  CREATE = "Create",
  DELETE = "Delete",
  UPDATE = "Update",
  NONE = "None",
  CREATE_AND_UPDATE = "CreateAndUpdate",
}
```

--------------------------------

### generateFlowDefinition Method Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-flow-parser.md

Parses the XML and generates a ParsedFlow object, then logs its properties.

```typescript
const parser = new FlowParser(xmlContent);
const parsedFlow = await parser.generateFlowDefinition();

console.log(parsedFlow.label);           // "My Flow"
console.log(parsedFlow.transitions.length); // 5
console.log(parsedFlow.decisions?.length);  // 2
```

--------------------------------

### Error Message Example

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Illustrates the error message format when validation fails, including specific errors encountered.

```text
The following errors were encountered:
- Unsupported diagram tool: invalid
- filePath does not exist: /path/to/nonexistent.xml
- outputFileName must be alphanumeric with underscores: my-output
```

--------------------------------

### Pipeline Stage Result Flow

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-transformer.md

Illustrates the data flow through the pipeline stages, starting from a file path and progressing through parsing, version detection, UML generation, comparison, and final difference object creation.

```text
filePath
  → xmlContent
    → ParsedFlow (new)
      → ParsedFlow (old, if available) + ParsedFlow (new)
        → umlString (new)
          → (flows compared, new Flow marked with diff status)
            → umlString (old)
              → FlowDifference { old?, new }
```

--------------------------------

### Example Usage of EOL Constant

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Demonstrates using the EOL constant to write text files with correct line endings for the current platform.

```typescript
import { EOL } from "./constants.ts";

const content = `Line 1${EOL}Line 2${EOL}`;
Deno.writeTextFileSync("file.txt", content);
```

--------------------------------

### Generate UML Diagram with MermaidGenerator

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Example of using the MermaidGenerator to generate a UML diagram. The generated output is a string in Mermaid state diagram syntax.

```typescript
const generator = new MermaidGenerator();
const umlString = generator.generateDiagram(parsedFlow);
console.log(umlString); // Mermaid statediagram-v2 syntax
```

--------------------------------

### Runner execute() Method

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-main.md

The main execution method that drives the flow-to-UML transformation pipeline. It handles file retrieval, UML generation, and diagram output. Use this to start the entire process.

```typescript
async execute(): Promise<void>
```

--------------------------------

### Update Existing Comments on a Pull Request

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

This example shows how to update existing comments by first retrieving all comments for the current pull request, filtering for Flow Lens comments, deleting old ones, and then posting new ones. Ensure the GITHUB_TOKEN is available.

```typescript
const client = new GithubClient(Deno.env.get("GITHUB_TOKEN") || "");

// Get existing Flow Lens comments
const allComments = await client.getAllCommentsForPullRequest();
const flowLensComments = allComments.filter((c) =>
  c.body.includes("<!--flow-lens-hidden-comment-->")
);

// Delete old comments
for (const comment of flowLensComments) {
  await client.deleteReviewComment(comment.id);
}

// Post new comments
for (const newDiagram of newDiagrams) {
  const comment = client.translateToComment(newDiagram.body, newDiagram.path);
  await client.writeComment(comment);
}
```

--------------------------------

### Instantiate and Use XmlReader

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Demonstrates how to create an instance of XmlReader with a file path and retrieve the XML content. Logs the first 50 characters of the XML content.

```typescript
import { XmlReader } from "./xml_reader.ts";

const reader = new XmlReader("/path/to/flow.flow-meta.xml");
const xmlContent = reader.getXmlFileBody();
console.log(xmlContent.substring(0, 50)); // <?xml version="1.0"...
```

--------------------------------

### GithubClient Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

Initializes a new instance of the GithubClient. It requires a GitHub API token and optionally accepts a GitHub Actions context.

```APIDOC
## Constructor GithubClient

### Description
Initializes an Octokit client with the provided token and uses GitHub Actions context to get repository and pull request information. If not in a GitHub Actions environment, repository/PR context will be unavailable.

### Parameters
* **githubToken** (`string`) - Required - GitHub API token for authentication
* **context** (`typeof githubContext`) - Optional - GitHub Actions context (defaults to `@actions/github` context)

### Example
```typescript
import { GithubClient } from "./github_client.ts";

const client = new GithubClient(Deno.env.get("GITHUB_TOKEN") || "");
```
```

--------------------------------

### Run Flow Lens with Deno

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Basic command to run Flow Lens using Deno. Ensure necessary read and write permissions are granted.

```bash
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  [options]
```

--------------------------------

### Specify Diagram Tool Syntax

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Choose the syntax for generating diagrams. Defaults to Graphviz DOT format.

```bash
--diagramTool="mermaid"
# or
-d mermaid
```

--------------------------------

### Specify Output Mode

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Determine how output should be formatted and written. Different modes have specific requirements.

```bash
--mode="json"
# or
-m markdown
```

--------------------------------

### Run Flow Lens with JSON output and Mermaid diagrams

Source: https://github.com/google/flow-lens/blob/main/_autodocs/README.md

This command demonstrates how to run Flow Lens in JSON mode, specifying the diagram tool as Mermaid, providing an input file path, and setting output options.

```bash
deno run \
  --allow-read --allow-write \
  jsr:@goog/flow-lens \
  --mode="json" \
  --diagramTool="mermaid" \
  --filePath="./flow.flow-meta.xml" \
  --outputDirectory="." \
  --outputFileName="diagram"
```

--------------------------------

### Run Flow Lens CLI Command

Source: https://github.com/google/flow-lens/blob/main/README.md

This command executes Flow Lens to generate documentation from a Salesforce project. Specify output directory, file name, and Git parameters.

```sh
deno run \
  --allow-read \
  --allow-write \
  --allow-run \
  --allow-env \
  jsr:@goog/flow-lens \
  --mode="markdown" \
  --diagramTool="mermaid" \
  --gitRepo="/path/to/salesforce_project/" \
  --gitDiffFromHash="HEAD~1" \
  --gitDiffToHash="HEAD" \
  --outputDirectory="." \
  --outputFileName="test"

```

--------------------------------

### GitHub Actions Workflow for Generating Flow Previews

Source: https://github.com/google/flow-lens/blob/main/README.md

This YAML workflow demonstrates how to set up a GitHub Action to automatically generate and post flow diagrams as comments on pull requests using Flow Lens.

```yaml
name: Generate Flow Preview

on:
  pull_request:
    types: [opened, reopened, synchronize]

jobs:
  generate_preview:
    permissions: write-all
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
        with:
          ref: ${{ github.ref }}
          fetch-depth: 2

      - name: Set up Deno
        uses: denoland/setup-deno@v2
        with:
          deno-version: latest

      - name: Generate flow diagrams
        run: |
          deno run \
            --allow-read \
            --allow-write \
            --allow-env \
            --allow-net \
            --allow-run \
            jsr:@goog/flow-lens \
            --mode="github_action" \
            --diagramTool="mermaid" \
            --gitDiffFromHash="HEAD^1" \
            --gitDiffToHash="HEAD"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

--------------------------------

### XmlReader

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Validates and reads Salesforce Flow XML files. It provides methods to get the XML file content after performing basic file validation.

```APIDOC
## Class: XmlReader

### Description
Validates and reads Salesforce Flow XML files. It provides methods to get the XML file content after performing basic file validation.

### Module
`src/main/xml_reader.ts`

### Constructor

```typescript
constructor(filePath: string)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `filePath` | `string` | Path to the XML file to read |

### Method: getXmlFileBody()

```typescript
getXmlFileBody(): string
```

Reads and returns the complete XML file content after validation.

**Parameters:** None

**Returns:** String containing the raw XML content

**Throws:**
- Error with message `invalidFilePath` if the file does not exist or is not readable
- Error with message `invalidFileExtension` if the file does not have `.xml` extension

**Validation:**
- Checks file existence using `Deno.statSync()`
- Checks file extension (case-insensitive)
- Does not validate XML structure or content

**Example:**

```typescript
import { XmlReader } from "./xml_reader.ts";

const reader = new XmlReader("/path/to/flow.flow-meta.xml");
const xmlContent = reader.getXmlFileBody();
console.log(xmlContent.substring(0, 50)); // <?xml version="1.0"...
```
```

--------------------------------

### Specify Input File Paths

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Provide paths to Salesforce Flow XML files. This argument can be specified multiple times. It cannot be combined with Git diff options.

```bash
--filePath="/path/to/flow1.flow-meta.xml" \
--filePath="/path/to/flow2.flow-meta.xml"
```

--------------------------------

### Get Previous Flow File Version

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Retrieves the previous version of a flow file from Git using its file path. Returns undefined if the file is new.

```typescript
const detector = new FlowFileChangeDetector();

const currentXml = Deno.readTextFileSync("MyFlow.flow-meta.xml");
const previousXml = detector.getPreviousVersion("force-app/main/default/flows/MyFlow.flow-meta.xml");

if (previousXml) {
  console.log("Flow was modified");
} else {
  console.log("Flow is new");
}
```

--------------------------------

### UmlWriter Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Initializes the UmlWriter with a map of file paths to their differences and an optional GitHub client for posting comments.

```typescript
constructor(
  filePathToFlowDifference: Map<string, FlowDifference>,
  githubClient?: GithubClient
)
```

--------------------------------

### Generate JSON Diagrams from File Paths

Source: https://github.com/google/flow-lens/blob/main/README.md

Use this command to generate JSON output for UML diagrams from specified Salesforce Flow XML files. Ensure you have read and write permissions.

```shell
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  --mode="json" \
  --diagramTool="graphviz" \
  --filePath="/some/path/force-app/main/default/flows/ArticleSubmissionStatus.flow-meta.xml" \
  --filePath="/some/path/force-app/main/default/flows/LeadConversionScreen.flow-meta.xml" \
  --filePath="/some/path/force-app/main/default/flows/OpportunityClosure.flow-meta.xml" \
  --outputDirectory="." \
  --outputFileName="test"
```

--------------------------------

### Get Changed Flow Files

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Retrieves a list of Salesforce Flow files that have been modified in the current Git diff. This method relies on configuration for Git diff hashes and returns file paths relative to the repository root.

```typescript
import { FlowFileChangeDetector } from "./flow_file_change_detector.ts";
import { Configuration, ArgumentProcessor } from "./argument_processor.ts";

// Set configuration with Git diff hashes
// (normally done via command-line arguments)

const detector = new FlowFileChangeDetector();
const changedFlows = detector.getFlowFiles();

console.log(`Changed flows: ${changedFlows.join(", ")}`);
// Output: force-app/main/default/flows/MyFlow.flow-meta.xml
```

--------------------------------

### GitHub Action Output Format for UML Diagrams

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Formats UML diagrams as collapsible HTML details elements within a hidden comment for GitHub pull request reviews. Requires diagramTool: mermaid configuration.

```html
<!--flow-lens-hidden-comment-->
<details>
<summary>Click here to view a preview of the old version of this flow</summary>

```mermaid
[old UML diagram]
```
</details>

<details>
<summary>Click here to view a preview of the new version of this flow</summary>

```mermaid
[new UML diagram]
```
</details>
```

--------------------------------

### Define FlowFileChangeDetector Class

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Defines the FlowFileChangeDetector class, which is used to identify changed Salesforce Flow files in Git diffs and retrieve their previous versions. It has methods to get changed flow files and fetch a specific file's previous version.

```typescript
class FlowFileChangeDetector {
  getFlowFiles(): string[]
  getPreviousVersion(filePath: string): string | undefined
}
```

--------------------------------

### FlowParser Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-flow-parser.md

Initializes the FlowParser with the raw XML content of a Salesforce Flow definition file.

```APIDOC
## FlowParser Constructor

### Description
Initializes the FlowParser with the raw XML content of a Salesforce Flow definition file.

### Method
constructor

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **flowXml** (string) - Required - Raw XML content of a Salesforce Flow definition file

### Request Example
```typescript
const xmlContent = `<?xml version="1.0"?>
<Flow>
  <label>My Flow</label>
  <fullName>My_Flow</fullName>
  ...
</Flow>`;

const parser = new FlowParser(xmlContent);
```
```

--------------------------------

### Create and Post a Complete Comment

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

This snippet demonstrates how to create a new comment with a flow diagram and post it to a pull request. It requires initializing the GithubClient with a GITHUB_TOKEN.

```typescript
import { GithubClient } from "./github_client.ts";

const client = new GithubClient(
  Deno.env.get("GITHUB_TOKEN") || ""
);

const diagramBody = `
<details>
<summary>Flow Diagram: MyFlow</summary>

\
```mermaid
stateDiagram-v2
  [*] --> Start
  Start --> Process
  Process --> [*]
```
</details>
`;

const comment = client.translateToComment(
  diagramBody,
  "force-app/main/default/flows/MyFlow.flow-meta.xml"
);

await client.writeComment(comment);
```

--------------------------------

### ArgumentProcessor Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Initializes the ArgumentProcessor. Allows overriding Deno.args with a custom config for testing purposes.

```typescript
constructor(commandLineArguments?: RuntimeConfig)
```

--------------------------------

### Flow Lens CLI Command-Line Flags

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Lists the available command-line flags for configuring Flow Lens, including diagram tool, output mode, file paths, and Git diff options. Defaults and requirements are specified.

```plaintext
--diagramTool, -d         The diagram tool to use ('plantuml', 'graphviz', 'mermaid')
                          Default: 'graphviz'

--mode, -m                The output mode ('json', 'markdown', 'github_action')
                          Default: 'json'

--filePath, -f            Path(s) to Salesforce Flow XML files (space-separated)
                          Can be specified multiple times

--gitDiffFromHash, --from Starting commit hash for Git diff
                          Use with --gitDiffToHash

--gitDiffToHash, --to     Ending commit hash for Git diff
                          Use with --gitDiffFromHash

--gitRepo, -r             Path to Git repository (optional, defaults to current directory)

--outputDirectory, -o     Directory to save output files
                          Required for JSON and Markdown modes

--outputFileName, -n      Output file name (without extension)
                          Required for JSON mode
```

--------------------------------

### Markdown Output Format for UML Diagrams

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Generates individual Markdown files for each flow, embedding Mermaid diagrams for old and new versions. Requires outputDirectory and diagramTool: mermaid configuration.

```markdown
## Old Version

```mermaid
[old UML diagram]
```

## New Version

```mermaid
[new UML diagram]
```
```

```markdown
```mermaid
[new UML diagram]
```
```

--------------------------------

### Specify Output Directory

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Set the directory where output files will be written. This directory must exist and be writable. Required for JSON and Markdown modes.

```bash
--outputDirectory="."
# or
-o ./output
```

--------------------------------

### GitHub Action Mode Configuration

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Run Flow Lens in GitHub Action mode to post PR comments with diagrams. Requires read, write, run, environment, and network permissions. Requires GITHUB_TOKEN secret.

```bash
deno run \
  --allow-read \
  --allow-write \
  --allow-env \
  --allow-net \
  --allow-run \
  jsr:@goog/flow-lens \
  --mode="github_action" \
  --diagramTool="mermaid" \
  --gitDiffFromHash="HEAD^1" \
  --gitDiffToHash="HEAD"
```

--------------------------------

### Deno Permissions for GitHub Action Mode

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Specifies the Deno permissions required for running Flow Lens in GitHub Action mode.

```bash
--allow-read      # Read XML files
--allow-run       # Execute git commands
--allow-write     # Write temporary files
--allow-env       # Read GITHUB_TOKEN
--allow-net       # Make GitHub API calls
```

--------------------------------

### JSON Output Format for UML Diagrams

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Represents UML diagram differences in a JSON structure, suitable for file output. Requires outputDirectory and outputFileName configuration.

```json
[
  {
    "path": "force-app/main/default/flows/MyFlow.flow-meta.xml",
    "difference": {
      "old": "previous UML string",
      "new": "current UML string"
    }
  }
]
```

--------------------------------

### Specify Output File Name

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Define the base name for the JSON output file. The '.json' extension is added automatically. Only alphanumeric characters and underscores are allowed.

```bash
--outputFileName="flow_diagrams"
# or
-n diagrams
```

--------------------------------

### Run Flow Lens Tests

Source: https://github.com/google/flow-lens/blob/main/_autodocs/README.md

Execute the comprehensive test suites for Flow Lens. Ensure all necessary permissions are granted for reading, environment access, writing, and running subprocesses.

```bash
deno test --allow-read --allow-env --allow-write --allow-run
```

--------------------------------

### Deno Permissions for Markdown Mode

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Specifies the Deno permissions required for running Flow Lens in Markdown mode.

```bash
--allow-read      # Read XML files
--allow-write     # Write markdown files
```

--------------------------------

### ArgumentProcessor - GetConfig Method

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Validates all arguments and returns a RuntimeConfig object. Throws an error if validation fails.

```typescript
getConfig(): RuntimeConfig
```

--------------------------------

### Markdown Mode Configuration

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Run Flow Lens in Markdown mode to generate markdown files for diagrams. Requires read and write permissions.

```bash
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  --mode="markdown" \
  --diagramTool="mermaid" \
  --filePath="./flows/Flow1.flow-meta.xml" \
  --filePath="./flows/Flow2.flow-meta.xml" \
  --filePath="./flows/Flow3.flow-meta.xml" \
  --outputDirectory="./diagrams"
```

--------------------------------

### Generate and Compare Flow Diagrams

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Compares two flow definitions and generates UML diagrams using Mermaid. Visualizes differences with color-coded outlines for added, modified, or deleted nodes.

```typescript
import { compareFlows } from "./flow_comparator.ts";

const oldFlow = await new FlowParser(oldXml).generateFlowDefinition();
const newFlow = await new FlowParser(newXml).generateFlowDefinition();

compareFlows(oldFlow, newFlow);

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const oldDiagram = context.generate(oldFlow);
const newDiagram = context.generate(newFlow);

// oldDiagram shows deleted nodes with red outlines
// newDiagram shows added/modified nodes with green/orange outlines
```

--------------------------------

### Deno Permissions for JSON Mode

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Specifies the Deno permissions required for running Flow Lens in JSON mode with file paths.

```bash
--allow-read      # Read XML files
--allow-write     # Write JSON output file
```

--------------------------------

### JSON Mode Configuration

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Run Flow Lens in JSON mode to generate JSON output for diagrams. Requires read and write permissions.

```bash
deno run \
  --allow-read \
  --allow-write \
  jsr:@goog/flow-lens \
  --mode="json" \
  --diagramTool="graphviz" \
  --filePath="force-app/main/default/flows/MyFlow.flow-meta.xml" \
  --outputDirectory="." \
  --outputFileName="flow_diagrams"
```

--------------------------------

### Runner Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-main.md

Initializes the Runner class. It sets up internal components for detecting flow file changes and prepares collections for storing flow file data and differences.

```typescript
constructor()
```

--------------------------------

### Specify Git Repository Path

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Optionally specify the path to the Git repository. Useful when running Flow Lens outside the repository directory.

```bash
--gitRepo="/path/to/salesforce-repo"
# or
-r /home/user/projects/sfdc
```

--------------------------------

### FlowToUmlTransformer Constructor

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-transformer.md

Initializes the FlowToUmlTransformer with an array of flow file paths, a context for UML generation, and a change detector for Git diffs.

```typescript
constructor(
  filePaths: string[],
  generatorContext: UmlGeneratorContext,
  changeDetector: FlowFileChangeDetector
)
```

--------------------------------

### UmlGeneratorContext

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-uml-generators.md

Manages the instantiation and usage of different UML generators based on the selected diagram tool.

```APIDOC
## UmlGeneratorContext

### Description
Manages the instantiation and usage of different UML generators based on the selected diagram tool.

### Class Signature
```typescript
class UmlGeneratorContext {
  constructor(diagramTool: DiagramTool)
  generate(parsedFlow: ParsedFlow): string
}
```

### Constructor

```typescript
constructor(diagramTool: DiagramTool)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `diagramTool` | `DiagramTool` | Diagram tool selection (plantuml, graphviz, or mermaid) |

### Method: generate()

```typescript
generate(parsedFlow: ParsedFlow): string
```

Generates a UML diagram using the configured generator.

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `parsedFlow` | `ParsedFlow` | Parsed flow to diagram |

**Returns:** String containing the generated diagram in the selected format

**Example:**

```typescript
import { UmlGeneratorContext } from "./uml_generator_context.ts";
import { DiagramTool } from "./argument_processor.ts";

const context = new UmlGeneratorContext(DiagramTool.MERMAID);
const umlString = context.generate(parsedFlow);
```
```

--------------------------------

### Deno Permissions for Git Diff Mode

Source: https://github.com/google/flow-lens/blob/main/_autodocs/configuration.md

Specifies the Deno permissions required for running Flow Lens in Git Diff mode.

```bash
--allow-read      # Read XML files
--allow-run       # Execute git commands
--allow-write     # Write output files
```

--------------------------------

### RuntimeConfig Interface

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-configuration.md

Defines the structure of the configuration object containing validated CLI arguments.

```typescript
interface RuntimeConfig {
  diagramTool: DiagramTool;
  filePath?: string[];
  gitRepo?: string;
  gitDiffFromHash?: string;
  gitDiffToHash?: string;
  outputDirectory?: string;
  outputFileName?: string;
  mode: Mode;
}
```

--------------------------------

### UmlWriter

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-utilities.md

Writes generated UML diagrams to files or GitHub in the configured format.

```APIDOC
## UmlWriter

### Description
Writes generated UML diagrams to files or GitHub in the configured format.

### Class Signature
```typescript
class UmlWriter {
  constructor(filePathToFlowDifference: Map<string, FlowDifference>, githubClient?: GithubClient)
  async writeUmlDiagrams(): Promise<void>
}
```

#### Constructor
```typescript
constructor(
  filePathToFlowDifference: Map<string, FlowDifference>,
  githubClient?: GithubClient
)
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `filePathToFlowDifference` | `Map<string, FlowDifference>` | Map of file paths to diagram differences |
| `githubClient` | `GithubClient` (optional) | GitHub client for posting comments (auto-created if not provided) |

#### Method: writeUmlDiagrams()
```typescript
async writeUmlDiagrams(): Promise<void>
```

Writes UML diagrams using the output mode from configuration.

**Parameters:** None

**Returns:** Promise that resolves when all diagrams are written

**Example:**
```typescript
import { UmlWriter } from "./uml_writer.ts";

const differences = new Map([
  [
    "force-app/main/default/flows/MyFlow.flow-meta.xml",
    {
      old: "previous UML",
      new: "current UML",
    },
  ],
]);

const writer = new UmlWriter(differences);
await writer.writeUmlDiagrams();
```
```

--------------------------------

### New Version Flow Diagram

Source: https://github.com/google/flow-lens/blob/main/README.md

Mermaid diagram for the new version of the flow. Shows added, modified, and fault paths.

```mermaid
--- 
title: "Demo"
--- 
stateDiagram-v2

  classDef pink fill:#F9548A, color:white
  classDef orange fill:#DD7A00, color:white
  classDef navy fill:#344568, color:white
  classDef blue fill:#1B96FF, color:white
  classDef modified stroke-width: 5px, stroke: orange
  classDef added stroke-width: 5px, stroke: green
  classDef deleted stroke-width: 5px, stroke: red

  state "<b>Flow Start</b> <br> <u>Flow Start</u><hr><b>Flow Details</b><br>Process Type: AutoLaunchedFlow" as FLOW_START
  state "<span style='padding:6px;margin:6px;background-color:#FFFFFF;'><font color="green"><b>+</b></font></span><b>Assignment</b> 📝<br> <u>Set the Type</u><hr>Get_the_Acme_Account.Type = Other" as Set_the_Type
  class Set_the_Type orange added
  state "<span style='padding:6px;margin:6px;background-color:#FFFFFF;'><font color="#DD7A00"><b>Δ</b></font></span><b>Record Lookup</b> 🔍<br> <u>Get the 'Acme' Account</u><hr><b>sObject: Account</b><br>Fields Queried: all<br>Filter Logic: and<br>1. Name EqualTo Acme<br>Limit: First Record Only" as Get_the_Acme_Account
  class Get_the_Acme_Account pink modified
  state "<span style='padding:6px;margin:6px;background-color:#FFFFFF;'><font color="#DD7A00"><b>Δ</b></font></span><b>Record Update</b> ✏️<br> <u>Update the 'Acme' Account</u><hr><b>Reference Update</b><br><u>Get_the_Acme_Account</u><br>" as Update_the_Acme_Account
  class Update_the_Acme_Account pink modified
  state "<span style='padding:6px;margin:6px;background-color:#FFFFFF;'><font color="green"><b>+</b></font></span><b>Action Call</b> ⚡<br> <u>Log Error</u>" as Log_Error
  class Log_Error navy added
  state "<span style='padding:6px;margin:6px;background-color:#FFFFFF;'><font color="green"><b>+</b></font></span><b>Action Call</b> ⚡<br> <u>Log Error</u>" as Log_Error2
  class Log_Error2 navy added
  FLOW_START --> Get_the_Acme_Account
  Get_the_Acme_Account --> Set_the_Type
  Get_the_Acme_Account --> Log_Error : ❌ Fault ❌
  Set_the_Type --> Update_the_Acme_Account
  Update_the_Acme_Account --> Log_Error2 : ❌ Fault ❌

```

--------------------------------

### Translate Body and File Path to GithubComment

Source: https://github.com/google/flow-lens/blob/main/_autodocs/api-reference-github-client.md

Converts comment body and file path into a GithubComment object. Use this to prepare comments before writing them to a pull request. Requires pull request context.

```typescript
const body = `<details>
<summary>Flow Diagram</summary>

\
  stateDiagram-v2
  A --> B
\
</details>`;

const comment = client.translateToComment(
  body,
  "force-app/main/default/flows/Demo.flow-meta.xml"
);

await client.writeComment(comment);
```