@sabrish/power-platform-solution-blueprint 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to Power Platform Solution Blueprint will be documented in t
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] — 2026-10-10
+
+Fixes same-entity cross-entity false positives and PPTB rendering of the README, adds SRI hashes and publish-workflow hardening, removes `npm-shrinkwrap.json`, and adds the tool icon, vitest suite and manifest validation.
+
+### Added
+- **PPTB tool icon** — `public/icon/ppsb.svg` (copied to `dist/icon/`) is set as the `icon` field in `package.json`.
+- **Unit test suite (vitest)** — `pnpm test` runs `vitest run`. Tests are co-located as `*.test.ts` under `src/`.
+- **Manifest validation** — `pnpm validate` runs `pptb-validate` against the PPTB manifest.
+
+### Changed
+- **`@pptb/types` upgraded to `^1.2.6`** (was `v1.0.19+`).
+- **Publish workflow runs tests** before publishing to npm.
+- **Publish workflow split into build and publish jobs** — `dist/` is handed to the publish job as a workflow artifact.
+- **Orchestrator and gate documentation aligned with actual `/pre-commit` and `/push-branch` behaviour** — each commit is gated individually by `/pre-commit`; `/push-branch` runs the full pre-PR gate before pushing.
+
+### Fixed
+- **Same-entity flows and classic workflows no longer reported as cross-entity** — entity set names in definitions (for example `accounts`) are resolved to logical names (for example `account`) before the cross-entity comparison.
+- **Operation detection prefers `operationId`** over the action name when identifying the Dataverse operation.
+- **Path entity regex accepts digits** in entity logical names.
+- **README images and links render in PPTB** (#46) — raw HTML removed from the README, absolute URLs used for images and documentation links, links to missing `docs/examples` removed, and the PPSB icon added to the header.
+- **README badges replaced by a text version line** (Refs #46) — PPTB's README viewer blocks `img.shields.io` images, so the version and status badges are now the plain-text line `**Version:** 1.5.0 · **Status:** Stable`.
+
+### Security
+- **SRI hashes on pinned CDN scripts** — the Mermaid 10.9.1 and Cytoscape 3.33.1 `<script>` tags in the HTML export carry `integrity` (sha384) and `crossorigin` attributes.
+- **Publish workflow permissions hardened** — `id-token: write` is scoped to a dedicated publish job (the build/test job is read-only); publishing is restricted to releases or `main`; the unused `workflow_dispatch` `version` input is removed.
+- **HTML export escapes global choice option values** before writing them to the exported HTML.
+
+### Removed
+- **Preview badges from Cross-Entity Automation** — removed from the app and from the HTML export.
+- **`npm-shrinkwrap.json` and its generation process** — the file is no longer committed or published. The PPTB intake ignores it (pptb-web #109, desktop-app #652 / #644), PPTB Desktop installs tools via tar extraction and never reads it, and npm 12 cannot generate it. The development lockfile remains `pnpm-lock.yaml`.
+
+### Technical
+- **Release flow** — no longer regenerates a shrinkwrap; `npm version` now updates only `package.json`.
+
+---
+
+## [1.4.0] — 2026-07-01
+
+### Added
+- **AI-friendly Markdown export — YAML frontmatter and flat headings** — all generated Markdown files now include YAML frontmatter blocks with metadata (`blueprint_type`, logical name, display name, counts, version); entity overview sections include Dataverse description as blockquote for self-contained AI agent reading; cross-entity trace sections replace `<details>`/`<summary>` HTML collapsed blocks with flat `###` headings so content is visible to AI agents and rendered expanded in ADO Wiki
+
+### Changed
+- **Markdown export headings in cross-entity trace** — replaced `<details>`/`<summary>` HTML collapsed sections with flat `###` headings (H3) for improved readability in AI agents and Azure DevOps Wiki rendering
+
+### Technical
+- **MarkdownFormatter new static helpers** — `formatFrontmatter(fields)` generates YAML with proper escaping (string quoting for colons/hashes/newlines, YAML 1.1 literal detection, array flow sequences with per-item escaping); `formatBlockquote(text)` handles multi-line blockquotes with proper indentation
+- **`extractPublisherPrefix` refactoring** — moved 4th duplicate into `src/core/utils/entityName.ts` as named export; `MarkdownReporter.ts` imports it; pre-existing duplicates in `ERDGenerator.ts` and `SolutionDistributionAnalyzer.ts` tracked for follow-up consolidation
+- **Version import consolidation** — both `MarkdownReporter.ts` and `JsonReporter.ts` now import `version` from `package.json` (matching pattern)
+
+---
+
 ## [1.3.0] - 2026-06-23
 
 ### Added

package/README.md

@@ -1,9 +1,10 @@
+![PPSB](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/public/icon/ppsb.svg)
+
 # Power Platform Solution Blueprint (PPSB)
 
 > Complete architectural blueprints for your Power Platform solutions.
 
-![Version](https://img.shields.io/badge/version-1.1.2-blue)
-![Status](https://img.shields.io/badge/status-stable-green)
+**Version:** 1.5.0 · **Status:** Stable
 
 Generate comprehensive technical documentation for Dataverse and Power Platform solutions with automated discovery, analysis, and export capabilities.
 
@@ -21,8 +22,7 @@ PPSB benefits **solution architects** (system documentation), **developers** (on
 
 ## ✨ Key Features
 
-<details>
-<summary><b>📋 Discovery & Documentation</b> (click to expand)</summary>
+### 📋 Discovery & Documentation
 
 - **Entities**: Complete schema (fields, relationships, keys, alternate keys)
 - **Plugins**: Full registration details with execution order analysis
@@ -36,12 +36,9 @@ PPSB benefits **solution architects** (system documentation), **developers** (on
 - **Connection References**: Premium connector detection for licensing
 - **Global Choices**: Shared option sets with usage tracking
 - **Security**: Roles, field security profiles, attribute masking, column security
-- See [SUPPORTED_COMPONENTS.md](./SUPPORTED_COMPONENTS.md) for the full component status list — Supported, Partial, and Planned.
-
-</details>
+- See [SUPPORTED_COMPONENTS.md](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/SUPPORTED_COMPONENTS.md) for the full component status list — Supported, Partial, and Planned.
 
-<details>
-<summary><b>📊 Analysis & Visualization</b> (click to expand)</summary>
+### 📊 Analysis & Visualization
 
 - **Entity Relationship Diagram (ERD)**: Interactive Cytoscape.js force-directed graph with pan, zoom, node isolation, publisher filter, and PNG/SVG export
 - **Execution Pipeline**: Visual representation of client → sync → async automation flow per entity
@@ -51,28 +48,20 @@ PPSB benefits **solution architects** (system documentation), **developers** (on
 - **Entity Complexity**: Scoring based on field count, automation density, and relationship complexity
 - **Performance Risks**: Identify synchronous plugins with external calls, long execution chains
 
-</details>
-
-<details>
-<summary><b>💾 Export Formats</b> (click to expand)</summary>
+### 💾 Export Formats
 
 - **Markdown**: Complete file structure ready for Azure DevOps Wiki upload
 - **JSON**: Full data export for programmatic use, baselines, and CI/CD pipelines
 - **HTML**: Single-page interactive document with navigation, search, and accordion sections
 - **ZIP**: All formats bundled together with organized directory structure
 
-</details>
-
-<details>
-<summary><b>🔍 Smart Scope Selection</b> (click to expand)</summary>
+### 🔍 Smart Scope Selection
 
 - **By Publisher**: Select one or more publishers to document all their solutions
 - **By Solution**: Choose specific solutions regardless of publisher
 - **By Entity**: Document all entities (with optional system entity inclusion)
 - **Filtering**: Multi-select with live filtering and selected item management
 
-</details>
-
 ---
 
 ## 🚀 Quick Start
@@ -85,9 +74,8 @@ PPSB benefits **solution architects** (system documentation), **developers** (on
 6. **Export**: Download as Markdown, JSON, HTML, or ZIP bundle
 7. **Use**: Upload Markdown to Azure DevOps Wiki or share HTML with stakeholders
 
-📖 **[Detailed User Guide](docs/user-guide.md)** |
-📊 **[Example Output Structure](docs/examples/example-output-structure.md)** |
-🏗️ **[Architecture Documentation](docs/architecture.md)**
+📖 **[Detailed User Guide](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/user-guide.md)** |
+🏗️ **[Architecture Documentation](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/architecture.md)**
 
 ---
 
@@ -96,64 +84,64 @@ PPSB benefits **solution architects** (system documentation), **developers** (on
 ### Scope Selection
 Choose what to document - by publisher or solution with multi-select filtering.
 
-![Scope Selection](docs/screenshots/PPSB-1-What%20to%20document-selector.png)
+![Scope Selection](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-1-What%20to%20document-selector.png)
 
 ### Confirmation Screen
 Review your selection before generating the blueprint.
 
-![Generator Confirmation](docs/screenshots/PPSB-2-Generator-Confirmation.png)
+![Generator Confirmation](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-2-Generator-Confirmation.png)
 
 ### Results Dashboard
 Interactive dashboard with summary metrics, ERD visualization, and component browser.
 
-![Dashboard](docs/screenshots/PPSB-3-Dashboard.png)
+![Dashboard](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-3-Dashboard.png)
 
 ### Component Details
 Browse and explore all discovered components with expandable details and inline documentation.
 
-![Component Details](docs/screenshots/PPSB-4-Component-Details.png)
+![Component Details](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-4-Component-Details.png)
 
 ### Solution Distribution Analysis
 Analyze component distribution across solutions with dependency mapping and shared component detection.
 
-![Solution Distribution Analysis](docs/screenshots/PPSB-5-Solution%20Distrubution%20Analysis.png)
+![Solution Distribution Analysis](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-5-Solution%20Distrubution%20Analysis.png)
 
 ### External Dependencies Analysis
 Identify and assess all external API calls across flows, plugins, and web resources with risk scoring.
 
-![External Dependencies Analysis](docs/screenshots/PPSB-6-External%20Dependencies%20Analysis.png)
+![External Dependencies Analysis](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-6-External%20Dependencies%20Analysis.png)
 
 ### Export Options
 Choose your export format - Markdown, JSON, HTML, or ZIP bundle.
 
-![Export Options](docs/screenshots/PPSB-6-Export%20Options.png)
+![Export Options](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-6-Export%20Options.png)
 
 ### HTML Export
 Self-contained, interactive HTML documentation ready to share with stakeholders.
 
-![HTML Export Example 1](docs/screenshots/PPSB-7-Export%20html.png)
+![HTML Export Example 1](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-7-Export%20html.png)
 
-![HTML Export Example 2](docs/screenshots/PPSB-8-Export%20html.png)
+![HTML Export Example 2](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-8-Export%20html.png)
 
 ### Entity Relationship Diagram
 Interactive force-directed ERD with pan, zoom, node isolation, publisher filter, and PNG/SVG export.
 
-![ERD](docs/screenshots/PPSB-9-ERD.png)
+![ERD](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-9-ERD.png)
 
 ### Cross-Entity Automation
 Trace automation chains that cross entity boundaries — how plugins and flows on one entity trigger automation on related entities.
 
-![Cross-Entity Automation](docs/screenshots/PPSB-10-Cross-Entity-Automation.png)
+![Cross-Entity Automation](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-10-Cross-Entity-Automation.png)
 
 ### Global Automation Chain Map
 Full cross-entity automation chain map showing all entity pipelines and their inter-entity connections.
 
-![Global Chain Map](docs/screenshots/PPSB-11-Cross-Entity-Automation-Global-Chain-Map.png)
+![Global Chain Map](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-11-Cross-Entity-Automation-Global-Chain-Map.png)
 
 ### Fetch Diagnostics Log
 Real-time fetch diagnostics showing every Dataverse API call with timing, batch sizes, and retry information.
 
-![Fetch Log](docs/screenshots/PPSB-12-Fetch-Log.png)
+![Fetch Log](https://raw.githubusercontent.com/sabrish/power-platform-solution-blueprint/main/docs/screenshots/PPSB-12-Fetch-Log.png)
 
 ---
 
@@ -180,7 +168,7 @@ Real-time fetch diagnostics showing every Dataverse API call with timing, batch
 - **Complexity Analysis**: Get detailed migration recommendations with step-by-step guidance
 - **Dependency Mapping**: Understand cross-entity automation before migration
 
-📖 **[More Use Cases in User Guide](docs/user-guide.md#common-use-cases)**
+📖 **[More Use Cases in User Guide](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/user-guide.md#8-common-use-cases)**
 
 ---
 
@@ -193,8 +181,8 @@ Real-time fetch diagnostics showing every Dataverse API call with timing, batch
 - **Export**: JSZip (multi-file packages)
 - **Architecture**: Flat structure with separated core logic (`src/core/`) and React UI (`src/components/`)
 
-🏗️ **[Architecture Details](docs/architecture.md)** |
-🛣️ **[Roadmap](docs/roadmap.md)**
+🏗️ **[Architecture Details](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/architecture.md)** |
+🛣️ **[Roadmap](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/roadmap.md)**
 
 ---
 
@@ -243,15 +231,11 @@ pnpm typecheck
 
 Comprehensive documentation for all aspects of PPSB:
 
-- **[User Guide](docs/user-guide.md)** - Complete usage instructions from scope selection to export
-- **[Architecture](docs/architecture.md)** - Technical design, component structure, and extension points
-- **[API Security](docs/API_SECURITY.md)** - Complete API reference, security considerations, and data access documentation
-- **[Roadmap](docs/roadmap.md)** - Future versions (baseline comparison, CLI, CI/CD integration)
-- **[Examples](docs/examples/)** - Sample outputs and documentation structure
-  - [Output Structure](docs/examples/example-output-structure.md)
-  - [Sample ERD](docs/examples/sample-erd.md)
-  - [Sample Entity Documentation](docs/examples/sample-entity-doc.md)
-- **[Changelog](CHANGELOG.md)** - Version history and release notes
+- **[User Guide](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/user-guide.md)** - Complete usage instructions from scope selection to export
+- **[Architecture](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/architecture.md)** - Technical design, component structure, and extension points
+- **[API Security](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/API_SECURITY.md)** - Complete API reference, security considerations, and data access documentation
+- **[Roadmap](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/roadmap.md)** - Future versions (baseline comparison, CLI, CI/CD integration)
+- **[Changelog](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/CHANGELOG.md)** - Version history and release notes
 
 ---
 
@@ -326,13 +310,13 @@ PPSB is under active development with exciting features planned:
 - Multi-tenant support
 - Advanced visualizations and AI-powered insights
 
-📖 **[Full Roadmap](docs/roadmap.md)**
+📖 **[Full Roadmap](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/roadmap.md)**
 
 ---
 
 ## 📄 License
 
-[MIT License](LICENSE)
+[MIT License](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/LICENSE)
 
 Copyright © 2026 SAB. All rights reserved.
 
@@ -342,18 +326,17 @@ Copyright © 2026 SAB. All rights reserved.
 
 - **Issues**: [GitHub Issues](https://github.com/sabrish/power-platform-solution-blueprint/issues) - Report bugs or request features
 - **Discussions**: [GitHub Discussions](https://github.com/sabrish/power-platform-solution-blueprint/discussions) - Ask questions and share ideas
-- **Documentation**: [docs/](docs/) - Comprehensive guides and examples
+- **Documentation**: [docs/](https://github.com/sabrish/power-platform-solution-blueprint/tree/main/docs/) - Comprehensive guides
 
 ---
 
 ## 🌟 Quick Links
 
-- [Installation](#installation)
-- [User Guide](docs/user-guide.md)
-- [Architecture](docs/architecture.md)
-- [Roadmap](docs/roadmap.md)
-- [Changelog](CHANGELOG.md)
-- [Examples](docs/examples/)
+- [Installation](#-installation)
+- [User Guide](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/user-guide.md)
+- [Architecture](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/architecture.md)
+- [Roadmap](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/docs/roadmap.md)
+- [Changelog](https://github.com/sabrish/power-platform-solution-blueprint/blob/main/CHANGELOG.md)
 
 ---