haconf 0.1.0__py3-none-any.whl

haconf/__init__.py

@@ -0,0 +1,16 @@
+"""haconf — check Home Assistant YAML and Jinja before reload; no instance needed.
+
+Exit-code contract (deviation D-HC-1, logged in the I1 commit and the README):
+
+    0   clean
+    1   findings
+    64  usage errors — a deliberate extension of the contract's 0/1, same
+        rationale as RestVerify's D-I1: a usage failure is not a lint outcome
+        and must not collide with 1.
+"""
+
+__version__ = "0.1.0"
+
+EXIT_CLEAN = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 64

haconf/__main__.py

@@ -0,0 +1,9 @@
+"""``python -m haconf`` entry point."""
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

haconf/catalog/v0.1/integrations.json

@@ -0,0 +1,165 @@
+{
+  "integrations": {
+    "automation": {
+      "shape": "list_of_maps",
+      "keys": ["alias", "id", "description", "mode", "max", "max_exceeded", "initial_state", "trace", "variables", "trigger", "triggers", "condition", "conditions", "action", "actions", "timestamp", "last_triggered", "use_blueprint"]
+    },
+    "script": {
+      "shape": "entity_map",
+      "keys": ["alias", "id", "description", "icon", "mode", "max", "max_exceeded", "fields", "variables", "sequence", "trace", "continue_on_error", "use_blueprint"]
+    },
+    "scene": {
+      "shape": "list_of_maps",
+      "keys": ["id", "name", "icon", "entities", "description"]
+    },
+    "command_line": {
+      "shape": "list_of_maps",
+      "keys": ["switch", "sensor", "binary_sensor", "cover"]
+    },
+    "rest": {
+      "shape": "list_of_maps",
+      "keys": ["resource", "method", "headers", "params", "payload", "verify_ssl", "timeout", "scan_interval", "authentication", "username", "password", "sensor", "binary_sensor"]
+    },
+    "zone": {
+      "shape": "list_of_maps",
+      "keys": ["name", "latitude", "longitude", "radius", "icon", "passive", "track_ios"]
+    },
+    "person": {
+      "shape": "list_of_maps",
+      "keys": ["name", "id", "user_id", "device_trackers", "picture"]
+    },
+    "sensor": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "state", "unit_of_measurement", "device_class", "state_class", "icon", "availability", "scan_interval", "value_template", "json_attributes", "json_attributes_topic", "json_attributes_path", "last_reset"]
+    },
+    "binary_sensor": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "state", "device_class", "icon", "delay_on", "delay_off", "availability", "value_template", "scan_interval", "json_attributes"]
+    },
+    "switch": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "device_class", "optimistic", "state", "command_on", "command_off", "state_topic", "command_topic", "value_template", "availability", "scan_interval"]
+    },
+    "light": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "optimistic", "state", "command_on", "command_off", "state_topic", "command_topic", "brightness", "color_temp", "value_template", "availability", "scan_interval"]
+    },
+    "cover": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "device_class", "optimistic", "state", "command_open", "command_close", "command_stop", "position_template", "state_template", "value_template", "availability", "scan_interval"]
+    },
+    "lock": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "optimistic", "state", "command", "value_template", "availability", "scan_interval"]
+    },
+    "fan": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "optimistic", "state", "command_on", "command_off", "state_topic", "command_topic", "percentage", "value_template", "availability", "scan_interval"]
+    },
+    "number": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "min", "max", "step", "mode", "unit_of_measurement", "value_template", "command_template", "set_value", "optimistic", "availability", "scan_interval"]
+    },
+    "select": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "options", "value_template", "command_template", "optimistic", "availability", "scan_interval"]
+    },
+    "button": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "command", "availability", "scan_interval"]
+    },
+    "update": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "state", "latest_version", "installed_version", "device_class", "value_template", "availability", "scan_interval"]
+    },
+    "camera": {
+      "shape": "platform_list",
+      "keys": ["platform", "name", "unique_id", "icon", "still_image_url", "stream_source", "verify_ssl", "availability", "scan_interval"]
+    },
+    "input_boolean": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "initial", "unique_id"]
+    },
+    "input_number": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "initial", "min", "max", "step", "mode", "unit_of_measurement", "unique_id"]
+    },
+    "input_select": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "options", "initial", "unique_id"]
+    },
+    "input_text": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "initial", "min", "max", "mode", "pattern", "unique_id"]
+    },
+    "input_datetime": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "has_date", "has_time", "initial", "unique_id"]
+    },
+    "input_button": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "unique_id"]
+    },
+    "counter": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "initial", "step", "minimum", "maximum", "restore", "unique_id"]
+    },
+    "timer": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "duration", "restore", "unique_id"]
+    },
+    "utility_meter": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "source", "cycle", "offset", "delta_values", "net_consumption", "tariffs", "periodically_reset_factor", "always_available", "unique_id"]
+    },
+    "group": {
+      "shape": "entity_map",
+      "keys": ["name", "icon", "entities", "all", "unique_id"]
+    },
+    "homeassistant": {
+      "shape": "options_map",
+      "keys": ["name", "latitude", "longitude", "elevation", "unit_system", "time_zone", "currency", "country", "language", "packages", "customize", "customize_domain", "customize_glob", "allowlist_external_dirs", "allowlist_external_urls", "media_dirs", "legacy_templates", "internal_url", "external_url"]
+    },
+    "recorder": {
+      "shape": "options_map",
+      "keys": ["db_url", "purge_keep_days", "auto_purge", "auto_repack", "commit_interval", "include", "exclude", "include_entities", "exclude_entities", "include_domains", "exclude_domains", "include_entity_globs", "exclude_entity_globs", "db_max_retries", "db_retry_wait"]
+    },
+    "logger": {
+      "shape": "options_map",
+      "keys": ["default", "logs", "filters"]
+    },
+    "http": {
+      "shape": "options_map",
+      "keys": ["server_host", "server_port", "ssl_certificate", "ssl_key", "cors_allowed_origins", "use_x_forwarded_for", "trusted_proxies", "ip_ban_enabled", "login_attempts_threshold"]
+    },
+    "systemmonitor": {
+      "shape": "options_map",
+      "keys": ["resources"]
+    },
+    "template": {"keys": null},
+    "mqtt": {"keys": null},
+    "shell_command": {"keys": null},
+    "climate": {"keys": null},
+    "media_player": {"keys": null},
+    "vacuum": {"keys": null},
+    "tts": {"keys": null},
+    "notify": {"keys": null},
+    "sun": {"keys": null},
+    "met": {"keys": null},
+    "google_translate": {"keys": null},
+    "radio_browser": {"keys": null},
+    "default_config": {"keys": null},
+    "frontend": {"keys": null},
+    "mobile_app": {"keys": null},
+    "esphome": {"keys": null},
+    "zha": {"keys": null},
+    "shelly": {"keys": null},
+    "hue": {"keys": null},
+    "homekit": {"keys": null},
+    "samsungtv": {"keys": null},
+    "sonos": {"keys": null},
+    "matter": {"keys": null},
+    "bluetooth": {"keys": null},
+    "cast": {"keys": null}
+  }
+}

