Skip to content

entity-level-git: refresh for sem 0.27, re-verify Dart - #216

Merged
alycda merged 2 commits into
mainfrom
claude/entity-git-mermaid
Oct 16, 2026
Merged

alycda merged 2 commits into
mainfrom
claude/entity-git-mermaid

Conversation

@alycda

@alycda alycda commented Oct 14, 2026

Copy link
Copy Markdown
Owner

Homebrew core's sem-cli now ships 0.27.0; the skill was written against
0.25.0. Built v0.27.0 from source and re-ran the skill's claims on a
synthetic repo holding a two-file Dart program and its TypeScript twin.

What changed underneath the skill:

  • 0.27 folded the verbs: callers/refs/context/entities became
    find --callers|--refs|--context|--in, log/blame became
    history [--blame], setup/update/telemetry moved under sem config,
    login/review/xref under sem cloud. Old spellings still work, so the
    allowlist keeps both and adds history.
  • 0.26 fixed Dart call resolution (upstream #491). The skill's headline
    Dart warning ("0 edges, a green 'No other entities are affected'")
    no longer reproduces: constructor and typed-receiver calls resolve
    exactly as in the TS twin, and what stays unresolved (an untyped
    receiver) is unresolved in TS too. Re-verified synthetically only;
    the section says to confirm on DittoXCactus before relying on it.
  • Caller answers now carry an INCOMPLETE verdict and a possible-callers
    list instead of a green check. That list is where cross-language name
    matches still surface, labelled as unresolved.
  • New sem certify <range>: local, read-only review certificate, with
    --arch --view and a self-contained --html page (no external
    resources; checked in the v0.27.0 source and rendered). Allowlisted.
  • New sem check runs the project's checkers and tests. Deliberately
    NOT allowlisted: it executes repo code.

preferred-tooling.md's compact table moves to the new spellings and
points at sem certify for "where's the risk".

Co-Authored-By: Claude Opus 5.5 [email protected]
Claude-Session: https://claude.ai/code/session_01MaMS38L5A67twbVeiRpQjn

Homebrew core's sem-cli now ships 0.27.0; the skill was written against
0.25.0. Built v0.27.0 from source and re-ran the skill's claims on a
synthetic repo holding a two-file Dart program and its TypeScript twin.

What changed underneath the skill:
- 0.27 folded the verbs: callers/refs/context/entities became
  `find --callers|--refs|--context|--in`, log/blame became
  `history [--blame]`, setup/update/telemetry moved under `sem config`,
  login/review/xref under `sem cloud`. Old spellings still work, so the
  allowlist keeps both and adds `history`.
- 0.26 fixed Dart call resolution (upstream #491). The skill's headline
  Dart warning ("0 edges, a green 'No other entities are affected'")
  no longer reproduces: constructor and typed-receiver calls resolve
  exactly as in the TS twin, and what stays unresolved (an untyped
  receiver) is unresolved in TS too. Re-verified synthetically only;
  the section says to confirm on DittoXCactus before relying on it.
- Caller answers now carry an INCOMPLETE verdict and a possible-callers
  list instead of a green check. That list is where cross-language name
  matches still surface, labelled as unresolved.
- New `sem certify <range>`: local, read-only review certificate, with
  `--arch --view` and a self-contained `--html` page (no external
  resources; checked in the v0.27.0 source and rendered). Allowlisted.
- New `sem check` runs the project's checkers and tests. Deliberately
  NOT allowlisted: it executes repo code.

preferred-tooling.md's compact table moves to the new spellings and
points at `sem certify` for "where's the risk".

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MaMS38L5A67twbVeiRpQjn
Prompted by humanlayer's show-me skill, which renders code as pseudocode,
call trees and Mermaid. Its diagrams come from the model reading the code,
so an invented edge looks exactly as authoritative as a real one. This
skill already has the real graph; what it lacked was a rendering. The
rule: every node and edge comes from sem output.

scripts/sem-mermaid.py (stdlib python3, already in core-packages) takes
nodes from `sem impact --json` and edges from `sem graph --json`,
filtered to that node set. Edges come from the graph rather than impact
because impact's JSON gives each entity's depth but not which entity it
was reached through, so depth-2 arrows drawn from impact alone would be
guesses. Possible callers are drawn dotted and labelled `unresolved`.
INCOMPLETE reasons and "no test reaches" go into `%%` comments.

It refuses rather than mislead:
- exit 2 when the graph has no edges in the target's *language* (not the
  repo): an empty graph drawn as a diagram reads as "nothing depends on
  this", the false negative Dart used to produce. Verified on a mixed repo
  where TS has edges and a Python file has none.
- exit 3 above --max-nodes (default 20) instead of silently dropping nodes.
- Cross-language possible callers are dropped and counted, since sem 0.27
  matches unresolved names across languages (a Dart caller listed for a TS
  method). Extensions are grouped into families so JS->TS and .c->.h survive.

Verified against sem 0.27.0 on the synthetic TS + Dart repo; both
diagrams parsed and rendered by Mermaid 11.4.1 in headless Chromium.
The skill's new section also covers the cases where Mermaid is the wrong
tool: a diff-shaped entity tree for "what changed" (no edges, nothing to
invent) and `sem certify --html` for module-level architecture.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01MaMS38L5A67twbVeiRpQjn
@github-actions

Copy link
Copy Markdown
Contributor

⊕ Entity-level changes

tools/agents/preferred-tooling.md

Status Type Name
Δ heading Entity-level git: sem, weave, inspect

tools/agents/skills/entity-level-git/SKILL.md

Status Type Name
Δ preamble (preamble)
- heading a wildcard would pre-approve sem setup/login/cloud/update and weave setup,
+ heading a wildcard would pre-approve `sem config setup
- heading which the body says never to run unprompted - the permission prompt is the
- heading backstop for those rules, so the allowlist must not remove it. Also excluded:
+ heading weave setup, which the body says never to run unprompted - the permission
+ heading prompt is the backstop for those rules, so the allowlist must not remove it.
+ heading sem check is left out too: it runs the project's test suite and checkers,
+ heading which is executing the repo's code, not reading it. Also excluded:
Δ heading exist only from 0.5.x, so on an older weave they simply do not resolve.
+ heading sem 0.27 renamed callers/refs/context/entities to find flags and log/blame
+ heading to history; both spellings are listed because the old ones still work.
+ heading sem certify only reads the repo and writes to stdout (its temp trees are
+ heading its own), checked in the v0.27.0 source.
Δ heading Availability and fallback
- heading Language coverage: Dart/Flutter (verified 2026-09-21)
+ heading Language coverage: Dart/Flutter (verified 2026-09-21; sem re-verified 2026-10-14)
Δ heading sem — entity diffs, blame, impact
+ heading Drawing it — Mermaid from sem's graph, never from reading code
Δ heading Choosing between them

exist only from 0.5.x, so on an older weave they simply do not resolve.

- # exist only from 0.5.x, so on an older weave they simply do not resolve.
- allowed-tools: Bash(sem diff *), Bash(sem impact *), Bash(sem callers *), Bash(sem refs *), Bash(sem find *), Bash(sem blame *), Bash(sem log *), Bash(sem entities *), Bash(sem graph *), Bash(sem context *), Bash(weave preview *), Bash(weave summary *), Bash(weave explain *), Bash(weave check *), Bash(inspect diff *), Bash(inspect predict *), Bash(inspect pr *), Bash(inspect file *), Bash(git status), Bash(git log *), Bash(git diff *)
- ---
+ # exist only from 0.5.x, so on an older weave they simply do not resolve.

tools/agents/skills/entity-level-git/scripts/pycache/sem-mermaid.cpython-313.pyc

Status Type Name
B file tools/agents/skills/entity-level-git/scripts/pycache/sem-mermaid.cpython-313.pyc [binary added]

tools/agents/skills/entity-level-git/scripts/sem-mermaid.py

Status Type Name
+ orphan module-level
+ function sem
+ orphan module-level
+ function family
+ function label
+ function main
+ orphan module-level

Summary: 18 added, 6 modified, 4 deleted, 1 binary across 4 files (3 added orphans)

functions and classes, not lines · sem

@alycda
alycda merged commit 8d9cf8d into main Oct 16, 2026
3 checks passed
@alycda
alycda deleted the claude/entity-git-mermaid branch October 16, 2026 09:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants