validate-manifest.py, the naming gate and setup-project.py: a chain link no tree answers for is offered what each caller reads, so the root's validator and setup's step (4) no longer offer --link-source, which neither takes, and the gate spells every --link-source value and path it prints

docs/cli.md

@@ -940,7 +940,9 @@ usage: validate-repository-naming.py [-h] [--policy POLICY]
                                      [--pins PINS]
                                      [--referent-chain REFERENT_CHAIN]
                                      [--link-source [PRODUCT=]PATH]
-                                     [--explain] [--quiet] [names ...]
+                                     [--link-source-label FLAG]
+                                     [--link-remedy LINK=TEXT] [--explain]
+                                     [--quiet] [names ...]
 
 Classify repository names against `contracts/repository-naming.yaml`.
 
@@ -993,6 +995,17 @@ options:
                         declared-unverified, and a source that cannot be read
                         is named with the system's reason: both are warnings
                         and not findings, an explicit source included.
+  --link-source-label FLAG
+                        the caller's own name for the bare --link-source it
+                        passes, such as --pin-source (a FLAG that starts with
+                        - is given after an =): the link-source-unreadable
+                        WARNING and the not-used NOTE name that value by FLAG,
+                        and neither says a value holding = was read as a PATH
+  --link-remedy LINK=TEXT
+                        the caller's words for what would let LINK's tree be
+                        read, offered in place of this script's own where that
+                        link is declared-unverified. Repeatable; the last
+                        value for a link wins.
   --explain             print every family each name satisfies, why one of
                         them won, and what the others are recorded as
   --quiet

scaffold-project.py

@@ -88,11 +88,6 @@
     VISIBILITY_CHOICES, NamingPolicy, Refusal, accepts_role, checked_value,
     git_out, link_pins_from_trees, repo_basename, shell_line, tree_digest,
 )
