decoupage_administratif 0.1.0

data/data/regions.json

@@ -0,0 +1,28 @@
+[
+{"code":"01","chefLieu":"97105","nom":"Guadeloupe","typeLiaison":3,"zone":"drom"},
+{"code":"02","chefLieu":"97209","nom":"Martinique","typeLiaison":3,"zone":"drom"},
+{"code":"03","chefLieu":"97302","nom":"Guyane","typeLiaison":3,"zone":"drom"},
+{"code":"04","chefLieu":"97411","nom":"La Réunion","typeLiaison":0,"zone":"drom"},
+{"code":"06","chefLieu":"97611","nom":"Mayotte","typeLiaison":0,"zone":"drom"},
+{"code":"11","chefLieu":"75056","nom":"Île-de-France","typeLiaison":1,"zone":"metro"},
+{"code":"24","chefLieu":"45234","nom":"Centre-Val de Loire","typeLiaison":2,"zone":"metro"},
+{"code":"27","chefLieu":"21231","nom":"Bourgogne-Franche-Comté","typeLiaison":0,"zone":"metro"},
+{"code":"28","chefLieu":"76540","nom":"Normandie","typeLiaison":0,"zone":"metro"},
+{"code":"32","chefLieu":"59350","nom":"Hauts-de-France","typeLiaison":4,"zone":"metro"},
+{"code":"44","chefLieu":"67482","nom":"Grand Est","typeLiaison":2,"zone":"metro"},
+{"code":"52","chefLieu":"44109","nom":"Pays de la Loire","typeLiaison":4,"zone":"metro"},
+{"code":"53","chefLieu":"35238","nom":"Bretagne","typeLiaison":0,"zone":"metro"},
+{"code":"75","chefLieu":"33063","nom":"Nouvelle-Aquitaine","typeLiaison":3,"zone":"metro"},
+{"code":"76","chefLieu":"31555","nom":"Occitanie","typeLiaison":1,"zone":"metro"},
+{"code":"84","chefLieu":"69123","nom":"Auvergne-Rhône-Alpes","typeLiaison":1,"zone":"metro"},
+{"code":"93","chefLieu":"13055","nom":"Provence-Alpes-Côte d'Azur","typeLiaison":0,"zone":"metro"},
+{"code":"94","chefLieu":"2A004","nom":"Corse","typeLiaison":0,"zone":"metro"},
+{"code":"975","chefLieu":"97502","nom":"Saint-Pierre-et-Miquelon","typeLiaison":0,"zone":"com"},
+{"code":"977","chefLieu":"97701","nom":"Saint-Barthélemy","typeLiaison":0,"zone":"com"},
+{"code":"978","chefLieu":"97801","nom":"Saint-Martin","typeLiaison":0,"zone":"com"},
+{"code":"984","chefLieu":"97502","nom":"Terres australes et antarctiques françaises","typeLiaison":0,"zone":"com"},
+{"code":"986","chefLieu":"98613","nom":"Wallis et Futuna","typeLiaison":0,"zone":"com"},
+{"code":"987","chefLieu":"98735","nom":"Polynésie française","typeLiaison":0,"zone":"com"},
+{"code":"988","chefLieu":"98818","nom":"Nouvelle-Calédonie","typeLiaison":0,"zone":"com"},
+{"code":"989","chefLieu":"98901","nom":"Île de Clipperton","typeLiaison":0,"zone":"com"}
+]

