@mmerterden/multi-agent-pipeline 20.6.0 → 20.7.0

package/pipeline/skills/shared/external/localization-reuse-map/scripts/resolve-legacy-values.py

@@ -1,186 +1,180 @@
 #!/usr/bin/env python3
-"""Resolve LEGACY translation values for a list of keys.
+"""Resolve the legacy translation of each requested key, per language.
 
-PRIMARY source  -  the in-repo legacy snapshot (`--snapshot-root`): one flat
-`<lang>.json` of `{key: value}` per language, refreshed offline by
-`fetch-legacy-labels.py`. No network per run.
-
-`--live` re-reads the project's label endpoint directly, to refresh or to verify the
-snapshot. That endpoint is project-specific, so nothing about it is baked in  -  supply
-it the same way `fetch-legacy-labels.py` takes it:
-
-    resolve-legacy-values.py --keys Continue,Cancel --langs all --live \\
-      --endpoint 'https://labels.example.internal/{env}/labels/{lang}' \\
-      --headers-file .secrets/label-headers.json
-
-Prefer --headers-file (JSON object) over repeated --header for anything secret.
-
-`--prefix` covers backends that store keys under a namespace prefix the app strips
-(e.g. a stored `Mobile-Continue` for the app's `Continue`); pass keys WITHOUT it.
-
-LAST-RESORT offline fallback (`--plist-root`): a legacy iOS app's shipped
-`<lang>.lproj/language.plist`. It is typically a stale subset  -  the snapshot and the
-service are authoritative; a plist hit deserves a note in the map.
-
-Output: `{key: {lang: value|null}}`. Never invent a value  -  `null` is a valid answer.
+Sources, in order of preference: the in-repo flat snapshot
+(<root>/<lang>.json), bundled language.plist files, or the live label
+endpoint. Values are never invented: a key the source lacks comes back null.
+Prints {key: {lang: value|null}} as JSON.
 """
 import argparse
 import json
 import os
+import plistlib
 import sys
 import urllib.request
 
-LANGS_ALL = ["en", "tr", "ar", "de", "es", "fr", "it", "ru"]
+ALL_LANGS = ["en", "tr", "ar", "de", "es", "fr", "it", "ru"]
 
 
-def _largest_str_map(obj):
-    best, stack = {}, [obj]
-    while stack:
-        cur = stack.pop()
-        if isinstance(cur, dict):
-            strs = {k: v for k, v in cur.items() if isinstance(v, str)}
-            if len(strs) > len(best):
-                best = strs
-            stack.extend(cur.values())
-        elif isinstance(cur, list):
-            stack.extend(cur)
-    return best
+def split_csv(value):
+    return [part.strip() for part in value.split(",") if part.strip()]
 
 
-def _parse_headers(a):
-    headers = {"Accept": "application/json"}
-    if a.headers_file:
-        with open(a.headers_file, encoding="utf-8") as fh:
-            loaded = json.load(fh)
-        if not isinstance(loaded, dict):
-            raise SystemExit(f"--headers-file must be a JSON object, got {type(loaded).__name__}")
-        headers.update({str(k): str(v) for k, v in loaded.items()})
-    for pair in a.header or []:
+def parse_langs(value):
+    if value.strip() == "all":
+        return list(ALL_LANGS)
+    return split_csv(value)
+
+
+def parse_pairs(pairs, flag):
+    result = {}
+    for pair in pairs or []:
         if "=" not in pair:
-            raise SystemExit(f"--header expects K=V, got {pair!r}")
-        k, v = pair.split("=", 1)
-        headers[k.strip()] = v.strip()
+            raise SystemExit(f"{flag} expects K=V, got {pair!r}")
+        key, value = pair.split("=", 1)
+        result[key.strip()] = value.strip()
+    return result
+
+
+def build_headers(args):
+    headers = {"Accept": "application/json"}
+    if args.headers_file:
+        with open(args.headers_file, encoding="utf-8") as handle:
+            extra = json.load(handle)
+        if not isinstance(extra, dict):
+            raise SystemExit(f"--headers-file must hold a JSON object: {args.headers_file}")
+        headers.update({str(k): str(v) for k, v in extra.items()})
+    headers.update(parse_pairs(args.header, "--header"))
     return headers
 
 
-def _parse_fail_statuses(values):
-    out = {}
-    for pair in values or []:
-        if "=" not in pair:
-            raise SystemExit(f"--fail-status expects CODE=message, got {pair!r}")
-        code, message = pair.split("=", 1)
-        out[code.strip()] = message.strip()
-    return out
+def largest_string_map(data):
+    best = {}
+    stack = [data]
+    while stack:
+        node = stack.pop()
+        if isinstance(node, dict):
+            if node and all(isinstance(k, str) and isinstance(v, str) for k, v in node.items()):
+                if len(node) > len(best):
+                    best = node
+            stack.extend(node.values())
+        elif isinstance(node, list):
+            stack.extend(node)
+    return best
 
 
-def fetch(lang, a):
-    if not a.endpoint:
-        raise RuntimeError("--live needs --endpoint (no label endpoint is built in)")
-    url = a.endpoint.format(env=a.env, lang=lang)
-    headers = _parse_headers(a)
-    headers.setdefault("Accept-Language", lang)
-    req = urllib.request.Request(url, headers=headers)
-    with urllib.request.urlopen(req, timeout=a.timeout) as r:
-        data = json.loads(r.read().decode("utf-8"))
-    fail_statuses = _parse_fail_statuses(a.fail_status)
-    if isinstance(data, dict) and a.status_field in data:
-        code = str(data.get(a.status_field))
-        if code in fail_statuses:
-            raise RuntimeError(f"{url}: {fail_statuses[code]} (status {code})")
-    m = _largest_str_map(data)
-    if not m:
-        raise RuntimeError(f"no label map found in the response for '{lang}' ({url})")
-    return m
-
-
-def resolve_api(keys, langs, a):
-    out = {k: {} for k in keys}
+def fetch_labels(endpoint, lang, env, headers, status_field, fail_status, timeout):
+    url = endpoint.format(lang=lang, env=env)
+    request_headers = dict(headers)
+    request_headers.setdefault("Accept-Language", lang)
+    request = urllib.request.Request(url, headers=request_headers)
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        data = json.loads(response.read().decode("utf-8"))
+    if isinstance(data, dict) and status_field in data:
+        code = str(data[status_field])
+        if code in fail_status:
+            raise RuntimeError(f"{url}: {fail_status[code]} (status {code})")
+    labels = largest_string_map(data)
+    if not labels:
+        raise RuntimeError(f"the response for '{lang}' carried no label map ({url})")
+    return labels
+
+
+def lookup(table, key, prefix):
+    if prefix and prefix + key in table:
+        return table[prefix + key]
+    return table.get(key)
+
+
+def from_snapshot(root, keys, langs, prefix):
+    result = {key: {} for key in keys}
     for lang in langs:
-        m = fetch(lang, a)
-        for k in keys:
-            out[k][lang] = m.get(a.prefix + k, m.get(k))
-    return out
-
-
-def resolve_snapshot(keys, langs, root, prefix):
-    """Read the in-repo legacy snapshot (<root>/<lang>.json, flat {key: value})  -  
-    offline, no network. Refresh it with fetch-legacy-labels.py."""
-    maps = {}
-    for l in langs:
-        p = os.path.join(root, f"{l}.json")
-        if os.path.isfile(p):
-            with open(p, encoding="utf-8") as fh:
-                maps[l] = json.load(fh)
+        path = os.path.join(root, f"{lang}.json")
+        table = {}
+        if os.path.isfile(path):
+            with open(path, encoding="utf-8") as handle:
+                table = json.load(handle)
         else:
-            sys.stderr.write(f"# no legacy snapshot for '{l}' under {root}\n")
-    return {k: {l: maps.get(l, {}).get(prefix + k, maps.get(l, {}).get(k)) for l in langs} for k in keys}
-
-
-def resolve_plist(keys, langs, root, prefix):
-    import plistlib
-    pl = {}
-    for l in langs:
-        for cand in (os.path.join(root, f"{l}.lproj", "language.plist"), os.path.join(root, f"{l}.plist")):
-            if os.path.isfile(cand):
-                with open(cand, "rb") as fh:
-                    pl[l] = plistlib.load(fh)
-                break
+            print(f"# no snapshot file for '{lang}': {path}", file=sys.stderr)
+        for key in keys:
+            result[key][lang] = lookup(table, key, prefix)
+    return result
+
+
+def from_plist(root, keys, langs, prefix):
+    result = {key: {} for key in keys}
+    for lang in langs:
+        table = {}
+        candidates = [os.path.join(root, f"{lang}.lproj", "language.plist"), os.path.join(root, f"{lang}.plist")]
+        found = next((p for p in candidates if os.path.isfile(p)), None)
+        if found:
+            with open(found, "rb") as handle:
+                table = plistlib.load(handle)
         else:
-            sys.stderr.write(f"# no plist for '{l}' under {root}\n")
-    return {k: {l: pl.get(l, {}).get(prefix + k, pl.get(l, {}).get(k)) for l in langs} for k in keys}
+            print(f"# no plist for '{lang}' under {root}", file=sys.stderr)
+        for key in keys:
+            result[key][lang] = lookup(table, key, prefix)
+    return result
+
+
+def from_live(args, keys, langs):
+    if not args.endpoint:
+        raise RuntimeError("--live needs --endpoint (no label endpoint is built in)")
+    headers = build_headers(args)
+    fail_status = parse_pairs(args.fail_status, "--fail-status")
+    result = {key: {} for key in keys}
+    for lang in langs:
+        table = fetch_labels(args.endpoint, lang, args.env, headers, args.status_field, fail_status, args.timeout)
+        for key in keys:
+            result[key][lang] = lookup(table, key, args.prefix)
+    return result
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__,
-                                formatter_class=argparse.RawDescriptionHelpFormatter)
-    ap.add_argument("--keys", required=True,
-                    help="comma-separated legacy keys, WITHOUT the --prefix")
-    ap.add_argument("--langs", default="en,tr", help="comma-separated langs, or 'all'")
-    ap.add_argument("--snapshot-root", help="PRIMARY: in-repo legacy snapshot dir  -  offline, no network")
-    ap.add_argument("--live", action="store_true",
-                    help="bypass the snapshot and read --endpoint live (to refresh / verify)")
-    ap.add_argument("--endpoint", help="URL template for the legacy label map; may contain {lang} and {env}")
-    ap.add_argument("--header", action="append",
-                    help="extra request header as K=V (repeatable); avoid for secrets")
-    ap.add_argument("--headers-file", help="JSON object of request headers  -  use this for tokens")
-    ap.add_argument("--env", default="", help="value substituted for {env} in --endpoint")
-    ap.add_argument("--status-field", default="statusCode",
-                    help="response field carrying a provider status code")
-    ap.add_argument("--fail-status", action="append",
-                    help="CODE=message for a provider error code that must abort (repeatable)")
-    ap.add_argument("--timeout", type=int, default=30)
-    ap.add_argument("--plist-root", help="last-resort offline fallback: dir with <lang>.lproj/language.plist")
-    ap.add_argument("--prefix", default="", help="prefix the backend stores keys under (default none)")
-    a = ap.parse_args()
-
-    langs = LANGS_ALL if a.langs.strip() == "all" else [l.strip() for l in a.langs.split(",") if l.strip()]
-    keys = [k.strip() for k in a.keys.split(",") if k.strip()]
-
-    # Preference: in-repo snapshot (offline) → live endpoint → plist.
-    if a.snapshot_root and not a.live:
-        out = resolve_snapshot(keys, langs, a.snapshot_root, a.prefix)
-    elif a.plist_root and not a.live and not a.snapshot_root:
-        sys.stderr.write("# OFFLINE plist fallback  -  the snapshot/service are the source of truth.\n")
-        out = resolve_plist(keys, langs, a.plist_root, a.prefix)
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("--keys", required=True, help="legacy keys separated by commas; leave off the backend prefix")
+    parser.add_argument("--langs", default="en,tr", help="comma list or 'all'")
+    parser.add_argument("--snapshot-root", help="directory holding <lang>.json flat snapshots")
+    parser.add_argument("--live", action="store_true", help="query the label endpoint instead of the snapshot")
+    parser.add_argument("--endpoint", help="URL template with {lang} and optional {env}")
+    parser.add_argument("--header", action="append", help="extra request header K=V (repeatable)")
+    parser.add_argument("--headers-file", help="JSON object of request headers; keeps secrets off argv")
+    parser.add_argument("--env", default="", help="value substituted for {env}")
+    parser.add_argument("--status-field", default="statusCode", help="response field carrying a status code")
+    parser.add_argument("--fail-status", action="append", help="CODE=message treated as a failure (repeatable)")
+    parser.add_argument("--timeout", type=int, default=30)
+    parser.add_argument("--plist-root", help="last resort: directory of bundled <lang>.lproj/language.plist")
+    parser.add_argument("--prefix", default="", help="backend key prefix the app strips, e.g. Mobile-")
+    args = parser.parse_args()
+
+    keys = split_csv(args.keys)
+    langs = parse_langs(args.langs)
+
+    if args.snapshot_root and not args.live:
+        result = from_snapshot(args.snapshot_root, keys, langs, args.prefix)
+    elif args.plist_root and not args.live:
+        print("# reading bundled plists: a stale subset; trust the snapshot and the service over them", file=sys.stderr)
+        result = from_plist(args.plist_root, keys, langs, args.prefix)
     else:
         try:
-            out = resolve_api(keys, langs, a)
+            result = from_live(args, keys, langs)
         except Exception as exc:
-            sys.stderr.write(f"# live label fetch failed ({exc}).\n")
-            if a.snapshot_root:
-                sys.stderr.write("# falling back to --snapshot-root.\n")
-                out = resolve_snapshot(keys, langs, a.snapshot_root, a.prefix)
-            elif a.plist_root:
-                sys.stderr.write("# falling back to --plist-root.\n")
-                out = resolve_plist(keys, langs, a.plist_root, a.prefix)
+            print(f"# live label fetch failed ({exc})", file=sys.stderr)
+            if args.snapshot_root:
+                result = from_snapshot(args.snapshot_root, keys, langs, args.prefix)
+            elif args.plist_root:
+                result = from_plist(args.plist_root, keys, langs, args.prefix)
             else:
                 raise
 
-    json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
+    json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
     sys.stdout.write("\n")
-    absent = [k for k, v in out.items() if not any(v.values())]
-    if absent:
-        sys.stderr.write(f"\n# {len(absent)} key(s) with no value: " + ", ".join(absent) + "\n")
+
+    empty = [key for key, values in result.items() if not any(values.values())]
+    if empty:
+        print(f"# {len(empty)} key(s) with no legacy value in any requested language:", file=sys.stderr)
+        for key in empty:
+            print(f"#   {key}", file=sys.stderr)
 
 
 if __name__ == "__main__":

package/pipeline/skills/shared/external/localization-reuse-map/scripts/resolve-new-values.py

@@ -1,170 +1,152 @@
 #!/usr/bin/env python3
-"""Bulk-resolve the redesign (new) translation values for a list of localization keys.
-
-Reads the per-key authored source under
-`<resources>/Resources/Localization/LocalizationStrings/Sources/Suggested/<Key>.json`
-(SSOT in the resources repo) and prints `{key: {lang: value|null}}`.
-
-Why a script: the model otherwise hand-copies 8 languages x N keys out of JSON
-files  -  slow, token-heavy, and error-prone. This is pure file IO, so it is a
-script. Read-only; touches nothing.
-
-Key-form handling: code often references a key as `AddAddress.continueButton`
-(camelCase leaf) while the Suggested filename PascalCases every dotted segment
-(`AddAddress.ContinueButton.json`). We normalise the first character of
-each segment to upper-case before resolving, so either form works as input.
-Accessibility keys live under `AccessibilityStrings/Sources/Suggested/`  -  pass
-`--domain accessibility` for those.
-
-`--catalog <file>`: the SHIPPED string catalog, checked whenever a key has no Suggested
-file. Pass it. A missing Suggested file means "not in this snapshot", NOT "this key is
-unauthored"  -  the snapshot is a generated mirror and goes stale the moment a key is added
-upstream. Concluding "unauthored" from the snapshot alone has already produced a batch of
-pointless authoring requests for keys that were shipping in all eight languages. With
-`--catalog`, each key reports where its values came from (`suggested` / `catalog`), and
-only keys absent from BOTH are reported as genuinely unauthored.
-
-Accepts an Apple `.xcstrings` (`{"strings": {key: {"localizations": {lang: {"stringUnit":
-{"value": ...}}}}}}`) or a flat `{key: {lang: value}}` map.
+"""Look up the redesign copy of each given key, one language map per key.
+
+The primary source is the Suggested/<Key>.json file of each key, found in a
+resources checkout or a snapshot of it. A key missing there can still be
+answered by a string catalog the app ships (.xcstrings or a flat JSON map).
+Nothing is modified; the JSON result goes to stdout.
 """
 import argparse
 import json
 import os
 import sys
 
-DOMAIN_DIR = {
-    "localization": "LocalizationStrings",
-    "accessibility": "AccessibilityStrings",
+ALL_LANGS = ["en", "tr", "ar"] + sorted(["ru", "it", "fr", "es", "de"])
+
+DOMAIN_DIRS = {
+    "localization": ("Suggested", "LocalizationStrings"),
+    "accessibility": ("AccessibilitySuggested", "AccessibilityStrings"),
 }
 
 
-def normalise(key: str) -> str:
-    """PascalCase the first char of every dotted segment (file naming convention)."""
-    return ".".join(s[:1].upper() + s[1:] if s else s for s in key.split("."))
+def parse_langs(value):
+    if value.strip() == "all":
+        return list(ALL_LANGS)
+    return [part.strip() for part in value.split(",") if part.strip()]
+
+
+def normalize_key(key):
+    return ".".join(seg[:1].upper() + seg[1:] for seg in key.split("."))
+
+
+def read_keys(opts):
+    raw = [piece.strip() for piece in opts.keys.split(",")] if opts.keys else []
+    if opts.keys_file:
+        source = open(opts.keys_file, encoding="utf-8") if opts.keys_file != "-" else sys.stdin
+        with source:
+            raw += [line.strip() for line in source]
+    return list(dict.fromkeys(key for key in raw if key))
 
 
-SNAPSHOT_SUBDIR = {"localization": "Suggested", "accessibility": "AccessibilitySuggested"}
+def suggested_dir(opts):
+    if opts.suggested_dir:
+        return opts.suggested_dir
+    snapshot_name, source_name = DOMAIN_DIRS[opts.domain]
+    root = opts.resources_root
+    snapshot = os.path.join(root, "Localization", snapshot_name)
+    if os.path.isdir(snapshot):
+        return snapshot
+    return os.path.join(root, "Resources", "Localization", source_name, "Sources", "Suggested")
 
 
-def suggested_dir(resources_root: str, domain: str) -> str:
-    # In-repo snapshot layout first (specs/resources/Localization/Suggested)  -  single-repo, offline;
-    # else the full the resources repo layout.
-    snap = os.path.join(resources_root, "Localization", SNAPSHOT_SUBDIR[domain])
-    if os.path.isdir(snap):
-        return snap
-    return os.path.join(
-        resources_root, "Resources", "Localization",
-        DOMAIN_DIR[domain], "Sources", "Suggested",
-    )
+def read_json(path):
+    with open(path, encoding="utf-8") as stream:
+        return json.load(stream)
 
 
-def resolve(key: str, sug_dir: str, langs):
-    path = os.path.join(sug_dir, normalise(key) + ".json")
-    if not os.path.isfile(path):
-        return None  # absent from THIS snapshot  -  see load_catalog before concluding
-    with open(path, encoding="utf-8") as fh:
-        data = json.load(fh)
-    out = {}
-    for lang in langs:
-        entry = data.get(lang)
-        out[lang] = entry.get("value") if isinstance(entry, dict) else None
-    return out
+def xcstrings_values(entry):
+    found = {}
+    for lang, localization in ((entry or {}).get("localizations") or {}).items():
+        unit = (localization or {}).get("stringUnit") or {}
+        if "value" in unit:
+            found[lang] = unit["value"]
+    return found
 
 
 def load_catalog(path):
-    """{key: {lang: value}} from an .xcstrings or an already-flat catalog."""
-    if not path:
+    data = read_json(path)
+    if not isinstance(data, dict):
         return {}
-    with open(path, encoding="utf-8") as fh:
-        raw = json.load(fh)
-    strings = raw.get("strings") if isinstance(raw, dict) else None
-    if not isinstance(strings, dict):
-        return raw if isinstance(raw, dict) else {}
-    out = {}
-    for key, entry in strings.items():
-        locs = (entry or {}).get("localizations") or {}
-        out[key] = {lang: ((v or {}).get("stringUnit") or {}).get("value")
-                    for lang, v in locs.items()}
-    return out
-
-
-def resolve_from_catalog(key, catalog, langs):
-    for cand in (key, normalise(key)):
-        vals = catalog.get(cand)
-        if vals:
-            return {lang: vals.get(lang) for lang in langs}
-    return None
+    strings = data.get("strings")
+    if isinstance(strings, dict):
+        return {key: xcstrings_values(entry) for key, entry in strings.items()}
+    return data
+
+
+def read_suggested(path, langs):
+    data = read_json(path)
+    per_lang = data if isinstance(data, dict) else {}
+
+    def value_of(lang):
+        block = per_lang.get(lang)
+        return block.get("value") if isinstance(block, dict) else None
+
+    return {lang: value_of(lang) for lang in langs}
+
+
+def from_catalog(catalog, key, langs):
+    entry = catalog.get(key)
+    if entry is None:
+        entry = catalog.get(normalize_key(key))
+    if not isinstance(entry, dict):
+        return None
+    return {lang: entry.get(lang) for lang in langs}
 
 
 def main():
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--keys", help="comma-separated keys (code- or file-form)")
-    ap.add_argument("--keys-file", help="file with one key per line (- for stdin)")
-    ap.add_argument("--resources-root",
-                    help="resources checkout OR the in-repo snapshot root (specs/resources)")
-    ap.add_argument("--suggested-dir", help="explicit Suggested dir (overrides --resources-root detection)")
-    ap.add_argument("--domain", choices=list(DOMAIN_DIR), default="localization")
-    ap.add_argument("--catalog", help="shipped string catalog (.xcstrings or flat JSON) used "
-                                     "whenever a key has no Suggested file  -  pass it, or a "
-                                     "stale snapshot reads as 'unauthored'")
-    ap.add_argument("--report-source", action="store_true",
-                    help="emit {key: {source, values}} instead of {key: values}")
-    ap.add_argument("--langs", default="en,tr",
-                    help="comma-separated langs, or 'all' (ar,de,en,es,fr,it,ru,tr)")
-    args = ap.parse_args()
-
-    if args.langs.strip() == "all":
-        langs = ["ar", "de", "en", "es", "fr", "it", "ru", "tr"]
-    else:
-        langs = [l.strip() for l in args.langs.split(",") if l.strip()]
-
-    keys = []
-    if args.keys:
-        keys += [k.strip() for k in args.keys.split(",") if k.strip()]
-    if args.keys_file:
-        src = sys.stdin if args.keys_file == "-" else open(args.keys_file, encoding="utf-8")
-        keys += [ln.strip() for ln in src if ln.strip()]
+    cli = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    cli.add_argument("--keys", help="keys separated by commas, in code form or file form")
+    cli.add_argument("--keys-file", help="one key per line; use - to read stdin")
+    cli.add_argument("--resources-root", help="root of the resources checkout or of its snapshot")
+    cli.add_argument("--suggested-dir", help="use this Suggested folder instead of looking for one")
+    cli.add_argument("--domain", default="localization", choices=sorted(DOMAIN_DIRS))
+    cli.add_argument("--catalog", help="string catalog the app ships (.xcstrings or flat JSON), consulted when a key has no Suggested file")
+    cli.add_argument("--report-source", action="store_true", help="return {source, values} per key instead of the bare values")
+    cli.add_argument("--langs", default="en,tr", help="languages separated by commas, or 'all'")
+    opts = cli.parse_args()
+
+    keys = read_keys(opts)
     if not keys:
-        ap.error("supply --keys and/or --keys-file")
-
-    if args.suggested_dir:
-        sug_dir = args.suggested_dir
-    elif args.resources_root:
-        sug_dir = suggested_dir(args.resources_root, args.domain)
-    else:
-        ap.error("supply --resources-root or --suggested-dir")
-    if not os.path.isdir(sug_dir):
-        ap.error(f"Suggested dir not found: {sug_dir} (is --resources-root / --suggested-dir correct?)")
-
-    catalog = load_catalog(args.catalog)
-    result, source = {}, {}
-    for k in keys:
-        vals = resolve(k, sug_dir, langs)
-        src = "suggested" if vals is not None else None
-        if vals is None and catalog:
-            vals = resolve_from_catalog(k, catalog, langs)
-            src = "catalog" if vals is not None else None
-        result[k] = vals
-        source[k] = src
-
-    if args.report_source:
-        json.dump({k: {"source": source[k], "values": result[k]} for k in keys},
-                  sys.stdout, ensure_ascii=False, indent=2)
-    else:
-        json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+        cli.error("supply --keys and/or --keys-file")
+    if not (opts.resources_root or opts.suggested_dir):
+        cli.error("supply --resources-root or --suggested-dir")
+    directory = suggested_dir(opts)
+    if not os.path.isdir(directory):
+        cli.error(f"no Suggested folder at {directory} (check --resources-root / --suggested-dir / --domain)")
+
+    langs = parse_langs(opts.langs)
+    catalog = load_catalog(opts.catalog) if opts.catalog else None
+
+    result, via_catalog, unresolved = {}, [], []
+    for key in keys:
+        path = os.path.join(directory, normalize_key(key) + ".json")
+        source, values = None, None
+        if os.path.isfile(path):
+            source, values = "suggested", read_suggested(path, langs)
+        elif catalog is not None:
+            values = from_catalog(catalog, key, langs)
+            if values is not None:
+                source = "catalog"
+                via_catalog.append(key)
+        if values is None:
+            unresolved.append(key)
+        result[key] = values if not opts.report_source else {"source": source, "values": values}
+
+    json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
     sys.stdout.write("\n")
 
-    from_catalog = [k for k in keys if source[k] == "catalog"]
-    unauthored = [k for k in keys if source[k] is None]
-    if from_catalog:
-        sys.stderr.write(
-            f"\n# {len(from_catalog)} key(s) resolved from the CATALOG, not the snapshot  -  "
-            "the snapshot is stale, refresh it with snapshot-resources.sh: "
-            + ", ".join(from_catalog) + "\n")
-    if unauthored:
-        label = ("with no authored source" if catalog else
-                 "absent from the snapshot (no --catalog given, so 'unauthored' is UNVERIFIED)")
-        sys.stderr.write(f"\n# {len(unauthored)} key(s) {label}: " + ", ".join(unauthored) + "\n")
+    def listing(header, items):
+        print(f"# {len(items)} key(s) {header}:", file=sys.stderr)
+        for item in items:
+            print(f"#   {item}", file=sys.stderr)
+
+    if via_catalog:
+        listing("came from the catalog because the snapshot lacks them; run snapshot-resources.sh to refresh it", via_catalog)
+    if unresolved:
+        if catalog is None:
+            listing("are not in the snapshot (without --catalog, calling them 'unauthored' is UNVERIFIED)", unresolved)
+        else:
+            listing("have no authored source anywhere", unresolved)
 
 
 if __name__ == "__main__":