From b6eefaf3a0f71e04bd7690e9361643c90c2fdf57 Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Fri, 18 Sep 2026 16:20:06 -0700 Subject: [PATCH 1/6] migrated rohd_source_navigator to packages, prepped for publication --- CHANGELOG.md | 5 + analysis_options.yaml | 1 + doc/releases.md | 36 ++++++-- packages/rohd_devtools_widgets/pubspec.yaml | 2 +- packages/rohd_source_navigator/CHANGELOG.md | 9 ++ .../rohd_source_navigator}/LICENSE | 0 packages/rohd_source_navigator/README.md | 91 +++++++++++++++++++ .../lib/dtd_service.dart | 0 .../rohd_source_navigator}/lib/flc_data.dart | 0 .../lib/rohd_source_navigator.dart | 0 .../lib/source_navigator.dart | 0 .../rohd_source_navigator}/pubspec.yaml | 4 +- .../test/flc_data_test.dart | 0 rohd-multipackage.code-workspace | 4 + rohd_extension/dart/README.md | 15 --- test/prepare_release_metadata_test.dart | 22 +++++ tool/check_release.sh | 13 +-- tool/prepare_release.sh | 21 +++-- tool/prepare_release_metadata.dart | 1 + tool/test/check_release_test.sh | 24 +++-- tool/test/prepare_release_test.sh | 39 +++++--- 21 files changed, 228 insertions(+), 59 deletions(-) create mode 100644 packages/rohd_source_navigator/CHANGELOG.md rename {rohd_extension/dart => packages/rohd_source_navigator}/LICENSE (100%) create mode 100644 packages/rohd_source_navigator/README.md rename {rohd_extension/dart => packages/rohd_source_navigator}/lib/dtd_service.dart (100%) rename {rohd_extension/dart => packages/rohd_source_navigator}/lib/flc_data.dart (100%) rename {rohd_extension/dart => packages/rohd_source_navigator}/lib/rohd_source_navigator.dart (100%) rename {rohd_extension/dart => packages/rohd_source_navigator}/lib/source_navigator.dart (100%) rename {rohd_extension/dart => packages/rohd_source_navigator}/pubspec.yaml (64%) rename {rohd_extension/dart => packages/rohd_source_navigator}/test/flc_data_test.dart (100%) delete mode 100644 rohd_extension/dart/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5dabd8bfb..5e77c5cf1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,9 @@ +## Next Release + +- Exposed the shared `rohd_source_navigator` code used by `rohd-schematic-viewer` as a standalone pub.dev package. +- Corrected the ROHD dependency in `rohd_devtools_widgets` from `^0.6.9` to `^0.6.11` to reflect the minimum compatible ROHD version. + ## 0.6.11 - Added `NetlistSynthesizer` for generating JSON netlists, with configurable synthesis passes, validation, and hierarchy support (). diff --git a/analysis_options.yaml b/analysis_options.yaml index 63d394a99..54df7e247 100644 --- a/analysis_options.yaml +++ b/analysis_options.yaml @@ -10,6 +10,7 @@ analyzer: - doc/tutorials/chapter_9/rohd_vf_example - packages/rohd_devtools_widgets - packages/rohd_hierarchy + - packages/rohd_source_navigator - packages/rohd_waveform - reviews/** - rohd_devtools_extension diff --git a/doc/releases.md b/doc/releases.md index dedb27cd9..abf3d5634 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -18,13 +18,15 @@ released, not a repository-wide version. | [rohd_hierarchy](../packages/rohd_hierarchy) | Shared hierarchy models, addressing, adapters, and search. | Independent pub.dev package; `dart pub publish` from its directory. | Its own `pubspec.yaml`. | Tag `rohd_hierarchy-v`; release **rohd_hierarchy v**. | | [rohd_waveform](../packages/rohd_waveform) | Shared waveform models and data services. | Independent pub.dev package; `dart pub publish` from its directory. | Its own `pubspec.yaml`. | Tag `rohd_waveform-v`; release **rohd_waveform v**. | | [rohd_devtools_widgets](../packages/rohd_devtools_widgets) | Reusable Flutter controls and utilities for debug viewers. | Independent pub.dev package; `flutter pub publish` from its directory. | Its own `pubspec.yaml`. | Tag `rohd_devtools_widgets-v`; release **rohd_devtools_widgets v**. | +| [rohd_source_navigator](../packages/rohd_source_navigator) | Shared FLC data models and source-navigation utilities for debug viewers. | Independent pub.dev package; `dart pub publish` from its directory. | Its own `pubspec.yaml`. | Tag `rohd_source_navigator-v`; release **rohd_source_navigator v**. | | [ROHD DevTools application](../rohd_devtools_extension) | Interactive hardware debug UI embedded in Dart DevTools. | Flutter web build produced by CI and bundled under `extension/devtools` in the ROHD pub.dev package; the application itself is not published to pub.dev. | Tracked by the containing ROHD release and the build's source/artifact commits, not an independent application release version. | Included in ROHD's tag and release notes; no separate release tag. The `artifacts` branch holds CI output, not an immutable release. | | [ROHD VS Code extension](../rohd_extension) | Editor snippets, completions, and cross-probe source navigation. | GitHub Actions builds and attaches a VSIX when its GitHub release is published; a maintainer tests and publishes that VSIX to the VS Code Marketplace separately. | `rohd_extension/package.json`. | Tag `rohd-vscode-v`; release `ROHD VS Code v`, with `rohd-vscode-v.vsix` attached automatically. | -The internal Dart source-navigation port in `rohd_extension/dart` uses -`publish_to: none` and has no independent release or tag. The VS Code extension -compiles its TypeScript implementation, not the Dart port. Tutorial applications -are also not independently released packages. +The source-navigation library lives in `packages/rohd_source_navigator`, alongside +the other independently published libraries. Git dependencies following the move +must use the new package path; older pinned commits retain `rohd_extension/dart`. +The VS Code extension still compiles its separate TypeScript implementation. +Tutorial applications are not independently released packages. ## GitHub Strategy @@ -91,13 +93,15 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet `Check rohd_devtools_widgets` jobs for dependency resolution, formatting, fatal-info analysis, and package tests. These run alongside the root checks and DevTools app job; documentation deployment waits for all of them. + Source navigator is not included in that matrix; run its local checks with + `tool/prepare_release.sh --run-tests rohd_source_navigator`. Preparation skips local test suites by default and does not query GitHub or verify CI status. Use `--run-tests` to repeat selected package suites locally. ROHD's local tests require Icarus Verilog; Verilator is required in CI and when `ROHD_REQUIRE_VERILATOR=1`. 5. Run `tool/prepare_release.sh [--run-tests] [package ...]` on the preparation - branch from the repository root. No package names selects all four; explicit + branch from the repository root. No package names selects all five; explicit names select only those packages. Versions come from their manifests, not command-line arguments. It validates selected metadata before making changes, fetches `main` from `intel/rohd`, and requires that commit to be an ancestor @@ -115,9 +119,10 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet commit, tag, push, or upload anything. If a guard fails, incorporate the latest `main` or wait for its artifact workflow as appropriate, then rerun preparation. 6. To inspect archives without preparing metadata, run - `tool/check_release.sh [package ...]`. Like preparation, it defaults to all four + `tool/check_release.sh [package ...]`. Like preparation, it defaults to all five packages and accepts explicit names: `rohd`, `rohd_hierarchy`, `rohd_waveform`, - and `rohd_devtools_widgets`. Each uses its existing version. The helper runs + `rohd_devtools_widgets`, and `rohd_source_navigator`. Each uses its existing + version. The helper runs `dart pub publish --dry-run` in each selected Dart package directory or `flutter pub publish --dry-run` for widgets. Review warnings, included files, and compressed archive sizes. For ROHD, first prepare @@ -130,7 +135,7 @@ Preparation runs the following checks before invoking `tool/check_release.sh`: | Selected Package | Default Checks | Added With `--run-tests` | | --- | --- | --- | | `rohd` | `tool/run_checks.sh --skip-tests`: dependencies, formatting, analysis, API docs, and temporary-file checks; then `tool/package_vscode.sh` compiles and packages a temporary VSIX. | Simulator prerequisites and ROHD tests via `tool/run_checks.sh`. | -| `rohd_hierarchy`, `rohd_waveform` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`. | `dart test` in each selected package. | +| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`. | `dart test` in each selected package. | | `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`. | `flutter test` in the widgets package. | Artifact provenance verification and the DevTools installation smoke test always @@ -155,10 +160,10 @@ separate DevTools application remain a separate step when its shared widgets cha Preparation examples (choose one): ```sh -# All four packages, using each manifest's version; rely on CI for test suites: +# All five packages, using each manifest's version; rely on CI for test suites: tool/prepare_release.sh -# All four packages, also running their test suites locally: +# All five packages, also running their test suites locally: tool/prepare_release.sh --run-tests # ROHD only: @@ -172,6 +177,9 @@ tool/prepare_release.sh rohd rohd_hierarchy rohd_waveform # Only hierarchy and waveform: tool/prepare_release.sh rohd_hierarchy rohd_waveform + +# Only source navigator: +tool/prepare_release.sh rohd_source_navigator ``` Preparation requires Dart for YAML metadata parsing using the root package's @@ -195,6 +203,7 @@ the selected dry runs: tool/check_release.sh --validate-only tool/check_release.sh --validate-only rohd_hierarchy rohd_waveform rohd_devtools_widgets tool/check_release.sh rohd_hierarchy rohd_waveform rohd_devtools_widgets +tool/check_release.sh rohd_source_navigator ``` `--validate-only` checks package names, manifest presence, and SDK availability. @@ -237,6 +246,13 @@ dependencies determine ordering only when the required versions have not yet been published. Sharing a repository or source commit does not require a coordinated release. +`rohd_source_navigator` has only hosted Dart dependencies and can be published +independently of ROHD and the Flutter packages. Once its version is available on +pub.dev, consumers such as the ROHD Schematic Viewer can replace their Git +dependency with `rohd_source_navigator: ^0.1.0` and remove any Git override for +that package. Existing Dart imports remain unchanged. See the +[package README](../packages/rohd_source_navigator/README.md) for migration details. + For each package, wait until its required dependencies are available on pub.dev, then validate from a clean disposable checkout of the release commit without local dependency overrides or reused path-based lockfiles. Remove that checkout's diff --git a/packages/rohd_devtools_widgets/pubspec.yaml b/packages/rohd_devtools_widgets/pubspec.yaml index 952b02313..1da9d6820 100644 --- a/packages/rohd_devtools_widgets/pubspec.yaml +++ b/packages/rohd_devtools_widgets/pubspec.yaml @@ -11,7 +11,7 @@ dependencies: cupertino_ui: '>=1.0.0 <1.1.0' flutter: {sdk: flutter} material_ui: '>=1.1.0 <1.3.0' - rohd: ^0.6.9 + rohd: ^0.6.11 rohd_hierarchy: ^0.1.0 web: ^1.0.0 dev_dependencies: diff --git a/packages/rohd_source_navigator/CHANGELOG.md b/packages/rohd_source_navigator/CHANGELOG.md new file mode 100644 index 000000000..8a1fd5006 --- /dev/null +++ b/packages/rohd_source_navigator/CHANGELOG.md @@ -0,0 +1,9 @@ +## 0.1.0 + +- Prepare the existing ROHD source-navigation library for independent pub.dev + distribution, including FLC parsing, source frames, path utilities, frame + cycling, and DTD integration. +- Preserve the public imports and implementation previously consumed through + a Git dependency. +- Move the package to `packages/rohd_source_navigator`, alongside the other + independently published ROHD libraries. diff --git a/rohd_extension/dart/LICENSE b/packages/rohd_source_navigator/LICENSE similarity index 100% rename from rohd_extension/dart/LICENSE rename to packages/rohd_source_navigator/LICENSE diff --git a/packages/rohd_source_navigator/README.md b/packages/rohd_source_navigator/README.md new file mode 100644 index 000000000..d0675064a --- /dev/null +++ b/packages/rohd_source_navigator/README.md @@ -0,0 +1,91 @@ +# rohd_source_navigator + +Shared Dart source-navigation models and utilities for ROHD debug tools, +including the [ROHD Schematic Viewer](https://github.com/intel/rohd-schematic-viewer). + +## Installation + +```sh +dart pub add rohd_source_navigator +``` + +For Flutter applications, use `flutter pub add rohd_source_navigator`. + +## API + +- `FlcData`, `FlcEntry`, and `FlcFrame`: parse and look up file/line/column + traces from v5/v6 FLC hierarchy JSON or embedded netlist trace attributes. +- `SourceFrame` and `FrameCycler`: represent source locations and cycle through + a selection's frames. +- `normalizePath` and `resolveCandidatePaths`: prepare source paths for a + host application's file resolution. +- `DtdService` and request encoding helpers: source-navigation communication + for Dart Tooling Daemon integrations. + +Import the complete API: + +```dart +import 'package:rohd_source_navigator/rohd_source_navigator.dart'; +``` + +The existing focused imports remain supported: + +```dart +import 'package:rohd_source_navigator/flc_data.dart'; +import 'package:rohd_source_navigator/source_navigator.dart'; +import 'package:rohd_source_navigator/dtd_service.dart'; +``` + +For example, look up a signal's source location: + +```dart +import 'package:rohd_source_navigator/flc_data.dart'; + +void main() { + final data = FlcData.fromJson({ + 'version': 5, + 'files': ['lib/top.dart'], + 'modules': { + 'Top': { + 'tree': [ + ['0:42:5', 'result'], + ], + }, + }, + }); + + final frames = data.lookupSignal('Top', 'result'); + print(frames?.first); // lib/top.dart:42:5 [rohd] +} +``` + +This is a Dart library, not an editor extension. The +[ROHD VS Code extension](https://github.com/intel/rohd/tree/main/rohd_extension) +continues to use its separate TypeScript implementation; installing this +package does not install or activate that extension. + +## Migrating from a Git dependency + +Once version 0.1.0 is available on pub.dev, replace the Git dependency with: + +```yaml +dependencies: + rohd_source_navigator: ^0.1.0 +``` + +Also remove any Git or path entry for `rohd_source_navigator` from +`dependency_overrides` or `pubspec_overrides.yaml`; otherwise Pub will continue +using that override instead of the hosted package. Run `dart pub get` (or +`flutter pub get`) to update the lockfile. Existing Dart imports do not change. + +If continuing to use a Git dependency at a commit containing the package move, +change its `path` from `rohd_extension/dart` to +`packages/rohd_source_navigator`. Dependencies pinned to older commits or tags +keep their original path. + +## Development + +The package lives in `packages/rohd_source_navigator` in the ROHD repository. Run +`dart pub get`, `dart analyze`, and `dart test` from that directory. +Use `dart pub publish --dry-run` there to inspect the publication archive, or +`tool/check_release.sh rohd_source_navigator` from the repository root. diff --git a/rohd_extension/dart/lib/dtd_service.dart b/packages/rohd_source_navigator/lib/dtd_service.dart similarity index 100% rename from rohd_extension/dart/lib/dtd_service.dart rename to packages/rohd_source_navigator/lib/dtd_service.dart diff --git a/rohd_extension/dart/lib/flc_data.dart b/packages/rohd_source_navigator/lib/flc_data.dart similarity index 100% rename from rohd_extension/dart/lib/flc_data.dart rename to packages/rohd_source_navigator/lib/flc_data.dart diff --git a/rohd_extension/dart/lib/rohd_source_navigator.dart b/packages/rohd_source_navigator/lib/rohd_source_navigator.dart similarity index 100% rename from rohd_extension/dart/lib/rohd_source_navigator.dart rename to packages/rohd_source_navigator/lib/rohd_source_navigator.dart diff --git a/rohd_extension/dart/lib/source_navigator.dart b/packages/rohd_source_navigator/lib/source_navigator.dart similarity index 100% rename from rohd_extension/dart/lib/source_navigator.dart rename to packages/rohd_source_navigator/lib/source_navigator.dart diff --git a/rohd_extension/dart/pubspec.yaml b/packages/rohd_source_navigator/pubspec.yaml similarity index 64% rename from rohd_extension/dart/pubspec.yaml rename to packages/rohd_source_navigator/pubspec.yaml index a91365ac2..de739c070 100644 --- a/rohd_extension/dart/pubspec.yaml +++ b/packages/rohd_source_navigator/pubspec.yaml @@ -3,7 +3,9 @@ description: > Dart implementation of the ROHD source navigator — path normalisation, frame cycling, and DTD service for cross-probe source navigation. version: 0.1.0 -publish_to: none +homepage: https://intel.github.io/rohd-website/ +repository: https://github.com/intel/rohd/tree/main/packages/rohd_source_navigator +issue_tracker: https://github.com/intel/rohd/issues environment: sdk: ^3.0.0 diff --git a/rohd_extension/dart/test/flc_data_test.dart b/packages/rohd_source_navigator/test/flc_data_test.dart similarity index 100% rename from rohd_extension/dart/test/flc_data_test.dart rename to packages/rohd_source_navigator/test/flc_data_test.dart diff --git a/rohd-multipackage.code-workspace b/rohd-multipackage.code-workspace index a1df03666..92a31c952 100644 --- a/rohd-multipackage.code-workspace +++ b/rohd-multipackage.code-workspace @@ -15,6 +15,10 @@ "name": "rohd_waveform", "path": "packages/rohd_waveform" }, + { + "name": "rohd_source_navigator", + "path": "packages/rohd_source_navigator" + }, { "name": "rohd_devtools_extension", "path": "rohd_devtools_extension" diff --git a/rohd_extension/dart/README.md b/rohd_extension/dart/README.md deleted file mode 100644 index 878957d74..000000000 --- a/rohd_extension/dart/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# rohd_source_navigator - -Internal Dart port of ROHD source-navigation logic, including source frames, -path normalization, frame cycling, file/line/column data, and a Dart Tooling -Daemon (DTD) service. This package uses `publish_to: none` and is not released -on pub.dev. - -The [ROHD VS Code extension](../README.md) uses its TypeScript implementation. -Its `npm run compile` command runs `tsc` to generate JavaScript in `out/`, and -`.vscodeignore` excludes `dart/` from the VSIX. This Dart port is not compiled -to JavaScript or consumed by the extension's current build. - -## Development - -Run `dart pub get`, `dart analyze`, and `dart test` from this directory. diff --git a/test/prepare_release_metadata_test.dart b/test/prepare_release_metadata_test.dart index 608784122..78c917ff0 100644 --- a/test/prepare_release_metadata_test.dart +++ b/test/prepare_release_metadata_test.dart @@ -53,6 +53,8 @@ void main() { write('packages/rohd_waveform/CHANGELOG.md', '## 2.3.4\n'); write('packages/rohd_devtools_widgets/pubspec.yaml', 'version: 3.4.5\n'); write('packages/rohd_devtools_widgets/CHANGELOG.md', '## Next Release\n'); + write('packages/rohd_source_navigator/pubspec.yaml', 'version: 4.5.6\n'); + write('packages/rohd_source_navigator/CHANGELOG.md', '## Next Release\n'); }); tearDown(() => fixture.deleteSync(recursive: true)); @@ -64,12 +66,14 @@ void main() { 'rohd_hierarchy', 'rohd_waveform', 'rohd_devtools_widgets', + 'rohd_source_navigator', ]); expect(result.exitCode, 0, reason: '${result.stderr}'); expect(result.stdout, contains('rohd: 0.6.11 (prepared')); expect(result.stdout, contains('rohd_hierarchy: 1.2.3 (prepared')); expect(result.stdout, contains('rohd_waveform: 2.3.4 (prepared')); expect(result.stdout, contains('rohd_devtools_widgets: 3.4.5 (prepared')); + expect(result.stdout, contains('rohd_source_navigator: 4.5.6 (prepared')); expect(read('pubspec.yaml'), manifest); expect(read('CHANGELOG.md'), '## 0.6.11\n\n- Update.\n'); expect(read('lib/src/utilities/config.dart'), @@ -77,6 +81,9 @@ void main() { expect(read('packages/rohd_hierarchy/CHANGELOG.md'), '## 1.2.3\n'); expect(read('packages/rohd_waveform/CHANGELOG.md'), '## 2.3.4\n'); expect(read('packages/rohd_devtools_widgets/CHANGELOG.md'), '## 3.4.5\n'); + expect(read('packages/rohd_source_navigator/CHANGELOG.md'), '## 4.5.6\n'); + expect(read('packages/rohd_source_navigator/pubspec.yaml'), + 'version: 4.5.6\n'); }); test('validation does not change metadata', () { @@ -98,6 +105,21 @@ void main() { '## Next Release\n'); }); + test('source navigator selection uses its package directory', () { + final validation = run(['--check', 'rohd_source_navigator']); + expect(validation.exitCode, 0, reason: '${validation.stderr}'); + expect(read('packages/rohd_source_navigator/CHANGELOG.md'), + '## Next Release\n'); + + final result = run(['rohd_source_navigator']); + expect(result.exitCode, 0, reason: '${result.stderr}'); + expect(read('packages/rohd_source_navigator/CHANGELOG.md'), '## 4.5.6\n'); + expect(read('packages/rohd_source_navigator/pubspec.yaml'), + 'version: 4.5.6\n'); + expect(read('CHANGELOG.md'), startsWith('## Next Release')); + expect(read('lib/src/utilities/config.dart'), contains('0.6.10')); + }); + for (final manifest in [ 'name: rohd_hierarchy\n', 'version: 12\n', diff --git a/tool/check_release.sh b/tool/check_release.sh index 0b61b2e11..cd8233ef1 100755 --- a/tool/check_release.sh +++ b/tool/check_release.sh @@ -9,8 +9,8 @@ # Usage (from repo root): # tool/check_release.sh [--validate-only] [package ...] # -# With no package names, check rohd, rohd_hierarchy, rohd_waveform, and -# rohd_devtools_widgets. Explicit names select only those packages. Each package +# With no package names, check rohd, rohd_hierarchy, rohd_waveform, +# rohd_devtools_widgets, and rohd_source_navigator. Each selected package # uses its existing pubspec.yaml version; manifests and changelogs are not edited. # Dart is required for Dart packages; Flutter is required for widgets. # @@ -19,6 +19,7 @@ # tool/check_release.sh rohd # tool/check_release.sh rohd_hierarchy rohd_waveform # tool/check_release.sh rohd_devtools_widgets +# tool/check_release.sh rohd_source_navigator # tool/check_release.sh --validate-only # # --validate-only checks names, manifests, and SDK availability without invoking @@ -42,8 +43,8 @@ export FLUTTER_SUPPRESS_ANALYTICS=true usage() { echo "Usage: $0 [--validate-only] [package ...]" - echo "Packages: rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets" - echo "Defaults to all four packages, using each package's pubspec.yaml version." + echo "Packages: rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator" + echo "Defaults to all five packages, using each package's pubspec.yaml version." echo "Runs publication dry runs only; never uploads packages." } @@ -58,7 +59,7 @@ if [[ "${1:-}" == '--validate-only' ]]; then shift fi if [[ $# -eq 0 ]]; then - set -- rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets + set -- rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator fi readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" @@ -73,7 +74,7 @@ for package in "$@"; do directory="$REPO_ROOT" sdk=dart ;; - rohd_hierarchy|rohd_waveform) + rohd_hierarchy|rohd_waveform|rohd_source_navigator) directory="$REPO_ROOT/packages/$package" sdk=dart ;; diff --git a/tool/prepare_release.sh b/tool/prepare_release.sh index eb4300ef4..0e91b7ae1 100755 --- a/tool/prepare_release.sh +++ b/tool/prepare_release.sh @@ -13,8 +13,9 @@ # main into it. When selecting ROHD, wait for that main commit's DevTools build. # Publish from the preparation branch; merge its PR after publication succeeds. # -# With no arguments, select rohd, rohd_hierarchy, rohd_waveform, and -# rohd_devtools_widgets. Explicit package names select only those packages. +# With no arguments, select rohd, rohd_hierarchy, rohd_waveform, +# rohd_devtools_widgets, and rohd_source_navigator. +# Explicit package names select only those packages. # Set each selected package's version in its own pubspec.yaml before running. # The manifests are never rewritten; each pending changelog heading is promoted # to its package's version (an existing version heading is also accepted). @@ -26,7 +27,8 @@ # The DevTools build comes from main, not from branch-only implementation changes. # Each selected sub-package gets dependency resolution, a non-writing format check, # and analysis (including fatal infos) in its own directory. Dart is used -# for hierarchy/waveform, Flutter for widgets, and dart format for all three. +# for hierarchy/waveform/source navigator, Flutter for widgets, and dart format +# for all sub-packages. # Test suites are skipped by default; verify CI results for the release commit. # Add --run-tests to also run all selected package suites locally, including # ROHD's simulator prerequisites when ROHD is selected. @@ -40,10 +42,10 @@ # # Examples: # -# ROHD plus all three publishable sub-packages (the default): +# ROHD plus all four publishable sub-packages (the default): # tool/prepare_release.sh # -# All four packages, including their test suites: +# All five packages, including their test suites: # tool/prepare_release.sh --run-tests # # ROHD only: @@ -58,6 +60,9 @@ # Only hierarchy and waveform (no ROHD metadata or DevTools changes): # tool/prepare_release.sh rohd_hierarchy rohd_waveform # +# Only source navigator: +# tool/prepare_release.sh rohd_source_navigator +# # Sub-package archive checks only (no metadata preparation): # tool/check_release.sh rohd_hierarchy rohd_waveform rohd_devtools_widgets # @@ -75,8 +80,8 @@ export FLUTTER_SUPPRESS_ANALYTICS=true if [[ $# -eq 1 && "$1" == '--help' ]]; then echo "Usage: $0 [--run-tests] [package ...]" - echo "Packages: rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets" - echo "Defaults to all four packages, using each package's pubspec.yaml version." + echo "Packages: rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator" + echo "Defaults to all five packages, using each package's pubspec.yaml version." echo "Test suites are skipped by default; use --run-tests to include them." echo "Artifact verification and its smoke test still run when ROHD is selected." echo "Selecting ROHD also checks VSIX packaging (requires Node.js and npm)." @@ -94,7 +99,7 @@ for argument in "$@"; do done set -- "${packages[@]}" if [[ $# -eq 0 ]]; then - set -- rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets + set -- rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator fi # Resolve all paths and source provenance before changing the working tree. diff --git a/tool/prepare_release_metadata.dart b/tool/prepare_release_metadata.dart index e35e3a3a1..53469e136 100644 --- a/tool/prepare_release_metadata.dart +++ b/tool/prepare_release_metadata.dart @@ -24,6 +24,7 @@ const _packagePaths = { 'rohd_hierarchy': 'packages/rohd_hierarchy', 'rohd_waveform': 'packages/rohd_waveform', 'rohd_devtools_widgets': 'packages/rohd_devtools_widgets', + 'rohd_source_navigator': 'packages/rohd_source_navigator', }; void main(List arguments) { diff --git a/tool/test/check_release_test.sh b/tool/test/check_release_test.sh index 1396b108d..fa11ac326 100755 --- a/tool/test/check_release_test.sh +++ b/tool/test/check_release_test.sh @@ -23,7 +23,7 @@ trap 'rm -rf "$FIXTURE"' EXIT mkdir -p "$FIXTURE/repo/tool" "$FIXTURE/bin" "$FIXTURE/repo/extension/devtools/build" cp "$REPO_ROOT/tool/check_release.sh" "$REPO_ROOT/tool/prepare_release.sh" "$FIXTURE/repo/tool/" -for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do +for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do mkdir -p "$FIXTURE/repo/packages/$package" touch "$FIXTURE/repo/packages/$package/pubspec.yaml" done @@ -66,24 +66,33 @@ run_case() { run_case 0 "$HELPER" --help [[ ! -s "$SDK_LOG" ]] run_case 0 "$HELPER" -[[ "$(wc -l < "$SDK_LOG")" -eq 4 ]] +[[ "$(wc -l < "$SDK_LOG")" -eq 5 ]] +grep -Fx "dart|$FIXTURE/repo/packages/rohd_source_navigator|pub publish --dry-run" "$SDK_LOG" DASH__SUPPRESS_ANALYTICS=false FLUTTER_SUPPRESS_ANALYTICS=false run_case 0 "$HELPER" rohd_devtools_widgets run_case 0 "$HELPER" --validate-only [[ ! -s "$SDK_LOG" ]] -for invalid in --force --dry-run ../rohd rohd_source_navigator rohd_devtools_extension; do +for invalid in --force --dry-run ../rohd rohd_devtools_extension; do run_case 2 "$HELPER" rohd_hierarchy "$invalid" [[ ! -s "$SDK_LOG" ]] done -run_case 0 "$HELPER" --validate-only rohd rohd_devtools_widgets +run_case 0 "$HELPER" --validate-only rohd rohd_devtools_widgets rohd_source_navigator [[ ! -s "$SDK_LOG" ]] cd "$FIXTURE" -run_case 0 "$HELPER" rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets -[[ "$(wc -l < "$SDK_LOG")" -eq 4 ]] +run_case 0 "$HELPER" rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator +[[ "$(wc -l < "$SDK_LOG")" -eq 5 ]] grep -Fx "dart|$FIXTURE/repo|pub publish --dry-run" "$SDK_LOG" grep -Fx "dart|$FIXTURE/repo/packages/rohd_hierarchy|pub publish --dry-run" "$SDK_LOG" grep -Fx "dart|$FIXTURE/repo/packages/rohd_waveform|pub publish --dry-run" "$SDK_LOG" grep -Fx "flutter|$FIXTURE/repo/packages/rohd_devtools_widgets|pub publish --dry-run" "$SDK_LOG" +grep -Fx "dart|$FIXTURE/repo/packages/rohd_source_navigator|pub publish --dry-run" "$SDK_LOG" + +run_case 0 "$HELPER" rohd_source_navigator +[[ "$(cat "$SDK_LOG")" == "dart|$FIXTURE/repo/packages/rohd_source_navigator|pub publish --dry-run" ]] +FAIL_PACKAGE=rohd_source_navigator run_case 1 "$HELPER" rohd_source_navigator rohd_hierarchy +[[ "$(wc -l < "$SDK_LOG")" -eq 2 ]] +grep -F 'rohd_source_navigator: FAILED (exit 65;' "$FIXTURE/output" +grep -F 'rohd_hierarchy: PASSED' "$FIXTURE/output" export FAIL_PACKAGE=rohd_hierarchy run_case 1 "$HELPER" rohd_hierarchy rohd_waveform @@ -107,6 +116,9 @@ run_case 1 "$HELPER" rohd rm "$FIXTURE/repo/packages/rohd_waveform/pubspec.yaml" run_case 2 "$HELPER" rohd_hierarchy rohd_waveform [[ ! -s "$SDK_LOG" ]] +rm "$FIXTURE/repo/packages/rohd_source_navigator/pubspec.yaml" +run_case 2 "$HELPER" rohd_hierarchy rohd_source_navigator +[[ ! -s "$SDK_LOG" ]] rm "$FIXTURE/bin/flutter" run_case 2 "$HELPER" rohd_hierarchy rohd_devtools_widgets [[ ! -s "$SDK_LOG" ]] diff --git a/tool/test/prepare_release_test.sh b/tool/test/prepare_release_test.sh index c036ed87b..5588f0d26 100644 --- a/tool/test/prepare_release_test.sh +++ b/tool/test/prepare_release_test.sh @@ -86,13 +86,14 @@ printf "static const String version = '0.0.0';\n" > "$UPSTREAM/lib/src/utilities printf '## Next Release\n' > "$UPSTREAM/CHANGELOG.md" printf 'fixture configuration\n' > "$UPSTREAM/extension/devtools/config.yaml" printf 'extension/devtools/build/\n' > "$UPSTREAM/.gitignore" -for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do +for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do mkdir -p "$UPSTREAM/packages/$package" printf '## Next Release\n' > "$UPSTREAM/packages/$package/CHANGELOG.md" done printf 'version: 1.2.3\n' > "$UPSTREAM/packages/rohd_hierarchy/pubspec.yaml" printf 'version: 2.3.4\n' > "$UPSTREAM/packages/rohd_waveform/pubspec.yaml" printf 'version: 3.4.5\n' > "$UPSTREAM/packages/rohd_devtools_widgets/pubspec.yaml" +printf 'version: 4.5.6\n' > "$UPSTREAM/packages/rohd_source_navigator/pubspec.yaml" git init --quiet --initial-branch=main "$UPSTREAM" git -C "$UPSTREAM" add . @@ -140,7 +141,7 @@ assert_unchanged() { [[ "$(cat "$RELEASE/CHANGELOG.md")" == '## Next Release' ]] [[ "$(cat "$RELEASE/extension/devtools/build/index.html")" == 'original payload' ]] [[ "$(cat "$RELEASE/extension/devtools/config.yaml")" == 'fixture configuration' ]] - for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do + for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do [[ "$(cat "$RELEASE/packages/$package/CHANGELOG.md")" == '## Next Release' ]] done } @@ -152,11 +153,12 @@ expected_checks() { if [[ "$package" == rohd_devtools_widgets ]]; then sdk=flutter fi - printf '%s|%s|%s\n' "$sdk" "$RELEASE/packages/$package" 'pub get' - printf '%s|%s|%s\n' dart "$RELEASE/packages/$package" 'format --output=none --set-exit-if-changed .' - printf '%s|%s|%s\n' "$sdk" "$RELEASE/packages/$package" 'analyze --fatal-infos' + local directory="$RELEASE/packages/$package" + printf '%s|%s|%s\n' "$sdk" "$directory" 'pub get' + printf '%s|%s|%s\n' dart "$directory" 'format --output=none --set-exit-if-changed .' + printf '%s|%s|%s\n' "$sdk" "$directory" 'analyze --fatal-infos' if [[ "$include_tests" == true ]]; then - printf '%s|%s|%s\n' "$sdk" "$RELEASE/packages/$package" test + printf '%s|%s|%s\n' "$sdk" "$directory" test fi } @@ -179,17 +181,18 @@ assert_unchanged unset SMOKE_STATUS run_case 0 "DevTools source commit (upstream main): $MAIN_COMMIT" -[[ "$(cat "$STAGE_LOG")" == $'smoke\nchecks-skip-tests\nvsix\ndry-run\ndry-run\ndry-run\ndry-run' ]] +[[ "$(cat "$STAGE_LOG")" == $'smoke\nchecks-skip-tests\nvsix\ndry-run\ndry-run\ndry-run\ndry-run\ndry-run' ]] [[ ! -e "$(cat "$VSIX_PATH_LOG")" ]] grep -Fq 'Test suites were not run.' "$FIXTURE/output" expected_log="$( - for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do + for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do expected_checks "$package" done printf 'dart|%s|pub publish --dry-run\n' "$RELEASE" printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_hierarchy" printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_waveform" printf 'flutter|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_devtools_widgets" + printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_source_navigator" )" [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] [[ "$(cat "$RELEASE/pubspec.yaml")" == "version: '0.6.11' # release" ]] @@ -200,18 +203,20 @@ expected_log="$( [[ "$(cat "$RELEASE/packages/rohd_hierarchy/CHANGELOG.md")" == '## 1.2.3' ]] [[ "$(cat "$RELEASE/packages/rohd_waveform/CHANGELOG.md")" == '## 2.3.4' ]] [[ "$(cat "$RELEASE/packages/rohd_devtools_widgets/CHANGELOG.md")" == '## 3.4.5' ]] +[[ "$(cat "$RELEASE/packages/rohd_source_navigator/CHANGELOG.md")" == '## 4.5.6' ]] git -C "$RELEASE" diff --exit-code -- pubspec.yaml 'packages/*/pubspec.yaml' run_case 0 "DevTools source commit (upstream main): $MAIN_COMMIT" --run-tests -[[ "$(cat "$STAGE_LOG")" == $'smoke\nchecks\nvsix\ndry-run\ndry-run\ndry-run\ndry-run' ]] +[[ "$(cat "$STAGE_LOG")" == $'smoke\nchecks\nvsix\ndry-run\ndry-run\ndry-run\ndry-run\ndry-run' ]] expected_log="$( - for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do + for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do expected_checks "$package" true done printf 'dart|%s|pub publish --dry-run\n' "$RELEASE" printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_hierarchy" printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_waveform" printf 'flutter|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_devtools_widgets" + printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_source_navigator" )" [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] ! grep -Fq 'Test suites were not run.' "$FIXTURE/output" @@ -267,12 +272,22 @@ expected_log="$( [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] [[ "$(cat "$STAGE_LOG")" == 'dry-run' ]] -for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets; do +run_case 0 'rohd_source_navigator: PASSED' --run-tests rohd_source_navigator +expected_log="$( + expected_checks rohd_source_navigator true + printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_source_navigator" +)" +[[ "$(cat "$SDK_LOG")" == "$expected_log" ]] +[[ "$(cat "$STAGE_LOG")" == 'dry-run' ]] +[[ "$(cat "$RELEASE/lib/src/utilities/config.dart")" == "static const String version = '0.0.0';" ]] +[[ "$(cat "$RELEASE/CHANGELOG.md")" == '## Next Release' ]] + +for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do export FAIL_PACKAGE="$package" FAIL_COMMAND=test run_case 0 "$package: PASSED" "$package" ! grep -Fq '|test' "$SDK_LOG" for check_command in 'pub get' 'format --output=none --set-exit-if-changed .' 'analyze --fatal-infos' test; do - export FAIL_PACKAGE="$package" FAIL_COMMAND="$check_command" + export FAIL_COMMAND="$check_command" check_arguments=() include_tests=false if [[ "$check_command" == test ]]; then From ebd3b647471b6a2fc5bb889664ec15fd4d52fcb3 Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Tue, 22 Sep 2026 12:31:44 -0700 Subject: [PATCH 2/6] added pana checks for packages, updated rohd for new source-nav package promotion --- .github/workflows/general.yml | 8 ++ CHANGELOG.md | 6 - doc/releases.md | 62 ++++++--- packages/rohd_devtools_widgets/CHANGELOG.md | 6 + packages/rohd_devtools_widgets/pubspec.yaml | 4 +- packages/rohd_source_navigator/CHANGELOG.md | 8 +- packages/rohd_source_navigator/README.md | 29 +---- tool/gh_actions/pana_source.sh | 60 ++++++++- tool/prepare_release.sh | 13 +- tool/test/pana_source_test.sh | 131 ++++++++++++++++++++ tool/test/prepare_release_test.sh | 29 ++++- 11 files changed, 292 insertions(+), 64 deletions(-) create mode 100644 tool/test/pana_source_test.sh diff --git a/.github/workflows/general.yml b/.github/workflows/general.yml index 14010b74a..7a031a52e 100644 --- a/.github/workflows/general.yml +++ b/.github/workflows/general.yml @@ -93,6 +93,8 @@ jobs: sdk: dart - package: rohd_devtools_widgets sdk: flutter + - package: rohd_source_navigator + sdk: dart defaults: run: working-directory: packages/${{ matrix.package }} @@ -114,6 +116,9 @@ jobs: - name: Install package dependencies run: ${{ matrix.sdk }} pub get + - name: Setup Pana source analysis + run: bash ../../tool/gh_actions/install_pana.sh + - name: Verify package formatting run: dart format --output=none --set-exit-if-changed . @@ -123,6 +128,9 @@ jobs: - name: Run package tests run: ${{ matrix.sdk }} test + - name: Check hosted dependencies and run Pana + run: bash ../../tool/gh_actions/pana_source.sh . ${{ matrix.sdk }} + deploy-documentation: name: Deploy Documentation needs: diff --git a/CHANGELOG.md b/CHANGELOG.md index 5e77c5cf1..3406c52f2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,3 @@ - -## Next Release - -- Exposed the shared `rohd_source_navigator` code used by `rohd-schematic-viewer` as a standalone pub.dev package. -- Corrected the ROHD dependency in `rohd_devtools_widgets` from `^0.6.9` to `^0.6.11` to reflect the minimum compatible ROHD version. - ## 0.6.11 - Added `NetlistSynthesizer` for generating JSON netlists, with configurable synthesis passes, validation, and hierarchy support (). diff --git a/doc/releases.md b/doc/releases.md index abf3d5634..7828fbce1 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -89,12 +89,12 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet The non-published DevTools app therefore also declares its own local overrides. 4. Verify the PR's CI results cover the relevant tests for the release commit, including DevTools app tests when shared widgets change. The General workflow - has separate `Check rohd_hierarchy`, `Check rohd_waveform`, and - `Check rohd_devtools_widgets` jobs for dependency resolution, formatting, - fatal-info analysis, and package tests. These run alongside the root checks - and DevTools app job; documentation deployment waits for all of them. - Source navigator is not included in that matrix; run its local checks with - `tool/prepare_release.sh --run-tests rohd_source_navigator`. + has separate `Check rohd_hierarchy`, `Check rohd_waveform`, + `Check rohd_devtools_widgets`, and `Check rohd_source_navigator` jobs for + dependency resolution, formatting, fatal-info analysis, package tests, and + isolated hosted dependency checks and Pana reports. + These run alongside the root checks and DevTools app job; documentation + deployment waits for all of them. Preparation skips local test suites by default and does not query GitHub or verify CI status. Use `--run-tests` to repeat selected package suites locally. ROHD's local @@ -111,7 +111,9 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet web build before preparing metadata, then runs ROHD's checks. Sub-package-only preparation leaves ROHD metadata and DevTools untouched. Each selected sub-package gets dependency resolution, formatting checks, and analysis in its - own directory, plus tests when `--run-tests` is supplied. Selecting ROHD also + own directory, plus isolated hosted dependency checks and Pana reports even + when tests are skipped. + Tests run when `--run-tests` is supplied. Selecting ROHD also compiles and packages a temporary VSIX using the same helper as the VS Code release workflow, even when test suites are skipped. Only after all enabled checks for selected packages pass does it run @@ -135,8 +137,8 @@ Preparation runs the following checks before invoking `tool/check_release.sh`: | Selected Package | Default Checks | Added With `--run-tests` | | --- | --- | --- | | `rohd` | `tool/run_checks.sh --skip-tests`: dependencies, formatting, analysis, API docs, and temporary-file checks; then `tool/package_vscode.sh` compiles and packages a temporary VSIX. | Simulator prerequisites and ROHD tests via `tool/run_checks.sh`. | -| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`. | `dart test` in each selected package. | -| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`. | `flutter test` in the widgets package. | +| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`; also isolated hosted dependency checks and a Pana report. | `dart test` in each selected package. | +| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`; also isolated hosted dependency checks and a Pana report. | `flutter test` in the widgets package. | Artifact provenance verification and the DevTools installation smoke test always run when ROHD is selected, even when test suites are skipped. The VSIX packaging @@ -153,9 +155,25 @@ fatal. The script prints each sub-package stage and stops on the first failed prerequisite or enabled check; no publication dry runs start unless all enabled checks pass. An early failure such as a nonempty `tmp_test` directory means later stages have not run. Review leftover test files before retrying. -Checks use the current checkout's dependency overrides; hosted-dependency -validation without overrides is still required as described below. Tests for the -separate DevTools application remain a separate step when its shared widgets change. +The ordinary package checks use the current checkout's dependency overrides. +Both CI and preparation reuse the existing Pana runner: +`bash tool/gh_actions/pana_source.sh packages/ `. +Its package mode uses a disposable copy without checkout overrides, lockfiles, +generated resolution/build state, or repository-relative analyzer configuration. +Inline overrides are rejected; keep local overrides in `pubspec_overrides.yaml`. +It runs `pub get` and `pub downgrade`, each followed by fatal-info analysis of +`lib/`, using the selected SDK. Flutter analysis uses `--no-pub` to preserve the +downgraded resolution. Required dependencies must already be available on pub.dev; +there is no fallback to local packages. Command failures stop CI and preparation. +Pana's report is printed for review, but package scoring findings such as missing +examples or newer dependency major versions are advisory. No custom report parser +is used. The root's existing no-argument Pana invocation and score gate are +unchanged. Temporary copies are cleaned up on success or failure, and developers' +overrides are never removed or rewritten. + +Pana does not run consumer tests. Final override-free tests and archive checks +are still required as described below. Tests for the separate DevTools +application remain a separate step when its shared widgets change. Preparation examples (choose one): @@ -180,11 +198,17 @@ tool/prepare_release.sh rohd_hierarchy rohd_waveform # Only source navigator: tool/prepare_release.sh rohd_source_navigator + +# Source navigator and widgets, including both package test suites: +tool/prepare_release.sh --run-tests rohd_source_navigator rohd_devtools_widgets ``` Preparation requires Dart for YAML metadata parsing using the root package's -dependencies. Selecting widgets also requires Flutter, including the default -all-package selection. Selecting ROHD also requires Node.js and npm for the VSIX +dependencies. Selecting any sub-package also requires Pana, installed with +`bash tool/gh_actions/install_pana.sh`, and network access to hosted dependencies. +Selecting widgets also requires Flutter, including the default all-package +selection. The Pana runner discovers Flutter from its executable or uses +`FLUTTER_ROOT` when set. Selecting ROHD also requires Node.js and npm for the VSIX check; the release workflow uses Node.js 24. Explicit sub-package-only preparation does not build the VSIX or require Node.js/npm. @@ -222,7 +246,10 @@ The helper's isolated regression checks run with Both stub publication commands on a restricted PATH. Preparation tests also stub package-check commands to verify their order, SDK choice, and failure handling. They cover both the default skipped suites and the `--run-tests` mode, including -VSIX failure before publication checks and temporary-archive cleanup. The shared +Pana prerequisites and failure before publication checks, VSIX failure, and +temporary-archive cleanup. The existing Pana runner's root mode, package isolation, +and failure propagation are covered by `bash tool/test/pana_source_test.sh`, +using stub SDK/Pana executables without network access. The shared VSIX helper has isolated command and failure checks in `bash tool/test/package_vscode_test.sh`. The root checker's default and `--skip-tests` paths are covered by @@ -251,10 +278,11 @@ independently of ROHD and the Flutter packages. Once its version is available on pub.dev, consumers such as the ROHD Schematic Viewer can replace their Git dependency with `rohd_source_navigator: ^0.1.0` and remove any Git override for that package. Existing Dart imports remain unchanged. See the -[package README](../packages/rohd_source_navigator/README.md) for migration details. +[package README](../packages/rohd_source_navigator/README.md) for installation +instructions and API examples. For each package, wait until its required dependencies are available on pub.dev, -then validate from a clean disposable checkout of the release commit without +then complete final validation from a clean disposable checkout of the release commit without local dependency overrides or reused path-based lockfiles. Remove that checkout's `pubspec_overrides.yaml`, run dependency resolution, analysis and tests again, and repeat the publish dry run. A dry run using local overrides does not prove that diff --git a/packages/rohd_devtools_widgets/CHANGELOG.md b/packages/rohd_devtools_widgets/CHANGELOG.md index bd0841426..de4f6c66b 100644 --- a/packages/rohd_devtools_widgets/CHANGELOG.md +++ b/packages/rohd_devtools_widgets/CHANGELOG.md @@ -1,3 +1,9 @@ +## 0.1.1 + +- Fix the ROHD dependency lower bound: require `^0.6.10` instead of `^0.6.9`, + since signal formatting uses `toRadixString`'s `includeWidth` and `sepChar` + parameters introduced in ROHD 0.6.10. + ## 0.1.0 - Initial release of shared ROHD DevTools widgets. diff --git a/packages/rohd_devtools_widgets/pubspec.yaml b/packages/rohd_devtools_widgets/pubspec.yaml index 1da9d6820..952e3934a 100644 --- a/packages/rohd_devtools_widgets/pubspec.yaml +++ b/packages/rohd_devtools_widgets/pubspec.yaml @@ -1,6 +1,6 @@ name: rohd_devtools_widgets description: "Shared Flutter widgets and utilities for ROHD debug tools, including cross-probing, signal formatting, help, and PNG export." -version: 0.1.0 +version: 0.1.1 homepage: https://intel.github.io/rohd-website/ repository: https://github.com/intel/rohd/tree/main/packages/rohd_devtools_widgets issue_tracker: https://github.com/intel/rohd/issues @@ -11,7 +11,7 @@ dependencies: cupertino_ui: '>=1.0.0 <1.1.0' flutter: {sdk: flutter} material_ui: '>=1.1.0 <1.3.0' - rohd: ^0.6.11 + rohd: ^0.6.10 rohd_hierarchy: ^0.1.0 web: ^1.0.0 dev_dependencies: diff --git a/packages/rohd_source_navigator/CHANGELOG.md b/packages/rohd_source_navigator/CHANGELOG.md index 8a1fd5006..987ffb111 100644 --- a/packages/rohd_source_navigator/CHANGELOG.md +++ b/packages/rohd_source_navigator/CHANGELOG.md @@ -1,9 +1,3 @@ ## 0.1.0 -- Prepare the existing ROHD source-navigation library for independent pub.dev - distribution, including FLC parsing, source frames, path utilities, frame - cycling, and DTD integration. -- Preserve the public imports and implementation previously consumed through - a Git dependency. -- Move the package to `packages/rohd_source_navigator`, alongside the other - independently published ROHD libraries. +- Initial release of shared ROHD source-navigation utilities. diff --git a/packages/rohd_source_navigator/README.md b/packages/rohd_source_navigator/README.md index d0675064a..3af3e72ad 100644 --- a/packages/rohd_source_navigator/README.md +++ b/packages/rohd_source_navigator/README.md @@ -28,7 +28,7 @@ Import the complete API: import 'package:rohd_source_navigator/rohd_source_navigator.dart'; ``` -The existing focused imports remain supported: +Use focused imports for FLC data, source-navigation utilities, or DTD integration: ```dart import 'package:rohd_source_navigator/flc_data.dart'; @@ -59,33 +59,12 @@ void main() { } ``` -This is a Dart library, not an editor extension. The +This is a Dart library, not an editor extension. Installing this package does not +install or activate the [ROHD VS Code extension](https://github.com/intel/rohd/tree/main/rohd_extension) -continues to use its separate TypeScript implementation; installing this -package does not install or activate that extension. - -## Migrating from a Git dependency - -Once version 0.1.0 is available on pub.dev, replace the Git dependency with: - -```yaml -dependencies: - rohd_source_navigator: ^0.1.0 -``` - -Also remove any Git or path entry for `rohd_source_navigator` from -`dependency_overrides` or `pubspec_overrides.yaml`; otherwise Pub will continue -using that override instead of the hosted package. Run `dart pub get` (or -`flutter pub get`) to update the lockfile. Existing Dart imports do not change. - -If continuing to use a Git dependency at a commit containing the package move, -change its `path` from `rohd_extension/dart` to -`packages/rohd_source_navigator`. Dependencies pinned to older commits or tags -keep their original path. +or its separate TypeScript implementation. ## Development The package lives in `packages/rohd_source_navigator` in the ROHD repository. Run `dart pub get`, `dart analyze`, and `dart test` from that directory. -Use `dart pub publish --dry-run` there to inspect the publication archive, or -`tool/check_release.sh rohd_source_navigator` from the repository root. diff --git a/tool/gh_actions/pana_source.sh b/tool/gh_actions/pana_source.sh index 7f36d922b..dca3a0cc2 100755 --- a/tool/gh_actions/pana_source.sh +++ b/tool/gh_actions/pana_source.sh @@ -5,10 +5,66 @@ # # pana_source.sh # GitHub Actions step: execute pana analysis on project source. +# With , check an isolated package instead. # # 2025 September 26 # Author: Desmond A. Kirkpatrick -PATH="$PATH":"$HOME/.pub-cache/bin" +set -euo pipefail -pana --exit-code-threshold 0 . +export PATH="$PATH:${PUB_CACHE:-$HOME/.pub-cache}/bin" + +if [[ $# -eq 0 ]]; then + exec pana --exit-code-threshold 0 . +fi +if [[ $# -ne 2 || ! -f "$1/pubspec.yaml" || + ( "$2" != dart && "$2" != flutter ) ]]; then + echo "Usage: $0 [ ]" >&2 + exit 2 +fi +if ! command -v pana > /dev/null; then + echo "Pana is required; run tool/gh_actions/install_pana.sh first." >&2 + exit 2 +fi + +package_dir="$(cd "$1" && pwd)" +sdk="$2" +analyze_arguments=(analyze --fatal-infos) +pana_arguments=() +if [[ "$sdk" == flutter ]]; then + flutter_root="${FLUTTER_ROOT:-}" + if [[ -z "$flutter_root" ]]; then + flutter_executable="$(command -v flutter)" + flutter_root="$(dirname "$(dirname "$(readlink -f "$flutter_executable")")")" + fi + pana_arguments+=(--flutter-sdk "$flutter_root") + analyze_arguments+=(--no-pub) +fi + +temp_dir="$(mktemp -d "${TMPDIR:-/tmp}/rohd-pana.XXXXXXXX")" +trap 'rm -rf "$temp_dir"' EXIT +trap 'exit 130' INT +trap 'exit 143' TERM +mkdir "$temp_dir/package" +# Checkout lint includes are repository-relative; compatibility analysis below +# checks the library, while normal CI retains the full repository lint policy. +tar -C "$package_dir" \ + --exclude=.git --exclude=.dart_tool --exclude=.packages \ + --exclude=build --exclude=coverage --exclude=analysis_options.yaml \ + --exclude=pubspec.lock --exclude=pubspec_overrides.yaml \ + --exclude=.flutter-plugins --exclude=.flutter-plugins-dependencies \ + -cf - . | tar -C "$temp_dir/package" -xf - +cd "$temp_dir/package" +if grep -Eq '^[[:space:]]*dependency_overrides[[:space:]]*:' pubspec.yaml; then + echo "Move inline dependency overrides to pubspec_overrides.yaml before hosted checks." >&2 + exit 2 +fi + +echo "=== ${package_dir##*/}: hosted dependency compatibility ===" +"$sdk" pub get +"$sdk" "${analyze_arguments[@]}" lib +"$sdk" pub downgrade +"$sdk" "${analyze_arguments[@]}" lib + +echo "=== ${package_dir##*/}: Pana report (package scores are advisory) ===" +PANA_ANALYSIS_INCLUDES=0 pana "${pana_arguments[@]}" . diff --git a/tool/prepare_release.sh b/tool/prepare_release.sh index 0e91b7ae1..bfe6029f1 100755 --- a/tool/prepare_release.sh +++ b/tool/prepare_release.sh @@ -28,7 +28,8 @@ # Each selected sub-package gets dependency resolution, a non-writing format check, # and analysis (including fatal infos) in its own directory. Dart is used # for hierarchy/waveform/source navigator, Flutter for widgets, and dart format -# for all sub-packages. +# for all sub-packages. The existing Pana runner also checks hosted dependencies +# with pub get, pub downgrade, and library analysis in an override-free copy. # Test suites are skipped by default; verify CI results for the release commit. # Add --run-tests to also run all selected package suites locally, including # ROHD's simulator prerequisites when ROHD is selected. @@ -37,8 +38,9 @@ # # Dart is required to read YAML metadata using the root package's dependencies. # Selecting ROHD also requires Node.js and npm (release CI uses Node.js 24). -# Selecting rohd_devtools_widgets also requires Flutter. Any failed prerequisite -# or package check stops preparation before publication dry runs. +# Selecting rohd_devtools_widgets also requires Flutter. Selecting any sub-package +# requires Pana (tool/gh_actions/install_pana.sh) and hosted dependencies. +# Any failed prerequisite or package check stops preparation before dry runs. # # Examples: # @@ -85,6 +87,7 @@ if [[ $# -eq 1 && "$1" == '--help' ]]; then echo "Test suites are skipped by default; use --run-tests to include them." echo "Artifact verification and its smoke test still run when ROHD is selected." echo "Selecting ROHD also checks VSIX packaging (requires Node.js and npm)." + echo "Sub-packages also require Pana and always check hosted dependency lower bounds." echo "Prepares metadata, runs package checks and publication dry runs; never uploads packages." exit 0 fi @@ -115,6 +118,9 @@ prepare_rohd=false for package in "$@"; do if [[ "$package" == rohd ]]; then prepare_rohd=true + elif ! PATH="$PATH:${PUB_CACHE:-$HOME/.pub-cache}/bin" command -v pana > /dev/null; then + echo "Pana is required; run tool/gh_actions/install_pana.sh first." >&2 + exit 2 fi done cd "$REPO_ROOT" @@ -216,6 +222,7 @@ for package in "$@"; do echo "=== $package: tests skipped (use --run-tests) ===" fi ) + bash "$SCRIPT_DIR/gh_actions/pana_source.sh" "$REPO_ROOT/packages/$package" "$sdk" done git diff --check bash "$SCRIPT_DIR/check_release.sh" "$@" diff --git a/tool/test/pana_source_test.sh b/tool/test/pana_source_test.sh new file mode 100644 index 000000000..90a9c01a5 --- /dev/null +++ b/tool/test/pana_source_test.sh @@ -0,0 +1,131 @@ +#!/bin/bash + +# Copyright (C) 2026 Intel Corporation +# SPDX-License-Identifier: BSD-3-Clause +# +# Test the existing Pana runner with fake SDKs and no network access. +# Usage: bash tool/test/pana_source_test.sh + +set -euo pipefail + +readonly REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" +readonly FIXTURE="$(mktemp -d)" +trap 'rm -rf "$FIXTURE"' EXIT +export SOURCE="$FIXTURE/source package" SDK_LOG="$FIXTURE/sdk.log" +export PUB_CACHE="$FIXTURE/pub cache" TMPDIR="$FIXTURE/temp space" +export FLUTTER_ROOT="$FIXTURE/flutter sdk" PANA_ANALYSIS_INCLUDES=1 + +mkdir -p "$SOURCE/lib" "$SOURCE/.dart_tool" "$SOURCE/example" \ + "$FIXTURE/bin" "$PUB_CACHE/bin" "$TMPDIR" "$FLUTTER_ROOT/bin" +for executable in bash cmp dirname grep mkdir mktemp readlink rm tar; do + ln -s "$(command -v "$executable")" "$FIXTURE/bin/$executable" +done +printf 'name: fixture\n' > "$SOURCE/pubspec.yaml" +printf 'library fixture;\n' > "$SOURCE/lib/fixture.dart" +for file in pubspec.lock pubspec_overrides.yaml analysis_options.yaml \ + .dart_tool/package_config.json example/pubspec.lock example/pubspec_overrides.yaml; do + printf 'checkout-only state\n' > "$SOURCE/$file" +done +cp -R "$SOURCE" "$FIXTURE/original" + +cat > "$FIXTURE/bin/dart" <<'EOF' +#!/bin/bash +set -euo pipefail +[[ "$PWD" == "$TMPDIR"/rohd-pana.*/package ]] +printf '%s|%s\n' "${0##*/}" "$*" >> "$SDK_LOG" +case "$*" in + 'pub get') + for file in pubspec.lock pubspec_overrides.yaml analysis_options.yaml \ + .dart_tool example/pubspec.lock example/pubspec_overrides.yaml; do + [[ ! -e "$file" ]] + done + cmp pubspec.yaml "$SOURCE/pubspec.yaml" + cmp lib/fixture.dart "$SOURCE/lib/fixture.dart" + printf 'hosted resolution\n' > pubspec.lock ;; + 'pub downgrade') printf 'downgraded resolution\n' > pubspec.lock ;; + 'analyze --fatal-infos lib'|'analyze --fatal-infos --no-pub lib') + if [[ "${FAIL_COMMAND:-}" == downgrade-analysis ]] && + grep -q downgraded pubspec.lock; then + exit 71 + fi ;; + *) exit 99 ;; +esac +if [[ "${FAIL_COMMAND:-}" == "$*" ]]; then exit 71; fi +EOF +chmod +x "$FIXTURE/bin/dart" +ln -s "$FIXTURE/bin/dart" "$FLUTTER_ROOT/bin/flutter" +ln -s "$FLUTTER_ROOT/bin/flutter" "$FIXTURE/bin/flutter" + +cat > "$PUB_CACHE/bin/pana" <<'EOF' +#!/bin/bash +set -euo pipefail +if [[ "$PWD" == "$SOURCE" ]]; then + [[ "$*" == '--exit-code-threshold 0 .' ]] +else + [[ "$PWD" == "$TMPDIR"/rohd-pana.*/package && "$PANA_ANALYSIS_INCLUDES" == 0 ]] + if [[ "$EXPECTED_SDK" == flutter ]]; then + [[ $# -eq 3 && "$1" == --flutter-sdk && "$2" == "$EXPECTED_FLUTTER_ROOT" && "$3" == . ]] + else + [[ $# -eq 1 && "$1" == . ]] + fi + printf 'changed by Pana\n' > pubspec.yaml +fi +printf 'pana\n' >> "$SDK_LOG" +exit "${PANA_STATUS:-0}" +EOF +chmod +x "$PUB_CACHE/bin/pana" +export EXPECTED_FLUTTER_ROOT="$FLUTTER_ROOT" +cd "$SOURCE" + +passed=0 +run_case() { + local expected="$1" status=0 + shift + : > "$SDK_LOG" + PATH="$FIXTURE/bin" /bin/bash "$REPO_ROOT/tool/gh_actions/pana_source.sh" \ + "$@" > "$FIXTURE/output" 2>&1 || status=$? + if [[ "$status" -ne "$expected" ]]; then + cat "$FIXTURE/output" + echo "Expected exit $expected, got $status for: $*" >&2 + exit 1 + fi + diff -ru "$FIXTURE/original" "$SOURCE" + [[ -z "$(find "$TMPDIR" -mindepth 1 -print -quit)" ]] + passed=$((passed + 1)) +} + +run_case 0 +[[ "$(cat "$SDK_LOG")" == pana ]] +PANA_STATUS=127 run_case 127 +run_case 2 "$SOURCE" +run_case 2 "$SOURCE" invalid +run_case 2 "$FIXTURE/missing" dart + +for sdk in dart flutter; do + export EXPECTED_SDK="$sdk" + analyze='analyze --fatal-infos' + if [[ "$sdk" == flutter ]]; then analyze+=' --no-pub'; fi + analyze+=' lib' + run_case 0 "$SOURCE" "$sdk" + expected_log="$(printf '%s|%s\n' "$sdk" 'pub get' "$sdk" "$analyze" \ + "$sdk" 'pub downgrade' "$sdk" "$analyze"; printf 'pana\n')" + [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] + PANA_STATUS=73 run_case 73 "$SOURCE" "$sdk" + for failure in 'pub get' "$analyze" 'pub downgrade' downgrade-analysis; do + FAIL_COMMAND="$failure" run_case 71 "$SOURCE" "$sdk" + ! grep -q '^pana$' "$SDK_LOG" + done +done + +mv "$PUB_CACHE/bin/pana" "$FIXTURE/pana" +run_case 2 "$SOURCE" dart +grep -q 'Pana is required' "$FIXTURE/output" +[[ ! -s "$SDK_LOG" ]] +mv "$FIXTURE/pana" "$PUB_CACHE/bin/pana" +printf 'dependency_overrides:\n' >> "$SOURCE/pubspec.yaml" +cp "$SOURCE/pubspec.yaml" "$FIXTURE/original/pubspec.yaml" +run_case 2 "$SOURCE" dart +grep -q 'Move inline dependency overrides' "$FIXTURE/output" +[[ ! -s "$SDK_LOG" ]] + +echo "$passed Pana runner checks passed using only fake SDK/Pana executables." diff --git a/tool/test/prepare_release_test.sh b/tool/test/prepare_release_test.sh index 5588f0d26..827ce3540 100644 --- a/tool/test/prepare_release_test.sh +++ b/tool/test/prepare_release_test.sh @@ -57,10 +57,27 @@ printf '%s\n' \ 'esac' > "$FIXTURE/bin/dart" chmod +x "$FIXTURE/bin/dart" ln -s dart "$FIXTURE/bin/flutter" +ln -s /bin/true "$FIXTURE/bin/pana" cp "$REPO_ROOT/tool/prepare_release.sh" "$REPO_ROOT/tool/check_release.sh" \ "$REPO_ROOT/tool/prepare_release_metadata.dart" "$UPSTREAM/tool/" cp "$REPO_ROOT/tool/gh_actions/check_tmp_test.sh" "$UPSTREAM/tool/gh_actions/" +cat > "$UPSTREAM/tool/gh_actions/pana_source.sh" <<'EOF' +#!/bin/bash +set -euo pipefail +[[ $# -eq 2 && -f "$1/pubspec.yaml" ]] || exit 99 +cd "$1" +if [[ "${PWD##*/}" == rohd_devtools_widgets ]]; then + [[ "$2" == flutter ]] || exit 99 +else + [[ "$2" == dart ]] || exit 99 +fi +printf 'pana|%s|pana\n' "$PWD" >> "$SDK_LOG" +if [[ "${FAIL_PACKAGE:-}" == "${PWD##*/}" && "${FAIL_COMMAND:-}" == pana ]]; then + echo 'Simulated check failure: pana' >&2 + exit 71 +fi +EOF printf '%s\n' '#!/bin/bash' \ '[[ -f "$1/build/index.html" && -f "$1/config.yaml" ]] || exit 1' \ 'printf "smoke\n" >> "$STAGE_LOG"' \ @@ -124,7 +141,8 @@ run_case() { local status=0 : > "$SDK_LOG" : > "$STAGE_LOG" - PATH="$FIXTURE/bin" ROHD_ARTIFACT_REPOSITORY="$UPSTREAM" ROHD_ARTIFACT_BRANCH=artifacts \ + PATH="$FIXTURE/bin" PUB_CACHE="$FIXTURE/pub-cache" \ + ROHD_ARTIFACT_REPOSITORY="$UPSTREAM" ROHD_ARTIFACT_BRANCH=artifacts \ /bin/bash "$RELEASE/tool/prepare_release.sh" "$@" > "$FIXTURE/output" 2>&1 || status=$? if [[ "$status" -ne "$expected" ]] || ! grep -Fq "$message" "$FIXTURE/output"; then cat "$FIXTURE/output" @@ -160,8 +178,15 @@ expected_checks() { if [[ "$include_tests" == true ]]; then printf '%s|%s|%s\n' "$sdk" "$directory" test fi + printf 'pana|%s|pana\n' "$directory" } +rm "$FIXTURE/bin/pana" +run_case 2 'Pana is required' rohd_source_navigator +assert_unchanged +[[ ! -s "$STAGE_LOG" ]] +ln -s /bin/true "$FIXTURE/bin/pana" + git -C "$UPSTREAM" commit --quiet --allow-empty -m 'Fixture main advances' readonly MAIN_COMMIT="$(git -C "$UPSTREAM" rev-parse main)" run_case 1 'The release branch does not contain the latest upstream main.' @@ -286,7 +311,7 @@ for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_na export FAIL_PACKAGE="$package" FAIL_COMMAND=test run_case 0 "$package: PASSED" "$package" ! grep -Fq '|test' "$SDK_LOG" - for check_command in 'pub get' 'format --output=none --set-exit-if-changed .' 'analyze --fatal-infos' test; do + for check_command in 'pub get' 'format --output=none --set-exit-if-changed .' 'analyze --fatal-infos' test pana; do export FAIL_COMMAND="$check_command" check_arguments=() include_tests=false From e626b7f181c2f639dbd9563001944cd13342371e Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Wed, 23 Sep 2026 09:22:35 -0700 Subject: [PATCH 3/6] improve packages with READMEs and examples --- packages/rohd_devtools_widgets/README.md | 3 ++ .../rohd_devtools_widgets/example/main.dart | 43 +++++++++++++++++++ packages/rohd_hierarchy/README.md | 3 ++ packages/rohd_hierarchy/example/main.dart | 34 +++++++++++++++ packages/rohd_source_navigator/README.md | 3 ++ .../rohd_source_navigator/example/main.dart | 29 +++++++++++++ packages/rohd_source_navigator/pubspec.yaml | 2 +- packages/rohd_waveform/README.md | 3 ++ packages/rohd_waveform/example/main.dart | 26 +++++++++++ 9 files changed, 145 insertions(+), 1 deletion(-) create mode 100644 packages/rohd_devtools_widgets/example/main.dart create mode 100644 packages/rohd_hierarchy/example/main.dart create mode 100644 packages/rohd_source_navigator/example/main.dart create mode 100644 packages/rohd_waveform/example/main.dart diff --git a/packages/rohd_devtools_widgets/README.md b/packages/rohd_devtools_widgets/README.md index f51ab4d2a..8e5a7e0b7 100644 --- a/packages/rohd_devtools_widgets/README.md +++ b/packages/rohd_devtools_widgets/README.md @@ -70,6 +70,9 @@ across DevTools packages. ## Usage +For a complete runnable example, see +[`example/main.dart`](example/main.dart). + Add the package to your Flutter application: ```shell diff --git a/packages/rohd_devtools_widgets/example/main.dart b/packages/rohd_devtools_widgets/example/main.dart new file mode 100644 index 000000000..cd556c729 --- /dev/null +++ b/packages/rohd_devtools_widgets/example/main.dart @@ -0,0 +1,43 @@ +// Copyright (C) 2026 Intel Corporation +// SPDX-License-Identifier: BSD-3-Clause +// +// main.dart +// Runnable cross-probe button Flutter example. +// +// 2026 September 23 +// Author: Desmond Kirkpatrick + +import 'package:flutter/material.dart'; +import 'package:rohd_devtools_widgets/rohd_devtools_widgets.dart'; + +void main() => runApp(const CrossProbeExample()); + +class CrossProbeExample extends StatefulWidget { + const CrossProbeExample({super.key}); + + @override + State createState() => _CrossProbeExampleState(); +} + +class _CrossProbeExampleState extends State { + final _channel = LocalCrossProbeChannel(); + late final LocalCrossProbeService _service = LocalCrossProbeService( + _channel, + source: 'example', + ); + + @override + void dispose() { + _service.dispose(); + _channel.dispose(); + super.dispose(); + } + + @override + Widget build(BuildContext context) => MaterialApp( + home: Scaffold( + appBar: AppBar(title: const Text('Cross-probe example')), + body: Center(child: CrossProbeButton(service: _service)), + ), + ); +} diff --git a/packages/rohd_hierarchy/README.md b/packages/rohd_hierarchy/README.md index d426f8b1a..608ecf830 100644 --- a/packages/rohd_hierarchy/README.md +++ b/packages/rohd_hierarchy/README.md @@ -116,6 +116,9 @@ transport layer. ## Usage +For a complete runnable example, see +[`example/main.dart`](example/main.dart). + ### Building a dictionary from a netlist ```dart diff --git a/packages/rohd_hierarchy/example/main.dart b/packages/rohd_hierarchy/example/main.dart new file mode 100644 index 000000000..c73d6bc0b --- /dev/null +++ b/packages/rohd_hierarchy/example/main.dart @@ -0,0 +1,34 @@ +// Copyright (C) 2026 Intel Corporation +// SPDX-License-Identifier: BSD-3-Clause +// +// main.dart +// Runnable hierarchy construction and search example. +// +// 2026 September 23 +// Author: Desmond Kirkpatrick + +import 'package:rohd_hierarchy/rohd_hierarchy.dart'; + +void main() { + final root = HierarchyOccurrence( + name: 'top', + signals: [ + SignalOccurrence(name: 'clk', width: 1, direction: 'input'), + SignalOccurrence(name: 'count', width: 8), + ], + children: [ + HierarchyOccurrence( + name: 'counter', + definition: 'Counter', + signals: [SignalOccurrence(name: 'enable', width: 1)], + ), + ], + ); + final hierarchy = BaseHierarchyAdapter.fromTree(root); + final clockSignals = hierarchy.searchSignals('clk'); + + if (clockSignals.length != 1 || + clockSignals.single.path.join('/') != 'top/clk') { + throw StateError('Expected to find the top-level clock signal.'); + } +} diff --git a/packages/rohd_source_navigator/README.md b/packages/rohd_source_navigator/README.md index 3af3e72ad..6c1185380 100644 --- a/packages/rohd_source_navigator/README.md +++ b/packages/rohd_source_navigator/README.md @@ -13,6 +13,9 @@ For Flutter applications, use `flutter pub add rohd_source_navigator`. ## API +For a complete runnable example, see +[`example/main.dart`](example/main.dart). + - `FlcData`, `FlcEntry`, and `FlcFrame`: parse and look up file/line/column traces from v5/v6 FLC hierarchy JSON or embedded netlist trace attributes. - `SourceFrame` and `FrameCycler`: represent source locations and cycle through diff --git a/packages/rohd_source_navigator/example/main.dart b/packages/rohd_source_navigator/example/main.dart new file mode 100644 index 000000000..148fcddf0 --- /dev/null +++ b/packages/rohd_source_navigator/example/main.dart @@ -0,0 +1,29 @@ +// Copyright (C) 2026 Intel Corporation +// SPDX-License-Identifier: BSD-3-Clause +// +// main.dart +// Runnable FLC source-location lookup example. +// +// 2026 September 23 +// Author: Desmond Kirkpatrick + +import 'package:rohd_source_navigator/flc_data.dart'; + +void main() { + final data = FlcData.fromJson({ + 'version': 5, + 'files': ['lib/top.dart'], + 'modules': { + 'Top': { + 'tree': [ + ['0:42:5', 'result'], + ], + }, + }, + }); + + final frames = data.lookupSignal('Top', 'result'); + if (frames?.single.line != 42) { + throw StateError('Expected the result signal at lib/top.dart:42.'); + } +} diff --git a/packages/rohd_source_navigator/pubspec.yaml b/packages/rohd_source_navigator/pubspec.yaml index de739c070..f02cf087f 100644 --- a/packages/rohd_source_navigator/pubspec.yaml +++ b/packages/rohd_source_navigator/pubspec.yaml @@ -11,7 +11,7 @@ environment: sdk: ^3.0.0 dependencies: - json_rpc_2: ^3.0.0 + json_rpc_2: ^4.0.0 web_socket_channel: ^3.0.0 dev_dependencies: diff --git a/packages/rohd_waveform/README.md b/packages/rohd_waveform/README.md index fbdf88556..ef72ba319 100644 --- a/packages/rohd_waveform/README.md +++ b/packages/rohd_waveform/README.md @@ -10,6 +10,9 @@ that needs signal values over time. ## Service +For a complete runnable example, see +[`example/main.dart`](example/main.dart). + `rohd_waveform` provides a small service layer for requesting, caching, and streaming waveform values: diff --git a/packages/rohd_waveform/example/main.dart b/packages/rohd_waveform/example/main.dart new file mode 100644 index 000000000..f0a88666a --- /dev/null +++ b/packages/rohd_waveform/example/main.dart @@ -0,0 +1,26 @@ +// Copyright (C) 2026 Intel Corporation +// SPDX-License-Identifier: BSD-3-Clause +// +// main.dart +// Runnable waveform data construction example. +// +// 2026 September 23 +// Author: Desmond Kirkpatrick + +import 'package:rohd_waveform/rohd_waveform.dart'; + +void main() { + final data = WaveformData( + signalId: 'top/counter', + data: [ + Data(time: 0, value: '0'), + Data(time: 10, value: '1'), + Data(time: 20, value: '0'), + ], + ); + final waveform = SignalWaveform.fromWaveformData(data); + + if (waveform.data.length != 3 || data.startTime != 0 || data.endTime != 20) { + throw StateError('Expected three waveform samples from time 0 to 20.'); + } +} From c5762ade0684289e5666fc0f32481a7ad26c1845 Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Wed, 23 Sep 2026 10:34:33 -0700 Subject: [PATCH 4/6] gate on pana score except for rohd_source_navigator --- .github/workflows/general.yml | 2 +- doc/releases.md | 27 ++++++++++++++------- packages/rohd_devtools_widgets/CHANGELOG.md | 4 +-- tool/gh_actions/pana_source.sh | 14 ++++++++--- tool/test/pana_source_test.sh | 17 +++++++++++-- 5 files changed, 46 insertions(+), 18 deletions(-) diff --git a/.github/workflows/general.yml b/.github/workflows/general.yml index 7a031a52e..d7370f964 100644 --- a/.github/workflows/general.yml +++ b/.github/workflows/general.yml @@ -128,7 +128,7 @@ jobs: - name: Run package tests run: ${{ matrix.sdk }} test - - name: Check hosted dependencies and run Pana + - name: Gate hosted dependencies and Pana score run: bash ../../tool/gh_actions/pana_source.sh . ${{ matrix.sdk }} deploy-documentation: diff --git a/doc/releases.md b/doc/releases.md index 7828fbce1..c6fdefc64 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -92,7 +92,7 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet has separate `Check rohd_hierarchy`, `Check rohd_waveform`, `Check rohd_devtools_widgets`, and `Check rohd_source_navigator` jobs for dependency resolution, formatting, fatal-info analysis, package tests, and - isolated hosted dependency checks and Pana reports. + isolated hosted dependency checks and blocking Pana score gates. These run alongside the root checks and DevTools app job; documentation deployment waits for all of them. Preparation skips local test suites by default and does not query GitHub or @@ -111,7 +111,8 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet web build before preparing metadata, then runs ROHD's checks. Sub-package-only preparation leaves ROHD metadata and DevTools untouched. Each selected sub-package gets dependency resolution, formatting checks, and analysis in its - own directory, plus isolated hosted dependency checks and Pana reports even + own directory, plus isolated hosted dependency checks and blocking Pana score + gates even when tests are skipped. Tests run when `--run-tests` is supplied. Selecting ROHD also compiles and packages a temporary VSIX using the same helper as the VS Code @@ -137,8 +138,8 @@ Preparation runs the following checks before invoking `tool/check_release.sh`: | Selected Package | Default Checks | Added With `--run-tests` | | --- | --- | --- | | `rohd` | `tool/run_checks.sh --skip-tests`: dependencies, formatting, analysis, API docs, and temporary-file checks; then `tool/package_vscode.sh` compiles and packages a temporary VSIX. | Simulator prerequisites and ROHD tests via `tool/run_checks.sh`. | -| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`; also isolated hosted dependency checks and a Pana report. | `dart test` in each selected package. | -| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`; also isolated hosted dependency checks and a Pana report. | `flutter test` in the widgets package. | +| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`; also isolated hosted dependency checks and a blocking Pana score gate. | `dart test` in each selected package. | +| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`; also isolated hosted dependency checks and a blocking Pana score gate. | `flutter test` in the widgets package. | Artifact provenance verification and the DevTools installation smoke test always run when ROHD is selected, even when test suites are skipped. The VSIX packaging @@ -165,11 +166,19 @@ It runs `pub get` and `pub downgrade`, each followed by fatal-info analysis of `lib/`, using the selected SDK. Flutter analysis uses `--no-pub` to preserve the downgraded resolution. Required dependencies must already be available on pub.dev; there is no fallback to local packages. Command failures stop CI and preparation. -Pana's report is printed for review, but package scoring findings such as missing -examples or newer dependency major versions are advisory. No custom report parser -is used. The root's existing no-argument Pana invocation and score gate are -unchanged. Temporary copies are cleaned up on success or failure, and developers' -overrides are never removed or rewritten. +Pana's report is printed for review, and package scoring findings such as missing +examples or newer dependency major versions block CI and preparation, matching +the root package's policy. The runner passes `--exit-code-threshold 0` for every +sub-package, requiring a full score. The sole temporary exception is +`rohd_source_navigator`, which uses threshold `10` while its canonical +`https://github.com/intel/rohd/tree/main/packages/rohd_source_navigator` +repository URL cannot be validated before the path exists on upstream `main`; +remove the exception when [#718](https://github.com/intel/rohd/pull/718) merges. +Hosted dependency resolution, lower-bound analysis, and fatal-info library +analysis remain mandatory for every package before Pana runs. No custom report +parser is used. The root's existing no-argument Pana invocation and score gate +are unchanged. Temporary copies are cleaned up on success or failure, and +developers' overrides are never removed or rewritten. Pana does not run consumer tests. Final override-free tests and archive checks are still required as described below. Tests for the separate DevTools diff --git a/packages/rohd_devtools_widgets/CHANGELOG.md b/packages/rohd_devtools_widgets/CHANGELOG.md index de4f6c66b..891d3c811 100644 --- a/packages/rohd_devtools_widgets/CHANGELOG.md +++ b/packages/rohd_devtools_widgets/CHANGELOG.md @@ -1,8 +1,6 @@ ## 0.1.1 -- Fix the ROHD dependency lower bound: require `^0.6.10` instead of `^0.6.9`, - since signal formatting uses `toRadixString`'s `includeWidth` and `sepChar` - parameters introduced in ROHD 0.6.10. +- Fix the ROHD dependency lower bound: require `^0.6.10` instead of `^0.6.9`, since signal formatting uses `toRadixString`'s `includeWidth` and `sepChar` parameters introduced in ROHD 0.6.10 (). ## 0.1.0 diff --git a/tool/gh_actions/pana_source.sh b/tool/gh_actions/pana_source.sh index dca3a0cc2..ddec29cb1 100755 --- a/tool/gh_actions/pana_source.sh +++ b/tool/gh_actions/pana_source.sh @@ -28,9 +28,16 @@ if ! command -v pana > /dev/null; then fi package_dir="$(cd "$1" && pwd)" +package="${package_dir##*/}" sdk="$2" analyze_arguments=(analyze --fatal-infos) pana_arguments=() +pana_score_threshold=0 +if [[ "$package" == rohd_source_navigator ]]; then + # TODO(desmonddak): https://github.com/intel/rohd/pull/718 Remove this + # exception after the package move is on main and Pana can verify its URL. + pana_score_threshold=10 +fi if [[ "$sdk" == flutter ]]; then flutter_root="${FLUTTER_ROOT:-}" if [[ -z "$flutter_root" ]]; then @@ -60,11 +67,12 @@ if grep -Eq '^[[:space:]]*dependency_overrides[[:space:]]*:' pubspec.yaml; then exit 2 fi -echo "=== ${package_dir##*/}: hosted dependency compatibility ===" +echo "=== $package: hosted dependency compatibility ===" "$sdk" pub get "$sdk" "${analyze_arguments[@]}" lib "$sdk" pub downgrade "$sdk" "${analyze_arguments[@]}" lib -echo "=== ${package_dir##*/}: Pana report (package scores are advisory) ===" -PANA_ANALYSIS_INCLUDES=0 pana "${pana_arguments[@]}" . +echo "=== $package: Pana score gate (threshold $pana_score_threshold) ===" +PANA_ANALYSIS_INCLUDES=0 \ + pana --exit-code-threshold "$pana_score_threshold" "${pana_arguments[@]}" . diff --git a/tool/test/pana_source_test.sh b/tool/test/pana_source_test.sh index 90a9c01a5..dca4a09f9 100644 --- a/tool/test/pana_source_test.sh +++ b/tool/test/pana_source_test.sh @@ -12,6 +12,7 @@ readonly REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" readonly FIXTURE="$(mktemp -d)" trap 'rm -rf "$FIXTURE"' EXIT export SOURCE="$FIXTURE/source package" SDK_LOG="$FIXTURE/sdk.log" +export NAVIGATOR="$FIXTURE/rohd_source_navigator" export PUB_CACHE="$FIXTURE/pub cache" TMPDIR="$FIXTURE/temp space" export FLUTTER_ROOT="$FIXTURE/flutter sdk" PANA_ANALYSIS_INCLUDES=1 @@ -27,6 +28,8 @@ for file in pubspec.lock pubspec_overrides.yaml analysis_options.yaml \ printf 'checkout-only state\n' > "$SOURCE/$file" done cp -R "$SOURCE" "$FIXTURE/original" +cp -R "$SOURCE" "$NAVIGATOR" +cp -R "$NAVIGATOR" "$FIXTURE/original-navigator" cat > "$FIXTURE/bin/dart" <<'EOF' #!/bin/bash @@ -64,9 +67,11 @@ if [[ "$PWD" == "$SOURCE" ]]; then else [[ "$PWD" == "$TMPDIR"/rohd-pana.*/package && "$PANA_ANALYSIS_INCLUDES" == 0 ]] if [[ "$EXPECTED_SDK" == flutter ]]; then - [[ $# -eq 3 && "$1" == --flutter-sdk && "$2" == "$EXPECTED_FLUTTER_ROOT" && "$3" == . ]] + [[ $# -eq 5 && "$1" == --exit-code-threshold && "$2" == "$EXPECTED_THRESHOLD" && + "$3" == --flutter-sdk && "$4" == "$EXPECTED_FLUTTER_ROOT" && "$5" == . ]] else - [[ $# -eq 1 && "$1" == . ]] + [[ $# -eq 3 && "$1" == --exit-code-threshold && "$2" == "$EXPECTED_THRESHOLD" && + "$3" == . ]] fi printf 'changed by Pana\n' > pubspec.yaml fi @@ -75,6 +80,7 @@ exit "${PANA_STATUS:-0}" EOF chmod +x "$PUB_CACHE/bin/pana" export EXPECTED_FLUTTER_ROOT="$FLUTTER_ROOT" +export EXPECTED_THRESHOLD=0 cd "$SOURCE" passed=0 @@ -90,6 +96,7 @@ run_case() { exit 1 fi diff -ru "$FIXTURE/original" "$SOURCE" + diff -ru "$FIXTURE/original-navigator" "$NAVIGATOR" [[ -z "$(find "$TMPDIR" -mindepth 1 -print -quit)" ]] passed=$((passed + 1)) } @@ -103,6 +110,7 @@ run_case 2 "$FIXTURE/missing" dart for sdk in dart flutter; do export EXPECTED_SDK="$sdk" + export EXPECTED_THRESHOLD=0 analyze='analyze --fatal-infos' if [[ "$sdk" == flutter ]]; then analyze+=' --no-pub'; fi analyze+=' lib' @@ -117,7 +125,12 @@ for sdk in dart flutter; do done done +export EXPECTED_SDK=dart EXPECTED_THRESHOLD=10 +run_case 0 "$NAVIGATOR" dart +[[ "$(cat "$SDK_LOG")" == $'dart|pub get\ndart|analyze --fatal-infos lib\ndart|pub downgrade\ndart|analyze --fatal-infos lib\npana' ]] + mv "$PUB_CACHE/bin/pana" "$FIXTURE/pana" +export EXPECTED_THRESHOLD=0 run_case 2 "$SOURCE" dart grep -q 'Pana is required' "$FIXTURE/output" [[ ! -s "$SDK_LOG" ]] From c816e86d529dad764400def17455db66313389c2 Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Wed, 23 Sep 2026 10:43:23 -0700 Subject: [PATCH 5/6] bring dart up to 3.4.0 to support json_rpc2 at 4.1.0 --- packages/rohd_source_navigator/pubspec.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/rohd_source_navigator/pubspec.yaml b/packages/rohd_source_navigator/pubspec.yaml index f02cf087f..06280e3d1 100644 --- a/packages/rohd_source_navigator/pubspec.yaml +++ b/packages/rohd_source_navigator/pubspec.yaml @@ -8,7 +8,7 @@ repository: https://github.com/intel/rohd/tree/main/packages/rohd_source_navigat issue_tracker: https://github.com/intel/rohd/issues environment: - sdk: ^3.0.0 + sdk: '>=3.4.0 <4.0.0' dependencies: json_rpc_2: ^4.0.0 From a8b992c5defd7e5da4284d6de89d145f3ece43cf Mon Sep 17 00:00:00 2001 From: "Desmond A. Kirkpatrick" Date: Wed, 23 Sep 2026 12:17:51 -0700 Subject: [PATCH 6/6] CI coverage for tool/test regression suite, pana opt-in for release prep --- .github/workflows/general.yml | 37 ++++++++++++++++++++++++++++++ doc/releases.md | 38 +++++++++++++++++++------------ tool/prepare_release.sh | 38 ++++++++++++++++++++++--------- tool/test/prepare_release_test.sh | 24 ++++++++++++++++--- 4 files changed, 109 insertions(+), 28 deletions(-) diff --git a/.github/workflows/general.yml b/.github/workflows/general.yml index d7370f964..22902495b 100644 --- a/.github/workflows/general.yml +++ b/.github/workflows/general.yml @@ -78,6 +78,43 @@ jobs: with: runCmd: ROHD_REQUIRE_VERILATOR=1 tool/gh_actions/run_tests.sh + shell-regression-tests: + name: Shell Regression Tests + permissions: {} + timeout-minutes: 30 + runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }} + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Setup Flutter SDK + uses: flutter-actions/setup-flutter@v2 + with: + channel: stable + version: 3.44.0 + + - name: Install root Dart dependencies + run: dart pub get + + - name: Install DevTools application dependencies + working-directory: rohd_devtools_extension + run: flutter pub get + + - name: Run shell regression suites + shell: bash + run: | + set -euo pipefail + shopt -s nullglob + suites=(tool/test/*_test.sh) + ((${#suites[@]})) || { + echo 'No shell regression suites found.' >&2 + exit 1 + } + for suite in "${suites[@]}"; do + echo "=== $suite ===" + bash "$suite" + done + sub-package-checks: name: Check ${{ matrix.package }} permissions: {} diff --git a/doc/releases.md b/doc/releases.md index c6fdefc64..f6f745f5b 100644 --- a/doc/releases.md +++ b/doc/releases.md @@ -111,10 +111,9 @@ with a merge or rebase; the preparation PR itself does not need to be merged yet web build before preparing metadata, then runs ROHD's checks. Sub-package-only preparation leaves ROHD metadata and DevTools untouched. Each selected sub-package gets dependency resolution, formatting checks, and analysis in its - own directory, plus isolated hosted dependency checks and blocking Pana score - gates even - when tests are skipped. - Tests run when `--run-tests` is supplied. Selecting ROHD also + own directory. Tests run when `--run-tests` is supplied, and isolated hosted + dependency checks plus the blocking Pana score gate run when `--run-pana` is + supplied. Selecting ROHD also compiles and packages a temporary VSIX using the same helper as the VS Code release workflow, even when test suites are skipped. Only after all enabled checks for selected packages pass does it run @@ -138,8 +137,8 @@ Preparation runs the following checks before invoking `tool/check_release.sh`: | Selected Package | Default Checks | Added With `--run-tests` | | --- | --- | --- | | `rohd` | `tool/run_checks.sh --skip-tests`: dependencies, formatting, analysis, API docs, and temporary-file checks; then `tool/package_vscode.sh` compiles and packages a temporary VSIX. | Simulator prerequisites and ROHD tests via `tool/run_checks.sh`. | -| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`; also isolated hosted dependency checks and a blocking Pana score gate. | `dart test` in each selected package. | -| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`; also isolated hosted dependency checks and a blocking Pana score gate. | `flutter test` in the widgets package. | +| `rohd_hierarchy`, `rohd_waveform`, `rohd_source_navigator` | In each package directory: `dart pub get`, `dart format --output=none --set-exit-if-changed .`, then `dart analyze --fatal-infos`. | `dart test` with `--run-tests`; isolated hosted dependency checks and a blocking Pana score gate with `--run-pana`. | +| `rohd_devtools_widgets` | In its package directory: `flutter pub get`, `dart format --output=none --set-exit-if-changed .`, then `flutter analyze --fatal-infos`. | `flutter test` with `--run-tests`; isolated hosted dependency checks and a blocking Pana score gate with `--run-pana`. | Artifact provenance verification and the DevTools installation smoke test always run when ROHD is selected, even when test suites are skipped. The VSIX packaging @@ -157,7 +156,8 @@ prerequisite or enabled check; no publication dry runs start unless all enabled checks pass. An early failure such as a nonempty `tmp_test` directory means later stages have not run. Review leftover test files before retrying. The ordinary package checks use the current checkout's dependency overrides. -Both CI and preparation reuse the existing Pana runner: +CI always reuses the existing Pana runner, while local preparation runs it only +with `--run-pana`: `bash tool/gh_actions/pana_source.sh packages/ `. Its package mode uses a disposable copy without checkout overrides, lockfiles, generated resolution/build state, or repository-relative analyzer configuration. @@ -175,10 +175,12 @@ sub-package, requiring a full score. The sole temporary exception is repository URL cannot be validated before the path exists on upstream `main`; remove the exception when [#718](https://github.com/intel/rohd/pull/718) merges. Hosted dependency resolution, lower-bound analysis, and fatal-info library -analysis remain mandatory for every package before Pana runs. No custom report -parser is used. The root's existing no-argument Pana invocation and score gate -are unchanged. Temporary copies are cleaned up on success or failure, and -developers' overrides are never removed or rewritten. +analysis remain mandatory whenever Pana runs. No custom report parser is used. +The root's existing no-argument Pana invocation and score gate are unchanged. +Temporary copies are cleaned up on success or failure, and developers' overrides +are never removed or rewritten. Default local preparation reports skipped Pana +gates explicitly; verify the CI result for the exact release commit before +publishing when they are skipped. Pana does not run consumer tests. Final override-free tests and archive checks are still required as described below. Tests for the separate DevTools @@ -193,6 +195,9 @@ tool/prepare_release.sh # All five packages, also running their test suites locally: tool/prepare_release.sh --run-tests +# All five packages, also running hosted dependency and Pana score gates: +tool/prepare_release.sh --run-pana + # ROHD only: tool/prepare_release.sh rohd @@ -208,12 +213,12 @@ tool/prepare_release.sh rohd_hierarchy rohd_waveform # Only source navigator: tool/prepare_release.sh rohd_source_navigator -# Source navigator and widgets, including both package test suites: -tool/prepare_release.sh --run-tests rohd_source_navigator rohd_devtools_widgets +# Source navigator and widgets, including package tests and Pana score gates: +tool/prepare_release.sh --run-tests --run-pana rohd_source_navigator rohd_devtools_widgets ``` Preparation requires Dart for YAML metadata parsing using the root package's -dependencies. Selecting any sub-package also requires Pana, installed with +dependencies. `--run-pana` also requires Pana, installed with `bash tool/gh_actions/install_pana.sh`, and network access to hosted dependencies. Selecting widgets also requires Flutter, including the default all-package selection. The Pana runner discovers Flutter from its executable or uses @@ -267,6 +272,11 @@ They allow real Dart execution only for the metadata helper, never for publicati commands. Its focused metadata tests run with `dart test test/prepare_release_metadata_test.dart`. +The General workflow's blocking `Shell Regression Tests` job discovers and runs +every `tool/test/*_test.sh` suite on pull requests and `main`. It installs the +root Dart dependencies and the DevTools application's Flutter dependencies so +the DevTools artifact-discovery regression uses the real loader; all other +shell suites retain their own isolated fixtures. ## Publication Order diff --git a/tool/prepare_release.sh b/tool/prepare_release.sh index bfe6029f1..2b5e96711 100755 --- a/tool/prepare_release.sh +++ b/tool/prepare_release.sh @@ -28,18 +28,18 @@ # Each selected sub-package gets dependency resolution, a non-writing format check, # and analysis (including fatal infos) in its own directory. Dart is used # for hierarchy/waveform/source navigator, Flutter for widgets, and dart format -# for all sub-packages. The existing Pana runner also checks hosted dependencies -# with pub get, pub downgrade, and library analysis in an override-free copy. -# Test suites are skipped by default; verify CI results for the release commit. -# Add --run-tests to also run all selected package suites locally, including -# ROHD's simulator prerequisites when ROHD is selected. +# for all sub-packages. Test suites and the isolated hosted Pana score gate are +# skipped by default; verify CI results for the release commit. Add --run-tests +# to also run all selected package suites locally, including ROHD's simulator +# prerequisites when ROHD is selected. Add --run-pana to run hosted dependency +# resolution, pub downgrade, library analysis, and the Pana score gate. # Only after all selected checks pass do publication dry runs start. # It never publishes, commits, tags, pushes, merges, or rebases. # # Dart is required to read YAML metadata using the root package's dependencies. # Selecting ROHD also requires Node.js and npm (release CI uses Node.js 24). -# Selecting rohd_devtools_widgets also requires Flutter. Selecting any sub-package -# requires Pana (tool/gh_actions/install_pana.sh) and hosted dependencies. +# Selecting rohd_devtools_widgets also requires Flutter. --run-pana requires +# Pana (tool/gh_actions/install_pana.sh) and hosted dependencies. # Any failed prerequisite or package check stops preparation before dry runs. # # Examples: @@ -81,21 +81,24 @@ export DASH__SUPPRESS_ANALYTICS=true export FLUTTER_SUPPRESS_ANALYTICS=true if [[ $# -eq 1 && "$1" == '--help' ]]; then - echo "Usage: $0 [--run-tests] [package ...]" + echo "Usage: $0 [--run-tests] [--run-pana] [package ...]" echo "Packages: rohd rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator" echo "Defaults to all five packages, using each package's pubspec.yaml version." echo "Test suites are skipped by default; use --run-tests to include them." + echo "Pana score checks are skipped by default; use --run-pana to include them." echo "Artifact verification and its smoke test still run when ROHD is selected." echo "Selecting ROHD also checks VSIX packaging (requires Node.js and npm)." - echo "Sub-packages also require Pana and always check hosted dependency lower bounds." echo "Prepares metadata, runs package checks and publication dry runs; never uploads packages." exit 0 fi run_tests=false +run_pana=false packages=() for argument in "$@"; do if [[ "$argument" == '--run-tests' ]]; then run_tests=true + elif [[ "$argument" == '--run-pana' ]]; then + run_pana=true else packages+=("$argument") fi @@ -114,11 +117,17 @@ if [[ "$run_tests" == true ]]; then else echo "Test suites skipped; verify CI results for the release commit. Use --run-tests to run them locally." fi +if [[ "$run_pana" == true ]]; then + echo "Pana score checks enabled for selected sub-packages (--run-pana)." +else + echo "Pana score checks skipped; verify CI results for the release commit. Use --run-pana to run them locally." +fi prepare_rohd=false for package in "$@"; do if [[ "$package" == rohd ]]; then prepare_rohd=true - elif ! PATH="$PATH:${PUB_CACHE:-$HOME/.pub-cache}/bin" command -v pana > /dev/null; then + elif [[ "$run_pana" == true ]] && + ! PATH="$PATH:${PUB_CACHE:-$HOME/.pub-cache}/bin" command -v pana > /dev/null; then echo "Pana is required; run tool/gh_actions/install_pana.sh first." >&2 exit 2 fi @@ -222,7 +231,11 @@ for package in "$@"; do echo "=== $package: tests skipped (use --run-tests) ===" fi ) - bash "$SCRIPT_DIR/gh_actions/pana_source.sh" "$REPO_ROOT/packages/$package" "$sdk" + if [[ "$run_pana" == true ]]; then + bash "$SCRIPT_DIR/gh_actions/pana_source.sh" "$REPO_ROOT/packages/$package" "$sdk" + else + echo "=== $package: Pana score gate skipped (use --run-pana) ===" + fi done git diff --check bash "$SCRIPT_DIR/check_release.sh" "$@" @@ -242,3 +255,6 @@ EOF if [[ "$run_tests" == false ]]; then echo "Test suites were not run. Verify CI results for the release commit before publishing." fi +if [[ "$run_pana" == false ]]; then + echo "Pana score gates were not run. Verify CI results for the release commit before publishing." +fi diff --git a/tool/test/prepare_release_test.sh b/tool/test/prepare_release_test.sh index 827ce3540..963b34032 100644 --- a/tool/test/prepare_release_test.sh +++ b/tool/test/prepare_release_test.sh @@ -167,6 +167,7 @@ assert_unchanged() { expected_checks() { local package="$1" local include_tests="${2:-false}" + local include_pana="${3:-false}" local sdk=dart if [[ "$package" == rohd_devtools_widgets ]]; then sdk=flutter @@ -178,11 +179,13 @@ expected_checks() { if [[ "$include_tests" == true ]]; then printf '%s|%s|%s\n' "$sdk" "$directory" test fi - printf 'pana|%s|pana\n' "$directory" + if [[ "$include_pana" == true ]]; then + printf 'pana|%s|pana\n' "$directory" + fi } rm "$FIXTURE/bin/pana" -run_case 2 'Pana is required' rohd_source_navigator +run_case 2 'Pana is required' --run-pana rohd_source_navigator assert_unchanged [[ ! -s "$STAGE_LOG" ]] ln -s /bin/true "$FIXTURE/bin/pana" @@ -209,6 +212,7 @@ run_case 0 "DevTools source commit (upstream main): $MAIN_COMMIT" [[ "$(cat "$STAGE_LOG")" == $'smoke\nchecks-skip-tests\nvsix\ndry-run\ndry-run\ndry-run\ndry-run\ndry-run' ]] [[ ! -e "$(cat "$VSIX_PATH_LOG")" ]] grep -Fq 'Test suites were not run.' "$FIXTURE/output" +grep -Fq 'Pana score gates were not run.' "$FIXTURE/output" expected_log="$( for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do expected_checks "$package" @@ -245,6 +249,7 @@ expected_log="$( )" [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] ! grep -Fq 'Test suites were not run.' "$FIXTURE/output" +grep -Fq 'Pana score gates were not run.' "$FIXTURE/output" run_case 0 "DevTools source commit (upstream main): $MAIN_COMMIT" rohd [[ "$(cat "$SDK_LOG")" == "dart|$RELEASE|pub publish --dry-run" ]] @@ -307,6 +312,16 @@ expected_log="$( [[ "$(cat "$RELEASE/lib/src/utilities/config.dart")" == "static const String version = '0.0.0';" ]] [[ "$(cat "$RELEASE/CHANGELOG.md")" == '## Next Release' ]] +run_case 0 'rohd_source_navigator: PASSED' --run-pana rohd_source_navigator +expected_log="$( + expected_checks rohd_source_navigator false true + printf 'dart|%s|pub publish --dry-run\n' "$RELEASE/packages/rohd_source_navigator" +)" +[[ "$(cat "$SDK_LOG")" == "$expected_log" ]] +[[ "$(cat "$STAGE_LOG")" == 'dry-run' ]] +grep -Fq 'Test suites were not run.' "$FIXTURE/output" +! grep -Fq 'Pana score gates were not run.' "$FIXTURE/output" + for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_navigator; do export FAIL_PACKAGE="$package" FAIL_COMMAND=test run_case 0 "$package: PASSED" "$package" @@ -318,6 +333,8 @@ for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_na if [[ "$check_command" == test ]]; then check_arguments+=(--run-tests) include_tests=true + elif [[ "$check_command" == pana ]]; then + check_arguments+=(--run-pana) fi run_case 71 "Simulated check failure: $check_command" "${check_arguments[@]}" "$package" rohd_hierarchy rohd_waveform [[ ! -s "$STAGE_LOG" ]] @@ -327,7 +344,8 @@ for package in rohd_hierarchy rohd_waveform rohd_devtools_widgets rohd_source_na if [[ "$expected_line" == *"|$check_command" ]]; then break fi - done < <(expected_checks "$package" "$include_tests") + done < <(expected_checks "$package" "$include_tests" \ + "$([[ "$check_command" == pana ]] && echo true || echo false)") )" [[ "$(cat "$SDK_LOG")" == "$expected_log" ]] done