@monoes/monograph 1.1.0 → 1.2.0

package/src/config/config-parsing.ts

@@ -0,0 +1,102 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export type ConfigFormat = 'json' | 'jsonc' | 'toml';
+
+export const CONFIG_NAMES = [
+  '.monographrc.json',
+  '.monographrc.jsonc',
+  'monograph.toml',
+  '.monograph.toml',
+  'monograph.json',
+  'monograph.config.json',
+] as const;
+
+export function detectConfigFormat(filePath: string): ConfigFormat {
+  const ext = filePath.split('.').pop()?.toLowerCase();
+  if (ext === 'json') return 'json';
+  if (ext === 'jsonc') return 'jsonc';
+  return 'toml';
+}
+
+function isRepoRoot(dir: string): boolean {
+  return existsSync(resolve(dir, '.git'))
+    || existsSync(resolve(dir, '.hg'))
+    || existsSync(resolve(dir, '.svn'));
+}
+
+export function findConfigFile(startDir: string): string | undefined {
+  let dir = startDir;
+  const visited = new Set<string>();
+  while (true) {
+    if (visited.has(dir)) break;
+    visited.add(dir);
+    for (const name of CONFIG_NAMES) {
+      const candidate = resolve(dir, name);
+      if (existsSync(candidate)) return candidate;
+    }
+    if (isRepoRoot(dir)) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return undefined;
+}
+
+export function detectSourceRoot(projectRoot: string): string {
+  for (const candidate of ['src', 'lib', 'app', 'source']) {
+    if (existsSync(resolve(projectRoot, candidate))) return candidate;
+  }
+  return 'src';
+}
+
+function stripJsoncComments(text: string): string {
+  let result = '';
+  let i = 0;
+  let inString = false;
+  while (i < text.length) {
+    if (inString) {
+      if (text[i] === '\\') {
+        result += text[i] + (text[i + 1] ?? '');
+        i += 2;
+        continue;
+      }
+      if (text[i] === '"') inString = false;
+      result += text[i++];
+    } else if (text[i] === '"') {
+      inString = true;
+      result += text[i++];
+    } else if (text[i] === '/' && text[i + 1] === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (text[i] === '/' && text[i + 1] === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i += 2;
+    } else {
+      result += text[i++];
+    }
+  }
+  return result;
+}
+
+export function parseConfigFile(filePath: string): Record<string, unknown> {
+  const content = readFileSync(filePath, 'utf8');
+  const format = detectConfigFormat(filePath);
+
+  if (format === 'toml') {
+    throw new Error(
+      `TOML config files are not supported without a TOML parser dependency. ` +
+      `Convert ${filePath} to JSON format instead.`
+    );
+  }
+
+  const stripped = format === 'jsonc' ? stripJsoncComments(content) : content;
+  return JSON.parse(stripped) as Record<string, unknown>;
+}
+
+export function loadConfigFromDir(dir: string): { config: Record<string, unknown>; configPath: string } | undefined {
+  const configPath = findConfigFile(dir);
+  if (!configPath) return undefined;
+  const config = parseConfigFile(configPath);
+  return { config, configPath };
+}

package/src/config/duplicates-config.ts

@@ -0,0 +1,62 @@
+// Full duplication detection configuration block.
+
+export type DuplicationDetectionMode = 'strict' | 'mild' | 'weak' | 'semantic';
+
+export interface DuplicationNormalizationConfig {
+  ignoreIdentifiers: boolean;
+  ignoreStringValues: boolean;
+  ignoreNumericValues: boolean;
+}
+
+export interface DuplicatesConfig {
+  enabled: boolean;
+  mode: DuplicationDetectionMode;
+  minTokens: number;
+  minLines: number;
+  threshold: number;
+  ignore: string[];
+  ignoreDefaults: boolean;
+  skipLocal: boolean;
+  crossLanguage: boolean;
+  ignoreImports: boolean;
+  normalization: DuplicationNormalizationConfig;
+  minCorpusSizeForShingleFilter: number;
+  minCorpusSizeForTokenCache: number;
+}
+
+export const DEFAULT_DUPLICATES_CONFIG: DuplicatesConfig = {
+  enabled: true,
+  mode: 'mild',
+  minTokens: 50,
+  minLines: 5,
+  threshold: 0.9,
+  ignore: [],
+  ignoreDefaults: false,
+  skipLocal: false,
+  crossLanguage: false,
+  ignoreImports: false,
+  normalization: {
+    ignoreIdentifiers: false,
+    ignoreStringValues: false,
+    ignoreNumericValues: false,
+  },
+  minCorpusSizeForShingleFilter: 1000,
+  minCorpusSizeForTokenCache: 5000,
+};
+
+export function mergeDuplicatesConfig(
+  base: DuplicatesConfig,
+  partial: Partial<DuplicatesConfig>,
+): DuplicatesConfig {
+  return {
+    ...base,
+    ...partial,
+    normalization: partial.normalization
+      ? { ...base.normalization, ...partial.normalization }
+      : base.normalization,
+  };
+}
+
+export function isDuplicationEnabled(config: DuplicatesConfig): boolean {
+  return config.enabled;
+}

package/src/config/external-plugin.ts

@@ -0,0 +1,77 @@
+// Loads and discovers external monograph plugins from node_modules.
+// External plugins declare entry points and used exports to suppress false positives.
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export type EntryPointRole = 'productionSource' | 'testSource' | 'entryPoint' | 'configFile';
+
+export interface ExternalUsedExport {
+  symbol: string;
+  scopeOverride?: string;
+}
+
+export interface ExternalEntryPoint {
+  pattern: string;
+  role: EntryPointRole;
+}
+
+export interface ExternalPluginDef {
+  name: string;
+  version: string;
+  entryPoints: ExternalEntryPoint[];
+  usedExports: ExternalUsedExport[];
+  suppressPatterns: string[];
+}
+
+export const PLUGIN_MANIFEST_KEY = 'monograph-plugin';
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function discoverExternalPlugins(root: string): ExternalPluginDef[] {
+  const nmDir = join(root, 'node_modules');
+  if (!existsSync(nmDir)) return [];
+
+  const plugins: ExternalPluginDef[] = [];
+
+  try {
+    const entries = readdirSync(nmDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const pkgPath = join(nmDir, entry.name, 'package.json');
+      const pkg = readJson(pkgPath);
+      if (!pkg) continue;
+
+      const manifest = pkg[PLUGIN_MANIFEST_KEY];
+      if (!manifest || typeof manifest !== 'object') continue;
+
+      const m = manifest as Record<string, unknown>;
+      plugins.push({
+        name: (pkg['name'] as string | undefined) ?? entry.name,
+        version: (pkg['version'] as string | undefined) ?? '0.0.0',
+        entryPoints: (m['entryPoints'] as ExternalEntryPoint[] | undefined) ?? [],
+        usedExports: (m['usedExports'] as ExternalUsedExport[] | undefined) ?? [],
+        suppressPatterns: (m['suppressPatterns'] as string[] | undefined) ?? [],
+      });
+    }
+  } catch { /* skip */ }
+
+  return plugins;
+}
+
+export function mergePluginSuppressPatterns(plugins: ExternalPluginDef[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const p of plugins) {
+    for (const pat of p.suppressPatterns) {
+      if (!seen.has(pat)) { seen.add(pat); result.push(pat); }
+    }
+  }
+  return result;
+}

package/src/config/health-config.ts

@@ -0,0 +1,42 @@
+export type FallowEmailMode = 'raw' | 'handle' | 'hash';
+
+export interface FallowOwnershipConfig {
+  botPatterns: string[];
+  emailMode: FallowEmailMode;
+}
+
+export interface FallowHealthConfig {
+  maxCyclomatic: number;
+  maxCognitive: number;
+  maxCrap: number;
+  ignore: string[];
+  ownership: FallowOwnershipConfig;
+  suggestInlineSuppression: boolean;
+}
+
+export const DEFAULT_BOT_PATTERNS: string[] = [
+  '*[bot]*', 'dependabot*', 'renovate*', 'github-actions*', 'svc-*', '*-service-account*',
+];
+
+export const DEFAULT_FALLOW_HEALTH_CONFIG: FallowHealthConfig = {
+  maxCyclomatic: 20,
+  maxCognitive: 15,
+  maxCrap: 30.0,
+  ignore: [],
+  ownership: { botPatterns: DEFAULT_BOT_PATTERNS, emailMode: 'raw' },
+  suggestInlineSuppression: false,
+};
+
+export function mergeFallowHealthConfig(partial: Partial<FallowHealthConfig>): FallowHealthConfig {
+  const base = DEFAULT_FALLOW_HEALTH_CONFIG;
+  return {
+    maxCyclomatic: partial.maxCyclomatic ?? base.maxCyclomatic,
+    maxCognitive: partial.maxCognitive ?? base.maxCognitive,
+    maxCrap: partial.maxCrap ?? base.maxCrap,
+    ignore: partial.ignore ?? base.ignore,
+    suggestInlineSuppression: partial.suggestInlineSuppression ?? base.suggestInlineSuppression,
+    ownership: partial.ownership !== undefined
+      ? { ...base.ownership, ...partial.ownership }
+      : base.ownership,
+  };
+}

package/src/config/ignore-exports-used-in-file.ts

@@ -0,0 +1,46 @@
+// Three-state control for suppressing unused-export findings when an export
+// is also referenced in the file that declares it.
+
+export interface IgnoreExportsUsedInFileByKind {
+  interface: boolean;
+  typeAlias: boolean;
+}
+
+export type IgnoreExportsUsedInFileConfig =
+  | { kind: 'disabled' }
+  | { kind: 'enabled' }
+  | { kind: 'byKind'; byKind: IgnoreExportsUsedInFileByKind };
+
+export const IGNORE_EXPORTS_DISABLED: IgnoreExportsUsedInFileConfig = { kind: 'disabled' };
+export const IGNORE_EXPORTS_ENABLED: IgnoreExportsUsedInFileConfig = { kind: 'enabled' };
+
+export function ignoreExportsByKind(byKind: IgnoreExportsUsedInFileByKind): IgnoreExportsUsedInFileConfig {
+  return { kind: 'byKind', byKind };
+}
+
+export function isIgnoreExportsEnabled(config: IgnoreExportsUsedInFileConfig): boolean {
+  return config.kind !== 'disabled';
+}
+
+export function suppressesExport(
+  config: IgnoreExportsUsedInFileConfig,
+  isTypeOnly: boolean,
+): boolean {
+  if (config.kind === 'disabled') return false;
+  if (config.kind === 'enabled') return true;
+  if (isTypeOnly) return config.byKind.interface || config.byKind.typeAlias;
+  return false;
+}
+
+export function parseIgnoreExportsConfig(raw: unknown): IgnoreExportsUsedInFileConfig {
+  if (raw === false || raw === null || raw === undefined) return IGNORE_EXPORTS_DISABLED;
+  if (raw === true) return IGNORE_EXPORTS_ENABLED;
+  if (typeof raw === 'object') {
+    const obj = raw as Record<string, unknown>;
+    return ignoreExportsByKind({
+      interface: Boolean(obj['interface']),
+      typeAlias: Boolean(obj['typeAlias'] ?? obj['type_alias']),
+    });
+  }
+  return IGNORE_EXPORTS_DISABLED;
+}

package/src/config/migration-types.ts

@@ -0,0 +1,73 @@
+export interface MigrationWarning {
+  source: string;
+  field: string;
+  message: string;
+  suggestion?: string;
+}
+
+export interface MigrationResult<T = unknown> {
+  config: T;
+  warnings: MigrationWarning[];
+  sources: string[];
+}
+
+export type MigrationSourceKind = 'knip' | 'jscpd' | 'fallow' | 'auto';
+
+export interface MigrationSource {
+  kind: MigrationSourceKind;
+  filePath: string;
+}
+
+export const KNIP_CONFIG_FILENAMES = [
+  'knip.json',
+  'knip.jsonc',
+  '.knip.json',
+  '.knip.jsonc',
+  'knip.ts',
+  'knip.js',
+  'knip.config.ts',
+  'knip.config.js',
+] as const;
+
+export const JSCPD_CONFIG_FILENAMES = [
+  '.jscpd.json',
+  '.jscpd.yaml',
+  '.jscpd.yml',
+] as const;
+
+export const KNOWN_KNIP_FIELDS = new Set([
+  'entry', 'project', 'ignore', 'ignoreBinaries', 'ignoreDependencies', 'ignoreExportsUsedInFile',
+  'rules', 'plugins', 'workspaces', 'paths', 'typescript', 'tags',
+]);
+
+export const KNOWN_JSCPD_FIELDS = new Set([
+  'threshold', 'minLines', 'minTokens', 'format', 'ignore', 'path', 'reporters',
+  'output', 'blame', 'silent', 'absolute', 'gitignore', 'maxLines', 'maxSize',
+]);
+
+export function detectMigrationSource(dirPath: string, files: string[]): MigrationSource | null {
+  for (const filename of KNIP_CONFIG_FILENAMES) {
+    if (files.includes(filename)) {
+      return { kind: 'knip', filePath: `${dirPath}/${filename}` };
+    }
+  }
+  for (const filename of JSCPD_CONFIG_FILENAMES) {
+    if (files.includes(filename)) {
+      return { kind: 'jscpd', filePath: `${dirPath}/${filename}` };
+    }
+  }
+  return null;
+}
+
+export function makeMigrationWarning(
+  source: string,
+  field: string,
+  message: string,
+  suggestion?: string,
+): MigrationWarning {
+  return { source, field, message, suggestion };
+}
+
+export function migrationSuccess<T>(config: T, sources: string[], warnings: MigrationWarning[] = []): MigrationResult<T> {
+  return { config, warnings, sources };
+}

package/src/config/output-format.ts

@@ -0,0 +1,24 @@
+export type FallowOutputFormat = 'human' | 'json' | 'sarif' | 'compact' | 'markdown' | 'code-climate' | 'badge';
+
+export const DEFAULT_OUTPUT_FORMAT: FallowOutputFormat = 'human';
+
+const VALID_FORMATS = new Set<string>([
+  'human', 'json', 'sarif', 'compact', 'markdown', 'code-climate', 'badge',
+]);
+
+const FORMAT_ALIASES: Record<string, FallowOutputFormat> = {
+  codeclimate: 'code-climate',
+  'gitlab-codequality': 'code-climate',
+  'gitlab-code-quality': 'code-climate',
+};
+
+export function parseFallowOutputFormat(s: string): FallowOutputFormat | undefined {
+  const normalized = s.toLowerCase();
+  if (VALID_FORMATS.has(normalized)) return normalized as FallowOutputFormat;
+  if (normalized in FORMAT_ALIASES) return FORMAT_ALIASES[normalized];
+  return undefined;
+}
+
+export function isFallowOutputFormat(s: string): s is FallowOutputFormat {
+  return VALID_FORMATS.has(s.toLowerCase());
+}