tagpath

Parse, lint, and search tag-based identifiers across languages and naming conventions.

Tag Path treats every identifier as a path through an ordered sequence of tags. auth0__user__validate, personName, PersonName, and person_name all decompose into canonical tag lists — enabling semantic equivalence across conventions.

Install

cargo install tagpath

Quick Start

# Parse an identifier into tags
tagpath parse person_name
# name:       person_name
# convention: snake_case
# tags:       [person, name]
# canonical:  person_name

# Auto-detects convention
tagpath parse personName
# tags:       [person, name]

tagpath parse PersonName
# tags:       [person, name]

# Namespace dimensions (__ separator)
tagpath parse "auth0__user__validate"
# tags:       [auth0, user, validate]
# dimension 0: [auth0]
# dimension 1: [user]
# dimension 2: [validate]
# role:       validator

# JSON output
tagpath parse createContext_auth --format json

# Extract identifiers from source files
tagpath extract src/ --format text
tagpath extract src/ --ast    # AST-aware (tree-sitter)

# Cross-language semantic search
tagpath search "user" src/    # finds user_name, userName, UserName, user-name
tagpath search "validate_user" src/  # finds across all conventions

# Lint against .naming.toml rules
tagpath lint src/

# Generate cross-convention aliases
tagpath alias person_name
# snake_case:      person_name
# camelCase:       personName
# PascalCase:      PersonName
# kebab-case:      person-name
# UPPER_SNAKE_CASE: PERSON_NAME
# Ada_Case:        Person_Name

tagpath alias person_name --convention camelCase
# camelCase:       personName

# Human-readable prose descriptions
tagpath prose create_user_profile
# Creates a user profile

tagpath prose is_valid_email
# Checks if email is valid

# Build tag co-occurrence graphs
tagpath graph src/ --format dot       # DOT output for Graphviz
tagpath graph src/ --format json      # JSON nodes + edges
tagpath graph src/ --query "user"     # subgraph around "user" tag

# Initialize a .naming.toml
tagpath init --lang typescript
tagpath init --preset immutable-tag

Features

• Convention detection — auto-detects snake_case, camelCase, PascalCase, kebab-case, UPPER_SNAKE_CASE, Ada_Case
• Semantic equivalence — person_name = personName = PersonName → [person, name]
• Role detection — create_* (factory), use_* (hook), set_* (setter), is_* (predicate), etc.
• Shape detection — *_a (array), *_r (record), *_m (map), *$ (signal)
• Namespace dimensions — __ separates semantic dimensions
• Mixed convention support — handles createContext_auth (camelCase + underscore extension)
• Language presets — 39 languages with per-context conventions
• Configurable — .naming.toml for project-specific conventions
• Composable configs — extends inherits from language presets with per-context overrides
• Identifier extraction — extract identifiers from source files with regex or tree-sitter AST
• Semantic search — find identifiers across naming conventions by canonical tag matching
• Lint — validate naming conventions against .naming.toml rules
• Tree-sitter integration — AST-aware extraction for 14 languages with context classification
• Alias generation — convert any identifier to all 6 naming conventions
• Prose conversion — human-readable descriptions with role/shape awareness
• Tag graph — co-occurrence graph of tag relationships across a codebase (petgraph, DOT/JSON output)

Language Presets

Configuration

Create a .naming.toml in your project root:

version = 1
name = "my-project"
convention = "snake_case"
immutable = true
singular = true

[vectors]
join = "_"
namespace = "__"

[patterns]
factory = "create_{name}"
hook = "use_{name}"
setter = "set_{name}"

[tags]
open = true

Composable Configs (extends)

Configs can extend language presets and override specific contexts:

# Extend a language preset
version = 1
name = "my-project"
extends = ["rust"]

[contexts.function]
convention = "camelCase"  # override function convention

The extends field accepts an array of preset names. Fields from the extending config override inherited values. Context-level overrides merge with the parent — only the specified fields are replaced.

Tree-sitter Integration

Tagpath uses tree-sitter for AST-aware identifier extraction in 14 languages:

All 14 languages are enabled by default. Disable grammars you don't need to reduce binary size:

# Install with only Rust and Python grammars
cargo install tagpath --no-default-features --features lang-rust,lang-python

# Install without any tree-sitter (regex-only extraction)
cargo install tagpath --no-default-features

All other supported languages (25 of 39 presets) use regex-based identifier extraction.

• Use --ast flag with tagpath extract to enable tree-sitter mode
• AST extraction classifies identifiers by context (function, type, variable, etc.)

Roadmap

• Phase 1 ✅ — Parse, detect conventions, semantic equivalence
• Phase 2 ✅ — tree-sitter integration, lint command, extract identifiers, semantic search, composable configs
• Phase 3 ✅ — Alias generation, prose conversion, tag co-occurrence graph

License

MIT