Cvoya.Graph.Analyzers 1.0.0

Downloadable open-source computer software from CVOYA. See the CVOYA software catalog.

Cvoya.Graph.Analyzers

Compile-time code analyzers for CVOYA graph - provides static analysis and validation of your graph entity models to catch issues early in the development cycle.

🚀 Quick Start

dotnet add package Cvoya.Graph.Analyzers

The analyzers are automatically enabled when you build your project. No additional configuration required!

// The analyzers will catch issues like this:
[Node("User")]
public class User : INode
{
    // ❌ CG001: Missing parameterless constructor
    public User(string name) { Name = name; }

    // ❌ CG002: Property must have public getter and setter
    [Property]
    public string Name { get; private set; }

    // ❌ CG004: Invalid property type for node
    [Property]
    public IGraph Graph { get; set; }
}

📦 Analyzer Rules

🔧 Configuration

You can customize analyzer behavior in your .editorconfig:

# Disable specific rules
dotnet_diagnostic.CG007.severity = none

# Change severity levels
dotnet_diagnostic.CG010.severity = error

# Configure for specific files
[**/Generated/*.cs]
dotnet_diagnostic.CG001.severity = none

📋 Rule Details

CG001: Missing Parameterless Constructor

// ❌ Bad
[Node("User")]
public class User : INode
{
    public User(string name) { /* ... */ }
}

// ✅ Good
[Node("User")]
public class User : INode
{
    public User() { }
    public User(string name) : this() { /* ... */ }
}

CG002: Property Must Have Public Accessors

// ❌ Bad
[Property]
public string Name { get; private set; }

// ✅ Good
[Property]
public string Name { get; set; }

CG003: Property Cannot Be Graph Interface Type

// ❌ Bad
[Property]
public IGraph Graph { get; set; }

[Property]
public INode RelatedNode { get; set; }

// ✅ Good - use relationships instead
public IGraph Graph => /* get from context */;

CG002, CG003, and CG006 inspect the same effective property set as runtime and generated serialization: inherited public instance properties with a getter. Static properties, indexers, non-public or write-only properties, and properties marked [Property(Ignore = true)] are excluded.

CG016: Open Generic Graph Entities Are Not Supported

// ❌ Bad - T is unbound where the non-generic serializer would be generated
public record GenericNode<T> : Node;

// ✅ Good - keep the reusable base abstract and expose a closed concrete entity
public abstract record GenericNode<T> : Node;

[Node("StringNode")]
public record StringNode : GenericNode<string>;

The serialization generator supports non-generic concrete entities built from closed generic constructions. It does not generate serializers for concrete open generic entity declarations or entities nested in an open generic containing type.

CG018: Invalid Graph Key or Ignored Property Declaration

// ❌ Bad - keys must be non-nullable graph-storable scalars
[Property(IsKey = true)]
public string? CustomerNumber { get; set; }

// ❌ Bad - ignored properties cannot request schema behavior
[Property(Ignore = true, IsUnique = true)]
public string ImportMarker { get; set; } = string.Empty;

// ✅ Good - multiple scalar declarations form a composite key
[Property(IsKey = true)]
public string Tenant { get; set; } = string.Empty;

[Property(IsKey = true)]
public long AccountNumber { get; set; }

Key declarations are opt-in. A keyless entity is valid, and a property named Id is ordinary mapped data unless it explicitly sets IsKey = true. CG018 uses the same graph-storable scalar classification as runtime schema validation. Existing property-type rules remain the single report for types that are unsupported regardless of key configuration.

📚 Documentation

For comprehensive documentation, examples, and best practices:

🌐 Complete Documentation

🔗 Related Packages

• Cvoya.Graph.Neo4j - Neo4j database provider
• Cvoya.Graph.Serialization - Object serialization framework
• Cvoya.Graph.Serialization.CodeGen - Code generation for performant serialization/deserialization
• Cvoya.Graph.Analyzers - Compile-time code analyzers

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Need help? Check the troubleshooting guide or open an issue.