data/lib/decoupage_administratif/base_model.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  module BaseModel
+    # Find a single record by its code (primary key equivalent)
+    # @param code [String] the code to search for
+    # @return [Object, nil] the element with the given code, or nil if not found
+    # @raise [NotFoundError] if the record is not found and no default block is given
+    # @example
+    #   DecoupageAdministratif::Commune.find('72039')
+    #   DecoupageAdministratif::Region.find('52')
+    def find(code)
+      result = find_by(code: code)
+      raise DecoupageAdministratif::NotFoundError, "#{name.split('::').last} not found for code #{code}" if result.nil?
+
+      result
+    end
+
+    # @param criteria [Hash] a hash with the attributes to filter by
+    # @return [untyped] the element that matches the criteria
+    # @example
+    #   DecoupageAdministratif::Commune.find_by(nom: 'Paris')
+    def find_by(criteria)
+      all.find { |item| criteria.all? { |k, v| item.send(k) == v } }
+    end
+
+    # @param args [Hash] keyword arguments containing filter criteria and options
+    # @option args [Boolean] :case_insensitive perform case-insensitive matching
+    # @option args [Boolean] :partial allow partial string matching (contains)
+    # @return [Array] an array of all items that match the criteria
+    # @example
+    #   DecoupageAdministratif::Departement.where(code_region: '52')
+    #   DecoupageAdministratif::Commune.where(nom: 'pari', case_insensitive: true, partial: true)
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def where(**args)
+      # Separate options from criteria
+      case_insensitive = args.delete(:case_insensitive) || false
+      partial = args.delete(:partial) || false
+
+      all.select do |item|
+        args.all? do |key, value|
+          item_value = item.send(key)
+
+          if case_insensitive && value.is_a?(String) && item_value.is_a?(String)
+            if partial
+              item_value.downcase.include?(value.downcase)
+            else
+              item_value.downcase == value.downcase
+            end
+          elsif partial && value.is_a?(String) && item_value.is_a?(String)
+            item_value.include?(value)
+          else
+            item_value == value
+          end
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    end
+  end
+end

data/lib/decoupage_administratif/commune.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Commune
+    extend BaseModel
+    include TerritoryExtensions
+
+    # @!attribute [r] code
+    #   @return [String] INSEE code of the commune
+    # @!attribute [r] nom
+    #   @return [String] Name of the commune
+    # @!attribute [r] zone
+    #   @return [String] Zone of the commune ("metro", "drom", "com")
+    # @!attribute [r] region_code
+    #   @return [String] INSEE code of the region
+    # @!attribute [r] departement_code
+    #   @return [String] INSEE code of the department
+    # @!attribute [r] commune_type
+    #   @return [Symbol] Type of the commune. Possible values:
+    #     - :commune_actuelle: Standard current commune
+    #     - :commune_deleguee: Delegated commune
+    #     - :commune_associee: Associated commune
+    #   @note Default value is :commune_actuelle
+    attr_reader :code, :nom, :zone, :region_code, :departement_code, :commune_type
+
+    # rubocop:disable Metrics/ParameterLists
+    # @param code [String] the INSEE code of the commune
+    # @param nom [String] the name of the commune
+    # @param zone [String] the zone of the commune ("metro", "drom", "com")
+    # @param region_code [String] the INSEE code of the region
+    # @param departement_code [String] the INSEE code of the department
+    # @param commune_type [Symbol] the type of the commune (default: :commune_actuelle)
+    def initialize(code:, nom:, zone:, region_code:, departement_code:, commune_type: :commune_actuelle)
+      @code = code
+      @nom = nom
+      @zone = zone
+      @region_code = region_code
+      @departement_code = departement_code
+      @commune_type = commune_type
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # @return [Array<Commune>] a collection of all communes
+    def self.all
+      @all ||= Parser.new('communes').data.map do |commune_data|
+        Commune.new(
+          code: commune_data["code"],
+          nom: commune_data["nom"],
+          zone: commune_data["zone"],
+          region_code: commune_data["region"],
+          departement_code: commune_data["departement"],
+          commune_type: commune_data["type"]&.gsub("-", "_")&.to_sym
+        )
+      end
+    end
+
+    # @return [Array<Commune>] a collection of all communes _actuelles_
+    def self.actuelles
+      @actuelles ||= where(commune_type: :commune_actuelle)
+    end
+
+    # @raise [NotFoundError] if no region is found for the code
+    # @return [Region] the region of the commune
+    def region
+      @region ||= DecoupageAdministratif::Region.find(@region_code)
+    end
+
+    # @raise [NotFoundError] if no department is found for the code
+    # @return [Departement] the department of the commune
+    def departement
+      @departement ||= DecoupageAdministratif::Departement.find(@departement_code)
+    end
+
+    # @return [Epci, nil] the EPCI of the commune, if it belongs to one
+    def epci
+      found_epci = DecoupageAdministratif::Epci.all.find do |epci|
+        epci.membres.any? { |m| m["code"] == @code }
+      end
+      found_epci.is_a?(DecoupageAdministratif::Epci) ? (@epci ||= found_epci) : nil
+    end
+  end
+end

