{
  "version": "act 2.1.1",
  "url": "https://act101.ai/docs/analysis-tools",
  "operations": [
    {
      "name": "analyze_api_diff",
      "anchor": "op-analyze-api-diff",
      "description": "Diff the exported/public symbol surface between merge-base(base_ref, HEAD) and the working tree: per-symbol verdict rows (breaking / possibly-breaking / additive) with both signatures where they changed \u2014 removed public symbols, gained parameters, and visibility narrowing are breaking; new exports additive. Visibility-unmodeled grammars yield unjudgeable rows naming the grammar (never silence, never guessed-private); type-level claims only where types are modeled. Params: none [, base_ref (string \u2014 omit to diff against HEAD)]",
      "params": "none [, base_ref (string \u2014 omit to diff against HEAD)]",
      "category": "Code Health",
      "tier": "architecture"
    },
    {
      "name": "analyze_chokepoints",
      "anchor": "op-analyze-chokepoints",
      "description": "Find files that act as critical bottlenecks \u2014 high betweenness centrality in the dependency graph (R4). granularity=\"symbol\" ranks individual functions over the call graph instead of files (capped, with truncation disclosure). Params: none [, granularity (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, granularity (string), include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "architecture"
    },
    {
      "name": "analyze_clones",
      "anchor": "op-analyze-clones",
      "description": "Detect duplicated code as clone classes \u2014 type-1 (exact) and type-2 (renamed identifiers/literals) subtree clones with member ranges, token counts, and an extract_function remediation pointer when all members sit in function bodies; type-3 (gapped) clones are not detected. Params: none [, include (string[]), exclude (string[]), min_tokens (number)]. Use include/exclude to restrict the scan scope; min_tokens overrides the minimum clone size (default 50).",
      "params": "none [, include (string[]), exclude (string[]), min_tokens (number)]",
      "category": "Code Health",
      "tier": "engineer"
    },
    {
      "name": "analyze_clusters",
      "anchor": "op-analyze-clusters",
      "description": "Identify tightly coupled groups of files using community detection. Use to discover natural module boundaries and understand which files change together. Clusters where a hub file glues unrelated files together are flagged via hub_collapse=true and top_hubs (named hub files); pass dampen_top_k (u32) to exclude the top-k highest-degree files from propagation and reveal genuine neighborhoods. Params: none [, granularity (string), min_size (u32), dampen_top_k (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, granularity (string), min_size (u32), dampen_top_k (u32), include (string[]), exclude (string[])]",
      "category": "Structure",
      "tier": "architecture"
    },
    {
      "name": "analyze_cohesion",
      "anchor": "op-analyze-cohesion",
      "description": "Measure intra-module cohesion for each file \u2014 ratio of internal to total symbol edges (H2); counts call edges between symbols (syntactic, LSP-enriched when available). Also reports class-level LCOM4 (connected components of each class's method graph \u2014 methods linked by a shared field access or intra-class call) with coverage-law disclosure of which grammars were modeled. Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Structure",
      "tier": "architecture"
    },
    {
      "name": "analyze_conformance",
      "anchor": "op-analyze-conformance",
      "description": "Evaluate the [architecture] contract in .act/config.toml against the actual import graph \u2014 deny-rule, layer-rank, and public-surface violations with the offending import's file:line, plus named cycle exemptions (suppressed but counted). Returns contract_present: false when no contract section exists. Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope.",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Code Health",
      "tier": "architecture"
    },
    {
      "name": "analyze_coupling",
      "anchor": "op-analyze-coupling",
      "description": "Measure coupling per file \u2014 how many files depend on it (afferent) vs how many it depends on (efferent), plus instability and abstractness scores; symbol granularity reflects call relationships (syntactic, LSP-enriched when available). Use to find the most critical/fragile files. Params: none [, granularity (string), sort (string: coupling|instability|distance|afferent|efferent, default coupling = most entangled first), threshold (f64), top_n (u32, default 200), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, granularity (string), sort (string: coupling|instability|distance|afferent|efferent, default coupling = most entangled first), threshold (f64), top_n (u32, default 200), include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "engineer"
    },
    {
      "name": "analyze_cycle_risk",
      "anchor": "op-analyze-cycle-risk",
      "description": "Score each circular dependency cycle by its external risk surface (R6 circular risk zones analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "architecture"
    },
    {
      "name": "analyze_cycles",
      "anchor": "op-analyze-cycles",
      "description": "Find circular dependency chains in the codebase. Use to identify import cycles that cause build issues or indicate architecture problems. Params: none [, granularity (string), max_length (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, granularity (string), max_length (u32), include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "free"
    },
    {
      "name": "analyze_dead_code",
      "anchor": "op-analyze-dead-code",
      "description": "Find dead code \u2014 functions, classes, and types that are never referenced from any entry point; reachability follows call edges (syntactic, LSP-enriched when available). Use before cleanup to safely identify what can be deleted. Params: none [, entry (string[]), granularity (string), include_tests (bool), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, entry (string[]), granularity (string), include_tests (bool), include (string[]), exclude (string[])]",
      "category": "Code Health",
      "tier": "free"
    },
    {
      "name": "analyze_depth",
      "anchor": "op-analyze-depth",
      "description": "Compute longest transitive dependency chain per file (S4 dependency depth analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Complexity",
      "tier": "free"
    },
    {
      "name": "analyze_entry_points",
      "anchor": "op-analyze-entry-points",
      "description": "Detect entry points: main functions, HTTP routes, CLI commands, event listeners, test files (S5). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Structure",
      "tier": "engineer"
    },
    {
      "name": "analyze_export",
      "anchor": "op-analyze-export",
      "description": "Export the full semantic graph (files, symbols, dependencies) in JSON, DOT (Graphviz), or CSV format. Use for visualization or external analysis. Responses are size-bounded: large graphs return truncated:true plus next_cursor \u2014 pass it back as cursor to page through; stats always reports full node/edge counts. Params: none [, format (string), cursor (u32), max_bytes (u32, default 1000000, hard cap 4000000), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, format (string), cursor (u32), max_bytes (u32, default 1000000, hard cap 4000000), include (string[]), exclude (string[])]",
      "category": "Surface & API",
      "tier": "free"
    },
    {
      "name": "analyze_extraction",
      "anchor": "op-analyze-extraction",
      "description": "Score clusters for service or package extraction viability (M2 extraction candidates analysis); skips hub-collapse artifact clusters (flagged by analyze_clusters). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Code Health",
      "tier": "enterprise"
    },
    {
      "name": "analyze_fan_balance",
      "anchor": "op-analyze-fan-balance",
      "description": "Compute fan-in/fan-out imbalance for migration ordering guidance (M6 fan balance analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "enterprise"
    },
    {
      "name": "analyze_features",
      "anchor": "op-analyze-features",
      "description": "Inventory language-specific AST features used in the codebase \u2014 async, generics, decorators, etc. (M3). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Migration Readiness",
      "tier": "enterprise"
    },
    {
      "name": "analyze_hotspots",
      "anchor": "op-analyze-hotspots",
      "description": "Rank files by composite complexity score \u2014 max cyclomatic complexity, statement count, nesting depth (H1). Test files are excluded by default (is_test_file conventions); summary.test_files_excluded discloses the count. Item-level exclusion (e.g. Rust #[cfg(test)]) is per-grammar; summary.item_level_exclusion_grammars names grammars where it was modeled. Params: none [, top_n (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, top_n (u32), include (string[]), exclude (string[])]",
      "category": "Complexity",
      "tier": "engineer"
    },
    {
      "name": "analyze_impact",
      "anchor": "op-analyze-impact",
      "description": "Compute change impact \u2014 two modes. File mode (Free, default): finds all files directly and transitively depending on `target` (R1). Symbol mode (Architecture): when `symbol` is set, returns transitive callers of that function symbol \u2014 syntactic-floor analysis, LSP-enhanced when available, no LSP required. Append `::<line>` to `symbol` to disambiguate overloads (e.g. `\"process::42\"`). Params: target (string) [, symbol (string), max_depth (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]). Errors: SYMBOL_NOT_FOUND, AMBIGUOUS_SYMBOL, UNSUPPORTED_SYMBOL_KIND.",
      "params": "target (string) [, symbol (string), max_depth (u32), include (string[]), exclude (string[])]",
      "category": "Migration Readiness",
      "tier": "architecture"
    },
    {
      "name": "analyze_inconsistencies",
      "anchor": "op-analyze-inconsistencies",
      "description": "Detect inconsistent abstractions \u2014 sibling files in the same directory that diverge from the group's structural pattern (H5). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Code Health",
      "tier": "engineer"
    },
    {
      "name": "analyze_inheritance",
      "anchor": "op-analyze-inheritance",
      "description": "Detect tangled inheritance \u2014 deep hierarchies (>N levels) and diamond inheritance (H6). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Complexity",
      "tier": "engineer"
    },
    {
      "name": "analyze_interface_bloat",
      "anchor": "op-analyze-interface-bloat",
      "description": "Detect interface bloat \u2014 files where the public API is disproportionately large relative to implementation (H3). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Code Health",
      "tier": "architecture"
    },
    {
      "name": "analyze_interfaces",
      "anchor": "op-analyze-interfaces",
      "description": "Map cross-module interfaces \u2014 symbols that cross directory-module boundaries, ranked by interface width (M4). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Surface & API",
      "tier": "enterprise"
    },
    {
      "name": "analyze_layers",
      "anchor": "op-analyze-layers",
      "description": "Detect architectural layers from directory names and find dependency direction violations (S1+S2); result carries classification_coverage and is marked unreliable below 0.5 coverage (verdicts not-modeled). Params: none [, detect_only (bool), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, detect_only (bool), include (string[]), exclude (string[])]",
      "category": "Coupling & Cycles",
      "tier": "engineer"
    },
    {
      "name": "analyze_orphan_types",
      "anchor": "op-analyze-orphan-types",
      "description": "Find type definitions used exclusively outside their defining directory (H4 orphan types analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Code Health",
      "tier": "architecture"
    },
    {
      "name": "analyze_patterns",
      "anchor": "op-analyze-patterns",
      "description": "Find code smells \u2014 god functions, deep nesting, high coupling, and other structural issues. Use to identify refactoring targets or assess code quality. Params: none [, tier (string), pattern (string), file (string), severity (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, tier (string), pattern (string), file (string), severity (string), include (string[]), exclude (string[])]",
      "category": "Complexity",
      "tier": "engineer"
    },
    {
      "name": "analyze_platform_deps",
      "anchor": "op-analyze-platform-deps",
      "description": "Detect platform-specific API usage by scanning imports (M5 platform dependencies analysis). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Migration Readiness",
      "tier": "enterprise"
    },
    {
      "name": "analyze_readiness",
      "anchor": "op-analyze-readiness",
      "description": "Compute migration readiness scores per file \u2014 composite of complexity, coupling, porting blockers (M1). Params: none [, include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, include (string[]), exclude (string[])]",
      "category": "Migration Readiness",
      "tier": "enterprise"
    },
    {
      "name": "analyze_roles",
      "anchor": "op-analyze-roles",
      "description": "Classify files by architectural role: entry point, routing, business logic, data access, config, test, utility, types, generated (S3). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Structure",
      "tier": "engineer"
    },
    {
      "name": "analyze_seams",
      "anchor": "op-analyze-seams",
      "description": "Find the natural boundaries between file clusters \u2014 the narrowest points where groups of files communicate. Use to identify where to split modules or add API boundaries. Params: none [, min_cluster_size (u32), max_seam_width (u32), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, min_cluster_size (u32), max_seam_width (u32), include (string[]), exclude (string[])]",
      "category": "Structure",
      "tier": "engineer"
    },
    {
      "name": "analyze_stability",
      "anchor": "op-analyze-stability",
      "description": "Compute stability index (R2) and detect stable dependency violations (R3) \u2014 flags edges where stable modules depend on unstable ones. Params: none [, index_only (bool), include (string[]), exclude (string[])].",
      "params": "none [, index_only (bool), include (string[]), exclude (string[])].",
      "category": "Migration Readiness",
      "tier": "architecture"
    },
    {
      "name": "analyze_surface",
      "anchor": "op-analyze-surface",
      "description": "Measure API surface area \u2014 count exposed functions, types, and complexity at a module boundary. Use to assess whether an API is too large or leaky. Params: none [, boundary (string), files (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, boundary (string), files (string), include (string[]), exclude (string[])]",
      "category": "Surface & API",
      "tier": "engineer"
    },
    {
      "name": "analyze_test_gaps",
      "anchor": "op-analyze-test-gaps",
      "description": "Detect source files with no or partial test coverage (R5). When coverage_report is supplied (lcov, JaCoCo XML, or coverage.py JSON), statuses are evidence-based (evidence: \"lcov\"); otherwise convention-based (evidence: \"convention\"). Params: none [, coverage_report (string), include (string[]), exclude (string[])]. Use include/exclude to restrict the scan scope (e.g. include=[\"crates\"], exclude=[\"corpus\"]).",
      "params": "none [, coverage_report (string), include (string[]), exclude (string[])]",
      "category": "Migration Readiness",
      "tier": "architecture"
    },
    {
      "name": "analyze_type_completeness",
      "anchor": "op-analyze-type-completeness",
      "description": "Analyze type boundary completeness \u2014 detect 'any' types, untyped parameters, missing return types at exported function boundaries (M7). Params: none [, include (string[]), exclude (string[])].",
      "params": "none [, include (string[]), exclude (string[])].",
      "category": "Surface & API",
      "tier": "enterprise"
    },
    {
      "name": "churn_hotspots",
      "anchor": "op-churn-hotspots",
      "description": "Rank code by git churn \u2014 change frequency weighted by recency. Workspace mode (no `file`, Architecture) ranks symbols by score = \u03a3 recency-decayed changes; single-file mode (`file`, Free teaser) returns that file's bare commit count. Honest degradation: grammars without symbol extraction yield file-level facts only. Params: none [, file (string), top_n (u32)=50, max_files (u32)=500]",
      "params": "none [, file (string), top_n (u32)=50, max_files (u32)=500].",
      "category": "Evolution & Runtime",
      "tier": "free"
    },
    {
      "name": "co_change_clusters",
      "anchor": "op-co-change-clusters",
      "description": "Cluster symbols that change together across git history (co-change coupling). Returns clusters with support (shared commits) and confidence. Useful for finding hidden coupling and shotgun-surgery risk. Params: none [, min_support (u32)=3, min_confidence (f64)=0.7, max_files (u32)=500]",
      "params": "none [, min_support (u32)=3, min_confidence (f64)=0.7, max_files (u32)=500].",
      "category": "Evolution & Runtime",
      "tier": "architecture"
    },
    {
      "name": "coverage_overlay",
      "anchor": "op-coverage-overlay",
      "description": "Join line coverage onto symbols \u2014 per-symbol covered/hits, plus the count of coverage records that mapped to no symbol. Joins against the current working tree; a disclosure field flags tree-relative unmapped counts and stale-report line drift. Makes test-gap analysis concrete. Auto-detects the report format: lcov, JaCoCo XML, or coverage.py native JSON. Params: report (string, path to a coverage report) [, top_n (u32)]",
      "params": "report (string, path to a coverage report) [, top_n (u32)].",
      "category": "Evolution & Runtime",
      "tier": "architecture"
    },
    {
      "name": "ownership_map",
      "anchor": "op-ownership-map",
      "description": "Map code ownership from git blame \u2014 per-symbol author line shares and a bus factor (smallest author set owning >50% of lines). Low bus factor = knowledge concentration risk. Identities consolidate via .mailmap when present; otherwise fragmentation_hints disclose suspect identity pairs. Workspace-wide results are ranked lowest-bus-factor-first and capped at top_n. Params: none [, file (string), max_files (u32)=500, top_n (u32)=50]",
      "params": "none [, file (string), max_files (u32)=500, top_n (u32)=50].",
      "category": "Evolution & Runtime",
      "tier": "architecture"
    },
    {
      "name": "profile_overlay",
      "anchor": "op-profile-overlay",
      "description": "Join a CPU/sample profile onto symbols \u2014 per-symbol self% / total% / inclusive samples, ranked hottest first, plus an unmapped-frames count. Auto-detects the report format: speedscope JSON, or pprof (gzipped protobuf). Params: report (string, path to a profile report) [, top_n (u32)]",
      "params": "report (string, path to a profile report) [, top_n (u32)].",
      "category": "Evolution & Runtime",
      "tier": "architecture"
    },
    {
      "name": "simulate",
      "anchor": "op-simulate",
      "description": "Simulate structural refactors in-memory and report before/after deltas \u2014 never touches disk (simulated: true). ops is an ordered change script: move_file{from,to}, remove_edge{from,to}, split_file{file,groups:[[symbol]]}, merge_files{files,to}, delete_module{file} (the deletion test \u2014 drops the module and re-wires transitive bridges A\u2192M\u2192B\u21d2A\u2192B). Returns cycles (resolved/introduced), coupling deltas per affected unit, chokepoint centrality changes, deletion deltas for delete_module ops (surface_consumers + surface_modeled \u2014 the load-bearing signal of external symbols calling/extending the module's own surface, plus rewired vs severed file-routing edges), and \u2014 when an [architecture] contract exists in .act/config.toml \u2014 conformance violation deltas (cleared/introduced). Params: ops (required, non-empty) [, include (string[]), exclude (string[])].",
      "params": "ops (required, non-empty) [, include (string[]), exclude (string[])].",
      "category": "Code Health",
      "tier": "architecture"
    },
    {
      "name": "split_module",
      "anchor": "op-split-module",
      "description": "Propose how to split a file into cohesive modules \u2014 detects symbol clusters (label propagation), scores per-cluster cohesion (compute_cohesion), runs compute_extraction on the real workspace graph to produce a file-level extraction_score, and counts boundary edges (seams). Returns a ModuleSplit with confidence_floor=Syntactic, modeled_kinds=[clusters,cohesion,extraction,seams], and proposed_modules sorted by cohesion descending. Params: file (string)",
      "params": "file (string, workspace-relative path)",
      "category": "Structure",
      "tier": "architecture"
    },
    {
      "name": "trace_overlay",
      "anchor": "op-trace-overlay",
      "description": "Join OpenTelemetry spans onto symbols \u2014 per-symbol span count and whether the symbol lies on a trace's critical (longest-duration) path. Shows which code actually runs in production. Auto-detects the report format: OTLP/JSON or OTLP-protobuf. Params: report (string, path to an OTLP trace file) [, top_n (u32)]",
      "params": "report (string, path to an OTLP trace file) [, top_n (u32)].",
      "category": "Evolution & Runtime",
      "tier": "architecture"
    }
  ]
}