diff --git a/.github/workflows/README-manual-api-changelog.md b/.github/workflows/README-manual-api-changelog.md deleted file mode 100644 index 909e9548a..000000000 --- a/.github/workflows/README-manual-api-changelog.md +++ /dev/null @@ -1,234 +0,0 @@ -# Manual API Changelog Generation - -This workflow allows you to generate API changelogs by comparing any two versions of the ComfyUI Frontend package. - -## Usage - -### Via GitHub Actions UI - -1. Go to **Actions** tab in the repository -2. Select **Manual API Changelog Generation** from the workflows list -3. Click **Run workflow** button -4. Fill in the inputs: - - **Previous version**: The earlier version (e.g., `1.29.0` or `v1.29.0`) - - **Current version**: The later version (e.g., `1.30.2` or `v1.30.2`) - - **Create PR**: Check this to automatically create a pull request with the changelog - -### Via GitHub CLI - -```bash -# Basic usage - just generate changelog -gh workflow run manual-api-changelog.yaml \ - -f from_version=1.29.0 \ - -f to_version=1.30.2 \ - -f create_pr=false - -# Generate changelog and create PR -gh workflow run manual-api-changelog.yaml \ - -f from_version=1.29.0 \ - -f to_version=1.30.2 \ - -f create_pr=true -``` - -## What It Does - -1. **Validates Inputs**: Checks that version formats are valid (X.Y.Z) and tags exist -2. **Builds Both Versions**: Checks out each version tag, installs dependencies, and builds TypeScript types -3. **Generates Snapshots**: Creates structured JSON snapshots of the public API surface for each version -4. **Compares APIs**: Analyzes differences and categorizes as: - - ⚠️ **Breaking changes** (removals, signature changes) - - ✨ **Additions** (new interfaces, methods, properties) - - 🔄 **Modifications** (non-breaking changes) -5. **Uploads Artifact**: Saves the changelog and snapshots as a workflow artifact (90-day retention) -6. **Creates PR** (optional): Generates a draft PR to update `docs/API-CHANGELOG.md` - -## Output - -### Workflow Artifacts - -Every run produces an artifact containing: -- `CHANGELOG-{from}-to-{to}.md` - Human-readable changelog -- `from.json` - API snapshot of the earlier version -- `to.json` - API snapshot of the later version - -**Retention**: 90 days - -### Pull Request (Optional) - -If `create_pr` is enabled and changes are detected: -- Creates a draft PR with title: `[docs] API Changelog: v{from} → v{to}` -- Updates `docs/API-CHANGELOG.md` with the new changelog entry -- Includes detailed metadata and review instructions -- Labeled with `documentation` - -## Example Changelog Output - -```markdown -## v1.30.2 (2025-11-04) - -Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface. - -### ✨ Additions - -**Type Aliases** -- `WorkflowId` - -**Interfaces** -- `ExtensionMetadata` - - Members: `id`, `name`, `version`, `description` - -### 🔄 Modifications - -> **Note**: Some modifications may be breaking changes. - -**Interfaces** -- `ComfyApi` - - ✨ Added member: `queuePromptAsync` - - ✨ Added member: `cancelPrompt` - - ⚠️ **Breaking**: Removed member: `queuePrompt` - -**Enums** -- `NodeStatus` - - ✨ Added enum value: `ERROR` - - ✨ Added enum value: `COMPLETED` -``` - -## Use Cases - -### 1. Generate Changelog for Missed Releases - -If the automatic workflow failed or was skipped for a release: - -```bash -gh workflow run manual-api-changelog.yaml \ - -f from_version=1.28.0 \ - -f to_version=1.29.0 \ - -f create_pr=true -``` - -### 2. Compare Non-Adjacent Versions - -To see cumulative changes across multiple releases: - -```bash -gh workflow run manual-api-changelog.yaml \ - -f from_version=1.25.0 \ - -f to_version=1.30.2 \ - -f create_pr=false -``` - -### 3. Test Upcoming Changes - -Compare current `main` branch against the latest release (requires creating a temporary tag): - -```bash -# Create temporary tag for current main -git tag v1.31.0-preview -git push origin v1.31.0-preview - -# Run comparison -gh workflow run manual-api-changelog.yaml \ - -f from_version=1.30.2 \ - -f to_version=1.31.0-preview \ - -f create_pr=false - -# Clean up temporary tag -git tag -d v1.31.0-preview -git push origin :refs/tags/v1.31.0-preview -``` - -### 4. Audit Historical Changes - -Generate changelogs for documentation purposes: - -```bash -# Compare multiple version pairs -for from in 1.26.0 1.27.0 1.28.0 1.29.0; do - to=$(echo "$from" | awk -F. '{print $1"."$2+1".0"}') - gh workflow run manual-api-changelog.yaml \ - -f from_version=$from \ - -f to_version=$to \ - -f create_pr=false -done -``` - -## Validation - -The workflow validates: -- ✅ Version format matches semantic versioning (X.Y.Z) -- ✅ Both version tags exist in the repository -- ✅ Tags reference valid commits with buildable code - -If validation fails, the workflow exits early with a clear error message. - -## Limitations - -- **Tag requirement**: Both versions must have corresponding `vX.Y.Z` git tags -- **Build requirement**: Both versions must have functional build processes -- **Type files**: Requires `dist/index.d.ts` to exist after building -- **Scripts**: Requires `scripts/snapshot-api.js` and `scripts/compare-api-snapshots.js` to be present - -## Related Workflows - -- **[Release API Changelogs](.github/workflows/release-api-changelogs.yaml)**: Automatic changelog generation triggered by NPM releases -- **[Release NPM Types](.github/workflows/release-npm-types.yaml)**: Publishes type definitions and triggers automatic changelog - -## Troubleshooting - -### "Tag does not exist" error - -Ensure the version exists as a git tag: - -```bash -git tag -l 'v*' | grep 1.29.0 -``` - -If missing, the version may not have been released yet. - -### "Build failed" error - -Check that the version can be built successfully: - -```bash -git checkout v1.29.0 -pnpm install -pnpm build:types -``` - -### No changes detected - -If the workflow reports no changes but you expect some: -1. Check the artifact snapshots to verify they're different -2. Ensure you're comparing the correct versions -3. Review the comparison script logic in `scripts/compare-api-snapshots.js` - -### PR not created - -PR creation requires: -- `create_pr` input set to `true` -- Significant changes detected (more than just headers) -- `PR_GH_TOKEN` secret configured with appropriate permissions - -## Security - -- **Permissions**: Workflow requires `contents: write` and `pull-requests: write` -- **Token**: Uses `secrets.PR_GH_TOKEN` for PR creation -- **Isolation**: Each workflow run uses a unique concurrency group -- **Artifacts**: Retained for 90 days, accessible to repository collaborators - -## Monitoring - -View workflow runs: -```bash -gh run list --workflow=manual-api-changelog.yaml -``` - -View specific run details: -```bash -gh run view -``` - -Download artifacts: -```bash -gh run download -``` diff --git a/.github/workflows/README.md b/.github/workflows/README.md index f62e91eda..e32739b29 100644 --- a/.github/workflows/README.md +++ b/.github/workflows/README.md @@ -19,3 +19,214 @@ Workflow files follow a consistent naming pattern: `-. Each workflow file contains comments explaining its purpose, triggers, and behavior. For specific details about what each workflow does, refer to the comments at the top of each `.yaml` file. For GitHub Actions documentation, see [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows). + +## Manual API Changelog Generation + +The `manual-api-changelog.yaml` workflow allows you to generate API changelogs by comparing any two versions of the ComfyUI Frontend package. + +### Usage + +#### Via GitHub Actions UI + +1. Go to **Actions** tab in the repository +2. Select **Manual API Changelog Generation** from the workflows list +3. Click **Run workflow** button +4. Fill in the inputs: + - **Previous version**: The earlier version (e.g., `1.29.0` or `v1.29.0`) + - **Current version**: The later version (e.g., `1.30.2` or `v1.30.2`) + - **Create PR**: Check this to automatically create a pull request with the changelog + +#### Via GitHub CLI + +```bash +# Basic usage - just generate changelog +gh workflow run manual-api-changelog.yaml \ + -f from_version=1.29.0 \ + -f to_version=1.30.2 \ + -f create_pr=false + +# Generate changelog and create PR +gh workflow run manual-api-changelog.yaml \ + -f from_version=1.29.0 \ + -f to_version=1.30.2 \ + -f create_pr=true +``` + +### What It Does + +1. **Validates Inputs**: Checks that version formats are valid (X.Y.Z) and tags exist +2. **Builds Both Versions**: Checks out each version tag, installs dependencies, and builds TypeScript types +3. **Generates Snapshots**: Creates structured JSON snapshots of the public API surface for each version +4. **Compares APIs**: Analyzes differences and categorizes as: + - ⚠️ **Breaking changes** (removals, signature changes) + - ✨ **Additions** (new interfaces, methods, properties) + - 🔄 **Modifications** (non-breaking changes) +5. **Uploads Artifact**: Saves the changelog and snapshots as a workflow artifact (90-day retention) +6. **Creates PR** (optional): Generates a draft PR to update `docs/API-CHANGELOG.md` + +### Output + +#### Workflow Artifacts + +Every run produces an artifact containing: +- `CHANGELOG-{from}-to-{to}.md` - Human-readable changelog +- `from.json` - API snapshot of the earlier version +- `to.json` - API snapshot of the later version + +**Retention**: 90 days + +#### Pull Request (Optional) + +If `create_pr` is enabled and changes are detected: +- Creates a draft PR with title: `[docs] API Changelog: v{from} → v{to}` +- Updates `docs/API-CHANGELOG.md` with the new changelog entry +- Includes detailed metadata and review instructions +- Labeled with `documentation` + +### Example Changelog Output + +```markdown +## v1.30.2 (2025-11-04) + +Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface. + +### ✨ Additions + +**Type Aliases** +- `WorkflowId` + +**Interfaces** +- `ExtensionMetadata` + - Members: `id`, `name`, `version`, `description` + +### 🔄 Modifications + +> **Note**: Some modifications may be breaking changes. + +**Interfaces** +- `ComfyApi` + - ✨ Added member: `queuePromptAsync` + - ✨ Added member: `cancelPrompt` + - ⚠️ **Breaking**: Removed member: `queuePrompt` + +**Enums** +- `NodeStatus` + - ✨ Added enum value: `ERROR` + - ✨ Added enum value: `COMPLETED` +``` + +### Use Cases + +#### 1. Generate Changelog for Missed Releases + +If the automatic workflow failed or was skipped for a release: + +```bash +gh workflow run manual-api-changelog.yaml \ + -f from_version=1.28.0 \ + -f to_version=1.29.0 \ + -f create_pr=true +``` + +#### 2. Compare Non-Adjacent Versions + +To see cumulative changes across multiple releases: + +```bash +gh workflow run manual-api-changelog.yaml \ + -f from_version=1.25.0 \ + -f to_version=1.30.2 \ + -f create_pr=false +``` + +#### 3. Test Upcoming Changes + +Compare current `main` branch against the latest release (requires creating a temporary tag): + +```bash +# Create temporary tag for current main +git tag v1.31.0-preview +git push origin v1.31.0-preview + +# Run comparison +gh workflow run manual-api-changelog.yaml \ + -f from_version=1.30.2 \ + -f to_version=1.31.0-preview \ + -f create_pr=false + +# Clean up temporary tag +git tag -d v1.31.0-preview +git push origin :refs/tags/v1.31.0-preview +``` + +#### 4. Audit Historical Changes + +Generate changelogs for documentation purposes: + +```bash +# Compare multiple version pairs +for from in 1.26.0 1.27.0 1.28.0 1.29.0; do + to=$(echo "$from" | awk -F. '{print $1"."$2+1".0"}') + gh workflow run manual-api-changelog.yaml \ + -f from_version=$from \ + -f to_version=$to \ + -f create_pr=false +done +``` + +### Validation + +The workflow validates: +- ✅ Version format matches semantic versioning (X.Y.Z) +- ✅ Both version tags exist in the repository +- ✅ Tags reference valid commits with buildable code + +If validation fails, the workflow exits early with a clear error message. + +### Limitations + +- **Tag requirement**: Both versions must have corresponding `vX.Y.Z` git tags +- **Build requirement**: Both versions must have functional build processes +- **Type files**: Requires `dist/index.d.ts` to exist after building +- **Scripts**: Requires `scripts/snapshot-api.ts` and `scripts/compare-api-snapshots.ts` to be present + +### Related Workflows + +- **[Release API Changelogs](.github/workflows/release-api-changelogs.yaml)**: Automatic changelog generation triggered by NPM releases +- **[Release NPM Types](.github/workflows/release-npm-types.yaml)**: Publishes type definitions and triggers automatic changelog + +### Troubleshooting + +#### "Tag does not exist" error + +Ensure the version exists as a git tag: + +```bash +git tag -l 'v*' | grep 1.29.0 +``` + +If missing, the version may not have been released yet. + +#### "Build failed" error + +Check that the version can be built successfully: + +```bash +git checkout v1.29.0 +pnpm install +pnpm build:types +``` + +#### No changes detected + +If the workflow reports no changes but you expect some: +1. Check the artifact snapshots to verify they're different +2. Ensure you're comparing the correct versions +3. Review the comparison script logic in `scripts/compare-api-snapshots.ts` + +#### PR not created + +PR creation requires: +- `create_pr` input set to `true` +- Significant changes detected (more than just headers) +- `PR_GH_TOKEN` secret configured with appropriate permissions diff --git a/.github/workflows/manual-api-changelog.yaml b/.github/workflows/manual-api-changelog.yaml index 457176113..681a7af23 100644 --- a/.github/workflows/manual-api-changelog.yaml +++ b/.github/workflows/manual-api-changelog.yaml @@ -98,7 +98,7 @@ jobs: run: | # Copy scripts to temporary location mkdir -p /tmp/api-changelog-scripts - cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/ + cp scripts/snapshot-api.ts scripts/compare-api-snapshots.ts /tmp/api-changelog-scripts/ - name: Build and snapshot TO version run: | @@ -107,13 +107,13 @@ jobs: # Restore scripts mkdir -p scripts - cp /tmp/api-changelog-scripts/*.js scripts/ + cp /tmp/api-changelog-scripts/*.ts scripts/ pnpm install --frozen-lockfile pnpm build:types # Generate snapshot - node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-to.json + node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > /tmp/api-snapshots-to.json echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.to_version }}" @@ -124,13 +124,13 @@ jobs: # Restore scripts mkdir -p scripts - cp /tmp/api-changelog-scripts/*.js scripts/ + cp /tmp/api-changelog-scripts/*.ts scripts/ pnpm install --frozen-lockfile pnpm build:types # Generate snapshot - node scripts/snapshot-api.js dist/index.d.ts > /tmp/api-snapshots-from.json + node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > /tmp/api-snapshots-from.json echo "✅ Created snapshot for v${{ steps.validate_versions.outputs.from_version }}" @@ -140,7 +140,7 @@ jobs: # Restore scripts mkdir -p scripts - cp /tmp/api-changelog-scripts/*.js scripts/ + cp /tmp/api-changelog-scripts/*.ts scripts/ # Copy snapshots to working directory cp /tmp/api-snapshots-from.json .api-snapshots/from.json @@ -153,7 +153,7 @@ jobs: GIT_REF=$(git rev-parse ${{ steps.validate_versions.outputs.to_tag }}) # Run the comparison script - CHANGELOG_OUTPUT=$(node scripts/compare-api-snapshots.js \ + CHANGELOG_OUTPUT=$(node --loader tsx scripts/compare-api-snapshots.ts \ .api-snapshots/from.json \ .api-snapshots/to.json \ ${{ steps.validate_versions.outputs.from_version }} \ diff --git a/.github/workflows/release-api-changelogs.yaml b/.github/workflows/release-api-changelogs.yaml index a66a5d8fe..028af8ac7 100644 --- a/.github/workflows/release-api-changelogs.yaml +++ b/.github/workflows/release-api-changelogs.yaml @@ -88,7 +88,7 @@ jobs: mkdir -p .api-snapshots # Generate snapshot of current types - node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/current.json + node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > .api-snapshots/current.json echo "Current API snapshot created" @@ -97,7 +97,7 @@ jobs: run: | # Copy scripts to temporary location to use with previous version mkdir -p /tmp/api-changelog-scripts - cp scripts/snapshot-api.js scripts/compare-api-snapshots.js /tmp/api-changelog-scripts/ + cp scripts/snapshot-api.ts scripts/compare-api-snapshots.ts /tmp/api-changelog-scripts/ - name: Checkout previous version if: steps.previous_version.outputs.tag != '' @@ -110,7 +110,7 @@ jobs: # Restore scripts mkdir -p scripts - cp /tmp/api-changelog-scripts/*.js scripts/ + cp /tmp/api-changelog-scripts/*.ts scripts/ - name: Build previous types if: steps.previous_version.outputs.tag != '' @@ -122,7 +122,7 @@ jobs: if: steps.previous_version.outputs.tag != '' run: | # Generate snapshot of previous types - node scripts/snapshot-api.js dist/index.d.ts > .api-snapshots/previous.json + node --loader tsx scripts/snapshot-api.ts dist/index.d.ts > .api-snapshots/previous.json echo "Previous API snapshot created" @@ -130,7 +130,7 @@ jobs: if: steps.previous_version.outputs.tag != '' run: | # Remove copied scripts to avoid conflicts - rm -f scripts/snapshot-api.js scripts/compare-api-snapshots.js + rm -f scripts/snapshot-api.ts scripts/compare-api-snapshots.ts git checkout - git stash pop || true @@ -146,7 +146,7 @@ jobs: # Run the comparison script if [ -f .api-snapshots/previous.json ]; then - node scripts/compare-api-snapshots.js \ + node --loader tsx scripts/compare-api-snapshots.ts \ .api-snapshots/previous.json \ .api-snapshots/current.json \ ${{ steps.previous_version.outputs.version }} \ diff --git a/demo-snapshots/CHANGELOG-DEMO.md b/demo-snapshots/CHANGELOG-DEMO.md deleted file mode 100644 index cfbe38c4a..000000000 --- a/demo-snapshots/CHANGELOG-DEMO.md +++ /dev/null @@ -1,49 +0,0 @@ -## v1.30.2 (2025-11-01) - -Comparing v1.29.0 → v1.30.2. This changelog documents changes to the public API surface that third-party extensions and custom nodes depend on. - -### ✨ Additions - -**Type Aliases** - -- `WorkflowId` - -**Interfaces** - -- `ExtensionMetadata` - - Members: `id`, `name`, `version`, `description` - -### 🔄 Modifications - -> **Note**: Some modifications may be breaking changes. - -**Interfaces** - -- `ComfyApi` - - ✨ Added member: `queuePromptAsync` - - ✨ Added member: `cancelPrompt` - - ✨ Added member: `getQueueStatus` - - ⚠️ **Breaking**: Removed member: `queuePrompt` -- `NodeDef` - - ✨ Added member: `input` - - ✨ Added member: `output` - - ✨ Added member: `output_name` -- `WorkflowMetadata` - - ✨ Added member: `tags` - - ✨ Added member: `thumbnail` - -**Enums** - -- `NodeStatus` - - ✨ Added enum value: `ERROR` - - ✨ Added enum value: `COMPLETED` - -**Classes** - -- `WorkflowManager` - - ✨ Added member: `cache` - - ✨ Added method: `deleteWorkflow()` - - ✨ Added method: `searchWorkflows()` - ---- - diff --git a/demo-snapshots/README.md b/demo-snapshots/README.md deleted file mode 100644 index 5de4442ee..000000000 --- a/demo-snapshots/README.md +++ /dev/null @@ -1,188 +0,0 @@ -# API Changelog Generation Demo - -This demo showcases the automated API changelog generation system comparing two versions of the ComfyUI Frontend public API. - -## Overview - -The demo compares **v1.29.0** → **v1.30.2** to demonstrate: -- Breaking change detection -- API additions tracking -- Non-breaking modifications -- Human-readable changelog generation - -## Demo Files - -### Input Files -- **`v1.29.0.d.ts`** - TypeScript definitions representing the v1.29.0 API surface -- **`v1.30.2.d.ts`** - TypeScript definitions representing the v1.30.2 API surface - -### Generated Files -- **`v1.29.0.json`** - Structured API snapshot from v1.29.0 -- **`v1.30.2.json`** - Structured API snapshot from v1.30.2 -- **`CHANGELOG-DEMO.md`** - Generated changelog comparing the two versions - -## Running the Demo - -```bash -# Generate API snapshots -node scripts/snapshot-api.js demo-snapshots/v1.29.0.d.ts > demo-snapshots/v1.29.0.json -node scripts/snapshot-api.js demo-snapshots/v1.30.2.d.ts > demo-snapshots/v1.30.2.json - -# Compare snapshots and generate changelog -node scripts/compare-api-snapshots.js \ - demo-snapshots/v1.29.0.json \ - demo-snapshots/v1.30.2.json \ - 1.29.0 \ - 1.30.2 \ - > demo-snapshots/CHANGELOG-DEMO.md -``` - -## Key Changes Detected - -### ⚠️ Breaking Changes - -1. **`ComfyApi.queuePrompt()` removed** - - Replaced with `queuePromptAsync()` which includes additional options - - Extension developers need to update their code to use the new async method - -### ✨ New Additions - -1. **New Interface: `ExtensionMetadata`** - - Provides metadata for extensions - - Fields: `id`, `name`, `version`, `description` - -2. **New Type: `WorkflowId`** - - Type alias for workflow identifiers - -3. **Enhanced `ComfyApi` Interface** - - `queuePromptAsync()` - Async queue with priority support - - `cancelPrompt()` - Cancel queued prompts - - `getQueueStatus()` - Query queue state - -4. **Extended `NodeDef` Interface** - - `input` - Input specification - - `output` - Output types - - `output_name` - Output names - -5. **Enhanced `NodeStatus` Enum** - - Added `ERROR` state - - Added `COMPLETED` state - -6. **Extended `WorkflowManager` Class** - - `cache` property for workflow caching - - `deleteWorkflow()` method - - `searchWorkflows()` method - -### 🔄 Non-Breaking Modifications - -1. **`WorkflowMetadata` enhancements** - - Added optional `tags` field - - Added optional `thumbnail` field - -## Real-World Usage - -In production, this system will: - -1. **Automatic Triggering**: Run after each NPM types release -2. **Version Detection**: Automatically detect current and previous versions from git tags -3. **Build Integration**: Build actual TypeScript types from the repository -4. **PR Creation**: Generate draft pull requests with the changelog -5. **Human Review**: Allow maintainers to review and enhance before merging - -## Benefits for Extension Developers - -### Clear Breaking Change Visibility -Extension developers can immediately see: -- What APIs were removed -- What signatures changed -- How to migrate their code - -### Migration Planning -With clear documentation of additions and changes, developers can: -- Plan updates around breaking changes -- Adopt new features when ready -- Understand version compatibility - -### Historical Reference -The cumulative `docs/API-CHANGELOG.md` provides: -- Complete API evolution history -- Context for design decisions -- Migration guides for major versions - -## Example Extension Migration - -### Before (v1.29.0) -```typescript -// Old code using queuePrompt -const result = await api.queuePrompt(workflow); -console.log('Queued:', result.prompt_id); -``` - -### After (v1.30.2) -```typescript -// New code using queuePromptAsync with priority -const result = await api.queuePromptAsync(workflow, { priority: 1 }); -console.log('Queued:', result.prompt_id, 'Position:', result.number); -``` - -## Snapshot Structure - -The JSON snapshots contain structured representations of: - -```json -{ - "types": { /* Type aliases */ }, - "interfaces": { /* Interface definitions with members */ }, - "enums": { /* Enum values */ }, - "functions": { /* Exported functions */ }, - "classes": { /* Class definitions with methods */ }, - "constants": { /* Exported constants */ } -} -``` - -Each entry includes: -- **Name**: Identifier -- **Kind**: Type of declaration -- **Members/Methods**: Properties and functions -- **Types**: Parameter and return types -- **Visibility**: Public/private/protected modifiers -- **Optional**: Whether parameters/properties are optional - -## Comparison Algorithm - -The comparison script: - -1. **Categorizes changes** into breaking, additions, and modifications -2. **Detects breaking changes**: - - Removed interfaces, classes, functions - - Removed methods or properties - - Changed method signatures - - Changed return types - - Removed enum values -3. **Tracks additions**: - - New interfaces, classes, types - - New methods and properties - - New enum values -4. **Identifies modifications**: - - Type changes - - Optionality changes - - Signature changes - -## Future Enhancements - -Planned improvements include: - -- **LLM Enhancement**: Use AI to generate better descriptions and migration guides -- **Email Notifications**: Alert developers on mailing list for major changes -- **Release Notes Integration**: Auto-include in GitHub releases -- **Deprecation Tracking**: Mark APIs as deprecated before removal -- **Example Code**: Generate migration code snippets automatically - -## Conclusion - -This automated system ensures: -- ✅ Zero manual effort for changelog generation -- ✅ Consistent documentation format -- ✅ Clear breaking change visibility -- ✅ Historical API evolution tracking -- ✅ Better extension developer experience diff --git a/demo-snapshots/v1.29.0.d.ts b/demo-snapshots/v1.29.0.d.ts deleted file mode 100644 index 50dc58c26..000000000 --- a/demo-snapshots/v1.29.0.d.ts +++ /dev/null @@ -1,58 +0,0 @@ -/** - * Mock TypeScript definitions representing v1.29.0 API surface - * This represents the public API as it existed in version 1.29.0 - */ - -export interface ComfyApi { - /** - * Get API URL for backend calls - */ - apiURL(path: string): string - - /** - * Get file URL for static resources - */ - fileURL(path: string): string - - /** - * Queue a prompt for execution - */ - queuePrompt(prompt: object): Promise<{ prompt_id: string }> - - /** - * Interrupt current execution - */ - interrupt(): Promise -} - -export interface NodeDef { - name: string - category: string - display_name?: string - description?: string - python_module: string -} - -export enum NodeStatus { - IDLE = 'idle', - QUEUED = 'queued', - RUNNING = 'running' -} - -export interface WorkflowMetadata { - title?: string - description?: string - author?: string - version?: string -} - -export class WorkflowManager { - workflows: Map - - constructor() - - loadWorkflow(id: string): Promise - saveWorkflow(id: string, data: object): Promise -} - -export type NodeId = string diff --git a/demo-snapshots/v1.29.0.json b/demo-snapshots/v1.29.0.json deleted file mode 100644 index 232567bad..000000000 --- a/demo-snapshots/v1.29.0.json +++ /dev/null @@ -1,192 +0,0 @@ -{ - "types": { - "NodeId": { - "kind": "type", - "name": "NodeId", - "text": "export type NodeId = string;", - "exported": true - } - }, - "interfaces": { - "ComfyApi": { - "kind": "interface", - "name": "ComfyApi", - "members": [ - { - "name": "apiURL", - "kind": "method", - "parameters": [ - { - "name": "path", - "type": "string", - "optional": false - } - ], - "returnType": "string" - }, - { - "name": "fileURL", - "kind": "method", - "parameters": [ - { - "name": "path", - "type": "string", - "optional": false - } - ], - "returnType": "string" - }, - { - "name": "queuePrompt", - "kind": "method", - "parameters": [ - { - "name": "prompt", - "type": "object", - "optional": false - } - ], - "returnType": "Promise<{ prompt_id: string }>" - }, - { - "name": "interrupt", - "kind": "method", - "parameters": [], - "returnType": "Promise" - } - ], - "exported": true, - "heritage": [] - }, - "NodeDef": { - "kind": "interface", - "name": "NodeDef", - "members": [ - { - "name": "name", - "type": "string", - "optional": false - }, - { - "name": "category", - "type": "string", - "optional": false - }, - { - "name": "display_name", - "type": "string", - "optional": true - }, - { - "name": "description", - "type": "string", - "optional": true - }, - { - "name": "python_module", - "type": "string", - "optional": false - } - ], - "exported": true, - "heritage": [] - }, - "WorkflowMetadata": { - "kind": "interface", - "name": "WorkflowMetadata", - "members": [ - { - "name": "title", - "type": "string", - "optional": true - }, - { - "name": "description", - "type": "string", - "optional": true - }, - { - "name": "author", - "type": "string", - "optional": true - }, - { - "name": "version", - "type": "string", - "optional": true - } - ], - "exported": true, - "heritage": [] - } - }, - "enums": { - "NodeStatus": { - "kind": "enum", - "name": "NodeStatus", - "members": [ - { - "name": "IDLE", - "value": "\"idle\"" - }, - { - "name": "QUEUED", - "value": "\"queued\"" - }, - { - "name": "RUNNING", - "value": "\"running\"" - } - ], - "exported": true - } - }, - "functions": {}, - "classes": { - "WorkflowManager": { - "kind": "class", - "name": "WorkflowManager", - "members": [ - { - "name": "workflows", - "type": "Map", - "visibility": "public" - } - ], - "methods": [ - { - "name": "loadWorkflow", - "parameters": [ - { - "name": "id", - "type": "string", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - }, - { - "name": "saveWorkflow", - "parameters": [ - { - "name": "id", - "type": "string", - "optional": false - }, - { - "name": "data", - "type": "object", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - } - ], - "exported": true, - "heritage": [] - } - }, - "constants": {} -} diff --git a/demo-snapshots/v1.30.2.d.ts b/demo-snapshots/v1.30.2.d.ts deleted file mode 100644 index da0cf0a16..000000000 --- a/demo-snapshots/v1.30.2.d.ts +++ /dev/null @@ -1,92 +0,0 @@ -/** - * Mock TypeScript definitions representing v1.30.2 API surface - * This represents the public API with several breaking changes and additions - */ - -export interface ComfyApi { - /** - * Get API URL for backend calls - */ - apiURL(path: string): string - - /** - * Get file URL for static resources - */ - fileURL(path: string): string - - /** - * Queue a prompt for execution (async version) - */ - queuePromptAsync( - prompt: object, - options?: { priority?: number } - ): Promise<{ prompt_id: string; number: number }> - - /** - * Cancel a queued prompt - */ - cancelPrompt(prompt_id: string): Promise - - /** - * Interrupt current execution - */ - interrupt(): Promise - - /** - * Get queue status - */ - getQueueStatus(): Promise<{ queue_running: any[]; queue_pending: any[] }> -} - -export interface NodeDef { - name: string - category: string - display_name?: string - description?: string - python_module: string - input: { - required?: Record - optional?: Record - } - output: string[] - output_name: string[] -} - -export enum NodeStatus { - IDLE = 'idle', - QUEUED = 'queued', - RUNNING = 'running', - ERROR = 'error', - COMPLETED = 'completed' -} - -export interface WorkflowMetadata { - title?: string - description?: string - author?: string - version?: string - tags?: string[] - thumbnail?: string -} - -export interface ExtensionMetadata { - id: string - name: string - version: string - description?: string -} - -export class WorkflowManager { - workflows: Map - cache: Map - - constructor() - - loadWorkflow(id: string): Promise - saveWorkflow(id: string, data: object): Promise - deleteWorkflow(id: string): Promise - searchWorkflows(query: string): Promise -} - -export type NodeId = string -export type WorkflowId = string diff --git a/demo-snapshots/v1.30.2.json b/demo-snapshots/v1.30.2.json deleted file mode 100644 index 79d655223..000000000 --- a/demo-snapshots/v1.30.2.json +++ /dev/null @@ -1,311 +0,0 @@ -{ - "types": { - "NodeId": { - "kind": "type", - "name": "NodeId", - "text": "export type NodeId = string;", - "exported": true - }, - "WorkflowId": { - "kind": "type", - "name": "WorkflowId", - "text": "export type WorkflowId = string;", - "exported": true - } - }, - "interfaces": { - "ComfyApi": { - "kind": "interface", - "name": "ComfyApi", - "members": [ - { - "name": "apiURL", - "kind": "method", - "parameters": [ - { - "name": "path", - "type": "string", - "optional": false - } - ], - "returnType": "string" - }, - { - "name": "fileURL", - "kind": "method", - "parameters": [ - { - "name": "path", - "type": "string", - "optional": false - } - ], - "returnType": "string" - }, - { - "name": "queuePromptAsync", - "kind": "method", - "parameters": [ - { - "name": "prompt", - "type": "object", - "optional": false - }, - { - "name": "options", - "type": "{ priority?: number }", - "optional": true - } - ], - "returnType": "Promise<{ prompt_id: string; number: number }>" - }, - { - "name": "cancelPrompt", - "kind": "method", - "parameters": [ - { - "name": "prompt_id", - "type": "string", - "optional": false - } - ], - "returnType": "Promise" - }, - { - "name": "interrupt", - "kind": "method", - "parameters": [], - "returnType": "Promise" - }, - { - "name": "getQueueStatus", - "kind": "method", - "parameters": [], - "returnType": "Promise<{ queue_running: any[]; queue_pending: any[] }>" - } - ], - "exported": true, - "heritage": [] - }, - "NodeDef": { - "kind": "interface", - "name": "NodeDef", - "members": [ - { - "name": "name", - "type": "string", - "optional": false - }, - { - "name": "category", - "type": "string", - "optional": false - }, - { - "name": "display_name", - "type": "string", - "optional": true - }, - { - "name": "description", - "type": "string", - "optional": true - }, - { - "name": "python_module", - "type": "string", - "optional": false - }, - { - "name": "input", - "type": "{\n required?: Record;\n optional?: Record;\n }", - "optional": false - }, - { - "name": "output", - "type": "string[]", - "optional": false - }, - { - "name": "output_name", - "type": "string[]", - "optional": false - } - ], - "exported": true, - "heritage": [] - }, - "WorkflowMetadata": { - "kind": "interface", - "name": "WorkflowMetadata", - "members": [ - { - "name": "title", - "type": "string", - "optional": true - }, - { - "name": "description", - "type": "string", - "optional": true - }, - { - "name": "author", - "type": "string", - "optional": true - }, - { - "name": "version", - "type": "string", - "optional": true - }, - { - "name": "tags", - "type": "string[]", - "optional": true - }, - { - "name": "thumbnail", - "type": "string", - "optional": true - } - ], - "exported": true, - "heritage": [] - }, - "ExtensionMetadata": { - "kind": "interface", - "name": "ExtensionMetadata", - "members": [ - { - "name": "id", - "type": "string", - "optional": false - }, - { - "name": "name", - "type": "string", - "optional": false - }, - { - "name": "version", - "type": "string", - "optional": false - }, - { - "name": "description", - "type": "string", - "optional": true - } - ], - "exported": true, - "heritage": [] - } - }, - "enums": { - "NodeStatus": { - "kind": "enum", - "name": "NodeStatus", - "members": [ - { - "name": "IDLE", - "value": "\"idle\"" - }, - { - "name": "QUEUED", - "value": "\"queued\"" - }, - { - "name": "RUNNING", - "value": "\"running\"" - }, - { - "name": "ERROR", - "value": "\"error\"" - }, - { - "name": "COMPLETED", - "value": "\"completed\"" - } - ], - "exported": true - } - }, - "functions": {}, - "classes": { - "WorkflowManager": { - "kind": "class", - "name": "WorkflowManager", - "members": [ - { - "name": "workflows", - "type": "Map", - "visibility": "public" - }, - { - "name": "cache", - "type": "Map", - "visibility": "public" - } - ], - "methods": [ - { - "name": "loadWorkflow", - "parameters": [ - { - "name": "id", - "type": "string", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - }, - { - "name": "saveWorkflow", - "parameters": [ - { - "name": "id", - "type": "string", - "optional": false - }, - { - "name": "data", - "type": "object", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - }, - { - "name": "deleteWorkflow", - "parameters": [ - { - "name": "id", - "type": "string", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - }, - { - "name": "searchWorkflows", - "parameters": [ - { - "name": "query", - "type": "string", - "optional": false - } - ], - "returnType": "Promise", - "visibility": "public" - } - ], - "exported": true, - "heritage": [] - } - }, - "constants": {} -} diff --git a/eslint.config.ts b/eslint.config.ts index d9610e30e..6681d2126 100644 --- a/eslint.config.ts +++ b/eslint.config.ts @@ -58,8 +58,7 @@ export default defineConfig([ 'src/extensions/core/*', 'src/scripts/*', 'src/types/generatedManagerTypes.ts', - 'src/types/vue-shim.d.ts', - 'demo-snapshots/*' + 'src/types/vue-shim.d.ts' ] }, { diff --git a/scripts/compare-api-snapshots.js b/scripts/compare-api-snapshots.ts similarity index 99% rename from scripts/compare-api-snapshots.js rename to scripts/compare-api-snapshots.ts index bc93673c3..89f168b68 100644 --- a/scripts/compare-api-snapshots.js +++ b/scripts/compare-api-snapshots.ts @@ -441,4 +441,5 @@ function formatChange(change) { const changes = compareApis(previousApi, currentApi) const changelog = formatChangelog(changes, previousVersion, currentVersion) +// eslint-disable-next-line no-console console.log(changelog) diff --git a/scripts/snapshot-api.js b/scripts/snapshot-api.ts similarity index 99% rename from scripts/snapshot-api.js rename to scripts/snapshot-api.ts index 0fbce44c5..654417ca8 100644 --- a/scripts/snapshot-api.js +++ b/scripts/snapshot-api.ts @@ -310,4 +310,5 @@ const sourceFile = ts.createSourceFile( const apiSurface = extractApiSurface(sourceFile) // Output as JSON +// eslint-disable-next-line no-console console.log(JSON.stringify(apiSurface, null, 2))