Platform Matrix Scanner

The Platform Matrix scanner collects signals that predict where builds will break when changing CI runners, containers, or CPU architectures. This intelligence is essential for migrations to ARM64, cloud provider changes, or containerization projects.

Detected Signals

Runtime Versions

Native Module Detection

Packages requiring native compilation are flagged with architecture implications:

OS Assumptions

Scripts in package.json are analyzed for platform-specific commands:

Container Images

Docker base images are extracted from Dockerfile and docker-compose.yml:

FROM node:20-alpine AS builder    # ← Detected
FROM nginx:1.25-alpine            # ← Detected

Use Cases

CI Runner Migration

Before moving from GitHub-hosted to self-hosted runners:

1. Run vg scan on your repository
2. Review platformMatrix.nativeModules for compilation requirements
3. Check platformMatrix.osAssumptions for script compatibility
4. Ensure target runner has required SDKs

ARM64 Transition

Before deploying to ARM64 (Apple Silicon, Graviton):

vg scan --format json | jq '.platformMatrix.nativeModules'

Verify each listed package has ARM64 support.

Containerization

When dockerizing an application:

1. Use platformMatrix.nodeVersion to select base image
2. Install system dependencies for packages in nativeModules
3. Use multi-stage builds to minimize image size

Example Output

{
  "platformMatrix": {
    "nodeVersion": {
      "declared": ">=20.0.0",
      "source": "package.json#engines.node"
    },
    "versionFiles": {
      ".nvmrc": "20.10.0",
      ".node-version": null
    },
    "nativeModules": [
      {
        "name": "sharp",
        "risk": "medium",
        "notes": "libvips required; prebuilt binaries available for most platforms"
      },
      {
        "name": "canvas",
        "risk": "high",
        "notes": "Requires cairo, pango system libraries"
      }
    ],
    "osAssumptions": [
      {
        "script": "prebuild",
        "pattern": "rm -rf dist",
        "recommendation": "Use rimraf for cross-platform compatibility"
      }
    ],
    "dockerImages": [
      { "image": "node:20-alpine", "file": "Dockerfile" },
      { "image": "nginx:1.25-alpine", "file": "docker-compose.yml" }
    ]
  }
}

Configuration

// vibgrate.config.ts
const config: VibgrateConfig = {
  scanners: {
    platformMatrix: {
      enabled: true,
      // Flag additional packages as native
      additionalNativeModules: ['better-sqlite3'],
    },
  },
};