ea 0.1.0 → 0.1.4

data/examples/lur_statistics.rb

@@ -0,0 +1,326 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Load local development version
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+# Example: Repository Statistics and Analysis
+#
+# This example demonstrates how to extract and analyze comprehensive
+# statistics from a UML repository, including package structure,
+# class complexity, relationships, and model quality metrics.
+
+require "lutaml"
+require "lutaml/uml_repository"
+require "ea"
+
+puts "=" * 80
+puts "LUR Repository Statistics Examples"
+puts "=" * 80
+puts
+
+# Setup: Find a test file
+qea_file = Dir.glob("examples/qea/*.qea").first
+xmi_file = Dir.glob("examples/qea/*.xmi").first
+test_file = qea_file || xmi_file
+
+unless test_file
+  puts "No test files found in examples/qea/"
+  puts
+  puts "This example demonstrates statistics extraction. To run:"
+  puts "  1. Place a .qea or .xmi file in examples/qea/"
+  puts "  2. Or examine the statistics API below"
+  puts
+  puts "Statistics API example:"
+  puts <<~RUBY
+    repo = Lutaml::UmlRepository::Repository.from_xmi("model.xmi")
+
+    stats = repo.statistics
+
+    # Core counts
+    puts "Packages: \#{stats[:total_packages]}"
+    puts "Classes: \#{stats[:total_classes]}"
+    puts "Associations: \#{stats[:total_associations]}"
+
+    # Stereotypes
+    stats[:classes_by_stereotype].each do |stereotype, count|
+      puts "\#{stereotype}: \#{count}"
+    end
+
+    # Complexity metrics
+    puts "Max attributes: \#{stats[:max_attributes]}"
+    puts "Avg attributes: \#{stats[:avg_attributes]}"
+
+    # Package structure
+    puts "Max package depth: \#{stats[:max_package_depth]}"
+  RUBY
+  exit 0
+end
+
+puts "Loading model: #{test_file}"
+puts "File size: #{File.size(test_file) / 1024}KB"
+puts
+
+# Load repository
+if test_file.end_with?(".qea")
+  document = Ea::Qea.parse(test_file)
+  repo = Lutaml::UmlRepository::Repository.new(document: document)
+elsif test_file.end_with?(".xmi")
+  repo = Lutaml::UmlRepository::Repository.from_xmi(test_file)
+end
+
+puts "Repository loaded successfully"
+puts
+
+# Statistics Section 1: Overview
+puts "=" * 80
+puts "1. Model Overview"
+puts "=" * 80
+
+stats = repo.statistics
+
+puts "Total elements:"
+puts "  Packages:      #{stats[:total_packages]}"
+puts "  Classes:       #{stats[:total_classes]}"
+puts "  Data types:    #{stats[:total_data_types]}"
+puts "  Enumerations:  #{stats[:total_enums]}"
+puts "  Associations:  #{stats[:total_associations]}"
+puts "  Diagrams:      #{stats[:total_diagrams]}"
+puts
+
+# Statistics Section 2: Package Structure
+puts "=" * 80
+puts "2. Package Structure"
+puts "=" * 80
+
+if stats[:max_package_depth]
+  puts "Package hierarchy depth: #{stats[:max_package_depth]}"
+end
+
+packages = repo.packages_index
+if packages.any?
+  puts "Total packages: #{packages.size}"
+  puts "\nSample packages:"
+  packages.first(5).each do |pkg|
+    puts "  - #{pkg.name}"
+  end
+end
+puts
+
+# Statistics Section 3: Class Stereotypes
+puts "=" * 80
+puts "3. Class Stereotypes"
+puts "=" * 80
+
+if stats[:classes_by_stereotype]
+  stereotype_count = stats[:classes_by_stereotype].size
+  puts "Unique stereotypes: #{stereotype_count}"
+  puts "\nStereotype distribution:"
+
+  stats[:classes_by_stereotype].sort_by do |_, count|
+    -count
+  end.first(10).each do |stereotype, count|
+    percentage = (count.to_f / stats[:total_classes] * 100).round(1)
+    puts "  #{stereotype.ljust(30)} #{count.to_s.rjust(5)} (#{percentage}%)"
+  end
+else
+  puts "No stereotype information available"
+end
+puts
+
+# Statistics Section 4: Class Complexity
+puts "=" * 80
+puts "4. Class Complexity Metrics"
+puts "=" * 80
+
+all_classes = repo.classes_index.grep(Lutaml::Uml::UmlClass)
+
+if all_classes.any?
+  # Attribute counts
+  attr_counts = all_classes.map { |c| c.attributes&.size || 0 }
+
+  puts "Attribute statistics:"
+  puts "  Classes with attributes: #{attr_counts.count(&:positive?)}"
+  puts "  Min attributes: #{attr_counts.min}"
+  puts "  Max attributes: #{attr_counts.max}"
+  puts "  Avg attributes: #{(attr_counts.sum.to_f / attr_counts.size).round(2)}"
+  puts "  Median attributes: #{attr_counts.sort[attr_counts.size / 2]}"
+
+  # Find most complex classes
+  puts "\nMost complex classes (by attribute count):"
+  complex_classes = all_classes.map { |c| [c.name, c.attributes&.size || 0] }
+    .sort_by { |_, count| -count }
+    .first(5)
+
+  complex_classes.each do |name, count|
+    puts "  #{name}: #{count} attributes"
+  end
+
+  # Operation counts
+  op_counts = all_classes.map { |c| c.operations&.size || 0 }
+
+  puts "\nOperation statistics:"
+  puts "  Classes with operations: #{op_counts.count(&:positive?)}"
+  puts "  Max operations: #{op_counts.max}"
+  puts "  Avg operations: #{(op_counts.sum.to_f / op_counts.size).round(2)}"
+else
+  puts "No class data available"
+end
+puts
+
+# Statistics Section 5: Inheritance
+puts "=" * 80
+puts "5. Inheritance Analysis"
+puts "=" * 80
+
+if all_classes.any?
+  classes_with_parent = all_classes.select do |c|
+    repo.supertype_of(c)
+  end
+
+  puts "Inheritance statistics:"
+  puts "  Classes with parent: #{classes_with_parent.size}"
+  puts "  Root classes: #{all_classes.size - classes_with_parent.size}"
+  puts "  Inheritance usage: " \
+       "#{(classes_with_parent.size.to_f / all_classes.size * 100).round(1)}%"
+
+  # Find deepest hierarchies
+  max_depth = 0
+  deepest_class = nil
+
+  all_classes.first(100).each do |klass|
+    ancestors = repo.ancestors_of(klass)
+    if ancestors.size > max_depth
+      max_depth = ancestors.size
+      deepest_class = klass
+    end
+  end
+
+  if deepest_class
+    puts "\nDeepest inheritance hierarchy: #{max_depth} levels"
+    puts "  Class: #{deepest_class.name}"
+    ancestors = repo.ancestors_of(deepest_class)
+    puts "  Ancestors: #{ancestors.map(&:name).join(' < ')}"
+  end
+end
+puts
+
+# Statistics Section 6: Associations
+puts "=" * 80
+puts "6. Association Analysis"
+puts "=" * 80
+
+associations = repo.associations_index
+
+if associations.any?
+  puts "Total associations: #{associations.size}"
+
+  # Association types
+  assoc_types = associations.group_by do |a|
+    a.member_end_type&.first || "unknown"
+  end
+
+  puts "\nAssociation types:"
+  assoc_types.sort_by { |_, list| -list.size }.first(10).each do |type, list|
+    puts "  #{type.ljust(20)} #{list.size}"
+  end
+
+  # Most connected classes
+  connection_counts = Hash.new(0)
+
+  all_classes.first(100).each do |klass|
+    assocs = repo.associations_of(klass)
+    connection_counts[klass.name] = assocs.size
+  end
+
+  puts "\nMost connected classes:"
+  connection_counts.sort_by { |_, count| -count }.first(5).each do |name, count|
+    puts "  #{name}: #{count} associations"
+  end
+end
+puts
+
+# Statistics Section 7: Model Quality
+puts "=" * 80
+puts "7. Model Quality Indicators"
+puts "=" * 80
+
+# Run validation
+validation = repo.validate
+
+puts "Validation status: #{validation.valid? ? 'PASS ✓' : 'FAIL ✗'}"
+puts "  Errors: #{validation.errors.size}"
+puts "  Warnings: #{validation.warnings.size}"
+
+if all_classes.any?
+  # Calculate documentation coverage
+  documented_classes = all_classes.count do |c|
+    c.respond_to?(:documentation) && c.documentation && !c.documentation.empty?
+  end
+  doc_coverage = (documented_classes.to_f / all_classes.size * 100).round(1)
+
+  puts "\nDocumentation coverage:"
+  puts "  Documented classes: #{documented_classes}/#{all_classes.size} " \
+       "(#{doc_coverage}%)"
+
+  # Naming conventions
+  camel_case = all_classes.count { |c| c.name =~ /^[A-Z][a-zA-Z0-9]*$/ }
+  naming_compliance = (camel_case.to_f / all_classes.size * 100).round(1)
+
+  puts "\nNaming conventions:"
+  puts "  CamelCase classes: #{camel_case}/#{all_classes.size} " \
+       "(#{naming_compliance}%)"
+
+  # Abstract classes
+  abstract_classes = all_classes.count do |c|
+    c.respond_to?(:is_abstract) && c.is_abstract
+  end
+  abstract_ratio = (abstract_classes.to_f / all_classes.size * 100).round(1)
+
+  puts "\nAbstraction:"
+  puts "  Abstract classes: #{abstract_classes}/#{all_classes.size} " \
+       "(#{abstract_ratio}%)"
+end
+puts
+
+# Statistics Section 8: Export Summary
+puts "=" * 80
+puts "8. Summary Statistics (JSON format)"
+puts "=" * 80
+
+require "json"
+
+summary = {
+  model: {
+    packages: stats[:total_packages],
+    classes: stats[:total_classes],
+    data_types: stats[:total_data_types],
+    enumerations: stats[:total_enums],
+    associations: stats[:total_associations],
+    diagrams: stats[:total_diagrams],
+  },
+  structure: {
+    max_package_depth: stats[:max_package_depth],
+  },
+  validation: {
+    valid: validation.valid?,
+    errors: validation.errors.size,
+    warnings: validation.warnings.size,
+  },
+}
+
+if stats[:classes_by_stereotype]
+  summary[:stereotypes] = stats[:classes_by_stereotype]
+end
+
+puts JSON.pretty_generate(summary)
+puts
+
+puts "=" * 80
+puts "Statistics analysis complete!"
+puts "=" * 80
+puts
+puts "You can also get statistics via CLI:"
+puts "  $ lutaml uml stats model.lur"
+puts "  $ lutaml uml stats model.lur --detailed"
+puts "  $ lutaml uml stats model.lur --format json"

