@unifyplane/logsdk 1.0.0

package/validators/bootstrap/validate-repo-structure.ts

@@ -0,0 +1,590 @@
+/**
+ * validators/validate-repo-structure.ts
+ *
+ * UnifyPlane — Repo Structure Validator (STRICT)
+ *
+ * Enforces REQUIRED repo-root layout:
+ *   contracts/, validators/, semantics/, tools/, src/, tests/, README.md
+ *
+ * Enforces contracts/ substructure (only):
+ *   specs/, schemas/, registries/, constraints/, abi/, authority/
+ *
+ * Enforces structural separation:
+ *   - No validators/semantics/tools/evidence under contracts/
+ *   - No evidence/ directory anywhere in repo (evidence is runtime-only, outside Git)
+ *   - No runtime log artifacts in Git (e.g., *.ndjson, *.log)
+ *
+ * Enforces runtime boundary:
+ *   - src/ contains runtime execution only
+ *   - No generators, audits, or repo-inspection logic under src/
+ *
+ * Enforces system-type constraint:
+ *   - contracts/authority/ must be empty or absent for pipeline/content systems
+ *   - contracts/authority/ allowed for process systems only
+ *
+ * Output:
+ *   evidence/validators/validate-repo-structure/repo-structure-audit.json
+ *
+ * Usage:
+ *   npx tsx validators/validate-repo-structure.ts --root <repo-root>
+ *   (Optional override) --systemType process|pipeline|content
+ *
+ * NOTE: --root is REQUIRED (no ambient CWD fallback).
+ */
+
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+type SystemType = "process" | "pipeline" | "content";
+
+type Severity = "high" | "medium" | "low" | "info";
+
+type Finding = {
+  severity: Severity;
+  rule_id: string;
+  message: string;
+  path?: string;
+  expected?: string;
+  observed?: string;
+};
+
+type AuditReport = {
+  audit_metadata: {
+    validator: "validate-repo-structure";
+    mode: "strict";
+    repo_root: string;
+    repo_name: string;
+    system_type: SystemType;
+    audited_at: string;
+    validator_file: string;
+  };
+  summary: {
+    overall_status: "COMPLIANT" | "NON_COMPLIANT";
+    risk_level: "LOW" | "MEDIUM" | "HIGH";
+    total_findings: number;
+    by_severity: Record<Severity, number>;
+    missing_required: string[];
+  };
+  findings: Finding[];
+  folder_inventory: {
+    top_level: Record<string, boolean>;
+    contracts: Record<string, { exists: boolean; file_count: number; dir_count: number }>;
+  };
+  notes: string[];
+  output_path: string;
+};
+
+const REQUIRED_TOP_LEVEL = [
+  "contracts",
+  "validators",
+  "semantics",
+  "tools",
+  "src",
+  "tests",
+] as const;
+
+const REQUIRED_FILES = ["README.md"] as const;
+
+// Explicitly ignored repo-root helper artifacts (non-authoritative, diagnostic only)
+// NOTE: These are allowed ONLY at repo root and MUST NOT expand without governance review.
+const IGNORED_TOP_LEVEL_FILES = new Set([
+  "filestructure.output.txt",
+]);
+
+const CONTRACTS_ALLOWED_SUBFOLDERS = [
+  "specs",
+  "schemas",
+  "registries",
+  "constraints",
+  "abi",
+  "authority",
+] as const;
+
+const CONTRACTS_FORBIDDEN_SUBFOLDERS = [
+  "validators",
+  "semantics",
+  "tools",
+  "evidence",
+] as const;
+
+const DEFAULT_IGNORE_DIRS = new Set([
+  ".git",
+  ".github",
+  ".vscode",
+  "node_modules",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".turbo",
+  ".cache",
+  ".pnpm-store",
+]);
+
+// Runtime evidence artifacts that must not live in Git
+const FORBIDDEN_FILE_EXTS = new Set([
+  ".ndjson",
+  ".log",
+  ".trace",
+  ".spool",
+  ".loki",
+]);
+
+const FORBIDDEN_FILE_NAMES = new Set([
+  "loki.ndjson",
+  "trace.ndjson",
+  "logs.ndjson",
+]);
+
+// Allowed evidence location (tool outputs only)
+const ALLOWED_EVIDENCE_PREFIX = "evidence/validators/";
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function parseArgs(argv: string[]) {
+  const args: Record<string, string | boolean> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--root") args.root = argv[++i] ?? "";
+    else if (a === "--systemType") args.systemType = argv[++i] ?? "";
+    else if (a === "--help") args.help = true;
+  }
+  return args;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function statSafe(p: string) {
+  try {
+    return await fs.stat(p);
+  } catch {
+    return null;
+  }
+}
+
+async function listDirSafe(p: string): Promise<string[]> {
+  try {
+    return await fs.readdir(p);
+  } catch {
+    return [];
+  }
+}
+
+function classifyRisk(findings: Finding[]): "LOW" | "MEDIUM" | "HIGH" {
+  if (findings.some((f) => f.severity === "high")) return "HIGH";
+  if (findings.some((f) => f.severity === "medium")) return "MEDIUM";
+  return "LOW";
+}
+
+function countBySeverity(findings: Finding[]): Record<Severity, number> {
+  return findings.reduce(
+    (acc, f) => {
+      acc[f.severity] += 1;
+      return acc;
+    },
+    { high: 0, medium: 0, low: 0, info: 0 } as Record<Severity, number>,
+  );
+}
+
+/**
+ * Extract system type from README.md (STRICT expectation).
+ * Accepted patterns (case-insensitive):
+ *   - "System Type: process"
+ *   - "system_type: pipeline"
+ *   - "system-type = content"
+ */
+function extractSystemTypeFromReadme(readme: string): SystemType | null {
+  const re = /system[\s_-]*type\s*[:=]\s*(process|pipeline|content)\b/i;
+  const m = readme.match(re);
+  if (!m) return null;
+  const v = m[1].toLowerCase();
+  if (v === "process" || v === "pipeline" || v === "content") return v;
+  return null;
+}
+
+async function walkRepo(
+  root: string,
+  onEntry: (absPath: string, relPath: string, st: { isDir: boolean; isFile: boolean }) => Promise<void>,
+  ignoreDirs: Set<string>,
+) {
+  async function walkDir(dirAbs: string, dirRel: string) {
+    const entries = await fs.readdir(dirAbs, { withFileTypes: true });
+    for (const ent of entries) {
+      const abs = path.join(dirAbs, ent.name);
+      const rel = dirRel ? path.posix.join(dirRel, ent.name) : ent.name;
+
+      if (ent.isDirectory()) {
+        if (ignoreDirs.has(ent.name)) continue;
+        await onEntry(abs, rel, { isDir: true, isFile: false });
+        await walkDir(abs, rel);
+      } else if (ent.isFile()) {
+        await onEntry(abs, rel, { isDir: false, isFile: true });
+      }
+    }
+  }
+
+  await walkDir(root, "");
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    console.log(
+      [
+        "validate-repo-structure (STRICT)",
+        "Usage:",
+        "  npx tsx validators/validate-repo-structure.ts --root <repo-root> [--systemType process|pipeline|content]",
+        "",
+        "Notes:",
+        "  --root is REQUIRED. No ambient process.cwd() fallback.",
+      ].join("\n"),
+    );
+    process.exit(0);
+  }
+
+  const rootArg = typeof args.root === "string" ? args.root.trim() : "";
+  if (!rootArg) {
+    console.error("ERROR: --root is required (no ambient CWD fallback).");
+    process.exit(2);
+  }
+
+  const repoRoot = path.resolve(rootArg);
+  const repoName = path.basename(repoRoot);
+
+  const findings: Finding[] = [];
+  const notes: string[] = [];
+
+  // --- Required presence checks
+  const topLevelInventory: Record<string, boolean> = {};
+  const missingRequired: string[] = [];
+
+  for (const folder of REQUIRED_TOP_LEVEL) {
+    const p = path.join(repoRoot, folder);
+    const ok = await exists(p);
+    topLevelInventory[folder] = ok;
+    if (!ok) {
+      missingRequired.push(`${folder}/`);
+      findings.push({
+        severity: "high",
+        rule_id: "MISSING_REQUIRED_TOP_LEVEL",
+        message: `Missing required top-level folder: ${folder}/`,
+        path: `${folder}/`,
+        expected: "Folder must exist at repo root (strict mode).",
+      });
+    }
+  }
+
+  for (const file of REQUIRED_FILES) {
+    const p = path.join(repoRoot, file);
+    const ok = await exists(p);
+    topLevelInventory[file] = ok;
+    if (!ok) {
+      missingRequired.push(file);
+      findings.push({
+        severity: "high",
+        rule_id: "MISSING_REQUIRED_FILE",
+        message: `Missing required repo-root file: ${file}`,
+        path: file,
+        expected: "File must exist at repo root (strict mode).",
+      });
+    }
+  }
+
+  // --- Determine system type (from override OR README)
+  let systemType: SystemType | null = null;
+
+  const override = typeof args.systemType === "string" ? args.systemType.trim().toLowerCase() : "";
+  if (override) {
+    if (override === "process" || override === "pipeline" || override === "content") {
+      systemType = override;
+      notes.push("System type provided via --systemType override.");
+    } else {
+      findings.push({
+        severity: "high",
+        rule_id: "INVALID_SYSTEM_TYPE_OVERRIDE",
+        message: `Invalid --systemType value: ${override}`,
+        expected: "process | pipeline | content",
+      });
+    }
+  }
+
+  if (!systemType && (await exists(path.join(repoRoot, "README.md")))) {
+    const readme = await fs.readFile(path.join(repoRoot, "README.md"), "utf8");
+    const parsed = extractSystemTypeFromReadme(readme);
+    if (!parsed) {
+      findings.push({
+        severity: "high",
+        rule_id: "README_MISSING_SYSTEM_TYPE",
+        message: "README.md does not declare system type.",
+        path: "README.md",
+        expected: 'Include a line like "System Type: process|pipeline|content" (strict mode).',
+      });
+    } else {
+      systemType = parsed;
+    }
+  }
+
+  if (!systemType) {
+    // Default to pipeline for report completeness, but keep non-compliance
+    systemType = "pipeline";
+    findings.push({
+      severity: "high",
+      rule_id: "SYSTEM_TYPE_UNRESOLVED",
+      message: "System type could not be resolved; using pipeline as placeholder for report.",
+      expected: "Declare system type in README or pass --systemType.",
+    });
+  }
+
+  // --- contracts/ structural checks
+  const contractsPath = path.join(repoRoot, "contracts");
+  const contractsInventory: Record<string, { exists: boolean; file_count: number; dir_count: number }> =
+    Object.fromEntries(
+      CONTRACTS_ALLOWED_SUBFOLDERS.map((k) => [k, { exists: false, file_count: 0, dir_count: 0 }]),
+    );
+
+  if (await exists(contractsPath)) {
+    const entries = await fs.readdir(contractsPath, { withFileTypes: true });
+
+    // Disallow any unknown subfolder under contracts/
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      const name = ent.name;
+
+      const isAllowed = (CONTRACTS_ALLOWED_SUBFOLDERS as readonly string[]).includes(name);
+      if (!isAllowed) {
+        findings.push({
+          severity: "high",
+          rule_id: "NON_CANONICAL_CONTRACTS_SUBFOLDER",
+          message: `Non-canonical subfolder under contracts/: ${name}/`,
+          path: `contracts/${name}/`,
+          expected: `Only allowed: ${CONTRACTS_ALLOWED_SUBFOLDERS.join(", ")}`,
+        });
+      }
+    }
+
+    // Explicitly forbidden names under contracts/
+    for (const forbidden of CONTRACTS_FORBIDDEN_SUBFOLDERS) {
+      const p = path.join(contractsPath, forbidden);
+      if (await exists(p)) {
+        findings.push({
+          severity: "high",
+          rule_id: "FORBIDDEN_FOLDER_UNDER_CONTRACTS",
+          message: `Forbidden folder found under contracts/: ${forbidden}/`,
+          path: `contracts/${forbidden}/`,
+          expected: "Non-authoritative artifacts must not live under contracts/.",
+        });
+      }
+    }
+
+    // Inventory allowed subfolders and count content
+    for (const sub of CONTRACTS_ALLOWED_SUBFOLDERS) {
+      const subPath = path.join(contractsPath, sub);
+      const subExists = await exists(subPath);
+      if (!subExists) {
+        // In strict mode: we require top-level folders, not necessarily every contracts/* subfolder.
+        // BUT we still enforce that if contracts/ exists, it should contain only canonical subfolders.
+        // Missing subfolders are INFO (not required).
+        findings.push({
+          severity: "info",
+          rule_id: "MISSING_CONTRACTS_SUBFOLDER",
+          message: `contracts/${sub}/ is absent (allowed).`,
+          path: `contracts/${sub}/`,
+          expected: "Optional within contracts/, but recommended for structural completeness.",
+        });
+        continue;
+      }
+
+      const subEntries = await fs.readdir(subPath, { withFileTypes: true });
+      const fileCount = subEntries.filter((e) => e.isFile()).length;
+      const dirCount = subEntries.filter((e) => e.isDirectory()).length;
+
+      contractsInventory[sub] = { exists: true, file_count: fileCount, dir_count: dirCount };
+    }
+
+    // Authority folder system-type constraint
+    const authorityPath = path.join(contractsPath, "authority");
+    if (await exists(authorityPath)) {
+      const authEntries = await fs.readdir(authorityPath, { withFileTypes: true });
+      const authFileCount = authEntries.filter((e) => e.isFile()).length;
+      const hasAuthMaterial = authFileCount > 0 || authEntries.some((e) => e.isDirectory());
+
+      if ((systemType === "pipeline" || systemType === "content") && hasAuthMaterial) {
+        findings.push({
+          severity: "high",
+          rule_id: "AUTHORITY_IN_NON_PROCESS_SYSTEM",
+          message: `Non-process system (${systemType}) contains authority declarations.`,
+          path: "contracts/authority/",
+          expected: "Pipeline/content systems must not contain authority declarations.",
+          observed: `Found ${authEntries.length} entries.`,
+        });
+      }
+    }
+  } else {
+    // contracts/ is required by strict top-level check. If missing, already high severity.
+    notes.push("contracts/ missing or inaccessible; contracts substructure checks skipped.");
+  }
+
+  // --- Forbidden evidence directory anywhere + forbidden file artifacts anywhere
+  const forbiddenEvidenceDirs: string[] = [];
+  const forbiddenArtifacts: string[] = [];
+
+  await walkRepo(
+    repoRoot,
+    async (abs, rel, st) => {
+      const base = path.basename(rel);
+
+      // evidence/ directory presence is allowed for validator outputs under evidence/validators/
+      // Other disallowed artifacts are still caught via file extension rules.
+      if (st.isDir && base.toLowerCase() === "evidence") {
+        // no-op: evidence folder itself is permitted as a container for validator outputs
+      }
+
+      if (st.isFile) {
+        const ext = path.extname(base).toLowerCase();
+        const lower = base.toLowerCase();
+
+        if (FORBIDDEN_FILE_NAMES.has(lower) || FORBIDDEN_FILE_EXTS.has(ext)) {
+          // allow validator evidence JSON files under the allowed prefix
+          const isAllowedValidatorEvidence =
+            rel.startsWith(ALLOWED_EVIDENCE_PREFIX) && ext === ".json";
+
+          if (!isAllowedValidatorEvidence) {
+            forbiddenArtifacts.push(rel);
+          }
+        }
+      }
+    },
+    DEFAULT_IGNORE_DIRS,
+  );
+
+  for (const d of forbiddenEvidenceDirs) {
+    findings.push({
+      severity: "high",
+      rule_id: "EVIDENCE_FOLDER_IN_GIT",
+      message: "evidence/ folder present in repo (evidence must not be stored in Git).",
+      path: d,
+      expected: "Remove evidence/ from repo; store runtime evidence outside Git.",
+    });
+  }
+
+  for (const f of forbiddenArtifacts) {
+    findings.push({
+      severity: "high",
+      rule_id: "RUNTIME_EVIDENCE_ARTIFACT_IN_GIT",
+      message: "Runtime evidence/log artifact detected in repo.",
+      path: f,
+      expected: "Do not commit runtime logs/traces/ndjson/spool artifacts.",
+    });
+  }
+
+  // --- Extra top-level folders (reported as medium)
+  const topEntries = await fs.readdir(repoRoot, { withFileTypes: true });
+  const allowedTopNames = new Set<string>([
+    ...REQUIRED_TOP_LEVEL,
+    ...REQUIRED_FILES,
+    ...Array.from(DEFAULT_IGNORE_DIRS),
+    // Common meta
+    "evidence", // allowed as container for validator outputs only
+    "docs",
+    "scripts",
+    ".editorconfig",
+    ".gitignore",
+    ".gitattributes",
+    "package.json",
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "tsconfig.json",
+    "eslint.config.js",
+    ".eslintrc",
+    ".prettierrc",
+    "prettier.config.js",
+    "LICENSE",
+  ]);
+
+  for (const ent of topEntries) {
+    const name = ent.name;
+    // Explicit ignore for known non-authoritative helper files
+    if (IGNORED_TOP_LEVEL_FILES.has(name)) continue;
+    if (allowedTopNames.has(name)) continue;
+
+    // Treat unknown top-level as medium (structure drift)
+    findings.push({
+      severity: "medium",
+      rule_id: "UNKNOWN_TOP_LEVEL_ENTRY",
+      message: "Unknown / non-canonical top-level entry found.",
+      path: name,
+      expected: `Keep repo-root minimal; canonical folders are: ${[
+        ...REQUIRED_TOP_LEVEL,
+        ...REQUIRED_FILES,
+      ].join(", ")}`,
+      observed: name,
+    });
+  }
+
+  // --- Build report
+  const bySeverity = countBySeverity(findings);
+  const risk = classifyRisk(findings);
+  const overall =
+    findings.some((f) => f.severity === "high") ? "NON_COMPLIANT" : "COMPLIANT";
+
+  const report: AuditReport = {
+    audit_metadata: {
+      validator: "validate-repo-structure",
+      mode: "strict",
+      repo_root: repoRoot,
+      repo_name: repoName,
+      system_type: systemType,
+      audited_at: nowIso(),
+      validator_file: "validators/validate-repo-structure.ts",
+    },
+    summary: {
+      overall_status: overall,
+      risk_level: risk,
+      total_findings: findings.length,
+      by_severity: bySeverity,
+      missing_required: missingRequired,
+    },
+    findings,
+    folder_inventory: {
+      top_level: topLevelInventory,
+      contracts: contractsInventory,
+    },
+    notes,
+    output_path: "evidence/validators/validate-repo-structure/repo-structure-audit.json",
+  };
+
+  // --- Ensure evidence output folder exists and write JSON
+  const outDir = path.join(
+    repoRoot,
+    "evidence",
+    "validators",
+    "validate-repo-structure",
+  );
+  await fs.mkdir(outDir, { recursive: true });
+  const outPath = path.join(outDir, "repo-structure-audit.json");
+  await fs.writeFile(outPath, JSON.stringify(report, null, 2) + "\n", "utf8");
+
+  // --- Console summary (minimal)
+  console.log(`[validate-repo-structure][strict] ${overall} (${risk})`);
+  console.log(`Report: ${path.relative(repoRoot, outPath)}`);
+
+  // Exit code: 0 compliant, 1 non-compliant, 2 usage/config error
+  process.exit(overall === "COMPLIANT" ? 0 : 1);
+}
+
+main().catch((err) => {
+  console.error("FATAL: validator crashed");
+  console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+  process.exit(2);
+});