@bluelibs/runner 3.2.0 → 3.3.1

package/dist/defs.d.ts

@@ -1,5 +1,27 @@
+/**
+ * Core public TypeScript types for BlueLibs Runner.
+ *
+ * This file contains the strongly-typed contract for tasks, resources, events
+ * and middleware. It mirrors the mental model described in the README:
+ * - Tasks are functions (with lifecycle events)
+ * - Resources are singletons (with init/dispose hooks and lifecycle events)
+ * - Events are simple, strongly-typed emissions
+ * - Middleware can target both tasks and resources
+ *
+ * DX goals:
+ * - Crystal‑clear generics and helper types that infer dependency shapes
+ * - Friendly JSDoc you can hover in editors to understand usage instantly
+ * - Safe overrides and strong typing around config and register mechanics
+ */
 import { MiddlewareEverywhereOptions } from "./define";
 export { ICacheInstance } from "./globals/middleware/cache.middleware";
+export * from "./models/StoreTypes";
+/**
+ * Internal brand symbols used to tag created objects at runtime and help with
+ * type‑narrowing. Prefer the `isTask`/`isResource`/`isEvent`/`isMiddleware`
+ * helpers instead of touching these directly.
+ * @internal
+ */
 export declare const symbolTask: unique symbol;
 export declare const symbolResource: unique symbol;
 export declare const symbolResourceWithConfig: unique symbol;
@@ -9,27 +31,81 @@ export declare const symbolMiddlewareConfigured: unique symbol;
 export declare const symbolMiddlewareGlobal: unique symbol;
 export declare const symbolMiddlewareEverywhereTasks: unique symbol;
 export declare const symbolMiddlewareEverywhereResources: unique symbol;
+/** @internal Path to aid anonymous id generation and error messages */
 export declare const symbolFilePath: unique symbol;
+/** @internal Marks disposable instances */
 export declare const symbolDispose: unique symbol;
+/** @internal Link to internal Store */
 export declare const symbolStore: unique symbol;
+/** @internal Brand used by index() resources */
 export declare const symbolIndexResource: unique symbol;
