te.js 2.0.3 → 2.1.1

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

@@ -1,101 +1,101 @@
-/**
- * Resolves downstream dependency sources for level-2 documentation (handler + deps context).
- * Reads a target file, extracts relative imports, and returns their source code.
- */
-
-import { readFile } from 'node:fs/promises';
-import path from 'node:path';
-import { DEPENDENCY_CONTEXT_MAX_CHARS } from '../constants.js';
-
-/** Match ES module imports: import x from './...' or import { x } from '../...' or import '...' */
-const IMPORT_REGEX = /import\s+(?:(?:\{[^}]*\}|\w+)(?:\s*,\s*(?:\{[^}]*\}|\w+))*\s+from\s+)?['"]([^'"]+)['"]/g;
-
-/**
- * Extract import specifiers that are relative paths (./ or ../).
- * @param {string} source - File source code
- * @returns {string[]} Relative paths (e.g. ['../services/user.service.js'])
- */
-function extractRelativeImports(source) {
-  const out = [];
-  let match;
-  IMPORT_REGEX.lastIndex = 0;
-  while ((match = IMPORT_REGEX.exec(source)) !== null) {
-    const spec = match[1];
-    if (spec.startsWith('./') || spec.startsWith('../')) {
-      out.push(spec);
-    }
-  }
-  return [...new Set(out)];
-}
-
-/**
- * Resolve target file path from groupId and DIR_TARGETS.
- * @param {string} groupId - e.g. 'users' or 'subdir/users'
- * @param {string} dirTargets - e.g. 'targets'
- * @returns {string} Absolute path to the target file
- */
-function resolveTargetFilePath(groupId, dirTargets = 'targets') {
-  const baseDir = path.join(process.cwd(), dirTargets);
-  const relative = groupId.replace(/\//g, path.sep) + '.target.js';
-  return path.join(baseDir, relative);
-}
-
-/**
- * Read a target file and all its relative-import dependencies (one level deep).
- * @param {string} groupId - Source group id (e.g. 'users')
- * @param {string} [dirTargets] - DIR_TARGETS (default from process.env or 'targets')
- * @returns {Promise<Map<string, string>>} Map of absolute file path -> source code
- */
-export async function resolveDependencySources(groupId, dirTargets = process.env.DIR_TARGETS || 'targets') {
-  const targetPath = resolveTargetFilePath(groupId, dirTargets);
-  const result = new Map();
-
-  let targetSource;
-  try {
-    targetSource = await readFile(targetPath, 'utf8');
-  } catch {
-    return result;
-  }
-
-  result.set(targetPath, targetSource);
-  const targetDir = path.dirname(targetPath);
-  const relativeImports = extractRelativeImports(targetSource);
-
-  for (const rel of relativeImports) {
-    const resolvedPath = path.resolve(targetDir, rel);
-    try {
-      const code = await readFile(resolvedPath, 'utf8');
-      result.set(resolvedPath, code);
-    } catch {
-      // Skip missing or unreadable files
-    }
-  }
-
-  return result;
-}
-
-/**
- * Format resolved dependency sources as a single string for LLM context.
- * @param {Map<string, string>} sources - Map of file path -> source
- * @param {string} [targetPath] - Path to the target file (excluded from "dependencies" label)
- * @param {number} [maxChars] - Max total characters to include (default: DEPENDENCY_CONTEXT_MAX_CHARS)
- * @returns {string}
- */
-export function formatDependencyContext(sources, targetPath, maxChars = DEPENDENCY_CONTEXT_MAX_CHARS) {
-  if (!sources || sources.size === 0) return '';
-  const lines = [];
-  let total = 0;
-  for (const [filePath, code] of sources) {
-    const label = filePath === targetPath ? 'Target' : path.relative(process.cwd(), filePath);
-    const block = `\n// --- ${label} ---\n${code}`;
-    if (total + block.length > maxChars) {
-      lines.push(block.slice(0, maxChars - total) + '\n// ... (truncated)');
-      break;
-    }
-    lines.push(block);
-    total += block.length;
-  }
-  return lines.join('\n');
-}
-
-export { extractRelativeImports, resolveTargetFilePath };
+/**
+ * Resolves downstream dependency sources for level-2 documentation (handler + deps context).
+ * Reads a target file, extracts relative imports, and returns their source code.
+ */
+
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { DEPENDENCY_CONTEXT_MAX_CHARS } from '../constants.js';
+
+/** Match ES module imports: import x from './...' or import { x } from '../...' or import '...' */
+const IMPORT_REGEX = /import\s+(?:(?:\{[^}]*\}|\w+)(?:\s*,\s*(?:\{[^}]*\}|\w+))*\s+from\s+)?['"]([^'"]+)['"]/g;
+
+/**
+ * Extract import specifiers that are relative paths (./ or ../).
+ * @param {string} source - File source code
+ * @returns {string[]} Relative paths (e.g. ['../services/user.service.js'])
+ */
+function extractRelativeImports(source) {
+  const out = [];
+  let match;
+  IMPORT_REGEX.lastIndex = 0;
+  while ((match = IMPORT_REGEX.exec(source)) !== null) {
+    const spec = match[1];
+    if (spec.startsWith('./') || spec.startsWith('../')) {
+      out.push(spec);
+    }
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Resolve target file path from groupId and DIR_TARGETS.
+ * @param {string} groupId - e.g. 'users' or 'subdir/users'
+ * @param {string} dirTargets - e.g. 'targets'
+ * @returns {string} Absolute path to the target file
+ */
+function resolveTargetFilePath(groupId, dirTargets = 'targets') {
+  const baseDir = path.join(process.cwd(), dirTargets);
+  const relative = groupId.replace(/\//g, path.sep) + '.target.js';
+  return path.join(baseDir, relative);
+}
+
+/**
+ * Read a target file and all its relative-import dependencies (one level deep).
+ * @param {string} groupId - Source group id (e.g. 'users')
+ * @param {string} [dirTargets] - DIR_TARGETS (default from process.env or 'targets')
+ * @returns {Promise<Map<string, string>>} Map of absolute file path -> source code
+ */
+export async function resolveDependencySources(groupId, dirTargets = process.env.DIR_TARGETS || 'targets') {
+  const targetPath = resolveTargetFilePath(groupId, dirTargets);
+  const result = new Map();
+
+  let targetSource;
+  try {
+    targetSource = await readFile(targetPath, 'utf8');
+  } catch {
+    return result;
+  }
+
+  result.set(targetPath, targetSource);
+  const targetDir = path.dirname(targetPath);
+  const relativeImports = extractRelativeImports(targetSource);
+
+  for (const rel of relativeImports) {
+    const resolvedPath = path.resolve(targetDir, rel);
+    try {
+      const code = await readFile(resolvedPath, 'utf8');
+      result.set(resolvedPath, code);
+    } catch {
+      // Skip missing or unreadable files
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Format resolved dependency sources as a single string for LLM context.
+ * @param {Map<string, string>} sources - Map of file path -> source
+ * @param {string} [targetPath] - Path to the target file (excluded from "dependencies" label)
+ * @param {number} [maxChars] - Max total characters to include (default: DEPENDENCY_CONTEXT_MAX_CHARS)
+ * @returns {string}
+ */
+export function formatDependencyContext(sources, targetPath, maxChars = DEPENDENCY_CONTEXT_MAX_CHARS) {
+  if (!sources || sources.size === 0) return '';
+  const lines = [];
+  let total = 0;
+  for (const [filePath, code] of sources) {
+    const label = filePath === targetPath ? 'Target' : path.relative(process.cwd(), filePath);
+    const block = `\n// --- ${label} ---\n${code}`;
+    if (total + block.length > maxChars) {
+      lines.push(block.slice(0, maxChars - total) + '\n// ... (truncated)');
+      break;
+    }
+    lines.push(block);
+    total += block.length;
+  }
+  return lines.join('\n');
+}
+
+export { extractRelativeImports, resolveTargetFilePath };

package/auto-docs/constants.js

@@ -1,37 +1,37 @@
-/**
- * Shared constants for auto-documentation.
- * Centralizes OpenAPI version, method keys, and token/character limits.
- */
-
-/** OpenAPI 3.0 version string */
-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']);
-
-/** 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 };
-
-/** Default max chars for dependency context in formatDependencyContext and level-2 prompts. */
-export const DEPENDENCY_CONTEXT_MAX_CHARS = 6000;
-
-/** Max handler source chars in single-endpoint enhance prompts (no deps). */
-export const PROMPT_HANDLER_SLICE = 3000;
-
-/** Max handler source chars in single-endpoint enhance prompts (with deps). */
-export const PROMPT_HANDLER_SLICE_WITH_DEPS = 4000;
-
-/** Max dependency source chars included in enhance/summarize prompts. */
-export const PROMPT_DEPENDENCY_SLICE = 5000;
-
-/** Max total code chars in group-summary prompt when no dependency context. */
-export const PROMPT_GROUP_CODE_LIMIT = 4000;
-
-/** Max total code chars in group-summary prompt when dependency context is present. */
-export const PROMPT_GROUP_CODE_LIMIT_WITH_DEPS = 6000;
-
-/** Max handler source chars per endpoint in group-summary code snippets. */
-export const PROMPT_GROUP_SNIPPET_CHARS = 800;
+/**
+ * Shared constants for auto-documentation.
+ * Centralizes OpenAPI version, method keys, and token/character limits.
+ */
+
+/** OpenAPI 3.0 version string */
+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']);
+
+/** 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 };
+
+/** Default max chars for dependency context in formatDependencyContext and level-2 prompts. */
+export const DEPENDENCY_CONTEXT_MAX_CHARS = 6000;
+
+/** Max handler source chars in single-endpoint enhance prompts (no deps). */
+export const PROMPT_HANDLER_SLICE = 3000;
+
+/** Max handler source chars in single-endpoint enhance prompts (with deps). */
+export const PROMPT_HANDLER_SLICE_WITH_DEPS = 4000;
+
+/** Max dependency source chars included in enhance/summarize prompts. */
+export const PROMPT_DEPENDENCY_SLICE = 5000;
+
+/** Max total code chars in group-summary prompt when no dependency context. */
+export const PROMPT_GROUP_CODE_LIMIT = 4000;
+
+/** Max total code chars in group-summary prompt when dependency context is present. */
+export const PROMPT_GROUP_CODE_LIMIT_WITH_DEPS = 6000;
+
+/** Max handler source chars per endpoint in group-summary code snippets. */
+export const PROMPT_GROUP_SNIPPET_CHARS = 800;

package/auto-docs/docs-llm/index.js

@@ -0,0 +1,7 @@
+/**
+ * LLM provider for auto-documentation (docs-specific).
+ * Use createProvider(config) with baseURL, apiKey, model.
+ * For the generic LLM client only, use lib/llm.
+ */
+
+export { LLMProvider, createProvider, extractJSON, extractJSONArray, reconcileOrderedTags } from './provider.js';