Platform Matrix Scanner - CLI Documentation

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

Signal	Source File	Example Value
Node.js engine	`package.json` → `engines.node`	`>=20.0.0`
npm/pnpm engine	`package.json` → `engines.npm`	`>=9.0.0`
Node version file	`.nvmrc`, `.node-version`	`20.10.0`
.NET Target Framework	`.csproj` → `TargetFramework`	`net8.0`
.NET SDK version	`global.json`	`8.0.100`
Python version	`pyproject.toml`, `.python-version`	`3.11`

Native Module Detection

Packages requiring native compilation are flagged with architecture implications:

Package	Risk Level	Notes
`sharp`	🟡 Medium	libvips dependency, prebuilt binaries available
`bcrypt`	🟡 Medium	C++ compilation required
`canvas`	🔴 High	cairo, pango dependencies
`node-gyp` consumers	varies	Explicit compilation step
`fsevents`	🟢 Low	macOS only, gracefully ignored elsewhere

Tip: Native modules are the #1 cause of CI failures when migrating to different architectures. Review the list carefully before ARM64 transitions.

OS Assumptions

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

Pattern	Detection
`rm -rf`, `cp -r`	Unix-only commands
`if [ -f ...`	Bash conditionals
`C:\` paths	Windows-only paths
`chmod`, `ln -s`	Unix permissions/symlinks

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:

Run vg scan on your repository
Review platformMatrix.nativeModules for compilation requirements
Check platformMatrix.osAssumptions for script compatibility
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:

Use platformMatrix.nodeVersion to select base image
Install system dependencies for packages in nativeModules
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'],
    },
  },
};