@aventara/cli 0.0.0-stage → 0.1.0-pilot.0

package/dist/node-version.guard.js

@@ -0,0 +1,59 @@
+// biome-ignore lint/style/useNodejsImportProtocol: Node 14.0–14.13.0 resolves no "node:" specifier in an ES module, and this module runs on the Nodes the packages do not support.
+import { readFileSync } from "fs";
+function versionOf(text) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)/.exec(text);
+    if (match === null) {
+        throw new Error(`"${text}" is not a Node version`);
+    }
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareVersions(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const difference = left[index] - right[index];
+        if (difference !== 0) {
+            return difference;
+        }
+    }
+    return 0;
+}
+/**
+ * Whether `range` admits `version`. Reads `^x.y.z` (the same major, from the
+ * floor; majors ≥ 1) and `>=x.y.z`, joined by `||`; anything else throws rather
+ * than admit or refuse by guess.
+ */
+function admits(range, version) {
+    return range.split("||").some((part) => {
+        const comparator = /^\s*(\^|>=)(\d+\.\d+\.\d+)\s*$/.exec(part);
+        if (comparator === null) {
+            throw new Error(`engines.node "${range}": the bin's Node guard reads only "^x.y.z" and ">=x.y.z" joined by "||"`);
+        }
+        const floor = versionOf(comparator[2]);
+        return (compareVersions(version, floor) >= 0 &&
+            (comparator[1] === ">=" || version[0] === floor[0]));
+    });
+}
+/** The sentence a bin answers on `version`, or `undefined` when `range` admits it. */
+export function nodeVersionRefusal(bin, packageName, range, version) {
+    return admits(range, versionOf(version))
+        ? undefined
+        : `${bin}: Node ${version} is not supported; ${packageName} needs Node ${range}.`;
+}
+/**
+ * Reads the manifest at `manifestUrl`; on a Node its `engines.node` does not
+ * admit, writes the sentence to stderr, sets exit code 1 and answers `true` —
+ * the bin then loads nothing else.
+ */
+export function refuseUnsupportedNode(bin, manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const range = manifest.engines === undefined ? undefined : manifest.engines.node;
+    if (range === undefined) {
+        throw new Error(`${manifest.name} declares no engines.node for its bin's Node guard`);
+    }
+    const refusal = nodeVersionRefusal(bin, manifest.name, range, process.version);
+    if (refusal === undefined) {
+        return false;
+    }
+    process.stderr.write(`${refusal}\n`);
+    process.exitCode = 1;
+    return true;
+}

package/dist/plan/project.planner.d.ts

@@ -0,0 +1,52 @@
+import type { CatalogEntry } from "../catalog/catalog-entry.interface.js";
+import { type ProjectInspection } from "../project/project.inspector.js";
+import type { OrmScaffold } from "../templates/template.registry.js";
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * §4.1's `plan`: everything `aventara init` will write, decided before anything
+ * is written — the files, the anchored `app.module.ts` edit (or the printed
+ * instructions), the merged manifests — and every **conflict**, computed both
+ * ways so the confirmation can choose. Pure apart from reading the files it
+ * would replace.
+ *
+ * What is Nest's (its default start scripts, `AventaraModule`'s import) and what
+ * is Aventara's (its packages at this CLI's version, D1; the `aventara:prepare`
+ * and `postinstall` scripts, Q16-22, D2) is decided here; what is the ORM's
+ * comes from its templates (D7).
+ */
+/** The name of the script that regenerates the ORM client and the discovery artifact (Q16-22). */
+export declare const PREPARE_SCRIPT = "aventara:prepare";
+export type PlannedWrite = {
+    readonly path: string;
+    readonly content: string;
+    /** `create` a new file, or `replace` one whose content changes. */
+    readonly change: "create" | "replace";
+};
+export type ProjectPlan = {
+    /** What is written when the conflicts are kept as they are. */
+    readonly keeping: readonly PlannedWrite[];
+    /** What is written once the conflicts are confirmed (`--yes`, or a yes). */
+    readonly replacing: readonly PlannedWrite[];
+    /** Existing content that differs from what would be written. */
+    readonly conflicts: readonly string[];
+    readonly warnings: readonly string[];
+    /** Printed when the anchored edit could not be made. */
+    readonly instructions: string | undefined;
+    readonly nextSteps: readonly string[];
+};
+export type PlanInput = {
+    readonly inspection: ProjectInspection;
+    readonly entry: CatalogEntry;
+    readonly scaffold: OrmScaffold;
+    readonly packageManager: PackageManager;
+    /** This CLI's version: every Aventara package is pinned to it (D1). */
+    readonly aventaraVersion: string;
+    readonly skipInstall: boolean;
+    /** The current text of a project file, or `undefined` when absent. */
+    readonly read: (file: string) => string | undefined;
+    /** The anchored edit is not attempted; the wiring is printed (a service holding its client, §4.4.4). */
+    readonly wiringByHand?: string;
+    /** Said before the write, beside the planner's own. */
+    readonly warnings?: readonly string[];
+};
+export declare function planInit(input: PlanInput): ProjectPlan;

