🧠 API Reference

CLI

`doctor(path='.', verbose=False, debug=False, format='table', output=None, profile=None, rules=None)`

Run diagnostics on an Azure Functions application.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the Azure Functions app. Defaults to current directory.	`'.'`
`verbose`	`Annotated[bool, Option(-v, --verbose, help='Show detailed hints for failed checks')]`	Show detailed hints for failed checks.	`False`
`debug`	`Annotated[bool, Option(help='Enable debug logging')]`	Enable debug logging to stderr.	`False`
`format`	`Annotated[str, Option(help="Output format: 'table', 'json', 'sarif', or 'junit'")]`	Output format: 'table', 'json', 'sarif', or 'junit'.	`'table'`
`output`	`Annotated[Optional[Path], Option(help='Optional path to save output result')]`	Optional file path to save output result.	`None`
`profile`	`Annotated[Optional[str], Option(help="Rule profile: 'minimal' or 'full'")]`	Optional rule profile ('minimal' or 'full').	`None`
`rules`	`Annotated[Optional[Path], Option(help='Optional path to a custom rules.json')]`	Optional path to a custom rules.json.	`None`

Source code in src/azure_functions_doctor/cli.py

@cli.command(name="doctor")
def doctor(
    path: str = ".",
    verbose: Annotated[bool, typer.Option("-v", "--verbose", help="Show detailed hints for failed checks")] = False,
    debug: Annotated[bool, typer.Option(help="Enable debug logging")] = False,
    format: Annotated[str, typer.Option(help="Output format: 'table', 'json', 'sarif', or 'junit'")] = "table",
    output: Annotated[Optional[Path], typer.Option(help="Optional path to save output result")] = None,
    profile: Annotated[Optional[str], typer.Option(help="Rule profile: 'minimal' or 'full'")] = None,
    rules: Annotated[Optional[Path], typer.Option(help="Optional path to a custom rules.json")] = None,
) -> None:
    """
    Run diagnostics on an Azure Functions application.

    Args:
        path: Path to the Azure Functions app. Defaults to current directory.
        verbose: Show detailed hints for failed checks.
        debug: Enable debug logging to stderr.
        format: Output format: 'table', 'json', 'sarif', or 'junit'.
        output: Optional file path to save output result.
        profile: Optional rule profile ('minimal' or 'full').
        rules: Optional path to a custom rules.json.
    """
    # Validate inputs before proceeding
    _validate_inputs(path, format, output)

    if rules is not None and not rules.exists():
        raise typer.BadParameter(f"Rules path does not exist: {rules}")

    # Configure logging based on CLI flags
    if debug:
        setup_logging(level="DEBUG", format_style="structured")
    else:
        # Use environment variable or default to WARNING
        setup_logging(level=None, format_style="simple")

    start_time = time.time()
    # Allow v1 projects when invoked from CLI so we can show warning but continue
    doctor = Doctor(path, allow_v1=True, profile=profile, rules_path=rules)
    resolved_path = Path(path).resolve()

    # Log diagnostic start
    loaded_rules = doctor.load_rules()
    log_diagnostic_start(str(resolved_path), len(loaded_rules))
    results = doctor.run_all_checks(rules=loaded_rules)

    # Calculate execution metrics
    end_time = time.time()
    duration_ms = (end_time - start_time) * 1000

    # Count results for logging
    total_checks = sum(len(section["items"]) for section in results)
    passed_items = sum(1 for section in results for item in section["items"] if item.get("status") == "pass")
    failed_items = sum(1 for section in results for item in section["items"] if item.get("status") == "fail")
    # Note: handlers currently only return "pass"/"fail", not "error"
    errors = 0

    # Log diagnostic completion
    log_diagnostic_complete(total_checks, passed_items, failed_items, errors, duration_ms)

    # Pre-compute aggregated counts from normalized item['status'] values
    passed_count = 0
    warning_count = 0  # explicit 'warn' statuses
    fail_count = 0  # explicit 'fail' statuses
    for section in results:
        for item in section["items"]:
            s = item.get("status")
            if s == "pass":
                passed_count += 1
            elif s == "warn":
                warning_count += 1
            elif s == "fail":
                fail_count += 1
            else:
                warning_count += 1  # unknown treated as warning

    if format == "json":
        generated_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
        metadata = {
            "tool_version": __version__,
            "generated_at": generated_at,
            "target_path": str(Path(path).resolve()),
        }
        json_output = {"metadata": metadata, "results": results}
        _write_output(json.dumps(json_output, indent=2), output, "JSON")
        raise typer.Exit(1 if fail_count > 0 else 0)

    if format == "sarif":
        sarif_results = []
        for section in results:
            for item in section["items"]:
                status = item.get("status")
                if status == "pass":
                    continue
                level = "error" if status == "fail" else "warning"
                sarif_results.append(
                    {
                        "ruleId": item.get("label", ""),
                        "message": {"text": item.get("value", "")},
                        "level": level,
                    }
                )

        sarif_output = {
            "version": "2.1.0",
            "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
            "runs": [
                {
                    "tool": {
                        "driver": {
                            "name": "azure-functions-doctor",
                            "version": __version__,
                        }
                    },
                    "results": sarif_results,
                }
            ],
        }
        _write_output(json.dumps(sarif_output, indent=2), output, "SARIF")
        raise typer.Exit(1 if fail_count > 0 else 0)

    if format == "junit":
        import xml.etree.ElementTree as ET

        tests = 0
        failures = 0
        suite = ET.Element(
            "testsuite",
            name="func-doctor",
            tests="0",
            failures="0",
            time=f"{duration_ms / 1000:.3f}",
        )

        for section in results:
            for item in section["items"]:
                tests += 1
                case = ET.SubElement(suite, "testcase", classname=section["title"], name=item.get("label", ""))
                status = item.get("status")
                if status != "pass":
                    failures += 1
                    failure = ET.SubElement(case, "failure", message=item.get("value", ""))
                    failure.text = item.get("hint", "")

        suite.set("tests", str(tests))
        suite.set("failures", str(failures))
        junit_output = ET.tostring(suite, encoding="utf-8", xml_declaration=True).decode("utf-8")
        _write_output(junit_output, output, "JUnit")
        raise typer.Exit(1 if fail_count > 0 else 0)

    # Note: Top header removed per UI change; programming model header intentionally omitted

    if debug:
        console.print("[dim]Debug logging enabled - check stderr for detailed logs[/dim]\n")

    # Table-format user-facing output (requested design)
    console.print("Azure Functions Doctor   ")
    console.print(f"Path: {resolved_path}")

    # Print each section with simple title and items
    for section in results:
        console.print()
        console.print(section["title"])

        for item in section["items"]:
            label = item.get("label", "")
            value = item.get("value", "")
            status = item.get("status", "pass")
            icon = format_status_icon(status)

            # Compose main line: [ICON] Label: value (status)
            line = Text.assemble((f"[{icon}] ", "bold"), (label, "dim"))
            if value:
                line.append(": ")
                line.append(format_detail(status, value))

            # append status in parentheses for clarity on UI when non-pass
            if status != "pass":
                line.append(f" ({status})", "italic dim")

            console.print(line)

            # show hint as 'fix:' only when verbose is enabled
            if status != "pass" and verbose:
                hint = item.get("hint", "")
                if hint:
                    prefix = "↪ "
                    console.print(f"    {prefix}fix: {hint}")

    # Use the precomputed counts from earlier for final output
    console.print()
    # Print Doctor summary at the bottom like the requested sample
    console.print("Doctor summary (to see all details, run azure-functions doctor -v):")
    # Use singular/plural simple form as in sample (error vs errors)
    # Summary now reflects canonical statuses: fails, warnings, passed
    w_label = "warning" if warning_count == 1 else "warnings"
    f_label = "fail" if fail_count == 1 else "fails"
    # 'passed' label remains same for singular/plural in current design
    console.print(f"  {fail_count} {f_label}, {warning_count} {w_label}, {passed_count} passed")
    exit_code = 1 if fail_count > 0 else 0
    console.print(f"Exit code: {exit_code}")
    if exit_code != 0:
        raise typer.Exit(exit_code)

