glirastes 0.3.2 → 0.5.0

package/dist/codegen/tools/semantics.js

@@ -0,0 +1,206 @@
+import { z } from 'zod';
+import { ToolPresentationSchema } from '../../contracts/index.js';
+import { createJsonSchemaLike } from '../../runtime/json-schema.js';
+import { AGENT_MODEL_PATTERN, agenticContentProblem, lockDigest } from './agentic.js';
+import { compareCodeUnits } from './canonical.js';
+import { toolFinding } from './findings.js';
+/** Languages of synonyms, titles and example sentences (spec 4.7 "DE/EN"). */
+export const SEMANTICS_LANGUAGES = ['de', 'en'];
+/** Fields of a `tool-semantics.json` entry that carry an origin and can be locked. */
+export const SEMANTICS_FIELDS = [
+    'description',
+    'title',
+    'module',
+    'sharedWith',
+    'usageHints',
+    'presentation',
+    'synonyms',
+    'examples',
+    'exampleCalls',
+    'approvalHint',
+];
+export const SEMANTICS_LIMITS = {
+    description: 1_000,
+    title: 200,
+    hint: 500,
+    hints: 20,
+    synonym: 100,
+    synonyms: 20,
+    example: 200,
+    examplesMin: 3,
+    examplesMax: 5,
+    exampleCalls: 10,
+    approvalHint: 500,
+    sharedWith: 50,
+};
+const digest = z.string().regex(/^sha256:[A-Za-z0-9_-]{43}$/);
+const IDENTIFIER = /^[A-Za-z][A-Za-z0-9_.-]{0,199}$/;
+const text = (max) => z.string().trim().min(1).max(max);
+const perLanguage = (item) => z.object({ de: item.optional(), en: item.optional() }).strict();
+/**
+ * One entry of `.glirastes/tool-semantics.json` (spec 4.3, 4.7): the Get It
+ * Done format (`name`, `modelName`, `description`, `module`, `sharedWith`,
+ * `usageHints`, `presentation`) plus the stage-2 fields. A field without an
+ * origin was written by a human; `locked` pins reviewed fields by digest;
+ * `agent` names who wrote the agent fields and for which interface.
+ */
+export const SemanticsEntrySchema = z.object({
+    name: z.string().trim().min(1).max(200).optional(),
+    stableKey: z.string().trim().min(1).max(2_100).optional(),
+    /** Written by older exports; read for compatibility, never used. */
+    modelName: z.string().optional(),
+    description: z.string().optional(),
+    module: z.string().optional(),
+    sharedWith: z.array(z.string()).optional(),
+    usageHints: z.array(z.string()).optional(),
+    presentation: z.unknown().optional(),
+    title: perLanguage(text(SEMANTICS_LIMITS.title)).optional(),
+    synonyms: perLanguage(z.array(text(SEMANTICS_LIMITS.synonym)).max(SEMANTICS_LIMITS.synonyms)).optional(),
+    examples: perLanguage(z.array(text(SEMANTICS_LIMITS.example))
+        .min(SEMANTICS_LIMITS.examplesMin).max(SEMANTICS_LIMITS.examplesMax)).optional(),
+    exampleCalls: z.array(z.object({
+        sentence: text(SEMANTICS_LIMITS.example).optional(),
+        input: z.record(z.string(), z.unknown()),
+    }).strict()).max(SEMANTICS_LIMITS.exampleCalls).optional(),
+    approvalHint: text(SEMANTICS_LIMITS.approvalHint).optional(),
+    origin: z.partialRecord(z.enum(SEMANTICS_FIELDS), z.enum(['human', 'code', 'agent'])).optional(),
+    locked: z.partialRecord(z.enum(SEMANTICS_FIELDS), digest).optional(),
+    agent: z.object({
+        model: z.string().regex(AGENT_MODEL_PATTERN),
+        interfaceDigest: digest,
+    }).strict().optional(),
+}).strict();
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Whether an agent wrote the entry or one of its fields; such entries get the unified check. */
+export function isAgenticSemantics(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.agent !== undefined)
+        return true;
+    return isRecord(value.origin) && Object.values(value.origin).includes('agent');
+}
+/** The app's language plus English, each once. */
+export function requiredLanguages(locale) {
+    const own = locale.toLowerCase().split('-')[0];
+    return own === 'de' ? ['de', 'en'] : ['en'];
+}
+function fieldValue(entry, field) {
+    return entry[field];
+}
+function proseOf(entry) {
+    return {
+        description: entry.description,
+        title: entry.title,
+        usageHints: entry.usageHints,
+        synonyms: entry.synonyms,
+        examples: entry.examples,
+        approvalHint: entry.approvalHint,
+        presentation: entry.presentation,
+        sentences: entry.exampleCalls?.map((call) => call.sentence),
+    };
+}
+function agentLimitsProblem(entry) {
+    if (entry.description !== undefined && entry.description.length > SEMANTICS_LIMITS.description) {
+        return `the description is longer than ${SEMANTICS_LIMITS.description} characters`;
+    }
+    const hints = entry.usageHints ?? [];
+    if (hints.length > SEMANTICS_LIMITS.hints || hints.some((hint) => hint.length > SEMANTICS_LIMITS.hint)) {
+        return `usageHints hold at most ${SEMANTICS_LIMITS.hints} hints of ${SEMANTICS_LIMITS.hint} characters`;
+    }
+    const identifiers = [...(entry.module === undefined ? [] : [entry.module]), ...(entry.sharedWith ?? [])];
+    if ((entry.sharedWith?.length ?? 0) > SEMANTICS_LIMITS.sharedWith || identifiers.some((name) => !IDENTIFIER.test(name))) {
+        return 'module and sharedWith must be module names (letters, digits, _, . or -)';
+    }
+    if (entry.presentation !== undefined && !ToolPresentationSchema.safeParse(entry.presentation).success) {
+        return 'the presentation does not match its schema (locale, singular, plural, approval)';
+    }
+    return undefined;
+}
+/**
+ * The unified check of one semantics entry against the tool it describes
+ * (spec 4.6, 4.7). Locked fields must still match their digest and never be
+ * marked as agent output. No entry may carry secrets, provider keys or
+ * control characters: `origin` is the writer's own claim, and synonyms reach
+ * the generated module. An agent entry must also name its model and
+ * interface, stay within the prose and length limits and give example calls
+ * that the tool's input schema accepts. A rejected entry is ignored and
+ * reported. An agent entry for an earlier interface stays in use and is
+ * listed for renewal; its example calls were written for the old schema, so
+ * the ones the current schema refuses are left out instead of rejecting it.
+ */
+export function validateSemanticsEntry(entry, context) {
+    const agentic = isAgenticSemantics(entry);
+    const reject = (reason) => ({
+        findings: [toolFinding(agentic || entry.locked ? 'resolution-rejected' : 'tool-semantics-invalid', 'warning', context.stableKey, `The tool-semantics.json entry was rejected: ${reason}.`)],
+        stale: false,
+    });
+    for (const field of SEMANTICS_FIELDS) {
+        const pinned = entry.locked?.[field];
+        if (pinned === undefined)
+            continue;
+        if (entry.origin?.[field] === 'agent')
+            return reject(`the locked field ${field} is marked as agent output`);
+        if (lockDigest(fieldValue(entry, field) ?? null) !== pinned) {
+            return reject(`the locked field ${field} was changed after review; restore it from git, or review it and run glirastes tools verify`);
+        }
+    }
+    const content = agenticContentProblem({
+        prose: proseOf(entry), module: entry.module, sharedWith: entry.sharedWith, calls: entry.exampleCalls?.map((call) => call.input),
+    });
+    if (content)
+        return reject(`it contains ${content}`);
+    if (agentic) {
+        if (!entry.agent)
+            return reject('an agent entry names its model and the interfaceDigest it was written for (agent.model, agent.interfaceDigest)');
+        const business = agenticContentProblem(proseOf(entry), { prose: true });
+        if (business)
+            return reject(`it contains ${business}`);
+        const limits = agentLimitsProblem(entry);
+        if (limits)
+            return reject(limits);
+    }
+    const stale = entry.agent !== undefined && context.interfaceDigest !== undefined
+        && entry.agent.interfaceDigest !== context.interfaceDigest;
+    const calls = entry.exampleCalls ?? [];
+    if (calls.length === 0)
+        return { entry, findings: [], stale };
+    const schema = context.input ? createJsonSchemaLike(context.input) : undefined;
+    const accepted = (call) => schema?.safeParse(call.input).success === true;
+    if (stale) {
+        const kept = calls.filter(accepted);
+        return kept.length === calls.length
+            ? { entry, findings: [], stale }
+            : { entry: { ...entry, exampleCalls: kept }, findings: [], stale, droppedExampleCalls: calls.length - kept.length };
+    }
+    if (!schema)
+        return reject('example calls need a tool with an input contract');
+    const index = calls.findIndex((call) => !accepted(call));
+    if (index >= 0)
+        return reject(`example call ${index + 1} does not match the input schema`);
+    return { entry, findings: [], stale };
+}
+export function semanticsFacts(entry, languages) {
+    const protectedFields = entry
+        ? SEMANTICS_FIELDS.filter((field) => fieldValue(entry, field) !== undefined
+            && (entry.locked?.[field] !== undefined || entry.origin?.[field] !== 'agent'))
+        : [];
+    return {
+        protectedFields,
+        hasSynonyms: SEMANTICS_LANGUAGES.some((language) => (entry?.synonyms?.[language]?.length ?? 0) > 0),
+        missingExamples: languages.filter((language) => (entry?.examples?.[language]?.length ?? 0) === 0),
+    };
+}
+/** Synonyms and example sentences of both languages, each once, in code-unit order. */
+export function semanticsSearch(entry) {
+    const collect = (values) => [...new Set(values.map((value) => value.trim()))]
+        .filter((value) => value.length > 0)
+        .sort(compareCodeUnits);
+    return {
+        synonyms: collect(SEMANTICS_LANGUAGES.flatMap((language) => entry?.synonyms?.[language] ?? []))
+            .slice(0, SEMANTICS_LIMITS.synonyms),
+        examples: collect(SEMANTICS_LANGUAGES.flatMap((language) => entry?.examples?.[language] ?? [])),
+    };
+}
+//# sourceMappingURL=semantics.js.map

