kctl-conform 0.2.0__py3-none-any.whl

kctl_conform/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

kctl_conform/baseline.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .model import Violation
+
+
+def save_baseline(path: Path, violations: list[Violation]) -> None:
+    payload = {
+        "version": 1,
+        "violations": sorted({v.key() for v in violations}),
+    }
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def load_baseline(path: Path) -> set[str]:
+    if not path.is_file():
+        return set()
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return set(data.get("violations", []))
+
+
+def new_violations(current: list[Violation], baseline: set[str]) -> list[Violation]:
+    return [v for v in current if v.key() not in baseline]
+
+
+def stale_baseline_keys(current: list[Violation], baseline: set[str]) -> set[str]:
+    """Baselined keys that are no longer violated (ratchet has slack to tighten)."""
+    current_keys = {v.key() for v in current}
+    return baseline - current_keys

kctl_conform/cli.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import typer
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+import kctl_conform.rules  # noqa: F401  (registers all rules)
+
+from . import __version__
+from .baseline import load_baseline, new_violations, save_baseline, stale_baseline_keys
+from .engine import run_all
+from .registry import all_rules
+from .report import render_json, render_markdown
+from .workspace import WorkspaceInfo
+
+app = typer.Typer(
+    name="kctl-conform",
+    help="Score kctl-* packages and the workspace against the architecture standard.",
+    no_args_is_help=True,
+)
+
+BASELINE_NAME = "conformance-baseline.json"
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-conform {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show version and exit.",
+    ),
+) -> None:
+    """kctl-conform CLI."""
+
+
+@app.command()
+def check(
+    package: str = typer.Option(None, "--package", help="Limit to one package."),
+    json_out: bool = typer.Option(False, "--json", help="Emit JSON."),
+    ci: bool = typer.Option(False, "--ci", help="Exit non-zero on violations absent from baseline."),
+) -> None:
+    """Evaluate the standard across the workspace."""
+    ws = WorkspaceInfo.discover()
+    if package:
+        ws.packages = [p for p in ws.packages if p.name == package]
+    report = run_all(ws)
+    typer.echo(render_json(report) if json_out else render_markdown(report))
+    if ci:
+        baseline = load_baseline(ws.root / BASELINE_NAME)
+        fresh = new_violations(report.all_violations(), baseline)
+        if fresh:
+            typer.echo(f"\n{len(fresh)} new violation(s) not in baseline:", err=True)
+            for v in fresh:
+                typer.echo(f"  {v.rule_id} {v.location} — {v.detail}", err=True)
+            raise typer.Exit(code=1)
+
+
+@app.command()
+def report(
+    fmt: str = typer.Option("markdown", "--format", "-f", help="markdown|json"),
+) -> None:
+    """Render the fleet dashboard / refactor backlog."""
+    ws = WorkspaceInfo.discover()
+    rep = run_all(ws)
+    typer.echo(render_json(rep) if fmt == "json" else render_markdown(rep))
+
+
+@app.command()
+def explain(rule_id: str = typer.Argument(..., help="e.g. SIZE-004")) -> None:
+    """Explain a rule: title, rationale, severity, autofix hint."""
+    idx = {r.id: r for r in all_rules()}
+    rule = idx.get(rule_id.upper())
+    if rule is None:
+        typer.echo(f"unknown rule: {rule_id}", err=True)
+        raise typer.Exit(code=2)
+    typer.echo(f"{rule.id}  [{rule.severity.value}]  ({rule.category}, {rule.scope.value})")
+    typer.echo(f"  {rule.title}")
+    typer.echo(f"  why: {rule.rationale}")
+    typer.echo(f"  checked: {rule.how.value}")
+    if rule.autofix_hint:
+        typer.echo(f"  fix: {rule.autofix_hint}")
+
+
+@app.command()
+def baseline(
+    verify: bool = typer.Option(False, "--verify", help="Report drift instead of writing."),
+) -> None:
+    """Write (or verify) the ratchet baseline of current violations."""
+    ws = WorkspaceInfo.discover()
+    rep = run_all(ws)
+    current = rep.all_violations()
+    path = ws.root / BASELINE_NAME
+    if verify:
+        existing = load_baseline(path)
+        fresh = new_violations(current, existing)
+        stale = stale_baseline_keys(current, existing)
+        if fresh or stale:
+            for v in fresh:
+                typer.echo(f"NEW   {v.rule_id} {v.location}", err=True)
+            for k in sorted(stale):
+                typer.echo(f"STALE {k}", err=True)
+            raise typer.Exit(code=1)
+        typer.echo("baseline is current")
+        return
+    save_baseline(path, current)
+    typer.echo(f"wrote {len(set(v.key() for v in current))} entries to {path}")
+
+
+# Wrap app so KctlError subclasses surface as clean user-facing messages.
+app = cli_entrypoint(app)
+register_introspection_commands(app)

