@warlock.js/core 5.30.0 → 5.31.0

package/esm/tooling/inspect/collect-models.mjs

@@ -0,0 +1,154 @@
+import { getAllModelsFromRegistry } from "@warlock.js/cascade";
+import { isLazy } from "@mongez/reinforcements";
+
+//#region ../../packages/core/src/tooling/inspect/collect-models.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** A static property of a class, read structurally. */
+function staticOf(model, key) {
+	return typeof model === "function" ? Reflect.get(model, key) : void 0;
+}
+function stringOrNull(value) {
+	return typeof value === "string" && value.length > 0 ? value : null;
+}
+/**
+* Whether a value is a Cascade model class: a class with its own `table` and
+* the static `query()` every model inherits. Read by shape, not `instanceof`.
+*/
+function isModelClass(value) {
+	return typeof value === "function" && typeof Reflect.get(value, "table") === "string" && typeof Reflect.get(value, "query") === "function";
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function readColumns(model, name, warnings) {
+	const schema = staticOf(model, "schema");
+	if (typeof schema !== "object" || schema === null) return [];
+	const convert = Reflect.get(schema, "toJsonSchema");
+	if (typeof convert !== "function") return [];
+	let json;
+	try {
+		json = convert.call(schema, "draft-2020-12");
+	} catch (error) {
+		warnings.push({
+			code: "WL4001",
+			message: `${name}.schema could not be converted to JSON Schema: ${errorMessage(error)}`,
+			source: "models"
+		});
+		return [];
+	}
+	if (!isRecord(json) || !isRecord(json.properties)) return [];
+	const required = new Set(Array.isArray(json.required) ? json.required.filter((key) => typeof key === "string") : []);
+	return Object.entries(json.properties).map(([column, columnSchema]) => ({
+		name: column,
+		required: required.has(column),
+		schema: isRecord(columnSchema) ? columnSchema : {}
+	})).sort((first, second) => first.name.localeCompare(second.name));
+}
+/** The name of a relation target given as a string, a class or `lazy(() => X)`. */
+function relationTargetName(target) {
+	if (typeof target === "string") return target;
+	try {
+		const resolved = isLazy(target) ? target.resolve() : target;
+		return typeof resolved === "function" && resolved.name ? resolved.name : null;
+	} catch {
+		return null;
+	}
+}
+function readRelations(model) {
+	const relations = staticOf(model, "relations");
+	if (!isRecord(relations)) return [];
+	return Object.entries(relations).filter((entry) => isRecord(entry[1])).map(([name, definition]) => ({
+		name,
+		type: typeof definition.type === "string" ? definition.type : "unknown",
+		model: relationTargetName(definition.model),
+		foreignKey: stringOrNull(definition.foreignKey),
+		localKey: stringOrNull(definition.localKey)
+	})).sort((first, second) => first.name.localeCompare(second.name));
+}
+function columnSetting(model, key) {
+	return stringOrNull(staticOf(model, key));
+}
+/**
+* Describe every model the app defines: the classes exported by the model
+* modules the boot pass imported, plus everything `@RegisterModel()` put in
+* Cascade's registry. Columns come from the model's Seal `schema` as JSON
+* Schema; the model's resource is registered in `registry` so its output
+* shape lands in `components.schemas`.
+*/
+function collectModels(modules, registry, warnings) {
+	const found = /* @__PURE__ */ new Map();
+	for (const module of modules) for (const [exportName, value] of Object.entries(module.exports)) {
+		if (!isModelClass(value) || found.has(value)) continue;
+		found.set(value, {
+			name: value.name || exportName,
+			sourceFile: module.file,
+			registered: false
+		});
+	}
+	for (const [name, model] of getAllModelsFromRegistry()) {
+		const existing = found.get(model);
+		if (existing) {
+			existing.registered = true;
+			existing.name = name;
+		} else found.set(model, {
+			name,
+			sourceFile: null,
+			registered: true
+		});
+	}
+	const resourceModels = /* @__PURE__ */ new Map();
+	const models = [];
+	for (const [model, meta] of found) try {
+		const resource = staticOf(model, "resource");
+		let resourceName = null;
+		if (registry.isResourceClass(resource)) {
+			const ref = registry.resourceRef(resource).$ref;
+			resourceName = typeof ref === "string" ? ref.split("/").pop() ?? null : null;
+			if (resourceName) resourceModels.set(resourceName, [...resourceModels.get(resourceName) ?? [], meta.name]);
+		}
+		const dataSource = staticOf(model, "dataSource");
+		const deletedAt = staticOf(model, "deletedAtColumn");
+		models.push({
+			name: meta.name,
+			table: stringOrNull(staticOf(model, "table")),
+			primaryKey: stringOrNull(staticOf(model, "primaryKey")),
+			dataSource: stringOrNull(dataSource),
+			sourceFile: meta.sourceFile,
+			registered: meta.registered,
+			columns: readColumns(model, meta.name, warnings),
+			relations: readRelations(model),
+			resource: resourceName,
+			deleteStrategy: columnSetting(model, "deleteStrategy"),
+			createdAtColumn: columnSetting(model, "createdAtColumn"),
+			updatedAtColumn: columnSetting(model, "updatedAtColumn"),
+			deletedAtColumn: stringOrNull(deletedAt)
+		});
+	} catch (error) {
+		warnings.push({
+			code: null,
+			message: `Model ${meta.name} could not be described: ${errorMessage(error)}`,
+			source: meta.sourceFile ?? "models"
+		});
+	}
+	return {
+		models: models.sort((first, second) => first.name.localeCompare(second.name)),
+		resourceModels
+	};
+}
+/**
+* Every resource in `components.schemas`, with the models that use it. Called
+* after routes and models registered their resources.
+*/
+function collectResources(registry, resourceModels) {
+	return Object.entries(registry.schemas).map(([name, schema]) => ({
+		name,
+		schema,
+		models: [...resourceModels.get(name) ?? []].sort()
+	})).sort((first, second) => first.name.localeCompare(second.name));
+}
+
+//#endregion
+export { collectModels, collectResources };
+//# sourceMappingURL=collect-models.mjs.map

package/esm/tooling/inspect/collect-models.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-models.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/collect-models.ts"],"sourcesContent":["import { isLazy } from \"@mongez/reinforcements\";\nimport { getAllModelsFromRegistry } from \"@warlock.js/cascade\";\nimport type { SchemaRegistry } from \"../../openapi/schema-registry\";\nimport type {\n  InspectModel,\n  InspectModelColumn,\n  InspectModelRelation,\n  InspectResource,\n  InspectWarning,\n  JsonSchema,\n} from \"./inspect-report.types\";\n\n/** A model module the boot pass imported: its file and its exports. */\nexport type InspectModelModule = {\n  /** Project-relative path. */\n  file: string;\n  exports: Record<string, unknown>;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/** A static property of a class, read structurally. */\nfunction staticOf(model: unknown, key: string): unknown {\n  return typeof model === \"function\" ? Reflect.get(model, key) : undefined;\n}\n\nfunction stringOrNull(value: unknown): string | null {\n  return typeof value === \"string\" && value.length > 0 ? value : null;\n}\n\n/**\n * Whether a value is a Cascade model class: a class with its own `table` and\n * the static `query()` every model inherits. Read by shape, not `instanceof`.\n */\nexport function isModelClass(value: unknown): value is (...args: never[]) => unknown {\n  return (\n    typeof value === \"function\" &&\n    typeof Reflect.get(value, \"table\") === \"string\" &&\n    typeof Reflect.get(value, \"query\") === \"function\"\n  );\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction readColumns(\n  model: unknown,\n  name: string,\n  warnings: InspectWarning[],\n): InspectModelColumn[] {\n  const schema = staticOf(model, \"schema\");\n\n  if (typeof schema !== \"object\" || schema === null) return [];\n\n  const convert = Reflect.get(schema, \"toJsonSchema\");\n\n  if (typeof convert !== \"function\") return [];\n\n  let json: unknown;\n\n  try {\n    json = convert.call(schema, \"draft-2020-12\");\n  } catch (error) {\n    warnings.push({\n      code: \"WL4001\",\n      message: `${name}.schema could not be converted to JSON Schema: ${errorMessage(error)}`,\n      source: \"models\",\n    });\n\n    return [];\n  }\n\n  if (!isRecord(json) || !isRecord(json.properties)) {\n    return [];\n  }\n\n  const required = new Set(\n    Array.isArray(json.required) ? json.required.filter((key) => typeof key === \"string\") : [],\n  );\n\n  return Object.entries(json.properties)\n    .map(([column, columnSchema]) => ({\n      name: column,\n      required: required.has(column),\n      schema: isRecord(columnSchema) ? (columnSchema as JsonSchema) : {},\n    }))\n    .sort((first, second) => first.name.localeCompare(second.name));\n}\n\n/** The name of a relation target given as a string, a class or `lazy(() => X)`. */\nfunction relationTargetName(target: unknown): string | null {\n  if (typeof target === \"string\") return target;\n\n  try {\n    const resolved = isLazy(target) ? target.resolve() : target;\n\n    return typeof resolved === \"function\" && resolved.name ? resolved.name : null;\n  } catch {\n    return null;\n  }\n}\n\nfunction readRelations(model: unknown): InspectModelRelation[] {\n  const relations = staticOf(model, \"relations\");\n\n  if (!isRecord(relations)) return [];\n\n  return Object.entries(relations)\n    .filter((entry): entry is [string, Record<string, unknown>] => isRecord(entry[1]))\n    .map(([name, definition]) => ({\n      name,\n      type: typeof definition.type === \"string\" ? definition.type : \"unknown\",\n      model: relationTargetName(definition.model),\n      foreignKey: stringOrNull(definition.foreignKey),\n      localKey: stringOrNull(definition.localKey),\n    }))\n    .sort((first, second) => first.name.localeCompare(second.name));\n}\n\nfunction columnSetting(model: unknown, key: string): string | null {\n  return stringOrNull(staticOf(model, key));\n}\n\n/** The outcome of {@link collectModels}: the models plus the resources they name. */\nexport type CollectedModels = {\n  models: InspectModel[];\n  /** Resource classes keyed by the name they got in `components.schemas`, with their models. */\n  resourceModels: Map<string, string[]>;\n};\n\n/**\n * Describe every model the app defines: the classes exported by the model\n * modules the boot pass imported, plus everything `@RegisterModel()` put in\n * Cascade's registry. Columns come from the model's Seal `schema` as JSON\n * Schema; the model's resource is registered in `registry` so its output\n * shape lands in `components.schemas`.\n */\nexport function collectModels(\n  modules: readonly InspectModelModule[],\n  registry: SchemaRegistry,\n  warnings: InspectWarning[],\n): CollectedModels {\n  const found = new Map<\n    unknown,\n    { name: string; sourceFile: string | null; registered: boolean }\n  >();\n\n  for (const module of modules) {\n    for (const [exportName, value] of Object.entries(module.exports)) {\n      if (!isModelClass(value) || found.has(value)) continue;\n\n      found.set(value, {\n        name: value.name || exportName,\n        sourceFile: module.file,\n        registered: false,\n      });\n    }\n  }\n\n  for (const [name, model] of getAllModelsFromRegistry()) {\n    const existing = found.get(model);\n\n    if (existing) {\n      existing.registered = true;\n      existing.name = name;\n    } else {\n      found.set(model, { name, sourceFile: null, registered: true });\n    }\n  }\n\n  const resourceModels = new Map<string, string[]>();\n  const models: InspectModel[] = [];\n\n  for (const [model, meta] of found) {\n    try {\n      const resource = staticOf(model, \"resource\");\n      let resourceName: string | null = null;\n\n      if (registry.isResourceClass(resource)) {\n        const ref = registry.resourceRef(resource).$ref;\n\n        resourceName = typeof ref === \"string\" ? (ref.split(\"/\").pop() ?? null) : null;\n\n        if (resourceName) {\n          resourceModels.set(resourceName, [\n            ...(resourceModels.get(resourceName) ?? []),\n            meta.name,\n          ]);\n        }\n      }\n\n      const dataSource = staticOf(model, \"dataSource\");\n      const deletedAt = staticOf(model, \"deletedAtColumn\");\n\n      models.push({\n        name: meta.name,\n        table: stringOrNull(staticOf(model, \"table\")),\n        primaryKey: stringOrNull(staticOf(model, \"primaryKey\")),\n        dataSource: stringOrNull(dataSource),\n        sourceFile: meta.sourceFile,\n        registered: meta.registered,\n        columns: readColumns(model, meta.name, warnings),\n        relations: readRelations(model),\n        resource: resourceName,\n        deleteStrategy: columnSetting(model, \"deleteStrategy\"),\n        createdAtColumn: columnSetting(model, \"createdAtColumn\"),\n        updatedAtColumn: columnSetting(model, \"updatedAtColumn\"),\n        deletedAtColumn: stringOrNull(deletedAt),\n      });\n    } catch (error) {\n      warnings.push({\n        code: null,\n        message: `Model ${meta.name} could not be described: ${errorMessage(error)}`,\n        source: meta.sourceFile ?? \"models\",\n      });\n    }\n  }\n\n  return {\n    models: models.sort((first, second) => first.name.localeCompare(second.name)),\n    resourceModels,\n  };\n}\n\n/**\n * Every resource in `components.schemas`, with the models that use it. Called\n * after routes and models registered their resources.\n */\nexport function collectResources(\n  registry: SchemaRegistry,\n  resourceModels: ReadonlyMap<string, string[]>,\n): InspectResource[] {\n  return Object.entries(registry.schemas)\n    .map(([name, schema]) => ({\n      name,\n      schema,\n      models: [...(resourceModels.get(name) ?? [])].sort(),\n    }))\n    .sort((first, second) => first.name.localeCompare(second.name));\n}\n"],"mappings":"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"}