Doctor

`Doctor(path='.', allow_v1=False, profile=None, rules_path=None)`

Diagnostic runner for Azure Functions apps.

Loads checks from model-specific rule assets located in azure_functions_doctor.assets.rules.v1.json and v2.json. Legacy rules.json support has been removed; callers should ensure the appropriate v1/v2 files are present in package assets.

Source code in src/azure_functions_doctor/doctor.py

def __init__(
    self,
    path: str = ".",
    allow_v1: bool = False,
    profile: Optional[str] = None,
    rules_path: Optional[Path] = None,
) -> None:
    self.project_path: Path = Path(path).resolve()
    self.profile = profile
    self.rules_path: Optional[Path] = None
    if rules_path is not None:
        resolved = rules_path.resolve()
        if not resolved.is_file():
            raise ValueError(f"rules_path must be an existing file: {resolved}")
        self.rules_path = resolved
    self.programming_model = self._detect_programming_model()
    # If v1 detected in nested function folders (function.json not at project root)
    # and caller did not allow v1, signal incompatibility.
    function_json_files = list(self.project_path.rglob("function.json"))
    nested_v1 = any(f.parent.resolve() != self.project_path for f in function_json_files)

    if nested_v1 and not allow_v1:
        raise SystemExit("v1 programming model detected - limited support")

