te.js 2.1.5 → 2.2.0

package/auto-docs/analysis/handler-analyzer.test.js

@@ -0,0 +1,106 @@
+/**
+ * Unit tests for auto-docs handler-analyzer (detectMethods, analyzeHandler).
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  detectMethods,
+  analyzeHandler,
+  ALL_METHODS,
+} from './handler-analyzer.js';
+
+describe('handler-analyzer', () => {
+  describe('detectMethods', () => {
+    it('returns all methods when handler is not a function', () => {
+      expect(detectMethods(null)).toEqual(ALL_METHODS);
+      expect(detectMethods(undefined)).toEqual(ALL_METHODS);
+    });
+
+    it('detects GET when handler uses ammo.GET', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200, {});
+      };
+      expect(detectMethods(handler)).toContain('GET');
+    });
+
+    it('detects POST and GET when handler checks both', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200, {});
+        if (ammo.POST) ammo.fire(201, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('POST');
+    });
+
+    it('returns all methods when no method checks found (method-agnostic)', () => {
+      const handler = () => {};
+      expect(detectMethods(handler)).toEqual(ALL_METHODS);
+    });
+
+    it('detects GET and HEAD when handler uses ammo.only("GET")', () => {
+      const handler = (ammo) => {
+        ammo.only('GET');
+        ammo.fire({ status: 'ok' });
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+      expect(detected).toHaveLength(2);
+    });
+
+    it('detects POST and PUT when handler uses ammo.only("POST", "PUT")', () => {
+      const handler = (ammo) => {
+        ammo.only('POST', 'PUT');
+        ammo.fire(200, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('POST');
+      expect(detected).toContain('PUT');
+      expect(detected).toHaveLength(2);
+    });
+
+    it('detects from ammo.only with double-quoted methods', () => {
+      const handler = (ammo) => {
+        ammo.only('GET');
+        ammo.fire(200);
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+    });
+
+    it('detects from .only with no space after comma', () => {
+      const handler = (ammo) => {
+        ammo.only('GET', 'POST');
+        ammo.fire(200);
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toContain('GET');
+      expect(detected).toContain('HEAD');
+      expect(detected).toContain('POST');
+      expect(detected).toHaveLength(3);
+    });
+
+    it('prefers ammo.only over property access when both present', () => {
+      const handler = (ammo) => {
+        ammo.only('POST');
+        if (ammo.GET) ammo.fire(200);
+        ammo.fire(201, {});
+      };
+      const detected = detectMethods(handler);
+      expect(detected).toEqual(['POST']);
+    });
+  });
+
+  describe('analyzeHandler', () => {
+    it('returns object with methods array', () => {
+      const handler = (ammo) => {
+        if (ammo.GET) ammo.fire(200);
+      };
+      const result = analyzeHandler(handler);
+      expect(result).toHaveProperty('methods');
+      expect(Array.isArray(result.methods)).toBe(true);
+      expect(result.methods).toContain('GET');
+    });
+  });
+});

package/auto-docs/analysis/source-resolver.test.js

@@ -0,0 +1,58 @@
+/**
+ * Unit tests for auto-docs source-resolver (extractRelativeImports, resolveTargetFilePath, formatDependencyContext).
+ */
+import { describe, it, expect } from 'vitest';
+import path from 'node:path';
+import {
+  extractRelativeImports,
+  resolveTargetFilePath,
+  formatDependencyContext,
+} from './source-resolver.js';
+
+describe('source-resolver', () => {
+  describe('extractRelativeImports', () => {
+    it('extracts relative import paths', () => {
+      const source = `import x from './foo.js';\nimport { y } from '../bar.js';`;
+      const imports = extractRelativeImports(source);
+      expect(imports).toContain('./foo.js');
+      expect(imports).toContain('../bar.js');
+    });
+    it('ignores absolute or node imports', () => {
+      const source = `import path from 'path';\nimport x from './local.js';`;
+      const imports = extractRelativeImports(source);
+      expect(imports).toEqual(['./local.js']);
+    });
+    it('returns unique paths', () => {
+      const source = `import a from './foo.js';\nimport b from './foo.js';`;
+      expect(extractRelativeImports(source)).toHaveLength(1);
+    });
+  });
+
+  describe('resolveTargetFilePath', () => {
+    it('joins dirTargets with groupId and .target.js', () => {
+      const resolved = resolveTargetFilePath('users', 'targets');
+      expect(resolved).toMatch(/targets[\\/]users\.target\.js$/);
+    });
+    it('converts groupId slashes to path sep', () => {
+      const resolved = resolveTargetFilePath('subdir/users', 'targets');
+      expect(resolved).toMatch(/subdir[\\/]users\.target\.js$/);
+    });
+  });
+
+  describe('formatDependencyContext', () => {
+    it('returns empty string for empty sources', () => {
+      expect(formatDependencyContext(new Map(), null)).toBe('');
+    });
+    it('formats map of path -> source with labels', () => {
+      const sources = new Map([
+        ['/cwd/targets/users.target.js', 'const x = 1;'],
+        ['/cwd/services/user.js', 'const y = 2;'],
+      ]);
+      const targetPath = '/cwd/targets/users.target.js';
+      const out = formatDependencyContext(sources, targetPath, 1000);
+      expect(out).toContain('Target');
+      expect(out).toContain('const x = 1;');
+      expect(out).toContain('const y = 2;');
+    });
+  });
+});

