From bab82e84405d9530f4de362381e0fcbddee0c5c3 Mon Sep 17 00:00:00 2001 From: Maciej Setkowski <2069561+msetkowski@users.noreply.github.com> Date: Mon, 9 Nov 2026 23:16:37 +0100 Subject: [PATCH] Trace links to baseline requirements are not broken Existing BL- keys count as valid link targets in the overview's broken references and in the MCP traceability graph, where linked baseline items now appear as nodes; a removed one makes the link broken again. The requirement page links them to the baseline instead of showing "(missing)", and `BL-03` in Markdown resolves to the baseline item (an in-page anchor on version pages). The view gets baseline keys as a HashSet: SpEL cannot call methods on Kotlin's internal EmptySet, which made the requirement page fail while the baseline was empty. Co-Authored-By: Claude Opus 5.5 --- .../reqlith/controller/ProjectController.kt | 2 +- .../reqlith/controller/ProjectViewSupport.kt | 28 +++++++++--- .../io/reqlith/controller/ReqlithMcpTools.kt | 11 +++-- .../io/reqlith/model/dto/ProjectDocument.kt | 6 +-- .../io/reqlith/service/BaselineService.kt | 2 + .../io/reqlith/service/ElementService.kt | 2 +- .../resources/templates/element/show.html | 5 ++- .../io/reqlith/controller/BaselinePagesIT.kt | 43 +++++++++++++++++++ .../io/reqlith/controller/McpServerIT.kt | 14 ++++++ .../reqlith/model/dto/ProjectDocumentTest.kt | 7 +++ 10 files changed, 103 insertions(+), 17 deletions(-) diff --git a/src/main/kotlin/io/reqlith/controller/ProjectController.kt b/src/main/kotlin/io/reqlith/controller/ProjectController.kt index 3eea6b0..ff9d38b 100644 --- a/src/main/kotlin/io/reqlith/controller/ProjectController.kt +++ b/src/main/kotlin/io/reqlith/controller/ProjectController.kt @@ -101,7 +101,7 @@ class ProjectController( model.addAttribute("openSuggestions", reviews.openSuggestions(project)) model.addAttribute("externalLinks", links.all(project)) model.addAttribute("modified", elements.all(project).associate { it.key to it.updatedAt }) - model.addAttribute("brokenLinks", document.brokenLinks()) + model.addAttribute("brokenLinks", document.brokenLinks(support.baselineKeys())) model.addAttribute("functionalWithoutScenario", document.functionalWithoutScenario()) return "project/overview" } diff --git a/src/main/kotlin/io/reqlith/controller/ProjectViewSupport.kt b/src/main/kotlin/io/reqlith/controller/ProjectViewSupport.kt index f5e0126..6680f4e 100644 --- a/src/main/kotlin/io/reqlith/controller/ProjectViewSupport.kt +++ b/src/main/kotlin/io/reqlith/controller/ProjectViewSupport.kt @@ -48,6 +48,8 @@ class ProjectViewSupport( model.addAttribute("active", active) val baselineItems = baseline.all() model.addAttribute("baseline", baselineItems) + // A HashSet: SpEL cannot call methods on Kotlin's internal EmptySet, which toSet() returns for no items. + model.addAttribute("baselineKeys", baselineItems.map { it.key }.toHashSet()) model.addAttribute("sections", sections(project, document, baselineItems.size)) val state = state(project, document) model.addAttribute("stateLabel", state.first) @@ -77,17 +79,29 @@ class ProjectViewSupport( /** Renders markdown with element and role keys linked into the project's read view. */ fun render(markdownText: String?, project: Project, document: ProjectDocument): String = markdown.render(markdownText, resolver(project, document)) - /** Renders markdown of a frozen version: references point to anchors on the same page. */ - fun renderInPage(markdownText: String?, document: ProjectDocument): String = markdown.render(markdownText) { key -> - document.element(key)?.let { Reference("#$key", "$key · ${it.title}") } - ?: document.role(key)?.let { Reference("#$key", "$key · ${it.name}") } + /** Renders markdown of a frozen version: references point to anchors on the same page (the baseline is shown there too). */ + fun renderInPage(markdownText: String?, document: ProjectDocument): String { + val baselineTitles = baselineTitles() + return markdown.render(markdownText) { key -> + document.element(key)?.let { Reference("#$key", "$key · ${it.title}") } + ?: document.role(key)?.let { Reference("#$key", "$key · ${it.name}") } + ?: baselineTitles[key]?.let { Reference("#$key", "$key · $it") } + } } - fun resolver(project: Project, document: ProjectDocument) = ReferenceResolver { key -> - document.element(key)?.let { Reference("/p/${project.key}/e/$key", "$key · ${it.title}") } - ?: document.role(key)?.let { Reference("/roles/$key", "$key · ${it.name}") } + fun resolver(project: Project, document: ProjectDocument): ReferenceResolver { + val baselineTitles = baselineTitles() + return ReferenceResolver { key -> + document.element(key)?.let { Reference("/p/${project.key}/e/$key", "$key · ${it.title}") } + ?: document.role(key)?.let { Reference("/roles/$key", "$key · ${it.name}") } + ?: baselineTitles[key]?.let { Reference("/baseline/$key", "$key · $it") } + } } + fun baselineKeys(): Set = baseline.keys() + + private fun baselineTitles(): Map = baseline.all().associate { it.key to it.title } + /** Baseline descriptions rendered for the document views (key to HTML). */ fun renderBaseline(): Map = baseline.all().associate { it.key to markdown.render(it.bodyMd) } diff --git a/src/main/kotlin/io/reqlith/controller/ReqlithMcpTools.kt b/src/main/kotlin/io/reqlith/controller/ReqlithMcpTools.kt index 30b34e9..adea65a 100644 --- a/src/main/kotlin/io/reqlith/controller/ReqlithMcpTools.kt +++ b/src/main/kotlin/io/reqlith/controller/ReqlithMcpTools.kt @@ -215,8 +215,8 @@ class ReqlithMcpTools(private val read: McpReadModel, private val log: McpAccess @McpTool( name = "get_traceability", - description = "Traceability graph of a project (BR → SR → FR/NFR → scenarios, risks, dependencies, roles) " + - "with gaps: functional requirements without a scenario and broken links.", + description = "Traceability graph of a project (BR → SR → FR/NFR → scenarios, risks, dependencies, roles, " + + "and baseline NFRs it links to) with gaps: functional requirements without a scenario and broken links.", annotations = McpTool.McpAnnotations(readOnlyHint = true, destructiveHint = false, idempotentHint = true), ) fun getTraceability( @@ -228,13 +228,16 @@ class ReqlithMcpTools(private val read: McpReadModel, private val log: McpAccess audit(context, "get_traceability", p.key, mapOf("version" to version)) val doc = read.document(p, version).let { it.document to it.label } val (document, label) = doc + val targets = document.elements.flatMap { e -> e.links.map { it.toKey } }.toSet() + val baseline = read.baseline() Traceability( project = p.key, version = label, - nodes = document.elements.map { TraceNode(it.key, it.type.label, it.title) } + document.roles.map { TraceNode(it.key, "Role", it.name) }, + nodes = document.elements.map { TraceNode(it.key, it.type.label, it.title) } + document.roles.map { TraceNode(it.key, "Role", it.name) } + + baseline.filter { it.key in targets }.map { TraceNode(it.key, baselineType(it), it.title) }, edges = document.elements.flatMap { e -> e.links.map { TraceEdge(e.key, it.kind.label, it.toKey) } }, functionalWithoutScenario = document.functionalWithoutScenario().map { it.key }, - brokenLinks = document.brokenLinks().map { TraceEdge(it.first, it.second.kind.label, it.second.toKey) }, + brokenLinks = document.brokenLinks(baseline.map { it.key }.toSet()).map { TraceEdge(it.first, it.second.kind.label, it.second.toKey) }, ) } diff --git a/src/main/kotlin/io/reqlith/model/dto/ProjectDocument.kt b/src/main/kotlin/io/reqlith/model/dto/ProjectDocument.kt index 5a56c82..47d0384 100644 --- a/src/main/kotlin/io/reqlith/model/dto/ProjectDocument.kt +++ b/src/main/kotlin/io/reqlith/model/dto/ProjectDocument.kt @@ -33,9 +33,9 @@ data class ProjectDocument( fun incomingLinks(): Map>> = elements.flatMap { from -> from.links.map { it.toKey to (it to from.key) } } .groupBy({ it.first }, { it.second }) - /** Links whose target key does not exist in this document. */ - fun brokenLinks(): List> { - val known = elements.map { it.key }.toSet() + roles.map { it.key } + /** Links whose target key does not exist in this document, nor among [baselineKeys] (the global NFR baseline). */ + fun brokenLinks(baselineKeys: Set = emptySet()): List> { + val known = elements.map { it.key }.toSet() + roles.map { it.key } + baselineKeys return elements.flatMap { e -> e.links.filter { it.toKey !in known }.map { e.key to it } } } diff --git a/src/main/kotlin/io/reqlith/service/BaselineService.kt b/src/main/kotlin/io/reqlith/service/BaselineService.kt index be9b900..d9d5422 100644 --- a/src/main/kotlin/io/reqlith/service/BaselineService.kt +++ b/src/main/kotlin/io/reqlith/service/BaselineService.kt @@ -29,6 +29,8 @@ class BaselineService(private val baseline: BaselineRequirementRepository, priva fun get(key: String): BaselineRequirement = baseline.findByKey(key) ?: throw NotFoundException("Baseline requirement $key not found") + fun keys(): Set = baseline.findAll().map { it.key }.toSet() + fun canEdit(user: CurrentUser): Boolean = user.isArchitect /** Changes whenever any baseline requirement is added, changed or removed (part of export cache keys). */ diff --git a/src/main/kotlin/io/reqlith/service/ElementService.kt b/src/main/kotlin/io/reqlith/service/ElementService.kt index 9391af6..ac8535a 100644 --- a/src/main/kotlin/io/reqlith/service/ElementService.kt +++ b/src/main/kotlin/io/reqlith/service/ElementService.kt @@ -107,7 +107,7 @@ class ElementService( if (content.title.isBlank()) throw ValidationException("title", "Title is required") if (content.title.length > 300) throw ValidationException("title", "Keep the title under 300 characters") content.links.forEach { - if (!MarkdownRenderer.KEY.matches(it.toKey)) throw ValidationException("links", "${it.toKey} is not an element or role key") + if (!MarkdownRenderer.KEY.matches(it.toKey)) throw ValidationException("links", "${it.toKey} is not an element, role or baseline key") if (it.toKey == key) throw ValidationException("links", "An element cannot link to itself") } } diff --git a/src/main/resources/templates/element/show.html b/src/main/resources/templates/element/show.html index b6b643b..e4286a5 100644 --- a/src/main/resources/templates/element/show.html +++ b/src/main/resources/templates/element/show.html @@ -49,7 +49,10 @@

Title

SR-03 RO-01 - BL-01 + XX-1
diff --git a/src/test/kotlin/io/reqlith/controller/BaselinePagesIT.kt b/src/test/kotlin/io/reqlith/controller/BaselinePagesIT.kt index 3f43743..44a39c8 100644 --- a/src/test/kotlin/io/reqlith/controller/BaselinePagesIT.kt +++ b/src/test/kotlin/io/reqlith/controller/BaselinePagesIT.kt @@ -1,8 +1,13 @@ package io.reqlith.controller +import io.reqlith.model.dto.ElementContent import io.reqlith.model.dto.ReqlithOidcUser import io.reqlith.model.entity.BaselineCategory +import io.reqlith.model.entity.ElementType +import io.reqlith.model.entity.LinkKind +import io.reqlith.model.entity.TraceLink import io.reqlith.service.BaselineService +import io.reqlith.service.ElementService import io.reqlith.support.Fixtures import io.reqlith.support.IntegrationTest import io.reqlith.support.TestUsers @@ -26,9 +31,47 @@ class BaselinePagesIT( @Autowired private val users: TestUsers, @Autowired private val fixtures: Fixtures, @Autowired private val baseline: BaselineService, + @Autowired private val elements: ElementService, ) { private fun login(user: ReqlithOidcUser) = oidcLogin().oidcUser(user) + @Test + fun `trace links and references to baseline requirements are not broken while the requirement exists`() { + val architect = users.create("Ada Archer", architect = true) + val owner = users.create("Olive Owens") + val project = fixtures.project(owner) + val requirement = baseline.create(architect, BaselineCategory.SECURITY, "Encrypt data at rest " + UUID.randomUUID().toString().take(6), null) + val nfr = elements.create( + owner, + project, + ElementType.NFR, + ElementContent( + "Encrypt refund photos", + "Applies `${requirement.key}` to uploaded photos.", + null, + emptySet(), + setOf(TraceLink(LinkKind.DERIVED_FROM, requirement.key)), + ), + ) + + mvc.get("/p/${project.key}/draft") { with(login(owner)) }.andExpect { + content { string(not(containsString("${nfr.key} → ${requirement.key}"))) } + } + mvc.get("/p/${project.key}/e/${nfr.key}") { with(login(owner)) }.andExpect { + content { string(containsString("""title="Baseline requirement">${requirement.key}""")) } + content { string(containsString("""class="ref" rel="noopener noreferrer">${requirement.key}""")) } + content { string(not(containsString("${requirement.key} (missing)"))) } + } + + baseline.delete(architect, requirement) + mvc.get("/p/${project.key}/draft") { with(login(owner)) }.andExpect { + content { string(containsString("${nfr.key} → ${requirement.key}")) } + } + mvc.get("/p/${project.key}/e/${nfr.key}") { with(login(owner)) }.andExpect { + content { string(containsString("${requirement.key} (missing)")) } + } + } + @Test fun `architects add and edit baseline requirements from the baseline pages`() { val architect = users.create("Ada Archer", architect = true) diff --git a/src/test/kotlin/io/reqlith/controller/McpServerIT.kt b/src/test/kotlin/io/reqlith/controller/McpServerIT.kt index 0d73483..2def8bf 100644 --- a/src/test/kotlin/io/reqlith/controller/McpServerIT.kt +++ b/src/test/kotlin/io/reqlith/controller/McpServerIT.kt @@ -176,6 +176,20 @@ class McpServerIT( assertContains(hits, security.key) assertFalse(mcp.call("search_requirements", "project" to key, "type" to "FR", "text" to marker).text().contains(security.key)) + val editor = users.create("Carla Conti") + val project = projects.get(key) + fixtures.addMember(project, editor, MemberRole.CONTRIBUTOR) + val nfr = elements.create( + editor, + project, + ElementType.NFR, + ElementContent("Encrypt refund photos", null, null, emptySet(), setOf(TraceLink(LinkKind.DERIVED_FROM, security.key))), + ) + val trace = mcp.call("get_traceability", "project" to key, "version" to "draft").text() + assertContains(trace, "{\"from\":\"${nfr.key}\",\"kind\":\"Derived from\",\"to\":\"${security.key}\"}") + assertContains(trace, "{\"key\":\"${security.key}\",") + assertContains(trace, "\"brokenLinks\":[]") + val detail = mcp.call("get_requirement", "project" to key, "key" to security.key.lowercase()).text() assertContains(detail, "AES-256 for all stores") assertContains(detail, "/baseline/${security.key}") diff --git a/src/test/kotlin/io/reqlith/model/dto/ProjectDocumentTest.kt b/src/test/kotlin/io/reqlith/model/dto/ProjectDocumentTest.kt index 15e48fb..8af8fec 100644 --- a/src/test/kotlin/io/reqlith/model/dto/ProjectDocumentTest.kt +++ b/src/test/kotlin/io/reqlith/model/dto/ProjectDocumentTest.kt @@ -43,6 +43,13 @@ class ProjectDocumentTest { assertEquals(listOf("FR-01" to "SR-09"), doc.brokenLinks().map { it.first to it.second.toKey }) } + @Test + fun `links to baseline requirements are not broken while they exist`() { + val doc = document(element("NFR-01", LinkKind.DERIVED_FROM to "BL-03")) + assertEquals(emptyList(), doc.brokenLinks(setOf("BL-01", "BL-03"))) + assertEquals(listOf("NFR-01" to "BL-03"), doc.brokenLinks(setOf("BL-01")).map { it.first to it.second.toKey }) + } + @Test fun `incoming links are grouped by target`() { val doc = document(element("FR-01", LinkKind.DERIVED_FROM to "SR-01"), element("SR-01"))