-export declare const symbols: {
-    task: symbol;
-    resource: symbol;
-    resourceWithConfig: symbol;
-    indexResource: symbol;
-    event: symbol;
-    middleware: symbol;
-    middlewareEverywhereTasks: symbol;
-    middlewareEverywhereResources: symbol;
-    filePath: symbol;
-    dispose: symbol;
-    store: symbol;
+export interface ITagDefinition<TConfig = void> {
+    id: string | symbol;
+}
+/**
+ * A configured instance of a tag as produced by `ITag.with()`.
+ */
+export interface ITagWithConfig<TConfig = void> {
+    id: string | symbol;
+    /** The tag definition used to produce this configured instance. */
+    tag: ITag<TConfig>;
+    /** The configuration captured for this tag instance. */
+    config: TConfig;
+}
+/**
+ * A tag definition (builder). Use `.with(config)` to obtain configured instances,
+ * and `.extract(tags)` to find either a configured instance or the bare tag in a list.
+ */
+export interface ITag<TConfig = void> extends ITagDefinition<TConfig> {
+    /**
+     * Creates a configured instance of the tag.
+     */
+    with(config: TConfig): ITagWithConfig<TConfig>;
+    /**
+     * Extracts either a configured instance or the bare tag from a list of tags
+     * or from a taggable object (`{ meta: { tags?: [] } }`).
+     */
+    extract(target: TagType[] | ITaggable): ExtractedTagResult<TConfig> | null;
+    [symbolFilePath]: string;
+}
+/**
+ * Restrict bare tags to those whose config can be omitted (void or optional object),
+ * mirroring the same principle used for resources in `RegisterableItems`.
+ * Required-config tags must appear as configured instances.
+ */
+export type TagType = string | ITag<void> | ITag<{
+    [K in any]?: any;
+}> | ITagWithConfig<any>;
+/**
+ * Conditional result type for `ITag.extract`:
+ * - For void config → just the identifier
+ * - For optional object config → identifier with optional config
+ * - For required config → identifier with required config
+ */
+export type ExtractedTagResult<TConfig> = {} extends TConfig ? {
+    id: string | symbol;
+    config?: TConfig;
+} : {
+    id: string | symbol;
+    config: TConfig;
 };
+/**
+ * Any object that can carry tags via metadata. This mirrors how tasks,
+ * resources, events, and middleware expose `meta.tags`.
+ */
+export interface ITaggable {
+    meta?: {
+        tags?: TagType[];
+    };
+}
+/**
+ * Common metadata you can attach to tasks/resources/events/middleware.
+ * Useful for docs, filtering and middleware decisions.
+ */
 export interface IMeta {
     title?: string;
     description?: string;
-    tags?: string[];
+    tags?: TagType[];
 }
 export interface ITaskMeta extends IMeta {
 }
@@ -39,27 +115,47 @@ export interface IEventMeta extends IMeta {
 }
 export interface IMiddlewareMeta extends IMeta {
 }
+/**
+ * A mapping of dependency keys to Runner definitions. Used in `dependencies`
+ * for tasks and resources. Values are later transformed into the actual
+ * callable/value shape by `DependencyValuesType`.
+ */
 export type DependencyMapType = Record<string, ITask<any, any, any, any> | IResource<any, any, any> | IEventDefinition<any>>;
 type ExtractTaskInput<T> = T extends ITask<infer I, any, infer D> ? I : never;
 type ExtractTaskOutput<T> = T extends ITask<any, infer O, infer D> ? O : never;
 type ExtractResourceValue<T> = T extends IResource<any, infer V, infer D> ? V : never;
 type ExtractEventParams<T> = T extends IEvent<infer P> ? P : never;
 /**
- * This represents a task dependency function that can be called with or without parameters.
+ * Task dependencies transform into callable functions: call with the task input
+ * and you receive the task output.
  */
 type TaskDependency<I, O> = (...args: I extends null | void ? [] : [I]) => O;
 /**
- * This represents the resource's value type.
+ * Resource dependencies resolve to the resource's value directly.
  */
 type ResourceDependency<V> = V;
 /**
- * This represents an event emission function that can be called with or without parameters.
+ * Event dependencies resolve to an emitter function. If the payload type is
+ * `void`, the function can be called with zero args (or an empty object).
  */
 type EventDependency<P> = P extends void ? (() => Promise<void>) & ((input?: Record<string, never>) => Promise<void>) : (input: P) => Promise<void>;
+/**
+ * Transforms a dependency definition into the usable shape inside `run`/`init`:
+ * - Task -> callable function
+ * - Resource -> resolved value
+ * - Event -> emit function
+ */
 export type DependencyValueType<T> = T extends ITask<any, any, any> ? TaskDependency<ExtractTaskInput<T>, ExtractTaskOutput<T>> : T extends IResource<any, any> ? ResourceDependency<ExtractResourceValue<T>> : T extends IEventDefinition<any> ? EventDependency<ExtractEventParams<T>> : never;
 export type DependencyValuesType<T extends DependencyMapType> = {
     [K in keyof T]: DependencyValueType<T[K]>;
 };
+/**
+ * Anything you can put inside a resource's `register: []`.
+ * - Resources (with or without `.with()`)
+ * - Tasks
+ * - Middleware
+ * - Events
+ */
 export type RegisterableItems<T = any> = IResourceWithConfig<any> | IResource<void, any, any, any> | IResource<{
     [K in any]?: any;
 }, any, any, any> | ITask<any, any, any, any> | IMiddleware<any> | IEvent<any>;
@@ -67,8 +163,17 @@ export type MiddlewareAttachments = IMiddleware<void> | IMiddleware<{
     [K in any]?: any;
 }> | IMiddlewareConfigured<any>;
 export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = any, TDependencies extends DependencyMapType = {}, TOn extends "*" | IEventDefinition<any> | undefined = undefined> {
+    /**
+     * Stable identifier. If omitted, an anonymous id is generated from file path
+     * (see README: Anonymous IDs).
+     */
     id?: string | symbol;
+    /**
+     * Access other tasks/resources/events. Can be an object or a function when
+     * you need late or config‑dependent resolution.
+     */
     dependencies?: TDependencies | (() => TDependencies);
+    /** Middleware applied around task execution. */
     middleware?: MiddlewareAttachments[];
     /**
      * Listen to events in a simple way
@@ -79,7 +184,12 @@ export interface ITaskDefinition<TInput = any, TOutput extends Promise<any> = an
      * The event with the lowest order will be executed first.
      */
     listenerOrder?: number;
+    /** Optional metadata used for docs, filtering and tooling. */
     meta?: ITaskMeta;
+    /**
+     * The task body. If `on` is set, the input is an `IEventEmission`. Otherwise,
+     * it's the declared input type.
+     */
     run: (input: TOn extends undefined ? TInput : IEventEmission<TOn extends "*" ? any : ExtractEventParams<TOn>>, dependencies: DependencyValuesType<TDependencies>) => TOutput;
 }
 export type BeforeRunEventPayload<TInput> = {
@@ -120,11 +230,22 @@ export interface ITask<TInput = any, TOutput extends Promise<any> = any, TDepend
         afterRun: IEvent<AfterRunEventPayload<TInput, TOutput>>;
         onError: IEvent<OnErrorEventPayload>;
     };
+    [symbolFilePath]: string;
+    [symbolTask]: true;
 }
 export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependencies extends DependencyMapType = {}, TContext = any, THooks = any, TRegisterableItems = any> {
+    /** Stable identifier. Omit to get an anonymous id. */
     id?: string | symbol;
+    /** Static or lazy dependency map. Receives `config` when provided. */
     dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * Register other registerables (resources/tasks/middleware/events). Accepts a
+     * static array or a function of `config` to support dynamic wiring.
+     */
     register?: Array<RegisterableItems> | ((config: TConfig) => Array<RegisterableItems>);
+    /**
+     * Initialize and return the resource value. Called once during boot.
+     */
     init?: (this: any, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<TValue>;
     /**
      * Clean-up function for the resource. This is called when the resource is no longer needed.
@@ -136,11 +257,20 @@ export interface IResourceDefinition<TConfig = any, TValue = unknown, TDependenc
      */
     dispose?: (this: any, value: TValue, config: TConfig, dependencies: DependencyValuesType<TDependencies>, context: TContext) => Promise<void>;
     meta?: IResourceMeta;
+    /**
+     * Safe overrides to swap behavior while preserving identities. See
+     * README: Overrides.
+     */
     overrides?: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
+    /** Middleware applied around init/dispose. */
     middleware?: MiddlewareAttachments[];
+    /**
+     * Create a private, mutable context shared between `init` and `dispose`.
+     */
     context?: () => TContext;
     /**
      * This is optional and used from an index resource to get the correct caller.
+     * This is the reason we allow it here as well.
      */
     [symbolFilePath]?: string;
     /**
@@ -162,14 +292,21 @@ export interface IResource<TConfig = void, TValue = any, TDependencies extends D
     };
     overrides: Array<IResource | ITask | IMiddleware | IResourceWithConfig>;
     middleware: MiddlewareAttachments[];
+    [symbolFilePath]: string;
+    [symbolIndexResource]: boolean;
+    [symbolResource]: true;
 }
 export interface IResourceWithConfig<TConfig = any, TValue = any, TDependencies extends DependencyMapType = any> {
+    /** The id of the underlying resource. */
     id: string;
+    /** The underlying resource definition. */
     resource: IResource<TConfig, TValue, TDependencies>;
+    /** The configuration captured by `.with(config)`. */
     config: TConfig;
 }
 export type EventHandlerType<T = any> = (event: IEventEmission<T>) => any | Promise<any>;
 export interface IEventDefinition<TPayload = void> {
+    /** Stable identifier. Omit to get an anonymous id. */
     id?: string | symbol;
     meta?: IEventMeta;
 }
@@ -179,6 +316,7 @@ export interface IEvent<TPayload = any> extends IEventDefinition<TPayload> {
      * We use this event to discriminate between resources with just 'id' and 'events' as they collide. This is a workaround, should be redone using classes and instanceof.
      */
     [symbolEvent]: true;
+    [symbolFilePath]: string;
 }
 /**
  * This represents the object that is passed to event handlers
@@ -215,8 +353,13 @@ export interface IEventEmission<TPayload = any> {
     isPropagationStopped(): boolean;
 }
 export interface IMiddlewareDefinition<TConfig = any, TDependencies extends DependencyMapType = any> {
+    /** Stable identifier. Omit to get an anonymous id. */
     id?: string | symbol;
+    /** Static or lazy dependency map. */
     dependencies?: TDependencies | ((config: TConfig) => TDependencies);
+    /**
+     * The middleware body, called with task/resource execution input.
+     */
     run: (input: IMiddlewareExecutionInput, dependencies: DependencyValuesType<TDependencies>, config: TConfig) => Promise<any>;
     meta?: IMiddlewareMeta;
 }
