@fougere/compiler 0.10.0-alpha.0 → 0.12.0-alpha.0

package/src/scan/scanner.ts

@@ -2,6 +2,7 @@ import { DEFAULT_CONVENTIONS, frondDirsOf, frondPackage, providerDirsOf, resolve
 import { Fronds, awaitKeyOf, cardinalityOf, computeBindingPlan, emitKeyOf, getPresenterFields, outputOf, ownedBy, repositoryKeyOf, storageKeyOf, targetOf, type CollectorEntry, type EntityEntry, type FrondDescriptor, type HandlerEntry, type MiddlewareEntry, type OperationContract, type OperationsMap, type PresenterEntry, type ProviderEntry, type SeedEntry, type TypeRef, viewsOf, type ExtensionEntry } from '@fougere/core/descriptor';
 import { getModuleLoader, loadFrondConfig } from '@fougere/core/node';
 import type { FrondConfig, ErrorCode } from '@fougere/core';
+import type { Signature } from '@fougere/core/descriptor';
 import { readdir, readFile } from 'node:fs/promises';
 import { existsSync, type Dirent } from 'node:fs';
 import { join, dirname, basename, resolve as resolvePath } from 'node:path';
@@ -13,9 +14,9 @@ import {
   parseRefusals,
   parsePresenterMethods,
   parseConstructorParams,
-  resetTypePrograms,
-  seedTypeProgram,
 } from './handler-parser.js';
+import { parseImplements } from './Implemented.js';
+import { resetTypePrograms, seedTypeProgram } from './TypeProgram.js';
 
 import { lowerFirst } from '@fougere/schema';
 
@@ -96,7 +97,7 @@ async function loadClass(filePath: string): Promise<ProviderEntry['ctor']> {
 }
 
 function isEntityClass(value: unknown): value is SchemaView {
-  return typeof value === 'function' && 'getFields' in (value as any);
+  return typeof value === 'function' && 'getFields' in (value as object);
 }
 
 // Workspace
@@ -176,6 +177,9 @@ function tupleMembers(raw: string): string[] {
 const ctorParamsOf = (filePath: string) =>
   parseConstructorParams(filePath);
 
+const implementsOf = (filePath: string) =>
+  parseImplements(filePath);
+
 const presenterMethodsOf = (filePath: string) =>
   parsePresenterMethods(filePath);
 
@@ -190,6 +194,28 @@ async function toProvider(filePath: string): Promise<ProviderEntry> {
   const params = await ctorParamsOf(filePath);
   const deps = params.map((p) => depKeyOf(p.type));
 
+  const stated = await implementsOf(filePath);
+
+  // A port is answered by EXTENDING it: the boot reads the prototype chain, and `implements`
+  // leaves none. Said here rather than refused, because implementing a class is legal — only
+  // the author knows whether a port was meant. Warned, so `createApp` prints it too.
+  for (const { name: base } of stated.filter((one) => one.isClass)) {
+    record({
+      severity: 'warning',
+      code: 'port-implemented-not-extended',
+      filePath,
+      subject: name,
+      message: `${name} implements the class ${base}. A port is answered by EXTENDING it — `
+        + `\`implements\` leaves nothing at runtime, so the boot binds no port and the first `
+        + `dependency on ${base} answers '${base}' is not registered. Write `
+        + `\`class ${name} extends ${base}\`, or ${base} states an interface if its shape is all you wanted.`,
+    });
+  }
+
+  // `implements AsyncDisposable` — the language's own marker, which `App` already answers. It
+  // says two things at once: there is ONE of me in this frond's scope, and that scope closes me.
+  const kept = stated.some((one) => one.name === 'AsyncDisposable');
+
   // A repository inherits its constructor from `Repository(…)`, so the file declares none
   // and the scan reads no parameter. The mixin knows what it was built for and says so at
   // runtime — same escape as `Crud.__ops`, and the same reason: what a prefab fabricates,
@@ -209,7 +235,7 @@ async function toProvider(filePath: string): Promise<ProviderEntry> {
   // `name` beside `ctor`, and it IS the registration key — what `depKeyOf` returns, since
   // it reads the type as written. It used to be asked of `ctor.name` at boot, which held
   // until a bundler lowered a static field and renamed the declaration doing it.
-  return { name, ctor, deps, filePath };
+  return { name, ctor, deps, filePath, ...(kept ? { kept: true as const } : {}) };
 }
 
 /**
@@ -264,8 +290,9 @@ function resolveSchema(type: TypeRef, moduleExports: Record<string, unknown>): S
         // `Partial<X>` in a signature IS the patch declaration (Crud.update) —
         // project it onto the schema view instead of dropping the wrapper, so
         // the facade validates in patch mode (absent field → untouched).
-        if (type.name === 'Partial' && 'partial' in resolved && typeof (resolved as any).partial === 'function') {
-          return (resolved as any).partial() as SchemaView;
+        const narrowing = (resolved as { partial?: () => SchemaView }).partial;
+        if (type.name === 'Partial' && typeof narrowing === 'function') {
+          return narrowing.call(resolved);
         }
         return resolved as unknown as SchemaView;
       }
@@ -278,6 +305,83 @@ function resolveSchema(type: TypeRef, moduleExports: Record<string, unknown>): S
   return undefined;
 }
 
+/**
+ * A convention may omit a declaration only when it has one answer.
+ *
+ * Only values the caller supplies through the BODY are candidates: a schema-typed collector,
+ * fact or context parameter is not input merely because it names an entity. Reading them all
+ * ignored provenance and took the first schema it met, so swapping two parameters silently
+ * changed the contract the façade validated the request against.
+ */
+function inputOf(
+  method: Signature,
+  handlerName: string,
+  filePath: string,
+  collectorTypeNames: Set<string>,
+  moduleExports: Record<string, unknown>,
+  stated: boolean,
+): SchemaView | undefined {
+  const binding = computeBindingPlan(method.params, collectorTypeNames);
+  const candidates = method.params.flatMap((param, index) => {
+    if (binding[index]?.source.kind !== 'input') return [];
+    const schema = resolveSchema(param.type, moduleExports);
+
+    return schema ? [{ param, schema }] : [];
+  });
+
+  if (candidates.length === 1) return candidates[0]!.schema;
+  if (candidates.length < 2 || stated) return undefined;
+
+  const subject = `${handlerName}.${method.name}`;
+  record({
+    severity: 'blocking',
+    code: 'input-contract-ambiguous',
+    filePath,
+    subject,
+    message: `Cannot infer the input contract for ${subject}: ${candidates.length} entity `
+      + `candidates — ${candidates.map(({ param }) => `${param.name}: ${param.type.raw}`).join('; ')}. `
+      + `Declare operations.${method.name}.input in frond.config.ts.`,
+  });
+
+  return undefined;
+}
+
+/** What one method of a handler is read against, while its contract is built. */
+interface Reading {
+  handlerName: string;
+  filePath: string;
+  moduleExports: Record<string, unknown>;
+  collectorTypeNames: Set<string>;
+  refused: ErrorCode[] | undefined;
+  stated: boolean;
+}
+
+/**
+ * The contract carries the description; `signature` is the raw material it was read from.
+ * Leaving it only on the signature meant every consumer had to look one level down, and only
+ * the façade did.
+ */
+function contractOf(method: Signature, read: Reading): OperationContract {
+  const meta: OperationContract = {
+    signature: method,
+    ...(method.description && { description: method.description }),
+    ...(read.refused?.length ? { errors: read.refused } : {}),
+  };
+
+  const input = inputOf(
+    method, read.handlerName, read.filePath, read.collectorTypeNames, read.moduleExports, read.stated,
+  );
+  if (input) meta.input = input;
+
+  if (method.returnType) {
+    meta.output = resolveSchema(method.returnType, read.moduleExports);
+    // `output` is the shape of one row; this says how many rows come back.
+    meta.cardinality = cardinalityOf(method.returnType);
+  }
+
+  return meta;
+}
+
 /** Parse ALL method signatures for unified binding. */
 async function inferOperations(
   filePath: string,
@@ -334,53 +438,11 @@ async function inferOperations(
   }
 
   for (const method of parsed.methods) {
-    // The contract is what carries the description; `signature` is the raw material it
-    // was read from. Leaving it only on the signature meant every consumer had to know
-    // to look one level down, and only the façade did.
-    const refused = refusals.get(`${handlerName}.${method.name}`);
-    const meta: OperationContract = {
-      signature: method,
-      ...(method.description && { description: method.description }),
-      ...(refused?.length ? { errors: refused } : {}),
-    };
-
-    // A convention may omit a declaration only when it has one answer. Only values the
-    // caller supplies through the body are candidates: a schema-typed collector, fact or
-    // context parameter is not input merely because it names an entity. The old loop
-    // ignored provenance and assigned the first schema it met, so swapping two parameters
-    // silently changed the contract the façade used to validate the request body.
-    const binding = computeBindingPlan(method.params, collectorTypeNames);
-    const candidates = method.params.flatMap((param, index) => {
-      if (binding[index]?.source.kind !== 'input') return [];
-      const schema = resolveSchema(param.type, moduleExports);
-      return schema ? [{ param, schema }] : [];
-    });
-    if (candidates.length === 1) {
-      meta.input = candidates[0].schema;
-    } else if (
-      candidates.length > 1
-      && declared[method.name]?.input === undefined
-      && !explicitInputs.has(method.name)
-    ) {
-      const subject = `${handlerName}.${method.name}`;
-      record({
-        severity: 'blocking',
-        code: 'input-contract-ambiguous',
-        filePath,
-        subject,
-        message: `Cannot infer the input contract for ${subject}: ${candidates.length} entity `
-          + `candidates — ${candidates.map(({ param }) => `${param.name}: ${param.type.raw}`).join('; ')}. `
-          + `Declare operations.${method.name}.input in frond.config.ts.`,
-      });
-    }
-
-    if (method.returnType) {
-      meta.output = resolveSchema(method.returnType, moduleExports);
-      // `output` is the shape of one row; this says how many rows come back.
-      meta.cardinality = cardinalityOf(method.returnType);
-    }
-
-    map.set(method.name, meta);
+    map.set(method.name, contractOf(method, {
+      handlerName, filePath, moduleExports, collectorTypeNames,
+      refused: refusals.get(`${handlerName}.${method.name}`),
+      stated: declared[method.name]?.input !== undefined || explicitInputs.has(method.name),
+    }));
   }
 
   return map;
@@ -460,7 +522,7 @@ async function toPresenterEntry(filePath: string): Promise<PresenterEntry | null
   const ctor = await loadClass(filePath);
   const target = targetOf(ctor);
   if (!target) return null;
-  const entityName = lowerFirst((target as any).name);
+  const entityName = lowerFirst((target as { name: string }).name);
   const fields = getPresenterFields(ctor);
   const presenterParams = await ctorParamsOf(filePath);
   const deps = presenterParams.map((p) => depKeyOf(p.type));
@@ -517,7 +579,7 @@ async function toCollectorEntry(filePath: string): Promise<CollectorEntry | null
   if (!target) return null;
   // The target's NAME and nothing else — a collector reads no fields, so the class it
   // was built on needs no schema.
-  const typeName = lowerFirst((target as any).name);
+  const typeName = lowerFirst((target as { name: string }).name);
   const collectorParams = await ctorParamsOf(filePath);
   const deps = collectorParams.map((p) => depKeyOf(p.type));
   return { typeName, ctor, deps, filePath };
@@ -527,10 +589,7 @@ async function toCollectorEntry(filePath: string): Promise<CollectorEntry | null
  * Recognized by its FORM: a class in `middlewares/` that declares `around`. The scope is
  * the frond's own unless `frond.config.ts` widened it, which is why the config comes first.
  */
-async function toMiddlewareEntry(
-  filePath: string,
-  scopes: FrondConfig['middlewares'],
-): Promise<MiddlewareEntry | null> {
+async function toMiddlewareEntry(filePath: string): Promise<MiddlewareEntry | null> {
   const ctor = await loadClass(filePath);
   const prototype = (ctor as { prototype?: { around?: unknown } }).prototype;
   if (typeof prototype?.around !== 'function') return null;
@@ -539,12 +598,48 @@ async function toMiddlewareEntry(
   return {
     name: ctor.name,
     ctor,
-    scope: scopes?.[ctor.name] ?? 'frond',
     deps: params.map((p) => depKeyOf(p.type)),
     filePath,
   };
 }
 
+/** `frond.config.ts` takes precedence; failing that, `@expose`, which defaults to exposed. */
+function markExposed(
+  entities: EntityEntry[],
+  handlers: HandlerEntry[],
+  exposed: readonly string[] | undefined,
+): void {
+  if (exposed) {
+    const stated = new Set(exposed);
+    for (const entity of entities) entity.exposed = stated.has((entity.entityClass as { name: string }).name);
+    for (const handler of handlers) handler.exposed = stated.has(handler.ctor.name);
+
+    return;
+  }
+
+  for (const entity of entities) entity.exposed = (entity.entityClass as { __exposed?: boolean }).__exposed !== false;
+  for (const handler of handlers) handler.exposed = (handler.ctor as { __exposed?: boolean }).__exposed !== false;
+}
+
+/**
+ * The only thing that needs flattening is the handler CLASS, which becomes its name — that is the
+ * DI key. Everything else travels verbatim, so a slot added to `OperationOverride` reaches its
+ * reader without a stop here; enumerating keys by hand is what used to drop whatever was added
+ * last, the same invariant `cloneField` holds one layer down.
+ */
+function overridesOf(
+  operations: FrondConfig['operations'],
+): FrondDescriptor['operationsOverrides'] {
+  if (!operations) return undefined;
+
+  return Object.fromEntries(
+    Object.entries(operations).map(([opName, { handler, ...rest }]) => [
+      opName,
+      { ...rest, handlerName: handler?.name },
+    ]),
+  );
+}
+
 async function scanFrond(frondPath: string, name: string, source: FrondDescriptor['source'], conventions: Conventions, projectRoot?: string): Promise<FrondDescriptor> {
   const {
     entities: entitiesDir, handlers: handlersDir,
@@ -594,41 +689,10 @@ async function scanFrond(frondPath: string, name: string, source: FrondDescripto
 
   const presenters = await collect(presentersDir, toPresenterEntry);
   const seeds = await collect(seedsDir, toSeedEntry);
-  const middlewares = await collect(middlewaresDir, (f) => toMiddlewareEntry(f, frondConfig?.middlewares));
+  const middlewares = await collect(middlewaresDir, (f) => toMiddlewareEntry(f));
 
-  // Mark exposed entries: frond.config.ts takes precedence, then @expose decorator
-  if (frondConfig?.expose) {
-    const exposeSet = new Set(frondConfig.expose);
-    for (const e of entities) {
-      e.exposed = exposeSet.has((e.entityClass as any).name);
-    }
-    for (const h of handlers) {
-      h.exposed = exposeSet.has(h.ctor.name);
-    }
-  } else {
-    // Fallback: check @expose decorator, default to true (expose everything unless explicitly hidden)
-    for (const e of entities) {
-      e.exposed = (e.entityClass as any).__exposed !== false;
-    }
-    for (const h of handlers) {
-      h.exposed = (h.ctor as any).__exposed !== false;
-    }
-  }
-
-  // Flatten per-op config overrides: the only thing that needs flattening is the handler
-  // CLASS, which becomes its name (that is the DI key). Everything else — the surface keys
-  // AND the contract keys (`input`, `binding`) — travels verbatim, so a slot added to
-  // OperationOverride reaches its reader without a stop here. Enumerating keys by hand is
-  // what used to silently drop whatever was added last (the same invariant `cloneField`
-  // holds one layer down).
-  const operationsOverrides = frondConfig?.operations
-    ? Object.fromEntries(
-        Object.entries(frondConfig.operations).map(([opName, { handler, ...rest }]) => [
-          opName,
-          { ...rest, handlerName: handler?.name },
-        ]),
-      )
-    : undefined;
+  markExposed(entities, handlers, frondConfig?.expose);
+  const operationsOverrides = overridesOf(frondConfig?.operations);
 
   return {
     name,