feat: Add typeid explain command for human/machine-readable TypeID introspection and optional schema support

Changes:
- Introduced a new CLI command: `typeid explain`, enabling human-readable and machine-readable (JSON) explanations for TypeID values.
- Enhanced documentation in README.md with detailed usage, configuration, and design principles for the new explain feature.
- Added support for schema-based explanations via JSON (default) and YAML (optional extra dependency).
- Described schema discovery rules, including support for both local and user config directory schemas.
- Updated `pyproject.toml` and `poetry.lock` to define a new optional extra dependency group: `yaml` (using PyYAML).
- Registered the `yaml` extra in [tool.poetry.extras], enabling users to install YAML support as needed.
- Added explanation formatting utilities and proper schema loading logic in CLI, robustly handling both errors and absence of schema.
- Provided new examples in documentation for using explain with and without schema, and illustrating output formats.
- Ensured backward compatibility by preserving all existing APIs and CLI commands.

Author: akhundMurad

README.md

@@ -36,6 +36,19 @@ This particular implementation provides an pip package that can be used by any P
     poetry add typeid-python
     ```
 
+### Optional dependencies
+
+TypeID supports schema-based ID explanations using JSON (always available) and
+YAML (optional).
+
+To enable YAML support:
+
+```console
+pip install typeid-python[yaml]
+```
+
+If the extra is not installed, JSON schemas will still work.
+
 ## Usage
 
 ### Basic
@@ -109,3 +122,158 @@ This particular implementation provides an pip package that can be used by any P
     $ typeid encode 0188bac7-4afa-78aa-bc3b-bd1eef28d881 --prefix prefix
     prefix_01h2xcejqtf2nbrexx3vqjhp41
     ```
+
+## ✨ NEW: `typeid explain` — “What is this ID?”
+
+TypeID can now **explain a TypeID** in a human-readable way.
+
+This is useful when:
+
+* debugging logs
+* inspecting database records
+* reviewing production incidents
+* understanding IDs shared via Slack, tickets, or dashboards
+
+### Basic usage (no schema required)
+
+```console
+$ typeid explain user_01h45ytscbebyvny4gc8cr8ma2
+```
+
+Example output:
+
+```yaml
+id: user_01h45ytscbebyvny4gc8cr8ma2
+valid: true
+
+parsed:
+  prefix: user
+  suffix: 01h45ytscbebyvny4gc8cr8ma2
+  uuid: 01890bf0-846f-7762-8605-5a3abb40e0e5
+  created_at: 2025-03-12T10:41:23Z
+  sortable: true
+
+schema:
+  found: false
+```
+
+Even without configuration, `typeid explain` can:
+
+* validate the ID
+* extract the UUID
+* derive creation time (UUIDv7)
+* determine sortability
+
+## Schema-based explanations
+
+To make explanations richer, you can define a **TypeID schema** describing what each
+prefix represents.
+
+### Example schema (`typeid.schema.json`)
+
+```json
+{
+  "schema_version": 1,
+  "types": {
+    "user": {
+      "name": "User",
+      "description": "End-user account",
+      "owner_team": "identity-platform",
+      "pii": true,
+      "retention": "7y",
+      "links": {
+        "logs": "https://logs.company/search?q={id}",
+        "trace": "https://traces.company/?id={id}"
+      }
+    }
+  }
+}
+```
+
+### Explain using schema
+
+```console
+$ typeid explain user_01h45ytscbebyvny4gc8cr8ma2
+```
+
+Output (excerpt):
+
+```yaml
+schema:
+  found: true
+  name: User
+  owner_team: identity-platform
+  pii: true
+  retention: 7y
+
+links:
+  logs: https://logs.company/search?q=user_01h45ytscbebyvny4gc8cr8ma2
+```
+
+## Schema discovery rules
+
+If `--schema` is not provided, TypeID looks for a schema in the following order:
+
+1. Environment variable:
+
+   ```console
+   TYPEID_SCHEMA=/path/to/schema.json
+   ```
+2. Current directory:
+
+   * `typeid.schema.json`
+   * `typeid.schema.yaml`
+3. User config directory:
+
+   * `~/.config/typeid/schema.json`
+   * `~/.config/typeid/schema.yaml`
+
+If no schema is found, the command still works with derived information only.
+
+## YAML schemas (optional)
+
+YAML schemas are supported if the optional dependency is installed:
+
+```console
+pip install typeid-python[yaml]
+```
+
+Example (`typeid.schema.yaml`):
+
+```yaml
+schema_version: 1
+types:
+  user:
+    name: User
+    owner_team: identity-platform
+    links:
+      logs: "https://logs.company/search?q={id}"
+```
+
+## JSON output (machine-readable)
+
+```console
+$ typeid explain user_01h45ytscbebyvny4gc8cr8ma2 --json
+```
+
+Useful for:
+
+* scripts
+* CI pipelines
+* IDE integrations
+
+## Design principles
+
+* **Non-breaking**: existing APIs and CLI commands remain unchanged
+* **Schema-optional**: works fully offline
+* **Read-only**: no side effects or external mutations
+* **Declarative**: meaning is defined by users, not inferred by the tool
+
+You can think of `typeid explain` as:
+
+> **OpenAPI — but for identifiers instead of HTTP endpoints**
+
+## License
+
+MIT
+

