@venizia/ignis-boot 0.2.0-35 → 0.2.0-36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +91 -123
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,56 +1,31 @@
|
|
|
1
|
-
|
|
1
|
+
# @venizia/ignis-boot
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
# :fire: IGNIS - `@venizia/ignis-boot`
|
|
6
|
-
|
|
7
|
-
**Generates one static registration file from your decorated classes.**
|
|
8
|
-
|
|
9
|
-
[](https://ignis.venizia.ai/references/base/bootstrapping)
|
|
10
|
-
[](https://www.npmjs.com/package/@venizia/ignis-boot)
|
|
11
|
-
[](LICENSE.md)
|
|
12
|
-
[](https://www.typescriptlang.org/)
|
|
13
|
-
|
|
14
|
-
[Artifact registration reference](https://ignis.venizia.ai/references/base/bootstrapping) •
|
|
15
|
-
[Registering artifacts guide](https://ignis.venizia.ai/guides/core-concepts/application/bootstrapping) •
|
|
16
|
-
[Changelog](https://ignis.venizia.ai/changelogs/2026-09-03-deprecated-boot-api-removed)
|
|
17
|
-
|
|
18
|
-
</div>
|
|
19
|
-
|
|
20
|
-
---
|
|
21
|
-
|
|
22
|
-
`ignis-artifacts` walks a source root with the TypeScript compiler API, finds every named,
|
|
23
|
-
non-abstract class that carries an IGNIS stereotype decorator (`@service`, `@controller`, ...), and
|
|
24
|
-
writes one file of plain static imports: `src/generated/artifacts.ts`. The application passes that
|
|
25
|
-
file as `configs.artifacts`; `@venizia/ignis`'s `registerArtifacts` boot step binds it.
|
|
26
|
-
|
|
27
|
-
**This package runs at build time only.** No decorator runs and no class is imported while
|
|
28
|
-
scanning - detection reads source text, so a datasource that opens a pool at import stays inert.
|
|
3
|
+
Build-time tools for an IGNIS application: `ignis-artifacts` writes one static file that registers your decorated classes, and `ignis-build-info` stamps the build. Install it as a devDependency of the application.
|
|
29
4
|
|
|
30
5
|
## Install
|
|
31
6
|
|
|
32
7
|
```bash
|
|
33
|
-
bun add -d @venizia/ignis-boot
|
|
8
|
+
bun add -d @venizia/ignis-boot typescript
|
|
34
9
|
```
|
|
35
10
|
|
|
36
|
-
`
|
|
37
|
-
deployed application installs nothing extra for it at runtime.
|
|
11
|
+
`typescript` 5 or 6 is a required peer: the scanner reads your source with the TypeScript compiler API. Both binaries run under Bun (they carry a `bun` shebang).
|
|
38
12
|
|
|
39
|
-
##
|
|
13
|
+
## Register your classes
|
|
40
14
|
|
|
41
15
|
Decorate the classes you want registered:
|
|
42
16
|
|
|
43
17
|
```typescript
|
|
44
|
-
import {
|
|
18
|
+
import { BaseService, service } from '@venizia/ignis';
|
|
45
19
|
|
|
46
20
|
@service()
|
|
47
|
-
export class PricingService extends BaseService {
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
21
|
+
export class PricingService extends BaseService {
|
|
22
|
+
constructor() {
|
|
23
|
+
super({ scope: PricingService.name });
|
|
24
|
+
}
|
|
25
|
+
}
|
|
51
26
|
```
|
|
52
27
|
|
|
53
|
-
Add
|
|
28
|
+
Add two scripts and run the first one:
|
|
54
29
|
|
|
55
30
|
```json
|
|
56
31
|
{
|
|
@@ -61,13 +36,26 @@ Add the generator scripts and run one:
|
|
|
61
36
|
}
|
|
62
37
|
```
|
|
63
38
|
|
|
64
|
-
|
|
65
|
-
|
|
39
|
+
`generate` writes plain static imports and one object:
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
// AUTO-GENERATED by @venizia/ignis-boot - do not edit. Regenerate: ignis-artifacts generate --root src --out src/generated/artifacts.ts
|
|
43
|
+
import { PricingService } from '../services/pricing.service';
|
|
44
|
+
|
|
45
|
+
export const GeneratedArtifacts = {
|
|
46
|
+
configurations: [],
|
|
47
|
+
dataSources: [],
|
|
48
|
+
components: [],
|
|
49
|
+
repositories: [],
|
|
50
|
+
services: [PricingService],
|
|
51
|
+
controllers: [],
|
|
52
|
+
};
|
|
66
53
|
```
|
|
67
54
|
|
|
68
|
-
|
|
55
|
+
Hand that object to the application. The `registerArtifacts` boot step binds every class in it:
|
|
69
56
|
|
|
70
57
|
```typescript
|
|
58
|
+
import type { IApplicationConfigs } from '@venizia/ignis';
|
|
71
59
|
import { GeneratedArtifacts } from './generated/artifacts';
|
|
72
60
|
|
|
73
61
|
export const configs: IApplicationConfigs = {
|
|
@@ -76,131 +64,111 @@ export const configs: IApplicationConfigs = {
|
|
|
76
64
|
};
|
|
77
65
|
```
|
|
78
66
|
|
|
79
|
-
Commit the generated file
|
|
80
|
-
walkthrough: [Registering artifacts](https://ignis.venizia.ai/guides/core-concepts/application/bootstrapping).
|
|
67
|
+
Commit the generated file and never edit it by hand. Run `check:artifacts` where lint runs, so a stale index fails before it reaches CI.
|
|
81
68
|
|
|
82
|
-
|
|
69
|
+
The scanner reads source text and never imports a module. No decorator runs and no import side effect fires, so a datasource that opens a pool at import stays inert. Because the output is plain imports, `bun build --compile` sees every class; a compiled binary has no source tree to scan at run time.
|
|
83
70
|
|
|
84
|
-
|
|
85
|
-
under bun.
|
|
71
|
+
## `ignis-artifacts`
|
|
86
72
|
|
|
87
73
|
```
|
|
88
74
|
ignis-artifacts <generate|check> [--root src] [--out src/generated/artifacts.ts] [--ignore a,b] [--export GeneratedArtifacts]
|
|
89
75
|
```
|
|
90
76
|
|
|
91
77
|
| Flag | Default | Meaning |
|
|
92
|
-
|
|
93
|
-
| `--root` | `src` | Directory to scan, recursively |
|
|
94
|
-
| `--out` | `src/generated/artifacts.ts` | Output
|
|
95
|
-
| `--ignore` |
|
|
78
|
+
|---|---|---|
|
|
79
|
+
| `--root` | `src` | Directory to scan, recursively (`.ts` files, `.d.ts` skipped) |
|
|
80
|
+
| `--out` | `src/generated/artifacts.ts` | Output file; import paths are relative to it |
|
|
81
|
+
| `--ignore` | none | Comma-separated globs, relative to `--root`, added to the default list |
|
|
96
82
|
| `--export` | `GeneratedArtifacts` | Name of the exported constant |
|
|
97
83
|
|
|
98
|
-
|
|
99
|
-
| :--- | :--- | :--- |
|
|
100
|
-
| `generate` | Writes `--out` when its content changed | `0` |
|
|
101
|
-
| `check` | Renders in memory and compares with `--out`; fails a stale index | `0` fresh, `1` stale |
|
|
102
|
-
|
|
103
|
-
Default ignore list: `**/__tests__/**`, `**/*.test.ts`, `**/*.spec.ts`, `**/generated/**`.
|
|
104
|
-
|
|
105
|
-
## Detection rules
|
|
84
|
+
The default ignore list always applies: `**/__tests__/**`, `**/*.test.ts`, `**/*.spec.ts`, `**/generated/**`. A decorated class hidden by one of your own `--ignore` patterns prints one `warning:` line on stderr.
|
|
106
85
|
|
|
107
|
-
|
|
86
|
+
| Command | Effect | Exit code |
|
|
87
|
+
|---|---|---|
|
|
88
|
+
| `generate` | Writes `--out` only when the content changed | `0` |
|
|
89
|
+
| `check` | Renders in memory and compares with `--out`, ignoring the header line | `0` fresh, `1` stale or missing |
|
|
90
|
+
| anything else | Prints the usage line | `2` |
|
|
108
91
|
|
|
109
|
-
|
|
110
|
-
- Not `abstract`.
|
|
111
|
-
- Decorated with `component`, `controller`, `service`, `repository` or `datasource`, imported from
|
|
112
|
-
`@venizia/ignis` or `@venizia/ignis-kernel` (import aliases resolved) - or with
|
|
113
|
-
`injectable({ type })` where `type` is a string literal or `ArtifactTypes.<NAME>`.
|
|
92
|
+
### What gets emitted
|
|
114
93
|
|
|
115
|
-
|
|
94
|
+
A class lands in the index when all of these hold. The scanner logs a warning for a decorated class it skips.
|
|
116
95
|
|
|
117
|
-
|
|
96
|
+
- It is a named export (`export class` or `export { Name }`), not `export default`.
|
|
97
|
+
- It is not `abstract`.
|
|
98
|
+
- It carries exactly one of `@configuration`, `@component`, `@controller`, `@service`, `@repository` or `@datasource`, imported by name from `@venizia/ignis` or `@venizia/ignis-kernel` (aliases resolved). `@injectable({ type })` counts when `type` is a string literal or `ArtifactTypes.<NAME>`.
|
|
118
99
|
|
|
119
|
-
`@
|
|
120
|
-
a shell script.
|
|
100
|
+
`@model` classes are recognized and never emitted - a repository registers its model. A decorator re-exported through your own wrapper module is not recognized. Two stereotypes on one class fail the scan.
|
|
121
101
|
|
|
122
|
-
|
|
123
|
-
| :--- | :--- |
|
|
124
|
-
| `generateArtifactIndex(opts)` | Renders and writes `opts.out` when the content changed |
|
|
125
|
-
| `checkArtifactIndex(opts)` | Renders in memory and compares with `opts.out`, without writing |
|
|
126
|
-
| `IGenerateOptions` | `{ root, out, ignore?, exportName? }` - shared options for both |
|
|
127
|
-
| `ArtifactScanner.getInstance().scan({ root, ignore? })` | The scan step alone, as `IScannedArtifact[]` |
|
|
128
|
-
| `ArtifactIndexEmitter.render({ artifacts, outFile, exportName })` | The render step alone, as text |
|
|
129
|
-
| `ArtifactStereotypes`, `ArtifactTypes`, `ArtifactIndexFields` | The decorator-to-type map and the emitted field names |
|
|
102
|
+
The output is deterministic: imports sorted by path, names sorted within each field, empty fields kept, a field wider than 100 columns wrapped one name per line.
|
|
130
103
|
|
|
131
|
-
|
|
132
|
-
import { checkArtifactIndex } from '@venizia/ignis-boot/generator';
|
|
104
|
+
## `ignis-build-info`
|
|
133
105
|
|
|
134
|
-
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
## `ignis-build-info` - stamp the build
|
|
138
|
-
|
|
139
|
-
A second binary in the same package. It resolves what a running service should be able to say
|
|
140
|
-
about itself - service, version, commit, branch, build time - at BUILD time, and writes it as a
|
|
141
|
-
static file the bundle bakes in. Nothing is read back at run time: a `bun build --compile` binary
|
|
142
|
-
ships no `node_modules`, no `.git` and no readable `package.json`, and a Distroless image has no
|
|
143
|
-
`git` to spawn, so a runtime resolver would report blanks in exactly the deployment that matters.
|
|
106
|
+
A compiled binary or a Distroless image has no `.git` and no readable `package.json`, so `ignis-build-info` resolves the build stamp at build time and writes it as a static file.
|
|
144
107
|
|
|
145
108
|
```
|
|
146
109
|
ignis-build-info generate [--out src/_build_info.ts] [--root .] [--format ts|json] [--export BUILD_INFO]
|
|
147
110
|
```
|
|
148
111
|
|
|
149
112
|
| Flag | Default | Meaning |
|
|
150
|
-
|
|
151
|
-
| `--out` | `src/_build_info.ts` | Output
|
|
152
|
-
| `--root` | `.` | Where `package.json` is read and
|
|
153
|
-
| `--format` | `ts` | `ts`
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| `--out` | `src/_build_info.ts` | Output file; rewritten on every run |
|
|
115
|
+
| `--root` | `.` | Where `package.json` is read and `git` runs |
|
|
116
|
+
| `--format` | `ts` | `ts` writes an `export const`; `json` writes the same record as JSON |
|
|
154
117
|
| `--export` | `BUILD_INFO` | Name of the exported constant in `ts` format |
|
|
155
118
|
|
|
156
|
-
Each field
|
|
157
|
-
`unspecified`, so a pipeline that forgot a variable is visible rather than silent.
|
|
119
|
+
Each field reads the environment first (first non-blank key wins), then its fallback. A field nothing resolves reads `unspecified`.
|
|
158
120
|
|
|
159
|
-
| Field | Environment,
|
|
160
|
-
|
|
161
|
-
| `
|
|
121
|
+
| Field | Environment keys, in order | Fallback |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| `service` | - | `package.json` `name` |
|
|
124
|
+
| `version` | `APP_ENV_BUILD_VERSION`, `APP_BUILD_VERSION`, `CI_COMMIT_TAG`, `GITHUB_REF_NAME` | `package.json` `version` |
|
|
162
125
|
| `commit` | `APP_ENV_BUILD_COMMIT_TAG`, `APP_BUILD_COMMIT`, `CI_COMMIT_SHA`, `GITHUB_SHA`, `COMMIT_SHA` | `git rev-parse --short=12 HEAD` |
|
|
163
126
|
| `branch` | `APP_BUILD_BRANCH`, `CI_COMMIT_REF_NAME`, `GITHUB_REF_NAME`, `BRANCH_NAME` | `git rev-parse --abbrev-ref HEAD` |
|
|
164
|
-
| `builtAt` | `APP_ENV_BUILD_DATE`, `APP_BUILD_DATE` | the
|
|
165
|
-
| `service` | - | `package.json#name` |
|
|
127
|
+
| `builtAt` | `APP_ENV_BUILD_DATE`, `APP_BUILD_DATE` | the time the generator ran |
|
|
166
128
|
|
|
167
|
-
Register the stamp once at the
|
|
129
|
+
Register the stamp once at the entry point. The health-check component's `/stats` route reports it:
|
|
168
130
|
|
|
169
131
|
```typescript
|
|
170
|
-
import { BUILD_INFO } from './_build_info';
|
|
171
132
|
import { BuildInfoRegistry } from '@venizia/ignis-helpers/core';
|
|
133
|
+
import { BUILD_INFO } from './_build_info';
|
|
172
134
|
|
|
173
135
|
BuildInfoRegistry.set({ buildInfo: BUILD_INFO });
|
|
174
136
|
```
|
|
175
137
|
|
|
176
|
-
|
|
177
|
-
Node the `git` fields degrade to `unspecified` and the build still succeeds; set the variables
|
|
178
|
-
above if a Node invocation has to be exact.
|
|
138
|
+
## Entry points
|
|
179
139
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
`
|
|
140
|
+
| Subpath | What it gives | Extra peers |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| `@venizia/ignis-boot` | Everything from the two subpaths below | `typescript` |
|
|
143
|
+
| `@venizia/ignis-boot/generator` | `generateArtifactIndex`, `checkArtifactIndex`, `ArtifactScanner`, `ArtifactIndexEmitter`, `ArtifactStereotypes`, `ArtifactTypes`, `ArtifactIndexFields` | `typescript` |
|
|
144
|
+
| `@venizia/ignis-boot/build-info` | `generateBuildInfo`, `BuildInfoResolver`, `BuildInfoEmitter`, `BuildInfoFormats`, `BuildInfoEnvironmentKeys` | none |
|
|
145
|
+
|
|
146
|
+
| Binary | File |
|
|
147
|
+
|---|---|
|
|
148
|
+
| `ignis-artifacts` | `dist/cjs/clis/artifacts.js` |
|
|
149
|
+
| `ignis-build-info` | `dist/cjs/clis/build-info.js` |
|
|
150
|
+
|
|
151
|
+
The package ships CommonJS and ESM builds. The programmatic API mirrors the CLI:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { checkArtifactIndex } from '@venizia/ignis-boot/generator';
|
|
155
|
+
|
|
156
|
+
const { isFresh } = checkArtifactIndex({ root: 'src', out: 'src/generated/artifacts.ts' });
|
|
157
|
+
```
|
|
183
158
|
|
|
184
|
-
##
|
|
159
|
+
## Where it sits
|
|
185
160
|
|
|
186
|
-
-
|
|
187
|
-
field per kind, empty arrays kept. A field wider than 100 columns wraps one name per line, so the
|
|
188
|
-
file passes the repo's `prettier -l` unchanged.
|
|
189
|
-
- **The scanner never executes a module.** No decorator runs and no import side effect fires while
|
|
190
|
-
scanning, so a stereotype re-exported through a local wrapper module is not recognised - the
|
|
191
|
-
import must name an IGNIS module directly.
|
|
192
|
-
- **`check` belongs where lint runs**, not only in CI - a stale index should fail locally before a
|
|
193
|
-
push reaches the pipeline.
|
|
161
|
+
`dev-configs -> inversion -> {filter, helpers} -> {boot, kernel} -> connectors -> {core-worker, core-server} -> atlas`. Boot depends on `@venizia/ignis-helpers` only; no IGNIS package depends on boot, so the application declares it.
|
|
194
162
|
|
|
195
|
-
|
|
163
|
+
The generated index replaces the runtime booters IGNIS once took from LoopBack 4, which globbed the file system at startup.
|
|
196
164
|
|
|
197
165
|
## Links
|
|
198
166
|
|
|
199
|
-
[
|
|
200
|
-
[
|
|
201
|
-
[
|
|
202
|
-
[
|
|
203
|
-
[
|
|
167
|
+
- [Registering artifacts (guide)](https://ignis.venizia.ai/guides/core-concepts/application/bootstrapping)
|
|
168
|
+
- [Artifact registration (reference)](https://ignis.venizia.ai/references/base/bootstrapping)
|
|
169
|
+
- [Build info](https://ignis.venizia.ai/guides/core-concepts/application/build-info)
|
|
170
|
+
- [Runtime boot API removed](https://ignis.venizia.ai/changelogs/2026-09-03-deprecated-boot-api-removed)
|
|
171
|
+
- [Changelogs](https://ignis.venizia.ai/changelogs/)
|
|
172
|
+
- [Source](https://github.com/VENIZIA-AI/ignis/blob/main/packages/boot)
|
|
204
173
|
|
|
205
|
-
MIT licensed - see [LICENSE.md](LICENSE.md).
|
|
206
|
-
Questions: [GitHub Issues](https://github.com/VENIZIA-AI/ignis/issues) • developer@venizia.ai
|
|
174
|
+
MIT licensed - see [LICENSE.md](./LICENSE.md).
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@venizia/ignis-boot",
|
|
3
|
-
"version": "0.2.0-
|
|
3
|
+
"version": "0.2.0-36",
|
|
4
4
|
"description": "Build-time artifact index generator for IGNIS applications: scans decorated classes with the TypeScript AST and emits one static registration file per package, so bun build --compile sees plain imports.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"artifact-index",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
},
|
|
31
31
|
"license": "MIT",
|
|
32
32
|
"engines": {
|
|
33
|
-
"bun": ">=1.
|
|
33
|
+
"bun": ">=1.4"
|
|
34
34
|
},
|
|
35
35
|
"main": "./dist/cjs/index.js",
|
|
36
36
|
"module": "./dist/esm/index.js",
|
|
@@ -84,7 +84,7 @@
|
|
|
84
84
|
"test:watch": "NODE_ENV=test bun test --watch --env-file=.env.test"
|
|
85
85
|
},
|
|
86
86
|
"dependencies": {
|
|
87
|
-
"@venizia/ignis-helpers": "^0.2.0-
|
|
87
|
+
"@venizia/ignis-helpers": "^0.2.0-41"
|
|
88
88
|
},
|
|
89
89
|
"devDependencies": {
|
|
90
90
|
"@types/bun": "^1.4.1",
|