Implement unused-relation diagnostics lint rule

[leynos]

Summary

• Adds a comprehensive ExecPlan document for implementing the unused-relation diagnostics lint rule. The plan outlines the contract, constraints, tolerances, risks, progress tracking, decision log, and verification gates to guide future implementation on top of the existing Sempai architecture.

Changes

• New file added: docs/execplans/4-1-1-implement-unused-relation-diagnostics.md
  • Contains detailed plan sections: Purpose, Constraints, Tolerances, Risks, Progress, Surprises & Discoveries, Decision Log, Outcomes & Retrospective, and a staged plan (Stage 0 through Stage 6).
  • Documents expected behavior (one diagnostic per unused declaration, diagnostic shape aligned with stable Sempai diagnostics, source-order emission, and declaration-span targeting).
  • Outlines prerequisite requirements (semantic analysis substrate, rule-runner/catalog surface) and gating approach.
  • Provides concrete verification steps and gate commands to run once prerequisites exist.

Rationale

• Establishes a canonical, repeatable plan for implementing the unused-relation lint in a repository that currently has stubbed engine surfaces and no semantic analysis yet. Ensures alignment with existing diagnostic contracts and ensures future work is well-scoped and testable.

Plan of work (high-level)

• Stage 0: Prerequisite audit and route selection
  • Confirm semantic-analysis module exists for resolved relations and usage sites.
  • Locate lint catalog/rule-runner registration surface.
  • Verify public DiagnosticReport pathways for semantic diagnostics.
• Stage 1: Lock the contract in tests first
  • Add diagnostic code coverage, JSON snapshot tests, and a BDD scenario outlining the unused-relation contract.
  • Prepare semantic-lint unit tests and behavior tests to accompany prerequisites.
• Stage 2: Extend the diagnostic contract, not the schema
  • Add a new stable diagnostic code (e.g., E_SEMPAI_UNUSED_RELATION) and ensure serde/Display behavior stays compatible with the existing contract.
• Stage 3: Implement the semantic rule
  • Implement logic to detect declared-but-unused relations using resolved symbol data, emit at most one diagnostic per declaration, and sort by source order.
• Stage 4: Wire the rule into the lint catalog and public surface
  • Register the rule with the catalog/rule runner and ensure the public compile path surfaces diagnostics.
• Stage 5: Documentation and roadmap reconciliation
  • Update relevant docs to reflect final behavior and ensure roadmap alignment.
• Stage 6: Verification and evidence capture
  • Run fmt, lint, tests, and full gates as described in the plan.

Verification / Test plan

• The ExecPlan specifies the required tests and gates, including:
  • Unit tests for the new diagnostic code and serialization shape.
  • JSON snapshot tests for diagnostics.
  • Behavior/BDD tests at the semantic and facade levels once the prerequisite substrate exists.
  • Full workspace gates (fmt, markdownlint, nixie, check-fmt, lint, test) as part of verification.
• Currently, this PR adds planning scaffolding. Actual implementation will follow Stage 0 and rely on the prerequisite semantic-analysis components.

Notes

• The plan assumes the existence of a semantic-analysis crate and a lint catalog surface in a future branch. If prerequisites are not present, Stage 0 is a hard stop until the required substrate is merged.
• The plan emphasizes keeping the stable diagnostic contract intact and avoiding schema changes in this milestone.

◳ Generated by DevBoxer ◰

---

ℹ️ Tag @devboxerhub to ask questions and address PR feedback

📎 Task: https://www.devboxer.com/task/ad6124ee-1841-45a3-a7e1-115315fba15c

Summary by Sourcery

Documentation:

• Document the intended behaviour, constraints, risks, staged implementation plan, and verification strategy for the future unused-relation semantic lint rule.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 83b5a4d5-a23a-4059-b5f0-ab7e1f2b5e3e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch implement-unused-relation-lint-x5jvb3

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Adds a new ExecPlan documentation file that defines a staged, test-first implementation strategy for an unused-relation semantic lint rule in Sempai, including constraints, risks, decision log, and concrete verification/gating steps without changing any Rust code yet.

Sequence diagram for compilation with unused-relation diagnostics

sequenceDiagram
  actor Developer
  participant Engine
  participant Parser
  participant Normalizer
  participant SemanticAnalyzer
  participant LintCatalog
  participant UnusedRelationRule
  participant DiagnosticReport

  Developer->>Engine: compile_yaml(config)
  Engine->>Parser: parse(input)
  Parser-->>Engine: ast

  Engine->>Normalizer: normalize(ast)
  Normalizer-->>Engine: normalized_ast

  Engine->>SemanticAnalyzer: analyze_relations(normalized_ast)
  SemanticAnalyzer->>LintCatalog: run_lints(resolved_relations, usage_sites)

  LintCatalog->>UnusedRelationRule: check_unused_relations(resolved_relations, usage_sites)
  UnusedRelationRule-->>LintCatalog: unused_relation_diagnostics

  LintCatalog-->>SemanticAnalyzer: semantic_lint_diagnostics
  SemanticAnalyzer-->>Engine: semantic_diagnostics

  Engine->>DiagnosticReport: build(diagnostics)
  DiagnosticReport-->>Developer: json_with_unused_relation_diagnostics

Loading

File-Level Changes

Change	Details	Files
Introduce an ExecPlan document outlining the staged implementation strategy and verification plan for the unused-relation diagnostics lint rule.	Document expected observable behavior and diagnostic contract for the unused-relation lint, including schema, span targeting, and source-order emission. Define constraints, tolerances, and risks around semantic prerequisites, diagnostic schema stability, roadmap alignment, and repository limits. Lay out a multi-stage plan (prerequisite audit, test-first contract locking, semantic rule implementation, catalog wiring, documentation updates, and verification) with explicit go/no-go gates and success criteria. Record current repository context, surprises, and decision log to guide how and where future semantic and lint code should be added.	docs/execplans/4-1-1-implement-unused-relation-diagnostics.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.