package/dist/plan/project.planner.js

@@ -0,0 +1,178 @@
+import { spliceAppModule, wiringInstructions, } from "../apply/app-module.anchor.js";
+import { mergeEnvFile, mergeGitignore, mergePackageManifest, mergePnpmWorkspace, } from "../apply/manifest.merger.js";
+import { APP_MODULE, } from "../project/project.inspector.js";
+/**
+ * §4.1's `plan`: everything `aventara init` will write, decided before anything
+ * is written — the files, the anchored `app.module.ts` edit (or the printed
+ * instructions), the merged manifests — and every **conflict**, computed both
+ * ways so the confirmation can choose. Pure apart from reading the files it
+ * would replace.
+ *
+ * What is Nest's (its default start scripts, `AventaraModule`'s import) and what
+ * is Aventara's (its packages at this CLI's version, D1; the `aventara:prepare`
+ * and `postinstall` scripts, Q16-22, D2) is decided here; what is the ORM's
+ * comes from its templates (D7).
+ */
+/** The name of the script that regenerates the ORM client and the discovery artifact (Q16-22). */
+export const PREPARE_SCRIPT = "aventara:prepare";
+/** D3: `nest new`'s start scripts (B1), and what each becomes so `.env` reaches the server. */
+const START_SCRIPTS = {
+    start: { from: "nest start", to: "nest start --env-file .env" },
+    "start:dev": {
+        from: "nest start --watch",
+        to: "nest start --watch --env-file .env",
+    },
+    "start:debug": {
+        from: "nest start --debug --watch",
+        to: "nest start --debug --watch --env-file .env",
+    },
+    "start:prod": {
+        from: "node dist/main",
+        to: "node --env-file-if-exists=.env dist/main",
+    },
+};
+/**
+ * F-853: `nest new`'s e2e script per module kind (B1, B28), and the same run with
+ * the `.env` the start scripts load — the e2e spec boots `AppModule`, whose
+ * service needs `DATABASE_URL`, and neither vitest nor jest loads `.env`.
+ */
+const E2E_SCRIPTS = {
+    esm: {
+        from: "vitest run --config ./vitest.config.e2e.ts",
+        to: "node --env-file-if-exists=.env ./node_modules/vitest/vitest.mjs run --config ./vitest.config.e2e.ts",
+    },
+    cjs: {
+        from: "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --config ./test/jest-e2e.json",
+        to: "node --env-file-if-exists=.env --experimental-vm-modules ./node_modules/jest/bin/jest.js --config ./test/jest-e2e.json",
+    },
+};
+const NEST_HOST = "@aventara/nest";
+const CORE = "@aventara/core";
+function writeOf(path, before, after) {
+    return before === after
+        ? []
+        : [
+            {
+                path,
+                content: after,
+                change: before === undefined ? "create" : "replace",
+            },
+        ];
+}
+export function planInit(input) {
+    const { inspection, scaffold, packageManager } = input;
+    const conflicts = new Set();
+    const keeping = [];
+    const replacing = [];
+    const warnings = [...(input.warnings ?? [])];
+    const both = (path, before, merge) => {
+        const kept = merge(false);
+        const replaced = merge(true);
+        for (const conflict of replaced.conflicts) {
+            conflicts.add(conflict);
+        }
+        keeping.push(...writeOf(path, before, kept.text));
+        replacing.push(...writeOf(path, before, replaced.text));
+    };
+    // The ORM's new files: identical content is no change (P3), other content a conflict.
+    for (const file of scaffold.files) {
+        const before = input.read(file.path);
+        if (before === undefined) {
+            keeping.push({
+                path: file.path,
+                content: file.content,
+                change: "create",
+            });
+            replacing.push({
+                path: file.path,
+                content: file.content,
+                change: "create",
+            });
+        }
+        else if (before !== file.content) {
+            conflicts.add(file.path);
+            replacing.push({
+                path: file.path,
+                content: file.content,
+                change: "replace",
+            });
+        }
+    }
+    // The one edit to developer code (R2).
+    const wiring = {
+        imports: [
+            `import { AventaraModule } from '${NEST_HOST}';`,
+            ...scaffold.appModule.imports,
+        ],
+        entries: scaffold.appModule.entries,
+    };
+    const appModule = input.read(APP_MODULE);
+    const edit = input.wiringByHand !== undefined
+        ? { kind: "not-anchored", reason: input.wiringByHand }
+        : appModule === undefined
+            ? {
+                kind: "not-anchored",
+                reason: `there is no ${APP_MODULE}`,
+            }
+            : spliceAppModule(appModule, wiring);
+    let instructions;
+    if (edit.kind === "edited") {
+        keeping.push(...writeOf(APP_MODULE, appModule, edit.text));
+        replacing.push(...writeOf(APP_MODULE, appModule, edit.text));
+    }
+    else {
+        instructions = wiringInstructions(wiring);
+        warnings.push(`${APP_MODULE} was not edited: ${edit.reason}; add AventaraModule by hand, as printed below`);
+    }
+    const versions = {
+        [CORE]: input.aventaraVersion,
+        [NEST_HOST]: input.aventaraVersion,
+        [input.entry.adapterPackage]: input.aventaraVersion,
+    };
+    both("package.json", inspection.manifestText, (replace) => mergePackageManifest(inspection.manifestText, {
+        dependencies: { ...versions, ...scaffold.dependencies },
+        devDependencies: scaffold.devDependencies,
+        scripts: {
+            [PREPARE_SCRIPT]: scaffold.prepare,
+            // D2: the generated trees are ignored and rebuilt on every install.
+            postinstall: `${packageManager} run ${PREPARE_SCRIPT}`,
+        },
+        rewrites: inspection.usesNestConfig
+            ? {}
+            : {
+                ...START_SCRIPTS,
+                "test:e2e": E2E_SCRIPTS[inspection.moduleKind],
+            },
+    }, replace));
+    const env = input.read(".env");
+    if (Object.keys(scaffold.env).length > 0) {
+        both(".env", env, (replace) => mergeEnvFile(env, scaffold.env, replace));
+    }
+    const gitignore = input.read(".gitignore");
+    both(".gitignore", gitignore, () => mergeGitignore(gitignore, scaffold.gitignore));
+    if (packageManager === "pnpm" && scaffold.nativeBuilds.length > 0) {
+        const workspace = input.read("pnpm-workspace.yaml");
+        both("pnpm-workspace.yaml", workspace, () => mergePnpmWorkspace(workspace, scaffold.nativeBuilds));
+    }
+    const run = packageManager === "pnpm" ? "pnpm" : "npm";
+    return {
+        keeping,
+        replacing,
+        conflicts: [...conflicts],
+        warnings,
+        instructions,
+        nextSteps: [
+            ...(input.skipInstall
+                ? [`Install, which also runs ${PREPARE_SCRIPT}: ${run} install`]
+                : []),
+            ...scaffold.nextSteps,
+            ...(inspection.usesNestConfig
+                ? [
+                    "The start scripts were left as they are: @nestjs/config loads .env, so make sure it does before Prisma connects.",
+                ]
+                : []),
+            `Start the server: ${run} run start:dev`,
+            "In your frontend: npx @aventara/client init",
+        ],
+    };
+}

