@neohm/nh-cli 1.1.5 → 1.3.0

package/src/lib/collision.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Name-collision guard for the flag generators.
+ *
+ * `nh gen -j Order` must not quietly land next to an existing OrderJob: the
+ * job identifier registries (job.constants / job.maps) are project-wide, so a
+ * second class of the same name is a genuine conflict rather than a shadowed
+ * local. The same holds for controllers, services and processors, where two
+ * identically named providers in one Nest container is a bug that surfaces
+ * far from its cause.
+ *
+ * So before writing anything, look for the target *anywhere* under src/ —
+ * by filename and by exported class name — and report what is already there
+ * instead of creating a near-duplicate.
+ */
+
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'coverage', '.git']);
+
+/** Every .ts file under `dir`, recursively. */
+function walkTs(dir, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      walkTs(path.join(dir, entry.name), out);
+    } else if (entry.isFile() && entry.name.endsWith('.ts')) {
+      out.push(path.join(dir, entry.name));
+    }
+  }
+  return out;
+}
+
+function exportedClassNames(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  return [...content.matchAll(/export\s+(?:abstract\s+)?class\s+(\w+)/g)].map(
+    (m) => m[1],
+  );
+}
+
+/**
+ * Look for `className` / `fileName` under srcDir.
+ *
+ * Returns `null` when the name is free, otherwise
+ * `{ kind: 'class' | 'file', file }` describing the first conflict found —
+ * a class match is reported ahead of a filename match, since it is the one
+ * that actually breaks at runtime.
+ */
+function findConflict(srcDir, { className, fileName }) {
+  const files = walkTs(srcDir);
+
+  if (className) {
+    for (const file of files) {
+      if (exportedClassNames(file).includes(className)) {
+        return { kind: 'class', file, name: className };
+      }
+    }
+  }
+
+  if (fileName) {
+    for (const file of files) {
+      if (path.basename(file) === fileName) {
+        return { kind: 'file', file, name: fileName };
+      }
+    }
+  }
+
+  return null;
+}
+
+/** Human-readable one-liner for a conflict, relative to the project root. */
+function describeConflict(conflict, root) {
+  const rel = path.relative(root, conflict.file);
+  return conflict.kind === 'class'
+    ? `a class named ${conflict.name} already exists in ${rel}`
+    : `a file named ${conflict.name} already exists at ${rel}`;
+}
+
+module.exports = { walkTs, exportedClassNames, findConflict, describeConflict };

package/src/lib/flavour.js

@@ -0,0 +1,106 @@
+'use strict';
+
+const fs = require('fs');
+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
+ * 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
+ * user who created it and access is a scope.
+ *
+ * `nh` generates the first, `nhx` the second. Everything that does not generate
+ * code — sync, check, list, remove — is the same command either way.
+ */
+const FLAVOURS = {
+  nestend: {
+    key: 'nestend',
+    cli: 'nh',
+    package: '@neohm/nestend',
+    /** Rows belong to a tenant; the scope check carries a role beside it. */
+    tenantScoped: true,
+  },
+  nestendx: {
+    key: 'nestendx',
+    cli: 'nhx',
+    package: '@neohm/nestendx',
+    tenantScoped: false,
+  },
+};
+
+let active = FLAVOURS.nestend;
+
+/** Set by the bin entrypoint before anything else is required. */
+function setFlavour(key) {
+  const flavour = FLAVOURS[key];
+  if (!flavour) throw new Error(`Unknown flavour "${key}".`);
+  active = flavour;
+  return active;
+}
+
+function current() {
+  return active;
+}
+
+/** The package specifier generated imports are written against. */
+function pkg() {
+  return active.package;
+}
+
+/** The command the person actually typed, for help text and hints. */
+function cli() {
+  return active.cli;
+}
+
+/**
+ * Which package a project depends on, read from its package.json. Returns null
+ * when it depends on neither — a project that has not installed one yet is not
+ * an error, it is simply not evidence either way.
+ */
+function detectFlavour(projectRoot) {
+  const manifest = path.join(projectRoot, 'package.json');
+  let deps;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+    deps = { ...parsed.dependencies, ...parsed.devDependencies };
+  } catch {
+    return null;
+  }
+
+  // nestendx first: "@neohm/nestend" is a prefix of it, and a project can only
+  // sensibly depend on one.
+  if (deps[FLAVOURS.nestendx.package]) return FLAVOURS.nestendx.key;
+  if (deps[FLAVOURS.nestend.package]) return FLAVOURS.nestend.key;
+  return null;
+}
+
+/**
+ * Refuse to scaffold against the wrong package. Generating tenanted code into a
+ * nestendx project produces files that import a package that is not there and
+ * columns no table has — a failure the person would meet later, in a compiler
+ * error, with nothing pointing back here.
+ */
+function assertFlavourMatchesProject(projectRoot) {
+  const detected = detectFlavour(projectRoot);
+  if (!detected || detected === active.key) return;
+
+  const wanted = FLAVOURS[detected];
+  throw new Error(
+    `This project depends on ${wanted.package}, but you ran ${active.cli}, ` +
+      `which generates ${active.package} code.\n  Use \`${wanted.cli}\` here instead.`,
+  );
+}
+
+module.exports = {
+  FLAVOURS,
+  setFlavour,
+  current,
+  pkg,
+  cli,
+  detectFlavour,
+  assertFlavourMatchesProject,
+};

