@fougere/compiler 0.11.0-alpha.0 → 0.12.1-alpha.0

package/src/boot.ts

@@ -1,5 +1,5 @@
 import { Logger, applyConfig, createApp, type App, type CreateAppOptions, type Extension, type FougereConfig, type Transport } from '@fougere/core';
-import { loadConfig } from '@fougere/core/node';
+import { loadConfig, remotesOf, statedModules } from '@fougere/core/node';
 import { scanProject } from './scan/scanner.js';
 
 import type { Container } from '@fougere/container';
@@ -9,9 +9,14 @@ interface BootOptions {
   root?: string;
   /** Override config (merged with fougere.config.ts). */
   config?: Partial<FougereConfig>;
-  /** Container factory. Required. */
-  createContainer: () => Container;
-  /** Only boot these fronds (by name). Absent = all. */
+  /** The container to resolve through. Absent, core builds its own. */
+  createContainer?: () => Container;
+  /**
+   * Boot only these fronds, by name — absent, every one found. Not `fronds:`, which says what
+   * an app is MADE of: this narrows the same list to what one process carries.
+   */
+  only?: string[];
+  /** @deprecated The name `only:` now carries. */
   fronds?: string[];
   /**
    * Remote fronds — label → address. A declared remote wins over local
@@ -64,16 +69,27 @@ export async function boot(options: BootOptions): Promise<App> {
     log.info('database initialized');
   }
 
+  // What the config names by module — imported here, because core resolves no specifier.
+  const stated = await statedModules(config.fronds);
+
   log.debug('creating app (scan + container)');
   const app = await createApp({
+    ...(stated.fronds.length > 0 ? { fronds: stated.fronds } : {}),
     // boot() lives on the Node entry, so boot() is what reads the disk. `createApp` is
     // handed the answer and reaches for nothing.
-    scan: await scanProject(root, options.fronds, config.conventions),
+    scan: await scanProject(root, options.only ?? options.fronds, config.conventions),
     createContainer: options.createContainer,
     storageFactory: dbSetup?.storageFactory,
     db: dbSetup?.db,
     auth: config.auth,
-    remotes: options.remotes,
+    // The tree's string leaves say the same thing `remotes:` does, and this boot read
+    // neither of them from the file until now — a project stating its topology got a
+    // process that believed every frond was local.
+    remotes: options.remotes ?? remotesOf(config),
+    // Who inherits code from whom — handed over whole, because a refusal names where an
+    // entry sits in the tree.
+    under: config.fronds,
+    narrowed: (options.only ?? options.fronds) !== undefined,
     ports: config.ports,
     // Read from the config for the same reason `ports` is, one line up: it is a fact the
     // project states, not one the caller passes. Absent here, `serveRest` and
@@ -87,7 +103,7 @@ export async function boot(options: BootOptions): Promise<App> {
     // Its own gesture, handed over whole. The ORDER — tables, then rows, then whatever this
     // host takes on — is `createApp`'s, and was written out by four hosts before.
     migrate: dbSetup?.migrate,
-    extensions: options.extensions ?? [],
+    extensions: [...stated.extensions, ...(options.extensions ?? [])],
     onEmit: options.onEmit,
     remoteTransport: options.remoteTransport,
   });

package/src/scan/Implemented.ts

@@ -0,0 +1,41 @@
+/** What a scanned class declares it implements. */
+import { loadTS, checkedSourceOf, findDefaultClass } from './TypeProgram.js';
+
+/**
+ * What a scanned class says it IMPLEMENTS, and whether each name is a class.
+ *
+ * A class is the interesting case: `implements` is erased, so `Object.getPrototypeOf(ctor).name`
+ * is empty and the boot binds no port. An interface is the ordinary one — and one of them,
+ * `AsyncDisposable`, is how a provider says its scope keeps it and closes it.
+ */
+export async function parseImplements(filePath: string, projectRoot?: string): Promise<Implemented[]> {
+  const ts = await loadTS();
+  const { source, checker } = checkedSourceOf(filePath, projectRoot);
+  const cls = findDefaultClass(source);
+  if (!cls?.heritageClauses) return [];
+
+  const found: Implemented[] = [];
+  for (const clause of cls.heritageClauses) {
+    if (clause.token !== ts.SyntaxKind.ImplementsKeyword) continue;
+
+    for (const base of clause.types) {
+      if (!ts.isIdentifier(base.expression)) continue;
+
+      let symbol = checker.getSymbolAtLocation(base.expression);
+      if (symbol && symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+
+      found.push({
+        name: base.expression.text,
+        isClass: symbol?.declarations?.some((one) => ts.isClassDeclaration(one)) ?? false,
+      });
+    }
+  }
+
+  return found;
+}
+
+/** One `implements` clause, and what the checker says its name is. */
+export interface Implemented {
+  name: string;
+  isClass: boolean;
+}

package/src/scan/TypeProgram.ts

@@ -0,0 +1,199 @@
+/** The TypeScript program the scan reads through, and the mutable state it keeps. */
+import type ts from '@typescript/typescript6';
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, dirname, resolve as resolvePath } from 'node:path';
+
+/** Lazy-loaded TypeScript module — avoids bundling the 9MB compiler. */
+let _ts: typeof ts | undefined;
+export async function loadTS(): Promise<typeof ts> {
+  if (!_ts) _ts = (await import('@typescript/typescript6')).default;
+  return _ts;
+}
+export function getTS(): typeof ts {
+  if (!_ts) throw new Error('TypeScript not loaded — call an async parse function first');
+  return _ts;
+}
+
+interface TypeProject {
+  roots: Set<string>;
+  options: ts.CompilerOptions;
+  program: ts.Program;
+}
+
+/** One checked program per project/configuration during a scan. */
+const typeProjects = new Map<string, TypeProject>();
+const compilerProjects = new Map<string, { key: string; roots: string[]; options: ts.CompilerOptions }>();
+
+/** What survives a run. */
+const sourceFiles = new Map<string, { mtime: number; file: ts.SourceFile }>();
+const retained = new Map<string, { host: ts.CompilerHost; program: ts.Program }>();
+
+export function resetTypePrograms(): void {
+  typeProjects.clear();
+  compilerProjects.clear();
+}
+
+function keptHost(key: string, options: ts.CompilerOptions): ts.CompilerHost {
+  const cached = retained.get(key);
+  if (cached) return cached.host;
+  const typescript = getTS();
+  const base = typescript.createCompilerHost(options);
+  const host: ts.CompilerHost = {
+    ...base,
+    getSourceFile(fileName, languageVersion, onError, shouldCreate) {
+      const path = resolvePath(fileName);
+      const mtime = statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? -1;
+      const cached = sourceFiles.get(path);
+      if (cached && cached.mtime === mtime) return cached.file;
+      const file = base.getSourceFile(fileName, languageVersion, onError, shouldCreate);
+      if (file && mtime >= 0) sourceFiles.set(path, { mtime, file });
+      return file;
+    },
+  };
+  retained.set(key, { host, program: undefined as unknown as ts.Program });
+  return host;
+}
+
+function builtProgram(key: string, roots: readonly string[], options: ts.CompilerOptions): ts.Program {
+  const typescript = getTS();
+  const host = keptHost(key, options);
+  const program = typescript.createProgram({
+    rootNames: [...roots], options, host, oldProgram: retained.get(key)?.program,
+  });
+  retained.set(key, { host, program });
+  return program;
+}
+
+function compilerProjectOf(filePath: string, projectRoot?: string): { key: string; roots: string[]; options: ts.CompilerOptions } {
+  const typescript = getTS();
+  const absolute = resolvePath(filePath);
+  const configPath = typescript.findConfigFile(dirname(absolute), typescript.sys.fileExists);
+
+  if (configPath) {
+    const key = `${configPath}:${projectRoot ?? ''}`;
+    const cached = compilerProjects.get(key);
+    if (cached) return cached;
+
+    const read = typescript.readConfigFile(configPath, typescript.sys.readFile);
+    if (read.error) throw new Error(typescript.flattenDiagnosticMessageText(read.error.messageText, '\n'));
+    const parsed = typescript.parseJsonConfigFileContent(read.config, typescript.sys, dirname(configPath));
+    const configured = {
+      key,
+      // Compiler options belong to the project; its entire include glob does not belong
+      // to this scan. Each declaration inspected below becomes a root and TypeScript
+      // follows its imports. Seeding the monorepo here made a one-file scan compile it all.
+      roots: [],
+      // Handlers may be authored or emitted as JavaScript. They still need to belong to
+      // the checked program so constructor parsing does not fail on the first cold scan.
+      options: { ...parsed.options, allowJs: true, noEmit: true },
+    };
+    compilerProjects.set(key, configured);
+    return configured;
+  }
+
+  const key = projectRoot ?? dirname(absolute);
+  const cached = compilerProjects.get(key);
+  if (cached) return cached;
+  const configured = {
+    key,
+    roots: [],
+    options: {
+      target: typescript.ScriptTarget.ES2022,
+      module: typescript.ModuleKind.Node16,
+      moduleResolution: typescript.ModuleResolutionKind.Node16,
+      strict: true,
+      skipLibCheck: true,
+      allowJs: true,
+      noEmit: true,
+    },
+  };
+  compilerProjects.set(key, configured);
+  return configured;
+}
+
+/** Declare every file a run will read, so one program covers it. */
+export async function seedTypeProgram(filePaths: readonly string[], projectRoot?: string): Promise<void> {
+  const typescript = await loadTS();
+  const grouped = new Map<string, { options: ts.CompilerOptions; paths: string[] }>();
+
+  for (const filePath of filePaths) {
+    const absolute = resolvePath(filePath);
+    const typescript = getTS();
+  const configured = compilerProjectOf(absolute, projectRoot);
+    const group = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
+    group.paths.push(absolute);
+    grouped.set(configured.key, group);
+  }
+
+  for (const [key, { options, paths }] of grouped) {
+    const roots = new Set(typeProjects.get(key)?.roots ?? []);
+    for (const path of paths) roots.add(path);
+    typeProjects.set(key, { roots, options, program: builtProgram(key, [...roots], options) });
+  }
+}
+
+/** The program a file belongs to, built once and widened as more files are asked for. */
+export function projectOf(filePath: string, projectRoot?: string): { program: ts.Program; absolute: string } {
+  const absolute = resolvePath(filePath);
+  const configured = compilerProjectOf(absolute, projectRoot);
+  let project = typeProjects.get(configured.key);
+
+  if (!project) {
+    // `path.resolve` is variadic, so handing it directly to `map` also passed the
+    // index and the whole roots array as path segments. A fixture without a warm scan
+    // cache exposed that first-run-only failure.
+    const roots = new Set(configured.roots.map((root) => resolvePath(root)));
+    roots.add(absolute);
+    const program = builtProgram(configured.key, [...roots], configured.options);
+    project = { roots, options: configured.options, program };
+    typeProjects.set(configured.key, project);
+  } else if (!project.roots.has(absolute)) {
+    project.roots.add(absolute);
+    project.program = builtProgram(configured.key, [...project.roots], project.options);
+  }
+
+  return { program: project.program, absolute };
+}
+
+export function checkedSourceOf(filePath: string, projectRoot?: string): { source: ts.SourceFile; checker: ts.TypeChecker } {
+  const { program, absolute } = projectOf(filePath, projectRoot);
+  const source = program.getSourceFile(absolute);
+  if (!source) throw new Error(`TypeScript did not include '${absolute}' in its program.`);
+
+  return { source, checker: program.getTypeChecker() };
+}
+
+/** A file, opened. Five places read and parsed one, each spelling the same two calls. */
+export function sourceOf(filePath: string): ts.SourceFile {
+  const ts = getTS();
+  return ts.createSourceFile(filePath, readFileSync(filePath, 'utf-8'), ts.ScriptTarget.Latest, true);
+}
+
+// ── Class finding ────────────────────────────
+
+/** Find the default exported class in a source file. */
+export function findDefaultClass(source: ts.SourceFile): ts.ClassDeclaration | undefined {
+  const ts = getTS();
+  for (const stmt of source.statements) {
+    // export default class Foo { ... }
+    if (ts.isClassDeclaration(stmt) && stmt.modifiers?.some(
+      (m) => m.kind === ts.SyntaxKind.ExportKeyword,
+    ) && stmt.modifiers?.some(
+      (m) => m.kind === ts.SyntaxKind.DefaultKeyword,
+    )) {
+      return stmt;
+    }
+  }
+
+  // export default Foo (separate statement) — find the class it points to
+  for (const stmt of source.statements) {
+    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isIdentifier(stmt.expression)) {
+      const name = stmt.expression.text;
+      for (const s of source.statements) {
+        if (ts.isClassDeclaration(s) && s.name?.text === name) return s;
+      }
+    }
+  }
+
+  return undefined;
+}