data/examples/qea/README_qea_parser.adoc

@@ -0,0 +1,230 @@
+= QEA Parser - Enterprise Architect Database Parser
+
+A Ruby library for parsing Enterprise Architect .qea (SQLite) database files into structured Ruby objects using Lutaml::Model.
+
+== Overview
+
+This library provides direct parsing of Enterprise Architect `.qea` files (SQLite databases) without requiring XMI export. This provides significant performance improvements and access to EA-specific metadata.
+
+You can:
+
+* Parse QEA files directly to UML documents
+* Access UML model elements (classes, attributes, operations, associations, packages, diagrams)
+* Query and analyze Enterprise Architect models programmatically
+* Build LUR packages for fast querying
+
+== Installation
+
+[source,bash]
+----
+gem install lutaml
+----
+
+== Usage
+
+=== Basic Usage - Parse to UML Document
+
+[source,ruby]
+----
+require "ea/qea"
+
+# Parse QEA file to UML Document
+document = Ea::Qea.parse("model.qea")
+
+# Use with UmlRepository for querying
+repo = Lutaml::UmlRepository::Repository.new(document: document)
+
+# Query the model
+puts "Total classes: #{repo.classes_index.size}"
+puts "Total packages: #{repo.packages_index.size}"
+
+# Find classes by stereotype
+feature_types = repo.find_classes_by_stereotype("featureType")
+puts "Feature types: #{feature_types.size}"
+
+# Get statistics
+stats = repo.statistics
+puts "Packages: #{stats[:total_packages]}"
+puts "Classes: #{stats[:total_classes]}"
+puts "Associations: #{stats[:total_associations]}"
+----
+
+=== Parse with Validation
+
+[source,ruby]
+----
+require "ea/qea"
+
+# Parse with validation
+result = Ea::Qea.parse("model.qea", validate: true)
+
+document = result[:document]
+validation = result[:validation_result]
+
+if validation.valid?
+  puts "Model is valid!"
+else
+  puts "Validation errors: #{validation.errors.size}"
+  validation.errors.first(5).each do |error|
+    puts "  - #{error}"
+  end
+end
+----
+
+=== Low-Level Database Access
+
+[source,ruby]
+----
+require "ea/qea"
+
+# Load database with progress callback
+database = Ea::Qea.load_database("model.qea") do |table, current, total|
+  puts "Loading #{table}: #{current}/#{total}"
+end
+
+# Access raw EA tables
+puts "Objects: #{database.objects.size}"
+puts "Attributes: #{database.attributes.size}"
+puts "Connectors: #{database.connectors.size}"
+puts "Packages: #{database.packages.size}"
+
+# Get statistics
+stats = database.stats
+stats.each do |table_name, count|
+  puts "#{table_name}: #{count} records"
+end
+----
+
+=== Quick Database Info
+
+[source,ruby]
+----
+require "ea/qea"
+
+# Get quick statistics without full loading
+info = Ea::Qea.database_info("model.qea")
+puts info  # => {"objects" => 693, "attributes" => 1910, ...}
+----
+
+== Performance
+
+Direct QEA parsing offers several advantages over XMI:
+
+* *Performance*: 10-20x faster than XMI parsing
+* *No export step*: Parse directly from EA database
+* *EA metadata*: Access to EA-specific information not available in XMI
+* *Memory efficient*: Streams data from SQLite without loading entire file
+
+Typical performance for a 20MB EA model:
+
+* *QEA parsing*: 1-2 seconds
+* *XMI parsing*: 20-40 seconds
+* *Speedup*: 10-20x faster
+* *Memory*: Lower memory footprint with QEA
+
+== CLI Usage
+
+All CLI commands accept both XMI and QEA files:
+
+[source,bash]
+----
+# Build LUR from QEA (10-20x faster than XMI)
+lutaml uml build model.qea -o model.lur
+
+# All other commands work the same
+lutaml uml search model.lur "Building"
+lutaml uml tree model.lur
+lutaml uml stats model.lur
+----
+
+== File Validation
+
+[source,ruby]
+----
+require "ea/qea/file_detector"
+
+# Check if file is valid QEA
+if Ea::Qea::FileDetector.qea_file?("model.qea")
+  puts "Valid QEA file"
+end
+
+# Validate structure
+result = Ea::Qea::FileDetector.validate_qea("model.qea")
+if result[:valid]
+  puts "QEA file is valid"
+else
+  result[:errors].each { |e| puts "ERROR: #{e}" }
+end
+
+# Get file information
+info = Ea::Qea::FileDetector.file_info("model.qea")
+puts "Size: #{info[:size_mb]} MB"
+puts "Tables: #{info[:table_count]}"
+puts "Objects: #{info[:object_count]}"
+----
+
+== Configuration
+
+QEA parsing is configured via `config/qea_schema.yml`:
+
+[source,yaml]
+----
+tables:
+  - table_name: t_object
+    enabled: true
+    model_class: Object
+
+  - table_name: t_attribute
+    enabled: true
+    model_class: Attribute
+
+  # ... other tables
+----
+
+== Database Schema
+
+The QEA parser supports all Enterprise Architect tables:
+
+*Core UML Model:*
+
+* `objects` - UML objects (classes, interfaces, components, etc.)
+* `attributes` - Class attributes and properties
+* `operations` - Class operations and methods
+* `operationparams` - Operation parameters
+* `connectors` - Relationships between objects
+* `packages` - UML packages and namespaces
+* `diagrams` - UML diagrams
+
+*Extended Model:*
+
+* `taggedvalues` - Tagged values (stereotypes, metadata)
+* `stereotypes` - Stereotype definitions
+* `datatypes` - Data type definitions
+* `constraints` - Model constraints
+* And 80+ more tables...
+
+== Examples
+
+See the `examples/` directory for complete working examples:
+
+* `examples/lur_basic_usage.rb` - Basic repository operations with QEA files
+* `examples/lur_cli_workflow.rb` - Command-line workflow with QEA
+* `examples/lur_statistics.rb` - Statistics and validation
+
+== Limitations
+
+* QEA files must be SQLite 3 format
+* Requires EA-specific table structure
+* Some EA proprietary features may not be fully supported
+* Only reads from QEA; does not write back to EA database
+* Read-only access (safe for concurrent use)
+
+== License
+
+This library is part of LutaML and follows the same BSD-3 license.
+
+== Credits
+
+* Built with https://github.com/lutaml/lutaml-model[Lutaml::Model]
+* Uses SQLite3 for database access
+* Part of the LutaML project ecosystem