kctl_conform/core/callbacks.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from kctl_lib.callbacks import AppContextBase
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Standard kctl context scaffold (satisfies the AppContextBase convention).
+
+    kctl-conform is a workspace analysis tool with no service client or profile;
+    commands resolve the workspace via WorkspaceInfo.discover() directly, so this
+    context is intentionally minimal.
+    """
+
+    root_override: Path | None = None

kctl_conform/core/config.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+from .exceptions import ConformError
+
+
+def find_workspace_root(start: Path | None = None) -> Path:
+    """Walk upward until a pyproject.toml declaring a uv workspace is found."""
+    cur = (start or Path.cwd()).resolve()
+    for candidate in [cur, *cur.parents]:
+        pp = candidate / "pyproject.toml"
+        if pp.is_file():
+            data = tomllib.loads(pp.read_text(encoding="utf-8"))
+            if "workspace" in data.get("tool", {}).get("uv", {}):
+                return candidate
+    raise ConformError("could not locate uv workspace root (no [tool.uv.workspace] found)")

kctl_conform/core/exceptions.py

@@ -0,0 +1,5 @@
+from kctl_lib.exceptions import KctlError
+
+
+class ConformError(KctlError):
+    """Raised when the conformance checker cannot run (e.g. workspace not found)."""

kctl_conform/engine.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+
+from .model import Rule, Severity, Violation
+from .registry import PACKAGE_RULES, REPO_RULES, all_rules
+from .workspace import WorkspaceInfo
+
+WEIGHT = {Severity.ERROR: 3, Severity.WARN: 1}
+
+
+@dataclass
+class Report:
+    by_package: dict[str, list[Violation]] = field(default_factory=dict)
+    repo: list[Violation] = field(default_factory=list)
+
+    def all_violations(self) -> list[Violation]:
+        out = list(self.repo)
+        for vs in self.by_package.values():
+            out.extend(vs)
+        return out
+
+
+def _dedup(violations: list[Violation]) -> list[Violation]:
+    seen: dict[str, Violation] = {}
+    for v in violations:
+        seen.setdefault(v.key(), v)
+    return list(seen.values())
+
+
+def _is_exempt(rule_id: str, patterns: list[str]) -> bool:
+    return any(fnmatch.fnmatch(rule_id, p) for p in patterns)
+
+
+def run_all(ws: WorkspaceInfo) -> Report:
+    report = Report()
+    for pkg in ws.packages:
+        if pkg.kind == "library":
+            continue
+        collected: list[Violation] = []
+        for _rule, check in PACKAGE_RULES:
+            collected.extend(check(pkg))
+        deduped = _dedup(collected)
+        report.by_package[pkg.name] = [v for v in deduped if not _is_exempt(v.rule_id, pkg.exempt)]
+    repo_ctx = ws.repo_ctx()
+    repo_collected: list[Violation] = []
+    for _rule, repo_check in REPO_RULES:
+        repo_collected.extend(repo_check(repo_ctx))
+    report.repo = _dedup(repo_collected)
+    return report
+
+
+def _rule_index() -> dict[str, Rule]:
+    return {r.id: r for r in all_rules()}
+
+
+def package_score(report: Report, pkg_name: str) -> float:
+    rules = [r for r, _ in PACKAGE_RULES]
+    total = sum(WEIGHT[r.severity] for r in rules)
+    if total == 0:
+        return 100.0
+    failed_ids = {v.rule_id for v in report.by_package.get(pkg_name, [])}
+    idx = _rule_index()
+    lost = sum(WEIGHT[idx[rid].severity] for rid in failed_ids if rid in idx)
+    return round(100.0 * (1 - lost / total), 1)

kctl_conform/introspect.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass, field
+
+import click
+import typer
+
+
+@dataclass
+class CommandInfo:
+    path: str  # "things list"
+    options: set[str] = field(default_factory=set)
+
+
+def _load_command(app: typer.Typer) -> click.Command:
+    return typer.main.get_command(app)
+
+
+def command_tree(app: typer.Typer) -> list[CommandInfo]:
+    """Flatten a Typer app into leaf commands with their option names."""
+    root = _load_command(app)
+    leaves: list[CommandInfo] = []
+
+    def walk(cmd: click.Command, prefix: list[str]) -> None:
+        if isinstance(cmd, click.Group):
+            for name, sub in cmd.commands.items():
+                walk(sub, prefix + [name])
+        else:
+            opts: set[str] = set()
+            for param in cmd.params:
+                if isinstance(param, click.Option):
+                    opts.update(param.opts)
+            leaves.append(CommandInfo(path=" ".join(prefix), options=opts))
+
+    walk(root, [])
+    return [ci for ci in leaves if ci.path]
+
+
+def load_app(module: str) -> typer.Typer | None:
+    """Import `<module>.cli` and return its `app`, or None on failure."""
+    try:
+        mod = importlib.import_module(f"{module}.cli")
+    except Exception:
+        return None
+    app = getattr(mod, "app", None)
+    return app if isinstance(app, typer.Typer) else None
+
+
+def global_options(app: typer.Typer) -> set[str]:
+    """Option names declared on the root group (the CLI's global options)."""
+    root = _load_command(app)
+    opts: set[str] = set()
+    for param in root.params:
+        if isinstance(param, click.Option):
+            opts.update(param.opts)
+    return opts
+
+
+def group_names(app: typer.Typer) -> set[str]:
+    """Top-level command/group names (e.g. {'commands', 'doctor', 'skill'})."""
+    root = _load_command(app)
+    if isinstance(root, click.Group):
+        return set(root.commands.keys())
+    return set()

kctl_conform/model.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Severity(StrEnum):
+    ERROR = "error"
+    WARN = "warn"
+
+
+class Scope(StrEnum):
+    PACKAGE = "package"
+    REPO = "repo"
+
+
+class How(StrEnum):
+    STATIC = "static"
+    INTROSPECT = "introspect"
+    RUNTIME = "runtime"
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    category: str
+    severity: Severity
+    scope: Scope
+    title: str
+    rationale: str
+    how: How
+    autofix_hint: str | None = None
+
+
+@dataclass
+class Violation:
+    rule_id: str
+    location: str
+    detail: str
+
+    def key(self) -> str:
+        return f"{self.rule_id}::{self.location}"

kctl_conform/registry.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from .model import Rule, Violation
+
+if TYPE_CHECKING:
+    from .workspace import PackageCtx, RepoCtx
+
+PackageCheck = Callable[["PackageCtx"], list[Violation]]
+RepoCheck = Callable[["RepoCtx"], list[Violation]]
+
+PACKAGE_RULES: list[tuple[Rule, PackageCheck]] = []
+REPO_RULES: list[tuple[Rule, RepoCheck]] = []
+
+
+def package_rule(rule: Rule) -> Callable[[PackageCheck], PackageCheck]:
+    def deco(fn: PackageCheck) -> PackageCheck:
+        PACKAGE_RULES.append((rule, fn))
+        return fn
+
+    return deco
+
+
+def repo_rule(rule: Rule) -> Callable[[RepoCheck], RepoCheck]:
+    def deco(fn: RepoCheck) -> RepoCheck:
+        REPO_RULES.append((rule, fn))
+        return fn
+
+    return deco
+
+
+def all_rules() -> list[Rule]:
+    return [r for r, _ in PACKAGE_RULES] + [r for r, _ in REPO_RULES]

kctl_conform/report.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+
+from .engine import Report, package_score
+from .model import Violation
+from .registry import all_rules
+
+
+def _severity_map() -> dict[str, str]:
+    return {r.id: r.severity.value for r in all_rules()}
+
+
+def _count(violations: list[Violation], severity: str, sev_map: dict[str, str]) -> int:
+    return sum(1 for v in violations if sev_map.get(v.rule_id) == severity)
+
+
+def render_json(report: Report) -> str:
+    payload = {
+        "packages": {
+            name: [{"rule_id": v.rule_id, "location": v.location, "detail": v.detail} for v in vs]
+            for name, vs in report.by_package.items()
+        },
+        "repo": [{"rule_id": v.rule_id, "location": v.location, "detail": v.detail} for v in report.repo],
+        "scores": {name: package_score(report, name) for name in report.by_package},
+    }
+    return json.dumps(payload, indent=2)
+
+
+def render_markdown(report: Report) -> str:
+    sev = _severity_map()
+    ranked = sorted(report.by_package.items(), key=lambda kv: len(kv[1]), reverse=True)
+    lines = [
+        "# kctl-conform report",
+        "",
+        "## Packages (ranked by violations)",
+        "",
+        "| Package | Score | Errors | Warns |",
+        "|---------|-------|--------|-------|",
+    ]
+    for name, vs in ranked:
+        lines.append(
+            f"| {name} | {package_score(report, name)} | {_count(vs, 'error', sev)} | {_count(vs, 'warn', sev)} |"
+        )
+    lines += ["", "## Violations", ""]
+    for name, vs in ranked:
+        if not vs:
+            continue
+        lines.append(f"### {name}")
+        lines += [f"- `{v.rule_id}` {v.location} — {v.detail}" for v in sorted(vs, key=lambda v: v.rule_id)]
+        lines.append("")
+    if report.repo:
+        lines.append("### repo")
+        lines += [f"- `{v.rule_id}` {v.location} — {v.detail}" for v in sorted(report.repo, key=lambda v: v.rule_id)]
+        lines.append("")
+    return "\n".join(lines)

kctl_conform/rules/__init__.py

@@ -0,0 +1,3 @@
+from . import afford, docs, layout, naming, repo, size, testing, wire  # noqa: F401
+
+__all__ = ["afford", "docs", "layout", "naming", "repo", "size", "testing", "wire"]

kctl_conform/rules/afford.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from ..introspect import command_tree, global_options, group_names, load_app
+from ..model import How, Rule, Scope, Severity, Violation
+from ..registry import package_rule
+from ..workspace import PackageCtx
+
+
+@package_rule(
+    Rule(
+        "AFFORD-001",
+        "AFFORD",
+        Severity.ERROR,
+        Scope.PACKAGE,
+        "--json and --profile resolve",
+        "Uniform global options for agents.",
+        How.INTROSPECT,
+    )
+)
+def check_global_options(ctx: PackageCtx) -> list[Violation]:
+    app = load_app(ctx.module)
+    if app is None:
+        return [Violation("AFFORD-001", ctx.module, "could not import app for introspection")]
+    opts = global_options(app)
+    out: list[Violation] = []
+    if "--json" not in opts:
+        out.append(Violation("AFFORD-001", ctx.module, "no --json global option"))
+    if "--profile" not in opts and "-p" not in opts:
+        out.append(Violation("AFFORD-001", ctx.module, "no --profile/-p global option"))
+    return out
+
+
+@package_rule(
+    Rule(
+        "AFFORD-002",
+        "AFFORD",
+        Severity.ERROR,
+        Scope.PACKAGE,
+        "commands tree/list registered",
+        "One-call machine-readable discovery.",
+        How.INTROSPECT,
+    )
+)
+def check_introspection_commands(ctx: PackageCtx) -> list[Violation]:
+    app = load_app(ctx.module)
+    if app is None:
+        return [Violation("AFFORD-002", ctx.module, "could not import app")]
+    if "commands" not in group_names(app):
+        return [Violation("AFFORD-002", ctx.module, "no 'commands' group (introspection)")]
+    return []
+
+
+@package_rule(
+    Rule(
+        "AFFORD-004",
+        "AFFORD",
+        Severity.WARN,
+        Scope.PACKAGE,
+        "doctor ai-summary registered",
+        "One-call diagnostic summary for agents.",
+        How.INTROSPECT,
+    )
+)
+def check_doctor_ai_summary(ctx: PackageCtx) -> list[Violation]:
+    app = load_app(ctx.module)
+    if app is None:
+        return []
+    paths = {ci.path for ci in command_tree(app)}
+    if not any(p == "doctor ai-summary" for p in paths):
+        return [Violation("AFFORD-004", ctx.module, "no 'doctor ai-summary' command")]
+    return []
+
+
+@package_rule(
+    Rule(
+        "AFFORD-006",
+        "AFFORD",
+        Severity.WARN,
+        Scope.PACKAGE,
+        "skill generate registered",
+        "Auto-generate SKILL.md from introspection.",
+        How.INTROSPECT,
+    )
+)
+def check_skill_generate(ctx: PackageCtx) -> list[Violation]:
+    app = load_app(ctx.module)
+    if app is None:
+        return []
+    paths = {ci.path for ci in command_tree(app)}
+    if not any(p == "skill generate" for p in paths):
+        return [Violation("AFFORD-006", ctx.module, "no 'skill generate' command")]
+    return []

kctl_conform/rules/docs.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+
+from ..model import How, Rule, Scope, Severity, Violation
+from ..registry import package_rule
+from ..workspace import PackageCtx
+
+_README_MIN = 60
+_DESC_MAX = 200
+
+
+@package_rule(
+    Rule(
+        "DOC-001",
+        "DOC",
+        Severity.WARN,
+        Scope.PACKAGE,
+        "README >= 60 lines",
+        "Docs scale with the CLI surface.",
+        How.STATIC,
+    )
+)
+def check_readme_length(ctx: PackageCtx) -> list[Violation]:
+    n = PackageCtx.line_count(ctx.readme())
+    if n >= _README_MIN:
+        return []
+    return [Violation("DOC-001", str(ctx.readme()), f"{n} lines (min {_README_MIN})")]
+
+
+@package_rule(
+    Rule(
+        "DOC-002",
+        "DOC",
+        Severity.WARN,
+        Scope.PACKAGE,
+        "SKILL.md description <= 200 chars",
+        "Slim picker payloads; keywords go in the body.",
+        How.STATIC,
+    )
+)
+def check_skill_description(ctx: PackageCtx) -> list[Violation]:
+    skills = ctx.path / "skills"
+    if not skills.is_dir():
+        return []
+    out: list[Violation] = []
+    for skill in skills.rglob("SKILL.md"):
+        text = skill.read_text(encoding="utf-8", errors="replace")
+        m = re.search(r"(?m)^description:\s*(.+)$", text)
+        if m and len(m.group(1).strip()) > _DESC_MAX:
+            out.append(
+                Violation(
+                    "DOC-002",
+                    str(skill),
+                    f"description {len(m.group(1).strip())} chars (max {_DESC_MAX})",
+                )
+            )
+    return out