Version 1.7.0

.github/skills/coding-style.md

@@ -0,0 +1,24 @@
+---
+description: Use when writing or reviewing Python, JavaScript, HTML, or CSS code in this project.
+---
+
+# Coding Style
+
+## Python
+- Targets Python 3.8+.
+- Keep functions small, use clear exceptions, and follow existing snake_case naming.
+
+## JavaScript
+- Uses modern syntax (const/let, arrow functions) and camelCase naming.
+- Keep functions small to match existing modules.
+- When adding new JS modules, update imports so `DependencyProcessor` can resolve module order; all dashboard JS is bundled into one script at generation time.
+
+## HTML
+- Keep markup semantic and accessible; keep it minimal and label form controls in templates.
+
+## CSS
+- Use existing class conventions (Bootstrap/Datatables) and keep selectors shallow.
+- Prefer CSS variables for theme values.
+
+## General
+- Update docs in `docs/` when user-facing behavior changes.

.github/skills/conventions-and-gotchas.md

@@ -0,0 +1,13 @@
+---
+description: Use when modifying core logic, adding features, or debugging issues related to runs, logs, versions, database backends, or offline mode.
+---
+
+# Project Conventions and Gotchas
+
+- Run identity is `run_start` from output.xml; duplicates are rejected. `run_alias` defaults to file name and may be auto-adjusted to avoid collisions.
+- If you add log support, log names must mirror output names (output-XYZ.xml -> log-XYZ.html) for `uselogs` and server log linking.
+- `--projectversion` and `version_` tags are mutually exclusive; version tags are parsed from output tags in `RobotDashboard._process_single_output`.
+- Custom DB backends are supported via `--databaseclass`; the module must expose a `DatabaseProcessor` class compatible with `AbstractDatabaseProcessor`.
+- Offline mode is handled by embedding dependency content into the HTML; do not assume external CDN availability when `--offlinedependencies` is used.
+- Data flow is always: parse outputs -> DB -> HTML. Reuse `RobotDashboard` methods instead of reimplementing this flow.
+- Template changes should keep placeholder keys intact (e.g. `placeholder_runs`, `placeholder_css`) because replacements are string-based.

.github/skills/dashboard.md