package/dist/project/package-manager.detector.d.ts

@@ -0,0 +1,12 @@
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * Q16-5's default package manager: a lockfile says what a project already uses
+ * (`init`); otherwise the package manager that launched this CLI says what the
+ * developer uses — `npm_config_user_agent` is `npm/…` under `npx` and
+ * `npm exec`, `pnpm/…` under `pnpm dlx` and `pnpm exec`, and unset when the bin
+ * runs directly (B11); otherwise npm.
+ */
+export declare function detectPackageManager(signals: {
+    readonly lockfile?: PackageManager | undefined;
+    readonly userAgent?: string | undefined;
+}): PackageManager;

package/dist/project/package-manager.detector.js

@@ -0,0 +1,14 @@
+/**
+ * Q16-5's default package manager: a lockfile says what a project already uses
+ * (`init`); otherwise the package manager that launched this CLI says what the
+ * developer uses — `npm_config_user_agent` is `npm/…` under `npx` and
+ * `npm exec`, `pnpm/…` under `pnpm dlx` and `pnpm exec`, and unset when the bin
+ * runs directly (B11); otherwise npm.
+ */
+export function detectPackageManager(signals) {
+    if (signals.lockfile !== undefined) {
+        return signals.lockfile;
+    }
+    const launcher = signals.userAgent?.split("/")[0];
+    return launcher === "pnpm" ? "pnpm" : "npm";
+}