package/dist/codegen/tools/semantics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantics.js","sourceRoot":"","sources":["../../../src/codegen/tools/semantics.ts"],"names":[],"mappings":"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"}

package/dist/codegen/tools/sources/app-files.d.ts

@@ -0,0 +1,35 @@
+export declare const MAX_APP_SOURCE_FILES = 20000;
+export declare const MAX_APP_SOURCE_BYTES = 2000000;
+export interface AppSourceFile {
+    /** App-relative POSIX path. */
+    path: string;
+    /** The name in the TypeScript program: `<file>.vue.ts` for a `.vue` file (see vue-sfc.ts). */
+    absolute: string;
+    /** For a `.vue` file only its script blocks, at their original offsets. */
+    source: string;
+}
+export type AppSourceScan = {
+    complete: true;
+    files: AppSourceFile[];
+} | {
+    complete: false;
+    reason: string;
+};
+/** `src` when the app has one, else the app root. */
+export declare function defaultSourceDir(root: string): string;
+/**
+ * Whether a link could hide files a walk must enumerate: a folder, or a file
+ * the walk would read. A link to anything else (`CLAUDE.md -> AGENTS.md`, an
+ * image, a link that points nowhere) holds no source and is ignored.
+ */
+export declare function linkHidesFiles(absolute: string, wantedFile: boolean): Promise<boolean>;
+/**
+ * Bounded walk over the app's own source files. A linked folder, a linked
+ * source file, an oversized file or too many files make the scan incomplete
+ * instead of silently skipping code that could register a UI action. Links to
+ * anything else are ignored.
+ */
+export declare function scanAppSources(root: string, options: {
+    srcDir?: string;
+    matches(source: string): boolean;
+}): Promise<AppSourceScan>;