data/lib/decoupage_administratif/config.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Config
+    class << self
+      # @return [String] the directory where data files are stored
+      def data_directory
+        @data_directory ||= determine_data_directory
+      end
+
+      # @param path [String] the path to set as data directory
+      attr_writer :data_directory
+
+      # @return [String] the directory where embedded data files are stored
+      def embedded_data_directory
+        @embedded_data_directory ||= File.join(gem_root, 'data')
+      end
+
+      # @return [String] the root directory of the gem
+      def gem_root
+        @gem_root ||= File.expand_path('../..', __dir__)
+      end
+
+      private
+
+      def determine_data_directory
+        ENV['DECOUPAGE_DATA_DIR'] ||
+          user_data_directory ||
+          fallback_directory
+      end
+
+      def user_data_directory
+        return nil unless Dir.home
+
+        File.join(Dir.home, '.local', 'share', 'decoupage_administratif')
+      end
+
+      def fallback_directory
+        if defined?(Rails) && Rails.respond_to?(:root)
+          Rails.root.join('tmp', 'decoupage_administratif').to_s
+        else
+          File.join(Dir.tmpdir, 'decoupage_administratif')
+        end
+      end
+    end
+  end
+end

data/lib/decoupage_administratif/departement.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Departement
+    extend BaseModel
+    include TerritoryExtensions
+    # @!attribute [r] code
+    #   @return [String] INSEE code of the department
+    # @!attribute [r] nom
+    #   @return [String] Name of the department
+    # @!attribute [r] zone
+    #   @return [String] Zone of the department ("metro", "drom", "com")
+    # @!attribute [r] code_region
+    #   @return [String] INSEE code of the region
+    attr_reader :code, :nom, :zone, :code_region
+
+    # @param code [String] the INSEE code of the department
+    # @param nom [String] the name of the department
+    # @param zone [String] the zone of the department ("metro", "drom", "com")
+    # @param code_region [String] the INSEE code of the region
+    def initialize(code:, nom:, zone:, code_region:)
+      @code = code
+      @nom = nom
+      @zone = zone
+      @code_region = code_region
+    end
+
+    # @return [Array<Departement>] a collection of all departments
+    def self.all
+      @all ||= Parser.new('departements').data.map do |departement_data|
+        DecoupageAdministratif::Departement.new(
+          code: departement_data["code"],
+          nom: departement_data["nom"],
+          zone: departement_data["zone"],
+          code_region: departement_data["region"]
+        )
+      end
+    end
+
+    # @return [Array<Commune>] a collection of all actual communes in the department
+    def communes
+      @communes ||= DecoupageAdministratif::Commune.where(departement_code: @code, commune_type: :commune_actuelle)
+    end
+
+    # @raise [NotFoundError] if no region is found for the code
+    # @return [Region] the region of the department
+    def region
+      @region ||= DecoupageAdministratif::Region.find(@code_region)
+    end
+  end
+end

