How it works
Technology

GNEISS is a CLI tool that analyzes Java codebases for macro-architectural decay using a Graph Neural Network.
It's not a linter. It's not a bug detector. It's a diagnostic tool that tells you whether your codebase is becoming structurally fragile over time.
Sample output
Example CLI report

This is the kind of output a repository scan produces after the graph is built and the highest-risk structural hotspots are ranked.
gneiss scan output
🔍 GNEISS Structural Analysis

✔ Found 3797 Java files
✔ Built dependency graph with 3797 nodes and 17761 edges
✔ Analysis complete

📊 Analysis Results

──────────────────────────────────────────────────
🔍 GNEISS Scan Complete
✔ 3797 files analyzed (17761 connections mapped)

📋 WATCH LIST — Low structural risk, but monitor these files
──────────────────────────────────────────────────────────────────────

📄 FILE #1: org.apache.cayenne.exp.ExpressionFactory
💥 THE PROBLEM: Acts as a God Object for expression construction — 196
   connections across 14 dependent packages. Every module that needs to
   build a query expression imports this directly, creating a hidden
   coordination bottleneck.
🔥 IF YOU TOUCH THIS: Changes to expression creation signatures will
   ripple into cayenne-server, cayenne-client, cayenne-tools and the
   modeler simultaneously. High regression surface.
🛠️ HOW TO FIX IT:
   • Line 34: \`import org.apache.cayenne.exp.parser.ExpressionParser\`
     → move parser delegation behind an ExpressionBuilder interface
   • Line 67: \`import org.apache.cayenne.map.DbAttribute\`
     → this cross-layer dependency (expression→mapping) should be
     inverted via a lightweight AttributeDescriptor contract
   • Extract a StaticExpressionFactory for the 12 pure utility methods
     that have no state dependency — that alone removes ~40 inbound edges

──────────────────────────────────────────────────────────────────────

📄 FILE #2: org.apache.cayenne.map.DbEntity
💥 THE PROBLEM: Central mapping hub with 384 connections — the highest
   degree node in the graph. Acts as a shared data contract between the
   ORM core, the modeler GUI, and the serialization layer. Three
   completely separate concerns all coupled to one class.
🔥 IF YOU TOUCH THIS: Any field rename or method signature change breaks
   the modeler, the XML serializer, and runtime query resolution
   simultaneously. This is the highest-risk single file in the codebase.
🛠️ HOW TO FIX IT:
   • Line 12: \`import org.apache.cayenne.modeler.*\`
     → the mapping layer should not import the modeler. Invert this via
     a DbEntityListener interface the modeler implements
   • Line 89: \`import org.apache.cayenne.util.XMLSerializable\`
     → extract a DbEntityDescriptor as a pure data transfer object for
     serialization, breaking the runtime/persistence coupling
   • Long-term: split into DbEntityDefinition (schema) and
     DbEntityRuntime (query execution) — removes ~200 edges

──────────────────────────────────────────────────────────────────────

📄 FILE #3: org.apache.cayenne.exp.Expression
💥 THE PROBLEM: Abstract base with 237 connections — every concrete
   expression type and every consumer imports this directly. No
   intermediate abstraction layer exists between the base class and its
   237 dependents.
🔥 IF YOU TOUCH THIS: Modifying the abstract Expression contract
   triggers a cascade across the entire expression subsystem. Even
   adding a default method is high risk.
🛠️ HOW TO FIX IT:
   • Introduce an IExpression interface containing only the 4 methods
     actually used by external consumers (evaluate, toEJBQL,
     getOperandCount, deepCopy)
   • Move the remaining 11 methods to an AbstractExpression base —
     external modules bind to the interface, not the abstract class
   • This decouples 180+ of the 237 inbound edges immediately

──────────────────────────────────────────────────────────────────────

... and 7 other files flagged at lower severity

──────────────────────────────────────────────────────────────────────
📈 SUMMARY
- Architecture Status: MINIMAL DEBT (Healthy Architecture)
- Structural Note: Codebase is healthy overall, but 3 files carry
  disproportionate coupling load. None are urgent — but DbEntity in
  particular should be watched on every PR that touches the mapping layer.
- Recommendation: No immediate refactor needed. Add coupling regression
  checks to CI for the top 3 files above.

📈 Metrics
Risk Level: LOW
Decay Probability: 26.42%
Codebase Health: 73.6/100
Spectral Gap Ratio: 0.0041
PageRank Entropy: 0.8923
Structural Delta: 0.0000
──────────────────────────────────────────────────