package/dist/codegen/tools/sources/app-files.js

@@ -0,0 +1,109 @@
+import { existsSync } from 'node:fs';
+import { lstat, readdir, readFile, stat } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+import { compareCodeUnits } from '../canonical.js';
+import { programFileName, vueScriptOf } from './vue-sfc.js';
+export const MAX_APP_SOURCE_FILES = 20_000;
+export const MAX_APP_SOURCE_BYTES = 2_000_000;
+const SOURCE_FILE = /\.(?:tsx?|jsx?|mjs|cjs|vue)$/;
+/** `a.test.tsx`, `a.spec.ts`, `Button.stories.tsx`: test and story files, not app code. */
+const TEST_FILE = /\.(?:test|spec|stories)\.[^.]+$/;
+/**
+ * Dependencies and test folders never register app handlers, at any depth: a
+ * client action or navigation bridge that exists only in a test harness must
+ * not enable a tool.
+ */
+const SKIPPED_ANYWHERE = new Set(['node_modules', '__tests__']);
+/**
+ * Build output, generated code, coverage, end-to-end suites, story builds and
+ * static assets sit directly in the scanned folder, where tools put them. A
+ * feature folder with such a name deeper down, e.g. `src/app/(app)/build/` or
+ * `src/features/e2e/`, is app code and is scanned.
+ */
+const SKIPPED_AT_SCAN_ROOT = new Set([
+    'dist', 'build', 'out', 'coverage', 'generated', 'e2e', 'storybook-static', 'public',
+]);
+/** `src` when the app has one, else the app root. */
+export function defaultSourceDir(root) {
+    return existsSync(join(root, 'src')) ? 'src' : '.';
+}
+function appRelative(root, absolute) {
+    return relative(root, absolute).split(sep).join('/');
+}
+/** A source file the scan reads: not a declaration file, not a test or story. */
+function isScannedSource(name) {
+    return SOURCE_FILE.test(name) && !name.endsWith('.d.ts') && !TEST_FILE.test(name);
+}
+/**
+ * Whether a link could hide files a walk must enumerate: a folder, or a file
+ * the walk would read. A link to anything else (`CLAUDE.md -> AGENTS.md`, an
+ * image, a link that points nowhere) holds no source and is ignored.
+ */
+export async function linkHidesFiles(absolute, wantedFile) {
+    if (wantedFile)
+        return true;
+    try {
+        return (await stat(absolute)).isDirectory();
+    }
+    catch (error) {
+        return !['ENOENT', 'ELOOP', 'ENOTDIR'].includes(error.code ?? '');
+    }
+}
+/**
+ * Bounded walk over the app's own source files. A linked folder, a linked
+ * source file, an oversized file or too many files make the scan incomplete
+ * instead of silently skipping code that could register a UI action. Links to
+ * anything else are ignored.
+ */
+export async function scanAppSources(root, options) {
+    const files = [];
+    let visited = 0;
+    const start = join(root, options.srcDir ?? defaultSourceDir(root));
+    if (!existsSync(start))
+        return { complete: true, files: [] };
+    const walk = async (directory) => {
+        const entries = (await readdir(directory, { withFileTypes: true }))
+            .sort((left, right) => compareCodeUnits(left.name, right.name));
+        for (const entry of entries) {
+            if (entry.name.startsWith('.') || SKIPPED_ANYWHERE.has(entry.name))
+                continue;
+            if (directory === start && SKIPPED_AT_SCAN_ROOT.has(entry.name))
+                continue;
+            const absolute = join(directory, entry.name);
+            if (entry.isSymbolicLink()) {
+                if (await linkHidesFiles(absolute, isScannedSource(entry.name))) {
+                    return `${appRelative(root, absolute)} is a link; its sources cannot be enumerated.`;
+                }
+                continue;
+            }
+            if (entry.isDirectory()) {
+                const failure = await walk(absolute);
+                if (failure)
+                    return failure;
+                continue;
+            }
+            if (!entry.isFile() || !isScannedSource(entry.name))
+                continue;
+            visited += 1;
+            if (visited > MAX_APP_SOURCE_FILES)
+                return 'The app has too many source files to enumerate UI actions.';
+            if ((await lstat(absolute)).size > MAX_APP_SOURCE_BYTES) {
+                return `${appRelative(root, absolute)} is too large to read.`;
+            }
+            const text = await readFile(absolute, 'utf8');
+            const script = entry.name.endsWith('.vue') ? vueScriptOf(text) : { ok: true, text };
+            if (!script.ok) {
+                if (options.matches(text))
+                    return `${appRelative(root, absolute)} ${script.reason}`;
+                continue;
+            }
+            if (options.matches(script.text)) {
+                files.push({ path: appRelative(root, absolute), absolute: programFileName(absolute), source: script.text });
+            }
+        }
+        return undefined;
+    };
+    const failure = await walk(start);
+    return failure ? { complete: false, reason: failure } : { complete: true, files };
+}
+//# sourceMappingURL=app-files.js.map