package/esm/tooling/inspect/collect-packages.d.mts

@@ -0,0 +1,10 @@
+//#region ../../packages/core/src/tooling/inspect/collect-packages.d.ts
+/**
+ * Import a package the way the APP resolves it, so inspect reads the same
+ * module instance (and registry) the app's own modules populated. Resolves to
+ * `undefined` when the app does not have the package.
+ */
+type AppModuleImporter = (specifier: string) => Promise<unknown>;
+//#endregion
+export { AppModuleImporter };
+//# sourceMappingURL=collect-packages.d.mts.map

package/esm/tooling/inspect/collect-packages.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-packages.d.mts","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/collect-packages.ts"],"mappings":";AAgBA;;;;AAA8D;AAA9D,KAAY,iBAAA,IAAqB,SAAA,aAAsB,OAAO"}

package/esm/tooling/inspect/collect-packages.mjs

@@ -0,0 +1,157 @@
+import path from "node:path";
+import { readFileSync, readdirSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { resolve as resolve$1 } from "import-meta-resolve";
+
+//#region ../../packages/core/src/tooling/inspect/collect-packages.ts
+/** The default {@link AppModuleImporter}: resolve from `<cwd>/package.json`, then import. */
+function createAppModuleImporter(cwd) {
+	return async (specifier) => {
+		let url;
+		try {
+			url = resolve$1(specifier, pathToFileURL(path.join(cwd, "package.json")).href);
+		} catch {
+			return;
+		}
+		return import(url);
+	};
+}
+function readJson(file) {
+	try {
+		return JSON.parse(readFileSync(file, "utf8"));
+	} catch {
+		return;
+	}
+}
+function stringField(value, key) {
+	if (typeof value !== "object" || value === null) return null;
+	const field = Reflect.get(value, key);
+	return typeof field === "string" ? field : null;
+}
+/** The app's own `name` and `version`. */
+function readAppPackage(cwd) {
+	const manifest = readJson(path.join(cwd, "package.json"));
+	return {
+		name: stringField(manifest, "name"),
+		version: stringField(manifest, "version")
+	};
+}
+/** Every `@warlock.js/*` package installed at the app root, with its version. */
+function collectPackages(cwd) {
+	const scope = path.join(cwd, "node_modules", "@warlock.js");
+	let entries;
+	try {
+		entries = readdirSync(scope);
+	} catch {
+		return [];
+	}
+	const packages = [];
+	for (const entry of entries) {
+		const manifest = readJson(path.join(scope, entry, "package.json"));
+		const name = stringField(manifest, "name");
+		const version = stringField(manifest, "version");
+		if (name && version) packages.push({
+			name,
+			version
+		});
+	}
+	return packages.sort((first, second) => first.name.localeCompare(second.name));
+}
+function errorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function numberOrNull(value) {
+	return typeof value === "number" ? value : null;
+}
+function retentionOf(value) {
+	return typeof value === "boolean" || typeof value === "number" ? value : null;
+}
+function backoffOf(value) {
+	if (typeof value === "number") return value;
+	if (typeof value === "object" && value !== null) {
+		const type = Reflect.get(value, "type");
+		const delay = Reflect.get(value, "delay");
+		if (typeof type === "string" && typeof delay === "number") return {
+			type,
+			delay
+		};
+	}
+	return null;
+}
+/**
+* The jobs `defineJob()` registered, read from the app's `@warlock.js/queue`
+* (`registeredJobs()` / `queueOf()`). Empty when the app has no queue package.
+*/
+async function collectJobs(importFromApp, warnings) {
+	let queue;
+	try {
+		queue = await importFromApp("@warlock.js/queue");
+	} catch (error) {
+		warnings.push({
+			code: null,
+			message: `@warlock.js/queue could not be loaded: ${errorMessage(error)}`,
+			source: "jobs"
+		});
+		return [];
+	}
+	if (typeof queue !== "object" || queue === null) return [];
+	const registered = Reflect.get(queue, "registeredJobs");
+	const queueOf = Reflect.get(queue, "queueOf");
+	if (typeof registered !== "function") return [];
+	const jobs = registered();
+	if (!Array.isArray(jobs)) return [];
+	return jobs.filter((job) => typeof job === "object" && job !== null).map((job) => {
+		const queueName = typeof queueOf === "function" ? queueOf(job) : Reflect.get(job, "queue");
+		return {
+			name: stringField(job, "name") ?? "anonymous",
+			queue: typeof queueName === "string" ? queueName : "default",
+			attempts: numberOrNull(Reflect.get(job, "attempts")),
+			backoff: backoffOf(Reflect.get(job, "backoff")),
+			removeOnComplete: retentionOf(Reflect.get(job, "removeOnComplete")),
+			removeOnFail: retentionOf(Reflect.get(job, "removeOnFail"))
+		};
+	}).sort((first, second) => first.name.localeCompare(second.name));
+}
+function isoOrNull(value) {
+	if (typeof value !== "object" || value === null) return null;
+	const toISOString = Reflect.get(value, "toISOString");
+	if (typeof toISOString !== "function") return null;
+	const iso = toISOString.call(value);
+	return typeof iso === "string" ? iso : null;
+}
+/**
+* The tasks on the app's `@warlock.js/scheduler` scheduler (`scheduler.list()`):
+* name, cron expression, interval settings and next run. Empty when absent.
+*/
+async function collectSchedules(importFromApp, warnings) {
+	let module;
+	try {
+		module = await importFromApp("@warlock.js/scheduler");
+	} catch (error) {
+		warnings.push({
+			code: null,
+			message: `@warlock.js/scheduler could not be loaded: ${errorMessage(error)}`,
+			source: "schedules"
+		});
+		return [];
+	}
+	if (typeof module !== "object" || module === null) return [];
+	const scheduler = Reflect.get(module, "scheduler");
+	const list = typeof scheduler === "object" && scheduler !== null ? Reflect.get(scheduler, "list") : void 0;
+	if (typeof list !== "function") return [];
+	const tasks = list.call(scheduler);
+	if (!Array.isArray(tasks)) return [];
+	return tasks.filter((task) => typeof task === "object" && task !== null).map((task) => {
+		const intervals = Reflect.get(task, "intervals");
+		return {
+			name: stringField(task, "name") ?? "anonymous",
+			cron: stringField(task, "cronExpression"),
+			intervals: typeof intervals === "object" && intervals !== null ? Object.fromEntries(Object.entries(intervals)) : {},
+			nextRun: isoOrNull(Reflect.get(task, "nextRun"))
+		};
+	}).sort((first, second) => first.name.localeCompare(second.name));
+}
+
+//#endregion
+export { collectJobs, collectPackages, collectSchedules, createAppModuleImporter, readAppPackage };
+//# sourceMappingURL=collect-packages.mjs.map

package/esm/tooling/inspect/collect-packages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-packages.mjs","names":["resolveModule"],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/collect-packages.ts"],"sourcesContent":["import { readdirSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { pathToFileURL } from \"node:url\";\nimport { resolve as resolveModule } from \"import-meta-resolve\";\nimport type {\n  InspectJob,\n  InspectPackage,\n  InspectSchedule,\n  InspectWarning,\n} from \"./inspect-report.types\";\n\n/**\n * Import a package the way the APP resolves it, so inspect reads the same\n * module instance (and registry) the app's own modules populated. Resolves to\n * `undefined` when the app does not have the package.\n */\nexport type AppModuleImporter = (specifier: string) => Promise<unknown>;\n\n/** The default {@link AppModuleImporter}: resolve from `<cwd>/package.json`, then import. */\nexport function createAppModuleImporter(cwd: string): AppModuleImporter {\n  return async (specifier) => {\n    let url: string;\n\n    try {\n      url = resolveModule(specifier, pathToFileURL(path.join(cwd, \"package.json\")).href);\n    } catch {\n      return undefined;\n    }\n\n    return import(url);\n  };\n}\n\nfunction readJson(file: string): unknown {\n  try {\n    return JSON.parse(readFileSync(file, \"utf8\"));\n  } catch {\n    return undefined;\n  }\n}\n\nfunction stringField(value: unknown, key: string): string | null {\n  if (typeof value !== \"object\" || value === null) return null;\n\n  const field = Reflect.get(value, key);\n\n  return typeof field === \"string\" ? field : null;\n}\n\n/** The app's own `name` and `version`. */\nexport function readAppPackage(cwd: string): { name: string | null; version: string | null } {\n  const manifest = readJson(path.join(cwd, \"package.json\"));\n\n  return { name: stringField(manifest, \"name\"), version: stringField(manifest, \"version\") };\n}\n\n/** Every `@warlock.js/*` package installed at the app root, with its version. */\nexport function collectPackages(cwd: string): InspectPackage[] {\n  const scope = path.join(cwd, \"node_modules\", \"@warlock.js\");\n  let entries: string[];\n\n  try {\n    entries = readdirSync(scope);\n  } catch {\n    return [];\n  }\n\n  const packages: InspectPackage[] = [];\n\n  for (const entry of entries) {\n    const manifest = readJson(path.join(scope, entry, \"package.json\"));\n    const name = stringField(manifest, \"name\");\n    const version = stringField(manifest, \"version\");\n\n    if (name && version) packages.push({ name, version });\n  }\n\n  return packages.sort((first, second) => first.name.localeCompare(second.name));\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nfunction numberOrNull(value: unknown): number | null {\n  return typeof value === \"number\" ? value : null;\n}\n\nfunction retentionOf(value: unknown): boolean | number | null {\n  return typeof value === \"boolean\" || typeof value === \"number\" ? value : null;\n}\n\nfunction backoffOf(value: unknown): InspectJob[\"backoff\"] {\n  if (typeof value === \"number\") return value;\n\n  if (typeof value === \"object\" && value !== null) {\n    const type = Reflect.get(value, \"type\");\n    const delay = Reflect.get(value, \"delay\");\n\n    if (typeof type === \"string\" && typeof delay === \"number\") return { type, delay };\n  }\n\n  return null;\n}\n\n/**\n * The jobs `defineJob()` registered, read from the app's `@warlock.js/queue`\n * (`registeredJobs()` / `queueOf()`). Empty when the app has no queue package.\n */\nexport async function collectJobs(\n  importFromApp: AppModuleImporter,\n  warnings: InspectWarning[],\n): Promise<InspectJob[]> {\n  let queue: unknown;\n\n  try {\n    queue = await importFromApp(\"@warlock.js/queue\");\n  } catch (error) {\n    warnings.push({\n      code: null,\n      message: `@warlock.js/queue could not be loaded: ${errorMessage(error)}`,\n      source: \"jobs\",\n    });\n    return [];\n  }\n\n  if (typeof queue !== \"object\" || queue === null) return [];\n\n  const registered = Reflect.get(queue, \"registeredJobs\");\n  const queueOf = Reflect.get(queue, \"queueOf\");\n\n  if (typeof registered !== \"function\") return [];\n\n  const jobs: unknown = registered();\n\n  if (!Array.isArray(jobs)) return [];\n\n  return jobs\n    .filter((job): job is object => typeof job === \"object\" && job !== null)\n    .map((job) => {\n      const queueName: unknown =\n        typeof queueOf === \"function\" ? queueOf(job) : Reflect.get(job, \"queue\");\n\n      return {\n        name: stringField(job, \"name\") ?? \"anonymous\",\n        queue: typeof queueName === \"string\" ? queueName : \"default\",\n        attempts: numberOrNull(Reflect.get(job, \"attempts\")),\n        backoff: backoffOf(Reflect.get(job, \"backoff\")),\n        removeOnComplete: retentionOf(Reflect.get(job, \"removeOnComplete\")),\n        removeOnFail: retentionOf(Reflect.get(job, \"removeOnFail\")),\n      };\n    })\n    .sort((first, second) => first.name.localeCompare(second.name));\n}\n\nfunction isoOrNull(value: unknown): string | null {\n  if (typeof value !== \"object\" || value === null) return null;\n\n  const toISOString = Reflect.get(value, \"toISOString\");\n\n  if (typeof toISOString !== \"function\") return null;\n\n  const iso: unknown = toISOString.call(value);\n\n  return typeof iso === \"string\" ? iso : null;\n}\n\n/**\n * The tasks on the app's `@warlock.js/scheduler` scheduler (`scheduler.list()`):\n * name, cron expression, interval settings and next run. Empty when absent.\n */\nexport async function collectSchedules(\n  importFromApp: AppModuleImporter,\n  warnings: InspectWarning[],\n): Promise<InspectSchedule[]> {\n  let module: unknown;\n\n  try {\n    module = await importFromApp(\"@warlock.js/scheduler\");\n  } catch (error) {\n    warnings.push({\n      code: null,\n      message: `@warlock.js/scheduler could not be loaded: ${errorMessage(error)}`,\n      source: \"schedules\",\n    });\n    return [];\n  }\n\n  if (typeof module !== \"object\" || module === null) return [];\n\n  const scheduler: unknown = Reflect.get(module, \"scheduler\");\n  const list =\n    typeof scheduler === \"object\" && scheduler !== null\n      ? Reflect.get(scheduler, \"list\")\n      : undefined;\n\n  if (typeof list !== \"function\") return [];\n\n  const tasks: unknown = list.call(scheduler);\n\n  if (!Array.isArray(tasks)) return [];\n\n  return tasks\n    .filter((task): task is object => typeof task === \"object\" && task !== null)\n    .map((task) => {\n      const intervals: unknown = Reflect.get(task, \"intervals\");\n\n      return {\n        name: stringField(task, \"name\") ?? \"anonymous\",\n        cron: stringField(task, \"cronExpression\"),\n        intervals:\n          typeof intervals === \"object\" && intervals !== null\n            ? Object.fromEntries(Object.entries(intervals))\n            : {},\n        nextRun: isoOrNull(Reflect.get(task, \"nextRun\")),\n      };\n    })\n    .sort((first, second) => first.name.localeCompare(second.name));\n}\n"],"mappings":"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"}

