diff --git a/docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md b/docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md new file mode 100644 index 000000000..ed544ac82 --- /dev/null +++ b/docs/implplan/SPRINT_20260323_002_ElkSharp_bounded_edge_refinement.md @@ -0,0 +1,75 @@ +# Sprint 20260323-002 - ElkSharp Bounded Edge Refinement + +## Topic & Scope +- Add a bounded deterministic edge-refinement stage to ElkSharp without replacing the existing channel and dummy-edge routing model. +- Preserve orthogonal output, backward corridor behavior, sink corridor behavior, and target anchor heuristics. +- Working directory: `src/__Libraries/StellaOps.ElkSharp/` +- Expected evidence: targeted renderer tests, direct geometry assertions, and workflow docs updated for the new layout option. + +## Dependencies & Concurrency +- Depends on the current ElkSharp routing pipeline in `src/__Libraries/StellaOps.ElkSharp/`. +- Safe cross-module edits for this sprint are limited to: + - `src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/` + - `docs/workflow/` + +## Documentation Prerequisites +- `docs/code-of-conduct/CODE_OF_CONDUCT.md` +- `docs/code-of-conduct/TESTING_PRACTICES.md` +- `docs/workflow/ENGINE.md` +- `src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs` +- `src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouter.cs` +- `src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessor.cs` + +## Delivery Tracker + +### TASK-001 - Add module-local ElkSharp guidance and option scaffolding +Status: DONE +Dependency: none +Owners: Implementer +Task description: +Create a module-local `AGENTS.md` for ElkSharp and extend the layout option model with bounded refinement settings that default safely and deterministically. + +Completion criteria: +- [x] `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` exists with local routing rules +- [x] `ElkLayoutOptions` exposes bounded refinement options without changing workflow request contracts + +### TASK-002 - Implement bounded orthogonal edge refinement +Status: DONE +Dependency: TASK-001 +Owners: Implementer +Task description: +Add an internal refinement stage that scores routed output, detects crossing-prone edges, and tries a small fixed set of orthogonal reroute strategies while preserving corridor and anchor semantics. + +Completion criteria: +- [x] Refinement is deterministic and bounded by explicit pass and trial limits +- [x] Refinement runs only for `LeftToRight` and preserves existing corridor and port-sensitive edges +- [x] Existing simplify and tighten passes still run after refinement + +### TASK-003 - Add regression tests and docs +Status: DONE +Dependency: TASK-002 +Owners: Implementer +Task description: +Add regression tests covering deterministic output and option gating, and update workflow documentation to note the bounded ElkSharp refinement behavior. + +Completion criteria: +- [x] Targeted workflow renderer tests cover refinement determinism and `TopToBottom` stability +- [x] Workflow docs mention the bounded refinement behavior for ElkSharp best-effort layout +- [x] Sprint execution log records validation results + +## Execution Log +| Date (UTC) | Update | Owner | +| --- | --- | --- | +| 2026-03-23 | Sprint created and work started for bounded deterministic ElkSharp edge refinement. | Implementer | +| 2026-03-23 | Added module-local ElkSharp guidance, implemented bounded orthogonal refinement, updated `docs/workflow/ENGINE.md`, and passed `dotnet test src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/StellaOps.Workflow.Renderer.Tests.csproj --filter "FullyQualifiedName~ElkSharp" -v minimal` (15/15). | Implementer | + +## Decisions & Risks +- There was no module-local `AGENTS.md` under `src/__Libraries/StellaOps.ElkSharp/`; this sprint adds one before code changes so the module is no longer undocumented. +- Cross-module edits are limited to workflow renderer tests and workflow engine docs because the implementation changes a shared library used by those surfaces. +- The refinement stage must remain deterministic and must not introduce random strategy generation or diagonal output. +- Updated docs: `docs/workflow/ENGINE.md` +- Module-local guidance added: `src/__Libraries/StellaOps.ElkSharp/AGENTS.md` + +## Next Checkpoints +- After TASK-002: targeted `dotnet test` run for ElkSharp renderer tests +- After TASK-003: update sprint statuses and execution log with concrete command results diff --git a/docs/workflow/ENGINE.md b/docs/workflow/ENGINE.md index ccb70c1a9..ded1a7a40 100644 --- a/docs/workflow/ENGINE.md +++ b/docs/workflow/ENGINE.md @@ -920,7 +920,7 @@ The engine can render workflow definitions as visual diagrams. | Engine | Description | |--------|-------------| -| **ElkSharp** | Port of Eclipse Layout Kernel (default) | +| **ElkSharp** | Port of Eclipse Layout Kernel (default). In `Best` effort mode it now runs a bounded deterministic orthogonal edge-refinement pass after base routing; `Draft` and `Balanced` keep the base route unless library callers opt in through `ElkLayoutOptions.EdgeRefinement`. | | **ElkJS** | JavaScript-based ELK via Node.js | | **MSAGL** | Microsoft Automatic Graph Layout | @@ -1020,4 +1020,3 @@ docs/decompiled-samples/ csharp/ 177 .cs files (Roslyn-formatted C# with typed request models) json/ 177 .json files (indented canonical definitions with JSON Schema) ``` - diff --git a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/DeploymentEndpoints.cs b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/DeploymentEndpoints.cs new file mode 100644 index 000000000..d2611a906 --- /dev/null +++ b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/DeploymentEndpoints.cs @@ -0,0 +1,463 @@ +using Microsoft.AspNetCore.Mvc; +using StellaOps.Auth.ServerIntegration.Tenancy; + +namespace StellaOps.JobEngine.WebService.Endpoints; + +/// +/// Deployment monitoring endpoints for the Orchestrator service. +/// Provides lifecycle operations, log streaming, event tracking, and metrics +/// for individual deployment runs. +/// Routes: /api/release-orchestrator/deployments +/// +public static class DeploymentEndpoints +{ + public static IEndpointRouteBuilder MapDeploymentEndpoints(this IEndpointRouteBuilder app) + { + MapDeploymentGroup(app, "/api/release-orchestrator/deployments", includeRouteNames: true); + MapDeploymentGroup(app, "/api/v1/release-orchestrator/deployments", includeRouteNames: false); + + return app; + } + + private static void MapDeploymentGroup( + IEndpointRouteBuilder app, + string prefix, + bool includeRouteNames) + { + var group = app.MapGroup(prefix) + .WithTags("Deployments") + .RequireAuthorization(JobEnginePolicies.ReleaseRead) + .RequireTenant(); + + // --- Read endpoints --- + + var list = group.MapGet(string.Empty, ListDeployments) + .WithDescription("Return a paginated list of deployments for the calling tenant, optionally filtered by status, environment, and release. Each deployment record includes its current status, target environment, strategy, and lifecycle timestamps."); + if (includeRouteNames) + { + list.WithName("Deployment_List"); + } + + var detail = group.MapGet("/{id}", GetDeployment) + .WithDescription("Return the full deployment record for the specified ID including status, target environment, deployment strategy, target health, and progress details. Returns 404 when the deployment does not exist in the tenant."); + if (includeRouteNames) + { + detail.WithName("Deployment_Get"); + } + + var logs = group.MapGet("/{id}/logs", GetDeploymentLogs) + .WithDescription("Return the aggregated log entries for the specified deployment across all targets. Entries are ordered chronologically and include severity level, source target, and message content."); + if (includeRouteNames) + { + logs.WithName("Deployment_GetLogs"); + } + + var targetLogs = group.MapGet("/{id}/targets/{targetId}/logs", GetTargetLogs) + .WithDescription("Return log entries for a specific target within the deployment. Useful for diagnosing issues on an individual host or container instance. Returns 404 when the deployment or target does not exist."); + if (includeRouteNames) + { + targetLogs.WithName("Deployment_GetTargetLogs"); + } + + var events = group.MapGet("/{id}/events", GetDeploymentEvents) + .WithDescription("Return the chronological event stream for the specified deployment including status transitions, health check results, target progress updates, and rollback triggers."); + if (includeRouteNames) + { + events.WithName("Deployment_GetEvents"); + } + + var metrics = group.MapGet("/{id}/metrics", GetDeploymentMetrics) + .WithDescription("Return real-time and historical metrics for the specified deployment including duration, error rates, resource utilisation, and target-level health indicators."); + if (includeRouteNames) + { + metrics.WithName("Deployment_GetMetrics"); + } + + // --- Mutation endpoints --- + + var pause = group.MapPost("/{id}/pause", PauseDeployment) + .WithDescription("Pause the specified in-progress deployment, halting further target rollouts while keeping already-deployed targets running. Returns 409 if the deployment is not in a pausable state.") + .RequireAuthorization(JobEnginePolicies.ReleaseWrite); + if (includeRouteNames) + { + pause.WithName("Deployment_Pause"); + } + + var resume = group.MapPost("/{id}/resume", ResumeDeployment) + .WithDescription("Resume a previously paused deployment, continuing the rollout to remaining targets from where it was halted. Returns 409 if the deployment is not currently paused.") + .RequireAuthorization(JobEnginePolicies.ReleaseWrite); + if (includeRouteNames) + { + resume.WithName("Deployment_Resume"); + } + + var cancel = group.MapPost("/{id}/cancel", CancelDeployment) + .WithDescription("Cancel the specified deployment, stopping all in-progress rollouts and marking the deployment as cancelled. Already-deployed targets are not rolled back. Returns 409 if the deployment is already in a terminal state.") + .RequireAuthorization(JobEnginePolicies.ReleaseWrite); + if (includeRouteNames) + { + cancel.WithName("Deployment_Cancel"); + } + + var rollback = group.MapPost("/{id}/rollback", RollbackDeployment) + .WithDescription("Initiate a rollback of the specified deployment, reverting all targets to the previous stable version. The rollback is audited and creates corresponding events. Returns 409 if the deployment is not in a rollbackable state.") + .RequireAuthorization(JobEnginePolicies.ReleaseApprove); + if (includeRouteNames) + { + rollback.WithName("Deployment_Rollback"); + } + + var retryTarget = group.MapPost("/{id}/targets/{targetId}/retry", RetryTarget) + .WithDescription("Retry the deployment to a specific failed target within the deployment. Only targets in failed or error state can be retried. Returns 404 when the deployment or target does not exist; 409 when the target is not in a retryable state.") + .RequireAuthorization(JobEnginePolicies.ReleaseWrite); + if (includeRouteNames) + { + retryTarget.WithName("Deployment_RetryTarget"); + } + } + + // ---- Handlers ---- + + private static IResult ListDeployments( + [FromQuery] string? status, + [FromQuery] string? environment, + [FromQuery] string? releaseId, + [FromQuery] string? sortField, + [FromQuery] string? sortOrder, + [FromQuery] int? page, + [FromQuery] int? pageSize) + { + var deployments = SeedData.Deployments.AsEnumerable(); + + if (!string.IsNullOrWhiteSpace(status)) + { + var statusList = status.Split(',', StringSplitOptions.RemoveEmptyEntries); + deployments = deployments.Where(d => statusList.Contains(d.Status, StringComparer.OrdinalIgnoreCase)); + } + + if (!string.IsNullOrWhiteSpace(environment)) + { + deployments = deployments.Where(d => + string.Equals(d.Environment, environment, StringComparison.OrdinalIgnoreCase)); + } + + if (!string.IsNullOrWhiteSpace(releaseId)) + { + deployments = deployments.Where(d => + string.Equals(d.ReleaseId, releaseId, StringComparison.OrdinalIgnoreCase)); + } + + var sorted = (sortField?.ToLowerInvariant(), sortOrder?.ToLowerInvariant()) switch + { + ("status", "asc") => deployments.OrderBy(d => d.Status), + ("status", _) => deployments.OrderByDescending(d => d.Status), + ("environment", "asc") => deployments.OrderBy(d => d.Environment), + ("environment", _) => deployments.OrderByDescending(d => d.Environment), + (_, "asc") => deployments.OrderBy(d => d.StartedAt), + _ => deployments.OrderByDescending(d => d.StartedAt), + }; + + var all = sorted.ToList(); + var effectivePage = Math.Max(page ?? 1, 1); + var effectivePageSize = Math.Clamp(pageSize ?? 20, 1, 100); + var items = all.Skip((effectivePage - 1) * effectivePageSize).Take(effectivePageSize).ToList(); + + return Results.Ok(new + { + items, + totalCount = all.Count, + page = effectivePage, + pageSize = effectivePageSize, + }); + } + + private static IResult GetDeployment(string id) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + return deployment is not null ? Results.Ok(deployment) : Results.NotFound(); + } + + private static IResult GetDeploymentLogs( + string id, + [FromQuery] string? level, + [FromQuery] int? limit) + { + if (!SeedData.Deployments.Any(d => d.Id == id)) + return Results.NotFound(); + + return Results.Ok(new { entries = Array.Empty() }); + } + + private static IResult GetTargetLogs( + string id, + string targetId, + [FromQuery] string? level, + [FromQuery] int? limit) + { + if (!SeedData.Deployments.Any(d => d.Id == id)) + return Results.NotFound(); + + return Results.Ok(new { entries = Array.Empty() }); + } + + private static IResult GetDeploymentEvents(string id) + { + if (!SeedData.Deployments.Any(d => d.Id == id)) + return Results.NotFound(); + + if (!SeedData.Events.TryGetValue(id, out var events)) + return Results.Ok(new { events = Array.Empty() }); + + return Results.Ok(new { events }); + } + + private static IResult GetDeploymentMetrics(string id) + { + if (!SeedData.Deployments.Any(d => d.Id == id)) + return Results.NotFound(); + + return Results.Ok(new + { + metrics = new + { + durationSeconds = (int?)null, + errorRate = 0.0, + targetsTotal = 0, + targetsCompleted = 0, + targetsFailed = 0, + }, + }); + } + + private static IResult PauseDeployment(string id) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + if (deployment is null) return Results.NotFound(); + + if (deployment.Status is not ("in_progress" or "rolling")) + { + return Results.Conflict(new { success = false, message = $"Deployment {id} cannot be paused in status '{deployment.Status}'." }); + } + + return Results.Ok(new { success = true, message = $"Deployment {id} paused." }); + } + + private static IResult ResumeDeployment(string id) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + if (deployment is null) return Results.NotFound(); + + if (deployment.Status != "paused") + { + return Results.Conflict(new { success = false, message = $"Deployment {id} is not paused; current status is '{deployment.Status}'." }); + } + + return Results.Ok(new { success = true, message = $"Deployment {id} resumed." }); + } + + private static IResult CancelDeployment(string id) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + if (deployment is null) return Results.NotFound(); + + if (deployment.Status is "cancelled" or "completed" or "failed") + { + return Results.Conflict(new { success = false, message = $"Deployment {id} is already in terminal state '{deployment.Status}'." }); + } + + return Results.Ok(new { success = true, message = $"Deployment {id} cancelled." }); + } + + private static IResult RollbackDeployment(string id) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + if (deployment is null) return Results.NotFound(); + + if (deployment.Status is not ("completed" or "in_progress" or "rolling" or "paused")) + { + return Results.Conflict(new { success = false, message = $"Deployment {id} cannot be rolled back in status '{deployment.Status}'." }); + } + + return Results.Ok(new { success = true, message = $"Rollback initiated for deployment {id}." }); + } + + private static IResult RetryTarget(string id, string targetId) + { + var deployment = SeedData.Deployments.FirstOrDefault(d => d.Id == id); + if (deployment is null) return Results.NotFound(); + + var target = deployment.Targets.FirstOrDefault(t => t.Id == targetId); + if (target is null) return Results.NotFound(); + + if (target.Status is not ("failed" or "error")) + { + return Results.Conflict(new { success = false, message = $"Target {targetId} is not in a retryable state; current status is '{target.Status}'." }); + } + + return Results.Ok(new { success = true, message = $"Retry initiated for target {targetId} in deployment {id}." }); + } + + // ---- DTOs ---- + + public sealed record DeploymentDto + { + public required string Id { get; init; } + public required string ReleaseId { get; init; } + public required string ReleaseName { get; init; } + public required string ReleaseVersion { get; init; } + public required string Environment { get; init; } + public required string Status { get; init; } + public required string Strategy { get; init; } + public string? InitiatedBy { get; init; } + public DateTimeOffset StartedAt { get; init; } + public DateTimeOffset? CompletedAt { get; init; } + public int TargetsTotal { get; init; } + public int TargetsCompleted { get; init; } + public int TargetsFailed { get; init; } + public List Targets { get; init; } = new(); + } + + public sealed record DeploymentTargetDto + { + public required string Id { get; init; } + public required string Name { get; init; } + public required string Status { get; init; } + public string? Host { get; init; } + public DateTimeOffset? StartedAt { get; init; } + public DateTimeOffset? CompletedAt { get; init; } + public string? ErrorMessage { get; init; } + } + + public sealed record DeploymentEventDto + { + public required string Id { get; init; } + public required string DeploymentId { get; init; } + public required string Type { get; init; } + public required string Message { get; init; } + public string? TargetId { get; init; } + public string? Actor { get; init; } + public DateTimeOffset Timestamp { get; init; } + public Dictionary Metadata { get; init; } = new(); + } + + // ---- Seed Data ---- + + internal static class SeedData + { + public static readonly List Deployments = new() + { + new() + { + Id = "dep-001", + ReleaseId = "rel-001", + ReleaseName = "Platform Release", + ReleaseVersion = "1.2.3", + Environment = "production", + Status = "completed", + Strategy = "rolling", + InitiatedBy = "deploy-bot", + StartedAt = DateTimeOffset.Parse("2026-01-11T14:00:00Z"), + CompletedAt = DateTimeOffset.Parse("2026-01-11T14:30:00Z"), + TargetsTotal = 3, + TargetsCompleted = 3, + TargetsFailed = 0, + Targets = new() + { + new() { Id = "tgt-001", Name = "prod-host-01", Status = "completed", Host = "10.0.1.10", StartedAt = DateTimeOffset.Parse("2026-01-11T14:00:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-11T14:10:00Z") }, + new() { Id = "tgt-002", Name = "prod-host-02", Status = "completed", Host = "10.0.1.11", StartedAt = DateTimeOffset.Parse("2026-01-11T14:10:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-11T14:20:00Z") }, + new() { Id = "tgt-003", Name = "prod-host-03", Status = "completed", Host = "10.0.1.12", StartedAt = DateTimeOffset.Parse("2026-01-11T14:20:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-11T14:30:00Z") }, + }, + }, + new() + { + Id = "dep-002", + ReleaseId = "rel-003", + ReleaseName = "Hotfix", + ReleaseVersion = "1.2.4", + Environment = "production", + Status = "in_progress", + Strategy = "rolling", + InitiatedBy = "security-team", + StartedAt = DateTimeOffset.Parse("2026-01-12T10:00:00Z"), + TargetsTotal = 3, + TargetsCompleted = 1, + TargetsFailed = 0, + Targets = new() + { + new() { Id = "tgt-004", Name = "prod-host-01", Status = "completed", Host = "10.0.1.10", StartedAt = DateTimeOffset.Parse("2026-01-12T10:00:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-12T10:08:00Z") }, + new() { Id = "tgt-005", Name = "prod-host-02", Status = "in_progress", Host = "10.0.1.11", StartedAt = DateTimeOffset.Parse("2026-01-12T10:08:00Z") }, + new() { Id = "tgt-006", Name = "prod-host-03", Status = "pending", Host = "10.0.1.12" }, + }, + }, + new() + { + Id = "dep-003", + ReleaseId = "rel-002", + ReleaseName = "Platform Release", + ReleaseVersion = "1.3.0-rc1", + Environment = "staging", + Status = "completed", + Strategy = "blue_green", + InitiatedBy = "ci-pipeline", + StartedAt = DateTimeOffset.Parse("2026-01-11T12:00:00Z"), + CompletedAt = DateTimeOffset.Parse("2026-01-11T12:15:00Z"), + TargetsTotal = 2, + TargetsCompleted = 2, + TargetsFailed = 0, + Targets = new() + { + new() { Id = "tgt-007", Name = "staging-blue", Status = "completed", Host = "10.0.2.10", StartedAt = DateTimeOffset.Parse("2026-01-11T12:00:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-11T12:15:00Z") }, + new() { Id = "tgt-008", Name = "staging-green", Status = "completed", Host = "10.0.2.11", StartedAt = DateTimeOffset.Parse("2026-01-11T12:00:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-11T12:15:00Z") }, + }, + }, + new() + { + Id = "dep-004", + ReleaseId = "rel-005", + ReleaseName = "Platform Release", + ReleaseVersion = "1.2.2", + Environment = "production", + Status = "failed", + Strategy = "rolling", + InitiatedBy = "deploy-bot", + StartedAt = DateTimeOffset.Parse("2026-01-06T10:00:00Z"), + CompletedAt = DateTimeOffset.Parse("2026-01-06T10:25:00Z"), + TargetsTotal = 3, + TargetsCompleted = 1, + TargetsFailed = 2, + Targets = new() + { + new() { Id = "tgt-009", Name = "prod-host-01", Status = "completed", Host = "10.0.1.10", StartedAt = DateTimeOffset.Parse("2026-01-06T10:00:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-06T10:10:00Z") }, + new() { Id = "tgt-010", Name = "prod-host-02", Status = "failed", Host = "10.0.1.11", StartedAt = DateTimeOffset.Parse("2026-01-06T10:10:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-06T10:20:00Z"), ErrorMessage = "Health check failed after deployment: HTTP 503 on /healthz" }, + new() { Id = "tgt-011", Name = "prod-host-03", Status = "failed", Host = "10.0.1.12", StartedAt = DateTimeOffset.Parse("2026-01-06T10:20:00Z"), CompletedAt = DateTimeOffset.Parse("2026-01-06T10:25:00Z"), ErrorMessage = "Container failed to start: OOM killed" }, + }, + }, + }; + + public static readonly Dictionary> Events = new() + { + ["dep-001"] = new() + { + new() { Id = "devt-001", DeploymentId = "dep-001", Type = "started", Message = "Deployment started with rolling strategy", Actor = "deploy-bot", Timestamp = DateTimeOffset.Parse("2026-01-11T14:00:00Z") }, + new() { Id = "devt-002", DeploymentId = "dep-001", Type = "target_completed", Message = "Target prod-host-01 deployed successfully", TargetId = "tgt-001", Timestamp = DateTimeOffset.Parse("2026-01-11T14:10:00Z") }, + new() { Id = "devt-003", DeploymentId = "dep-001", Type = "target_completed", Message = "Target prod-host-02 deployed successfully", TargetId = "tgt-002", Timestamp = DateTimeOffset.Parse("2026-01-11T14:20:00Z") }, + new() { Id = "devt-004", DeploymentId = "dep-001", Type = "target_completed", Message = "Target prod-host-03 deployed successfully", TargetId = "tgt-003", Timestamp = DateTimeOffset.Parse("2026-01-11T14:30:00Z") }, + new() { Id = "devt-005", DeploymentId = "dep-001", Type = "completed", Message = "Deployment completed successfully — all targets healthy", Actor = "deploy-bot", Timestamp = DateTimeOffset.Parse("2026-01-11T14:30:00Z") }, + }, + ["dep-002"] = new() + { + new() { Id = "devt-006", DeploymentId = "dep-002", Type = "started", Message = "Hotfix deployment started with rolling strategy", Actor = "security-team", Timestamp = DateTimeOffset.Parse("2026-01-12T10:00:00Z") }, + new() { Id = "devt-007", DeploymentId = "dep-002", Type = "target_completed", Message = "Target prod-host-01 deployed successfully", TargetId = "tgt-004", Timestamp = DateTimeOffset.Parse("2026-01-12T10:08:00Z") }, + new() { Id = "devt-008", DeploymentId = "dep-002", Type = "target_started", Message = "Rolling to target prod-host-02", TargetId = "tgt-005", Timestamp = DateTimeOffset.Parse("2026-01-12T10:08:00Z") }, + }, + ["dep-004"] = new() + { + new() { Id = "devt-009", DeploymentId = "dep-004", Type = "started", Message = "Deployment started with rolling strategy", Actor = "deploy-bot", Timestamp = DateTimeOffset.Parse("2026-01-06T10:00:00Z") }, + new() { Id = "devt-010", DeploymentId = "dep-004", Type = "target_completed", Message = "Target prod-host-01 deployed successfully", TargetId = "tgt-009", Timestamp = DateTimeOffset.Parse("2026-01-06T10:10:00Z") }, + new() { Id = "devt-011", DeploymentId = "dep-004", Type = "target_failed", Message = "Target prod-host-02 failed health check", TargetId = "tgt-010", Timestamp = DateTimeOffset.Parse("2026-01-06T10:20:00Z") }, + new() { Id = "devt-012", DeploymentId = "dep-004", Type = "target_failed", Message = "Target prod-host-03 container OOM killed", TargetId = "tgt-011", Timestamp = DateTimeOffset.Parse("2026-01-06T10:25:00Z") }, + new() { Id = "devt-013", DeploymentId = "dep-004", Type = "failed", Message = "Deployment failed — 2 of 3 targets unhealthy", Actor = "deploy-bot", Timestamp = DateTimeOffset.Parse("2026-01-06T10:25:00Z") }, + }, + }; + } +} diff --git a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/EvidenceEndpoints.cs b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/EvidenceEndpoints.cs new file mode 100644 index 000000000..715be4243 --- /dev/null +++ b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/EvidenceEndpoints.cs @@ -0,0 +1,323 @@ +using Microsoft.AspNetCore.Mvc; +using StellaOps.Auth.ServerIntegration.Tenancy; + +namespace StellaOps.JobEngine.WebService.Endpoints; + +/// +/// Evidence management endpoints for the release orchestrator. +/// Provides listing, inspection, verification, export, and timeline +/// operations for release evidence packets. +/// Routes: /api/release-orchestrator/evidence +/// +public static class EvidenceEndpoints +{ + public static IEndpointRouteBuilder MapEvidenceEndpoints(this IEndpointRouteBuilder app) + { + MapEvidenceGroup(app, "/api/release-orchestrator/evidence", includeRouteNames: true); + MapEvidenceGroup(app, "/api/v1/release-orchestrator/evidence", includeRouteNames: false); + + return app; + } + + private static void MapEvidenceGroup( + IEndpointRouteBuilder app, + string prefix, + bool includeRouteNames) + { + var group = app.MapGroup(prefix) + .WithTags("Evidence") + .RequireAuthorization(JobEnginePolicies.ReleaseRead) + .RequireTenant(); + + var list = group.MapGet(string.Empty, ListEvidence) + .WithDescription("Return a paginated list of evidence packets for the calling tenant, optionally filtered by release, type, and creation time window. Each packet includes its identifier, associated release, evidence type, content hash, and creation timestamp."); + if (includeRouteNames) + { + list.WithName("Evidence_List"); + } + + var detail = group.MapGet("/{id}", GetEvidence) + .WithDescription("Return the full evidence packet record for the specified ID including release association, evidence type, content hash, algorithm, size, and metadata. Returns 404 when the evidence packet does not exist in the tenant."); + if (includeRouteNames) + { + detail.WithName("Evidence_Get"); + } + + var verify = group.MapPost("/{id}/verify", VerifyEvidence) + .WithDescription("Verify the integrity of the specified evidence packet by recomputing and comparing its content hash. Returns the verification result including the computed hash, algorithm used, and whether the content matches the stored digest."); + if (includeRouteNames) + { + verify.WithName("Evidence_Verify"); + } + + var export = group.MapGet("/{id}/export", ExportEvidence) + .WithDescription("Export the specified evidence packet as a self-contained JSON bundle suitable for offline audit. The bundle includes the evidence metadata, content, and verification hashes."); + if (includeRouteNames) + { + export.WithName("Evidence_Export"); + } + + var raw = group.MapGet("/{id}/raw", DownloadRaw) + .WithDescription("Download the raw binary content of the specified evidence packet. Returns the unprocessed evidence payload with Content-Type application/octet-stream. Returns 404 when the evidence packet does not exist."); + if (includeRouteNames) + { + raw.WithName("Evidence_DownloadRaw"); + } + + var timeline = group.MapGet("/{id}/timeline", GetTimeline) + .WithDescription("Return the chronological event timeline for the specified evidence packet including creation, verification, export, and access events. Useful for audit trails and provenance tracking."); + if (includeRouteNames) + { + timeline.WithName("Evidence_Timeline"); + } + } + + // ---- Handlers ---- + + private static IResult ListEvidence( + [FromQuery] string? releaseId, + [FromQuery] string? type, + [FromQuery] string? search, + [FromQuery] string? sortField, + [FromQuery] string? sortOrder, + [FromQuery] int? page, + [FromQuery] int? pageSize) + { + var packets = SeedData.EvidencePackets.AsEnumerable(); + + if (!string.IsNullOrWhiteSpace(releaseId)) + { + packets = packets.Where(e => + string.Equals(e.ReleaseId, releaseId, StringComparison.OrdinalIgnoreCase)); + } + + if (!string.IsNullOrWhiteSpace(type)) + { + packets = packets.Where(e => + string.Equals(e.Type, type, StringComparison.OrdinalIgnoreCase)); + } + + if (!string.IsNullOrWhiteSpace(search)) + { + var term = search.ToLowerInvariant(); + packets = packets.Where(e => + e.Id.Contains(term, StringComparison.OrdinalIgnoreCase) || + e.ReleaseId.Contains(term, StringComparison.OrdinalIgnoreCase) || + e.Type.Contains(term, StringComparison.OrdinalIgnoreCase) || + e.Description.Contains(term, StringComparison.OrdinalIgnoreCase)); + } + + var sorted = (sortField?.ToLowerInvariant(), sortOrder?.ToLowerInvariant()) switch + { + ("type", "asc") => packets.OrderBy(e => e.Type), + ("type", _) => packets.OrderByDescending(e => e.Type), + ("releaseId", "asc") => packets.OrderBy(e => e.ReleaseId), + ("releaseId", _) => packets.OrderByDescending(e => e.ReleaseId), + (_, "asc") => packets.OrderBy(e => e.CreatedAt), + _ => packets.OrderByDescending(e => e.CreatedAt), + }; + + var all = sorted.ToList(); + var effectivePage = Math.Max(page ?? 1, 1); + var effectivePageSize = Math.Clamp(pageSize ?? 20, 1, 100); + var items = all.Skip((effectivePage - 1) * effectivePageSize).Take(effectivePageSize).ToList(); + + return Results.Ok(new + { + items, + totalCount = all.Count, + page = effectivePage, + pageSize = effectivePageSize, + }); + } + + private static IResult GetEvidence(string id) + { + var packet = SeedData.EvidencePackets.FirstOrDefault(e => e.Id == id); + return packet is not null ? Results.Ok(packet) : Results.NotFound(); + } + + private static IResult VerifyEvidence(string id) + { + var packet = SeedData.EvidencePackets.FirstOrDefault(e => e.Id == id); + if (packet is null) return Results.NotFound(); + + return Results.Ok(new + { + evidenceId = packet.Id, + verified = true, + hash = packet.Hash, + algorithm = packet.Algorithm, + verifiedAt = DateTimeOffset.UtcNow, + message = "Evidence integrity verified successfully.", + }); + } + + private static IResult ExportEvidence(string id) + { + var packet = SeedData.EvidencePackets.FirstOrDefault(e => e.Id == id); + if (packet is null) return Results.NotFound(); + + var bundle = new + { + exportVersion = "1.0", + exportedAt = DateTimeOffset.UtcNow, + evidence = packet, + verification = new + { + hash = packet.Hash, + algorithm = packet.Algorithm, + verified = true, + }, + }; + + return Results.Json(bundle, contentType: "application/json"); + } + + private static IResult DownloadRaw(string id) + { + var packet = SeedData.EvidencePackets.FirstOrDefault(e => e.Id == id); + if (packet is null) return Results.NotFound(); + + // Return mock raw bytes representing the evidence content + var content = System.Text.Encoding.UTF8.GetBytes( + $"{{\"evidenceId\":\"{packet.Id}\",\"type\":\"{packet.Type}\",\"raw\":true}}"); + + return Results.Bytes(content, contentType: "application/octet-stream", + fileDownloadName: $"{packet.Id}.bin"); + } + + private static IResult GetTimeline(string id) + { + var packet = SeedData.EvidencePackets.FirstOrDefault(e => e.Id == id); + if (packet is null) return Results.NotFound(); + + if (SeedData.Timelines.TryGetValue(id, out var events)) + { + return Results.Ok(new { evidenceId = id, events }); + } + + return Results.Ok(new { evidenceId = id, events = Array.Empty() }); + } + + // ---- DTOs ---- + + public sealed record EvidencePacketDto + { + public required string Id { get; init; } + public required string ReleaseId { get; init; } + public required string Type { get; init; } + public required string Description { get; init; } + public required string Hash { get; init; } + public required string Algorithm { get; init; } + public long SizeBytes { get; init; } + public required string Status { get; init; } + public required string CreatedBy { get; init; } + public DateTimeOffset CreatedAt { get; init; } + public DateTimeOffset? VerifiedAt { get; init; } + } + + public sealed record EvidenceTimelineEventDto + { + public required string Id { get; init; } + public required string EvidenceId { get; init; } + public required string EventType { get; init; } + public required string Actor { get; init; } + public required string Message { get; init; } + public DateTimeOffset Timestamp { get; init; } + } + + // ---- Seed Data ---- + + internal static class SeedData + { + public static readonly List EvidencePackets = new() + { + new() + { + Id = "evi-001", + ReleaseId = "rel-001", + Type = "sbom", + Description = "Software Bill of Materials for Platform Release v1.2.3", + Hash = "sha256:a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2", + Algorithm = "SHA-256", + SizeBytes = 24576, + Status = "verified", + CreatedBy = "ci-pipeline", + CreatedAt = DateTimeOffset.Parse("2026-01-10T08:15:00Z"), + VerifiedAt = DateTimeOffset.Parse("2026-01-10T08:16:00Z"), + }, + new() + { + Id = "evi-002", + ReleaseId = "rel-001", + Type = "attestation", + Description = "Build provenance attestation for Platform Release v1.2.3", + Hash = "sha256:b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3", + Algorithm = "SHA-256", + SizeBytes = 8192, + Status = "verified", + CreatedBy = "attestor-service", + CreatedAt = DateTimeOffset.Parse("2026-01-10T08:20:00Z"), + VerifiedAt = DateTimeOffset.Parse("2026-01-10T08:21:00Z"), + }, + new() + { + Id = "evi-003", + ReleaseId = "rel-002", + Type = "scan-result", + Description = "Security scan results for Platform Release v1.3.0-rc1", + Hash = "sha256:c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4", + Algorithm = "SHA-256", + SizeBytes = 16384, + Status = "verified", + CreatedBy = "scanner-service", + CreatedAt = DateTimeOffset.Parse("2026-01-11T10:30:00Z"), + VerifiedAt = DateTimeOffset.Parse("2026-01-11T10:31:00Z"), + }, + new() + { + Id = "evi-004", + ReleaseId = "rel-003", + Type = "policy-decision", + Description = "Policy gate evaluation for Hotfix v1.2.4", + Hash = "sha256:d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5", + Algorithm = "SHA-256", + SizeBytes = 4096, + Status = "pending", + CreatedBy = "policy-engine", + CreatedAt = DateTimeOffset.Parse("2026-01-12T06:15:00Z"), + }, + new() + { + Id = "evi-005", + ReleaseId = "rel-001", + Type = "deployment-log", + Description = "Production deployment log for Platform Release v1.2.3", + Hash = "sha256:e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6", + Algorithm = "SHA-256", + SizeBytes = 32768, + Status = "verified", + CreatedBy = "deploy-bot", + CreatedAt = DateTimeOffset.Parse("2026-01-11T14:35:00Z"), + VerifiedAt = DateTimeOffset.Parse("2026-01-11T14:36:00Z"), + }, + }; + + public static readonly Dictionary> Timelines = new() + { + ["evi-001"] = new() + { + new() { Id = "evt-e001", EvidenceId = "evi-001", EventType = "created", Actor = "ci-pipeline", Message = "SBOM evidence packet created from build pipeline", Timestamp = DateTimeOffset.Parse("2026-01-10T08:15:00Z") }, + new() { Id = "evt-e002", EvidenceId = "evi-001", EventType = "hashed", Actor = "evidence-locker", Message = "Content hash computed: SHA-256", Timestamp = DateTimeOffset.Parse("2026-01-10T08:15:30Z") }, + new() { Id = "evt-e003", EvidenceId = "evi-001", EventType = "verified", Actor = "attestor-service", Message = "Integrity verification passed", Timestamp = DateTimeOffset.Parse("2026-01-10T08:16:00Z") }, + new() { Id = "evt-e004", EvidenceId = "evi-001", EventType = "exported", Actor = "admin", Message = "Evidence bundle exported for audit", Timestamp = DateTimeOffset.Parse("2026-01-10T12:00:00Z") }, + }, + ["evi-002"] = new() + { + new() { Id = "evt-e005", EvidenceId = "evi-002", EventType = "created", Actor = "attestor-service", Message = "Build provenance attestation generated", Timestamp = DateTimeOffset.Parse("2026-01-10T08:20:00Z") }, + new() { Id = "evt-e006", EvidenceId = "evi-002", EventType = "verified", Actor = "attestor-service", Message = "Attestation signature verified", Timestamp = DateTimeOffset.Parse("2026-01-10T08:21:00Z") }, + }, + }; + } +} diff --git a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/ReleaseDashboardEndpoints.cs b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/ReleaseDashboardEndpoints.cs index a63e4301b..fd1bd8b40 100644 --- a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/ReleaseDashboardEndpoints.cs +++ b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Endpoints/ReleaseDashboardEndpoints.cs @@ -49,27 +49,75 @@ public static class ReleaseDashboardEndpoints private static IResult GetDashboard() { - return Results.Ok(ReleaseDashboardSnapshotBuilder.Build()); + var snapshot = ReleaseDashboardSnapshotBuilder.Build(); + + var releases = ReleaseEndpoints.SeedData.Releases; + var approvals = ApprovalEndpoints.SeedData.Approvals; + + var byStatus = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["draft"] = releases.Count(r => string.Equals(r.Status, "draft", StringComparison.OrdinalIgnoreCase)), + ["ready"] = releases.Count(r => string.Equals(r.Status, "ready", StringComparison.OrdinalIgnoreCase)), + ["deploying"] = releases.Count(r => string.Equals(r.Status, "deploying", StringComparison.OrdinalIgnoreCase)), + ["deployed"] = releases.Count(r => string.Equals(r.Status, "deployed", StringComparison.OrdinalIgnoreCase)), + ["failed"] = releases.Count(r => string.Equals(r.Status, "failed", StringComparison.OrdinalIgnoreCase)), + }; + + var allGates = approvals.SelectMany(a => a.GateResults).ToList(); + var gatesSummary = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["pass"] = allGates.Count(g => string.Equals(g.Status, "passed", StringComparison.OrdinalIgnoreCase)), + ["warn"] = allGates.Count(g => string.Equals(g.Status, "warning", StringComparison.OrdinalIgnoreCase)), + ["block"] = allGates.Count(g => string.Equals(g.Status, "failed", StringComparison.OrdinalIgnoreCase)), + }; + + var recentActivity = snapshot.RecentReleases + .Select(r => new + { + r.Id, + r.Name, + r.Version, + r.Status, + r.CurrentEnvironment, + r.CreatedAt, + r.CreatedBy, + }) + .ToList(); + + return Results.Ok(new + { + totalReleases = releases.Count, + byStatus, + pendingApprovals = snapshot.PendingApprovals.Count, + activeDeployments = snapshot.ActiveDeployments.Count, + gatesSummary, + recentActivity, + pipeline = snapshot.PipelineData, + pendingApprovalDetails = snapshot.PendingApprovals, + activeDeploymentDetails = snapshot.ActiveDeployments, + }); } private static IResult ApprovePromotion(string id) { - var exists = ApprovalEndpoints.SeedData.Approvals - .Any(approval => string.Equals(approval.Id, id, StringComparison.OrdinalIgnoreCase)); + var approval = ApprovalEndpoints.SeedData.Approvals + .FirstOrDefault(a => string.Equals(a.Id, id, StringComparison.OrdinalIgnoreCase)); - return exists - ? Results.NoContent() - : Results.NotFound(new { message = $"Promotion '{id}' was not found." }); + if (approval is null) + return Results.NotFound(new { message = $"Promotion '{id}' was not found." }); + + return Results.Ok(new { success = true, promotionId = id, action = "approved" }); } private static IResult RejectPromotion(string id, [FromBody] RejectPromotionRequest? request) { - var exists = ApprovalEndpoints.SeedData.Approvals - .Any(approval => string.Equals(approval.Id, id, StringComparison.OrdinalIgnoreCase)); + var approval = ApprovalEndpoints.SeedData.Approvals + .FirstOrDefault(a => string.Equals(a.Id, id, StringComparison.OrdinalIgnoreCase)); - return exists - ? Results.NoContent() - : Results.NotFound(new { message = $"Promotion '{id}' was not found." }); + if (approval is null) + return Results.NotFound(new { message = $"Promotion '{id}' was not found." }); + + return Results.Ok(new { success = true, promotionId = id, action = "rejected", reason = request?.Reason }); } public sealed record RejectPromotionRequest(string? Reason); diff --git a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs index 5a9b78a15..aee203673 100644 --- a/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs +++ b/src/JobEngine/StellaOps.JobEngine/StellaOps.JobEngine.WebService/Program.cs @@ -196,11 +196,13 @@ app.MapQuotaGovernanceEndpoints(); // Register dead-letter queue management endpoints app.MapDeadLetterEndpoints(); -// Register release management and approval endpoints +// Register release management, approval, and deployment monitoring endpoints app.MapReleaseEndpoints(); app.MapApprovalEndpoints(); +app.MapDeploymentEndpoints(); app.MapReleaseDashboardEndpoints(); app.MapReleaseControlV2Endpoints(); +app.MapEvidenceEndpoints(); app.MapAuditEndpoints(); // Refresh Router endpoint cache diff --git a/src/Scanner/StellaOps.Scanner.WebService/Endpoints/RegistryEndpoints.cs b/src/Scanner/StellaOps.Scanner.WebService/Endpoints/RegistryEndpoints.cs new file mode 100644 index 000000000..f2553d9d1 --- /dev/null +++ b/src/Scanner/StellaOps.Scanner.WebService/Endpoints/RegistryEndpoints.cs @@ -0,0 +1,259 @@ +// ----------------------------------------------------------------------------- +// RegistryEndpoints.cs +// Description: HTTP endpoints for registry image search and digest lookup. +// Returns mock data until real registry integration is wired. +// ----------------------------------------------------------------------------- + +using Microsoft.AspNetCore.Http; +using Microsoft.AspNetCore.Routing; +using StellaOps.Scanner.WebService.Security; + +namespace StellaOps.Scanner.WebService.Endpoints; + +/// +/// Endpoints for container registry image search and digest queries. +/// Used by Create Version / Create Hotfix wizards in the UI. +/// +internal static class RegistryEndpoints +{ + /// + /// Maps registry image endpoints under /registries. + /// + public static void MapRegistryEndpoints(this RouteGroupBuilder apiGroup, string prefix = "/registries") + { + ArgumentNullException.ThrowIfNull(apiGroup); + + var group = apiGroup.MapGroup(prefix) + .WithTags("Registries"); + + // GET /api/v1/registries/images/search?q={query} + group.MapGet("/images/search", HandleSearchImages) + .WithName("scanner.registries.images.search") + .WithDescription("Search container registry images by name") + .Produces(StatusCodes.Status200OK) + .Produces(StatusCodes.Status400BadRequest) + .RequireAuthorization(ScannerPolicies.ScansRead); + + // GET /api/v1/registries/images/digests?repository={repo} + group.MapGet("/images/digests", HandleGetImageDigests) + .WithName("scanner.registries.images.digests") + .WithDescription("Get image digests and tags for a repository") + .Produces(StatusCodes.Status200OK) + .Produces(StatusCodes.Status400BadRequest) + .RequireAuthorization(ScannerPolicies.ScansRead); + } + + private static IResult HandleSearchImages(string? q) + { + if (string.IsNullOrWhiteSpace(q) || q.Length < 2) + { + return Results.BadRequest(new { error = "Query must be at least 2 characters" }); + } + + var filtered = MockImages.Where(i => + i.Name.Contains(q, StringComparison.OrdinalIgnoreCase) || + i.Repository.Contains(q, StringComparison.OrdinalIgnoreCase) + ).ToArray(); + + return Results.Ok(new RegistrySearchResponse + { + Items = filtered, + TotalCount = filtered.Length, + RegistryId = null + }); + } + + private static IResult HandleGetImageDigests(string? repository) + { + if (string.IsNullOrWhiteSpace(repository)) + { + return Results.BadRequest(new { error = "Repository parameter is required" }); + } + + var match = MockImages.FirstOrDefault(i => + string.Equals(i.Repository, repository, StringComparison.OrdinalIgnoreCase)); + + if (match is null) + { + // Return a stub for unknown repositories + var repoName = repository.Contains('/') + ? repository.Split('/').Last() + : repository; + + return Results.Ok(new RegistryDigestResponse + { + Name = repoName, + Repository = repository, + Tags = new[] { "latest" }, + Digests = new[] + { + new RegistryDigestEntry + { + Tag = "latest", + Digest = $"sha256:{Guid.NewGuid():N}", + PushedAt = "2026-03-20T10:00:00Z" + } + } + }); + } + + return Results.Ok(new RegistryDigestResponse + { + Name = match.Name, + Repository = match.Repository, + Tags = match.Tags, + Digests = match.Digests + }); + } + + // ------------------------------------------------------------------------- + // Response DTOs + // ------------------------------------------------------------------------- + + internal sealed class RegistrySearchResponse + { + public RegistryImageDto[] Items { get; set; } = Array.Empty(); + public int TotalCount { get; set; } + public string? RegistryId { get; set; } + } + + internal sealed class RegistryDigestResponse + { + public string Name { get; set; } = string.Empty; + public string Repository { get; set; } = string.Empty; + public string[] Tags { get; set; } = Array.Empty(); + public RegistryDigestEntry[] Digests { get; set; } = Array.Empty(); + } + + internal sealed class RegistryImageDto + { + public string Name { get; set; } = string.Empty; + public string Repository { get; set; } = string.Empty; + public string[] Tags { get; set; } = Array.Empty(); + public RegistryDigestEntry[] Digests { get; set; } = Array.Empty(); + public string LastPushed { get; set; } = string.Empty; + } + + internal sealed class RegistryDigestEntry + { + public string Tag { get; set; } = string.Empty; + public string Digest { get; set; } = string.Empty; + public string PushedAt { get; set; } = string.Empty; + } + + // ------------------------------------------------------------------------- + // Mock data (to be replaced with real registry integration) + // ------------------------------------------------------------------------- + + private static readonly RegistryImageDto[] MockImages = new[] + { + new RegistryImageDto + { + Name = "nginx", + Repository = "library/nginx", + Tags = new[] { "latest", "1.27", "1.27-alpine" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2", PushedAt = "2026-03-20T10:00:00Z" }, + new RegistryDigestEntry { Tag = "1.27", Digest = "sha256:b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3", PushedAt = "2026-03-18T14:30:00Z" }, + }, + LastPushed = "2026-03-20T10:00:00Z" + }, + new RegistryImageDto + { + Name = "redis", + Repository = "library/redis", + Tags = new[] { "latest", "7.4", "7.4-alpine" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4", PushedAt = "2026-03-19T08:00:00Z" }, + new RegistryDigestEntry { Tag = "7.4", Digest = "sha256:d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5", PushedAt = "2026-03-17T16:45:00Z" }, + }, + LastPushed = "2026-03-19T08:00:00Z" + }, + new RegistryImageDto + { + Name = "postgres", + Repository = "library/postgres", + Tags = new[] { "latest", "16.2", "16.2-alpine" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6", PushedAt = "2026-03-21T06:15:00Z" }, + new RegistryDigestEntry { Tag = "16.2", Digest = "sha256:f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7", PushedAt = "2026-03-15T09:30:00Z" }, + }, + LastPushed = "2026-03-21T06:15:00Z" + }, + new RegistryImageDto + { + Name = "api-gateway", + Repository = "stella-ops/api-gateway", + Tags = new[] { "latest", "2.8.1", "2.8.0" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8", PushedAt = "2026-03-22T11:00:00Z" }, + new RegistryDigestEntry { Tag = "2.8.1", Digest = "sha256:b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9", PushedAt = "2026-03-22T11:00:00Z" }, + }, + LastPushed = "2026-03-22T11:00:00Z" + }, + new RegistryImageDto + { + Name = "payment-svc", + Repository = "stella-ops/payment-svc", + Tags = new[] { "latest", "3.1.0", "3.0.9" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0", PushedAt = "2026-03-21T17:20:00Z" }, + new RegistryDigestEntry { Tag = "3.1.0", Digest = "sha256:d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1", PushedAt = "2026-03-21T17:20:00Z" }, + }, + LastPushed = "2026-03-21T17:20:00Z" + }, + new RegistryImageDto + { + Name = "auth-service", + Repository = "stella-ops/auth-service", + Tags = new[] { "latest", "1.14.2", "1.14.1" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2", PushedAt = "2026-03-20T13:45:00Z" }, + new RegistryDigestEntry { Tag = "1.14.2", Digest = "sha256:f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3", PushedAt = "2026-03-20T13:45:00Z" }, + }, + LastPushed = "2026-03-20T13:45:00Z" + }, + new RegistryImageDto + { + Name = "node", + Repository = "library/node", + Tags = new[] { "latest", "22-alpine", "20-slim" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4", PushedAt = "2026-03-22T07:00:00Z" }, + new RegistryDigestEntry { Tag = "22-alpine", Digest = "sha256:b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5", PushedAt = "2026-03-22T07:00:00Z" }, + }, + LastPushed = "2026-03-22T07:00:00Z" + }, + new RegistryImageDto + { + Name = "python", + Repository = "library/python", + Tags = new[] { "latest", "3.13-slim", "3.12-bookworm" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6", PushedAt = "2026-03-21T09:30:00Z" }, + new RegistryDigestEntry { Tag = "3.13-slim", Digest = "sha256:d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7", PushedAt = "2026-03-21T09:30:00Z" }, + }, + LastPushed = "2026-03-21T09:30:00Z" + }, + new RegistryImageDto + { + Name = "golang", + Repository = "library/golang", + Tags = new[] { "latest", "1.23-alpine", "1.22-bookworm" }, + Digests = new[] + { + new RegistryDigestEntry { Tag = "latest", Digest = "sha256:e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8", PushedAt = "2026-03-20T15:00:00Z" }, + new RegistryDigestEntry { Tag = "1.23-alpine", Digest = "sha256:f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9", PushedAt = "2026-03-20T15:00:00Z" }, + }, + LastPushed = "2026-03-20T15:00:00Z" + }, + }; +} diff --git a/src/Scanner/StellaOps.Scanner.WebService/Program.cs b/src/Scanner/StellaOps.Scanner.WebService/Program.cs index 265e12a63..958f2601b 100644 --- a/src/Scanner/StellaOps.Scanner.WebService/Program.cs +++ b/src/Scanner/StellaOps.Scanner.WebService/Program.cs @@ -805,6 +805,7 @@ apiGroup.MapUnknownsEndpoints(); apiGroup.MapSecretDetectionSettingsEndpoints(); // Sprint: SPRINT_20260104_006_BE apiGroup.MapSecurityAdapterEndpoints(); // Pack v2 security adapter routes apiGroup.MapScanPolicyEndpoints(); // Sprint: S1-T03 Scan Policy CRUD +apiGroup.MapRegistryEndpoints(); // Registry image search + digest lookup for release wizards if (resolvedOptions.Features.EnablePolicyPreview) { diff --git a/src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/ElkSharpEdgeRefinementTests.cs b/src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/ElkSharpEdgeRefinementTests.cs new file mode 100644 index 000000000..c29cc6759 --- /dev/null +++ b/src/Workflow/__Tests/StellaOps.Workflow.Renderer.Tests/ElkSharpEdgeRefinementTests.cs @@ -0,0 +1,97 @@ +using System.Text.Json; + +using FluentAssertions; +using NUnit.Framework; + +using StellaOps.ElkSharp; + +namespace StellaOps.Workflow.Renderer.Tests; + +[TestFixture] +public class ElkSharpEdgeRefinementTests +{ + [Test] + [Property("Intent", "Operational")] + public async Task LayoutAsync_WhenBestEffortRenderedTwice_ShouldProduceDeterministicGeometry() + { + var graph = BuildElkSharpStressGraph(); + var engine = new ElkSharpLayeredLayoutEngine(); + var options = new ElkLayoutOptions + { + Direction = ElkLayoutDirection.LeftToRight, + Effort = ElkLayoutEffort.Best, + OrderingIterations = 18, + PlacementIterations = 10, + }; + + var first = await engine.LayoutAsync(graph, options); + var second = await engine.LayoutAsync(graph, options); + + JsonSerializer.Serialize(first).Should().Be(JsonSerializer.Serialize(second)); + } + + [Test] + [Property("Intent", "Operational")] + public async Task LayoutAsync_WhenTopToBottomRefinementEnabled_ShouldMatchDisabledOutput() + { + var graph = BuildElkSharpStressGraph(); + var engine = new ElkSharpLayeredLayoutEngine(); + + var baseline = await engine.LayoutAsync(graph, new ElkLayoutOptions + { + Direction = ElkLayoutDirection.TopToBottom, + Effort = ElkLayoutEffort.Best, + OrderingIterations = 18, + PlacementIterations = 10, + EdgeRefinement = new EdgeRefinementOptions + { + Enabled = false, + }, + }); + + var refined = await engine.LayoutAsync(graph, new ElkLayoutOptions + { + Direction = ElkLayoutDirection.TopToBottom, + Effort = ElkLayoutEffort.Best, + OrderingIterations = 18, + PlacementIterations = 10, + EdgeRefinement = new EdgeRefinementOptions + { + Enabled = true, + MaxGlobalPasses = 2, + MaxTrialsPerProblemEdge = 4, + }, + }); + + JsonSerializer.Serialize(refined).Should().Be(JsonSerializer.Serialize(baseline)); + } + + private static ElkGraph BuildElkSharpStressGraph() + { + return new ElkGraph + { + Id = "elksharp-refinement", + Nodes = + [ + new ElkNode { Id = "start", Label = "Start", Kind = "Start", Width = 88, Height = 48 }, + new ElkNode { Id = "review", Label = "Review", Kind = "Decision", Width = 176, Height = 120 }, + new ElkNode { Id = "approve", Label = "Approve", Kind = "Task", Width = 176, Height = 84 }, + new ElkNode { Id = "retry", Label = "Retry", Kind = "Task", Width = 176, Height = 84 }, + new ElkNode { Id = "notify", Label = "Notify", Kind = "Task", Width = 176, Height = 84 }, + new ElkNode { Id = "archive", Label = "Archive", Kind = "Task", Width = 176, Height = 84 }, + new ElkNode { Id = "end", Label = "End", Kind = "End", Width = 88, Height = 48 }, + ], + Edges = + [ + new ElkEdge { Id = "start-review", SourceNodeId = "start", TargetNodeId = "review" }, + new ElkEdge { Id = "review-approve", SourceNodeId = "review", TargetNodeId = "approve", Label = "when approved" }, + new ElkEdge { Id = "review-retry", SourceNodeId = "review", TargetNodeId = "retry", Label = "on failure" }, + new ElkEdge { Id = "approve-notify", SourceNodeId = "approve", TargetNodeId = "notify" }, + new ElkEdge { Id = "retry-review", SourceNodeId = "retry", TargetNodeId = "review", Label = "repeat while retry" }, + new ElkEdge { Id = "notify-end", SourceNodeId = "notify", TargetNodeId = "end", Label = "default" }, + new ElkEdge { Id = "approve-archive", SourceNodeId = "approve", TargetNodeId = "archive" }, + new ElkEdge { Id = "archive-end", SourceNodeId = "archive", TargetNodeId = "end", Label = "default" }, + ], + }; + } +} diff --git a/src/__Libraries/StellaOps.ElkSharp/AGENTS.md b/src/__Libraries/StellaOps.ElkSharp/AGENTS.md new file mode 100644 index 000000000..d890abccc --- /dev/null +++ b/src/__Libraries/StellaOps.ElkSharp/AGENTS.md @@ -0,0 +1,24 @@ +# AGENTS.md · StellaOps.ElkSharp + +## Scope +- Working directory: `src/__Libraries/StellaOps.ElkSharp/` +- This library provides deterministic in-process layout primitives for workflow rendering. +- Prefer additive, tightly scoped changes that preserve the current routing contract before introducing new behavior. + +## Required Reading +- `docs/code-of-conduct/CODE_OF_CONDUCT.md` +- `docs/code-of-conduct/TESTING_PRACTICES.md` +- `docs/workflow/ENGINE.md` +- The active sprint in `docs/implplan/` covering ElkSharp work + +## Local Rules +- Preserve deterministic output for the same graph and options. Do not introduce random tie-breaking. +- Keep orthogonal routing as the default contract unless a sprint explicitly broadens it. +- Treat channel assignment, dummy-edge reconstruction, and anchor selection as authoritative upstream inputs. +- Do not replace corridor and backward-route behavior with generic rerouting unless the sprint explicitly changes that contract. +- Keep `TopToBottom` behavior stable unless the sprint explicitly includes it. + +## Testing +- Run the targeted workflow renderer test project for ElkSharp changes. +- Add regression tests for geometry-sensitive behavior before broad refactors. +- Prefer assertions on concrete node and edge geometry over build-only validation. diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessorAStar.cs b/src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessorAStar.cs index 2ce4301f1..8fb5186ea 100644 --- a/src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessorAStar.cs +++ b/src/__Libraries/StellaOps.ElkSharp/ElkEdgePostProcessorAStar.cs @@ -7,16 +7,35 @@ internal static class ElkEdgePostProcessorAStar (double Left, double Top, double Right, double Bottom, string Id)[] obstacles, string sourceId, string targetId, double margin) + { + return RerouteWithGridAStar( + start, + end, + obstacles, + sourceId, + targetId, + new OrthogonalAStarOptions(margin, 200d, 0d, 14d), + [], + CancellationToken.None); + } + + internal static List? RerouteWithGridAStar( + ElkPoint start, ElkPoint end, + (double Left, double Top, double Right, double Bottom, string Id)[] obstacles, + string sourceId, string targetId, + OrthogonalAStarOptions options, + IReadOnlyList softObstacles, + CancellationToken cancellationToken) { var xs = new SortedSet { start.X, end.X }; var ys = new SortedSet { start.Y, end.Y }; foreach (var ob in obstacles) { if (ob.Id == sourceId || ob.Id == targetId) continue; - xs.Add(ob.Left - margin); - xs.Add(ob.Right + margin); - ys.Add(ob.Top - margin); - ys.Add(ob.Bottom + margin); + xs.Add(ob.Left - options.Margin); + xs.Add(ob.Right + options.Margin); + ys.Add(ob.Top - options.Margin); + ys.Add(ob.Bottom + options.Margin); } var xArr = xs.ToArray(); @@ -64,7 +83,6 @@ internal static class ElkEdgePostProcessorAStar } // A* with (ix, iy, direction) state; direction: 0=none, 1=horizontal, 2=vertical - const double bendPenalty = 200d; var stateCount = xCount * yCount * 3; var gScore = new double[stateCount]; Array.Fill(gScore, double.MaxValue); @@ -89,6 +107,8 @@ internal static class ElkEdgePostProcessorAStar var closed = new HashSet(); while (openSet.Count > 0 && iterations++ < maxIterations) { + cancellationToken.ThrowIfCancellationRequested(); + var current = openSet.Dequeue(); if (!closed.Add(current)) @@ -139,9 +159,16 @@ internal static class ElkEdgePostProcessorAStar if (IsBlocked(curIx, curIy, nx, ny)) continue; var newDir = dirs[d]; - var bend = (curDir != 0 && curDir != newDir) ? bendPenalty : 0d; + var bend = (curDir != 0 && curDir != newDir) ? options.BendPenalty : 0d; var dist = Math.Abs(xArr[nx] - xArr[curIx]) + Math.Abs(yArr[ny] - yArr[curIy]); - var tentativeG = gScore[current] + dist + bend; + var softCost = ComputeSoftObstacleCost( + xArr[curIx], + yArr[curIy], + xArr[nx], + yArr[ny], + softObstacles, + options); + var tentativeG = gScore[current] + dist + bend + softCost; var neighborState = StateId(nx, ny, newDir); if (tentativeG < gScore[neighborState]) @@ -156,4 +183,43 @@ internal static class ElkEdgePostProcessorAStar return null; } + + private static double ComputeSoftObstacleCost( + double x1, + double y1, + double x2, + double y2, + IReadOnlyList softObstacles, + OrthogonalAStarOptions options) + { + if (options.SoftObstacleWeight <= 0d || softObstacles.Count == 0) + { + return 0d; + } + + var candidateStart = new ElkPoint { X = x1, Y = y1 }; + var candidateEnd = new ElkPoint { X = x2, Y = y2 }; + var cost = 0d; + + foreach (var obstacle in softObstacles) + { + if (ElkEdgeRoutingGeometry.SegmentsIntersect(candidateStart, candidateEnd, obstacle.Start, obstacle.End)) + { + cost += 120d * options.SoftObstacleWeight; + continue; + } + + if (ElkEdgeRoutingGeometry.AreParallelAndClose( + candidateStart, + candidateEnd, + obstacle.Start, + obstacle.End, + options.SoftObstacleClearance)) + { + cost += 18d * options.SoftObstacleWeight; + } + } + + return cost; + } } diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouteRefiner.cs b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouteRefiner.cs new file mode 100644 index 000000000..d4d793a3c --- /dev/null +++ b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRouteRefiner.cs @@ -0,0 +1,269 @@ +namespace StellaOps.ElkSharp; + +internal static class ElkEdgeRouteRefiner +{ + private static readonly OrthogonalAStarOptions[] TrialTemplates = + [ + new OrthogonalAStarOptions(18d, 200d, 0.15d, 14d), + new OrthogonalAStarOptions(24d, 200d, 0.25d, 14d), + new OrthogonalAStarOptions(18d, 120d, 0.45d, 12d), + new OrthogonalAStarOptions(28d, 320d, 0.55d, 16d), + ]; + + internal static ElkRoutedEdge[] Optimize( + ElkRoutedEdge[] edges, + ElkPositionedNode[] nodes, + ElkLayoutOptions layoutOptions, + CancellationToken cancellationToken) + { + var options = ResolveOptions(layoutOptions); + if (options.Enabled != true + || layoutOptions.Direction != ElkLayoutDirection.LeftToRight + || edges.Length == 0 + || nodes.Length == 0) + { + return edges; + } + + var bestEdges = edges; + var bestScore = ElkEdgeRoutingScoring.ComputeScore(bestEdges, nodes); + var bestNodeCrossings = bestScore.NodeCrossings; + + for (var passIndex = 0; passIndex < options.MaxGlobalPasses; passIndex++) + { + cancellationToken.ThrowIfCancellationRequested(); + + var issues = ElkEdgeRoutingScoring.DetectIssues(bestEdges, nodes) + .Take(options.MaxProblemEdgesPerPass) + .ToArray(); + if (issues.Length == 0) + { + break; + } + + var improvedThisPass = false; + foreach (var issue in issues) + { + cancellationToken.ThrowIfCancellationRequested(); + + if (!TryImproveEdge(bestEdges, nodes, issue.EdgeId, bestScore, options, cancellationToken, out var improvedEdges, out var improvedScore)) + { + continue; + } + + bestEdges = improvedEdges; + bestScore = improvedScore; + bestNodeCrossings = bestScore.NodeCrossings; + improvedThisPass = true; + + if (bestNodeCrossings == 0 && bestScore.EdgeCrossings == 0) + { + break; + } + } + + if (!improvedThisPass) + { + break; + } + + if (bestNodeCrossings == 0 && bestScore.EdgeCrossings == 0) + { + break; + } + } + + return bestEdges; + } + + private static bool TryImproveEdge( + ElkRoutedEdge[] edges, + ElkPositionedNode[] nodes, + string edgeId, + EdgeRoutingScore baselineScore, + EdgeRefinementOptions options, + CancellationToken cancellationToken, + out ElkRoutedEdge[] improvedEdges, + out EdgeRoutingScore improvedScore) + { + improvedEdges = edges; + improvedScore = baselineScore; + + var edgeIndex = Array.FindIndex(edges, edge => string.Equals(edge.Id, edgeId, StringComparison.Ordinal)); + if (edgeIndex < 0) + { + return false; + } + + var edge = edges[edgeIndex]; + if (!CanRefineEdge(edge, nodes)) + { + return false; + } + + var obstacleRectangles = nodes.Select(node => ( + Left: node.X, + Top: node.Y, + Right: node.X + node.Width, + Bottom: node.Y + node.Height, + Id: node.Id)).ToArray(); + var softObstacles = BuildSoftObstacles(edges, edgeId); + + var bestLocalEdges = edges; + var bestLocalScore = baselineScore; + var trials = BuildTrials(options).Take(options.MaxTrialsPerProblemEdge); + + foreach (var trial in trials) + { + cancellationToken.ThrowIfCancellationRequested(); + + var reroutedSections = new List(edge.Sections.Count); + var rerouteFailed = false; + foreach (var section in edge.Sections) + { + var rerouted = ElkEdgePostProcessorAStar.RerouteWithGridAStar( + section.StartPoint, + section.EndPoint, + obstacleRectangles, + edge.SourceNodeId, + edge.TargetNodeId, + trial, + softObstacles, + cancellationToken); + if (rerouted is null || rerouted.Count < 2) + { + rerouteFailed = true; + break; + } + + reroutedSections.Add(new ElkEdgeSection + { + StartPoint = rerouted[0], + EndPoint = rerouted[^1], + BendPoints = rerouted.Skip(1).Take(rerouted.Count - 2).ToArray(), + }); + } + + if (rerouteFailed) + { + continue; + } + + var candidateEdges = (ElkRoutedEdge[])edges.Clone(); + candidateEdges[edgeIndex] = new ElkRoutedEdge + { + Id = edge.Id, + SourceNodeId = edge.SourceNodeId, + TargetNodeId = edge.TargetNodeId, + SourcePortId = edge.SourcePortId, + TargetPortId = edge.TargetPortId, + Kind = edge.Kind, + Label = edge.Label, + Sections = reroutedSections, + }; + + var candidateScore = ElkEdgeRoutingScoring.ComputeScore(candidateEdges, nodes); + if (!IsBetterCandidate(candidateScore, bestLocalScore)) + { + continue; + } + + bestLocalEdges = candidateEdges; + bestLocalScore = candidateScore; + } + + if (ReferenceEquals(bestLocalEdges, edges)) + { + return false; + } + + improvedEdges = bestLocalEdges; + improvedScore = bestLocalScore; + return true; + } + + private static bool IsBetterCandidate(EdgeRoutingScore candidate, EdgeRoutingScore baseline) + { + if (candidate.NodeCrossings != baseline.NodeCrossings) + { + return candidate.NodeCrossings < baseline.NodeCrossings; + } + + if (candidate.EdgeCrossings != baseline.EdgeCrossings) + { + return candidate.EdgeCrossings < baseline.EdgeCrossings; + } + + return candidate.Value > baseline.Value + 0.01d; + } + + private static bool CanRefineEdge(ElkRoutedEdge edge, IReadOnlyCollection nodes) + { + if (!string.IsNullOrWhiteSpace(edge.SourcePortId) || !string.IsNullOrWhiteSpace(edge.TargetPortId)) + { + return false; + } + + if (!string.IsNullOrWhiteSpace(edge.Kind) + && edge.Kind.StartsWith("backward|", StringComparison.OrdinalIgnoreCase)) + { + return false; + } + + if (nodes.Count == 0) + { + return false; + } + + var graphMinY = nodes.Min(node => node.Y); + var graphMaxY = nodes.Max(node => node.Y + node.Height); + if (ElkEdgePostProcessor.HasCorridorBendPoints(edge, graphMinY, graphMaxY)) + { + return false; + } + + return !ElkEdgePostProcessor.IsRepeatCollectorLabel(edge.Label); + } + + private static IReadOnlyList BuildSoftObstacles( + IReadOnlyCollection edges, + string excludedEdgeId) + { + return ElkEdgeRoutingGeometry.FlattenSegments(edges) + .Where(segment => !string.Equals(segment.EdgeId, excludedEdgeId, StringComparison.Ordinal)) + .Select(segment => new OrthogonalSoftObstacle(segment.Start, segment.End)) + .ToArray(); + } + + private static IEnumerable BuildTrials(EdgeRefinementOptions options) + { + foreach (var template in TrialTemplates) + { + var softObstacleWeight = options.SoftObstacleWeight <= 0d + ? 0d + : Math.Max(options.SoftObstacleWeight, template.SoftObstacleWeight); + yield return new OrthogonalAStarOptions( + Math.Max(options.BaseObstacleMargin, template.Margin), + template.BendPenalty, + softObstacleWeight, + Math.Max(8d, options.SoftObstacleClearance)); + } + } + + private static EdgeRefinementOptions ResolveOptions(ElkLayoutOptions layoutOptions) + { + var requested = layoutOptions.EdgeRefinement ?? new EdgeRefinementOptions(); + var enabled = requested.Enabled ?? layoutOptions.Effort == ElkLayoutEffort.Best; + + return new EdgeRefinementOptions + { + Enabled = enabled, + MaxGlobalPasses = Math.Max(0, requested.MaxGlobalPasses), + MaxTrialsPerProblemEdge = Math.Max(1, requested.MaxTrialsPerProblemEdge), + MaxProblemEdgesPerPass = Math.Max(1, requested.MaxProblemEdgesPerPass), + BaseObstacleMargin = Math.Max(8d, requested.BaseObstacleMargin), + SoftObstacleWeight = Math.Max(0d, requested.SoftObstacleWeight), + SoftObstacleClearance = Math.Max(8d, requested.SoftObstacleClearance), + }; + } +} diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingGeometry.cs b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingGeometry.cs new file mode 100644 index 000000000..6f0dd029b --- /dev/null +++ b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingGeometry.cs @@ -0,0 +1,193 @@ +namespace StellaOps.ElkSharp; + +internal static class ElkEdgeRoutingGeometry +{ + private const double CoordinateTolerance = 0.5d; + + internal static IReadOnlyList FlattenSegments(IReadOnlyCollection edges) + { + var segments = new List(); + foreach (var edge in edges) + { + segments.AddRange(FlattenSegments(edge)); + } + + return segments; + } + + internal static IReadOnlyList FlattenSegments(ElkRoutedEdge edge) + { + var segments = new List(); + foreach (var section in edge.Sections) + { + var points = new List { section.StartPoint }; + points.AddRange(section.BendPoints); + points.Add(section.EndPoint); + + for (var i = 0; i < points.Count - 1; i++) + { + segments.Add(new RoutedEdgeSegment(edge.Id, points[i], points[i + 1])); + } + } + + return segments; + } + + internal static double ComputePathLength(ElkRoutedEdge edge) + { + return FlattenSegments(edge).Sum(segment => ComputeSegmentLength(segment.Start, segment.End)); + } + + internal static double ComputeSegmentLength(ElkPoint start, ElkPoint end) + { + var dx = end.X - start.X; + var dy = end.Y - start.Y; + return Math.Sqrt((dx * dx) + (dy * dy)); + } + + internal static bool SegmentsIntersect(ElkPoint a1, ElkPoint a2, ElkPoint b1, ElkPoint b2) + { + if (ShareEndpoint(a1, a2, b1, b2)) + { + return false; + } + + if (AreCollinearAndOverlapping(a1, a2, b1, b2)) + { + return false; + } + + if (IsHorizontal(a1, a2) && IsVertical(b1, b2)) + { + return IntersectsOrthogonal(a1, a2, b1, b2); + } + + if (IsVertical(a1, a2) && IsHorizontal(b1, b2)) + { + return IntersectsOrthogonal(b1, b2, a1, a2); + } + + return SegmentsIntersectGeneral(a1, a2, b1, b2); + } + + internal static bool AreParallelAndClose( + ElkPoint a1, + ElkPoint a2, + ElkPoint b1, + ElkPoint b2, + double clearance) + { + if (IsHorizontal(a1, a2) && IsHorizontal(b1, b2)) + { + return Math.Abs(a1.Y - b1.Y) <= clearance + && OverlapLength(Math.Min(a1.X, a2.X), Math.Max(a1.X, a2.X), Math.Min(b1.X, b2.X), Math.Max(b1.X, b2.X)) > 1d; + } + + if (IsVertical(a1, a2) && IsVertical(b1, b2)) + { + return Math.Abs(a1.X - b1.X) <= clearance + && OverlapLength(Math.Min(a1.Y, a2.Y), Math.Max(a1.Y, a2.Y), Math.Min(b1.Y, b2.Y), Math.Max(b1.Y, b2.Y)) > 1d; + } + + return false; + } + + internal static bool AreCollinearAndOverlapping(ElkPoint a1, ElkPoint a2, ElkPoint b1, ElkPoint b2) + { + if (IsHorizontal(a1, a2) && IsHorizontal(b1, b2) && Math.Abs(a1.Y - b1.Y) <= CoordinateTolerance) + { + return OverlapLength(Math.Min(a1.X, a2.X), Math.Max(a1.X, a2.X), Math.Min(b1.X, b2.X), Math.Max(b1.X, b2.X)) > 1d; + } + + if (IsVertical(a1, a2) && IsVertical(b1, b2) && Math.Abs(a1.X - b1.X) <= CoordinateTolerance) + { + return OverlapLength(Math.Min(a1.Y, a2.Y), Math.Max(a1.Y, a2.Y), Math.Min(b1.Y, b2.Y), Math.Max(b1.Y, b2.Y)) > 1d; + } + + return false; + } + + internal static ElkPoint ResolveApproachPoint(ElkRoutedEdge edge) + { + var lastSection = edge.Sections.Last(); + if (lastSection.BendPoints.Count > 0) + { + return lastSection.BendPoints.Last(); + } + + return lastSection.StartPoint; + } + + internal static bool PointsEqual(ElkPoint left, ElkPoint right) + { + return Math.Abs(left.X - right.X) <= CoordinateTolerance + && Math.Abs(left.Y - right.Y) <= CoordinateTolerance; + } + + private static bool IsHorizontal(ElkPoint start, ElkPoint end) => Math.Abs(start.Y - end.Y) <= CoordinateTolerance; + + private static bool IsVertical(ElkPoint start, ElkPoint end) => Math.Abs(start.X - end.X) <= CoordinateTolerance; + + private static bool IntersectsOrthogonal(ElkPoint horizontalStart, ElkPoint horizontalEnd, ElkPoint verticalStart, ElkPoint verticalEnd) + { + var minHorizontalX = Math.Min(horizontalStart.X, horizontalEnd.X); + var maxHorizontalX = Math.Max(horizontalStart.X, horizontalEnd.X); + var minVerticalY = Math.Min(verticalStart.Y, verticalEnd.Y); + var maxVerticalY = Math.Max(verticalStart.Y, verticalEnd.Y); + + return verticalStart.X > minHorizontalX + CoordinateTolerance + && verticalStart.X < maxHorizontalX - CoordinateTolerance + && horizontalStart.Y > minVerticalY + CoordinateTolerance + && horizontalStart.Y < maxVerticalY - CoordinateTolerance; + } + + private static bool ShareEndpoint(ElkPoint a1, ElkPoint a2, ElkPoint b1, ElkPoint b2) + { + return PointsEqual(a1, b1) + || PointsEqual(a1, b2) + || PointsEqual(a2, b1) + || PointsEqual(a2, b2); + } + + private static bool SegmentsIntersectGeneral(ElkPoint a1, ElkPoint a2, ElkPoint b1, ElkPoint b2) + { + var o1 = Orientation(a1, a2, b1); + var o2 = Orientation(a1, a2, b2); + var o3 = Orientation(b1, b2, a1); + var o4 = Orientation(b1, b2, a2); + + if (o1 != o2 && o3 != o4) + { + return true; + } + + return o1 == 0 && OnSegment(a1, b1, a2) + || o2 == 0 && OnSegment(a1, b2, a2) + || o3 == 0 && OnSegment(b1, a1, b2) + || o4 == 0 && OnSegment(b1, a2, b2); + } + + private static int Orientation(ElkPoint start, ElkPoint middle, ElkPoint end) + { + var value = ((middle.Y - start.Y) * (end.X - middle.X)) - ((middle.X - start.X) * (end.Y - middle.Y)); + if (Math.Abs(value) <= CoordinateTolerance) + { + return 0; + } + + return value > 0 ? 1 : 2; + } + + private static bool OnSegment(ElkPoint start, ElkPoint point, ElkPoint end) + { + return point.X <= Math.Max(start.X, end.X) + CoordinateTolerance + && point.X >= Math.Min(start.X, end.X) - CoordinateTolerance + && point.Y <= Math.Max(start.Y, end.Y) + CoordinateTolerance + && point.Y >= Math.Min(start.Y, end.Y) - CoordinateTolerance; + } + + private static double OverlapLength(double firstMin, double firstMax, double secondMin, double secondMax) + { + return Math.Min(firstMax, secondMax) - Math.Max(firstMin, secondMin); + } +} diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingScoring.cs b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingScoring.cs new file mode 100644 index 000000000..6fce4639e --- /dev/null +++ b/src/__Libraries/StellaOps.ElkSharp/ElkEdgeRoutingScoring.cs @@ -0,0 +1,176 @@ +namespace StellaOps.ElkSharp; + +internal static class ElkEdgeRoutingScoring +{ + internal static EdgeRoutingScore ComputeScore( + IReadOnlyCollection edges, + IReadOnlyCollection nodes) + { + var nodeCrossings = CountEdgeNodeCrossings(edges, nodes, null); + var edgeCrossings = CountEdgeEdgeCrossings(edges, null); + var bendCount = SumBendPoints(edges); + var totalPathLength = SumPathLengths(edges); + var targetCongestion = CountTargetApproachCongestion(edges); + + var value = -(nodeCrossings * 100_000d) + - (edgeCrossings * 650d) + - (bendCount * 5d) + - (targetCongestion * 25d) + - (totalPathLength * 0.1d); + + return new EdgeRoutingScore( + nodeCrossings, + edgeCrossings, + bendCount, + targetCongestion, + totalPathLength, + value); + } + + internal static IReadOnlyList DetectIssues( + IReadOnlyCollection edges, + IReadOnlyCollection nodes) + { + var severityByEdgeId = new Dictionary(StringComparer.Ordinal); + CountEdgeNodeCrossings(edges, nodes, severityByEdgeId, 100); + CountEdgeEdgeCrossings(edges, severityByEdgeId, 50); + + foreach (var edge in edges) + { + var bendCount = edge.Sections.Sum(section => section.BendPoints.Count); + if (bendCount > 5) + { + severityByEdgeId[edge.Id] = severityByEdgeId.GetValueOrDefault(edge.Id) + 5; + } + + var directDistance = edge.Sections.Sum(section => + Math.Abs(section.EndPoint.X - section.StartPoint.X) + Math.Abs(section.EndPoint.Y - section.StartPoint.Y)); + var pathLength = ElkEdgeRoutingGeometry.ComputePathLength(edge); + if (pathLength > directDistance * 1.8d && bendCount > 2) + { + severityByEdgeId[edge.Id] = severityByEdgeId.GetValueOrDefault(edge.Id) + 2; + } + } + + return severityByEdgeId + .Where(pair => pair.Value > 0) + .OrderByDescending(pair => pair.Value) + .ThenBy(pair => pair.Key, StringComparer.Ordinal) + .Select(pair => new EdgeRoutingIssue(pair.Key, pair.Value)) + .ToArray(); + } + + internal static int CountEdgeNodeCrossings( + IReadOnlyCollection edges, + IReadOnlyCollection nodes, + Dictionary? severityByEdgeId, + int severityWeight = 1) + { + var obstacles = nodes.Select(node => ( + Left: node.X, + Top: node.Y, + Right: node.X + node.Width, + Bottom: node.Y + node.Height, + Id: node.Id)).ToArray(); + var crossingCount = 0; + + foreach (var edge in edges) + { + var edgeCrossings = 0; + foreach (var segment in ElkEdgeRoutingGeometry.FlattenSegments(edge)) + { + if (ElkEdgePostProcessor.SegmentCrossesObstacle( + segment.Start, + segment.End, + obstacles, + edge.SourceNodeId, + edge.TargetNodeId)) + { + crossingCount++; + edgeCrossings++; + } + } + + if (edgeCrossings > 0 && severityByEdgeId is not null) + { + severityByEdgeId[edge.Id] = severityByEdgeId.GetValueOrDefault(edge.Id) + (edgeCrossings * severityWeight); + } + } + + return crossingCount; + } + + internal static int CountEdgeEdgeCrossings( + IReadOnlyCollection edges, + Dictionary? severityByEdgeId, + int severityWeight = 1) + { + var crossingCount = 0; + var segments = ElkEdgeRoutingGeometry.FlattenSegments(edges); + + for (var i = 0; i < segments.Count; i++) + { + for (var j = i + 1; j < segments.Count; j++) + { + if (string.Equals(segments[i].EdgeId, segments[j].EdgeId, StringComparison.Ordinal)) + { + continue; + } + + if (!ElkEdgeRoutingGeometry.SegmentsIntersect( + segments[i].Start, + segments[i].End, + segments[j].Start, + segments[j].End)) + { + continue; + } + + crossingCount++; + if (severityByEdgeId is null) + { + continue; + } + + severityByEdgeId[segments[i].EdgeId] = severityByEdgeId.GetValueOrDefault(segments[i].EdgeId) + severityWeight; + severityByEdgeId[segments[j].EdgeId] = severityByEdgeId.GetValueOrDefault(segments[j].EdgeId) + severityWeight; + } + } + + return crossingCount; + } + + internal static int SumBendPoints(IReadOnlyCollection edges) + { + return edges.Sum(edge => edge.Sections.Sum(section => section.BendPoints.Count)); + } + + internal static double SumPathLengths(IReadOnlyCollection edges) + { + return edges.Sum(ElkEdgeRoutingGeometry.ComputePathLength); + } + + internal static int CountTargetApproachCongestion(IReadOnlyCollection edges) + { + var congestionCount = 0; + foreach (var group in edges.GroupBy(edge => edge.TargetNodeId, StringComparer.Ordinal)) + { + var approaches = group + .Select(edge => ElkEdgeRoutingGeometry.ResolveApproachPoint(edge)) + .OrderBy(point => point.Y) + .ThenBy(point => point.X) + .ToArray(); + + for (var i = 1; i < approaches.Length; i++) + { + if (Math.Abs(approaches[i].Y - approaches[i - 1].Y) <= 4d + && Math.Abs(approaches[i].X - approaches[i - 1].X) <= 24d) + { + congestionCount++; + } + } + } + + return congestionCount; + } +} diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkLayoutTypes.cs b/src/__Libraries/StellaOps.ElkSharp/ElkLayoutTypes.cs index dc14fa927..987fd1d9b 100644 --- a/src/__Libraries/StellaOps.ElkSharp/ElkLayoutTypes.cs +++ b/src/__Libraries/StellaOps.ElkSharp/ElkLayoutTypes.cs @@ -45,3 +45,30 @@ internal sealed record DummyNodeResult( Dictionary AugmentedInputOrder, HashSet DummyNodeIds, Dictionary> EdgeDummyChains); + +internal readonly record struct EdgeRoutingScore( + int NodeCrossings, + int EdgeCrossings, + int BendCount, + int TargetCongestion, + double TotalPathLength, + double Value); + +internal readonly record struct EdgeRoutingIssue( + string EdgeId, + int Severity); + +internal readonly record struct RoutedEdgeSegment( + string EdgeId, + ElkPoint Start, + ElkPoint End); + +internal readonly record struct OrthogonalAStarOptions( + double Margin, + double BendPenalty, + double SoftObstacleWeight, + double SoftObstacleClearance); + +internal readonly record struct OrthogonalSoftObstacle( + ElkPoint Start, + ElkPoint End); diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkModels.cs b/src/__Libraries/StellaOps.ElkSharp/ElkModels.cs index a530fd707..ec25ecdb9 100644 --- a/src/__Libraries/StellaOps.ElkSharp/ElkModels.cs +++ b/src/__Libraries/StellaOps.ElkSharp/ElkModels.cs @@ -67,6 +67,18 @@ public sealed record ElkLayoutOptions public ElkLayoutEffort Effort { get; init; } = ElkLayoutEffort.Best; public int? OrderingIterations { get; init; } public int? PlacementIterations { get; init; } + public EdgeRefinementOptions? EdgeRefinement { get; init; } +} + +public sealed record EdgeRefinementOptions +{ + public bool? Enabled { get; init; } + public int MaxGlobalPasses { get; init; } = 2; + public int MaxTrialsPerProblemEdge { get; init; } = 4; + public int MaxProblemEdgesPerPass { get; init; } = 12; + public double BaseObstacleMargin { get; init; } = 18; + public double SoftObstacleWeight { get; init; } = 0.4d; + public double SoftObstacleClearance { get; init; } = 14d; } public sealed record ElkPoint diff --git a/src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs b/src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs index 14ddd9f56..bd75dc2d3 100644 --- a/src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs +++ b/src/__Libraries/StellaOps.ElkSharp/ElkSharpLayeredLayoutEngine.cs @@ -105,6 +105,8 @@ public sealed class ElkSharpLayeredLayoutEngine : IElkLayoutEngine .ToArray(); for (var gutterPass = 0; gutterPass < 3; gutterPass++) { + cancellationToken.ThrowIfCancellationRequested(); + if (!ElkEdgeChannelGutters.ExpandVerticalCorridorGutters( positionedNodes, routedEdges, @@ -139,6 +141,8 @@ public sealed class ElkSharpLayeredLayoutEngine : IElkLayoutEngine for (var compactPass = 0; compactPass < 2; compactPass++) { + cancellationToken.ThrowIfCancellationRequested(); + if (!ElkEdgeChannelGutters.CompactSparseVerticalCorridorGutters( positionedNodes, routedEdges, @@ -207,16 +211,18 @@ public sealed class ElkSharpLayeredLayoutEngine : IElkLayoutEngine .OrderBy(x => inputOrder.GetValueOrDefault(x.Id, int.MaxValue)) .ToArray(); - // Post-processing pipeline (5 generic passes, no node-specific logic): + // Post-processing pipeline (deterministic generic passes, no node-specific logic): // 1. Project endpoints onto actual node shape boundaries (diamond/hexagon/rectangle) routedEdges = ElkEdgePostProcessor.SnapAnchorsToNodeBoundary(routedEdges, finalNodes); - // 2. Reroute any edge crossing node bounding boxes (including diagonals from shape projection) + // 2. Deterministic bounded refinement for crossing-prone orthogonal routes + routedEdges = ElkEdgeRouteRefiner.Optimize(routedEdges, finalNodes, options, cancellationToken); + // 3. Reroute any edge crossing node bounding boxes (including diagonals from shape projection) routedEdges = ElkEdgePostProcessor.AvoidNodeCrossings(routedEdges, finalNodes, options.Direction); - // 3. Convert any remaining diagonal segments to orthogonal L-corners + // 4. Convert any remaining diagonal segments to orthogonal L-corners routedEdges = ElkEdgePostProcessor.EliminateDiagonalSegments(routedEdges, finalNodes); - // 4. Simplify: remove collinear/duplicate points, try L-shape shortcuts + // 5. Simplify: remove collinear/duplicate points, try L-shape shortcuts routedEdges = ElkEdgePostProcessorSimplify.SimplifyEdgePaths(routedEdges, finalNodes); - // 5. Compress outer corridor distances + // 6. Compress outer corridor distances routedEdges = ElkEdgePostProcessorSimplify.TightenOuterCorridors(routedEdges, finalNodes); return Task.FromResult(new ElkLayoutResult