data/lib/decoupage_administratif/epci.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Epci
+    extend BaseModel
+    include TerritoryExtensions
+
+    # @!attribute [r] code
+    #   @return [String] SIREN code of the EPCI
+    # @!attribute [r] nom
+    #   @return [String] Name of the EPCI
+    # @!attribute [r] membres
+    #   @return [Array<Hash>] Members of the EPCI, each member is a hash with "nom" and "code" keys
+    attr_reader :code, :nom, :membres
+
+    # @param code [String] the SIREN code of the EPCI
+    # @param nom [String] the name of the EPCI
+    # @param membres [Array<Hash>] the members of the EPCI, each member is a hash with "nom" and "code" keys
+    def initialize(code:, nom:, membres: [])
+      @code = code
+      @nom = nom
+      @membres = membres
+    end
+
+    # @return [Array<Epci>] a collection of all EPCI
+    def self.all
+      Parser.new('epci').data.map do |epci_data|
+        Epci.new(
+          code: epci_data["code"],
+          nom: epci_data["nom"],
+          membres: epci_data["membres"].map { |membre| membre.slice("nom", "code") }
+        )
+      end
+    end
+
+    # Search for an EPCI that includes all the specified codes
+    # @param codes [Array<String>] an array of commune codes
+    # @return [Array<Epci>] a collection of EPCI that include all the specified codes
+    def self.search_by_communes_codes(codes)
+      all.select do |epci|
+        epci.membres.map do |m|
+          codes.include?(m['code'])
+        end.all?
+      end
+    end
+
+    # @return [Array<Commune>] a collection of all communes that are members of the EPCI
+    # @raise [NotFoundError] if a commune code is not found
+    def communes
+      @communes ||= @membres.map do |membre|
+        DecoupageAdministratif::Commune.find(membre["code"])
+      end.compact
+    end
+
+    # @return [Array<Region>] an array of regions that the EPCI communes belong to
+    # Sometimes an EPCI can have communes from different regions.
+    def regions
+      @regions ||= communes.map(&:region).uniq
+    end
+  end
+end

data/lib/decoupage_administratif/parser.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module DecoupageAdministratif
+  class Parser
+    # @!attribute [r] data
+    #   @return [Array<Hash>] Parsed data from the JSON file for the given model
+    attr_reader :data
+
+    # @param model [String] the name of the model to parse (e.g., 'communes', 'departements', 'regions')
+    # @return [Parser] a new Parser instance
+    # @note Only expected model names should be used to avoid loading unwanted files. The file path is constructed from the model name.
+    def initialize(model)
+      @model = model
+      @file_path = File.join(DecoupageAdministratif::Config.data_directory, "#{@model}.json")
+      load_data
+    end
+
+    private
+
+    def load_data
+      file = File.read(@file_path)
+      @data = JSON.parse(file)
+    rescue Errno::ENOENT
+      # Try to load from embedded data if external file not found
+      @file_path = File.join(DecoupageAdministratif::Config.embedded_data_directory, "#{@model}.json")
+      begin
+        file = File.read(@file_path)
+        @data = JSON.parse(file)
+      rescue Errno::ENOENT
+        raise Error,
+              "File #{@file_path} does not exist. You can update the data with 'rake decoupage_administratif:update'"
+      rescue JSON::ParserError
+        raise Error, "File #{@model}.json is not valid JSON"
+      end
+    rescue JSON::ParserError
+      raise Error, "File #{@model}.json is not valid JSON"
+    end
+  end
+end

data/lib/decoupage_administratif/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'rails'
+
+module DecoupageAdministratif
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load 'tasks/install.rake'
+    end
+  end
+end

data/lib/decoupage_administratif/region.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Region
+    extend BaseModel
+    include TerritoryExtensions
+
+    # @!attribute [r] code
+    #   @return [String] INSEE code of the region
+    # @!attribute [r] nom
+    #   @return [String] Name of the region
+    # @!attribute [r] zone
+    #   @return [String] Zone of the region ("metro", "drom", "com")
+    attr_reader :code, :nom, :zone
+
+    # @param code [String] the INSEE code of the region
+    # @param nom [String] the name of the region
+    # @param zone [String] the zone of the region ("metro", "drom", "com")
+    def initialize(code:, nom:, zone:)
+      @code = code
+      @nom = nom
+      @zone = zone
+    end
+
+    # @return [Array<Region>] a collection of all regions
+    def self.all
+      @all ||= Parser.new('regions').data.map do |region_data|
+        Region.new(
+          code: region_data["code"],
+          nom: region_data["nom"],
+          zone: region_data["zone"]
+        )
+      end
+    end
+
+    # @return [Array<Departement>] a collection of all departments in the region
+    def departements
+      @departements ||= DecoupageAdministratif::Departement.all.select do |departement|
+        departement.code_region == @code
+      end
+    end
+
+    # @return [Array<Commune>] a collection of all actual communes in the region
+    def communes
+      @communes ||= DecoupageAdministratif::Commune.all.select do |commune|
+        commune.region_code == @code && commune.commune_type == :commune_actuelle
+      end
+    end
+  end
+end