package/dist/codegen/tools/sources/app-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-files.js","sourceRoot":"","sources":["../../../../src/codegen/tools/sources/app-files.ts"],"names":[],"mappings":"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"}

package/dist/codegen/tools/sources/fastapi-routes.py

@@ -0,0 +1,177 @@
+"""Count the HTTP routes a FastAPI app declares, from syntax only.
+
+Run as ``python3 -I fastapi-routes.py <app-dir>``. The app is never imported
+or run: every ``.py`` file below the directory is parsed with ``ast`` and one
+JSON object is printed. The generator compares the count with the OpenAPI
+export, so a stale export or a hidden route cannot pass silently.
+"""
+import ast
+import json
+import os
+import sys
+
+DECORATOR_METHODS = {
+    'get': 'GET', 'put': 'PUT', 'post': 'POST', 'delete': 'DELETE',
+    'options': 'OPTIONS', 'head': 'HEAD', 'patch': 'PATCH', 'trace': 'TRACE',
+}
+CONSTRUCTORS = {'FastAPI', 'APIRouter'}
+SKIPPED_DIRECTORIES = {'__pycache__', '.venv', 'venv', 'env', 'node_modules', 'site-packages', '.git', 'tests'}
+FILE_LIMIT = 1024 * 1024
+
+
+def is_test_file(name):
+    return name.startswith('test_') or name.endswith('_test.py') or name == 'conftest.py'
+
+
+def constant_false(node):
+    return isinstance(node, ast.Constant) and node.value is False
+
+
+def keyword(call, name):
+    for item in call.keywords:
+        if item.arg == name:
+            return item.value
+    return None
+
+
+class FileCounter:
+    def __init__(self, relative):
+        self.relative = relative
+        self.fastapi_modules = set()
+        self.constructors = {}
+        self.receivers = {}
+        self.routes = []
+        self.problems = []
+
+    def where(self, node):
+        return '%s:%d' % (self.relative, node.lineno)
+
+    def read_imports(self, tree):
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom) and node.module == 'fastapi':
+                for alias in node.names:
+                    if alias.name in CONSTRUCTORS:
+                        self.constructors[alias.asname or alias.name] = alias.name
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name == 'fastapi':
+                        self.fastapi_modules.add(alias.asname or alias.name)
+
+    def constructor_of(self, value):
+        if not isinstance(value, ast.Call):
+            return None
+        func = value.func
+        if isinstance(func, ast.Name) and func.id in self.constructors:
+            return self.constructors[func.id]
+        if (isinstance(func, ast.Attribute) and func.attr in CONSTRUCTORS
+                and isinstance(func.value, ast.Name) and func.value.id in self.fastapi_modules):
+            return func.attr
+        return None
+
+    def read_receivers(self, tree):
+        for node in ast.walk(tree):
+            targets = []
+            if isinstance(node, ast.Assign):
+                targets, value = node.targets, node.value
+            elif isinstance(node, ast.AnnAssign) and node.value is not None:
+                targets, value = [node.target], node.value
+            else:
+                continue
+            if self.constructor_of(value) is None:
+                continue
+            hidden = keyword(value, 'include_in_schema')
+            for target in targets:
+                if isinstance(target, ast.Name):
+                    self.receivers[target.id] = constant_false(hidden)
+
+    def methods_of(self, call, default):
+        value = keyword(call, 'methods')
+        if value is None:
+            return default
+        if isinstance(value, (ast.List, ast.Tuple, ast.Set)) and all(
+                isinstance(item, ast.Constant) and isinstance(item.value, str) for item in value.elts):
+            return sorted({item.value.upper() for item in value.elts})
+        self.problems.append('%s computes the methods of a route; write them as a literal list.' % self.where(call))
+        return None
+
+    def add_route(self, call, receiver, methods):
+        if methods is None:
+            return
+        hidden = keyword(call, 'include_in_schema')
+        if hidden is not None and not isinstance(hidden, ast.Constant):
+            self.problems.append('%s computes include_in_schema; write True or False.' % self.where(call))
+            return
+        self.routes.append({
+            'file': self.relative,
+            'line': call.lineno,
+            'methods': methods,
+            'hidden': constant_false(hidden) or self.receivers[receiver],
+        })
+
+    def read_routes(self, tree):
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
+                continue
+            target = node.func.value
+            if not isinstance(target, ast.Name) or target.id not in self.receivers:
+                continue
+            name = node.func.attr
+            if name in DECORATOR_METHODS:
+                self.add_route(node, target.id, [DECORATOR_METHODS[name]])
+            elif name in ('api_route', 'add_api_route'):
+                self.add_route(node, target.id, self.methods_of(node, ['GET']))
+
+    def read_hidden_routers(self, tree):
+        """``include_router(router, include_in_schema=False)`` hides every route of a router of this file."""
+        for node in ast.walk(tree):
+            if (not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute)
+                    or node.func.attr != 'include_router'):
+                continue
+            router = node.args[0] if node.args else keyword(node, 'router')
+            if constant_false(keyword(node, 'include_in_schema')) and isinstance(router, ast.Name) \
+                    and router.id in self.receivers:
+                self.receivers[router.id] = True
+
+    def count(self, tree):
+        self.read_imports(tree)
+        if not self.constructors and not self.fastapi_modules:
+            return
+        self.read_receivers(tree)
+        self.read_hidden_routers(tree)
+        self.read_routes(tree)
+
+
+def main(root):
+    routes = []
+    problems = []
+    for directory, subdirectories, files in os.walk(root):
+        subdirectories[:] = sorted(name for name in subdirectories if name not in SKIPPED_DIRECTORIES)
+        for name in sorted(files):
+            if not name.endswith('.py') or is_test_file(name):
+                continue
+            path = os.path.join(directory, name)
+            relative = os.path.relpath(path, root).replace(os.sep, '/')
+            if os.path.getsize(path) > FILE_LIMIT:
+                problems.append('%s is larger than 1 MiB; split it or move it out of the FastAPI source directory.' % relative)
+                continue
+            with open(path, encoding='utf-8') as handle:
+                text = handle.read()
+            try:
+                tree = ast.parse(text, filename=relative)
+            except SyntaxError as error:
+                problems.append('%s:%s is not valid Python: %s.' % (relative, error.lineno, error.msg))
+                continue
+            counter = FileCounter(relative)
+            counter.count(tree)
+            routes.extend(counter.routes)
+            problems.extend(counter.problems)
+    routes.sort(key=lambda route: (route['file'], route['line']))
+    json.dump({'routes': routes, 'problems': problems}, sys.stdout, sort_keys=True)
+    sys.stdout.write('\n')
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2 or not os.path.isdir(sys.argv[1]):
+        sys.stderr.write('usage: python3 -I fastapi-routes.py <app-dir>\n')
+        sys.exit(2)
+    main(sys.argv[1])

