@tech4good/platform-tooling 0.1.0-alpha.0 → 0.1.0-alpha.2
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 +143 -16
- package/dist/entities-cli.d.ts +2 -0
- package/dist/entities-cli.js +141 -0
- package/dist/entity-registry.d.ts +57 -0
- package/dist/entity-registry.js +302 -0
- package/dist/firestore-indexes.d.ts +20 -0
- package/dist/firestore-indexes.js +49 -7
- package/dist/index.d.ts +1 -0
- package/dist/index.js +5 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -5,7 +5,10 @@ checks local Firestore composite-index definitions against supported lab query
|
|
|
5
5
|
calls. It runs as compiled JavaScript on Node.js 22 or later and has no Angular
|
|
6
6
|
runtime or Firebase credential dependency.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
`t4g-entities` also generates application entity/mock registries from declarations
|
|
9
|
+
beside each model, with watch mode for development. See [entity discovery](#entity-discovery-and-generated-registries).
|
|
10
|
+
|
|
11
|
+
The packaging pilot is currently versioned as `0.1.0-alpha.2`. The query analyzer was
|
|
9
12
|
extracted from angular-schematics without changing its index-planning behavior.
|
|
10
13
|
Store-feature discovery also recognizes named and aliased imports from packages
|
|
11
14
|
whose implementations are outside the scanned app sources.
|
|
@@ -14,10 +17,10 @@ This also improves discovery of stores created through an imported Angular
|
|
|
14
17
|
|
|
15
18
|
## Use in an application
|
|
16
19
|
|
|
17
|
-
|
|
20
|
+
Install it as a development dependency:
|
|
18
21
|
|
|
19
22
|
```bash
|
|
20
|
-
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.
|
|
23
|
+
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.2
|
|
21
24
|
```
|
|
22
25
|
|
|
23
26
|
Use these package scripts (also emitted by the updated `ng-add` schematic):
|
|
@@ -57,6 +60,33 @@ local customizations and updating direct imports/callers. Do not rerun the
|
|
|
57
60
|
overwrite-based `ng-add` schematic to adopt this package. Future checker fixes
|
|
58
61
|
arrive by updating this dependency and its lockfile.
|
|
59
62
|
|
|
63
|
+
## Understand missing-index messages
|
|
64
|
+
|
|
65
|
+
Each missing index identifies the query that needs it. For example, a store
|
|
66
|
+
load with `problemCount > 3` and empty query options can report:
|
|
67
|
+
|
|
68
|
+
```text
|
|
69
|
+
Missing index: collections at src/app/main/home/home.component.ts:54 (initial load)
|
|
70
|
+
[{"fieldPath":"_deleted","order":"ASCENDING"},{"fieldPath":"problemCount","order":"ASCENDING"},{"fieldPath":"__name__","order":"ASCENDING"}]
|
|
71
|
+
Missing index: collections at src/app/main/home/home.component.ts:54 (incremental reload)
|
|
72
|
+
[{"fieldPath":"_deleted","order":"ASCENDING"},{"fieldPath":"_updatedAt","order":"ASCENDING"},{"fieldPath":"problemCount","order":"ASCENDING"},{"fieldPath":"__name__","order":"ASCENDING"}]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
An initial load uses your filters plus the store's `_deleted` filter. With empty
|
|
76
|
+
query options, later loads also add `_updatedAt > lastLoadTime` to fetch changes.
|
|
77
|
+
Those queries can need different indexes. Equality-only initial loads may be
|
|
78
|
+
covered by automatic indexes, so only the incremental index may be reported.
|
|
79
|
+
|
|
80
|
+
Other labels distinguish streams (initial results and live updates), counts,
|
|
81
|
+
aggregates, and direct database queries. A **full load with query options**
|
|
82
|
+
reuses the full query on subsequent loads, without an automatic timestamp cutoff.
|
|
83
|
+
When multiple calls or load stages need the same index, **Also needed for** lists
|
|
84
|
+
their purposes and locations. The definition is reported and added only once.
|
|
85
|
+
|
|
86
|
+
These message improvements were introduced in `0.1.0-alpha.1`; applications pinned to
|
|
87
|
+
`0.1.0-alpha.0` still use the earlier output. Use the local-development commands
|
|
88
|
+
below to try them before publishing.
|
|
89
|
+
|
|
60
90
|
## Programmatic API
|
|
61
91
|
|
|
62
92
|
Both ESM imports and CommonJS `require` are supported. Importing the library
|
|
@@ -79,6 +109,11 @@ that were found and added during that run; rerun without `fix` to verify the
|
|
|
79
109
|
resulting file. The package owns its TypeScript parser dependency, independently
|
|
80
110
|
of the application's compiler version.
|
|
81
111
|
|
|
112
|
+
Each missing index includes `query` for its first use and `queries` for all uses.
|
|
113
|
+
Each query's `purpose` is `initial-load`, `incremental-load`, `full-load`, `stream`,
|
|
114
|
+
`count`, `aggregate`, or `database-query`. Shared requirements remain one entry
|
|
115
|
+
in `missingIndexes`, even when multiple query purposes or locations need them.
|
|
116
|
+
|
|
82
117
|
## Supported scope
|
|
83
118
|
|
|
84
119
|
- Lab store `load`, `stream`, `count`, and `aggregate` calls.
|
|
@@ -131,7 +166,7 @@ npm run test:indexes
|
|
|
131
166
|
npm run pack:tooling
|
|
132
167
|
```
|
|
133
168
|
|
|
134
|
-
The last command creates `tech4good-platform-tooling-0.1.0-alpha.
|
|
169
|
+
The last command creates `tech4good-platform-tooling-0.1.0-alpha.2.tgz` in the repository
|
|
135
170
|
root. In a disposable application checkout, install its absolute path as a dev
|
|
136
171
|
dependency and apply the scripts shown above. A tarball installation exercises
|
|
137
172
|
the same compiled files, exports, and executable that npm consumers receive.
|
|
@@ -168,7 +203,7 @@ cd /path/to/angular-schematics
|
|
|
168
203
|
npm run pack:tooling
|
|
169
204
|
|
|
170
205
|
cd /path/to/math-pets
|
|
171
|
-
npm install --no-save --package-lock=false /path/to/angular-schematics/tech4good-platform-tooling-0.1.0-alpha.
|
|
206
|
+
npm install --no-save --package-lock=false /path/to/angular-schematics/tech4good-platform-tooling-0.1.0-alpha.2.tgz
|
|
172
207
|
./node_modules/.bin/t4g-check-firestore-indexes
|
|
173
208
|
```
|
|
174
209
|
|
|
@@ -214,14 +249,15 @@ the Angular/schematics version.
|
|
|
214
249
|
|
|
215
250
|
### 1. Prepare the version
|
|
216
251
|
|
|
217
|
-
|
|
218
|
-
|
|
252
|
+
This checkout is prepared for `0.1.0-alpha.2`. It is already set in the package
|
|
253
|
+
manifest, root lockfile, and generated dependency; do not bump again to publish
|
|
254
|
+
this release.
|
|
219
255
|
|
|
220
256
|
For a subsequent release, choose an unused version and bump only this workspace.
|
|
221
|
-
For example, after publishing `0.1.0-alpha.
|
|
257
|
+
For example, after publishing `0.1.0-alpha.2`, prepare the next alpha with:
|
|
222
258
|
|
|
223
259
|
```bash
|
|
224
|
-
npm version 0.1.0-alpha.
|
|
260
|
+
npm version 0.1.0-alpha.3 --workspace @tech4good/platform-tooling --no-git-tag-version --ignore-scripts
|
|
225
261
|
```
|
|
226
262
|
|
|
227
263
|
Replace the example version with the one being released. This updates
|
|
@@ -233,6 +269,9 @@ Then update these files together:
|
|
|
233
269
|
|
|
234
270
|
- Set `devDependencies["@tech4good/platform-tooling"]` in
|
|
235
271
|
`src/ng-add/files/package.json.template` to the same exact version.
|
|
272
|
+
- Update the root `package.json` dependency on platform-tooling as well; schematics
|
|
273
|
+
use its registry generator. Run `npm install --package-lock-only --ignore-scripts`
|
|
274
|
+
to synchronize the lockfile after changing dependency pins.
|
|
236
275
|
- Record the release's changes under that version in `packages/tooling/CHANGELOG.md`.
|
|
237
276
|
- Update versioned installation examples and remove any obsolete "unpublished"
|
|
238
277
|
wording in this README and the root README as part of preparing the release.
|
|
@@ -261,7 +300,7 @@ Publish from that reviewed release commit.
|
|
|
261
300
|
|
|
262
301
|
### 3. Publish to npm
|
|
263
302
|
|
|
264
|
-
For
|
|
303
|
+
For this alpha release:
|
|
265
304
|
|
|
266
305
|
```bash
|
|
267
306
|
npm login
|
|
@@ -289,20 +328,20 @@ different contents, so later changes require a new version.
|
|
|
289
328
|
|
|
290
329
|
### 4. Verify and record the published release
|
|
291
330
|
|
|
292
|
-
For
|
|
331
|
+
For this alpha (substitute the actual version for later releases):
|
|
293
332
|
|
|
294
333
|
```bash
|
|
295
|
-
npm view @tech4good/platform-tooling@0.1.0-alpha.
|
|
334
|
+
npm view @tech4good/platform-tooling@0.1.0-alpha.2 version
|
|
296
335
|
npm view @tech4good/platform-tooling dist-tags
|
|
297
|
-
git tag -a platform-tooling-v0.1.0-alpha.
|
|
336
|
+
git tag -a platform-tooling-v0.1.0-alpha.2 -m "Release @tech4good/platform-tooling 0.1.0-alpha.2"
|
|
298
337
|
```
|
|
299
338
|
|
|
300
|
-
Confirm the first command returns `0.1.0-alpha.
|
|
339
|
+
Confirm the first command returns `0.1.0-alpha.2` and the `alpha` tag points to
|
|
301
340
|
that version. Create the Git tag on the release commit, and push that commit
|
|
302
341
|
through the repository's normal Git workflow. Then push this specific tag:
|
|
303
342
|
|
|
304
343
|
```bash
|
|
305
|
-
git push origin platform-tooling-v0.1.0-alpha.
|
|
344
|
+
git push origin platform-tooling-v0.1.0-alpha.2
|
|
306
345
|
```
|
|
307
346
|
|
|
308
347
|
The `platform-tooling-v` prefix distinguishes tooling releases from the existing
|
|
@@ -314,7 +353,7 @@ npm before releasing angular-schematics with a template that references it.
|
|
|
314
353
|
From the application's directory, install the chosen published version:
|
|
315
354
|
|
|
316
355
|
```bash
|
|
317
|
-
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.
|
|
356
|
+
npm install --save-dev --save-exact @tech4good/platform-tooling@0.1.0-alpha.2
|
|
318
357
|
npm run check:indexes
|
|
319
358
|
```
|
|
320
359
|
|
|
@@ -322,3 +361,91 @@ For first-time adoption, also add or replace `check:indexes` and `fix:indexes`
|
|
|
322
361
|
with the commands in [Use in an application](#use-in-an-application) before running the check.
|
|
323
362
|
Commit the application's updated `package.json` and lockfile. A tooling upgrade
|
|
324
363
|
does not require upgrading angular-schematics in that application.
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
## Entity discovery and generated registries
|
|
367
|
+
|
|
368
|
+
Starting in `0.1.0-alpha.2`, `t4g-entities` collects entity definitions from the
|
|
369
|
+
consuming application. Runtime helpers come from `@tech4good/platform-data`.
|
|
370
|
+
No application models or fixtures are published inside platform-tooling.
|
|
371
|
+
|
|
372
|
+
Declare an exported constant beside its interface in `*.model.ts`:
|
|
373
|
+
|
|
374
|
+
```ts
|
|
375
|
+
import { DataEntity, defineEntity } from '@tech4good/platform-data';
|
|
376
|
+
export interface Problem extends DataEntity { title: string; }
|
|
377
|
+
export const problemEntity = defineEntity<Problem>({ collection: 'problems' });
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
The store uses `problemEntity.collection`. Optionally export a mock definition
|
|
381
|
+
from `*.mock.ts`, importing the entity directly from its relative model file:
|
|
382
|
+
|
|
383
|
+
```ts
|
|
384
|
+
import { defineEntityMock } from '@tech4good/platform-data/testing';
|
|
385
|
+
import { problemEntity } from './problem.model';
|
|
386
|
+
|
|
387
|
+
// Reuse the mock store and fixtures declared in this file.
|
|
388
|
+
export const problemMock = defineEntityMock(problemEntity, {
|
|
389
|
+
store: ProblemMockDB,
|
|
390
|
+
seeds: PROBLEM_DB,
|
|
391
|
+
});
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
Without a custom mock definition, generation supplies an empty in-memory mock
|
|
395
|
+
collection. With one, the concrete mock-store type and fixture types are retained.
|
|
396
|
+
Factories and seed arrays are evaluated by the application, never by discovery.
|
|
397
|
+
Named import aliases and namespace imports are supported. Collection names must
|
|
398
|
+
be literals. Definition calls must initialize exported top-level constants;
|
|
399
|
+
dynamic collection expressions and indirect/barrel model imports in mock
|
|
400
|
+
definitions are rejected with an actionable filename. Ordinary model interfaces
|
|
401
|
+
without `defineEntity` are ignored; they may be unrelated UI types.
|
|
402
|
+
|
|
403
|
+
```bash
|
|
404
|
+
# Generate once, or verify committed generated files without writing.
|
|
405
|
+
npx t4g-entities
|
|
406
|
+
npx t4g-entities --check
|
|
407
|
+
|
|
408
|
+
# Generate before starting the child process, then watch additions/edits/deletions.
|
|
409
|
+
npx t4g-entities --watch -- ng serve
|
|
410
|
+
npx t4g-entities --watch -- jest --watch
|
|
411
|
+
|
|
412
|
+
# Generate and run a one-off command; propagate its exit status.
|
|
413
|
+
npx t4g-entities -- ng build
|
|
414
|
+
|
|
415
|
+
# Inspect/help, or use another project's root.
|
|
416
|
+
npx t4g-entities --help
|
|
417
|
+
npx t4g-entities --project-root /path/to/math-pets
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
The default scan root is `src/app`. The two generated files under
|
|
421
|
+
`src/app/core/store` are `entities.generated.ts` (`APP_ENTITIES`, `AppEntityMap`)
|
|
422
|
+
and `entity-mocks.generated.ts` (`APP_ENTITY_MOCKS`). `--source-root` and
|
|
423
|
+
`--output-dir` accept project-relative directories for other layouts. Output is
|
|
424
|
+
sorted and unchanged files are not rewritten. Generation refuses to overwrite
|
|
425
|
+
handwritten output files; duplicates, invalid declarations, and dangling mocks
|
|
426
|
+
fail before changing the registries. It does not edit services, security rules,
|
|
427
|
+
indexes, or model files.
|
|
428
|
+
|
|
429
|
+
The watcher polls definition files every 300 ms, including newly created
|
|
430
|
+
folders. Invalid edits report an error and retain the last valid registry;
|
|
431
|
+
correcting the file resumes generation. The supervised command stops the watcher
|
|
432
|
+
when it exits. Interrupting the CLI also terminates its command process group
|
|
433
|
+
on POSIX systems. Watch mode is for development; use one-shot generation or
|
|
434
|
+
`--check` as the build/CI gate.
|
|
435
|
+
|
|
436
|
+
Generated applications wire this into `npm start`, `npm run watch`, and
|
|
437
|
+
`npm run test:watch`; build/test/lint regenerate first. Direct `ng`/`jest` commands
|
|
438
|
+
bypass those scripts. Keep generated files in git for editor support and review,
|
|
439
|
+
and run `check:entities` before regeneration when CI should detect stale output.
|
|
440
|
+
No shared-package release is needed when an app adds an entity.
|
|
441
|
+
|
|
442
|
+
Import `APP_ENTITY_MOCKS` only from mock/test composition. Generated apps replace
|
|
443
|
+
`data.providers.ts` with `data.providers.prod.ts` in production, so fixture modules
|
|
444
|
+
are excluded from the production import graph. The real registry has no mock
|
|
445
|
+
imports. The index checker understands collection names read through
|
|
446
|
+
`problemEntity.collection`.
|
|
447
|
+
|
|
448
|
+
For schematic authors, the package also exports the pure
|
|
449
|
+
`generateEntityRegistrySources(sources, options)` API for virtual file trees and
|
|
450
|
+
`generateEntityRegistries(options)` / `watchEntityRegistries(options, callbacks)`
|
|
451
|
+
for disk-based workflows. Sources are a map of project-relative paths to text.
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
"use strict";
|
|
3
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
4
|
+
const node_child_process_1 = require("node:child_process");
|
|
5
|
+
const entity_registry_1 = require("./entity-registry");
|
|
6
|
+
const help = `Usage: t4g-entities [--check | --watch] [--project-root <path>] [-- <command> ...]
|
|
7
|
+
|
|
8
|
+
Discover defineEntity exports in *.model.ts and defineEntityMock exports in *.mock.ts.
|
|
9
|
+
Generate entities.generated.ts and entity-mocks.generated.ts inside the app.
|
|
10
|
+
|
|
11
|
+
--check Fail if generated files are missing/stale; do not write
|
|
12
|
+
--watch Regenerate when definitions are added, changed, or removed
|
|
13
|
+
--project-root <path> Default: current directory
|
|
14
|
+
--source-root <path> Project-relative scan directory (default: src/app)
|
|
15
|
+
--output-dir <path> Project-relative output directory (default: src/app/core/store)
|
|
16
|
+
-- <command> ... Generate first, then run a command; keep watcher alive until it exits
|
|
17
|
+
--help, -h Show this help
|
|
18
|
+
|
|
19
|
+
Examples: t4g-entities --watch -- ng serve
|
|
20
|
+
t4g-entities -- ng build
|
|
21
|
+
t4g-entities --check
|
|
22
|
+
|
|
23
|
+
No app code is executed during discovery. No Firebase connection or deployment is made.`;
|
|
24
|
+
/**
|
|
25
|
+
* Parse generator flags before `--`; pass subsequent arguments unchanged to the
|
|
26
|
+
* child command. Generation must succeed before starting Angular or another tool.
|
|
27
|
+
* In watch mode this process owns both the poller and the child's lifetime.
|
|
28
|
+
*/
|
|
29
|
+
async function main(args) {
|
|
30
|
+
const options = {};
|
|
31
|
+
let check = false;
|
|
32
|
+
let watch = false;
|
|
33
|
+
let command = [];
|
|
34
|
+
for (let i = 0; i < args.length; i++) {
|
|
35
|
+
const arg = args[i];
|
|
36
|
+
if (arg === '--') {
|
|
37
|
+
command = args.slice(i + 1);
|
|
38
|
+
if (!command.length)
|
|
39
|
+
throw new Error('-- requires a command.');
|
|
40
|
+
break;
|
|
41
|
+
}
|
|
42
|
+
if (arg === '--help' || arg === '-h') {
|
|
43
|
+
console.log(help);
|
|
44
|
+
return 0;
|
|
45
|
+
}
|
|
46
|
+
if (arg === '--check')
|
|
47
|
+
check = true;
|
|
48
|
+
else if (arg === '--watch')
|
|
49
|
+
watch = true;
|
|
50
|
+
else if (['--project-root', '--source-root', '--output-dir'].includes(arg)) {
|
|
51
|
+
const value = args[++i];
|
|
52
|
+
if (!value || value.startsWith('-'))
|
|
53
|
+
throw new Error(`${arg} requires a path.`);
|
|
54
|
+
if (arg === '--project-root')
|
|
55
|
+
options.projectRoot = value;
|
|
56
|
+
if (arg === '--source-root')
|
|
57
|
+
options.sourceRoot = value;
|
|
58
|
+
if (arg === '--output-dir')
|
|
59
|
+
options.outputDir = value;
|
|
60
|
+
}
|
|
61
|
+
else
|
|
62
|
+
throw new Error(`Unknown argument: ${arg}`);
|
|
63
|
+
}
|
|
64
|
+
if (check && (watch || command.length))
|
|
65
|
+
throw new Error('--check cannot be combined with --watch or a command.');
|
|
66
|
+
const report = (result) => {
|
|
67
|
+
if (result.changed.length)
|
|
68
|
+
console.log(`[entities] ${result.collections.length} collections; ${result.success ? 'generated' : 'stale'}: ${result.changed.join(', ')}`);
|
|
69
|
+
};
|
|
70
|
+
const watcher = watch ? (0, entity_registry_1.watchEntityRegistries)(options, {
|
|
71
|
+
onChange: report,
|
|
72
|
+
onError: error => console.error(`[entities] ${error.message} Fix the definition to regenerate; previous output is unchanged.`),
|
|
73
|
+
}) : undefined;
|
|
74
|
+
if (!watch) {
|
|
75
|
+
const result = (0, entity_registry_1.generateEntityRegistries)({ ...options, check });
|
|
76
|
+
report(result);
|
|
77
|
+
if (!result.success)
|
|
78
|
+
return 1;
|
|
79
|
+
}
|
|
80
|
+
if (!command.length && !watcher)
|
|
81
|
+
return 0;
|
|
82
|
+
return new Promise(resolve => {
|
|
83
|
+
// Spawn without a shell to preserve argument boundaries. A separate POSIX
|
|
84
|
+
// process group lets shutdown reach descendants such as npm -> ng serve.
|
|
85
|
+
const child = command.length ? (0, node_child_process_1.spawn)(command[0], command.slice(1), {
|
|
86
|
+
cwd: options.projectRoot, stdio: 'inherit', detached: process.platform !== 'win32',
|
|
87
|
+
}) : undefined;
|
|
88
|
+
let finished = false;
|
|
89
|
+
let stopping = false;
|
|
90
|
+
let killTimer;
|
|
91
|
+
/** Shared exit path for spawn errors, child exits and wrapper termination. */
|
|
92
|
+
function finish(code) {
|
|
93
|
+
if (finished)
|
|
94
|
+
return;
|
|
95
|
+
finished = true;
|
|
96
|
+
watcher?.close();
|
|
97
|
+
if (killTimer)
|
|
98
|
+
clearTimeout(killTimer);
|
|
99
|
+
process.off('SIGINT', interrupt);
|
|
100
|
+
process.off('SIGTERM', terminate);
|
|
101
|
+
resolve(code);
|
|
102
|
+
}
|
|
103
|
+
function kill(signal) {
|
|
104
|
+
if (!child?.pid)
|
|
105
|
+
return;
|
|
106
|
+
try {
|
|
107
|
+
if (process.platform !== 'win32')
|
|
108
|
+
process.kill(-child.pid, signal);
|
|
109
|
+
else
|
|
110
|
+
child.kill(signal);
|
|
111
|
+
}
|
|
112
|
+
catch (error) {
|
|
113
|
+
if (error.code !== 'ESRCH')
|
|
114
|
+
throw error;
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
/** Stop polling first, allow graceful child cleanup, then bound shutdown time. */
|
|
118
|
+
function stop(signal) {
|
|
119
|
+
if (stopping)
|
|
120
|
+
return;
|
|
121
|
+
stopping = true;
|
|
122
|
+
watcher?.close();
|
|
123
|
+
if (!child) {
|
|
124
|
+
finish(signal === 'SIGINT' ? 130 : 143);
|
|
125
|
+
return;
|
|
126
|
+
}
|
|
127
|
+
kill(signal);
|
|
128
|
+
killTimer = setTimeout(() => { kill('SIGKILL'); finish(signal === 'SIGINT' ? 130 : 143); }, 2000);
|
|
129
|
+
}
|
|
130
|
+
const interrupt = () => stop('SIGINT');
|
|
131
|
+
const terminate = () => stop('SIGTERM');
|
|
132
|
+
process.on('SIGINT', interrupt);
|
|
133
|
+
process.on('SIGTERM', terminate);
|
|
134
|
+
child?.once('error', error => { console.error(error.message); finish(1); });
|
|
135
|
+
child?.once('exit', (code, signal) => { kill('SIGTERM'); finish(code ?? (signal === 'SIGINT' ? 130 : 143)); });
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
main(process.argv.slice(2)).then(code => { process.exitCode = code; }).catch(error => {
|
|
139
|
+
console.error(`[entities] ${error instanceof Error ? error.message : String(error)}`);
|
|
140
|
+
process.exitCode = 1;
|
|
141
|
+
});
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Source-only entity discovery shared by the CLI and Angular schematics.
|
|
3
|
+
* Parse declarations instead of importing application modules: importing them
|
|
4
|
+
* could initialize Angular/Firebase or pull mock fixtures into build tooling.
|
|
5
|
+
* Generated files belong to the consuming app, not the published data package.
|
|
6
|
+
*/
|
|
7
|
+
/** Filesystem settings; sourceRoot/outputDir must remain project-relative. */
|
|
8
|
+
export interface EntityRegistryOptions {
|
|
9
|
+
/** Filesystem project root for disk operations; defaults to the current directory. */
|
|
10
|
+
projectRoot?: string;
|
|
11
|
+
/** Project-relative directory containing entity files. Defaults to src/app. */
|
|
12
|
+
sourceRoot?: string;
|
|
13
|
+
/** Project-relative generated-file directory. Defaults to src/app/core/store. */
|
|
14
|
+
outputDir?: string;
|
|
15
|
+
}
|
|
16
|
+
export interface EntityRegistryResult {
|
|
17
|
+
/** Generated TypeScript text keyed by project-relative destination path. */
|
|
18
|
+
files: Record<string, string>;
|
|
19
|
+
/** Discovered collection names in deterministic order. */
|
|
20
|
+
collections: string[];
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Produce both registry modules from project-relative source text, with no disk
|
|
24
|
+
* access or app execution. Also accepts the leading slash used by schematic Trees.
|
|
25
|
+
* Models are discovered first, then mocks are matched by direct relative import.
|
|
26
|
+
* Invalid declarations, duplicate collections and orphan mocks throw before any
|
|
27
|
+
* output is returned. Files without entity helper calls need no registration.
|
|
28
|
+
*/
|
|
29
|
+
export declare function generateEntityRegistrySources(sources: Record<string, string>, options?: Pick<EntityRegistryOptions, 'sourceRoot' | 'outputDir'>): EntityRegistryResult;
|
|
30
|
+
/**
|
|
31
|
+
* Discover from disk and write changed registries, or compare only with check:true.
|
|
32
|
+
* `changed` lists different/missing outputs in either mode; `success` is false
|
|
33
|
+
* only when check mode finds stale output. Discovery or filesystem errors throw.
|
|
34
|
+
*/
|
|
35
|
+
export declare function generateEntityRegistries(options?: EntityRegistryOptions & {
|
|
36
|
+
check?: boolean;
|
|
37
|
+
}): {
|
|
38
|
+
changed: string[];
|
|
39
|
+
success: boolean;
|
|
40
|
+
/** Generated TypeScript text keyed by project-relative destination path. */
|
|
41
|
+
files: Record<string, string>;
|
|
42
|
+
/** Discovered collection names in deterministic order. */
|
|
43
|
+
collections: string[];
|
|
44
|
+
};
|
|
45
|
+
/**
|
|
46
|
+
* Generate synchronously before starting a polling watcher, so callers can start
|
|
47
|
+
* Angular only after valid modules exist. Polling finds new/deleted directories
|
|
48
|
+
* across Node platforms. Later invalid edits report onError and retain the last
|
|
49
|
+
* valid output; another source edit retries. The caller must close the watcher.
|
|
50
|
+
*/
|
|
51
|
+
export declare function watchEntityRegistries(options: EntityRegistryOptions, callbacks?: {
|
|
52
|
+
onChange?: (result: ReturnType<typeof generateEntityRegistries>) => void;
|
|
53
|
+
onError?: (error: Error) => void;
|
|
54
|
+
intervalMs?: number;
|
|
55
|
+
}): {
|
|
56
|
+
close(): void;
|
|
57
|
+
};
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
|
|
14
|
+
Object.defineProperty(o, "default", { enumerable: true, value: v });
|
|
15
|
+
}) : function(o, v) {
|
|
16
|
+
o["default"] = v;
|
|
17
|
+
});
|
|
18
|
+
var __importStar = (this && this.__importStar) || (function () {
|
|
19
|
+
var ownKeys = function(o) {
|
|
20
|
+
ownKeys = Object.getOwnPropertyNames || function (o) {
|
|
21
|
+
var ar = [];
|
|
22
|
+
for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
|
|
23
|
+
return ar;
|
|
24
|
+
};
|
|
25
|
+
return ownKeys(o);
|
|
26
|
+
};
|
|
27
|
+
return function (mod) {
|
|
28
|
+
if (mod && mod.__esModule) return mod;
|
|
29
|
+
var result = {};
|
|
30
|
+
if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
|
|
31
|
+
__setModuleDefault(result, mod);
|
|
32
|
+
return result;
|
|
33
|
+
};
|
|
34
|
+
})();
|
|
35
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
36
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
37
|
+
};
|
|
38
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
39
|
+
exports.generateEntityRegistrySources = generateEntityRegistrySources;
|
|
40
|
+
exports.generateEntityRegistries = generateEntityRegistries;
|
|
41
|
+
exports.watchEntityRegistries = watchEntityRegistries;
|
|
42
|
+
const fs = __importStar(require("node:fs"));
|
|
43
|
+
const path = __importStar(require("node:path"));
|
|
44
|
+
const typescript_1 = __importDefault(require("typescript"));
|
|
45
|
+
const slash = (value) => value.replace(/\\/g, '/');
|
|
46
|
+
const header = '// Generated by t4g-entities. Do not edit; update *.model.ts / *.mock.ts instead.\n';
|
|
47
|
+
function quote(value) {
|
|
48
|
+
return "'" + value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")
|
|
49
|
+
.replace(/[\u0000-\u001f\u2028\u2029]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`) + "'";
|
|
50
|
+
}
|
|
51
|
+
/** Normalize both slash styles so path validation is consistent across developer machines. */
|
|
52
|
+
function relativeDirectory(value) {
|
|
53
|
+
const portable = slash(value);
|
|
54
|
+
const normalized = path.posix.normalize(portable).replace(/\/+$/, '') || '.';
|
|
55
|
+
if (path.isAbsolute(value) || path.posix.isAbsolute(portable) || /^[a-z]:/i.test(portable) || normalized === '..' || normalized.startsWith('../')) {
|
|
56
|
+
throw new Error(`Entity registry paths must stay inside the project: ${value}`);
|
|
57
|
+
}
|
|
58
|
+
return normalized;
|
|
59
|
+
}
|
|
60
|
+
function unwrap(node) {
|
|
61
|
+
while (typescript_1.default.isParenthesizedExpression(node) || typescript_1.default.isAsExpression(node) || typescript_1.default.isSatisfiesExpression(node))
|
|
62
|
+
node = node.expression;
|
|
63
|
+
return node;
|
|
64
|
+
}
|
|
65
|
+
/** Resolve named aliases/namespace imports; type-only imports cannot identify runtime helpers. */
|
|
66
|
+
function imports(file) {
|
|
67
|
+
const values = new Map();
|
|
68
|
+
for (const statement of file.statements) {
|
|
69
|
+
if (!typescript_1.default.isImportDeclaration(statement) || !typescript_1.default.isStringLiteral(statement.moduleSpecifier) || statement.importClause?.isTypeOnly)
|
|
70
|
+
continue;
|
|
71
|
+
const bindings = statement.importClause?.namedBindings;
|
|
72
|
+
if (bindings && typescript_1.default.isNamedImports(bindings)) {
|
|
73
|
+
for (const binding of bindings.elements)
|
|
74
|
+
if (!binding.isTypeOnly) {
|
|
75
|
+
values.set(binding.name.text, { module: statement.moduleSpecifier.text, name: binding.propertyName?.text ?? binding.name.text });
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
else if (bindings && typescript_1.default.isNamespaceImport(bindings)) {
|
|
79
|
+
values.set(bindings.name.text, { module: statement.moduleSpecifier.text, name: '*' });
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
return values;
|
|
83
|
+
}
|
|
84
|
+
function reference(node, names) {
|
|
85
|
+
node = unwrap(node);
|
|
86
|
+
if (typescript_1.default.isIdentifier(node))
|
|
87
|
+
return names.get(node.text);
|
|
88
|
+
if (typescript_1.default.isPropertyAccessExpression(node) && typescript_1.default.isIdentifier(node.expression)) {
|
|
89
|
+
const parent = names.get(node.expression.text);
|
|
90
|
+
if (parent?.name === '*')
|
|
91
|
+
return { module: parent.module, name: node.name.text };
|
|
92
|
+
}
|
|
93
|
+
return undefined;
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Accept only exported top-level constants calling the expected package helper.
|
|
97
|
+
* Reject recognizable but unsupported uses instead of silently omitting entities.
|
|
98
|
+
* Arbitrary factories, re-export chains and app execution are outside this scanner.
|
|
99
|
+
*/
|
|
100
|
+
function declarations(file, helper, module) {
|
|
101
|
+
const names = imports(file);
|
|
102
|
+
const declarations = [];
|
|
103
|
+
function visit(node) {
|
|
104
|
+
if (typescript_1.default.isCallExpression(node)) {
|
|
105
|
+
const callee = reference(node.expression, names);
|
|
106
|
+
if (callee?.module === module && callee.name === helper) {
|
|
107
|
+
let parent = node;
|
|
108
|
+
while (parent.parent && (typescript_1.default.isParenthesizedExpression(parent.parent) || typescript_1.default.isAsExpression(parent.parent) || typescript_1.default.isSatisfiesExpression(parent.parent)))
|
|
109
|
+
parent = parent.parent;
|
|
110
|
+
const declaration = parent.parent;
|
|
111
|
+
const list = declaration?.parent;
|
|
112
|
+
const statement = list?.parent;
|
|
113
|
+
if (!declaration || !typescript_1.default.isVariableDeclaration(declaration) || !typescript_1.default.isIdentifier(declaration.name) ||
|
|
114
|
+
!list || !typescript_1.default.isVariableDeclarationList(list) || !(list.flags & typescript_1.default.NodeFlags.Const) ||
|
|
115
|
+
!statement || !typescript_1.default.isVariableStatement(statement) || statement.parent !== file ||
|
|
116
|
+
!statement.modifiers?.some(modifier => modifier.kind === typescript_1.default.SyntaxKind.ExportKeyword)) {
|
|
117
|
+
throw new Error(`${file.fileName}: ${helper} must initialize an exported top-level const.`);
|
|
118
|
+
}
|
|
119
|
+
declarations.push({ name: declaration.name.text, call: node });
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
typescript_1.default.forEachChild(node, visit);
|
|
123
|
+
}
|
|
124
|
+
visit(file);
|
|
125
|
+
return { names, declarations };
|
|
126
|
+
}
|
|
127
|
+
function modulePath(from, to) {
|
|
128
|
+
const relative = slash(path.posix.relative(path.posix.dirname(from), to)).replace(/\.ts$/, '');
|
|
129
|
+
return relative.startsWith('.') ? relative : `./${relative}`;
|
|
130
|
+
}
|
|
131
|
+
/**
|
|
132
|
+
* Produce both registry modules from project-relative source text, with no disk
|
|
133
|
+
* access or app execution. Also accepts the leading slash used by schematic Trees.
|
|
134
|
+
* Models are discovered first, then mocks are matched by direct relative import.
|
|
135
|
+
* Invalid declarations, duplicate collections and orphan mocks throw before any
|
|
136
|
+
* output is returned. Files without entity helper calls need no registration.
|
|
137
|
+
*/
|
|
138
|
+
function generateEntityRegistrySources(sources, options = {}) {
|
|
139
|
+
const sourceRoot = relativeDirectory(options.sourceRoot ?? 'src/app');
|
|
140
|
+
const outputDir = relativeDirectory(options.outputDir ?? 'src/app/core/store');
|
|
141
|
+
const entities = [];
|
|
142
|
+
const models = new Map();
|
|
143
|
+
const files = Object.entries(sources).map(([name, text]) => [slash(name).replace(/^\//, ''), text])
|
|
144
|
+
.filter(([name]) => (sourceRoot === '.' || name.startsWith(`${sourceRoot}/`)) && /\.(model|mock)\.ts$/.test(name))
|
|
145
|
+
.sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
|
|
146
|
+
.map(([name, text]) => typescript_1.default.createSourceFile(name, text, typescript_1.default.ScriptTarget.Latest, true));
|
|
147
|
+
for (const file of files) {
|
|
148
|
+
const errors = file.parseDiagnostics;
|
|
149
|
+
if (errors.length)
|
|
150
|
+
throw new Error(`${file.fileName}: ${typescript_1.default.flattenDiagnosticMessageText(errors[0].messageText, '\n')}`);
|
|
151
|
+
if (!file.fileName.endsWith('.model.ts'))
|
|
152
|
+
continue;
|
|
153
|
+
for (const { name, call } of declarations(file, 'defineEntity', '@tech4good/platform-data').declarations) {
|
|
154
|
+
const value = call.arguments[0] && unwrap(call.arguments[0]);
|
|
155
|
+
if (call.arguments.length !== 1 || !value || !typescript_1.default.isObjectLiteralExpression(value) || value.properties.length !== 1) {
|
|
156
|
+
throw new Error(`${file.fileName}: defineEntity requires { collection: 'literal-name' }.`);
|
|
157
|
+
}
|
|
158
|
+
const property = value.properties[0];
|
|
159
|
+
const collection = typescript_1.default.isPropertyAssignment(property) && property.name.getText(file).replace(/^['"]|['"]$/g, '') === 'collection'
|
|
160
|
+
? unwrap(property.initializer) : undefined;
|
|
161
|
+
if (!collection || !typescript_1.default.isStringLiteralLike(collection) || !collection.text || collection.text.trim() !== collection.text ||
|
|
162
|
+
collection.text.includes('/') || ['.', '..'].includes(collection.text) || /^__.*__$/.test(collection.text)) {
|
|
163
|
+
throw new Error(`${file.fileName}: collection must be a nonempty literal collection name, without slashes.`);
|
|
164
|
+
}
|
|
165
|
+
if (entities.some(entity => entity.collection === collection.text))
|
|
166
|
+
throw new Error(`${file.fileName}: Duplicate entity collection "${collection.text}".`);
|
|
167
|
+
const entity = { file: file.fileName, name, collection: collection.text };
|
|
168
|
+
entities.push(entity);
|
|
169
|
+
models.set(`${file.fileName}#${name}`, entity);
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
// A separate pass makes associations independent of filename/traversal order.
|
|
173
|
+
for (const file of files.filter(file => file.fileName.endsWith('.mock.ts'))) {
|
|
174
|
+
const { names, declarations: mocks } = declarations(file, 'defineEntityMock', '@tech4good/platform-data/testing');
|
|
175
|
+
for (const { name, call } of mocks) {
|
|
176
|
+
const target = call.arguments[0] && reference(call.arguments[0], names);
|
|
177
|
+
let model = target && target.module.startsWith('.') ? path.posix.normalize(path.posix.join(path.posix.dirname(file.fileName), target.module)) : '';
|
|
178
|
+
model = model.replace(/\.js$/, '.ts');
|
|
179
|
+
if (!model.endsWith('.ts'))
|
|
180
|
+
model += '.ts';
|
|
181
|
+
const entity = target && models.get(`${model}#${target.name}`);
|
|
182
|
+
if (!entity)
|
|
183
|
+
throw new Error(`${file.fileName}: ${name} must reference a defineEntity export imported directly from its relative *.model file.`);
|
|
184
|
+
if (call.arguments.length !== 2)
|
|
185
|
+
throw new Error(`${file.fileName}: ${name} requires an entity definition and mock options.`);
|
|
186
|
+
if (entity.mock)
|
|
187
|
+
throw new Error(`${file.fileName}: Duplicate mock definition for "${entity.collection}".`);
|
|
188
|
+
entity.mock = { file: file.fileName, name };
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
entities.sort((a, b) => a.collection < b.collection ? -1 : a.collection > b.collection ? 1 : 0);
|
|
192
|
+
// Production consumers can import entity identities/types without importing
|
|
193
|
+
// fixture modules. Development providers import the separate mock registry.
|
|
194
|
+
const entityFile = `${outputDir}/entities.generated.ts`;
|
|
195
|
+
const mockFile = `${outputDir}/entity-mocks.generated.ts`;
|
|
196
|
+
const entityImports = entities.map((entity, i) => `import { ${entity.name} as entity${i} } from ${quote(modulePath(entityFile, entity.file))};`).join('\n');
|
|
197
|
+
const entityEntries = entities.map((entity, i) => ` [${quote(entity.collection)}]: entity${i},`).join('\n');
|
|
198
|
+
const mockImports = entities.map((entity, i) => entity.mock
|
|
199
|
+
? `import { ${entity.mock.name} as mock${i} } from ${quote(modulePath(mockFile, entity.mock.file))};`
|
|
200
|
+
: `import { ${entity.name} as entity${i} } from ${quote(modulePath(mockFile, entity.file))};`).join('\n');
|
|
201
|
+
const mockEntries = entities.map((entity, i) => ` [${quote(entity.collection)}]: ${entity.mock ? `mock${i}` : `defineEntityMock(entity${i}, { seeds: [] })`},`).join('\n');
|
|
202
|
+
return {
|
|
203
|
+
collections: entities.map(entity => entity.collection),
|
|
204
|
+
files: {
|
|
205
|
+
[entityFile]: `${header}import type { EntityType } from '@tech4good/platform-data';\n${entityImports}\n\nexport const APP_ENTITIES = {\n${entityEntries}\n} as const;\n\nexport type AppEntityMap = {\n [K in keyof typeof APP_ENTITIES]: EntityType<(typeof APP_ENTITIES)[K]>;\n};\n`,
|
|
206
|
+
[mockFile]: `${header}${entities.some(entity => !entity.mock) ? "import { defineEntityMock } from '@tech4good/platform-data/testing';\n" : ''}${mockImports}\n\nexport const APP_ENTITY_MOCKS = {\n${mockEntries}\n} as const;\n`,
|
|
207
|
+
},
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
function readSources(options) {
|
|
211
|
+
const root = path.resolve(options.projectRoot ?? process.cwd());
|
|
212
|
+
const directory = path.join(root, relativeDirectory(options.sourceRoot ?? 'src/app'));
|
|
213
|
+
if (!fs.existsSync(directory))
|
|
214
|
+
throw new Error(`Entity source directory does not exist: ${directory}`);
|
|
215
|
+
const sources = {};
|
|
216
|
+
function visit(directory) {
|
|
217
|
+
for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
|
|
218
|
+
const file = path.join(directory, entry.name);
|
|
219
|
+
if (entry.isDirectory() && !entry.name.startsWith('.') && !['node_modules', 'dist'].includes(entry.name))
|
|
220
|
+
visit(file);
|
|
221
|
+
else if (entry.isFile() && /\.(model|mock)\.ts$/.test(entry.name))
|
|
222
|
+
sources[slash(path.relative(root, file))] = fs.readFileSync(file, 'utf8');
|
|
223
|
+
}
|
|
224
|
+
}
|
|
225
|
+
visit(directory);
|
|
226
|
+
return sources;
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Compare before writing to avoid needless Angular rebuilds. Check mode reports
|
|
230
|
+
* missing/stale files without changing them. In write mode the generated header
|
|
231
|
+
* marks files we own; refuse handwritten destinations before updating either file.
|
|
232
|
+
*/
|
|
233
|
+
function writeResult(result, options, check) {
|
|
234
|
+
const root = path.resolve(options.projectRoot ?? process.cwd());
|
|
235
|
+
const changed = [];
|
|
236
|
+
// Validate both destinations before changing either one.
|
|
237
|
+
if (!check)
|
|
238
|
+
for (const file of Object.keys(result.files)) {
|
|
239
|
+
const target = path.join(root, file);
|
|
240
|
+
if (fs.existsSync(target) && !fs.readFileSync(target, 'utf8').startsWith(header)) {
|
|
241
|
+
throw new Error(`Refusing to overwrite a non-generated file: ${file}`);
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
for (const [file, text] of Object.entries(result.files)) {
|
|
245
|
+
const target = path.join(root, file);
|
|
246
|
+
const previous = fs.existsSync(target) ? fs.readFileSync(target, 'utf8') : undefined;
|
|
247
|
+
if (previous === text)
|
|
248
|
+
continue;
|
|
249
|
+
changed.push(file);
|
|
250
|
+
if (!check) {
|
|
251
|
+
if (previous !== undefined && !previous.startsWith(header))
|
|
252
|
+
throw new Error(`Refusing to overwrite a non-generated file: ${file}`);
|
|
253
|
+
fs.mkdirSync(path.dirname(target), { recursive: true });
|
|
254
|
+
// Rename prevents the Angular watcher from reading a partially written module.
|
|
255
|
+
const temporary = `${target}.${process.pid}.tmp`;
|
|
256
|
+
try {
|
|
257
|
+
fs.writeFileSync(temporary, text);
|
|
258
|
+
fs.renameSync(temporary, target);
|
|
259
|
+
}
|
|
260
|
+
finally {
|
|
261
|
+
if (fs.existsSync(temporary))
|
|
262
|
+
fs.unlinkSync(temporary);
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
}
|
|
266
|
+
return { ...result, changed, success: !check || changed.length === 0 };
|
|
267
|
+
}
|
|
268
|
+
/**
|
|
269
|
+
* Discover from disk and write changed registries, or compare only with check:true.
|
|
270
|
+
* `changed` lists different/missing outputs in either mode; `success` is false
|
|
271
|
+
* only when check mode finds stale output. Discovery or filesystem errors throw.
|
|
272
|
+
*/
|
|
273
|
+
function generateEntityRegistries(options = {}) {
|
|
274
|
+
return writeResult(generateEntityRegistrySources(readSources(options), options), options, options.check ?? false);
|
|
275
|
+
}
|
|
276
|
+
/**
|
|
277
|
+
* Generate synchronously before starting a polling watcher, so callers can start
|
|
278
|
+
* Angular only after valid modules exist. Polling finds new/deleted directories
|
|
279
|
+
* across Node platforms. Later invalid edits report onError and retain the last
|
|
280
|
+
* valid output; another source edit retries. The caller must close the watcher.
|
|
281
|
+
*/
|
|
282
|
+
function watchEntityRegistries(options, callbacks = {}) {
|
|
283
|
+
const initial = readSources(options);
|
|
284
|
+
const result = writeResult(generateEntityRegistrySources(initial, options), options, false);
|
|
285
|
+
callbacks.onChange?.(result);
|
|
286
|
+
let signature = JSON.stringify(initial);
|
|
287
|
+
const timer = setInterval(() => {
|
|
288
|
+
try {
|
|
289
|
+
const sources = readSources(options);
|
|
290
|
+
const next = JSON.stringify(sources);
|
|
291
|
+
if (next === signature)
|
|
292
|
+
return;
|
|
293
|
+
// Remember invalid source too, so the same error is not repeated every tick.
|
|
294
|
+
signature = next;
|
|
295
|
+
callbacks.onChange?.(writeResult(generateEntityRegistrySources(sources, options), options, false));
|
|
296
|
+
}
|
|
297
|
+
catch (error) {
|
|
298
|
+
callbacks.onError?.(error instanceof Error ? error : new Error(String(error)));
|
|
299
|
+
}
|
|
300
|
+
}, callbacks.intervalMs ?? 300);
|
|
301
|
+
return { close: () => clearInterval(timer) };
|
|
302
|
+
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
type Direction = 'ASCENDING' | 'DESCENDING';
|
|
2
|
+
type QueryPurpose = 'initial-load' | 'incremental-load' | 'full-load' | 'stream' | 'count' | 'aggregate' | 'database-query';
|
|
2
3
|
interface FirestoreIndexField {
|
|
3
4
|
fieldPath: string;
|
|
4
5
|
order?: Direction;
|
|
@@ -24,6 +25,7 @@ interface Query {
|
|
|
24
25
|
filters: Filter[];
|
|
25
26
|
orderBy: Sort[];
|
|
26
27
|
aggregateFields: string[];
|
|
28
|
+
purpose: QueryPurpose;
|
|
27
29
|
}
|
|
28
30
|
interface Diagnostic {
|
|
29
31
|
file: string;
|
|
@@ -32,19 +34,37 @@ interface Diagnostic {
|
|
|
32
34
|
}
|
|
33
35
|
interface MissingIndex {
|
|
34
36
|
collection: string;
|
|
37
|
+
/** First use, retained for consumers of the original API. */
|
|
35
38
|
query: Query;
|
|
39
|
+
queries: Query[];
|
|
36
40
|
requiredFields: FirestoreIndexField[];
|
|
37
41
|
}
|
|
42
|
+
/** Source-analysis report, not a check of indexes deployed to a Firebase project. */
|
|
38
43
|
export interface CheckResult {
|
|
44
|
+
/** False for unresolved checks, or missing definitions unless fix mode added them. */
|
|
39
45
|
success: boolean;
|
|
46
|
+
/** App call sites analyzed; one load call may expand into multiple query shapes. */
|
|
40
47
|
checkedQueries: number;
|
|
48
|
+
/** Deduplicated missing definitions, retained in the report even after fix mode adds them. */
|
|
41
49
|
missingIndexes: MissingIndex[];
|
|
50
|
+
/** Unsupported/dynamic queries and analysis failures that need manual review. */
|
|
42
51
|
unresolvedQueries: Diagnostic[];
|
|
43
52
|
}
|
|
53
|
+
/** Local analysis settings; no mode contacts Firebase or deploys indexes. */
|
|
44
54
|
export interface CheckOptions {
|
|
55
|
+
/** App directory containing src/app and firestore.indexes.json; defaults to cwd. */
|
|
45
56
|
projectRoot?: string;
|
|
57
|
+
/** Append confidently inferred missing definitions to the local index file. */
|
|
46
58
|
fix?: boolean;
|
|
59
|
+
/** Suppress console diagnostics while retaining the structured result. */
|
|
47
60
|
quiet?: boolean;
|
|
48
61
|
}
|
|
62
|
+
/**
|
|
63
|
+
* Compare statically discoverable app queries with local Firestore definitions.
|
|
64
|
+
* Store calls expand into their runtime shapes, including _deleted filters and
|
|
65
|
+
* initial/incremental load variants. Dynamic or unsupported queries are reported
|
|
66
|
+
* as unresolved rather than treated as covered. Fix mode only edits the local
|
|
67
|
+
* index file; deployment and runtime validation remain separate steps.
|
|
68
|
+
*/
|
|
49
69
|
export declare function checkFirestoreIndexes(options?: CheckOptions): CheckResult;
|
|
50
70
|
export {};
|
|
@@ -40,6 +40,15 @@ exports.checkFirestoreIndexes = checkFirestoreIndexes;
|
|
|
40
40
|
const fs = __importStar(require("node:fs"));
|
|
41
41
|
const path = __importStar(require("node:path"));
|
|
42
42
|
const typescript_1 = __importDefault(require("typescript"));
|
|
43
|
+
const purposeLabels = {
|
|
44
|
+
'initial-load': 'initial load',
|
|
45
|
+
'incremental-load': 'incremental reload',
|
|
46
|
+
'full-load': 'full load with query options',
|
|
47
|
+
stream: 'stream',
|
|
48
|
+
count: 'count',
|
|
49
|
+
aggregate: 'aggregate',
|
|
50
|
+
'database-query': 'direct database query',
|
|
51
|
+
};
|
|
43
52
|
const equalityOps = new Set(['==', 'in']);
|
|
44
53
|
const rangeOps = new Set(['<', '<=', '>', '>=', '!=', 'not-in']);
|
|
45
54
|
const arrayOps = new Set(['array-contains', 'array-contains-any']);
|
|
@@ -109,6 +118,15 @@ class Literals {
|
|
|
109
118
|
const receiverSymbol = this.symbol(receiver);
|
|
110
119
|
if (receiverSymbol && this.mutated.has(receiverSymbol))
|
|
111
120
|
return undefined;
|
|
121
|
+
// Entity collection identity now lives beside the interface in *.model.ts.
|
|
122
|
+
// Resolve the declarative helper without executing application code.
|
|
123
|
+
if (node.name.text === 'collection') {
|
|
124
|
+
const definition = this.resolve(node.expression, new Set(seen));
|
|
125
|
+
if (definition && typescript_1.default.isCallExpression(definition) && this.name(definition.expression) === 'defineEntity') {
|
|
126
|
+
const options = this.object(definition.arguments[0]);
|
|
127
|
+
return this.resolve(options?.get('collection'), seen);
|
|
128
|
+
}
|
|
129
|
+
}
|
|
112
130
|
}
|
|
113
131
|
const symbol = this.symbol(node);
|
|
114
132
|
if (!symbol || this.mutated.has(symbol))
|
|
@@ -438,7 +456,10 @@ function extractQueries(files, root, literals, mappings) {
|
|
|
438
456
|
const filters = parseFilters(node.arguments[offset], literals);
|
|
439
457
|
const { orderBy, hasOptions } = parseOptions(node.arguments[offset + 1], literals);
|
|
440
458
|
const aggregateFields = method === 'aggregate' ? parseAggregates(node.arguments[offset + 2], literals) : [];
|
|
441
|
-
const
|
|
459
|
+
const purpose = operation === 'load' ? (hasOptions ? 'full-load' : 'initial-load') :
|
|
460
|
+
method === 'count' || method === 'aggregate' ? method :
|
|
461
|
+
operation === 'stream' || method === 'streamEntities' || method === 'streamEntitiesChanges' ? 'stream' : 'database-query';
|
|
462
|
+
const query = { file: relative, line, rawText: node.getText(file), collection: segments[segments.length - 1], filters, orderBy, aggregateFields, purpose };
|
|
442
463
|
if (new Set(filters.filter((filter) => arrayOps.has(filter.operator)).map((filter) => filter.field)).size > 1)
|
|
443
464
|
throw new Error('Queries with multiple array fields are unsupported by composite indexes.');
|
|
444
465
|
checked++;
|
|
@@ -453,7 +474,7 @@ function extractQueries(files, root, literals, mappings) {
|
|
|
453
474
|
const active = { ...query, filters: [...filters, { field: '_deleted', operator: '==' }] };
|
|
454
475
|
queries.push(active);
|
|
455
476
|
if (operation === 'load' && !hasOptions) {
|
|
456
|
-
queries.push({ ...active, filters: [...active.filters, { field: '_updatedAt', operator: '>' }] });
|
|
477
|
+
queries.push({ ...active, purpose: 'incremental-load', filters: [...active.filters, { field: '_updatedAt', operator: '>' }] });
|
|
457
478
|
}
|
|
458
479
|
}
|
|
459
480
|
}
|
|
@@ -596,6 +617,13 @@ function validateIndexes(value) {
|
|
|
596
617
|
if ('fieldOverrides' in value && !Array.isArray(value.fieldOverrides))
|
|
597
618
|
throw new Error('fieldOverrides must be an array.');
|
|
598
619
|
}
|
|
620
|
+
/**
|
|
621
|
+
* Compare statically discoverable app queries with local Firestore definitions.
|
|
622
|
+
* Store calls expand into their runtime shapes, including _deleted filters and
|
|
623
|
+
* initial/incremental load variants. Dynamic or unsupported queries are reported
|
|
624
|
+
* as unresolved rather than treated as covered. Fix mode only edits the local
|
|
625
|
+
* index file; deployment and runtime validation remain separate steps.
|
|
626
|
+
*/
|
|
599
627
|
function checkFirestoreIndexes(options = {}) {
|
|
600
628
|
const root = path.resolve(options.projectRoot || process.cwd());
|
|
601
629
|
const indexesPath = path.join(root, 'firestore.indexes.json');
|
|
@@ -618,7 +646,7 @@ function checkFirestoreIndexes(options = {}) {
|
|
|
618
646
|
const extracted = extractQueries(files, root, literals, discoverMappings(files, literals));
|
|
619
647
|
result.checkedQueries = extracted.checked;
|
|
620
648
|
result.unresolvedQueries.push(...extracted.diagnostics);
|
|
621
|
-
const signatures = new
|
|
649
|
+
const signatures = new Map();
|
|
622
650
|
for (const query of extracted.queries) {
|
|
623
651
|
const required = plan(query);
|
|
624
652
|
if (satisfied(query, required, indexes))
|
|
@@ -630,13 +658,27 @@ function checkFirestoreIndexes(options = {}) {
|
|
|
630
658
|
continue;
|
|
631
659
|
}
|
|
632
660
|
const signature = JSON.stringify([query.collection, required.fields]);
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
661
|
+
const existing = signatures.get(signature);
|
|
662
|
+
if (existing) {
|
|
663
|
+
existing.queries.push(query);
|
|
664
|
+
}
|
|
665
|
+
else {
|
|
666
|
+
const missing = { collection: query.collection, query, queries: [query], requiredFields: required.fields };
|
|
667
|
+
signatures.set(signature, missing);
|
|
668
|
+
result.missingIndexes.push(missing);
|
|
636
669
|
}
|
|
637
670
|
}
|
|
638
671
|
for (const missing of result.missingIndexes) {
|
|
639
|
-
|
|
672
|
+
const alsoNeeded = missing.queries.slice(1).map((query) => `\n Also needed for ${purposeLabels[query.purpose]} at ${query.file}:${query.line}`).join('');
|
|
673
|
+
log(`Missing index: ${missing.collection} at ${missing.query.file}:${missing.query.line} (${purposeLabels[missing.query.purpose]})${alsoNeeded}\n ${JSON.stringify(missing.requiredFields)}`);
|
|
674
|
+
}
|
|
675
|
+
const missingPurposes = new Set(result.missingIndexes.flatMap((missing) => missing.queries.map((query) => query.purpose)));
|
|
676
|
+
if (missingPurposes.has('initial-load') || missingPurposes.has('incremental-load')) {
|
|
677
|
+
log('Load behavior: initial loads use your filters plus _deleted. With empty query options, incremental reloads also add _updatedAt > lastLoadTime.');
|
|
678
|
+
log('These query shapes can need different indexes; equality-only initial loads may be covered by automatic indexes.');
|
|
679
|
+
}
|
|
680
|
+
if (missingPurposes.has('full-load')) {
|
|
681
|
+
log('Loads with non-empty query options reuse the full query on subsequent loads; no automatic _updatedAt cutoff is added.');
|
|
640
682
|
}
|
|
641
683
|
if (options.fix && result.missingIndexes.length) {
|
|
642
684
|
indexes.indexes.push(...result.missingIndexes.map((missing) => ({
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.checkFirestoreIndexes = void 0;
|
|
3
|
+
exports.watchEntityRegistries = exports.generateEntityRegistrySources = exports.generateEntityRegistries = exports.checkFirestoreIndexes = void 0;
|
|
4
4
|
var firestore_indexes_1 = require("./firestore-indexes");
|
|
5
5
|
Object.defineProperty(exports, "checkFirestoreIndexes", { enumerable: true, get: function () { return firestore_indexes_1.checkFirestoreIndexes; } });
|
|
6
|
+
var entity_registry_1 = require("./entity-registry");
|
|
7
|
+
Object.defineProperty(exports, "generateEntityRegistries", { enumerable: true, get: function () { return entity_registry_1.generateEntityRegistries; } });
|
|
8
|
+
Object.defineProperty(exports, "generateEntityRegistrySources", { enumerable: true, get: function () { return entity_registry_1.generateEntityRegistrySources; } });
|
|
9
|
+
Object.defineProperty(exports, "watchEntityRegistries", { enumerable: true, get: function () { return entity_registry_1.watchEntityRegistries; } });
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tech4good/platform-tooling",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.2",
|
|
4
4
|
"description": "Development tools for Tech4Good Angular and Firebase applications.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "commonjs",
|
|
@@ -14,7 +14,8 @@
|
|
|
14
14
|
"./package.json": "./package.json"
|
|
15
15
|
},
|
|
16
16
|
"bin": {
|
|
17
|
-
"t4g-check-firestore-indexes": "./dist/cli.js"
|
|
17
|
+
"t4g-check-firestore-indexes": "./dist/cli.js",
|
|
18
|
+
"t4g-entities": "./dist/entities-cli.js"
|
|
18
19
|
},
|
|
19
20
|
"files": [
|
|
20
21
|
"dist"
|