data/lib/decoupage_administratif/search.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  class Search
+    # @!attribute [r] codes
+    #   @return [Array<String>, nil] List of INSEE codes used for the search
+    # @!attribute [r] regions
+    #   @return [Array<Region>] Regions found by the search
+    # @!attribute [r] departements
+    #   @return [Array<Departement>] Departments found by the search
+    # @!attribute [r] epcis
+    #   @return [Array<Epci>] EPCIs found by the search
+    # @!attribute [r] communes
+    #   @return [Array<Commune>] Communes found by the search
+    attr_reader :codes, :regions, :departements, :epcis, :communes
+
+    def initialize(codes = nil)
+      @codes = codes&.uniq
+      initialize_class_caches
+    end
+
+    # Search for territories by municipality.
+    # If the list of municipalities represents a department or an EPCI, the corresponding territories are displayed.
+    # If the codes do not correspond to any territory, a list of municipalities is returned.
+    # @return [Hash] a hash containing the regions, departments, EPCI, and communes found
+    # @note Returns empty arrays if no territories are found for the given codes.
+    def by_insee_codes
+      @codes = group_by_departement
+      @codes = find_communes_by_codes
+
+      search_for_departements
+      search_for_region
+      search_for_epcis
+      search_for_communes
+
+      {
+        regions: @regions,
+        departements: @departements,
+        epcis: @epcis,
+        communes: @communes
+      }
+    end
+
+    # Return the territories associated with a given INSEE code.
+    # @param code_insee [String] the INSEE code of the commune
+    # @return [Hash] a hash containing the EPCI, department, and region associated with the commune
+    def find_territories_by_commune_insee_code(code_insee)
+      # Use cache if available, fallback to find_by for compatibility with tests
+      commune = @@communes_cache&.[](code_insee) || DecoupageAdministratif::Commune.find_by(code: code_insee)
+      return {} if commune.nil?
+
+      {
+        epci: commune.epci,
+        departement: commune.departement,
+        region: commune.region
+      }
+    end
+
+    private
+
+    # Class-level caches for performance optimization
+    # rubocop:disable Style/ClassVars
+    @@departements_cache = nil
+    @@communes_cache = nil
+    # rubocop:enable Style/ClassVars
+
+    # Initialize class-level caches for performance optimization
+    # @return [void]
+    def initialize_class_caches
+      return if @@departements_cache && @@communes_cache
+
+      # rubocop:disable Style/ClassVars
+      @@departements_cache = DecoupageAdministratif::Departement.all.each_with_object({}) { |dept, hash| hash[dept.code] = dept }
+      @@communes_cache = DecoupageAdministratif::Commune.actuelles.each_with_object({}) { |commune, hash| hash[commune.code] = commune }
+      # rubocop:enable Style/ClassVars
+    end
+
+    # Group the codes by department.
+    # @return [Hash<Departement, Array<Commune>>] Hash with departments as keys and their communes as values
+    def group_by_departement
+      # Group the codes by DecoupageAdministratif::Departement
+      # and DecoupageAdministratif::Communes as values
+      @codes.group_by do |code|
+        dept_code = code[0..1] == "97" ? code[0..2] : code[0..1]
+        @@departements_cache[dept_code]
+      end
+    end
+
+    # Find communes by their codes.
+    # @return [Array<Commune>] List of communes matching the codes
+    def find_communes_by_codes
+      @codes.transform_values do |codes_insee|
+        codes_insee.filter_map do |code|
+          commune = @@communes_cache[code]
+          next if commune.nil?
+
+          commune.commune_type == :commune_actuelle ? commune : nil
+        end
+      end
+    end
+
+    # Search for departments matching the codes.
+    # @return [void]
+    def search_for_departements
+      @departements = []
+      return if only_nil_key?
+
+      departements_to_delete = []
+      @codes.each do |departement, communes|
+        next unless should_add_departement?(departement, communes)
+
+        @departements << departement
+        departements_to_delete << departement
+      end
+      departements_to_delete.each { |dep_code| @codes.delete(dep_code) }
+    end
+
+    # Check if only one key and it is nil
+    # @return [Boolean]
+    def only_nil_key?
+      @codes.keys.uniq.count == 1 && @codes.keys.first.nil?
+    end
+
+    # Should add departement to result?
+    # @param departement [Departement, nil]
+    # @param communes [Array<Commune>]
+    # @return [Boolean]
+    def should_add_departement?(departement, communes)
+      return false if departement.nil?
+
+      departement.communes.count == communes.count && departement.communes.map(&:code).sort == communes.map(&:code).sort
+    end
+
+    # Search for regions matching the codes.
+    # @return [void]
+    def search_for_region
+      @regions = []
+      return if @departements.empty?
+
+      regions = DecoupageAdministratif::Region.all
+      regions.each do |region|
+        next unless region.departements.all? do |departement|
+          @departements.map(&:code).include? departement.code
+        end
+
+        @regions << region
+        region.departements.each do |departement|
+          @departements.delete(departement)
+        end
+      end
+    end
+
+    # Search for EPCIs matching the codes.
+    # @return [void]
+    def search_for_epcis
+      @epcis = []
+      return if @codes.keys.uniq.count == 1 && @codes.keys.first.nil?
+
+      @codes.each_value do |communes|
+        # Find EPCIs that match all communes in the current group
+        @epcis = DecoupageAdministratif::Epci.search_by_communes_codes(communes.map(&:code))
+        @epcis.each do |epci|
+          communes.reject! do |commune|
+            epci.communes.include?(commune)
+          end
+        end
+      end
+    end
+
+    # Search for communes matching the codes.
+    # @return [void]
+    def search_for_communes
+      @communes = []
+      return if @codes.keys.uniq.count == 1 && @codes.keys.first.nil?
+
+      @codes.each_value do |communes|
+        communes.map { |commune| @communes << commune }
+      end
+    end
+  end
+end

