@monoes/monograph 1.5.6 → 1.5.8

package/src/cli/skill-gen.ts

@@ -1,347 +0,0 @@
-/**
- * Skill File Generator
- *
- * Generates per-community skill/context files that describe a code community's
- * purpose, top symbols, and relationships. These files help AI agents navigate
- * large codebases by providing curated summaries per architectural boundary.
- */
-
-import fs from 'fs/promises';
-import path from 'path';
-import { openDb, closeDb } from '../storage/db.js';
-
-// ============================================================================
-// TYPES
-// ============================================================================
-
-export interface SkillGenResult {
-  filesWritten: string[];
-  communityCount: number;
-}
-
-interface CommunityRow {
-  community_id: number;
-  label: string;
-}
-
-interface MemberRow {
-  id: string;
-  label: string;
-  name: string;
-  file_path: string | null;
-  start_line: number | null;
-  is_exported: number | null;
-}
-
-interface EdgeRow {
-  target_community: number | null;
-  target_name: string | null;
-  count: number;
-}
-
-// ============================================================================
-// MAIN EXPORT
-// ============================================================================
-
-/**
- * Generate per-community skill files from the Monograph knowledge graph.
- *
- * @param repoPath - Absolute path to the repository root
- * @param outputDir - Output directory for skill files (default: .monomind/skills/)
- * @returns Metadata about the generated files
- */
-export async function generateSkillFiles(
-  repoPath: string,
-  outputDir?: string,
-): Promise<SkillGenResult> {
-  const dbPath = path.join(repoPath, '.monomind', 'monograph.db');
-  const skillsDir = outputDir ?? path.join(repoPath, '.monomind', 'skills');
-
-  const db = openDb(dbPath);
-
-  try {
-    const communities = queryCommunities(db);
-
-    if (communities.length === 0) {
-      return { filesWritten: [], communityCount: 0 };
-    }
-
-    await fs.mkdir(skillsDir, { recursive: true });
-
-    const filesWritten: string[] = [];
-
-    for (const community of communities) {
-      const members = queryMembers(db, community.community_id);
-      const crossConnections = queryCrossConnections(db, community.community_id);
-
-      const content = renderSkillMarkdown(community, members, crossConnections, repoPath);
-
-      const kebab = toKebabName(community.label || `community-${community.community_id}`);
-      const filePath = path.join(skillsDir, `${kebab}.md`);
-      await fs.writeFile(filePath, content, 'utf-8');
-      filesWritten.push(filePath);
-    }
-
-    return { filesWritten, communityCount: communities.length };
-  } finally {
-    closeDb(db);
-  }
-}
-
-// ============================================================================
-// DB QUERIES
-// ============================================================================
-
-function queryCommunities(db: ReturnType<typeof openDb>): CommunityRow[] {
-  // Try label-based community detection first (community_id column on nodes)
-  try {
-    const rows = db.prepare(`
-      SELECT community_id, label AS label, COUNT(*) AS member_count
-      FROM nodes
-      WHERE community_id IS NOT NULL
-        AND label NOT IN ('File', 'Folder', 'Community', 'Concept')
-      GROUP BY community_id
-      HAVING member_count >= 2
-      ORDER BY member_count DESC
-      LIMIT 20
-    `).all() as Array<{ community_id: number; label: string; member_count: number }>;
-
-    if (rows.length > 0) {
-      // Derive a community label from the most common folder in file paths,
-      // falling back to the most common node label, then a generic name.
-      return rows.map((r) => ({
-        community_id: r.community_id,
-        label: deriveCommunityLabel(db, r.community_id) || r.label || `Community ${r.community_id}`,
-      }));
-    }
-  } catch {
-    // community_id column may not exist in older DBs
-  }
-
-  // Fallback: try querying explicit Community nodes
-  try {
-    const rows = db.prepare(`
-      SELECT id AS community_id, name AS label
-      FROM nodes
-      WHERE label = 'Community'
-      ORDER BY name
-      LIMIT 20
-    `).all() as Array<{ community_id: number; label: string }>;
-    return rows;
-  } catch {
-    return [];
-  }
-}
-
-function deriveCommunityLabel(
-  db: ReturnType<typeof openDb>,
-  communityId: number,
-): string {
-  // Use the most common folder name from member file paths as the label
-  try {
-    const rows = db.prepare(`
-      SELECT file_path
-      FROM nodes
-      WHERE community_id = ?
-        AND file_path IS NOT NULL
-        AND label NOT IN ('File', 'Folder', 'Community', 'Concept')
-    `).all(communityId) as Array<{ file_path: string }>;
-
-    const folderCounts = new Map<string, number>();
-    for (const row of rows) {
-      const parts = row.file_path.replace(/\\/g, '/').split('/').filter(Boolean);
-      if (parts.length >= 2) {
-        const folder = parts[parts.length - 2];
-        const lower = folder.toLowerCase();
-        if (!['src', 'lib', 'core', 'utils', 'common', 'shared', 'helpers', 'dist'].includes(lower)) {
-          folderCounts.set(folder, (folderCounts.get(folder) ?? 0) + 1);
-        }
-      }
-    }
-
-    let best = '';
-    let bestCount = 0;
-    for (const [folder, count] of folderCounts) {
-      if (count > bestCount) {
-        bestCount = count;
-        best = folder;
-      }
-    }
-
-    if (best) {
-      return best.charAt(0).toUpperCase() + best.slice(1);
-    }
-  } catch {
-    // ignore
-  }
-  return '';
-}
-
-function queryMembers(
-  db: ReturnType<typeof openDb>,
-  communityId: number,
-): MemberRow[] {
-  try {
-    return db.prepare(`
-      SELECT id, label, name, file_path, start_line, is_exported
-      FROM nodes
-      WHERE community_id = ?
-        AND label NOT IN ('File', 'Folder', 'Community', 'Concept')
-      ORDER BY
-        CASE WHEN is_exported = 1 THEN 0 ELSE 1 END,
-        label,
-        name
-      LIMIT 50
-    `).all(communityId) as MemberRow[];
-  } catch {
-    return [];
-  }
-}
-
-function queryCrossConnections(
-  db: ReturnType<typeof openDb>,
-  communityId: number,
-): EdgeRow[] {
-  try {
-    return db.prepare(`
-      SELECT n2.community_id AS target_community, n2.name AS target_name, COUNT(*) AS count
-      FROM edges e
-      JOIN nodes n1 ON n1.id = e.source_id
-      JOIN nodes n2 ON n2.id = e.target_id
-      WHERE n1.community_id = ?
-        AND (n2.community_id IS NULL OR n2.community_id != ?)
-        AND e.relation = 'CALLS'
-      GROUP BY n2.community_id
-      ORDER BY count DESC
-      LIMIT 8
-    `).all(communityId, communityId) as EdgeRow[];
-  } catch {
-    return [];
-  }
-}
-
-// ============================================================================
-// MARKDOWN RENDERING
-// ============================================================================
-
-function renderSkillMarkdown(
-  community: CommunityRow,
-  members: MemberRow[],
-  crossConnections: EdgeRow[],
-  repoPath: string,
-): string {
-  const label = community.label;
-  const lines: string[] = [];
-
-  // Frontmatter
-  lines.push('---');
-  lines.push(`name: ${toKebabName(label)}`);
-  lines.push(`description: "Skill for the ${label} community. ${members.length} symbols."`);
-  lines.push(`type: Code Community`);
-  lines.push(`tags: [monograph, code-community]`);
-  lines.push(`timestamp: ${new Date().toISOString()}`);
-  lines.push('---');
-  lines.push('');
-
-  // Title
-  lines.push(`# ${label}`);
-  lines.push('');
-  lines.push(`${members.length} symbols | Community ${community.community_id}`);
-  lines.push('');
-
-  // Key Files
-  const fileMap = buildFileMap(members, repoPath);
-  if (fileMap.size > 0) {
-    lines.push('## Key Files');
-    lines.push('');
-    lines.push('| File | Symbols |');
-    lines.push('|------|---------|');
-    const sorted = [...fileMap.entries()].sort((a, b) => b[1].length - a[1].length);
-    for (const [relPath, symbols] of sorted.slice(0, 10)) {
-      const sym = symbols.slice(0, 5).join(', ');
-      const extra = symbols.length > 5 ? ` (+${symbols.length - 5})` : '';
-      lines.push(`| \`${relPath}\` | ${sym}${extra} |`);
-    }
-    lines.push('');
-  }
-
-  // Key Symbols
-  if (members.length > 0) {
-    lines.push('## Key Symbols');
-    lines.push('');
-    lines.push('| Symbol | Type | File | Line |');
-    lines.push('|--------|------|------|------|');
-    for (const m of members.slice(0, 20)) {
-      const filePath = m.file_path
-        ? toRelativePath(m.file_path, repoPath)
-        : '';
-      lines.push(`| \`${m.name}\` | ${m.label} | \`${filePath}\` | ${m.start_line ?? ''} |`);
-    }
-    lines.push('');
-  }
-
-  // Connected Areas
-  if (crossConnections.length > 0) {
-    lines.push('## Connected Areas');
-    lines.push('');
-    lines.push('| Community | Call Count |');
-    lines.push('|-----------|-----------|');
-    for (const c of crossConnections) {
-      const target = c.target_community != null
-        ? `Community ${c.target_community}`
-        : 'External';
-      lines.push(`| ${target} | ${c.count} calls |`);
-    }
-    lines.push('');
-  }
-
-  // How to Explore
-  const firstSymbol = members[0]?.name ?? label;
-  lines.push('## How to Explore');
-  lines.push('');
-  lines.push(`1. \`monograph_context({name: "${firstSymbol}"})\` — see callers and callees`);
-  lines.push(`2. \`monograph_query({query: "${label.toLowerCase()}"})\` — find related symbols`);
-  lines.push('3. Read key files listed above for implementation details');
-  lines.push('');
-
-  return lines.join('\n');
-}
-
-// ============================================================================
-// UTILITY HELPERS
-// ============================================================================
-
-function buildFileMap(
-  members: MemberRow[],
-  repoPath: string,
-): Map<string, string[]> {
-  const map = new Map<string, string[]>();
-  for (const m of members) {
-    if (!m.file_path) continue;
-    const rel = toRelativePath(m.file_path, repoPath);
-    const arr = map.get(rel);
-    if (arr) {
-      arr.push(m.name);
-    } else {
-      map.set(rel, [m.name]);
-    }
-  }
-  return map;
-}
-
-function toRelativePath(filePath: string, repoPath: string): string {
-  const normalizedFile = filePath.replace(/\\/g, '/');
-  const normalizedRepo = repoPath.replace(/\\/g, '/');
-  if (normalizedFile.startsWith(normalizedRepo)) {
-    return normalizedFile.slice(normalizedRepo.length).replace(/^\//, '');
-  }
-  return normalizedFile.replace(/^\//, '');
-}
-
-function toKebabName(label: string): string {
-  return label
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 50) || 'skill';
-}

package/src/commands/flags.ts

@@ -1,72 +0,0 @@
-export type OutputFormat = 'text' | 'json' | 'compact';
-
-export interface FlagsOptions {
-  root: string;
-  configPath?: string;
-  output: OutputFormat;
-  noCache: boolean;
-  threads: number;
-  quiet: boolean;
-  production: boolean;
-  workspace?: string[];
-  changedWorkspaces?: string;
-  changedSince?: string;
-  explain: boolean;
-  top?: number;
-}
-
-export interface FeatureFlag {
-  name: string;
-  filePath: string;
-  isEnabled: boolean | null;
-  condition?: string;
-  line?: number;
-}
-
-export interface FlagUse {
-  name: string;
-  isEnabled: boolean | null;
-  condition?: string;
-  span?: { start: number; end: number };
-}
-
-export interface FlagsResult {
-  flags: FeatureFlag[];
-  totalFiles: number;
-  totalFlags: number;
-}
-
-export function flagUseToFeatureFlag(flagUse: FlagUse, filePath: string, line?: number): FeatureFlag {
-  return {
-    name: flagUse.name,
-    filePath,
-    isEnabled: flagUse.isEnabled,
-    condition: flagUse.condition,
-    line,
-  };
-}
-
-export function groupFlagsByName(flags: FeatureFlag[]): Map<string, FeatureFlag[]> {
-  const map = new Map<string, FeatureFlag[]>();
-  for (const flag of flags) {
-    const existing = map.get(flag.name);
-    if (existing) existing.push(flag);
-    else map.set(flag.name, [flag]);
-  }
-  return map;
-}
-
-export function formatFlagsText(result: FlagsResult, top?: number): string {
-  const lines: string[] = [
-    `Feature flags: ${result.totalFlags} across ${result.totalFiles} files`,
-    '',
-  ];
-  const entries = [...groupFlagsByName(result.flags).entries()];
-  const sorted = entries.sort((a, b) => b[1].length - a[1].length);
-  const limited = top !== undefined ? sorted.slice(0, top) : sorted;
-  for (const [name, uses] of limited) {
-    lines.push(`  ${name} (${uses.length} uses)`);
-    for (const u of uses) lines.push(`    ${u.filePath}${u.line !== undefined ? `:${u.line}` : ''}`);
-  }
-  return lines.join('\n');
-}

package/src/config/boundary-config.ts

@@ -1,183 +0,0 @@
-export type BoundaryPreset = 'layered' | 'hexagonal' | 'feature-sliced' | 'bulletproof';
-
-export interface BoundaryZoneConfig {
-  name: string;
-  patterns: string[];
-  root?: string;
-}
-
-export interface BoundaryRuleConfig {
-  from: string;
-  allow: string[];
-}
-
-export interface BoundaryConfigFallow {
-  preset?: BoundaryPreset;
-  zones?: BoundaryZoneConfig[];
-  rules?: BoundaryRuleConfig[];
-}
-
-export interface ResolvedZone {
-  name: string;
-  patterns: string[];
-  root: string;
-}
-
-export interface ResolvedBoundaryRule {
-  from: ResolvedZone;
-  allow: ResolvedZone[];
-}
-
-export interface ResolvedBoundaryConfig {
-  zones: ResolvedZone[];
-  rules: ResolvedBoundaryRule[];
-}
-
-function makeZone(name: string, sourceRoot: string, extraPatterns?: string[]): BoundaryZoneConfig {
-  return {
-    name,
-    patterns: extraPatterns ?? [`${sourceRoot}/${name}/**`],
-  };
-}
-
-function makeRule(from: string, allow: string[]): BoundaryRuleConfig {
-  return { from, allow };
-}
-
-export function expandPreset(preset: BoundaryPreset, sourceRoot: string): BoundaryConfigFallow {
-  switch (preset) {
-    case 'layered': {
-      const zones = [
-        { name: 'presentation', patterns: ['ui', 'pages', 'views', 'components'].map(d => `${sourceRoot}/${d}/**`) },
-        { name: 'application', patterns: ['application', 'usecases', 'services'].map(d => `${sourceRoot}/${d}/**`) },
-        { name: 'domain', patterns: ['domain', 'entities', 'models'].map(d => `${sourceRoot}/${d}/**`) },
-        { name: 'infrastructure', patterns: ['infrastructure', 'adapters', 'repositories', 'db', 'api'].map(d => `${sourceRoot}/${d}/**`) },
-      ];
-      const rules = [
-        makeRule('presentation', ['application']),
-        makeRule('application', ['domain']),
-        makeRule('domain', []),
-        makeRule('infrastructure', ['domain', 'application']),
-      ];
-      return { zones, rules };
-    }
-    case 'hexagonal': {
-      const zones = [
-        { name: 'adapters', patterns: ['adapters', 'ports', 'infrastructure'].map(d => `${sourceRoot}/${d}/**`) },
-        { name: 'application', patterns: ['application', 'usecases'].map(d => `${sourceRoot}/${d}/**`) },
-        { name: 'domain', patterns: ['domain', 'core'].map(d => `${sourceRoot}/${d}/**`) },
-      ];
-      const rules = [
-        makeRule('adapters', ['application', 'domain']),
-        makeRule('application', ['domain']),
-        makeRule('domain', []),
-      ];
-      return { zones, rules };
-    }
-    case 'feature-sliced': {
-      const layers = ['app', 'processes', 'pages', 'widgets', 'features', 'entities', 'shared'];
-      const zones = layers.map(name => makeZone(name, sourceRoot));
-      const rules = layers.map((name, i) => makeRule(name, layers.slice(i + 1)));
-      return { zones, rules };
-    }
-    case 'bulletproof': {
-      const zones: BoundaryZoneConfig[] = [
-        makeZone('features', sourceRoot),
-        makeZone('components', sourceRoot),
-        makeZone('hooks', sourceRoot),
-        makeZone('pages', sourceRoot),
-        makeZone('routes', sourceRoot),
-        makeZone('api', sourceRoot),
-        makeZone('lib', sourceRoot),
-        makeZone('types', sourceRoot),
-        makeZone('config', sourceRoot),
-        {
-          name: 'shared',
-          patterns: ['utils', 'helpers', 'shared', 'common', 'constants', 'models', 'interfaces'].map(d => `${sourceRoot}/${d}/**`),
-        },
-      ];
-      const rules = [
-        makeRule('features', ['components', 'hooks', 'pages', 'routes', 'api', 'lib', 'types', 'config', 'shared']),
-        makeRule('components', ['hooks', 'lib', 'types', 'config', 'shared']),
-      ];
-      return { zones, rules };
-    }
-  }
-}
-
-export function resolveBoundaryConfig(
-  config: BoundaryConfigFallow,
-  sourceRoot: string,
-): ResolvedBoundaryConfig {
-  let baseZones: BoundaryZoneConfig[] = [];
-  let baseRules: BoundaryRuleConfig[] = [];
-
-  if (config.preset) {
-    const expanded = expandPreset(config.preset, sourceRoot);
-    baseZones = expanded.zones ?? [];
-    baseRules = expanded.rules ?? [];
-  }
-
-  const customZones = config.zones ?? [];
-  const customRules = config.rules ?? [];
-
-  const zoneMap = new Map<string, BoundaryZoneConfig>();
-  for (const z of [...baseZones, ...customZones]) {
-    zoneMap.set(z.name, z);
-  }
-
-  const ruleMap = new Map<string, BoundaryRuleConfig>();
-  for (const r of [...baseRules, ...customRules]) {
-    ruleMap.set(r.from, r);
-  }
-
-  const resolvedZones: ResolvedZone[] = Array.from(zoneMap.values()).map(z => ({
-    name: z.name,
-    patterns: z.patterns,
-    root: z.root ?? sourceRoot,
-  }));
-
-  const zoneByName = new Map<string, ResolvedZone>(resolvedZones.map(z => [z.name, z]));
-
-  const resolvedRules: ResolvedBoundaryRule[] = [];
-  for (const rule of ruleMap.values()) {
-    const fromZone = zoneByName.get(rule.from);
-    if (!fromZone) continue;
-    const allowZones = rule.allow.map(name => zoneByName.get(name)).filter((z): z is ResolvedZone => z !== undefined);
-    resolvedRules.push({ from: fromZone, allow: allowZones });
-  }
-
-  return { zones: resolvedZones, rules: resolvedRules };
-}
-
-export function classifyZone(
-  resolved: ResolvedBoundaryConfig,
-  filePath: string,
-): string | undefined {
-  for (const zone of resolved.zones) {
-    for (const pattern of zone.patterns) {
-      const prefix = pattern.replace('/**', '').replace('**', '');
-      if (filePath.includes(prefix)) {
-        return zone.name;
-      }
-    }
-  }
-  return undefined;
-}
-
-export function isImportAllowed(
-  resolved: ResolvedBoundaryConfig,
-  fromPath: string,
-  toPath: string,
-): boolean {
-  const fromZoneName = classifyZone(resolved, fromPath);
-  const toZoneName = classifyZone(resolved, toPath);
-
-  if (!fromZoneName || !toZoneName) return true;
-  if (fromZoneName === toZoneName) return true;
-
-  const rule = resolved.rules.find(r => r.from.name === fromZoneName);
-  if (!rule) return true;
-
-  return rule.allow.some(z => z.name === toZoneName);
-}

package/src/config/cli-schema.ts

@@ -1,81 +0,0 @@
-// Generate a JSON Schema document describing the monograph CLI commands.
-
-export interface CliParam {
-  name: string;
-  type: 'string' | 'boolean' | 'number' | 'array';
-  description: string;
-  required?: boolean;
-  default?: unknown;
-  enum?: string[];
-}
-
-export interface CliSubcommand {
-  name: string;
-  description: string;
-  params: CliParam[];
-}
-
-export interface CliSchema {
-  name: string;
-  version: string;
-  description: string;
-  subcommands: CliSubcommand[];
-}
-
-const COMMON_PARAMS: CliParam[] = [
-  { name: 'reporter', type: 'string', description: 'Output format', enum: ['human', 'json', 'compact', 'markdown'] },
-  { name: 'no-gitignore', type: 'boolean', description: 'Disable .gitignore respect', default: false },
-];
-
-export function buildCliSchema(version = '1.0.0'): CliSchema {
-  return {
-    name: 'monograph',
-    version,
-    description: 'Monograph code analysis CLI',
-    subcommands: [
-      {
-        name: 'analyze',
-        description: 'Detect unused files, exports, dependencies, and more',
-        params: [
-          { name: 'root', type: 'string', description: 'Project root', required: true },
-          { name: 'entry', type: 'array', description: 'Entry point patterns' },
-          { name: 'project', type: 'string', description: 'Path to tsconfig.json' },
-          { name: 'production', type: 'boolean', description: 'Apply production mode filter', default: false },
-          { name: 'include-entry-exports', type: 'boolean', description: 'Include entry file exports in analysis', default: false },
-          { name: 'changed-since', type: 'string', description: 'Only report issues in files changed since git ref' },
-          { name: 'group-by', type: 'string', description: 'Group output by owner/directory/package/section', enum: ['owner', 'directory', 'package', 'section'] },
-          ...COMMON_PARAMS,
-        ],
-      },
-      {
-        name: 'health',
-        description: 'Compute function complexity, maintainability, and health scores',
-        params: [
-          { name: 'root', type: 'string', description: 'Project root', required: true },
-          { name: 'max-cyclomatic', type: 'number', description: 'Cyclomatic complexity threshold', default: 10 },
-          { name: 'max-cognitive', type: 'number', description: 'Cognitive complexity threshold', default: 15 },
-          { name: 'max-crap', type: 'number', description: 'CRAP score threshold', default: 30 },
-          { name: 'coverage', type: 'string', description: 'Path to Istanbul coverage JSON' },
-          { name: 'save-snapshot', type: 'boolean', description: 'Save a VitalSigns snapshot', default: false },
-          { name: 'trend', type: 'boolean', description: 'Show trend vs last snapshot', default: false },
-          ...COMMON_PARAMS,
-        ],
-      },
-      {
-        name: 'find-dupes',
-        description: 'Detect code duplication using token-based clone detection',
-        params: [
-          { name: 'root', type: 'string', description: 'Project root', required: true },
-          { name: 'min-tokens', type: 'number', description: 'Minimum token count', default: 50 },
-          { name: 'min-lines', type: 'number', description: 'Minimum line count', default: 5 },
-          { name: 'cross-language', type: 'boolean', description: 'Enable cross-language detection', default: false },
-          ...COMMON_PARAMS,
-        ],
-      },
-    ],
-  };
-}
-
-export function schemaToJsonString(schema: CliSchema): string {
-  return JSON.stringify(schema, null, 2);
-}