package/dist/project/project.inspector.d.ts

@@ -0,0 +1,38 @@
+import type { PackageManifest } from "../apply/manifest.merger.js";
+import type { AdapterCatalog, CatalogEntry } from "../catalog/catalog-entry.interface.js";
+import type { ModuleKind } from "../templates/template.registry.js";
+import type { PackageManager } from "../wizard/wizard.questions.js";
+/**
+ * §4.1's `inspect`: what `aventara init` needs to know about the project in the
+ * working directory, read before anything is asked or written — so every
+ * refusal here leaves the directory exactly as it was (it is a property of the
+ * order, not of a rollback).
+ */
+/** The project is not one `aventara init` serves. A refusal: one sentence, nothing written. */
+export declare class ProjectRefusedError extends Error {
+    readonly name = "ProjectRefusedError";
+}
+/** The ORM a project already has, by the catalog's family packages (R14, D10). */
+export type OrmPresence = {
+    readonly kind: "absent";
+} | {
+    readonly kind: "present";
+    /** The family packages found among its dependencies. */
+    readonly packages: readonly string[];
+    /** The catalog entries whose family they belong to. */
+    readonly families: readonly CatalogEntry["orm"]["label"][];
+};
+export type ProjectInspection = {
+    readonly directory: string;
+    readonly manifest: PackageManifest;
+    readonly manifestText: string;
+    readonly moduleKind: ModuleKind;
+    /** The package manager the lockfile names, if exactly one does. */
+    readonly lockfile: PackageManager | undefined;
+    readonly orm: OrmPresence;
+    /** `@nestjs/config` loads `.env` itself, so the start scripts are left alone (P5). */
+    readonly usesNestConfig: boolean;
+};
+/** The file the anchored edit opens (R2). */
+export declare const APP_MODULE = "src/app.module.ts";
+export declare function inspectProject(directory: string, catalog: AdapterCatalog): ProjectInspection;

