@saasicat/cli 1.0.0-rc.1 → 1.0.0-rc.10

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
 import { UserPort, PlatformUserDto, AuditQueryPort, AuditEntry, AdminManifest, ManifestAccessPort, PlanCatalog, UserManagementPort } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
+import * as TypeScript from 'typescript';
 import { CommandRunner } from 'nest-commander';
 
 declare const CLI_CONTEXT_CONFIG_TOKEN: unique symbol;
@@ -381,19 +382,41 @@ declare function extractModelNames(schema: string): string[];
  * `name -> complete block text incl. opening/closing braces`.
  */
 declare function extractModelBlocks(fragment: string): Map<string, string>;
+/** Returns all `enum X { ... }` blocks from a fragment, keyed by name. */
+declare function extractEnumBlocks(fragment: string): Map<string, string>;
+/** Names of all top-level `enum X { ... }` blocks in the schema. */
+declare function extractEnumNames(schema: string): string[];
+/**
+ * What a fragment contributes: its enums and its models. Both travel
+ * together, because a model's `BillingCycle` field is a validation error in
+ * a schema that has the model and not the enum — which is what `apply` used
+ * to produce for every consumer whose schema did not already carry the enums
+ * by hand, and what the example app masked by carrying them.
+ */
+interface FragmentBlocks {
+    enums: Map<string, string>;
+    models: Map<string, string>;
+}
+declare function extractFragmentBlocks(fragment: string): FragmentBlocks;
 interface ApplyResult {
-    /** Number of models that were added. */
+    /** Models that were added. */
     added: string[];
-    /** Number of models that were already present (no write). */
+    /** Models that were already present (no write). */
     skipped: string[];
-    /** Resulting schema text. When `added.length === 0` identical to the input. */
+    /** Enums that were added, before the models that use them. */
+    addedEnums: string[];
+    /** Enums that were already present (no write). */
+    skippedEnums: string[];
+    /** Resulting schema text. When nothing was added, identical to the input. */
     schema: string;
 }
 /**
- * Appends missing models from `fragmentBlocks` to the end of `schema`. Existing
- * models (same name) stay unchanged and are listed in `skipped`.
+ * Appends missing enums and models from `fragmentBlocks` to the end of
+ * `schema`. Existing blocks (same name) stay unchanged and are listed as
+ * skipped. A plain map of models is accepted for the callers that only ever
+ * had models; the enums are then `[]`, which is what they were before.
  */
