roadmap-core 0.2.0__tar.gz → 0.2.2__tar.gz

{roadmap_core-0.2.0/roadmap_core.egg-info → roadmap_core-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.0
+Version: 0.2.2
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core
@@ -104,6 +104,31 @@ roadmap release first-thing
 The store is one SQLite file at `roadmap/roadmap.db`. There is nothing to
 provision and no migration to run: it is created on first open.
 
+### When something is off, ask
+
+```bash
+roadmap doctor          # is this project's setup actually working?
+roadmap --version       # which roadmap-core is this?
+```
+
+`doctor` exits non-zero when something is genuinely broken and names the remedy.
+Run it first, because **the way this setup fails is by looking fine**: the read
+commands answer from the store, and a store nobody has `push`ed to is empty, so
+`validate` says *"ok — 0 item(s), no problems"* and `ready` says the backlog is
+finished. Both are green, confident and wrong. Same for a command run from
+outside the project: every path still resolves, and `push` reports *"no item
+files to push"*, which reads as an empty backlog rather than as a wrong
+directory.
+
+Those are the two failures `tests/test_adoption.py` was written after, and both
+are one line of `doctor` output:
+
+```
+FAIL  store       roadmap/roadmap.db holds 0 items while roadmap/items/ holds 7.
+                  Every read command will report an empty backlog and call it ok.
+                  Seed it: `roadmap push`
+```
+
 **Two things that are conventions rather than choices**, both found by doing
 this rather than by reading the code:
 

{roadmap_core-0.2.0 → roadmap_core-0.2.2}/README.md

@@ -83,6 +83,31 @@ roadmap release first-thing
 The store is one SQLite file at `roadmap/roadmap.db`. There is nothing to
 provision and no migration to run: it is created on first open.
 
+### When something is off, ask
+
+```bash
+roadmap doctor          # is this project's setup actually working?
+roadmap --version       # which roadmap-core is this?
+```
+
+`doctor` exits non-zero when something is genuinely broken and names the remedy.
+Run it first, because **the way this setup fails is by looking fine**: the read
+commands answer from the store, and a store nobody has `push`ed to is empty, so
+`validate` says *"ok — 0 item(s), no problems"* and `ready` says the backlog is
+finished. Both are green, confident and wrong. Same for a command run from
+outside the project: every path still resolves, and `push` reports *"no item
+files to push"*, which reads as an empty backlog rather than as a wrong
+directory.
+
+Those are the two failures `tests/test_adoption.py` was written after, and both
+are one line of `doctor` output:
+
+```
+FAIL  store       roadmap/roadmap.db holds 0 items while roadmap/items/ holds 7.
+                  Every read command will report an empty backlog and call it ok.
+                  Seed it: `roadmap push`
+```
+
 **Two things that are conventions rather than choices**, both found by doing
 this rather than by reading the code:
 

{roadmap_core-0.2.0 → roadmap_core-0.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "roadmap-core"
-version = "0.2.0"
+version = "0.2.2"
 description = "The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend."
 requires-python = ">=3.11"
 readme = "README.md"

{roadmap_core-0.2.0 → roadmap_core-0.2.2}/roadmap_core/cli.py

@@ -34,6 +34,7 @@ Commands
     status   move an item's status deliberately (the store owns that field)
     release  give it back
     validate schema, dangling deps, cycles
+    doctor   check that this project's setup actually works
 
 State fields — ``status`` and the claim — are the store's, and a file's value
 for them is honored when the item is first filed and ignored afterwards. A
@@ -781,7 +782,7 @@ def cmd_sync(args: argparse.Namespace) -> int:
         if current_arcs != rendered_arcs:
             print(
                 f"{GENERATED_ARCS_MD.relative_to(REPO_ROOT)} is stale — "
-                "run `python scripts/roadmap.py sync`",
+                f"run `{graph.CLI} sync`",
                 file=sys.stderr,
             )
             return 1
@@ -792,7 +793,7 @@ def cmd_sync(args: argparse.Namespace) -> int:
         if current != rendered:
             print(
                 f"{GENERATED_MD.relative_to(REPO_ROOT)} is stale — "
-                "run `python scripts/roadmap.py sync`",
+                f"run `{graph.CLI} sync`",
                 file=sys.stderr,
             )
             return 1
@@ -1244,7 +1245,7 @@ def cmd_pull(args: argparse.Namespace) -> int:
         return 0
     print(
         f"{len(created)} created, {len(updated)} updated — "
-        f"now run `python scripts/roadmap.py sync` and commit"
+        f"now run `{graph.CLI} sync` and commit"
     )
     return 0
 
@@ -1508,7 +1509,7 @@ def cmd_prune(args: argparse.Namespace) -> int:
         else:
             print(f"pruned {key} — store: {outcome}, no file")
     _release_dependents(done)
-    print(f"{len(done)} item(s) pruned — now run `python scripts/roadmap.py sync` and commit")
+    print(f"{len(done)} item(s) pruned — now run `{graph.CLI} sync` and commit")
     return 0
 
 
@@ -1913,6 +1914,236 @@ def cmd_validate(args: argparse.Namespace) -> int:
     return 1
 
 
+def installed_version() -> str:
+    """The version of the distribution this module was imported from.
+
+    A source checkout that was never installed has no distribution metadata,
+    which is a legitimate way to run the CLI and must not raise. It is still
+    worth distinguishing in the output: "which version is this" and "there is no
+    package here, you are running a directory" are different answers to the same
+    question, and only one of them can be compared against a pin.
+    """
+    try:
+        from importlib.metadata import PackageNotFoundError, version
+    except ImportError:  # pragma: no cover - stdlib since 3.8
+        return "unknown"
+    try:
+        return version("roadmap-core")
+    except PackageNotFoundError:
+        return "not installed (running from a source tree)"
+
+
+class _Check:
+    """One question `doctor` asks, and what the answer means.
+
+    `fatal=False` for things worth printing but not worth failing on. A doctor
+    that fails on everything imperfect gets run once and then ignored, which
+    leaves an adopter exactly where they started.
+    """
+
+    __slots__ = ("name", "ok", "detail", "fatal")
+
+    def __init__(self, name: str, ok: bool, detail: str, fatal: bool = True) -> None:
+        self.name, self.ok, self.detail, self.fatal = name, ok, detail, fatal
+
+
+def _check_yaml() -> _Check:
+    try:
+        import yaml  # noqa: F401
+    except ImportError:
+        return _Check(
+            "pyyaml",
+            False,
+            "not installed — `push`, `pull` and `--source files` all fail on this "
+            "one import. Install the extra: pip install 'roadmap-core[files]'",
+        )
+    return _Check("pyyaml", True, "importable")
+
+
+def _check_repo_root() -> _Check:
+    """Where the CLI thinks the project is, and how it decided.
+
+    The failure this exists for is silent: pointed one directory too high, every
+    path still resolves, `push` reports "no item files to push", and that reads
+    as an empty backlog rather than as a misconfiguration.
+    """
+    pinned = os.environ.get("ROADMAP_REPO_ROOT")
+    if pinned:
+        how = "pinned by ROADMAP_REPO_ROOT"
+    elif (REPO_ROOT / "roadmap" / "items").exists():
+        how = "found by walking up from the working directory"
+    else:
+        return _Check(
+            "repo root",
+            False,
+            f"{REPO_ROOT} — no roadmap/items/ above the working directory, so this "
+            "is the working directory itself, chosen as a fallback. Run from "
+            "inside the project, or set ROADMAP_REPO_ROOT.",
+        )
+    return _Check("repo root", True, f"{REPO_ROOT} ({how})")
+
+
+def _check_items() -> tuple[_Check, int]:
+    if not ITEMS_DIR.is_dir():
+        return (
+            _Check(
+                "items",
+                False,
+                f"{ITEMS_DIR} does not exist. That directory IS the authoring "
+                "format — there is no `roadmap new`, so a project without it has "
+                "nowhere to file work.",
+            ),
+            0,
+        )
+    count = len(list(ITEMS_DIR.glob("*.yaml")))
+    return _Check("items", True, f"{count} file(s) in {ITEMS_DIR}", fatal=False), count
+
+
+def _check_store(source: str, on_disk: int, chosen: bool) -> list[_Check]:
+    """Whether the store the write commands use agrees that work exists.
+
+    THE CHECK THIS COMMAND WAS WRITTEN FOR. `local` reads a SQLite file that is
+    empty until `push` seeds it, and an empty store answers `validate` with
+    "ok — 0 item(s), no problems" and `ready` with "nothing ready". Both are
+    green, confident, and wrong, and the remedy is one command that nothing
+    suggests because nothing has noticed.
+    """
+    if source == "local":
+        checks = [_Check("source", True, "local — a SQLite file, no server needed",
+                         fatal=False)]
+        path = Path(ROADMAP_STORE_PATH)
+        try:
+            with store_for("local") as store:
+                in_store = len(store.items())
+        except Exception as exc:  # noqa: BLE001 - report it, do not raise from a doctor
+            checks.append(_Check("store", False, f"{path} could not be opened: {exc}"))
+            return checks
+        if in_store == 0 and on_disk > 0:
+            checks.append(_Check(
+                "store",
+                False,
+                f"{path} holds 0 items while roadmap/items/ holds {on_disk}. "
+                "Every read command will report an empty backlog and call it ok. "
+                "Seed it: `roadmap push`",
+            ))
+        else:
+            checks.append(_Check("store", True, f"{path} — {in_store} item(s)"))
+        return checks
+
+    # `db` is the built-in default for writes, so a project that has configured
+    # nothing lands here without asking to. Saying FAIL twice at that project
+    # would be describing a served store it never wanted; saying nothing would
+    # hide that an unqualified `claim` is aimed somewhere unreachable. So it is
+    # one warning that names the fork, and it becomes a real failure the moment
+    # somebody actually chooses `db`.
+    if not chosen and not DEFAULT_BACKEND:
+        return [_Check(
+            "source",
+            False,
+            "nothing configured, so writes default to the `db` source and would "
+            "need a backend and a token. For the SQLite floor set "
+            "ROADMAP_SOURCE=local (see templates/roadmap.yml); for a served "
+            "store set LUCILLE_BACKEND_URL and LUCILLE_ADMIN_JWT.",
+            fatal=False,
+        )]
+
+    detail = "db — a served store over the admin API"
+    checks = [_Check("source", True, detail, fatal=False)]
+    if not DEFAULT_BACKEND:
+        checks.append(_Check(
+            "backend url",
+            False,
+            "the db source is selected but no backend URL is set. The published "
+            "package ships no default on purpose — a private hostname is not a "
+            "sensible fallback. Set LUCILLE_BACKEND_URL, or use ROADMAP_SOURCE=local.",
+        ))
+    else:
+        checks.append(_Check("backend url", True, DEFAULT_BACKEND, fatal=False))
+    if not os.environ.get("LUCILLE_ADMIN_JWT", "").strip():
+        checks.append(_Check(
+            "credential",
+            False,
+            "no admin token in the environment, so every db-source command will "
+            "exit before it reaches the network.",
+        ))
+    else:
+        checks.append(_Check("credential", True, "present", fatal=False))
+    return checks
+
+
+def _check_generated() -> list[_Check]:
+    """The committed projections. Absent is a real gap — they are what a reader
+    with no install sees — but never fatal: a project mid-adoption has not run
+    `sync` yet, and failing here would make the first doctor run red for a
+    project doing nothing wrong."""
+    out = []
+    for label, path in (("ROADMAP.md", GENERATED_MD), ("ARCS.md", GENERATED_ARCS_MD)):
+        if path.exists():
+            out.append(_Check(label, True, str(path), fatal=False))
+        else:
+            out.append(_Check(
+                label, False, f"{path} not generated yet — run `roadmap sync`",
+                fatal=False,
+            ))
+    return out
+
+
+def cmd_doctor(args: argparse.Namespace) -> int:
+    """Answer "is this project's roadmap setup working?" in one command.
+
+    Every check here exists because its absence was paid for. The CLI that could
+    not find its graph, the shim at the wrong depth reporting an empty backlog,
+    two installs a major version apart with nothing able to report its own
+    version, a `local` store nobody had seeded — each was found by someone
+    reading a green, confident, wrong answer and believing it.
+
+    Exit code is the product: non-zero when something is actually broken, so a
+    setup step in CI or a bootstrap script can gate on it rather than on a human
+    reading output.
+    """
+    # "Chosen" means somebody said so — on the command line or in the
+    # environment — as opposed to inheriting the built-in write default. The
+    # distinction changes what an unconfigured db source means, and nothing
+    # downstream can recover it.
+    chosen = bool(_ENV_SOURCE) or "--source" in (sys.argv[1:] or [])
+    source = _write_source(args)
+
+    checks: list[_Check] = [
+        _Check("version", True, f"roadmap-core {installed_version()}", fatal=False),
+        _Check("package", True, str(Path(__file__).resolve().parent), fatal=False),
+        _check_yaml(),
+        _check_repo_root(),
+    ]
+    items_check, on_disk = _check_items()
+    checks.append(items_check)
+    checks.append(_Check(
+        "arcs",
+        True,
+        f"{len(list(ARCS_DIR.glob('*.yaml')))} file(s) in {ARCS_DIR}"
+        if ARCS_DIR.is_dir() else f"{ARCS_DIR} does not exist (optional)",
+        fatal=False,
+    ))
+    checks += _check_store(source, on_disk, chosen)
+    checks += _check_generated()
+
+    width = max(len(c.name) for c in checks)
+    broken = [c for c in checks if not c.ok and c.fatal]
+    for check in checks:
+        mark = "ok  " if check.ok else ("FAIL" if check.fatal else "warn")
+        stream = sys.stderr if not check.ok and check.fatal else sys.stdout
+        print(f"{mark}  {check.name.ljust(width)}  {check.detail}", file=stream)
+
+    if broken:
+        print(
+            f"\n{len(broken)} problem(s) — the commands above will not behave as "
+            "documented until each is resolved.",
+            file=sys.stderr,
+        )
+        return 1
+    print("\nsetup looks complete.")
+    return 0
+
+
 def _add_source(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--source", choices=("db", "files", "local"), default=_ENV_SOURCE or "files",
@@ -1967,6 +2198,12 @@ def _add_compared_source(parser: argparse.ArgumentParser) -> None:
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(description=__doc__,
                                      formatter_class=argparse.RawDescriptionHelpFormatter)
+    # Before the subparsers, and deliberately answerable without one: "which
+    # version is this" is asked when two installs are suspected of disagreeing,
+    # and at that moment every subcommand is under suspicion too.
+    parser.add_argument(
+        "--version", action="version", version=f"roadmap-core {installed_version()}"
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     p_sync = sub.add_parser("sync", help="regenerate roadmap/ROADMAP.md")
@@ -2053,6 +2290,12 @@ def main(argv: list[str] | None = None) -> int:
     _add_source(p_validate)
     p_validate.set_defaults(func=cmd_validate)
 
+    p_doctor = sub.add_parser(
+        "doctor", help="check that this project's roadmap setup actually works"
+    )
+    _add_write_source(p_doctor)
+    p_doctor.set_defaults(func=cmd_doctor)
+
     args = parser.parse_args(argv)
     return args.func(args)
 

{roadmap_core-0.2.0 → roadmap_core-0.2.2/roadmap_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: roadmap-core
-Version: 0.2.0
+Version: 0.2.2
 Summary: The roadmap work-item and arc graph: status derivation, validation, and markdown rendering. Stdlib-only, so any repo can adopt it without adopting a backend.
 License: MIT
 Project-URL: Source, https://github.com/gald33/roadmap-core
@@ -104,6 +104,31 @@ roadmap release first-thing
 The store is one SQLite file at `roadmap/roadmap.db`. There is nothing to
 provision and no migration to run: it is created on first open.
 
+### When something is off, ask
+
+```bash
+roadmap doctor          # is this project's setup actually working?
+roadmap --version       # which roadmap-core is this?
+```
+
+`doctor` exits non-zero when something is genuinely broken and names the remedy.
+Run it first, because **the way this setup fails is by looking fine**: the read
+commands answer from the store, and a store nobody has `push`ed to is empty, so
+`validate` says *"ok — 0 item(s), no problems"* and `ready` says the backlog is
+finished. Both are green, confident and wrong. Same for a command run from
+outside the project: every path still resolves, and `push` reports *"no item
+files to push"*, which reads as an empty backlog rather than as a wrong
+directory.
+
+Those are the two failures `tests/test_adoption.py` was written after, and both
+are one line of `doctor` output:
+
+```
+FAIL  store       roadmap/roadmap.db holds 0 items while roadmap/items/ holds 7.
+                  Every read command will report an empty backlog and call it ok.
+                  Seed it: `roadmap push`
+```
+
 **Two things that are conventions rather than choices**, both found by doing
 this rather than by reading the code:
 

{roadmap_core-0.2.0 → roadmap_core-0.2.2}/tests/test_adoption.py

@@ -311,3 +311,65 @@ def test_diff_reconciles_against_the_local_store_without_a_credential(project):
         f"diff reported agreement:\n{drifted.stdout}\n{drifted.stderr}"
     )
     assert "first-thing" in drifted.stdout + drifted.stderr
+
+
+# --- doctor -------------------------------------------------------------------
+#
+# The command that certifies an adoption has to be certified by the adoption
+# test, or it is one more thing whose correctness is assumed. These use the same
+# scratch project as everything above: nothing installed, no server, no token.
+
+
+def test_doctor_passes_on_a_project_that_is_set_up(project):
+    """The healthy case, and the only one where a zero exit is meaningful — it is
+    meaningful only because the broken cases below are red."""
+    run(project, "push")
+    result = run(project, "doctor")
+
+    assert result.returncode == 0, f"{result.stdout}\n{result.stderr}"
+    assert "setup looks complete" in result.stdout
+    assert "roadmap-core" in result.stdout, "doctor must report the version it is"
+
+
+def test_doctor_catches_the_store_nobody_seeded(project):
+    """THE failure this command exists for, and the reason a version of it that
+    only reports success would be worse than nothing.
+
+    A `local` store is empty until `push` seeds it, and every read command
+    answers from the store. So `validate` on this exact project says *"ok — 0
+    item(s), no problems"* and `ready` says the backlog is finished: green,
+    confident, and wrong, with a one-command remedy nothing suggests.
+    """
+    # The premise: the other commands really are cheerful about it.
+    assert run(project, "validate").returncode == 0
+    assert "0 item(s)" in run(project, "validate").stdout
+
+    result = run(project, "doctor")
+
+    assert result.returncode == 1, f"doctor passed a broken setup:\n{result.stdout}"
+    assert "0 items while roadmap/items/ holds 1" in result.stderr
+    assert "roadmap push" in result.stderr, "a diagnosis without a remedy is half of one"
+
+
+def test_doctor_catches_being_pointed_at_the_wrong_directory(tmp_path):
+    """The second failure `test_adoption.py`'s own docstring records: run from
+    somewhere with no project above it and every path still resolves, `push`
+    reports "no item files to push", and that reads as an empty backlog rather
+    than as a misconfiguration."""
+    elsewhere = tmp_path / "not-a-project"
+    elsewhere.mkdir()
+
+    result = run(elsewhere, "doctor")
+
+    assert result.returncode == 1
+    assert "repo root" in result.stderr
+    assert "roadmap/items" in result.stderr
+
+
+def test_the_version_is_answerable_without_a_subcommand(project):
+    """Asked when two installs are suspected of disagreeing — a moment when
+    every subcommand is under suspicion too, so it must not need one."""
+    result = run(project, "--version")
+
+    assert result.returncode == 0
+    assert "roadmap-core" in result.stdout

{roadmap_core-0.2.0 → roadmap_core-0.2.2}/tests/test_graph.py

@@ -180,3 +180,55 @@ def test_generated_markdown_names_the_console_script_this_package_installs():
     arcs, by_key = _one_of_everything()
     for text in (graph.render_markdown(by_key), graph.render_arcs_markdown(arcs, by_key)):
         assert f"`{graph.CLI} sync`" in text
+
+
+# --- and the CLI's own messages, which the test above does not reach ---------
+#
+# `graph.CLI` fixed the headers *inside* the generated files. It did not fix the
+# messages the CLI prints when it wants you to regenerate them — and those are
+# strictly more likely to be read, because `sync --check` prints one every time
+# the drift guard fires. An adopter upgrading to the release that removed
+# `scripts/roadmap.py` from the generated files was told, by that same release,
+# to run `python scripts/roadmap.py sync`.
+#
+# Parsed rather than imported: `roadmap_core.cli` is not importable in the
+# isolation job, and the docstrings in that module discuss the extraction repo
+# legitimately. Only strings on their way to a user are checked.
+
+def _printed_strings(path):
+    """Every string constant that reaches a `print(...)` call, f-strings included."""
+    import ast
+
+    tree = ast.parse(path.read_text())
+    out = []
+
+    def literals(node):
+        if isinstance(node, ast.Constant) and isinstance(node.value, str):
+            out.append(node.value)
+        elif isinstance(node, ast.JoinedStr):
+            for part in node.values:
+                if isinstance(part, ast.Constant) and isinstance(part.value, str):
+                    out.append(part.value)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Call) and getattr(node.func, "id", None) == "print":
+            for arg in node.args:
+                literals(arg)
+                for sub in ast.walk(arg):
+                    literals(sub)
+    return out
+
+
+def test_cli_messages_name_no_path_from_the_extraction_repo():
+    import importlib.util
+    from pathlib import Path
+
+    cli_path = Path(importlib.util.find_spec("roadmap_core.cli").origin)
+    printed = _printed_strings(cli_path)
+    assert printed, "parsed no printed strings — the AST walk stopped working"
+    for text in printed:
+        for bad in _EXTRACTION_REPO_PATHS:
+            assert bad not in text, (
+                f"cli.py prints {text!r}, naming {bad!r} — a path that exists only in "
+                f"the repository this package was extracted from. Use `graph.CLI`."
+            )