sem Semantic Diff Skill

This skill provides instructions on how to use sem, a semantic version control tool that tracks functions, classes, and types rather than just lines of text.

Capabilities & Limitations (What sem Does Well and Does Not Do)

What sem Does Well

• Local Codebase Navigation: Builds a precise semantic dependency graph of all classes, functions, methods, and properties defined within the local repository.
• Structural Diffs & History: Shows added, modified, renamed, or deleted entities across commits without formatting or whitespace noise.
• Internal Impact Analysis: Tracing the transitive impact (sem impact) or callers/callees (sem graph) of local entities across the workspace.

What sem Does Not Do (Important Limitations)

• External Dependencies: sem only indexes entities defined within the local repository's source files. It does not parse or track external packages or transitive library dependencies (e.g., from pubspec.yaml, node_modules, Cargo.toml, etc.).
• External Impact Analysis: Running sem impact on an external type or class (e.g., DartType or ClassElement from an external package) will fail with error: Entity '...' not found.
• Workflow for External Packages: If tasked with evaluating how an external package is used across a codebase, do not start with sem. Use standard grep or ripgrep to find import statements and locate local wrapper classes or helper functions. Once local wrapper entities are identified, use sem impact on those local entities to trace their usage across the codebase.

Finding Entities (<entity_name>)

Many sem commands require an <entity_name>. You can discover the exact names or IDs of entities in the codebase using the following methods: