Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,10 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
describe("@toolctrl/plugins package entrypoint", () => {
|
||||
it("exports the manifest schema API", async () => {
|
||||
const module = await import("../src/index.ts");
|
||||
|
||||
expect(module.validateFeatureManifestShape).toEqual(expect.any(Function));
|
||||
expect(module.loadFeatureManifests).toEqual(expect.any(Function));
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,19 @@
|
||||
export type {
|
||||
FeatureManifest,
|
||||
FeatureManifestClassification,
|
||||
FeatureManifestComponent,
|
||||
FeatureManifestDiagnostic,
|
||||
FeatureManifestDiagnosticCode,
|
||||
FeatureManifestStatus,
|
||||
FeatureManifestValidationContext,
|
||||
FeatureManifestValidationResult,
|
||||
} from "./manifest-schema";
|
||||
export { validateFeatureManifestShape } from "./manifest-schema";
|
||||
export type {
|
||||
FeatureManifestFile,
|
||||
FeatureManifestLoaderDiagnostic,
|
||||
FeatureManifestLoaderDiagnosticCode,
|
||||
FeatureManifestLoaderOptions,
|
||||
FeatureManifestLoaderResult,
|
||||
} from "./manifest-loader";
|
||||
export { loadFeatureManifests } from "./manifest-loader";
|
||||
@@ -0,0 +1,131 @@
|
||||
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,
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,218 @@
|
||||
export type FeatureManifestClassification = "core" | "plugin-candidate" | "remove-candidate" | "mixed";
|
||||
export type FeatureManifestStatus = "active" | "proposed" | "review-needed";
|
||||
export type FeatureManifestDiagnosticCode = "invalid_type" | "missing_required" | "invalid_enum" | "invalid_format" | "invalid_item";
|
||||
|
||||
export interface FeatureManifestDiagnostic {
|
||||
code: FeatureManifestDiagnosticCode;
|
||||
manifestId: string | null;
|
||||
path: string;
|
||||
message: string;
|
||||
}
|
||||
|
||||
export interface FeatureManifestValidationContext {
|
||||
manifestId?: string;
|
||||
path?: string;
|
||||
}
|
||||
|
||||
export interface FeatureManifestValidationResult {
|
||||
ok: boolean;
|
||||
manifest: FeatureManifest | null;
|
||||
diagnostics: FeatureManifestDiagnostic[];
|
||||
}
|
||||
|
||||
export interface FeatureManifestComponent {
|
||||
id: string;
|
||||
title: string;
|
||||
rationale: string;
|
||||
codeAreas: string[];
|
||||
notes?: string;
|
||||
}
|
||||
|
||||
export interface FeatureManifest {
|
||||
schemaVersion: "1.0";
|
||||
id: string;
|
||||
title: string;
|
||||
classification: FeatureManifestClassification;
|
||||
status: FeatureManifestStatus;
|
||||
owner: string;
|
||||
description: string;
|
||||
rationale: string[];
|
||||
codeAreas: string[];
|
||||
dependencies: string[];
|
||||
consumers: string[];
|
||||
components?: FeatureManifestComponent[];
|
||||
integration: {
|
||||
ownership: "tenant-owned" | "admin-managed" | "hybrid" | "system-only";
|
||||
surfaces: { adminRoutes: string[]; tenantRoutes: string[]; publicRoutes: string[]; apiRoutes: string[] };
|
||||
configuration: { admin: string[]; tenant: string[]; environment: string[]; secrets: string[] };
|
||||
workers: { required: boolean; queues: string[]; jobs: string[]; notes: string[] };
|
||||
externalProviders: string[];
|
||||
permissions: string[];
|
||||
auditEvents: string[];
|
||||
billingImpacts: string[];
|
||||
uat: string[];
|
||||
};
|
||||
boundaries: { mustKeep: string[]; mayMoveToPlugin: string[]; mustNotTouch: string[] };
|
||||
pruning: { phase: string; action: "keep" | "extract-plugin" | "remove" | "review"; notes: string[] };
|
||||
validation: { source: string[]; lastReviewed: string };
|
||||
}
|
||||
|
||||
const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
|
||||
const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
|
||||
const PERMISSION_TOKEN_PATTERN = /^[a-z][A-Za-z0-9]*(?:\.(?:[A-Za-z][A-Za-z0-9]*|\*))+$/;
|
||||
const AUDIT_EVENT_PATTERN = /^[a-z][a-z0-9_]*(?:\.[a-z][a-z0-9_]*)+$/;
|
||||
const CLASSIFICATIONS = ["core", "plugin-candidate", "remove-candidate", "mixed"] as const;
|
||||
const STATUSES = ["active", "proposed", "review-needed"] as const;
|
||||
const OWNERSHIPS = ["tenant-owned", "admin-managed", "hybrid", "system-only"] as const;
|
||||
const PRUNING_ACTIONS = ["keep", "extract-plugin", "remove", "review"] as const;
|
||||
|
||||
function isRecord(value: unknown): value is Record<string, unknown> {
|
||||
return typeof value === "object" && value !== null && !Array.isArray(value);
|
||||
}
|
||||
|
||||
function add(diagnostics: FeatureManifestDiagnostic[], code: FeatureManifestDiagnosticCode, manifestId: string | null, path: string, message: string) {
|
||||
diagnostics.push({ code, manifestId, path, message });
|
||||
}
|
||||
|
||||
function manifestIdFor(input: Record<string, unknown>, context: FeatureManifestValidationContext): string | null {
|
||||
return context.manifestId ?? (typeof input.id === "string" && input.id.length > 0 ? input.id : null);
|
||||
}
|
||||
|
||||
function requireString(source: Record<string, unknown>, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null, options: { nonEmpty?: boolean; pattern?: RegExp; constValue?: string } = {}) {
|
||||
const value = source[key];
|
||||
if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`);
|
||||
if (typeof value !== "string") return add(diagnostics, "invalid_type", manifestId, path, `${path} must be a string.`);
|
||||
if (options.nonEmpty && value.length === 0) add(diagnostics, "invalid_format", manifestId, path, `${path} must not be empty.`);
|
||||
if (options.constValue !== undefined && value !== options.constValue) add(diagnostics, "invalid_enum", manifestId, path, `${path} must be ${options.constValue}.`);
|
||||
if (options.pattern && !options.pattern.test(value)) add(diagnostics, "invalid_format", manifestId, path, `${path} has an invalid format.`);
|
||||
}
|
||||
|
||||
function requireEnum<T extends readonly string[]>(source: Record<string, unknown>, key: string, values: T, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) {
|
||||
const value = source[key];
|
||||
if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`);
|
||||
if (typeof value !== "string") return add(diagnostics, "invalid_type", manifestId, path, `${path} must be a string.`);
|
||||
if (!values.includes(value)) add(diagnostics, "invalid_enum", manifestId, path, `${path} must be one of: ${values.join(", ")}.`);
|
||||
}
|
||||
|
||||
function requireStringArray(source: Record<string, unknown>, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null, options: { itemPattern?: RegExp } = {}) {
|
||||
const value = source[key];
|
||||
if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`);
|
||||
if (!Array.isArray(value)) return add(diagnostics, "invalid_type", manifestId, path, `${path} must be an array.`);
|
||||
value.forEach((item, index) => {
|
||||
const itemPath = `${path}.${index}`;
|
||||
if (typeof item !== "string") return add(diagnostics, "invalid_item", manifestId, itemPath, `${itemPath} must be a string.`);
|
||||
if (options.itemPattern && !options.itemPattern.test(item)) add(diagnostics, "invalid_format", manifestId, itemPath, `${itemPath} has an invalid format.`);
|
||||
});
|
||||
}
|
||||
|
||||
function requireObject(source: Record<string, unknown>, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null): Record<string, unknown> | null {
|
||||
const value = source[key];
|
||||
if (value === undefined) {
|
||||
add(diagnostics, "missing_required", manifestId, path, `${path} is required.`);
|
||||
return null;
|
||||
}
|
||||
if (!isRecord(value)) {
|
||||
add(diagnostics, "invalid_type", manifestId, path, `${path} must be an object.`);
|
||||
return null;
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
function requireBoolean(source: Record<string, unknown>, key: string, path: string, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) {
|
||||
const value = source[key];
|
||||
if (value === undefined) return add(diagnostics, "missing_required", manifestId, path, `${path} is required.`);
|
||||
if (typeof value !== "boolean") add(diagnostics, "invalid_type", manifestId, path, `${path} must be a boolean.`);
|
||||
}
|
||||
|
||||
function validateComponents(input: Record<string, unknown>, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) {
|
||||
if (input.components === undefined) return;
|
||||
if (!Array.isArray(input.components)) return add(diagnostics, "invalid_type", manifestId, "components", "components must be an array.");
|
||||
input.components.forEach((component, index) => {
|
||||
const path = `components.${index}`;
|
||||
if (!isRecord(component)) return add(diagnostics, "invalid_item", manifestId, path, `${path} must be an object.`);
|
||||
requireString(component, "id", `${path}.id`, diagnostics, manifestId, { pattern: ID_PATTERN });
|
||||
requireString(component, "title", `${path}.title`, diagnostics, manifestId);
|
||||
requireString(component, "rationale", `${path}.rationale`, diagnostics, manifestId);
|
||||
requireStringArray(component, "codeAreas", `${path}.codeAreas`, diagnostics, manifestId);
|
||||
if (component.notes !== undefined && typeof component.notes !== "string") add(diagnostics, "invalid_type", manifestId, `${path}.notes`, `${path}.notes must be a string.`);
|
||||
});
|
||||
}
|
||||
|
||||
function validateIntegration(input: Record<string, unknown>, diagnostics: FeatureManifestDiagnostic[], manifestId: string | null) {
|
||||
const integration = requireObject(input, "integration", "integration", diagnostics, manifestId);
|
||||
if (!integration) return;
|
||||
requireEnum(integration, "ownership", OWNERSHIPS, "integration.ownership", diagnostics, manifestId);
|
||||
const surfaces = requireObject(integration, "surfaces", "integration.surfaces", diagnostics, manifestId);
|
||||
if (surfaces) {
|
||||
requireStringArray(surfaces, "adminRoutes", "integration.surfaces.adminRoutes", diagnostics, manifestId);
|
||||
requireStringArray(surfaces, "tenantRoutes", "integration.surfaces.tenantRoutes", diagnostics, manifestId);
|
||||
requireStringArray(surfaces, "publicRoutes", "integration.surfaces.publicRoutes", diagnostics, manifestId);
|
||||
requireStringArray(surfaces, "apiRoutes", "integration.surfaces.apiRoutes", diagnostics, manifestId);
|
||||
}
|
||||
const configuration = requireObject(integration, "configuration", "integration.configuration", diagnostics, manifestId);
|
||||
if (configuration) {
|
||||
requireStringArray(configuration, "admin", "integration.configuration.admin", diagnostics, manifestId);
|
||||
requireStringArray(configuration, "tenant", "integration.configuration.tenant", diagnostics, manifestId);
|
||||
requireStringArray(configuration, "environment", "integration.configuration.environment", diagnostics, manifestId);
|
||||
requireStringArray(configuration, "secrets", "integration.configuration.secrets", diagnostics, manifestId);
|
||||
}
|
||||
const workers = requireObject(integration, "workers", "integration.workers", diagnostics, manifestId);
|
||||
if (workers) {
|
||||
requireBoolean(workers, "required", "integration.workers.required", diagnostics, manifestId);
|
||||
requireStringArray(workers, "queues", "integration.workers.queues", diagnostics, manifestId);
|
||||
requireStringArray(workers, "jobs", "integration.workers.jobs", diagnostics, manifestId);
|
||||
requireStringArray(workers, "notes", "integration.workers.notes", diagnostics, manifestId);
|
||||
}
|
||||
requireStringArray(integration, "externalProviders", "integration.externalProviders", diagnostics, manifestId);
|
||||
requireStringArray(integration, "permissions", "integration.permissions", diagnostics, manifestId, { itemPattern: PERMISSION_TOKEN_PATTERN });
|
||||
requireStringArray(integration, "auditEvents", "integration.auditEvents", diagnostics, manifestId, { itemPattern: AUDIT_EVENT_PATTERN });
|
||||
requireStringArray(integration, "billingImpacts", "integration.billingImpacts", diagnostics, manifestId);
|
||||
requireStringArray(integration, "uat", "integration.uat", diagnostics, manifestId);
|
||||
}
|
||||
|
||||
function isValidDate(value: string) {
|
||||
if (!DATE_PATTERN.test(value)) return false;
|
||||
const date = new Date(`${value}T00:00:00.000Z`);
|
||||
return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
|
||||
}
|
||||
|
||||
export function validateFeatureManifestShape(input: unknown, context: FeatureManifestValidationContext = {}): FeatureManifestValidationResult {
|
||||
if (!isRecord(input)) {
|
||||
const path = context.path ?? "$";
|
||||
return { ok: false, manifest: null, diagnostics: [{ code: "invalid_type", manifestId: context.manifestId ?? null, path, message: `${path} must be an object.` }] };
|
||||
}
|
||||
const diagnostics: FeatureManifestDiagnostic[] = [];
|
||||
const manifestId = manifestIdFor(input, context);
|
||||
requireString(input, "schemaVersion", "schemaVersion", diagnostics, manifestId, { constValue: "1.0" });
|
||||
requireString(input, "id", "id", diagnostics, manifestId, { pattern: ID_PATTERN });
|
||||
requireString(input, "title", "title", diagnostics, manifestId, { nonEmpty: true });
|
||||
requireEnum(input, "classification", CLASSIFICATIONS, "classification", diagnostics, manifestId);
|
||||
requireEnum(input, "status", STATUSES, "status", diagnostics, manifestId);
|
||||
requireString(input, "owner", "owner", diagnostics, manifestId);
|
||||
requireString(input, "description", "description", diagnostics, manifestId);
|
||||
requireStringArray(input, "rationale", "rationale", diagnostics, manifestId);
|
||||
requireStringArray(input, "codeAreas", "codeAreas", diagnostics, manifestId);
|
||||
requireStringArray(input, "dependencies", "dependencies", diagnostics, manifestId, { itemPattern: ID_PATTERN });
|
||||
requireStringArray(input, "consumers", "consumers", diagnostics, manifestId);
|
||||
validateComponents(input, diagnostics, manifestId);
|
||||
validateIntegration(input, diagnostics, manifestId);
|
||||
const boundaries = requireObject(input, "boundaries", "boundaries", diagnostics, manifestId);
|
||||
if (boundaries) {
|
||||
requireStringArray(boundaries, "mustKeep", "boundaries.mustKeep", diagnostics, manifestId);
|
||||
requireStringArray(boundaries, "mayMoveToPlugin", "boundaries.mayMoveToPlugin", diagnostics, manifestId);
|
||||
requireStringArray(boundaries, "mustNotTouch", "boundaries.mustNotTouch", diagnostics, manifestId);
|
||||
}
|
||||
const pruning = requireObject(input, "pruning", "pruning", diagnostics, manifestId);
|
||||
if (pruning) {
|
||||
requireString(pruning, "phase", "pruning.phase", diagnostics, manifestId);
|
||||
requireEnum(pruning, "action", PRUNING_ACTIONS, "pruning.action", diagnostics, manifestId);
|
||||
requireStringArray(pruning, "notes", "pruning.notes", diagnostics, manifestId);
|
||||
}
|
||||
const validation = requireObject(input, "validation", "validation", diagnostics, manifestId);
|
||||
if (validation) {
|
||||
requireStringArray(validation, "source", "validation.source", diagnostics, manifestId);
|
||||
requireString(validation, "lastReviewed", "validation.lastReviewed", diagnostics, manifestId);
|
||||
if (typeof validation.lastReviewed === "string" && !isValidDate(validation.lastReviewed)) add(diagnostics, "invalid_format", manifestId, "validation.lastReviewed", "validation.lastReviewed must be an ISO date in YYYY-MM-DD format.");
|
||||
}
|
||||
return { ok: diagnostics.length === 0, manifest: diagnostics.length === 0 ? (input as unknown as FeatureManifest) : null, diagnostics };
|
||||
}
|
||||
Reference in new issue
Block a user