mirror of
https://github.com/bitwarden/browser
synced 2026-02-08 20:50:28 +00:00
first draft of internal documentation for generator modules
This commit is contained in:
✨ Audrey ✨
@@ -1,3 +1,35 @@
|
||||
# Tools
|
||||
|
||||
This lib represents the public API of the Tools team at Bitwarden. Modules are imported using `@bitwarden/{feature-name}` for example `@bitwarden/send-core` and `@bitwarden/send-components`.
|
||||
This lib represents the public API of the Tools team at Bitwarden. Modules are imported using `@bitwarden/{feature-name}` for example `@bitwarden/generator-core` and `@bitwarden/send-ui`.
|
||||
|
||||
## Contributing
|
||||
|
||||
We're presently looking for help implementing our backlog of [ADRs](https://contributing.bitwarden.com/architecture/adr/).
|
||||
An easy place to start could be aligning our `-ui` and `-component` modules with
|
||||
[ADR-0011](https://contributing.bitwarden.com/architecture/adr/angular-folder-structure). Something like
|
||||
[ADR-0014](https://contributing.bitwarden.com/architecture/adr/typescript-strict) is more challenging.
|
||||
|
||||
Before you begin:
|
||||
|
||||
- Familiarize yourself with our [code contribution guidelines](https://contributing.bitwarden.com/contributing/).
|
||||
- Check out any [Deep Dive docs](https://contributing.bitwarden.com/architecture/deep-dives/) related to your contribution.
|
||||
- [Reach out](https://github.com/orgs/bitwarden/discussions/new/choose) to the [tools engineers](https://github.com/orgs/bitwarden/teams/team-tools-dev) with your plans!
|
||||
|
||||
:::tip[Want to contribute but don't know where to start?]
|
||||
|
||||
One of the realities of software is you can always do it better. Where we think
|
||||
there's opportunity for improvement, we're writing FIXMEs.
|
||||
|
||||
Many of these come from [new lints](https://github.com/bitwarden/clients/pull/14650/files),
|
||||
but that doesn't mean they're simple to solve!
|
||||
|
||||
Try taking a look at one!
|
||||
|
||||
:::
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Exporters](./export/vault-export/README.md)
|
||||
- [Generators](./generator/readme.md)
|
||||
- [Sends](./send/README.md)
|
||||
- [Tools Card Component](./card/README.md)
|
||||
|
||||
99
libs/tools/generator/conventions.md
Normal file
99
libs/tools/generator/conventions.md
Normal file
@@ -0,0 +1,99 @@
|
||||
# Conventions
|
||||
|
||||
This file outlines the code conventions that we're applying to code within the generator
|
||||
modules. These conventions supplement the conventions in the
|
||||
[contributing documentation][code-style].
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you are using a programming assistant, please include this file in the prompt's
|
||||
> context when generating code.
|
||||
|
||||
## Modules
|
||||
|
||||
Every source folder is treated as a module, and must have a barrel file. It may
|
||||
import from its ancestors and its children. Modules should not import from their
|
||||
cousins or grandchildren. Do not import barrel files from parent scopes.
|
||||
|
||||
✅ Do:
|
||||
|
||||
```ts
|
||||
import foo from "../../foo";
|
||||
import bar from "../bar";
|
||||
import baz from "../baz.ts";
|
||||
|
||||
import biz from "./biz";
|
||||
```
|
||||
|
||||
❌ Do not:
|
||||
|
||||
```ts
|
||||
import foo from "../";
|
||||
import bar from "../../foo/bar";
|
||||
import baz from "../bar/baz.ts";
|
||||
|
||||
import buz from "./baz/biz/buz";
|
||||
```
|
||||
|
||||
### Barrel files ([ADR-0002][adr-0002])
|
||||
|
||||
The root barrel file contains all public exports of the module. All other barrel files
|
||||
are internal to the module. This is presently [enforced with a lint][restrict-path-lint].
|
||||
|
||||
### Common files
|
||||
|
||||
The following files may be used to consolidate low-level module items.
|
||||
|
||||
- `data.ts` <- constants; may only depend on external modules.
|
||||
- `index.ts` <- exports; may define aggregates and apply type assertions to improve module DevEx.
|
||||
- `type.ts` <- type definitions; may only depend on `data.ts` and external modules.
|
||||
- `util.ts` <- utility functions; may only depend on `data.ts`, `type.ts`, and external modules.
|
||||
|
||||
[Example][common-files-example]
|
||||
|
||||
> [!TIP]
|
||||
> Implementing the `const object` pattern ([ADR-0025][adr-0025]):
|
||||
>
|
||||
> 1. Write the const object into `data.ts`
|
||||
> 2. Derive type definitions from the const object in `type.ts`
|
||||
> 3. Import types and data into `index.ts`, perform type assertions, and re-export the data.
|
||||
|
||||
## Rx ([ADR-0015][adr-0015])
|
||||
|
||||
Reactive code should be written functionally, with liberal use of observable injection. Core
|
||||
rx code should not depend on services. It should depend solely on reactive objects and
|
||||
functions.
|
||||
|
||||
Services and other long-lived components compose the rx logic for injection into other contexts.
|
||||
They read observables from their dependencies and inject them into the Core rx code.
|
||||
|
||||
[Example][rx-example]
|
||||
|
||||
## Logging
|
||||
|
||||
The generator's reactivity model is time-sensitive, which makes identifying and diagnosing runtime
|
||||
behaviors difficult. Consider, for example, interactively debugging an observable subject to
|
||||
`timeout()`. Because the computer's clock keeps running when the debugger is paused, stopping a
|
||||
program subject to this operation can exhaust the timeout, resulting in
|
||||
[heisenbugs][heisenbug]. The generator's permanent runtime logging
|
||||
facilities decrease this complexity of debugging by writing structured logs using the
|
||||
`SemanticLogger`.
|
||||
|
||||
When a generator creates a logger, it sets the log's `type` parameter. This can be filtered by
|
||||
editing XYZ.
|
||||
|
||||
> [!CAUTION]
|
||||
> The `SemanticLogger` writes arbitrary runtime information into the console. It is
|
||||
> automatically disabled outside of development environments to mitigate data leaks.
|
||||
|
||||
[adr-0002]: https://contributing.bitwarden.com/architecture/adr/public-module-npm-packages
|
||||
[adr-0015]: https://contributing.bitwarden.com/architecture/adr/short-lived-browser-services#decision-outcome
|
||||
[adr-0025]: https://github.com/bitwarden/contributing-docs/pull/605
|
||||
[code-style]: https://contributing.bitwarden.com/contributing/code-style/
|
||||
[common-files-example]: https://github.com/bitwarden/clients/tree/main/libs/tools/generator/core/src/metadata
|
||||
[heisenbug]: https://en.wikipedia.org/wiki/Heisenbug
|
||||
[restrict-path-lint]: https://github.com/bitwarden/clients/blob/721657a5c30802edef34a20309c01ae2952b1da1/eslint.config.mjs#L131-L134
|
||||
[rx-example]: https://github.com/bitwarden/clients/tree/2e78c3edc7153d275c8814f3ffde02fb4a82ac0d/libs/common/src/tools/achievements
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Generator README](./readme.md)
|
||||
59
libs/tools/generator/readme.md
Normal file
59
libs/tools/generator/readme.md
Normal file
@@ -0,0 +1,59 @@
|
||||
# Bitwarden Credential Generators
|
||||
|
||||
This folder contains the TypeScript implementation of the Bitwarden credential
|
||||
generator.
|
||||
|
||||
## generator-core
|
||||
|
||||
Package name: `@bitwarden/generator-core`
|
||||
|
||||
Contains credential generation services, configurations, types, and utilities.
|
||||
|
||||
Use this module to integrate the generator with your services.
|
||||
|
||||
## generator-components
|
||||
|
||||
Package name: `@bitwarden/generator-components`
|
||||
|
||||
Contains Angular components and modules.
|
||||
|
||||
Use this module to integrate the generator with your components.
|
||||
|
||||
## generator-history
|
||||
|
||||
Package name: `@bitwarden/generator-history`
|
||||
|
||||
Generator history layer.
|
||||
|
||||
Use this module to record generated credentials to an account's credential log.
|
||||
|
||||
## generator-navigation
|
||||
|
||||
Package name: `@bitwarden/generator-navigation`
|
||||
|
||||
Backwards compatibility layer for legacy generator support.
|
||||
|
||||
:::warning
|
||||
|
||||
Do not use this module.
|
||||
|
||||
:::
|
||||
|
||||
## generator-legacy
|
||||
|
||||
Package name: `@bitwarden/generator-legacy`
|
||||
|
||||
Backwards compatibility layer for legacy generator support.
|
||||
|
||||
:::warning
|
||||
|
||||
Do not use this module.
|
||||
|
||||
:::
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Tools README](../readme.md)
|
||||
- [Generator conventions](../conventions.md)
|
||||
- [Generator help](https://bitwarden.com/help/generator/)
|
||||
- [Generator SDK](https://github.com/bitwarden/sdk-internal/tree/main/crates/bitwarden-generators)
|
||||
Reference in New Issue
Block a user