package/src/scan/emit.ts

@@ -86,13 +86,16 @@ function collectorOf(c: CollectorEntry, imports: Imports): string {
 }
 
 function providerOf(p: ProviderEntry, imports: Imports): string {
+  // `kept` travels like every other member: a provider that loses it on disk is registered
+  // transient, so the same code would answer differently depending on how it was booted.
   return `{ name: ${lit(nameOf(p))}, ctor: ${imports.aliasOf(p.ctor as Live)}, `
-    + `deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)} }`;
+    + `deps: ${lit(p.deps)}, filePath: ${lit(p.filePath)}`
+    + `${p.kept ? ', kept: true' : ''} }`;
 }
 
 function middlewareOf(m: MiddlewareEntry, imports: Imports): string {
   return `{ name: ${lit(m.name)}, ctor: ${imports.aliasOf(m.ctor as Live)}, `
-    + `scope: ${lit(m.scope)}, deps: ${lit(m.deps)}, filePath: ${lit(m.filePath)} }`;
+    + `deps: ${lit(m.deps)}, filePath: ${lit(m.filePath)} }`;
 }
 
 function seedOf(s: SeedEntry, imports: Imports): string {
@@ -125,25 +128,11 @@ export function emitScan(result: ScanResult, options: EmitOptions): string {
   const imports = new Imports(options.outFile);
   const core = options.core ?? '@fougere/core';
 
-  // Every class the descriptor names by a file comes first: a schema slot holding one of
-  // them then finds it in the table instead of being imported a second time.
-  for (const f of result.fronds) {
-    for (const e of f.entities) {
-      imports.default(e.entityClass as Live, e.filePath);
-      const name = (e.entityClass as { name?: string }).name;
-      if (name) imports.byClassName.set(name, e.entityClass as Live);
-    }
-    for (const p of f.providers) imports.default(p.ctor as Live, p.filePath);
-    for (const h of f.handlers) imports.default(h.ctor as Live, h.filePath);
-    for (const p of f.presenters) imports.default(p.ctor as Live, p.filePath);
-    for (const c of f.collectors) imports.default(c.ctor as Live, c.filePath);
-    for (const m of f.middlewares) imports.default(m.ctor as Live, m.filePath);
-    for (const s of f.seeds) if (typeof s.data === 'function') imports.default(s.data as Live, s.filePath);
-  }
+  collectImports(result, imports);
 
-  const fronds = result.fronds.map((f) => frondOf(f, imports)).join(',\n');
-  // `cause` is dropped: it is an Error, and the build that produced this already reported
-  // it. What a boot logs is the message, and that travels.
+  const fronds = result.fronds.map((one) => frondOf(one, imports)).join(',\n');
+  // `cause` is dropped: it is an Error, and the build that produced this already reported it.
+  // What a boot logs is the message, and that travels.
   const diagnostics = result.diagnostics.map(({ cause: _cause, ...rest }) => lit(rest));
 
   // The annotation is a convenience for a file a human's tsc will read; it is never what
@@ -166,3 +155,26 @@ ${fronds}
 };
 `;
 }
+
+/**
+ * Every class the descriptor names by a file, imported first: a schema slot holding one of them
+ * then finds it in the table instead of being imported a second time.
+ */
+function collectImports(result: ScanResult, imports: Imports): void {
+  for (const frond of result.fronds) {
+    for (const entity of frond.entities) {
+      imports.default(entity.entityClass as Live, entity.filePath);
+      const name = (entity.entityClass as { name?: string }).name;
+      if (name) imports.byClassName.set(name, entity.entityClass as Live);
+    }
+
+    for (const one of frond.providers) imports.default(one.ctor as Live, one.filePath);
+    for (const one of frond.handlers) imports.default(one.ctor as Live, one.filePath);
+    for (const one of frond.presenters) imports.default(one.ctor as Live, one.filePath);
+    for (const one of frond.collectors) imports.default(one.ctor as Live, one.filePath);
+    for (const one of frond.middlewares) imports.default(one.ctor as Live, one.filePath);
+    for (const seed of frond.seeds) {
+      if (typeof seed.data === 'function') imports.default(seed.data as Live, seed.filePath);
+    }
+  }
+}