kctl-conform 0.2.0__tar.gz

kctl_conform-0.2.0/.gitignore

@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Agent memory (claude-mem regenerates AGENTS.md locally; not a committed guide)
+AGENTS.md

kctl_conform-0.2.0/PKG-INFO

@@ -0,0 +1,8 @@
+Metadata-Version: 2.4
+Name: kctl-conform
+Version: 0.2.0
+Summary: Conformance checker for the kctl-* CLI architecture standard
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.4.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9.0

kctl_conform-0.2.0/README.md

@@ -0,0 +1,73 @@
+# kctl-conform
+
+Conformance checker for the **kctl CLI architecture standard**. It scores every
+`packages/kctl-*` package and the workspace against a written set of rules, and
+gates CI with a baseline/ratchet so existing debt is grandfathered while new
+violations are blocked.
+
+See the standard: `docs/standards/kctl-cli-architecture.md`.
+
+## Install / run
+
+```bash
+uv sync --all-extras --all-packages
+uv run kctl-conform check
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kctl-conform check [--package <name>] [--json] [--ci]` | Evaluate rules across the workspace. `--ci` exits non-zero on violations not in the baseline. |
+| `kctl-conform report [--format markdown\|json]` | Fleet dashboard / refactor backlog. |
+| `kctl-conform explain <RULE-ID>` | Explain a rule: title, rationale, severity, fix hint. |
+| `kctl-conform baseline [--verify]` | Write (or verify) the ratchet baseline of current violations. |
+
+## Rule categories
+
+| Category | Concern |
+|----------|---------|
+| `LAYOUT` | Required files/dirs per package (cli.py, core/, commands/, tests/, SKILL.md). |
+| `SIZE`   | File-size caps for cli.py and command modules; registration extraction. |
+| `WIRE`   | Required kctl-lib wiring (cli_entrypoint, introspection, AppContext). |
+| `AFFORD` | AI affordances (--json/--profile, commands tree/list, doctor ai-summary, skill generate). |
+| `TEST`   | conftest.py, test_standard.py with the 4 standard classes, test-to-command ratio. |
+| `DOC`    | README length, SKILL.md description length. |
+| `REPO`   | Workspace hygiene (no tracked build artifacts, orphan tests, co-located skills, justfile). |
+
+## Severities
+
+- `error` — a clear breakage; weighted 3x in scoring.
+- `warn` — drift worth fixing; weighted 1x.
+
+## Package classification
+
+A package may opt out of CLI rules via its own `pyproject.toml`:
+
+```toml
+[tool.kctl-conform]
+kind = "library"        # skipped entirely (e.g. kctl-lib)
+# or
+kind = "meta"
+exempt = ["AFFORD-*"]   # rule-id globs dropped for this package
+```
+
+- `kind = "library"` — not a CLI; excluded from all package rules.
+- `exempt = [...]` — rule-id glob patterns whose violations are dropped for
+  this package (used by meta/dev tools where a rule is genuinely N/A).
+
+## Baseline / ratchet
+
+```bash
+uv run kctl-conform baseline      # snapshot current violations
+uv run kctl-conform check --ci    # fail only on NEW violations
+```
+
+The committed `conformance-baseline.json` records accepted existing debt;
+re-run `baseline` after fixing violations to ratchet it down.
+
+## Tests
+
+```bash
+uv run pytest packages/kctl-conform/tests/ -v
+```

kctl_conform-0.2.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-conform"
+version = "0.2.0"
+description = "Conformance checker for the kctl-* CLI architecture standard"
+requires-python = ">=3.12"
+dependencies = ["kctl-lib>=0.4.0", "typer>=0.9.0", "rich>=13.0"]
+
+[project.scripts]
+kctl-conform = "kctl_conform.cli:app"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_conform"]
+
+[tool.kctl-conform]
+kind = "meta"
+# Rules genuinely N/A for a profile-less local analysis tool (not a service CLI):
+#   AFFORD-001 = no global --json/--profile options
+#   AFFORD-004 = no `doctor ai-summary` (no external service to probe)
+#   AFFORD-006 = no `skill generate` (no agent-facing SKILL.md)
+#   LAYOUT-006 = no core/client.py (reads the local filesystem, no API client)
+#   LAYOUT-003 = commands live in cli.py; no commands/ package
+#   LAYOUT-005 = no skills/<x>-admin/SKILL.md (developer tool, not an agent endpoint)
+#   TEST-002  = test_standard.py has Version/Help only; no config/completions groups to test
+exempt = ["AFFORD-001", "AFFORD-004", "AFFORD-006", "LAYOUT-003", "LAYOUT-005", "LAYOUT-006", "TEST-002"]

kctl_conform-0.2.0/src/kctl_conform/__init__.py

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

kctl_conform-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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"]