hermex 1.3.0-beta.4 → 2.0.0-beta.10

package/dist/index.d.mts

@@ -0,0 +1,381 @@
+import { z } from "zod";
+
+//#region src/config/schema.d.ts
+declare const RuleSeveritySchema: z.ZodEnum<{
+  error: "error";
+  info: "info";
+  warn: "warn";
+}>;
+declare const RuleConfigSchema: z.ZodObject<{
+  severity: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warn: "warn";
+  }>;
+  patterns: z.ZodArray<z.ZodString>;
+  message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const PackageFieldRuleSchema: z.ZodObject<{
+  severity: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warn: "warn";
+  }>;
+  patterns: z.ZodArray<z.ZodString>;
+  message: z.ZodOptional<z.ZodString>;
+  values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+declare const EngineVersionRuleSchema: z.ZodObject<{
+  severity: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warn: "warn";
+  }>;
+  range: z.ZodString;
+  message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const CodeownersRuleSchema: z.ZodObject<{
+  severity: z.ZodEnum<{
+    error: "error";
+    info: "info";
+    warn: "warn";
+  }>;
+  message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const HermexConfigSchema: z.ZodObject<{
+  includes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  excludes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  packages: z.ZodDefault<z.ZodObject<{
+    internal: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strip>>;
+  versus: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    name: z.ZodString;
+    packages: z.ZodArray<z.ZodString>;
+  }, z.core.$strip>>>;
+  rules: z.ZodDefault<z.ZodObject<{
+    detect_files: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    require_files: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    forbid_packages: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    require_packages: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    require_scripts: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    require_package_fields: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+      values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+      values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>]>>;
+    forbid_package_fields: z.ZodDefault<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+      values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      patterns: z.ZodArray<z.ZodString>;
+      message: z.ZodOptional<z.ZodString>;
+      values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>]>>;
+    engine_version: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      range: z.ZodString;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodArray<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      range: z.ZodString;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>]>>;
+    codeowners: z.ZodOptional<z.ZodObject<{
+      severity: z.ZodEnum<{
+        error: "error";
+        info: "info";
+        warn: "warn";
+      }>;
+      message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>>;
+  output: z.ZodDefault<z.ZodObject<{
+    summary: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<"log">, z.ZodLiteral<false>]>>;
+    components: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+      chart: "chart";
+      table: "table";
+    }>, z.ZodLiteral<false>]>>;
+    packages: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+      chart: "chart";
+      table: "table";
+    }>, z.ZodLiteral<false>]>>;
+    patterns: z.ZodDefault<z.ZodUnion<readonly [z.ZodEnum<{
+      chart: "chart";
+      table: "table";
+    }>, z.ZodLiteral<false>]>>;
+    details: z.ZodDefault<z.ZodBoolean>;
+    versus: z.ZodDefault<z.ZodBoolean>;
+    rules: z.ZodDefault<z.ZodBoolean>;
+    format: z.ZodDefault<z.ZodEnum<{
+      human: "human";
+      json: "json";
+    }>>;
+  }, z.core.$strip>>;
+  releaseAge: z.ZodDefault<z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    registry: z.ZodDefault<z.ZodString>;
+    authToken: z.ZodOptional<z.ZodString>;
+    thresholds: z.ZodDefault<z.ZodObject<{
+      patch: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<false>]>>;
+      minor: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<false>]>>;
+      major: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<false>]>>;
+    }, z.core.$strip>>;
+    enforceOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    cacheTtlMs: z.ZodOptional<z.ZodNumber>;
+    cacheDisabled: z.ZodDefault<z.ZodBoolean>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Config as returned after parsing — all defaults applied, all fields required */
+type HermexConfig = z.infer<typeof HermexConfigSchema>;
+/** Config as accepted by the user — everything optional */
+type HermexConfigInput = z.input<typeof HermexConfigSchema>;
+type RuleSeverity = z.infer<typeof RuleSeveritySchema>;
+type RuleConfig = z.infer<typeof RuleConfigSchema>;
+type PackageFieldRule = z.infer<typeof PackageFieldRuleSchema>;
+type EngineVersionRule = z.infer<typeof EngineVersionRuleSchema>;
+type CodeownersRule = z.infer<typeof CodeownersRuleSchema>;
+type PackagesConfig = HermexConfig['packages'];
+type VersusConfig = HermexConfig['versus'][number];
+type RulesConfig = HermexConfig['rules'];
+type OutputConfig = HermexConfig['output'];
+type ReleaseAgeConfig = HermexConfig['releaseAge'];
+type ReleaseAgeThresholds = HermexConfig['releaseAge']['thresholds'];
+//#endregion
+//#region src/npm-registry/types.d.ts
+type UpgradeLevel = 'needs_upgrade' | 'mandatory_upgrade';
+type SemverBump = 'patch' | 'minor' | 'major';
+interface AvailableUpgrade {
+  version: string;
+  releasedDaysAgo: number;
+  semverBump: SemverBump;
+  level: UpgradeLevel;
+  thresholdDays: number;
+  isLatest?: boolean;
+}
+/** An upgrade candidate that hasn't yet breached its bump tier's age threshold. */
+interface PendingUpgrade {
+  version: string;
+  semverBump: SemverBump;
+  releasedDaysAgo: number;
+  thresholdDays: number;
+  daysRemaining: number;
+}
+interface ReleaseAgeEntry {
+  installedVersion: string;
+  upgrades: AvailableUpgrade[];
+  worstLevel: UpgradeLevel | null;
+  pendingUpgrade?: PendingUpgrade;
+  deprecated?: string;
+  latestVersion?: string;
+  latestReleasedDaysAgo?: number;
+  minCompliantVersion?: string;
+  minCompliantReleasedDaysAgo?: number;
+  severity: 'error' | 'warn';
+}
+//#endregion
+//#region src/utils/package-distribution.d.ts
+interface ComponentUsage {
+  name: string;
+  source: string;
+  count: number;
+  files: Set<string>;
+}
+interface PackageDistribution {
+  packageName: string;
+  version: string | null;
+  componentCount: number;
+  usageCount: number;
+  percentage: number;
+  components: string[];
+  internal: boolean;
+  hasVersionConflict: boolean;
+  allVersions: string[];
+  releaseAge?: ReleaseAgeEntry;
+}
+//#endregion
+//#region src/utils/pattern-counter.d.ts
+interface PatternCount {
+  patternType: string;
+  displayName: string;
+  count: number;
+}
+//#endregion
+//#region src/utils/versus.d.ts
+interface VersusEntry {
+  packageName: string;
+  count: number;
+  percentage: number;
+  components: string[];
+}
+interface VersusResult {
+  name: string;
+  packages: string[];
+  entries: VersusEntry[];
+  totalCount: number;
+}
+//#endregion
+//#region src/rules/shared.d.ts
+interface RuleViolation {
+  type: 'detect_files' | 'require_files' | 'require_packages' | 'require_scripts' | 'require_package_fields' | 'forbid_package_fields' | 'engine_version' | 'codeowners';
+  severity: 'error' | 'warn' | 'info';
+  patterns: string[];
+  message?: string;
+  matchedFiles: string[];
+  installedRange?: string;
+  requiredRange?: string;
+  fieldPath?: string;
+  actualValue?: string;
+}
+//#endregion
+//#region src/utils/package-rules.d.ts
+interface BannedPackageViolation {
+  packageName: string;
+  severity: 'error' | 'warn' | 'info';
+  message?: string;
+}
+//#endregion
+//#region src/index.d.ts
+/**
+ * Identity helper for authoring `hermex.config.ts` with full type inference
+ * and autocomplete — mirrors the same `defineConfig` convention used by
+ * Vite, ESLint's flat config, and Vitest. Returns its argument unchanged;
+ * `loadConfig` (`src/config/loader.ts`) accepts a plain object default
+ * export either way, so this is purely a DX affordance, not a requirement.
+ */
+declare function defineConfig(config: HermexConfigInput): HermexConfigInput;
+/** Shape of a single entry in `components` — same as `ComponentUsage`, but with `files` as an array (JSON has no `Set`) */
+interface HermexScanComponent extends Omit<ComponentUsage, 'files'> {
+  files: string[];
+}
+/** Shape of the JSON emitted by `hermex scan --format json` (see `printJson`) */
+interface HermexScanResult {
+  version: string;
+  summary: {
+    filesAnalyzed: number;
+    totalImports: number;
+    totalComponents: number;
+    totalUsagePatterns: number;
+  };
+  packages: PackageDistribution[];
+  components: HermexScanComponent[];
+  patterns: PatternCount[];
+  versus: VersusResult[];
+  ruleViolations: RuleViolation[];
+  bannedPackageViolations: BannedPackageViolation[];
+}
+//#endregion
+export { type BannedPackageViolation, type CodeownersRule, type ComponentUsage, type EngineVersionRule, type HermexConfig, type HermexConfigInput, HermexScanComponent, HermexScanResult, type OutputConfig, type PackageDistribution, type PackageFieldRule, type PackagesConfig, type PatternCount, type ReleaseAgeConfig, type ReleaseAgeThresholds, type RuleConfig, type RuleSeverity, type RuleViolation, type RulesConfig, type VersusConfig, type VersusEntry, type VersusResult, defineConfig };

package/dist/index.mjs

@@ -0,0 +1,13 @@
+//#region src/index.ts
+/**
+* Identity helper for authoring `hermex.config.ts` with full type inference
+* and autocomplete — mirrors the same `defineConfig` convention used by
+* Vite, ESLint's flat config, and Vitest. Returns its argument unchanged;
+* `loadConfig` (`src/config/loader.ts`) accepts a plain object default
+* export either way, so this is purely a DX affordance, not a requirement.
+*/
+function defineConfig(config) {
+	return config;
+}
+//#endregion
+export { defineConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermex",
-  "version": "1.3.0-beta.4",
+  "version": "2.0.0-beta.10",
   "description": "SWC-based AST parser for analyzing code and React component usage patterns across entire codebases",
   "keywords": [
     "analysis",
@@ -30,7 +30,14 @@
     "LICENSE.md"
   ],
   "type": "module",
-  "main": "./dist/cli.mjs",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
   "scripts": {
     "format": "oxfmt --write",
     "format:ci": "oxfmt --check",
@@ -77,5 +84,10 @@
   },
   "engines": {
     "node": ">=24.11.1"
+  },
+  "pnpm": {
+    "overrides": {
+      "micromatch>picomatch": "^2.3.2"
+    }
   }
 }