WillTools 2026-09-09 -- clean snapshot of the development repo for review

History-free snapshot of the private development repository at cbe45c5
(2026-09-09). Code, docs and public catalogue only; no plant or job
knowledge layers, no client or job names (tools/scrub.py clean). The
intro deck is left out of this snapshot because its slide images could
not be checked for job drawings.

WillTools.extension/tests/test_joblocate.py

@@ -0,0 +1,154 @@
+# -*- coding: utf-8 -*-
+"""Tests for `vibe.joblocate` -- picking a job's knowledge.yaml with no doc.
+
+Loaded the ordinary way `conftest.py` makes possible (the module has no
+Revit import at all, so a plain `from vibe import joblocate` just works).
+Every env var is passed explicitly through `env={...}` rather than touched
+on the real process environment, so these never depend on, or leak into,
+whatever WILLTOOLS_JOBS happens to be set to on the machine running them.
+"""
+from vibe import joblocate as JL
+
+
+def _mk_job(tmp_path, name, text=u'job:\n  plant: x\n'):
+    folder = tmp_path / name
+    folder.mkdir()
+    (folder / 'knowledge.yaml').write_text(text, encoding='utf-8')
+    return folder
+
+
+# ---------------------------------------------------------------- job_candidates
+
+def test_job_candidates_finds_every_folder_with_a_knowledge_file(tmp_path):
+    _mk_job(tmp_path, 'alpha')
+    _mk_job(tmp_path, 'beta')
+    (tmp_path / 'not_a_job.txt').write_text('x', encoding='utf-8')
+    found = JL.job_candidates(str(tmp_path))
+    assert len(found) == 2
+    assert all(f.endswith('knowledge.yaml') for f in found)
+
+
+def test_job_candidates_ignores_a_folder_with_no_knowledge_yaml(tmp_path):
+    (tmp_path / 'empty_job').mkdir()
+    assert JL.job_candidates(str(tmp_path)) == []
+
+
+def test_job_candidates_ignores_files_at_the_top_level(tmp_path):
+    (tmp_path / 'knowledge.yaml').write_text('x', encoding='utf-8')
+    assert JL.job_candidates(str(tmp_path)) == []
+
+
+def test_job_candidates_on_a_root_that_does_not_exist_is_empty(tmp_path):
+    assert JL.job_candidates(str(tmp_path / 'nope')) == []
+
+
+def test_job_candidates_on_no_root_at_all_is_empty():
+    assert JL.job_candidates(None) == []
+    assert JL.job_candidates('') == []
+
+
+# --------------------------------------------------------- resolve_job_knowledge
+
+def test_explicit_wins_over_everything_else(tmp_path):
+    _mk_job(tmp_path, 'alpha')
+    _mk_job(tmp_path, 'beta')
+    result = JL.resolve_job_knowledge(explicit='some/file.yaml',
+                                      jobs_root=str(tmp_path))
+    assert result.path == 'some/file.yaml'
+    assert result.how == 'explicit'
+    assert bool(result) is True
+
+
+def test_no_root_configured_is_not_blocking():
+    """The ordinary state of a machine with no WILLTOOLS_JOBS at all -- a
+    caller may fall back to DEFAULTS without treating this as an error."""
+    result = JL.resolve_job_knowledge(jobs_root=None, env={})
+    assert result.path is None
+    assert result.blocking is False
+    assert 'WILLTOOLS_JOBS' in result.reason
+
+
+def test_a_root_that_is_not_a_folder_is_blocking(tmp_path):
+    not_a_dir = tmp_path / 'not_a_dir.txt'
+    not_a_dir.write_text('x', encoding='utf-8')
+    result = JL.resolve_job_knowledge(jobs_root=str(not_a_dir))
+    assert result.path is None
+    assert result.blocking is True
+    assert str(not_a_dir) in result.reason
+
+
+def test_a_single_job_folder_is_used_with_no_further_input(tmp_path):
+    job = _mk_job(tmp_path, 'sample_job')
+    result = JL.resolve_job_knowledge(jobs_root=str(tmp_path))
+    assert result.path == str(job / 'knowledge.yaml')
+    assert result.how == 'single'
+    assert result.blocking is False
+
+
+def test_an_empty_jobs_root_is_not_blocking(tmp_path):
+    """Nothing under it yet -- a fresh install, not a misconfiguration."""
+    result = JL.resolve_job_knowledge(jobs_root=str(tmp_path))
+    assert result.path is None
+    assert result.blocking is False
+    assert str(tmp_path) in result.reason
+
+
+def test_several_job_folders_with_none_named_refuses_and_lists_them(tmp_path):
+    """The exact ruling this module exists to enforce: guessing among several
+    real job folders is a worse failure than asking, so this is BLOCKING."""
+    _mk_job(tmp_path, 'sample_job')
+    _mk_job(tmp_path, 'Horizon')
+    _mk_job(tmp_path, 'sample_job_detached')
+    result = JL.resolve_job_knowledge(jobs_root=str(tmp_path))
+    assert result.path is None
+    assert result.blocking is True
+    assert result.reason is not None
+    assert 'sample_job' in result.reason
+    assert 'Horizon' in result.reason
+    assert 'sample_job_detached' in result.reason
+    assert len(result.candidates) == 3
+    assert '--job' in result.reason
+
+
+def test_a_named_job_picks_one_of_several(tmp_path):
+    _mk_job(tmp_path, 'sample_job')
+    horizon = _mk_job(tmp_path, 'Horizon')
+    result = JL.resolve_job_knowledge(jobs_root=str(tmp_path),
+                                      job_name='Horizon')
+    assert result.path == str(horizon / 'knowledge.yaml')
+    assert result.how == 'named'
+    assert result.blocking is False
+
+
+def test_a_named_job_that_does_not_exist_is_blocking_and_lists_real_ones(
+        tmp_path):
+    _mk_job(tmp_path, 'sample_job')
+    _mk_job(tmp_path, 'Horizon')
+    result = JL.resolve_job_knowledge(jobs_root=str(tmp_path),
+                                      job_name='NoSuchJob')
+    assert result.path is None
+    assert result.blocking is True
+    assert 'NoSuchJob' in result.reason
+    assert 'sample_job' in result.reason
+    assert 'Horizon' in result.reason
+
+
+def test_env_supplies_the_root_when_jobs_root_is_not_given(tmp_path):
+    job = _mk_job(tmp_path, 'only-one')
+    result = JL.resolve_job_knowledge(env={JL.JOBS_ENV: str(tmp_path)})
+    assert result.path == str(job / 'knowledge.yaml')
+
+
+def test_explicit_bypasses_env_entirely(tmp_path):
+    _mk_job(tmp_path, 'alpha')
+    _mk_job(tmp_path, 'beta')
+    result = JL.resolve_job_knowledge(explicit='chosen.yaml',
+                                      env={JL.JOBS_ENV: str(tmp_path)})
+    assert result.path == 'chosen.yaml'
+    assert result.how == 'explicit'
+
+
+def test_result_is_falsy_when_nothing_was_found():
+    result = JL.resolve_job_knowledge(jobs_root=None, env={})
+    assert not result
+    assert bool(result) is False