Skip to content

Add semantic diff explainer#25

Closed
orban wants to merge 1 commit intonightshift/bus-factorfrom
feature/semantic-diff
Closed

Add semantic diff explainer#25
orban wants to merge 1 commit intonightshift/bus-factorfrom
feature/semantic-diff

Conversation

@orban
Copy link
Copy Markdown
Owner

@orban orban commented Apr 4, 2026

Summary

  • add scripts/explain_semantic_diff.sh as a dedicated CLI that explains the semantic meaning of a diff per affected Intent node
  • keep the first version shell-native and deterministic offline, with optional Claude-backed enrichment when ANTHROPIC_API_KEY is present
  • add coverage for help, invalid refs, no-change handling, dry-run output, affected-node detection, and representative semantic formatting

Scope

This PR intentionally stays narrow. It does not refactor the agent system or eval harness. Instead it adds a standalone workflow that sits between detect_changes.sh and suggest_updates.sh:

  • detect_changes.sh answers which nodes changed
  • explain_semantic_diff.sh answers what those changes likely mean semantically
  • suggest_updates.sh answers what to write back into nodes

Assumptions / Limitations

  • offline mode uses heuristics, so summaries are directionally useful but not authoritative
  • the Claude path is optional and filters sensitive file diffs before prompting, but it still inherits the usual LLM interpretation risk
  • untracked files are not included, matching the existing git-diff based scripts

Tests

  • ./tests/test_explain_semantic_diff.sh
  • ./tests/test_suggest_updates.sh

Sample Output

# Semantic Diff Explainer

Range: main..HEAD
Changed files: 2

## src/AGENTS.md

Summary: The diff changes executable code in this node and deserves semantic review.
Changed files: 2
Confidence: high

Behavioral impact: Behavior likely changed in code paths covered by this node, not just formatting or comments.
Contract impact: Interfaces, invariants, or caller expectations likely changed and should be reviewed against the node guidance.
Internal-only signal: No clear internal-only signal.

Review focus:
- Re-read the node entry point `src/api.ts` because the main workflow changed.
- Inspect `src/api.ts` for user-visible logic changes and edge-case handling.
- Check whether test updates in `tests/api.test.ts` reflect intended behavior rather than masking a regression.

Nightshift-Task: semantic-diff
Nightshift-Ref: https://github.com/marcus/nightshift
@orban
Copy link
Copy Markdown
Owner Author

orban commented Apr 15, 2026

Superseded by #27 (via #26). Closing to consolidate review on the latest iteration.

@orban orban closed this Apr 15, 2026
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.

1 participant