DesignFix

DesignFix is an LLM-assisted design-rule–violation detector and repair tool for Java projects. It continuously checks your codebase against a set of author-defined design rules, surfaces violations in a web dashboard, and uses an LLM to suggest minimal fixes that you can review and apply.

Just want to use DesignFix? Install DesignFix (publisher: DevX Lab, devx-gmu.designfix) from the VS Code Marketplace. It includes the dashboard: open a Java project that has ruleTable.json at its root, run DesignFix: Set OpenAI API Key, and click DesignFix in the status bar. The rest of this README describes running DesignFix from source, for development.

DesignFix has two components that run together:

Component	Folder	Role	Default port
Extension	DesignFix-Extension/	VS Code extension. Watches the target Java project, converts each .java file to srcML XML, hosts a WebSocket server, and streams file/rule data to the web app.	WebSocket 8887
Client (web app)	DesignFix-client/	React dashboard. Receives the XML, runs the XPath rule checks in-browser, shows violated rules, and drives the LLM fix workflow.	HTTP 9010

They talk to each other over a WebSocket (ws://localhost:8887).

---

1. Prerequisites

0. Windows machine
1. Node.js (v16+ recommended) and npm.
2. VS Code ^1.86.0.
3. srcML 0.9.5: the tool that converts Java to XML.

   ⚠️ Use srcML 0.9.5, not 1.1.0. Version 1.1.0 wraps class inheritance in a <super_list> element, which breaks every rule that uses src:super/src:extends (inheritance-based rules silently report 0 violations). All rules in this project were authored against 0.9.5.

   • The extension resolves the srcML binary from DesignFix-Extension/src/Constants.ts:
     • Windows: SRCML_PATH_WINDOWS
   • If your srcML lives elsewhere, update the matching constant.
4. An OpenAI API key (only needed for the LLM "suggest fix" feature). Add it to the gitignored DesignFix-client/.env as OPENAI_API_KEY=your-key. The web app's dev server reads it from there and injects it into the OpenAI proxy, so the key never reaches the browser.
5. A target Java project to analyze. It must contain a ruleTable.json (the design rules) and a tagTable.json at its root. These are loaded by the extension on connect.

---

2. One-time setup

Install dependencies for both components.

# From the repository root: "DesignFix-VSCode"

# Extension
cd "DesignFix-Extension"
npm install
npm run compile        # compiles TypeScript in src/ to out/

# Client
cd "..\DesignFix-client"
npm install

---

3. Running the tool

You need three things running: the extension (in an Extension Development Host), the web app, and the target Java project opened inside the Extension Development Host.

3a. Start the extension (Extension Development Host)

1. Open the DesignFix-Extension/ folder in VS Code.
2. Compile if you have not already, or run the watch task:

   cd "DesignFix-Extension"
   npm run compile     # or: npm run watch

3. Press F5 ("Run Extension"). This launches a second VS Code window, the Extension Development Host, with the DesignFix extension loaded (it activates when the opened folder contains ruleTable.json).
4. In that new window, open your target Java project folder (File → Open Folder). The extension analyzes workspaceFolders[0], so the Java project must be the workspace root there.

🔁 Every time you run npm run compile, you must relaunch the Extension Development Host (stop it and press F5 again). The running host keeps the old build until relaunched.

3b. Start the web app

cd "DesignFix-client"
npm run start-Windows      # macOS: npm run start-Mac | Linux: npm run start-Linux

• Serves the dashboard at http://localhost:9010.
• The Windows/Linux scripts set NODE_OPTIONS=--openssl-legacy-provider (required for the older React build).

3c. Connect

Open http://localhost:9010 in your browser. On page load the client opens the WebSocket to the extension (8887). The extension then:

1. Sends the project path and folder hierarchy.
2. Converts all .java files to srcML XML and streams them.
3. Sends the tag table and rule table.
4. Triggers a full rule verification.

While this runs, the dashboard shows "Loading Rules and Preprocessing." Wait until that heading disappears before trusting any counts.

---

4. Using the dashboard

Left navigation:

• Table of Contents: overview.
• All Rules: every rule with satisfied/violated status.
• Violated Rules: only rules with at least one violation, each showing an Examples count and a Violated count. Expand a card and open the Violated tab to see the offending code snippet(s) and file.
• Learn Design Rules: rule documentation.
• DesignFix LLM status (top navigation) shows whether your OpenAI key is loaded. You do not enter the key in the browser: add it to the gitignored DesignFix-client/.env as OPENAI_API_KEY=your-key. The dev server reads that file and injects the key into the OpenAI proxy, so it stays server-side.

---

5. Requesting and applying a fix

1. Go to Violated Rules and expand the rule you want to fix; open its Violated tab to see the violating snippet and file.
2. Provide your OpenAI key once by adding OPENAI_API_KEY=your-key to DesignFix-client/.env (gitignored). The dev server picks it up automatically on the next request; no browser entry is needed. The top navigation shows "key loaded" when it is set.
3. Click the Fix action on the violation. The client calls suggestFix() (DesignFix-client/src/activeLLM/suggestFix.js), sending the LLM:
   • the design rule,
   • a rule-satisfying example (and its file path),
   • the surrounding class/method context,
   • the full original file content and its path,
   • the violation snippet. The LLM returns a fully rewritten file plus an explanation, constrained to change only the minimal lines needed.
4. Review the suggestion in the dashboard, then click Accept Fix to send it to the VS Code extension. This does not change the project file yet.
5. In the Extension Development Host, review the native VS Code diff between the file on disk and the suggested version.
6. Select DesignFix: Accept Fix to save the change, or DesignFix: Reject Fix to discard the suggestion. Accepting saves the reconciled change to the target file; rejecting leaves the file unchanged.
7. The extension watches the saved .java file, reconverts it to srcML, and asks the client to recheck the affected rules. If the dashboard does not update after a few seconds, reload the web page.

The OpenAI call goes through a local proxy (/openai-proxy/v1) to avoid browser CORS issues. The proxy is configured in the client's dev server (setupProxy.js), which also injects your API key from OPENAI_API_KEY in DesignFix-client/.env so the key stays server-side and never reaches the browser.

---

6. Quick start (TL;DR)

# 1. Install
cd "DesignFix-Extension"; npm install; npm run compile
cd "..\DesignFix-client"; npm install

# 2. Extension: open DesignFix-Extension in VS Code → F5 →
#    in the new window, open your Java project (with ruleTable.json at its root)

# 3. Web app
cd "DesignFix-client"; npm run start-Windows

# 4. Add OPENAI_API_KEY=your-key to DesignFix-client/.env (gitignored), then open
#    http://localhost:9010, wait for preprocessing, go to "Violated Rules",
#    click Fix, review the diff, apply it, and watch the violation count drop.

---

7. Building the extension package (.vsix)

The packaged extension serves its own copy of the dashboard, so packaging also builds DesignFix-client into DesignFix-Extension/dashboard. The build stops if the bundle would contain your OpenAI key or build-machine environment variables, and it regenerates DesignFix-Extension/THIRD_PARTY_NOTICES.md.

cd "DesignFix-client"; npm install
cd "..\DesignFix-Extension"; npm install
npm run package:vsix      # compiles, builds the dashboard, writes designfix-<version>.vsix

Install the result with code --install-extension designfix-<version>.vsix. In an Extension Development Host (F5) the extension still accepts the dashboard from npm run start-Windows on port 8887 and records accepted fixes under data/; installed copies do neither unless the designfix.devSocket.enabled and designfix.fixLogs.enabled settings are turned on.