Peer-provider auditing

flog check peers is a read-only audit for direct dependency declarations that act as providers for required peer dependencies:

flog check peers

The command discovers the containing project with the same package.json workspace and pnpm-workspace.yaml fallback rules as install. It audits the root importer and every workspace importer by default, even when invoked from a workspace or a nested directory. Current-directory position never narrows the audit.

Use workspace names, paths, owned files, or path globs to narrow it:

flog check peers --workspace @example/web --workspace packages/plugin

Exact and glob selectors cannot be mixed, and duplicate aliases or overlapping globs are errors. --cwd is intentionally unsupported; relative paths resolve from the invocation directory.

Classifications#

For each declaration in dependencies, devDependencies, or optionalDependencies that the baseline graph actually uses as a required peer provider, Flog removes that one declaration in memory and resolves the complete project again:

• equivalent candidate for removal means every affected peer need selects the same immutable provider snapshot and peer context automatically;
• resolution-changing candidate for removal means every affected peer need remains valid, but at least one provider version or context changes;
• required explicit provider means the counterfactual graph is invalid or an affected required peer need is no longer present and comparable.

These are dependency-graph findings, not source-code findings. Flog does not inspect imports, dynamic loading, configuration files, or other direct runtime usage. A candidate may therefore still be required by application code. Declarations in peerDependencies are compatibility contracts and are never removal candidates. Optional peer dependencies are not auto-installed and are not reported.

The audit resolves baseline and one-declaration counterfactuals entirely in memory. It may make authenticated registry metadata requests, but it does not write package.json, flog.lock, node_modules, package archives, lifecycle state, or workspace state. A valid lockfile supplies version preferences; a missing or platform-stale lockfile does not make the audit mutating.

JSON and CI#

--json writes a deterministic versioned document to standard output. Version 1 has this top-level shape:

{
  "version": 1,
  "check": "peers",
  "importers": [".", "apps/web"],
  "findings": [],
  "candidateCount": 0
}

Each finding records the importer path and name, declaration field/name/ specifier, classification, one baseline provider snapshot, the sorted counterfactualProviders snapshot array, and the affected consumers. Each consumer entry includes its immutable snapshot, required range, and baseline/counterfactual provider snapshots. Arrays are deterministically ordered. Human diagnostics remain on standard error while the JSON document is written to standard output.

Candidates do not fail the command by default. CI can enforce a policy with:

flog check peers --json --fail-on-candidates

Equivalent and resolution-changing candidates make that invocation exit unsuccessfully after writing the report. Invalid baseline configuration, registry failures, cancellation, malformed selectors, and other operational errors are failures regardless of this option.