@monoes/monograph 1.1.0 → 1.2.0

package/src/cli/skill-gen.ts

@@ -0,0 +1,352 @@
+/**
+ * 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);
+
+  let communities: CommunityRow[];
+  try {
+    communities = queryCommunities(db);
+  } finally {
+    closeDb(db);
+  }
+
+  if (communities.length === 0) {
+    return { filesWritten: [], communityCount: 0 };
+  }
+
+  await fs.mkdir(skillsDir, { recursive: true });
+
+  const filesWritten: string[] = [];
+
+  for (const community of communities) {
+    const db2 = openDb(dbPath);
+    let members: MemberRow[];
+    let crossConnections: EdgeRow[];
+    try {
+      members = queryMembers(db2, community.community_id);
+      crossConnections = queryCrossConnections(db2, community.community_id);
+    } finally {
+      closeDb(db2);
+    }
+
+    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 };
+}
+
+// ============================================================================
+// 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('---');
+  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

@@ -0,0 +1,72 @@
+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

@@ -0,0 +1,183 @@
+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

@@ -0,0 +1,81 @@
+// 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);
+}