@monoes/monograph 1.1.0 → 1.2.0

package/src/config/schema-gen.ts

@@ -0,0 +1,115 @@
+export interface JSONSchemaProperty {
+  type?: string | string[];
+  description?: string;
+  items?: JSONSchemaProperty;
+  properties?: Record<string, JSONSchemaProperty>;
+  enum?: unknown[];
+  minimum?: number;
+  maximum?: number;
+  default?: unknown;
+  additionalProperties?: boolean | JSONSchemaProperty;
+  required?: string[];
+  '$ref'?: string;
+}
+
+export interface JSONSchema {
+  '$schema': string;
+  '$id': string;
+  title: string;
+  description: string;
+  type: 'object';
+  properties: Record<string, JSONSchemaProperty>;
+  additionalProperties: boolean;
+}
+
+export function generateConfigSchema(): JSONSchema {
+  return {
+    '$schema': 'http://json-schema.org/draft-07/schema#',
+    '$id': 'https://monograph.dev/config.schema.json',
+    title: 'Monograph Configuration',
+    description: 'Configuration file for @monoes/monograph code intelligence',
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      entryPoints: {
+        type: 'array', items: { type: 'string' },
+        description: 'Glob patterns for project entry point files',
+      },
+      include: {
+        type: 'array', items: { type: 'string' },
+        description: 'Glob patterns to include in analysis',
+      },
+      exclude: {
+        type: 'array', items: { type: 'string' },
+        description: 'Glob patterns to exclude from analysis',
+      },
+      ignorePatterns: {
+        type: 'array', items: { type: 'string' },
+        description: 'Additional ignore patterns (alongside .gitignore)',
+      },
+      sealed: {
+        type: 'boolean', default: false,
+        description: 'When true, child workspace configs cannot override root settings',
+      },
+      includeEntryExports: {
+        type: 'boolean', default: false,
+        description: 'Report unused exports in entry point files (catches framework typos)',
+      },
+      failOnError: {
+        type: 'boolean', default: false,
+        description: 'Exit with non-zero status when any errors are found',
+      },
+      outputFormat: {
+        type: 'string', enum: ['json', 'sarif', 'codeclimate', 'compact', 'markdown'],
+        description: 'Default output format',
+      },
+      boundaries: {
+        type: 'object',
+        additionalProperties: { type: 'array', items: { type: 'string' } },
+        description: 'Zone-to-allowed-zones mapping for architectural boundary enforcement',
+      },
+      regression: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          baseline: { type: 'object', additionalProperties: { type: 'number' } },
+          tolerance: { type: 'string', description: 'e.g. "5" (absolute) or "2%" (percentage)' },
+          failOnRegression: { type: 'boolean', default: false },
+        },
+        description: 'Regression detection against a saved baseline',
+      },
+      health: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          enabled: { type: 'boolean', default: true },
+          minScore: { type: 'number', minimum: 0, maximum: 100, description: 'CI gate: fail when score < minScore' },
+          effort: { type: 'string', enum: ['low', 'medium', 'high'], default: 'medium' },
+          suggestInlineSuppression: { type: 'boolean', default: true },
+          ownership: {
+            type: 'object', additionalProperties: false,
+            properties: {
+              emailMode: { type: 'string', enum: ['raw', 'handle', 'hash'], default: 'handle' },
+              botPatterns: {
+                type: 'array', items: { type: 'string' },
+                default: ['*[bot]*', 'dependabot*', 'renovate*', 'github-actions*', 'svc-*'],
+                description: 'Glob patterns to exclude from ownership metrics',
+              },
+            },
+          },
+        },
+      },
+      flags: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          enabled: { type: 'boolean', default: false },
+          envPrefixes: { type: 'array', items: { type: 'string' } },
+          sdkPatterns: { type: 'array', items: { type: 'string' } },
+        },
+        description: 'Feature flag detection configuration',
+      },
+    },
+  };
+}
+
+export function schemaToJson(schema: JSONSchema): string {
+  return JSON.stringify(schema, null, 2);
+}

