fix(io-boundaries): distinguish "no I/O" from "language unsupported" (INV-javam)

UAT-2026-04-13 DQ-03 + DQ-04 flagged the silent-failure class:
`hypergumbo io-boundaries` on a codebase containing a language
with no I/O primitive catalog returned zero boundaries with no
warning. Output identical to a genuinely I/O-free codebase, and
downstream taint-flow trivially passed every claim (false
security confidence).

Even as organic catalog expansion lands (WI-banaf TypeScript,
WI-vibur Elixir, WI-sakan Java, WI-rujos Kotlin), the invariant
has to hold independently: hypergumbo will always have some
language with no catalog, and "zero" must never silently mean
"we didn't look."

The fix is narrow:

1. IoBoundaryCatalog gains an `is_supported: bool` field. Default
   True. `load_catalog()` sets it to False when no YAML file
   (and no alias / parent) resolves.

2. New `io_boundary.is_language_supported(lang)` helper exposes
   the flag to callers without materializing the full catalog.

3. `cmd_io_boundaries` tracks unsupported languages separately
   from supported-but-zero-matches languages and:
   - Prints a stderr notice ("no I/O primitive catalog for
     language(s): X, Y. Zero boundaries reported for these
     languages does NOT mean the code is I/O-free — INV-javam")
     so humans aren't misled.
   - Adds `unsupported_languages: [...]` to the JSON output
     (stable schema — always present, empty list when every
     detected language is supported) so programmatic consumers
     like taint-flow can refuse to assert success on unsupported
     code.

Taint-flow consumption of this signal is deferred to a sibling
PR. The current change delivers the io-boundaries side, which is
what every downstream checker needs anyway.

9 new tests:
- Catalog-level: nonexistent language returns is_supported=False,
  supported languages return True, aliased languages (typescript,
  cpp) inherit True from their alias target, parent-inherited
  languages (scala, kotlin, elixir) return True, and the
  module-level helper mirrors the flag.
- cmd-level: the stderr notice fires for a brainfuck-language
  node, does NOT fire on a python-only codebase, the JSON output
  surfaces `unsupported_languages: ["brainfuck", "nim"]`, and
  emits `unsupported_languages: []` when every language is
  supported (stable schema guard).

Tracker: moved INV-javam from `violated` to `pending_validation`
— bakeoff will confirm the notice fires on real unsupported
repos (TypeScript/Nim/Solidity/Elixir) and doesn't on
fully-supported ones.

Signed-off-by: jgstern-agent <josh-agent@iterabloom.com>

Author: jgstern-agent

.ci/affected-tests.txt

@@ -1,8 +1,8 @@
 # Test selection manifest
-# Generated by smart-test at 2026-04-15T09:17:20-04:00
+# Generated by smart-test at 2026-04-15T09:45:01-04:00
 # Mode: targeted
 # Baseline: 02dba9744d2c86e26f06565aad4ebcae7ef0f4a8
-# Changed files: 35
+# Changed files: 37
 # Changed source files: 7
 # Selected tests: 66
 #

CHANGELOG.md

@@ -23,6 +23,7 @@ This changelog tracks the **tool version** (package releases). The **schema vers
 
 ### Fixed
 
+- **io-boundaries distinguishes "no I/O detected" from "language unsupported"** (INV-javam / UAT DQ-03+DQ-04): previously, `hypergumbo io-boundaries` on a codebase containing an unsupported language (pre-banaf TypeScript, pre-vibur Elixir, pre-rujos Kotlin, Solidity, Nim, ...) returned zero boundaries with no warning — output identical to a genuinely I/O-free codebase, and downstream taint-flow assertions trivially passed with false security confidence. `IoBoundaryCatalog` now carries an `is_supported: bool` field (False when no YAML / alias / parent resolves), `io_boundary.is_language_supported(lang)` exposes this to callers, `cmd_io_boundaries` emits a stderr notice ("no I/O primitive catalog for language(s): X, Y. Zero boundaries reported for these languages does NOT mean the code is I/O-free — INV-javam"), and the JSON output includes a stable `unsupported_languages: []` field so programmatic consumers can detect the condition. Complements the organic catalog expansion in WI-banaf/sakan/rujos/vibur: even after coverage grows, some languages will always lack catalogs and the invariant needs to hold.
 - **Laravel `apiResource()` no longer emits phantom HTML-form routes; `.except()` / `.only()` honored** (WI-jorim / UAT BUG-07): `Route::apiResource('posts', PostController::class)` now produces 5 routes (index/store/show/update/destroy) instead of 7 — the `GET /create` and `GET /{id}/edit` HTML-form routes that don't exist for an API resource are dropped. Chained `.except([...])` / `.only([...])` modifiers (variadic strings or array literal) are now parsed and applied to both `resource` and `apiResource`. Multiple modifiers compose in source-order. Variable args (e.g. `->except($actions)`) and unrelated chained methods (e.g. `->name(...)`, `->middleware(...)`) are correctly ignored. On koel: ~40 phantom routes were eliminated (~19% of the 207 originally reported). New constant `LARAVEL_RESOURCE_ACTIONS` and `LARAVEL_API_RESOURCE_EXCLUDED_ACTIONS` make the action set self-documenting.
 - **Subcommand parser cleanup** (WI-balij / UAT UX-03 + UX-04): two argparse plumbing rough edges.
   - `hypergumbo foobar` no longer silently inserts `sketch` and reports `path does not exist`. The dispatch in `main()` now detects when the first positional looks like a subcommand attempt (no path separators, no leading `.`/`~`, doesn't exist on disk) and prints `'foobar' is not a valid subcommand` plus a `Did you mean: ...` line via `difflib.get_close_matches`. Exits 2.

packages/hypergumbo-core/src/hypergumbo_core/cli.py

@@ -2925,9 +2925,17 @@ class _Edge:
             languages.add(lang)
 
     # Load catalogs for detected languages
+    # INV-javam: track unsupported languages (no catalog) separately from
+    # supported-but-zero-matches languages. The former must be surfaced
+    # to callers so "zero I/O detected" isn't silently indistinguishable
+    # from "language has no catalog at all".
     catalogs = {}
-    for lang in languages:
+    unsupported_languages: list[str] = []
+    for lang in sorted(languages):
         catalog = load_catalog(lang)
+        if not catalog.is_supported:
+            unsupported_languages.append(lang)
+            continue
         if catalog.primitives:
             catalogs[lang] = catalog
             # Also key by the catalog's base language so edge-prefix lookups
@@ -3002,15 +3010,44 @@ def _is_test_chain(chain: Any) -> bool:
             }
         else:
             output = bmap.to_dict()
+        # INV-javam: expose unsupported-language signal to programmatic
+        # consumers. Empty list when every detected language has a catalog.
+        output["unsupported_languages"] = unsupported_languages
         print(json.dumps(output, indent=2, sort_keys=True))
     elif getattr(args, "by_file", False):
         _print_io_boundaries_by_file(filtered_entries, nodes_by_id, repo_root)
+        _print_unsupported_languages_notice(unsupported_languages)
     else:
         _print_io_boundaries_by_type(filtered_entries, nodes_by_id, bmap, repo_root)
+        _print_unsupported_languages_notice(unsupported_languages)
 
     return 0
 
 
+def _print_unsupported_languages_notice(
+    unsupported_languages: list[str],
+) -> None:
+    """INV-javam: emit an explicit notice when the repo contains languages
+    with no I/O primitive catalog.
+
+    Without this, the human-readable output for an unsupported language
+    is indistinguishable from a genuinely I/O-free codebase — and
+    downstream taint-flow trivially passes every claim on those
+    languages (false security confidence). The notice runs to stderr so
+    piping the boundary report to a file / grep / jq is unaffected.
+    """
+    if not unsupported_languages:
+        return
+    langs = ", ".join(unsupported_languages)
+    print(
+        f"\nNote: no I/O primitive catalog for language(s): {langs}. "
+        "Zero boundaries reported for these languages does NOT mean "
+        "the code is I/O-free — it means hypergumbo cannot detect I/O "
+        "for this language yet. (INV-javam)",
+        file=sys.stderr,
+    )
+
+
 def _format_io_caller(
     symbol_id: str,
     nodes_by_id: Dict[str, Any],

packages/hypergumbo-core/src/hypergumbo_core/io_boundary.py

@@ -120,6 +120,13 @@ class IoBoundaryCatalog:
     language: str
     primitives: list[IoPrimitive] = field(default_factory=list)
     ambiguous_names: frozenset[str] = field(default_factory=frozenset)
+    # INV-javam: True when a YAML catalog (or alias/parent) was loaded
+    # for this language. False when no catalog exists — this is the
+    # signal callers (io-boundaries, taint-flow) use to distinguish
+    # "found zero I/O" from "language unsupported". Silent zeros are
+    # the class of bug the invariant guards against: output identical
+    # to a clean codebase, plus false security confidence in taint-flow.
+    is_supported: bool = True
     _by_qualified: dict[str, IoPrimitive] = field(
         default_factory=dict, repr=False,
     )
@@ -321,6 +328,14 @@ def _from_dict(cls, data: dict) -> IoBoundaryCatalog:
 }
 
 
+def is_language_supported(language: str) -> bool:
+    """True if ``language`` has an I/O primitive catalog (directly, via
+    alias, or with a parent). Callers use this to distinguish "found
+    zero I/O" from "language unsupported" — the INV-javam invariant.
+    """
+    return load_catalog(language).is_supported
+
+
 def load_catalog(language: str) -> IoBoundaryCatalog:
     """Load the I/O primitive catalog for a language.
 
@@ -337,7 +352,10 @@ def load_catalog(language: str) -> IoBoundaryCatalog:
         if alias:
             path = _CATALOG_DIR / f"{alias}.yaml"
     if not path.exists():
-        return IoBoundaryCatalog(language=language)
+        # INV-javam: no catalog file (and no alias resolving to one) —
+        # callers use is_supported to emit explicit "language
+        # unsupported" output instead of silently returning zero I/O.
+        return IoBoundaryCatalog(language=language, is_supported=False)
     catalog = IoBoundaryCatalog.from_yaml(path)
 
     # Merge parent catalog if defined (e.g. scala inherits java entries)

packages/hypergumbo-core/tests/test_cli_io_boundaries.py

@@ -961,3 +961,134 @@ def test_test_chains_excluded_by_default(self, tmp_path, capsys):
         )
         chains = data["boundaries"]["fs_write"]["chains"]
         assert "test" not in chains[0]["io_edge_src"]
+
+
+# ============================================================================
+# INV-javam: distinguish "no I/O detected" from "language unsupported"
+# ============================================================================
+
+
+def test_cmd_io_boundaries_emits_notice_for_unsupported_language(
+    tmp_path: Path, capsys,
+) -> None:
+    """INV-javam: when the behavior map contains nodes in a language with
+    no IO primitive catalog, io-boundaries prints an explicit unsupported-
+    language notice to stderr. Without this, zero boundaries is
+    indistinguishable from a truly I/O-free codebase.
+    """
+    # A node in a language ("brainfuck") hypergumbo has no catalog for.
+    bmap = _make_behavior_map(
+        nodes=[
+            {
+                "id": "brainfuck:main.bf:1-3:main:function",
+                "name": "main",
+                "kind": "function",
+                "language": "brainfuck",
+                "path": "main.bf",
+                "span": {"start_line": 1, "end_line": 3},
+            },
+        ],
+        edges=[],
+    )
+    args = _make_args(tmp_path, bmap)
+    rc = cmd_io_boundaries(args)
+    assert rc == 0
+
+    _, err = capsys.readouterr()
+    assert "brainfuck" in err
+    assert "no I/O primitive catalog" in err
+    assert "does NOT mean" in err  # the key "don't misread zero" framing
+    assert "INV-javam" in err
+
+
+def test_cmd_io_boundaries_json_output_exposes_unsupported_languages(
+    tmp_path: Path, capsys,
+) -> None:
+    """INV-javam: JSON consumers get an `unsupported_languages` field so
+    programmatic pipelines (e.g., taint-flow) can refuse to assert
+    success when the language isn't actually supported.
+    """
+    bmap = _make_behavior_map(
+        nodes=[
+            {
+                "id": "brainfuck:main.bf:1-3:main:function",
+                "name": "main",
+                "kind": "function",
+                "language": "brainfuck",
+                "path": "main.bf",
+                "span": {"start_line": 1, "end_line": 3},
+            },
+            {
+                "id": "nim:src/thing.nim:1-5:main:function",
+                "name": "main",
+                "kind": "function",
+                "language": "nim",
+                "path": "src/thing.nim",
+                "span": {"start_line": 1, "end_line": 5},
+            },
+        ],
+        edges=[],
+    )
+    args = _make_args(tmp_path, bmap, json_output=True)
+    rc = cmd_io_boundaries(args)
+    assert rc == 0
+
+    data = json.loads(capsys.readouterr().out)
+    assert "unsupported_languages" in data
+    # Both languages have no catalog; list is sorted alphabetically
+    assert data["unsupported_languages"] == ["brainfuck", "nim"]
+
+
+def test_cmd_io_boundaries_no_notice_when_all_languages_supported(
+    tmp_path: Path, capsys,
+) -> None:
+    """INV-javam: the notice must NOT fire when every detected language
+    has a catalog. Anti-regression — we don't want to spam users on
+    fully-supported codebases.
+    """
+    bmap = _make_behavior_map(
+        nodes=[
+            {
+                "id": "python:src/api.py:1-5:main:function",
+                "name": "main",
+                "kind": "function",
+                "language": "python",
+                "path": "src/api.py",
+                "span": {"start_line": 1, "end_line": 5},
+            },
+        ],
+        edges=[],
+    )
+    args = _make_args(tmp_path, bmap)
+    rc = cmd_io_boundaries(args)
+    assert rc == 0
+
+    _, err = capsys.readouterr()
+    assert "no I/O primitive catalog" not in err
+    assert "INV-javam" not in err
+
+
+def test_cmd_io_boundaries_json_output_empty_unsupported_when_all_supported(
+    tmp_path: Path, capsys,
+) -> None:
+    """INV-javam: programmatic consumers always get the field, even when
+    empty — keeps the JSON schema stable."""
+    bmap = _make_behavior_map(
+        nodes=[
+            {
+                "id": "python:src/api.py:1-5:main:function",
+                "name": "main",
+                "kind": "function",
+                "language": "python",
+                "path": "src/api.py",
+                "span": {"start_line": 1, "end_line": 5},
+            },
+        ],
+        edges=[],
+    )
+    args = _make_args(tmp_path, bmap, json_output=True)
+    rc = cmd_io_boundaries(args)
+    assert rc == 0
+
+    data = json.loads(capsys.readouterr().out)
+    assert data["unsupported_languages"] == []

packages/hypergumbo-core/tests/test_io_boundary.py

@@ -439,6 +439,42 @@ def test_load_nonexistent_language_returns_empty(self) -> None:
         assert catalog.language == "brainfuck"
         assert len(catalog.primitives) == 0
 
+    def test_unsupported_language_flagged_is_supported_false(self) -> None:
+        """INV-javam: a language with no catalog/alias/parent returns
+        is_supported=False so callers can distinguish "found zero I/O"
+        from "language unsupported".
+        """
+        catalog = load_catalog("brainfuck")
+        assert catalog.is_supported is False
+
+    def test_supported_language_is_supported_true(self) -> None:
+        """INV-javam: a language with a catalog returns is_supported=True."""
+        assert load_catalog("python").is_supported is True
+        assert load_catalog("java").is_supported is True
+
+    def test_alias_language_is_supported(self) -> None:
+        """INV-javam: an aliased language (typescript → javascript) is
+        considered supported because the alias catalog loads.
+        """
+        assert load_catalog("typescript").is_supported is True
+        assert load_catalog("cpp").is_supported is True
+
+    def test_parent_language_is_supported(self) -> None:
+        """INV-javam: a language with a parent catalog (scala → java,
+        kotlin → java, elixir → erlang) is considered supported.
+        """
+        assert load_catalog("scala").is_supported is True
+        assert load_catalog("kotlin").is_supported is True
+        assert load_catalog("elixir").is_supported is True
+
+    def test_is_language_supported_helper(self) -> None:
+        """INV-javam: module-level helper mirrors the catalog flag for
+        callers that don't want to materialize the full catalog.
+        """
+        from hypergumbo_core.io_boundary import is_language_supported
+        assert is_language_supported("python") is True
+        assert is_language_supported("brainfuck") is False
+
     def test_cpp_alias_loads_c_catalog(self) -> None:
         """C++ has no dedicated catalog but falls back to C via alias."""
         catalog = load_catalog("cpp")