@neohm/nh-cli 1.4.0 → 2.0.0

package/README.md

@@ -6,7 +6,7 @@ sibling [`@neohm/nestendx`](../nestendx).
 
 `nh` generates fully wired modules, entities, controllers, services, DTOs, data
 processors, migrations and seeds — and keeps your import barrels
-(`es6.classes.ts`) and `app.module.ts` registration in sync, so the project
+(`module.registry.ts`) and `app.module.ts` registration in sync, so the project
 builds without any manual import wiring.
 
 ## Two flavours, one CLI
@@ -19,7 +19,7 @@ differ only where the two packages do:
 | ------------------------ | ------------------------------------------ | ----------------------------------------- |
 | Import specifier         | `@neohm/nestend`                           | `@neohm/nestendx`                         |
 | What a row belongs to    | a tenant (`tenant_id` + `TenantEntity`)    | the user who created it (`created_by`)    |
-| Access check             | `validateAccess(scope, role)`              | `validateAccess(scope)` — there are no roles |
+| Access check             | `validateRole(role)` (scope checked first) | `validateAccess(scope)` — there are no roles |
 | Generated migration      | FK + index on `tenant_id`                  | no tenant column to key                   |
 
 Everything that does not write package-specific code — `sync`, `check`, `list`,
@@ -64,7 +64,7 @@ The project root is auto-detected by walking up from the current directory for a
 | `nh gen <flag>`       | Generate one artifact instead of a whole module — see [Flag generation](#flag-generation). |
 | `nh migration`        | Generate a standalone migration `<timestamp>M-<Name>.ts`.                                                        |
 | `nh seed`             | Generate a seed file `<timestamp>S-<Name>.ts`.                                                                   |
-| `nh sync`             | Rebuild every `es6.classes.ts` barrel and register modules in `app.module.ts`.                                   |
+| `nh sync`             | Rebuild every `module.registry.ts` barrel and register modules in `app.module.ts`.                                   |
 | `nh check`            | Dry-run of `sync` — show what would change without writing.                                                      |
 | `nh list`             | List scaffolded modules with their entities and providers.                                                       |
 | `nh remove <name>`    | Safely remove a scaffolded module and de-register it (migrations are preserved).                                 |
@@ -83,7 +83,7 @@ $ nh gen
 ? Create controller (ShapeController)? Yes
 ? Create DTO (AddShapeDataDto)? Yes
 ? Create data processor (ShapeDataProcessor)? Yes
-? Create listing processor (ShapeListProcessor)? Yes
+? Create filter processor (ShapeFilterProcessor)? Yes
 ? Create migration (M-AddShapeTable)? Yes
 ```
 
@@ -92,13 +92,13 @@ Produces, under `src/shape/`:
 ```text
 shape/
   shape.module.ts                    # ShapeModule (imports CommonModule, QueueModule, ...)
-  es6.classes.ts                     # barrel of controllers/services/jobs/subscribers
+  module.registry.ts                     # barrel of controllers/services/jobs/subscribers
   controllers/shape.controller.ts
   services/shape.service.ts
   dtos/add.shape.data.dto.ts
   entities/shape.entity.ts
   libraries/shape.data.processor.ts
-  libraries/shape.list.processor.ts
+  libraries/shape.filter.processor.ts
   enums/  jobs/  subscribers/
   external/                          # optional API-key surface (nh gen -x ...)
     controllers/  libraries/  services/
@@ -125,11 +125,11 @@ Generated artifacts extend the `@neohm/nestend` base classes:
   `TenantEntity` relation, and `TenantScopeSubscriber` stamps and guards it),
   `CommonEntity` under `nhx`; both with an empty `attributes` jsonb column
 - DTO → `CommonDataDto`
-- Data processor → `CommonDataProcessor` (`process()` → `validate()` → `set()`),
+- Data processor → `BaseDataProcessor` (`process()` → `validate()` → `set()`),
   reached through the service's `upsert()`. It takes the caller and, on edit,
   loads the row scoped to them — another owner's `id` is a field error, never an
   update.
-- Listing processor → `CommonListProcessor` (column allowlist config, `id` default sort). It takes `CommonListFilterDto` directly — no per-list DTO is generated, since paging, sorting, filters and free-text search all live on the base DTO and the filterable columns are declared in the processor's `columns` config.
+- Filter processor → `BaseFilterProcessor` (column allowlist config, `id` default sort). It takes `CommonListFilterDto` directly — no per-list DTO is generated, since paging, sorting, filters and free-text search all live on the base DTO and the filterable columns are declared in the processor's `columns` config.
 
 ### Controller → service → processor
 
@@ -137,7 +137,7 @@ Generated controllers run under `@UsePipes(StrictValidationPipe)`, take ids
 with `ParseUUIDPipe`, and describe every route with `@ApiOperation`.
 
 Controllers hold no business logic. They authenticate with
-`AuthService.validateAccess()`, then delegate to the module's service — so the
+`AuthService.validateRole()` (`validateAccess()` under nhx), then delegate to the module's service — so the
 same operation is reusable from a job, a subscriber or another service, and the
 HTTP surface stays readable.
 
@@ -150,7 +150,7 @@ answers you already gave:
 | `get(user, id)` | always | `GET /api/v1/shape/:id` |
 | `remove(user, id)` | always | `DELETE /api/v1/shape/:id` |
 | `upsert(user, data)` | data processor: Yes | `POST /api/v1/shape` |