package/src/config/types.ts

@@ -0,0 +1,149 @@
+// Complete monograph configuration schema — all config structs for
+// constructing a resolved config from disk and validating config files.
+
+export type ProductionAnalysis = 'files' | 'exports';
+
+export interface PerAnalysisProductionConfig {
+  files?: boolean;
+  exports?: boolean;
+}
+
+export type ProductionConfigValue = boolean | PerAnalysisProductionConfig;
+
+export interface RegressionConfig {
+  tolerance?: number;
+  baselinePath?: string;
+}
+
+export interface AuditConfig {
+  gate?: 'error' | 'warn' | 'off';
+  includeHealthGate?: boolean;
+}
+
+export type DetectionMode = 'default' | 'aggressive' | 'lenient';
+
+export interface NormalizationConfig {
+  stripComments?: boolean;
+  normalizeWhitespace?: boolean;
+  normalizeIdentifiers?: boolean;
+}
+
+export interface BoundaryRule {
+  from: string | string[];
+  to: string | string[];
+  tag?: string;
+}
+
+export interface BoundaryZone {
+  name: string;
+  pattern: string | string[];
+  rules?: BoundaryRule[];
+}
+
+export interface BoundaryConfig {
+  preset?: 'domain-driven' | 'layered' | 'none';
+  zones?: BoundaryZone[];
+  rules?: BoundaryRule[];
+}
+
+export interface ResolveConfig {
+  paths?: Record<string, string[]>;
+  alias?: Record<string, string>;
+  conditions?: string[];
+  extensions?: string[];
+}
+
+export interface HealthConfig {
+  cyclomaticThreshold?: number;
+  cognitiveThreshold?: number;
+  crapThreshold?: number;
+  minLines?: number;
+}
+
+export interface OwnershipConfig {
+  codeownersPath?: string;
+  emailMode?: 'fullEmail' | 'domainEmail' | 'displayName';
+}
+
+export interface IgnoreExportRule {
+  pattern: string;
+  reason?: string;
+}
+
+export interface ConfigOverride {
+  files?: string[];
+  ignore?: IgnoreExportRule[];
+  production?: ProductionConfigValue;
+}
+
+export interface MonographConfig {
+  root?: string;
+  entry?: string | string[];
+  project?: string;
+  production?: ProductionConfigValue;
+  ignore?: IgnoreExportRule[];
+  overrides?: ConfigOverride[];
+  regression?: RegressionConfig;
+  audit?: AuditConfig;
+  detection?: DetectionMode;
+  normalization?: NormalizationConfig;
+  boundaries?: BoundaryConfig;
+  resolve?: ResolveConfig;
+  health?: HealthConfig;
+  ownership?: OwnershipConfig;
+  plugins?: string[];
+}
+
+export interface ResolvedMonographConfig extends Required<Pick<MonographConfig, 'root' | 'entry' | 'production' | 'detection'>> {
+  project: string | undefined;
+  ignore: IgnoreExportRule[];
+  overrides: ConfigOverride[];
+  regression: Required<RegressionConfig>;
+  audit: Required<AuditConfig>;
+  normalization: Required<NormalizationConfig>;
+  boundaries: BoundaryConfig;
+  resolve: Required<ResolveConfig>;
+  health: Required<HealthConfig>;
+  ownership: Required<OwnershipConfig>;
+  plugins: string[];
+}
+
+export const DEFAULT_MONOGRAPH_CONFIG: ResolvedMonographConfig = {
+  root: '.',
+  entry: [],
+  production: true,
+  detection: 'default',
+  project: undefined,
+  ignore: [],
+  overrides: [],
+  regression: { tolerance: 0, baselinePath: '.monograph/regression-baseline.json' },
+  audit: { gate: 'error', includeHealthGate: false },
+  normalization: { stripComments: true, normalizeWhitespace: true, normalizeIdentifiers: false },
+  boundaries: {},
+  resolve: { paths: {}, alias: {}, conditions: [], extensions: ['.ts', '.tsx', '.mts', '.cts'] },
+  health: { cyclomaticThreshold: 10, cognitiveThreshold: 15, crapThreshold: 30, minLines: 5 },
+  ownership: { emailMode: 'fullEmail', codeownersPath: 'CODEOWNERS' },
+  plugins: [],
+};
+
+// ── Round 10: extended MonographConfig fields ──────────────────────────────────
+
+export interface ExtendedMonographConfig extends MonographConfig {
+  extends?: string[];
+  sealed?: boolean;
+  includeEntryExports?: boolean;
+  publicPackages?: string[];
+  dynamicallyLoaded?: string[];
+  codeowners?: string;
+  ignoreDependencies?: string[];
+  ignoreExportsUsedInFile?: boolean | { interface?: boolean; typeAlias?: boolean };
+  usedClassMembers?: Array<string | { extends?: string[]; implements?: string[]; members: string[] }>;
+  duplicates?: {
+    enabled?: boolean;
+    mode?: 'strict' | 'mild' | 'weak' | 'semantic';
+    minTokens?: number;
+    minLines?: number;
+    crossLanguage?: boolean;
+    ignoreImports?: boolean;
+  };
+}

