CrossWayAI README

A VS Code extension that visualizes code dependencies for Progress OpenEdge ABL projects, to help developers understand project structure, navigate relationships between files and modules, and identify coupling and architectural issues. Visualize file, module, and symbol dependencies in VS Code with AI-assisted analysis. The extension uses AI to generate and update interactive dependency graphs, enabling faster code comprehension, refactoring, and architectural insights.

Features

• Automated Project Analysis: Scans your OpenEdge ABL project to discover all source files (.p, .w, .cls, .i).
• Windows/Unix support: Supports both types of operation systems VSCode workspaces
• Single/Multi-Project Workspace Support: Supports workspaces containing either single or multiple OpenEdge projects.
• Dependency Mapping: Triggers a deep analysis using an underlying ABL script to generate a dependency map.
• Proparse Support Integrated Proparse support to enable more complex code analysis in later releases
• Context Menu Integration: Access diagram generation commands directly from the editor or explorer context menus for quick analysis.
• AI support integration: Several Diagram functionalities are handled via existing AI tooling (vscode / html): Table Relations Diagram, node functional description etc.
• Multiple Diagram Types: Provides commands to generate various diagrams to visualize your application's architecture, including:
  • Impact Diagram
  • Include Diagram
  • Interface Diagram
  • Inheritance Diagram
  • Call Diagram
  • Package Diagram
  • Instance Chain Diagram
  • Property Access Diagram
  • Table Relations Diagram

Requirements

• Progress OpenEdge 11.7 - 12.8 installation.
• OpenEdge ABL VS Code extension (installed automatically with CrossWayAI)
• Java JDK installation (needed by Proparse to run)
• Workspace configuration file (.code-workspace) present in the workspace root, next to the project folders. This is the recommended layout, although storing the file in a subfolder is also supported (see Workspace Root)

AI Configuration

In order to use the integrated AI support you need to set the AI enabled = true (disabled by default) CrossWayAI supports both external AI providers (OpenAI-compatible Chat Completions APIs) and VS Code Language Models. The HTTP provider does not support native provider APIs with different endpoint shapes, such as Anthropic Claude's /v1/messages, unless they are exposed through an OpenAI-compatible proxy.

CrossWayAI AI features are grounded in the plain text files in your workspace. For example, AI node summaries read the selected ABL source file (.p, .w, .cls, or .i) as text and send it directly to the configured AI provider for a functional summary. The Table Relations Diagram works differently: it hands a prompt to the VS Code Chat agent, which reads the dumped .df schema text created by CrossWayAI: Dump All DB Definitions. That schema text is therefore processed by whichever model backs VS Code Chat, which may not be the provider configured for CrossWayAI. Either way, providing the actual source and schema text helps the AI produce more precise summaries and diagrams.

By enabling and using AI features, you are responsible for deciding whether your source code, schema files, database metadata, and other workspace content may be sent to the configured AI provider. CrossWayAI does not control how external AI providers or VS Code language models process, store, retain, train on, or secure that data. Review your provider's terms, privacy policy, and your organization's security rules before enabling AI features. Do not use AI features with confidential, regulated, customer-owned, or otherwise sensitive code or data unless you are authorized to share that content with the configured AI service.

For detailed setup instructions, see: AI Configuration Guide

Java Configuration

To use Proparse support, you need to have a correctly installed and configured JDK in the PATH environment variable. This is mandatory for the Proparse functionalities to be available.

Before You Start

Important: CrossWayAI requires your ABL sources to be compiled. It reads .xref files produced by the OpenEdge ABL extension's background builder — without them, no dependency data will be available. Note that at least one source directory needs to be specified in the openedge-project.json configuration file.

Complete the OpenEdge ABL extension setup first and make sure your project compiles successfully before running CrossWayAI.

CrossWayAI watches generated .xref files after the dependency map is available. The CrossWayAILog output may show diagnostic XREF created, XREF updated, or XREF deleted messages for pending file watcher events; duplicate events for the same xref are collapsed before incremental analysis updates the dependency data.

Getting Started

1. Open your OpenEdge ABL project workspace in VS Code.
2. Open the Command Palette (Ctrl+Shift+P).
3. Run the "CrossWayAI: Generate Dependency Map" command.
   • This will create a .crosswayai directory in your workspace root, generate an initial dsMap.json file containing your project's source files, and then execute the backend ABL process for a full analysis.

5. Run the "CrossWayAI: Dump All DB Definitions" command

   • This will dump all databases configured in the openedge-project.json under the .crosswayai\dump directory in your workspace root.

6. (optionally) run the "CrossWayAI: Proparse All Projects" command

   • This will output corresponding proparse files of all workspace ABL files under the .crosswayai\proparse directory in your workspace root.

Once the analysis is complete, you can use the other commands to generate specific diagrams or to view the corresponding XREF or Proparse content of an ABL file.

Workspace Root

CrossWayAI stores its .crosswayai folder (dependency map, log and generated diagrams) in the workspace root. By default, the root is the folder containing the open .code-workspace file. If that file is located inside one of your projects, CrossWayAI uses the deepest folder shared by all workspace folders instead, so the .crosswayai folder remains inside the workspace you see in the Explorer.

