1	<?php
2
3	declare(strict_types=1);
4
5	/**
6	* This file is part of fast-forward/dev-tools.
7	*
8	* This source file is subject to the license bundled
9	* with this source code in the file LICENSE.
10	*
11	* @copyright Copyright (c) 2026 Felipe Sayão Lobato Abreu <github@mentordosnerds.com>
12	* @license   https://opensource.org/licenses/MIT MIT License
13	*
14	* @see       https://github.com/php-fast-forward/dev-tools
15	* @see       https://github.com/php-fast-forward
16	* @see       https://datatracker.ietf.org/doc/html/rfc2119
17	*/
18
19	namespace FastForward\DevTools\GitIgnore;
20
21	/**
22	* Defines the contract for merging .gitignore entries.
23	*
24	* This service SHALL combine canonical and project-specific .gitignore
25	* definitions into a single normalized result. The resulting entry list MUST
26	* exclude blank lines and comment lines from the merged output, MUST remove
27	* duplicate entries, and MUST group directory entries before file entries.
28	* Directory and file groups SHALL be sorted independently in ascending string
29	* order to provide deterministic output.
30	*/
31	interface MergerInterface
32	{
33	/**
34	* Merges two GitIgnore instances, removing duplicates and sorting entries.
35	*
36	* Directories are placed before files in the resulting list.
37	* The path from $project is used in the returned instance.
38	*
39	* @param GitIgnoreInterface $canonical the canonical .gitignore from dev-tools
40	* @param GitIgnoreInterface $project the project-specific .gitignore
41	*
42	* @return GitIgnoreInterface a new GitIgnore instance with merged entries
43	*/
44	public function merge(GitIgnoreInterface $canonical, GitIgnoreInterface $project): GitIgnoreInterface;
45	}