Dies ist die deutsche MFDoctor-Dokumentation. Technische Bezeichner, CLI-Flags, Regel-IDs und Codebeispiele bleiben unverändert, damit die Inhalte zwischen den Sprachen vollständig kompatibel bleiben. Verwenden Sie den Sprachumschalter für die kanonische englische Fassung.

CLI command reference

The build plugin is the primary MFDoctor experience. Use the CLI for a local check, a cross-project federation gate, baseline maintenance, runtime trace correlation, or a deliberate deployed-manifest probe. MFDoctor is not a CLI-only source scanner and does not inject an agent into the browser. The build plugin remains the primary integration; use the CLI for tasks outside a bundler emit.

After installing @tonoizer/mfdoctor as a development dependency, run the binary through your package manager or a package script:

pnpm exec mfdoctor check

The examples below use the shorter mfdoctor form.

Einen Befehl auswählen

Command	Use it for	Network access
`check`	Analyze one project or checkout	No
`workspace`	Discover built MFDoctor project facts below one or more roots and gate the full federation	No
`federation`	Analyze explicit `project.json` globs, or use workspace discovery explicitly	No
`baseline`	Generate, extend, or prune accepted finding fingerprints	No
`runtime`	Correlate an Observability export with local MFDoctor project facts	No
`prompt`	Reprint fix prompts from a saved MFDoctor report	No
`rules`	Inspect all built-in rules or one rule's metadata	No
`probe`	Validate a deployed manifest and optionally its remote entry	Yes

MFDoctor loads an optional mfdoctor.config.ts; command-line flags override its values. Use extends for named presets and shareable policy packs.

Ein Projekt prüfen

mfdoctor check

Analyzes the current working directory. Use a positional path to analyze a different project:

mfdoctor check packages/host --ci

--ci applies CI policy even when MFDoctor does not detect a CI environment. It defaults failOn to error and output to terminal, JSON, and SARIF. Local development defaults failOn to never, so findings print without breaking the build.

Report-Formate auswählen

mfdoctor check --format terminal,json,sarif

Accepted formats are terminal, json, and sarif. JSON and SARIF artifacts are written below .mf/doctor/. A format list containing only json or sarif does not add human-readable terminal output.

Akzeptierte technische Schulden anwenden

mfdoctor check --baseline ./mfdoctor.baseline.json

Matching findings remain visible but are marked as suppressed and do not fail policy by default. Treat the file as tracked debt and shrink it as issues are fixed. See Fingerprint baselines.

Terminalausgabe steuern

mfdoctor check --verbose
mfdoctor check --no-score
mfdoctor check --no-prompt
mfdoctor check --prompt

MFDoctor is quiet when a check has no findings. --verbose restores the green success line.
--no-score hides the terminal health score. Report JSON still contains summary.score and summary.scoreLabel.
--no-prompt hides the copy-paste fix prompts printed after findings.
--prompt force-enables those prompts, including when config disables them.

You can also set MFDOCTOR_QUIET=0 to show successful checks or MFDOCTOR_QUIET=1 to force quiet success. Environment configuration wins over the file configuration.

Ein Diagnose-Bundle schreiben

mfdoctor check --diagnostics-dir .mf/doctor/diagnostics

Writes report.json, summary.md, and prompts/*.md to a directory inside the project root. MFDoctor rejects a diagnostics path that escapes the project.

Agenten-Lösungsprompts ausgeben

mfdoctor prompt
mfdoctor prompt --finding config/name-required
mfdoctor prompt --finding <fingerprint> .mf/doctor/report.json

prompt reads .mf/doctor/report.json by default. Without --finding, it prints up to three prompts for the highest-priority non-suppressed findings. Pass a rule ID or exact finding fingerprint to print one prompt. This command does not re-run analysis.

Einen Workspace prüfen

Build each app with its MFDoctor adapter first so it emits .mf/doctor/project.json, then run one cross-project gate:

mfdoctor workspace
mfdoctor workspace apps packages --format terminal,json,sarif
mfdoctor workspace apps packages --group checkout

With no roots, workspace searches below the current directory.
Positional values such as apps packages are discovery roots.
Discovery looks for **/.mf/doctor/project.json beneath each root.
--group checkout includes only projects assigned to that explicit federationGroup, which keeps independent federation graphs separate.

Override the discovery layout only when the defaults do not fit:

mfdoctor workspace --glob "packages/*/.mf/doctor/project.json"

Quote globs so the CLI—not the shell—expands them consistently.

Eine Federation prüfen

Use federation --workspace when you want to spell out that workspace discovery feeds federation analysis. It runs the same discovery and analysis path as workspace:

mfdoctor federation --workspace
mfdoctor federation --workspace apps packages --format terminal,json,sarif
mfdoctor federation --workspace apps packages --group checkout

