topmark.cli.commands.check

topmark / cli / commands / check

TopMark check command.

Checks whether the TopMark header is present, needs updating or complies. Performs a dry-run check by default and applies changes when --apply is given.

Input modes supported

• Paths mode (default): one or more PATHS and/or --files-from FILE.
• Content on STDIN: a single - as the sole PATH plus --stdin-filename NAME.
• Lists on STDIN for ...-from: allow --files-from -, --include-from -, or --exclude-from - (exactly one may consume STDIN).

Output model

• TEXT output is console-oriented and may use -v / --quiet.
• Markdown output is document-oriented and ignores TEXT-only verbosity/quiet controls.
• JSON/NDJSON output is machine-readable and uses the full raw result set.

Examples:

Check files and print a human summary:

$ topmark check --summary src

Emit per-file objects in NDJSON (one per line):

$ topmark check --output-format=ndjson src pkg

Write changes and show diffs (human output only):

$ topmark check --apply --diff .

Read a single file's content from STDIN:

$ cat foo.py | topmark check - --stdin-filename foo.py

Read a list of paths from STDIN:

$ git ls-files | topmark check --files-from -

check_command

check_command(
    *,
    verbosity,
    quiet,
    color_mode,
    no_color,
    strict,
    no_config,
    config_files,
    stdin_filename,
    files_from,
    include_from,
    exclude_from,
    include_patterns,
    exclude_patterns,
    include_file_types,
    exclude_file_types,
    header_mutation_mode,
    allow_header_in_empty_files,
    empty_insert_mode,
    render_empty_header_when_no_fields,
    allow_reflow,
    allow_content_probe,
    apply_changes,
    write_mode,
    diff,
    summary_mode,
    report_scope,
    align_fields,
    relative_to,
    output_format,
)

Run the header check pipeline in dry-run or apply mode.

The command reads positional paths from click.get_current_context().args (Black-style) and supports three input styles:

1. Paths mode (default): PATHS and/or --files-from FILE.
2. Content-on-STDIN: use - as the sole PATH and provide --stdin-filename.
3. Lists-on-STDIN for one of the "...-from" options: --files-from -, --include-from -, or --exclude-from - (exactly one may consume STDIN).

Parameters:

Name	Type	Description	Default
verbosity	int	Increase TEXT output detail.	required
quiet	bool	Suppress TEXT output.	required
color_mode	ColorMode | None	Set the color mode (default: auto).	required
no_color	bool	bool: If set, disable color mode.	required
strict	bool | None	if True, report warnings as errors.	required
no_config	bool	If True, skip loading project/user configuration files.	required
config_files	list[str]	Additional configuration file paths to load and merge.	required
stdin_filename	str | None	Assumed filename when reading content from STDIN).	required
files_from	list[str]	Files that contain newline-delimited paths to add to the candidate set before filtering. Use - to read from STDIN.	required
include_from	list[str]	Files that contain include glob patterns (one per line). Use - to read patterns from STDIN.	required
exclude_from	list[str]	Files that contain exclude glob patterns (one per line). Use - to read patterns from STDIN.	required
include_patterns	list[str]	Glob patterns to include (intersection).	required
exclude_patterns	list[str]	Glob patterns to exclude (subtraction).	required
include_file_types	list[str]	Restrict processing to the given file type identifiers.	required
exclude_file_types	list[str]	Exclude processing for the given file type identifiers.	required
header_mutation_mode	HeaderMutationMode | None	Check-only header mutation mode override for this run (all, add-only, or update-only).	required
allow_header_in_empty_files	bool | None	Check-only override controlling whether headers may be inserted into files classified as empty under the effective empty insert mode.	required
empty_insert_mode	EmptyInsertMode | None	Check-only override for how TopMark classifies files as empty for header insertion policy (bytes-empty, logical-empty, or whitespace-empty).	required
render_empty_header_when_no_fields	bool | None	Check-only override controlling whether an otherwise empty header may be inserted when no fields are configured.	required
allow_reflow	bool | None	Check-only override controlling whether content reflow is allowed during header insertion or update.	required
allow_content_probe	bool | None	Shared policy override controlling whether file-type detection may consult file contents when needed.	required
apply_changes	bool	Write changes to files; otherwise perform a dry run.	required
write_mode	str | None	Whether to use safe atomic writing, faster in-place writing or writing to STDOUT (default: atomic writer).	required
diff	bool	Show unified diffs of header changes (human output only).	required
summary_mode	bool	Show outcome counts instead of per-file details.	required
report_scope	ReportScope	Reporting scope for human per-file output (actionable, noncompliant, all). Ignored for summary mode and machine-readable formats.	required
align_fields	bool	Whether to align header fields when rendering (captured in config).	required
relative_to	str | None	Base path used only for resolving header metadata (e.g., file_relpath).	required
output_format	OutputFormat | None	Output format to use (text, markdown, json, or ndjson). Verbosity and quiet controls apply only to TEXT output.	required

