@monoes/monograph 1.1.0 → 1.2.0

package/src/report/number-format.ts

@@ -0,0 +1,91 @@
+import * as path from 'node:path';
+
+export const MAX_FLAT_ITEMS = 10;
+export const MAX_GROUPED_FILES = 10;
+export const DIR_ROLLUP_THRESHOLD = 200;
+
+export function thousands(n: number): string {
+  return n.toLocaleString('en-US');
+}
+
+export function formatPercent(n: number, decimals = 1): string {
+  return `${n.toFixed(decimals)}%`;
+}
+
+export function formatPath(filePath: string, root: string): string {
+  const rel = path.relative(root, filePath).replace(/\\/g, '/');
+  const lastSlash = rel.lastIndexOf('/');
+  if (lastSlash === -1) return rel;
+  const dir = rel.slice(0, lastSlash + 1);
+  const filename = rel.slice(lastSlash + 1);
+  return `${dir}${filename}`;
+}
+
+export function formatPathParts(filePath: string, root: string): { dir: string; filename: string } {
+  const rel = path.relative(root, filePath).replace(/\\/g, '/');
+  const lastSlash = rel.lastIndexOf('/');
+  if (lastSlash === -1) return { dir: '', filename: rel };
+  return { dir: rel.slice(0, lastSlash + 1), filename: rel.slice(lastSlash + 1) };
+}
+
+export function buildSectionHeader(title: string, count: number): string {
+  return `${title} (${thousands(count)})`;
+}
+
+export interface GroupedByFile {
+  filePath: string;
+  items: Array<{ name: string; line?: number; extra?: string }>;
+}
+
+export function buildGroupedByFile<T extends { filePath: string; exportName?: string; memberName?: string; line?: number }>(
+  items: T[],
+  root: string,
+  maxFiles: number = MAX_GROUPED_FILES,
+  maxPerFile: number = MAX_FLAT_ITEMS,
+): GroupedByFile[] {
+  const byFile = new Map<string, typeof items>();
+  for (const item of items) {
+    const existing = byFile.get(item.filePath);
+    if (existing) existing.push(item);
+    else byFile.set(item.filePath, [item]);
+  }
+
+  const sorted = [...byFile.entries()]
+    .sort((a, b) => b[1].length - a[1].length)
+    .slice(0, maxFiles);
+
+  return sorted.map(([filePath, fileItems]) => ({
+    filePath,
+    items: fileItems.slice(0, maxPerFile).map(i => ({
+      name: i.exportName ?? i.memberName ?? filePath,
+      line: i.line,
+    })),
+  }));
+}
+
+export function pluralize(count: number, singular: string, plural?: string): string {
+  return count === 1 ? singular : (plural ?? singular + 's');
+}
+
+export function summarizeTruncation(shown: number, total: number, noun: string): string | null {
+  if (shown >= total) return null;
+  return `… and ${thousands(total - shown)} more ${noun}`;
+}
+
+export function formatCircularCycle(cycle: string[], root: string): string {
+  return cycle
+    .map(f => path.relative(root, f).replace(/\\/g, '/'))
+    .join(' → ');
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m ${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes}B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/report/output-grouped.ts

@@ -0,0 +1,102 @@
+import * as path from 'node:path';
+import type { AnalysisResults } from '../results/types.js';
+import { totalIssues } from '../results/types.js';
+import { buildSectionHeader, thousands } from './number-format.js';
+
+export type GroupOutputFormat = 'json' | 'text' | 'compact' | 'sarif';
+
+export interface ResultGroup {
+  key: string;
+  owner?: string;
+  root?: string;
+  results: AnalysisResults;
+}
+
+export interface GroupedOutputOptions {
+  format: GroupOutputFormat;
+  root: string;
+  showEmpty?: boolean;
+  maxGroupsInText?: number;
+}
+
+export function buildGroupedJsonOutput(
+  groups: ResultGroup[],
+  opts: { root: string; schemaVersion?: number },
+): Record<string, unknown> {
+  const schemaVersion = opts.schemaVersion ?? 4;
+  const groupsJson = groups.map(g => ({
+    key: g.key,
+    owner: g.owner,
+    root: g.root ? path.relative(opts.root, g.root) : undefined,
+    issueCount: totalIssues(g.results),
+    results: g.results,
+  }));
+  return {
+    $schema: `https://monograph.dev/schema/v${schemaVersion}/grouped-results.json`,
+    schemaVersion,
+    root: opts.root,
+    groupCount: groups.length,
+    totalIssues: groups.reduce((s, g) => s + totalIssues(g.results), 0),
+    groups: groupsJson,
+  };
+}
+
+export function buildGroupedTextLines(
+  groups: ResultGroup[],
+  opts: GroupedOutputOptions,
+): string[] {
+  const lines: string[] = [];
+  const nonEmpty = opts.showEmpty ? groups : groups.filter(g => totalIssues(g.results) > 0);
+
+  if (nonEmpty.length === 0) {
+    lines.push('No issues found across all groups.');
+    return lines;
+  }
+
+  lines.push(buildSectionHeader(`Groups with issues`, nonEmpty.length));
+  lines.push('');
+
+  const shown = opts.maxGroupsInText
+    ? nonEmpty.slice(0, opts.maxGroupsInText)
+    : nonEmpty;
+
+  for (const group of shown) {
+    const count = totalIssues(group.results);
+    const label = group.owner ?? group.key;
+    lines.push(`  ${label}: ${thousands(count)} issue${count === 1 ? '' : 's'}`);
+
+    if (group.results.unusedFiles.length > 0) lines.push(`    • unused files: ${group.results.unusedFiles.length}`);
+    if (group.results.unusedExports.length > 0) lines.push(`    • unused exports: ${group.results.unusedExports.length}`);
+    if (group.results.unusedDependencies.length > 0) lines.push(`    • unused deps: ${group.results.unusedDependencies.length}`);
+    if (group.results.circularDependencies.length > 0) lines.push(`    • circular deps: ${group.results.circularDependencies.length}`);
+  }
+
+  if (opts.maxGroupsInText && nonEmpty.length > opts.maxGroupsInText) {
+    lines.push(`  … and ${nonEmpty.length - opts.maxGroupsInText} more groups`);
+  }
+
+  return lines;
+}
+
+export function buildGroupedCompactLines(groups: ResultGroup[], root: string): string[] {
+  return groups
+    .filter(g => totalIssues(g.results) > 0)
+    .map(g => {
+      const label = g.owner ?? g.key;
+      const count = totalIssues(g.results);
+      return `${label}:${count}`;
+    });
+}
+
+export function partitionGroupsByOwner(
+  groups: ResultGroup[],
+  ownerFilter: (owner: string) => boolean,
+): { matched: ResultGroup[]; unmatched: ResultGroup[] } {
+  const matched: ResultGroup[] = [];
+  const unmatched: ResultGroup[] = [];
+  for (const g of groups) {
+    if (g.owner && ownerFilter(g.owner)) matched.push(g);
+    else unmatched.push(g);
+  }
+  return { matched, unmatched };
+}

package/src/report/pipeline-perf.ts

@@ -0,0 +1,56 @@
+export interface PipelineTimings {
+  discoverFilesMs: number;
+  fileCount: number;
+  workspacesMs: number;
+  workspaceCount: number;
+  pluginsMs: number;
+  scriptAnalysisMs: number;
+  parseExtractMs: number;
+  moduleCount: number;
+  cacheHits: number;
+  cacheMisses: number;
+  cacheUpdateMs: number;
+  entryPointsMs: number;
+  entryPointCount: number;
+  resolveImportsMs: number;
+  buildGraphMs: number;
+  analyzeMs: number;
+  duplicationMs?: number;
+  totalMs: number;
+}
+
+export const ZERO_PIPELINE_TIMINGS: PipelineTimings = {
+  discoverFilesMs: 0, fileCount: 0, workspacesMs: 0, workspaceCount: 0,
+  pluginsMs: 0, scriptAnalysisMs: 0, parseExtractMs: 0, moduleCount: 0,
+  cacheHits: 0, cacheMisses: 0, cacheUpdateMs: 0, entryPointsMs: 0,
+  entryPointCount: 0, resolveImportsMs: 0, buildGraphMs: 0, analyzeMs: 0,
+  totalMs: 0,
+};
+
+export function buildPipelinePerformanceLines(t: PipelineTimings): string[] {
+  const cacheDetail = t.cacheHits > 0 ? `, ${t.cacheHits} cached, ${t.cacheMisses} parsed` : '';
+  const fmt = (ms: number) => ms.toFixed(1).padStart(8);
+  return [
+    '',
+    '┌─ Pipeline Performance ─────────────────────────────',
+    `│  discover files:   ${fmt(t.discoverFilesMs)}ms  (${t.fileCount} files)`,
+    `│  workspaces:       ${fmt(t.workspacesMs)}ms  (${t.workspaceCount} workspaces)`,
+    `│  plugins:          ${fmt(t.pluginsMs)}ms`,
+    `│  script analysis:  ${fmt(t.scriptAnalysisMs)}ms`,
+    `│  parse/extract:    ${fmt(t.parseExtractMs)}ms  (${t.moduleCount} modules${cacheDetail})`,
+    `│  cache update:     ${fmt(t.cacheUpdateMs)}ms`,
+    `│  entry points:     ${fmt(t.entryPointsMs)}ms  (${t.entryPointCount} entries)`,
+    `│  resolve imports:  ${fmt(t.resolveImportsMs)}ms`,
+    `│  build graph:      ${fmt(t.buildGraphMs)}ms`,
+    `│  analyze:          ${fmt(t.analyzeMs)}ms`,
+    ...(t.duplicationMs !== undefined ? [`│  duplication:      ${fmt(t.duplicationMs)}ms`] : []),
+    '│  ────────────────────────────────────────────────',
+    `│  TOTAL:            ${fmt(t.totalMs)}ms`,
+    '└───────────────────────────────────────────────────',
+    '',
+  ];
+}
+
+export function timingsSummary(t: PipelineTimings): string {
+  return `${t.fileCount} files in ${t.totalMs.toFixed(0)}ms (${t.cacheHits} cache hits)`;
+}

package/src/report/trace-human.ts

@@ -0,0 +1,127 @@
+import { relative } from 'node:path';
+
+export interface ExportTraceRef {
+  fromFile: string;
+  kind: string;
+}
+
+export interface ReExportChain {
+  barrelFile: string;
+  exportedAs: string;
+  referenceCount: number;
+}
+
+export interface ExportTraceInput {
+  exportName: string;
+  file: string;
+  isUsed: boolean;
+  fileReachable: boolean;
+  isEntryPoint: boolean;
+  reason: string;
+  directReferences: ExportTraceRef[];
+  reExportChains: ReExportChain[];
+}
+
+export interface FileTraceExport {
+  name: string;
+  referenceCount: number;
+  isTypeOnly: boolean;
+  referencedBy: ExportTraceRef[];
+}
+
+export interface FileTraceInput {
+  file: string;
+  isReachable: boolean;
+  isEntryPoint: boolean;
+  exports: FileTraceExport[];
+  importedBy: string[];
+}
+
+export interface DependencyTraceInput {
+  packageName: string;
+  isUsed: boolean;
+  importCount: number;
+  importedBy: string[];
+  typeOnlyImportedBy: string[];
+  usedInScripts: boolean;
+}
+
+export interface CloneGroupTrace {
+  lineCount: number;
+  tokenCount: number;
+  instances: Array<{ file: string; startLine: number; endLine: number }>;
+}
+
+export interface CloneTraceInput {
+  matchedInstance?: { file: string; startLine: number; endLine: number };
+  cloneGroups: CloneGroupTrace[];
+}
+
+function rel(file: string, root: string): string { return relative(root, file); }
+
+export function printExportTraceHuman(trace: ExportTraceInput, root: string): void {
+  const status = trace.isUsed ? 'USED' : 'UNUSED';
+  console.error(`\n  ${status} ${trace.exportName} in ${rel(trace.file, root)}`);
+  console.error(`\n  File: ${trace.fileReachable ? 'reachable' : 'unreachable'}${trace.isEntryPoint ? ' (entry point)' : ''}`);
+  console.error(`  Reason: ${trace.reason}`);
+  if (trace.directReferences.length > 0) {
+    console.error(`\n  ${trace.directReferences.length} direct reference(s):`);
+    for (const r of trace.directReferences) console.error(`    -> ${rel(r.fromFile, root)} (${r.kind})`);
+  }
+  if (trace.reExportChains.length > 0) {
+    console.error('\n  Re-exported through:');
+    for (const c of trace.reExportChains) console.error(`    -> ${rel(c.barrelFile, root)} as '${c.exportedAs}' (${c.referenceCount} ref(s))`);
+  }
+  console.error('');
+}
+
+export function printFileTraceHuman(trace: FileTraceInput, root: string): void {
+  const status = trace.isReachable ? 'REACHABLE' : 'UNREACHABLE';
+  const entry = trace.isEntryPoint ? ' (entry point)' : '';
+  console.error(`\n  ${status} ${rel(trace.file, root)}${entry}`);
+  if (trace.exports.length > 0) {
+    console.error(`\n  Exports (${trace.exports.length}):`);
+    for (const e of trace.exports) {
+      const used = e.referenceCount > 0 ? `${e.referenceCount} ref(s)` : 'unused';
+      const tag = e.isTypeOnly ? ' (type)' : '';
+      console.error(`    export ${e.name}${tag} [${used}]`);
+      for (const r of e.referencedBy) console.error(`      -> ${rel(r.fromFile, root)} (${r.kind})`);
+    }
+  }
+  if (trace.importedBy.length > 0) {
+    console.error(`\n  Imported by (${trace.importedBy.length}):`);
+    for (const p of trace.importedBy) console.error(`    -> ${rel(p, root)}`);
+  }
+  console.error('');
+}
+
+export function printDependencyTraceHuman(trace: DependencyTraceInput): void {
+  const status = trace.isUsed ? 'USED' : 'UNUSED';
+  console.error(`\n  ${status} ${trace.packageName} (${trace.importCount} import(s))`);
+  if (trace.importedBy.length > 0) {
+    console.error('\n  Imported by:');
+    for (const p of trace.importedBy) {
+      const tag = trace.typeOnlyImportedBy.includes(p) ? ' (type-only)' : '';
+      console.error(`    -> ${p}${tag}`);
+    }
+  }
+  if (trace.usedInScripts) console.error('\n  Referenced from package.json scripts or CI configs.');
+  console.error('');
+}
+
+export function printCloneTraceHuman(trace: CloneTraceInput, root: string): void {
+  if (trace.matchedInstance) {
+    const m = trace.matchedInstance;
+    console.error(`\n  FOUND clone at ${rel(m.file, root)}:${m.startLine}-${m.endLine}`);
+  }
+  console.error(`  ${trace.cloneGroups.length} clone group(s) containing this location`);
+  for (let i = 0; i < trace.cloneGroups.length; i++) {
+    const g = trace.cloneGroups[i];
+    console.error(`\n  Clone group ${i + 1} (${g.lineCount} lines, ${g.tokenCount} tokens, ${g.instances.length} instance(s))`);
+    for (const inst of g.instances) {
+      const marker = trace.matchedInstance && trace.matchedInstance.file === inst.file && trace.matchedInstance.startLine === inst.startLine ? '>>' : '->';
+      console.error(`    ${marker} ${rel(inst.file, root)}:${inst.startLine}-${inst.endLine}`);
+    }
+  }
+  console.error('');
+}