For a hand-tuned CI layout, pass one or more quoted project.json patterns without --workspace:

mfdoctor federation ".mf/doctor/**/project.json"
mfdoctor federation ".mf/doctor/**/project.json" --baseline ./mfdoctor.baseline.json

Use workspace for normal monorepo discovery. Use explicit federation globs when the reports live in a custom location or CI has already selected an exact set of project files.

Manage a baseline

All three commands read .mf/doctor/report.json and write mfdoctor.baseline.json by default. The explicit forms are:

mfdoctor baseline generate .mf/doctor/report.json --out mfdoctor.baseline.json
mfdoctor baseline update .mf/doctor/report.json --out mfdoctor.baseline.json
mfdoctor baseline prune .mf/doctor/report.json --out mfdoctor.baseline.json

Action	Effect
`generate`	Replace the output with the unique current finding fingerprints.
`update`	Add new current fingerprints while retaining existing entries. A missing output file starts empty.
`prune`	Remove entries that no longer match the current report. It requires an existing baseline.

Review baseline changes like code. Do not automatically update the baseline on every CI run, because that would silently accept new debt.

Eine Laufzeitspur korrelieren

mfdoctor runtime ./trace.json
mfdoctor runtime ./trace.json ".mf/doctor/**/project.json" --format terminal,json

runtime reads a user-supplied Module Federation Observability export and correlates it with local MFDoctor project facts. Project files default to .mf/doctor/**/project.json. You may instead set runtimeTrace in mfdoctor.config and omit the trace path.

MFDoctor never fetches URLs found in a trace and never executes remote JavaScript. It collapses trace URLs to origin plus basename and redacts token, cookie, authorization, password, and secret fields before emitting findings.

Regelkatalog prüfen

mfdoctor rules
mfdoctor rules config/name-required

With no rule ID, rules prints the machine-readable built-in catalog as JSON. With one ID, it prints that rule's default severity, category, impact, fix, supported bundlers, docs path, and official sources. An unknown rule exits 2.

Ein bereitgestelltes Manifest prüfen

mfdoctor probe https://cdn.example.com/mf-manifest.json
mfdoctor probe http://localhost:3001/mf-manifest.json --remote-entry

probe is the only command that makes a network request. It downloads the manifest, validates that it looks like a federation manifest, and prints a small JSON summary. Query strings are removed from output so signed URLs do not leak into logs.

--remote-entry sends a HEAD request to the entry named by the manifest and reports its status, content type, and size. MFDoctor does not download or execute that JavaScript.

Safety defaults:

HTTPS is required, except for an initial localhost or loopback URL.
The timeout is 10 seconds; override it with --timeout 5000.
The manifest limit is 2 MiB; override it with --max-bytes 1000000.
Redirects are revalidated at every hop and limited to five.
Private, link-local, loopback, and cloud-metadata targets are blocked by the public CLI probe.
URLs containing user names or passwords are rejected.

An unreachable or invalid target exits 2. A valid manifest whose requested remote entry returns an HTTP error exits 1.

Exit codes

Code	Meaning
`0`	Analysis completed and the active policy passed.
`1`	Findings failed policy, or a requested remote entry returned an HTTP error.
`2`	Invalid arguments, missing inputs, incomplete analysis, an unknown rule, or another hard failure.

GitHub Actions

Run the workspace gate after the federated apps have emitted their MFDoctor project facts. Pin the Action to a release tag (not @main) so CI stays reproducible:

permissions:
  contents: read
  security-events: write

jobs:
  federation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: voidzero-dev/setup-vp@v1.17.0
        with:
          node-version: 26
          cache: true
      - run: pnpm --filter './apps/docs' build
      - uses: tonoizer/module-federation-doctor/.github/actions/workspace-federation-gate@1.0.0
        with:
          roots: .
          cli: pnpm exec mfdoctor
          formats: terminal,json,sarif

The Action requires a runnable mfdoctor CLI (cli input); missing CLI is a hard failure. upload-sarif needs permissions.security-events: write and fails loudly when that permission is missing.

Optional action inputs are build-command, globs, upload-sarif, and upload-artifact. You can also run the CLI directly and upload .mf/doctor/results.sarif with github/codeql-action/upload-sarif when code scanning is enabled.

#CLI command reference

#Einen Befehl auswählen

#Ein Projekt prüfen

#Report-Formate auswählen

#Akzeptierte technische Schulden anwenden

#Terminalausgabe steuern

#Ein Diagnose-Bundle schreiben

#Agenten-Lösungsprompts ausgeben

#Einen Workspace prüfen

#Eine Federation prüfen

#Manage a baseline

#Eine Laufzeitspur korrelieren

#Regelkatalog prüfen

#Ein bereitgestelltes Manifest prüfen

#Exit codes

#GitHub Actions