Merge #358

358: Create code samples from code, a.k.a. code excerpts r=ahmednfwela a=ahmednfwela

# Pull Request
## What does this PR do?

This PR completely automates updating the code samples file [.code-samples.meilisearch.yaml](https://github.com/meilisearch/meilisearch-dart/blob/main/.code-samples.meilisearch.yaml)
it creates a new PRIVATE `tool` that does 2 things
1. updates the sample file from source code (run by contributors)
2. check if the sample file is up to date with source code (run in CI)

the private tool checks dart files in `lib/` and `test/` directory for lines that follow this pattern:
```dart
// #docregion key
anything()
// #enddocregion
```
where `key` is a key in `.code-samples.meilisearch.yaml`

[This run](https://github.com/meilisearch/meilisearch-dart/actions/runs/6259938891/job/16996958519?pr=358#step:4:158) shows CI fail in action, due to format mismatch for key `search_parameter_guide_show_ranking_score_1` between code file and yaml file.

This commit f9109a0 shows how to fix the failed run, by running `dart run ./tool/bin/meili.dart update-samples` in the root directory of the repo.


this should simplify adding samples, and avoid issues like #357

--- 

## Update

I have also added functionality to detect missing and useless keys, see this failing run for example: https://github.com/meilisearch/meilisearch-dart/actions/runs/6262599763/job/17005143489?pr=358#step:4:159

## PR checklist
WIP
- [ ] remove unnecessary indentations from code.
Please check if your PR fulfills the following requirements:
- [x] Does this PR fix an existing issue, or have you listed the changes applied in the PR description (and why they are needed)?
- [x] Have you read the contributing guidelines?
- [x] Have you made sure that the title is accurate and descriptive of the changes?

Thank you so much for contributing to Meilisearch!


Co-authored-by: Ahmed Fwela <ahmednfwela@bdaya-dev.com>
Co-authored-by: Ahmed Fwela <63286031+ahmednfwela@users.noreply.github.com>

.github/workflows/pre-release-tests.yml

@@ -27,4 +27,4 @@ jobs:
       - name: Meilisearch (${{ env.MEILISEARCH_VERSION }}) setup with Docker
         run: docker run -d -p 7700:7700 getmeili/meilisearch:${{ env.MEILISEARCH_VERSION }} meilisearch --master-key=masterKey --no-analytics
       - name: Run integration tests
-        run: docker run --net="host" -v $PWD:/package -w /package dart:${{ matrix.version }} /bin/sh -c 'dart pub get && dart run test'
+        run: docker run --net="host" -v $PWD:/package -w /package dart:${{ matrix.version }} /bin/sh -c 'dart pub get && dart pub get -C tool && dart run test'

.github/workflows/tests.yml

@@ -41,6 +41,7 @@ jobs:
       - name: Install dependencies
         run: |
           dart pub get
+          dart pub get -C tool
           dart pub global activate coverage
       - name: Run integration tests
         run: dart test --concurrency=4 --reporter=github --coverage=./coverage/reports
@@ -61,7 +62,9 @@ jobs:
     steps:
       - uses: actions/checkout@v3
       - name: Install dependencies
-        run: dart pub get
+        run: |
+          dart pub get
+          dart pub get -C tool
       - name: Run linter
         run: dart analyze --fatal-infos && dart format . --set-exit-if-changed
 
@@ -75,6 +78,19 @@ jobs:
         with:
           config_file: .yamllint.yml
 
+  check-code-samples:
+    name: check .code-samples.meilisearch.yaml
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: dart-lang/setup-dart@v1
+        with:
+          sdk: '3.0.0'
+      - name: check if samples changed
+        run: |
+          dart pub get
+          dart pub get -C tool
+          dart run ./tool/bin/meili.dart update-samples --fail-on-change
   pana:
     runs-on: ubuntu-latest
     timeout-minutes: 10

CONTRIBUTING.md

@@ -9,6 +9,7 @@ First of all, thank you for contributing to Meilisearch! The goal of this docume
     - [Requirements ](#requirements-)
     - [Setup ](#setup-)
     - [Tests and Linter ](#tests-and-linter-)
+    - [Updating code samples](#updating-code-samples)
   - [Git Guidelines](#git-guidelines)
     - [Git Branches ](#git-branches-)
     - [Git Commits ](#git-commits-)
@@ -76,6 +77,31 @@ dart test
 dart analyze
 ```
 
+### Updating code samples
+
+Some PRs require updating the code samples (found in `.code-samples.meilisearch.yaml`), this is done automatically using code excerpts, which are actual pieces of code subject to testing and linting.
+
+A lot of them are placed in `test/code_samples.dart`.
+
+Also most of the tests in that file are skipped, since they are mostly duplicated in other test files.
+
+The process to define a new code sample is as follows:
+1. Add the piece of code in `test/code_samples.dart`
+2. surround it with `#docregion key` and `#enddocregion`, e.g.
+    ```
+    // #docregion meilisearch_contributing_1
+    final client = MeilisearchClient();
+    anything();    
+    // #enddocregion
+    ```
+3. run this command to update the code samples
+    ```bash
+    dart run ./tool/bin/meili.dart update-samples
+    ```
+4. to test if the code samples are updated correctly, run: 
+    ```bash
+    dart run ./tool/bin/meili.dart update-samples --fail-on-change
+    ```
 ## Git Guidelines
 
 ### Git Branches <!-- omit in TOC -->

lib/src/filter_builder/values.dart

@@ -29,8 +29,10 @@ class MeiliDateTimeValueExpression extends MeiliValueExpressionBase {
           "DateTime passed to Meili must be in UTC to avoid inconsistency accross multiple devices",
         );
 
+  /// Unix epoch time is seconds since epoch
   @override
-  String transform() => value.millisecondsSinceEpoch.toString();
+  String transform() =>
+      (value.millisecondsSinceEpoch / 1000).floor().toString();
 
   @override
   bool operator ==(Object other) {