|
| 1 | +# MDClasses Repository Instructions |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +MDClasses is a Java library for reading and analyzing metadata from 1C:Enterprise 8 platform. The library works with configurations exported in XML format (via configurator or merge/comparison tools) or in EDT format. |
| 6 | + |
| 7 | +**Project Type**: Java library |
| 8 | +**Build Tool**: Gradle with Kotlin DSL |
| 9 | +**Primary Language**: Java 21+ |
| 10 | +**Target Runtime**: JVM (Java 21, 25 tested) |
| 11 | +**Repository Size**: Medium-sized Java project with extensive test coverage |
| 12 | + |
| 13 | +## Build and Test Instructions |
| 14 | + |
| 15 | +### Prerequisites |
| 16 | +- Java 21 or higher (tested on Java 21, and 25) |
| 17 | +- Git with LFS support for test data |
| 18 | +- No additional environment setup required |
| 19 | + |
| 20 | +### Bootstrap and Build Commands |
| 21 | + |
| 22 | +**Always initialize Git submodules and LFS when cloning:** |
| 23 | +```bash |
| 24 | +git submodule update --init --recursive |
| 25 | +git lfs pull |
| 26 | +``` |
| 27 | + |
| 28 | +**Build the project:** |
| 29 | +```bash |
| 30 | +./gradlew build |
| 31 | +``` |
| 32 | + |
| 33 | +**Run tests only:** |
| 34 | +```bash |
| 35 | +./gradlew test |
| 36 | +``` |
| 37 | + |
| 38 | +**Run quality checks (includes tests and code quality):** |
| 39 | +```bash |
| 40 | +./gradlew check |
| 41 | +``` |
| 42 | + |
| 43 | +**Generate Javadoc:** |
| 44 | +```bash |
| 45 | +./gradlew javadoc |
| 46 | +``` |
| 47 | + |
| 48 | +**Run all precommit checks:** |
| 49 | +```bash |
| 50 | +./gradlew precommit |
| 51 | +``` |
| 52 | +This runs tests and updates license headers. |
| 53 | + |
| 54 | +**Update license headers:** |
| 55 | +```bash |
| 56 | +./gradlew updateLicenses |
| 57 | +``` |
| 58 | + |
| 59 | +**Clean build artifacts:** |
| 60 | +```bash |
| 61 | +./gradlew clean |
| 62 | +``` |
| 63 | + |
| 64 | +### Build Notes |
| 65 | +- The build uses Gradle wrapper (`./gradlew` on Unix, `gradlew.bat` on Windows) |
| 66 | +- Always use the wrapper to ensure consistent Gradle version |
| 67 | +- Test results are located in `build/reports/tests/test/` |
| 68 | +- JaCoCo coverage reports are in `build/reports/jacoco/test/` |
| 69 | +- Build time: typically 1-2 minutes for full build with tests |
| 70 | + |
| 71 | +### Common Build Issues |
| 72 | +- If tests fail due to missing test data, ensure Git LFS is properly initialized |
| 73 | +- Lombok annotations are used extensively - IDE should have Lombok plugin installed |
| 74 | +- If seeing "out of memory" errors, set `org.gradle.jvmargs=-Xmx2048m` in `gradle.properties` |
| 75 | + |
| 76 | +## Project Structure |
| 77 | + |
| 78 | +### Key Directories |
| 79 | +- `src/main/java/` - Main source code |
| 80 | + - `com/github/_1c_syntax/bsl/reader/` - Core readers for different formats |
| 81 | + - `com/github/_1c_syntax/bsl/mdo/` - Metadata object model classes |
| 82 | + - `com/github/_1c_syntax/bsl/mdclasses/` - Main library API |
| 83 | +- `src/test/java/` - Test code |
| 84 | +- `src/test/resources/` - Test fixtures and sample configurations |
| 85 | +- `src/main/resources/` - XSD schemas and converters |
| 86 | +- `docs/` - Documentation (MkDocs format, Russian and English) |
| 87 | +- `.github/workflows/` - CI/CD pipelines |
| 88 | + |
| 89 | +### Key Configuration Files |
| 90 | +- `build.gradle.kts` - Main build configuration (Gradle Kotlin DSL) |
| 91 | +- `settings.gradle.kts` - Gradle settings |
| 92 | +- `gradle.properties` - Build properties |
| 93 | +- `lombok.config` - Lombok configuration |
| 94 | +- `mkdocs.yml` / `mkdocs.en.yml` - Documentation configuration |
| 95 | +- `.github/workflows/java-ci.yml` - Main CI pipeline |
| 96 | +- `.github/workflows/gh-pages.yml` - Documentation deployment |
| 97 | +- `license/HEADER.txt` - License header template |
| 98 | + |
| 99 | +### Main Entry Points |
| 100 | +- `com.github._1c_syntax.bsl.mdclasses.MDClasses` - Main API class for loading configurations |
| 101 | +- `com.github._1c_syntax.bsl.mdo.Configuration` - Root configuration object |
| 102 | +- `com.github._1c_syntax.bsl.reader.designer.DesignerReader` - XML format reader |
| 103 | +- `com.github._1c_syntax.bsl.reader.edt.EDTReader` - EDT format reader |
| 104 | + |
| 105 | +## CI/CD Validation |
| 106 | + |
| 107 | +### GitHub Actions Workflows |
| 108 | +1. **Java CI** (`.github/workflows/java-ci.yml`) |
| 109 | + - Runs on: push and pull request |
| 110 | + - Tests matrix: Java 21, 25 on Ubuntu, Windows, macOS |
| 111 | + - Command: `./gradlew check --stacktrace` |
| 112 | + - Duration: ~5-10 minutes |
| 113 | + - Artifacts: Test results uploaded for all matrix combinations |
| 114 | + |
| 115 | +2. **GitHub Pages** (`.github/workflows/gh-pages.yml`) |
| 116 | + - Runs on: push to master/develop when docs change |
| 117 | + - Builds Javadoc and MkDocs documentation |
| 118 | + - Requires Python 3.10+ and Java 21 |
| 119 | + |
| 120 | +### Pre-commit Validation Steps |
| 121 | +Before submitting a PR, ensure: |
| 122 | +1. All tests pass: `./gradlew test` |
| 123 | +2. Code quality checks pass: `./gradlew check` |
| 124 | +3. License headers are up to date: `./gradlew updateLicenses` |
| 125 | +4. If touching docs, verify locally: `pip install mkdocs mkdocs-material pygments-bsl && mkdocs serve` |
| 126 | + |
| 127 | +## Code Conventions |
| 128 | + |
| 129 | +### Java Code Style |
| 130 | +- Target Java 21, use modern Java features where appropriate |
| 131 | +- Use Lombok annotations for reducing boilerplate (`@Getter`, `@Setter`, `@Builder`, etc.) |
| 132 | +- Package naming: `com.github._1c_syntax.bsl.*` |
| 133 | +- Follow standard Java naming conventions |
| 134 | +- UTF-8 encoding for all files |
| 135 | +- License headers required on all Java files (automatically updated via Gradle task) |
| 136 | + |
| 137 | +### Project-Specific Patterns |
| 138 | +- This is a **read-only** library - it does not modify configurations |
| 139 | +- Metadata objects follow 1C:Enterprise naming and structure |
| 140 | +- XStream is used for XML serialization/deserialization |
| 141 | +- Use `@Nullable` and `@NonNull` annotations from `org.jspecify` |
| 142 | +- Converters pattern used for transforming between different representations |
| 143 | +- Extensive use of ClassGraph for runtime class discovery |
| 144 | + |
| 145 | +### Testing Guidelines |
| 146 | +- JUnit 5 is used for testing |
| 147 | +- AssertJ for fluent assertions |
| 148 | +- Test resources include real 1C configuration samples |
| 149 | +- Tests are organized by functionality/reader type |
| 150 | +- Mock objects avoided in favor of integration tests with real data |
| 151 | + |
| 152 | +## Dependencies |
| 153 | + |
| 154 | +### Key Runtime Dependencies |
| 155 | +- `bsl-common-library` - Common 1C:Enterprise language utilities |
| 156 | +- `utils` - General utilities |
| 157 | +- `supportconf` - Support configuration handling |
| 158 | +- XStream - XML processing |
| 159 | +- Apache Commons Collections 4 - Collection utilities |
| 160 | +- Commons IO - File operations |
| 161 | +- ClassGraph - Runtime class discovery |
| 162 | +- SLF4J - Logging facade |
| 163 | + |
| 164 | +### Test Dependencies |
| 165 | +- JUnit 5 - Testing framework |
| 166 | +- AssertJ - Fluent assertions |
| 167 | +- JSONAssert - JSON comparison in tests |
| 168 | +- Reload4j - Logging implementation for tests |
| 169 | + |
| 170 | +## Additional Notes |
| 171 | + |
| 172 | +### Working with 1C:Enterprise |
| 173 | +- The library handles two main formats: |
| 174 | + 1. **Designer (XML)** format - exported via 1C:Enterprise configurator |
| 175 | + 2. **EDT** format - modern development environment format |
| 176 | +- Metadata structure mirrors 1C:Enterprise concepts (Catalogs, Documents, Registers, etc.) |
| 177 | +- Russian language is primary for domain concepts (alternate English names often available) |
| 178 | + |
| 179 | +### Documentation |
| 180 | +- Dual-language documentation (Russian primary, English available) |
| 181 | +- Javadoc is comprehensive and should be maintained |
| 182 | +- MkDocs for user-facing documentation |
| 183 | +- Update docs when changing public API |
| 184 | + |
| 185 | +### Performance |
| 186 | +- Benchmark tools available (`src/jmh/`) |
| 187 | +- JMH benchmarks for performance testing |
| 188 | +- Results stored in `build/jmh-results.json` |
| 189 | + |
| 190 | +### Integration |
| 191 | +- Library is designed to be used by BSL Language Server |
| 192 | +- Maven Central releases for public consumption |
| 193 | +- Snapshot builds deployed to Sonatype for testing |
| 194 | + |
| 195 | +## Trust These Instructions |
| 196 | + |
| 197 | +These instructions have been validated against the current codebase. Trust them as accurate and only search for additional information if something is incomplete or contradicts observed behavior. |
0 commit comments