package/auto-docs/constants.js

@@ -7,13 +7,24 @@
 export const OPENAPI_VERSION = '3.0.3';
 
 /** Lowercase HTTP method names (for method-keyed LLM response detection and OpenAPI operation keys). */
-export const METHOD_KEYS = new Set(['get', 'put', 'post', 'delete', 'patch', 'head', 'options']);
+export const METHOD_KEYS = new Set([
+  'get',
+  'put',
+  'post',
+  'delete',
+  'patch',
+  'head',
+  'options',
+]);
 
 /** When an endpoint accepts all HTTP methods, document it once under this key. */
 export const METHOD_AGNOSTIC_OPERATION_KEY = 'get';
 
 /** Max handler source length by level (chars; tokens roughly scale). Level 1 = moderate, 2 = high. */
-export const HANDLER_SOURCE_MAX_LENGTH_BY_LEVEL = { 1: 2800, 2: 6000 };
+export const HANDLER_SOURCE_MAX_LENGTH_BY_LEVEL = Object.freeze({
+  1: 2800,
+  2: 6000,
+});
 
 /** Default max chars for dependency context in formatDependencyContext and level-2 prompts. */
 export const DEPENDENCY_CONTEXT_MAX_CHARS = 6000;

package/auto-docs/openapi/generator.js

@@ -39,7 +39,7 @@ async function generateOpenAPISpec(registry, options = {}) {
     logger = null,
   } = options;
   const targets = registry?.targets ?? [];
-  const paths = {};
+  const paths = Object.create(null);
   const groupEndpoints = new Map();
   const dependencyContextByGroup = new Map();
 
@@ -71,10 +71,12 @@ async function generateOpenAPISpec(registry, options = {}) {
   );
   applyTagDisplayNames(paths, tagDescriptions);
 
