refactor: consolidate exporter escape helpers + fix Copilot setup workflow path

refactor: route per-class escapeHtml / jsonString wrappers through gvisual.ExportUtils
so we have one canonical implementation. Affected:

  - GraphAdversaryForecaster.jsonString -> ExportUtils.jsonString
    (the local copy was the only one that already covered \\b/\\f and
    sub-0x20 \\uXXXX escapes; ExportUtils already does both, so behavior
    is preserved while killing 22 lines of dupe.)
  - GraphAnnotationManager.jsonString  -> ExportUtils.jsonString
    (local copy did NOT escape \\b/\\f or control chars -> latent JSON
    output bug; now correct.)
  - GraphFairnessAuditEngine.escapeHtml -> ExportUtils.escapeHtml
  - GraphPercolationEngine.escapeHtml   -> ExportUtils.escapeHtml

Net: -47 lines, removes drift between exporters/engines, and silently
fixes two control-char escaping holes in JSON annotation output.

setup_copilot_agent: the existing copilot setup file was at
.github/copilot-setup-steps.yml with job name 'setup'. GitHub's coding
agent only picks it up at .github/workflows/copilot-setup-steps.yml
with job name 'copilot-setup-steps' (per docs), so the previous file was
effectively a no-op for the agent.

  - Move + rename to .github/workflows/copilot-setup-steps.yml
  - Rename job to copilot-setup-steps
  - Add timeout, least-privilege contents:read permissions
  - Add push/pull_request triggers scoped to pom.xml + this workflow
    so breakage is caught in normal CI, not only when an agent runs
  - Swap 'mvn dependency:resolve' for 'mvn dependency:go-offline' so
    the agent can run tests with -o
  - Add 'test-compile' step so test-only breakage surfaces before
    running the suite
  - Document the new helper conventions in copilot-instructions.md

Build verified: mvn compile -B -ntp (177 sources, BUILD SUCCESS).
Tests verified for touched classes:
  ExportUtilsTest, JsonGraphExporterTest, GraphMLExporterTest,
  SvgExporterTest, GexfExporterTest, GraphTimelineExporterTest -> 91/91 pass
  GraphAdversaryForecasterTest, GraphAnnotationManagerTest,
  GraphFairnessAuditEngineTest, GraphPercolationEngineTest (minus the
  pre-existing flaky testSiteCurveMonotonicallyNonDecreasing) -> 126/126 pass

The percolation site-curve monotonicity test is a pre-existing flake on
master and is unrelated to this refactor (reproduced before stash apply).

Author: sauravbhattacharya001

.github/copilot-instructions.md

