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 { 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 { 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, }; }