codeps
Code deps health tracker.
Parses SemanticDB or jdeps output
into the codeps export format,
then emits a flat metrics report:
SCC facts with optional budgeted cut analysis, per-node exposed-surface metrics
(ports/mutPorts/exposure/dependentsPerPublicPort) and declaration-surface
encapsulation —
over the package graph, or the file graph of the packages you select.
Quick start
Your local build already produces everything codeps needs: a compiler with SemanticDB enabled emits
.semanticdb files alongside your compiled classes, and the JDK ships jdeps — codeps just reads
that existing output. No extra tooling to install.
Requires a JDK (11+).
# macOS or Linux (Homebrew)
brew install sake92/tap/codeps
# Scala: compile with SemanticDB enabled
scala-cli compile --server=false --semanticdb -d classes src/
# Configure codeps to read the compiler output, then analyze it
mkdir -p .codeps
cat > .codeps/config.yaml <<'EOF'
projects:
app:
root: .
source: semanticdb
inputs: [classes/META-INF/semanticdb]
skip-tests: true
EOF
codeps status
One status run writes package and file reports when the selected source
supplies file data. See the jdeps setup guide
for Java input.
Other languages
For any other ecosystem, produce the codeps export format
with a tool of your choice (madge, pydeps, go list, ...), configure it as an
export source, then run status — codeps never parses that source code itself:
madge --json src | jq '... shape it into the codeps export format ...' > deps.json
cat > .codeps/config.yaml <<'EOF'
projects:
app:
root: .
source: export
inputs: [deps.json]
EOF
codeps status
The metrics are language-agnostic once the node/edge list carries per-node isExposed/ports/mutPorts
(see the metrics report) —
a TS/Python extractor only has to emit the same generic JSON shape.
Start with bounded findings from the latest cached report, then inspect selected subjects:
codeps findings --project app --limit 10 --format json
codeps inspect-cycle --project app --id scc:com.example.orders
codeps inspect-node --project app --id com.example.orders
Use ids returned by findings and preserve the selected project and scope. Check both
omitted and sourceFindingsOmitted before treating the selection as exhaustive.
The CLI reference covers finding
filters, file scope, and inspection. Cycle-cut analysis is available in the core library;
CLI reports have cutAnalysis.status: notRequested.
Development
Developing codeps itself requires deder (brew install sake92/tap/deder):
deder exec -t test # run all tests
deder exec -t run -m cli status
The website is built with flatmark:
./scripts/build-docs.sh # outputs docs/_site/
Deployed to GitHub Pages on every push to main (see .github/workflows/ghpages.yml).
