@webda/content-mapper 0.0.0-stage → 4.0.0-beta.4

package/lib/module-discovery.d.ts

@@ -0,0 +1,211 @@
+import type { AnalysisContext } from "./plan.ts";
+/** Sections recorded in `webda.module.json`. */
+export type Section = "models" | "moddas" | "deployers" | "beans";
+/** Structural metadata recorded for a model. */
+export interface ModelMetadata {
+    /** Namespaced name, repeated as the entry's own identifier. */
+    Identifier: string;
+    /** Pluralised display name. */
+    Plural: string;
+    /** Namespaced ancestors, nearest first. */
+    Ancestors: string[];
+    /** Namespaced direct subclasses. */
+    Subclasses: string[];
+    /** Attributes forming the primary key. */
+    PrimaryKey: string[];
+    /** Separator joining a composite primary key, when declared. */
+    PrimaryKeySeparator?: string;
+}
+/** One discovered Webda object. */
+export interface DiscoveredObject {
+    /** Namespaced name, as used for the section key. */
+    name: string;
+    /** Exported identifier. */
+    exportName: string;
+    /** Section it belongs to. */
+    section: Section;
+    /** `Import` value: output path without extension, then `:export`. */
+    importTarget: string;
+    /** File declaring it. */
+    fileName: string;
+    /** Name of the class as written, before any @Webda* tag renaming. */
+    className: string;
+    /** Names of the classes it derives from, nearest first. */
+    baseNames: string[];
+    /** Primary key attributes, when declared. */
+    primaryKey: string[];
+    /** Primary key separator, when declared. */
+    primaryKeySeparator?: string;
+}
+/** Discovery options. */
+export interface DiscoveryOptions {
+    /** Application root, used to relativise output paths. */
+    appPath: string;
+    /** Source root. */
+    rootDir: string;
+    /** Output root. */
+    outDir: string;
+    /** Namespace prefix applied to unqualified names. */
+    namespace?: string;
+    /**
+     * Return every classified class, including several resolving to the same
+     * namespaced name. The caller then owns deduplication — the module
+     * generator reproduces TypeScript 6's last-in-program-order-wins rule.
+     */
+    keepDuplicates?: boolean;
+}
+/**
+ * Name of the npm package that owns a file.
+ *
+ * Walks up to the nearest `package.json`, matching `getPackageFromType`.
+ * @param fileName - file to attribute
+ * @returns the package name, when one is found
+ */
+export declare function packageOf(fileName: string): string | undefined;
+/**
+ * The declared type of a class, and every type it derives from.
+ *
+ * Each base is re-resolved through its symbol: `getBaseTypes()` returns
+ * instantiated references whose own bases are empty, so a generic link
+ * otherwise terminates the walk.
+ * @param ctx - analysis context
+ * @param cls - the class declaration
+ * @returns the type chain, nearest first
+ */
+export declare function classTree(ctx: AnalysisContext, cls: any): any[];
+/**
+ * Whether a type chain contains a given class from a given package.
+ * @param ctx - analysis context
+ * @param chain - the type chain
+ * @param packageName - owning npm package
+ * @param symbolName - class name
+ * @returns true on a match
+ */
+export declare function chainExtends(ctx: AnalysisContext, chain: any[], packageName: string, symbolName: string): boolean;
+/**
+ * Output path for a source file, without extension.
+ *
+ * Mirrors `ts.getOutputFileNames` for the common `rootDir`/`outDir` layout.
+ * @param fileName - the source file
+ * @param options - discovery options
+ * @returns path relative to the application root
+ */
+export declare function outputTarget(fileName: string, options: DiscoveryOptions): string;
+/**
+ * The name a class is exported under, if any.
+ *
+ * Mirrors `getExportedName`: a `default` modifier records `"default"` rather
+ * than the class name, and a class with no export modifier may still be
+ * re-exported by a later `export { X }` — `webda.module.json` records the alias
+ * in both cases, so the `Import` string is wrong without this.
+ * @param ctx - analysis context
+ * @param sf - containing file
+ * @param cls - the class declaration
+ * @returns the exported name, or undefined when not exported
+ */
+export declare function exportedName(ctx: AnalysisContext, sf: any, cls: any): string | undefined;
+/**
+ * Discover every Webda object in the project.
+ * @param ctx - analysis context
+ * @param options - discovery options
+ * @returns discovered objects, ordered by section then name
+ */
+export declare function discoverWebdaObjects(ctx: AnalysisContext, options: DiscoveryOptions): DiscoveredObject[];
+/**
+ * Directory of the npm package that owns a file: the nearest folder with a
+ * `package.json`.
+ * @param fileName - file to attribute
+ * @returns the package directory, when one is found
+ */
+export declare function packageRootOf(fileName: string): string | undefined;
+/**
+ * Name of a model declared by a dependency package, as its own
+ * `webda.module.json` records it.
+ *
+ * The class is matched on its `Import` target: the declaring file relative to
+ * the package, without extension, then `:` and the export name. A source file
+ * (`src/x.ts`) also matches its compiled counterpart (`lib/x`).
+ * @param fileName - file declaring the class
+ * @param className - exported name of the class
+ * @param appPath - the project being compiled, whose own module is skipped
+ * @returns the namespaced model name, when the dependency declares one
+ */
+export declare function dependencyModelName(fileName: string, className: string, appPath: string): string | undefined;
+/**
+ * Build the structural half of each model's `webda.module.json` entry.
+ *
+ * Ancestors and subclasses are resolved among the discovered models, so they
+ * carry namespaced names rather than raw class names.
+ * @param objects - discovered objects
+ * @param plural - pluralisation function, supplied by the host
+ * @returns metadata per model name
+ */
+export declare function buildModelMetadata(objects: DiscoveredObject[], plural: (name: string) => string): Record<string, ModelMetadata>;
+/** One reflected attribute. */
+export interface ReflectedAttribute {
+    /** Type as written in the source. */
+    type: string;
+    /** Resolved type arguments, when the type is generic. */
+    typeParameters?: string[];
+}
+/**
+ * Reflect a model's attributes, as `webda.module.json` records them.
+ *
+ * The recorded type is the *written* text rather than a resolved type: an
+ * inline object literal appears verbatim, comments and all. Generic types are
+ * the exception — their arguments are resolved through the checker so a type
+ * parameter is reported as its constraint.
+ *
+ * Properties keyed by a symbol, carrying `@ignore`, or marked not-enumerable
+ * are excluded, matching the original.
+ * @param ctx - analysis context
+ * @param sf - file declaring the class
+ * @param cls - the class declaration
+ * @returns attribute name to reflected type
+ */
+export declare function reflectAttributes(ctx: AnalysisContext, sf: any, cls: any): Record<string, ReflectedAttribute>;
+/** Relations recorded for a model. */
+export interface ModelRelations {
+    /** Owning model, from a `ModelParent<T>` attribute. */
+    parent?: {
+        attribute: string;
+        model: string;
+    };
+    /**
+     * Outgoing links, from the `ModelLink*` family.
+     *
+     * `model` is absent when the target is a type parameter, as on a generic
+     * base class — the link is still real and is recorded without it.
+     */
+    links?: {
+        attribute: string;
+        model?: string;
+        type: string;
+    }[];
+    /** Reverse lookups, from `ModelRelated<T, U, "attr">`. */
+    queries?: {
+        attribute: string;
+        model: string;
+        targetAttribute: string;
+    }[];
+    /** Behaviour-typed attributes. */
+    behaviors?: {
+        attribute: string;
+        behavior: string;
+    }[];
+}
+/**
+ * Build a model's `Relations` entry.
+ *
+ * Relation kinds are recognised by the written type name — `ModelParent`,
+ * `ModelRelated`, the `ModelLink*` family — and the referenced model is
+ * resolved to its namespaced identifier so the graph is expressed in module
+ * terms rather than class names.
+ * @param ctx - analysis context
+ * @param sf - file declaring the class
+ * @param cls - the class declaration
+ * @param resolveModelId - maps a class name to its namespaced identifier
+ * @returns the relations, omitting empty groups
+ */
+export declare function buildRelations(ctx: AnalysisContext, sf: any, cls: any, resolveModelId: (className: string) => string | undefined): ModelRelations;
+//# sourceMappingURL=module-discovery.d.ts.map

package/lib/module-discovery.d.ts.map

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