data/lib/decoupage_administratif/territory_extensions.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module DecoupageAdministratif
+  module TerritoryExtensions
+    # Check if this territory intersects with a list of commune INSEE codes
+    # @param commune_insee_codes [Array<String>] array of commune INSEE codes to check against
+    # @return [Boolean] true if territory intersects with any of the provided codes
+    def territory_intersects_with_insee_codes?(commune_insee_codes)
+      territory_strategy.intersects_with_insee_codes?(commune_insee_codes)
+    end
+
+    # Get commune INSEE codes for this territory
+    # @return [Array<String>] array of commune INSEE codes covered by this territory
+    def territory_insee_codes
+      @territory_insee_codes ||= territory_strategy.insee_codes
+    end
+
+    private
+
+    def territory_strategy
+      @territory_strategy ||= case self.class.name.split('::').last
+                              when 'Commune'
+                                TerritoryStrategies::CommuneStrategy.new(self)
+                              when 'Departement'
+                                TerritoryStrategies::DepartementStrategy.new(self)
+                              when 'Region'
+                                TerritoryStrategies::RegionStrategy.new(self)
+                              when 'Epci'
+                                TerritoryStrategies::EpciStrategy.new(self)
+                              else
+                                raise NotImplementedError, "Territory strategy not implemented for #{self.class.name}"
+                              end
+    end
+  end
+end