haconf/catalog/v0.1/meta.json

@@ -0,0 +1,12 @@
+{
+  "name": "haconf default catalog",
+  "version": "v0.1",
+  "ha_min_version": "2026.9",
+  "generated_from": "Home Assistant Analytics 2026-09-25 (688,333 active installations; top-60 by usage) plus the Home Assistant documentation's integration pages; hand-curated for the v0.1 starter set. Sources: docs/FINDINGS.md (row 18) and docs/PLAN.md D2.",
+  "coverage": "59 integrations ship in v0.1; 34 of them carry curated key lists, the rest are name-checked only (keys: null) until curation lands in later catalog versions.",
+  "false_positive_mode": {
+    "unknown_key": "key lists are a curated subset of each integration's documented options; an unknown key is an error per R32, so a false positive means the catalog is missing a key - treat it as a catalog gap and report it.",
+    "unknown_integration": "informational only (N13): an integration we do not know is never an error.",
+    "integration_case": "the canonical lowercase form is named in the finding."
+  }
+}

haconf/catalog/v0.1/rules.json

@@ -0,0 +1,19 @@
+{
+  "rules": {
+    "unknown_key": {
+      "tier": "error",
+      "message": "unknown key {key!r} under {integration!r}",
+      "hint": "check the integration's documented options; if this key is valid, the catalog is missing it"
+    },
+    "unknown_integration": {
+      "tier": "info",
+      "message": "{key!r} is not in catalog {version} - informational only (unknown integrations are never errors)",
+      "hint": "informational only - unknown integrations are never errors"
+    },
+    "integration_case": {
+      "tier": "error",
+      "message": "integration names are lowercase: {name!r} should be {canonical!r}",
+      "hint": "write integration names in lowercase"
+    }
+  }
+}

haconf/catalog.py