package/esm/tooling/inspect/collect-pages.mjs

@@ -0,0 +1,108 @@
+import { connectorsManager } from "../../connectors/connectors-manager.mjs";
+import path from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import ts from "typescript";
+
+//#region ../../packages/core/src/tooling/inspect/collect-pages.ts
+function isInstalledPage(value) {
+	return typeof value === "object" && value !== null && typeof Reflect.get(value, "path") === "string" && typeof Reflect.get(value, "file") === "string";
+}
+/**
+* The pages the `web` connector installed, read through its public
+* `getInstalledPages()` without importing `@warlock.js/web`. `undefined` when
+* no such connector is registered (an API-only app).
+*/
+function installedPagesFromConnectors() {
+	const web = connectorsManager.list().find((connector) => connector.name === "web");
+	const read = web ? Reflect.get(web, "getInstalledPages") : void 0;
+	if (typeof read !== "function") return void 0;
+	const pages = read.call(web);
+	return Array.isArray(pages) ? pages : void 0;
+}
+function toPosix(file) {
+	return file.split(path.sep).join("/");
+}
+function relativeTo(cwd, file) {
+	return toPosix(path.isAbsolute(file) ? path.relative(cwd, file) : file);
+}
+/**
+* The page's layout chain, outermost first: every `layout.tsx` from the web
+* root (the nearest ancestor holding `root.tsx`, else `src/`) down to the
+* page's own directory — the rule `@warlock.js/web` applies.
+*/
+function layoutChainOf(pageFile, cwd) {
+	const srcRoot = path.join(cwd, "src");
+	const directories = [];
+	let current = path.dirname(pageFile);
+	while (current.startsWith(srcRoot)) {
+		directories.unshift(current);
+		if (existsSync(path.join(current, "root.tsx")) || current === srcRoot) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return directories.map((directory) => path.join(directory, "layout.tsx")).filter((candidate) => existsSync(candidate));
+}
+/**
+* Whether a module's source exports a binding named `name`, read with the
+* TypeScript parser (the page files are TSX that Node cannot import directly).
+*/
+function exportsName(file, name) {
+	let source;
+	try {
+		source = readFileSync(file, "utf8");
+	} catch {
+		return false;
+	}
+	const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, false, ts.ScriptKind.TSX);
+	for (const statement of sourceFile.statements) {
+		const exported = ts.canHaveModifiers(statement) ? (ts.getModifiers(statement) ?? []).some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) : false;
+		if (exported && ts.isVariableStatement(statement)) {
+			if (statement.declarationList.declarations.some((declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name)) return true;
+		}
+		if (exported && ts.isFunctionDeclaration(statement) && statement.name?.text === name) return true;
+		if (ts.isExportDeclaration(statement) && statement.exportClause && ts.isNamedExports(statement.exportClause) && statement.exportClause.elements.some((element) => element.name.text === name)) return true;
+	}
+	return false;
+}
+/**
+* Describe the installed pages: route path and name, page file, layout chain,
+* the files on that chain exporting a `loader`, actions and guard.
+*
+* @param pages The connector's installed page records; see {@link installedPagesFromConnectors}.
+*/
+function collectPages(pages, cwd, warnings) {
+	if (!pages) return [];
+	const collected = [];
+	for (const page of pages) {
+		if (!isInstalledPage(page)) {
+			warnings.push({
+				code: null,
+				message: "A page record has no path or file.",
+				source: "pages"
+			});
+			continue;
+		}
+		const pageFile = path.isAbsolute(page.file) ? page.file : path.join(cwd, page.file);
+		const layouts = layoutChainOf(pageFile, cwd);
+		const loaders = [...layouts, pageFile].filter((file) => exportsName(file, "loader"));
+		const actions = Array.isArray(page.actions) ? page.actions.filter((action) => typeof action === "string") : [];
+		collected.push({
+			path: page.path,
+			name: typeof page.name === "string" && page.name.length > 0 ? page.name : null,
+			file: relativeTo(cwd, pageFile),
+			layouts: layouts.map((file) => relativeTo(cwd, file)),
+			loaders: loaders.map((file) => relativeTo(cwd, file)),
+			actions: [...actions].sort(),
+			guard: typeof page.guard === "string" ? page.guard : null
+		});
+	}
+	return collected.sort((first, second) => {
+		if (first.path !== second.path) return first.path < second.path ? -1 : 1;
+		return first.file.localeCompare(second.file);
+	});
+}
+
+//#endregion
+export { collectPages, installedPagesFromConnectors };
+//# sourceMappingURL=collect-pages.mjs.map

