bash-classify 0.10.0__tar.gz → 0.11.0__tar.gz

{bash_classify-0.10.0 → bash_classify-0.11.0}/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "bash-classify-hook",
       "description": "Auto-allows low-risk bash commands in Claude Code using bash-classify",
-      "version": "0.10.0",
+      "version": "0.11.0",
       "author": {
         "name": "Filip Procházka",
         "url": "https://github.com/fprochazka"

{bash_classify-0.10.0 → bash_classify-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bash-classify
-Version: 0.10.0
+Version: 0.11.0
 Summary: Classify bash commands as READONLY, WRITE, DANGEROUS, or UNKNOWN
 Project-URL: Homepage, https://github.com/fprochazka/bash-classify
 Project-URL: Repository, https://github.com/fprochazka/bash-classify
@@ -180,6 +180,7 @@ Risk defaults are derived from classification (`READONLY`→LOW, `LOCAL_EFFECTS`
 - **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
 - **YAML command database** -- each command has classification rules with subcommand and option matching
 - **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Subcommand aliases** -- a subcommand can declare other names for itself, so `glab pipeline view` resolves to `glab ci view` and any rule written for the canonical name catches the aliased spelling
 - **Multi-goal build tools** -- `subcommand_mode: match_all` handles commands like `mvn clean install` and `gradle clean build test` where multiple goals can be combined in any order
 - **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
 - **File path detection** -- redirect operators (`>`, `>>`, `<`) are parsed into `write_paths`/`read_paths` in the output; writes to `/tmp` and `/var/tmp` stay at LOW risk

{bash_classify-0.10.0 → bash_classify-0.11.0}/README.md

@@ -151,6 +151,7 @@ Risk defaults are derived from classification (`READONLY`→LOW, `LOCAL_EFFECTS`
 - **Tree-sitter parsing** -- bash expressions are parsed into an AST for accurate command extraction, handling pipes, subshells, and command substitution
 - **YAML command database** -- each command has classification rules with subcommand and option matching
 - **Subcommand matching** -- `kubectl get` and `kubectl delete` can have different classifications
+- **Subcommand aliases** -- a subcommand can declare other names for itself, so `glab pipeline view` resolves to `glab ci view` and any rule written for the canonical name catches the aliased spelling
 - **Multi-goal build tools** -- `subcommand_mode: match_all` handles commands like `mvn clean install` and `gradle clean build test` where multiple goals can be combined in any order
 - **Delegation for wrappers** -- commands like `xargs`, `sudo`, and `env` delegate classification to the inner command
 - **File path detection** -- redirect operators (`>`, `>>`, `<`) are parsed into `write_paths`/`read_paths` in the output; writes to `/tmp` and `/var/tmp` stay at LOW risk

{bash_classify-0.10.0 → bash_classify-0.11.0}/SPEC.md

@@ -398,7 +398,7 @@ This is the core of the tool. Given an `argv` like `["kubectl", "--context=prod"
 
 1. **Look up the binary** (`kubectl`) in the database
 2. **Separate global options** from the rest of `argv`, using the database definition of which options are global and whether they take a value
-3. **Match the subcommand chain** from the remaining tokens (e.g. `get` → resolve to `kubectl.get`)
+3. **Match the subcommand chain** from the remaining tokens (e.g. `get` → resolve to `kubectl.get`), resolving any declared subcommand alias to its canonical name
 4. **Classify remaining options** against the matched subcommand's option definitions
 5. **Determine the final classification** based on subcommand default + any option overrides
 
@@ -451,6 +451,14 @@ The default mode. Subcommands are matched as a greedy chain through nested subco
 
 Example: `kubectl rollout status` matches `kubectl` → `rollout` → `status`, walking the tree.
 
+#### Subcommand aliases
+
+A subcommand may declare `aliases`. Every alias is another name for the same definition, so matching a word against a subcommand dictionary tries the canonical names and the aliases alike. What is reported is always the canonical name: `glab pipeline view 1000` yields `command: ["glab", "ci", "view"]` and `matched_rule: "glab.ci.view"`, while `argv` keeps `["glab", "pipeline", "view", "1000"]` — the word that was actually typed. Classification, options and `strict` behaviour are the canonical subcommand's, since it is literally the same definition.
+
+This matters to `match` mode: a rule written as `command: [glab, ci, view]` catches the aliased spelling too, without listing it.
+
+Aliases live in one namespace with their siblings. An alias that names a sibling subcommand, or that two siblings both claim, is rejected when the database file is loaded — the error names the file and the alias.
+
 #### `match_all`
 
 Each positional argument is matched independently against the **same** top-level subcommand dictionary. This is designed for build tools like Maven and Gradle where multiple goals/tasks appear as positional arguments in any order.
@@ -952,6 +960,14 @@ When command-level delegation resolves at least one inner command (and no option
 | `subcommand_mode` | `enum` | How subcommands are matched: `hierarchical` (default, chained tree walk) or `match_all` (each positional arg matched independently) |
 | `delegates_to` | `object` | How this command delegates execution to an inner command (see delegation modes) |
 
+#### Subcommand level
+
+A subcommand entry takes the same fields as the command level, minus `command` and `global_options` — its name is the key it is filed under — plus:
+
+| Field | Type | Description |
+|---|---|---|
+| `aliases` | `list[str]` | Alternative names for this subcommand (e.g. `pipe` and `pipeline` for `glab ci`). Each alias resolves to this same definition; the resolved `command` path and `matched_rule` name the canonical subcommand, while `argv` keeps the word that was typed. An alias that collides with a sibling subcommand, or that two siblings both claim, is a load-time error. |
+
 #### Option level
 
 | Field | Type | Description |
@@ -1129,7 +1145,7 @@ builtins, an unknown binary, an empty argv — carry `null` internally and seria
 - **Not a sandbox.** This is a classifier, not an enforcer. It does not execute or block anything. `match` mode is no exception: it reports which declared command shapes an expression invokes, and the caller decides what to do about it.
 - **No awk/sed/perl script analysis.** These are classified as a whole command; their embedded programs are opaque. They should simply not be in the READONLY allowlist.
 - **No variable resolution.** `$DIR`, `$(cmd)` in command position → UNKNOWN. We classify what we can see statically.
-- **No alias/function resolution.** We classify the literal command name as written.
+- **No shell alias/function resolution.** We classify the literal command name as written.
 
 ## Future extensions
 

{bash_classify-0.10.0 → bash_classify-0.11.0}/coding-agent-plugins/claude-code/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "bash-classify-hook",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Auto-allows low-risk bash commands in Claude Code using bash-classify",
   "author": {
     "name": "Filip Prochazka"

{bash_classify-0.10.0 → bash_classify-0.11.0}/docs/classification-guidance.md

@@ -84,6 +84,25 @@ options:                            # options that affect classification
 | `subcommands` | map | -- | Nested subcommand definitions (recursive) |
 | `delegates_to` | object | -- | How the command hands off to an inner command |
 
+#### Subcommand fields
+
+A subcommand takes the same fields as the top level, minus `command`, `description` and `global_options`, plus:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `aliases` | list | Alternative names for this subcommand (e.g. `pipe` and `pipeline` for `glab ci`) |
+
+An alias is another name for the same definition, not a copy of it: `glab pipeline view` classifies exactly as `glab ci view` and is reported as `["glab", "ci", "view"]`, while `argv` keeps the word that was typed. Declare aliases only for names the tool itself accepts (`glab ci --help` lists `pipe` and `pipeline`), and never a name a sibling subcommand already uses — that is rejected when the file loads.
+
+```yaml
+subcommands:
+  ci:
+    aliases: [pipe, pipeline]
+    subcommands:
+      list:
+        classification: READONLY
+```
+
 #### Option fields
 
 | Field | Type | Description |

{bash_classify-0.10.0 → bash_classify-0.11.0}/schemas/command.schema.json

@@ -174,6 +174,13 @@
       "type": "object",
       "additionalProperties": false,
       "properties": {
+        "aliases": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Alternative names for this subcommand (e.g. `pipe` and `pipeline` for `glab ci`). A match through an alias resolves to this definition and reports the canonical name in the command path. An alias must not collide with a sibling subcommand or with another sibling's alias."
+        },
         "classification": {
           "$ref": "#/$defs/Classification"
         },

{bash_classify-0.10.0 → bash_classify-0.11.0}/src/bash_classify/commands/glab.yaml

@@ -251,6 +251,8 @@ subcommands:
 
   # ── CI/CD: Pipelines ──────────────────────────────────────────
   ci:
+    # `pipe` and `pipeline` are glab's own deprecated aliases for `ci`
+    aliases: [pipe, pipeline]
     subcommands:
       list:
         classification: READONLY

{bash_classify-0.10.0 → bash_classify-0.11.0}/src/bash_classify/database.py

@@ -181,8 +181,19 @@ _ALIAS_FORBIDDEN_KEYS = frozenset(
 )
 
 
-def _parse_command_def(data: dict, command_name: str) -> CommandDef:
-    """Parse a raw YAML dict into a CommandDef structure."""
+def _parse_command_def(data: dict, command_name: str, is_subcommand: bool = False) -> CommandDef:
+    """Parse a raw YAML dict into a CommandDef structure.
+
+    `is_subcommand` distinguishes an entry under a `subcommands` map from the top level of
+    a command file. Only the former may carry `aliases`; a command file names itself by its
+    filename, so a second name for it is a separate `alias_of` file.
+    """
+    if "aliases" in data and not is_subcommand:
+        raise ValueError(
+            f"command '{command_name}': 'aliases' is only valid on subcommands; "
+            f"use an alias_of file for a command-level alias"
+        )
+
     alias_of = data.get("alias_of")
     if alias_of is not None:
         conflicting = sorted(_ALIAS_FORBIDDEN_KEYS & data.keys())
@@ -205,6 +216,7 @@ def _parse_command_def(data: dict, command_name: str) -> CommandDef:
 
     return CommandDef(
         command=command_name,
+        aliases=_parse_aliases(data.get("aliases"), command_name),
         classification=classification,
         risk=risk,
         global_options=global_options,
@@ -267,8 +279,23 @@ def _parse_options(raw: dict | None) -> dict[str, OptionDef]:
     return options
 
 
+def _parse_aliases(raw: object, command_name: str) -> list[str]:
+    """Parse the `aliases` list of a subcommand definition."""
+    if raw is None:
+        return []
+    if not isinstance(raw, list):
+        raise ValueError(f"subcommand '{command_name}': 'aliases' must be a list of strings")
+    return [_yaml_str(alias) for alias in raw]
+
+
 def _parse_subcommands(raw: dict | None) -> dict[str, CommandDef]:
-    """Parse a subcommands map recursively."""
+    """Parse a subcommands map recursively.
+
+    Each alias is registered in the same map as the definition it belongs to, pointing at
+    that very object, so `_match_subcommand` finds it by the typed word and still reports
+    the canonical name. An alias that would shadow a real sibling subcommand, or that two
+    siblings claim, is rejected here rather than silently resolving to one of them.
+    """
     if not raw:
         return {}
 
@@ -277,7 +304,26 @@ def _parse_subcommands(raw: dict | None) -> dict[str, CommandDef]:
     for name, props in raw.items():
         if props is None:
             props = {}
-        subcommands[name] = _parse_command_def(props, name)
+        canonical = _yaml_str(name)
+        subcommands[canonical] = _parse_command_def(props, canonical, is_subcommand=True)
+
+    aliased_by: dict[str, str] = {}
+    for canonical, definition in list(subcommands.items()):
+        for alias in definition.aliases:
+            if alias in subcommands:
+                raise ValueError(
+                    f"subcommand '{canonical}' declares alias '{alias}', "
+                    f"which is already a subcommand of the same parent"
+                )
+            if alias in aliased_by:
+                raise ValueError(
+                    f"subcommand '{canonical}' declares alias '{alias}', "
+                    f"which is already an alias of subcommand '{aliased_by[alias]}'"
+                )
+            aliased_by[alias] = canonical
+
+    for alias, canonical in aliased_by.items():
+        subcommands[alias] = subcommands[canonical]
 
     return subcommands
 

{bash_classify-0.10.0 → bash_classify-0.11.0}/src/bash_classify/matcher.py

@@ -452,6 +452,10 @@ def _match_subcommand(
 ) -> tuple[CommandDef, list[str], list[str]]:
     """Match subcommand chain from argv.
 
+    The chain holds canonical subcommand names: a word typed as a declared alias
+    (`glab pipeline view` for `glab ci view`) resolves to the definition it names, and it
+    is that definition's own name that lands in the chain. `argv` keeps the typed word.
+
     Returns (matched_def, command_chain, remaining_argv).
     """
     matched_def = command_def
@@ -466,8 +470,8 @@ def _match_subcommand(
             break
 
         if token in matched_def.subcommands:
-            command_chain.append(token)
             matched_def = matched_def.subcommands[token]
+            command_chain.append(matched_def.command)
             remaining = remaining[1:]
         else:
             break
@@ -496,8 +500,9 @@ def _match_all_subcommands(
             # Options pass through for _classify_options later
             remaining.append(token)
         elif token in command_def.subcommands:
-            matched_names.append(token)
-            matched_defs.append(command_def.subcommands[token])
+            matched = command_def.subcommands[token]
+            matched_names.append(matched.command)
+            matched_defs.append(matched)
         else:
             # Unrecognized goal — pass through as positional
             remaining.append(token)

{bash_classify-0.10.0 → bash_classify-0.11.0}/src/bash_classify/models.py

@@ -134,10 +134,17 @@ class OptionDef:
 
 @dataclass
 class CommandDef:
-    """Definition of a command (or subcommand) from the database."""
+    """Definition of a command (or subcommand) from the database.
+
+    ``command`` is the canonical name. A subcommand may additionally be reachable under
+    the names in ``aliases``: the parent's ``subcommands`` map holds the very same
+    definition object under each of them, so a matched alias still reports the canonical
+    name in the resolved command path.
+    """
 
     command: str
     alias_of: str | None = None
+    aliases: list[str] = field(default_factory=list)
     classification: Classification | None = None
     risk: Risk | None = None
     global_options: dict[str, OptionDef] = field(default_factory=dict)

bash_classify-0.11.0/tests/fixtures/match/glab-pipeline/block/pipe-get-alias.sh

@@ -0,0 +1 @@
+glab pipe get -p 1000 --with-job-details -F json 2>/dev/null | jq -r '.jobs[] | "\(.status)\t\(.name)"'

bash_classify-0.11.0/tests/fixtures/match/glab-pipeline/block/pipeline-view-alias.sh

@@ -0,0 +1 @@
+glab pipeline view 1000 2>&1 | head -50

{bash_classify-0.10.0 → bash_classify-0.11.0}/tests/test_database.py

@@ -238,6 +238,73 @@ class TestAliasOf:
         assert db["myalias"].alias_of == "target"
 
 
+class TestSubcommandAliases:
+    def test_alias_maps_to_the_same_definition_object(self, database: dict[str, CommandDef]) -> None:
+        """`glab pipe` and `glab pipeline` are glab's own deprecated names for `glab ci`."""
+        glab = database["glab"]
+        ci = glab.subcommands["ci"]
+        assert glab.subcommands["pipe"] is ci
+        assert glab.subcommands["pipeline"] is ci
+
+    def test_alias_keeps_the_canonical_name(self, database: dict[str, CommandDef]) -> None:
+        glab = database["glab"]
+        assert glab.subcommands["pipeline"].command == "ci"
+        assert glab.subcommands["ci"].aliases == ["pipe", "pipeline"]
+
+    def test_subcommand_without_aliases_has_an_empty_list(self, database: dict[str, CommandDef]) -> None:
+        assert database["glab"].subcommands["mr"].aliases == []
+
+    def test_nested_alias_is_registered(self, tmp_path: Path) -> None:
+        """Aliases work at any depth, not only on the first level."""
+        (tmp_path / "tool.yaml").write_text(
+            "command: tool\n"
+            "subcommands:\n"
+            "  remote:\n"
+            "    subcommands:\n"
+            "      list:\n"
+            "        aliases: [ls]\n"
+            "        classification: READONLY\n"
+        )
+        db = load_database(tmp_path)
+        remote = db["tool"].subcommands["remote"]
+        assert remote.subcommands["ls"] is remote.subcommands["list"]
+
+    def test_alias_colliding_with_a_sibling_subcommand_is_rejected(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.yaml").write_text(
+            "command: tool\nsubcommands:\n  ci:\n    aliases: [status]\n  status:\n    classification: READONLY\n"
+        )
+        db = load_database(tmp_path)
+        with pytest.raises(ValueError, match="tool.yaml.*alias 'status'.*already a subcommand"):
+            db["tool"]
+
+    def test_alias_claimed_by_two_siblings_is_rejected(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.yaml").write_text(
+            "command: tool\nsubcommands:\n  ci:\n    aliases: [p]\n  publish:\n    aliases: [p]\n"
+        )
+        db = load_database(tmp_path)
+        with pytest.raises(ValueError, match="tool.yaml.*alias 'p'.*already an alias of subcommand 'ci'"):
+            db["tool"]
+
+    def test_alias_repeating_its_own_subcommand_name_is_rejected(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.yaml").write_text("command: tool\nsubcommands:\n  ci:\n    aliases: [ci]\n")
+        db = load_database(tmp_path)
+        with pytest.raises(ValueError, match="tool.yaml.*alias 'ci'.*already a subcommand"):
+            db["tool"]
+
+    def test_top_level_aliases_key_is_rejected(self, tmp_path: Path) -> None:
+        """A command file names itself by its filename; a second name is an alias_of file."""
+        (tmp_path / "tool.yaml").write_text("command: tool\naliases: [t]\nclassification: READONLY\n")
+        db = load_database(tmp_path)
+        with pytest.raises(ValueError, match="tool.yaml.*'aliases' is only valid on subcommands"):
+            db["tool"]
+
+    def test_aliases_must_be_a_list(self, tmp_path: Path) -> None:
+        (tmp_path / "tool.yaml").write_text("command: tool\nsubcommands:\n  ci:\n    aliases: pipe\n")
+        db = load_database(tmp_path)
+        with pytest.raises(ValueError, match="tool.yaml.*'aliases' must be a list"):
+            db["tool"]
+
+
 class TestUserCommandsDir:
     def test_user_override_replaces_builtin(self, tmp_path: Path) -> None:
         """User YAML overrides built-in command definition."""

{bash_classify-0.10.0 → bash_classify-0.11.0}/tests/test_matcher.py

@@ -837,6 +837,66 @@ class TestRiskOptionOverrides:
         assert result.risk == Risk.HIGH
 
 
+class TestSubcommandAliases:
+    """A subcommand reached through an alias reports the canonical name.
+
+    `command` and `matched_rule` are what a rule or an allowlist is written against, so
+    they must name the subcommand the database defines. `argv` is what the user typed and
+    stays untouched.
+    """
+
+    def test_alias_resolves_to_the_canonical_command_path(self, database: dict[str, CommandDef]) -> None:
+        result = match_command(_make_invocation(["glab", "pipeline", "view", "1000"]), database)
+        assert result.command == ["glab", "ci", "view"]
+        assert result.argv == ["glab", "pipeline", "view", "1000"]
+        assert result.matched_rule == "glab.ci.view"
+
+    def test_alias_classifies_exactly_as_the_canonical_subcommand(self, database: dict[str, CommandDef]) -> None:
+        typed = match_command(_make_invocation(["glab", "pipe", "get", "-p", "1000", "-F", "json"]), database)
+        canonical = match_command(_make_invocation(["glab", "ci", "get", "-p", "1000", "-F", "json"]), database)
+        assert typed.command == canonical.command
+        assert typed.classification == canonical.classification
+        assert typed.risk == canonical.risk
+        assert typed.options == canonical.options
+        assert typed.positionals == canonical.positionals
+
+    def test_alias_only_shadows_at_its_own_level(self, database: dict[str, CommandDef]) -> None:
+        """`pipeline` is an alias of `glab ci`, not a word that means `ci` everywhere."""
+        result = match_command(_make_invocation(["glab", "mr", "pipeline"]), database)
+        assert result.command == ["glab", "mr"]
+
+    def test_nested_alias_reports_the_canonical_path(self) -> None:
+        inner = CommandDef(command="list", aliases=["ls"], classification=Classification.READONLY)
+        outer = CommandDef(command="remote", subcommands={"list": inner, "ls": inner})
+        database = {"tool": CommandDef(command="tool", subcommands={"remote": outer})}
+        result = match_command(_make_invocation(["tool", "remote", "ls", "origin"]), database)
+        assert result.command == ["tool", "remote", "list"]
+        assert result.argv == ["tool", "remote", "ls", "origin"]
+        assert result.matched_rule == "tool.remote.list"
+        assert result.classification == Classification.READONLY
+
+    def test_alias_inherits_strict_mode(self) -> None:
+        """The alias is the same definition, so an unknown option is UNKNOWN either way."""
+        sub = CommandDef(command="build", aliases=["b"], classification=Classification.LOCAL_EFFECTS, strict=True)
+        database = {"tool": CommandDef(command="tool", subcommands={"build": sub, "b": sub})}
+        result = match_command(_make_invocation(["tool", "b", "--no-such-flag"]), database)
+        assert result.command == ["tool", "build"]
+        assert result.classification == Classification.UNKNOWN
+
+    def test_alias_in_match_all_mode_reports_the_canonical_goal(self) -> None:
+        clean = CommandDef(command="clean", aliases=["clobber"], classification=Classification.LOCAL_EFFECTS)
+        database = {
+            "build-tool": CommandDef(
+                command="build-tool",
+                subcommand_mode=SubcommandMode.MATCH_ALL,
+                subcommands={"clean": clean, "clobber": clean},
+            )
+        }
+        result = match_command(_make_invocation(["build-tool", "clobber"]), database)
+        assert result.command == ["build-tool", "clean"]
+        assert result.classification == Classification.LOCAL_EFFECTS
+
+
 class TestRiskExplicitOverrideInCommandDef:
     def test_explicit_risk_in_command_def(self) -> None:
         """A command with explicit risk: LOW should use that risk."""

{bash_classify-0.10.0 → bash_classify-0.11.0}/tests/test_real_world.py

@@ -599,6 +599,32 @@ class TestGlabOptions:
         assert command.options == ["--per-page"]
         assert command.positionals == []
 
+    def test_ci_pipeline_alias(self, database):
+        """`glab pipeline` is glab's own deprecated spelling of `glab ci`."""
+        result = classify_expression("glab pipeline view 1000 --web", database)
+        assert result.classification == Classification.READONLY
+        command = result.commands[0]
+        assert command.command == ["glab", "ci", "view"]
+        assert command.argv == ["glab", "pipeline", "view", "1000", "--web"]
+        assert command.matched_rule == "glab.ci.view"
+        assert command.options == ["--web"]
+        assert command.positionals == ["1000"]
+
+    def test_ci_pipe_alias(self, database):
+        result = classify_expression("glab pipe get -p 1000 --with-job-details -F json", database)
+        assert result.classification == Classification.READONLY
+        command = result.commands[0]
+        assert command.command == ["glab", "ci", "get"]
+        assert command.argv[1] == "pipe"
+        assert command.options == ["-p", "--with-job-details", "-F"]
+
+    def test_ci_alias_inside_a_wrapper(self, database):
+        """The alias resolves the same way in a delegated inner command."""
+        result = classify_expression("timeout 60 glab pipeline trace deploy-test -p 1000", database)
+        inner = result.commands[0].inner_commands[0]
+        assert inner.command == ["glab", "ci", "trace"]
+        assert inner.argv == ["glab", "pipeline", "trace", "deploy-test", "-p", "1000"]
+
     def test_glab_classifications_unchanged(self, database):
         """Declaring options must not move any classification or risk."""
         assert classify_expression("glab mr view 42", database).classification == Classification.READONLY