@@ -53,8 +53,11 @@ GraphVisual is a Java graph visualization and analysis platform built with [JUNG
 mvn test                           # Run all 105 test suites
 mvn test -Dtest=ShortestPathFinderTest  # Run a specific test
 mvn test -pl . -Dtest="gvisual.*"      # Run all gvisual package tests
+mvn -B -ntp test-compile           # Quickly verify main + test sources compile
 ```
 
+The `copilot-setup-steps` workflow at `.github/workflows/copilot-setup-steps.yml` mirrors these commands and is what GitHub Copilot's cloud agent runs before starting a task.
+
 When adding new tests, place them in `Gvisual/test/` matching the source package.
 
 ## Common Patterns
@@ -72,3 +75,5 @@ When adding new tests, place them in `Gvisual/test/` matching the source package
 - The `docs/` directory is a separate GitHub Pages site — changes there don't affect the Java build
 - Database configuration may be in `Network.java` — check before modifying DB-related code
 - Use `mvn compile -q` to verify compilation after changes
+- **String escaping for exporters:** Use `gvisual.ExportUtils` (`escapeXml`, `escapeHtml`, `escapeJs`, `jsonString`, `quoteDot`) instead of writing per-class helpers. Existing per-class wrappers delegate to `ExportUtils` so behavior stays consistent across XML/JSON/HTML/SVG/GraphML/GEXF exporters.
+- **Output path safety:** New exporters that write files should call `ExportUtils.validateOutputPath(file)` first to prevent CWE-22 directory traversal.

.github/copilot-setup-steps.yml

@@ -0,0 +1,59 @@
+# Copilot Setup Steps for GraphVisual
+#
+# This workflow pre-installs the toolchain and project dependencies so that
+# GitHub Copilot's cloud coding agent (and other agentic clients) can build,
+# test, and validate changes without paying the cold-start cost each task.
+#
+# Per the GitHub docs the file MUST be at .github/workflows/copilot-setup-steps.yml
+# and the job MUST be named `copilot-setup-steps`, otherwise the agent does
+# not pick it up.
+# https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/customize-the-agent-environment
+
+name: Copilot Setup Steps
+
+on:
+  # Allows the workflow to be triggered manually for verification.
+  workflow_dispatch:
+  # Re-run when this file or the build descriptor changes so the cache stays
+  # fresh and we catch breakage before the agent does.
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+      - pom.xml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+      - pom.xml
+
+jobs:
+  # Job name is required to be exactly `copilot-setup-steps` for Copilot
+  # coding agent to consume the steps.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 11 (Temurin)
+        uses: actions/setup-java@v4
+        with:
+          java-version: '11'
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: Show toolchain
+        run: |
+          java -version
+          mvn -version
+
+      - name: Resolve dependencies (offline cache warm-up)
+        run: mvn -B -ntp dependency:go-offline
+
+      - name: Compile (main + test sources)
+        run: mvn -B -ntp test-compile
+
+      - name: Run unit tests
+        run: mvn -B -ntp test

.github/workflows/copilot-setup-steps.yml

@@ -813,26 +813,8 @@ private static String num(double d) {
         return String.format(Locale.ROOT, "%.6f", d);
     }
 
+    /** Delegates to {@link ExportUtils#jsonString(String)} for consistent JSON escaping. */
     private static String jsonString(String s) {
-        if (s == null) return "null";
-        StringBuilder sb = new StringBuilder(s.length() + 2);
-        sb.append('"');
-        for (int i = 0; i < s.length(); i++) {
-            char c = s.charAt(i);
-            switch (c) {
-                case '"':  sb.append("\\\""); break;
-                case '\\': sb.append("\\\\"); break;
-                case '\b': sb.append("\\b");  break;
-                case '\f': sb.append("\\f");  break;
-                case '\n': sb.append("\\n");  break;
-                case '\r': sb.append("\\r");  break;
-                case '\t': sb.append("\\t");  break;
-                default:
-                    if (c < 0x20) sb.append(String.format("\\u%04x", (int) c));
-                    else sb.append(c);
-            }
-        }
-        sb.append('"');
-        return sb.toString();
+        return ExportUtils.jsonString(s);
     }
 }

Gvisual/src/gvisual/GraphAdversaryForecaster.java

@@ -567,13 +567,9 @@ public void clear() {
 
     // --- Helpers ---
 
+    /** Delegates to {@link ExportUtils#jsonString(String)} for consistent (and control-char-safe) JSON escaping. */
     private static String jsonString(String value) {
-        if (value == null) return "null";
-        return "\"" + value.replace("\\", "\\\\")
-                          .replace("\"", "\\\"")
-                          .replace("\n", "\\n")
-                          .replace("\r", "\\r")
-                          .replace("\t", "\\t") + "\"";
+        return ExportUtils.jsonString(value);
     }
 
     private static String extractJsonStringValue(String line) {

Gvisual/src/gvisual/GraphAnnotationManager.java

@@ -958,8 +958,8 @@ private void appendCard(StringBuilder html, String label, String value, String c
         html.append("\">").append(escapeHtml(value)).append("</div></div>\n");
     }
 
+    /** Delegates to {@link ExportUtils#escapeHtml(String)} for consistent HTML escaping. */
     private String escapeHtml(String text) {
-        return text.replace("&", "&amp;").replace("<", "&lt;")
-                .replace(">", "&gt;").replace("\"", "&quot;");
+        return ExportUtils.escapeHtml(text);
     }
 }

Gvisual/src/gvisual/GraphFairnessAuditEngine.java

@@ -766,9 +766,9 @@ private void appendCard(StringBuilder html, String label, String value, String c
         html.append("\">").append(escapeHtml(value)).append("</div></div>\n");
     }
 
+    /** Delegates to {@link ExportUtils#escapeHtml(String)} for consistent HTML escaping. */
     private String escapeHtml(String text) {
-        return text.replace("&", "&amp;").replace("<", "&lt;")
-                .replace(">", "&gt;").replace("\"", "&quot;");
+        return ExportUtils.escapeHtml(text);
     }
 
     // -- Utility --------------------------------------------------------------