docs: document every version_basis kind and key

tests/test_doc_pages.py

@@ -1741,6 +1741,23 @@ class ArchitectureStatesTheArbitration(unittest.TestCase):
             self.assertIn(said, section)
 
 
+class VersionBasisReferenceIsTheSchema(unittest.TestCase):
+    """profiling.md listed five kinds of version_basis: `unverified`, its
+    `why` and the `url`, `commit` and `match` keys 18 profiles use were in
+    the schema alone."""
+
+    def test_the_row_names_every_kind_reason_and_key(self):
+        schema = json.loads((ROOT / "schemas" / "emulator.schema.json").read_text(encoding="utf-8"))
+        basis = schema["$defs"]["version_basis"]["properties"]
+        page = (WIKI / "profiling.md").read_text(encoding="utf-8")
+        row = next(line for line in page.splitlines() if line.startswith("| `version_basis` |"))
+        for word in [*basis["kind"]["enum"], *basis["why"]["enum"], *basis]:
+            with self.subTest(word=word):
+                self.assertIn(f"`{word}`", row)
+        tools = (WIKI / "tools.md").read_text(encoding="utf-8")
+        self.assertIn("`unverified`", tools)
+
+
 class ReportExcerptIsTheRun(unittest.TestCase):
     """reading-reports.md quoted 'From python scripts/verify.py --platform
     retrodeck' a run that said 0 required missing after the command had started

wiki/profiling.md

@@ -517,7 +517,7 @@ reports the profile as uncheckable, and the CI job that runs
 | `upstream` | no | original emulator repository URL |
 | `profiled_date` | see above | date of source analysis. Quote it, or YAML parses it as a date object |
 | `core_version` | every profile (`tests/test_version_basis.py`) | the version of the code at the pin, read where `version_basis` says. null when the code states none, never `Git`, `SVN` or a branch name. A dict keyed by build mode when the builds differ |
-| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read: `file` (`path`, `pattern`, optional `format`), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form), `alias` (`of`), `package` (`artifact`, the APK or binary read) or `none`. `repo` names `upstream` when the version is the upstream tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it |
+| `version_basis` | every profile (`tests/test_version_basis.py`) | where `core_version` is read, by `kind`: `file` (`path`, `pattern`, optional `format`, and `url` with its `commit` for a file outside the profile's repositories, such as the package file of a build a platform ships), `tag` (the nearest `tag` in the pin's history and its `distance`, `core_version` in git describe's form, `match` the glob a tag must fit), `alias` (`of`), `package` (`artifact`, the APK or binary read, `url` where it was obtained), `none` (the code states no version: `core_version` null) or `unverified` (no reading could be made: `core_version` stays as written and is reported unconfirmed, `why` says why: `no_pin`, `host_unsupported`, `host_gone`, `host_unreachable`, `pin_off_branch`, `no_artifact`, `no_source`). `repo` names `upstream` or `source_mirror` when the version is that tree's. `profile_sync --verify-version` reads it again, and a pin advance rewrites `core_version` from it |
 | `source_commit` | see above | commit SHA of `source` the code was read at. Anchors every `source_ref` line number |
 | `upstream_commit` | no | same, for `upstream` |
 | `pin_frozen` | no | why `source_commit` is held on purpose rather than followed. The profile is then judged against its own revision, like one pinned to a superseded tag |

wiki/tools.md

@@ -591,9 +591,11 @@ shows added, removed and renamed files in the directories the refs point at.
 says where it is read: a pattern in one file (`file`), the nearest tag and
 the commits after it (`tag`, written in git describe's form), the profile an
 alias follows (`alias`), an artefact read outside any source tree
-(`package`), or `none` when the code states nothing, with `core_version`
-null. `--verify-version` reads it again at the pin and exits 1 on a
-difference or a missing basis. `--set-version` writes what the code states.
+(`package`), `none` when the code states nothing, with `core_version`
+null, or `unverified` when no reading can be made (a forge gone, a host the
+tools cannot read, no artefact to read): `core_version` stays as written,
+reported unconfirmed, and `why` names the reason. `--verify-version` reads
+it again at the pin and exits 1 on a difference or a missing basis. `--set-version` writes what the code states.
 A pin advance reads the version at the new pin in the same write and is
 refused when it cannot: a package version moves by hand.