Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/packages/plugins/src/manifest-loader.ts
T

132 lines
5.0 KiB
TypeScript

import { readdir, readFile } from "node:fs/promises";
import path from "node:path";
import type { FeatureManifest, FeatureManifestDiagnostic } from "./manifest-schema";
import { validateFeatureManifestShape } from "./manifest-schema";
export type FeatureManifestLoaderDiagnosticCode = FeatureManifestDiagnostic["code"] | "missing_directory" | "invalid_json" | "missing_dependency";
export interface FeatureManifestLoaderDiagnostic {
code: FeatureManifestLoaderDiagnosticCode;
manifestId: string | null;
path: string;
message: string;
}
export interface FeatureManifestLoaderOptions {
rootDir?: string;
manifestDir?: string;
schemaFileName?: string;
includeSchema?: boolean;
}
export interface FeatureManifestFile {
fileName: string;
filePath: string;
manifestId: string | null;
manifest: FeatureManifest | null;
diagnostics: FeatureManifestLoaderDiagnostic[];
}
export interface FeatureManifestLoaderResult {
manifests: FeatureManifest[];
manifestFiles: FeatureManifestFile[];
diagnostics: FeatureManifestLoaderDiagnostic[];
ok: boolean;
}
const DEFAULT_MANIFEST_DIR = path.join("docs", "feature-manifests");
const DEFAULT_SCHEMA_FILE_NAME = "schema.json";
function resolveManifestDirectory(options: FeatureManifestLoaderOptions) {
const rootDir = options.rootDir ?? process.cwd();
const manifestDir = options.manifestDir ?? DEFAULT_MANIFEST_DIR;
return path.isAbsolute(manifestDir) ? manifestDir : path.join(rootDir, manifestDir);
}
function toLoaderDiagnostic(diagnostic: FeatureManifestDiagnostic, filePath: string): FeatureManifestLoaderDiagnostic {
return {
...diagnostic,
path: `${filePath}#${diagnostic.path}`,
};
}
function manifestIdFromUnknownJson(input: unknown): string | null {
if (typeof input !== "object" || input === null || Array.isArray(input)) return null;
const id = (input as { id?: unknown }).id;
return typeof id === "string" && id.length > 0 ? id : null;
}
async function readManifestFile(fileName: string, filePath: string): Promise<FeatureManifestFile> {
let parsed: unknown;
try {
parsed = JSON.parse(await readFile(filePath, "utf8"));
} catch (error) {
const message = error instanceof Error ? error.message : "Unknown JSON parse failure.";
const diagnostic: FeatureManifestLoaderDiagnostic = {
code: "invalid_json",
manifestId: null,
path: filePath,
message: `Failed to parse ${fileName}: ${message}`,
};
return { fileName, filePath, manifestId: null, manifest: null, diagnostics: [diagnostic] };
}
const validation = validateFeatureManifestShape(parsed, { manifestId: manifestIdFromUnknownJson(parsed) ?? undefined, path: filePath });
const diagnostics = validation.diagnostics.map((diagnostic) => toLoaderDiagnostic(diagnostic, filePath));
return {
fileName,
filePath,
manifestId: validation.manifest?.id ?? manifestIdFromUnknownJson(parsed),
manifest: validation.manifest,
diagnostics,
};
}
function validateDependencies(manifestFiles: FeatureManifestFile[]): FeatureManifestLoaderDiagnostic[] {
const manifestIds = new Set(manifestFiles.flatMap((file) => (file.manifest ? [file.manifest.id] : [])));
return manifestFiles.flatMap((file) => {
if (!file.manifest) return [];
return file.manifest.dependencies
.filter((dependencyId) => !manifestIds.has(dependencyId))
.map((dependencyId) => ({
code: "missing_dependency" as const,
manifestId: file.manifest!.id,
path: `${file.filePath}#dependencies`,
message: `${file.manifest!.id} depends on missing feature manifest ${dependencyId}.`,
}));
});
}
export async function loadFeatureManifests(options: FeatureManifestLoaderOptions = {}): Promise<FeatureManifestLoaderResult> {
const manifestDirectory = resolveManifestDirectory(options);
const schemaFileName = options.schemaFileName ?? DEFAULT_SCHEMA_FILE_NAME;
let entries: string[];
try {
entries = await readdir(manifestDirectory);
} catch (error) {
const message = error instanceof Error ? error.message : "Unknown directory read failure.";
const diagnostic: FeatureManifestLoaderDiagnostic = {
code: "missing_directory",
manifestId: null,
path: manifestDirectory,
message: `Failed to read feature manifest directory: ${message}`,
};
return { manifests: [], manifestFiles: [], diagnostics: [diagnostic], ok: false };
}
const fileNames = entries.filter((entry) => entry.endsWith(".json") && (options.includeSchema === true || entry !== schemaFileName)).sort((a, b) => a.localeCompare(b));
const manifestFiles = await Promise.all(fileNames.map((fileName) => readManifestFile(fileName, path.join(manifestDirectory, fileName))));
const dependencyDiagnostics = validateDependencies(manifestFiles);
const diagnostics = [...manifestFiles.flatMap((file) => file.diagnostics), ...dependencyDiagnostics];
return {
manifests: manifestFiles.flatMap((file) => (file.manifest ? [file.manifest] : [])),
manifestFiles,
diagnostics,
ok: diagnostics.length === 0,
};
}