@@ -0,0 +1,66 @@
+---
+description: Use when working on dashboard pages, tabs, graphs, Chart.js configurations, or the HTML template.
+---
+
+# Dashboard Pages and Charts
+
+## Pages / Tabs
+
+### Overview Page
+High-level summary of all test runs. Shows the latest results per project with pass/fail/skip counts, recent trends, and overall performance. Special sections: "Latest Runs" (latest run per project) and "Total Stats" (aggregated stats by project/tag). Projects can be grouped by custom `project_` tags.
+
+### Dashboard Page
+Interactive visualizations across four sections — Runs, Suites, Tests, Keywords. Layout is fully customizable via drag-and-drop. Most graphs support multiple display modes. Graphs can be expanded to fullscreen (increases data limits, e.g. Top 10 → Top 50).
+
+### Compare Page
+Side-by-side comparison of up to four test runs with statistics, charts (bar, radar, timeline), and summaries to identify regressions or improvements.
+
+### Tables Page
+Raw database data in DataTables for runs, suites, tests, and keywords. Useful for debugging and ad-hoc analysis.
+
+## Chart.js Architecture
+
+### Central Config: `graph_config.js`
+`get_graph_config(graphType, graphData, graphTitle, xTitle, yTitle)` is the single factory function that returns a complete Chart.js config object. All graphs route through it.
+
+### Supported Chart Types
+| Type | Chart.js `type` | Usage |
+|---|---|---|
+| `line` | `line` | Time-series trends (statistics, durations over time) |
+| `bar` | `bar` | Stacked bars (statistics amounts, durations, rankings) |
+| `timeline` | `bar` (indexAxis: y) | Horizontal bars for timeline views (test status, most-failed) |
+| `boxplot` | `boxplot` | Duration deviation / flaky test detection |
+| `donut` | `doughnut` | Run/suite distribution charts |
+| `heatmap` | `matrix` | Test execution activity by hour/minute per weekday |
+| `radar` | `radar` | Compare suite durations across runs |
+
+### Chart Factory: `chart_factory.js`
+- `create_chart(chartId, buildConfigFn)` — destroys existing chart, creates new `Chart` instance, attaches log-click handler.
+- `update_chart(chartId, buildConfigFn)` — updates data/options in-place for smooth transitions; falls back to `create_chart` if the chart doesn't exist yet.
+
+### Graph Data Modules (in `js/graph_data/`)
+Each module transforms filtered DB data into Chart.js-compatible datasets:
+- `statistics.js` — pass/fail/skip counts and percentages for runs, suites, tests, keywords.
+- `duration.js` — elapsed time data (total, average, min, max).
+- `duration_deviation.js` — boxplot quartile calculations for test duration spread.
+- `donut.js` — aggregated donut/doughnut data, including folder-level drill-down for suites.
+- `heatmap.js` — matrix data (day × hour/minute) for execution activity.
+- `messages.js` — failure message frequency data.
+- `tooltip_helpers.js` — rich tooltip metadata (duration, status, message).
+- `helpers.js` — shared utilities (height updates, data exclusions).
+
+### Graph Creation Modules (in `js/graph_creation/`)
+Each section has its own module that wires data modules to chart factory calls:
+- `overview.js` — Overview page project cards and grouped stats.
+- `run.js` — Run statistics, donut, duration, heatmap, stats graphs.
+- `suite.js` — Suite folder donut, statistics, duration, most-failed, most-time-consuming.
+- `test.js` — Test statistics (timeline), duration, deviation (boxplot), messages, most-flaky, most-failed, most-time-consuming.
+- `keyword.js` — Keyword statistics, times-run, duration variants, most-failed, most-time-consuming, most-used.
+- `compare.js` — Compare page statistics bar, radar, and timeline graphs.
+
+### Common Patterns
+- All graphs use the `settings` object (`js/variables/settings.js`) for display preferences (animation, graph types, date labels, legends, axis titles).
+- Graph type switching (e.g. bar ↔ line ↔ percentages) is driven by `settings.graphTypes.<graphName>GraphType`.
+- Fullscreen mode changes data limits (e.g. top-N from 10/30 to 50/100) via `inFullscreen` and `inFullscreenGraph` globals.
+- Clicking chart data points opens the corresponding Robot Framework log via `open_log_file` / `open_log_from_label`.
+- Chart color constants (passed/failed/skipped backgrounds and borders) live in `js/variables/chartconfig.js`.

.github/skills/project-architecture.md

@@ -0,0 +1,21 @@
+---
+description: Use when working on project structure, understanding how components connect, or navigating the codebase.
+---
+
+# Project Architecture
+
+## Big Picture
+- CLI entry point is `robotdashboard` -> `robotframework_dashboard.main:main`, which orchestrates: init DB, process outputs, list runs, remove runs, generate HTML.
+- Core workflow: output.xml -> `OutputProcessor` (Robot Result Visitor API) -> SQLite DB (`DatabaseProcessor`) -> HTML dashboard via `DashboardGenerator`.
+- Dashboard HTML is a template with placeholders replaced at build time; data payloads are zlib-compressed and base64-encoded strings embedded in HTML.
+- JS/CSS are merged and inlined by `DependencyProcessor` (topological import resolution for JS modules) and can be switched to CDN or fully offline assets.
+- Optional server mode uses FastAPI to host admin + dashboard + API endpoints; the server uses the same `RobotDashboard` pipeline.
+
+## Key Directories and Files
+- CLI + orchestration: `robotframework_dashboard/main.py`, `robotframework_dashboard/robotdashboard.py`, `robotframework_dashboard/arguments.py`.
+- Data extraction: `robotframework_dashboard/processors.py` (visitors for runs/suites/tests/keywords).
+- Database: `robotframework_dashboard/database.py` + schema in `robotframework_dashboard/queries.py`.
+- HTML templates: `robotframework_dashboard/templates/dashboard.html` and `robotframework_dashboard/templates/admin.html` (placeholders are replaced in `dashboard.py`).
+- Dependency inlining and CDN/offline switching: `robotframework_dashboard/dependencies.py`.
+- Server: `robotframework_dashboard/server.py` (FastAPI endpoints + admin UI).
+- Dashboard JS entry: `robotframework_dashboard/js/main.js` (imports modular setup files).