package/src/config/used-class-members.ts

@@ -0,0 +1,53 @@
+// Configuration types for suppressing unused-class-member findings.
+
+export type UsedClassMemberRuleKind = 'name' | 'scoped';
+
+export interface ScopedUsedClassMemberRule {
+  extends?: string[];
+  implements?: string[];
+  members: string[];
+}
+
+export type UsedClassMemberRule =
+  | { kind: 'name'; pattern: string }
+  | { kind: 'scoped'; rule: ScopedUsedClassMemberRule };
+
+export function nameRule(pattern: string): UsedClassMemberRule {
+  return { kind: 'name', pattern };
+}
+
+export function scopedRule(rule: ScopedUsedClassMemberRule): UsedClassMemberRule {
+  return { kind: 'scoped', rule };
+}
+
+export function matchesHeritage(
+  rule: ScopedUsedClassMemberRule,
+  classExtends: string[],
+  classImplements: string[],
+): boolean {
+  const extendsMatch = !rule.extends?.length || rule.extends.some(e => classExtends.includes(e));
+  const implMatch = !rule.implements?.length || rule.implements.some(i => classImplements.includes(i));
+  return extendsMatch && implMatch;
+}
+
+export function isMemberSuppressed(
+  rules: UsedClassMemberRule[],
+  memberName: string,
+  classExtends: string[] = [],
+  classImplements: string[] = [],
+): boolean {
+  for (const rule of rules) {
+    if (rule.kind === 'name') {
+      if (memberName === rule.pattern || memberMatchesGlob(memberName, rule.pattern)) return true;
+    } else {
+      if (matchesHeritage(rule.rule, classExtends, classImplements) && rule.rule.members.includes(memberName)) return true;
+    }
+  }
+  return false;
+}
+
+function memberMatchesGlob(name: string, pattern: string): boolean {
+  if (!pattern.includes('*')) return name === pattern;
+  const re = new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*') + '$');
+  return re.test(name);
+}

package/src/config/validate.ts