package/dist/project/project.inspector.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { lowestMajorOf } from "../catalog/range.reader.js";
+/**
+ * §4.1's `inspect`: what `aventara init` needs to know about the project in the
+ * working directory, read before anything is asked or written — so every
+ * refusal here leaves the directory exactly as it was (it is a property of the
+ * order, not of a rollback).
+ */
+/** The project is not one `aventara init` serves. A refusal: one sentence, nothing written. */
+export class ProjectRefusedError extends Error {
+    name = "ProjectRefusedError";
+}
+/** Nest 12 only (Phase 11 Q16). */
+const NEST_MAJOR = 12;
+/** D4: TypeScript 7 has no classic compiler API. */
+const FIRST_UNSUPPORTED_TYPESCRIPT = 7;
+/** The file the anchored edit opens (R2). */
+export const APP_MODULE = "src/app.module.ts";
+const LOCKFILES = [
+    ["package-lock.json", "npm"],
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+];
+function dependencyRange(manifest, name) {
+    return manifest.dependencies?.[name] ?? manifest.devDependencies?.[name];
+}
+function matchesFamily(pattern, name) {
+    return pattern.endsWith("*")
+        ? name.startsWith(pattern.slice(0, -1))
+        : name === pattern;
+}
+export function inspectProject(directory, catalog) {
+    const manifestPath = path.join(directory, "package.json");
+    if (!existsSync(manifestPath)) {
+        throw new ProjectRefusedError(`aventara init runs in a NestJS ${NEST_MAJOR} project, and there is no package.json in ${directory}`);
+    }
+    const manifestText = readFileSync(manifestPath, "utf8");
+    const manifest = JSON.parse(manifestText);
+    const nest = dependencyRange(manifest, "@nestjs/core");
+    if (nest === undefined) {
+        throw new ProjectRefusedError(`aventara init runs in a NestJS ${NEST_MAJOR} project, and this package.json has no @nestjs/core dependency`);
+    }
+    if (lowestMajorOf(nest) !== NEST_MAJOR) {
+        throw new ProjectRefusedError(`aventara init supports NestJS ${NEST_MAJOR} only, and this project depends on @nestjs/core ${nest}`);
+    }
+    const typescript = dependencyRange(manifest, "typescript");
+    const typescriptMajor = typescript === undefined ? undefined : lowestMajorOf(typescript);
+    if (typescriptMajor !== undefined &&
+        typescriptMajor >= FIRST_UNSUPPORTED_TYPESCRIPT) {
+        throw new ProjectRefusedError(`this project declares typescript ${typescript}, and TypeScript ${FIRST_UNSUPPORTED_TYPESCRIPT} has no classic compiler API for Aventara's generate steps to read types with; use TypeScript 6 or 5`);
+    }
+    const lockfiles = LOCKFILES.filter(([file]) => existsSync(path.join(directory, file))).map(([, manager]) => manager);
+    const known = lockfiles.filter((manager) => manager !== "yarn");
+    if (lockfiles.includes("yarn") && known.length === 0) {
+        throw new ProjectRefusedError("this project has only a yarn.lock, and aventara init supports npm and pnpm");
+    }
+    const appModule = path.join(directory, APP_MODULE);
+    if (existsSync(appModule) &&
+        /\bAventaraModule\b/.test(readFileSync(appModule, "utf8"))) {
+        throw new ProjectRefusedError(`this project is already initialized: ${APP_MODULE} uses AventaraModule`);
+    }
+    const dependencies = [
+        ...Object.keys(manifest.dependencies ?? {}),
+        ...Object.keys(manifest.devDependencies ?? {}),
+    ];
+    const present = catalog.filter((entry) => entry.familyPackages.some((pattern) => dependencies.some((name) => matchesFamily(pattern, name))));
+    const orm = present.length === 0
+        ? { kind: "absent" }
+        : {
+            kind: "present",
+            packages: dependencies.filter((name) => present.some((entry) => entry.familyPackages.some((pattern) => matchesFamily(pattern, name)))),
+            families: [...new Set(present.map((entry) => entry.orm.label))],
+        };
+    return {
+        directory,
+        manifest,
+        manifestText,
+        moduleKind: manifest.type === "module" ? "esm" : "cjs",
+        lockfile: known.length === 1 ? known[0] : undefined,
+        orm,
+        usesNestConfig: dependencyRange(manifest, "@nestjs/config") !== undefined,
+    };
+}

