sf-agentpmd 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bobby White
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,26 @@
+sf-agentpmd
+Copyright (c) 2026 Bobby White
+
+This product is licensed under the MIT License (see LICENSE).
+
+------------------------------------------------------------------------
+Third-party components
+------------------------------------------------------------------------
+
+This product bundles components from the AgentScript project by
+Salesforce, Inc., which are licensed under the Apache License, Version 2.0.
+The MIT license of this product does NOT apply to these vendored components;
+they remain governed by their original Apache-2.0 license.
+
+  Project:   AgentScript (https://github.com/salesforce/agentscript)
+  Copyright: Copyright (c) 2026 Salesforce, Inc.
+  License:   Apache License, Version 2.0
+             (https://www.apache.org/licenses/LICENSE-2.0)
+
+  Vendored packages and on-disk locations:
+    - @agentscript/types@0.2.1
+        vendor/agentscript-types/
+    - @agentscript/parser-javascript@2.4.0
+        vendor/agentscript-parser-javascript/
+
+A copy of the Apache License, Version 2.0 is available at the URL above.

package/README.md

@@ -0,0 +1,204 @@
+# sf-agentpmd
+
+SF CLI plugin that computes **standard McCabe cyclomatic complexity** for
+[AgentScript](https://github.com/salesforce/agentscript) (`.agent`) files,
+along with an inventory of declared and referenced agent actions.
+
+The intent (per `docs/agent-loc-categorization-skill-v2.md` § 7) is the
+by-the-book number a SonarQube / PMD / Checkstyle run would produce — but
+applied to the AgentScript surface that those tools don't cover today.
+
+## Current scope (v2)
+
+`sf agentpmd analyze [--source-dir <dir|file>] [--apex-source <dir>] [--fail-on N]`
+
+If `--source-dir` is omitted, the plugin walks up from cwd looking for
+`sfdx-project.json` and uses its `packageDirectories` as the source roots.
+Run it from anywhere inside an sfdx project and it just works.
+
+- Walks every `.agent` file under the resolved source roots.
+- For each `before_reasoning:`, `after_reasoning:`, and
+  `reasoning.instructions:` block, computes McCabe CC:
+
+  ```
+  CC = 1
+     + count(if_statement)
+     + count(elif_clause)
+     + count(ternary_expression)
+     + count(binary_expression where operator ∈ {and, or})
+  ```
+
+- Reports CC per procedure, per scope (`topic` / `start_agent` / `subagent`),
+  per file, and a total across files.
+- Collects all `actions:` declarations and classifies their `target:` URI
+  (`apex://`, `flow://`, `prompt://`, …).
+- Counts how many times each declared action is referenced from
+  `reasoning.actions`, `reasoning.instructions`, `before_reasoning`,
+  `after_reasoning`, and `transition` statements.
+- For every `apex://ClassName` target, resolves the `.cls` file by walking
+  up from the `.agent` location looking for a sibling `classes/` directory
+  (or honors `--apex-source <dir>`), parses it with
+  `@apexdevtools/apex-parser`, and computes per-method McCabe CC for every
+  method and constructor with a body:
+
+  ```
+  CC = 1
+     + count(if)
+     + count(for)         // includes enhanced-for
+     + count(while)
+     + count(do-while)
+     + count(when arm)    // each switch `when X { ... }`; `when else` excluded
+     + count(catch)
+     + count(ternary ?:)
+     + count(&&)
+     + count(||)
+  ```
+
+- Emits a **CC by location** rollup (AgentScript vs. Apex vs. Combined),
+  matching the whitepaper § 7 framing.
+
+### Flags
+
+| Flag | Purpose |
+| --- | --- |
+| `-d, --source-dir <path>` | Directory or single `.agent` file. Optional. Defaults to the `packageDirectories` of the nearest `sfdx-project.json`. |
+| `-n, --api-name <X>` | Filter to a specific bundle. Matches the bundle directory name **or** `config.developer_name:` inside the `.agent`. Repeat for multiple bundles. |
+| `--apex-source <path>` | Override directory for resolving `apex://` targets. Default: walk up from each `.agent` looking for a `classes/` sibling. |
+| `--format <fmt>` | Non-JSON output format: `text` (default), `markdown`, `sarif`, `csv`. Ignored when `--json` is set. |
+| `--width <N>` | Rule width for the text renderer. Default 60. |
+| `--ascii` | Force ASCII-only output in the text renderer (no emoji / box chars). Auto-enabled on non-TTY stdout. |
+| `--no-color` | Disable ANSI color. `NO_COLOR` env var also disables. |
+| `--sarif-warning <N>` / `--sarif-error <N>` | Override the SARIF level thresholds. Defaults 10 / 20. |
+| `--fail-on <N>` | Exit non-zero (code 2) if **combined** (agent + Apex) CC ≥ N. Useful in CI. |
+| `--json` | Machine-readable SF CLI envelope on stdout. Takes precedence over `--format`. |
+
+### Output formats at a glance
+
+| Format | When to use | Surface |
+| --- | --- | --- |
+| `text` (default) | Terminal eyeballs. | Color-coded, palette-aligned (red/yellow/green/gray by CC band). Auto-degrades to ASCII on non-TTY. |
+| `markdown` | PR descriptions, gists, whitepaper appendices. | Mermaid `xychart-beta` bar chart at top (AgentScript red vs Apex green) + per-bundle and per-class tables. |
+| `sarif` | GitHub Code Scanning / IDE annotations / CI. | SARIF 2.1.0 with one result per procedure / per method. Level driven by complexity thresholds. |
+| `csv` | Spreadsheet pivots, posture-comparison matrices. | One row per procedure or Apex method. RFC-4180 quoted. |
+| `--json` | Machine consumers (e.g. another sf plugin). | SF CLI envelope around the full `AnalysisReport`. |
+
+### Example
+
+```
+$ sf agentpmd analyze -d ./force-app/main/default/aiAuthoringBundles
+AgentForce PMD — Cyclomatic Complexity (McCabe)
+════════════════════════════════════════════════════════════
+
+📄 case_escalation_bot.agent   CC=31
+────────────────────────────────────────────────────────────
+  start_agent customer_verification   subtotal CC=8
+    before_reasoning         CC=2   if=1
+    after_reasoning          CC=5   if=3 and=1
+    reasoning.instructions   CC=1   (base only)
+  …
+```
+
+## Roadmap
+
+- **v3** — implement the four-category LOC rule from
+  `docs/agent-loc-categorization-skill-v2.md` (Scaffolding, Deterministic
+  Logic, Reasoning Logic, Conversation Surface) as a separate sub-command
+  (`sf agentpmd categorize-loc`).
+- **future** — Flow incorporation (§ 9 of the whitepaper) once a CC analog
+  for Flow elements is settled.
+
+## How it parses
+
+We do **not** use heuristic regex scanners. Two real parsers do the work:
+
+- **AgentScript** — the hand-written TypeScript parser in
+  [`@agentscript/parser-javascript`](https://github.com/salesforce/agentscript/tree/main/packages/parser-javascript),
+  vendored under `vendor/` because the upstream package isn't published to
+  npm yet.
+- **Apex** — [`@apexdevtools/apex-parser`](https://github.com/apex-dev-tools/apex-parser)
+  v5.0.0, an actively-maintained ANTLR4 TypeScript port. Pure-Node, no JVM.
+
+To resync the vendor copies after pulling new upstream commits:
+
+```
+./scripts/sync-vendor.sh
+```
+
+That copies the freshly-built `dist/` from
+`$AGENTSCRIPT_REPO/packages/{types,parser-javascript}` into
+`vendor/agentscript-{types,parser-javascript}/dist/`.
+
+## Layout
+
+```
+src/
+  commands/agentpmd/analyze.ts   # sf agentpmd analyze
+  analyzer/
+    parse.ts                     # AgentScript CST helpers
+    complexity.ts                # AgentScript McCabe CC walker
+    action-references.ts         # @actions.X declarations & references
+    apex-parse.ts                # @apexdevtools/apex-parser wrappers
+    apex-complexity.ts           # Apex McCabe CC walker
+    apex-resolve.ts              # apex://ClassName → .cls path resolver
+    apex-analyze.ts              # orchestrator for the Apex pass
+    analyze.ts                   # file discovery + top-level orchestrator
+    report.ts                    # text/json rendering (incl. § 7 split)
+    types.ts                     # public types
+  index.ts                       # programmatic entry
+test/
+  fixtures/                      # synthetic + gametwo fixtures
+  analyzer/*.spec.ts             # vitest unit + integration tests
+vendor/
+  agentscript-types/             # vendored from agentscript monorepo
+  agentscript-parser-javascript/
+scripts/
+  sync-vendor.sh
+docs/
+  agent-loc-categorization-skill-v2.md   # the categorization rule
+```
+
+## Development
+
+```
+npm install
+npm run build
+npm test
+node bin/dev.js agentpmd analyze --source-dir test/fixtures
+```
+
+The plugin uses ESM throughout and targets Node ≥ 20.
+
+## Claude Code skill
+
+The plugin ships with a bundled Claude Code skill (at `skill/` in the repo)
+that wraps the plugin from an adopter's point of view — discovery,
+install, upgrade, and output interpretation. It auto-triggers when a
+Claude session mentions `sf agentpmd`, "AgentScript cyclomatic
+complexity", or related phrases.
+
+**Activate the skill.** After installing the plugin, run:
+
+```bash
+sf agentpmd install-skill
+```
+
+This recursively copies the bundled skill tree to
+`~/.claude/skills/agentforcepmd/`. Restart Claude Code (or reload skills)
+to activate it.
+
+Local-dev contributors can instead symlink the in-repo `skill/` directory
+(it moved from `.claude/skills/agentforcepmd/` to `skill/`) so edits show
+up live:
+
+```bash
+ln -sfn "$(pwd)/skill" ~/.claude/skills/agentforcepmd
+```
+
+The skill's `SKILL.md` indexes four reference pages:
+
+- `references/command-structure.md` — every flag, defaults, exit codes
+- `references/install.md` — both pre- and post-publication install paths
+- `references/upgrade.md` — refresh dance for a linked checkout, plus
+  `sf plugins update` for the published case
+- `references/output-formats.md` — text / JSON / markdown / SARIF / CSV
+  surface with examples, plus a "pick a format" cheat sheet

package/bin/dev.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+
+import {execute} from '@oclif/core'
+
+await execute({development: true, dir: import.meta.url})

package/bin/run.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { execute } from '@oclif/core';
+await execute({ dir: import.meta.url });

package/dist/analyzer/action-references.d.ts

@@ -0,0 +1,21 @@
+import type { AgentScope } from './complexity.js';
+import type { ActionDeclaration, ActionReference } from './types.js';
+/**
+ * Within a scope body (the value of a `topic` or `start_agent`/`subagent`
+ * mapping_element), the `actions:` entry holds a mapping of named action
+ * declarations. Each declaration is itself a mapping with metadata fields
+ * like `target:`, `label:`, `inputs:`, `outputs:`.
+ */
+export declare function collectDeclarations(scope: AgentScope): ActionDeclaration[];
+/**
+ * Collect every member_expression of the form `@actions.X` *outside* the
+ * `actions:` declaration block. We treat them as references — i.e. usages of
+ * the declared actions in reasoning / before / after blocks.
+ *
+ * Context discrimination:
+ *   • inside reasoning > actions  → 'reasoning_actions'
+ *   • inside after_reasoning      → 'after_reasoning_run'
+ *   • inside before_reasoning     → 'before_reasoning_run'
+ *   • inside transition_statement → 'transition'
+ */
+export declare function collectReferences(scope: AgentScope): ActionReference[];

package/dist/analyzer/action-references.js

@@ -0,0 +1,130 @@
+import { descendants, extractStringLiteral, findMappingEntry, locOf, mappingKeyHeader, mappingValue, } from './parse.js';
+const TARGET_SCHEME = /^([a-z][a-z0-9+.-]*):\/\//i;
+function classifyTarget(uri) {
+    if (!uri)
+        return 'unknown';
+    const m = TARGET_SCHEME.exec(uri);
+    if (!m)
+        return 'unknown';
+    const scheme = m[1].toLowerCase();
+    if (scheme === 'apex')
+        return 'apex';
+    if (scheme === 'flow')
+        return 'flow';
+    if (scheme.startsWith('prompt'))
+        return 'prompt';
+    return 'unknown';
+}
+/**
+ * Within a scope body (the value of a `topic` or `start_agent`/`subagent`
+ * mapping_element), the `actions:` entry holds a mapping of named action
+ * declarations. Each declaration is itself a mapping with metadata fields
+ * like `target:`, `label:`, `inputs:`, `outputs:`.
+ */
+export function collectDeclarations(scope) {
+    const decls = [];
+    const actionsBlock = findMappingEntry(scope.body, 'actions');
+    if (!actionsBlock)
+        return decls;
+    for (const child of actionsBlock.namedChildren) {
+        if (child.type !== 'mapping_element')
+            continue;
+        const h = mappingKeyHeader(child);
+        if (!h)
+            continue;
+        const declName = h.kind;
+        const declBody = mappingValue(child);
+        if (!declBody) {
+            decls.push({
+                location: locOf(child),
+                name: declName,
+                scope: scope.label,
+                target: undefined,
+                targetKind: 'unknown',
+            });
+            continue;
+        }
+        const targetVal = findMappingEntry(declBody, 'target');
+        const targetStr = targetVal ? extractStringLiteral(targetVal) : undefined;
+        decls.push({
+            location: locOf(child),
+            name: declName,
+            scope: scope.label,
+            target: targetStr,
+            targetKind: classifyTarget(targetStr),
+        });
+    }
+    return decls;
+}
+/**
+ * Collect every member_expression of the form `@actions.X` *outside* the
+ * `actions:` declaration block. We treat them as references — i.e. usages of
+ * the declared actions in reasoning / before / after blocks.
+ *
+ * Context discrimination:
+ *   • inside reasoning > actions  → 'reasoning_actions'
+ *   • inside after_reasoning      → 'after_reasoning_run'
+ *   • inside before_reasoning     → 'before_reasoning_run'
+ *   • inside transition_statement → 'transition'
+ */
+export function collectReferences(scope) {
+    const refs = [];
+    const explore = (body, context) => {
+        if (!body)
+            return;
+        for (const n of descendants(body)) {
+            if (n.type !== 'member_expression')
+                continue;
+            // member_expression text is the full chain ("@actions.Foo[.Bar]");
+            // text matching is more robust than peeking through the wrapper
+            // chain (expression → atom → at_id).
+            if (!n.text.startsWith('@actions.'))
+                continue;
+            const name = actionNameFromMember(n);
+            if (!name)
+                continue;
+            // Differentiate when we're inside a transition_statement.
+            const ctx = isInsideTransition(n) ? 'transition' : context;
+            refs.push({
+                context: ctx,
+                location: locOf(n),
+                name,
+                scope: scope.label,
+            });
+        }
+    };
+    explore(findMappingEntry(scope.body, 'before_reasoning'), 'before_reasoning_run');
+    explore(findMappingEntry(scope.body, 'after_reasoning'), 'after_reasoning_run');
+    const reasoning = findMappingEntry(scope.body, 'reasoning');
+    if (reasoning) {
+        // `reasoning.actions:` — the declarative action contract block;
+        // refs here describe what the LLM is allowed to call.
+        explore(findMappingEntry(reasoning, 'actions'), 'reasoning_actions');
+        // `reasoning.instructions: ->` — refs here are `run @actions.X`
+        // invocations the LLM evaluates as part of its instructions.
+        // Per the whitepaper, these execute non-deterministically.
+        explore(findMappingEntry(reasoning, 'instructions'), 'reasoning_instructions_run');
+    }
+    return refs;
+}
+function actionNameFromMember(n) {
+    // member_expression text is "@actions.Foo_Bar" — strip the prefix.
+    const t = n.text;
+    const dot = t.indexOf('.');
+    if (dot === -1)
+        return undefined;
+    const rest = t.slice(dot + 1);
+    // Take the leading identifier, in case of further chained access.
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)/.exec(rest);
+    return m?.[1];
+}
+function isInsideTransition(n) {
+    let p = n.parent;
+    while (p) {
+        if (p.type === 'transition_statement')
+            return true;
+        p = p.parent;
+    }
+    return false;
+}
+//# sourceMappingURL=action-references.js.map

package/dist/analyzer/action-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-references.js","sourceRoot":"","sources":["../../src/analyzer/action-references.ts"],"names":[],"mappings":"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"}

package/dist/analyzer/analyze.d.ts

@@ -0,0 +1,43 @@
+import type { AnalysisReport, FileReport } from './types.js';
+export interface AnalyzeOptions {
+    /** Override location for apex:// resolution. Optional. */
+    apexSourceOverride?: string;
+    /**
+     * Filter to specific agent bundles by API name. Each entry is matched
+     * against (a) the bundle directory name and (b) `config.developer_name`
+     * inside the .agent file. When omitted or empty, all discovered bundles
+     * are analyzed.
+     */
+    apiNames?: string[];
+    /**
+     * Base directory for relative paths in the report. Defaults to the source
+     * root (or, when multiple roots are supplied, the longest common ancestor).
+     */
+    reportBase?: string;
+}
+/**
+ * Error thrown when --api-name filters produce no matches. Carries the
+ * candidate list so callers can show a useful hint.
+ */
+export declare class NoMatchingBundlesError extends Error {
+    readonly requested: string[];
+    readonly available: BundleIdentity[];
+    constructor(requested: string[], available: BundleIdentity[]);
+}
+export interface BundleIdentity {
+    /** The config.developer_name value, if present. */
+    developerName: string | undefined;
+    /** The bundle's directory name (parent of the .agent file). */
+    dirName: string;
+    /** Absolute path of the .agent file. */
+    path: string;
+}
+/**
+ * Analyze AgentScript bundles under one or more source roots.
+ *
+ * Backward-compatible: pass a single path (string) for the legacy
+ * single-root case. Pass an array of paths for multi-root analysis
+ * (e.g. multiple `packageDirectories` in an sfdx project).
+ */
+export declare function analyzeSource(rootPathOrPaths: string | string[], options?: AnalyzeOptions): Promise<AnalysisReport>;
+export declare function analyzeFile(absPath: string, base: string): Promise<FileReport>;