expressir 2.1.30 → 2.1.31

data/docs/_guides/cli/validate-schemas.adoc

@@ -0,0 +1,534 @@
+---
+title: Validate Schemas
+parent: CLI Guides
+grand_parent: Guides
+nav_order: 3
+---
+
+== Validate Schemas
+
+=== Purpose
+
+The `validate load` command checks EXPRESS schemas for syntax errors and version
+string compliance. This ensures schemas are well-formed and properly versioned
+before deployment or further processing.
+
+=== References
+
+* link:validate-ascii.html[Validate ASCII Content]
+* link:../../tutorials/parsing-your-first-schema.html[Tutorial: Parsing Your First Schema]
+* link:../../pages/express-language.html[EXPRESS Language Documentation]
+* link:format-schemas.html[Format Schemas]
+
+=== Concepts
+
+Schema validation:: Checking that EXPRESS schema files can be successfully parsed and meet structural requirements
+Version string:: Required metadata in schema declarations identifying the schema version
+Batch validation:: Validating multiple schemas in a single operation
+Schema manifest:: YAML file containing schema definitions that can be validated
+Exit codes:: Command returns 0 for success, 1 for validation failures
+
+=== Basic Usage
+
+==== Validate Single File
+
+[source,bash]
+----
+expressir validate load schema.exp
+----
+
+Output on success:
+[source]
+----
+Validating schema.exp
+Validation passed for all EXPRESS schemas.
+----
+
+Output on failure:
+[source]
+----
+Validating schema.exp
+******************** RESULTS: FAILED TO PARSE ********************
+Failed to parse: schema.exp
+
+******************** RESULTS: MISSING VERSION STRING ********************
+Missing version string: schema `example_schema` | schema.exp
+----
+
+==== Validate Multiple Files
+
+[source,bash]
+----
+# Explicit files
+expressir validate load schema1.exp schema2.exp schema3.exp
+
+# Using wildcards
+expressir validate load schemas/*.exp
+
+# Recursive search
+expressir validate load schemas/**/*.exp
+----
+
+==== Validate from Schema Manifest
+
+[source,bash]
+----
+# Validate all schemas defined in a manifest
+expressir validate load manifest.yaml
+
+# With verbose output
+expressir validate load manifest.yaml --verbose
+----
+
+==== CI/CD Usage
+
+[source,bash]
+----
+# Exit code 0 on success, 1 on failure
+expressir validate load schemas/*.exp
+if [ $? -eq 0 ]; then
+  echo "✓ All schemas valid"
+else
+  echo "✗ Validation failed"
+  exit 1
+fi
+----
+
+=== Command Options
+
+==== Available Options
+
+[options="header"]
+|===
+| Option | Description | Default
+
+| `--verbose`
+| Show detailed processing information
+| false
+
+| `--help`, `-h`
+| Display help message
+| -
+|===
+
+==== Verbose Option
+
+[source,bash]
+----
+expressir validate load schema.exp --verbose
+----
+
+Provides additional output about the validation process, including schema names and structure information.
+
+=== Validation Checks
+
+==== Syntax Validation
+
+The validator checks that schemas can be successfully parsed according to EXPRESS grammar rules:
+
+* **Keywords**: Proper use of EXPRESS keywords
+* **Structure**: Correct entity, type, function declarations
+* **Syntax**: Valid statements, expressions, and references
+* **Encoding**: UTF-8 character encoding
+
+Example of syntax errors detected:
+
+[source,express]
+----
+SCHEMA invalid_schema;
+  ENTITY person
+    name : STRING;  (* Missing semicolon after ENTITY *)
+  END_ENTITY;
+END_SCHEMA;
+----
+
+Validation output:
+[source]
+----
+Failed to parse: invalid_schema.exp
+----
+
+==== Version String Validation
+
+All schemas must include a version declaration:
+
+[source,express]
+----
+SCHEMA example_schema;
+  -- Valid: includes version
+END_SCHEMA; -- example_schema
+----
+
+Missing version:
+[source,express]
+----
+SCHEMA example_schema;
+  (* No version declared *)
+END_SCHEMA;
+----
+
+Validation output:
+[source]
+----
+Missing version string: schema `example_schema` | example_schema.exp
+----
+
+Valid version declaration:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');
+END_SCHEMA;
+----
+
+=== Use Cases
+
+==== Pre-commit Validation
+
+Validate schemas before committing to version control:
+
+[source,bash]
+----
+#!/bin/bash
+# .git/hooks/pre-commit
+
+# Get staged .exp files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.exp$')
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+echo "Validating staged EXPRESS schemas..."
+
+# Validate each staged file
+for file in $STAGED_FILES; do
+  if ! expressir validate load "$file"; then
+    echo "❌ Validation failed for: $file"
+    echo "Please fix validation errors before committing."
+    exit 1
+  fi
+done
+
+echo "✓ All staged schemas are valid"
+----
+
+Make it executable:
+[source,bash]
+----
+chmod +x .git/hooks/pre-commit
+----
+
+==== CI/CD Pipeline Integration
+
+GitHub Actions workflow:
+
+[source,yaml]
+----
+name: Validate Schemas
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.0'
+
+      - name: Install Expressir
+        run: gem install expressir
+
+      - name: Validate all schemas
+        run: |
+          echo "Validating EXPRESS schemas..."
+          if expressir validate load schemas/*.exp; then
+            echo "✓ All schemas valid"
+          else
+            echo "✗ Schema validation failed"
+            exit 1
+          fi
+----
+
+==== Quality Assurance Script
+
+Comprehensive validation script:
+
+[source,bash]
+----
+#!/bin/bash
+# validate-all.sh - Complete schema validation
+
+set -e
+
+SCHEMA_DIR="schemas"
+REPORT_FILE="validation_report.txt"
+
+echo "EXPRESS Schema Validation Report" > "$REPORT_FILE"
+echo "================================" >> "$REPORT_FILE"
+echo "Date: $(date)" >> "$REPORT_FILE"
+echo "" >> "$REPORT_FILE"
+
+# Count total schemas
+TOTAL=$(find "$SCHEMA_DIR" -name "*.exp" | wc -l)
+echo "Total schemas: $TOTAL" >> "$REPORT_FILE"
+echo "" >> "$REPORT_FILE"
+
+# Run validation
+echo "Running validation..." | tee -a "$REPORT_FILE"
+if expressir validate load "$SCHEMA_DIR"/*.exp >> "$REPORT_FILE" 2>&1; then
+  echo "✓ All schemas passed validation" | tee -a "$REPORT_FILE"
+  exit 0
+else
+  echo "✗ Validation failed - see $REPORT_FILE" | tee -a "$REPORT_FILE"
+  exit 1
+fi
+----
+
+==== Batch Validation with Reporting
+
+[source,bash]
+----
+#!/bin/bash
+# validate-with-report.sh
+
+VALID=0
+INVALID=0
+MISSING_VERSION=0
+
+for file in schemas/*.exp; do
+  echo "Checking: $file"
+
+  OUTPUT=$(expressir validate load "$file" 2>&1)
+  STATUS=$?
+
+  if [ $STATUS -eq 0 ]; then
+    echo "  ✓ Valid"
+    ((VALID++))
+  else
+    if echo "$OUTPUT" | grep -q "Failed to parse"; then
+      echo "  ✗ Parse error"
+      ((INVALID++))
+    fi
+    if echo "$OUTPUT" | grep -q "Missing version"; then
+      echo "  ⚠ Missing version"
+      ((MISSING_VERSION++))
+    fi
+  fi
+done
+
+echo ""
+echo "Summary:"
+echo "  Valid: $VALID"
+echo "  Parse errors: $INVALID"
+echo "  Missing version: $MISSING_VERSION"
+
+if [ $INVALID -gt 0 ] || [ $MISSING_VERSION -gt 0 ]; then
+  exit 1
+fi
+----
+
+=== Validation Workflow
+
+==== Development Workflow
+
+[source,bash]
+----
+# 1. Edit schema
+vim my_schema.exp
+
+# 2. Validate
+expressir validate load my_schema.exp
+
+# 3. If valid, format
+expressir format my_schema.exp -o my_schema.exp
+
+# 4. Commit
+git add my_schema.exp
+git commit -m "Add my_schema"
+----
+
+==== Team Workflow
+
+[source,bash]
+----
+# 1. Validate all schemas
+expressir validate load schemas/*.exp
+
+# 2. Fix any errors
+# (edit files as needed)
+
+# 3. Re-validate
+expressir validate load schemas/*.exp
+
+# 4. Proceed with deployment
+./deploy.sh
+----
+
+=== Common Validation Errors
+
+==== Parse Errors
+
+**Missing Semicolon**
+
+[source,express]
+----
+ENTITY person
+  name : STRING;  (* Missing semicolon after entity name *)
+----
+
+**Solution**: Add semicolon after ENTITY declaration:
+[source,express]
+----
+ENTITY person;
+  name : STRING;
+----
+
+**Invalid Keyword**
+
+[source,express]
+----
+ENTITTY person;  (* Typo in keyword *)
+----
+
+**Solution**: Correct the keyword spelling.
+
+**Unclosed Block**
+
+[source,express]
+----
+SCHEMA example;
+  ENTITY person;
+    name : STRING;
+  (* Missing END_ENTITY *)
+END_SCHEMA;
+----
+
+**Solution**: Add missing END_ENTITY.
+
+==== Version String Errors
+
+**Missing Version**
+
+[source,express]
+----
+SCHEMA example_schema;
+  (* No version declared *)
+END_SCHEMA;
+----
+
+**Solution**: Add SCHEMA_VERSION declaration:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');
+END_SCHEMA;
+----
+
+**Invalid Version Format**
+
+While any string is technically valid, use semantic versioning:
+[source,express]
+----
+SCHEMA example_schema;
+  SCHEMA_VERSION('1.0.0');  (* Recommended format *)
+END_SCHEMA;
+----
+
+=== Error Messages
+
+==== Failed to Parse
+
+[source]
+----
+******************** RESULTS: FAILED TO PARSE ********************
+Failed to parse: schema.exp
+----
+
+**Meaning**: The schema file contains syntax errors that prevent parsing.
+
+**Actions**:
+1. Open the file in an editor
+2. Check for common syntax errors
+3. Validate EXPRESS grammar rules
+4. Test with a minimal schema first
+
+==== Missing Version String
+
+[source]
+----
+******************** RESULTS: MISSING VERSION STRING ********************
+Missing version string: schema `example_schema` | schema.exp
+----
+
+**Meaning**: The schema lacks a SCHEMA_VERSION declaration.
+
+**Actions**:
+1. Add SCHEMA_VERSION to the schema
+2. Use semantic versioning format
+3. Document version in project metadata
+
+=== Best Practices
+
+**Validate Before Committing**::
+Always validate schemas before version control operations
++
+[source,bash]
+----
+expressir validate load schema.exp && git commit -m "Update schema"
+----
+
+**Automate Validation**::
+Add validation to CI/CD pipelines
++
+[source,bash]
+----
+# In CI script
+expressir validate load schemas/*.exp || exit 1
+----
+
+**Use Exit Codes**::
+Check validation results programmatically
++
+[source,bash]
+----
+if expressir validate load schema.exp; then
+  echo "Valid - proceeding"
+else
+  echo "Invalid - stopping"
+  exit 1
+fi
+----
+
+**Validate After Format**::
+Ensure formatting didn't introduce errors
++
+[source,bash]
+----
+expressir format schema.exp -o schema.exp
+expressir validate load schema.exp
+----
+
+**Keep Versions Updated**::
+Maintain accurate version strings in all schemas
+
+
+
+=== Next Steps
+
+**Related Commands**::
+* link:validate-ascii.html[Validate ASCII Content] - Check for non-ASCII characters
+* link:format-schemas.html[Format Schemas] - Pretty-print schemas
+* link:coverage-analysis.html[Coverage Analysis] - Check documentation
+
+**Advanced Topics**::
+* link:../ruby-api/parsing-files.html[Ruby API Parsing] - Programmatic validation
+* link:../deployment/ci-cd-setup.html[CI/CD Setup] - Automated workflows
+
+**Quality Assurance**::
+* link:benchmark-performance.html[Benchmark Performance] - Performance testing
+* link:../../tutorials/working-with-multiple-schemas.html[Working with Multiple Schemas]

data/docs/_guides/index.adoc

@@ -0,0 +1,165 @@
+---
+title: Overview
+has_children: true
+nav_order: 1
+---
+
+= Overview
+
+Task-oriented guides that show you how to accomplish specific goals with Expressir. Each guide focuses on a particular aspect or workflow.
+
+== About These Guides
+
+The guides are organized by topic area:
+
+* *CLI* - Command-line interface usage and commands
+* *Ruby API* - Programmatic usage from Ruby code
+* *LER* - Working with LER packages
+* *Manifests* - Managing schema collections with manifests
+* *Changes* - Tracking and managing schema changes
+* *Liquid* - Template integration and documentation generation
+* *Deployment* - Production deployment patterns
+
+== Guide Categories
+
+=== link:../cli/[CLI Guides]
+
+Learn to use Expressir's command-line tools effectively.
+
+*Available guides:*
+
+* link:../cli/format-schemas.html[Formatting Schemas] - Pretty-print and clean schemas
+* link:../cli/validate-schemas.html[Validating Schemas] - Ensure schema correctness
+* link:../cli/benchmark-performance.html[Benchmarking Performance] - Measure and optimize
+* link:../cli/coverage-analysis.html[Coverage Analysis] - Check documentation coverage
+* link:../cli/managing-changes.html[Managing Changes] - Work with change files
+
+---
+
+=== link:../ruby-api/[Ruby API Guides]
+
+Integrate Expressir into your Ruby applications.
+
+*Available guides:*
+
+* link:../ruby-api/parsing-files.html[Parsing Files] - Load EXPRESS schemas
+* link:../ruby-api/working-with-repository.html[Working with Repository] - Navigate schema collections
+* link:../ruby-api/formatting-schemas.html[Formatting Schemas] - Format schemas programmatically
+* link:../ruby-api/search-engine.html[Search Engine] - Use the search API
+
+---
+
+=== link:../ler/[LER Guides]
+
+Work with high-performance LER packages.
+
+*Available guides:*
+
+* link:../ler/creating-packages.html[Creating Packages] - Build LER files
+* link:../ler/loading-packages.html[Loading Packages] - Use pre-built packages
+* link:../ler/querying-packages.html[Querying Packages] - Search and filter
+* link:../ler/validating-packages.html[Validating Packages] - Ensure package integrity
+* link:../ler/package-formats.html[Package Formats] - Choose serialization formats
+
+---
+
+=== link:../manifests/[Manifest Guides]
+
+Manage schema collections with manifests for reproducible builds.
+
+*Available guides:*
+
+* link:../manifests/creating-manifests.html[Creating Manifests] - Generate manifests from root schemas
+* link:../manifests/resolving-manifests.html[Resolving Manifests] - Auto-resolve missing schema paths
+* link:../manifests/validating-manifests.html[Validating Manifests] - Ensure manifest completeness and integrity
+
+---
+
+=== link:../changes/[Changes Guides]
+
+Track and manage schema modifications across versions.
+
+*Available guides:*
+
+* link:../changes/changes-format.html[Changes Format] - Understanding the format
+* link:../changes/validating-changes.html[Validating Changes] - Verify change files
+* link:../changes/importing-eengine.html[Importing from eengine] - Convert eengine XML
+* link:../changes/programmatic-usage.html[Programmatic Usage] - Use changes API
+
+---
+
+=== link:../liquid/[Liquid Guides]
+
+Generate documentation using Liquid templates.
+
+*Available guides:*
+
+* link:../liquid/basic-templates.html[Basic Templates] - Create simple templates
+* link:../liquid/filters-and-tags.html[Filters and Tags] - Use Liquid features
+* link:../liquid/drops-reference.html[Drops Reference] - Access model data
+* link:../liquid/documentation-generation.html[Documentation Generation] - Generate docs
+
+---
+
+=== link:../deployment/[Deployment Guides]
+
+Deploy Expressir in production environments.
+
+*Available guides:*
+
+* link:../deployment/integrating-rails.html[Integrating with Rails] - Use in Rails apps
+* link:../deployment/gem-configuration.html[Gem Configuration] - Configure for production
+* link:../deployment/performance-tuning.html[Performance Tuning] - Optimize for scale
+
+== Using These Guides
+
+=== Guide Format
+
+Each guide follows a structured format:
+
+. *Purpose* - What the guide covers
+. *References* - Related documentation
+. *Concepts* - Key terminology
+. *Instructions* - Step-by-step procedures with examples
+. *Best practices* - Recommended approaches
+. *Troubleshooting* - Common issues and solutions
+
+=== Finding the Right Guide
+
+*If you want to...*
+
+* Use the command-line tools → Start with link:../cli/[CLI Guides]
+* Write Ruby code → Begin with link:../ruby-api/[Ruby API Guides]
+* Work with packages → Explore link:../ler/[LER Guides]
+* Manage schema collections → See link:../manifests/[Manifest Guides]
+* Track changes → Check link:../changes/[Changes Guides]
+* Generate docs → See link:../liquid/[Liquid Guides]
+* Deploy to production → Review link:../deployment/[Deployment Guides]
+
+=== Quick Reference
+
+For quick answers, use the link:../references/[References] section:
+
+* link:../references/cli-commands.html[CLI Commands Reference]
+* link:../references/ruby-api.html[Ruby API Reference]
+* link:../references/data-model/[Data Model Reference]
+
+== Getting Help
+
+If a guide doesn't cover your specific use case:
+
+* Check the link:../tutorials/[Tutorials] for learning-focused content
+* Review the link:../references/[References] for detailed specifications
+* Search https://github.com/lutaml/expressir/issues[GitHub Issues] for similar questions
+* Ask in https://github.com/lutaml/expressir/discussions[GitHub Discussions]
+
+== Contributing
+
+Help improve these guides:
+
+* Report unclear or missing information
+* Suggest new guides for common tasks
+* Share your own usage patterns
+* Submit pull requests with improvements
+
+See the https://github.com/lutaml/expressir/blob/main/CONTRIBUTING.md[Contributing Guide] for details.