package/src/lib/format.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Format generated files with the *target project's* prettier, honouring its
+ * own .prettierrc.
+ *
+ * The boilerplate lints with `prettier/prettier: error`, so a scaffold that is
+ * merely valid TypeScript is not good enough — it has to land already
+ * formatted, or `yarn lint` fails on freshly generated code. Templates aim to
+ * emit prettier-clean output on their own; this is the backstop that keeps
+ * that true for entity names long enough to push a line past 80 columns.
+ *
+ * Best-effort by design: a project without prettier installed still gets its
+ * files, just unformatted.
+ */
+function loadPrettier(root) {
+  try {
+    return require(require.resolve('prettier', { paths: [root] }));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format `files` in place. Returns the count actually rewritten, or null when
+ * prettier could not be resolved from the project.
+ */
+async function formatFiles(files, root) {
+  const prettier = loadPrettier(root);
+  if (!prettier) return null;
+
+  let changed = 0;
+  for (const file of new Set(files)) {
+    if (!file || !fs.existsSync(file)) continue;
+    if (!['.ts', '.js', '.json'].includes(path.extname(file))) continue;
+    try {
+      const source = fs.readFileSync(file, 'utf8');
+      const config = (await prettier.resolveConfig(file)) || {};
+      const next = await prettier.format(source, { ...config, filepath: file });
+      if (next !== source) {
+        fs.writeFileSync(file, next);
+        changed++;
+      }
+    } catch {
+      // A file prettier cannot parse is left exactly as generated.
+    }
+  }
+  return changed;
+}
+
+module.exports = { formatFiles, loadPrettier };

package/src/lib/registry.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const path = require('path');
+
+const tpl = require('./templates');
+const { log } = require('./fs.utils');
+const {
+  ensureConstantEntry,
+  ensureMapEntry,
+  detectExportName,
+  entityConstantsPath,
+} = require('./constants.engine');
+
+/**
+ * The project-wide identifier registries.
+ *
+ * Entities and jobs are addressed by string identifier at runtime, so each one
+ * has to appear twice: as `<name>: '<dot.name>'` in the constants file, and as
+ * `[Constants.<name>]: <Class>` in the map beside it. A generated job
+ * references `JobConstants.<name>Job` directly, so a missing entry is a
+ * compile error rather than a latent one.
+ *
+ * Shared by the `nh gen` wizard and the `nh gen -e` / `nh gen -j` flags so
+ * both register identically. Registration is best-effort: a registry the
+ * engine cannot parse produces a warning telling you the one line to add, not
+ * a failed run that has already written half a module.
+ */
+
+/** Register `<base>Job` in job.constants.ts and job.maps.ts. */
+function registerJob(paths, base, moduleDot, report) {
+  const n = tpl.names(base);
+
+  const constantsPath = path.join(paths.constantsDir, 'job.constants.ts');
+  const entry = ensureConstantEntry(
+    constantsPath,
+    tpl.jobConstantsFile(base),
+    `${n.camel}Job`,
+    `${n.dot}.job`,
+  );
+  if (entry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, constantsPath)} — add ${n.camel}Job: '${n.dot}.job' manually.`,
+    );
+  } else {
+    report(entry, constantsPath, paths.root);
+  }
+
+  const constantsRef = {
+    exportName: detectExportName(constantsPath) || 'JobConstants',
+    importPath: './job.constants',
+  };
+  const mapsPath = path.join(paths.constantsDir, 'job.maps.ts');
+  const mapEntry = ensureMapEntry(
+    mapsPath,
+    tpl.jobMapsFile(base, moduleDot, constantsRef),
+    `[${constantsRef.exportName}.${n.camel}Job]`,
+    n.jobClass,
+    [
+      { className: n.jobClass, importPath: `../${moduleDot}/jobs/${n.dot}.job` },
+      { className: constantsRef.exportName, importPath: constantsRef.importPath },
+    ],
+  );
+  if (mapEntry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, mapsPath)} — map ${n.jobClass} manually.`,
+    );
+  } else {
+    report(mapEntry, mapsPath, paths.root);
+  }
+}
+
+/** Register `<base>` in entity.constants.ts and entity.maps.ts. */
+function registerEntity(paths, base, moduleDot, report) {
+  const n = tpl.names(base);
+
+  // The boilerplate ships this file misspelled in some projects, so the
+  // engine reports whichever spelling is actually on disk.
+  const constantsPath = entityConstantsPath(paths.constantsDir);
+  const entry = ensureConstantEntry(
+    constantsPath,
+    tpl.entityConstantsFile(base),
+    n.camel,
+    n.dot,
+  );
+  if (entry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, constantsPath)} — add ${n.camel}: '${n.dot}' manually.`,
+    );
+  } else {
+    report(entry, constantsPath, paths.root);
+  }
+
+  const constantsRef = {
+    exportName: detectExportName(constantsPath) || 'EntityConstants',
+    importPath: `./${path.basename(constantsPath, '.ts')}`,
+  };
+  const mapsPath = path.join(paths.constantsDir, 'entity.maps.ts');
+  const mapEntry = ensureMapEntry(
+    mapsPath,
+    tpl.entityMapsFile(base, moduleDot, constantsRef),
+    `[${constantsRef.exportName}.${n.camel}]`,
+    n.entityClass,
+    [
+      {
+        className: n.entityClass,
+        importPath: `../${moduleDot}/entities/${n.dot}.entity`,
+      },
+      { className: constantsRef.exportName, importPath: constantsRef.importPath },
+    ],
+  );
+  if (mapEntry === 'failed') {
+    log.warn(
+      `Could not update ${path.relative(paths.root, mapsPath)} — map ${n.entityClass} manually.`,
+    );
+  } else {
+    report(mapEntry, mapsPath, paths.root);
+  }
+}
+
+module.exports = { registerJob, registerEntity };

package/src/lib/sync.engine.js

@@ -27,6 +27,14 @@ const CATEGORIES = [
 // Files in a category folder that are not providers themselves.
 const NON_PROVIDER_FILES = new Set(['es6.classes.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
+// scanner has to walk both roots or `nh sync` would strip them from the
+// barrel.
+const EXTERNAL_DIR = 'external';
+
 function exportedClassName(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
   const match = content.match(/export\s+class\s+(\w+)/);
@@ -80,12 +88,17 @@ function scanModule(dir, modFile) {
   const moduleDot = path.basename(dir);
   const providers = {};
   for (const cat of CATEGORIES) {
-    providers[cat.key] = listClassFiles(path.join(dir, cat.folder)).map(
-      (file) => ({
+    // Internal first, then the external/ mirror of the same category.
+    const roots = [
+      { base: dir, prefix: '' },
+      { base: path.join(dir, EXTERNAL_DIR), prefix: `${EXTERNAL_DIR}/` },
+    ];
+    providers[cat.key] = roots.flatMap(({ base, prefix }) =>
+      listClassFiles(path.join(base, cat.folder)).map((file) => ({
         file,
         className: exportedClassName(file),
-        importPath: `./${cat.folder}/${path.basename(file, '.ts')}`,
-      }),
+        importPath: `./${prefix}${cat.folder}/${path.basename(file, '.ts')}`,
+      })),
     );
   }
   return {
@@ -101,7 +114,15 @@ function scanModule(dir, modFile) {
   };
 }
 
-/** Render the es6.classes.ts content for a scanned module. */
+/**
+ * Render the es6.classes.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`
+ * formats what it writes, so if this emitted a single long line instead,
+ * every later `nh check` would report the barrel as drifted purely because
+ * prettier had reflowed it.
+ */
 function buildEs6Content(mod) {
   const importLines = [];
   const arrayLines = [];
@@ -110,8 +131,13 @@ function buildEs6Content(mod) {
     for (const e of entries) {
       importLines.push(`import { ${e.className} } from '${e.importPath}';`);
     }
-    const classes = entries.map((e) => e.className).join(', ');
-    arrayLines.push(`  ${cat.key}: [${classes}],`);
+    const classes = entries.map((e) => e.className);
+    const inline = `  ${cat.key}: [${classes.join(', ')}],`;
+    arrayLines.push(
+      inline.length <= 80
+        ? inline
+        : `  ${cat.key}: [\n${classes.map((c) => `    ${c},`).join('\n')}\n  ],`,
+    );
   }
   const header = importLines.length ? importLines.join('\n') + '\n\n' : '';
   return `${header}export const es6Classes = {\n${arrayLines.join('\n')}\n};\n`;
@@ -233,6 +259,7 @@ function applyPlan(plan) {
 
 module.exports = {
   CATEGORIES,
+  EXTERNAL_DIR,
   scanModules,
   scanModule,
   buildEs6Content,