package/esm/tooling/inspect/collect-pages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-pages.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/tooling/inspect/collect-pages.ts"],"sourcesContent":["import { existsSync, readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport ts from \"typescript\";\nimport { connectorsManager } from \"../../connectors/connectors-manager\";\nimport type { InspectPage, InspectWarning } from \"./inspect-report.types\";\n\n/** The fields of `@warlock.js/web`'s installed page record that inspect reads. */\ntype InstalledPageLike = {\n  path: string;\n  name?: unknown;\n  file: string;\n  actions?: unknown;\n  guard?: unknown;\n};\n\nfunction isInstalledPage(value: unknown): value is InstalledPageLike {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    typeof Reflect.get(value, \"path\") === \"string\" &&\n    typeof Reflect.get(value, \"file\") === \"string\"\n  );\n}\n\n/**\n * The pages the `web` connector installed, read through its public\n * `getInstalledPages()` without importing `@warlock.js/web`. `undefined` when\n * no such connector is registered (an API-only app).\n */\nexport function installedPagesFromConnectors(): unknown[] | undefined {\n  const web = connectorsManager.list().find((connector) => connector.name === \"web\");\n  const read = web ? Reflect.get(web, \"getInstalledPages\") : undefined;\n\n  if (typeof read !== \"function\") return undefined;\n\n  const pages: unknown = read.call(web);\n\n  return Array.isArray(pages) ? pages : undefined;\n}\n\nfunction toPosix(file: string): string {\n  return file.split(path.sep).join(\"/\");\n}\n\nfunction relativeTo(cwd: string, file: string): string {\n  return toPosix(path.isAbsolute(file) ? path.relative(cwd, file) : file);\n}\n\n/**\n * The page's layout chain, outermost first: every `layout.tsx` from the web\n * root (the nearest ancestor holding `root.tsx`, else `src/`) down to the\n * page's own directory — the rule `@warlock.js/web` applies.\n */\nexport function layoutChainOf(pageFile: string, cwd: string): string[] {\n  const srcRoot = path.join(cwd, \"src\");\n  const directories: string[] = [];\n  let current = path.dirname(pageFile);\n\n  while (current.startsWith(srcRoot)) {\n    directories.unshift(current);\n\n    if (existsSync(path.join(current, \"root.tsx\")) || current === srcRoot) break;\n\n    const parent = path.dirname(current);\n\n    if (parent === current) break;\n\n    current = parent;\n  }\n\n  return directories\n    .map((directory) => path.join(directory, \"layout.tsx\"))\n    .filter((candidate) => existsSync(candidate));\n}\n\n/**\n * Whether a module's source exports a binding named `name`, read with the\n * TypeScript parser (the page files are TSX that Node cannot import directly).\n */\nexport function exportsName(file: string, name: string): boolean {\n  let source: string;\n\n  try {\n    source = readFileSync(file, \"utf8\");\n  } catch {\n    return false;\n  }\n\n  const sourceFile = ts.createSourceFile(\n    file,\n    source,\n    ts.ScriptTarget.Latest,\n    false,\n    ts.ScriptKind.TSX,\n  );\n\n  for (const statement of sourceFile.statements) {\n    const exported = ts.canHaveModifiers(statement)\n      ? (ts.getModifiers(statement) ?? []).some(\n          (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,\n        )\n      : false;\n\n    if (exported && ts.isVariableStatement(statement)) {\n      if (\n        statement.declarationList.declarations.some(\n          (declaration) => ts.isIdentifier(declaration.name) && declaration.name.text === name,\n        )\n      ) {\n        return true;\n      }\n    }\n\n    if (exported && ts.isFunctionDeclaration(statement) && statement.name?.text === name) {\n      return true;\n    }\n\n    if (\n      ts.isExportDeclaration(statement) &&\n      statement.exportClause &&\n      ts.isNamedExports(statement.exportClause) &&\n      statement.exportClause.elements.some((element) => element.name.text === name)\n    ) {\n      return true;\n    }\n  }\n\n  return false;\n}\n\n/**\n * Describe the installed pages: route path and name, page file, layout chain,\n * the files on that chain exporting a `loader`, actions and guard.\n *\n * @param pages The connector's installed page records; see {@link installedPagesFromConnectors}.\n */\nexport function collectPages(\n  pages: readonly unknown[] | undefined,\n  cwd: string,\n  warnings: InspectWarning[],\n): InspectPage[] {\n  if (!pages) return [];\n\n  const collected: InspectPage[] = [];\n\n  for (const page of pages) {\n    if (!isInstalledPage(page)) {\n      warnings.push({ code: null, message: \"A page record has no path or file.\", source: \"pages\" });\n      continue;\n    }\n\n    const pageFile = path.isAbsolute(page.file) ? page.file : path.join(cwd, page.file);\n    const layouts = layoutChainOf(pageFile, cwd);\n    const loaders = [...layouts, pageFile].filter((file) => exportsName(file, \"loader\"));\n    const actions = Array.isArray(page.actions)\n      ? page.actions.filter((action): action is string => typeof action === \"string\")\n      : [];\n\n    collected.push({\n      path: page.path,\n      name: typeof page.name === \"string\" && page.name.length > 0 ? page.name : null,\n      file: relativeTo(cwd, pageFile),\n      layouts: layouts.map((file) => relativeTo(cwd, file)),\n      loaders: loaders.map((file) => relativeTo(cwd, file)),\n      actions: [...actions].sort(),\n      guard: typeof page.guard === \"string\" ? page.guard : null,\n    });\n  }\n\n  return collected.sort((first, second) => {\n    if (first.path !== second.path) return first.path < second.path ? -1 : 1;\n\n    return first.file.localeCompare(second.file);\n  });\n}\n"],"mappings":"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"}