Conversation
There was a problem hiding this comment.
Pull request overview
Adds a self-contained demos/ area to showcase Prism’s CLI and Python API flows using role/collection fixtures, plus committed “expected output” artifacts and a small CI workflow tweak to support docs generation.
Changes:
- Added runnable demo entrypoints (
run_cli_demos.sh,api_demo.py,api_runbook_demo.py) and documentation (demos/README.md). - Added Ansible fixtures for a demo role and a demo collection (roles + multiple plugin types).
- Added committed demo output artifacts under
demos/output/and updated.github/workflows/prism.ymlto install dev extras.
Reviewed changes
Copilot reviewed 54 out of 54 changed files in this pull request and generated 8 comments.
Show a summary per file
| File | Description |
|---|---|
| demos/run_cli_demos.sh | Runs a sequence of Prism CLI demo commands and writes outputs to demos/output/. |
| demos/output/roles/sample_role.md | Generated role documentation artifact for the collection’s sample_role. |
| demos/output/roles/ops_role.md | Generated role documentation artifact for the collection’s ops_role. |
| demos/output/role_demo_with_runbook_csv.md | Generated role doc artifact including runbook CSV output configuration. |
| demos/output/role_demo_with_runbook.md | Generated role doc artifact including runbook markdown output configuration. |
| demos/output/role_demo_detailed.md | Generated “detailed catalog” role documentation artifact. |
| demos/output/role_demo_RUNBOOK.md | Generated standalone runbook markdown artifact for role_demo. |
| demos/output/role_demo_RUNBOOK.csv | Generated standalone runbook CSV artifact for role_demo. |
| demos/output/role_demo_README.md | Generated “default” role README artifact for role_demo. |
| demos/output/role_demo.json | Generated JSON scan artifact for role_demo. |
| demos/output/collection_runbooks_csv/sample_role.runbook.csv | Generated per-role runbook CSV artifact for sample_role. |
| demos/output/collection_runbooks_csv/ops_role.runbook.csv | Generated per-role runbook CSV artifact for ops_role. |
| demos/output/collection_runbooks/sample_role.runbook.md | Generated per-role runbook markdown artifact for sample_role. |
| demos/output/collection_runbooks/ops_role.runbook.md | Generated per-role runbook markdown artifact for ops_role. |
| demos/output/collection_demo_detailed.md | Generated “detailed” collection documentation artifact. |
| demos/output/collection_demo.md | Generated collection documentation artifact. |
| demos/output/collection_demo.json | Generated JSON scan artifact for the demo collection. |
| demos/output/README.md | Explains how to recreate the committed demo output artifacts. |
| demos/fixtures/role_demo/templates/demo-service.conf.j2 | Template fixture used by the role_demo role. |
| demos/fixtures/role_demo/tasks/prepare.yml | Role fixture tasks for creating user/group prerequisites. |
| demos/fixtures/role_demo/tasks/main.yml | Role fixture entrypoint tasks, includes runbook/note annotations. |
| demos/fixtures/role_demo/tasks/deploy.yml | Role fixture deploy tasks, includes warning annotation and handler notify. |
| demos/fixtures/role_demo/meta/main.yml | Role fixture Galaxy metadata. |
| demos/fixtures/role_demo/handlers/main.yml | Role fixture handlers. |
| demos/fixtures/role_demo/defaults/main.yml | Role fixture default variables. |
| demos/fixtures/collection_demo/roles/sample_role/templates/sample-role.txt.j2 | Template fixture for sample_role. |
| demos/fixtures/collection_demo/roles/sample_role/tasks/main.yml | sample_role main tasks including a runbook annotation. |
| demos/fixtures/collection_demo/roles/sample_role/tasks/configure.yml | sample_role configure tasks including template + debug. |
| demos/fixtures/collection_demo/roles/sample_role/meta/main.yml | sample_role Galaxy metadata. |
| demos/fixtures/collection_demo/roles/sample_role/handlers/main.yml | sample_role handler fixture. |
| demos/fixtures/collection_demo/roles/sample_role/defaults/main.yml | sample_role defaults fixture. |
| demos/fixtures/collection_demo/roles/ops_role/tasks/main.yml | ops_role tasks including runbook/note annotations. |
| demos/fixtures/collection_demo/roles/ops_role/meta/main.yml | ops_role Galaxy metadata. |
| demos/fixtures/collection_demo/roles/ops_role/handlers/main.yml | ops_role handler fixture. |
| demos/fixtures/collection_demo/roles/ops_role/defaults/main.yml | ops_role defaults fixture. |
| demos/fixtures/collection_demo/plugins/test/demo_tests.py | Demo Jinja test plugin fixture for plugin inventory coverage. |
| demos/fixtures/collection_demo/plugins/strategy/demo_strategy.py | Demo strategy plugin fixture. |
| demos/fixtures/collection_demo/plugins/modules/demo_report.py | Demo module plugin fixture. |
| demos/fixtures/collection_demo/plugins/modules/demo_ping.py | Demo module plugin fixture. |
| demos/fixtures/collection_demo/plugins/module_utils/http_helpers.py | Demo module_utils fixture for plugin breadth. |
| demos/fixtures/collection_demo/plugins/lookup/environment_lookup.py | Demo lookup plugin fixture. |
| demos/fixtures/collection_demo/plugins/lookup/demo_lookup.py | Demo lookup plugin fixture. |
| demos/fixtures/collection_demo/plugins/inventory/demo_inventory.py | Demo inventory plugin fixture. |
| demos/fixtures/collection_demo/plugins/filter/demo_filters.py | Demo filter plugin fixture. |
| demos/fixtures/collection_demo/plugins/doc_fragments/common_options.py | Demo doc_fragments fixture. |
| demos/fixtures/collection_demo/plugins/connection/demo_connection.py | Demo connection plugin fixture. |
| demos/fixtures/collection_demo/plugins/callback/demo_callback.py | Demo callback plugin fixture. |
| demos/fixtures/collection_demo/plugins/callback/audit_callback.py | Second callback fixture for breadth. |
| demos/fixtures/collection_demo/galaxy.yml | Demo collection Galaxy metadata. |
| demos/fixtures/collection_demo/README.md | Minimal README so galaxy.yml has a concrete readme target. |
| demos/api_runbook_demo.py | API demo: render runbook markdown + CSV from a role scan. |
| demos/api_demo.py | API demo: scan role + collection and print a small JSON summary. |
| demos/README.md | Top-level docs for running the demos and expected outputs. |
| .github/workflows/prism.yml | CI workflow adjustments (env/permissions, dev extras install, action version change). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `configure.yml` | [Render sample role template output](#task-configure-yml-render-sample-role-template-output-3) | ansible.builtin.template | mode='0644' | - | | ||
| | `configure.yml` | [Print collection demo tags](#task-configure-yml-print-collection-demo-tags-4) | ansible.builtin.debug | msg='Collection tags: {{ collection_demo_tags | join('', '') }}' | - | |
There was a problem hiding this comment.
This parameter rendering shows join('', ''), which is confusing/misleading compared to the actual task source (join(', ')). If these demo artifacts are meant to be read by users, consider adjusting the parameter-serialization logic to render quotes in a human-readable way (e.g., prefer double quotes) and re-generate the demo output.
| | `deploy.yml` | [Render demo service configuration](#task-deploy-yml-render-demo-service-configuration-6) | ansible.builtin.template | mode='0644' | - | | ||
| | `deploy.yml` | [Verify configured feature flags](#task-deploy-yml-verify-configured-feature-flags-7) | ansible.builtin.debug | msg='Enabled features: {{ demo_feature_flags | join('', '') }}' | - | |
There was a problem hiding this comment.
Same readability issue as in the collection role output: the extracted parameter string renders as join('', '') instead of the source join(', '), which is easy to misinterpret. Consider improving the parameter rendering/escaping and re-generating this committed demo artifact.
| "collection": { | ||
| "path": "/raid5/source/test/prism/demos/fixtures/collection_demo", | ||
| "metadata": { | ||
| "namespace": "demo", |
There was a problem hiding this comment.
This committed JSON demo output embeds an absolute local filesystem path (/raid5/source/test/...). That makes the artifact non-portable and can leak environment-specific details. Consider removing/sanitizing absolute paths in demo outputs (e.g., store relative paths or omit the path fields) before committing.
| - name: Set up Python | ||
| uses: actions/setup-python@v6 | ||
| uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: ${{ matrix.python-version }} | ||
|
|
There was a problem hiding this comment.
actions/setup-python is downgraded to @v5 while the repo’s other workflow(s) use @v6 and this workflow also forces JavaScript actions onto Node 24. To avoid runtime/compatibility issues and keep workflows consistent, use actions/setup-python@v6 here as well (or remove the Node24 forcing if @v5 is required).
| - name: Set up Python | ||
| uses: actions/setup-python@v6 | ||
| uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.14" | ||
|
|
There was a problem hiding this comment.
Same issue as the tests job: actions/setup-python@v5 here is inconsistent with other workflows using @v6, and may be incompatible with the FORCE_JAVASCRIPT_ACTIONS_TO_NODE24 setting. Align on actions/setup-python@v6 to reduce CI break risk.
| "role_counters": { | ||
| "task_files": role_counters.get("task_files", 0), | ||
| "tasks": role_counters.get("tasks", 0), | ||
| "handlers": role_counters.get("handlers", 0), | ||
| "templates": role_counters.get("templates", 0), | ||
| }, |
There was a problem hiding this comment.
scanner_counters from scan_role() does not include keys like task_files, tasks, handlers, or templates (it focuses on variable/default-filter counters). As written, this demo will almost always print zeros. Consider sourcing these numbers from payload['metadata']['features'] (e.g. task_files_scanned, tasks_scanned) and/or payload['metadata']['doc_insights']['task_summary'] instead.
| - [ops_role](roles/ops_role.md): task_files=0, templates=0 | ||
| - [sample_role](roles/sample_role.md): task_files=0, templates=0 |
There was a problem hiding this comment.
The per-role summary shows task_files=0, templates=0, but the scanned roles in this fixture do contain task files/templates. This appears to come from using metadata.scanner_counters.task_files/templates, which aren’t populated by scan_role(). For demo accuracy, regenerate this file after fixing the counter source (e.g., use metadata.features.task_files_scanned and count templates/tasks from the catalog).
| - [ops_role](roles/ops_role.md): task_files=0, templates=0 | ||
| - [sample_role](roles/sample_role.md): task_files=0, templates=0 |
There was a problem hiding this comment.
Same as collection_demo.md: role rows report task_files=0, templates=0 even though the fixtures have content. If this output is meant to be committed as a demo artifact, it should be regenerated once the role counter source is corrected.
added some demos