powerplatform-review-tool/README.md

Evaluate Power Platform solution zip files based on best practice patterns

# Power Platform Review Tool

![npm version](https://img.shields.io/npm/v/@powercat-tools/powerplatform-review-tool)

🔍 A CLI and JavaScript utility to evaluate Power Platform Solution ZIPs based on best practice patterns for **Power Apps**, **Power Automate**, and **Copilot (Power Virtual Agents)**.

---


## ✨ Features

- 🏛️ **Analyze Power Platform Solutions** - Parse and evaluate `.zip` solution files
- 🧠 **Best Practice Evaluation** - Comprehensive pattern analysis against industry standards
- 📊 **SARIF Output** - Industry-standard Static Analysis Results Interchange Format
- ⚙️ **Multi-Component Support** - Canvas Apps, Power Automate, Copilot, and Dataverse
- 📃 **Dual Interface** - CLI for automation and Node.js module for integration
- � **Detailed Extraction** - Complete metadata export with Mermaid diagram generation
- 🚀 **CI/CD Ready** - Perfect for GitHub Actions, Azure DevOps, and other pipelines
- 📈 **Solution Scoring** - Percentage-based quality metrics

---


## 📦 Installation

### Global Installation (Recommended for CLI)

```bash
npm install -g @powercat-tools/powerplatform-review-tool
```

After global installation, the `pp-review` command will be available system-wide.

### Local Project Installation

```bash
npm install @powercat-tools/powerplatform-review-tool
```

Then use with `npx`:
```bash
npx pp-review review -f ./MySolution.zip -o review-result.json
```

### Development Installation

For contributing or testing:
```bash
git clone <repository-url>
cd powerplatform-review-tool
npm install
npm link  # Makes pp-review available locally
```

---


## 🚀 Usage (CLI)

### Review a solution:

```bash
pp-review review -f <path-to-solution.zip> -o <output-file>
```

### Extract metadata without evaluation:

```bash
pp-review extract -f <path-to-solution.zip> -o <output-file>
```

---


### 🔁 Examples

**Review a solution and generate a SARIF report:**
```bash
pp-review review -f "./MySolution.zip" -o review-result.json
```

**Extract metadata from a solution zip:**
```bash
pp-review extract -f "./MySolution.zip" -o solution-details.json
```

**Display help:**
```bash
pp-review --help
pp-review review --help
pp-review extract --help
```

---


### 💡 Options

| Flag           | Description                              | Required |
|----------------|------------------------------------------|----------|
| `-f, --file`   | Path to the solution zip file            | ✅ Yes    |
| `-o, --output` | Output path for the resulting JSON       | ✅ Yes    |

---


## 📜 Usage (as a JavaScript/TypeScript Module)

You can use the tool programmatically in your applications. The package supports both **CommonJS** (`require`) and **ES modules** (`import`) for maximum compatibility.

### 📦 Module Formats

- **ES Modules** (`.mjs`) - For modern browsers, React, Vite, and Node.js with `"type": "module"`
- **CommonJS** (`.cjs`) - For Node.js with `require()` and legacy projects

The package automatically selects the correct format based on your environment.

### Node.js Example (Extract Solution Details)

```typescript
import { extractSolutionDetail } from 'powerplatform-review-tool';
import fs from 'fs';

const zipBuffer = fs.readFileSync('./MySolution.zip');
const solutionDetails = await extractSolutionDetail(zipBuffer);
console.log(JSON.stringify(solutionDetails, null, 2));
```

### Node.js Example (Review Solution)

```typescript
import { startReview } from 'powerplatform-review-tool';
import fs from 'fs';

const zipBuffer = fs.readFileSync('./MySolution.zip');
const reviewResult = await startReview(zipBuffer, undefined, null, []);
console.log(JSON.stringify(reviewResult, null, 2));
```

### React/Browser Example

The package works seamlessly in React applications and browsers with modern bundlers like Vite or Webpack:

```typescript
import { extractSolutionDetail, startReview } from 'powerplatform-review-tool';
import type { SolutionDetails } from 'powerplatform-review-tool';

function SolutionReviewer() {
  const handleFileUpload = async (file: File) => {
    // Convert File to ArrayBuffer
    const arrayBuffer = await file.arrayBuffer();
    const buffer = Buffer.from(arrayBuffer);
    
    // Extract solution details
    const details: SolutionDetails = await extractSolutionDetail(buffer);
    console.log('Solution:', details.solutionOverview.displayName);
    
    // Run review
    const review = await startReview(buffer);
    console.log('Score:', review?.SolutionScore);
  };
  
  return (
    <input 
      type="file" 
      accept=".zip" 
      onChange={(e) => e.target.files?.[0] && handleFileUpload(e.target.files[0])}
    />
  );
}
```

> 💡 **Note for Browser Usage**: You'll need the `buffer` package polyfill for browser environments:
> ```bash
> npm install buffer
> ```

A complete React demo is available in the repository at `src/powerplatform-review-react-demo`.

### Available Exports

```typescript
import { 
  startReview,              // Run full review with best practice analysis
  extractSolutionDetail,    // Extract metadata only (apps, flows, tables, etc.)
  generateSarifFromReview,  // Convert review results to SARIF format
  getItemsFromDataset,      // Utility for PCF dataset mapping
  ReviewSchema              // Zod schema for validation
} from 'powerplatform-review-tool';

// Type definitions are also exported
import type { SolutionDetails, ReviewResult } from 'powerplatform-review-tool';
```

### CommonJS Usage (Node.js)

```javascript
const { startReview, extractSolutionDetail } = require('powerplatform-review-tool');
const fs = require('fs');

const zipBuffer = fs.readFileSync('./MySolution.zip');
const reviewResult = await startReview(zipBuffer, undefined, null, []);
console.log(JSON.stringify(reviewResult, null, 2));
```

---


## 🧰 Pattern Types Supported

The tool evaluates solutions against comprehensive best practice patterns:

### Canvas Apps
- ✅ Screen and control naming conventions
- ✅ Performance optimization patterns
- ✅ Accessibility compliance
- ✅ Code reusability patterns

### Power Automate Flows
- ✅ Error handling implementation
- ✅ Connection reference usage
- ✅ Action configuration best practices
- ✅ Flow structure and design patterns

### Copilot Studio Agent (Full Experience)
- ✅ Topic organization and structure
- ✅ Entity and variable usage
- ✅ Authentication configuration
- ✅ Conversation design patterns

### Dataverse
- ✅ Table and field naming conventions
- ✅ Relationship configurations
- ✅ Security role definitions

All patterns are **easily extendable** through the shared pattern library.

---


## 🛠️ Integration Examples

### ✅ GitHub Action

```yaml
- name: Review Power Platform Solution
  run: |
    npx pp-review review -f ./solutions/Solution.zip -o review-result.json
```

### ✅ Azure DevOps Pipeline

```yaml
- script: |
    npx pp-review review -f "$(Build.SourcesDirectory)/Solution.zip" -o review-result.json
  displayName: 'Run Power Platform Review Tool'
```

---


## 🧪 Testing & Development

### Running Tests

Test projects are included in the repository to verify all functionality:

**Node.js Tests (CLI + Programmatic API):**
```bash
cd src/powerplatform-review-tool-tests
npm run test:all          # Run all tests (CLI + Node.js)
npm run test:cli:help     # Show help
npm run test:cli:extract  # Test extraction
npm run test:cli:review   # Test review
npm run test:node         # Test Node.js programmatic usage
```

**React/Browser Demo:**
```bash
cd src/powerplatform-review-react-demo
npm install
npm run dev               # Start Vite dev server at http://localhost:5173
```

The test projects validate:
- ✅ CLI command execution
- ✅ Node.js programmatic API (CommonJS with `require`)
- ✅ ES module imports (Node.js with `import`)
- ✅ Browser/React usage with Vite bundler
- ✅ Solution metadata extraction
- ✅ Review scoring and SARIF output generation
- ✅ TypeScript type definitions

### Example Output

**Extract Command:**
```bash
pp-review extract -f ./MySolution.zip -o ./output/solution-details.json
```
Generates a JSON file with:
- Canvas apps with screens and controls
- Power Automate flows with actions
- Dataverse tables and relationships
- Mermaid diagrams for visualization
- Copilot/Agent configurations

**Review Command:**
```bash
pp-review review -f ./MySolution.zip -o ./output/review-results.json
```
Generates a SARIF-formatted file with:
- Overall solution score (percentage)
- Best practice violations by category
- Detailed findings with severity levels
- Recommendations for improvement

---


## 👨‍💼 Author

Developed with ❤️ by [Ramakrishnan](https://github.com/ramakrishnan24689)

---


## 📄 License

[MIT](https://opensource.org/licenses/MIT)