@@ -227,9 +370,16 @@ export interface IMiddleware<TConfig = any, TDependencies extends DependencyMapT
     [symbolMiddlewareEverywhereResources]?: boolean;
     id: string | symbol;
     dependencies: TDependencies | (() => TDependencies);
+    /**
+     * Attach this middleware globally. Use options to scope to tasks/resources.
+     */
     everywhere(config?: MiddlewareEverywhereOptions): IMiddleware<TConfig, TDependencies>;
+    /** Current configuration object (empty by default). */
     config: TConfig;
+    /** Configure the middleware and return a marked, configured instance. */
     with: (config: TConfig) => IMiddlewareConfigured<TConfig, TDependencies>;
+    [symbolFilePath]: string;
+    [symbolMiddleware]: true;
 }
 export interface IMiddlewareConfigured<TConfig = any, TDependencies extends DependencyMapType = any> extends IMiddleware<TConfig, TDependencies> {
     [symbolMiddlewareConfigured]: true;
@@ -239,10 +389,12 @@ export interface IMiddlewareDefinitionConfigured<C extends Record<string, any> =
     config?: C;
 }
 export interface IMiddlewareExecutionInput<TTaskInput = any, TResourceConfig = any> {
+    /** Task hook: present when wrapping a task run. */
     task?: {
         definition: ITask<TTaskInput>;
         input: TTaskInput;
     };
+    /** Resource hook: present when wrapping init/dispose. */
     resource?: {
         definition: IResource<TResourceConfig>;
         config: TResourceConfig;

package/dist/defs.js

@@ -1,6 +1,42 @@
 "use strict";
+/**
+ * Core public TypeScript types for BlueLibs Runner.
+ *
+ * This file contains the strongly-typed contract for tasks, resources, events
+ * and middleware. It mirrors the mental model described in the README:
+ * - Tasks are functions (with lifecycle events)
+ * - Resources are singletons (with init/dispose hooks and lifecycle events)
+ * - Events are simple, strongly-typed emissions
+ * - Middleware can target both tasks and resources
+ *
+ * DX goals:
+ * - Crystal‑clear generics and helper types that infer dependency shapes
+ * - Friendly JSDoc you can hover in editors to understand usage instantly
+ * - Safe overrides and strong typing around config and register mechanics
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.symbols = exports.symbolIndexResource = exports.symbolStore = exports.symbolDispose = exports.symbolFilePath = exports.symbolMiddlewareEverywhereResources = exports.symbolMiddlewareEverywhereTasks = exports.symbolMiddlewareGlobal = exports.symbolMiddlewareConfigured = exports.symbolMiddleware = exports.symbolEvent = exports.symbolResourceWithConfig = exports.symbolResource = exports.symbolTask = void 0;
+exports.symbolIndexResource = exports.symbolStore = exports.symbolDispose = exports.symbolFilePath = exports.symbolMiddlewareEverywhereResources = exports.symbolMiddlewareEverywhereTasks = exports.symbolMiddlewareGlobal = exports.symbolMiddlewareConfigured = exports.symbolMiddleware = exports.symbolEvent = exports.symbolResourceWithConfig = exports.symbolResource = exports.symbolTask = void 0;
+__exportStar(require("./models/StoreTypes"), exports);
+/**
+ * Internal brand symbols used to tag created objects at runtime and help with
+ * type‑narrowing. Prefer the `isTask`/`isResource`/`isEvent`/`isMiddleware`
+ * helpers instead of touching these directly.
+ * @internal
+ */
 exports.symbolTask = Symbol("runner.task");
 exports.symbolResource = Symbol("runner.resource");
 exports.symbolResourceWithConfig = Symbol("runner.resourceWithConfig");
@@ -10,21 +46,12 @@ exports.symbolMiddlewareConfigured = Symbol("runner.middlewareConfigured");
 exports.symbolMiddlewareGlobal = Symbol("runner.middlewareGlobal");
 exports.symbolMiddlewareEverywhereTasks = Symbol("runner.middlewareGlobalTasks");
 exports.symbolMiddlewareEverywhereResources = Symbol("runner.middlewareGlobalResources");
+/** @internal Path to aid anonymous id generation and error messages */
 exports.symbolFilePath = Symbol("runner.filePath");
+/** @internal Marks disposable instances */
 exports.symbolDispose = Symbol("runner.dispose");
+/** @internal Link to internal Store */
 exports.symbolStore = Symbol("runner.store");
+/** @internal Brand used by index() resources */
 exports.symbolIndexResource = Symbol("runner.indexResource");
-exports.symbols = {
-    task: exports.symbolTask,
-    resource: exports.symbolResource,
-    resourceWithConfig: exports.symbolResourceWithConfig,
-    indexResource: exports.symbolIndexResource,
-    event: exports.symbolEvent,
-    middleware: exports.symbolMiddleware,
-    middlewareEverywhereTasks: exports.symbolMiddlewareEverywhereTasks,
-    middlewareEverywhereResources: exports.symbolMiddlewareEverywhereResources,
-    filePath: exports.symbolFilePath,
-    dispose: exports.symbolDispose,
-    store: exports.symbolStore,
-};
 //# sourceMappingURL=defs.js.map

package/dist/defs.js.map

@@ -1 +1 @@
-{"version":3,"file":"defs.js","sourceRoot":"","sources":["../src/defs.ts"],"names":[],"mappings":";;;AAKa,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEW,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACxD,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEpD,QAAA,mBAAmB,GAAkB,MAAM,CACtD,sBAAsB,CACvB,CAAC;AAEW,QAAA,OAAO,GAAG;IACrB,IAAI,EAAE,kBAAU;IAChB,QAAQ,EAAE,sBAAc;IACxB,kBAAkB,EAAE,gCAAwB;IAC5C,aAAa,EAAE,2BAAmB;IAClC,KAAK,EAAE,mBAAW;IAClB,UAAU,EAAE,wBAAgB;IAC5B,yBAAyB,EAAE,uCAA+B;IAC1D,6BAA6B,EAAE,2CAAmC;IAClE,QAAQ,EAAE,sBAAc;IACxB,OAAO,EAAE,qBAAa;IACtB,KAAK,EAAE,mBAAW;CACnB,CAAC"}
+{"version":3,"file":"defs.js","sourceRoot":"","sources":["../src/defs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG;;;;;;;;;;;;;;;;;AAMH,sDAAoC;AACpC;;;;;GAKG;AACU,QAAA,UAAU,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AAClD,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AAC1D,QAAA,wBAAwB,GAAkB,MAAM,CAC3D,2BAA2B,CAC5B,CAAC;AACW,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AACpD,QAAA,gBAAgB,GAAkB,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAC9D,QAAA,0BAA0B,GAAkB,MAAM,CAC7D,6BAA6B,CAC9B,CAAC;AACW,QAAA,sBAAsB,GAAkB,MAAM,CACzD,yBAAyB,CAC1B,CAAC;AACW,QAAA,+BAA+B,GAAkB,MAAM,CAClE,8BAA8B,CAC/B,CAAC;AACW,QAAA,mCAAmC,GAAkB,MAAM,CACtE,kCAAkC,CACnC,CAAC;AAEF,uEAAuE;AAC1D,QAAA,cAAc,GAAkB,MAAM,CAAC,iBAAiB,CAAC,CAAC;AACvE,2CAA2C;AAC9B,QAAA,aAAa,GAAkB,MAAM,CAAC,gBAAgB,CAAC,CAAC;AACrE,uCAAuC;AAC1B,QAAA,WAAW,GAAkB,MAAM,CAAC,cAAc,CAAC,CAAC;AAEjE,gDAAgD;AACnC,QAAA,mBAAmB,GAAkB,MAAM,CACtD,sBAAsB,CACvB,CAAC"}

package/dist/docs/introspect.d.ts

@@ -0,0 +1,7 @@
+import type { IResource } from "../defs";
+import { DocsGraph } from "./model";
+type IntrospectOptions = {
+    includeGlobals?: boolean;
+};
+export declare function introspectResource(root: IResource<any, any, any, any>, config?: any, options?: IntrospectOptions): Promise<DocsGraph>;
+export {};

package/dist/docs/introspect.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.introspectResource = introspectResource;
+const EventManager_1 = require("../models/EventManager");
+const Logger_1 = require("../models/Logger");
+const Store_1 = require("../models/Store");
+const defs_1 = require("../defs");
+const model_1 = require("./model");
+async function introspectResource(root, config = {}, options = {}) {
+    const includeGlobals = options.includeGlobals ?? false;
+    // Build a Store but do not compute dependencies or initialize root.
+    const eventManager = new EventManager_1.EventManager();
+    const logger = new Logger_1.Logger(eventManager);
+    const store = new Store_1.Store(eventManager, logger);
+    // Only registration phase, with overrides processed, but no init.
+    store.initializeStore(root, config);
+    store.processOverrides();
+    const nodes = [];
+    const edges = [];
+    // Helpers
+    const shouldInclude = (id) => {
+        const str = (0, model_1.normalizeId)(id);
+        if (includeGlobals)
+            return true;
+        return !str.startsWith("globals.");
+    };
+    // Resources
+    for (const res of store.resources.values()) {
+        if (!shouldInclude(res.resource.id))
+            continue;
+        nodes.push({
+            ...(0, model_1.buildBaseNode)("resource", res.resource.id, res.resource[defs_1.symbols.filePath], res.resource.meta),
+        });
+        const regItems = Array.isArray(res.resource.register)
+            ? res.resource.register
+            : [];
+        for (const item of regItems) {
+            const targetId = item.id || item?.resource?.id;
+            if (!targetId || !shouldInclude(targetId))
+                continue;
+            edges.push({
+                type: "registers",
+                from: (0, model_1.normalizeId)(res.resource.id),
+                to: (0, model_1.normalizeId)(targetId),
+            });
+        }
+        // Resource dependencies
+        const deps = (res.resource.dependencies || {});
+        for (const depKey of Object.keys(deps)) {
+            const dep = deps[depKey];
+            const depId = dep?.id;
+            if (!depId || !shouldInclude(depId))
+                continue;
+            edges.push({
+                type: "dependsOn",
+                from: (0, model_1.normalizeId)(res.resource.id),
+                to: (0, model_1.normalizeId)(depId),
+                meta: { key: depKey },
+            });
+        }
+        // Resource middleware
+        for (const mw of res.resource.middleware || []) {
+            const mwId = mw.id;
+            if (!mwId || !shouldInclude(mwId))
+                continue;
+            edges.push({
+                type: "middleware",
+                from: (0, model_1.normalizeId)(res.resource.id),
+                to: (0, model_1.normalizeId)(mwId),
+                meta: { scope: "resource" },
+            });
+        }
+    }
+    // Tasks
+    for (const t of store.tasks.values()) {
+        if (!shouldInclude(t.task.id))
+            continue;
+        nodes.push({
+            ...(0, model_1.buildBaseNode)("task", t.task.id, t.task[defs_1.symbols.filePath], t.task.meta),
+            on: t.task.on
+                ? t.task.on === "*"
+                    ? "*"
+                    : (0, model_1.normalizeId)(t.task.on.id)
+                : undefined,
+            listenerOrder: t.task.listenerOrder,
+        });
+        // Dependencies
+        const deps = (t.task.dependencies || {});
+        for (const depKey of Object.keys(deps)) {
+            const dep = deps[depKey];
+            const depId = dep?.id;
+            if (!depId || !shouldInclude(depId))
+                continue;
+            edges.push({
+                type: "dependsOn",
+                from: (0, model_1.normalizeId)(t.task.id),
+                to: (0, model_1.normalizeId)(depId),
+                meta: { key: depKey },
+            });
+        }
+        // Middleware
+        for (const mw of t.task.middleware || []) {
+            const mwId = mw.id;
+            if (!mwId || !shouldInclude(mwId))
+                continue;
+            edges.push({
+                type: "middleware",
+                from: (0, model_1.normalizeId)(t.task.id),
+                to: (0, model_1.normalizeId)(mwId),
+                meta: { scope: "task" },
+            });
+        }
+        // Listeners
+        if (t.task.on && t.task.on !== "*") {
+            const eventId = t.task.on.id;
+            if (shouldInclude(eventId)) {
+                edges.push({
+                    type: "listensTo",
+                    from: (0, model_1.normalizeId)(t.task.id),
+                    to: (0, model_1.normalizeId)(eventId),
+                });
+            }
+        }
+    }
+    // Events (registered globally + lifecycle + custom)
+    for (const e of store.events.values()) {
+        const eventId = e.event.id;
+        if (!eventId)
+            continue;
+        if (!shouldInclude(eventId))
+            continue;
+        nodes.push({
+            ...(0, model_1.buildBaseNode)("event", eventId, e.event[defs_1.symbols.filePath], e.event.meta),
+        });
+    }
+    // Middleware nodes
+    for (const mw of store.middlewares.values()) {
+        if (!shouldInclude(mw.middleware.id))
+            continue;
+        nodes.push({
+            ...(0, model_1.buildBaseNode)("middleware", mw.middleware.id, mw.middleware[defs_1.symbols.filePath], mw.middleware.meta),
+            everywhere: {
+                tasks: Boolean(mw.middleware[defs_1.symbols.middlewareEverywhereTasks]),
+                resources: Boolean(mw.middleware[defs_1.symbols.middlewareEverywhereResources]),
+            },
+        });
+        // Dependencies of middleware
+        const deps = (mw.middleware.dependencies || {});
+        for (const depKey of Object.keys(deps)) {
+            const dep = deps[depKey];
+            const depId = dep?.id;
+            if (!depId || !shouldInclude(depId))
+                continue;
+            edges.push({
+                type: "dependsOn",
+                from: (0, model_1.normalizeId)(mw.middleware.id),
+                to: (0, model_1.normalizeId)(depId),
+                meta: { key: depKey },
+            });
+        }
+    }
+    // Override requests and overrides mapping
+    for (const req of store.overrideRequests) {
+        const source = req.source;
+        const targetId = req.override?.id || req.override?.resource?.id;
+        if (targetId && shouldInclude(source) && shouldInclude(targetId)) {
+            edges.push({
+                type: "overrideRequest",
+                from: (0, model_1.normalizeId)(source),
+                to: (0, model_1.normalizeId)(targetId),
+            });
+        }
+    }
+    for (const [id, ov] of store.overrides) {
+        if (!shouldInclude(id))
+            continue;
+        edges.push({
+            type: "overrides",
+            from: (0, model_1.normalizeId)(ov.id || ov?.resource?.id),
+            to: (0, model_1.normalizeId)(id),
+        });
+    }
+    const graph = {
+        version: 1,
+        summary: {
+            counts: {
+                resources: nodes.filter((n) => n.kind === "resource").length,
+                tasks: nodes.filter((n) => n.kind === "task").length,
+                events: nodes.filter((n) => n.kind === "event").length,
+                middleware: nodes.filter((n) => n.kind === "middleware").length,
+                edges: edges.length,
+            },
+        },
+        nodes,
+        edges,
+    };
+    return graph;
+}
+//# sourceMappingURL=introspect.js.map

package/dist/docs/introspect.js.map

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

package/dist/docs/markdown.d.ts

@@ -0,0 +1,2 @@
+import { DocsGraph } from "./model";
+export declare function renderMarkdown(graph: DocsGraph, outDir: string): void;