@runeditrun/rer 0.0.0-stage → 0.1.1

package/scripts/publish-check/hit_location.py

@@ -0,0 +1,18 @@
+"""Resolve a native Gitleaks hit to the exact byte spans of its match."""
+
+
+def match_spans(data, hit):
+    lines = data.splitlines(keepends=True)
+    try:
+        first, last = hit['StartLine'] - 1, hit['EndLine'] - 1
+        if not (0 <= first <= last < len(lines)):
+            return []
+        start = sum(map(len, lines[:first])) + hit['StartColumn'] - 1
+        end = sum(map(len, lines[:last])) + hit['EndColumn']
+        # Gitleaks 8.30.1 includes the preceding newline in columns
+        # after fragment line one; Git fragments may begin mid-file.
+        # Resolve that one-byte difference only against the exact match.
+        return [(start - shift, end - shift) for shift in (0, 1)
+                if data[start - shift:end - shift] == hit['Match'].encode('utf-8')]
+    except (KeyError, TypeError, IndexError, UnicodeError):
+        return []

package/scripts/publish-check/hygiene_config.py

@@ -0,0 +1,42 @@
+"""Base-owned defaults and explicit committed seed publication declarations."""
+import json
+import re
+from publication_config import intended_public_repositories
+
+# A home segment within a relative path is not an absolute home directory.
+# Match the username itself so a bare home, including one with spaces, counts.
+LOCAL_PATH = re.compile(r'''(?x)(?<![^\s("'`=:\[<>{|])(?:[*_]|~~)*(?:(?:(?i:(?a:file://)))?(?<!/[A-Z]:)/(?:Users|home)/|(?i:(?:(?a:file:///))?[A-Z]:[\\/]+Users[\\/]+))[^/\\\s"'<>`]+''')
+CONFIG = '.publish-check/config.json'
+# An alphabetic top-level label ends before a following digit, such as the DER
+# tag after a certificate's email value; other labels keep the full extent.
+EMAIL = re.compile(r"(?<![A-Za-z0-9_.+%-])[A-Za-z0-9_][A-Za-z0-9_.+%'-]{0,63}@(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)*[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.(?:[A-Za-z]{2,63}(?![A-Za-z.-])|[A-Za-z][A-Za-z0-9-]{1,62}(?![A-Za-z0-9.-]))|(?<![A-Za-z0-9_.+%-])[A-Za-z0-9_][A-Za-z0-9_.+%'-]{0,63}@(?:example|test|invalid)(?![A-Za-z0-9.-])", re.I)
+RULES = {'hygiene.local-path', 'hygiene.github-private', 'hygiene.github-missing',
+         'hygiene.email', 'hygiene.internal-reference'}
+
+
+def load_config(data=None):
+    config = json.loads(data) if data is not None else {'schemaVersion': 1}
+    if not isinstance(config, dict) or config.get('schemaVersion') != 1 or set(config) - {'schemaVersion', 'publicEmails', 'internalReferencePatterns'}:
+        raise ValueError('invalid publication config')
+    emails = config.get('publicEmails', [])
+    extra_patterns = config.get('internalReferencePatterns', [])
+    if not isinstance(extra_patterns, list):
+        raise ValueError('invalid internal references')
+    patterns = extra_patterns
+    if not isinstance(emails, list) or any(not isinstance(e, str) or not EMAIL.fullmatch(e) or '*' in e for e in emails):
+        raise ValueError('invalid public emails')
+    if not isinstance(patterns, list) or any(not isinstance(p, str) or not p for p in patterns):
+        raise ValueError('invalid internal references')
+    try:
+        compiled = [re.compile(p) for p in patterns]
+    except re.error:
+        raise ValueError('invalid internal reference regex') from None
+    return {'publicEmails': {e.lower() for e in emails}, 'internalReferencePatterns': compiled,
+            'intendedPublicRepositories': intended_public_repositories()}
+
+
+def public_email(address, config):
+    domain = address.lower().rsplit('@', 1)[1]
+    # RFC 2606 reserved names; .localhost also holds local dev personas (<as>@dev.localhost).
+    reserved = ('example', 'test', 'invalid', 'localhost', 'example.com', 'example.net', 'example.org')
+    return address.lower() in config['publicEmails'] or any(domain == d or domain.endswith('.' + d) for d in reserved)

