Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-architecture-analyze

agentforce-architecture-analyze

Verified

Declared architecture snapshot for one Agentforce agent: planner, topics, actions, flows, Apex, prompt templates, and NGA plugins. Renders a human-readable architecture document and Mermaid invocation graph from design-time metadata (not runtime audit rows). TRIGGER when user asks to describe, diagram, inventory, audit, document, or diff (e.g. v3 vs v5) the architecture / action tree / topic structure / tool inventory of a specific agent by agent API name in a specific org. DO NOT TRIGGER for runtime session traces, conversation transcripts, generation timings, or gateway audit chains — this skill reads design-time metadata only (use agentforce-d360-analyze for session traces).

FileKindSize
README.mdmarkdown8.5 KB
SKILL.mdskill md17.5 KB
assets/cli/describe_sobject.yamlconfig317 B
assets/cli/describe_tooling_sobject.yamlconfig347 B
assets/cli/list_metadata_genaiprompttemplate.yamlconfig342 B
assets/cli/org_display.yamlconfig280 B
assets/cli/retrieve_genai_plugin.yamlconfig391 B
assets/cli/show_access_token.yamlconfig700 B
assets/mermaid/action_tree.mmdother986 B
assets/mermaid/data_flow.mmdother893 B
assets/mermaid/dependency_graph.mmdother810 B
assets/mermaid/invocation_sequence.mmdother1004 B
assets/mermaid/planner_state.mmdother813 B
assets/soql/apex_class_bodies_by_ids.soqlother103 B
assets/soql/apex_class_bodies_by_names.soqlother102 B
assets/soql/bot_definition_details.soqlother152 B
assets/soql/bot_version_lookup.soqlother186 B
assets/soql/flow_definition_by_ids.soqlother115 B
assets/soql/flow_definition_ids_by_names.soqlother146 B
assets/soql/flow_definition_view_by_durable_ids.soqlother180 B
assets/soql/flow_metadata_by_id.soqlother73 B
assets/soql/functions_by_plugins.soqlother317 B
assets/soql/planner_attrs_by_parent_ids.soqlother156 B
assets/soql/planner_bundle_functions.soqlother93 B
assets/soql/planner_definition_by_agent_chain.soqlother174 B
assets/soql/plugin_functions_by_plugin_ids.soqlother93 B
assets/soql/plugin_instructions_by_plugin_ids.soqlother168 B
assets/soql/plugins_by_planner.soqlother199 B
references/architecture_sections.mdmarkdown8.3 KB
references/contract.jsonconfig11.7 KB
references/soql_fields.mdmarkdown24.6 KB
scripts/_shared/__init__.pyscript82 B
scripts/_shared/fs_guard.pyexecutablescript12.8 KB
scripts/_shared/paths.pyscript3.9 KB
scripts/_shared/runtime.pyscript2.0 KB
scripts/_shared/sql.pyscript355 B
scripts/cache_check.pyexecutablescript8.9 KB
scripts/config.pyscript5.9 KB
scripts/emit_env.pyexecutablescript5.1 KB
scripts/emit_result.pyexecutablescript10.7 KB
scripts/fetch_soql.pyscript26.1 KB
scripts/finalize.pyexecutablescript11.8 KB
scripts/main.pyscript113.9 KB
scripts/metadata_listing.pyscript9.5 KB
scripts/parallel_retrieve.pyscript3.3 KB
scripts/parse_bundle.pyexecutablescript7.9 KB
scripts/parse_wave.pyexecutablescript36.1 KB
scripts/probe_channels.pyscript11.1 KB
scripts/render_architecture.pyscript40.0 KB
scripts/resolve_bot.pyexecutablescript9.4 KB
scripts/resolve_invocation_target.pyscript4.8 KB
scripts/rest_client.pyscript33.7 KB
scripts/retrieve_planner.pyscript464 B
scripts/sanitize.pyexecutablescript1013 B
scripts/sf_cli.pyscript12.3 KB
scripts/soql_loader.pyscript11.1 KB
scripts/summarize_tree.pyexecutablescript4.6 KB
scripts/tests/__init__.pyscript0 B
scripts/tests/_bootstrap.pyscript843 B
scripts/tests/fixtures/__init__.pyscript0 B
scripts/tests/fixtures/genai_payloads.pyscript12.5 KB
scripts/tests/test_cache_check.pyscript12.6 KB
scripts/tests/test_cache_check_main.pyscript10.4 KB
scripts/tests/test_config.pyscript3.8 KB
scripts/tests/test_end_to_end_fixture.pyscript26.2 KB
scripts/tests/test_finalize.pyscript11.2 KB
scripts/tests/test_flow_children_inflation.pyscript25.6 KB
scripts/tests/test_fs_guard.pyscript4.3 KB
scripts/tests/test_iterative_wave_b.pyscript19.0 KB
scripts/tests/test_main_pipeline.pyscript145.1 KB
scripts/tests/test_parallel_retrieve.pyscript4.8 KB
scripts/tests/test_parse_bundle.pyscript15.6 KB
scripts/tests/test_parse_wave.pyscript26.9 KB
scripts/tests/test_parse_wave_classifiers.pyscript8.6 KB
scripts/tests/test_parse_wave_helpers.pyscript14.3 KB
scripts/tests/test_parse_wave_main.pyscript16.4 KB
scripts/tests/test_per_branch_visited.pyscript9.5 KB
scripts/tests/test_probe_channels.pyscript13.3 KB
scripts/tests/test_probe_cli_recipes.pyscript8.2 KB
scripts/tests/test_render_architecture.pyscript32.7 KB
scripts/tests/test_resolve_bot.pyscript7.5 KB
scripts/tests/test_resolve_creds.pyscript12.0 KB
scripts/tests/test_resolve_invocation_target.pyscript5.2 KB
scripts/tests/test_rest_client.pyscript49.8 KB
scripts/tests/test_runtime_override.pyscript3.9 KB
scripts/tests/test_sf_cli.pyscript17.3 KB
scripts/tests/test_signature_stamping.pyscript18.0 KB
scripts/tests/test_skill_md_pipeline_block.pyscript12.7 KB
scripts/tests/test_soql_loader.pyscript21.3 KB
scripts/tests/test_summarize_tree.pyscript8.9 KB
scripts/tests/test_write_emit_ctx.pyscript19.2 KB
scripts/write_emit_ctx.pyexecutablescript14.1 KB