data/examples/qea_standalone_query.rb

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Standalone QEA loading and querying (no lutaml-uml required).
+#
+# The `ea` gem's core is a standalone Sparx EA QEA parser. You can load a
+# .qea file and query the EA-native data structures directly — useful when
+# you only need EA metadata, statistics, or specific table rows and don't
+# want the UML metamodel in your dependency tree.
+#
+# Run: bundle exec ruby examples/qea_standalone_query.rb
+
+require "bundler/setup"
+require "ea"
+
+QEA_PATH = ENV.fetch(
+  "QEA_PATH",
+  "/Users/mulgogi/src/mn/plateau-model/20251010_current_plateau_v5.1.qea",
+)
+
+abort "QEA not found: #{QEA_PATH}" unless File.exist?(QEA_PATH)
+
+# Load the complete database. Returns an Ea::Qea::Database — an immutable
+# container with lazy-built indexes for O(1) lookups.
+#
+# NOTE: EA objects expose their database primary key as `ea_object_id`, NOT
+# `object_id`. Ruby's built-in `Object#object_id` (memory address) shadows
+# any attribute named `object_id`, so always use `ea_object_id`.
+database = Ea::Qea.load(QEA_PATH)
+
+# Each EA table is exposed as a repository (Enumerable, with find/where/pluck).
+puts "Loaded #{database.total_records} records across #{database.collection_names.size} collections"
+puts
+
+# Example queries ----------------------------------------------------------
+
+# 1. Find a class with attributes inside a real package.
+#    Use `ea_object_id` (the DB primary key), never `object_id`.
+sample = database.objects
+  .select { |o| o.object_type == "Class" && o.name && !o.name.empty? }
+  .select { |o| database.find_package(o.package_id) }
+  .select { |o| database.attributes_for_object(o.ea_object_id).any? }
+  .first
+puts "Sample class: #{sample.name} (ea_object_id=#{sample.ea_object_id})"
+puts
+
+# 2. All connectors for that class
+connectors = database.connectors_for_object(sample.ea_object_id)
+puts "Connectors for #{sample.name}: #{connectors.size}"
+connectors.first(3).each do |c|
+  puts "  type=#{c.connector_type} dest=#{c.destelement.inspect} src=#{c.sourceelement.inspect}"
+end
+puts
+
+# 3. All attributes for that class
+attributes = database.attributes_for_object(sample.ea_object_id)
+puts "Attributes for #{sample.name}: #{attributes.size}"
+attributes.first(3).each { |a| puts "  #{a.name}: #{a.type}" }
+puts
+
+# 4. Tagged values (stereotype properties) for the class
+tags = database.tagged_values_for_element(sample.ea_guid)
+puts "Tagged values for #{sample.name}: #{tags.size}"
+tags.first(3).each { |t| puts "  #{t.property}: #{t.value}" if t.value && !t.value.empty? }
+puts
+
+# 5. Packages hierarchy
+root_packages = database.packages.select { |p| p.parent_id.nil? || p.parent_id.zero? }
+puts "Root packages: #{root_packages.size}"
+root_packages.each do |pkg|
+  children = database.child_packages_for(pkg.package_id)
+  puts "  #{pkg.name} (id=#{pkg.package_id}, #{children.size} children)"
+end

