feat(hooks): make intake-sweep config bugs visible instead of quiet

hooks/intake-sweep.py

@@ -37,7 +37,9 @@
   INTAKE_SWEEP_STATE_DIR=DIR                      throttle stamp + swept-keys file
   INTAKE_SWEEP_CMD_TIMEOUT=S                      per-command adapter timeout, default 15
 
-Flags: --force (skip throttle; manual runs + tests).
+Flags: --force (skip throttle; manual runs + tests), --check (report what each source
+yields raw, before dedup; run it after editing the config, a typo'd field map or a dead
+path shows up as 0 items instead of failing quiet).
 Stdlib only. Always exits 0 (a sweep never blocks a session).
 """
 import importlib.util
@@ -206,6 +208,14 @@ def sweep(root, sources, sf, state_dir):
         reader = READERS.get(source.get("kind", ""))
         name = source.get("name", "?")
         if reader is None:
+            # An unrecognized `kind` is always a config bug, never a valid state: the
+            # source would be skipped in total silence. Warn on stderr (the hook's stdout
+            # is the surfaced candidate line; stderr never pollutes it).
+            print(
+                f"intake-sweep: source '{name}' has unknown kind "
+                f"'{source.get('kind', '')}' (expected: {'/'.join(sorted(READERS))}), skipped",
+                file=sys.stderr,
+            )
             continue
         n = 0
         for c in reader(source, root):
@@ -258,10 +268,43 @@ def record_swept(state_dir, keys):
         pass
 
 
+def check(root, sources):
+    """Report what each configured source actually yields RAW (before any dedup), so a
+    typo'd field map or a dead path is visible when you add a source. Not wired into any
+    hook: a sweep that finds nothing is a legitimate daily state, so this stays a
+    run-it-yourself verb rather than a warning that would fire every session."""
+    if not sources:
+        print(f"intake-sweep: no sources configured (looked in {root}/_meta/intake-sources.json)")
+        return 0
+    bad = 0
+    for source in sources:
+        if not isinstance(source, dict):
+            print("  ?  (malformed source entry, not an object)")
+            bad += 1
+            continue
+        name, kind = source.get("name", "?"), source.get("kind", "")
+        reader = READERS.get(kind)
+        if reader is None:
+            print(f"  FAIL {name}: unknown kind '{kind}' (expected: {'/'.join(sorted(READERS))})")
+            bad += 1
+            continue
+        items = reader(source, root)
+        titled = sum(1 for i in items if i["title"].strip())
+        urled = sum(1 for i in items if i["url"].strip())
+        status = "ok  " if items else "WARN"
+        if not items:
+            bad += 1
+        print(f"  {status} {name} ({kind}): {len(items)} item(s), {titled} titled, {urled} with url")
+    print(f"intake-sweep check: {len(sources)} source(s), {bad} needing attention")
+    return 0
+
+
 def main():
     force = "--force" in sys.argv[1:]
     root = _repo_root()
     sources = load_config(root)
+    if "--check" in sys.argv[1:]:
+        return check(root, sources)
     if not sources:
         return 0  # no consumer config -> silent no-op
 

tests/test-intake-sweep.sh

@@ -105,6 +105,35 @@ S3="$R3/_meta/backlog-staging.md"
 assert_true "first run staged inside the interval" "$(grep -q 'First item' "$S3"; echo $?)"
 assert_true "NC: second unforced run throttled" "$(! grep -q 'Second item' "$S3"; echo $?)"
 
+echo "== config bugs are loud, not quiet: unknown kind warns; --check reports raw yield =="
+R5="$(mkrepo)"
+printf '{"url": "https://example.com/a", "title": "Item A", "verdict": "keep"}\n' > "$R5/ledger.jsonl"
+cat > "$R5/_meta/intake-sources.json" <<'EOF'
+{"sources": [
+  {"name": "good", "kind": "jsonl", "path": "ledger.jsonl",
+   "include": {"field": "verdict", "equals": "keep"},
+   "map": {"title": "title", "url": "url"}},
+  {"name": "typo-kind", "kind": "jsonlines", "path": "ledger.jsonl",
+   "map": {"title": "title", "url": "url"}},
+  {"name": "dead-path", "kind": "jsonl", "path": "no-such-file.jsonl",
+   "map": {"title": "title", "url": "url"}}
+]}
+EOF
+err="$(REPO_ROOT="$R5" INTAKE_SWEEP_STATE_DIR="$R5/state" python3 "$SWEEP" --force 2>&1 >/dev/null)"
+assert_true "unknown kind warns on stderr" "$(echo "$err" | grep -q "typo-kind.*unknown kind 'jsonlines'"; echo $?)"
+assert_true "the good source still stages despite a broken sibling" \
+  "$(grep -q 'Item A' "$R5/_meta/backlog-staging.md"; echo $?)"
+out="$(REPO_ROOT="$R5" INTAKE_SWEEP_STATE_DIR="$R5/state" python3 "$SWEEP" --check 2>&1)"; rc=$?
+assert_true "--check exits 0" "$rc"
+assert_true "--check reports the good source's raw yield" "$(echo "$out" | grep -qE 'ok +good \(jsonl\): 1 item'; echo $?)"
+assert_true "--check FAILs the unknown kind" "$(echo "$out" | grep -q 'FAIL typo-kind'; echo $?)"
+assert_true "--check WARNs the dead path (0 items)" "$(echo "$out" | grep -q 'WARN dead-path'; echo $?)"
+assert_true "--check counts what needs attention" "$(echo "$out" | grep -q '3 source(s), 2 needing attention'; echo $?)"
+assert_true "NC: --check stages nothing (report-only)" \
+  "$(! grep -q 'dead-path\|typo-kind' "$R5/_meta/backlog-staging.md"; echo $?)"
+out="$(REPO_ROOT="$R2" INTAKE_SWEEP_STATE_DIR="$R2/state" python3 "$SWEEP" --check 2>&1)"
+assert_true "--check says so when no sources are configured" "$(echo "$out" | grep -q 'no sources configured'; echo $?)"
+
 echo "== surface wiring: backlog-stage.sh --surface runs the sweep then surfaces =="
 R4="$(mkrepo)"
 printf '{"url": "https://example.com/via-surface", "title": "Via surface", "verdict": "keep"}\n' > "$R4/ledger.jsonl"