package/dist/project/service.detector.d.ts

@@ -0,0 +1,45 @@
+/**
+ * R6 — finding the developer's own ORM service, lexically, over `src/**\/*.ts`:
+ * no compiler (`aventara init` may run before anything is installed).
+ *
+ * 1. **Candidates**: exported classes that `extends` the ORM's client class,
+ *    where the file imports that class from a specifier the ORM's templates
+ *    recognise (the generated client, or the ORM package).
+ * 2. **Compositions**: exported classes that hold a client instead of extending
+ *    one (`client = new PrismaClient(…)`, Phase 11 S7's shape) — reported with
+ *    the member, never wired.
+ * 3. **Modules**: each `@Module({…})`-decorated exported class with the
+ *    identifiers its `providers` and `exports` list, and whether it is `@Global()`.
+ *
+ * Which of them is *the* service is the caller's question (the wizard's).
+ */
+export type ExportReference = {
+    /** Relative to the project root, POSIX separators. */
+    readonly file: string;
+    readonly exportName: string;
+};
+export type ServiceComposition = ExportReference & {
+    /** The member that holds the client. */
+    readonly member: string;
+};
+export type ModuleDeclaration = ExportReference & {
+    readonly providers: readonly string[];
+    readonly exports: readonly string[];
+    readonly global: boolean;
+};
+export type ServiceScan = {
+    readonly candidates: readonly ExportReference[];
+    readonly compositions: readonly ServiceComposition[];
+    readonly modules: readonly ModuleDeclaration[];
+};
+export type ClientShape = {
+    /** The client class a service extends, e.g. the ORM's generated client. */
+    readonly clientClass: string;
+    /** Whether `specifier`, imported by `file` (project-relative), is the client's module. */
+    readonly importsClient: (specifier: string, file: string) => boolean;
+    /** Directories under `src/` that hold generated code, skipped. */
+    readonly skip: readonly string[];
+};
+export declare function scanServices(directory: string, shape: ClientShape): ServiceScan;
+/** The modules that make `service` injectable elsewhere: providing and exporting it, or global. */
+export declare function modulesProviding(scan: ServiceScan, service: ExportReference): readonly ModuleDeclaration[];