If your workspace folders have no common parent (for example, folders on different drives), the root falls back to the parent folder of the first workspace folder. In such cases, or whenever you want full control, you can override the root using crosswayai.workspaceRoot in the settings block of your .code-workspace file:

{
    "folders": [ ... ],
    "settings": {
        "crosswayai.workspaceRoot": "c:/projects/my-workspace"
    }
}

The value must be an absolute path to an existing folder (for example c:/projects/my-workspace on Windows or /home/me/projects/my-workspace on Linux/macOS). Relative paths or non-existent folders are ignored and reported in CrossWayAILog, and automatic detection is used instead. The same key can also be set in user or folder settings.

XREF watching restarts automatically whenever VS Code configuration changes (including unrelated settings) or workspace folders are added or removed. The watcher resolves the workspace root again and discards queued updates from its previous instance. Analysis already running finishes at its original root without refreshing the diagram from that obsolete watcher. When you change the root, existing generated files stay in their original location; run CrossWayAI: Generate Dependency Map if the new root does not have a dependency map yet.

XREF watching covers the workspace folders independently of the output root, so an output root outside the projects still receives incremental updates. Overlapping workspace folders share one update queue. Automatic common-parent detection respects directory-name capitalization on Unix and compares names case-insensitively on Windows.

Proparse results and diagrams use the same project/source folder layout beneath their output directories. Nested projects retain their paths relative to the output root. External projects use _external/<folder-name>-<path-hash> subfolders so matching filenames do not overwrite each other. After upgrading, rerun CrossWayAI: Proparse All Projects and regenerate diagrams for nested or external projects to use this layout. Existing generated files are not moved.

Diagram Exclusions

You can hide specific files or folders from generated diagrams by adding paths to the excludes array in .crosswayai/crosswayai_settings.json.

For detailed setup instructions, see: Diagram Exclusions Guide

Extension Commands

The following commands are available in the Command Palette :

• CrossWayAI: Generate Dependency Map: The primary command to kick off the full analysis of the workspace projects' files.
• CrossWayAI: Dump All DB Definitions: Helper command to dump the current workspace databases schema definition files in order to enable users to generate table relationship diagrams using the chat agent.
• CrossWayAI: Proparse All Projects: (optional) Helper command to output proparse files for the whole workspace

and via context menus:

• Diagram:

  • Impact: Generate an impact analysis diagram for the selected file.
  • Include: Generate an include diagram for the selected file
  • Interface: Generate an interface diagram for the selected class or interface.
  • Inheritance: Generate an inheritance diagram for the selected class.
  • Call: Generate a call (invoke and run) diagram for the selected class, procedure or .w .
  • Package: Generate a package diagram for the selected file.
  • Instance Chain: Generate an instantiation chain diagram for the selected file.
  • Property Access: Generate a property access chain diagram for the selected file.

• File:

  • XREF: Open the corresponding XREF file for the selected file.
  • PROPARSE: Open the corresponding Proparse file for the selected file.

• Table Relations Diagram: Generate the selected .df file's tables relations diagram using chat agent

• View diagram: Open the CrossWayAI Viewer for the selected .md file

Release Notes

2.0.0

• Improvements:

  • pruned unlinked .p and .i file nodes from dsMap.json to reduce generated map size
  • added quick navigation buttons (⌃/⌄) next to search count in CrossWayAI Viewer for iterating through search results
  • normalized ttFileNode.FileRelPath values to use forward slashes in generated dsMap.json while preserving compatibility with existing backslash paths and OS-native file lookups

• Bug Fixes:

  • fixed duplicate source-path collection so the same file is only loaded once, and added the crosswayai.workspaceRoot override for explicitly pinning the workspace root while preserving automatic .code-workspace detection when unset.
  • corrected double-click tooltip navigation to internal procedures so the whole procedure body is selected when it is closed with END. instead of END PROCEDURE.; previously only the declaration line of the last internal procedure in a file was selected
  • corrected XREF-to-source mapping so outgoing references appear in Impact, Include and Call diagrams after a procedure is moved to its source directory root, without matching same-named files in other folders
  • corrected the missing XREF files warning to show the absolute path of crosswayai.log instead of the relative .crosswayai/crosswayai.log path, so the log file can be opened directly from the CrossWayAILog output channel
  • corrected invoke tooltip double-click navigation for multiline method and constructor declarations, addressing Unix target selection; preserved name-only lookup and explicit no-parameter overload selection
  • corrected XREF parsing for files that use work tables (DEFINE WORKFILE / DEFINE WORK-TABLE), which failed with Entry 2 is outside the range of list <name>. (560) and left those files without any dependency links
  • corrected XREF lookup for projects with more than two source directories by using the openedge-project.json source entries instead of fixed .pct0 / .pct1 paths
  • Stopped CrossWayAILog from opening automatically and stealing focus; logs remain available in the Output panel.
  • Added an error notification when a Mermaid diagram cannot be saved.

For the full release history, see the CHANGELOG.

Enjoy!