apex-dev-tools / apex-dev-tools/apex-log-parser
✨ feat: Name the fields of each log event, and document them for consumers
- Linguagem predominante
- TypeScript
- Estrelas
- 2
- Forks
- 0
- Merge médio
- 5h 51min
- PRs com merge (30d)
- 32
Descrição
### Problem
#### Today
`LogEvents.ts` names the fields the parser itself needs for the tree and the timings, and joins the rest of the line into `text`. `VariableScopeBeginLine` (`src/LogEvents.ts:1210`) and `VariableAssignmentLine` (`:1220`) keep only `lineNumber`. Of 146 exported `*Line` classes, one carries a doc comment.
#### Why it matters
A consumer that needs a field the parser does not name has to re-read the raw line by pipe position and re-derive what each field means. Building a variables view in [certinia/debug-log-analyzer](https://github.com/certinia/debug-log-analyzer) (PRs #1006 and #1009 there) took about 200 lines of line reading, plus measurement across many logs to settle questions such as: the trailing address on a `this.field` line identifies the **owning object**, not the value that line wrote. None of that is discoverable from the types.
### Proposed solution
1. **Name the fields** on the events that carry data consumers ask for. `VARIABLE_ASSIGNMENT` gets `name`, `value`, `address`; `VARIABLE_SCOPE_BEGIN` gets `name`, `declaredType`, `canBeReferenced`, `isStatic`.
2. **A doc comment on every event class**: what the event marks, its fields in order, which are optional, and the log level it needs. One line where the name already says it.
3. **State a field's meaning where its name cannot.** An address that identifies an owner rather than a value is the case that cost us the most time.
#### Notes
- Field order per event is in the [Salesforce debug log documentation](https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_debugging_system_log_console.htm).
- A trailing field can be present and empty (`…|a|null|`), so a reader that splits on `|` and takes the last field gets the value wrong.
- A logged value can reach tens of thousands of characters. Naming the fields lets the parser decide once how to avoid copying them on a whole-log walk.
Happy to contribute the field naming for the variable events as a first PR if the shape suits.
### Alternatives considered
_None recorded._
Guia de contribuição
Avaliação
Esta issue ainda não foi avaliada.