scripts/tests/test_parse_wave_helpers.py

View on GitHub
"""Tests for ``parse_wave`` standalone helpers — non-classifier surface.

Covers:
- ``compute_stats``        node count + depth + per-kind counter
- ``finalize_cap``         drains pending → unresolved + sets partial
- ``atomic_write_json``    tmp + os.replace
- ``init_tree``            bundle + bot_def shape
- ``harvest_waves``        Flow XML walking with subflows + actionCalls
"""
from __future__ import annotations

import json
import os
import unittest
from pathlib import Path
from tempfile import TemporaryDirectory

from . import _bootstrap  # noqa: F401  — sys.path setup

import parse_wave  # type: ignore


_FLOW_NS = "http://soap.sforce.com/2006/04/metadata"


# -----------------------------------------------------------------------------
# compute_stats
# -----------------------------------------------------------------------------


class ComputeStatsTests(unittest.TestCase):

    def test_empty_root_returns_zero_counts(self):
        n, d, counts = parse_wave.compute_stats({})
        self.assertEqual(n, 0)
        self.assertEqual(d, 0)
        self.assertEqual(counts, {})

    def test_single_node_counts_kind(self):
        n, d, counts = parse_wave.compute_stats({"kind": "BOT_DEFINITION"})
        self.assertEqual(n, 1)
        self.assertEqual(counts["BOT_DEFINITION"], 1)
        self.assertEqual(d, 0)

    def test_nested_tree_returns_max_depth(self):
        root = {
            "kind": "BOT_DEFINITION",
            "children": [
                {"kind": "TOPIC", "children": [
                    {"kind": "FLOW", "children": [
                        {"kind": "APEX"},
                    ]},
                ]},
                {"kind": "STANDARD_ACTION"},
            ],
        }
        n, d, counts = parse_wave.compute_stats(root)
        self.assertEqual(n, 5)
        self.assertEqual(d, 3)
        self.assertEqual(counts["BOT_DEFINITION"], 1)
        self.assertEqual(counts["TOPIC"], 1)
        self.assertEqual(counts["FLOW"], 1)
        self.assertEqual(counts["APEX"], 1)
        self.assertEqual(counts["STANDARD_ACTION"], 1)