-| `list(user, data)` | listing processor: Yes | `POST /api/v1/shape/list` |
+| `list(user, data)` | filter processor: Yes | `POST /api/v1/shape/list` |
 
 `get()` and `remove()` keep their logic in the service — no processor: `remove()`
 soft-deletes through the same owner-scoped lookup as `get()`. A module that
@@ -191,14 +191,15 @@ export enum RoleEnum {
 }
 ```
 
-The controller gates each endpoint at the lowest role that should reach it — a
-senior role satisfies a junior one in nestend's scoped RBAC:
+The controller gates each endpoint at the lowest role that should reach it. A role
+carries its scope, so `validateRole()` first checks the organization holds the
+role's scope, then that the caller holds the role or a more senior one:
 
 | Endpoint | Gate |
 | --- | --- |
-| `GET :id`, `POST list` | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_READER)` |
-| `POST` (upsert) | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_MANAGER)` |
-| `DELETE :id` | `validateAccess(ScopeEnum.BILLING, RoleEnum.BILLING_ADMIN)` |
+| `GET :id`, `POST list` | `validateRole(RoleEnum.BILLING_READER)` |
+| `POST` (upsert) | `validateRole(RoleEnum.BILLING_MANAGER)` |
+| `DELETE :id` | `validateRole(RoleEnum.BILLING_ADMIN)` |
 
 Under `nhx` the gate is `validateAccess(ScopeEnum.BILLING)`. The enums name the
 identifiers only: create the `sys_scopes` row and the three `sys_roles` rows
@@ -209,14 +210,14 @@ identifiers only: create the `sys_scopes` row and the three `sys_roles` rows
 Bare `nh gen` scaffolds a whole module. Once that module exists, most work is
 adding *one* more file to it — which is what the target flags do. Each asks
 only what it cannot infer, refuses to shadow a name already in the project,
-registers the result in `es6.classes.ts`, and formats what it wrote.
+registers the result in `module.registry.ts`, and formats what it wrote.
 
 | Command | Generates | Asks |
 | --- | --- | --- |
 | `nh gen -c` | `controllers/<name>.controller.ts` | module, name, route path |
 | `nh gen -s` | `services/<name>.service.ts` | module, name |
 | `nh gen -dp` | `libraries/<name>.data.processor.ts` + `dtos/add.<name>.data.dto.ts` | module, name |
-| `nh gen -lp` | `libraries/<name>.list.processor.ts` | module, name, table name |
+| `nh gen -fp` | `libraries/<name>.filter.processor.ts` | module, name, table name |
 | `nh gen -e` | `entities/<name>.entity.ts` + `dtos/<name>.attributes.dto.ts` + `jobs/<name>.job.ts` + `subscribers/<name>.subscriber.ts` + a migration | module, name, table name |
 | `nh gen -j` | `jobs/<name>.job.ts` | module, name |
 
@@ -229,10 +230,10 @@ entity, `job.constants.ts` / `job.maps.ts` for the job it brought along.
 
 The two jobs are deliberately different shapes:
 
-| | Driven by | `handle()` takes |
-| --- | --- | --- |
-| the job `-e` brings along | the entity's subscriber | `event: DatabaseEventDto<<Name>Entity>` |
-| `nh gen -j` | an explicit `dispatch()` | `data: unknown` |
+| | Extends | Driven by | `handle()` takes |
+| --- | --- | --- | --- |
+| the job `-e` brings along | `BaseEntityJob` | the entity's subscriber | `event: DatabaseEventDto<<Name>Entity>` |
+| `nh gen -j` | `BaseJob` | an explicit `dispatch()` | `data: unknown` |
 
 So reach for `-j` when you want a queue worker that is not tied to a table's
 lifecycle.
@@ -249,7 +250,7 @@ Only one target flag per run; the module is created if it does not exist yet.
 | `nh gen -x -c` | `external/controllers/external.<name>.controller.ts` |
 | `nh gen -x -s` | `external/services/external.<name>.service.ts` |
 | `nh gen -x -dp` | `external/libraries/external.<name>.data.processor.ts` |
-| `nh gen -x -lp` | `external/libraries/external.<name>.list.processor.ts` |
+| `nh gen -x -fp` | `external/libraries/external.<name>.filter.processor.ts` |
 
 External files take an `external.` filename prefix and an `External` class
 prefix. An external controller differs from an internal one in three ways, all
@@ -261,7 +262,7 @@ than `AuthService`.
 inward/outward face, so there is nothing to mirror. Both refuse the flag rather
 than quietly ignoring it.
 
-External providers register into the *same* `es6.classes.ts` categories as
+External providers register into the *same* `module.registry.ts` categories as
 their internal siblings, listed after them — so `nh sync` and `nh check` see
 `<module>/external/<folder>` as well as `<module>/<folder>`.
 
@@ -296,7 +297,7 @@ this keeps that true for entity names long enough to push a line past 80
 columns. A project without prettier installed still gets its files, just
 unformatted.
 
-- Migration → `MigrationUtility`
+- Migration → `MigrationHelper`
 - Seed → `SeederUtility`
 
 Re-running `gen` for an existing module reuses it and only adds new files —
@@ -305,7 +306,7 @@ existing files are never overwritten.
 ## `nh sync` and `nh check`
 
 `sync` scans every module under `src/` — including its `external/` mirror —
-and regenerates its `es6.classes.ts` barrel from the files actually present in
+and regenerates its `module.registry.ts` barrel from the files actually present in
 `controllers/`, `services/`, `libraries/`, `dtos/`, `jobs/` and
 `subscribers/`, then ensures each module is imported and listed in
 `app.module.ts`. Files are classified by their **folder** and the presence of an
@@ -316,9 +317,9 @@ never silently dropped. The operation is idempotent.
 
 ```text
 $ nh check