package/dist/codegen/tools/sources/nest-decorators.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How a file reaches the decorators of `@nestjs/common`, through a named or a
+ * namespace import. Shared by the Nest endpoint source and the execution
+ * inventory, so a controller the source enumerates is one the inventory verifies.
+ */
+import ts from 'typescript';
+import type { EndpointMethod } from '../../../types.js';
+/** The HTTP method decorators of `@nestjs/common` that become endpoint tools. */
+export declare const NEST_METHOD_DECORATORS: Readonly<Record<string, EndpointMethod>>;
+export interface NestImports {
+    /** Local name → exported name, for named imports of `@nestjs/common`. */
+    common: Map<string, string>;
+    commonNamespaces: Set<string>;
+    core: Set<string>;
+    createZodDto: Set<string>;
+}
+/** The `@nestjs/common`, `@nestjs/core` and `nestjs-zod` bindings of a file, ignoring type-only imports. */
+export declare function readImports(file: ts.SourceFile): NestImports;
+/** The `@nestjs/common` export a decorator calls, e.g. `Get` for `@Get(':id')` or `@common.Get()`. */
+export declare function decoratorName(decorator: ts.Decorator, imports: NestImports): {
+    name: string;
+    args: ts.NodeArray<ts.Expression>;
+} | undefined;
+export declare function decoratorsOf(node: ts.Node, imports: NestImports): Array<{
+    name: string;
+    args: ts.NodeArray<ts.Expression>;
+}>;

