@fougere/core 0.5.0-alpha.1 → 0.7.0-alpha.0

package/src/scan/handler-parser.ts

@@ -1,9 +1,5 @@
-/**
- * Handler signature parser — extracts method signatures from handler source files.
- *
- * The AST says what the author declared; TypeScript's checker says what those types mean.
- * TypeScript is lazy-loaded to avoid bundling the compiler in production builds.
- */
+/** Handler signature parser — extracts method signatures from handler source files. */
+import type { TypeRef, Param, Signature } from '../wire/signature.js';
 import type ts from '@typescript/typescript6';
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve as resolvePath } from 'node:path';
@@ -25,26 +21,11 @@ interface TypeProject {
   program: ts.Program;
 }
 
-/**
- * One checked program per project/configuration during a scan.
- *
- * A checker is a project reader, not a file parser: creating one per handler would reopen
- * the standard library and every imported declaration for each method. `scanProject`
- * resets this map at the start of a run, so an edited source can never meet a program from
- * the previous run.
- */
+/** 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: the parsed declarations, and the program built over them.
- *
- * Rebuilding a program re-reads `lib.d.ts` and every imported `.d.ts`, and that is FIXED
- * work — measured, a second scan in one process cost the same at 16 frond files as at 406.
- * The mtime is the guard, so a run still cannot see a stale type: a file that moved is
- * re-read and TypeScript invalidates it and everything depending on it, which is a
- * narrower rule than discarding the program and not a weaker one.
- */
+/** 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 }>();
 
@@ -60,8 +41,8 @@ export function forgetParsedSources(): void {
 }
 
 function keptHost(key: string, options: ts.CompilerOptions): ts.CompilerHost {
-  const held = retained.get(key);
-  if (held) return held.host;
+  const cached = retained.get(key);
+  if (cached) return cached.host;
   const typescript = getTS();
   const base = typescript.createCompilerHost(options);
   const host: ts.CompilerHost = {
@@ -137,13 +118,7 @@ function compilerProjectOf(filePath: string, projectRoot?: string): { key: strin
   return configured;
 }
 
-/**
- * Declare every file a run will read, so one program covers it.
- *
- * `checkedSourceOf` rebuilds whenever it meets a root it has not seen, and a frond lives
- * outside its project's tsconfig `include`, so every declaration was a new root: 44 files
- * cost 7.3 s that way against 0.34 s for one program.
- */
+/** 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[] }>();
@@ -151,9 +126,9 @@ export async function seedTypeProgram(filePaths: readonly string[], projectRoot?
   for (const filePath of filePaths) {
     const absolute = resolvePath(filePath);
     const configured = compilerProjectOf(absolute, projectRoot);
-    const held = grouped.get(configured.key) ?? { options: configured.options, paths: [] };
-    held.paths.push(absolute);
-    grouped.set(configured.key, held);
+    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) {
@@ -167,25 +142,25 @@ function checkedSourceOf(filePath: string, projectRoot?: string): { source: ts.S
   const typescript = getTS();
   const absolute = resolvePath(filePath);
   const configured = compilerProjectOf(absolute, projectRoot);
-  let held = typeProjects.get(configured.key);
+  let project = typeProjects.get(configured.key);
 
-  if (!held) {
+  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);
-    held = { roots, options: configured.options, program };
-    typeProjects.set(configured.key, held);
-  } else if (!held.roots.has(absolute)) {
-    held.roots.add(absolute);
-    held.program = builtProgram(configured.key, [...held.roots], held.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);
   }
 
-  const source = held.program.getSourceFile(absolute);
+  const source = project.program.getSourceFile(absolute);
   if (!source) throw new Error(`TypeScript did not include '${absolute}' in its program.`);
-  return { source, checker: held.program.getTypeChecker() };
+  return { source, checker: project.program.getTypeChecker() };
 }
 
 /** A file, opened. Five places read and parsed one, each spelling the same two calls. */
@@ -195,7 +170,7 @@ function sourceOf(filePath: string): ts.SourceFile {
 }
 
 /** One declared parameter — a constructor's and a method's are read the same way. */