-  const tags = Array.from(tagDescriptions.entries()).map(([, { name, description }]) => ({
-    name,
-    ...(description && { description }),
-  }));
+  const tags = Array.from(tagDescriptions.entries()).map(
+    ([, { name, description }]) => ({
+      name,
+      ...(description && { description }),
+    }),
+  );
 
   const spec = {
     openapi: OPENAPI_VERSION,

package/auto-docs/openapi/generator.test.js

@@ -0,0 +1,132 @@
+/**
+ * Unit tests for auto-docs openapi/generator pure functions.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  toOpenAPIPath,
+  getPathParameters,
+  getQueryParameters,
+  buildSchemaFromMetadata,
+  buildResponses,
+  buildOperation,
+  mergeMetadata,
+} from './generator.js';
+
+describe('openapi-generator', () => {
+  describe('toOpenAPIPath', () => {
+    it('converts :param to {param}', () => {
+      expect(toOpenAPIPath('/users/:id')).toBe('/users/{id}');
+    });
+    it('converts multiple params', () => {
+      expect(toOpenAPIPath('/users/:userId/posts/:postId')).toBe(
+        '/users/{userId}/posts/{postId}',
+      );
+    });
+    it('returns / for empty or non-string', () => {
+      expect(toOpenAPIPath('')).toBe('/');
+      expect(toOpenAPIPath(null)).toBe('/');
+    });
+  });
+
+  describe('getPathParameters', () => {
+    it('extracts path params from te.js path', () => {
+      const params = getPathParameters('/users/:id');
+      expect(params).toHaveLength(1);
+      expect(params[0]).toMatchObject({
+        name: 'id',
+        in: 'path',
+        required: true,
+        schema: { type: 'string' },
+      });
+    });
+    it('returns empty array for path without params', () => {
+      expect(getPathParameters('/users')).toEqual([]);
+    });
+  });
+
+  describe('getQueryParameters', () => {
+    it('builds query params from metadata', () => {
+      const queryMeta = {
+        limit: { type: 'integer', required: false },
+        q: { type: 'string', required: true },
+      };
+      const params = getQueryParameters(queryMeta);
+      expect(params).toHaveLength(2);
+      expect(params.find((p) => p.name === 'limit')).toMatchObject({
+        in: 'query',
+        required: false,
+      });
+      expect(params.find((p) => p.name === 'q')).toMatchObject({
+        in: 'query',
+        required: true,
+      });
+    });
+    it('returns empty array for invalid meta', () => {
+      expect(getQueryParameters(null)).toEqual([]);
+    });
+  });
+
+  describe('buildSchemaFromMetadata', () => {
+    it('builds OpenAPI schema from field meta', () => {
+      const meta = {
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email', required: true },
+      };
+      const schema = buildSchemaFromMetadata(meta);
+      expect(schema.type).toBe('object');
+      expect(schema.properties.name.type).toBe('string');
+      expect(schema.properties.email.format).toBe('email');
+      expect(schema.required).toContain('email');
+    });
+  });
+
+  describe('buildResponses', () => {
+    it('returns 200 Success when responseMeta empty', () => {
+      const r = buildResponses(null);
+      expect(r['200']).toEqual({ description: 'Success' });
+    });
+    it('builds responses from metadata', () => {
+      const meta = {
+        200: { description: 'OK' },
+        201: { description: 'Created' },
+      };
+      const r = buildResponses(meta);
+      expect(r['200'].description).toBe('OK');
+      expect(r['201'].description).toBe('Created');
+    });
+  });
+
+  describe('buildOperation', () => {
+    it('builds operation with summary and responses', () => {
+      const meta = {
+        summary: 'Get user',
+        response: { 200: { description: 'OK' } },
+      };
+      const pathParams = [];
+      const op = buildOperation('get', meta, pathParams);
+      expect(op.summary).toBe('Get user');
+      expect(op.responses['200'].description).toBe('OK');
+    });
+  });
+
+  describe('mergeMetadata', () => {
+    it('prefers explicit when preferEnhanced false', () => {
+      const explicit = { summary: 'A', description: 'B' };
+      const enhanced = { summary: 'C', description: 'D' };
+      const merged = mergeMetadata(explicit, enhanced, {
+        preferEnhanced: false,
+      });
+      expect(merged.summary).toBe('A');
+      expect(merged.description).toBe('B');
+    });
+    it('prefers enhanced when preferEnhanced true', () => {
+      const explicit = { summary: 'A' };
+      const enhanced = { summary: 'C', description: 'D' };
+      const merged = mergeMetadata(explicit, enhanced, {
+        preferEnhanced: true,
+      });
+      expect(merged.summary).toBe('C');
+      expect(merged.description).toBe('D');
+    });
+  });
+});

package/auto-docs/openapi/spec-builders.js

@@ -16,7 +16,12 @@ export function isMethodKeyed(obj) {
   for (const key of Object.keys(obj)) {
     if (METHOD_KEYS.has(key.toLowerCase())) {
       const val = obj[key];
-      if (val && typeof val === 'object' && (val.summary != null || val.response != null)) return true;
+      if (
+        val &&
+        typeof val === 'object' &&
+        (val.summary != null || val.response != null)
+      )
+        return true;
     }
   }
   return false;
@@ -82,7 +87,7 @@ export function getQueryParameters(queryMeta) {
  */
 export function buildSchemaFromMetadata(meta) {
   if (!meta || typeof meta !== 'object') return {};
-  const properties = {};
+  const properties = Object.create(null);
   const required = [];
   for (const [key, value] of Object.entries(meta)) {
     if (value && typeof value === 'object' && value.type) {
@@ -91,7 +96,8 @@ export function buildSchemaFromMetadata(meta) {
         ...(value.description && { description: value.description }),
         ...(value.format && { format: value.format }),
       };
-      if (value.required === true || value.required === 'true') required.push(key);
+      if (value.required === true || value.required === 'true')
+        required.push(key);
     }
   }
   if (Object.keys(properties).length === 0) return {};
@@ -108,7 +114,8 @@ export function buildSchemaFromMetadata(meta) {
  * @returns {object|undefined} OpenAPI requestBody or undefined
  */
 export function buildRequestBody(requestMeta) {
-  if (!requestMeta?.body || typeof requestMeta.body !== 'object') return undefined;
+  if (!requestMeta?.body || typeof requestMeta.body !== 'object')
+    return undefined;
   const schema = buildSchemaFromMetadata(requestMeta.body);
   if (!schema || Object.keys(schema).length === 0) return undefined;
   return {
@@ -127,7 +134,7 @@ export function buildRequestBody(requestMeta) {
  * @returns {object} OpenAPI responses
  */
 export function buildResponses(responseMeta) {
-  const responses = {};
+  const responses = Object.create(null);
   if (!responseMeta || typeof responseMeta !== 'object') {
     responses['200'] = { description: 'Success' };
     return responses;
@@ -139,9 +146,10 @@ export function buildResponses(responseMeta) {
       ...(spec.schema && {
         content: {
           'application/json': {
-            schema: typeof spec.schema === 'object' && spec.schema.type
-              ? spec.schema
-              : { type: 'object' },
+            schema:
+              typeof spec.schema === 'object' && spec.schema.type
+                ? spec.schema
+                : { type: 'object' },
           },
         },
       }),
@@ -159,7 +167,8 @@ export function buildResponses(responseMeta) {
  * @returns {boolean}
  */
 export function isMethodAgnostic(methods) {
-  if (!Array.isArray(methods) || methods.length !== ALL_METHODS.length) return false;
+  if (!Array.isArray(methods) || methods.length !== ALL_METHODS.length)
+    return false;
   const set = new Set(methods.map((m) => m.toUpperCase()));
   return ALL_METHODS.every((m) => set.has(m));
 }
@@ -190,7 +199,10 @@ export function buildOperation(method, meta, pathParams, options = {}) {
   };
   const methodUpper = method.toUpperCase();
   const body = buildRequestBody(meta.request);
-  if (body && (methodAgnostic || (methodUpper !== 'GET' && methodUpper !== 'HEAD'))) {
+  if (
+    body &&
+    (methodAgnostic || (methodUpper !== 'GET' && methodUpper !== 'HEAD'))
+  ) {
     op.requestBody = body;
   }
   op.responses = buildResponses(meta.response);
@@ -207,17 +219,17 @@ export function buildOperation(method, meta, pathParams, options = {}) {
 export function mergeMetadata(explicit, enhanced, options = {}) {
   const preferEnhanced = options.preferEnhanced === true;
   const summary = preferEnhanced
-    ? (enhanced?.summary ?? explicit?.summary ?? '')
-    : (explicit?.summary ?? enhanced?.summary ?? '');
+    ? enhanced?.summary ?? explicit?.summary ?? ''
+    : explicit?.summary ?? enhanced?.summary ?? '';
   const description = preferEnhanced
-    ? (enhanced?.description ?? explicit?.description ?? '')
-    : (explicit?.description ?? enhanced?.description ?? '');
+    ? enhanced?.description ?? explicit?.description ?? ''
+    : explicit?.description ?? enhanced?.description ?? '';
   const request = preferEnhanced
-    ? (enhanced?.request ?? explicit?.request)
-    : (explicit?.request ?? enhanced?.request);
+    ? enhanced?.request ?? explicit?.request
+    : explicit?.request ?? enhanced?.request;
   const response = preferEnhanced
-    ? (enhanced?.response ?? explicit?.response)
-    : (explicit?.response ?? enhanced?.response);
+    ? enhanced?.response ?? explicit?.response
+    : explicit?.response ?? enhanced?.response;
   return {
     summary: summary || 'Endpoint',
     description: description || undefined,
@@ -234,7 +246,15 @@ export function mergeMetadata(explicit, enhanced, options = {}) {
  * @returns {object}
  */
 export function mergeMethodAgnosticMeta(metaByMethod, methods, fallbackMeta) {
-  const preferredOrder = ['post', 'put', 'patch', 'get', 'delete', 'head', 'options'];
+  const preferredOrder = [
+    'post',
+    'put',
+    'patch',
+    'get',
+    'delete',
+    'head',
+    'options',
+  ];
   for (const k of preferredOrder) {
     const m = metaByMethod.get(k);
     if (m && (m.summary || m.description)) return m;

package/cli/docs-command.js

@@ -32,25 +32,25 @@ function mask(value) {
 
 function ask(question, fallback = '') {
   const hint = fallback ? c.dim(` (${fallback})`) : '';
-  return new Promise((resolve) => {
-    rl.question(`${c.cyan('?')} ${question}${hint}${c.dim(': ')}`, (answer) => {
-      resolve(answer.trim() || fallback);
-    });
+  const { promise, resolve } = Promise.withResolvers();
+  rl.question(`${c.cyan('?')} ${question}${hint}${c.dim(': ')}`, (answer) => {
+    resolve(answer.trim() || fallback);
   });
+  return promise;
 }
 
 function askYesNo(question, fallback = false) {
   const hint = fallback ? 'Y/n' : 'y/N';
-  return new Promise((resolve) => {
-    rl.question(
-      `${c.cyan('?')} ${question} ${c.dim(`(${hint})`)}${c.dim(': ')}`,
-      (answer) => {
-        const val = answer.trim().toLowerCase();
-        if (!val) return resolve(fallback);
-        resolve(val === 'y' || val === 'yes');
-      },
-    );
-  });
+  const { promise, resolve } = Promise.withResolvers();
+  rl.question(
+    `${c.cyan('?')} ${question} ${c.dim(`(${hint})`)}${c.dim(': ')}`,
+    (answer) => {
+      const val = answer.trim().toLowerCase();
+      if (!val) return resolve(fallback);
+      resolve(val === 'y' || val === 'yes');
+    },
+  );
+  return promise;
 }
 
 async function loadTargetFiles(dirTargets = 'targets') {
@@ -88,13 +88,15 @@ async function loadTargetFiles(dirTargets = 'targets') {
 function getDocsOptionsFromConfig(config = {}) {
   const docs = config.docs || config.generateDocs || {};
   const e = process.env;
-  const baseURL = docs.llm?.baseURL ?? e.LLM_BASE_URL ?? 'https://api.openai.com/v1';
+  const baseURL =
+    docs.llm?.baseURL ?? e.LLM_BASE_URL ?? 'https://api.openai.com/v1';
   const apiKey = docs.llm?.apiKey ?? e.LLM_API_KEY ?? e.OPENAI_API_KEY;
   const model = docs.llm?.model ?? e.LLM_MODEL ?? 'gpt-4o-mini';
   if (!apiKey && !e.OPENAI_API_KEY) {
     return null;
   }
-  const dirTargets = docs.dirTargets ?? docs.dir?.targets ?? config.dir?.targets ?? 'targets';
+  const dirTargets =
+    docs.dirTargets ?? docs.dir?.targets ?? config.dir?.targets ?? 'targets';
   const output = docs.output ?? './openapi.json';
   const title = docs.title ?? 'API';
   const version = docs.version ?? '1.0.0';
@@ -116,7 +118,7 @@ function getDocsOptionsFromConfig(config = {}) {
  * @returns {Promise<void>}
  */
 export async function runDocsCommandCI() {
-  const config = loadConfigFile();
+  const config = await loadConfigFile();
   const options = getDocsOptionsFromConfig(config);
   if (!options) {
     console.error(
@@ -128,7 +130,9 @@ export async function runDocsCommandCI() {
   process.stdout.write(`${c.yellow('⏳')} Loading targets...`);
   const fileCount = await loadTargetFiles(dirTargets);
   const endpointCount = targetRegistry.targets?.length ?? 0;
-  process.stdout.write(`\r${c.green('✓')} Loaded ${c.bold(fileCount)} target file(s) — ${c.bold(endpointCount)} endpoint(s)\n`);
+  process.stdout.write(
+    `\r${c.green('✓')} Loaded ${c.bold(fileCount)} target file(s) — ${c.bold(endpointCount)} endpoint(s)\n`,
+  );
   if (endpointCount === 0) {
     console.log(c.yellow('  No endpoints found. Skipping doc generation.\n'));
     return;
@@ -156,19 +160,19 @@ export async function runDocsCommandCI() {
  * @returns {Promise<string[]>} e.g. ['refs/heads/main', 'refs/heads/feature/x']
  */
 function readPrePushRefs() {
-  return new Promise((resolve) => {
-    const chunks = [];
-    stdin.on('data', (chunk) => chunks.push(chunk));
-    stdin.on('end', () => {
-      const lines = Buffer.concat(chunks).toString('utf8').trim().split('\n');
-      const refs = [];
-      for (let i = 0; i < lines.length; i++) {
-        const parts = lines[i].split(/\s+/);
-        if (parts.length >= 4) refs.push(parts[2]); // remote_ref
-      }
-      resolve(refs);
-    });
+  const { promise, resolve } = Promise.withResolvers();
+  const chunks = [];
+  stdin.on('data', (chunk) => chunks.push(chunk));
+  stdin.on('end', () => {
+    const lines = Buffer.concat(chunks).toString('utf8').trim().split('\n');
+    const refs = [];
+    for (let i = 0; i < lines.length; i++) {
+      const parts = lines[i].split(/\s+/);
+      if (parts.length >= 4) refs.push(parts[2]);
+    }
+    resolve(refs);
   });
+  return promise;
 }
 
 /**
@@ -178,7 +182,7 @@ function readPrePushRefs() {
  * Configure via tejas.config.json docs.productionBranch or env DOCS_PRODUCTION_BRANCH (default: main).
  */
 export async function runDocsOnPush() {
-  const config = loadConfigFile();
+  const config = await loadConfigFile();
   const docs = config.docs || config.generateDocs || {};
   const productionBranch =
     docs.productionBranch ?? process.env.DOCS_PRODUCTION_BRANCH ?? 'main';
@@ -186,7 +190,11 @@ export async function runDocsOnPush() {
   const productionRef = `refs/heads/${productionBranch}`;
   const isPushingToProduction = remoteRefs.some((ref) => ref === productionRef);
   if (!isPushingToProduction) return;
-  console.log(c.dim(`  Docs: pushing to ${productionBranch} — generating documentation...\n`));
+  console.log(
+    c.dim(
+      `  Docs: pushing to ${productionBranch} — generating documentation...\n`,
+    ),
+  );
   await runDocsCommandCI();
 }
 
@@ -207,13 +215,13 @@ function serveDocsPreview(spec, port = 3333) {
     res.writeHead(404);
     res.end('Not found');
   });
-  return new Promise((resolve) => {
-    server.listen(port, () => resolve(server));
-  });
+  const { promise, resolve } = Promise.withResolvers();
+  server.listen(port, () => resolve(server));
+  return promise;
 }
 
 export async function runDocsCommand() {
-  const config = loadConfigFile();
+  const config = await loadConfigFile();
   const e = process.env;
 
   console.log();