Pmad.CodeCondenser 0.1.0

Pmad.CodeCondenser

A static analysis developer utility and .NET tool built on .NET 10 and Roslyn (Microsoft.CodeAnalysis.CSharp). It analyzes C# codebases to:

1. Detect Structural Code Clones (Type-2 Clones): Identify methods sharing identical AST logic structures (ignoring variable, parameter, and constant renames) and provide actionable refactoring advice.
2. Compact Repeated Inline Strings: Detect string literals >= 100 characters used more than once, with estimated character/token savings, minimal constant declaration snippets, and typical usage patterns. Also detects when inline strings match an existing const or static readonly string (with a lower threshold, default >= 20 characters), recommending referencing the existing constant instead.
3. Condense Verbose Comments: Scan overly verbose regular comments (//, /* */) and XML documentation comments (/// <summary>, <remarks>, <param>) and condense them into clear, concise summaries using local or cloud LLMs via Microsoft.Extensions.AI and Ollama.
4. Enforce Single Type Per File (Automatic Splitting & Renaming): Keep each class, interface, struct, enum, record, or delegate in its own .cs file matching its type name (allowing small inline types like 1-line delegates via configurable line tolerance) to optimize AI agent context window loading and codebase modularity.
5. Detect Lines of Code Limits: Automatically flag methods (> 150 LOC) and classes/records (> 1500 LOC) exceeding maintainability thresholds, excluding comments and blank lines (report-only, no auto-fix).
6. Modernize High-Impact Condensation Patterns: Identify verbose legacy framework calls and C# idioms (e.g. s.ReplaceLineEndings(), string.IsNullOrWhiteSpace(), ??, MinBy/MaxBy, ArgumentNullException.ThrowIfNull) and automatically rewrite them with codecondenser apply.
7. WYSIWYG Guarantee & Incremental Snapshots: Cache generated comment summaries and AST hashes so that dry-run reviews match applied code without LLM drift, while incremental runs only analyze changed code.
8. CI/CD & AI Agent Guardrails: Enforce strict duplication, repeated string, single-type-per-file, and lines-of-code tolerance in CI pipelines and AI coding agent workflows (exit code 2 on new violations).

Prerequisites

• .NET 10 SDK or higher.
• (Optional) Ollama: Only needed for LLM comment summarization. Structural code clone detection is 100% standalone and requires no AI backend.
  • Local Model (Default): Pull the recommended model:

    ollama pull gemma4:e4b
    

  • Cloud Model (Zero local VRAM): Log in to Ollama Cloud with free tier quota:

    ollama login
    

Installation

Pmad.CodeCondenser is distributed as a .NET Tool package on NuGet.org.

1. Install as a .NET Global Tool (Recommended)

Install globally to make the codecondenser command available everywhere on your machine:

dotnet tool install -g Pmad.CodeCondenser --prerelease

To update an existing global installation to the latest version:

dotnet tool update -g Pmad.CodeCondenser --prerelease

2. Install as a Local Tool (Repository / Team Manifest)

For team projects and automated CI pipelines, install Pmad.CodeCondenser as a repository-scoped local tool:

# 1. Create a tool manifest in your repository root (if not already present):
dotnet new tool-manifest

# 2. Add Pmad.CodeCondenser to the manifest:
dotnet tool install Pmad.CodeCondenser --prerelease

Commit the generated .config/dotnet-tools.json file. Team members and CI runners can restore and invoke the tool with:

# Restore tools:
dotnet tool restore

# Run via dotnet:
dotnet codecondenser [path] [options]
# or:
dotnet tool run codecondenser [path] [options]

3. Run Directly from Source

You can also run directly from the cloned repository without installing:

dotnet run --project src/Pmad.CodeCondenser.Cli -- [path] [options]

Quick Start & Core Workflows

The tool binary command is codecondenser (or dotnet codecondenser when used as a local tool).

codecondenser [command] [path] [options]

Scenario A: Clone Detection Only (Fast Dry-Run)

Scan for structural code clones without checking comments:

codecondenser analyze ./src --no-comments

Roslyn parses the syntax trees, normalizes identifier names, statements, and literals, and prints all duplicate method clusters with location details and refactoring guidance.

Scenario B: CI / AI Agent-Friendly Status Report (Report Mode - No LLM Required)

When no LLM is configured (or with codecondenser report), CodeCondenser runs deterministic status reporting:

codecondenser report ./src

Report mode scans both structural code clones and overly verbose comments, printing actionable recommendations and suppression tips (e.g. condense="no" or // codecondenser:ignore) without needing any local or cloud LLM backend.

Scenario C: LLM Comment Summarization (Analyze Mode)

When an LLM model or endpoint is specified, CodeCondenser summarizes verbose comments:

codecondenser analyze ./src -m gemma4:e4b
# Or explicitly:
codecondenser analyze ./src --summary summarize -m gemma4:e4b

Overly verbose comments are condensed using the LLM, and results are safely stored in .codecondenser/snapshot.json without modifying any files on disk.

Scenario D: Apply Summarized Comments to Source Code

Apply the summarized comments directly into your C# source files on disk:

codecondenser apply ./src

Scenario E: Single Type Per File Splitting & Renaming

CodeCondenser automatically ensures that each class, interface, struct, enum, record, or delegate has its own .cs file matching its type name:

# Dry run: view files requiring splitting or renaming
codecondenser analyze ./src

# Apply: split auxiliary types into new .cs files and rename mismatched files
codecondenser apply ./src

• Line Tolerance: Types with pure lines of code (comments and blank lines excluded) within the line tolerance (default: 1, e.g. a one-line delegate) remain inline without triggering a split.
• SDK Compatibility: SDK-style .csproj projects automatically glob newly created .cs files without project file edits.
• Opt-out: Pass --no-type-split to disable splitting or --no-type-rename to disable file renaming.

Scenario F: High-Impact Condensation Patterns (Legacy & LLM Code Modernization)

Developers and LLMs frequently generate verbose, legacy idioms because they are unaware of modern .NET framework methods or modern C# syntax. CodeCondenser identifies these patterns, estimates character and token savings, and can automatically rewrite them in-place with codecondenser apply:

# Dry run: view condensation candidates with token and character savings
codecondenser report ./src

# Apply: rewrite all safe condensation patterns automatically in source code
codecondenser apply ./src

# Target a specific target framework version (e.g. net6.0, net8.0, net10.0)
codecondenser report ./src --patterns-tfm 8.0

# Disable pattern checks entirely or selectively
codecondenser report ./src --no-patterns
codecondenser report ./src --pattern-rules PCC401,PCC402,PCC405

Built-in Condensation Patterns

Scenario G: Incremental Analysis (Modified Files Only)

Analyze only files that were added or modified since the last snapshot baseline:

codecondenser analyze ./src --incremental

In incremental mode, if new duplication, verbose comments, or type violations are detected, CodeCondenser outputs unified actionable feedback only once at the end, complete with suppression instructions (condense="no", // codecondenser:ignore, // codecondenser:ignore-type-split, or [SuppressMessage]).

Scenario H: Refresh Snapshot Baseline

Update or create the baseline snapshot stored in .codecondenser/snapshot.json:

codecondenser snapshot ./src

Scenario I: Install or Update Workspace AI Agent Skills

Install or synchronize the bundled AI agent skills into a workspace's .agents/skills directory so AI coding agents understand how to use Pmad.CodeCondenser:

# Install or update skills in the current workspace:
codecondenser skills

# Target a specific workspace:
codecondenser skills ./my-project

# Preview what files would be created or updated without modifying disk:
codecondenser skills --dry-run

CI/CD & Agent Guardrail Integration

Pmad.CodeCondenser can act as an automated gatekeeper in Pull Requests and CI workflows to block duplicate code introduction or unchecked verbose comments.

When executed with --incremental --duplication-tolerance 0 (and optionally --comment-tolerance 0), the tool compares current changes against the baseline snapshot. If new code clones or verbose comments are introduced, it outputs structured, actionable instructions once at the end and exits with exit code 2, failing the build with clear remediation and suppression steps.

GitHub Actions Workflow Example

name: Static Analysis & Clone Gate

on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup .NET 10 SDK
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Install Pmad.CodeCondenser
        run: dotnet tool install -g Pmad.CodeCondenser --prerelease

      - name: Run Incremental Clone Check with SARIF Export
        id: analyze
        continue-on-error: true
        run: |
          codecondenser ./src \
            --incremental \
            --duplication-tolerance 0 \
            --no-comments \
            --format sarif \
            --output results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always() && github.event.pull_request.head.repo.full_name == github.repository
        with:
          sarif_file: results.sarif
          category: codecondenser

      - name: Enforce Policy Quality Gate
        if: steps.analyze.outcome == 'failure'
        run: |
          echo "::error::Pmad.CodeCondenser detected code duplication exceeding tolerance."
          exit 1

Command-Line Reference

Commands

Options & Flags

Exit Codes

CI/CD, SARIF & Machine-Readable Formats

Pmad.CodeCondenser supports standard SARIF 2.1.0 and structured JSON exports for automated CI/CD integration, PR annotations, and custom quality dashboards:

1. SARIF 2.1.0 Export (--format sarif)

Generates standard OASIS SARIF 2.1.0 compatible with GitHub Code Scanning, GitLab, Azure DevOps, and VS Code.

• Symmetrical PR Diff Annotations: Emits a result for each participating method in a clone cluster with other methods in relatedLocations, guaranteeing that pull requests modifying any duplicate file receive inline PR annotations.
• Alert De-duplication: Includes stable partialFingerprints (astHash/v1 and locationKey/v1) and a deterministic Version 5 UUID correlationGuid to group identical clones on GitHub's Security tab without multiplying alerts.
• Rule Taxonomy:
  • CC001 (warning): ProductionCodeDuplication
  • CC002 (note): TestCodeDuplication
  • CC003 (note): VerboseComment
  • CC004 (warning): CrossBoundaryDuplication
  • CC005 (warning): SubMethodCodeDuplication
  • CC006 (warning): RepeatedInlineString
  • CC007 (warning): SingleTypePerFile
  • CC008 (warning): MethodTooLong
  • CC009 (warning): ClassTooLong

# Export SARIF to file
codecondenser analyze ./src --format sarif --output results.sarif

# Or pipe directly (progress/banners are automatically routed to stderr)
codecondenser analyze ./src --format sarif > results.sarif

2. Structured JSON Export (--format json)

Outputs a versioned JSON report conforming to the schemas/codecondenser-report.json schema, including full metrics, cluster impact scores, AST hashes, line numbers, and actionable recommendations.

codecondenser analyze ./src --format json --output results.json

Suppression Markers & Persistent Storage

1. XML Documentation Formatting (120 Columns & Summary Tags)

• Missing <summary> Tags: XML documentation comments missing <summary> tags automatically have them added.
• 120 Columns Line Length: Comments are formatted and word-wrapped so that every line stays within 120 columns (including indentation and comment prefixes), while preserving inline tags (e.g. <see cref="..."/>, <c>...</c>).

2. Persistent Summarized Comments (.codecondenser/summarized-comments.json)

Even summarized comments might exceed the character threshold (e.g. 110 characters). To ensure they are not re-analyzed or flagged across new sessions or clean checkouts:

• Applied summaries are saved to .codecondenser/summarized-comments.json, which should be committed to Git.
• .codecondenser/snapshot.json remains scoped to the local agent/developer session and should be gitignored:

# CodeCondenser: ignore session-scoped snapshot cache, commit summarized comments store
/.codecondenser/snapshot.json

3. Suppression & Ignore Markers

• Ignore a Regular Comment: Use // codecondenser:ignore or // nocondense on the line preceding the comment, or embed codecondenser:ignore / nocondense inside the comment.
• Ignore an XML Documentation Comment: Add condense="no" (or condense="false", nocondense="true", nocondense) as an attribute on any XML tag, e.g.:
  • <summary condense="no">...</summary>
  • <summary condense="false">...</summary>
  • <summary nocondense="true">...</summary>
  • <remarks condense="no">...</remarks>
• Ignore Code Duplication on a Method:
  • Comment above or inside method: // codecondenser:ignore-duplicate or // codecondenser:ignore
  • Attribute on method: [SuppressMessage("CodeCondenser", "Duplication")] or [CodeCondenserIgnore]
• Ignore a Repeated Inline String:
  • Comment on the line preceding or inline: // codecondenser:ignore-string or // nocondense
  • Attribute on enclosing member or class: [SuppressMessage("CodeCondenser", "RepeatedString")]
• Ignore Single Type Per File Splitting:
  • Comment on secondary type: // codecondenser:ignore-type-split or // codecondenser:ignore
  • Attribute on secondary type: [SuppressMessage("CodeCondenser", "SingleTypePerFile")] or [SingleTypePerFileIgnore]
• Ignore Lines of Code Limits on a Method or Class:
  • Comment above declaration: // codecondenser:ignore-loc or // noloc
  • Attribute on method: [SuppressMessage("CodeCondenser", "MethodLength")] or [LinesOfCodeIgnore]
  • Attribute on class: [SuppressMessage("CodeCondenser", "ClassLength")] or [LinesOfCodeIgnore]
• Standalone Ignore File (.codecondenserignore): Add glob patterns (like .gitignore) to a .codecondenserignore file in the repository root to exclude directories or files without modifying codecondenser.json.

Configuration (codecondenser.json)

Pmad.CodeCondenser automatically looks for a codecondenser.json configuration file in the target directory or working directory:

{
  "include": [
    "src/**"
  ],
  "exclude": [
    "**/Migrations/**",
    "**/bin/**",
    "**/obj/**"
  ],
  "useDefaultExcludes": true,
  "excludeTests": false,
  "enforceTestDuplication": false,
  "testPaths": [
    "tests/**",
    "test/**",
    "**/*.Tests/**",
    "**/*.Test/**",
    "**/*Test.cs",
    "**/*Tests.cs"
  ],
  "excludeGeneratedCode": true,
  "generatedCodePatterns": [
    "**/*.Designer.cs",
    "**/*.g.cs",
    "**/*.generated.cs",
    "**/*ModelSnapshot.cs",
    "**/Migrations/**"
  ],
  "summaryMode": "Report",
  "enableCommentSummarization": true,
  "enableDuplicationDetection": true,
  "enableRepeatedStringDetection": true,
  "enableTypeSplitting": true,
  "enableTypeRenaming": true,
  "typeLineTolerance": 1,
  "typeTolerance": null,
  "typeExitCode": 2,
  "enableLinesOfCodeDetection": true,
  "methodLinesOfCodeThreshold": 150,
  "classLinesOfCodeThreshold": 1500,
  "linesOfCodeTolerance": null,
  "linesOfCodeExitCode": 2,
  "duplicationTolerance": 0,
  "duplicationExitCode": 2,
  "commentTolerance": null,
  "commentExitCode": 2,
  "repeatedStringTolerance": null,
  "repeatedStringExitCode": 2,
  "repeatedStringLengthThreshold": 100,
  "existingConstantStringLengthThreshold": 20,
  "repeatedStringMinOccurrences": 2,
  "commentLengthThreshold": 100,
  "xmlSummaryLengthThreshold": 100,
  "xmlParamLengthThreshold": 50,
  "maxCommentLineLength": 120,
  "duplicationStatementThreshold": 8,
  "includeXmlDocumentation": true,
  "maxParallelLlmRequests": 4,
  "provider": "Ollama",
  "ollama": {
    "endpoint": "http://localhost:11434",
    "model": "gemma4:e4b",
    "contextSize": 24576
  },
  "snapshotFilePath": ".codecondenser/snapshot.json",
  "summarizedCommentsFilePath": ".codecondenser/summarized-comments.json"
}

CLI options override settings from codecondenser.json.

Global User Profile Configuration

To avoid committing personal LLM endpoints, local ports, or credentials into shared repository configuration files, Pmad.CodeCondenser supports a global user profile configuration file:

• Location:
  • Windows: %APPDATA%\CodeCondenser\codecondenser.json or %APPDATA%\CodeCondenser\config.json (fallback: %USERPROFILE%\.codecondenser\codecondenser.json)
  • Linux / macOS: ~/.codecondenser/codecondenser.json or ~/.codecondenser/config.json (fallback: ~/.codecondenser.json)
• Environment Variable Override: CODECONDENSER_GLOBAL_CONFIG or PMAD_CODECONDENSER_GLOBAL_CONFIG (or directory override via CODECONDENSER_APPDATA / CODECONDENSER_USER_PROFILE)
• CLI Flags: --global-config <path> to specify a custom path, or --no-global-config to bypass global profile loading entirely.

Hierarchical Precedence

Settings are resolved in the following priority order (highest to lowest):

1. CLI Arguments (--model, --endpoint, --summary, etc.)
2. Project Configuration (codecondenser.json in the target or repository root)
3. Global User Profile Configuration (%APPDATA%\CodeCondenser\codecondenser.json on Windows, ~/.codecondenser/codecondenser.json on Linux/macOS)
4. Built-in Defaults

Example Global Config (codecondenser.json)

{
  "provider": "Ollama",
  "ollama": {
    "endpoint": "http://localhost:11434",
    "model": "gemma4:e4b",
    "contextSize": 24576
  },
  "maxParallelLlmRequests": 4
}

Comment Summarization Benchmark & Model Selection

To identify optimal models for comment condensation, a comprehensive benchmark was conducted evaluating local and cloud Ollama candidates against comments extracted from reference projects (ComicGenCLI, NightCodeForge, HugeImages, Pmad.Git), evaluated by Qwen3.6-35B-A3B:latest (Temperature: 0.0, strict multi-criteria JSON scoring):

Model Recommendations by Environment

• Dedicated GPU (>= 8–12 GB VRAM): Use gemma4:e4b (default). 100% offline, 200+ tok/s, top-tier fidelity.
• Limited VRAM / Running in Parallel with Primary Coding LLM (Cloud Models):
  • Highest Quality: Use gpt-oss:20b-cloud (-m gpt-oss:20b-cloud). Ties with gemma4:e4b at 9.92/10, highest accuracy (9.88/10), and uses 0 GB local VRAM.
  • Fastest Cloud: Use nemotron-3-nano:30b-cloud (-m nemotron-3-nano:30b-cloud). Sub-second response (424 ms average), 9.68/10 score, and uses 0 GB local VRAM.

ollama login

For full benchmark methodology, CLI runner, and qualitative side-by-side case studies, see src/Pmad.CodeCondenser.Benchmark/README.md.

Architecture

• Pmad.CodeCondenser.Core: Domain models, AST normalization (AstNormalizer), clone detection (CloneDetector), comment extraction (VerboseCommentExtractor), Roslyn trivia rewriting (VerboseCommentRewriter), incremental diffing (SnapshotDiffer), and analysis engine (CodeCondenserEngine).
• Pmad.CodeCondenser.Infrastructure: LLM integration via Microsoft.Extensions.AI and OllamaSharp (CommentSummarizer), and snapshot JSON storage (JsonSnapshotStore).
• Pmad.CodeCondenser.Cli: Command-line interface with color-coded formatting and packaging as a packable .NET tool (codecondenser).

License

MIT License. See LICENSE for details.