.github/skills/workflows.md

@@ -0,0 +1,16 @@
+---
+description: Use when running the CLI, starting the server, or building/previewing the documentation site.
+---
+
+# Common Workflows
+
+## CLI
+- Usage and flags: see `docs/basic-command-line-interface-cli.md` (output import, tags, remove runs, dashboard generation).
+
+## Server Mode
+- Start with `robotdashboard --server` or `-s host:port:user:pass`.
+- See `docs/dashboard-server.md` for endpoints and admin UI behavior.
+
+## Documentation Site
+- Run `npm run docs:dev` for local dev, `npm run docs:build` to build, `npm run docs:preview` to preview.
+- Docs use VitePress and live in `docs/`.

.gitignore

@@ -13,6 +13,7 @@ index.txt
 .pabotsuitenames
 *.db
 *.vscode
+.github/*.md
 
 # docs entries
 node_modules

README.md

@@ -62,6 +62,7 @@ For detailed usage instructions, advanced examples, and full documentation, visi
 - 🖥️ [**Dashboard Server**](https://marketsquare.github.io/robotframework-dashboard/dashboard-server.html) - Host the dashboard for multi-user access, programmatic updates, and remote server integration.
 - 🗄️ [**Custom Database Class**](https://marketsquare.github.io/robotframework-dashboard/custom-database-class.html) - Extend or replace the default database backend to suit your storage needs, including SQLite, MySQL, or custom implementations.
 - 🔔 [**Listener Integration**](https://marketsquare.github.io/robotframework-dashboard/listener-integration.html) - Use a listener to automatically push test results to the dashboard for every executed run, integrating seamlessly into CI/CD pipelines.
+- 📂 [**Log Linking**](https://marketsquare.github.io/robotframework-dashboard/log-linking.html) - Enable clickable log navigation from dashboard graphs, covering file naming conventions, local and server usage, and remote log uploads.
 
 
 ## 🛠️ Contributions

atest/resources/cli_output/version.txt

@@ -6,4 +6,4 @@
 |_| \_\\___/|____/ \___/ |_| |____/_/   \_|____/|_| |_|____/ \___/_/   \_|_| \_|____/ 
 
 ======================================================================================
-Robotdashboard 1.6.2
+Robotdashboard 1.7.0

docs/.vitepress/config.mts

@@ -5,6 +5,11 @@ import { resolve } from 'node:path';
 const python_svg = readFileSync("docs/public/python.svg", "utf-8");
 const slack_svg = readFileSync("docs/public/slack.svg", "utf-8");
 
+// Read version from version.py
+const versionFile = readFileSync("robotframework_dashboard/version.py", "utf-8");
+const versionMatch = versionFile.match(/Robotdashboard\s+([\d.]+)/);
+const version = versionMatch ? versionMatch[1] : "unknown";
+
 export default defineConfig({
   title: "RobotDashboard",
   description: "Robot Framework Dashboard and Result Database command line tool",
@@ -53,7 +58,13 @@ export default defineConfig({
     nav: [
       { text: 'Home', link: '/' },
       { text: 'Documentation', link: '/getting-started.md' },
-      { text: 'Example Dashboard', link: '/example/robot_dashboard.html', target: '_self' }
+      { text: 'Example Dashboard', link: '/example/robot_dashboard.html', target: '_self' },
+      {
+        text: `v${version}`,
+        items: [
+          { text: 'Changelog', link: 'https://github.com/marketsquare/robotframework-dashboard/releases' },
+        ]
+      }
     ],
     sidebar: [
       {
@@ -86,6 +97,7 @@ export default defineConfig({
           { text: '🖥️ Dashboard Server', link: '/dashboard-server.md' },
           { text: '🗄️ Custom Database Class', link: '/custom-database-class.md' },
           { text: '🔔 Listener Integration', link: '/listener-integration.md' },
+          { text: '📂 Log Linking', link: '/log-linking.md' },
         ]
       },
         { text: '🤝 Contributions', link: '/contributions.md' }

docs/.vitepress/theme/vars.css

@@ -114,6 +114,12 @@ html.dark table {
   background-color: var(--vp-c-content-bg);
 }
 
+/* Ensure tables always fill the available width */
+.vp-doc table {
+  width: 100%;
+  display: table;
+}
+
 /* Table header row */
 html.dark table th {
   background-color: #0d1b3f; /* slightly darker than table rows */

docs/advanced-cli-examples.md

@@ -56,6 +56,13 @@ robotdashboard -o output.xml:project_custom_name
 robotdashboard -f ./results:project_1
 ```
 
+When using `project_` tags:
+- Each unique `project_` tag creates a **separate project section** on the Overview page
+- The Overview will group and display runs under the tag name instead of the run name
+- You can toggle between project-by-name and project-by-tag views in [Settings - Overview Tab](/settings#overview-settings-overview-tab)
+- The `project_` prefix text can be shown or hidden using the **Prefixes** toggle in Settings
+- Multiple `project_` tags on different outputs allow comparing different projects side by side on the Overview page
+
 ## Aliases for Clean Dashboard Identification
 
 Aliases help replace long timestamps with clean, readable names. They also significantly improve clarity in comparison views and general dashboard readability.
@@ -94,45 +101,15 @@ robotdashboard -o output_my_alias2.xml
 robotdashboard -f ./nightly_runs    
 ```
 
-## Advanced UseLogs Information
-
-Enable interactive log navigation directly from dashboard graphs.
-
-By default, graphs are not clickable, so opening log files must be done manually.
-When UseLogs is enabled, you can open log files directly from run, suite, test, and keyword graphs.
-
-### How it works
-
-- Graph items become clickable when they point to exactly one run, suite, test, or keyword.
-- If a graph point refers to multiple runs or multiple suites/tests across different runs, no log file will open.
-- For logs to open correctly, the corresponding log.html file must exist in the same directory as the output.xml.
-- The expected log filename is automatically derived by:
-    - Replacing `output` with `log`
-    - Replacing `.xml` with `.html`
-- When clicking a suite or test node that maps to exactly one suite or test, the log file will open automatically at the correct suite or test location.
-- For server behavior and storing logs on the server, see [Dashboard Server](/dashboard-server.md).
+## Log Linking
 
-### Turning on clickable logs
+The `--uselogs` (`-u`) flag enables interactive log navigation directly from dashboard graphs. When enabled, clicking on a graph element opens the corresponding `log.html` file.
 
 ```bash
 robotdashboard -u true
 ```
-Expected filename behavior is applied when clicking graphs
-```bash
-robotdashboard -u true -o path/to/output12345.xml
-```
-Log file that should exist: path/to/log12345.html
-```bash
-robotdashboard -u true -o some_test_output_file.xml
-```
-Log file that should exist: some_test_log_file.html
-
-#### Reports
-Robotframework report .htmls can be accessed through the log html:  
-- Name the report html the same as the log html, following the logic explained above
-    - Ensure the log and report are in the same directory
-    - Make sure the filenames match, except `log` being `report`
-- Then, the link to the report inside the log html at the top right corner should work
+
+For the full guide covering file naming conventions, local vs. server usage, and remote log uploads, see the dedicated [Log Linking](/log-linking.md) page.
 
 ## Message Config Details
 

docs/basic-command-line-interface-cli.md

@@ -80,7 +80,12 @@ If you want to supply versions for each output, use:
 robotdashboard -o output.xml:version_1.2.1 -o output2.xml:version_2.3.4
 robotdashboard -f ./results:version_1.1 ./results2:version_2.3.4
 ```
---projectversion and version_ are mutually exclusive
+
+::: warning Version Constraints
+- `--projectversion` and `version_` tags are **mutually exclusive** — using both will produce an error.
+- Each output file can have at most **one** `version_` tag. Multiple `version_` tags on the same output will produce an error.
+:::
+
 > Added in RobotDashboard v1.3.0  
 > version_ tag support added in v1.4.0
 
@@ -137,14 +142,14 @@ robotdashboard --quantity 50
 
 ## Advanced Options
 
-### Enable clickable log files in the dashboard
+### Enable Log Linking in the dashboard
 ```bash
 robotdashboard -u true  
 robotdashboard --uselogs True  
 ```
 - Optional: `-u` or `--uselogs` enables clickable graphs in the dashboard that open corresponding log.html files.  
 - Requirements: log files must be in the same folder as their respective output.xml files, with `output` replaced by `log` and `.xml` replaced by `.html`.
-- See [Advanced CLI & Examples](/advanced-cli-examples#advanced-uselogs-information) for more details regarding the log linking!
+- See [Log Linking](/log-linking.md) for the full guide on file naming, local vs. server usage, and remote log uploads.
 
 ### Add messages config for bundling test messages
 ```bash

docs/custom-database-class.md

@@ -69,7 +69,7 @@ Your custom database class must implement the following methods:
 
 ---
 
-### `insert_output_data(self, output_data: dict, tags: list, run_alias: str, path: Path)`
+### `insert_output_data(self, output_data: dict, tags: list, run_alias: str, path: Path, project_version: str)`
 This method handles the actual insertion of all run-related data.
 
 You must process:
@@ -78,6 +78,7 @@ You must process:
 - `tags` — list of tags associated with the run  
 - `run_alias` — a human-friendly alias chosen by the user or system  
 - `path` — path to `output.xml`  
+- `project_version` — version string associated with this run (from `--projectversion` or `version_` tags), may be `None`  
 
 You can inspect the example implementations for the exact structure of `output_data` and how each record is inserted.
 
@@ -102,7 +103,8 @@ Must return **all data** in this dictionary format:
       "tags": "",
       "run_alias": "output-20241013-223319",
       "path": "results/output-20241013-223319.xml",
-      "metadata": "[]"
+      "metadata": "[]",
+      "project_version": "1.2.1"
     },
     {...etc}
   ],
