From 27ec6340b293265564fb1bfa771ecdc56651ee3c Mon Sep 17 00:00:00 2001 From: redcatbear Date: Wed, 5 Aug 2026 06:07:47 +0200 Subject: [PATCH 1/6] #39: Added requirement for marking transitive defects. --- doc/system_requirements.md | 140 +++++++++++++++++++++---------------- 1 file changed, 79 insertions(+), 61 deletions(-) diff --git a/doc/system_requirements.md b/doc/system_requirements.md index f9d09bf..05fec3a 100644 --- a/doc/system_requirements.md +++ b/doc/system_requirements.md @@ -136,7 +136,7 @@ Needs: req The following requirements refine the syntax-highlighting feature into user-visible capabilities. -### Markdown Syntax Highlighting +#### Markdown Syntax Highlighting `req~markdown-syntax-highlighting~1` The plugin highlights OpenFastTrace specification items in Markdown documents. Users distinguish OpenFastTrace syntax from surrounding Markdown text while reading or editing a specification. @@ -146,7 +146,7 @@ Covers: Needs: scn -### RST Syntax Highlighting +#### RST Syntax Highlighting `req~rst-syntax-highlighting~1` The plugin highlights OpenFastTrace specification items in RST documents. Users distinguish OpenFastTrace syntax from surrounding RST text while reading or editing a specification. @@ -156,7 +156,7 @@ Covers: Needs: scn -### Coverage Tag Syntax Highlighting +#### Coverage Tag Syntax Highlighting `req~coverage-tag-syntax-highlighting~1` The plugin highlights OpenFastTrace coverage tags in supported source code comments. Users distinguish OFT coverage tags from ordinary comment text while reading or editing source files. @@ -170,7 +170,7 @@ Needs: scn The following requirements refine the 'Go to Specification' Item feature into user-visible capabilities. -### Go to Symbol for Specification Items +#### Go to Symbol for Specification Items `req~go-to-symbol-for-specification-items~1` The plugin contributes OpenFastTrace specification item declarations to `Go to Symbol`. @@ -184,7 +184,7 @@ Covers: Needs: scn -### Recognize Markdown Specification Item Declaration Variants +#### Recognize Markdown Specification Item Declaration Variants `req~recognize-markdown-specification-item-declaration-variants~1` The plugin recognizes an OpenFastTrace specification item declaration in a Markdown document both when the full OFT item ID appears as the plain declaration line and when the full OFT item ID is enclosed in single backticks on that declaration line. @@ -198,7 +198,7 @@ Covers: Needs: scn -### Open Specification Item from Go to Symbol +#### Open Specification Item from Go to Symbol `req~open-specification-item-from-go-to-symbol~1` The plugin opens the selected OpenFastTrace specification item from the `Go to Symbol` result list in the editor at the declaration of that item. Users can jump from the result list to the defining item ID of the selected specification item. @@ -208,7 +208,7 @@ Covers: Needs: scn -### Open Specification Item from Coverage Definition +#### Open Specification Item from Coverage Definition `req~open-specification-item-from-coverage-definition~1` The plugin opens the covered OpenFastTrace specification item when a user invokes `Go To Declaration` on an OFT item ID under `Covers:` in a supported specification document. @@ -218,7 +218,7 @@ Covers: Needs: scn -### Stay on Specification Item Declaration on Go To Declaration +#### Stay on Specification Item Declaration on Go To Declaration `req~stay-on-specification-item-declaration-on-go-to-declaration~1` The plugin keeps the user on the current OpenFastTrace specification item declaration when a user invokes `Go To Declaration` on the declared item ID itself. Users can distinguish the declaration from coverage-providing occurrences of the same item. @@ -228,7 +228,7 @@ Covers: Needs: scn -### Show Covering Occurrences from Specification Item Declaration +#### Show Covering Occurrences from Specification Item Declaration `req~show-covering-occurrences-from-specification-item-declaration~1` The plugin shows the coverage-providing occurrences of an OpenFastTrace specification item when a user invokes `Go To Implementations` on the declared item ID. The result includes supported `Covers:` entries in specification documents and OFT coverage tags in source files. @@ -238,7 +238,7 @@ Covers: Needs: scn -### Open Specification Item from Coverage Tag Left Side +#### Open Specification Item from Coverage Tag Left Side `req~open-specification-item-from-coverage-tag-left-side~1` The plugin resolves the covering OpenFastTrace specification item when a user invokes `Go To Declaration` on the left side of an OFT coverage tag in a supported file and opens that item's declaration in the specification document. If the left side omits the name and revision, the plugin resolves the effective ID by copying the missing parts from the covered ID on the right side of the arrow. @@ -248,7 +248,7 @@ Covers: Needs: scn -### Open Specification Item from Coverage Tag Right Side +#### Open Specification Item from Coverage Tag Right Side `req~open-specification-item-from-coverage-tag-right-side~1` The plugin opens the covered OpenFastTrace specification item when a user invokes Go To on the right side of an OFT coverage tag in a supported file. @@ -262,7 +262,7 @@ Needs: scn The following requirements refine the Open OFT User Guide feature into user-visible capabilities. -### Open OFT User Guide in Help Menu +#### Open OFT User Guide in Help Menu `req~open-oft-user-guide-in-help-menu~1` The plugin adds an action for the OpenFastTrace user guide to the global Help menu. Users can find the user guide entry in the established IDE location for help content. @@ -272,7 +272,7 @@ Covers: Needs: scn -### Open OFT User Guide in Integrated Web View +#### Open OFT User Guide in Integrated Web View `req~open-oft-user-guide-in-integrated-web-view~1` The plugin opens the OpenFastTrace user guide from GitHub in an integrated web view tab. Users can read the guide inside the IDE. @@ -286,7 +286,7 @@ Needs: scn The following requirements refine the OFT live-template feature into user-visible capabilities. -### Bundle OFT Live Templates +#### Bundle OFT Live Templates `req~bundle-oft-live-templates~1` The plugin bundles an OpenFastTrace live-template group into the IDE installation. Users can access OFT live templates without importing template files manually. @@ -296,7 +296,7 @@ Covers: Needs: scn -### Provide OFT Scenario Live Template +#### Provide OFT Scenario Live Template `req~provide-oft-scenario-live-template~1` The bundled OpenFastTrace live-template group includes a scenario template for `scn` items. Users can insert a scenario skeleton with placeholders for the scenario title, item name, given-when-then text, and covered requirement. @@ -310,7 +310,7 @@ Needs: scn The following requirements refine the OFT reference-completion feature into user-visible capabilities. -### Complete Specification Item IDs in Covers Section +#### Complete Specification Item IDs in Covers Section `req~complete-specification-item-ids-in-covers-section~1` The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing an OFT item ID under `Covers:` in a supported specification document. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the item name, then by substring match against the item name, and finally by prefix match against the artifact type. @@ -320,7 +320,7 @@ Covers: Needs: scn -### Complete Specification Item IDs in Coverage Tag Target +#### Complete Specification Item IDs in Coverage Tag Target `req~complete-specification-item-ids-in-coverage-tag-target~1` The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing the target side of a likely OFT coverage tag in a supported source-code comment. Coverage-tag target completion is available for the default file extensions supported by the upstream OpenFastTrace Tag Importer. The completion context requires a left-hand artifact type and an arrow before the caret so suggestions appear for coverage-tag targets instead of ordinary comment text. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the item name, then by substring match against the item name, and finally by prefix match against the artifact type. @@ -334,7 +334,7 @@ Needs: scn The following requirements refine the Run OFT Trace feature into user-visible capabilities. -### Trace Open Project from Project Root +#### Trace Open Project from Project Root `req~trace-open-project-from-project-root~1` The plugin can trace an IntelliJ project by using the project directory as the default OpenFastTrace input root. @@ -344,7 +344,7 @@ Covers: Needs: scn -### Trace Selected Project Resources +#### Trace Selected Project Resources `req~trace-selected-project-resources~1` The plugin can trace selected project resources instead of the whole opened project directory. Users can restrict the OpenFastTrace scan to the resources they intend to include in the trace. @@ -354,7 +354,7 @@ Covers: Needs: scn -### Include IntelliJ Source Directories in Selected-Resource Trace +#### Include IntelliJ Source Directories in Selected-Resource Trace `req~include-intellij-source-directories-in-selected-resource-trace~1` When selected-resource tracing is active, the plugin can include source directories known to IntelliJ in the effective OpenFastTrace input set. Users do not need to discover and configure ordinary source roots by hand. @@ -364,7 +364,7 @@ Covers: Needs: scn -### Include IntelliJ Test Directories in Selected-Resource Trace +#### Include IntelliJ Test Directories in Selected-Resource Trace `req~include-intellij-test-directories-in-selected-resource-trace~1` When selected-resource tracing is active, the plugin can include test directories known to IntelliJ in the effective OpenFastTrace input set. Users do not need to discover and configure ordinary test roots by hand. @@ -374,7 +374,7 @@ Covers: Needs: scn -### Add Project-Relative Paths to Selected-Resource Trace +#### Add Project-Relative Paths to Selected-Resource Trace `req~add-project-relative-paths-to-selected-resource-trace~1` When selected-resource tracing is active, the plugin lets users add additional trace inputs through a multi-line text field in the run configuration editor. Each non-empty line specifies one file or directory path relative to the opened project directory that OpenFastTrace should scan. If the user has not changed that setting, the field contains exactly one default entry: `doc/`. @@ -384,7 +384,7 @@ Covers: Needs: scn -### Run Trace Project in Background +#### Run Trace Project in Background `req~run-trace-project-in-background~1` The plugin runs the OpenFastTrace project trace in a background task with IDE progress reporting. Users can start a trace without blocking the editor UI while the trace is running. @@ -394,7 +394,7 @@ Covers: Needs: scn -### Show Trace Result in Test Runner UI by Default +#### Show Trace Result in Test Runner UI by Default `req~show-trace-result-in-test-runner-ui-by-default~2` The plugin shows the trace result in IntelliJ's Test Runner UI by default. Users can inspect the project trace as structured source-file suites, specification-item tests, and trace-link sub-tests. @@ -405,7 +405,7 @@ Covers: Needs: scn -### Show Trace Output in IDE Output Window +#### Show Trace Output in IDE Output Window `req~show-trace-output-in-ide-output-window~2` The plugin can show the OpenFastTrace text trace output in an IDE output sub-window and keep that output available after the trace finishes. Users who select the plain text result view can inspect the plain text result inside the IDE without looking at log files or an external terminal. @@ -416,7 +416,7 @@ Covers: Needs: scn -### Open Specification Item from Trace Output Window +#### Open Specification Item from Trace Output Window `req~open-specification-item-from-trace-output-window~1` The plugin makes OpenFastTrace specification item IDs in the trace output window navigable to their declarations in the opened project. Users can jump from a reported item in the trace output directly to the defining specification item without searching manually. @@ -426,7 +426,7 @@ Covers: Needs: scn -### OpenFastTrace Run Configurations +### OFT Run Configurations `req~openfasttrace-run-configurations~1` The plugin provides a dedicated run configuration type for OpenFastTrace. Users can create, name, and save multiple trace configurations to switch quickly between different scan scopes and filters. @@ -436,7 +436,7 @@ Covers: Needs: scn -### OpenFastTrace Run Configuration Templates +#### OpenFastTrace Run Configuration Templates `req~openfasttrace-run-configuration-templates~1` The plugin provides pre-configured templates when creating new OpenFastTrace run configurations. These templates allow users to quickly set up common scanning scenarios. The following templates are available: @@ -450,7 +450,7 @@ Covers: Needs: scn -### Filter Trace by Artifact Types +#### Filter Trace by Artifact Types `req~filter-trace-by-artifact-types~1` When using an OpenFastTrace run configuration, the plugin lets users filter the trace results by artifact types. Users can specify a comma-separated list of types (e.g., `req, dsn`) to focus the trace on specific document layers. @@ -460,7 +460,7 @@ Covers: Needs: scn -### Filter Trace by Tags +#### Filter Trace by Tags `req~filter-trace-by-tags~1` When using an OpenFastTrace run configuration, the plugin lets users filter the trace results by tags. Users can specify a comma-separated list of tags to focus the trace on tagged specification items and can select an `Include untagged items` checkbox below the Tags field to also include specification items without tags. @@ -470,7 +470,7 @@ Covers: Needs: scn -### Select Trace Result View in Run Configuration +#### Select Trace Result View in Run Configuration `req~select-trace-result-view-in-run-configuration~2` The OpenFastTrace run configuration includes a result-view option for choosing plain text output or the IntelliJ Test Runner UI. @@ -485,11 +485,11 @@ Covers: Needs: scn -### Plugin Distribution +#### Plugin Distribution The following requirements refine how the plugin distribution appears in JetBrains plugin management surfaces. -### Plugin Logo for JetBrains Plugin Surfaces +#### Plugin Logo for JetBrains Plugin Surfaces `req~plugin-logo-for-jetbrains-plugin-surfaces~1` The plugin distribution includes JetBrains-compliant OpenFastTrace plugin logo assets that IntelliJ Platform IDEs and JetBrains Marketplace can display for the plugin. Users can recognize the plugin in plugin-management surfaces. @@ -500,7 +500,7 @@ JetBrains plugin surfaces use packaged plugin logo resources to distinguish plug Needs: scn -### Marketplace Metadata for JetBrains Plugin Surfaces +#### Marketplace Metadata for JetBrains Plugin Surfaces `req~marketplace-metadata-for-jetbrains-plugin-surfaces~1` The plugin distribution includes Marketplace-facing descriptor metadata that IntelliJ Platform IDEs and JetBrains Marketplace can display for the plugin. Developers and other OpenFastTrace users can understand the plugin purpose, maintained project links, vendor identity, compatible IDE baseline, and current release notes before installing or updating the plugin. @@ -511,11 +511,11 @@ JetBrains plugin surfaces extract key listing information from the packaged plug Needs: scn -### Run Configuration Presentation +#### Run Configuration Presentation The following requirements refine how OpenFastTrace run configurations appear in the IDE run/debug UI. -### OpenFastTrace Run Configuration Icon +#### OpenFastTrace Run Configuration Icon `req~openfasttrace-run-configuration-icon~1` The plugin shows an OpenFastTrace-specific icon for the `OpenFastTrace` run configuration type. Users can distinguish OpenFastTrace trace configurations from generic run actions in the run/debug UI. @@ -525,7 +525,11 @@ Covers: Needs: scn -### Show Trace Source Files as Test Runner Suites +### OFT Test Runner Trace Results + +The following requirements refine the OFT test-runner trace-results feature into user-visible capabilities. + +#### Show Trace Source Files as Test Runner Suites `req~show-trace-source-files-as-test-runner-suites~1` The IntelliJ Test Runner UI result view shows each traced source file as a test runner suite. For traced source files below the opened project directory, the suite label uses the project-local path, for example `doc/system_requirements.md`. @@ -535,7 +539,7 @@ Covers: Needs: scn -### Show Trace Specification Items as Test Runner Tests +#### Show Trace Specification Items as Test Runner Tests `req~show-trace-specification-items-as-test-runner-tests~1` The IntelliJ Test Runner UI result view shows each traced specification item as a test entry below the suite for the source file that contains that item. @@ -545,7 +549,7 @@ Covers: Needs: scn -### Show Specification Item Title in Test Runner UI +#### Show Specification Item Title in Test Runner UI `req~show-specification-item-title-in-test-runner-ui~2` The IntelliJ Test Runner UI result view uses the item's title as the visible specification-item name when the imported OpenFastTrace item provides a non-blank title. Items without a title show the full specification item ID as the visible name. @@ -555,7 +559,7 @@ Covers: Needs: scn -### Show Specification Item ID in Test Runner Details +#### Show Specification Item ID in Test Runner Details `req~show-specification-item-id-in-test-runner-details~1` The IntelliJ Test Runner UI result view shows the full specification item ID and trace status in the details for specification-item entries, even when the entry is passed. @@ -565,7 +569,7 @@ Covers: Needs: scn -### Sort Specification Items in Test Runner UI +#### Sort Specification Items in Test Runner UI `req~sort-specification-items-in-test-runner-ui~1` Within each source-file suite, the IntelliJ Test Runner UI result view sorts specification item entries by artifact type, then by the name part of the specification item ID, then by revision number. @@ -575,7 +579,7 @@ Covers: Needs: scn -### Show Trace Links as Test Runner Sub-Tests +#### Show Trace Links as Test Runner Sub-Tests `req~show-trace-links-as-test-runner-sub-tests~1` The IntelliJ Test Runner UI result view shows each incoming or outgoing trace link as a sub-test below the connected specification item for which the link is shown. @@ -585,7 +589,7 @@ Covers: Needs: scn -### Show Specification Item Status in Test Runner UI +#### Show Specification Item Status in Test Runner UI `req~show-specification-item-status-in-test-runner-ui~2` The IntelliJ Test Runner UI result view includes a specification item's trace status in brackets in the item entry only when the item status is not clean, for example `(uncovered)` or `(defective)`. @@ -595,7 +599,7 @@ Covers: Needs: scn -### Show Trace Link Status in Test Runner UI +#### Show Trace Link Status in Test Runner UI `req~show-trace-link-status-in-test-runner-ui~2` The IntelliJ Test Runner UI result view includes a trace link's status in brackets in the link entry only when the link status is not clean, for example `(orphaned)`. @@ -605,7 +609,7 @@ Covers: Needs: scn -### Show Trace Link Direction in Test Runner UI +#### Show Trace Link Direction in Test Runner UI `req~show-trace-link-direction-in-test-runner-ui~1` The IntelliJ Test Runner UI result view marks each trace link entry as incoming or outgoing. Users can distinguish links that cover the specification item from links that the specification item covers. @@ -615,7 +619,7 @@ Covers: Needs: scn -### Show Unicode Trace Link Direction in Test Runner UI +#### Show Unicode Trace Link Direction in Test Runner UI `req~show-unicode-trace-link-direction-in-test-runner-ui~1` The IntelliJ Test Runner UI result view uses Unicode arrows in trace-link entries. Incoming links use `←`, outgoing links use `→`, and links without a single incoming or outgoing direction use `↔`. @@ -625,7 +629,7 @@ Covers: Needs: scn -### Map Specification Item Trace Status to Test Runner Status +#### Map Specification Item Trace Status to Test Runner Status `req~map-specification-item-trace-status-to-test-runner-status~1` The IntelliJ Test Runner UI result view treats a clean specification item as a passed test and a defective specification item as a failed test. @@ -635,7 +639,7 @@ Covers: Needs: scn -### Map Trace Link Status to Test Runner Status +#### Map Trace Link Status to Test Runner Status `req~map-trace-link-status-to-test-runner-status~1` The IntelliJ Test Runner UI result view treats a clean incoming or outgoing trace link as a passed sub-test and a defective incoming or outgoing trace link as a failed sub-test. @@ -645,7 +649,7 @@ Covers: Needs: scn -### Roll Up Source File Suite Trace Status +#### Roll Up Source File Suite Trace Status `req~roll-up-source-file-suite-trace-status~1` The IntelliJ Test Runner UI result view marks a source-file suite as failed if any specification item or trace-link sub-test below that source file is failed. It marks the source-file suite as passed only if all descendants are clean. @@ -655,7 +659,7 @@ Covers: Needs: scn -### Roll Up Top-Level Trace Status +#### Roll Up Top-Level Trace Status `req~roll-up-top-level-trace-status~1` The IntelliJ Test Runner UI result view marks the top-level trace suite as failed if any source-file suite contains a failed descendant. It marks the top-level trace suite as passed only if all source-file suites are clean. @@ -665,7 +669,7 @@ Covers: Needs: scn -### Show Specification Item Defect Details in Test Runner UI +#### Show Specification Item Defect Details in Test Runner UI `req~show-specification-item-defect-details-in-test-runner-ui~1` The IntelliJ Test Runner UI result view shows a clear details text for failed specification-item entries. The details identify the specification item, its trace status, and the reason the item is defective. @@ -675,7 +679,7 @@ Covers: Needs: scn -### Show Trace Link Defect Details in Test Runner UI +#### Show Trace Link Defect Details in Test Runner UI `req~show-trace-link-defect-details-in-test-runner-ui~1` The IntelliJ Test Runner UI result view shows a clear details text for failed trace-link entries. The details identify the owning specification item, the linked item, the link direction, the trace-link status, and the reason that status is defective. @@ -685,7 +689,7 @@ Covers: Needs: scn -### Show Trace Link ID Details in Test Runner UI +#### Show Trace Link ID Details in Test Runner UI `req~show-trace-link-id-details-in-test-runner-ui~1` The IntelliJ Test Runner UI result view shows the owning specification item ID, linked specification item ID, link direction, and trace-link status in the details for trace-link entries, even when the entry is passed. @@ -695,7 +699,7 @@ Covers: Needs: scn -### Navigate from Test Runner Specification Items +#### Navigate from Test Runner Specification Items `req~navigate-from-test-runner-specification-items~1` Users can navigate from a specification item entry in the IntelliJ Test Runner UI result view to the corresponding specification item declaration in the opened project. @@ -705,7 +709,7 @@ Covers: Needs: scn -### Navigate from Test Runner Trace Links +#### Navigate from Test Runner Trace Links `req~navigate-from-test-runner-trace-links~1` Users can navigate from a trace-link entry in the IntelliJ Test Runner UI result view to the corresponding specification item declaration or source-side coverage tag in the opened project. @@ -715,7 +719,7 @@ Covers: Needs: scn -### Navigate from Test Runner Source Files +#### Navigate from Test Runner Source Files `req~navigate-from-test-runner-source-files~1` Users can navigate from a source-file suite entry in the IntelliJ Test Runner UI result view to the corresponding file in the opened project. @@ -725,7 +729,7 @@ Covers: Needs: scn -### Show Scanned Base Directory in Trace Output Window +#### Show Scanned Base Directory in Trace Output Window `req~show-scanned-base-directory-in-trace-output-window~1` When a plain text project trace starts, the plugin writes the resolved project base directory that OpenFastTrace scans into the IDE output sub-window. Users can confirm the actual trace input root directly from the trace output. @@ -735,7 +739,7 @@ Covers: Needs: scn -### Show Resolved Trace Inputs in Trace Output Window +#### Show Resolved Trace Inputs in Trace Output Window `req~show-resolved-trace-inputs-in-trace-output-window~1` When a plain text project trace starts with selected-resource tracing, the plugin writes the resolved files and directories that it passes to OpenFastTrace into the IDE output sub-window. Users can confirm the actual configured trace scope directly from the trace output. @@ -745,7 +749,7 @@ Covers: Needs: scn -### Report Invalid Project Path before Trace Start +#### Report Invalid Project Path before Trace Start `req~report-invalid-project-path-before-trace-start~1` The plugin reports when the opened project does not resolve to a valid local path before starting the trace. Users can see why the trace cannot start without inspecting plugin logs. @@ -755,7 +759,7 @@ Covers: Needs: scn -### Show Failing Trace Result in IDE Output Window +#### Show Failing Trace Result in IDE Output Window `req~show-failing-trace-result-in-ide-output-window~1` When plain text output is selected, the plugin shows failing OpenFastTrace executions through the same IDE output flow as successful traces, including the text output and the failing result. Users can inspect trace failures without switching to plugin logs or an external terminal. @@ -765,7 +769,7 @@ Covers: Needs: scn -### Show Defect Count for Unclean Trace Chain in IDE Output Window +#### Show Defect Count for Unclean Trace Chain in IDE Output Window `req~show-defect-count-for-unclean-trace-chain-in-output-window~1` The plugin preserves the OpenFastTrace plain-text defect summary for an unclean trace chain in the IDE output window, including the reported total-item count and defect count. Users can verify how many trace issues OpenFastTrace found directly from the text result. @@ -1573,6 +1577,20 @@ Covers: Needs: dsn +#### Mark Transitive Defects in Test Runner +`scn~mark-transitive-defects-in-test-runner~1` + +**Given** an `OpenFastTrace` run configuration uses the IntelliJ Test Runner UI result view and the trace result contains defective specification items +**When** the trace completes +**Then** the node name of specification items that are identified as transitive defects start with "↳" +**And** the failure description calls the failure a transitive error +**And** the failure description tells users to fix the specification items this one depends on. + +Covers: +- `req~map-specification-item-trace-status-to-test-runner-status~1` + +Needs: dsn + ### Map Trace Link Status to Test Runner Status `scn~map-trace-link-status-to-test-runner-status~1` From 02fc54eea0146fd2134326a5a4de7f1a677b330e Mon Sep 17 00:00:00 2001 From: redcatbear Date: Wed, 5 Aug 2026 09:23:56 +0200 Subject: [PATCH 2/6] #39: Marking transitive defects. --- doc/design/building_block_view.md | 3 +- doc/design/runtime_view.md | 12 +++ .../trace/OftTraceTestNodeDetails.java | 8 ++ .../trace/OftTraceTestTreeMapper.java | 4 +- ...OftTraceTestRunnerOutputPresenterTest.java | 80 ++++++++++++++++++- .../trace/OftTraceTestTreeMapperTest.java | 79 ++++++++++++++++++ 6 files changed, 180 insertions(+), 6 deletions(-) diff --git a/doc/design/building_block_view.md b/doc/design/building_block_view.md index b195b2e..17524bc 100644 --- a/doc/design/building_block_view.md +++ b/doc/design/building_block_view.md @@ -382,7 +382,7 @@ Needs: impl, itest ### Trace Test Runner Presentation `dsn~trace-test-runner-presentation~1` -The plugin provides a trace test-runner presentation component that maps the structured OpenFastTrace trace result to IntelliJ SM test runner nodes. It creates project-local source-file suites, sorted specification-item tests, and incoming or outgoing trace-link sub-tests; derives compact title-aware labels, Unicode direction markers, pass/fail status, status roll-up, and item/link details from the OpenFastTrace trace status; and connects source-file, item, and link node navigation to the existing OpenFastTrace trace navigation support. +The plugin provides a trace test-runner presentation component that maps the structured OpenFastTrace trace result to IntelliJ SM test runner nodes. It creates project-local source-file suites, sorted specification-item tests, and incoming or outgoing trace-link sub-tests; derives compact title-aware labels, Unicode direction markers, transitive-defect markers, pass/fail status, status roll-up, and item/link details from the OpenFastTrace trace status; and connects source-file, item, and link node navigation to the existing OpenFastTrace trace navigation support. Covers: - `scn~show-trace-source-files-as-test-runner-suites~1` @@ -392,6 +392,7 @@ Covers: - `scn~sort-specification-items-in-test-runner-ui~1` - `scn~show-trace-links-as-test-runner-sub-tests~1` - `scn~show-specification-item-status-in-test-runner-ui~2` +- `scn~mark-transitive-defects-in-test-runner~1` - `scn~show-trace-link-status-in-test-runner-ui~2` - `scn~show-trace-link-direction-in-test-runner-ui~1` - `scn~show-unicode-trace-link-direction-in-test-runner-ui~1` diff --git a/doc/design/runtime_view.md b/doc/design/runtime_view.md index 7afcaad..309441b 100644 --- a/doc/design/runtime_view.md +++ b/doc/design/runtime_view.md @@ -606,6 +606,18 @@ Covers: Needs: impl, itest +No### Mark Transitive Defects in Test Runner UI +`dsn~mark-transitive-defects-in-test-runner~1` + +**Given** the trace test-runner presentation creates a specification-item test node for a defective item that is identified as a transitive defect +**When** it derives the node name from the OpenFastTrace trace result +**Then** it prefixes the visible node name with `↳` so transitive defects are visually distinct in the tree. + +Covers: +- `scn~mark-transitive-defects-in-test-runner~1` + +Needs: impl, itest + ### Show Trace Link Status in Test Runner UI `dsn~show-trace-link-status-in-test-runner-ui~2` diff --git a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java index aafa029..b205dcb 100644 --- a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java +++ b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java @@ -129,6 +129,9 @@ private static String traceLinkDetailText( } private static String itemFailureMessage(final LinkedSpecificationItem item, final String visibleStatus) { + if (item.isTransitiveDefect()) { + return "Transitive trace defect. The problem is not in this item but in one it depends on."; + } return switch (visibleStatus) { case "duplicate" -> "Duplicate OpenFastTrace specification item."; case "cycle" -> "OpenFastTrace coverage cycle."; @@ -138,6 +141,11 @@ private static String itemFailureMessage(final LinkedSpecificationItem item, fin } private static String itemFailureExplanation(final LinkedSpecificationItem item, final String visibleStatus) { + if (item.isTransitiveDefect()) { + return "This transitive error is caused by the specification items this one depends on." + + LINE_SEPARATOR + + "Fix the specification items this one depends on."; + } return switch (visibleStatus) { case "duplicate" -> "The trace contains more than one specification item with this ID."; case "cycle" -> "Deep coverage cannot be proven because the coverage graph contains a cycle."; diff --git a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java index 38ab8d7..ec488f1 100644 --- a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java +++ b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java @@ -91,8 +91,10 @@ private static OftTraceItemNode mapItem( ) { final String itemStatus = itemStatus(item); final String itemId = item.getId().toString(); + final String itemName = itemName(item); + final String visibleItemName = item.isTransitiveDefect() ? "↳ " + itemName : itemName; return new OftTraceItemNode( - nodeName(itemName(item), itemStatus, !item.isDefect()), + nodeName(visibleItemName, itemStatus, !item.isDefect()), itemId, item.isDefect(), item.isDefect() diff --git a/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestRunnerOutputPresenterTest.java b/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestRunnerOutputPresenterTest.java index d038168..64c4102 100644 --- a/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestRunnerOutputPresenterTest.java +++ b/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestRunnerOutputPresenterTest.java @@ -23,9 +23,12 @@ import org.itsallcode.openfasttrace.intellijplugin.trace.runconfig.OftRunConfigurationType; import org.jspecify.annotations.NonNull; +import java.io.IOException; import java.util.Arrays; import java.util.List; import java.util.Objects; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.concurrent.atomic.AtomicReference; import static org.hamcrest.MatcherAssert.assertThat; @@ -33,6 +36,7 @@ import static org.hamcrest.Matchers.hasSize; import static org.hamcrest.Matchers.is; import static org.hamcrest.Matchers.notNullValue; +import static org.junit.jupiter.api.Assertions.assertAll; // [itest->dsn~trace-test-runner-presentation~1] public class OftTraceTestRunnerOutputPresenterTest extends AbstractOftPlatformTestCase { @@ -128,6 +132,39 @@ public void testGivenDefectiveTraceResultWhenPresentedThenItCreatesFailedItemAnd assertThat(resultsViewer.getFailedTestCount(), is(2)); } + // [itest->dsn~mark-transitive-defects-in-test-runner~1] + // [itest->dsn~trace-test-runner-presentation~1] + // [itest->dsn~show-specification-item-status-in-test-runner-ui~2] + // [itest->dsn~show-specification-item-defect-details-in-test-runner-ui~1] + // [itest->dsn~roll-up-source-file-suite-trace-status~1] + // [itest->dsn~roll-up-top-level-trace-status~1] + public void testGivenTransitiveDefectTraceResultWhenPresentedThenItPrefixesTheNodeNameAndExplainsTheError() + throws IOException { + writeUncleanTraceChainProject(Path.of(Objects.requireNonNull(getProject().getBasePath()))); + + final OftTraceResult result = new OftTraceService().traceProject( + OftTraceInputs.wholeProject(Path.of(Objects.requireNonNull(getProject().getBasePath())), List.of(), List.of()), + OftTraceProgress.NONE + ); + final SMTRunnerConsoleView console = present(result); + final SMTestRunnerResultsForm resultsViewer = console.getResultsViewer(); + final SMTestProxy suite = resultsViewer.getTestsRootNode().getChildren().getFirst(); + final SMTestProxy transitiveFeature = suite.getChildren().stream() + .filter(child -> child.getName().startsWith("↳ Feature")) + .findFirst() + .orElseThrow(); + + assertAll( + () -> assertThat(transitiveFeature.isSuite(), is(true)), + () -> assertThat(transitiveFeature.isDefect(), is(true)), + () -> assertThat(transitiveFeature.getErrorMessage(), + is("Transitive trace defect. The problem is not in this item but in one it depends on.")), + () -> assertThat(transitiveFeature.getStacktrace(), containsString("Specification item ID: feat~chain_feature~1")), + () -> assertThat(transitiveFeature.getStacktrace(), containsString("Trace status: uncovered")), + () -> assertThat(transitiveFeature.getStacktrace(), containsString("Fix the specification items this one depends on.")), + () -> assertThat(resultsViewer.getTestsRootNode().isDefect(), is(true))); + } + public void testGivenResultWithoutStructuredTraceWhenPresentedThenItCreatesFailedFallbackNode() { final SMTRunnerConsoleView console = present(OftTraceResult.invalidInput("invalid configuration")); final SMTestRunnerResultsForm resultsViewer = console.getResultsViewer(); @@ -234,12 +271,47 @@ private static Trace trace(final LinkedSpecificationItem... items) { .build(); } - private static LinkedSpecificationItem titledItem(final String id, final String locationPath, final String title) { - return new LinkedSpecificationItem(SpecificationItem.builder() + private static LinkedSpecificationItem titledItem( + final String id, + final String locationPath, + final String title, + final String... needsArtifactTypes + ) { + final SpecificationItem.Builder builder = SpecificationItem.builder() .id(SpecificationItemId.parseId(id)) .title(title) .status(ItemStatus.APPROVED) - .location(locationPath, 1) - .build()); + .location(locationPath, 1); + Arrays.stream(needsArtifactTypes).forEach(builder::addNeedsArtifactType); + return new LinkedSpecificationItem(builder.build()); + } + + private void writeUncleanTraceChainProject(final Path projectRoot) throws IOException { + final Path docDirectory = Files.createDirectories(projectRoot.resolve("doc")); + Files.writeString( + docDirectory.resolve("trace.md"), + """ + ### Feature + `feat~chain_feature~1` + + Needs: req + + ### Requirement + `req~chain_requirement~1` + + Covers: + - `feat~chain_feature~1` + + Needs: dsn + + ### Design + `dsn~chain_design~1` + + Covers: + - `req~chain_requirement~1` + + Needs: impl + """ + ); } } diff --git a/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapperTest.java b/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapperTest.java index 3f59c93..b908579 100644 --- a/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapperTest.java +++ b/src/test/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapperTest.java @@ -11,7 +11,11 @@ import org.itsallcode.openfasttrace.intellijplugin.trace.OftTraceTestTree.OftTraceSuiteNode; import org.junit.jupiter.api.Assertions; import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.io.TempDir; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Path; import java.util.Arrays; import java.util.List; @@ -20,6 +24,7 @@ import static org.hamcrest.Matchers.containsString; import static org.hamcrest.Matchers.hasSize; import static org.hamcrest.Matchers.is; +import static org.hamcrest.Matchers.startsWith; class OftTraceTestTreeMapperTest { private static final String PROJECT_BASE = "/workspace/openfasttrace-intellij-plugin"; @@ -275,6 +280,44 @@ void testGivenOutgoingOrphanedTraceLinkWhenMappingThenItCreatesFailedItemAndLink ); } + // [itest->dsn~mark-transitive-defects-in-test-runner~1] + // [itest->dsn~trace-test-runner-presentation~1] + // [itest->dsn~mark-transitive-defects-in-test-runner~1] + // [itest->dsn~trace-test-runner-presentation~1] + // [itest->dsn~show-specification-item-status-in-test-runner-ui~2] + // [itest->dsn~show-specification-item-defect-details-in-test-runner-ui~1] + // [itest->dsn~roll-up-source-file-suite-trace-status~1] + // [itest->dsn~roll-up-top-level-trace-status~1] + @Test + void testGivenTransitiveDefectsWhenMappingThenItPrefixesTheirNodeNames(@TempDir final Path temporaryDirectory) + throws IOException { + writeUncleanTraceChainProject(temporaryDirectory); + + final Trace trace = new OftTraceService().traceProject( + OftTraceInputs.wholeProject(temporaryDirectory, List.of(), List.of()), + OftTraceProgress.NONE + ).trace().orElseThrow(); + final OftTraceTestTree tree = OftTraceTestTreeMapper.map(trace); + final OftTraceSuiteNode suite = tree.suites().getFirst(); + + Assertions.assertAll( + () -> assertThat( + suite.items().stream() + .map(OftTraceItemNode::name) + .toList(), + hasSize(3) + ), + () -> assertThat(suite.items().get(0).name(), is("Design (uncovered)")), + () -> assertThat(suite.items().get(1).name(), startsWith("↳ Feature")), + () -> assertThat(suite.items().get(2).name(), startsWith("↳ Requirement")), + () -> assertThat(itemNamedStartingWith(suite, "↳ Requirement").details().failureMessage(), + is("Transitive trace defect. The problem is not in this item but in one it depends on.")), + () -> assertThat(itemNamedStartingWith(suite, "↳ Requirement").details().detailText(), + containsString("Fix the specification items this one depends on.")), + () -> assertThat(tree.failed(), is(true)) + ); + } + // [itest->dsn~trace-test-runner-presentation~1] // [itest->dsn~show-specification-item-status-in-test-runner-ui~2] // [itest->dsn~map-specification-item-trace-status-to-test-runner-status~1] @@ -315,6 +358,13 @@ private static OftTraceItemNode onlyItem(final OftTraceTestTree tree, final Stri return items.getFirst(); } + private static OftTraceItemNode itemNamedStartingWith(final OftTraceSuiteNode suite, final String itemNamePrefix) { + return suite.items().stream() + .filter(item -> item.name().startsWith(itemNamePrefix)) + .findFirst() + .orElseThrow(); + } + private static Trace trace(final LinkedSpecificationItem... items) { final List traceItems = Arrays.asList(items); return Trace.builder() @@ -325,6 +375,35 @@ private static Trace trace(final LinkedSpecificationItem... items) { .build(); } + private static void writeUncleanTraceChainProject(final Path projectRoot) throws IOException { + final Path docDirectory = Files.createDirectories(projectRoot.resolve("doc")); + Files.writeString( + docDirectory.resolve("trace.md"), + """ + ### Feature + `feat~chain_feature~1` + + Needs: req + + ### Requirement + `req~chain_requirement~1` + + Covers: + - `feat~chain_feature~1` + + Needs: dsn + + ### Design + `dsn~chain_design~1` + + Covers: + - `req~chain_requirement~1` + + Needs: impl + """ + ); + } + private static LinkedSpecificationItem item( final String id, final String locationPath, From 7694c4cda5586c2e8aca1fc1d60042127de309a6 Mon Sep 17 00:00:00 2001 From: redcatbear Date: Wed, 5 Aug 2026 09:27:25 +0200 Subject: [PATCH 3/6] #66: Updated changelog and user guide. --- doc/changes/changes_0.10.0.md | 4 +++- doc/user_guide.md | 2 ++ 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/changes/changes_0.10.0.md b/doc/changes/changes_0.10.0.md index fe87add..e36ad03 100644 --- a/doc/changes/changes_0.10.0.md +++ b/doc/changes/changes_0.10.0.md @@ -1,6 +1,7 @@ # OpenFastTrace IntelliJ Plugin 0.10.0, released 2026-07-04 We also updated the bundled OFT to 4.8.0 so tag filters now work end to end instead of being ignored. +The Test Runner UI now marks transitive defects with a leading `↳` so they stand out from direct defects in the result tree. ## Bundled OpenFastTrace @@ -8,4 +9,5 @@ OpenFastTrace 4.8.0 ## Bugfix -* #39: Re-enabled tag filter test \ No newline at end of file +* #39: Re-enabled tag filter test +* #66: Transitive defects now use a visible `↳` prefix in the Test Runner UI diff --git a/doc/user_guide.md b/doc/user_guide.md index 0fe1eb5..918ae94 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -166,6 +166,8 @@ Use it to: Clean items are shown as passed tests. Trace defects are shown as failed tests. The top-level trace result is marked failed when OFT reports trace defects. +Transitive defects in the tree are prefixed with `↳` so they are easy to distinguish from direct defects. + Plain text output is useful when you want the raw OFT report. Specification item IDs in the plain text output are clickable when the plugin can resolve them to project files. ![OpenFastTrace trace result in the IntelliJ Test Runner UI](user_guide/images/test-runner-results.png) From 3e51da1ffe3ba5d51b38ca27bebca3f41b884c2d Mon Sep 17 00:00:00 2001 From: redcatbear Date: Thu, 6 Aug 2026 06:25:26 +0200 Subject: [PATCH 4/6] #66: Fixed self trace. --- .../intellijplugin/trace/OftTraceTestNodeDetails.java | 2 ++ .../intellijplugin/trace/OftTraceTestTreeMapper.java | 7 ++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java index b205dcb..8db2ae0 100644 --- a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java +++ b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestNodeDetails.java @@ -128,6 +128,7 @@ private static String traceLinkDetailText( + "Trace-link status: " + visibleStatus; } + // [impl -> dsn~mark-transitive-defects-in-test-runner~1] private static String itemFailureMessage(final LinkedSpecificationItem item, final String visibleStatus) { if (item.isTransitiveDefect()) { return "Transitive trace defect. The problem is not in this item but in one it depends on."; @@ -140,6 +141,7 @@ private static String itemFailureMessage(final LinkedSpecificationItem item, fin }; } + // [impl -> dsn~mark-transitive-defects-in-test-runner~1] private static String itemFailureExplanation(final LinkedSpecificationItem item, final String visibleStatus) { if (item.isTransitiveDefect()) { return "This transitive error is caused by the specification items this one depends on." diff --git a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java index ec488f1..9f6fb2e 100644 --- a/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java +++ b/src/main/java/org/itsallcode/openfasttrace/intellijplugin/trace/OftTraceTestTreeMapper.java @@ -92,7 +92,7 @@ private static OftTraceItemNode mapItem( final String itemStatus = itemStatus(item); final String itemId = item.getId().toString(); final String itemName = itemName(item); - final String visibleItemName = item.isTransitiveDefect() ? "↳ " + itemName : itemName; + final String visibleItemName = getVisibleItemName(item, itemName); return new OftTraceItemNode( nodeName(visibleItemName, itemStatus, !item.isDefect()), itemId, @@ -106,6 +106,11 @@ private static OftTraceItemNode mapItem( ); } + // [impl -> dsn~mark-transitive-defects-in-test-runner~1] + private static String getVisibleItemName(final LinkedSpecificationItem item, final String itemName) { + return item.isTransitiveDefect() ? "↳ " + itemName : itemName; + } + private static List visibleLinksByItem( final List items ) { From 65ddd250c06cd9fa3a90fbcf230f00076175af37 Mon Sep 17 00:00:00 2001 From: redcatbear Date: Thu, 6 Aug 2026 07:53:40 +0200 Subject: [PATCH 5/6] #66: Made terminology around ID more precise. --- doc/design/building_block_view.md | 4 ++-- doc/design/runtime_view.md | 10 +++++----- doc/design/solution_strategy.md | 10 +++++----- doc/system_requirements.md | 26 +++++++++++++------------- doc/user_guide.md | 2 +- 5 files changed, 26 insertions(+), 26 deletions(-) diff --git a/doc/design/building_block_view.md b/doc/design/building_block_view.md index 17524bc..411fdf9 100644 --- a/doc/design/building_block_view.md +++ b/doc/design/building_block_view.md @@ -252,7 +252,7 @@ Needs: impl ### Specification Item Navigation `dsn~specification-item-navigation~1` -The plugin exposes indexed OpenFastTrace specification item declarations through the IntelliJ navigation facilities so users can find declarations through `Go to Symbol` and the Symbols tab in `Search Everywhere`, invoke `Go To Declaration` from `Covers:` entries and from either side of coverage tags, and invoke `Go To Implementations` on a declaration to see coverage-providing occurrences. For shortened left sides of coverage tags, the navigation component resolves the effective covering item ID by inheriting missing name and revision parts from the covered ID on the right side before opening the corresponding declaration. +The plugin exposes indexed OpenFastTrace specification item declarations through the IntelliJ navigation facilities so users can find declarations through `Go to Symbol` and the Symbols tab in `Search Everywhere`, invoke `Go To Declaration` from `Covers:` entries and from either side of coverage tags, and invoke `Go To Implementations` on a declaration to see coverage-providing occurrences. For shortened left sides of coverage tags, the navigation component resolves the effective covering item ID by inheriting the missing middle component and revision from the covered ID on the right side before opening the corresponding declaration. Covers: - `scn~show-specification-item-in-go-to-symbol~1` @@ -269,7 +269,7 @@ Needs: impl ### Specification Item Completion `dsn~specification-item-completion~1` -The plugin provides a specification-item completion component that activates IntelliJ basic completion for supported OFT reference authoring contexts, reads declared specification item IDs from the project-local declaration index, and presents those IDs in a deterministic order based on full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches. Supported contexts include OFT item references under `Covers:` in supported specification documents, completion requests started from an active live-template placeholder when the placeholder expands inside a `Covers:` entry, and the target side of likely OFT coverage tags in source-code comments for the default file extensions supported by the upstream OpenFastTrace Tag Importer after a left-hand artifact type and arrow. +The plugin provides a specification-item completion component that activates IntelliJ basic completion for supported OFT reference authoring contexts, reads declared specification item IDs from the project-local declaration index, and presents those IDs in a deterministic order based on full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches. Supported contexts include OFT item references under `Covers:` in supported specification documents, completion requests started from an active live-template placeholder when the placeholder expands inside a `Covers:` entry, and the target side of likely OFT coverage tags in source-code comments for the default file extensions supported by the upstream OpenFastTrace Tag Importer after a left-hand artifact type and arrow. Covers: - `scn~complete-specification-item-id-in-covers-section~1` diff --git a/doc/design/runtime_view.md b/doc/design/runtime_view.md index 309441b..6394911 100644 --- a/doc/design/runtime_view.md +++ b/doc/design/runtime_view.md @@ -205,7 +205,7 @@ Needs: impl, itest **Given** a supported source file contains an OFT coverage tag whose left side is shortened and the corresponding covering specification item is declared in the project **When** a user invokes `Go To Declaration` on the left side of the coverage tag -**Then** the navigation component resolves the effective covering item ID by copying the missing name and revision parts from the covered ID on the right side and opens the specification document at the declaration anchor of that covering item. +**Then** the navigation component resolves the effective covering item ID by copying the missing middle component and revision from the covered ID on the right side and opens the specification document at the declaration anchor of that covering item. Covers: - `scn~open-specification-item-from-coverage-tag-left-side~1` @@ -232,7 +232,7 @@ Needs: impl, itest **Given** a supported specification document contains a `Covers:` entry and the opened project already indexes declared OpenFastTrace specification items **When** a user invokes IntelliJ basic completion while editing an OFT item ID in that `Covers:` entry **Then** the completion component confirms that the caret is inside a `Covers:` reference, loads declared specification item IDs from the declaration index -**And** ranks them by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches +**And** ranks them by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches **And** shows the ordered suggestions in the standard IDE completion popup. Covers: @@ -258,7 +258,7 @@ Needs: impl, itest **Given** a source, configuration, or markup file with a default extension supported by the upstream OpenFastTrace Tag Importer contains a comment with an OFT coverage-tag candidate whose left-hand side contains an artifact type and whose right-hand side contains the caret after `->` **When** a user invokes IntelliJ basic completion on the right-hand side -**Then** the completion component confirms the supported file and comment context, extracts the target-side prefix under the caret, loads declared specification item IDs from the declaration index, ranks them by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches, and shows the ordered suggestions in the standard IDE completion popup. +**Then** the completion component confirms the supported file and comment context, extracts the target-side prefix under the caret, loads declared specification item IDs from the declaration index, ranks them by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches, and shows the ordered suggestions in the standard IDE completion popup. Covers: - `scn~complete-specification-item-id-in-coverage-tag-target~1` @@ -346,7 +346,7 @@ Needs: impl, itest **Given** the bundled OpenFastTrace live-template group is available in a supported editing context **When** a user expands the `scn` live template -**Then** IntelliJ inserts the scenario template text from the bundled plugin resource and lets the user tab through the placeholders for the title, item name, `Given`, `When`, `Then`, and covered requirement. +**Then** IntelliJ inserts the scenario template text from the bundled plugin resource and lets the user tab through the placeholders for the title, item ID, `Given`, `When`, `Then`, and covered requirement. Covers: - `scn~insert-oft-scenario-live-template~1` @@ -575,7 +575,7 @@ Needs: impl, itest **Given** the trace test-runner presentation maps traced specification items for one source-file suite **When** it creates the specification-item test nodes -**Then** it orders them by artifact type, the specification item ID name part, and revision number. +**Then** it orders them by artifact type, the middle component of the specification item ID, and revision number. Covers: - `scn~sort-specification-items-in-test-runner-ui~1` diff --git a/doc/design/solution_strategy.md b/doc/design/solution_strategy.md index 59574ac..2d6c0f8 100644 --- a/doc/design/solution_strategy.md +++ b/doc/design/solution_strategy.md @@ -30,7 +30,7 @@ This strategy reduces custom code, lowers maintenance effort, and improves cross The index distinguishes rigorously between OpenFastTrace declarations and OpenFastTrace coverage occurrences. That distinction is the foundation for correct IDE navigation. -An OpenFastTrace specification item is declared only in a specification document such as Markdown or reStructuredText when the document defines the item itself. The declaration is the item header line that contains the full OpenFastTrace item ID, for example `req~user_login~1`. In Markdown, OFT permits two declaration forms for that line: the plain full ID and the same full ID enclosed in single backticks. Both forms declare the same specification item and must therefore produce the same canonical declaration identity for indexing and navigation. This full ID is the canonical identity of the item because it combines artifact type, name, and revision into the stable project-wide key. The precise location of the declaration is the text range of that ID in the specification item header. In OFT terms, this is the item's visible sub-title. In IDE terms, this is the declaration site and primary navigation target. +An OpenFastTrace specification item is declared only in a specification document such as Markdown or reStructuredText when the document defines the item itself. The declaration is the item header line that contains the full OpenFastTrace item ID, for example `req~user_login~1`. In Markdown, OFT permits two declaration forms for that line: the plain full ID and the same full ID enclosed in single backticks. Both forms declare the same specification item and must therefore produce the same canonical declaration identity for indexing and navigation. This full ID is the canonical identity of the item because it combines artifact type, the middle component of the ID, and revision into the stable project-wide key. The precise location of the declaration is the text range of that ID in the specification item header. In OFT terms, this is the item's visible sub-title. In IDE terms, this is the declaration site and primary navigation target. The remainder of the specification item body does not declare the item again. In particular, entries under `Covers:` are not declarations. They are coverage occurrences that point to other declared specification items. The same is true for OFT coverage tags in source files. These locations provide coverage in the OpenFastTrace domain model, but from the JetBrains IDE point of view they are usages or references of an already declared item. @@ -39,17 +39,17 @@ This terminology matters because the IntelliJ Platform separates declarations fr The OFT to JetBrains mapping is therefore as follows: - An OFT specification item identified by its full ID is the semantic project entity that users search and navigate to. Conceptually this is the symbol. -- The occurrence of that full ID in the header of a specification item in `.md`, `.markdown`, or `.rst` is the declaration. In Markdown, both the plain form and the single-backtick form are declaration forms of the same item. In a PSI-first implementation this declaration is represented by a PSI element that carries the item's canonical name and can act as a `NavigationItem`. +- The occurrence of that full ID in the header of a specification item in `.md`, `.markdown`, or `.rst` is the declaration. In Markdown, both the plain form and the single-backtick form are declaration forms of the same item. In a PSI-first implementation this declaration is represented by a PSI element that carries the item's canonical identifier and can act as a `NavigationItem`. - The text range of the full ID inside that header is the declaration anchor. That is the range that `Go To` and search results should open. - An occurrence of an OFT item ID under `Covers:` in a specification document is a reference from one item to another declared item. - An occurrence of an OFT item ID inside an OFT coverage tag in source code is also a reference from that source location to a declared item. - A `Go to Symbol` result is produced from indexed declarations only. Coverage occurrences are not separate symbol results. -This mapping also clarifies what the index stores. The symbol-facing index stores declarations keyed by the canonical full OFT item ID. Additional lookup keys such as the name part may be stored as aliases for search convenience, but they do not replace the canonical identity. The artifact type prefix such as `req`, `dsn`, or `impl` is part of that identity and may additionally be surfaced as presentation metadata, grouping information, or a type label in result lists. +This mapping also clarifies what the index stores. The symbol-facing index stores declarations keyed by the canonical full OFT item ID. Additional lookup keys such as the middle component of the ID may be stored as aliases for search convenience, but they do not replace the canonical identity. The artifact type prefix such as `req`, `dsn`, or `impl` is part of that identity and may additionally be surfaced as presentation metadata, grouping information, or a type label in result lists. -For IntelliJ's search and navigation facilities, the declaration index is the source of truth for `Go to Symbol` and `Search Everywhere`. JetBrains documents [Go to Symbol](https://plugins.jetbrains.com/docs/intellij/go-to-class-and-go-to-symbol.html) as a contributor that feeds the IDE with names and matching `NavigationItem` instances, typically PSI elements. The plugin contributes declaration elements, not synthetic wrappers around arbitrary text matches and not coverage occurrences. This keeps symbol search aligned with the IDE expectation that a search result names something that is actually declared somewhere in the project. +For IntelliJ's search and navigation facilities, the declaration index is the source of truth for `Go to Symbol` and `Search Everywhere`. JetBrains documents [Go to Symbol](https://plugins.jetbrains.com/docs/intellij/go-to-class-and-go-to-symbol.html) as a contributor that feeds the IDE with IDs and matching `NavigationItem` instances, typically PSI elements. The plugin contributes declaration elements, not synthetic wrappers around arbitrary text matches and not coverage occurrences. This keeps symbol search aligned with the IDE expectation that a search result names something that is actually declared somewhere in the project. -Coverage locations are still first-class data, but they belong in reference resolution and usage-style navigation. They are the places where the IDE should resolve from a usage to a declaration, and they are also the basis for `Go To Implementations` on a declared specification item. The same declaration index also feeds completion in `Covers:` sections and on the target side of likely source-code coverage tags, where the plugin ranks declared IDs by full-ID prefix, name-prefix, name-substring, and artifact-type prefix matches in that order. +Coverage locations are still first-class data, but they belong in reference resolution and usage-style navigation. They are the places where the IDE should resolve from a usage to a declaration, and they are also the basis for `Go To Implementations` on a declared specification item. The same declaration index also feeds completion in `Covers:` sections and on the target side of likely source-code coverage tags, where the plugin ranks declared IDs by full-ID prefix, middle-component prefix, middle-component substring, and artifact-type prefix matches in that order. ## Phased OFT Integration diff --git a/doc/system_requirements.md b/doc/system_requirements.md index 05fec3a..7655901 100644 --- a/doc/system_requirements.md +++ b/doc/system_requirements.md @@ -8,9 +8,9 @@ The IntelliJ plugin makes authoring OpenFastTrace documents easier in the enviro ## Notation -This document uses OpenFastTrace specification items to express product features, user requirements, scenarios, and design items. Each specification item has a unique identifier in the form `~~`. +This document uses OpenFastTrace specification items to express product features, user requirements, scenarios, and design items. Each specification item has a unique ID in the form `~~`. -In this document, feature items use the artifact type `feat`, user requirements use `req`, scenarios use `scn`, and design items use `dsn`. The item name describes the subject of the item in a project-wide unique form. The revision distinguishes semantically different versions of the same item. +In this document, feature items use the artifact type `feat`, user requirements use `req`, scenarios use `scn`, and design items use `dsn`. The title describes the subject of the item. The ID is the canonical reference used when one item points to another. The revision distinguishes semantically different versions of the same item. Informative text explains background, scope, and intent. Specification items define the normative content of the document. Relationships between items are expressed with OpenFastTrace keywords such as `Needs` and `Covers`. @@ -84,7 +84,7 @@ Needs: req ### Go to Specification Item `feat~go-to-specification-item~1` -The plugin lets users search specification items by name across the project and navigate from OpenFastTrace references in the editor. Users can select a matching item from the result list or invoke Go To on a specification reference or coverage-tag side and open the corresponding definition in the editor. +The plugin lets users search specification items by ID across the project and navigate from OpenFastTrace references in the editor. Users can select a matching item from the result list or invoke Go To on a specification reference or coverage-tag side and open the corresponding definition in the editor. Needs: req @@ -241,7 +241,7 @@ Needs: scn #### Open Specification Item from Coverage Tag Left Side `req~open-specification-item-from-coverage-tag-left-side~1` -The plugin resolves the covering OpenFastTrace specification item when a user invokes `Go To Declaration` on the left side of an OFT coverage tag in a supported file and opens that item's declaration in the specification document. If the left side omits the name and revision, the plugin resolves the effective ID by copying the missing parts from the covered ID on the right side of the arrow. +The plugin resolves the covering OpenFastTrace specification item when a user invokes `Go To Declaration` on the left side of an OFT coverage tag in a supported file and opens that item's declaration in the specification document. If the left side omits the middle component and revision, the plugin resolves the effective ID by copying the missing parts from the covered ID on the right side of the arrow. Covers: - `feat~go-to-specification-item~1` @@ -299,7 +299,7 @@ Needs: scn #### Provide OFT Scenario Live Template `req~provide-oft-scenario-live-template~1` -The bundled OpenFastTrace live-template group includes a scenario template for `scn` items. Users can insert a scenario skeleton with placeholders for the scenario title, item name, given-when-then text, and covered requirement. +The bundled OpenFastTrace live-template group includes a scenario template for `scn` items. Users can insert a scenario skeleton with placeholders for the scenario title, item ID, given-when-then text, and covered requirement. Covers: - `feat~oft-live-templates~1` @@ -313,7 +313,7 @@ The following requirements refine the OFT reference-completion feature into user #### Complete Specification Item IDs in Covers Section `req~complete-specification-item-ids-in-covers-section~1` -The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing an OFT item ID under `Covers:` in a supported specification document. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the item name, then by substring match against the item name, and finally by prefix match against the artifact type. +The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing an OFT item ID under `Covers:` in a supported specification document. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the middle component of the ID, then by substring match against the middle component of the ID, and finally by prefix match against the artifact type. Covers: - `feat~oft-reference-completion~1` @@ -323,7 +323,7 @@ Needs: scn #### Complete Specification Item IDs in Coverage Tag Target `req~complete-specification-item-ids-in-coverage-tag-target~1` -The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing the target side of a likely OFT coverage tag in a supported source-code comment. Coverage-tag target completion is available for the default file extensions supported by the upstream OpenFastTrace Tag Importer. The completion context requires a left-hand artifact type and an arrow before the caret so suggestions appear for coverage-tag targets instead of ordinary comment text. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the item name, then by substring match against the item name, and finally by prefix match against the artifact type. +The plugin suggests existing OpenFastTrace specification item IDs when a user invokes completion while editing the target side of a likely OFT coverage tag in a supported source-code comment. Coverage-tag target completion is available for the default file extensions supported by the upstream OpenFastTrace Tag Importer. The completion context requires a left-hand artifact type and an arrow before the caret so suggestions appear for coverage-tag targets instead of ordinary comment text. The suggestion list is ranked first by exact prefix match against the full ID, then by prefix match against the middle component of the ID, then by substring match against the middle component of the ID, and finally by prefix match against the artifact type. Covers: - `feat~oft-reference-completion~1` @@ -572,7 +572,7 @@ Needs: scn #### Sort Specification Items in Test Runner UI `req~sort-specification-items-in-test-runner-ui~1` -Within each source-file suite, the IntelliJ Test Runner UI result view sorts specification item entries by artifact type, then by the name part of the specification item ID, then by revision number. +Within each source-file suite, the IntelliJ Test Runner UI result view sorts specification item entries by artifact type, then by the middle component of the specification item ID, then by revision number. Covers: - `feat~oft-test-runner-trace-results~1` @@ -975,7 +975,7 @@ Needs: dsn **Given** a project contains the specification items `impl~openfasttrace_navigation_target~1` and `req~openfasttrace_navigation_target~1`, and a supported source file contains the OFT coverage tag `[impl->req~openfasttrace_navigation_target~1]` **When** a user invokes `Go To Declaration` on `impl` on the left side of the coverage tag -**Then** the editor opens `impl~openfasttrace_navigation_target~1` at its definition by copying the missing name and revision from the covered ID on the right side. +**Then** the editor opens `impl~openfasttrace_navigation_target~1` at its definition by copying the missing middle component and revision from the covered ID on the right side. Covers: - `req~open-specification-item-from-coverage-tag-left-side~1` @@ -1015,7 +1015,7 @@ The following scenarios describe completion support while editing OFT references **Given** a project contains declared OpenFastTrace specification items and a user edits a `Covers:` entry in a supported specification document **When** the user types a partial specification item ID and invokes completion -**Then** the IDE suggests existing declared specification item IDs from the project index and orders the suggestion list by full-ID prefix match, then name-prefix match, then name-substring match, and finally artifact-type prefix match +**Then** the IDE suggests existing declared specification item IDs from the project index and orders the suggestion list by full-ID prefix match, then middle-component prefix match, then middle-component substring match, and finally artifact-type prefix match Covers: - `req~complete-specification-item-ids-in-covers-section~1` @@ -1027,7 +1027,7 @@ Needs: dsn **Given** a project contains declared OpenFastTrace specification items and a user edits the target side of an OFT coverage tag candidate such as `[impl->dsn~openfasttrace]` in a comment of a file whose extension is supported by the upstream OpenFastTrace Tag Importer **When** the user invokes completion -**Then** the IDE suggests existing declared specification item IDs from the project index and orders the suggestion list by full-ID prefix match, then name-prefix match, then name-substring match, and finally artifact-type prefix match +**Then** the IDE suggests existing declared specification item IDs from the project index and orders the suggestion list by full-ID prefix match, then middle-component prefix match, then middle-component substring match, and finally artifact-type prefix match Covers: - `req~complete-specification-item-ids-in-coverage-tag-target~1` @@ -1131,7 +1131,7 @@ Needs: dsn **Given** the OpenFastTrace plugin is installed and a user edits an OFT specification document in a live-template context **When** the user expands the `scn` live template -**Then** the IDE inserts an OFT scenario skeleton with placeholders for the title, item name, `Given`, `When`, `Then`, and covered requirement +**Then** the IDE inserts an OFT scenario skeleton with placeholders for the title, item ID, `Given`, `When`, `Then`, and covered requirement Covers: - `req~provide-oft-scenario-live-template~1` @@ -1498,7 +1498,7 @@ Needs: dsn **Given** an `OpenFastTrace` run configuration uses the IntelliJ Test Runner UI result view and one source-file suite contains multiple specification items **When** the trace completes -**Then** the specification item entries in that source-file suite are ordered by artifact type, ID name part, and revision number +**Then** the specification item entries in that source-file suite are ordered by artifact type, the middle component of the ID, and revision number Covers: - `req~sort-specification-items-in-test-runner-ui~1` diff --git a/doc/user_guide.md b/doc/user_guide.md index 918ae94..16f543d 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -190,7 +190,7 @@ Wait for IntelliJ indexing to finish. Symbol search and completion depend on the ### Navigation Does Not Jump To The Expected Item -Check the item ID spelling, artifact type, name, and revision. OFT revisions are part of the ID, so `req~example~1` and `req~example~2` are different items. +Check the item ID spelling, artifact type, middle component, and revision. OFT revisions are part of the ID, so `req~example~1` and `req~example~2` are different items. Check that the declaration exists in the opened project, not only in another checkout or a generated report. From aa0033ca2b3e11ef8b143295b654cdc321a61d69 Mon Sep 17 00:00:00 2001 From: redcatbear Date: Thu, 6 Aug 2026 07:55:40 +0200 Subject: [PATCH 6/6] #66: Renamed "name" to "id" in templates. --- .../resources/liveTemplates/OpenFastTrace.xml | 36 +++++++++---------- .../templates/OftLiveTemplatesTest.java | 4 +-- 2 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/main/resources/liveTemplates/OpenFastTrace.xml b/src/main/resources/liveTemplates/OpenFastTrace.xml index ae113c5..c08b0fd 100644 --- a/src/main/resources/liveTemplates/OpenFastTrace.xml +++ b/src/main/resources/liveTemplates/OpenFastTrace.xml @@ -9,13 +9,13 @@