From 1a3acb7ca5dc03b2cf8577ab0c0bb0e20d006c9d Mon Sep 17 00:00:00 2001 From: gabrielmoro Date: Sun, 14 Jun 2026 20:14:41 -0300 Subject: [PATCH] Add SKILL documents for various project tasks and update project documentation --- .../skills/documentation-review/SKILL.md | 55 ++++++++++++++ .opencode/skills/generate-tests/SKILL.md | 37 +++++++++ .../skills/minimum-requirements/SKILL.md | 34 +++++++++ .opencode/skills/release-notes/SKILL.md | 67 ++++++++++++++++ .../skills/validate-architecture/SKILL.md | 53 +++++++++++++ AGENTS.md | 76 +++++++++++++++++++ README.md | 6 ++ doc/1-getting-started.md | 6 ++ opencode.json | 7 ++ 9 files changed, 341 insertions(+) create mode 100644 .opencode/skills/documentation-review/SKILL.md create mode 100644 .opencode/skills/generate-tests/SKILL.md create mode 100644 .opencode/skills/minimum-requirements/SKILL.md create mode 100644 .opencode/skills/release-notes/SKILL.md create mode 100644 .opencode/skills/validate-architecture/SKILL.md create mode 100644 AGENTS.md create mode 100644 opencode.json diff --git a/.opencode/skills/documentation-review/SKILL.md b/.opencode/skills/documentation-review/SKILL.md new file mode 100644 index 0000000..3f9d71e --- /dev/null +++ b/.opencode/skills/documentation-review/SKILL.md @@ -0,0 +1,55 @@ +--- +name: documentation-review +description: Validate project documentation matches actual implementation +--- + +When invoked: + +1. Scan all documentation: + ```text + doc/**/*.md + README.md + ``` + +2. Validate links: + + ### Internal + - For each markdown link to a file (e.g., `[text](some/path.md)`), verify the referenced file exists. + - For anchor links (e.g., `[text](#section)`), verify the target section heading exists in the file. + + ### External + - For URLs (e.g., `https://...`), verify they are reachable (HTTP 200). + +3. Verify configuration examples match actual project configuration: + + ### Dart Package + - Cross-check `pubspec.yaml` snippets in docs against actual `pubspec.yaml`. + - Verify `analysis_options.yaml` examples match the real file. + - Verify installation instructions (`dev_dependencies:` snippets) match the current package name and version convention. + - Verify CLI run command (`dart run eagle_eye:main`) is accurate. + - Verify JSON configuration examples (`eagle_eye_config.json`) match the actual rule engine. + +4. Verify documented APIs exist: + - Check that all referenced public Dart APIs, classes, and functions exist in `lib/`. + +5. Verify setup instructions are accurate: + - Cross-check `README.md` setup steps against actual build files (`pubspec.yaml`, `analysis_options.yaml`). + +6. Verify release instructions are still valid: + - Check `CHANGELOG.md` and `pubspec.yaml` version consistency. + +7. Report findings: + + ### Errors + - Broken internal links + - Broken external URLs + - Configuration examples that don't match real files + - Non-existent APIs referenced in docs + + ### Warnings + - Outdated version references + - Missing sections or incomplete documentation + - Deprecated feature references + + ### Suggestions + - Recommended improvements to clarity or completeness diff --git a/.opencode/skills/generate-tests/SKILL.md b/.opencode/skills/generate-tests/SKILL.md new file mode 100644 index 0000000..9158e8f --- /dev/null +++ b/.opencode/skills/generate-tests/SKILL.md @@ -0,0 +1,37 @@ +--- +name: generate-tests +description: Generate tests following project conventions +--- + +When invoked: + +1. Detect testing framework: + - Read `pubspec.yaml` `dev_dependencies:` for `test` (Dart `package:test`). + - If `flutter_test` is found, classify as Flutter widget tests. + - This project uses `package:test` (`^1.31.1`). + +2. Analyze existing tests in `test/`: + - Read existing test files to determine naming conventions. + - Note the use of `test()`, `group()`, `expect()` patterns. + - Observe file naming (`*_test.dart` suffix). + - Observe directory structure mirroring `lib/`. + +3. Follow current naming conventions: + - File names: `_test.dart` matching `.dart` in `lib/`. + - Test names: descriptive strings, typically lowercase with spaces. + - Use `group()` for logical grouping. + - Use `test()` for individual test cases. + - Use `expect(actual, matcher)` for assertions. + +4. Generate unit tests for: + - Public API classes and functions in `lib/`. + - Edge cases (null inputs, empty collections, invalid patterns). + - Error paths (exceptions, validation failures). + +5. Generate integration tests when applicable: + - End-to-end CLI execution tests. + - Config file loading and parsing. + +6. Ensure generated tests use the project's assertion style and test architecture: + - Match existing `package:test` conventions. + - Use the same matchers and patterns found in existing tests. diff --git a/.opencode/skills/minimum-requirements/SKILL.md b/.opencode/skills/minimum-requirements/SKILL.md new file mode 100644 index 0000000..3a55b43 --- /dev/null +++ b/.opencode/skills/minimum-requirements/SKILL.md @@ -0,0 +1,34 @@ +--- +name: minimum-requirements +description: Determine minimum requirements to consume the library +--- + +When invoked: + +1. Detect project type: + - Check `pubspec.yaml` for `name:` and `environment:` fields to confirm Dart Package. + - If `flutter:` dependency exists in `pubspec.yaml`, classify as Flutter Package. + +2. Inspect dependency declarations: + - Read `pubspec.yaml` — specifically the `environment:` section. + +3. Determine minimum supported versions: + + ### Dart Package + - Read `environment.sdk` from `pubspec.yaml` (e.g., `^3.8.0`). + - Parse the minimum SDK version from the constraint. + + ### Flutter Package + - Read `environment.sdk` and `environment.flutter` from `pubspec.yaml`. + - Parse the minimum Flutter and Dart versions. + +4. Create or update a section called `## Minimum Requirements` inside `README.md`. + + Example output: + ```md + ## Minimum Requirements + + ### Dart Package + + - Dart 3.8+ + ``` diff --git a/.opencode/skills/release-notes/SKILL.md b/.opencode/skills/release-notes/SKILL.md new file mode 100644 index 0000000..9744af8 --- /dev/null +++ b/.opencode/skills/release-notes/SKILL.md @@ -0,0 +1,67 @@ +--- +name: release-notes +description: Generate release notes and prepare the next release +--- + +When invoked: + +1. Detect current version from `pubspec.yaml`: + - Read the `version:` field (e.g., `2.0.2`). + +2. Get the latest Git tag: + ```bash + git tag --sort=-v:refname | head -1 + ``` + +3. Analyze unreleased changes: + ```bash + git log ..HEAD --oneline + ``` + +4. Categorize commits by conventional commit type: + + | Category | Keywords | + |----------|----------| + | Major | `breaking`, `BREAKING CHANGE` | + | Minor | `feat`, `feature` | + | Patch | `fix`, `docs`, `chore`, `refactor`, `test`, `changelog` | + +5. Determine next semantic version based on the highest category found. + +6. Update version in `pubspec.yaml`: + - Replace the `version:` field with the new version. + +7. Create or update `CHANGELOG.md`: + - Add a new section at the top: + + ```md + ## X.Y.Z + + ### Features + + - Added ... + + ### Fixes + + - Fixed ... + + ### Documentation + + - Updated ... + ``` + +8. Generate a release summary with: + - New version number + - Number of commits by category + - Key changes + +9. Prompt the user to: + ```bash + git commit -m "Bump version to X.Y.Z" + git tag vX.Y.Z + git push && git push --tags + ``` + +10. Verify publishing metadata: + - Confirm `pubspec.yaml` has `homepage`, `description`, and valid `version`. + - No sensitive or private packages (check for `publish_to: none`). diff --git a/.opencode/skills/validate-architecture/SKILL.md b/.opencode/skills/validate-architecture/SKILL.md new file mode 100644 index 0000000..d888603 --- /dev/null +++ b/.opencode/skills/validate-architecture/SKILL.md @@ -0,0 +1,53 @@ +--- +name: validate-architecture +description: Verify architectural consistency and dependency rules +--- + +When invoked: + +1. Detect project structure: + - Analyze `lib/` directory layout. + - Identify internal packages and subdirectories (`analyzer/`, `data/`, `model/`, `util/`). + - Note the `bin/` entry point. + +2. Analyze dependencies between modules: + - Map which `lib/` subdirectories import from which others. + - Track imports across package boundaries. + +3. Verify architecture rules for Dart packages: + + ### Package boundaries + - Public API should be minimal and intentional. + - Internal implementation details should not be exposed. + - Files outside `lib/` (e.g., `bin/`, `test/`) should not be imported by `lib/`. + + ### Layer separation + - `lib/model/` should have minimal dependencies (ideally none on other layers). + - `lib/data/` may depend on `model/` but not on `analyzer/` or `util/`. + - `lib/analyzer/` may depend on `model/` and `util/`. + - `lib/util/` should be independent of other layers. + - `bin/main.dart` should only depend on the public API entry point. + +4. Detect: + + ### Violations + - Cyclic dependencies between packages/modules. + - Forbidden dependencies (e.g., data layer importing analyzer). + - Unused modules or files. + - Internal implementation leaks (private files imported externally). + + ### Warnings + - Overly broad exports. + - Files with too many dependencies. + - Modules with unclear responsibilities. + +5. Produce a report with: + + ### Violations + Critical issues that break architectural rules. + + ### Warnings + Potential issues or code smells. + + ### Recommendations + Suggested improvements for the module structure and dependency graph. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..d84085f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,76 @@ +# EagleEye + +## Project Overview + +EagleEye is a Dart CLI tool for detecting architecture violations in Dart projects. It analyzes Dart project files against configurable architectural rules to enforce dependency boundaries and layering. + +- **Library type:** Dart Package (CLI tool) +- **Primary language:** Dart ^3.8.0 +- **Runtime/platform:** Dart CLI +- **Repository:** https://github.com/CodandoTV/eagle-eye +- **Documentation:** https://codandotv.github.io/eagle-eye/ + +## Build System + +- **Dart SDK constraint:** ^3.8.0 (defined in `pubspec.yaml:7`) +- **Dependencies defined in:** `pubspec.yaml` +- **Build and release commands:** + - `dart pub get` — Install dependencies + - `dart analyze` — Static analysis + - `dart test` — Run tests + - `dart run eagle_eye:main` — Run the CLI tool locally + - `dart pub publish` — Publish to pub.dev + +## Project Structure + +``` +bin/ + main.dart — CLI entry point +lib/ + analyzer/ — Core analysis engine + checker/ — Rule checkers + data/ — Data access layer + model/ — Domain models + exceptions/ — Custom exceptions + util/ — Utilities +test/ + analyzer/ — Analyzer tests + checker/ — Rule checker tests + model/ — Model tests +doc/ — MkDocs documentation source + index.md — Documentation home + img/ — Documentation images +example/ + README.md — Example usage guide +``` + +## Version Management + +- **Version:** Defined in `pubspec.yaml` under the `version` field +- Current version: `2.0.2` + +## Documentation + +- **Generator:** MkDocs +- **Configuration:** `mkdocs.yml` +- **Source directory:** `doc/` +- **Theme:** Material for MkDocs +- **Live site:** https://codandotv.github.io/eagle-eye/ + +## Distribution + +- **pub.dev package URL:** https://pub.dev/packages/eagle_eye +- **Package name:** `eagle_eye` + +## Git Workflow + +- **Default branch:** `main` +- **Release process:** + 1. Update version in `pubspec.yaml` + 2. Update `CHANGELOG.md` + 3. Commit changes + 4. Tag with `vX.Y.Z` + 5. Push commits and tags + 6. Publish to pub.dev (`dart pub publish`) +- **Git tag strategy:** `vX.Y.Z` (e.g., `v2.0.2`) +- **Versioning strategy:** Semantic Versioning (SemVer) diff --git a/README.md b/README.md index 613fb34..81da279 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,12 @@ 📚 Check our documentation [here](https://codandotv.github.io/eagle-eye/). +## Minimum Requirements + +### Dart Package + +- Dart 3.8+ + --- ## Features diff --git a/doc/1-getting-started.md b/doc/1-getting-started.md index b4b7f17..bb3ef16 100644 --- a/doc/1-getting-started.md +++ b/doc/1-getting-started.md @@ -1,5 +1,11 @@ # Getting started 🚀 +## Minimum Requirements + +- **Dart SDK:** ^3.8.0 + +--- + ## 1. Define rules !!! warning "Deprecated - Only available before v2.0.0" diff --git a/opencode.json b/opencode.json new file mode 100644 index 0000000..61966d8 --- /dev/null +++ b/opencode.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://opencode.ai/config.json", + "instructions": ["AGENTS.md"], + "skills": { + "paths": [".opencode/skills"] + } +}