# -----------------------------------------------------------------------------
# finalize_cap
# -----------------------------------------------------------------------------


class FinalizeCapTests(unittest.TestCase):

    def test_drains_pending_into_unresolved(self):
        tree = {
            "_pending_fetches": {
                "FLOW": ["FlowA", "FlowB"],
                "APEX": ["ClassA"],
                "PROMPT_TEMPLATE": [], "STANDARD_ACTION": [],
            },
            "_unresolved": [],
        }
        out = parse_wave.finalize_cap(tree)
        self.assertEqual(len(out["_unresolved"]), 3)
        # Pending wiped per-kind
        for kind in parse_wave.BFS_KINDS:
            self.assertEqual(out["_pending_fetches"][kind], [])
        # _partial flipped
        self.assertTrue(out["_partial"])
        self.assertEqual(out["_partial_reason"], "max-wave-depth")

    def test_does_not_overwrite_existing_partial_reason(self):
        tree = {
            "_pending_fetches": {"FLOW": ["FlowA"], "APEX": [],
                                  "PROMPT_TEMPLATE": [], "STANDARD_ACTION": []},
            "_unresolved": [],
            "_partial_reason": "max-depth-cap",  # earlier-set, more specific
        }
        out = parse_wave.finalize_cap(tree)
        # Reason kept; depth-cap wins priority over wave-depth.
        self.assertEqual(out["_partial_reason"], "max-depth-cap")

    def test_no_pending_no_changes(self):
        tree = {
            "_pending_fetches": {k: [] for k in parse_wave.BFS_KINDS},
            "_unresolved": [],
            "_partial": False,
            "_partial_reason": None,
        }
        out = parse_wave.finalize_cap(tree)
        self.assertEqual(out["_unresolved"], [])
        # Nothing drained, _partial untouched
        self.assertFalse(out["_partial"])

    def test_unresolved_entry_shape(self):
        tree = {
            "_pending_fetches": {"FLOW": ["FlowA"], "APEX": [],
                                  "PROMPT_TEMPLATE": [], "STANDARD_ACTION": []},
            "_unresolved": [],
        }
        out = parse_wave.finalize_cap(tree)
        entry = out["_unresolved"][0]
        self.assertEqual(entry["kind"], "FLOW")
        self.assertEqual(entry["api_name"], "FlowA")
        self.assertEqual(entry["reason"], "max-wave-depth exceeded")


# -----------------------------------------------------------------------------
# atomic_write_json
# -----------------------------------------------------------------------------


