132 lines
5.0 KiB
TypeScript
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,
|
|
};
|
|
}
|