@forinda/kickjs-cli 3.2.0 → 4.1.0

package/dist/{typegen-C30frihW.mjs → typegen-C-H8pg-y.mjs}

@@ -1,5 +1,5 @@
 /**
- * @forinda/kickjs-cli v3.2.0
+ * @forinda/kickjs-cli v4.1.0
  *
  * Copyright (c) Felix Orinda
  *
@@ -8,8 +8,10 @@
  *
  * @license MIT
  */
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, extname, join, relative, resolve, sep } from "node:path";
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { statSync } from "node:fs";
+import { globSync } from "glob";
 //#region src/typegen/scanner.ts
 /** Decorators that mark a class as DI-managed */
 const DECORATOR_NAMES = [
@@ -64,6 +66,28 @@ const BARE_CREATE_TOKEN_REGEX = /createToken\s*(?:<[^>]*>)?\s*\(\s*['"`]([^'"`]+
 /** Match `@Inject('literal')` — only literals; computed args are skipped */
 const INJECT_LITERAL_REGEX = /@Inject\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g;
 /**
+* Match the start of a `defineAdapter(...)` or `definePlugin(...)` call,
+* tolerating optional `<TConfig, TExtra>` generics. Captures the helper
+* name. The callsite's first-arg object is parsed forward via
+* `findBalancedClose` so nested objects/parens don't confuse us.
+*/
+const DEFINE_HELPER_START = /\b(defineAdapter|definePlugin)\s*(?:<[^>]*>)?\s*\(/g;
+/**
+* Match a class declaration whose `implements` clause includes `AppAdapter`.
+* Captures the class name. Used to pick up the (rare, post-defineAdapter)
+* legacy class-style adapters so their literal `name = '...'` field can
+* still feed `KickJsPluginRegistry`.
+*/
+const APP_ADAPTER_CLASS_REGEX = new RegExp(String.raw`export\s+(?:default\s+)?(?:abstract\s+)?class\s+(\w+)` + String.raw`(?:\s+extends\s+\w+(?:<[^>]*>)?)?` + String.raw`\s+implements\s+[^{]*\bAppAdapter\b`, "g");
+/** Match a string-literal `name = '...'` field on a class body. */
+const CLASS_NAME_FIELD_REGEX = /\bname\s*(?::\s*[^=]+)?=\s*['"`]([^'"`]+)['"`]/;
+/**
+* Match the start of a `defineAugmentation('Name', ...)` call. Captures
+* the literal name. The optional second-arg object is parsed forward so
+* `description` / `example` can be pulled out.
+*/
+const DEFINE_AUGMENTATION_START = /\bdefineAugmentation\s*\(\s*['"`]([^'"`]+)['"`]\s*(,\s*\{)?/g;
+/**
 * Locate the start of a route decorator: `@Get(`, `@Post(`, etc.
 * Used by `extractRoutesFromSource`; the rest of the route declaration
 * (balanced parens, stacked decorators, method name) is parsed by walking
@@ -410,6 +434,120 @@ function extractInjectsFromSource(source, filePath, cwd) {
 	return out;
 }
 /**
+* Extract the bounds of an object literal that begins at `openBracePos`
+* (the index of the `{` character). Returns the index of the matching `}`
+* or -1 if no match is found. Counts balanced braces only — does not
+* understand string literals so a `{` or `}` inside a string inside the
+* object will skew the depth counter (matches `findBalancedClose`).
+*/
+function findBalancedBrace(text, openBracePos) {
+	let depth = 1;
+	for (let i = openBracePos + 1; i < text.length; i++) {
+		const ch = text[i];
+		if (ch === "{") depth++;
+		else if (ch === "}") {
+			depth--;
+			if (depth === 0) return i;
+		}
+	}
+	return -1;
+}
+/**
+* Extract plugins/adapters declared via `defineAdapter({ name: '...' })`
+* or `definePlugin({ name: '...' })` calls and via class-style adapters
+* (`class XxxAdapter implements AppAdapter` with a string-literal `name`
+* field).
+*
+* Only the literal `name:` field feeds the result — the symbol on the LHS
+* is irrelevant since `dependsOn` references the runtime name.
+*/
+function extractPluginsAndAdaptersFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	const seen = /* @__PURE__ */ new Set();
+	DEFINE_HELPER_START.lastIndex = 0;
+	let helperMatch;
+	while ((helperMatch = DEFINE_HELPER_START.exec(source)) !== null) {
+		const helper = helperMatch[1];
+		const openParen = DEFINE_HELPER_START.lastIndex - 1;
+		const closeParen = findBalancedClose(source, openParen);
+		if (closeParen < 0) continue;
+		const callArgs = source.slice(openParen + 1, closeParen);
+		const nameMatch = /\bname\s*:\s*['"`]([^'"`]+)['"`]/.exec(callArgs);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `${helper}::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: helper === "definePlugin" ? "plugin" : "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	APP_ADAPTER_CLASS_REGEX.lastIndex = 0;
+	let classMatch;
+	while ((classMatch = APP_ADAPTER_CLASS_REGEX.exec(source)) !== null) {
+		const classStart = classMatch.index;
+		const bracePos = source.indexOf("{", classStart);
+		if (bracePos < 0) continue;
+		const closeBrace = findBalancedBrace(source, bracePos);
+		if (closeBrace < 0) continue;
+		const body = source.slice(bracePos + 1, closeBrace);
+		const nameMatch = CLASS_NAME_FIELD_REGEX.exec(body);
+		if (!nameMatch) continue;
+		const name = nameMatch[1];
+		const dedupeKey = `class::${name}::${filePath}`;
+		if (seen.has(dedupeKey)) continue;
+		seen.add(dedupeKey);
+		out.push({
+			kind: "adapter",
+			name,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
+* Extract `defineAugmentation('Name', { description, example })` calls
+* from a source file. The metadata object is optional — when absent both
+* `description` and `example` resolve to `null`.
+*/
+function extractAugmentationsFromSource(source, filePath, cwd) {
+	const out = [];
+	const relPath = toRelative(filePath, cwd);
+	DEFINE_AUGMENTATION_START.lastIndex = 0;
+	let match;
+	while ((match = DEFINE_AUGMENTATION_START.exec(source)) !== null) {
+		const name = match[1];
+		let description = null;
+		let example = null;
+		if (match[2]) {
+			const bracePos = source.indexOf("{", match.index + match[0].length - 1);
+			if (bracePos >= 0) {
+				const closeBrace = findBalancedBrace(source, bracePos);
+				if (closeBrace >= 0) {
+					const body = source.slice(bracePos + 1, closeBrace);
+					const descMatch = /\bdescription\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					const exampleMatch = /\bexample\s*:\s*['"`]([^'"`]+)['"`]/.exec(body);
+					description = descMatch ? descMatch[1] : null;
+					example = exampleMatch ? exampleMatch[1] : null;
+				}
+			}
+		}
+		out.push({
+			name,
+			description,
+			example,
+			filePath,
+			relativePath: relPath
+		});
+	}
+	return out;
+}
+/**
 * Default search order for the env schema file. Newer projects keep
 * the schema under `src/config/` so the framework's "config" concept
 * has a single home; older scaffolds dropped it at `src/env.ts` (kept
@@ -480,6 +618,8 @@ async function scanProject(opts) {
 	const routes = [];
 	const tokens = [];
 	const injects = [];
+	const pluginsAndAdapters = [];
+	const augmentations = [];
 	const sources = /* @__PURE__ */ new Map();
 	for (const file of files) {
 		let source;
@@ -492,6 +632,8 @@ async function scanProject(opts) {
 		classes.push(...extractClassesFromSource(source, file, opts.cwd));
 		tokens.push(...extractTokensFromSource(source, file, opts.cwd));
 		injects.push(...extractInjectsFromSource(source, file, opts.cwd));
+		pluginsAndAdapters.push(...extractPluginsAndAdaptersFromSource(source, file, opts.cwd));
+		augmentations.push(...extractAugmentationsFromSource(source, file, opts.cwd));
 	}
 	for (const [file, source] of sources) {
 		const classesInFile = classes.filter((c) => c.filePath === file);
@@ -504,16 +646,149 @@ async function scanProject(opts) {
 	tokens.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	injects.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	routes.sort((a, b) => a.controller.localeCompare(b.controller) || a.method.localeCompare(b.method));
+	pluginsAndAdapters.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
+	augmentations.sort((a, b) => a.name.localeCompare(b.name) || a.relativePath.localeCompare(b.relativePath));
 	return {
 		classes,
 		routes,
 		tokens,
 		injects,
 		collisions: findCollisions(classes),
-		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts")
+		env: await detectEnvFile(opts.cwd, opts.envFile ?? "src/env.ts"),
+		pluginsAndAdapters,
+		augmentations
 	};
 }
 //#endregion
+//#region src/typegen/asset-types.ts
+/**
+* Walks every `assetMap` entry's source directory + emits a typed
+* `KickAssets` ambient augmentation (assets-plan.md PR 4). Generates
+* `.kickjs/types/assets.d.ts` so adopters get autocomplete on
+* `assets.<namespace>.<key>` and `@Asset('<namespace>/<key>')`.
+*
+* Pure module — no side effects beyond what the caller does with the
+* returned content. Mirrors the shape of `renderPlugins` /
+* `renderRegistry` in the generator so the typegen output stays
+* consistent across surfaces.
+*
+* @module @forinda/kickjs-cli/typegen/asset-types
+*/
+function discoverAssets(assetMap, cwd) {
+	if (!assetMap) return {
+		entries: [],
+		count: 0
+	};
+	const seen = /* @__PURE__ */ new Map();
+	for (const [namespace, entry] of Object.entries(assetMap)) {
+		if (!entry || typeof entry.src !== "string") continue;
+		const srcAbs = resolve(cwd, entry.src);
+		if (!isDir(srcAbs)) continue;
+		const matches = globSync(entry.glob ?? "**/*", {
+			cwd: srcAbs,
+			nodir: true,
+			dot: false,
+			posix: true
+		});
+		matches.sort();
+		for (const rel of matches) {
+			const key = stripExt(rel);
+			const logical = `${namespace}/${key}`;
+			seen.set(logical, {
+				namespace,
+				key
+			});
+		}
+	}
+	return {
+		entries: [...seen.values()],
+		count: seen.size
+	};
+}
+function renderAssetTypes(discovered) {
+	const HEADER = `/* eslint-disable */
+// AUTO-GENERATED by \`kick typegen\`. DO NOT EDIT.
+// Re-run with \`kick typegen\` or rely on \`kick dev\` to refresh.
+`;
+	if (discovered.entries.length === 0) return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * (No assetMap entries discovered yet — declare with
+   *  \`assetMap: { name: { src: 'src/...' } }\` in kick.config.ts.)
+   */
+  interface KickAssets {}
+}
+
+export {}
+`;
+	const tree = {};
+	for (const entry of discovered.entries) {
+		const path = `${entry.namespace}/${entry.key}`.split("/");
+		let node = tree;
+		for (let i = 0; i < path.length - 1; i++) {
+			const part = path[i];
+			const existing = node[part];
+			if (existing === LEAF) {
+				const promoted = {};
+				node[part] = promoted;
+				node = promoted;
+			} else {
+				if (!existing) node[part] = {};
+				node = node[part];
+			}
+		}
+		const leaf = path[path.length - 1];
+		if (typeof node[leaf] === "object") continue;
+		node[leaf] = LEAF;
+	}
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every typed asset discovered in the project's assetMap.
+   * Each leaf is a \`() => string\` thunk that returns the resolved
+   * absolute path for the file in the current run mode (dev → src,
+   * prod → dist).
+   */
+  interface KickAssets {
+${renderTree(tree, "    ")}
+  }
+}
+
+export {}
+`;
+}
+const LEAF = Symbol("asset-leaf");
+function renderTree(node, indent) {
+	const keys = Object.keys(node).sort();
+	const lines = [];
+	for (const key of keys) {
+		const child = node[key];
+		const safeKey = isIdentifier(key) ? key : JSON.stringify(key);
+		if (child === LEAF) lines.push(`${indent}${safeKey}: () => string`);
+		else {
+			lines.push(`${indent}${safeKey}: {`);
+			lines.push(renderTree(child, `${indent}  `));
+			lines.push(`${indent}}`);
+		}
+	}
+	return lines.join("\n");
+}
+function isIdentifier(str) {
+	return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(str);
+}
+function isDir(path) {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+function stripExt(path) {
+	const ext = extname(path);
+	return ext ? path.slice(0, -ext.length) : path;
+}
+//#endregion
 //#region src/typegen/generator.ts
 /**
 * Generates `.d.ts` files inside `.kickjs/types/` from the discovered
@@ -649,12 +924,17 @@ function renderIndex(includeEnv) {
 export type { ServiceToken } from './services'
 export type { ModuleToken } from './modules'
 
-// The registry, routes, and env augmentations are loaded as side-effects —
-// importing this file (or having it on tsconfig include) is enough for
-// \`container.resolve()\`, \`Ctx<KickRoutes.UserController['getUser']>\`,
-// and \`@Value('PORT')\` to resolve.
+// The registry, routes, plugins, assets, and env augmentations are
+// loaded as side-effects — importing this file (or having it on
+// tsconfig include) is enough for \`container.resolve()\`,
+// \`Ctx<KickRoutes.UserController['getUser']>\`,
+// \`dependsOn: ['TenantAdapter']\`, \`assets.mails.welcome()\`, and
+// \`@Value('PORT')\` to resolve.
 import './registry'
 import './routes'
+import './plugins'
+import './augmentations'
+import './assets'
 ${includeEnv ? "import './env'\n" : ""}`;
 }
 /**
@@ -849,9 +1129,94 @@ ${interfaces.join("\n")}
 export {}
 `;
 }
+/**
+* Render the `KickJsPluginRegistry` augmentation. Each entry maps the
+* literal `name` field of a plugin/adapter to a marker type (the
+* registry value isn't load-bearing at runtime — `dependsOn` only cares
+* about `keyof`, so any non-`never` type works). We emit `'plugin'` /
+* `'adapter'` strings so DevTools can later read the registry to tell
+* the kinds apart without a second source of truth.
+*
+* When the project has no discoverable plugins/adapters, the augmentation
+* is intentionally empty rather than skipped so the `keyof` constraint
+* resolves to `never` (which is harmless — `dependsOn: []` still works).
+*/
+function renderPlugins(items) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const entries = [...byName.values()].sort((a, b) => a.name.localeCompare(b.name)).map((item) => `    '${item.name}': '${item.kind}'`).join("\n");
+	return `${HEADER}
+declare module '@forinda/kickjs' {
+  /**
+   * Map of every plugin/adapter \`name\` discovered in the project. The
+   * value type is the kind tag (\`'plugin'\` or \`'adapter'\`); the
+   * \`keyof\` of this interface narrows \`dependsOn\` so misspelled deps
+   * become compile errors instead of boot-time \`MissingMountDepError\`.
+   */
+  interface KickJsPluginRegistry {
+${entries ? entries : "    // (no plugins/adapters discovered yet — `defineAdapter`/`definePlugin` calls feed this)"}
+  }
+}
+
+export {}
+`;
+}
+/**
+* Render the augmentation manifest — one block per `defineAugmentation`
+* call discovered in the project. The output is a `.d.ts` file that
+* does nothing at runtime but acts as in-IDE documentation: adopters
+* jumping into it see every interface their plugins offer for
+* augmentation, alongside any `description` / `example` the plugin
+* authors provided.
+*/
+function renderAugmentations(items) {
+	if (items.length === 0) return `${HEADER}
+// No augmentations discovered.
+//
+// Plugins advertise augmentable interfaces via:
+//
+//   import { defineAugmentation } from '@forinda/kickjs'
+//   defineAugmentation('FeatureFlags', {
+//     description: 'Feature flag shape consumed by FlagsPlugin',
+//     example: '{ beta: boolean; rolloutPercentage: number }',
+//   })
+//
+// See \`docs/guide/typegen.md#augmentations\` for the full pattern.
+export {}
+`;
+	const byName = /* @__PURE__ */ new Map();
+	for (const item of items) if (!byName.has(item.name)) byName.set(item.name, item);
+	const blocks = [];
+	for (const item of [...byName.values()].sort((a, b) => a.name.localeCompare(b.name))) {
+		const docLines = [];
+		if (item.description) for (const line of item.description.split("\n")) docLines.push(` * ${line}`);
+		if (item.example) {
+			docLines.push(` * @example`, ` * \`\`\`ts`);
+			for (const line of item.example.split("\n")) docLines.push(` * ${line}`);
+			docLines.push(` * \`\`\``);
+		}
+		docLines.push(` * @see ${item.relativePath}`);
+		blocks.push([
+			"/**",
+			...docLines,
+			" */",
+			`export interface ${item.name}Augmentation {}`
+		].join("\n"));
+	}
+	return `${HEADER}
+// Catalogue of augmentable interfaces in this project. The interfaces
+// below are documentation only — augment the source-of-truth interfaces
+// in your own \`d.ts\` files (the framework declares the actual types).
+
+${blocks.join("\n\n")}
+`;
+}
 /** Write all generated `.d.ts` files to `outDir` */
 async function generateTypes(opts) {
-	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, outDir, allowDuplicates = false, schemaValidator = false } = opts;
+	const { classes, routes = [], tokens = [], injects = [], collisions = [], env = null, pluginsAndAdapters = [], augmentations = [], assets = {
+		entries: [],
+		count: 0
+	}, outDir, allowDuplicates = false, schemaValidator = false } = opts;
 	if (collisions.length > 0 && !allowDuplicates) throw new TokenCollisionError(collisions);
 	await mkdir(outDir, { recursive: true });
 	const registryFile = join(outDir, "registry.d.ts");
@@ -859,6 +1224,9 @@ async function generateTypes(opts) {
 	const modulesFile = join(outDir, "modules.d.ts");
 	const routesFile = join(outDir, "routes.ts");
 	const envFile = join(outDir, "env.ts");
+	const pluginsFile = join(outDir, "plugins.d.ts");
+	const augmentationsFile = join(outDir, "augmentations.d.ts");
+	const assetsFile = join(outDir, "assets.d.ts");
 	const indexFile = join(outDir, "index.d.ts");
 	const collidingNames = new Set(collisions.map((c) => c.className));
 	const registryContent = renderRegistry(classes, registryFile, collidingNames);
@@ -875,17 +1243,26 @@ async function generateTypes(opts) {
 	const modulesContent = renderUnion("ModuleToken", modules, "(no @Module classes discovered — `kick g module <name>` to add one)");
 	const routesContent = renderRoutes(routes, routesFile, schemaValidator);
 	const envContent = renderEnv(env, envFile);
+	const pluginsContent = renderPlugins(pluginsAndAdapters);
+	const augmentationsContent = renderAugmentations(augmentations);
+	const assetsContent = renderAssetTypes(assets);
 	const indexContent = renderIndex(envContent !== null);
 	await writeFile(registryFile, registryContent, "utf-8");
 	await writeFile(servicesFile, servicesContent, "utf-8");
 	await writeFile(modulesFile, modulesContent, "utf-8");
 	await writeFile(routesFile, routesContent, "utf-8");
+	await writeFile(pluginsFile, pluginsContent, "utf-8");
+	await writeFile(augmentationsFile, augmentationsContent, "utf-8");
+	await writeFile(assetsFile, assetsContent, "utf-8");
 	await writeFile(indexFile, indexContent, "utf-8");
 	const written = [
 		registryFile,
 		servicesFile,
 		modulesFile,
 		routesFile,
+		pluginsFile,
+		augmentationsFile,
+		assetsFile,
 		indexFile
 	];
 	if (envContent) {
@@ -893,17 +1270,62 @@ async function generateTypes(opts) {
 		written.push(envFile);
 	}
 	await writeFile(join(dirname(outDir), ".gitignore"), "# Auto-generated by kick typegen\n*\n", "utf-8");
+	const uniquePluginNames = new Set(pluginsAndAdapters.map((p) => p.name)).size;
+	const uniqueAugmentations = new Set(augmentations.map((a) => a.name)).size;
 	return {
 		registryEntries: classTokens.length,
 		serviceTokens: new Set(allServices).size,
 		moduleTokens: modules.length,
 		routeEntries: routes.length,
+		pluginEntries: uniquePluginNames,
+		augmentationEntries: uniqueAugmentations,
+		assetEntries: assets.count,
 		envWritten: envContent !== null,
 		written,
 		resolvedCollisions: collisions.length
 	};
 }
 //#endregion
+//#region src/typegen/token-conventions.ts
+/**
+* Regex for the §22.2 token shape. Breakdown:
+*
+* - `^(kick\/)?` — optional reserved framework prefix.
+* - `([a-z][\w-]*\/[A-Z]\w*)` — `<scope>/<PascalKey>`. Scope is
+*   lowercase, key is PascalCase.
+* - `(\/.+)?` — optional `/suffix` for sub-flavours
+*   (e.g. `mycorp/Cache/redis`).
+* - `(:[a-z][\w-]+(:[a-z][\w-]+)*)?` — optional `:instance` (and
+*   further `:extra` colon-sections) for `.scoped()` shards.
+*/
+const TOKEN_CONVENTION_REGEX = /^(kick\/)?([a-z][\w-]*\/[A-Z]\w*)(\/.+)?(:[a-z][\w-]+(:[a-z][\w-]+)*)?$/;
+const LEGACY_PREFIX = "kickjs.";
+function validateTokenConventions(tokens) {
+	const warnings = [];
+	for (const token of tokens) {
+		const name = token.name;
+		if (name.startsWith(LEGACY_PREFIX)) continue;
+		if (TOKEN_CONVENTION_REGEX.test(name)) continue;
+		warnings.push({
+			token: name,
+			variable: token.variable,
+			filePath: token.relativePath,
+			reason: "does not match `<scope>/<PascalKey>[/<suffix>][:<instance>]`",
+			suggestion: suggestRename(name)
+		});
+	}
+	return warnings;
+}
+function suggestRename(name) {
+	if (/^[A-Z]\w*$/.test(name)) return `'<scope>/${name}' (e.g. 'mycorp/${name}')`;
+	if (name.includes(".")) return `consider '<scope>/PascalKey' instead of dotted form`;
+	const slashLower = /^([a-z][\w-]*)\/([a-z]\w*)$/.exec(name);
+	if (slashLower) {
+		const [, scope, key] = slashLower;
+		return `'${scope}/${key.charAt(0).toUpperCase()}${key.slice(1)}'`;
+	}
+}
+//#endregion
 //#region src/typegen/index.ts
 /**
 * Public entry point for the KickJS typegen module.
@@ -944,6 +1366,7 @@ async function runTypegen(opts = {}) {
 		cwd,
 		envFile: envFile === false ? void 0 : envFile
 	});
+	const assets = discoverAssets(opts.assetMap, cwd);
 	const result = await generateTypes({
 		classes: scan.classes,
 		routes: scan.routes,
@@ -951,23 +1374,39 @@ async function runTypegen(opts = {}) {
 		injects: scan.injects,
 		collisions: scan.collisions,
 		env: envFile === false ? null : scan.env,
+		pluginsAndAdapters: scan.pluginsAndAdapters,
+		augmentations: scan.augmentations,
+		assets,
 		outDir,
 		allowDuplicates,
 		schemaValidator
 	});
+	const tokenWarnings = validateTokenConventions(scan.tokens);
 	const elapsed = Date.now() - start;
 	if (!silent) {
 		const where = outDir.replace(cwd + "/", "");
 		const collisionNote = result.resolvedCollisions > 0 ? `, ${result.resolvedCollisions} collisions namespaced` : "";
 		const envNote = result.envWritten ? ", env typed" : "";
-		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		const pluginNote = result.pluginEntries > 0 ? `, ${result.pluginEntries} plugins/adapters` : "";
+		const augNote = result.augmentationEntries > 0 ? `, ${result.augmentationEntries} augmentations` : "";
+		const assetNote = result.assetEntries > 0 ? `, ${result.assetEntries} assets` : "";
+		console.log(`  kick typegen → ${result.serviceTokens} services, ${result.routeEntries} routes, ${result.moduleTokens} modules${pluginNote}${augNote}${assetNote}${envNote}${collisionNote} → ${where} (${elapsed}ms)`);
+		if (tokenWarnings.length > 0) {
+			console.warn(`  kick typegen: ${tokenWarnings.length} token(s) don't match the §22.2 convention:`);
+			for (const warning of tokenWarnings) {
+				const variableNote = warning.variable ? ` [${warning.variable}]` : "";
+				console.warn(`    '${warning.token}' (${warning.filePath})${variableNote} — ${warning.reason}`);
+				if (warning.suggestion) console.warn(`      → suggestion: ${warning.suggestion}`);
+			}
+		}
 	}
 	return {
 		scan,
-		result
+		result,
+		tokenWarnings
 	};
 }
 //#endregion
 export { runTypegen };
 
-//# sourceMappingURL=typegen-C30frihW.mjs.map
+//# sourceMappingURL=typegen-C-H8pg-y.mjs.map