Pmad.CodeCondenser 0.0.1

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. 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.
3. 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.
4. CI/CD & AI Agent Guardrails: Enforce strict duplication tolerance in CI pipelines and AI coding agent workflows (exit code 2 on new duplication).

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 pmad-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 pmad-codecondenser [path] [options]
# or:
dotnet tool run pmad-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 pmad-codecondenser (or dotnet pmad-codecondenser when used as a local tool).

pmad-codecondenser [command] [path] [options]

Scenario A: Instant Code Clone Detection (No Comments)

Scan for structural code clones without checking comments:

pmad-codecondenser ./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 Dry-Run (Report Mode - No LLM Required)

When no LLM is configured (or with --report-only), CodeCondenser defaults to report mode:

pmad-codecondenser ./src
# Or explicitly:
pmad-codecondenser ./src --summary report

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 (Summarize Mode)

When an LLM model or endpoint is specified (or configured in codecondenser.json), CodeCondenser defaults to summarize mode:

pmad-codecondenser ./src -m gemma4:e4b
# Or explicitly:
pmad-codecondenser ./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:

# Using the --apply flag:
pmad-codecondenser ./src --apply

# Or using the 'apply' command verb:
pmad-codecondenser apply ./src

Scenario E: Incremental Analysis (Modified Files Only)

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

pmad-codecondenser ./src --incremental

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

Scenario F: Refresh Snapshot Baseline

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

# Using the snapshot command verb:
pmad-codecondenser snapshot ./src

# Or using the --update-snapshot flag:
pmad-codecondenser ./src --update-snapshot

Scenario G: 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:
pmad-codecondenser skills

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

# Preview what files would be created or updated without modifying disk:
pmad-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: |
          pmad-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: pmad-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

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

# Or pipe directly (progress/banners are automatically routed to stderr)
pmad-codecondenser ./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.

pmad-codecondenser ./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]
• 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,
  "duplicationTolerance": 0,
  "duplicationExitCode": 2,
  "commentTolerance": null,
  "commentExitCode": 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 (pmad-codecondenser).

License

MIT License. See LICENSE for details.