@@ -0,0 +1,108 @@
+import { readFileSync, existsSync } from 'fs';
+
+export interface ValidationError {
+  field: string;
+  message: string;
+  line?: number;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}
+
+const KNOWN_TOP_LEVEL_FIELDS = new Set([
+  'entryPoints', 'include', 'exclude', 'ignorePatterns', 'boundaries', 'workspaces',
+  'regression', 'health', 'flags', 'coverage', 'suppressions',
+  'outputFormat', 'maxIssues', 'failOnError', 'sealed', 'includeEntryExports',
+]);
+
+const KNOWN_HEALTH_FIELDS = new Set([
+  'enabled', 'minScore', 'effort', 'ownership', 'suggestInlineSuppression',
+]);
+
+const KNOWN_REGRESSION_FIELDS = new Set([
+  'baseline', 'tolerance', 'failOnRegression',
+]);
+
+function stripJsonComments(text: string): string {
+  return text.replace(/\/\/[^\n]*/g, '').replace(/\/\*[\s\S]*?\*\//g, '');
+}
+
+function validateBoundaries(boundaries: unknown, errors: ValidationError[]): void {
+  if (!boundaries || typeof boundaries !== 'object' || Array.isArray(boundaries)) {
+    errors.push({ field: 'boundaries', message: 'must be an object mapping zone names to arrays of allowed zones' });
+    return;
+  }
+  for (const [zone, allowed] of Object.entries(boundaries as Record<string, unknown>)) {
+    if (!Array.isArray(allowed) || !allowed.every(v => typeof v === 'string')) {
+      errors.push({ field: `boundaries.${zone}`, message: 'must be an array of zone name strings' });
+    }
+  }
+}
+
+export function validateConfig(configPath: string): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationError[] = [];
+
+  if (!existsSync(configPath)) {
+    return { valid: false, errors: [{ field: '', message: `Config file not found: ${configPath}` }], warnings };
+  }
+
+  let raw: string;
+  try { raw = readFileSync(configPath, 'utf8'); }
+  catch (err) { return { valid: false, errors: [{ field: '', message: `Cannot read file: ${err}` }], warnings }; }
+
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(stripJsonComments(raw));
+  } catch (err) {
+    return { valid: false, errors: [{ field: '', message: `JSON parse error: ${err}` }], warnings };
+  }
+
+  // Unknown top-level fields
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_TOP_LEVEL_FIELDS.has(key)) {
+      warnings.push({ field: key, message: `Unknown field '${key}' — will be ignored` });
+    }
+  }
+
+  // entryPoints
+  if ('entryPoints' in parsed) {
+    const ep = parsed['entryPoints'];
+    if (!Array.isArray(ep) || !ep.every(v => typeof v === 'string')) {
+      errors.push({ field: 'entryPoints', message: 'must be an array of glob strings' });
+    }
+  }
+
+  // boundaries
+  if ('boundaries' in parsed) validateBoundaries(parsed['boundaries'], errors);
+
+  // health sub-config
+  if ('health' in parsed && parsed['health'] && typeof parsed['health'] === 'object') {
+    for (const key of Object.keys(parsed['health'] as object)) {
+      if (!KNOWN_HEALTH_FIELDS.has(key)) {
+        warnings.push({ field: `health.${key}`, message: `Unknown health field '${key}'` });
+      }
+    }
+    const health = parsed['health'] as Record<string, unknown>;
+    if ('minScore' in health && (typeof health['minScore'] !== 'number' || health['minScore'] < 0 || health['minScore'] > 100)) {
+      errors.push({ field: 'health.minScore', message: 'must be a number between 0 and 100' });
+    }
+    if ('effort' in health && !['low', 'medium', 'high'].includes(health['effort'] as string)) {
+      errors.push({ field: 'health.effort', message: 'must be one of: low, medium, high' });
+    }
+  }
+
+  // regression sub-config
+  if ('regression' in parsed && parsed['regression'] && typeof parsed['regression'] === 'object') {
+    for (const key of Object.keys(parsed['regression'] as object)) {
+      if (!KNOWN_REGRESSION_FIELDS.has(key)) {
+        warnings.push({ field: `regression.${key}`, message: `Unknown regression field '${key}'` });
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/config/workspace.ts

@@ -0,0 +1,137 @@
+// Discovers monorepo workspace packages, detects undeclared workspaces,
+// and parses tsconfig rootDir.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export interface WorkspaceInfo {
+  name: string;
+  rootPath: string;
+  packageJson: Record<string, unknown>;
+}
+
+export interface WorkspaceDiagnostic {
+  kind: 'undeclaredWorkspace' | 'missingPackageJson' | 'parseError';
+  message: string;
+  path: string;
+}
+
+export interface WorkspaceConfig {
+  root: string;
+  patterns: string[];
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+export function discoverWorkspaces(root: string): WorkspaceInfo[] {
+  const pkgPath = join(root, 'package.json');
+  const pkg = readJson(pkgPath);
+  if (!pkg) return [];
+
+  const patterns: string[] = [];
+  if (Array.isArray(pkg['workspaces'])) {
+    patterns.push(...(pkg['workspaces'] as string[]));
+  } else if (typeof pkg['workspaces'] === 'object' && pkg['workspaces'] !== null) {
+    const ws = pkg['workspaces'] as Record<string, unknown>;
+    if (Array.isArray(ws['packages'])) patterns.push(...(ws['packages'] as string[]));
+  }
+
+  const results: WorkspaceInfo[] = [];
+  for (const pattern of patterns) {
+    const base = pattern.replace(/\/\*$/, '');
+    const dir = resolve(root, base);
+    if (!existsSync(dir)) continue;
+    try {
+      const entries = readdirSync(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const wsPkgPath = join(dir, entry.name, 'package.json');
+        const wsPkg = readJson(wsPkgPath);
+        if (!wsPkg) continue;
+        results.push({
+          name: (wsPkg['name'] as string | undefined) ?? entry.name,
+          rootPath: resolve(dir, entry.name),
+          packageJson: wsPkg,
+        });
+      }
+    } catch { /* skip unreadable dirs */ }
+  }
+  return results;
+}
+
+export function findUndeclaredWorkspaces(
+  root: string,
+  declared: WorkspaceInfo[],
+  ignores: string[] = [],
+): WorkspaceDiagnostic[] {
+  const declaredPaths = new Set(declared.map(w => resolve(w.rootPath)));
+  const diagnostics: WorkspaceDiagnostic[] = [];
+  const packagesDir = join(root, 'packages');
+
+  if (!existsSync(packagesDir)) return diagnostics;
+
+  try {
+    const entries = readdirSync(packagesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (ignores.includes(entry.name)) continue;
+      const candidate = resolve(packagesDir, entry.name);
+      if (declaredPaths.has(candidate)) continue;
+      const hasPkg = existsSync(join(candidate, 'package.json'));
+      if (hasPkg) {
+        diagnostics.push({
+          kind: 'undeclaredWorkspace',
+          message: `Directory "${entry.name}" has package.json but is not in workspaces`,
+          path: candidate,
+        });
+      }
+    }
+  } catch { /* skip */ }
+
+  return diagnostics;
+}
+
+export function parseTsconfigRootDir(tsconfigPath: string): string | null {
+  const json = readJson(tsconfigPath);
+  if (!json) return null;
+  const co = (json['compilerOptions'] as Record<string, unknown> | undefined);
+  const rootDir = co?.['rootDir'];
+  return typeof rootDir === 'string' ? rootDir : null;
+}
+
+// ── Round 10: enhanced undeclared workspace detection ─────────────────────────
+
+export interface EnhancedWorkspaceDiagnostic extends WorkspaceDiagnostic {
+  suggestion: string;
+}
+
+export function findUndeclaredWorkspacesEnhanced(
+  root: string,
+  declared: WorkspaceInfo[],
+  ignores: string[] = [],
+): EnhancedWorkspaceDiagnostic[] {
+  const basic = findUndeclaredWorkspaces(root, declared, ignores);
+  return basic.map(d => ({
+    ...d,
+    suggestion: `Add "${d.path.replace(root, '').replace(/^\//, '')}" to the workspaces array in package.json`,
+  }));
+}
+
+export function validateWorkspaceDeclarations(
+  declared: WorkspaceInfo[],
+  root: string,
+): WorkspaceDiagnostic[] {
+  const diagnostics: WorkspaceDiagnostic[] = [];
+  for (const ws of declared) {
+    if (!ws.packageJson['name']) {
+      diagnostics.push({ kind: 'missingPackageJson', message: `Workspace at "${ws.rootPath.replace(root, '')}" has no name field`, path: ws.rootPath });
+    }
+  }
+  return diagnostics;
+}

package/src/coverage/cloud-client.ts

@@ -0,0 +1,111 @@
+// Types and stub for fetching production runtime coverage from a remote API.
+
+export type CloudRuntimeRiskBand = 'hot' | 'warm' | 'cold' | 'unknown';
+export type CloudTrackingState = 'tracked' | 'untracked' | 'partial';
+export type CloudRuntimeWarning = 'low_traffic' | 'short_window' | 'partial_coverage';
+
+export interface CloudRuntimeBlastRadiusEntry {
+  callerName: string;
+  callerFile: string;
+  callerLine: number;
+  trafficWeight: number;
+}
+
+export interface CloudRuntimeImportanceEntry {
+  name: string;
+  filePath: string;
+  importanceScore: number;
+}
+
+export interface CloudRuntimeFunction {
+  name: string;
+  filePath: string;
+  startLine: number;
+  hitCount: number;
+  riskBand: CloudRuntimeRiskBand;
+  importanceScore: number;
+  blastRadius: CloudRuntimeBlastRadiusEntry[];
+}
+
+export interface CloudRuntimeSummary {
+  totalFunctions: number;
+  hotFunctions: number;
+  coldFunctions: number;
+  unknownFunctions: number;
+  observationWindowDays: number;
+  trackingState: CloudTrackingState;
+  warnings: CloudRuntimeWarning[];
+}
+
+export interface CloudRuntimeContext {
+  projectId: string;
+  environment: string;
+  commitSha?: string;
+  period: string;
+  summary: CloudRuntimeSummary;
+  functions: CloudRuntimeFunction[];
+  importanceEntries: CloudRuntimeImportanceEntry[];
+}
+
+export type CloudErrorKind =
+  | 'AuthError'
+  | 'TierRequired'
+  | 'NetworkError'
+  | 'ValidationError'
+  | 'NotFound'
+  | 'RateLimited';
+
+export interface CloudError {
+  kind: CloudErrorKind;
+  message: string;
+  exitCode: number;
+}
+
+export interface CloudRequest {
+  projectId: string;
+  environment?: string;
+  commitSha?: string;
+  period?: string;
+  apiKey?: string;
+  apiBase?: string;
+}
+
+/** Build the URL for a cloud runtime context request. */
+export function buildCloudRequestUrl(base: string, req: CloudRequest): string {
+  const params = new URLSearchParams();
+  if (req.environment) params.set('environment', req.environment);
+  if (req.commitSha) params.set('commit_sha', req.commitSha);
+  if (req.period) params.set('period', req.period);
+  const qs = params.toString();
+  const encoded = encodeURIComponent(req.projectId);
+  return `${base}/projects/${encoded}/runtime-context${qs ? '?' + qs : ''}`;
+}
+
+/** Fetch runtime coverage context from the cloud API (stub — real impl requires HTTP client). */
+export async function fetchRuntimeContext(
+  req: CloudRequest,
+): Promise<CloudRuntimeContext | CloudError> {
+  const base = req.apiBase ?? 'https://api.fallow.cloud/v1';
+  const url = buildCloudRequestUrl(base, req);
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      headers: {
+        Authorization: `Bearer ${req.apiKey ?? ''}`,
+        Accept: 'application/json',
+      },
+    });
+  } catch (e) {
+    return { kind: 'NetworkError', message: String(e), exitCode: 3 };
+  }
+  if (res.status === 401) return { kind: 'AuthError', message: 'Invalid API key', exitCode: 4 };
+  if (res.status === 402) return { kind: 'TierRequired', message: 'Feature requires paid tier', exitCode: 5 };
+  if (res.status === 429) return { kind: 'RateLimited', message: 'Rate limit exceeded', exitCode: 6 };
+  if (res.status === 404) return { kind: 'NotFound', message: `Project ${req.projectId} not found`, exitCode: 7 };
+  if (!res.ok) return { kind: 'ValidationError', message: `HTTP ${res.status}`, exitCode: 8 };
+  return (await res.json()) as CloudRuntimeContext;
+}
+
+export function isCloudError(v: CloudRuntimeContext | CloudError): v is CloudError {
+  return (v as CloudError).kind !== undefined && (v as CloudError).exitCode !== undefined;
+}