class AtomicWriteJsonTests(unittest.TestCase):

    def test_writes_indented_json(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.json"
            parse_wave.atomic_write_json(target, {"a": 1, "b": [1, 2]})
            data = json.loads(target.read_text())
        self.assertEqual(data, {"a": 1, "b": [1, 2]})

    def test_overwrites_existing(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.json"
            target.write_text("old")
            parse_wave.atomic_write_json(target, {"new": True})
            data = json.loads(target.read_text())
        self.assertEqual(data, {"new": True})

    def test_no_tmp_left_behind(self):
        with TemporaryDirectory() as t:
            target = Path(t) / "out.json"
            parse_wave.atomic_write_json(target, {"x": 1})
            tmp_sibling = target.with_suffix(target.suffix + ".tmp")
        self.assertFalse(tmp_sibling.exists())


# -----------------------------------------------------------------------------
# init_tree
# -----------------------------------------------------------------------------


class InitTreeTests(unittest.TestCase):

    def _setup_env(self, **overrides) -> dict:
        defaults = {
            "AGENT_API_NAME": "DemoAgent",
            "AGENT_VERSION": "v3",
            "BOT_ID": "0Xx000000000ABC",
            "BOT_MASTER_LABEL": "Demo Agent",
            "VERSION_AUTO_PICKED": "false",
        }
        defaults.update(overrides)
        return defaults

    def _run(self, *, work_dir: Path, env: dict, bundle: dict) -> dict:
        old = dict(os.environ)
        try:
            os.environ.update(env)
            return parse_wave.init_tree(work_dir, bundle)
        finally:
            os.environ.clear()
            os.environ.update(old)

    def test_initial_tree_shape(self):
        with TemporaryDirectory() as t:
            tree = self._run(
                work_dir=Path(t),
                env=self._setup_env(),
                bundle={"generation": "nga", "plannerName": "MyPlanner",
                        "plannerType": "Atlas__Reasoning"},
            )
        self.assertEqual(tree["_schema_version"], "3.1")
        self.assertEqual(tree["agent"]["api_name"], "DemoAgent")
        self.assertEqual(tree["agent"]["version"], "v3")
        self.assertEqual(tree["agent"]["generation"], "nga")
        self.assertEqual(tree["agent"]["planner_name"], "MyPlanner")
        self.assertEqual(tree["root"]["kind"], "BOT_DEFINITION")
        self.assertEqual(tree["root"]["children"], [])
        self.assertTrue(tree["_partial"])
        self.assertIsNone(tree["_partial_reason"])
        # _pending_fetches has all 4 BFS kinds
        for kind in parse_wave.BFS_KINDS:
            self.assertIn(kind, tree["_pending_fetches"])

    def test_pulls_bot_definition_metadata_from_disk(self):
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            (work_dir / "_bot_definition.json").write_text(json.dumps({
                "result": {"records": [{
                    "DeveloperName": "DemoAgent",
                    "MasterLabel": "Demo (from disk)",
                    "Description": "via _bot_definition.json",
                    "AgentType": "Internal",
                    "Type": "AiCopilot",
                    "AgentTemplate": "TPL",
                    "BotSource": "AgentforceAgentCopilot",
                }]},
            }))
            tree = self._run(
                work_dir=work_dir,
                env=self._setup_env(),
                bundle={"generation": "classic"},
            )
        # MasterLabel from _bot_definition.json wins over env
        self.assertEqual(tree["agent"]["master_label"], "Demo (from disk)")
        self.assertEqual(tree["agent"]["description"], "via _bot_definition.json")
        self.assertEqual(tree["agent"]["agent_type"], "Internal")

    def test_version_auto_picked_flag_propagates(self):
        with TemporaryDirectory() as t:
            tree = self._run(
                work_dir=Path(t),
                env=self._setup_env(VERSION_AUTO_PICKED="true"),
                bundle={"generation": "nga"},
            )
        self.assertTrue(tree["agent"]["_version_auto_picked"])


# -----------------------------------------------------------------------------
# harvest_waves
# -----------------------------------------------------------------------------


def _flow_xml(*, name: str, action_calls: list[dict] | None = None,
              subflows: list[str] | None = None) -> str:
    """Build a minimal Flow XML body."""
    acs = "".join(
        f"""  <actionCalls>
    <name>{ac['name']}</name>
    <actionType>{ac['actionType']}</actionType>
    <actionName>{ac['actionName']}</actionName>
  </actionCalls>
"""
        for ac in (action_calls or [])
    )
    subs = "".join(
        f"""  <subflows>
    <name>sub_{i}</name>
    <flowName>{fn}</flowName>
  </subflows>
"""
        for i, fn in enumerate(subflows or [])
    )
    return f"""<?xml version="1.0" encoding="UTF-8"?>
<Flow xmlns="{_FLOW_NS}">
  <fullName>{name}</fullName>
{acs}{subs}</Flow>
"""


class HarvestWavesTests(unittest.TestCase):

    def _setup_wave(self, work_dir: Path, *, flow_files: dict[str, str],
                    apex_class_names: list[str] | None = None,
                    prompt_template_names: list[str] | None = None) -> None:
        """Plant a wave1/unpackaged/{flows,classes,genAiPromptTemplates}/
        directory tree under work_dir/sf_meta/."""
        wave = work_dir / "sf_meta" / "wave1" / "unpackaged"
        flows_dir = wave / "flows"
        flows_dir.mkdir(parents=True)
        for filename, body in flow_files.items():
            (flows_dir / filename).write_text(body)
        if apex_class_names:
            classes_dir = wave / "classes"
            classes_dir.mkdir()
            for n in apex_class_names:
                (classes_dir / f"{n}.cls-meta.xml").write_text("<x/>")
        if prompt_template_names:
            prompt_dir = wave / "genAiPromptTemplates"
            prompt_dir.mkdir()
            for n in prompt_template_names:
                (prompt_dir / f"{n}.genAiPromptTemplate").write_text("<x/>")

    def test_returns_empty_when_no_sf_meta(self):
        with TemporaryDirectory() as t:
            flow_children, vis, pend, cycles = parse_wave.harvest_waves(Path(t))
        self.assertEqual(flow_children, {})
        self.assertEqual(cycles, [])
        for v in vis.values():
            self.assertEqual(v, set())

    def test_harvests_flow_action_calls_and_subflows(self):
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            self._setup_wave(work_dir, flow_files={
                "MainFlow.flow": _flow_xml(
                    name="MainFlow",
                    action_calls=[
                        {"name": "callA", "actionType": "apex",
                         "actionName": "MyClass"},
                        {"name": "callB", "actionType": "generatePromptResponse",
                         "actionName": "MyPrompt"},
                    ],
                    subflows=["NestedFlow"],
                ),
            })
            flow_children, visited, pending, _cycles = parse_wave.harvest_waves(work_dir)
        # MainFlow visited
        self.assertIn("MainFlow", visited["FLOW"])
        # Apex + prompt-template + nested flow ref harvested into pending
        self.assertIn("MyClass", pending["APEX"])
        self.assertIn("MyPrompt", pending["PROMPT_TEMPLATE"])
        self.assertIn("NestedFlow", pending["FLOW"])
        # MainFlow's children include the apex + prompt-template + subflow
        self.assertEqual(len(flow_children["MainFlow"]), 3)

    def test_apex_classes_marked_visited(self):
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            self._setup_wave(
                work_dir,
                flow_files={"F.flow": _flow_xml(name="F")},
                apex_class_names=["AlreadyApex"],
            )
            _, visited, _, _ = parse_wave.harvest_waves(work_dir)
        self.assertIn("AlreadyApex", visited["APEX"])

    def test_prompt_templates_marked_visited(self):
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            self._setup_wave(
                work_dir,
                flow_files={"F.flow": _flow_xml(name="F")},
                prompt_template_names=["AlreadyPrompt"],
            )
            _, visited, _, _ = parse_wave.harvest_waves(work_dir)
        self.assertIn("AlreadyPrompt", visited["PROMPT_TEMPLATE"])

    def test_already_visited_apex_pruned_from_pending(self):
        """When pass-2/3 marks an Apex class visited AFTER pass-1 routed it
        into pending, the post-pass prune drops it from pending."""
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            self._setup_wave(work_dir,
                             flow_files={"F.flow": _flow_xml(
                                 name="F",
                                 action_calls=[{
                                     "name": "callA", "actionType": "apex",
                                     "actionName": "ClassX",
                                 }],
                             )},
                             apex_class_names=["ClassX"])
            _, visited, pending, _ = parse_wave.harvest_waves(work_dir)
        self.assertIn("ClassX", visited["APEX"])
        # Pruned because already-visited (Apex class file present this wave)
        self.assertNotIn("ClassX", pending["APEX"])

    def test_malformed_flow_xml_returns_empty_children(self):
        with TemporaryDirectory() as t:
            work_dir = Path(t)
            self._setup_wave(work_dir, flow_files={
                "Broken.flow": "<<<not xml>>>",
            })
            flow_children, _, _, _ = parse_wave.harvest_waves(work_dir)
        self.assertEqual(flow_children["Broken"], [])


if __name__ == "__main__":
    unittest.main()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall