1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* Fast Forward Development Tools for PHP projects.
7	*
8	* This file is part of fast-forward/dev-tools project.
9	*
10	* @author   Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
11	* @license  https://opensource.org/licenses/MIT MIT License
12	*
13	* @see      https://github.com/php-fast-forward/
14	* @see      https://github.com/php-fast-forward/dev-tools
15	* @see      https://github.com/php-fast-forward/dev-tools/issues
16	* @see      https://php-fast-forward.github.io/dev-tools/
17	* @see      https://datatracker.ietf.org/doc/html/rfc2119
18	*/
19
20	namespace FastForward\DevTools\Changelog\Checker;
21
22	/**
23	* Verifies that the changelog contains meaningful unreleased changes.
24	*
25	* This is used to prevent merging changes that have not been documented in the changelog.
26	* It compares the unreleased entries in the changelog against the current branch or a specified reference (e.g., a base branch or commit hash).
27	*/
28	interface UnreleasedEntryCheckerInterface
29	{
30	/**
31	* Checks if there are pending unreleased entries in the changelog compared to a given reference.
32	*
33	* This method MUST read the unreleased section of the changelog and compare it against the changes in the current branch or a specified reference.
34	* If there are entries in the unreleased section that are not present in the reference, it indicates that there are pending changes that have not been released yet.
35	* The method MUST return true if there are pending unreleased entries, and false otherwise.
36	*
37	* @param string $file the changelog file path, relative to the working directory or absolute
38	* @param string|null $againstReference The reference to compare against (e.g., a branch or commit hash).
39	*
40	* @return bool true if there are pending unreleased entries, false otherwise
41	*/
42	public function hasPendingChanges(string $file, ?string $againstReference = null): bool;
43	}