Find NDIcalc document definitions in installed calculator packages

[stevevanhooser]

⚠️ Merge order

Merge this after VH-Lab/NDIcalc-vis-matlab's python-packaging PR. The new runtime dependency points at https://github.com/VH-Lab/NDIcalc-vis-matlab/archive/refs/heads/main.zip, and main has no pyproject.toml until that PR merges. Until then every CI job that installs NDI will fail at the install step. That failure is expected. The dependency is not pointed at the feature branch, on purpose.

Why

Today ndi_install.py git-clones NDIcalc-vis-matlab, and install_ndi_common_docs() copies its ndi_common/{database,schema}_documents/{calc,neuro,vision} trees into src/ndi/ndi_common/, which is gitignored. A uv/pip install (the double-click installer path that #328 prepared for) never runs that script, so every NDIcalc document type was missing.

What

This works the way MATLAB does: ndi.common.PathConstants.CalcDoc/CalcDocSchema are built from ndi.fun.find_calc_directories().

• ndi.fun.find_calc_directories (src/ndi/fun/utils.py): returns each calculator toolbox directory. MATLAB scans for sibling NDIcalc*-matlab folders; this reads the ndi.calc entry points instead (importlib.metadata.entry_points(group="ndi.calc"), sorted by name). If an entry point fails to load, raises, or returns something that is not a directory, it warns and is skipped, so import ndi cannot crash on it.
• ndi_common_PathConstants.CalcDoc / CalcDocSchema: these use the MATLAB names and are lists of <toolbox>/ndi_common/database_documents (resp. schema_documents). They are lazy and memoized. You can override them (assign a list, or None/del to rediscover) and also through set_paths(calc_doc=..., calc_doc_schema=...), the same way DOCUMENT_PATH works.
• DID globals: $NDICALCDOCUMENTPATH / $NDICALCSCHEMAPATH are now registered as those lists, as in MATLAB. DID-python already supports list values: did.validate.resolve_definition_path tries each entry of a list, so no DID-python change is needed. The only gap there is that DID's DEFINITIONS type annotation still says dict[str, str], and that is cosmetic. Empty values are not registered, matching MATLAB. The old comment saying Python has no separate calculator packages has been replaced.
• Lookups: ndi_document.read_blank_definition (both the explicit-path and bare-name searches), ndi.validate._load_schema and ndi.fun.doc.allTypes (which MATLAB also points at CalcDoc) now search NDI's tree first, then every CalcDoc/CalcDocSchema folder. vision/contrast_tuning resolves from the installed package.
• python -m ndi check: adds a "NDI calculator documents (ndi.calc)" check, and the DID-globals check now handles list values.
• Copy step removed: the NDIcalc-vis-matlab entry and install_ndi_common_docs() are gone from ndi_install.py, along with the .gitignore entries for the copied folders. The Pyraview and vhlab-toolbox steps are unchanged.
• pyproject.toml: adds ndicalc-vis-matlab @ …/archive/refs/heads/main.zip. It is an archive URL, not git+.
• CI: the install-without-git job now imports ndicalc_vis_matlab and checks that vision/contrast_tuning resolves, both directly and through DID's $NDICALCDOCUMENTPATH.

Tests

• New tests/test_calc_doc_discovery.py builds a fake calculator package (a module plus a .dist-info with an ndi.calc entry point) in tmp_path, so it needs no network. It covers:
  • discovery
  • broken, unimportable and non-directory entry points, which warn and are skipped
  • overriding CalcDoc
  • DID list registration, with an empty list left unregistered
  • definition, bare-name, schema, DID-placeholder and allTypes resolution
• A class in that file tests the real ndicalc-vis-matlab: it is discovered, vision/contrast_tuning resolves, and its schema resolves through DID. It skips if the package is absent.
• test_document_path_variables.py, test_did_integration.py and test_issues_93_94.py now read the calculator trees from CalcDoc/CalcDocSchema instead of the copied folders. The calculator-only assertions skip when no calculator package is installed. test_ndi_install_exit_codes.py drops its stub for the removed function.
• test_matlab_bridge_properties.py now follows metaclass= the same way it follows a base class. CalcDoc/CalcDocSchema are metaclass properties, as DOCUMENT_PATH is, so they are now visible to the check, and their entries in bridge_property_allowlist.yaml are removed.

Run locally: black --check, ruff check, and the full pytest tests/ (5906 passed, 601 skipped). The bridge checks also ran against an NDI-matlab checkout with NDI_BRIDGE_CHECK_STRICT=1 (197 passed). I also ran the affected tests with ndicalc-vis-matlab uninstalled, and they pass and skip correctly.

Sandbox caveat: this sandbox gets 403 on github.com/.../archive/.... So locally I installed every dependency from local clones, and ndicalc-vis-matlab from a clone of its python-packaging branch. The archive-URL install path is checked only by CI.

Bridge

• src/ndi/common/ndi_matlab_python_bridge.yaml: adds CalcDoc and CalcDocSchema properties. set_paths gets two new arguments. updateDIDConstants now returns dict[str, str | list[str]], and the divergence paragraph in its decision_log is replaced. Hashes are unchanged (MATLAB has not moved).
• src/ndi/fun/ndi_matlab_python_bridge.yaml: find_calc_directories stays ported_differently, now with python_path: ndi/fun/utils.py, output arguments, and a decision_log explaining that entry points replace the sibling-folder scan. allTypes's log now mentions CalcDoc.

🤖 Generated with Claude Code

https://claude.ai/code/session_013devLWydMwi8CvWpbHm6in

---

Generated by Claude Code

[stevevanhooser]

Install without git (and every other job that installs NDI) is failing, as expected. uv reports that ndicalc-vis-matlab @ https://github.com/VH-Lab/NDIcalc-vis-matlab/archive/refs/heads/main.zip "does not appear to be a Python project": NDIcalc-vis-matlab's main has no pyproject.toml yet, because the packaging is still on its python-packaging branch.

This PR cannot fix that on its own side. Pointing the dependency at the feature branch was ruled out on purpose. Once VH-Lab/NDIcalc-vis-matlab's python-packaging PR merges, CI here gets re-run against the new main, and I'll fix anything that is still red.

---

Generated by Claude Code