symbols
symbols
Section titled “symbols”The symbols command counts declarations: functions, types, enums, and
constants, broken down per language.
Where loc answers how much code is here, this answers what is declared in
it. The two are different questions and a repository can move sharply in one
while barely moving in the other — a codebase can grow by 20,000 lines of
generated code and gain four declarations, or lose 400 functions and gain none
because the code was rewritten shorter.
sephera symbols --path .Analyze a remote repository directly:
sephera symbols --url https://github.com/Reim-developer/Sepherasephera symbols --path . # per-language declaration countssephera symbols --path . --by-file # which files carry the declarationssephera symbols --path . --format markdown # the summary, pastable into a reviewRun from inside the repository you want to measure.
Counts come from parse trees
Section titled “Counts come from parse trees”Every count is read from a Tree-sitter parse tree, not matched from text. That distinction is the whole reason to use this command rather than a regular expression over the source, and it is visible in three places:
- a keyword inside a comment or a string literal is not a declaration
- a function nested inside an
implblock, a class body, or a trait is attributed to the right file and counted once, not missed - a
moddeclaration, which names a file rather than declaring anything in it, is not counted
Supported languages: Rust, Python, TypeScript, JavaScript, Go, Java, C, and C++.
Output formats
Section titled “Output formats”--format selects the rendering, and --output writes it to a file:
sephera symbols --path . --format json --output reports/symbols.jsonsephera symbols --path . --format markdown| format | for |
|---|---|
table | a terminal; the default |
markdown | pasting into a pull request; adds the declaration list |
json | a dashboard or a script |
Sample output
Section titled “Sample output”╭──────────┬───────┬───────────┬───────┬───────┬───────────┬───────╮│ Language ┆ Files ┆ Functions ┆ Types ┆ Enums ┆ Constants ┆ Total │╞══════════╪═══════╪═══════════╪═══════╪═══════╪═══════════╪═══════╡│ Rust ┆ 10 ┆ 273 ┆ 32 ┆ 6 ┆ 9 ┆ 320 ││ Totals ┆ 10 ┆ 273 ┆ 32 ┆ 6 ┆ 9 ┆ 320 │╰──────────┴───────┴───────────┴───────┴───────┴───────────┴───────╯Files scanned: 10Languages detected: 1Listing every declaration
Section titled “Listing every declaration”The per-language summary cannot tell you where a declaration is, and for a
rename or a review you need to. --detail lists every one, with its file, line,
and kind:
sephera symbols --path crates/sephera_graph --detailIt is opt-in because it produces far more output than the summary — one line per declaration rather than one row per language.
Breaking it down per file
Section titled “Breaking it down per file”--by-file answers a different question: not how many functions are here, but
which files carry them. A per-language summary cannot answer it, because a
language’s declarations are spread across its files unevenly and the interesting
case is the one that is heaviest.
sephera symbols --path . --by-filesephera symbols --path . --by-file --format markdownFiles are listed heaviest first.
JSON shape
Section titled “JSON shape”{ "report": { "base_path": ".", "by_language": [], "totals": {}, "files_scanned": 2, "files_skipped": 0, "languages_detected": 1 }, "symbols": [ { "file_path": "src/gitignore.rs", "name": "IgnoreRules", "kind": "types", "line": 51, "end_line": 60 } ]}--by-file adds a by_file array. symbols is present only with --detail;
end_line is what lets a consumer highlight a multi-line declaration rather than
just its first line.
Ignore patterns
Section titled “Ignore patterns”Identical to every other analysis command: repeat --ignore to combine patterns,
and pass --no-gitignore to analyse the tree as it is on disk rather than as the
repository’s own rules describe it.
sephera symbols --path crates --ignore "*.snap" --ignore targetA pattern containing *, ?, or [ is a glob matched against both the file name
and the path relative to the base; anything else is a regex matched against that
relative path.
Defaults from .sephera.toml
Section titled “Defaults from .sephera.toml”symbols reads [project] and [symbols]:
[project]ignore = ["vendor"]
[symbols]format = "json"output = "reports/symbols.json"sephera symbols --path . # writes reports/symbols.jsonsephera symbols --path . --format markdown # a typed flag still winsAn unknown key in that file is an error naming the correction, not a setting that
quietly does nothing. See .sephera.toml.
Progress
Section titled “Progress”--progress takes auto (the default — draw only when standard error is a
terminal), always, or never. The bar goes to standard error, so a captured
report on standard output is unaffected either way. See loc for
the full description.
Related commands
Section titled “Related commands”locmeasures how much code exists; this reports what it declaresgraphresolves what those declarations import, and is the command that answers what breaks if you change onecontextbuilds a pack around a change, using the dependency graph to decide what is near it
Names the tree declares functions, types, enums, constants counted from the parse