@fougere/core 0.2.0-alpha.2 → 0.3.0-alpha.0

package/dist/scan/frond.d.ts

@@ -0,0 +1,224 @@
+/**
+ * A frond as the SCAN found it — one interface per convention directory, plus what the
+ * run could not read.
+ *
+ * The declared side is `frond-config.ts`; this is the described one. They meet at
+ * `FrondDescriptor.operationsOverrides`, where a declaration reaches the façade.
+ */
+import type { SchemaView } from '@fougere/schema';
+import type { ParsedParam, OperationContract, OperationsMap } from '../wire/operation.js';
+import type { PresenterViews } from '../prefab/presenter.js';
+import type { Fronds } from './Fronds.js';
+/**
+ * A discovered provider — a class under `services/` or `repositories/`, injected by type.
+ *
+ * Which of the two directories it came from is deliberately not recorded. The scan used
+ * to tag it `kind: 'service' | 'repository'`, a field it filled on every provider and
+ * that **no consumer ever read** — the two directories are two spellings of the same
+ * thing, and DI resolves by type either way.
+ */
+export interface ProviderEntry {
+    /**
+     * The class constructor (default export of the file).
+     *
+     * `never[]` and not `unknown[]`: the arguments are the CONTAINER's to supply, so the
+     * slot must accept any constructor — and with `unknown[]` a real class is refused,
+     * because assigning it would need `unknown` to be one of its declared parameters.
+     * Invisible on the scan path, where the value arrives as `unknown` and is cast; the
+     * module `fougere build` writes states the class by name, and that is where it showed.
+     */
+    ctor: new (...args: never[]) => unknown;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered entity (Entity subclass in entities/ dir). */
+export interface EntityEntry {
+    /** Registration key: class name lowercased first char (e.g. 'product'). */
+    name: string;
+    /** The Entity class (has static getFields()). */
+    entityClass: SchemaView;
+    /** Absolute file path (for debugging). */
+    filePath: string;
+    /** Whether this entity is part of the frond's public contract. */
+    exposed?: boolean;
+}
+/** A discovered handler (controls what a service exposes). */
+export interface HandlerEntry {
+    /** Registration key (e.g. 'postHandler'). */
+    name: string;
+    /**
+     * The name this handler answers to — its class name minus `Handler`, lowercased
+     * (`PostHandler` → `post`). It is what `facadeKeyOf` builds its key from and what
+     * travels as `FrondCall.entity` on the wire.
+     *
+     * **It is NOT an entity name**, and it was called `entityName` for long enough to
+     * mislead: `toEntityName` (`scanner.ts`) strips the suffix without checking that any
+     * entity carries the result, and the boot states the consequence — *pointing at
+     * nothing is legal*. A health check, a search across several shapes, a pure
+     * computation: ordinary handlers that own no row. `PresenterEntry`/`CollectorEntry`
+     * keep `entityName` because those really do target a declared entity.
+     */
+    address: string;
+    /** The handler class. */
+    ctor: new (...args: never[]) => unknown;
+    /** All operations with full signatures for binding. */
+    operations: OperationsMap;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+    /** Whether this handler is part of the frond's public contract. */
+    exposed?: boolean;
+    /** Output schema override — when Crud(Entity, Output), restricts ORM output. */
+    outputOverride?: SchemaView;
+    /** Surface name — subdirectory in handlers/ (e.g. 'admin', 'public'). */
+    surface?: string;
+}
+/** Return type metadata for a presenter computed field. */
+export interface PresenterFieldMeta {
+    name: string;
+    /** Inferred return type name: 'string', 'number', 'boolean', or a class name. */
+    returnType?: string;
+    /**
+     * The field emits a LIST per row — `tags(posts: Post[]): string[][]`.
+     *
+     * The method answers one value per row, so the outer array level of its return type is
+     * the page, not the field: what remains after removing it is the field's own arity.
+     * Nothing measured that remainder, so a computed list and a computed scalar looked
+     * identical and every projection announced the scalar.
+     */
+    list?: boolean;
+    /** Whether the return is nullable. */
+    nullable?: boolean;
+    /**
+     * The declared parameters AFTER the rows. Kept raw rather than resolved: the scan
+     * meets presenters before collectors, so the plan is computed at boot where the
+     * collector names are known — exactly as a handler op's is.
+     *
+     * A computed field that declares `user?: User` is then fed by the collector
+     * that resolves one. A presenter is not a second mechanism.
+     */
+    params?: ParsedParam[];
+}
+/** A discovered presenter (computed fields for an entity's output). */
+export interface PresenterEntry {
+    /** Entity name this presenter enriches (e.g. 'post' from PostPresenter). */
+    entityName: string;
+    /** The presenter class. */
+    ctor: new (...args: never[]) => unknown;
+    /** Computed field names (method names on prototype). */
+    fields: string[];
+    /** Per-field type metadata (inferred from source via parser). */
+    fieldMeta: PresenterFieldMeta[];
+    /**
+     * The view each computed field emits, when the presenter declares one
+     * (`Presenter(Order, { items: [OrderItemView] })`). Stated rather than inferred: the
+     * parser reads a scalar off a return type and nothing more, so an object-valued field
+     * has no derivable shape without this.
+     */
+    views?: PresenterViews;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered collector (resolves handler input params from invocation context). */
+export interface CollectorEntry {
+    /** Registration key of the TYPE this collector resolves — 'user', 'ability'. */
+    typeName: string;
+    /** The collector class. */
+    ctor: new (...args: never[]) => unknown;
+    /** Constructor dependency type names (from AST scan). */
+    deps: string[];
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** A discovered seed file (array of records or async factory). */
+export interface SeedEntry {
+    /** Entity name this seed targets (from filename: Author.seed.ts → 'author'). */
+    entityName: string;
+    /** Raw default export — array or function. Resolved at runtime. */
+    data: Record<string, unknown>[] | SeedFactory;
+    /** Absolute file path (for debugging). */
+    filePath: string;
+}
+/** Seed factory — receives a resolver to access handlers cross-frond. */
+export type SeedFactory = (resolve: <T>(name: string) => T) => Promise<Record<string, unknown>[]>;
+/** Where a frond lives on disk. */
+export interface FrondSource {
+    /** Absolute path to the frond directory. */
+    path: string;
+    /** The @fronds/{name} package name. Always present. */
+    package: string;
+}
+export interface FrondDescriptor {
+    name: string;
+    source: FrondSource;
+    providers: ProviderEntry[];
+    entities: EntityEntry[];
+    handlers: HandlerEntry[];
+    presenters: PresenterEntry[];
+    collectors: CollectorEntry[];
+    seeds: SeedEntry[];
+    /** Per-surface entity lists from frond.config.ts (e.g. { graphql: ['Post'], rest: ['Post', 'Author'] }). */
+    surfaces?: Record<string, string[]>;
+    /** Entities this frond may read across sources — see `FrondConfig.reads`. */
+    reads?: string[];
+    /**
+     * Per-operation overrides from frond.config.ts. Key = operation name.
+     *
+     * Two depths, as declared on {@link OperationOverride}: the surface keys travel to the
+     * transport adapters, the contract keys (`input`/`output`/`binding`) travel to the
+     * façade — where config is the third producer of an operation's contract, alongside a
+     * prefab's `__ops` and the scan.
+     */
+    operationsOverrides?: Record<string, OperationContract & {
+        kind?: 'query' | 'command';
+        /** Class name to resolve from DI (overrides default `{Entity}Handler` lookup). */
+        handlerName?: string;
+        /** Method name on the resolved handler (defaults to op name). */
+        method?: string;
+    }>;
+}
+/** Result of scanning a project directory. */
+/**
+ * Something the scan could NOT do — recorded instead of swallowed.
+ *
+ * The scan answers with what it found. Until now it answered the same way whether
+ * a directory held nothing or could not be read, and whether a handler declared no
+ * operation or failed to parse: `catch → empty`. So every downstream reader — the
+ * façade, the identity card, anything asking "what does this app serve?" — could
+ * not tell **"there is nothing"** from **"I could not look"**.
+ *
+ * That distinction is what makes a rule about an ABSENCE sound. Without it, a check
+ * derived from the scan reports "nothing wrong" precisely when it read nothing.
+ */
+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.
+     * `warning` — something may be missing and the scan cannot decide, e.g. a base
+     * class it is not allowed to resolve. Statable in `frond.config.ts`.
+     */
+    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[];
+}
+//# sourceMappingURL=frond.d.ts.map

package/dist/scan/frond.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frond.d.ts","sourceRoot":"","sources":["../../src/scan/frond.ts"],"names":[],"mappings":"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"}

package/dist/scan/frond.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=frond.js.map

package/dist/scan/frond.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frond.js","sourceRoot":"","sources":["../../src/scan/frond.ts"],"names":[],"mappings":""}

package/dist/{handler-parser.d.ts → scan/handler-parser.d.ts}

@@ -1,3 +1,12 @@
+export declare function resetTypePrograms(): void;
+/**
+ * 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.
+ */
+export declare function seedTypeProgram(filePaths: readonly string[], projectRoot?: string): Promise<void>;
 /** A parsed type reference — supports primitives, entities, arrays, generics. */
 export interface ParsedType {
     /** Raw type text as written in source (e.g. 'Pagination<Post>'). */
@@ -16,8 +25,10 @@ export interface ParsedType {
     arrayDepth?: number;
     /** Generic type arguments (e.g. for Pagination<Post> → [{ name: 'Post' }]). */
     generics?: ParsedType[];
-    /** Whether the type is nullable (T | null | undefined). */
+    /** 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;
 }
@@ -48,12 +59,6 @@ export interface ParsedMethod {
      */
     description?: string;
 }
-/**
- * Parse ALL method signatures from a handler source file (CRUD included).
- *
- * Used by the binding algorithm — every operation gets a BindingPlan.
- * When projectRoot is provided, follows heritage clauses to parse parent methods.
- */
 /**
  * What a handler file yielded — its methods, AND what the pass could not open.
  *
@@ -67,16 +72,20 @@ export interface HandlerParse {
     /** Base classes whose source this pass could not open. Empty is a claim. */
     unresolvedHeritage: string[];
 }
+/**
+ * Every method a handler declares, its inherited ones included — the raw material of a
+ * binding plan. With a `projectRoot`, the heritage clause is followed too.
+ */
 export declare function parseAllHandlerMethods(filePath: string, projectRoot?: string): Promise<HandlerParse>;
 /**
  * Parse a presenter source file and extract all method signatures.
  *
  * Returns all methods (no CRUD filtering) — each method is a computed field.
  */
-export declare function parsePresenterMethods(filePath: string): Promise<ParsedMethod[]>;
+export declare function parsePresenterMethods(filePath: string, projectRoot?: string): Promise<ParsedMethod[]>;
 /**
  * Parse constructor parameter types from a source file's default class.
  * Returns type names (e.g. ['PostOrm', 'Logger']) for DI resolution.
  */
-export declare function parseConstructorParams(filePath: string): Promise<ParsedParam[]>;
+export declare function parseConstructorParams(filePath: string, projectRoot?: string): Promise<ParsedParam[]>;
 //# sourceMappingURL=handler-parser.d.ts.map

package/dist/scan/handler-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-parser.d.ts","sourceRoot":"","sources":["../../src/scan/handler-parser.ts"],"names":[],"mappings":"AAsCA,wBAAgB,iBAAiB,IAAI,IAAI,CAGxC;AAiDD;;;;;;GAMG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBvG;AAkDD,iFAAiF;AACjF,MAAM,WAAW,UAAU;IACzB,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,4DAA4D;AAC5D,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA8dD;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,4EAA4E;IAC5E,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAG1G;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAK3G;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAQ3G"}