-function parsedParam(param: ts.ParameterDeclaration, source: ts.SourceFile, checker?: ts.TypeChecker): ParsedParam {
+function parsedParam(param: ts.ParameterDeclaration, source: ts.SourceFile, checker?: ts.TypeChecker): Param {
   const ts = getTS();
   const type = param.type ? parseTypeNode(param.type, source, checker) : { raw: 'unknown', name: 'unknown' };
   return {
@@ -207,63 +182,9 @@ function parsedParam(param: ts.ParameterDeclaration, source: ts.SourceFile, chec
   };
 }
 
-/** A parsed type reference — supports primitives, entities, arrays, generics. */
-export interface ParsedType {
-  /** Raw type text as written in source (e.g. 'Pagination<Post>'). */
-  raw: string;
-  /** Base type name (e.g. 'Pagination', 'string', 'Post'). */
-  name: string;
-  /** Whether this is an array (T[] or Array<T>) — true at any depth. */
-  array?: boolean;
-  /**
-   * How MANY array levels: `string[]` is 1, `string[][]` is 2. `array` only ever said
-   * "at least one", which sufficed while one level meant one thing. It stopped sufficing
-   * when a presenter method started taking the page — there the outer level IS the page
-   * and what remains is the field, so telling `string[]` from `string[][]` is telling a
-   * computed string from a computed list.
-   */
-  arrayDepth?: number;
-  /** Generic type arguments (e.g. for Pagination<Post> → [{ name: 'Post' }]). */
-  generics?: ParsedType[];
-  /** Whether `null` belongs to the type. */
-  nullable?: boolean;
-  /** Whether absence (`undefined` or `void`) belongs to the type. */
-  undefined?: boolean;
-  /** Whether this is a Promise wrapper (unwrapped in output). */
-  promise?: boolean;
-}
-
-/** A parsed method parameter. */
-export interface ParsedParam {
-  name: string;
-  type: ParsedType;
-  optional?: boolean;
-}
 
-/** A parsed method signature from a handler source file. */
-export interface ParsedMethod {
-  name: string;
-  params: ParsedParam[];
-  returnType?: ParsedType;
-  /**
-   * Came from a base class, not from the file being scanned. What a prefab
-   * handler declares about its own ops beats this — the scan reads a signature
-   * and guesses, the builder knows.
-   */
-  inherited?: boolean;
-  /**
-   * The operation in words — the first sentence of the method's doc comment.
-   *
-   * Not a new thing to write: handlers already carry it (`/** Judge: the author,
-   * a draft… *&#47;`), the AST already holds it, and nothing read it. A caller that
-   * discovers an operation over the wire has its name and its schema; what the
-   * operation is FOR lived only in the source.
-   */
-  description?: string;
-}
-
-/** Parse a TypeScript type node into a ParsedType. */
-function parseTypeNode(node: ts.TypeNode, source: ts.SourceFile, checker?: ts.TypeChecker): ParsedType {
+/** Parse a TypeScript type node into a TypeRef. */
+function parseTypeNode(node: ts.TypeNode, source: ts.SourceFile, checker?: ts.TypeChecker): TypeRef {
   const ts = getTS();
   const raw = node.getText(source);
 
@@ -373,7 +294,7 @@ function meaningfulSymbolName(type: ts.Type, checker: ts.TypeChecker): string {
 }
 
 /** Turn a checked TypeScript type into the small, serializable vocabulary the runtime reads. */
-function parseCheckedType(type: ts.Type, raw: string, checker: ts.TypeChecker, depth = 0): ParsedType {
+function parseCheckedType(type: ts.Type, raw: string, checker: ts.TypeChecker, depth = 0): TypeRef {
   const typescript = getTS();
   if (depth > 12) return { raw, name: checker.typeToString(type) };
 
@@ -481,20 +402,7 @@ function resolveSpecifier(specifier: string, fromFile: string, projectRoot: stri
 
 // ── Mixin / heritage parsing ─────────────────
 
-/**
- * The class a returned expression carries, however it is wrapped.
- *
- * A mixin does not always hand its class back bare. `Crud` returns
- * `asCrudConstructor(class CrudHandler { … })` — one assertion helper standing between
- * `return` and the class — and a parser accepting only a bare `return class` found
- * nothing there, silently: the five inherited CRUD ops stopped being derived, and a warm
- * scan cache kept answering the old parse for weeks (`scan-cache.ts` keys on source, not
- * on parser version).
- *
- * So unwrap rather than match one shape: descend through call arguments, `as` and
- * `satisfies` assertions, and parentheses. What is looked for is a class; where the
- * author put it is their business.
- */
+/** The class a returned expression carries, however it is wrapped. */
 function classInExpression(expr: ts.Node, depth = 0): ts.ClassExpression | undefined {
   const ts = getTS();
   if (depth > 8) return undefined;
@@ -545,9 +453,9 @@ function extractClassMethods(
   source: ts.SourceFile,
   skip: Set<string>,
   checker?: ts.TypeChecker,
-): ParsedMethod[] {
+): Signature[] {
   const ts = getTS();
-  const results: ParsedMethod[] = [];
+  const results: Signature[] = [];
 
   for (const member of cls.members) {
     if (!ts.isMethodDeclaration(member)) continue;
@@ -555,7 +463,7 @@ function extractClassMethods(
     // `private`/`protected` is a statement about the surface, and the AST carries it —
     // it was read past. Every helper a handler names by intent (`mustOwn`, `readMany`,
     // `refuse`) became a callable op: measured on the bench, `list.readMany` executed
-    // and `list.mayPublish` judged its argument. A door is what the author declares
+    // and `list.mayPublish` validated its argument. A door is what the author declares
     // public, and TypeScript already has the word for it. `#name` is private too, but
     // it is not an identifier, so it never reached here in the first place.
     if (member.modifiers?.some((m) => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword)) continue;
@@ -574,14 +482,7 @@ function extractClassMethods(
   return results;
 }
 
-/**
- * The first sentence of a member's doc comment, or nothing.
- *
- * One sentence on purpose: what a caller needs to choose an operation is a claim,
- * not an essay, and the rest of the comment addresses whoever edits the method.
- * Reads the leading trivia rather than `ts.getJSDocTags` — the comment is what the
- * author wrote, tags are a schema they never agreed to.
- */
+/** The first sentence of a member's doc comment, or nothing. */
 function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefined {
   const ts = getTS();
   const ranges = ts.getLeadingCommentRanges(source.text, member.pos) ?? [];
@@ -604,11 +505,7 @@ function docSentenceOf(member: ts.Node, source: ts.SourceFile): string | undefin
  * Parse inherited methods from a class's heritage clause.
  * Handles both `extends Crud(Entity)` (mixin) and `extends BaseClass` patterns.
  */
-/**
- * Where a name used here is declared. The checker follows the import, the re-export chain
- * and an installed package's types — the three cases three hand-rolled functions treated
- * separately.
- */
+/** Where a name used here is declared. */
 function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | undefined {
   const typescript = getTS();
   let symbol = checker.getSymbolAtLocation(node);
@@ -617,20 +514,14 @@ function declarationFileOf(node: ts.Node, checker: ts.TypeChecker): string | und
   return symbol.declarations?.[0]?.getSourceFile().fileName;
 }
 
-/**
- * The methods a base class contributes, read from the INSTANTIATED type.
- *
- * `extends Crud(Post)` gives `create(input: Partial<Post>)` directly: the checker has
- * already substituted the mixin's type parameter. The three functions this replaces
- * detected the generic names and mapped them to the mixin's arguments by position.
- */
+/** The methods a base class contributes, read from the INSTANTIATED type. */
 function inheritedFromBase(
   base: ts.ExpressionWithTypeArguments,
   checker: ts.TypeChecker,
   skip: Set<string>,
-): ParsedMethod[] {
+): Signature[] {
   const typescript = getTS();
-  const results: ParsedMethod[] = [];
+  const results: Signature[] = [];
 
   for (const property of checker.getPropertiesOfType(checker.getTypeAtLocation(base))) {
     if (skip.has(property.name)) continue;
@@ -670,13 +561,11 @@ function parseInheritedMethods(
   checker: ts.TypeChecker,
   skip: Set<string>,
   /**
-   * Base classes this pass could not open — an INSTALLED one, typically, whose
-   * source is not in the workspace. Reported rather than treated as "no inherited
-   * method": the two used to be the same answer, so an op inherited from a
-   * published base class was absent from the façade without a word.
+   * Base classes this pass could not open — an INSTALLED one, typically, whose source is not in
+   * the workspace.
    */
   unresolved: string[],
-): ParsedMethod[] {
+): Signature[] {
   const ts = getTS();
   if (!cls.heritageClauses) return [];
 
@@ -738,16 +627,9 @@ function findDefaultClass(source: ts.SourceFile): ts.ClassDeclaration | undefine
   return undefined;
 }
 
-/**
- * What a handler file yielded — its methods, AND what the pass could not open.
- *
- * The second half is why this is a pair rather than an array: an unresolvable base
- * class used to give the same answer as a base class with no method, so an op
- * inherited from an installed package was missing from the façade in silence. The
- * pair travels through the scan cache, which is why {@link PARSER_VERSION} moved.
- */
+/** What a handler file yielded — its methods, AND what the pass could not open. */
 export interface HandlerParse {
-  methods: ParsedMethod[];
+  methods: Signature[];
   /** Base classes whose source this pass could not open. Empty is a claim. */
   unresolvedHeritage: string[];
 }
@@ -761,12 +643,8 @@ export async function parseAllHandlerMethods(filePath: string, projectRoot?: str
   return parseClassMethods(filePath, CONSTRUCTOR_ONLY, projectRoot);
 }
 
-/**
- * Parse a presenter source file and extract all method signatures.
- *
- * Returns all methods (no CRUD filtering) — each method is a computed field.
- */
-export async function parsePresenterMethods(filePath: string, projectRoot?: string): Promise<ParsedMethod[]> {
+/** Parse a presenter source file and extract all method signatures. */
+export async function parsePresenterMethods(filePath: string, projectRoot?: string): Promise<Signature[]> {
   await loadTS();
   // No `projectRoot`, so no heritage pass and nothing to report: a presenter's
   // computed fields are its own methods.
@@ -775,9 +653,9 @@ export async function parsePresenterMethods(filePath: string, projectRoot?: stri
 
 /**
  * Parse constructor parameter types from a source file's default class.
- * Returns type names (e.g. ['PostOrm', 'Logger']) for DI resolution.
+ * Returns type names (e.g. ['PostStorage', 'Logger']) for DI resolution.
  */
-export async function parseConstructorParams(filePath: string, projectRoot?: string): Promise<ParsedParam[]> {
+export async function parseConstructorParams(filePath: string, projectRoot?: string): Promise<Param[]> {
   const ts = await loadTS();
   const { source, checker } = checkedSourceOf(filePath, projectRoot);
   const cls = findDefaultClass(source);

package/src/scan/result.ts

@@ -0,0 +1,29 @@
+import type { Fronds } from '../descriptor/Fronds.js';
+
+/** Result of scanning a project directory. */
+/** Something the scan could NOT do — recorded instead of swallowed. */
+export interface ScanDiagnostic {
+  /**
+   * `blocking` — the app now serves less than its source declares, and no caller can know it: a
+   * handler that failed to parse contributes zero operations.
+   */
+  severity: 'blocking' | 'warning';
+  /** Stable rule name — `handler-parse-failed`, `directory-unreadable`. */
+  code: string;
+  /** Absolute path of what could not be read. */
+  filePath: string;
+  /** The frond it belongs to, when the scan got far enough to know. */
+  frond?: string;
+  /** The declaration the diagnostic is about — e.g. `PostHandler.publish`. */
+  subject?: string;
+  /** What could not be done, and what it costs. One sentence, for a human. */
+  message: string;
+  /** The underlying failure, kept whole. */
+  cause?: unknown;
+}
+
+export interface ScanResult {
+  fronds: Fronds;
+  /** What the scan could not do. Empty is a claim, not a default — see {@link ScanDiagnostic}. */
+  diagnostics: ScanDiagnostic[];
+}