@@ -177,15 +179,24 @@ Each type must be a list of dictionaries matching what RobotDashboard expects.
 ### `remove_runs(self, remove_runs: list)`
 `remove_runs` may contain any of the following:
 
-- `index=<n>`  
-- `run_start=<timestamp>`  
-- `alias=<alias>`  
-- `tag=<tag>`  
+- `index=<n>` — remove by index (supports ranges with `:` and lists with `;`)  
+- `run_start=<timestamp>` — remove by exact run_start timestamp  
+- `alias=<alias>` — remove by run alias  
+- `tag=<tag>` — remove all runs matching the given tag  
+- `limit=<n>` — keep only the N most recent runs, removing all older ones  
 
 You must correctly interpret and remove runs accordingly. If you only want to support removing based on run_start or index you could only implement those usages.
 
 ---
 
+### *(Optional)* `vacuum_database(self)`
+Called after run removal when the `--novacuum` flag is **not** set.  
+In the default SQLite implementation, this runs `VACUUM` to reclaim disk space after deletions.
+
+If your database backend does not need compaction, you can safely omit this method or implement it as a no-op. Make sure you then provide the --novacuum flag when running the dashboard to avoid errors.
+
+---
+
 ### *(Optional)* `update_output_path(self, log_path: str)`
 This is only required when using: