## What Build a Rust binary that extracts GLQL field, function, and data source metadata directly from the source code and outputs structured YAML. This can be used to replace manual documentation with an always-up-to-date, code-driven system. ## Why GLQL documentation at [fields](https://docs.gitlab.com/ee/user/glql/fields/) and [functions](https://docs.gitlab.com/ee/user/glql/functions/) is manually maintained. Manual docs drift from implementation as fields and functions are added or modified. There is no single source of truth, and maintaining per-field examples at scale is a maintenance burden that doesn't scale. Automating this: - Eliminates discrepancies between code and documentation - Reduces maintenance overhead when adding new fields or functions - Creates a structured spec (YAML) that can drive markdown, API specs, or other doc formats --- ## Scope ### In scope **Auto-generated field spec** (`docs/glql_fields.yaml`): Documents sources, their types, and fields. Extract from code: | Level | What's documented | |-------|-------------------| | **Sources** | Top-level grouping (WorkItems, MergeRequests, Projects) with the types each source handles (e.g., WorkItems → Issue, Epic, Task, Incident, etc.). Type-to-source mapping extracted from `Source::from()`. | | **Query fields** | Name, aliases, supported operators, allowed value types (with enum values, reference types, list relationships), constraints (paired fields, operator restrictions) | | **Display fields** | Name, aliases, description | | **Sort fields** | Name, aliases, description, GraphQL enum value | > **Note on per-type field support**: The current code validates fields at the _source_ level, not the _type_ level. For example, the WorkItems analyzer treats all its types (Issue, Epic, Task, etc.) identically — `is_valid_field()` doesn't differentiate. The existing docs at docs.gitlab.com say things like "Supported for: Issues" but this granularity is not encoded in GLQL's type system. The generated YAML will document fields per source. Per-type support annotations can be added manually or via a future code change to encode this in the analyzers. **Manually maintained function spec** (`docs/glql_functions.yaml`): Functions are defined inline in match statements (not a registry), so they cannot be introspected programmatically. This file is maintained by hand. | Attribute | Detail | |-----------|--------| | Name | e.g. `currentUser`, `today`, `startOfDay`, `labels` | | Type | `value` (query) or `field` (display) | | Parameters | Name, type, description | | Syntax | e.g. `currentUser()`, `startOfDay(-1)` | | Description | What the function does | | Additional details | Constraints, edge cases | ### Out of scope - Per-field query examples (add manually if needed) - CI pipeline for automatic regeneration - Validation against GitLab GraphQL schema --- ## Technical approach ### Architecture ``` bin/generate_docs.rs docs/glql_functions.yaml │ (manually maintained) ├─► Instantiate each SourceAnalyzer │ (WorkItems, MergeRequests, Projects) │ ├─► Map types to sources via Source::from() │ (Issue, Epic, Task… → WorkItems; │ MergeRequest → MergeRequests; │ Project → Projects) │ ├─► For each Field enum variant: │ • is_valid_field() → determines source support │ • field_type() → returns FieldType tree │ • Parse FieldType recursively to extract: │ operators, value types, constraints │ ├─► valid_sort_fields() + graphql_sort_value() │ → sort field documentation │ └─► Serialize → docs/glql_fields.yaml ``` ### Key implementation details **Extracting field metadata**: The `FieldType` enum is recursive. A field like `assignee` returns: ``` Multiple([ StringLike, ReferenceLike(UserRef), ListLike(HasMany, Multiple([StringLike, ReferenceLike(UserRef)])), Nullable ]) ``` The generator must walk this tree to extract all value types, then check for `WithOperators` and `PairedWith` wrappers to get operator restrictions and field constraints. **Extracting aliases**: The `Field::from(String)` implementation maps multiple string inputs to the same field variant (e.g., `"assignees"` → `Assignee.aliased_as("assignees")`). The generator iterates known alias strings per field to build the alias list. **Functions**: Since functions are defined inline in match statements (not a registry), they cannot be auto-extracted. Functions are maintained in a separate manually written `docs/glql_functions.yaml`. There are currently 3 value functions (`currentUser`, `today`, `startOfDay`) and 1 field function (`labels`). ### Dependencies ```toml # Add to Cargo.toml serde_yaml = "0.9" ``` `serde` and `chrono` are already present. --- ## Output format ### Auto-generated: `docs/glql_fields.yaml` ```yaml version: '1.0' generated_at: '2026-03-20T10:30:00Z' sources: - name: 'WorkItems' graphql_name: 'workItems' query_fields: - name: 'type' aliases: [] operators: ['=', 'in'] value_types: - type: 'Enum' values: [ 'Issue', 'Incident', 'Epic', 'TestCase', 'Requirement', 'Task', 'Ticket', 'Objective', 'KeyResult', ] additional_details: - 'If omitted, the default type is Issue' - name: 'assignee' aliases: ['assignees'] operators: ['=', 'in', '!='] value_types: - type: 'String' - type: 'Reference' reference_type: 'UserRef' syntax: '@username' - type: 'List' relationship: 'HasMany' contains: ['String', 'UserRef'] - type: 'Nullable' values: ['null', 'none', 'any'] - name: 'state' aliases: [] operators: ['='] value_types: - type: 'Enum' values: ['opened', 'closed', 'all'] - name: 'epic' aliases: [] operators: ['=', '!='] value_types: - type: 'Number' - type: 'String' - type: 'Reference' reference_type: 'EpicRef' syntax: '&123' display_fields: - name: 'assignee' aliases: ['assignees'] description: 'Display users assigned to the work item' - name: 'epic' aliases: [] description: 'Display a link to the parent epic' sort_fields: - name: 'created' aliases: ['createdAt'] description: 'Sort by creation date' graphql_value: 'CREATED' - name: 'start' aliases: ['startDate'] description: 'Sort by start date' graphql_value: 'START_DATE' - name: 'MergeRequests' graphql_name: 'mergeRequests' query_fields: - name: 'type' aliases: [] operators: ['='] value_types: - type: 'Enum' values: ['MergeRequest'] - name: 'assignee' aliases: ['assignees'] operators: ['=', '!='] value_types: - type: 'String' - type: 'Reference' reference_type: 'UserRef' syntax: '@username' - type: 'Nullable' values: ['null', 'none', 'any'] # ... - name: 'Projects' graphql_name: 'projects' query_fields: - name: 'type' aliases: [] operators: ['='] value_types: - type: 'Enum' values: ['Project'] # ... ``` ### Manually maintained: `docs/glql_functions.yaml` ```yaml functions: - name: 'currentUser' type: 'value' parameters: [] syntax: 'currentUser()' description: 'Evaluates to the current authenticated user' return_type: 'Reference(UserRef) | Null' additional_details: - 'Case-insensitive function name' - 'Returns Null if no username in context' - name: 'today' type: 'value' parameters: [] syntax: 'today()' description: "Returns current date at 00:00 in user's timezone" return_type: 'Quoted(String)' additional_details: - 'Date format: YYYY-MM-DD' - 'When used with = operator, matches 00:00 to 23:59' - name: 'startOfDay' type: 'value' parameters: - name: 'days' type: 'i64' description: 'Number of days offset (positive or negative)' syntax: 'startOfDay(-1)' description: 'Returns date n days from now at 00:00' return_type: 'Quoted(String)' additional_details: - 'Negative values for past dates' - 'Date format: YYYY-MM-DD' - name: 'labels' type: 'field' parameters: - name: 'patterns' type: 'String[]' description: 'Wildcard patterns to match labels' syntax: 'labels("workflow::*", "backend")' description: 'Filters and displays matching labels in a separate column' return_type: 'FieldFunction' additional_details: - 'Supports wildcard (*) for pattern matching' - 'Extracted labels are removed from the regular labels column' - 'Minimum 1, maximum 100 label patterns' - 'Case-insensitive matching' ``` --- ## Tasks ### Phase 1: Infrastructure - [ ] Create `bin/generate_docs.rs` with main entry point - [ ] Add `serde_yaml` dependency to `Cargo.toml` - [ ] Define documentation data model structs with `#[derive(Serialize)]` ### Phase 2: Source & field extraction - [ ] Create list of all `Field` enum variants to iterate over - [ ] Implement recursive `FieldType` parser (operators, value types, constraints) - [ ] Extract query fields for WorkItems, MergeRequests, Projects - [ ] Extract field aliases - [ ] Extract sort fields with GraphQL value mappings ### Phase 3: Display fields - [ ] List all display fields per source - [ ] Map display field names to descriptions ### Phase 4: Functions (manual) - [ ] Create `docs/glql_functions.yaml` with value functions (currentUser, today, startOfDay) - [ ] Add field function (labels) ### Phase 5: Validation - [ ] Verify generated YAML output is well-formed - [ ] Spot-check 10+ fields against current docs for accuracy - [ ] Verify all operators and enum values match source code --- ## Acceptance criteria - [ ] `cargo run --bin generate_docs` produces `docs/glql_fields.yaml` - [ ] YAML contains all 3 data sources - [ ] Every query field includes name, aliases, operators, and value types - [ ] Display fields include name, aliases, and description - [ ] Sort fields include name, aliases, and GraphQL value - [ ] `docs/glql_functions.yaml` documents all 4 functions with parameters and descriptions - [ ] Generated field data matches actual implementation (verified by spot-check) --- ## Open questions 1. **Display field descriptions** are not in code. Infer from field names, or populate manually? 2. **Output directory**: `docs/` (new) or `doc/` (existing)? 3. **Complex constraints** (e.g., "project and group are mutually exclusive") live in `validate_query()`, not the type system. Extract programmatically or document manually? --- ## Follow-ups - **Auto-extract functions**: Currently functions are defined as inline match arms and can't be introspected. Requires refactoring into a registry pattern (e.g., a `Vec<FunctionDef>`) that both the evaluator and the doc generator consume. Once done, `glql_functions.yaml` can be auto-generated alongside the fields spec. - **Per-type field support**: The current code validates fields at the source level (WorkItems, MergeRequests, Projects), not the type level (Issue vs Epic vs Task). The existing docs at docs.gitlab.com document per-type support (e.g., "Supported for: Issues, epics") but this isn't encoded in the analyzers. Encoding this in `SourceAnalyzer` would allow the generator to output per-type `supported_types` for each field. - **Generate markdown documentation from YAML**: Transform the YAML spec files into publishable markdown (e.g., for docs.gitlab.com). ---