@dependency-maritime/cli 0.1.0-beta.1

package/dist/cli/index.js

@@ -0,0 +1,1197 @@
+// src/cli/commands/analyze.ts
+import { parseArgs } from "node:util";
+import * as fsPromises from "node:fs/promises";
+
+// src/cli/analyze/adapters.ts
+import * as fs from "fs/promises";
+import { existsSync } from "node:fs";
+import * as path from "path";
+
+// src/schema/dependency-cruiser.ts
+import { z } from "zod";
+var DependencySchema = z.object({
+  /** 'true' if following this dependency will ultimately return to the source */
+  circular: z.boolean(),
+  /** Whether or not this is a node.js core module */
+  coreModule: z.boolean(),
+  /** 'true' if dependency-cruiser could not resolve the module name to a file */
+  couldNotResolve: z.boolean(),
+  /** The type of inclusion - local, core, npm, etc. */
+  dependencyTypes: z.array(z.string()),
+  /** true if this dependency is dynamic, false in all other cases */
+  dynamic: z.boolean(),
+  /** true if the dependency was defined by a require not named 'require' */
+  exoticallyRequired: z.boolean(),
+  /** Whether or not this is a dependency that can be followed any further */
+  followable: z.boolean(),
+  /** the instability of the dependency */
+  instability: z.number().optional(),
+  /** If the module specification is an URI with a protocol, this holds it */
+  protocol: z.enum(["data:", "file:", "node:"]).optional(),
+  /** If the module specification is an URI and contains a mime type, this holds it */
+  mimeType: z.string().optional(),
+  /** The module system used (e.g., "es6", "cjs") */
+  moduleSystem: z.enum(["amd", "cjs", "es6", "tsd"]),
+  /** The import string used in the code (e.g., "./utils") */
+  module: z.string(),
+  /** The absolute or relative path to the resolved file (e.g., "src/utils.ts") */
+  resolved: z.string(),
+  /** 'true' if this dependency violated a rule */
+  valid: z.boolean(),
+  /** Whether the dependency exists only before compilation (e.g. type-only) */
+  preCompilationOnly: z.boolean().optional(),
+  /** 'true' when the module included the module explicitly as type only */
+  typeOnly: z.boolean().optional(),
+  /** Cycle path if circular */
+  cycle: z.array(z.object({
+    name: z.string(),
+    dependencyTypes: z.array(z.string())
+  })).optional()
+}).passthrough();
+var ModuleSchema = z.object({
+  /** The path to the source file (acts as the unique ID) */
+  source: z.string(),
+  /** 'true' if this module violated a rule */
+  valid: z.boolean(),
+  /** List of outgoing dependencies */
+  dependencies: z.array(DependencySchema),
+  /** List of files that depend on this module (incoming edges) */
+  dependents: z.array(z.string()),
+  /** Whether or not this is a node.js core module */
+  coreModule: z.boolean().optional(),
+  /** 'true' if dependency-cruiser could not resolve the module name to a file */
+  couldNotResolve: z.boolean().optional(),
+  /** Whether the module is an orphan */
+  orphan: z.boolean().optional()
+}).passthrough();
+var ViolationSchema = z.object({
+  type: z.enum(["dependency", "module", "cycle", "reachability", "instability"]).optional(),
+  from: z.string(),
+  to: z.string(),
+  rule: z.object({
+    name: z.string(),
+    severity: z.enum(["error", "warn", "info", "ignore"])
+  }).passthrough()
+}).passthrough();
+var CruiseResultSchema = z.object({
+  /** List of all modules scanned */
+  modules: z.array(ModuleSchema),
+  /** Summary of the scan (violations, errors, etc.) */
+  summary: z.object({
+    error: z.number(),
+    ignore: z.number(),
+    info: z.number(),
+    totalCruised: z.number(),
+    totalDependenciesCruised: z.number().optional(),
+    violations: z.array(ViolationSchema),
+    warn: z.number(),
+    optionsUsed: z.unknown()
+  }).passthrough()
+}).passthrough();
+
+// src/cli/analyze/models.ts
+var ValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+
+// src/cli/analyze/adapters.ts
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+function getPortableFallbackConfig(cwd = process.cwd()) {
+  const options = {
+    doNotFollow: {
+      path: "node_modules"
+    },
+    tsPreCompilationDeps: true,
+    enhancedResolveOptions: {
+      exportsFields: ["exports"],
+      conditionNames: ["import", "require", "node", "default"]
+    }
+  };
+  const tsConfigApp = path.resolve(cwd, "tsconfig.app.json");
+  const tsConfigDefault = path.resolve(cwd, "tsconfig.json");
+  try {
+    if (existsSync(tsConfigApp)) {
+      options.tsConfig = { fileName: "./tsconfig.app.json" };
+    } else if (existsSync(tsConfigDefault)) {
+      options.tsConfig = { fileName: "./tsconfig.json" };
+    }
+  } catch {
+  }
+  return { options };
+}
+async function resolveDepcruiseConfig(configPath, cwd = process.cwd()) {
+  if (configPath) {
+    const absConfigPath = path.resolve(cwd, configPath);
+    if (!existsSync(absConfigPath)) {
+      throw new ValidationError(`Specified dependency-cruiser configuration file not found at ${configPath}`);
+    }
+    try {
+      const extractDepcruiseConfigModule = await import("dependency-cruiser/config-utl/extract-depcruise-config");
+      const extractDepcruiseConfig = extractDepcruiseConfigModule.default || extractDepcruiseConfigModule;
+      const config = await extractDepcruiseConfig(absConfigPath);
+      return {
+        config,
+        configPath: absConfigPath,
+        source: "explicit"
+      };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ValidationError(`Failed to load specified dependency-cruiser configuration at ${configPath}: ${message}`);
+    }
+  }
+  const conventionalFiles = [
+    ".dependency-cruiser.cjs",
+    ".dependency-cruiser.js",
+    ".dependency-cruiser.mjs",
+    ".dependency-cruiser.json"
+  ];
+  for (const fileName of conventionalFiles) {
+    const candidate = path.resolve(cwd, fileName);
+    if (existsSync(candidate)) {
+      try {
+        const extractDepcruiseConfigModule = await import("dependency-cruiser/config-utl/extract-depcruise-config");
+        const extractDepcruiseConfig = extractDepcruiseConfigModule.default || extractDepcruiseConfigModule;
+        const config = await extractDepcruiseConfig(candidate);
+        return {
+          config,
+          configPath: candidate,
+          source: "discovered"
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ValidationError(`Failed to load discovered dependency-cruiser configuration at ${fileName}: ${message}`);
+      }
+    }
+  }
+  return {
+    config: getPortableFallbackConfig(cwd),
+    configPath: null,
+    source: "fallback"
+  };
+}
+async function generateDependencyGraph(options) {
+  const cwd = options.cwd ? path.resolve(options.cwd) : process.cwd();
+  const resolvedConfig = await resolveDepcruiseConfig(options.configPath, cwd);
+  const prevCwd = process.cwd();
+  let cruiseResultRaw;
+  try {
+    process.chdir(cwd);
+    const { cruise } = await import("dependency-cruiser");
+    const rawOptions = resolvedConfig.config.options || {};
+    const cruiseOptions = { ...rawOptions };
+    if (resolvedConfig.config.forbidden || resolvedConfig.config.allowed || resolvedConfig.config.required) {
+      cruiseOptions.ruleSet = resolvedConfig.config;
+    }
+    const cruiseOutput = await cruise(options.sourceRoots, cruiseOptions);
+    cruiseResultRaw = cruiseOutput.output;
+  } catch (err) {
+    if (err instanceof ValidationError) {
+      throw err;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to generate dependency graph: ${message}`);
+  } finally {
+    process.chdir(prevCwd);
+  }
+  const validationResult = CruiseResultSchema.safeParse(cruiseResultRaw);
+  if (!validationResult.success) {
+    throw new ValidationError(`Generated dependency graph failed schema validation:
+${validationResult.error.message}`);
+  }
+  const modules = validationResult.data.modules.map((m) => ({
+    source: m.source,
+    dependencies: m.dependencies,
+    dependents: m.dependents
+  }));
+  return {
+    cruiseResult: validationResult.data,
+    modules,
+    configSource: resolvedConfig.source
+  };
+}
+async function readDependencyGraph(graphPath, cwd = process.cwd()) {
+  const absolutePath = path.resolve(cwd, graphPath);
+  let data;
+  let parsed;
+  try {
+    data = await fs.readFile(absolutePath, "utf8");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Failed to read dependency graph at ${graphPath}: ${message}`);
+  }
+  try {
+    parsed = JSON.parse(data);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ValidationError(`Invalid JSON in dependency graph at ${graphPath}: ${message}`);
+  }
+  const validationResult = CruiseResultSchema.safeParse(parsed);
+  if (!validationResult.success) {
+    throw new ValidationError(`Invalid dependency-cruiser output shape in ${graphPath}:
+${validationResult.error.message}`);
+  }
+  return validationResult.data.modules.map((m) => ({
+    source: m.source,
+    dependencies: m.dependencies,
+    dependents: m.dependents
+  }));
+}
+async function runEslintComplexityScan(sourcePath, sourceFiles, cwd = process.cwd()) {
+  let eslintModule;
+  try {
+    eslintModule = await import("eslint");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ValidationError(`ESLint is not installed in ${cwd}: ${message}. Maritime requires ESLint 9+ as a peer dependency.`);
+  }
+  const ESLint = eslintModule.ESLint;
+  const rawPaths = Array.isArray(sourcePath) ? sourcePath : [sourcePath];
+  const globPatterns = rawPaths.map((p) => `${path.resolve(cwd, p).replace(/\\/g, "/")}/**/*.{ts,tsx}`);
+  const hasExplicitFiles = sourceFiles !== void 0;
+  let targets;
+  if (hasExplicitFiles) {
+    targets = sourceFiles.map((f) => path.resolve(cwd, f).replace(/\\/g, "/"));
+  } else {
+    targets = globPatterns;
+  }
+  try {
+    const eslint = new ESLint({
+      cwd,
+      overrideConfig: [{
+        rules: {
+          "complexity": ["warn", 0]
+        }
+      }]
+    });
+    const unignoredTargets = [];
+    const ignoredResults = [];
+    for (const t of targets) {
+      if (hasExplicitFiles) {
+        try {
+          await fs.access(t);
+        } catch {
+          ignoredResults.push({
+            filePath: t,
+            ignored: true,
+            messages: []
+          });
+          continue;
+        }
+      }
+      const isIgnored = await eslint.isPathIgnored(t);
+      if (isIgnored) {
+        ignoredResults.push({
+          filePath: t,
+          ignored: true,
+          messages: []
+        });
+      } else {
+        unignoredTargets.push(t);
+      }
+    }
+    const lintResults = [];
+    if (unignoredTargets.length > 0) {
+      if (hasExplicitFiles) {
+        for (const targetFile of unignoredTargets) {
+          try {
+            const rawResults = await eslint.lintFiles([targetFile]);
+            for (const result of rawResults) {
+              lintResults.push({
+                filePath: result.filePath,
+                ignored: Boolean(result.ignored),
+                messages: result.messages.map((msg) => ({
+                  ruleId: typeof msg.ruleId === "string" ? msg.ruleId : "unknown",
+                  message: msg.message,
+                  fatal: Boolean(msg.fatal)
+                }))
+              });
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes("No files matching") || message.includes("are ignored") || message.includes("All files matched")) {
+              ignoredResults.push({
+                filePath: targetFile,
+                ignored: true,
+                messages: []
+              });
+            } else {
+              throw err;
+            }
+          }
+        }
+      } else {
+        const rawResults = await eslint.lintFiles(unignoredTargets);
+        for (const result of rawResults) {
+          lintResults.push({
+            filePath: result.filePath,
+            ignored: Boolean(result.ignored),
+            messages: result.messages.map((msg) => ({
+              ruleId: typeof msg.ruleId === "string" ? msg.ruleId : "unknown",
+              message: msg.message,
+              fatal: Boolean(msg.fatal)
+            }))
+          });
+        }
+      }
+    }
+    return [...lintResults, ...ignoredResults];
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("All files matched") && message.includes("are ignored")) {
+      return targets.map((t) => ({
+        filePath: t,
+        ignored: true,
+        messages: []
+      }));
+    }
+    throw new Error(`Failed to run ESLint: ${message}`);
+  }
+}
+async function countLinesOfCode(sourceFiles, cwd = process.cwd()) {
+  const locMap = {};
+  for (const file of sourceFiles) {
+    try {
+      const absolutePath = path.resolve(cwd, file);
+      const content = await fs.readFile(absolutePath, "utf8");
+      locMap[file] = content.split("\n").length;
+    } catch {
+      locMap[file] = 0;
+    }
+  }
+  return locMap;
+}
+function getToolVersion() {
+  try {
+    const currentFile = fileURLToPath(import.meta.url);
+    let currDir = path.dirname(currentFile);
+    while (currDir) {
+      const pkgPath = path.join(currDir, "package.json");
+      if (existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+          if (pkg.name === "@dependency-maritime/cli" && typeof pkg.version === "string") {
+            return pkg.version;
+          }
+        } catch {
+        }
+      }
+      const parent = path.dirname(currDir);
+      if (parent === currDir) break;
+      currDir = parent;
+    }
+  } catch {
+  }
+  return "0.0.0";
+}
+async function writeOutputFiles(metricsPath, metricsData, reportPath, reportData, arg5, arg6, arg7) {
+  let manifestPath;
+  let manifestData;
+  let cwd = process.cwd();
+  if (typeof arg5 === "object" && arg5 !== null) {
+    manifestPath = arg5.manifestPath;
+    manifestData = arg5.manifestData;
+    if (arg5.cwd) {
+      cwd = arg5.cwd;
+    }
+  } else if (typeof arg5 === "string") {
+    if (arg6 !== void 0) {
+      manifestPath = arg5;
+      manifestData = arg6;
+      if (typeof arg7 === "string") {
+        cwd = arg7;
+      }
+    } else {
+      cwd = arg5;
+    }
+  } else if (typeof arg7 === "string") {
+    cwd = arg7;
+  }
+  const absMetricsPath = path.resolve(cwd, metricsPath);
+  const absReportPath = path.resolve(cwd, reportPath);
+  await fs.mkdir(path.dirname(absMetricsPath), { recursive: true });
+  await fs.mkdir(path.dirname(absReportPath), { recursive: true });
+  const promises = [
+    fs.writeFile(absMetricsPath, JSON.stringify(metricsData, null, 2)),
+    fs.writeFile(absReportPath, reportData)
+  ];
+  if (manifestPath && manifestData !== void 0) {
+    const absManifestPath = path.resolve(cwd, manifestPath);
+    await fs.mkdir(path.dirname(absManifestPath), { recursive: true });
+    promises.push(fs.writeFile(absManifestPath, JSON.stringify(manifestData, null, 2)));
+  }
+  await Promise.all(promises);
+}
+
+// src/cli/analyze/calculate-metrics.ts
+function isSupportedTypeScriptFile(filepath) {
+  const lower = filepath.toLowerCase();
+  if (!lower.endsWith(".ts") && !lower.endsWith(".tsx")) {
+    return false;
+  }
+  if (lower.endsWith(".d.ts")) {
+    return false;
+  }
+  if (lower.includes(".test.") || lower.includes(".spec.")) {
+    return false;
+  }
+  return true;
+}
+function calculateInstability(fanIn, fanOut) {
+  if (fanIn + fanOut === 0) {
+    return 0;
+  }
+  return fanOut / (fanIn + fanOut);
+}
+function calculateScore(loc, complexity, fanOut, instability) {
+  return loc / 10 + complexity * 2 + fanOut * 2 + instability * 20;
+}
+function calculateHealthScore(files, thresholds) {
+  let score = 100;
+  for (const f of files) {
+    if (f.loc > thresholds.loc) score -= 1;
+    if (f.complexity > thresholds.complexity) score -= 1;
+    if (f.fanOut > thresholds.fanOut) score -= 1;
+  }
+  return Math.max(0, Math.min(100, score));
+}
+function calculateMetrics(modules, locMap, complexityMap, thresholds, sourcePrefix = "src") {
+  const rawPrefixes = Array.isArray(sourcePrefix) ? sourcePrefix : [sourcePrefix];
+  const normalizedPrefixes = rawPrefixes.map((p) => p === "." ? "" : p.replace(/\/+$/, ""));
+  const files = modules.filter((m) => {
+    if (m.source.startsWith("node_modules/") || m.source.startsWith("node:")) {
+      return false;
+    }
+    const isSource = normalizedPrefixes.some((prefix) => {
+      if (prefix === "") return true;
+      return m.source === prefix || m.source.startsWith(`${prefix}/`);
+    });
+    return isSource && isSupportedTypeScriptFile(m.source);
+  }).map((m) => {
+    const loc = locMap[m.source] || 0;
+    const fanOut = m.dependencies.length;
+    const fanIn = m.dependents.length;
+    const instability = calculateInstability(fanIn, fanOut);
+    let complexity = 0;
+    let scanned = false;
+    const eslintData = complexityMap[m.source];
+    if (eslintData !== void 0) {
+      if (typeof eslintData === "object" && eslintData !== null) {
+        complexity = eslintData.complexity;
+        scanned = eslintData.scanned;
+      } else if (typeof eslintData === "number") {
+        complexity = eslintData;
+        scanned = true;
+      }
+    }
+    const score = calculateScore(loc, complexity, fanOut, instability);
+    return {
+      file: m.source,
+      loc,
+      fanOut,
+      fanIn,
+      instability: parseFloat(instability.toFixed(2)),
+      complexity,
+      score: parseFloat(score.toFixed(1)),
+      scanned
+    };
+  });
+  const healthScore = calculateHealthScore(files, thresholds);
+  const unmeasuredFiles = files.filter((f) => !f.scanned).map((f) => f.file);
+  const skippedCount = unmeasuredFiles.length;
+  const topByScore = [...files].sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    return a.file.localeCompare(b.file);
+  }).slice(0, 10);
+  const topByComplexity = [...files].sort((a, b) => {
+    if (b.complexity !== a.complexity) return b.complexity - a.complexity;
+    return a.file.localeCompare(b.file);
+  }).slice(0, 10);
+  return {
+    files,
+    healthScore: parseFloat(healthScore.toFixed(1)),
+    topByScore,
+    topByComplexity,
+    skippedCount,
+    unmeasuredFiles
+  };
+}
+
+// src/cli/analyze/parse-eslint.ts
+import * as path2 from "path";
+function parseEslintComplexityReport(eslintResults, cwd) {
+  const complexityMap = {};
+  for (const file of eslintResults) {
+    const relPath = path2.relative(cwd, file.filePath).replace(/\\/g, "/");
+    if (file.ignored || file.messages.some((m) => m.fatal === true)) {
+      complexityMap[relPath] = { complexity: 0, scanned: false };
+      continue;
+    }
+    let maxC = 0;
+    for (const msg of file.messages) {
+      if (msg.ruleId === "complexity") {
+        const match = msg.message.match(/complexity of (\d+)/);
+        if (match) {
+          const c = parseInt(match[1], 10);
+          if (c > maxC) {
+            maxC = c;
+          }
+        }
+      }
+    }
+    complexityMap[relPath] = {
+      complexity: maxC > 0 ? maxC : 1,
+      scanned: true
+    };
+  }
+  return complexityMap;
+}
+
+// src/cli/analyze/render-markdown-report.ts
+function escapeMarkdown(text) {
+  return text.replace(/_/g, "\\_").replace(/\*/g, "\\*");
+}
+function renderMarkdownReport(result, thresholds, date = /* @__PURE__ */ new Date()) {
+  const dateString = date.toISOString().split("T")[0];
+  const healthScoreFormatted = result.healthScore.toFixed(1);
+  const totalFiles = result.files.length;
+  const measuredFiles = result.files.filter((f) => f.scanned).length;
+  const unmeasuredFilesCount = result.skippedCount;
+  const scoreTableRows = result.topByScore.map(
+    (f) => `| \`${escapeMarkdown(f.file)}\` | **${f.score}** | ${f.loc} | ${f.complexity} | ${f.fanOut} | ${f.instability} |`
+  ).join("\n");
+  const complexityTableRows = result.topByComplexity.map(
+    (f) => `| \`${escapeMarkdown(f.file)}\` | **${f.complexity}** | ${f.loc} |`
+  ).join("\n");
+  let skippedSection = "";
+  if (unmeasuredFilesCount > 0 && result.unmeasuredFiles.length > 0) {
+    const fileList = result.unmeasuredFiles.map((f) => `- \`${escapeMarkdown(f)}\``).join("\n");
+    skippedSection = `
+
+### \u26A0\uFE0F Skipped / Unmeasured Files (${unmeasuredFilesCount})
+${fileList}`;
+  }
+  return `
+## \u{1F6A8} Automated Complexity Report
+
+**Last Updated:** ${dateString}
+
+### \u{1F3E5} Repository Health Score: **${healthScoreFormatted} / 100**
+
+*   **Formula**: 100 - Penalties for Files exceeding thresholds (LOC > ${thresholds.loc}, Complexity > ${thresholds.complexity}, Fan-Out > ${thresholds.fanOut}).
+*   **Total Graph Files**: ${totalFiles}
+*   **Measured Files**: ${measuredFiles}
+*   **Unmeasured Files**: ${unmeasuredFilesCount}
+
+### \u{1F525} Top 10 High-Complexity Files (Compound Score)
+_Score = (LOC/10) + (Complexity*2) + (FanOut*2) + (Instability*20)_
+
+| File | Score | LOC | Complexity | Fan-Out | Instability |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+${scoreTableRows}
+
+### \u{1F9E0} Top 10 Logic-Heavy Files (Cyclomatic Complexity)
+| File | Max Complexity | LOC |
+| :--- | :--- | :--- |
+${complexityTableRows}${skippedSection}
+`.trim() + "\n";
+}
+
+// src/cli/analyze/environment.ts
+import * as fs2 from "fs";
+import * as path3 from "path";
+import { createRequire } from "node:module";
+var LEGACY_CONFIG_FILES = [
+  ".eslintrc",
+  ".eslintrc.js",
+  ".eslintrc.cjs",
+  ".eslintrc.mjs",
+  ".eslintrc.json",
+  ".eslintrc.yaml",
+  ".eslintrc.yml"
+];
+var FLAT_CONFIG_FILES = [
+  "eslint.config.js",
+  "eslint.config.mjs",
+  "eslint.config.cjs",
+  "eslint.config.ts",
+  "eslint.config.mts",
+  "eslint.config.cts"
+];
+function validateNodeVersion(nodeVersionStr = process.versions.node) {
+  const cleanVersion = nodeVersionStr.replace(/^v/, "");
+  const parts = cleanVersion.split(".").map((p) => parseInt(p, 10));
+  const major = parts[0] || 0;
+  const minor = parts[1] || 0;
+  if (major < 20 || major === 20 && minor < 19) {
+    throw new ValidationError(
+      `Maritime requires Node.js >=20.19.0 (current version: v${cleanVersion}).`
+    );
+  }
+}
+function detectEslintConfig(cwd = process.cwd()) {
+  for (const legacyFile of LEGACY_CONFIG_FILES) {
+    const fullPath = path3.join(cwd, legacyFile);
+    if (fs2.existsSync(fullPath)) {
+      return { mode: "Legacy", isLegacy: true, hasFlatConfig: false, legacyFile };
+    }
+  }
+  const pkgPath = path3.join(cwd, "package.json");
+  if (fs2.existsSync(pkgPath)) {
+    try {
+      const content = fs2.readFileSync(pkgPath, "utf8");
+      const parsed = JSON.parse(content);
+      if (parsed && typeof parsed === "object" && "eslintConfig" in parsed && parsed.eslintConfig !== void 0) {
+        return { mode: "Legacy", isLegacy: true, hasFlatConfig: false, legacyFile: "package.json (eslintConfig)" };
+      }
+    } catch {
+    }
+  }
+  for (const flatFile of FLAT_CONFIG_FILES) {
+    const fullPath = path3.join(cwd, flatFile);
+    if (fs2.existsSync(fullPath)) {
+      return { mode: `Flat Config (${flatFile})`, isLegacy: false, hasFlatConfig: true };
+    }
+  }
+  return { mode: "None Detected", isLegacy: false, hasFlatConfig: false };
+}
+function validateEslintEnvironment(cwd = process.cwd(), nodeVersionStr) {
+  validateNodeVersion(nodeVersionStr);
+  const absCwd = path3.resolve(cwd);
+  const req = createRequire(path3.join(absCwd, "package.json"));
+  let eslintModule;
+  try {
+    const eslintPath = req.resolve("eslint");
+    eslintModule = req(eslintPath);
+  } catch {
+    throw new ValidationError(
+      `ESLint is not installed in ${absCwd}. Maritime requires ESLint 9+ as a peer dependency.`
+    );
+  }
+  const eslintVersion = eslintModule.ESLint?.version;
+  if (eslintVersion) {
+    const major = parseInt(eslintVersion.split(".")[0], 10);
+    if (isNaN(major) || major < 9) {
+      throw new ValidationError(
+        `Unsupported ESLint version (v${eslintVersion}). Maritime requires ESLint >=9.0.0.`
+      );
+    }
+  }
+  const detected = detectEslintConfig(cwd);
+  if (detected.isLegacy) {
+    throw new ValidationError(
+      `Legacy ESLint configuration detected (${detected.legacyFile}). Maritime requires ESLint 9+ flat configuration (eslint.config.*).`
+    );
+  }
+  if (!detected.hasFlatConfig) {
+    throw new ValidationError(
+      `No ESLint flat configuration found in ${cwd}. Maritime requires ESLint 9+ flat configuration (eslint.config.*).`
+    );
+  }
+  return { mode: detected.mode };
+}
+
+// src/schema/manifest.ts
+import { z as z2 } from "zod";
+var MANIFEST_SCHEMA_VERSION = "1.0.0";
+var ArtifactManifestArtifactsSchema = z2.object({
+  graph: z2.string().min(1),
+  metrics: z2.string().min(1),
+  report: z2.string().min(1)
+});
+var ArtifactManifestSummarySchema = z2.object({
+  totalFiles: z2.number().int().nonnegative(),
+  healthScore: z2.number(),
+  scannedCount: z2.number().int().nonnegative(),
+  skippedCount: z2.number().int().nonnegative()
+});
+var ArtifactManifestSchema = z2.object({
+  schemaVersion: z2.literal(MANIFEST_SCHEMA_VERSION),
+  toolVersion: z2.string().min(1),
+  generatedAt: z2.string(),
+  sourceRoots: z2.array(z2.string()).min(1),
+  artifacts: ArtifactManifestArtifactsSchema,
+  summary: ArtifactManifestSummarySchema
+});
+
+// src/cli/commands/analyze.ts
+import * as path4 from "path";
+var DEFAULT_THRESHOLDS = {
+  loc: 300,
+  complexity: 10,
+  fanOut: 15
+};
+async function runAnalyzeCommand(args) {
+  let values;
+  try {
+    const parsed = parseArgs({
+      args,
+      allowPositionals: true,
+      options: {
+        source: { type: "string", multiple: true, default: ["src"] },
+        graph: { type: "string" },
+        metrics: { type: "string" },
+        report: { type: "string" },
+        output: { type: "string" },
+        "depcruise-config": { type: "string" },
+        cwd: { type: "string" },
+        "fail-on-unmeasured": { type: "boolean", default: false },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+    values = parsed.values;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`Error parsing arguments: ${message}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(`
+Usage: maritime analyze [options]
+
+Options:
+  --output <dir>            Output directory for all generated artifacts (e.g. .maritime)
+  --source <dir>            Source directory/directories to analyze (repeatable or comma-separated, default: "src")
+  --graph <file>            Dependency graph JSON file path (input if file exists; output if generated)
+  --metrics <file>          Output JSON file for complexity metrics
+  --report <file>           Output Markdown file for complexity report
+  --depcruise-config <file> Optional path to repository dependency-cruiser configuration
+  --cwd <dir>               Working directory root for resolution
+  --fail-on-unmeasured      Fail if any graph source file is skipped/unmeasured by ESLint
+
+Examples:
+  # Concise generated-graph workflow:
+  maritime analyze --source app --output .maritime
+
+  # Explicit pre-generated graph workflow:
+  maritime analyze --source app --graph artifacts/dependency-graph.json --metrics metrics.json --report report.md
+
+Exit Codes:
+  0 - Successful analysis
+  1 - Operational or runtime failure
+  2 - Invalid CLI arguments, environment, or invalid input artifact/schema
+        `);
+    return 0;
+  }
+  const workingDir = values.cwd ? path4.resolve(values.cwd) : process.cwd();
+  let targetGraphPath = values.graph;
+  let targetMetricsPath = values.metrics;
+  let targetReportPath = values.report;
+  if (values.output) {
+    targetGraphPath = targetGraphPath ?? path4.join(values.output, "dependency-graph.json");
+    targetMetricsPath = targetMetricsPath ?? path4.join(values.output, "complexity-metrics.json");
+    targetReportPath = targetReportPath ?? path4.join(values.output, "complexity-report.md");
+  }
+  if (!targetMetricsPath || !targetReportPath) {
+    console.error("Error: Either --output or both --metrics and --report must be specified.");
+    return 2;
+  }
+  if (!targetGraphPath) {
+    targetGraphPath = "dependency-graph.json";
+  }
+  const rawSources = values.source && values.source.length > 0 ? values.source.flatMap((s) => s.split(",").map((item) => item.trim())).filter(Boolean) : ["src"];
+  const normalizedSources = rawSources.map((rawSrc) => {
+    let norm = path4.relative(workingDir, path4.resolve(workingDir, rawSrc)).replace(/\\/g, "/");
+    if (norm === "") norm = ".";
+    return norm;
+  });
+  try {
+    console.log("\u{1F4CA} Starting Complexity Analysis...");
+    console.log("   - Validating Environment & Configuration...");
+    const { mode: eslintConfigMode } = validateEslintEnvironment(workingDir);
+    console.log(`   - Working Directory: ${workingDir}`);
+    console.log(`   - Source Root (raw): ${rawSources.join(", ")}`);
+    console.log(`   - Source Root (normalized): ${normalizedSources.join(", ")}`);
+    console.log(`   - Graph Path: ${targetGraphPath}`);
+    console.log(`   - ESLint Config Mode: ${eslintConfigMode}`);
+    const manifestDir = values.output ? path4.resolve(workingDir, values.output) : path4.dirname(path4.resolve(workingDir, targetMetricsPath));
+    let modules;
+    const isGraphSupplied = values.graph !== void 0;
+    let effectiveGraphPath;
+    if (isGraphSupplied) {
+      console.log("   - Reading Supplied Dependency Cruiser JSON...");
+      modules = await readDependencyGraph(values.graph, workingDir);
+      const absGraphPath = path4.resolve(workingDir, values.graph);
+      const relGraphToManifest = path4.relative(manifestDir, absGraphPath);
+      const isOutside = relGraphToManifest.startsWith("..") || path4.isAbsolute(relGraphToManifest);
+      if (isOutside) {
+        console.log("   - Staging supplied graph into artifact directory...");
+        effectiveGraphPath = path4.join(manifestDir, path4.basename(absGraphPath));
+        try {
+          await fsPromises.mkdir(manifestDir, { recursive: true });
+          await fsPromises.copyFile(absGraphPath, effectiveGraphPath);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          throw new Error(`Failed to stage supplied dependency graph into artifact directory: ${message}`);
+        }
+      } else {
+        effectiveGraphPath = absGraphPath;
+      }
+    } else {
+      console.log("   - Generating Dependency Graph with dependency-cruiser...");
+      const genResult = await generateDependencyGraph({
+        sourceRoots: rawSources,
+        configPath: values["depcruise-config"],
+        cwd: workingDir
+      });
+      console.log(`   - Dependency-Cruiser Config Source: ${genResult.configSource}`);
+      modules = genResult.modules;
+      effectiveGraphPath = path4.resolve(workingDir, targetGraphPath);
+      await fsPromises.mkdir(path4.dirname(effectiveGraphPath), { recursive: true });
+      await fsPromises.writeFile(effectiveGraphPath, JSON.stringify(genResult.cruiseResult, null, 2));
+    }
+    const sourceFiles = modules.map((m) => m.source).filter((src) => {
+      const isSource = normalizedSources.some((norm) => {
+        if (norm === ".") return true;
+        return src === norm || src.startsWith(`${norm}/`);
+      });
+      return isSource && isSupportedTypeScriptFile(src);
+    });
+    console.log("   - Running ESLint for Complexity...");
+    const eslintResults = await runEslintComplexityScan(rawSources, sourceFiles, workingDir);
+    const complexityMap = parseEslintComplexityReport(eslintResults, workingDir);
+    console.log("   - Counting Lines of Code...");
+    const locMap = await countLinesOfCode(sourceFiles, workingDir);
+    console.log("   - Aggregating Metrics...");
+    const analysisResult = calculateMetrics(
+      modules,
+      locMap,
+      complexityMap,
+      DEFAULT_THRESHOLDS,
+      normalizedSources
+    );
+    console.log(`   - Skipped / Unmeasured Source Files: ${analysisResult.skippedCount}`);
+    if (analysisResult.skippedCount > 0) {
+      console.warn(`\u26A0\uFE0F Warning: ${analysisResult.skippedCount} graph source file(s) were skipped or ignored by ESLint and could not be measured:`);
+      analysisResult.unmeasuredFiles.forEach((f) => console.warn(`   - ${f}`));
+      if (values["fail-on-unmeasured"]) {
+        throw new ValidationError(
+          `Analysis failed because ${analysisResult.skippedCount} graph source file(s) were not scanned by ESLint (--fail-on-unmeasured).`
+        );
+      }
+    }
+    console.log("   - Generating Outputs...");
+    const metricsMap = analysisResult.files.reduce((acc, f) => {
+      acc[f.file] = {
+        complexity: f.complexity,
+        loc: f.loc,
+        instability: f.instability,
+        fanIn: f.fanIn,
+        fanOut: f.fanOut,
+        scanned: f.scanned
+      };
+      return acc;
+    }, {});
+    const reportContent = renderMarkdownReport(analysisResult, DEFAULT_THRESHOLDS);
+    const targetManifestPath = path4.relative(workingDir, path4.join(manifestDir, "manifest.json")).replace(/\\/g, "/");
+    const relGraph = path4.relative(manifestDir, effectiveGraphPath).replace(/\\/g, "/");
+    const relMetrics = path4.relative(manifestDir, path4.resolve(workingDir, targetMetricsPath)).replace(/\\/g, "/");
+    const relReport = path4.relative(manifestDir, path4.resolve(workingDir, targetReportPath)).replace(/\\/g, "/");
+    const artifactRelPaths = { graph: relGraph, metrics: relMetrics, report: relReport };
+    for (const [key, relPath] of Object.entries(artifactRelPaths)) {
+      if (relPath.startsWith("..") || path4.isAbsolute(relPath)) {
+        throw new ValidationError(`Manifest artifact path for "${key}" escapes the artifact directory: "${relPath}"`);
+      }
+    }
+    const manifest = {
+      schemaVersion: MANIFEST_SCHEMA_VERSION,
+      toolVersion: getToolVersion(),
+      generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      sourceRoots: normalizedSources,
+      artifacts: {
+        graph: relGraph,
+        metrics: relMetrics,
+        report: relReport
+      },
+      summary: {
+        totalFiles: analysisResult.files.length,
+        healthScore: analysisResult.healthScore,
+        scannedCount: analysisResult.files.filter((f) => f.scanned).length,
+        skippedCount: analysisResult.skippedCount
+      }
+    };
+    await writeOutputFiles(
+      targetMetricsPath,
+      metricsMap,
+      targetReportPath,
+      reportContent,
+      targetManifestPath,
+      manifest,
+      workingDir
+    );
+    console.log("\u2705 Complexity Report Updated and Metrics Exported!");
+    return 0;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`Error analyzing project: ${message}`);
+    if (e instanceof ValidationError) {
+      return 2;
+    }
+    return 1;
+  }
+}
+
+// src/cli/commands/validate.ts
+import { parseArgs as parseArgs2 } from "node:util";
+import * as path6 from "node:path";
+
+// src/cli/validate/validate.ts
+import * as fsPromises2 from "node:fs/promises";
+import * as path5 from "node:path";
+
+// src/schema/complexity-metrics.ts
+import { z as z3 } from "zod";
+var ComplexityMetricSchema = z3.object({
+  complexity: z3.number(),
+  loc: z3.number(),
+  instability: z3.number().optional(),
+  fanIn: z3.number().optional(),
+  fanOut: z3.number().optional(),
+  scanned: z3.boolean().optional()
+});
+var ComplexityMetricsMapSchema = z3.record(z3.string(), ComplexityMetricSchema);
+
+// src/cli/validate/validate.ts
+async function validateArtifacts(options = {}) {
+  const workingDir = options.cwd ? path5.resolve(options.cwd) : process.cwd();
+  const artifactDirRelative = options.artifactDir ?? ".maritime";
+  const artifactDir = path5.resolve(workingDir, artifactDirRelative);
+  try {
+    const stat2 = await fsPromises2.stat(artifactDir);
+    if (!stat2.isDirectory()) {
+      throw new ValidationError(`Artifact path is not a directory: ${artifactDirRelative}`);
+    }
+  } catch (err) {
+    if (err instanceof ValidationError) throw err;
+    throw new ValidationError(`Artifact directory not found: ${artifactDirRelative}`);
+  }
+  const manifestPath = path5.join(artifactDir, "manifest.json");
+  let manifestRaw;
+  try {
+    manifestRaw = await fsPromises2.readFile(manifestPath, "utf8");
+  } catch {
+    throw new ValidationError(`Missing manifest file: ${path5.relative(workingDir, manifestPath)}`);
+  }
+  let manifestJson;
+  try {
+    manifestJson = JSON.parse(manifestRaw);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ValidationError(`Malformed JSON in manifest file ${path5.relative(workingDir, manifestPath)}: ${message}`);
+  }
+  const manifestParse = ArtifactManifestSchema.safeParse(manifestJson);
+  if (!manifestParse.success) {
+    const rawObj = manifestJson;
+    if (rawObj && typeof rawObj === "object" && "schemaVersion" in rawObj && typeof rawObj.schemaVersion === "string" && rawObj.schemaVersion !== MANIFEST_SCHEMA_VERSION) {
+      throw new ValidationError(
+        `Unsupported manifest schemaVersion "${rawObj.schemaVersion}". Supported schemaVersion is "${MANIFEST_SCHEMA_VERSION}".`
+      );
+    }
+    throw new ValidationError(`Invalid manifest structure in ${path5.relative(workingDir, manifestPath)}:
+${manifestParse.error.message}`);
+  }
+  const manifest = manifestParse.data;
+  const artifactKeys = ["graph", "metrics", "report"];
+  for (const key of artifactKeys) {
+    const declaredPath = manifest.artifacts[key];
+    const resolvedPath = path5.resolve(artifactDir, declaredPath);
+    const rel = path5.relative(artifactDir, resolvedPath);
+    if (rel.startsWith("..") || path5.isAbsolute(rel)) {
+      throw new ValidationError(`Manifest artifact path for "${key}" escapes the artifact directory: "${declaredPath}"`);
+    }
+    try {
+      await fsPromises2.access(resolvedPath);
+    } catch {
+      throw new ValidationError(`Declared artifact file for "${key}" not found: ${declaredPath}`);
+    }
+    if (key === "graph") {
+      let graphRaw;
+      try {
+        graphRaw = await fsPromises2.readFile(resolvedPath, "utf8");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ValidationError(`Failed to read graph file ${declaredPath}: ${message}`);
+      }
+      let graphJson;
+      try {
+        graphJson = JSON.parse(graphRaw);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ValidationError(`Invalid JSON in graph file ${declaredPath}: ${message}`);
+      }
+      const graphParse = CruiseResultSchema.safeParse(graphJson);
+      if (!graphParse.success) {
+        throw new ValidationError(`Invalid dependency-cruiser graph schema in ${declaredPath}:
+${graphParse.error.message}`);
+      }
+    }
+    if (key === "metrics") {
+      let metricsRaw;
+      try {
+        metricsRaw = await fsPromises2.readFile(resolvedPath, "utf8");
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ValidationError(`Failed to read metrics file ${declaredPath}: ${message}`);
+      }
+      let metricsJson;
+      try {
+        metricsJson = JSON.parse(metricsRaw);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new ValidationError(`Invalid JSON in metrics file ${declaredPath}: ${message}`);
+      }
+      const metricsParse = ComplexityMetricsMapSchema.safeParse(metricsJson);
+      if (!metricsParse.success) {
+        throw new ValidationError(`Invalid complexity metrics schema in ${declaredPath}:
+${metricsParse.error.message}`);
+      }
+    }
+  }
+  return {
+    manifest,
+    artifactDir
+  };
+}
+
+// src/cli/commands/validate.ts
+async function runValidateCommand(args) {
+  let values;
+  let positionals;
+  try {
+    const parsed = parseArgs2({
+      args,
+      allowPositionals: true,
+      options: {
+        cwd: { type: "string" },
+        help: { type: "boolean", short: "h" }
+      }
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`Error parsing arguments: ${message}`);
+    return 2;
+  }
+  if (values.help) {
+    console.log(`
+Usage: maritime validate [directory] [options]
+
+Arguments:
+  [directory]               Artifact directory containing manifest.json (default: ".maritime")
+
+Options:
+  --cwd <dir>               Working directory root for resolution
+  -h, --help                Show help message
+
+Examples:
+  maritime validate
+  maritime validate .maritime
+  maritime validate artifacts/maritime-output
+
+Exit Codes:
+  0 - Valid artifact directory contract
+  1 - Operational or runtime failure
+  2 - Invalid CLI arguments, missing/malformed manifest, path escaping, or schema mismatch
+        `);
+    return 0;
+  }
+  const artifactDirArg = positionals[0] || ".maritime";
+  const workingDir = values.cwd ? path6.resolve(values.cwd) : process.cwd();
+  try {
+    console.log(`\u{1F50D} Validating Maritime artifact directory: ${artifactDirArg}...`);
+    const result = await validateArtifacts({
+      artifactDir: artifactDirArg,
+      cwd: workingDir
+    });
+    console.log("\u2705 Artifact Directory Contract Validated!");
+    console.log(`   - Schema Version: ${result.manifest.schemaVersion}`);
+    console.log(`   - Tool Version: ${result.manifest.toolVersion}`);
+    console.log(`   - Generated At: ${result.manifest.generatedAt}`);
+    console.log(`   - Source Roots: ${result.manifest.sourceRoots.join(", ")}`);
+    console.log(`   - Total Files: ${result.manifest.summary.totalFiles}`);
+    console.log(`   - Health Score: ${result.manifest.summary.healthScore}`);
+    return 0;
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.error(`Error validating artifacts: ${message}`);
+    if (e instanceof ValidationError) {
+      return 2;
+    }
+    return 1;
+  }
+}
+
+// src/cli/index.ts
+async function analyzeProject(options) {
+  const args = [];
+  if (options.graph) {
+    args.push("--graph", options.graph);
+  }
+  if (options.metrics) {
+    args.push("--metrics", options.metrics);
+  }
+  if (options.report) {
+    args.push("--report", options.report);
+  }
+  if (options.output) {
+    args.push("--output", options.output);
+  }
+  if (options.depcruiseConfig) {
+    args.push("--depcruise-config", options.depcruiseConfig);
+  }
+  if (options.cwd) {
+    args.push("--cwd", options.cwd);
+  }
+  if (options.failOnUnmeasured) {
+    args.push("--fail-on-unmeasured");
+  }
+  if (options.source) {
+    const sources = Array.isArray(options.source) ? options.source : [options.source];
+    for (const s of sources) {
+      args.push("--source", s);
+    }
+  }
+  return runAnalyzeCommand(args);
+}
+async function validateProject(options = {}) {
+  const args = [];
+  if (options.artifactDir) {
+    args.push(options.artifactDir);
+  }
+  if (options.cwd) {
+    args.push("--cwd", options.cwd);
+  }
+  return runValidateCommand(args);
+}
+export {
+  ArtifactManifestArtifactsSchema,
+  ArtifactManifestSchema,
+  ArtifactManifestSummarySchema,
+  MANIFEST_SCHEMA_VERSION,
+  ValidationError,
+  analyzeProject,
+  calculateHealthScore,
+  calculateInstability,
+  calculateMetrics,
+  calculateScore,
+  countLinesOfCode,
+  detectEslintConfig,
+  generateDependencyGraph,
+  isSupportedTypeScriptFile,
+  parseEslintComplexityReport,
+  readDependencyGraph,
+  renderMarkdownReport,
+  resolveDepcruiseConfig,
+  runAnalyzeCommand,
+  runEslintComplexityScan,
+  runValidateCommand,
+  validateArtifacts,
+  validateEslintEnvironment,
+  validateNodeVersion,
+  validateProject,
+  writeOutputFiles
+};