poetry.lock

@@ -60,6 +60,7 @@ twine = "^6.2.0"
 
 [tool.poetry.extras]
 cli = ["click"]
+yaml = ["PyYAML"]
 
 [tool.poetry.scripts]
 typeid = "typeid.cli:cli"

pyproject.toml

@@ -0,0 +1,93 @@
+import json
+from pathlib import Path
+
+from click.testing import CliRunner
+
+from typeid import TypeID
+from typeid.cli import cli
+
+
+def _make_valid_id(prefix: str = "usr") -> str:
+    return str(TypeID(prefix=prefix))
+
+
+def test_cli_explain_pretty_offline_no_schema():
+    runner = CliRunner()
+    tid = _make_valid_id("usr")
+
+    result = runner.invoke(cli, ["explain", tid, "--no-schema"])
+    assert result.exit_code == 0
+    out = result.output
+
+    assert f"id: {tid}" in out
+    assert "valid: true" in out
+    assert "schema:" in out
+    assert "found: false" in out or "found: false" in out.lower()
+
+
+def test_cli_explain_json_offline():
+    runner = CliRunner()
+    tid = _make_valid_id("usr")
+
+    result = runner.invoke(cli, ["explain", tid, "--no-schema", "--json"])
+    assert result.exit_code == 0
+
+    payload = json.loads(result.output)
+    assert payload["id"] == tid
+    assert payload["valid"] is True
+    assert payload["schema"] is None
+    assert payload["parsed"]["prefix"] == "usr"
+    assert payload["parsed"]["uuid"] is not None
+
+
+def test_cli_explain_with_schema_file(tmp_path: Path):
+    runner = CliRunner()
+    tid = _make_valid_id("usr")
+
+    schema = {
+        "schema_version": 1,
+        "types": {
+            "usr": {"name": "User", "owner_team": "identity-platform", "links": {"logs": "https://logs?q={id}"}}
+        },
+    }
+    p = tmp_path / "typeid.schema.json"
+    p.write_text(json.dumps(schema), encoding="utf-8")
+
+    result = runner.invoke(cli, ["explain", tid, "--schema", str(p)])
+    assert result.exit_code == 0
+    out = result.output
+
+    assert "schema:" in out
+    assert "found: true" in out
+    assert "name: User" in out
+    assert "owner_team: identity-platform" in out
+    assert "links:" in out
+    assert "logs:" in out
+
+
+def test_cli_explain_schema_load_failure_still_works(tmp_path: Path):
+    runner = CliRunner()
+    tid = _make_valid_id("usr")
+
+    p = tmp_path / "typeid.schema.json"
+    p.write_text("{not json", encoding="utf-8")
+
+    result = runner.invoke(cli, ["explain", tid, "--schema", str(p)])
+    assert result.exit_code == 0
+    out = result.output
+
+    # Should still explain derived facts and surface warning
+    assert f"id: {tid}" in out
+    assert "valid: true" in out
+    assert "warnings:" in out.lower()
+
+
+def test_cli_explain_invalid_id_exit_code_zero_but_valid_false():
+    # We keep exit_code 0 for "explain" so it can be used in scripts without
+    # failing pipelines; the content will indicate validity.
+    runner = CliRunner()
+
+    result = runner.invoke(cli, ["explain", "not_a_typeid", "--no-schema"])
+    assert result.exit_code == 0
+    assert "valid: false" in result.output.lower()
+    assert "errors:" in result.output.lower()

tests/explain/__init__.py

@@ -0,0 +1,64 @@
+import json
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from typeid import TypeID
+from typeid.cli import cli
+
+
+yaml = pytest.importorskip("yaml")  # skip if PyYAML not installed
+
+
+def test_cli_explain_with_yaml_schema(tmp_path: Path):
+    runner = CliRunner()
+    tid = str(TypeID(prefix="usr"))
+
+    p = tmp_path / "typeid.schema.yaml"
+    p.write_text(
+        """
+schema_version: 1
+types:
+  usr:
+    name: User
+    owner_team: identity-platform
+    links:
+      logs: "https://logs?q={id}"
+""",
+        encoding="utf-8",
+    )
+
+    result = runner.invoke(cli, ["explain", tid, "--schema", str(p)])
+    assert result.exit_code == 0
+    out = result.output
+
+    assert "schema:" in out
+    assert "found: true" in out
+    assert "name: User" in out
+    assert "owner_team: identity-platform" in out
+    assert "logs:" in out
+
+
+def test_cli_explain_with_yaml_schema_json_output(tmp_path: Path):
+    runner = CliRunner()
+    tid = str(TypeID(prefix="usr"))
+
+    p = tmp_path / "typeid.schema.yaml"
+    p.write_text(
+        """
+schema_version: 1
+types:
+  usr:
+    name: User
+""",
+        encoding="utf-8",
+    )
+
+    result = runner.invoke(cli, ["explain", tid, "--schema", str(p), "--json"])
+    assert result.exit_code == 0
+
+    payload = json.loads(result.output)
+    assert payload["valid"] is True
+    assert payload["schema"] is not None
+    assert payload["schema"]["name"] == "User"