@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 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
- This is an unpublished `0.1.0-alpha.0` packaging pilot. The query analyzer was
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
- Once this version is published, install it as a development dependency:
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.0
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.0.tgz` in the repository
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.0.tgz
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
- For the first pilot release, keep the existing `0.1.0-alpha.0` version. It is
218
- already set in the package manifest, root lockfile, and generated dependency.
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.0`, prepare the next alpha with:
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.1 --workspace @tech4good/platform-tooling --no-git-tag-version --ignore-scripts
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 the first alpha release:
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 the first alpha (substitute the actual version for later releases):
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.0 version
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.0 -m "Release @tech4good/platform-tooling 0.1.0-alpha.0"
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.0` and the `alpha` tag points to
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.0
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.0
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,2 @@
1
+ #!/usr/bin/env node
2
+ export {};
@@ -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 query = { file: relative, line, rawText: node.getText(file), collection: segments[segments.length - 1], filters, orderBy, aggregateFields };
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 Set();
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
- if (!signatures.has(signature)) {
634
- signatures.add(signature);
635
- result.missingIndexes.push({ collection: query.collection, query, requiredFields: required.fields });
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
- log(`Missing index: ${missing.collection} at ${missing.query.file}:${missing.query.line}\n ${JSON.stringify(missing.requiredFields)}`);
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
@@ -1 +1,2 @@
1
1
  export { checkFirestoreIndexes, CheckOptions, CheckResult } from './firestore-indexes';
2
+ export { generateEntityRegistries, generateEntityRegistrySources, watchEntityRegistries, EntityRegistryOptions, EntityRegistryResult } from './entity-registry';
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.0",
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"