package/dist/codegen/tools/sources/nest-decorators.js

@@ -0,0 +1,65 @@
+/**
+ * How a file reaches the decorators of `@nestjs/common`, through a named or a
+ * namespace import. Shared by the Nest endpoint source and the execution
+ * inventory, so a controller the source enumerates is one the inventory verifies.
+ */
+import ts from 'typescript';
+const NEST_COMMON = '@nestjs/common';
+const NEST_CORE = '@nestjs/core';
+const NEST_ZOD = 'nestjs-zod';
+/** The HTTP method decorators of `@nestjs/common` that become endpoint tools. */
+export const NEST_METHOD_DECORATORS = {
+    Get: 'GET', Head: 'HEAD', Post: 'POST', Put: 'PUT', Patch: 'PATCH', Delete: 'DELETE',
+};
+/** The `@nestjs/common`, `@nestjs/core` and `nestjs-zod` bindings of a file, ignoring type-only imports. */
+export function readImports(file) {
+    const imports = { common: new Map(), commonNamespaces: new Set(), core: new Set(), createZodDto: new Set() };
+    for (const statement of file.statements) {
+        if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
+            continue;
+        if (statement.importClause?.isTypeOnly)
+            continue;
+        const module = statement.moduleSpecifier.text;
+        const bindings = statement.importClause?.namedBindings;
+        if (module === NEST_COMMON && bindings && ts.isNamespaceImport(bindings))
+            imports.commonNamespaces.add(bindings.name.text);
+        if (!bindings || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (element.isTypeOnly)
+                continue;
+            const exported = (element.propertyName ?? element.name).text;
+            if (module === NEST_COMMON)
+                imports.common.set(element.name.text, exported);
+            if (module === NEST_CORE)
+                imports.core.add(exported);
+            if (module === NEST_ZOD && exported === 'createZodDto')
+                imports.createZodDto.add(element.name.text);
+        }
+    }
+    return imports;
+}
+/** The `@nestjs/common` export a decorator calls, e.g. `Get` for `@Get(':id')` or `@common.Get()`. */
+export function decoratorName(decorator, imports) {
+    const call = decorator.expression;
+    if (!ts.isCallExpression(call))
+        return undefined;
+    const callee = call.expression;
+    if (ts.isIdentifier(callee)) {
+        const name = imports.common.get(callee.text);
+        return name ? { name, args: call.arguments } : undefined;
+    }
+    if (ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.expression)
+        && imports.commonNamespaces.has(callee.expression.text)) {
+        return { name: callee.name.text, args: call.arguments };
+    }
+    return undefined;
+}
+export function decoratorsOf(node, imports) {
+    const decorators = ts.canHaveDecorators(node) ? ts.getDecorators(node) ?? [] : [];
+    return decorators.flatMap((decorator) => {
+        const found = decoratorName(decorator, imports);
+        return found ? [found] : [];
+    });
+}
+//# sourceMappingURL=nest-decorators.js.map

package/dist/codegen/tools/sources/nest-decorators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nest-decorators.js","sourceRoot":"","sources":["../../../../src/codegen/tools/sources/nest-decorators.ts"],"names":[],"mappings":"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"}