@@ -0,0 +1,76 @@
+"""R32/R33/R42 — the versioned, bundled, network-free integration catalog.
+
+Layout (per docs/PLAN.md §2.0.5): ``catalog/<version>/`` holds ``meta.json``,
+``integrations.json`` and ``rules.json``. The catalog ships as package data and
+is read straight from the package directory — there is no fetch path and no
+network import anywhere in this module (R42). ``--catalog`` selects a version;
+an unknown version is a usage error that lists the shipped ones.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import UsageError
+
+_CATALOG_DIR = Path(__file__).with_name("catalog")
+DEFAULT_VERSION = "v0.1"
+
+
+@dataclass(frozen=True)
+class Catalog:
+    version: str
+    meta: dict
+    rules: dict
+    integrations: dict
+
+    def entry(self, name: str) -> dict | None:
+        return self.integrations.get(name)
+
+    def canonical(self, name: str) -> str | None:
+        """The name itself when it is a known integration, else None."""
+        return name if name in self.integrations else None
+
+    def case_fix(self, name: str) -> str | None:
+        """The canonical spelling when the name differs only by case."""
+        low = name.lower()
+        for candidate in self.integrations:
+            if candidate.lower() == low and candidate != name:
+                return candidate
+        return None
+
+    def keys_for(self, name: str) -> frozenset | None:
+        entry = self.integrations.get(name) or {}
+        keys = entry.get("keys")
+        return frozenset(keys) if keys else None
+
+    def shape_for(self, name: str) -> str | None:
+        return (self.integrations.get(name) or {}).get("shape")
+
+    def rule(self, rule_id: str) -> dict:
+        return self.rules.get(rule_id) or {}
+
+
+def available_versions() -> list[str]:
+    if not _CATALOG_DIR.is_dir():
+        return []
+    return sorted(
+        path.name for path in _CATALOG_DIR.iterdir()
+        if path.is_dir() and (path / "integrations.json").is_file()
+    )
+
+
+def load_catalog(version: str | None = None) -> Catalog:
+    chosen = version or DEFAULT_VERSION
+    root = _CATALOG_DIR / chosen
+    if not root.is_dir() or not (root / "integrations.json").is_file():
+        shipped = available_versions()
+        raise UsageError(
+            f"unknown catalog version: {chosen!r}",
+            hint="shipped catalogs: " + (", ".join(shipped) if shipped else "(none)"),
+        )
+    meta = json.loads((root / "meta.json").read_text(encoding="utf-8"))
+    rules = json.loads((root / "rules.json").read_text(encoding="utf-8")).get("rules", {})
+    integrations = json.loads((root / "integrations.json").read_text(encoding="utf-8"))
+    return Catalog(chosen, meta, rules, dict(integrations.get("integrations") or {}))

haconf/cli.py

@@ -0,0 +1,212 @@
+"""Command-line surface for haconf.
+
+Checks built so far (I1–I5): walker, YAML loader, catalog rules, Jinja
+templates, includes/secrets/packages, automation/script structure, entity
+integrity — with severity tiers (error / warning / info), plain-language hints,
+visible suppression (``.haconfignore`` + inline) and ``--json``.
+
+Exit codes: 0 clean (or info/warning only; ``--strict`` escalates warnings to a
+failure), 1 findings with errors, 64 usage (deviation D-HC-1, same rationale as
+RestVerify's D-I1).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import EXIT_CLEAN, EXIT_FINDINGS, EXIT_USAGE, __version__
+from . import entities as entitiesmod
+from . import includes as includesmod
+from . import loader as loadermod
+from . import rules as rulesmod
+from . import structure as structuremod
+from . import suppress as suppressmod
+from . import templates as templatesmod
+from . import walker as walkermod
+from .catalog import available_versions, load_catalog
+from .errors import HacheckError, UsageError
+
+_EPILOG = """\
+examples:
+  haconf ~/.homeassistant/
+  haconf /config --json
+  haconf ~/.homeassistant/ --strict
+  haconf ~/.homeassistant/ --suppress-help
+
+what haconf checks (I1-I8): the directory walk, YAML parsing (duplicate keys,
+multi-document files, quoting pitfalls, tabs/indentation), catalog rules
+(unknown key, integration-name case, unknown integration as info only, and
+every homeassistant: packages: body), Jinja templates including
+custom_templates/*.jinja (the real error text, e.g. "No filter named
+'strftime'"), !include/!secret integrity, automation/script/script-map
+structure at every nesting depth, and entity integrity - with severity tiers,
+suppression and --json.
+
+exit codes: 0 clean (or info/warning only; --strict escalates warnings) ·
+1 findings with errors · 64 usage (extension, deviation D-HC-1)
+
+release work (I5c/I6/I7): packaging, security pass, real-config validation -
+tracked in docs/PLAN.md.
+"""
+
+
+class _Parser(argparse.ArgumentParser):
+    """argparse with usage errors raised as UsageError (mapped to exit 64, D-HC-1)."""
+
+    def error(self, message):
+        raise UsageError(message)
+
+
+def build_parser() -> _Parser:
+    parser = _Parser(
+        prog="haconf",
+        description="Check Home Assistant YAML and Jinja before you reload — "
+                    "no instance needed.",
+        epilog=_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "config_dir",
+        nargs="?",
+        metavar="CONFIG-DIR",
+        help="path to the Home Assistant configuration directory "
+             "(any directory is accepted; the install shape is not detected)",
+    )
+    shipped = ", ".join(available_versions()) or "(none)"
+    parser.add_argument(
+        "--catalog",
+        metavar="VERSION",
+        default=None,
+        help=f"catalog version to use (shipped: {shipped})",
+    )
+    parser.add_argument(
+        "--json",
+        action="store_true",
+        help="machine-readable findings on stdout (one JSON object)",
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat warnings as failures (errors already fail)",
+    )
+    parser.add_argument(
+        "--suppress-help",
+        action="store_true",
+        help="show the two suppression forms and exit",
+    )
+    parser.add_argument("--version", action="version", version=f"haconf {__version__}")
+    return parser
+
+
+def _json_finding(finding) -> dict:
+    return {
+        "path": finding.path,
+        "line": finding.line,
+        "code": finding.code,
+        "severity": finding.severity,
+        "message": finding.message,
+        "hint": finding.resolved_hint,
+    }
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    try:
+        args = parser.parse_args(argv)
+    except UsageError as exc:
+        parser.print_usage(sys.stderr)
+        print(f"{parser.prog}: error: {exc.what}", file=sys.stderr)
+        return EXIT_USAGE
+    if args.suppress_help:
+        print(suppressmod.help_text())
+        return EXIT_CLEAN
+    if not args.config_dir:
+        parser.print_usage(sys.stderr)
+        print(f"{parser.prog}: error: the config directory is required "
+              "(e.g. `haconf ~/.homeassistant/`)", file=sys.stderr)
+        return EXIT_USAGE
+
+    try:
+        catalog = load_catalog(args.catalog)
+    except HacheckError as exc:
+        print(exc.render(), file=sys.stderr)
+        return exc.exit_code
+
+    root = Path(args.config_dir)
+    secrets_present, secrets_keys = includesmod.load_secrets(root)
+    registry_ids = entitiesmod.load_registry(root)
+
+    try:
+        files, findings = walkermod.walk(args.config_dir)
+    except HacheckError as exc:
+        print(exc.render(), file=sys.stderr)
+        return exc.exit_code
+
+    custom_templates = templatesmod.custom_template_files(root)
+    if not files and not custom_templates:
+        print(f"no YAML files found under {args.config_dir}")
+        return EXIT_CLEAN
+
+    declarations: list = []
+    references: list = []
+    for path in files:
+        findings.extend(loadermod.load_file(path, root))
+        findings.extend(rulesmod.check_file(path, root, catalog))
+        findings.extend(templatesmod.check_file(path, root))
+        findings.extend(includesmod.check_file(path, root, secrets_present, secrets_keys))
+        findings.extend(structuremod.check_file(path, root))
+        decls, refs = entitiesmod.collect_file(path, root)
+        declarations.extend(decls)
+        references.extend(refs)
+
+    findings.extend(templatesmod.check_custom_templates(root))
+
+    declared_ids = frozenset(f"{d.domain}.{d.object_id}" for d in declarations)
+    findings.extend(entitiesmod.check_duplicates(declarations))
+    findings.extend(entitiesmod.check_references(references, declared_ids, registry_ids))
+    findings.sort(key=lambda f: (f.path, f.line, f.code))
+
+    findings, suppressed = suppressmod.split(findings, root)
+
+    errors = [f for f in findings if f.severity == "error"]
+    warnings = [f for f in findings if f.severity == "warning"]
+    infos = [f for f in findings if f.severity == "info"]
+    failing = bool(errors) or (args.strict and bool(warnings))
+    exit_code = EXIT_FINDINGS if failing else EXIT_CLEAN
+
+    if args.json:
+        payload = {
+            "tool": "haconf",
+            "version": __version__,
+            "catalog": catalog.version,
+            "status": "findings" if findings else "clean",
+            "exit_code": exit_code,
+            "summary": {
+                "errors": len(errors),
+                "warnings": len(warnings),
+                "infos": len(infos),
+                "suppressed": len(suppressed),
+            },
+            "findings": [_json_finding(f) for f in findings],
+            "suppressed": [
+                {**_json_finding(s.finding), "reason": s.reason, "source": s.source}
+                for s in suppressed
+            ],
+        }
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return exit_code
+
+    for finding in findings:
+        print(finding.render())
+
+    if findings or suppressed:
+        summary = (f"summary: {len(errors)} error(s), {len(warnings)} warning(s), "
+                   f"{len(infos)} info(s)")
+        if suppressed:
+            summary += (f"; {len(suppressed)} suppressed "
+                        "(--suppress-help for the two forms)")
+        print(summary)
+
+    return exit_code