-es6.classes barrels:
-  ok      src/shape/es6.classes.ts
-  update  src/test/es6.classes.ts
+module registries:
+  ok      src/shape/module.registry.ts
+  update  src/test/module.registry.ts
             + services: TestService
 
 app.module.ts:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neohm/nh-cli",
-  "version": "1.4.0",
+  "version": "2.0.0",
   "description": "nh / nhx — Command Line Interface for neohm. NestJS projects",
   "main": "src/index.js",
   "bin": {

package/src/commands/check.js

@@ -21,8 +21,8 @@ async function check() {
   const plan = engine.buildPlan(paths, modules);
   let changes = 0;
 
-  console.log(chalk.bold('\nes6.classes barrels:'));
-  for (const p of plan.es6) {
+  console.log(chalk.bold('\nmodule registries:'));
+  for (const p of plan.registries) {
     const rel = path.relative(paths.root, p.path);
     if (p.changed) {
       changes++;

package/src/commands/gen.flag.js

@@ -21,7 +21,7 @@ const { registerJob, registerEntity } = require('../lib/registry');
 const { findConflict, describeConflict } = require('../lib/collision');
 
 /**
- * Single-artifact generation: `nh gen -c`, `-s`, `-dp`, `-lp`, `-e`, `-j`, and
+ * Single-artifact generation: `nh gen -c`, `-s`, `-dp`, `-fp`, `-e`, `-j`, and
  * the `-x` (external, API-key surface) variants of the first four.
  *
  * Bare `nh gen` still runs the full wizard — this path exists for adding one
@@ -34,7 +34,7 @@ const LABELS = {
   controller: 'controller',
   service: 'service',
   dataProcessor: 'data processor',
-  listProcessor: 'list processor',
+  filterProcessor: 'filter processor',
   entity: 'entity',
   job: 'job',
 };
@@ -44,7 +44,7 @@ const DESCRIBES = {
   controller: 'controller',
   service: 'service',
   dataProcessor: 'data processor (+ its payload DTO)',
-  listProcessor: 'list processor',
+  filterProcessor: 'filter processor',
   entity: 'entity, its job and subscriber, and a migration',
   job: 'job',
 };
@@ -55,14 +55,14 @@ const EXTERNAL_CAPABLE = new Set([
   'controller',
   'service',
   'dataProcessor',
-  'listProcessor',
+  'filterProcessor',
 ]);
 
 const FLAG = {
   controller: '-c',
   service: '-s',
   dataProcessor: '-dp',
-  listProcessor: '-lp',
+  filterProcessor: '-fp',
   entity: '-e',
   job: '-j',
 };
@@ -103,14 +103,14 @@ function primaryArtifacts(target, moduleDir, n, external) {
       return external
         ? one(n.externalProcessorClass, 'libraries', n.externalProcessorFile)
         : one(n.processorClass, 'libraries', n.processorFile);
-    case 'listProcessor':
+    case 'filterProcessor':
       return external
         ? one(
-            n.externalListProcessorClass,
+            n.externalFilterProcessorClass,
             'libraries',
-            n.externalListProcessorFile,
+            n.externalFilterProcessorFile,
           )
-        : one(n.listProcessorClass, 'libraries', n.listProcessorFile);
+        : one(n.filterProcessorClass, 'libraries', n.filterProcessorFile);
     case 'entity':
       return [
         {
@@ -151,11 +151,11 @@ function ensureModule(paths, moduleDot, external, report) {
   }
 
   const modulePath = path.join(moduleDir, `${moduleDot}.module.ts`);
-  const es6Path = path.join(moduleDir, 'es6.classes.ts');
+  const registryPath = path.join(moduleDir, 'module.registry.ts');
   const a = writeFile(modulePath, tpl.moduleFile(moduleDot));
-  const b = writeFile(es6Path, tpl.emptyEs6Classes());
+  const b = writeFile(registryPath, tpl.emptyModuleRegistry());
   if (a !== 'skipped') report(a, modulePath, paths.root);
-  if (b !== 'skipped') report(b, es6Path, paths.root);
+  if (b !== 'skipped') report(b, registryPath, paths.root);
 
   if (!existed) log.info(`Created module "${moduleDot}".`);
   return moduleDir;
@@ -166,7 +166,7 @@ async function genFlag(target, { external = false } = {}) {
   if (external && !EXTERNAL_CAPABLE.has(target)) {
     throw new Error(
       `-x is not supported for ${LABELS[target]} — external applies to ` +
-        `-c, -s, -dp and -lp only. Run \`nh gen ${FLAG[target]}\` without -x.`,
+        `-c, -s, -dp and -fp only. Run \`nh gen ${FLAG[target]}\` without -x.`,
     );
   }
 
@@ -225,7 +225,7 @@ async function genFlag(target, { external = false } = {}) {
   }
 
   let tableName;
-  if (target === 'listProcessor' || target === 'entity') {
+  if (target === 'filterProcessor' || target === 'entity') {
     ({ tableName } = await inquirer.prompt([
       {
         type: 'input',
@@ -295,8 +295,8 @@ async function genFlag(target, { external = false } = {}) {
       write(path.join(moduleDir, 'dtos', n.dtoFile), tpl.dto(rawName));
       break;
 
-    case 'listProcessor':
-      write(dest, tpl.listProcessor(rawName, tableName, { external }));
+    case 'filterProcessor':
+      write(dest, tpl.filterProcessor(rawName, tableName, { external }));
       break;
 
     case 'entity': {

package/src/commands/gen.js

@@ -25,7 +25,7 @@ async function gen() {
 
   // Every file this run writes or rewrites, formatted in one pass at the end.
   // Each write is announced through report(), so recording paths here catches
-  // templates, the constant registries, the es6 barrel and app.module alike.
+  // templates, the constant registries, the module registry and app.module alike.
   const touched = [];
   const report = (result, filePath, root) => {
     if (result !== "skipped") touched.push(filePath);
@@ -51,7 +51,7 @@ async function gen() {
     log.info(`Creating module "${moduleDot}".`);
   }
 
-  // Always ensure the module skeleton (folders + module file + es6 barrel).
+  // Always ensure the module skeleton (folders + module file + module registry).
   for (const sub of MODULE_SUBFOLDERS) ensureDir(path.join(moduleDir, sub));
   report(
     writeFile(
@@ -61,8 +61,8 @@ async function gen() {
     path.join(moduleDir, `${moduleDot}.module.ts`),
     paths.root,
   );
-  const es6Path = path.join(moduleDir, "es6.classes.ts");
-  report(writeFile(es6Path, tpl.emptyEs6Classes()), es6Path, paths.root);
+  const registryPath = path.join(moduleDir, "module.registry.ts");
+  report(writeFile(registryPath, tpl.emptyModuleRegistry()), registryPath, paths.root);
 
   // 2. Entity ---------------------------------------------------------------
   const { entityName } = await inquirer.prompt([
@@ -125,7 +125,7 @@ async function gen() {
   // job, subscriber or sibling service goes through, never an opt-in. It is
   // written after the processor prompts, because those answers decide which
   // methods it (and the controller) ships with: `get()` always, `upsert()`
-  // with a data processor, `list()` with a listing processor.
+  // with a data processor, `list()` with a filter processor.
 
   // 5. Optional: data processor (includes Add*DataDto) ----------------------
   const { processor } = await inquirer.prompt([
@@ -145,20 +145,20 @@ async function gen() {
     report(writeFile(procPath, tpl.processor(entityName, { withEntity: true })), procPath, paths.root);
   }
 
-  // 6. Optional: listing processor (takes CommonListFilterDto directly) ------
-  const { listProcessor } = await inquirer.prompt([
+  // 6. Optional: filter processor (takes CommonListFilterDto directly) ------
+  const { filterProcessor } = await inquirer.prompt([
     {
       type: "confirm",
-      name: "listProcessor",
-      message: `Create listing processor (${n.listProcessorClass})?`,
+      name: "filterProcessor",
+      message: `Create filter processor (${n.filterProcessorClass})?`,
       default: true,
     },
   ]);
 
-  if (listProcessor) {
-    const listProcPath = path.join(moduleDir, "libraries", n.listProcessorFile);
+  if (filterProcessor) {
+    const listProcPath = path.join(moduleDir, "libraries", n.filterProcessorFile);
     report(
-      writeFile(listProcPath, tpl.listProcessor(entityName, tableName)),
+      writeFile(listProcPath, tpl.filterProcessor(entityName, tableName)),
       listProcPath,
       paths.root,
     );
@@ -166,7 +166,7 @@ async function gen() {
 
   const servicePath = path.join(moduleDir, "services", n.serviceFile);
   report(
-    writeFile(servicePath, tpl.service(entityName, { processor, listProcessor })),
+    writeFile(servicePath, tpl.service(entityName, { processor, filterProcessor })),
     servicePath,
     paths.root,
   );
@@ -176,7 +176,7 @@ async function gen() {
     report(
       writeFile(
         p,
-        tpl.controller(entityName, { processor, listProcessor, enums }),
+        tpl.controller(entityName, { processor, filterProcessor, enums }),
       ),
       p,
       paths.root,

package/src/commands/sync.js

@@ -19,7 +19,7 @@ async function sync() {
   const plan = engine.buildPlan(paths, modules);
   const written = engine.applyPlan(plan);
 
-  for (const p of plan.es6) {
+  for (const p of plan.registries) {
     const rel = path.relative(paths.root, p.path);
     if (p.changed) log.overwritten(rel);
     else console.log(`  ${chalk.dim('ok')}      ${rel}`);

package/src/index.js

@@ -32,12 +32,12 @@ program
 
 // `gen` with no target flag runs the full wizard; a target flag generates just
 // that one artifact. -x mirrors a target onto the module's external (API-key)
-// surface and applies to -c, -s, -dp and -lp only.
+// surface and applies to -c, -s, -dp and -fp only.
 const GEN_TARGETS = [
   ['controller', 'controller'],
   ['service', 'service'],
   ['dataProcessor', 'dataProcessor'],
-  ['listProcessor', 'listProcessor'],
+  ['filterProcessor', 'filterProcessor'],
   ['entity', 'entity'],
   ['job', 'job'],
 ];
@@ -50,7 +50,7 @@ program
   .option('-c, --controller', 'generate only a controller')
   .option('-s, --service', 'generate only a service')
   .option('-dp, --data-processor', 'generate only a data processor')
-  .option('-lp, --list-processor', 'generate only a listing processor')
+  .option('-fp, --filter-processor', 'generate only a filter processor')
   .option('-e, --entity', 'generate an entity and its migration')
   .option('-j, --job', 'generate only a job')
   .option('-x, --external', 'put it on the external (api/e/v1) surface')
@@ -62,7 +62,7 @@ Examples:
   ${cli} gen -c              controller only (asks module, name, route path)
   ${cli} gen -s              bare injectable service
   ${cli} gen -dp             data processor (+ its Add<Name>DataDto if missing)
-  ${cli} gen -lp             listing processor
+  ${cli} gen -fp             filter processor
   ${cli} gen -e              entity + migration, registered in the constants/maps
   ${cli} gen -j              job, registered in job.constants/job.maps
   ${cli} gen -x -c           external controller under <module>/external/controllers
@@ -75,12 +75,12 @@ Examples:
       );
       if (chosen.length > 1) {
         throw new Error(
-          'Pick one target flag at a time (-c, -s, -dp, -lp, -e or -j).',
+          'Pick one target flag at a time (-c, -s, -dp, -fp, -e or -j).',
         );
       }
       if (!chosen.length) {
         if (opts.external) {
-          throw new Error('-x needs a target: -c, -s, -dp or -lp.');
+          throw new Error('-x needs a target: -c, -s, -dp or -fp.');
         }
         return require('./commands/gen')();
       }
@@ -102,7 +102,7 @@ program
 
 program
   .command('sync')
-  .description('rebuild es6.classes barrels and register modules in app.module.ts')
+  .description('rebuild module registries and register modules in app.module.ts')
   .action(run(() => require('./commands/sync')()));
 
 program

package/src/lib/flavour.js

@@ -7,7 +7,7 @@ const path = require('path');
  * Which package the generated code is written against.
  *
  * The two share every convention this CLI encodes — dot.separated filenames,
- * the processor lifecycle, es6.classes barrels, the migration utility — and
+ * the processor lifecycle, module registries, the migration utility — and
  * differ in what a record belongs to. `nestend` is the tenanted model: rows
  * carry a `tenant_id`, access is a scope *and* a role. `nestendx` is the B2C
  * one: users register themselves and hold scopes alone, so a row belongs to the

package/src/lib/sync.engine.js

@@ -8,12 +8,12 @@ const scan = require('./source.scan');
 /**
  * The sync engine is the single brain behind `nh sync`, `nh check` and the
  * auto-wiring step of `nh gen`. It scans scaffolded modules, regenerates each
- * module's es6.classes.ts barrel from the files actually present on disk, and
+ * module's module.registry.ts from the files actually present on disk, and
  * registers every module in app.module.ts — so the project builds without any
  * manual import wiring.
  */
 
-// Provider categories registered through es6.classes.ts. Files are classified
+// Provider categories registered through module.registry.ts. Files are classified
 // by the folder they live in (not by a fragile filename suffix) so that
 // non-standard names — e.g. the boilerplate's `test.service..ts` — are still
 // picked up and never silently dropped from the barrel.
@@ -27,12 +27,12 @@ const CATEGORIES = [
 ];
 
 // Files in a category folder that are not providers themselves.
-const NON_PROVIDER_FILES = new Set(['es6.classes.ts', 'index.ts']);
+const NON_PROVIDER_FILES = new Set(['module.registry.ts', 'index.ts']);
 
 // A module may expose an API-key surface from `<module>/external/<folder>`
 // (e.g. external/controllers/external.test.controller.ts). Those classes are
 // providers of the same categories as their internal siblings and belong in
-// the same es6.classes arrays — listed after the internal ones — so the
+// the same module.registry arrays — listed after the internal ones — so the
 // scanner has to walk both roots or `nh sync` would strip them from the
 // barrel.
 const EXTERNAL_DIR = 'external';
@@ -109,7 +109,7 @@ function scanModule(dir, modFile) {
     moduleFile: modFile,
     moduleClass: exportedClassName(modFile),
     moduleImportPath: `./${moduleDot}/${path.basename(modFile, '.ts')}`,
-    es6Path: path.join(dir, 'es6.classes.ts'),
+    registryPath: path.join(dir, 'module.registry.ts'),
     providers,
     entities: listTsFiles(path.join(dir, 'entities'), '.entity.ts'),
     dtos: listTsFiles(path.join(dir, 'dtos'), '.dto.ts'),
@@ -117,7 +117,7 @@ function scanModule(dir, modFile) {
 }
 
 /**
- * Render the es6.classes.ts content for a scanned module.
+ * Render the module.registry.ts content for a scanned module.
  *
  * The array literals are wrapped exactly the way prettier's 80-column printer
  * would: inline while they fit, one class per line once they don't. `nh gen`
@@ -125,7 +125,7 @@ function scanModule(dir, modFile) {
  * every later `nh check` would report the barrel as drifted purely because
  * prettier had reflowed it.
  */
-function buildEs6Content(mod) {
+function buildRegistryContent(mod) {
   const importLines = [];
   const arrayLines = [];
   for (const cat of CATEGORIES) {
@@ -142,19 +142,19 @@ function buildEs6Content(mod) {
     );
   }
   const header = importLines.length ? importLines.join('\n') + '\n\n' : '';
-  return `${header}export const es6Classes = {\n${arrayLines.join('\n')}\n};\n`;
+  return `${header}export const moduleRegistry = {\n${arrayLines.join('\n')}\n};\n`;
 }
 
-/** Plan the es6.classes.ts rewrite for one module. */
-function planEs6(mod) {
-  const next = buildEs6Content(mod);
-  const current = fs.existsSync(mod.es6Path)
-    ? fs.readFileSync(mod.es6Path, 'utf8')
+/** Plan the module.registry.ts rewrite for one module. */
+function planRegistry(mod) {
+  const next = buildRegistryContent(mod);
+  const current = fs.existsSync(mod.registryPath)
+    ? fs.readFileSync(mod.registryPath, 'utf8')
     : null;
   return {
-    type: 'es6',
+    type: 'registry',
     moduleDot: mod.moduleDot,
-    path: mod.es6Path,
+    path: mod.registryPath,
     current,
     next,
     changed: current !== next,
@@ -251,18 +251,18 @@ function planAppModule(paths, modules) {
   };
 }
 
-/** Full plan: every module's es6 barrel + app.module registration. */
+/** Full plan: every module's module registry + app.module registration. */
 function buildPlan(paths, modules = scanModules(paths)) {
   return {
     modules,
-    es6: modules.map(planEs6),
+    registries: modules.map(planRegistry),
     appModule: planAppModule(paths, modules),
   };
 }
 
 function applyPlan(plan) {
   const written = [];
-  for (const p of plan.es6) {
+  for (const p of plan.registries) {
     if (p.changed) {
       fs.writeFileSync(p.path, p.next);
       written.push(p.path);
@@ -280,8 +280,8 @@ module.exports = {
   EXTERNAL_DIR,
   scanModules,
   scanModule,
-  buildEs6Content,
-  planEs6,
+  buildRegistryContent,
+  planRegistry,
   planAppModule,
   buildPlan,
   applyPlan,

package/src/lib/templates.js

@@ -15,7 +15,7 @@ const { accessNames } = require('./access');
  * Code templates. All generated code imports shared base classes from the
  * package the active flavour names — `@neohm/nestend` under `nh`,
  * `@neohm/nestendx` under `nhx` (verified exports: CommonEntity, CommonDataDto,
- * CommonDataProcessor, MigrationUtility, SeederUtility, etc.) — and matches the
+ * BaseDataProcessor, MigrationHelper, SeederUtility, etc.) — and matches the
  * dot.separated filename / PascalCase class conventions used across the
  * boilerplates.
  *
@@ -59,8 +59,8 @@ function names(base) {
     dtoFile: `add.${dot}.data.dto.ts`,
     processorClass: `${pascal}DataProcessor`,
     processorFile: `${dot}.data.processor.ts`,
-    listProcessorClass: `${pascal}ListProcessor`,
-    listProcessorFile: `${dot}.list.processor.ts`,
+    filterProcessorClass: `${pascal}FilterProcessor`,
+    filterProcessorFile: `${dot}.filter.processor.ts`,
     subscriberClass: `${pascal}Subscriber`,
     subscriberFile: `${dot}.subscriber.ts`,
     jobClass: `${pascal}Job`,
@@ -74,8 +74,8 @@ function names(base) {
     externalServiceFile: `external.${dot}.service.ts`,
     externalProcessorClass: `External${pascal}DataProcessor`,
     externalProcessorFile: `external.${dot}.data.processor.ts`,
-    externalListProcessorClass: `External${pascal}ListProcessor`,
-    externalListProcessorFile: `external.${dot}.list.processor.ts`,
+    externalFilterProcessorClass: `External${pascal}FilterProcessor`,
+    externalFilterProcessorFile: `external.${dot}.filter.processor.ts`,
     // Fed through naming.migrationFileName/migrationClassName so the migration
     // `nh gen` writes is named exactly like one from `nh migration`.
     migrationName: `Add${pascal}Table`,
@@ -137,14 +137,14 @@ function attributesDto(base) {
  */
 function controller(
   base,
-  { processor = false, listProcessor = false, enums = {} } = {},
+  { processor = false, filterProcessor = false, enums = {} } = {},
 ) {
   const n = names(base);
   const a = accessNames(base);
   const scopeEnum = enums.scope || 'ScopeEnum';
   const roleEnum = enums.role || 'RoleEnum';
   const svcProp = `${n.camel}Service`;
-  const hasPost = processor || listProcessor;
+  const hasPost = processor || filterProcessor;
 
   // @nestjs/common members, alphabetised the way prettier leaves them.
   const nestCommon = [
@@ -159,7 +159,7 @@ function controller(
   nestCommon.sort();
 
   const nestendImports = ['AuthService'];
-  if (listProcessor) nestendImports.push('CommonListFilterDto');
+  if (filterProcessor) nestendImports.push('CommonListFilterDto');
   nestendImports.push('StrictValidationPipe');
 
   const imports = [
@@ -178,28 +178,24 @@ function controller(
     );
   }
 
-  // Tenanted access takes the entity's scope and the lowest role that should
-  // reach the endpoint (a senior role satisfies a junior one); the B2C model
-  // has no roles, so the same call carries the scope alone.
+  // Tenanted access names the lowest role that should reach the endpoint: the
+  // role carries its scope, so validateRole() checks the organization holds the
+  // scope first, then the role (a senior role satisfies a junior one). The B2C
+  // model has no roles, so the check is the scope alone.
   const tenanted = current().tenantScoped;
   imports.push(
-    `import { ${scopeEnum} } from '../../global/enums/scope.enum';`,
+    tenanted
+      ? `import { ${roleEnum} } from '../../global/enums/role.enum';`
+      : `import { ${scopeEnum} } from '../../global/enums/scope.enum';`,
   );
-  if (tenanted)
-    imports.push(`import { ${roleEnum} } from '../../global/enums/role.enum';`);
-  const scopeRef = `${scopeEnum}.${a.scopeKey}`;
   const gate = (indent, level) => {
-    if (!tenanted) {
-      const call = `await this.authService.validateAccess(${scopeRef})`;
-      return `${indent}const { user } = ${call};`.length <= 80
-        ? call
-        : `await this.authService.validateAccess(\n${indent}  ${scopeRef},\n${indent})`;
-    }
-    const roleRef = `${roleEnum}.${a.roles[level].key}`;
-    const call = `await this.authService.validateAccess(${scopeRef}, ${roleRef})`;
+    const [method, arg] = tenanted
+      ? ['validateRole', `${roleEnum}.${a.roles[level].key}`]
+      : ['validateAccess', `${scopeEnum}.${a.scopeKey}`];
+    const call = `await this.authService.${method}(${arg})`;
     return `${indent}const { user } = ${call};`.length <= 80
       ? call
-      : `await this.authService.validateAccess(\n${indent}  ${scopeRef},\n${indent}  ${roleRef},\n${indent})`;
+      : `await this.authService.${method}(\n${indent}  ${arg},\n${indent})`;
   };
 
   const methods = [
@@ -222,7 +218,7 @@ function controller(
   }`);
   }
 
-  if (listProcessor) {
+  if (filterProcessor) {
     methods.push(`  @Post('list')
   @ApiOperation({ summary: 'List, search and filter ${n.kebab}.' })
   async list(@Body() body: CommonListFilterDto) {
@@ -263,14 +259,14 @@ ${methods.join('\n\n')}
  * controller, so nothing downstream has to know how a record is fetched.
  *
  * `get()` is unconditional — it is the one operation that needs no processor.
- * `upsert()` appears with a data processor, `list()` with a listing processor.
+ * `upsert()` appears with a data processor, `list()` with a filter processor.
  */
-function service(base, { processor = false, listProcessor = false } = {}) {
+function service(base, { processor = false, filterProcessor = false } = {}) {
   const n = names(base);
   const label = toWords(base).join(' ');
 
   const nestendImports = [];
-  if (listProcessor) {
+  if (filterProcessor) {
     nestendImports.push('CommonListFilterDto', 'ListFilterService');
   }
   nestendImports.push('NotFoundException', 'UserEntity');
@@ -279,9 +275,9 @@ function service(base, { processor = false, listProcessor = false } = {}) {
     namedImport(nestendImports, pkg()),
     `import { Injectable } from '@nestjs/common';`,
   ];
-  if (listProcessor) {
+  if (filterProcessor) {
     imports.push(
-      `import { ${n.listProcessorClass} } from '../libraries/${n.dot}.list.processor';`,
+      `import { ${n.filterProcessorClass} } from '../libraries/${n.dot}.filter.processor';`,
     );
   }
   if (processor) {
@@ -295,7 +291,7 @@ function service(base, { processor = false, listProcessor = false } = {}) {
   );
 
   const members = [];
-  if (listProcessor) {
+  if (filterProcessor) {
     members.push(
       `  constructor(protected readonly listFilterService: ListFilterService) {}`,
     );
@@ -332,12 +328,12 @@ function service(base, { processor = false, listProcessor = false } = {}) {
   }`);
   }
 
-  if (listProcessor) {
+  if (filterProcessor) {
     // Emit the call already wrapped the way prettier's 80-column printer
     // would, so a long entity name doesn't leave the generated file dirty.
     // Prettier's three tiers: keep the fluent one-liner; else break the
     // .process() argument; else break the constructor arguments too.
-    const call = `new ${n.listProcessorClass}(this.listFilterService, user)`;
+    const call = `new ${n.filterProcessorClass}(this.listFilterService, user)`;
     const oneLine = `    return ${call}.process(data);`;
     const brokenArg = `    return ${call}.process(`;
     let body;
@@ -346,7 +342,7 @@ function service(base, { processor = false, listProcessor = false } = {}) {
     } else if (brokenArg.length <= 80) {
       body = `${brokenArg}\n      data,\n    );`;
     } else {
-      body = `    return new ${n.listProcessorClass}(\n      this.listFilterService,\n      user,\n    ).process(data);`;
+      body = `    return new ${n.filterProcessorClass}(\n      this.listFilterService,\n      user,\n    ).process(data);`;
     }
     members.push(`  async list(user: UserEntity, data: CommonListFilterDto) {
 ${body}
@@ -428,12 +424,12 @@ export class ${cls} {}
  */
 function additionalJob(base) {
   const n = names(base);
-  return `import { CommonJob, QueueService } from '${pkg()}';
+  return `import { BaseJob, QueueService } from '${pkg()}';
 import { Injectable } from '@nestjs/common';
 import { JobConstants } from '../../constants/job.constants';
 
 @Injectable()
-export class ${n.jobClass} extends CommonJob {
+export class ${n.jobClass} extends BaseJob {
   constructor(protected readonly queueService: QueueService) {
     super(JobConstants.${n.camel}Job);
   }
@@ -462,10 +458,10 @@ function processor(base, { external = false, withEntity = false } = {}) {
   const up = external ? '../..' : '..';
   const cls = external ? n.externalProcessorClass : n.processorClass;
   if (external) {
-    return `import { CommonDataProcessor } from '${pkg()}';
+    return `import { BaseDataProcessor } from '${pkg()}';
 import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';
 
-export class ${cls} extends CommonDataProcessor {
+export class ${cls} extends BaseDataProcessor {
   protected payload: ${n.dtoClass};
 
   async process(data: ${n.dtoClass}) {
@@ -522,10 +518,10 @@ export class ${cls} extends CommonDataProcessor {
     : `  private set(): void {
     // TODO: persist ${n.pascal} from this.payload, assigning fields explicitly.
   }`;
-  return `import { CommonDataProcessor, UserEntity } from '${pkg()}';
+  return `import { BaseDataProcessor, UserEntity } from '${pkg()}';
 import { ${n.dtoClass} } from '${up}/dtos/add.${n.dot}.data.dto';${entityImport}
 
-export class ${cls} extends CommonDataProcessor {
+export class ${cls} extends BaseDataProcessor {
   protected payload: ${n.dtoClass};${existingField}
 
   constructor(private readonly user: UserEntity) {
@@ -562,13 +558,13 @@ ${set}
 `;
 }
 
-function listProcessor(base, tableName, { external = false } = {}) {
+function filterProcessor(base, tableName, { external = false } = {}) {
   const n = names(base);
-  const cls = external ? n.externalListProcessorClass : n.listProcessorClass;
+  const cls = external ? n.externalFilterProcessorClass : n.filterProcessorClass;
   return `import {
   CommonListFilterConfig,
   CommonListFilterDto,
-  CommonListProcessor,
+  BaseFilterProcessor,
   FilterValueTypeEnum,
   ListFilterService,
   SortDirection,
@@ -593,7 +589,7 @@ function listProcessor(base, tableName, { external = false } = {}) {
  *    \`columns\`. Standing literal clauses go in \`predicates\`; anything
  *    carrying a value goes in the method, where add() binds it.
  */
-export class ${cls} extends CommonListProcessor {
+export class ${cls} extends BaseFilterProcessor {
   protected config: CommonListFilterConfig = {
     query: '${tableName} a',
     columns: [
@@ -643,14 +639,14 @@ ${
 
 function subscriber(base) {
   const n = names(base);
-  return `import { CommonSubscriber } from '${pkg()}';
+  return `import { BaseEntitySubscriber } from '${pkg()}';
 import { EventSubscriber } from 'typeorm';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
 import { DataSource } from 'typeorm';
 import { ${n.jobClass} } from '../jobs/${n.dot}.job';
 
 @EventSubscriber()
-export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
+export class ${n.subscriberClass} extends BaseEntitySubscriber<${n.entityClass}> {
   constructor(
     protected readonly datasource: DataSource,
     protected readonly entityJob: ${n.jobClass},
@@ -671,13 +667,13 @@ export class ${n.subscriberClass} extends CommonSubscriber<${n.entityClass}> {
 
 function job(base) {
   const n = names(base);
-  return `import { CommonJob, QueueService, DatabaseEventDto } from '${pkg()}';
+  return `import { BaseEntityJob, QueueService, DatabaseEventDto } from '${pkg()}';
 import { Injectable } from '@nestjs/common';
 import { JobConstants } from '../../constants/job.constants';
 import { ${n.entityClass} } from '../entities/${n.dot}.entity';
 
 @Injectable()
-export class ${n.jobClass} extends CommonJob {
+export class ${n.jobClass} extends BaseEntityJob {
   constructor(protected readonly queueService: QueueService) {
     super(JobConstants.${n.camel}Job);
   }
@@ -697,9 +693,9 @@ export class ${n.jobClass} extends CommonJob {
 function genMigration(base, tableName, timestamp) {
   const n = names(base);
   const className = migrationClassName(n.migrationName, timestamp);
-  return `import { MigrationUtility } from '${pkg()}';
+  return `import { MigrationHelper } from '${pkg()}';
 
-export class ${className} extends MigrationUtility {
+export class ${className} extends MigrationHelper {
   constructor() {
     super('${tableName}');
     this.process();
@@ -730,9 +726,9 @@ ${current().tenantScoped ? `    this.index('tenant_id');\n` : ''}    this.index(
 /** Standalone migration (`nh migration`). */
 function migration(migrationName, tableName, timestamp) {
   const className = migrationClassName(migrationName, timestamp);
-  return `import { MigrationUtility } from '${pkg()}';
+  return `import { MigrationHelper } from '${pkg()}';
 
-export class ${className} extends MigrationUtility {
+export class ${className} extends MigrationHelper {
   constructor() {
     super('${tableName}');
     this.process();
@@ -845,9 +841,9 @@ ${members}
 `;
 }
 
-/** A freshly scaffolded module before any es6.classes content exists. */
-function emptyEs6Classes() {
-  return `export const es6Classes = {
+/** A freshly scaffolded module before any module.registry content exists. */
+function emptyModuleRegistry() {
+  return `export const moduleRegistry = {
   controllers: [],
   services: [],
   libraries: [],
@@ -867,16 +863,16 @@ import {
   AuthModule,
   SystemPropertyModule,
 } from '${pkg()}';
-import { es6Classes } from './es6.classes';
+import { moduleRegistry } from './module.registry';
 
 @Module({
   imports: [CommonModule, QueueModule, AuthModule, SystemPropertyModule],
-  controllers: [...es6Classes.controllers],
+  controllers: [...moduleRegistry.controllers],
   providers: [
-    ...es6Classes.services,
-    ...es6Classes.libraries,
-    ...es6Classes.jobs,
-    ...es6Classes.subscribers,
+    ...moduleRegistry.services,
+    ...moduleRegistry.libraries,
+    ...moduleRegistry.jobs,
+    ...moduleRegistry.subscribers,
   ],
 })
 export class ${pascal}Module {}
@@ -897,7 +893,7 @@ module.exports = {
   additionalJob,
   dto,
   processor,
-  listProcessor,
+  filterProcessor,
   subscriber,
   job,
   genMigration,
@@ -907,6 +903,6 @@ module.exports = {
   entityConstantsFile,
   jobMapsFile,
   entityMapsFile,
-  emptyEs6Classes,
+  emptyModuleRegistry,
   moduleFile,
 };