package/scripts/publish-check/hygiene_text.py

@@ -0,0 +1,11 @@
+"""Decode common textual representations without executing source."""
+import html
+import re
+from urllib.parse import unquote
+
+
+def decoded_text(data):
+    text = data.replace(b'\0', b'').decode('utf-8', 'replace')
+    text = html.unescape(unquote(text))
+    return re.sub(r'\\(?:u([0-9a-fA-F]{4})|x([0-9a-fA-F]{2}))',
+                  lambda match: chr(int(match.group(1) or match.group(2), 16)), text).replace('\\/', '/')

package/scripts/publish-check/identity-recipe.mjs

@@ -0,0 +1,54 @@
+// Validate inert committed JSON with the maintained recipe implementation.
+// Never import or execute a tool from the repository being inspected.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {manifest, VERSION} from '../../edition-authoring/manifest.mjs';
+import {hash, json} from '../../edition-authoring/files.mjs';
+
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const identity = value => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]*\/[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(value) && !/\s/.test(value);
+function optionalArray(value, key) {
+  if (key in value && !Array.isArray(value[key])) throw Error('Invalid array');
+}
+function origin(value) {
+  if (!object(value) || typeof value.repository !== 'string' || typeof value.revision !== 'string' || value.revision.length !== 40) throw Error('Invalid origin');
+  optionalArray(value, 'paths');
+}
+function shape(recipe) {
+  if (!object(recipe) || recipe.identityKind !== 'project' || !identity(recipe.id) || !object(recipe.toolchain)) throw Error('Invalid identity');
+  if (recipe.parent !== undefined && recipe.parent !== null) origin(recipe.parent);
+  if (!Array.isArray(recipe.components)) throw Error('Invalid components');
+  for (const component of recipe.components) {
+    if (!object(component) || !identity(component.id) || !object(component.source)) throw Error('Invalid component');
+    for (const key of ['requires', 'conflicts']) {
+      optionalArray(component, key);
+      if (component[key]?.some(value => typeof value !== 'string')) throw Error('Invalid dependency');
+    }
+    const selected = component.source;
+    if (selected.kind === 'git') origin(selected);
+    else if (selected.kind === 'local') {
+      if (selected.origin !== undefined) origin(selected.origin);
+      optionalArray(selected, 'mappings');
+      if (selected.mappings?.some(value => !object(value))) throw Error('Invalid mapping');
+    }
+  }
+}
+
+let directory;
+try {
+  const data = fs.readFileSync(0, 'utf8');
+  const recipe = JSON.parse(data);
+  shape(recipe);
+  if (VERSION !== '1.1.0') throw Error('Unsupported recipe validator');
+  directory = fs.mkdtempSync(path.join(os.tmpdir(), 'publish-identity-'));
+  fs.writeFileSync(path.join(directory, 'edition.json'), data);
+  // manifest currently returns the complete parsed recipe, including metadata.
+  // Use its exact JSON.stringify(..., null, 2) + newline hash, as cli lock does.
+  process.stdout.write(hash(json(manifest(directory))));
+} catch {
+  // Input, paths and diagnostics are intentionally absent from the report.
+  process.exitCode = 1;
+} finally {
+  if (directory) fs.rmSync(directory, {recursive: true, force: true});
+}

package/scripts/publish-check/json_identity.py

@@ -0,0 +1,79 @@
+"""Strict JSON documents and exact native-match byte locations."""
+import json
+import re
+
+from hit_location import match_spans
+
+HEX = re.compile(r'[a-f0-9]{64}\Z')
+GIT_REVISION = re.compile(r'[a-f0-9]{40}\Z')
+
+
+class Document:
+    """Reject ambiguous/non-JSON input and retain exact byte spans of strings."""
+    def __init__(self, data):
+        self.data = data
+        text = data.decode('utf-8')
+        self.spans = {}
+        def invalid_constant(_):
+            raise ValueError('Non-JSON constant')
+
+        decoder = json.JSONDecoder(parse_constant=invalid_constant)
+
+        def whitespace(at):
+            while at < len(text) and text[at] in ' \t\r\n':
+                at += 1
+            return at
+
+        def parse(at, pointer):
+            at = whitespace(at)
+            if text[at] in '{[':
+                mapping = text[at] == '{'
+                end = '}' if mapping else ']'
+                result = {} if mapping else []
+                at = whitespace(at + 1)
+                if text[at] == end:
+                    return result, at + 1
+                while True:
+                    if mapping:
+                        key, at = decoder.raw_decode(text, at)
+                        if not isinstance(key, str) or key in result:
+                            raise ValueError('Ambiguous JSON member')
+                        at = whitespace(at)
+                        if text[at] != ':':
+                            raise ValueError('Invalid JSON member')
+                        at += 1
+                    else:
+                        key = len(result)
+                    value, at = parse(at, (*pointer, key))
+                    if mapping:
+                        result[key] = value
+                    else:
+                        result.append(value)
+                    at = whitespace(at)
+                    if text[at] == end:
+                        return result, at + 1
+                    if text[at] != ',':
+                        raise ValueError('Invalid JSON separator')
+                    at = whitespace(at + 1)
+            value, end = decoder.raw_decode(text, at)
+            if isinstance(value, str) and (HEX.fullmatch(value) or GIT_REVISION.fullmatch(value)):
+                self.spans[pointer] = (len(text[:at].encode('utf-8')), len(text[:end].encode('utf-8')), value)
+            return value, end
+
+        self.value, end = parse(0, ())
+        if whitespace(end) != len(text):
+            raise ValueError('Trailing JSON data')
+
+    def matches(self, hit, pointers):
+        if hit.get('RuleID') not in ('generic-api-key', 'hex-api-key'):
+            return False
+        located = set()
+        for left, right in match_spans(self.data, hit):
+            for pointer in pointers:
+                span = self.spans.get(pointer)
+                if span:
+                    a, b, value = span
+                    if (left <= a + 1 and b - 1 <= right and hit.get('Secret') == value
+                            and self.data[a + 1:b - 1] == value.encode('ascii')):
+                        located.add((a, b))
+        return len(located) == 1

package/scripts/publish-check/license-exceptions.json

@@ -0,0 +1,11 @@
+{
+  "schemaVersion": 1,
+  "exceptions": [{
+    "rule": "license.holder",
+    "path": "LICENSE",
+    "holder": "Peter Industries Pty Ltd as trustee for Peter Family Trust, trading as JustEvery",
+    "date": "2026-10-06",
+    "sha256": "75de081fbc3da1ca679dff36ae665709d8c312652527d321511a10f66a17fd7c",
+    "reason": "Owner-authorized preservation of HappyToHelp's original attribution, exactly as shipped in public v0.2.1 and retained for the fast-forward v0.2.2 candidate. Applies only to these complete LICENSE bytes."
+  }]
+}

package/scripts/publish-check/licenses.py

@@ -0,0 +1,49 @@
+"""Root licence holder checks and narrowly bound, dated exceptions."""
+from datetime import date, datetime, timezone
+import hashlib
+import json
+import re
+from pathlib import Path
+
+EXCEPTIONS = 'PUBLISH-EXCEPTIONS.json'
+HOLDER = re.compile(r'^\s*Copyright\s*(?:\(c\)|©)?\s*(?:\d{4}(?:\s*[-–,]\s*\d{4})*\s+)?(.+?)\s*$', re.I | re.M)
+
+
+def exceptions(data):
+    if data is None:
+        return []
+    document = json.loads(data)
+    if document.get('schemaVersion') != 1 or not isinstance(document.get('exceptions'), list):
+        raise ValueError('invalid exceptions')
+    for entry in document['exceptions']:
+        if (entry.get('rule') != 'license.holder' or entry.get('path') != 'LICENSE'
+                or not isinstance(entry.get('holder'), str) or not entry['holder'].strip()
+                or not re.fullmatch(r'[0-9a-f]{64}', entry.get('sha256', ''))
+                or not isinstance(entry.get('reason'), str) or not entry['reason'].strip()
+                or not re.fullmatch(r'\d{4}-\d{2}-\d{2}', entry.get('date', ''))
+                or date.fromisoformat(entry['date']) > datetime.now(timezone.utc).date()):
+            raise ValueError('invalid exception')
+    return document['exceptions']
+
+
+def license_rules(data, recorded):
+    if data is None or not data.strip():
+        return ['license.missing']
+    try:
+        text = data.decode('utf-8')
+    except UnicodeError:
+        return ['license.unreadable']
+    holders = HOLDER.findall(text)
+    if not holders:
+        return ['license.holder-missing']
+    digest = hashlib.sha256(data).hexdigest()
+    if any(holder != 'Run Edit Run' and not any(e['holder'] == holder and e['sha256'] == digest for e in recorded)
+           for holder in holders):
+        return ['license.holder']
+    return []
+
+
+def registry():
+    """Base-reviewed exceptions, bound to holder and complete LICENSE bytes."""
+    path = Path(__file__).with_name('license-exceptions.json')
+    return exceptions(path.read_bytes())

package/scripts/publish-check/policy.py

@@ -0,0 +1,18 @@
+"""Report redaction, separate from the Gitleaks secret detector."""
+import hashlib
+import re
+from hygiene_config import EMAIL, LOCAL_PATH
+from hygiene_text import decoded_text
+
+READ_LIMIT = 64 * 1024 * 1024
+TOKEN_PATH = re.compile(r'(?:gh[pousr]_|github_pat_|sk-|glpat-|npm_|whsec_|rk_live_|sk_live_|hf_|xapp-|xox[baprs]-|SG\.|re_|AIza|AKIA|ASIA)[A-Za-z0-9_./+\-]{16,}')
+
+
+def safe_path(path, env_hashes=frozenset(), internal_patterns=()):
+    raw = path.encode('utf-8', 'surrogateescape')
+    text = decoded_text(raw)
+    private = EMAIL.search(text) or LOCAL_PATH.search(text) or TOKEN_PATH.search(text)
+    if (private or hashlib.sha256(raw).digest() in env_hashes or any(re.search(p, text) for p in internal_patterns)
+            or any(ord(c) < 32 or 0xD800 <= ord(c) <= 0xDFFF for c in path) or len(path) > 500):
+        return '[redacted-path-sha256:' + hashlib.sha256(raw).hexdigest() + ']'
+    return path

package/scripts/publish-check/project_identity.py

@@ -0,0 +1,89 @@
+"""Same-tree, explicit project identities; never a repository-name allowlist."""
+import json
+from pathlib import Path
+import re
+import subprocess
+from hygiene_text import decoded_text
+from policy import READ_LIMIT
+from reviewed import unique_fields
+
+FIELDS = {'edition.json': 'id', 'sources.lock.json': 'edition', 'rer-project.json': 'projectId'}
+TOOLCHAIN = {'id': 'runeditrun/edition-authoring', 'version': '1.1.0'}
+VALIDATOR = Path(__file__).with_name('identity-recipe.mjs')
+
+
+def document(data):
+    def reject_constant(value):
+        raise ValueError('non-JSON constant')
+    value = json.loads(data, object_pairs_hook=unique_fields, parse_constant=reject_constant)
+    if not isinstance(value, dict):
+        raise ValueError('invalid identity document')
+    return value
+
+
+def schema_one(value):
+    return not isinstance(value, bool) and value == 1
+
+
+def same_toolchain(value):
+    return isinstance(value, dict) and all(value.get(k) == v for k, v in TOOLCHAIN.items())
+
+
+def ordinary_document(entry):
+    return bool(entry and entry['kind'] == 'blob' and entry['mode'] in ('100644', '100755')
+                and entry['size'] <= READ_LIMIT)
+
+
+def tree_identity(history, root_entries):
+    """Validate actual nonrecursive root entries, including empty Git trees."""
+    roots = {e['path']: e for e in root_entries if e['path'] in FIELDS}
+    entry = roots.get('edition.json')
+    if entry is None:
+        return None, frozenset()
+
+    def read(entry):
+        if not ordinary_document(entry):
+            raise ValueError('unreadable identity document')
+        return history.blob(entry['oid'])
+
+    # An unreadable root cannot establish whether the edition opts in. It must
+    # not silently become an absent/legacy edition, even when Git omits it from
+    # the recursive file inventory. Ordinary legacy JSON keeps its old rules.
+    try:
+        data = read(entry)
+    except (ValueError, TypeError):
+        return None, frozenset({'edition.json'})
+    try:
+        recipe = document(data)
+    except (ValueError, TypeError, UnicodeError):
+        # Malformed opt-ins cannot become ordinary, permissive metadata. Other
+        # legacy malformed documents keep the existing scanner behaviour.
+        opted = re.search(r'\bidentityKind\b', decoded_text(data))
+        return None, frozenset({'edition.json'} if opted else ())
+    if 'identityKind' not in recipe:
+        return None, frozenset()
+    try:
+        if recipe['identityKind'] != 'project':
+            raise ValueError('unknown identity kind')
+        result = subprocess.run(['node', str(VALIDATOR)], input=data, capture_output=True, timeout=15)
+        canonical = result.stdout.decode('ascii')
+        if result.returncode or not re.fullmatch(r'[0-9a-f]{64}', canonical):
+            raise ValueError('invalid recipe')
+    except (OSError, ValueError, UnicodeError, subprocess.TimeoutExpired):
+        return None, frozenset({'edition.json'})
+    invalid = set()
+    for name in ('sources.lock.json', 'rer-project.json'):
+        if name not in roots:
+            continue
+        try:
+            value = document(read(roots[name]))
+            if value.get(FIELDS[name]) != recipe['id']:
+                raise ValueError('inconsistent project identity')
+            if name == 'sources.lock.json':
+                if not schema_one(value.get('schemaVersion')) or not same_toolchain(value.get('toolchain')) or value.get('manifest') != canonical:
+                    raise ValueError('inconsistent source lock')
+            elif not schema_one(value.get('schema')):
+                raise ValueError('invalid project metadata')
+        except (ValueError, TypeError, UnicodeError):
+            invalid.add(name)
+    return (None if invalid else recipe['id']), frozenset(invalid)

package/scripts/publish-check/provenance.py

@@ -0,0 +1,91 @@
+"""Recognize source declarations, never ordinary repository mentions."""
+import json
+import re
+from github_refs import URL, FULL, normalize
+
+MANIFESTS = ('edition.json', 'sources.lock.json')
+
+
+def source_key(value):
+    if not isinstance(value, dict):
+        return None
+    repository = value.get('repository')
+    revision = value.get('revision', value.get('commit'))
+    if not isinstance(repository, str) or not isinstance(revision, str) or not re.fullmatch(r'[0-9a-f]{40}|[0-9a-f]{64}', revision):
+        return None
+    if '://' in repository and repository.split('://', 1)[0].lower() not in ('http', 'https', 'git', 'ssh', 'git+http', 'git+https', 'git+ssh'):
+        return None
+    match = URL.fullmatch(repository)
+    repo = normalize(match.group(1)) if match else normalize(repository) if FULL.fullmatch(repository) else None
+    return (repo, revision) if repo else None
+
+
+def declarations(document):
+    if not isinstance(document, dict):
+        return
+    pending = [document.get('parent')]
+    components = document.get('components', [])
+    if isinstance(components, list):
+        pending.extend(c.get('source') for c in components if isinstance(c, dict))
+    while pending:
+        value = pending.pop()
+        if not isinstance(value, dict):
+            continue
+        if source_key(value):
+            yield value
+        pending.append(value.get('origin'))
+
+
+def declared_keys(data):
+    try:
+        return {source_key(value) for value in declarations(json.loads(data))}
+    except (ValueError, TypeError):
+        return set()
+
+
+def copy_record(document, declared):
+    """Canonical copy inventories bind the acquisition identity to declared pins."""
+    copies = document.get('copies')
+    if document.get('schemaVersion') != 1 or not isinstance(copies, list) or not copies:
+        return False
+    for copy in copies:
+        if not isinstance(copy, dict) or source_key(dict(repository=document.get('repository'), revision=copy.get('revision'))) not in declared:
+            return False
+        path, origin = copy.get('path'), copy.get('originPath')
+        if not all(isinstance(value, str) and value and not value.startswith('/') and '..' not in value.split('/') for value in (path, origin)):
+            return False
+        files, modes = copy.get('files'), copy.get('modes')
+        if not isinstance(files, dict) or not files or not isinstance(modes, dict) or files.keys() != modes.keys():
+            return False
+        if any(not (name == path or name.startswith(path + '/')) or not isinstance(value, str) or not re.fullmatch(r'[0-9a-f]{64}', value) or modes[name] not in ('100644', '100755') for name, value in files.items()):
+            return False
+    return True
+
+
+def provenance_text(text, path, declared=frozenset()):
+    snapshot = re.fullmatch(r'\.edition/sources/[0-9a-f]{64}\.json', path)
+    copied = path.rsplit('/', 1)[-1].lower() in ('provenance.json', 'origin.json')
+    if path not in MANIFESTS and not snapshot and not copied and not path.endswith('.json'):
+        return text, False
+    try:
+        document = json.loads(text)
+    except ValueError:
+        return text, False
+    if not isinstance(document, dict):
+        return text, False
+    if copy_record(document, declared):
+        document['repository'] = ''
+        return json.dumps(document), True
+    candidates = list(declarations(document)) if path in MANIFESTS else []
+    if snapshot and isinstance(document.get('files'), dict) and source_key(document.get('origin')) in declared:
+        candidates.append(document['origin'])
+    hashes = document.get('files')
+    copies = document.get('copies')
+    mapped = isinstance(copies, dict) and copies and all(isinstance(k, str) and isinstance(v, str) and k and v for k, v in copies.items())
+    hashed = isinstance(hashes, dict) and hashes and all(isinstance(h, str) and re.fullmatch(r'[0-9a-f]{64}', h) for h in hashes.values())
+    selected = isinstance(document.get('path'), str) and bool(document['path'])
+    if copied and source_key(document) in declared and (mapped or hashed or selected):
+        candidates.append(document)
+    for value in candidates:
+        value['repository'] = ''
+    return (json.dumps(document) if candidates else text), bool(candidates)

package/scripts/publish-check/provenance_pins.py

@@ -0,0 +1,33 @@
+"""Git object IDs at declared module-provenance locations, never whole files."""
+from json_identity import GIT_REVISION
+
+
+def module_pins(path, document):
+    if not isinstance(document, dict):
+        return
+    if path == 'base/PROVENANCE.json':
+        maps = [(('moduleCommits',), document.get('moduleCommits'))]
+    elif path in ('edition.json', 'sources.lock.json'):
+        if type(document.get('schemaVersion')) is not int or document['schemaVersion'] != 1:
+            return
+        components = document.get('components')
+        if not isinstance(components, list):
+            return
+        maps = []
+        for index, component in enumerate(components):
+            source = component.get('source') if isinstance(component, dict) else None
+            if not isinstance(source, dict):
+                continue
+            suffix = () if source.get('kind') == 'git' else ('origin',) if source.get('kind') == 'local' else None
+            if suffix is None:
+                continue
+            origin = source if not suffix else source.get('origin')
+            if isinstance(origin, dict):
+                maps.append((('components', index, 'source', *suffix, 'moduleRevisions'), origin.get('moduleRevisions')))
+    else:
+        return
+    for pointer, pins in maps:
+        if isinstance(pins, dict):
+            for module, revision in pins.items():
+                if module and isinstance(revision, str) and GIT_REVISION.fullmatch(revision):
+                    yield (*pointer, module)

package/scripts/publish-check/public_base.py

@@ -0,0 +1,63 @@
+"""A public base is a branch of an explicitly named remote, never a local ref.
+
+The declared base decides which history counts as already public, so it must
+come from the remote itself: `<url>#<branch>` is fetched into an isolated
+namespace and local branches, HEAD, tags and commit IDs are refused.
+"""
+import os
+import re
+import subprocess
+
+NAMESPACE = 'refs/publish-check/public/'
+URL = re.compile(r'(?:(?:https|ssh|git|file)://[^\s/#]*/[^\s#]*|[A-Za-z0-9._-]+@[A-Za-z0-9.-]+:[^\s#]+|/[^\s#]*)')
+
+
+class PublicBaseError(Exception):
+    """Carries a stable, value-free reason code."""
+
+    def __init__(self, code):
+        super().__init__(code)
+        self.code = code
+
+
+def parse(spec, repo):
+    """Return (url, branch) or refuse."""
+    url, separator, branch = spec.rpartition('#')
+    if not separator or not url or not branch:
+        raise PublicBaseError('public-base.not-remote-branch')
+    if not URL.fullmatch(url) or url.startswith('-') or any(ord(c) < 32 for c in spec):
+        raise PublicBaseError('public-base.not-remote-url')
+    if branch.startswith(('-', 'refs/')) or branch == 'HEAD':
+        raise PublicBaseError('public-base.not-branch-name')
+    if not valid_ref('refs/heads/' + branch):
+        raise PublicBaseError('public-base.not-branch-name')
+    local = url[len('file://'):] if url.startswith('file://') else (url if url.startswith('/') else None)
+    if local and same_repository(local, repo):
+        raise PublicBaseError('public-base.is-candidate-repository')
+    return url, branch
+
+
+def valid_ref(name):
+    try:
+        return subprocess.run(['git', 'check-ref-format', name], capture_output=True, timeout=10).returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def common_dir(path, env):
+    result = subprocess.run(['git', '-C', path, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+                            env=env, capture_output=True, timeout=10)
+    return os.path.realpath(os.fsdecode(result.stdout.strip())) if result.returncode == 0 else None
+
+
+def same_repository(path, repo, env=None):
+    env = env or {k: v for k, v in os.environ.items() if not k.startswith('GIT_')}
+    try:
+        remote = common_dir(path, env)
+        return remote is not None and remote == common_dir(repo, env)
+    except (OSError, subprocess.TimeoutExpired):
+        raise PublicBaseError('public-base.fetch-failed') from None
+
+
+def display(url):
+    return re.sub(r'^([a-z]+://)[^/@]*@', r'\1', url)

package/scripts/publish-check/public_hygiene.py

@@ -0,0 +1,80 @@
+"""Public-tree and message hygiene; findings never include matched values."""
+from collections import Counter
+import re
+from github_refs import REPOSITORY_HOSTS, references
+from destination import RULE as PENDING_DESTINATION
+from hygiene_text import decoded_text
+from provenance import provenance_text
+from hygiene_config import EMAIL, LOCAL_PATH, public_email
+from font_licence import without_required_notices
+from trust_bundle import anchor_values
+URI_AUTHORITY = re.compile(r'''(?i)(?a:(?P<scheme>[a-z][a-z0-9+.-]*:))?//(?P<authority>[^/?#\s<>"']+)''')
+
+
+def email_userinfo(match):
+    userinfo, _, host = match['authority'].rpartition('@')
+    # Without a scheme, arbitrary //text can also be a source comment.
+    if not match['scheme'] and host.lower().split(':', 1)[0] not in REPOSITORY_HOSTS:
+        return match.group()
+    # Keep actual email-valued userinfo, including a decoded %40, while
+    # excluding the host delimiter in an ordinary transport username@host.
+    return userinfo
+
+
+def private_emails(text, config):
+    # URL paths, queries and fragments remain visible to email inspection.
+    email_text = URI_AUTHORITY.sub(email_userinfo, without_required_notices(text))
+    email_text = re.sub(r'(?i)\b(?a:git@github\.com:)(?=[A-Za-z0-9])', '', email_text)
+    version = r'(?:v?[0-9]+(?:\.[0-9]+)*(?:-[A-Za-z0-9-]+)?|[a-f0-9]{40})(?![A-Za-z0-9_.-])'
+    email_text = re.sub(r'(?m)^\s*-?\s*uses:\s*[\"\']?[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+@[^\s\"\']+', '', email_text)
+    email_text = re.sub(r'(?<![A-Za-z0-9])(?:@[A-Za-z0-9_.-]+/)?[A-Za-z0-9_.-]+(?:/[A-Za-z0-9_.-]+)?@' + version, '', email_text)
+    return [match.group() for match in EMAIL.finditer(email_text) if not public_email(match.group(), config)]
+
+
+def certificate_metadata(data, bundle, emails, config):
+    # Every match lies inside a verified trust-anchor subject value: none
+    # remains once those values are blanked, and each is one of theirs.
+    spans = anchor_values(data, bundle)
+    if not spans:
+        return False
+    blanked = bytearray(data)
+    for start, end in spans:
+        blanked[start:end] = b' ' * (end - start)
+    if private_emails(decoded_text(bytes(blanked)), config):
+        return False
+    inside = Counter(match.group() for start, end in spans for match in EMAIL.finditer(decoded_text(data[start:end])))
+    return not Counter(emails) - inside
+
+
+def inspect(data, path, config, resolver):
+    return inspect_text(data, path, config, resolver)
+
+
+def inspect_text(data, path, config, resolver):
+    # NUL removal covers UTF-16/32 ASCII content, matching the secret scanner.
+    text = decoded_text(data)
+    rules = set()
+    if LOCAL_PATH.search(text):
+        rules.add('hygiene.local-path')
+    if any(pattern.search(text) for pattern in config['internalReferencePatterns']):
+        rules.add('hygiene.internal-reference')
+    if '@' in text:
+        emails = private_emails(text, config)
+        bundle = config.get('trustBundles', {}).get(path)
+        if emails and not (bundle and certificate_metadata(data, bundle, emails, config)):
+            rules.add('hygiene.email')
+    ref_text, provenance = provenance_text(text, path, config.get('declaredSources', frozenset()))
+    for repository in references(ref_text, path, config.get('localPaths', frozenset()), config.get('projectIdentity')):
+        # A future source identity does not assert current GitHub visibility.
+        # Explicit release destinations still take the strict visibility path.
+        if (repository in config.get('intendedPublicRepositories', frozenset()) and
+                repository != config.get('pendingDestination')):
+            continue
+        state = resolver.resolve(repository)
+        if state == 'missing' and repository == config.get('pendingDestination'):
+            rules.add(PENDING_DESTINATION)
+        elif state in ('private', 'missing'):
+            rules.add('hygiene.github-' + state)
+        elif state != 'public':
+            rules.add('scan.github-incomplete')
+    return rules, provenance