-declare function applyFragmentBlocks(schema: string, fragmentBlocks: Map<string, string>, options?: {
+declare function applyFragmentBlocks(schema: string, fragmentBlocks: FragmentBlocks | Map<string, string>, options?: {
     fragmentLabel?: string;
 }): ApplyResult;
 
@@ -696,9 +719,9 @@ declare function assertModelsExist(declaredModels: readonly string[], models: Fk
 
 /** What the caller asked for. */
 interface InitOptions {
-    /** The catalogue this app administers. Also the storage-key prefix. */
-    projectKey: string;
-    /** Human name in the manifest and the YAML. Defaults to `projectKey`. */
+    /** Slug of the application: npm package name, storage-key prefix, id prefix. */
+    appKey: string;
+    /** Human name in the manifest and the YAML. Defaults to `appKey`. */
     appName?: string;
     /** Admin API prefix, e.g. `/api/v1/admin`. */
     apiBase?: string;
@@ -804,8 +827,34 @@ interface PatchOptionsFromPlan {
     };
 }
 
-/** The pattern `plan-catalog.schema.json` puts on `projectKey`. */
-declare function projectKeyPattern(): RegExp;
+interface ModuleResolutionVerdict {
+    readonly ok: boolean;
+    /** The effective setting, lower-cased as TypeScript names it, or null when unset. */
+    readonly value: string | null;
+    readonly reason?: string;
+}
+/**
+ * Judges an effective `moduleResolution`, as `readEffectiveModuleResolution`
+ * reports it.
+ *
+ * Unset is `ok`: TypeScript then derives it from `module`, and a `module`
+ * that implies the old resolution is a setup this cannot see from here —
+ * the next build says so, with TypeScript's own message.
+ */
+declare function judgeModuleResolution(value: string | null): ModuleResolutionVerdict;
+/**
+ * The `moduleResolution` a project's `tsconfig.json` resolves to, after
+ * `extends`, lower-cased as TypeScript names the kind (`node10`, `node16`,
+ * `nodenext`, `bundler`, `classic`) — or null when there is no config, the
+ * config cannot be parsed, or the option is not set anywhere in the chain.
+ *
+ * `ts` is whichever TypeScript will compile the project: the consumer's own
+ * when it can be resolved from the project root, so the reading matches the
+ * build that follows.
+ */
+declare function readEffectiveModuleResolution(root: string, ts: typeof TypeScript): string | null;
+
+declare function appKeyPattern(): RegExp;
 /** The pattern it puts on the keys inside a plan's `quotas` object. */
 declare function quotaKeyPattern(): RegExp;
 /** How many quotas a plan must declare — 1 today, and read rather than assumed. */
@@ -816,10 +865,25 @@ declare function minimumQuotasPerPlan(): number;
  * The message carries the pattern rather than a prose paraphrase, because the
  * paraphrase is what goes stale.
  */
-declare function assertValidProjectKey(projectKey: string): void;
+declare function assertValidAppKey(appKey: string): void;
 /** The same, for a quota key. `additionalProperties: false` makes it a hard rule. */
 declare function assertValidQuotaKey(quotaKey: string): void;
 
+interface WrittenSetting {
+    /** Dotted path as it reads in the file, e.g. `tenantBilling.cancellationNoticeDays.monthly`. */
+    key: string;
+    /** The value as JSON — `0`, `[]`, `"EUR"` — so an empty list is visible as one. */
+    value: string;
+}
+/**
+ * The settings a generated `config/saas.yaml` carries.
+ *
+ * Loaded with the platform's own loader, not a YAML parse: a document `init`
+ * writes that the platform would refuse is a bug worth failing the generation
+ * for, rather than one the first boot reports after every file exists.
+ */
+declare function settingsWrittenTo(catalogYaml: string, source?: string): WrittenSetting[];
+
 /** One entry of the move table: where a file was, and where it went. */
 interface MoveTable {
     readonly moves: Readonly<Record<string, string>>;
@@ -931,6 +995,147 @@ interface ManifestRewriteOptions {
 }
 declare function rewriteManifest(text: string, table: RenameTable, options: ManifestRewriteOptions): RenameResult;
 
+interface ProjectKeyResult {
+    readonly text: string;
+    /** How many occurrences were taken out. */
+    readonly rewritten: number;
+    /**
+     * 1-based line numbers of the occurrences left in place.
+     *
+     * Reported rather than removed: the codemod could not tell them from a
+     * consumer's own field, and a wrong deletion is worse than a named one.
+     */
+    readonly undecided: readonly number[];
+}
+/**
+ * Rewrites one source file.
+ *
+ * `yaml` switches to the config form: there the field is a top-level key in a
+ * file the platform owns the schema of, so it is decidable without an anchor.
+ */
+declare function removeProjectKey(text: string, kind?: 'source' | 'yaml'): ProjectKeyResult;
+
+/**
+ * The settings that belong in `config/saas.yaml#tenantBilling`, read off the
+ * schema that defines them.
+ *
+ * Not a list here, and not a copy of the one in `@saasicat/nest`: both derive
+ * from the same schema, so the day a third setting moves into that block, this
+ * codemod names it and the module refuses it without either being edited.
+ */
+declare const SETTINGS_THAT_MOVED: readonly string[];
+type MovedSetting = string;
+interface MovedSettingOccurrence {
+    /** Which setting it is, so the report can say where it goes. */
+    readonly setting: MovedSetting;
+    /** 1-based line number. */
+    readonly line: number;
+}
+interface MovedSettingsResult {
+    readonly occurrences: readonly MovedSettingOccurrence[];
+}
+/**
+ * Files a moved setting can actually be passed in.
+ *
+ * The codemod walk includes Markdown, and both consumers keep large
+ * documentation folders — an upgrade note that mentions `cancellationNoticeDays`
+ * would land in the report beside the line somebody has to change, and a report
+ * that mixes the two is one nobody reads twice. Prose cannot pass a module
+ * option, so prose is not scanned.
+ */
+declare const SCANNED_FOR_MOVED_SETTINGS: RegExp;
+/**
+ * Every occurrence of a moved setting in one source file.
+ *
+ * Matched on word boundaries alone: a longer name that contains it
+ * (`cancellationNoticeDaysV2`) is not reported, and everything else is —
+ * including a mention in a comment or a string.
+ *
+ * That last part is deliberate, and it is the opposite trade from the one this
+ * comment used to claim. Requiring a colon would read as "only a property",
+ * and it would then miss `{ cancellationNoticeDays }` and
+ * `const { cancellationNoticeDays } = options` — two ordinary ways to pass the
+ * same option. Telling a comment from code needs the grammar, which this does
+ * not have. So it over-reports inside code, where the cost is a glance, rather
+ * than under-reporting, where the cost is somebody not learning that their
+ * value is about to stop being read.
+ *
+ * A property access (`config.cancellationNoticeDays`) is reported too: reading
+ * the value back from module options is the same migration, one step further
+ * along.
+ */
+declare function findMovedSettings(text: string): MovedSettingsResult;
+/**
+ * Where a setting goes, for the report.
+ *
+ * One sentence per setting rather than one for both: they end up in the same
+ * block and mean different things, and "move these two to the file" is the
+ * instruction people follow halfway.
+ */
+declare const WHERE_IT_GOES: Record<string, string>;
+
+/** Which files a `dbCatalog` can be passed in: code, not prose. */
+declare const SCANNED_FOR_DB_CATALOG: RegExp;
+type DbCatalogShape = 'values' | 'mixed' | 'reference';
+interface DbCatalogOccurrence {
+    /** 1-based line of the `dbCatalog:` property. */
+    readonly line: number;
+    /**
+     * `values` — an object literal with no `path`: the old shape whole.
+     * `mixed` — a `path` with something beside it that the option does not
+     * take: an upgrade that stopped halfway, and the platform refuses it too.
+     * `reference` — anything else on the right of the colon: a variable, a
+     * call, a spread. This cannot see what it carries, so it is named for a
+     * person to look at rather than passed over.
+     */
+    readonly shape: DbCatalogShape;
+    /**
+     * The members that are not what the option takes — every one of a
+     * `values` block, the ones left beside the path of a `mixed` one, and
+     * nothing for a `reference`. A spread is listed as `...name`, because
+     * what it carries is decided elsewhere.
+     */
+    readonly leftovers: readonly string[];
+}
+interface DbCatalogResult {
+    readonly occurrences: readonly DbCatalogOccurrence[];
+}
+/**
+ * Every `dbCatalog:` property in one source file, with what stands to its right.
+ *
+ * A property in code, which means the name followed by a colon, outside any
+ * comment or string. The other codemod in this family reports every
+ * word-boundary mention of a setting, including one in a comment, on the
+ * reasoning that over-reporting inside code costs a glance. That reasoning
+ * does not carry here: `saasicat init` writes the sentence "pass `dbCatalog`
+ * instead" into every generated `app.module.ts`, so a mention is the normal
+ * case and a report of it would be noise on every upgrade — and a block
+ * commented out, or quoted as a sample, is migration work that does not
+ * exist. An OPTIONAL type member (`dbCatalog?:`) is not a property either: the
+ * `?` stands where the colon would. A required one (`dbCatalog: DbCatalogOptions`)
+ * is the same tokens as a value passed in from elsewhere, and is reported as a
+ * `reference` for that reason — a glance, which is what `reference` is for. A
+ * shorthand `{ dbCatalog }` is not seen — the value it carries is elsewhere,
+ * and the module's refusal names it at boot.
+ *
+ * What counts as migrated is read off `DB_CATALOG_MEMBERS`, the list the
+ * platform's own refusal reads, so the two cannot disagree about a block.
+ */
+declare function findDbCatalogBlocks(text: string): DbCatalogResult;
+/**
+ * What is wrong with one occurrence, in the words the report uses.
+ *
+ * Beside the shapes rather than in the printer, because one of them has no
+ * leftovers to name: a `values` block whose only member is one the option
+ * takes — `dbCatalog: { env: process.env }` — or one emptied mid-edit is
+ * genuinely broken and genuinely refused at boot, but "carries the values:"
+ * with nothing after it names a file to go and look at without saying what to
+ * look for.
+ */
+declare function describeDbCatalogOccurrence(occurrence: Pick<DbCatalogOccurrence, 'shape' | 'leftovers'>): string;
+/** What to write instead, for the report. */
+declare const WHERE_DB_CATALOG_GOES: string;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1174,4 +1379,4 @@ declare class UserCommands extends CommandRunner {
     parsePassword(val: string): string;
 }
 
-export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type MoveTable, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidProjectKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractModelBlocks, extractModelNames, findFkPointers, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, projectKeyPattern, quotaKeyPattern, relationNameOf, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, stripLineComment, structuralOnly, tablesAddressedBy };
+export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, type DbCatalogOccurrence, type DbCatalogResult, type DbCatalogShape, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, type MovedSetting, type MovedSettingOccurrence, type MovedSettingsResult, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, SCANNED_FOR_DB_CATALOG, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_DB_CATALOG_GOES, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, describeDbCatalogOccurrence, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findDbCatalogBlocks, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, settingsWrittenTo, stripLineComment, structuralOnly, tablesAddressedBy };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { MfaService, AdminAuditService, AdminManifestService, DiscoverySnapshot, ProviderSpec, DiscoveryScanner } from '@saasicat/nest';
 import { UserPort, PlatformUserDto, AuditQueryPort, AuditEntry, AdminManifest, ManifestAccessPort, PlanCatalog, UserManagementPort } from '@saasicat/core';
 import { Type, DynamicModule } from '@nestjs/common';
+import * as TypeScript from 'typescript';
 import { CommandRunner } from 'nest-commander';
 
 declare const CLI_CONTEXT_CONFIG_TOKEN: unique symbol;
@@ -381,19 +382,41 @@ declare function extractModelNames(schema: string): string[];
  * `name -> complete block text incl. opening/closing braces`.
  */
 declare function extractModelBlocks(fragment: string): Map<string, string>;
+/** Returns all `enum X { ... }` blocks from a fragment, keyed by name. */
+declare function extractEnumBlocks(fragment: string): Map<string, string>;
+/** Names of all top-level `enum X { ... }` blocks in the schema. */
+declare function extractEnumNames(schema: string): string[];
+/**
+ * What a fragment contributes: its enums and its models. Both travel
+ * together, because a model's `BillingCycle` field is a validation error in
+ * a schema that has the model and not the enum — which is what `apply` used
+ * to produce for every consumer whose schema did not already carry the enums
+ * by hand, and what the example app masked by carrying them.
+ */
+interface FragmentBlocks {
+    enums: Map<string, string>;
+    models: Map<string, string>;
+}
+declare function extractFragmentBlocks(fragment: string): FragmentBlocks;
 interface ApplyResult {
-    /** Number of models that were added. */
+    /** Models that were added. */
     added: string[];
-    /** Number of models that were already present (no write). */
+    /** Models that were already present (no write). */
     skipped: string[];
-    /** Resulting schema text. When `added.length === 0` identical to the input. */
+    /** Enums that were added, before the models that use them. */
+    addedEnums: string[];
+    /** Enums that were already present (no write). */
+    skippedEnums: string[];
+    /** Resulting schema text. When nothing was added, identical to the input. */
     schema: string;
 }
 /**
- * Appends missing models from `fragmentBlocks` to the end of `schema`. Existing
- * models (same name) stay unchanged and are listed in `skipped`.
+ * Appends missing enums and models from `fragmentBlocks` to the end of
+ * `schema`. Existing blocks (same name) stay unchanged and are listed as
+ * skipped. A plain map of models is accepted for the callers that only ever
+ * had models; the enums are then `[]`, which is what they were before.
  */
-declare function applyFragmentBlocks(schema: string, fragmentBlocks: Map<string, string>, options?: {
+declare function applyFragmentBlocks(schema: string, fragmentBlocks: FragmentBlocks | Map<string, string>, options?: {
     fragmentLabel?: string;
 }): ApplyResult;
 
@@ -696,9 +719,9 @@ declare function assertModelsExist(declaredModels: readonly string[], models: Fk
 
 /** What the caller asked for. */
 interface InitOptions {
-    /** The catalogue this app administers. Also the storage-key prefix. */
-    projectKey: string;
-    /** Human name in the manifest and the YAML. Defaults to `projectKey`. */
+    /** Slug of the application: npm package name, storage-key prefix, id prefix. */
+    appKey: string;
+    /** Human name in the manifest and the YAML. Defaults to `appKey`. */
     appName?: string;
     /** Admin API prefix, e.g. `/api/v1/admin`. */
     apiBase?: string;
@@ -804,8 +827,34 @@ interface PatchOptionsFromPlan {
     };
 }
 
-/** The pattern `plan-catalog.schema.json` puts on `projectKey`. */
-declare function projectKeyPattern(): RegExp;
+interface ModuleResolutionVerdict {
+    readonly ok: boolean;
+    /** The effective setting, lower-cased as TypeScript names it, or null when unset. */
+    readonly value: string | null;
+    readonly reason?: string;
+}
+/**
+ * Judges an effective `moduleResolution`, as `readEffectiveModuleResolution`
+ * reports it.
+ *
+ * Unset is `ok`: TypeScript then derives it from `module`, and a `module`
+ * that implies the old resolution is a setup this cannot see from here —
+ * the next build says so, with TypeScript's own message.
+ */
+declare function judgeModuleResolution(value: string | null): ModuleResolutionVerdict;
+/**
+ * The `moduleResolution` a project's `tsconfig.json` resolves to, after
+ * `extends`, lower-cased as TypeScript names the kind (`node10`, `node16`,
+ * `nodenext`, `bundler`, `classic`) — or null when there is no config, the
+ * config cannot be parsed, or the option is not set anywhere in the chain.
+ *
+ * `ts` is whichever TypeScript will compile the project: the consumer's own
+ * when it can be resolved from the project root, so the reading matches the
+ * build that follows.
+ */
+declare function readEffectiveModuleResolution(root: string, ts: typeof TypeScript): string | null;
+
+declare function appKeyPattern(): RegExp;
 /** The pattern it puts on the keys inside a plan's `quotas` object. */
 declare function quotaKeyPattern(): RegExp;
 /** How many quotas a plan must declare — 1 today, and read rather than assumed. */
@@ -816,10 +865,25 @@ declare function minimumQuotasPerPlan(): number;
  * The message carries the pattern rather than a prose paraphrase, because the
  * paraphrase is what goes stale.
  */
-declare function assertValidProjectKey(projectKey: string): void;
+declare function assertValidAppKey(appKey: string): void;
 /** The same, for a quota key. `additionalProperties: false` makes it a hard rule. */
 declare function assertValidQuotaKey(quotaKey: string): void;
 
+interface WrittenSetting {
+    /** Dotted path as it reads in the file, e.g. `tenantBilling.cancellationNoticeDays.monthly`. */
+    key: string;
+    /** The value as JSON — `0`, `[]`, `"EUR"` — so an empty list is visible as one. */
+    value: string;
+}
+/**
+ * The settings a generated `config/saas.yaml` carries.
+ *
+ * Loaded with the platform's own loader, not a YAML parse: a document `init`
+ * writes that the platform would refuse is a bug worth failing the generation
+ * for, rather than one the first boot reports after every file exists.
+ */
+declare function settingsWrittenTo(catalogYaml: string, source?: string): WrittenSetting[];
+
 /** One entry of the move table: where a file was, and where it went. */
 interface MoveTable {
     readonly moves: Readonly<Record<string, string>>;
@@ -931,6 +995,147 @@ interface ManifestRewriteOptions {
 }
 declare function rewriteManifest(text: string, table: RenameTable, options: ManifestRewriteOptions): RenameResult;
 
+interface ProjectKeyResult {
+    readonly text: string;
+    /** How many occurrences were taken out. */
+    readonly rewritten: number;
+    /**
+     * 1-based line numbers of the occurrences left in place.
+     *
+     * Reported rather than removed: the codemod could not tell them from a
+     * consumer's own field, and a wrong deletion is worse than a named one.
+     */
+    readonly undecided: readonly number[];
+}
+/**
+ * Rewrites one source file.
+ *
+ * `yaml` switches to the config form: there the field is a top-level key in a
+ * file the platform owns the schema of, so it is decidable without an anchor.
+ */
+declare function removeProjectKey(text: string, kind?: 'source' | 'yaml'): ProjectKeyResult;
+
+/**
+ * The settings that belong in `config/saas.yaml#tenantBilling`, read off the
+ * schema that defines them.
+ *
+ * Not a list here, and not a copy of the one in `@saasicat/nest`: both derive
+ * from the same schema, so the day a third setting moves into that block, this
+ * codemod names it and the module refuses it without either being edited.
+ */
+declare const SETTINGS_THAT_MOVED: readonly string[];
+type MovedSetting = string;
+interface MovedSettingOccurrence {
+    /** Which setting it is, so the report can say where it goes. */
+    readonly setting: MovedSetting;
+    /** 1-based line number. */
+    readonly line: number;
+}
+interface MovedSettingsResult {
+    readonly occurrences: readonly MovedSettingOccurrence[];
+}
+/**
+ * Files a moved setting can actually be passed in.
+ *
+ * The codemod walk includes Markdown, and both consumers keep large
+ * documentation folders — an upgrade note that mentions `cancellationNoticeDays`
+ * would land in the report beside the line somebody has to change, and a report
+ * that mixes the two is one nobody reads twice. Prose cannot pass a module
+ * option, so prose is not scanned.
+ */
+declare const SCANNED_FOR_MOVED_SETTINGS: RegExp;
+/**
+ * Every occurrence of a moved setting in one source file.
+ *
+ * Matched on word boundaries alone: a longer name that contains it
+ * (`cancellationNoticeDaysV2`) is not reported, and everything else is —
+ * including a mention in a comment or a string.
+ *
+ * That last part is deliberate, and it is the opposite trade from the one this
+ * comment used to claim. Requiring a colon would read as "only a property",
+ * and it would then miss `{ cancellationNoticeDays }` and
+ * `const { cancellationNoticeDays } = options` — two ordinary ways to pass the
+ * same option. Telling a comment from code needs the grammar, which this does
+ * not have. So it over-reports inside code, where the cost is a glance, rather
+ * than under-reporting, where the cost is somebody not learning that their
+ * value is about to stop being read.
+ *
+ * A property access (`config.cancellationNoticeDays`) is reported too: reading
+ * the value back from module options is the same migration, one step further
+ * along.
+ */
+declare function findMovedSettings(text: string): MovedSettingsResult;
+/**
+ * Where a setting goes, for the report.
+ *
+ * One sentence per setting rather than one for both: they end up in the same
+ * block and mean different things, and "move these two to the file" is the
+ * instruction people follow halfway.
+ */
+declare const WHERE_IT_GOES: Record<string, string>;
+
+/** Which files a `dbCatalog` can be passed in: code, not prose. */
+declare const SCANNED_FOR_DB_CATALOG: RegExp;
+type DbCatalogShape = 'values' | 'mixed' | 'reference';
+interface DbCatalogOccurrence {
+    /** 1-based line of the `dbCatalog:` property. */
+    readonly line: number;
+    /**
+     * `values` — an object literal with no `path`: the old shape whole.
+     * `mixed` — a `path` with something beside it that the option does not
+     * take: an upgrade that stopped halfway, and the platform refuses it too.
+     * `reference` — anything else on the right of the colon: a variable, a
+     * call, a spread. This cannot see what it carries, so it is named for a
+     * person to look at rather than passed over.
+     */
+    readonly shape: DbCatalogShape;
+    /**
+     * The members that are not what the option takes — every one of a
+     * `values` block, the ones left beside the path of a `mixed` one, and
+     * nothing for a `reference`. A spread is listed as `...name`, because
+     * what it carries is decided elsewhere.
+     */
+    readonly leftovers: readonly string[];
+}
+interface DbCatalogResult {
+    readonly occurrences: readonly DbCatalogOccurrence[];
+}
+/**
+ * Every `dbCatalog:` property in one source file, with what stands to its right.
+ *
+ * A property in code, which means the name followed by a colon, outside any
+ * comment or string. The other codemod in this family reports every
+ * word-boundary mention of a setting, including one in a comment, on the
+ * reasoning that over-reporting inside code costs a glance. That reasoning
+ * does not carry here: `saasicat init` writes the sentence "pass `dbCatalog`
+ * instead" into every generated `app.module.ts`, so a mention is the normal
+ * case and a report of it would be noise on every upgrade — and a block
+ * commented out, or quoted as a sample, is migration work that does not
+ * exist. An OPTIONAL type member (`dbCatalog?:`) is not a property either: the
+ * `?` stands where the colon would. A required one (`dbCatalog: DbCatalogOptions`)
+ * is the same tokens as a value passed in from elsewhere, and is reported as a
+ * `reference` for that reason — a glance, which is what `reference` is for. A
+ * shorthand `{ dbCatalog }` is not seen — the value it carries is elsewhere,
+ * and the module's refusal names it at boot.
+ *
+ * What counts as migrated is read off `DB_CATALOG_MEMBERS`, the list the
+ * platform's own refusal reads, so the two cannot disagree about a block.
+ */
+declare function findDbCatalogBlocks(text: string): DbCatalogResult;
+/**
+ * What is wrong with one occurrence, in the words the report uses.
+ *
+ * Beside the shapes rather than in the printer, because one of them has no
+ * leftovers to name: a `values` block whose only member is one the option
+ * takes — `dbCatalog: { env: process.env }` — or one emptied mid-edit is
+ * genuinely broken and genuinely refused at boot, but "carries the values:"
+ * with nothing after it names a file to go and look at without saying what to
+ * look for.
+ */
+declare function describeDbCatalogOccurrence(occurrence: Pick<DbCatalogOccurrence, 'shape' | 'leftovers'>): string;
+/** What to write instead, for the report. */
+declare const WHERE_DB_CATALOG_GOES: string;
+
 interface PatchAppModuleOptions {
     /** Import specifier for the persistence bundle, or null when not generated. */
     persistenceImport: string | null;
@@ -1174,4 +1379,4 @@ declare class UserCommands extends CommandRunner {
     parsePassword(val: string): string;
 }
 
-export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type MoveTable, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WhoAmIFlow, type WhoAmIResult, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidProjectKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, enableFkPointers, extractBlockNames, extractBlocks, extractModelBlocks, extractModelNames, findFkPointers, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, projectKeyPattern, quotaKeyPattern, relationNameOf, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, stripLineComment, structuralOnly, tablesAddressedBy };
+export { AUDIT_QUERY_PORT_TOKEN, AdminCommands, AdminManifestDoctorCheck, AdminMfaSetupCommand, AdminWhoamiCommand, type ApplyResult, AuditCommands, AuditTailCommand, AuditTailFlow, type AuditTailOptions, type BlockAttributeKind, type BlockAttributes, CLI_CONTEXT_CONFIG_TOKEN, CONSTRAINTS_MARKER, type CheckSeverity, type CliContextConfig, CliContextModule, type CliContextModuleOptions, CliContextService, CliError, type CliIdentity, type ConstraintsOutcome, type ConstraintsReport, DEFAULT_MANIFEST_CHECKS, DOCTOR_CHECKS_TOKEN, type DbCatalogOccurrence, type DbCatalogResult, type DbCatalogShape, DiscoveryCommands, DiscoveryScanCommand, DiscoverySnapshotDoctorCheck, type DoctorCheck, type DoctorCheckResult, DoctorCommands, DoctorFlow, type DoctorReport, type EnableFkResult, type FieldMismatch, type FieldMismatchReason, type FieldSignature, type FkModelNames, type FkPointer, type FragmentBlocks, type InitOptions, type InitPlan, LIMIT_FILTER_IMPORTS, LIMIT_FILTER_PROVIDER, MANIFEST_ACCESS_PORT_TOKEN, MANIFEST_CHECKS_TOKEN, type ManifestCheck, ManifestCheckCommand, type ManifestCheckReport, type ManifestCheckResult, ManifestCliFlow, ManifestCommands, type ManifestDiff, ManifestDumpCommand, ManifestHashCommand, type ManifestRewriteOptions, ManifestValidateCommand, MfaSetupFlow, type MfaSetupOptions, type MfaSetupResult, type MissingBlockAttribute, type MissingEnumValue, type MissingField, type ModuleResolutionVerdict, type MoveTable, type MovedSetting, type MovedSettingOccurrence, type MovedSettingsResult, PLATFORM_DOCTOR_CHECK_PROVIDERS, type ParsedSchema, type PatchAppModuleOptions, type PatchOptionsFromPlan, type PatchResult, PlanCatalogDoctorCheck, type PlannedFile, type ProjectKeyResult, type QuotaProviderFile, type QuotaSpec, type RenameResult, type RenameTable, type RewriteResult, SCANNED_FOR_DB_CATALOG, SCANNED_FOR_MOVED_SETTINGS, SETTINGS_THAT_MOVED, type SchemaCheckReport, UI_VUE_SPECIFIER, USER_MANAGEMENT_PORT_TOKEN, USER_PORT_TOKEN, UserCommands, UserPortDoctorCheck, WHERE_DB_CATALOG_GOES, WHERE_IT_GOES, WhoAmIFlow, type WhoAmIResult, type WrittenSetting, appKeyPattern, appendConstraints, applyFragmentBlocks, applyTokens, assertModelsExist, assertValidAppKey, assertValidQuotaKey, blankStringLiterals, blockBodyLines, breaksContract, buildImportMap, checkSchema, constraintsFor, describeDbCatalogOccurrence, enableFkPointers, extractBlockNames, extractBlocks, extractEnumBlocks, extractEnumNames, extractFragmentBlocks, extractModelBlocks, extractModelNames, findDbCatalogBlocks, findFkPointers, findMovedSettings, foreignKeyOf, hasBackRelation, hasConstraints, isNoLongerPublic, isOneToOne, judgeModuleResolution, kebabCase, migrationCreatedBy, minimumQuotasPerPlan, namedImports, parseBlockAttributes, parseEnumValues, parseFields, parseQuota, parseSchema, pascalCase, patchAppModule, patchOptionsFor, planInit, quotaKeyPattern, readEffectiveModuleResolution, relationNameOf, removeProjectKey, reportConstraints, rewriteImports, rewriteManifest, rewriteNames, rewriteSubpath, settingsWrittenTo, stripLineComment, structuralOnly, tablesAddressedBy };