chore: setup agents.md

[luxass]

Summary by CodeRabbit

• Documentation

  • Added comprehensive architecture guide and workflow diagrams documenting release scripts patterns, service architecture, and core workflows (verify, prepare, publish).

• New Features

  • Verify workflow now includes drift detection to identify mismatches between expected and actual package versions, with enhanced commit status reporting.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Caution

Review failed

The pull request is closed.

📝 Walkthrough

Walkthrough

This pull request introduces comprehensive documentation for the @ucdjs/release-scripts project, including an architecture guide, diagram conventions documentation, and seven Mermaid diagrams visualizing service dependencies, workflows (verify, prepare, publish), and algorithms. Additionally, it implements drift detection logic in the verify workflow and adds a setCommitStatus method to GitHubService.

Changes

Cohort / File(s)	Summary
Architecture & Diagram Documentation AGENTS.md, docs/diagrams/README.md	Introduces comprehensive architecture guide covering Effect-TS patterns, service descriptions, core workflows, configuration, and technology stack; documents Mermaid diagram usage, color conventions, and contribution guidelines.
Workflow Diagrams docs/diagrams/verify-workflow.mmd, docs/diagrams/prepare-workflow.mmd, docs/diagrams/publish-workflow.mmd	Visualizes three core workflows with multi-service interactions, including phases for package discovery, commit processing, version calculation, dependency graph analysis, and publication with error handling paths.
Design & Algorithm Diagrams docs/diagrams/service-dependency-graph.mmd, docs/diagrams/package-lifecycle.mmd, docs/diagrams/commit-attribution-flow.mmd, docs/diagrams/version-bump-calculation.mmd	Depicts system architecture, package state machine lifecycle, commit attribution logic with mode handling, and version bump calculation flowchart.
GitHub Service Enhancement src/services/github.service.ts	Adds setCommitStatus(sha, status) method to post commit status updates to GitHub API; wraps with error handling via GitHubError.
Verify Workflow Implementation src/verify.ts	Implements drift detection between release branch and expected package versions using semver range validation for workspace dependencies; logs outcomes and updates commit status; fails if drift detected.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• refactor: rewrite in effect #15: Concurrent Effect-based rewrite refactoring the same services (GitService, GitHubService, WorkspaceService, DependencyGraphService, VersionCalculatorService, PackageUpdaterService) into an Effect service layer—this PR documents and extends that architecture.

Poem

🐰 Hop, hop, diagrams flow!
Services dance in Mermaid's glow,
Drift detected, all now know,
Release scripts steal the show! ✨

✨ Finishing touches

• 📝 Generate docstrings

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 9a08ecf and 72e87d8.

📒 Files selected for processing (11)

• AGENTS.md
• docs/diagrams/README.md
• docs/diagrams/commit-attribution-flow.mmd
• docs/diagrams/package-lifecycle.mmd
• docs/diagrams/prepare-workflow.mmd
• docs/diagrams/publish-workflow.mmd
• docs/diagrams/service-dependency-graph.mmd
• docs/diagrams/verify-workflow.mmd
• docs/diagrams/version-bump-calculation.mmd
• src/services/github.service.ts
• src/verify.ts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[greptile-apps]

Greptile Summary

Added comprehensive architecture documentation (AGENTS.md) with 8 Mermaid diagrams documenting the release automation system. Implemented drift detection in verify workflow to identify mismatches between expected and actual package versions/dependencies on release branches, with enhanced commit status reporting to GitHub.

Confidence Score: 5/5

• This PR is safe to merge with no risk
• Changes are purely documentation additions and feature enhancements with well-structured code following existing patterns
• No files require special attention

Important Files Changed

Filename	Overview
AGENTS.md	Added comprehensive 900+ line architecture documentation covering services, workflows, diagrams, and patterns
docs/diagrams/README.md	Added diagram directory README with viewing order, color coding conventions, and usage instructions
docs/diagrams/verify-workflow.mmd	Added sequence diagram documenting verify workflow with drift detection, commit status reporting
src/verify.ts	Implemented drift detection logic to compare expected vs actual versions and dependency ranges, plus commit status reporting
src/services/github.service.ts	Added setCommitStatus method to post commit statuses to GitHub API

Sequence Diagram

sequenceDiagram
    actor Developer
    participant PR as Pull Request #16
    participant Docs as Documentation
    participant Code as Source Code
    participant Verify as Verify Workflow
    participant GitHub as GitHub API

    Developer->>Docs: Create AGENTS.md (900+ lines)
    Note over Docs: Architecture guide with<br/>services, workflows, patterns
    
    Developer->>Docs: Add 8 Mermaid diagrams
    Note over Docs: verify, prepare, publish workflows<br/>service deps, commit attribution<br/>version calc, package lifecycle

    Developer->>Docs: Create diagrams/README.md
    Note over Docs: Viewing order, color coding<br/>usage instructions

    Developer->>Code: Implement drift detection
    Note over Code: src/verify.ts

    Code->>Code: Add snapshotPackageJson()
    Note over Code: Read package.json from<br/>release branch HEAD

    Code->>Code: Add findDrift()
    Note over Code: Compare expected vs actual<br/>versions & dependencies

    Code->>Code: Add satisfiesRange()
    Note over Code: Validate dependency ranges<br/>with semver

    Developer->>Code: Add setCommitStatus()
    Note over Code: src/services/github.service.ts

    Code->>GitHub: POST /repos/:owner/:repo/statuses/:sha
    Note over GitHub: Report success/failure<br/>of verification

    Developer->>PR: Commit changes
    
    Note over Verify: New capabilities enabled
    Verify->>Verify: Detect version mismatches
    Verify->>Verify: Detect dependency range issues
    Verify->>Verify: Detect missing package.json
    Verify->>GitHub: Set commit status
    
    PR-->>Developer: Ready for review

Loading