data/examples/qea_to_repository.rb

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: QEA → UML Document → UmlRepository composition.
+#
+# This is the recommended composition pattern for getting from a .qea file to
+# a queryable Lutaml::UmlRepository::Repository. Each gem does one job:
+#
+#   ea                  parses .qea → Lutaml::Uml::Document
+#   lutaml-uml          wraps the Document in a queryable Repository
+#
+# No gem reaches into another at load time. The caller composes.
+#
+# Run: bundle exec ruby examples/qea_to_repository.rb
+
+require "bundler/setup"
+require "ea"
+require "lutaml/uml"
+require "lutaml/uml_repository"
+
+QEA_PATH = ENV.fetch(
+  "QEA_PATH",
+  "/Users/mulgogi/src/mn/plateau-model/20251010_current_plateau_v5.1.qea",
+)
+
+abort "QEA not found: #{QEA_PATH}" unless File.exist?(QEA_PATH)
+
+# Step 1: ea parses the .qea into a UML Document.
+puts "Parsing #{File.basename(QEA_PATH)}..."
+document = Ea::Qea.parse(QEA_PATH)
+puts "  → #{document.class} (#{document.packages.size} root packages)"
+puts
+
+# Step 2: lutaml-uml wraps the document in a queryable repository.
+#   This is composition — no load-time registration, no hidden coupling.
+repo = Lutaml::UmlRepository::Repository.from_document(document)
+puts "Wrapped in #{repo.class}"
+puts
+
+# Step 3: use the repository's query API.
+puts "Repository queries:"
+puts "  total classes: #{repo.all_classes.size}"
+puts "  total diagrams: #{repo.all_diagrams.size}"
+
+# find_class takes a qualified name like "ModelRoot::Pkg::ClassName".
+# Here we just take the first one from the index to demonstrate.
+first_id, first_class = repo.all_classes.first
+if first_class
+  puts
+  puts "Sample class from repository: #{first_class.respond_to?(:name) ? first_class.name : first_id}"
+end