package/dist/project/service.detector.js

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { closing, codeIndexes, codeMask, nextCode, OPENERS, } from "./source.scanner.js";
+function sourceFiles(directory, root, skip) {
+    if (!existsSync(directory)) {
+        return [];
+    }
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const full = path.join(directory, entry.name);
+        const relative = path.relative(root, full).split(path.sep).join("/");
+        if (entry.isDirectory()) {
+            return entry.name === "node_modules" || skip.includes(relative)
+                ? []
+                : sourceFiles(full, root, skip);
+        }
+        return /\.ts$/.test(entry.name) && !/\.(spec|test|d)\.ts$/.test(entry.name)
+            ? [relative]
+            : [];
+    });
+}
+/** The identifiers the array under `key`, at `object`'s own level, names (`providers: [A, B]`). */
+function arrayNames(text, code, object, key) {
+    const end = closing(text, code, object);
+    let depth = 0;
+    for (let at = object + 1; at < end; at += 1) {
+        if (!code[at]) {
+            continue;
+        }
+        const char = text[at];
+        if (OPENERS[char] !== undefined) {
+            depth += 1;
+        }
+        else if (char === ")" || char === "]" || char === "}") {
+            depth -= 1;
+        }
+        else if (depth === 0 &&
+            text.startsWith(key, at) &&
+            !/[\w$]/.test(text[at - 1]) &&
+            /^\s*:/.test(text.slice(at + key.length))) {
+            const open = nextCode(text, code, text.indexOf(":", at) + 1);
+            if (text[open] !== "[") {
+                return [];
+            }
+            return text
+                .slice(open + 1, closing(text, code, open))
+                .split(",")
+                .map((item) => item.trim())
+                .filter((item) => /^[A-Za-z_$][\w$]*$/.test(item));
+        }
+    }
+    return [];
+}
+export function scanServices(directory, shape) {
+    const candidates = [];
+    const compositions = [];
+    const modules = [];
+    for (const file of sourceFiles(path.join(directory, "src"), directory, shape.skip)) {
+        const text = readFileSync(path.join(directory, file), "utf8");
+        const code = codeMask(text);
+        const importsClient = [
+            ...text.matchAll(new RegExp(`^import\\s*\\{[^}]*\\b${shape.clientClass}\\b[^}]*\\}\\s*from\\s*['"]([^'"]+)['"]`, "gm")),
+        ].some((match) => code[match.index] && shape.importsClient(match[1], file));
+        for (const match of text.matchAll(/^export\s+class\s+([A-Za-z_$][\w$]*)([^{]*)\{/gm)) {
+            if (!code[match.index]) {
+                continue;
+            }
+            const exportName = match[1];
+            const heritage = match[2];
+            if (importsClient &&
+                new RegExp(`\\bextends\\s+${shape.clientClass}\\b`).test(heritage)) {
+                candidates.push({ file, exportName });
+                continue;
+            }
+            const bodyStart = match.index + match[0].length - 1;
+            const body = text.slice(bodyStart, closing(text, code, bodyStart));
+            const held = new RegExp(`([A-Za-z_$][\\w$]*)\\s*(?::\\s*${shape.clientClass}\\b[^=;]*)?=\\s*new\\s+${shape.clientClass}\\s*\\(`).exec(body);
+            if (importsClient && held !== null) {
+                compositions.push({ file, exportName, member: held[1] });
+            }
+        }
+        for (const decorator of codeIndexes(text, code, /@Module\s*\(/g)) {
+            const open = text.indexOf("(", decorator);
+            const object = nextCode(text, code, open + 1);
+            const close = closing(text, code, open);
+            const declared = /^\s*(?:@[\w$.]+\([^)]*\)\s*)*export\s+class\s+([A-Za-z_$][\w$]*)/.exec(text.slice(close + 1));
+            if (text[object] !== "{" || declared === null) {
+                continue;
+            }
+            const before = text.slice(Math.max(0, decorator - 200), decorator);
+            modules.push({
+                file,
+                exportName: declared[1],
+                providers: arrayNames(text, code, object, "providers"),
+                exports: arrayNames(text, code, object, "exports"),
+                global: /@Global\s*\(\s*\)\s*$/.test(before) ||
+                    /^\s*@Global\s*\(\s*\)/.test(text.slice(close + 1)),
+            });
+        }
+    }
+    return { candidates, compositions, modules };
+}
+/** The modules that make `service` injectable elsewhere: providing and exporting it, or global. */
+export function modulesProviding(scan, service) {
+    return scan.modules.filter((module) => module.providers.includes(service.exportName) &&
+        (module.exports.includes(service.exportName) || module.global));
+}

package/dist/project/source.scanner.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A lexical view of TypeScript source — enough to find decorators, classes,
+ * imports and brackets **in code**, never inside a comment, a string or a
+ * template literal's text — with no compiler: `aventara new` runs before
+ * anything (TypeScript included) is installed in the project, and the CLI
+ * carries no TypeScript of its own. Shared by the anchored `app.module.ts` edit
+ * and the detection of a developer's ORM service.
+ */
+/** For each character: is it code (not inside a comment, string or template text)? */
+export declare function codeMask(text: string): boolean[];
+/** Every index where `token` starts in code. */
+export declare function codeIndexes(text: string, code: boolean[], token: RegExp): number[];
+export declare const OPENERS: Readonly<Record<string, string>>;
+/** The index of the bracket closing the one at `open`, counting code brackets only. */
+export declare function closing(text: string, code: boolean[], open: number): number;
+export declare function nextCode(text: string, code: boolean[], from: number): number;