Imported from dalaus/TrafficLight (AGENTS.md). Install upstream with npx skills add dalaus/TrafficLight. Copyright stays with the author.

AGENTS.md - Traffic Light Simulation Project

This document provides essential information for agentic coding assistants working on the Traffic Light simulation project.

Project Overview

This is a C# Windows Forms application (.NET 10.0) that simulates traffic light systems and vehicle routing through intersections. The project includes pathfinding algorithms, map editing, and real-time simulation features.

Build, Lint, and Test Commands

Building and Running

The trick: you are working from linux host so you can't use dotnet command for building, running and etc. Ask user if you wanna run some dotnet command.

# Build the project
dotnet build TrafficLight/TrafficLight.csproj

# Run the application
dotnet run --project TrafficLight/TrafficLight.csproj

# Build for release
dotnet build -c Release TrafficLight/TrafficLight.csproj

# Publish as single-file executable (used in CI/CD)
dotnet publish -c Release -r win-x64 --self-contained true /p:PublishSingleFile=true /p:IncludeNativeLibrariesForSelfExtract=true /p:EnableCompressionInSingleFile=true TrafficLight/

Code Analysis and Linting

The project uses multiple analyzers that run during build:

# Run full analysis (automatically runs during build due to EnforceCodeStyleInBuild=true)
dotnet build TrafficLight/TrafficLight.csproj

# Run specific analyzers manually
dotnet build TrafficLight/TrafficLight.csproj /p:RunAnalyzers=true

Analyzers configured:

• Microsoft.CodeAnalysis.NetAnalyzers (v10.0.101)
• SonarAnalyzer.CSharp (v10.17.0.131074)
• StyleCop.Analyzers (v1.1.118)

Testing

Note: No automated tests are currently implemented in this codebase. For any new features or changes, consider adding unit tests using:

# Example test commands (when tests are added)
dotnet test TrafficLight/TrafficLight.csproj
dotnet test TrafficLight/TrafficLight.csproj --filter "TestCategory=Unit"
dotnet test TrafficLight/TrafficLight.csproj --logger "console;verbosity=detailed"

Code Style Guidelines

Language and Framework

• Target Framework: .NET 10.0 Windows
• UI Framework: Windows Forms
• Language Version: C# with nullable reference types enabled
• Implicit Usings: Enabled (no need to manually add common usings)
• Documentation: XML documentation comments are optional (SA1600 disabled)

Naming Conventions

• Private Fields: Prefix with underscore and use camelCase (e.g., _pathFinder)
• Constants: ALL_UPPER_CASE (warning level)
• Methods/Properties: PascalCase
• Local Variables: camelCase
• Namespaces: PascalCase, reflect folder structure

Code Structure and Organization

• File Ordering: Elements must be ordered by kind (fields, properties, constructors, methods)
• Access Ordering: Elements must be ordered by accessibility (public, internal, protected, private)
• Field Visibility: All fields must be private (SA1401 error)

Code Quality Metrics

Size Limits:

• Files: Maximum 200 lines (S104 error)
• Classes: Maximum 100 lines (S120 error)
• Methods: Maximum 15 lines (S138 error)

Complexity Limits:

• Cyclomatic Complexity: Maximum 7 (S1541 error)
• Cognitive Complexity: Maximum 10 (S3776 error)
• Nesting Level: Maximum 3 levels (S134 error)

Magic Numbers:

• Only allowed: 0, 1, -1, 2, 2f
• All other numeric literals require named constants (S109 error)

Code Patterns and Architecture

Dependency Injection:

• Use constructor injection for dependencies
• Prefer interfaces over concrete types
• Store injected dependencies as private readonly fields

Event Handling:

• Use standard .NET event pattern with EventHandler<T> or Action<T>
• Use null-conditional operator for event invocation: event?.Invoke(args)

Collections and LINQ:

• Prefer immutable collections where possible
• Use LINQ for data transformations
• Prefer IReadOnlyList<T>, IReadOnlyDictionary<TKey, TValue> for return types

Error Handling:

• Use exceptions for exceptional conditions
• Prefer specific exception types over generic Exception
• Validate parameters in public APIs
• Use ArgumentNullException for null checks

Null Safety:

• Nullable reference types are enabled (<Nullable>enable</Nullable>)
• Use ! operator only when certain value is not null
• Prefer ?. and ?? operators for null-safe operations

Imports and Using Statements

• Placement: Using directives can be outside namespaces (SA1200 disabled)
• Ordering: System namespaces first, then third-party, then project namespaces
• Static Usings: Avoid unless necessary for readability

File Organization

TrafficLight/
├── App/                    # Application logic with IAppModel, IEditorModel, IGameModel interfaces
├── Editor/                 # Map editing: MapGrid, MapValidator, MapSerializer, TileType, ToolOption
├── Model/                  # Domain models: Car, Intersection, GameMap, Route, Edge, Node, positions
├── Pathfinding/            # Pathfinding algorithms (DijkstraPathFinder, IPathFinder)
├── Simulation/             # Simulation engine with Rules/ subfolder
│   └── Rules/              # Movement rules: IMovementRule, LeftBlockingRule, RightBlockingRule,
│                           #                 NoOvertakingRule, TrafficLightRule
├── View/                   # UI components with Rendering/ subfolder
│   └── Rendering/          # Renderers: CarsRenderer, TrafficLightsRenderer, MapGridRenderer,
│                           #               LaneMarkersRenderer, GameOverOverlayRenderer, etc.
└── TrafficLight/           # Windows Forms entry point (TrafficLightAppForm, Program.cs)

Code Comments

• Documentation: Use XML comments for public APIs (when required)
• Implementation: Prefer self-documenting code over comments
• Suppressions: Use [SuppressMessage] attributes for justified analyzer suppressions

Common Patterns

Record Types:

• Use record for immutable data structures
• Use record struct for small, performance-critical immutable types

Pattern Matching:

• Use modern C# pattern matching features
• Prefer switch expressions over switch statements where appropriate

String Handling:

• Use string interpolation ($"") for complex strings
• Prefer string.IsNullOrEmpty() and string.IsNullOrWhiteSpace()

Performance Considerations

• Collections: Choose appropriate collection types based on usage patterns
• LINQ: Be aware of deferred execution vs. immediate execution
• Memory: Consider memory implications of large collections and object allocations

Diagram Generation

Diagrams are authored as Mermaid files in diagrams/*.mmd and rendered to PNG using the script below:

scripts/render_diagrams.sh

Example sources:

• diagrams/usecase.mmd
• diagrams/communication_tick.mmd

Development Workflow

1. Code Changes: Make changes following the style guidelines above
2. Build and test: Ask user to build app to ensure code compiles and passes analysis
3. Commit: Ensure all analyzer warnings/errors are resolved before committing

CI/CD Pipeline

The project uses GitHub Actions for automated building and publishing. The workflow:

• Builds on Windows with .NET 10.0
• Publishes as self-contained single-file executable
• Uploads the executable as build artifact

Notes for Agents

• Code style If you see code style violated mention it.
• No Tests: In this project tests aren't required.
• Single Responsibility: Keep classes focused on single responsibilities to maintain low complexity metrics.
• Code Analysis: The build will fail if any configured analyzer rules are violated at error severity.
• Documentation: The project appears to be a course assignment with some Russian comments, but code should be in English.
• Architecture: Follow the existing patterns of dependency injection, interface segregation, and event-driven design. /home/dalao/shared/TrafficLight/TrafficLight/AGENTS.md