-
REQ-FUN-06 (AI Translation Lifecycle & States):
- Target Release: Future Phase (v2.0+)
- Translation Lifecycle Statuses: Each translation entry in the cache database must support a state metadata flag:
draft (default for AI-generated translations) or verified (marked after Translation Manager manual review/override or XLIFF import).
- Translation Pipeline Triggers: The translation generator module must execute strictly upon commits or merges into the primary production branch (
master). Standard feature-branch builds are restricted from making live translation API calls and must execute in secure Read-Only mode.
- Traces to:
REQ-BUS-06
-
REQ-FUN-18 (Asynchronous Non-Blocking Translation CLI):
- Target Release: Future Phase (v2.0+)
- Decoupled Non-Blocking Workflow: The translation review cycle must be decoupled from code integration. Standard development builds must render
draft translations (optionally displaying a configurable "AI-translated draft" warning banner) or fall back to the source English language, ensuring developer velocity is not impacted by manual localization checks.
- Access Control Modes: The CLI must support a
--read-only-cache flag (active by default for general CI/CD builds) to parse and render using existing translation files without making writes, and a --write-cache flag (restricted to authorized Translation Manager sessions in CI/CD) to safely commit updates and state promotion (from draft to verified) to the translation database.
- Traces to:
REQ-BUS-06
-
REQ-FUN-08 (Server-Side Push-Gate Enforcement Modes):
- Target Release: Future Phase (v2.0+)
- Server-Side Modes: Under
--push-gate-mode, the gate enforces policies (reject, allow, auto-document, verify-document).
- Traces to:
REQ-BUS-08
-
REQ-FUN-15 (Quality Gate Scope & Completeness Criteria):
- Target Release: Future Phase (v2.0+)
- Quality Gate Scope: The Quality Gate calculates documentation coverage over all public (
public) and protected (protected) API entities (including classes, interfaces, methods, functions, properties, fields, enums, structs, constants, constructors, etc.) within the scope of code ingestion.
- Documentation Completeness Criteria: An entity is classified as fully "documented" if and only if:
- It has a non-empty, meaningful prose description in its docstring.
- If the entity is a method or function containing parameters or a return value, every single parameter and the return value must also have non-empty, associated descriptions in the docstring schema.
- Traces to:
REQ-BUS-08
-
REQ-FUN-16 (Quality Gate Automatic Exclusions):
- Target Release: Future Phase (v2.0+)
- Automatic Exclusions: The following elements are automatically excluded from the Quality Gate denominator:
- Overridden methods that are explicitly inherited without structural changes from base classes or external system libraries (e.g.,
Equals, GetHashCode, ToString in Java/C#, or __str__, __repr__ in Python).
- Trivial property getters and setters (e.g., automatic properties
get; set; in C#) containing no custom user logic.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-17 (Offline Local Gate Fallbacks):
- Target Release: Future Phase (v2.0+)
- Offline Local Execution: When executed outside a CI/CD environment (detected via environment variables or explicitly passed CLI flags), UDE must enforce an offline-by-default execution policy, utilizing local cache databases or mock placeholders instead of billing live LLM APIs.
- Traces to:
REQ-BUS-05
-
REQ-FUN-12 (Standalone Coverage Reporting Command):
- Target Release: Future Phase (v2.0+)
- Independent CLI Execution: The UDE CLI must support a dedicated, standalone subcommand (e.g.,
ude coverage) to audit documentation coverage and output reports. This command must be fully executable independently of the main documentation compilation and rendering workflow.
- Reporting Formats: The coverage command must generate structural reports detailing:
- Total audited entities, total documented entities, and the aggregate coverage percentage.
- A comprehensive list of specific undocumented or partially documented entities (with file names and line numbers).
- Outputs in multiple formats, including human-readable CLI terminal prints, detailed Markdown summaries, and structured JSON for integration with external dashboards.
- Traces to:
REQ-BUS-08
-
REQ-FUN-13 (Ignore Tags & Range Boundaries):
- Structural Exclusions: The parser, quality gate, and coverage modules must completely ignore any code blocks or entities demarcated by the following tags:
- Block Range Exclusions: All code and entities situated between
DOM-IGNORE-BEGIN and DOM-IGNORE-END comments.
- Conditional Block Exclusions: All code and entities situated between
\cond (or @cond) and \endcond (or @endcond) directives.
- Internal Tag Exclusions: Any entity containing or marked with the
\internal (or @internal) tag.
- Traces to:
REQ-BUS-05, REQ-BUS-08
-
REQ-FUN-09 (Context-Rich Source Ingestion & Decoupled Tooling): The ude-enrich module/script must extract both the declaration (signature) and the definition (implementation body/block) for any undocumented code entity. When sending a prompt to the LLM for English docstring generation, this tool must construct a composite payload containing both the declaration and the full implementation body as context, ensuring that the generated docstrings accurately reflect the internal logic, thrown exceptions, and side-effects of the code. The tool must write back only the resulting docstrings to the source code or output documentation without altering any functional logic.
- Target Release: Future Phase (v2.0+)
- Traces to:
REQ-BUS-05
-
REQ-FUN-10 (XLIFF Export and Import CLI Commands): The UDE CLI must support standard subcommands for exporting and importing localization files in XML Localisation Interchange File Format (XLIFF, .xlf format, version 1.2 or 2.0) to enable integration with professional translators:
- Target Release: Future Phase (v2.0+)
- Export Command (
ude translation export <lang> --output <file.xlf>): Extract all source English docstrings and prose blocks alongside their corresponding AI-proposed translation segments with a status of draft, formatting them into a standard XLIFF translation unit (<trans-unit>) containing <source> and <target> nodes.
- Import Command (
ude translation import <file.xlf>): Ingest a translated .xlf file back into the local translation cache, updating translation strings and automatically promoting their lifecycle status from draft to verified.
- Traces to:
REQ-BUS-06
-
REQ-FUN-07 (Non-Interactive CLI Automation): The CLI engine must support execution in completely non-interactive mode with standard exit codes, configurable via command-line arguments and environment variables, for hands-free automation in CI/CD pipelines.
-
REQ-FUN-11 (Transparent Compression of JSON Artifacts): The engine must store and manage all persistent JSON artifacts—specifically the Intermediate Representation (IR) files and the Translation Cache database—in a compressed format using the standard Gzip algorithm (with file extension .json.gz). The CLI orchestrator and modular subcommands must transparently decompress these files into memory upon startup or ingestion, and compress them back to disk upon execution completion or export, ensuring zero uncompressed JSON pollution in repository storage.
- Baseline (MVP v1.0): Intermediate Representation compression.
- Future Phase (v2.0+): Translation Cache compression.
- Traces to:
REQ-BUS-03
-
REQ-FUN-23 (Environment & Dependency Verification):
- Version 1 (Baseline / MVP): Before initiating execution of any collector or parsing task, the orchestrator and the collector must perform strict environment pre-flight checks:
- Verify that Python is installed, executable, and accessible on the system PATH (since the orchestrator and parsing engine run as Python scripts).
- Verify the availability and execution permission of the Doxygen binary (as specified in
ude_global.json or fallback system paths) if the project requires Doxygen preprocessing.
- Verify the physical presence of all required target configurations (e.g.,
ude_config.json and Doxyfile for Doxygen-based projects).
- Verify the existence, accessibility, and non-emptiness of all target source directories (
src_dir).
- Verify the presence of all necessary raw source code files (e.g.,
.h files for C++, .cs files for C#, etc.) within those source directories required to compile or parse the specific project.
If any checks fail, execution must be halted cleanly before subprocess spawn, throwing an environment-specific exception, writing diagnostic recommendations to stderr, and exiting with code 5.
- Traces to:
REQ-BUS-09
-
REQ-FUN-24 (Pipeline Fault Tolerance & Recovery):
- Version 1 (Baseline / MVP): The system must enforce high-reliability operational boundaries:
- Multi-Project Execution Policy: When orchestrated via
generate_all.bat, the orchestrator must support a configurable error policy (via ude_global.json): fail-fast (abort the entire pipeline run at the first project error) or continue-on-error (log the target failure, skip the failed project, continue compilation of remaining projects, and print a consolidated error list at the end).
- Malformed XML Protection: If individual generated XML files are malformed or unreadable, the parser must log specific warnings and proceed to extract structural entities from other valid compounds, avoiding total pipeline crashes.
- Crash Cleanup Guarantee: If an unhandled exception or pipeline failure occurs during execution, the system must trigger automated cleanup via
finally blocks to delete any generated temporary folders or XML files, preventing workspace contamination.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-25 (Unified Logging & Auditing):
- Version 1 (Baseline / MVP): The engine must implement a centralized, time-stamped, and thread-safe file-logging system writing to a configured log file (e.g.
ude_system.log). The logging module must:
- Document the starting parameters, timestamped progression, and duration of every lifecycle phase (Collect, Parse, Validation, Render, Cleanup).
- Intercept and capture Doxygen subprocess stderr logs, categorizing compiler warnings and errors into the unified UDE log stream.
- Log parse statistics (count of extracted namespaces, classes, methods, parameters, and entities) and rendering outputs (pages written).
- Support configurable logging verbosity levels (
DEBUG, INFO, WARNING, ERROR).
- Write detailed stack traces of any occurring exceptions to the log file, while printing only high-level, clean, and developer-friendly diagnostic messages to the console stderr.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-26 (Incremental Parsing Cache):
- Version 1 (Baseline / MVP): To prevent redundant parsing, the engine must implement incremental parsing based on file modification timestamps or content hashes (e.g. SHA-256) of input Doxygen XML files. If an XML compound (representing a class, namespace, structure, etc.) has not changed since the previous run, its corresponding entities must be loaded directly from
.build_cache.json.gz, bypassing raw XML parsing to reduce execution time.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-27 (Incremental Rendering Cache):
- Version 1 (Baseline / MVP): To optimize documentation rendering (preventing redundant disk writes, reducing SSD wear, and keeping Git commits of local outputs clean), the renderer must support incremental rendering. It must compare the signature hash (or content hash of the IR entity) and template hash against the previously rendered files. If neither has changed, the renderer must skip rewriting the target output file.
- Traces to:
REQ-BUS-03, REQ-BUS-09
-
REQ-FUN-28 (Target Folder Isolation for Metadata and Cache):
- Version 1 (Baseline / MVP): All pipeline-internal files—specifically the Intermediate Representation (
intermediate_representation.json.gz) and build/parsing caches (.build_cache.json.gz)—must be strictly stored within a dedicated target subdirectory under the ude/ tree, named according to the format <sdk>_<lang> (e.g. ude/Bimnv/bimnv_cpp/, ude/Bimnv/bimnv_cs/). This <sdk>_<lang> folder is a descendant of the ude/ root directory, is kept under git version control, and contains the target-specific batch script, ude_config.json, and Doxyfile. Intermediate and cache files must never be written to output_dir (which contains final user-facing files only) to ensure a clean separation between development metadata and production assets.
- Traces to:
REQ-BUS-03
-
REQ-FUN-29 (No Hardcoded Paths & Relative Path Resolution):
- Version 1 (Baseline / MVP): All directory and file paths used by the UDE engine must be defined exclusively in the configuration files (
ude_global.json, ude_config.json, product.json, etc.). Under no circumstances shall physical paths be hardcoded directly into the Python source code. Furthermore, all paths declared in the configurations must be relative (relative to the directory containing the config file). At runtime, the UDE orchestrator must automatically resolve and translate these relative paths into absolute paths, ensuring seamless portability between local developer environments and CI/CD servers.
- Traces to:
REQ-BUS-09