release-analyzer

Spectrum Tokens Release Analyzer

A tool for analyzing Spectrum Tokens release history and generating data for change frequency visualization.

Overview

This tool parses the Spectrum Tokens repository's git tags and generates structured JSON data showing release patterns, frequency, and types. It handles the different tag formats used throughout the project's history:

• Legacy format: v12.2.0 (pre-monorepo)
• Stable monorepo format: @adobe/[email protected]
• Beta format: @adobe/[email protected]
• Snapshot format: @adobe/[email protected]

Installation

cd tools/release-analyzer
pnpm install

Usage

Command Line Interface

# Show summary statistics
node src/cli.js summary

# Generate full analysis JSON
node src/cli.js analyze --pretty --output analysis.json

# Generate stats-only JSON for visualization
node src/cli.js analyze --stats-only --pretty --output stats.json

Programmatic Usage

import { analyzeReleases } from "@adobe/spectrum-tokens-release-analyzer";

const analysis = analyzeReleases("./path/to/spectrum-tokens-repo");
console.log(analysis.stats);

Output Format

Full Analysis Output

{
  "releases": [
    {
      "tag": "@adobe/[email protected]",
      "version": "13.13.0",
      "major": 13,
      "minor": 13,
      "patch": 0,
      "prerelease": null,
      "date": "2024-12-01",
      "type": "stable",
      "format": "@adobe/spectrum-tokens@{version}",
      "packageName": "@adobe/spectrum-tokens"
    }
  ],
  "byType": {
    "legacy": [...],
    "stable": [...],
    "beta": [...],
    "snapshot": [...]
  },
  "snapshotFeatures": {
    "s2-foundations": [...],
    "types": [...],
    "table": [...]
  },
  "stats": {
    "total": 200,
    "byType": {
      "legacy": 104,
      "stable": 54,
      "beta": 58,
      "snapshot": 24
    },
    "snapshotFeatures": 11,
    "dateRange": {
      "earliest": "2022-12-14",
      "latest": "2024-12-01"
    }
  },
  "timeline": [
    {
      "date": "2023-04-11",
      "type": "legacy",
      "version": "12.2.0",
      "tag": "v12.2.0",
      "feature": null,
      "major": 12,
      "minor": 2,
      "patch": 0,
      "prerelease": null
    }
  ]
}

Stats-Only Output

Simplified output focused on visualization needs:

{
  "stats": {
    "total": 200,
    "byType": { ... },
    "snapshotFeatures": 11,
    "dateRange": { ... }
  },
  "timeline": [ ... ],
  "snapshotFeatures": [
    {
      "feature": "s2-foundations",
      "count": 6,
      "releases": [ ... ]
    }
  ]
}

Release Types

Legacy Releases

• Format: v{major}.{minor}.{patch}
• Example: v12.2.0
• Pre-monorepo releases (ended April 2023)

Stable Releases

• Format: @adobe/spectrum-tokens@{major}.{minor}.{patch}
• Example: @adobe/[email protected]
• Production-ready releases

Beta Releases

• Format: @adobe/spectrum-tokens@{major}.{minor}.{patch}-beta.{number}
• Example: @adobe/[email protected]
• Pre-release validation builds

Snapshot Releases

• Format: @adobe/[email protected]{feature}-{timestamp}
• Example: @adobe/[email protected]
• Experimental feature development builds

Visualization Integration

The generated JSON data is designed for consumption by visualization libraries:

• Timeline data: Chronological release history
• Type grouping: Separate streams for different release types
• Feature breakdown: Snapshot releases grouped by development initiative
• Statistics: Summary metrics for dashboard displays

Development

# Run tests
pnpm test

# Run in development mode
pnpm run dev summary

License

Apache-2.0