Exit Status

SUCCESS (0): No changes required or all requested changes were written. WOULD_CHANGE (2): Dry-run detected files that would change with --apply. USAGE_ERROR (64): Invalid invocation (e.g., mixing - with --files-from -). FILE_NOT_FOUND (66): One or more specified files or directories could not be found. PERMISSION_DENIED (77): Insufficient permissions to read or write a file. ENCODING_ERROR (65): A file could not be decoded or encoded with the expected encoding. IO_ERROR (74): An unexpected I/O failure occurred while writing changes. PIPELINE_ERROR (70): An internal processing step failed. UNEXPECTED_ERROR (255): An unhandled error occurred.

Source code in src/topmark/cli/commands/check.py

@click.command(
    name=CliCmd.CHECK,
    context_settings=PATH_COMMAND_CONTEXT_SETTINGS,
    help=f"Inspect TopMark headers (dry-run), or add/update them with {CliOpt.APPLY_CHANGES}.",
    epilog=(
        "\b\n"
        "Examples:\n"
        "  # Preview which files would change (dry-run)\n"
        f"  topmark {CliCmd.CHECK} src\n"
        "  # Apply header updates in place\n"
        f"  topmark {CliCmd.CHECK} {CliOpt.APPLY_CHANGES} .\n"
        "  # Restrict check/apply to adding missing headers only\n"
        f"  topmark {CliCmd.CHECK} "
        f"{CliOpt.POLICY_HEADER_MUTATION_MODE}={HeaderMutationMode.ADD_ONLY.value} src\n"
    ),
)
@common_color_options
@common_text_output_verbosity_options
@common_text_output_quiet_options
@config_strict_options
@common_config_resolution_options
@common_stdin_content_mode_options
@common_files_from_options
@common_include_exclude_from_options
@common_file_filtering_options
@common_file_type_filtering_options
@check_policy_options
@shared_policy_options
@common_apply_and_write_options
@render_diff_options
@pipeline_reporting_options
@common_header_formatting_options
@common_output_format_options
def check_command(
    *,
    # common_ui_options (verbosity, color):
    verbosity: int,
    quiet: bool,
    color_mode: ColorMode | None,
    no_color: bool,
    # config_strict_options:
    strict: bool | None,
    # common_config_resolution_options:
    no_config: bool,
    config_files: list[str],
    # common_stdin_content_mode_options:
    stdin_filename: str | None,
    # common_files_from_options:
    files_from: list[str],
    # common_include_exclude_from_options:
    include_from: list[str],
    exclude_from: list[str],
    # common_file_filtering_options:
    include_patterns: list[str],
    exclude_patterns: list[str],
    # common_file_type_filtering_options:
    include_file_types: list[str],
    exclude_file_types: list[str],
    # policy_options (only for `check`):
    header_mutation_mode: HeaderMutationMode | None,
    allow_header_in_empty_files: bool | None,
    empty_insert_mode: EmptyInsertMode | None,
    render_empty_header_when_no_fields: bool | None,
    allow_reflow: bool | None,
    # policy_options (shared):
    allow_content_probe: bool | None,
    # common_apply_and_write_options
    apply_changes: bool,
    write_mode: str | None,
    # render_diff_options:
    diff: bool,
    # pipeline_reporting_options
    summary_mode: bool,
    report_scope: ReportScope,
    # common_header_formatting_options:
    align_fields: bool,
    relative_to: str | None,
    # common_output_format_options:
    output_format: OutputFormat | None,
) -> None:
    """Run the header check pipeline in dry-run or apply mode.

    The command reads positional paths from ``click.get_current_context().args``
    (Black-style) and supports three input styles:

    1. Paths mode (default): PATHS and/or ``--files-from FILE``.
    2. Content-on-STDIN: use ``-`` as the sole PATH **and** provide ``--stdin-filename``.
    3. Lists-on-STDIN for one of the "...-from" options: ``--files-from -``,
       ``--include-from -``, or ``--exclude-from -`` (exactly one may consume STDIN).

    Args:
        verbosity: Increase TEXT output detail.
        quiet: Suppress TEXT output.
        color_mode: Set the color mode (default: auto).
        no_color: bool: If set, disable color mode.
        strict: if True, report warnings as errors.
        no_config: If True, skip loading project/user configuration files.
        config_files: Additional configuration file paths to load and merge.
        stdin_filename: Assumed filename when reading content from STDIN).
        files_from: Files that contain newline-delimited *paths* to add to the
            candidate set before filtering. Use ``-`` to read from STDIN.
        include_from: Files that contain include glob patterns (one per line).
            Use ``-`` to read patterns from STDIN.
        exclude_from: Files that contain exclude glob patterns (one per line).
            Use ``-`` to read patterns from STDIN.
        include_patterns: Glob patterns to *include* (intersection).
        exclude_patterns: Glob patterns to *exclude* (subtraction).
        include_file_types: Restrict processing to the given file type identifiers.
        exclude_file_types: Exclude processing for the given file type identifiers.
        header_mutation_mode: Check-only header mutation mode override for this
            run (`all`, `add-only`, or `update-only`).
        allow_header_in_empty_files: Check-only override controlling whether
            headers may be inserted into files classified as empty under the
            effective empty insert mode.
        empty_insert_mode: Check-only override for how TopMark classifies files
            as empty for header insertion policy (`bytes-empty`,
            `logical-empty`, or `whitespace-empty`).
        render_empty_header_when_no_fields: Check-only override controlling
            whether an otherwise empty header may be inserted when no fields are
            configured.
        allow_reflow: Check-only override controlling whether content reflow is
            allowed during header insertion or update.
        allow_content_probe: Shared policy override controlling whether
            file-type detection may consult file contents when needed.
        apply_changes: Write changes to files; otherwise perform a dry run.
        write_mode: Whether to use safe atomic writing, faster in-place writing
            or writing to STDOUT (default: atomic writer).
        diff: Show unified diffs of header changes (human output only).
        summary_mode: Show outcome counts instead of per-file details.
        report_scope: Reporting scope for human per-file output (`actionable`, `noncompliant`,
            `all`). Ignored for summary mode and machine-readable formats.
        align_fields: Whether to align header fields when rendering (captured in config).
        relative_to: Base path used only for resolving header metadata (e.g., `file_relpath`).
        output_format: Output format to use (``text``, ``markdown``, ``json``, or ``ndjson``).
            Verbosity and quiet controls apply only to TEXT output.

    Exit Status:
        SUCCESS (0): No changes required or all requested changes were written.
        WOULD_CHANGE (2): Dry-run detected files that would change with ``--apply``.
        USAGE_ERROR (64): Invalid invocation (e.g., mixing ``-`` with ``--files-from -``).
        FILE_NOT_FOUND (66): One or more specified files or directories could not be found.
        PERMISSION_DENIED (77): Insufficient permissions to read or write a file.
        ENCODING_ERROR (65): A file could not be decoded or encoded with the expected encoding.
        IO_ERROR (74): An unexpected I/O failure occurred while writing changes.
        PIPELINE_ERROR (70): An internal processing step failed.
        UNEXPECTED_ERROR (255): An unhandled error occurred.
    """
    ctx: click.Context = click.get_current_context()
    state: TopmarkCliState = bootstrap_cli_state(ctx)
    # Effective output format (stored early so shared initialization sees it).
    state.output_format = output_format or OutputFormat.TEXT

    # Initialize typed CLI state (TEXT verbosity/quiet, color mode, console).
    init_common_state(
        ctx,
        verbosity=verbosity,
        quiet=quiet,
        color_mode=color_mode,
        no_color=no_color,
    )

    # Effective TEXT verbosity for console-oriented progressive disclosure.
    verbosity_level: int = state.verbosity

    # Reject common unsupported option spellings that permissive path parsing
    # would otherwise pass through as positional input paths, such as `--stdin`.
    validate_common_forbidden_path_command_options_in_extra_args(ctx)

    # Machine metadata.
    meta: MetaPayload = build_meta_payload()

    # Effective output format.
    fmt: OutputFormat = state.output_format

    apply_color_policy_for_output_format(ctx, fmt=fmt)
    enable_color: bool = state.color_enabled

    # common_from_sources_options - Fail fast if a `--*-from -` option is used without piped STDIN.
    validate_stdin_dash_requires_piped_input(
        ctx,
        files_from=files_from,
        include_from=include_from,
        exclude_from=exclude_from,
    )

    validate_diff_policy_for_output_format(ctx, diff=diff, fmt=fmt)

    warn_if_report_scope_ignored(
        ctx,
        output_format=output_format or OutputFormat.TEXT,
        summary_mode=summary_mode,
        report_scope=report_scope,
    )

    # Test harnesses may inject this via
    # `CliRunner.invoke(..., obj=TopmarkCliState(prune_pipeline_views=True))`.
    prune_views: bool = state.prune_pipeline_views

    # Store command-scoped runtime values in typed state:
    state.apply_changes = apply_changes
    state.write_mode = write_mode

    # Store policy option values for ConfigOverrides construction.
    state.policy = MutablePolicy(
        header_mutation_mode=header_mutation_mode,
        allow_header_in_empty_files=allow_header_in_empty_files,
        empty_insert_mode=empty_insert_mode,
        render_empty_header_when_no_fields=render_empty_header_when_no_fields,
        allow_reflow=allow_reflow,
        allow_content_probe=allow_content_probe,
    )

    # Build layered config, runtime options, and file list.
    plan: InputPlan = plan_cli_inputs(
        ctx=ctx,
        files_from=files_from,
        include_from=include_from,
        exclude_from=exclude_from,
        include_patterns=include_patterns,
        exclude_patterns=exclude_patterns,
        stdin_filename=stdin_filename,
    )

    prepared_cli_config: PreparedCliConfig = build_resolved_toml_sources_and_config_for_plan(
        ctx=ctx,
        plan=plan,
        no_config=no_config,
        config_paths=config_files,
        strict=strict,
        include_file_types=include_file_types,
        exclude_file_types=exclude_file_types,
        align_fields=align_fields,
        relative_to=relative_to,
    )

    run_options: RunOptions = build_run_options(
        apply_changes=apply_changes,
        write_mode=write_mode,
        stdin_mode=plan.stdin_mode,
        stdin_filename=plan.stdin_filename,
        prune_views=prune_views,
        keep_diff_view=diff,
    )

    logger.debug("run options: %s", run_options)

    # Content-to-STDOUT modes: keep stdout clean for the rewritten file content.
    #
    # - STDIN content mode emits the updated file to stdout when --apply is set.
    # - write_mode="stdout" also emits updated content to stdout.
    #
    # In both cases, route all human-facing console output (summaries, warnings,
    # diagnostics) to stderr.
    #
    # Console selection must happen after planning inputs because stdin mode affects routing.
    console: ConsoleProtocol = maybe_route_console_to_stderr(
        ctx,
        run_options=run_options,
        enable_color=enable_color,
    )

    config: FrozenConfig = prepared_cli_config.draft.freeze()

    logger.trace("Run config after layered CLI overrides: %s", config)

    # Validate the effective configuration.
    try:
        ensure_config_valid(
            config,
            resolved=prepared_cli_config.resolved_toml,
        )
    except ConfigValidationError as exc:
        console.error(f"Processing stopped: {exc}")
        ctx.exit(ExitCode.CONFIG_ERROR)

    # Display config validation diagnostics before resolving files.
    # TEXT keeps these behind -v; Markdown renders diagnostics whenever present.
    flattened_diagnostics: FrozenDiagnosticLog = config.validation_logs.flattened()

    if fmt == OutputFormat.TEXT and verbosity_level > 0 and not state.quiet:
        console.print(
            render_diagnostics_text(
                diagnostics=flattened_diagnostics,
                verbosity_level=verbosity_level,
                color=enable_color,
            )
        )
    elif fmt == OutputFormat.MARKDOWN and len(flattened_diagnostics) > 0:
        console.print(
            render_diagnostics_markdown(
                diagnostics=flattened_diagnostics,
            )
        )

    temp_path: Path | None = plan.temp_path  # for cleanup/STDIN-apply branch

    file_resolution: FileListResolution = build_file_resolution(
        run_options=run_options,
        config=config,
        temp_path=temp_path,
    )
    file_list: list[Path] = list(file_resolution.selected)

    # Missing explicit literals are represented later as synthetic contexts.
    # They do not count as selected files for pipeline execution.
    if not file_resolution.missing_literals and exit_if_no_files(
        file_list,
        console=console,
        styled=enable_color,
    ):
        # Nothing to do
        return

    # Choose and run the concrete pipeline variant.
    pipeline_kind: PipelineKindLiteral = "check"
    pipeline: Sequence[Step[ProcessingContext]] = select_pipeline(
        pipeline_kind,
        apply=apply_changes,
        diff=diff,
    )

    pipeline_run: PipelineExecution = run_steps_for_files(
        run_options=run_options,
        config=config,
        path_configs=None,
        pipeline=pipeline,
        file_list=file_list,
    )
    results: list[ProcessingContext] = pipeline_run.results
    encountered_exit_code: ExitCode | None = pipeline_run.exit_code

    # Add resolver-level hard failures before deriving the process exit code so
    # explicit missing inputs participate in reports and priority selection.
    missing_results: list[ProcessingContext] = build_missing_file_contexts(
        paths=file_resolution.missing_literals,
        config=config,
        run_options=run_options,
    )
    results.extend(missing_results)

    pipeline_error_code: ExitCode | None = exit_code_from_pipeline_results(results)
    encountered_exit_code = encountered_exit_code or pipeline_error_code

    # Report scope is a human per-file listing policy only.
    #
    # - Machine-readable output must always use the full raw result set.
    # - Human summary mode must also use the full raw result set so aggregated
    #   counts are not distorted by per-file report filtering.
    # - Human non-summary output uses the filtered per-file view.
    filtered: ReportFilterResult = filter_results_for_report(
        results,
        report_scope=report_scope,
        would_change=effective_would_add_or_update,
    )

    human_results: list[ProcessingContext] = results if summary_mode else filtered.view_results

    if fmt in (OutputFormat.JSON, OutputFormat.NDJSON):
        emit_processing_results_machine(
            console=console,
            meta=meta,
            config=config,
            resolved_toml=prepared_cli_config.resolved_toml,
            results=results,
            fmt=fmt,
            summary_mode=summary_mode,
        )
    else:
        report = PipelineCommandHumanReport(
            cmd=CliCmd.CHECK,
            pipeline_kind=pipeline_kind,
            file_list_total=len(results),
            view_results=human_results,
            report_scope=report_scope,
            unsupported_count=filtered.unsupported_count_all,
            verbosity_level=verbosity_level,
            summary_mode=summary_mode,
            show_diffs=diff,
            apply_changes=apply_changes,
            styled=enable_color,
        )

        if fmt == OutputFormat.TEXT and not state.quiet:
            console.print(render_pipeline_output_text(report))
        elif fmt == OutputFormat.MARKDOWN:
            console.print(render_pipeline_output_markdown(report))

    if apply_changes:
        # Writes (only when --apply is set)
        if run_options.stdin_mode:
            # For STDIN content mode, the modified file content is emitted to stdout in WriterStep.
            # So we do not have to output it here.
            #
            # Cleanup the temp file.
            safe_unlink(temp_path)
            return
        else:
            # Count outcomes after writer statuses have been finalized.
            written: int = sum(1 for r in results if r.status.write == WriteStatus.WRITTEN)
            failed: int = sum(1 for r in results if r.status.write == WriteStatus.FAILED)

            # Emit apply summary. TEXT honors --quiet; Markdown remains document-oriented.
            if fmt == OutputFormat.TEXT and not state.quiet:
                console.print(
                    render_pipeline_apply_summary_text(
                        command_path=ctx.command_path,
                        written=written,
                        failed=failed,
                        styled=enable_color,
                    )
                )
            elif fmt == OutputFormat.MARKDOWN:
                console.print(
                    render_pipeline_apply_summary_markdown(
                        command_path=ctx.command_path,
                        written=written,
                        failed=failed,
                    )
                )

                console.print(render_version_footer_markdown())

            if failed:
                # Keep the user-facing apply summary above, but do not raise here.
                # `encountered_exit_code` already includes the prioritized
                # pipeline-derived exit code, so the centralized
                # `maybe_exit_on_error(...)` call below decides whether this run
                # exits as FILE_NOT_FOUND, PERMISSION_DENIED, ENCODING_ERROR, or
                # IO_ERROR.
                encountered_exit_code = encountered_exit_code or ExitCode.IO_ERROR

    else:
        if fmt == OutputFormat.MARKDOWN:
            console.print(render_version_footer_markdown())

    # Exit on any error encountered during processing. Pipeline errors must beat
    # the dry-run WOULD_CHANGE signal so access/encoding failures never exit as
    # a successful diff-only result.
    maybe_exit_on_error(
        code=encountered_exit_code,
        temp_path=temp_path,
    )

    if not apply_changes and any(effective_would_add_or_update(r) for r in results):
        ctx.exit(ExitCode.WOULD_CHANGE)

    # Cleanup temp file if any (shouldn't be needed except on errors)
    if temp_path and temp_path.exists():
        safe_unlink(temp_path)