`load_rules()`

Load and validate rules based on detected programming model or custom path.

Source code in src/azure_functions_doctor/doctor.py

def load_rules(self) -> list[Rule]:
    """Load and validate rules based on detected programming model or custom path."""
    if self.rules_path is not None:
        with self.rules_path.open(encoding="utf-8") as f:
            rules: list[Rule] = json.load(f)
    elif self.programming_model == "v2":
        rules = self._load_v2_rules()
    elif self.programming_model == "v1":
        rules = self._load_v1_rules()
    else:
        raise RuntimeError("Unknown programming model; no rules to load")

    self._validate_rules(rules)
    return sorted(rules, key=lambda r: r.get("check_order", 999))

Handlers

`HandlerRegistry()`

Registry for diagnostic check handlers with individual handler methods.

Source code in src/azure_functions_doctor/handlers.py

def __init__(self) -> None:
    self._handlers = {
        "compare_version": self._handle_compare_version,
        "env_var_exists": self._handle_env_var_exists,
        "path_exists": self._handle_path_exists,
        "file_exists": self._handle_file_exists,
        "package_installed": self._handle_package_installed,
        "package_declared": self._handle_package_declared,
        "source_code_contains": self._handle_source_code_contains,
        "conditional_exists": self._handle_conditional_exists,
        "callable_detection": self._handle_callable_detection,
        "executable_exists": self._handle_executable_exists,
        "any_of_exists": self._handle_any_of_exists,
        "file_glob_check": self._handle_file_glob_check,
        "host_json_property": self._handle_host_json_property,
        "binding_validation": self._handle_binding_validation,
        "cron_validation": self._handle_cron_validation,
    }

`handle(rule, path)`

Route rule execution to appropriate handler.

Source code in src/azure_functions_doctor/handlers.py

def handle(self, rule: Rule, path: Path) -> dict[str, str]:
    """Route rule execution to appropriate handler."""
    check_type = rule.get("type")
    if check_type is None:
        return _create_result("fail", "Missing check type in rule")
    handler = self._handlers.get(check_type)

    if not handler:
        return _create_result("fail", f"Unknown check type: {check_type}")

    try:
        return handler(rule, path)
    except Exception as exc:
        return _handle_specific_exceptions(f"executing {check_type} check", exc)

`generic_handler(rule, path)`

Execute a diagnostic rule based on its type and condition.

This function maintains backward compatibility while delegating to the registry.

Parameters:

Name	Type	Description	Default
`rule`	`Rule`	The diagnostic rule to execute.	required
`path`	`Path`	Path to the Azure Functions project.	required

Returns:

Type	Description
`dict[str, str]`	A dictionary with the status and detail of the check.

Source code in src/azure_functions_doctor/handlers.py

def generic_handler(rule: Rule, path: Path) -> dict[str, str]:
    """
    Execute a diagnostic rule based on its type and condition.

    This function maintains backward compatibility while delegating to the registry.

    Args:
        rule: The diagnostic rule to execute.
        path: Path to the Azure Functions project.

    Returns:
        A dictionary with the status and detail of the check.
    """
    return _registry.handle(rule, path)

Configuration

Configuration management for Azure Functions Doctor.

Environment variables with FUNC_DOCTOR_ prefix (e.g. FUNC_DOCTOR_LOG_LEVEL) are loaded into Config. These options are reserved for future use; the CLI currently configures logging via logging_config.setup_logging() and does not read from Config. When wiring Config into the CLI/Doctor (e.g. max_file_size_mb, search_timeout_seconds), update this module and the CLI entry point.

`Config()`

Centralized configuration management with environment variable support.

Options (max_file_size_mb, search_timeout_seconds, etc.) are for future use; not yet wired into the CLI or Doctor. Use get_config() to access the global instance.