-# The variable a chain link's tree is read through, and which links share
-# one, for the sources the scaffold offers a link it could not read (#610).
-from repo_shape import (  # noqa: E402
-    pin_product_key, pin_source_env_name, pin_source_env_shared,
-)
 from shape_materialize import (  # noqa: E402
     RULESET_HINT, SHAPE_REPOSITORY, CommandFailed,
     copy_tree, default_reference, descendant_note, election_date, env_commit,
@@ -117,6 +112,11 @@
 # Whether `--elected-by`, `--reference` and `--name` are text a file can
 # hold: the question `adopt-project.py` asks of the same values (#282).
 from shape_materialize import unwritable_reason  # noqa: E402
+# The words a chain link that is not reachable is offered: what THIS tool
+# reads (#610), which setup's step (4) hands the naming gate too (#661).
+from shape_materialize import (  # noqa: E402
+    scaffold_link_remedies as _link_remedies,
+)
 # The shape half of the leg-path collision rule, which `adopt-project.py`
 # asks of its own mount paths (#172), imported as one unit (#197), with the
 # one spelling of the file a `--pin` adds to what the shape writes.
@@ -1054,48 +1054,6 @@ def _declaration(args) -> tuple[dict, set, tuple, dict]:
     return pins, declared_pins, chain, link_pins
 
 
-def _link_remedies(chain: tuple) -> dict[str, str]:
-    """What would let each chain link's own tree be read, in the scaffold's
-    own sources: `{pin_product_key(link): the words}` for the
-    `declared-unverified` WARNING about a tree that is not reachable (#610).
-
-    That warning offered "a sibling checkout, SHAPE_PIN_SOURCE_<LINK>, or
-    --link-source <link>=<path>": the naming validator's three, and two of
-    them the scaffold does not have. It has no `--link-source`, and it reads
-    no checkout beside anything (`link_pins_from_trees(chain, None, ...)`).
-    It reads `SHAPE_PIN_SOURCE_<LINK>` for every link, unless another link
-    of the chain shares the variable (#275), and its `--pin-source` for the
-    FIRST link alone (#441), the pinned product's clone. A later link that
-    shares its variable has neither, which only a hand-written chain can
-    hold, and the warning says so.
-
-    Keyed by `pin_product_key`, the key `_chain_link_findings` finds a
-    holder's entry by (#444). Keyed by `casefold()`, `openß` and `openss`,
-    two links of one chain, wrote one entry, and the first link was offered
-    the later one's words.
-    """
-    links = [repo_basename(link) for link in chain]
-    shared = pin_source_env_shared(links)
-    remedies: dict[str, str] = {}
-    for index, link in enumerate(links[:-1]):
-        key = pin_product_key(link)
-        sources = [] if key in shared else [pin_source_env_name(link)]
-        if not index:
-            sources.append(f"a --pin-source clone of {link} that holds its "
-                           "project.yaml")
-        if not sources:
-            remedies[key] = (
-                "the scaffold reads no source for it: "
-                f"{pin_source_env_name(link)} is another link's too, and "
-                "--pin-source is the first link's tree alone")
-        elif len(sources) == 1:
-            remedies[key] = f"{sources[0]} would let it be read"
-        else:
-            remedies[key] = (f"{sources[0]}, or {sources[1]}, "
-                             "would let it be read")
-    return remedies
-
-
 def _check_referent_chain(policy, assembly_name: str, declared_pins: set,
                           chain: tuple, link_pins: dict) -> None:
     """(d) A declared `--referent-chain` reaches the referent the name claims,

scripts/shape_materialize.py

@@ -64,9 +64,13 @@
 # which products share a `SHAPE_PIN_SOURCE_<PRODUCT>` variable, the one answer
 # the project's own `validate-pins.py` reports on (#275), with two
 # declarations ONE product when they share a pin file (`pin_product_key`).
+# `scaffold_link_remedies` reads a chain with the same names: each link's
+# variable (`pin_source_env_name`), whether another link shares it
+# (`pin_source_env_shared`), and the link's name (`repo_basename`) (#661).
 from repo_shape import (  # noqa: E402
     GH_TREE_API, NEUTRAL_PRODUCT_OWNER, PIN_SOURCE_ENV_PREFIX,
-    pin_product_key, pin_source_env_collisions, tree_digest,
+    pin_product_key, pin_source_env_collisions, pin_source_env_name,
+    pin_source_env_shared, repo_basename, tree_digest,
 )
 # How a `--pin-source` that is not printable is named, the one spelling the
 # scaffold's chain WARNING gives it too (#610).
@@ -2926,6 +2930,48 @@ def pin_digest_from_source(source: Path, commit: str, repository: str) -> str:
         ) from exc
 
 
+def scaffold_link_remedies(chain) -> dict[str, str]:
+    """What would let each chain link's own tree be read, in the scaffold's
+    own sources: `{pin_product_key(link): the words}` for the
+    `declared-unverified` WARNING about a tree that is not reachable (#610).
+
+    That warning offered "a sibling checkout, SHAPE_PIN_SOURCE_<LINK>, or
+    --link-source <link>=<path>": the naming validator's three, and two of
+    them the scaffold does not have. It has no `--link-source`, and it reads
+    no checkout beside anything (`link_pins_from_trees(chain, None, ...)`).
+    It reads `SHAPE_PIN_SOURCE_<LINK>` for every link, unless another link
+    of the chain shares the variable (#275), and its `--pin-source` for the
+    FIRST link alone (#441), the pinned product's clone. A later link that
+    shares its variable has neither, which only a hand-written chain can
+    hold, and the warning says so.
+
+    Keyed by `pin_product_key`, the key `_chain_link_findings` finds a
+    holder's entry by (#444). Keyed by `casefold()`, `openß` and `openss`,
+    two links of one chain, wrote one entry, and the first link was offered
+    the later one's words.
+    """
+    links = [repo_basename(link) for link in chain]
+    shared = pin_source_env_shared(links)
+    remedies: dict[str, str] = {}
+    for index, link in enumerate(links[:-1]):
+        key = pin_product_key(link)
+        sources = [] if key in shared else [pin_source_env_name(link)]
+        if not index:
+            sources.append(f"a --pin-source clone of {link} that holds its "
+                           "project.yaml")
+        if not sources:
+            remedies[key] = (
+                "the scaffold reads no source for it: "
+                f"{pin_source_env_name(link)} is another link's too, and "
+                "--pin-source is the first link's tree alone")
+        elif len(sources) == 1:
+            remedies[key] = f"{sources[0]} would let it be read"
+        else:
+            remedies[key] = (f"{sources[0]}, or {sources[1]}, "
+                             "would let it be read")
+    return remedies
+
+
 def shown_source(source) -> str:
     """A `--pin-source` path as a refusal names it: as it is, unless a
     character in it is not printable (`str.isprintable`), and then as