doctor

Non-mutating health check of a wiki’s docs/ structure and git clone.

CLASS	DESCRIPTION
`DoctorReport`	Result of a `doctor` health check. Non-mutating: built entirely from reads.

FUNCTION	DESCRIPTION
`check_shallow_clone`	Return True if `root` is a shallow git clone, False if not, None if not a git repo.
`check_skills_version_drift`	Compare the local `.agents/skills/.provenance` version to the installed `wiki_toolkit` version.
`run_doctor`	Run the non-mutating `doctor` health check against `docs_dir`.
`validate_jsonl`	Return a list of error messages for malformed lines in a JSONL file, empty if well-formed.

Classes¶

DoctorReport `dataclass` ¶

DoctorReport(
    python_version: str,
    docs_dir: Path,
    docs_dir_source: ContextConfigSource,
    missing_structure: list[str] = list(),
    present_structure: list[str] = list(),
    note_count: int = 0,
    is_shallow_clone: bool | None = None,
    jsonl_errors: dict[str, list[str]] = dict(),
    skills_version_drift: tuple[str, str] | None = None,
    sources: dict[str, ContextConfigSource] = dict(),
    dual_config_files: bool = False,
    repo_root_fallback: bool = False,
    invalid_sources: dict[str, ContextConfigSource] = dict(),
)

Result of a doctor health check. Non-mutating: built entirely from reads.

ATTRIBUTE	DESCRIPTION
`ok`	True if no missing structure, no shallow clone, no malformed JSONL, and no skills version drift. TYPE: `bool`

Attributes¶

ok `property` ¶

ok: bool

True if no missing structure, no shallow clone, no malformed JSONL, and no skills version drift.

Functions:¶

check_shallow_clone ¶

check_shallow_clone(root: Path) -> bool | None

Return True if root is a shallow git clone, False if not, None if not a git repo.

check_skills_version_drift ¶

check_skills_version_drift(docs_dir: Path) -> tuple[str, str] | None

Compare the local .agents/skills/.provenance version to the installed wiki_toolkit version.

Returns (local_version, installed_version) if they differ, None if they match or no local copy’s provenance marker exists.

run_doctor ¶

run_doctor(
    docs_dir: Path,
    root: Path | None = None,
    docs_dir_source: ContextConfigSource = "default",
    sources: dict[str, ContextConfigSource] | None = None,
    cwd: Path | None = None,
) -> DoctorReport

Run the non-mutating doctor health check against docs_dir.

root is the git repository root used for the shallow-clone check; it defaults to docs_dir’s parent, the common case where docs_dir is a docs/ subdirectory of the repo.

sources is the full per-field source mapping from build_context() (docs_dir, repo_root, branch_prefix, batch_byte_cap, batch_file_cap); when given, the report also carries settings-resolution warnings (dual config files, a repo_root that fell back to cwd, any field whose resolved value fell back to default because an upstream tier’s value was invalid). When omitted, only docs_dir_source is tracked, matching the tool’s pre-settings-diagnostics behavior.

validate_jsonl ¶

validate_jsonl(path: Path) -> list[str]

Return a list of error messages for malformed lines in a JSONL file, empty if well-formed.