@workos/oagen-emitters 0.12.1 → 0.12.2

package/src/node/live-surface.ts

@@ -0,0 +1,378 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+/**
+ * Snapshot of the live target SDK gathered by walking `--output` once.
+ *
+ * Replaces the heavier `--api-surface` extract step for the Node emitter.
+ * Only declaration *names* are extracted (regex-based, no AST). That is
+ * enough to drive "skip if already present" filtering in models, resources,
+ * and serializers.
+ */
+export interface LiveSurface {
+  /** Absolute root the surface was built from (e.g. workos-node repo root). */
+  rootDir: string;
+  /** Set of file paths (relative to rootDir, POSIX separators) that exist on disk. */
+  files: Set<string>;
+  /**
+   * Git-tracked paths under the SDK root.
+   *
+   * When non-empty, this is the canonical baseline surface for "existing SDK"
+   * decisions. It excludes prior bad generations that left untracked files in
+   * the tree, which lets the emitter stop re-emitting that junk so manifest
+   * pruning can clean it up on the next run.
+   */
+  trackedFiles: Set<string>;
+  /** Files marked `@oagen-ignore-file`: never emit on top of these. */
+  protectedFiles: Set<string>;
+  /**
+   * Files whose first lines contain the `auto-generated by oagen` header.
+   * These were produced by a prior generation and should be regenerated when
+   * the spec changes (e.g. parameter renames). Letting the engine see them
+   * in the new output list is what enables that update path — dropping them
+   * would freeze them at their last-generated content.
+   */
+  autogenFiles: Set<string>;
+  /** Class name → relative file path. */
+  classes: Map<string, ClassInfo>;
+  /** Interface or type-alias name → relative file path. */
+  interfaces: Map<string, InterfaceInfo>;
+  /** Function name → relative file path (for serializers, helpers). */
+  functions: Map<string, string>;
+  /**
+   * `export const X = {...} as const` declarations on disk → ordered
+   * member-name → literal-value mapping. Used by `enums.ts` to preserve
+   * acronym casing (e.g. `DSync: 'dsync'`) on regeneration; without this,
+   * `toPascalCase('dsync')` would emit `Dsync` and silently break call
+   * sites that referenced `EnumName.DSync`.
+   */
+  constObjectEnums: Map<string, Map<string, string>>;
+}
+
+export interface ClassInfo {
+  filePath: string;
+  methods: Set<string>;
+}
+
+export interface InterfaceInfo {
+  filePath: string;
+  fields: Set<string>;
+}
+
+const SRC_DIR = 'src';
+
+/**
+ * Walk `${rootDir}/src/` and build a live-surface snapshot.
+ *
+ * If `${rootDir}/src/` does not exist, returns an empty surface (greenfield).
+ * Reads each `.ts` file once; ignores `.spec.ts` and `.test.ts`.
+ */
+export function buildLiveSurface(rootDir: string): LiveSurface {
+  const surface: LiveSurface = {
+    rootDir,
+    files: new Set(),
+    trackedFiles: loadGitTrackedFiles(rootDir),
+    protectedFiles: new Set(),
+    autogenFiles: new Set(),
+    classes: new Map(),
+    interfaces: new Map(),
+    functions: new Map(),
+    constObjectEnums: new Map(),
+  };
+
+  const srcRoot = path.join(rootDir, SRC_DIR);
+  if (!fs.existsSync(srcRoot) || !fs.statSync(srcRoot).isDirectory()) {
+    return surface;
+  }
+
+  for (const absPath of walk(srcRoot)) {
+    const rel = toPosix(path.relative(rootDir, absPath));
+    surface.files.add(rel);
+    if (!rel.endsWith('.ts')) continue;
+    if (surface.trackedFiles.size > 0 && !surface.trackedFiles.has(rel)) continue;
+
+    let text: string;
+    try {
+      text = fs.readFileSync(absPath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    if (isProtected(text)) {
+      surface.protectedFiles.add(rel);
+    } else if (isAutogen(text)) {
+      surface.autogenFiles.add(rel);
+    }
+
+    if (rel.endsWith('.spec.ts') || rel.endsWith('.test.ts')) continue;
+
+    extractDeclarations(text, rel, surface);
+  }
+
+  return surface;
+}
+
+/**
+ * Module-level snapshot of the active live-surface, set by `index.ts` once per
+ * generation run. Used by callers that don't have a clean way to thread
+ * `EmitterContext` through (e.g. deeply-nested helpers in `resources.ts`
+ * that decide whether to inline a serializer call).
+ */
+let activeSurface: LiveSurface | null = null;
+export function setActiveLiveSurface(surface: LiveSurface): void {
+  activeSurface = surface;
+}
+export function liveSurfaceHasFunction(name: string): boolean {
+  return activeSurface?.functions.has(name) ?? false;
+}
+/** Returns the relative file path containing the function, if known. */
+export function liveSurfaceFunctionPath(name: string): string | undefined {
+  return activeSurface?.functions.get(name);
+}
+export function liveSurfaceHasFile(relPath: string): boolean {
+  return activeSurface?.files.has(relPath) ?? false;
+}
+export function liveSurfaceHasManagedFile(relPath: string): boolean {
+  const surface = activeSurface;
+  if (!surface) return false;
+  const managedPaths = surface.trackedFiles.size > 0 ? surface.trackedFiles : surface.files;
+  return managedPaths.has(relPath);
+}
+export function liveSurfaceHasAutogenFile(relPath: string): boolean {
+  return activeSurface?.autogenFiles.has(relPath) ?? false;
+}
+export function liveSurfaceHasExistingSdk(): boolean {
+  const surface = activeSurface;
+  if (!surface) return false;
+  const managedPaths = surface.trackedFiles.size > 0 ? surface.trackedFiles : surface.files;
+  return managedPaths.size > 0;
+}
+
+/** Empty surface — used as a default when no outputDir is available. */
+export function emptyLiveSurface(): LiveSurface {
+  return {
+    rootDir: '',
+    files: new Set(),
+    trackedFiles: new Set(),
+    protectedFiles: new Set(),
+    autogenFiles: new Set(),
+    classes: new Map(),
+    interfaces: new Map(),
+    functions: new Map(),
+    constObjectEnums: new Map(),
+  };
+}
+
+/** Returns the existing member-name → value map for a const-object enum, if any. */
+export function liveSurfaceConstEnumMembers(name: string): Map<string, string> | undefined {
+  return activeSurface?.constObjectEnums.get(name);
+}
+export function liveSurfaceInterfacePath(name: string): string | undefined {
+  return activeSurface?.interfaces.get(name)?.filePath;
+}
+
+/** Should the emitter avoid writing this relative path on disk? */
+export function shouldSkipPath(surface: LiveSurface, relPath: string): boolean {
+  return surface.protectedFiles.has(relPath);
+}
+
+/** Does the live SDK already contain a file at this relative path? */
+export function pathExists(surface: LiveSurface, relPath: string): boolean {
+  return surface.files.has(relPath);
+}
+
+function* walk(dir: string): Generator<string> {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      yield* walk(abs);
+    } else if (entry.isFile()) {
+      yield abs;
+    }
+  }
+}
+
+function toPosix(p: string): string {
+  return p.split(path.sep).join('/');
+}
+
+function loadGitTrackedFiles(rootDir: string): Set<string> {
+  try {
+    const stdout = execFileSync('git', ['-C', rootDir, 'ls-files', '--', 'src'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return new Set(
+      stdout
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map(toPosix),
+    );
+  } catch {
+    return new Set();
+  }
+}
+
+function isProtected(text: string): boolean {
+  // Look in the first 800 chars only — markers belong at file top.
+  const head = text.slice(0, 800);
+  return /@oagen-ignore-file\b/.test(head);
+}
+
+function isAutogen(text: string): boolean {
+  // Same locality assumption — the auto-generated header is always at top.
+  const head = text.slice(0, 400);
+  return /auto-generated by oagen/i.test(head);
+}
+
+const CLASS_RE = /^\s*export\s+(?:abstract\s+)?class\s+([A-Z][\w$]*)/gm;
+const INTERFACE_RE = /^\s*export\s+interface\s+([A-Z][\w$]*)/gm;
+const TYPE_ALIAS_RE = /^\s*export\s+type\s+([A-Z][\w$]*)\s*=/gm;
+// Picks up both standard declarations (`export function deserializeX(...)`)
+// and arrow-style consts (`export const deserializeX = (...) =>`). The
+// latter is the workos-node house style for serializers, including the
+// generic-arrow form `export const deserializeProfile = <T extends ...>(`.
+const FUNCTION_RE = /^\s*export\s+(?:async\s+)?function\s+([a-zA-Z_$][\w$]*)/gm;
+const CONST_FN_RE = /^\s*export\s+const\s+([a-zA-Z_$][\w$]*)\s*(?::\s*[^=]+)?=\s*(?:async\s+)?(?:<[^>]*>\s*)?\(/gm;
+// For methods, match a class member declaration (rough — picks up async + plain methods).
+const METHOD_RE =
+  /^\s{2,}(?:public\s+|private\s+|protected\s+|readonly\s+)*(?:async\s+)?([a-zA-Z_$][\w$]*)\s*(?:<[^>]*>)?\s*\(/gm;
+
+function extractDeclarations(text: string, relPath: string, surface: LiveSurface): void {
+  // Classes
+  for (const m of text.matchAll(CLASS_RE)) {
+    const name = m[1];
+    const body = sliceClassBody(text, m.index ?? 0);
+    const methods = new Set<string>();
+    if (body) {
+      for (const mm of body.matchAll(METHOD_RE)) {
+        const methodName = mm[1];
+        // Filter out keywords accidentally captured.
+        if (METHOD_KEYWORD_BLOCKLIST.has(methodName)) continue;
+        methods.add(methodName);
+      }
+    }
+    surface.classes.set(name, { filePath: relPath, methods });
+  }
+
+  // Interfaces
+  for (const m of text.matchAll(INTERFACE_RE)) {
+    const name = m[1];
+    const fields = extractInterfaceFields(text, m.index ?? 0);
+    surface.interfaces.set(name, { filePath: relPath, fields });
+  }
+
+  // Type aliases (treated as interfaces for skip purposes; field set is empty).
+  for (const m of text.matchAll(TYPE_ALIAS_RE)) {
+    const name = m[1];
+    if (!surface.interfaces.has(name)) {
+      surface.interfaces.set(name, { filePath: relPath, fields: new Set() });
+    }
+  }
+
+  // Top-level exported functions (both `function` and arrow-const styles).
+  for (const m of text.matchAll(FUNCTION_RE)) {
+    surface.functions.set(m[1], relPath);
+  }
+  for (const m of text.matchAll(CONST_FN_RE)) {
+    surface.functions.set(m[1], relPath);
+  }
+
+  // `export const X = { Member: 'value', ... } as const;` — capture the
+  // member-name → literal-value mapping so enum regeneration can preserve
+  // existing casing (e.g. `DSync: 'dsync'` instead of `Dsync: 'dsync'`).
+  for (const m of text.matchAll(CONST_OBJECT_ENUM_RE)) {
+    const enumName = m[1];
+    const body = m[2];
+    const members = new Map<string, string>();
+    for (const memberMatch of body.matchAll(CONST_OBJECT_MEMBER_RE)) {
+      const memberName = memberMatch[1] ?? memberMatch[2] ?? memberMatch[3];
+      const value = memberMatch[4];
+      if (memberName && value !== undefined) {
+        members.set(value, memberName);
+      }
+    }
+    if (members.size > 0) {
+      surface.constObjectEnums.set(enumName, members);
+    }
+  }
+}
+
+// `export const X = { ... } as const`
+const CONST_OBJECT_ENUM_RE = /^\s*export\s+const\s+([A-Z][\w$]*)\s*=\s*\{([\s\S]*?)\}\s*as\s+const\s*;/gm;
+// Member entries inside the object body — supports unquoted, single-quoted,
+// and double-quoted keys. Captures key (group 1/2/3) → string value (group 4).
+const CONST_OBJECT_MEMBER_RE = /(?:'([^']+)'|"([^"]+)"|([a-zA-Z_$][\w$]*))\s*:\s*'([^']*)'/g;
+
+const METHOD_KEYWORD_BLOCKLIST = new Set([
+  'if',
+  'for',
+  'while',
+  'switch',
+  'catch',
+  'return',
+  'throw',
+  'constructor', // tracked separately if needed
+]);
+
+/**
+ * Given the start index of a class declaration, return the brace-delimited body
+ * as a substring. Returns '' if the body cannot be located.
+ */
+function sliceClassBody(text: string, start: number): string {
+  const open = text.indexOf('{', start);
+  if (open < 0) return '';
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) {
+        return text.slice(open + 1, i);
+      }
+    }
+  }
+  return '';
+}
+
+/**
+ * Pull field names from an interface body. Conservative: only matches simple
+ * declarations of the form `name?: ...;` or `name: ...;`. Generics, methods,
+ * and computed property names are skipped (they don't influence skip decisions).
+ */
+function extractInterfaceFields(text: string, start: number): Set<string> {
+  const fields = new Set<string>();
+  const open = text.indexOf('{', start);
+  if (open < 0) return fields;
+  let depth = 0;
+  let close = -1;
+  for (let i = open; i < text.length; i++) {
+    const c = text[i];
+    if (c === '{') depth++;
+    else if (c === '}') {
+      depth--;
+      if (depth === 0) {
+        close = i;
+        break;
+      }
+    }
+  }
+  if (close < 0) return fields;
+  const body = text.slice(open + 1, close);
+  const fieldRe = /^\s*(?:readonly\s+)?(?:'([^']+)'|"([^"]+)"|([a-zA-Z_$][\w$]*))\s*\??\s*:/gm;
+  for (const m of body.matchAll(fieldRe)) {
+    const name = m[1] ?? m[2] ?? m[3];
+    if (name) fields.add(name);
+  }
+  return fields;
+}