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_signature_stamping.py

View on GitHub
"""Tests for Section-7 signature stamping.

Previously, every flow and every Apex class in the rendered architecture
report's Section 7 showed `_Signature not captured._` because Wave B
fetched `SymbolTable` + `Flow.Metadata` but we never projected that data
onto the tree nodes the renderer reads. These tests pin the three
helpers that close the gap:

  * `_derive_apex_signature` — SymbolTable → one-line method signature
  * `_derive_flow_signature` — Flow.Metadata → `in:/out:` param list
  * `_stamp_signatures`     — walks the tree and writes `node["signature"]`

The renderer at `render_architecture.py` reads `node.get("signature")`
already; no renderer change was required.
"""
from __future__ import annotations

import unittest

from . import _bootstrap  # noqa: F401

import main  # type: ignore


# ---------------------------------------------------------------------------
# _derive_apex_signature
# ---------------------------------------------------------------------------


class DeriveApexSignatureTests(unittest.TestCase):
    def test_invocable_method_is_preferred(self):
        """@InvocableMethod is what Flow / Agentforce actually call. If
        present, it MUST be picked over any other method — otherwise the
        rendered signature points at a private helper instead of the
        public entry point."""
        apex_row = {
            "Name": "OrderLookup",
            "SymbolTable": {
                "methods": [
                    {
                        "name": "helper",
                        "returnType": "void",
                        "modifiers": ["private"],
                        "parameters": [{"name": "x", "type": "String"}],
                        "annotations": [],
                    },
                    {
                        "name": "run",
                        "returnType": "List<Result>",
                        "modifiers": ["public", "static"],
                        "parameters": [
                            {"name": "input", "type": "List<Request>"},
                        ],
                        "annotations": [{"name": "InvocableMethod"}],
                    },
                ],
            },
        }
        sig = main._derive_apex_signature(apex_row)
        self.assertEqual(sig, "public static List<Result> run(List<Request> input)")

    def test_no_invocable_falls_back_to_global(self):
        """Without `@InvocableMethod`, a `global` method wins over a
        `private` helper."""
        apex_row = {
            "Name": "Utility",
            "SymbolTable": {
                "methods": [
                    {
                        "name": "privateHelper",
                        "returnType": "void",
                        "modifiers": ["private"],
                        "parameters": [],
                        "annotations": [],
                    },
                    {
                        "name": "publicEntry",
                        "returnType": "String",
                        "modifiers": ["global"],
                        "parameters": [{"name": "id", "type": "Id"}],
                        "annotations": [],
                    },
                ],
            },
        }
        sig = main._derive_apex_signature(apex_row)
        self.assertEqual(sig, "global String publicEntry(Id id)")

    def test_empty_symbol_table_returns_none(self):
        """`SymbolTable = null` is the common case for classes the org
        couldn't compile a symbol table for. Must not raise, must return
        None so the renderer falls back to the `_Signature not captured._`
        placeholder."""
        self.assertIsNone(
            main._derive_apex_signature({"Name": "X", "SymbolTable": None})
        )
        self.assertIsNone(
            main._derive_apex_signature({"Name": "X", "SymbolTable": {}})
        )
        self.assertIsNone(
            main._derive_apex_signature(
                {"Name": "X", "SymbolTable": {"methods": []}}
            )
        )

    def test_no_candidate_methods_returns_none(self):
        """A class whose only method is private AND not invocable has no
        sensible public signature to surface; return None rather than
        expose internal detail."""
        apex_row = {
            "Name": "PrivateOnly",
            "SymbolTable": {
                "methods": [
                    {
                        "name": "hidden",
                        "returnType": "void",
                        "modifiers": ["private"],
                        "parameters": [],
                        "annotations": [],
                    },
                ],
            },
        }
        self.assertIsNone(main._derive_apex_signature(apex_row))


# ---------------------------------------------------------------------------
# _derive_flow_signature
# ---------------------------------------------------------------------------


class DeriveFlowSignatureTests(unittest.TestCase):
    def test_input_and_output_both_present(self):
        """Both sides rendered with ` | ` separator.

        Flow.Metadata exposes a flat `variables[]` list; each item carries
        boolean `isInput` / `isOutput` flags. We partition the list by
        those flags rather than reading the non-existent
        `inputParameters` / `outputParameters` fields.
        """
        record = {
            "Metadata": {
                "variables": [
                    {"name": "caseId", "dataType": "String",
                     "isInput": True, "isOutput": False},
                    {"name": "priority", "dataType": "String",
                     "isInput": True, "isOutput": False},
                    {"name": "result", "dataType": "String",
                     "isInput": False, "isOutput": True},
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(
            sig,
            "in: caseId: String, priority: String | out: result: String",
        )

    def test_only_input_side(self):
        """outputs empty → only `in:` side rendered, no trailing ` | `."""
        record = {
            "Metadata": {
                "variables": [
                    {"name": "caseId", "dataType": "String",
                     "isInput": True, "isOutput": False},
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(sig, "in: caseId: String")

    def test_no_parameters_returns_none(self):
        """No variables at all → None (render falls back to placeholder)."""
        record = {"Metadata": {"variables": []}}
        self.assertIsNone(main._derive_flow_signature(record))
        self.assertIsNone(main._derive_flow_signature({"Metadata": {}}))
        self.assertIsNone(main._derive_flow_signature({}))

    def test_collection_type_rendered_as_list(self):
        """`isCollection: True` on a variable → `List<DataType>` (and for
        sObject variables, the `objectType` feeds the inner type rather
        than the literal `SObject`; case-insensitive match on
        `dataType`)."""
        record = {
            "Metadata": {
                "variables": [
                    {
                        "name": "ids",
                        "dataType": "String",
                        "isCollection": True,
                        "isInput": True,
                        "isOutput": False,
                    },
                    {
                        "name": "cases",
                        "dataType": "sObject",
                        "objectType": "Case",
                        "isCollection": True,
                        "isInput": True,
                        "isOutput": False,
                    },
                    {
                        "name": "result",
                        "dataType": "SObject",   # upper-case variant
                        "objectType": "Account",
                        "isInput": False,
                        "isOutput": True,
                    },
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(
            sig,
            "in: ids: List<String>, cases: List<Case> | out: result: Account",
        )

    def test_round_trip_variable_appears_on_both_sides(self):
        """A variable with `isInput: True` AND `isOutput: True` is a
        round-trip — flows use this for parameters the caller passes in
        and the flow mutates back out. It must appear on BOTH sides of
        the rendered signature."""
        record = {
            "Metadata": {
                "variables": [
                    {"name": "payload", "dataType": "String",
                     "isInput": True, "isOutput": True},
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(
            sig,
            "in: payload: String | out: payload: String",
        )

    def test_derive_flow_signature_local_variables_ignored(self):
        """A variable with `isInput: False` AND `isOutput: False` is a
        flow-local — it exists only inside the flow's execution and is
        not part of its public surface. It must not appear in either
        side of the signature."""
        record = {
            "Metadata": {
                "variables": [
                    {"name": "scratch", "dataType": "String",
                     "isInput": False, "isOutput": False},
                    {"name": "caseId", "dataType": "String",
                     "isInput": True, "isOutput": False},
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(sig, "in: caseId: String")

    def test_derive_flow_signature_handlefaultfault_shape(self):
        """Real-org fixture modeled on `handleFlowFault` from the
        my-org-alias org: 8 variables → 5 inputs, 3 outputs. Pins the
        exact expected signature string end-to-end so that any future
        regression in partitioning, rendering, or ordering surfaces
        immediately."""
        record = {
            "Metadata": {
                "variables": [
                    {"name": "alwaysLogError", "dataType": "Boolean",
                     "isCollection": False, "isInput": True,
                     "isOutput": False, "objectType": None},
                    {"name": "errorCode", "dataType": "String",
                     "isCollection": False, "isInput": False,
                     "isOutput": True, "objectType": None},
                    {"name": "errorMessage", "dataType": "String",
                     "isCollection": False, "isInput": False,
                     "isOutput": True, "objectType": None},
                    {"name": "flowFaultMessage", "dataType": "String",
                     "isCollection": False, "isInput": True,
                     "isOutput": False, "objectType": None},
                    {"name": "flowName", "dataType": "String",
                     "isCollection": False, "isInput": True,
                     "isOutput": False, "objectType": None},
                    {"name": "flowObject", "dataType": "String",
                     "isCollection": False, "isInput": True,
                     "isOutput": False, "objectType": None},
                    {"name": "flowSection", "dataType": "String",
                     "isCollection": False, "isInput": True,
                     "isOutput": False, "objectType": None},
                    {"name": "isFatal", "dataType": "Boolean",
                     "isCollection": False, "isInput": False,
                     "isOutput": True, "objectType": None},
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(
            sig,
            "in: alwaysLogError: Boolean, flowFaultMessage: String, "
            "flowName: String, flowObject: String, flowSection: String | "
            "out: errorCode: String, errorMessage: String, isFatal: Boolean",
        )

    def test_derive_flow_signature_apex_type_uses_apexclass(self):
        """Apex-typed variables (e.g. Flow invocable action return rows)
        carry the concrete class name in `apexClass`, not `dataType`
        (which is the generic literal `Apex`). The signature MUST render
        the concrete class so authors can trace the type back to real
        code — `List<Apex>` is useless."""
        record = {
            "Metadata": {
                "variables": [
                    {
                        "name": "OrgList",
                        "dataType": "Apex",
                        "apexClass": "CX_OrgSelector.Org",
                        "isCollection": True,
                        "isInput": False,
                        "isOutput": True,
                    },
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(sig, "out: OrgList: List<CX_OrgSelector.Org>")

    def test_derive_flow_signature_apex_type_without_apexclass_falls_through(self):
        """Defensive fallback: if `apexClass` is missing/blank on an
        Apex-typed variable we render the literal `Apex` so the surface
        still reports *something* — losing the signature entirely would
        regress today's behavior."""
        record = {
            "Metadata": {
                "variables": [
                    {
                        "name": "rows",
                        "dataType": "Apex",
                        "apexClass": None,
                        "isCollection": True,
                        "isInput": False,
                        "isOutput": True,
                    },
                ],
            },
        }
        sig = main._derive_flow_signature(record)
        self.assertEqual(sig, "out: rows: List<Apex>")

    def test_bare_metadata_dict_accepted(self):
        """Test convenience: callers can pass the `Metadata` dict
        directly (what they'd get from `record["Metadata"]`) without
        wrapping it in the outer Tooling row. Exercised by several
        sibling tests; pin the contract explicitly."""
        bare = {
            "variables": [
                {"name": "caseId", "dataType": "String",
                 "isInput": True, "isOutput": False},
            ],
        }
        sig = main._derive_flow_signature(bare)
        self.assertEqual(sig, "in: caseId: String")


# ---------------------------------------------------------------------------
# _stamp_signatures — walks tree, writes node["signature"]
# ---------------------------------------------------------------------------


class StampSignaturesTests(unittest.TestCase):
    def test_stamp_applies_to_tree(self):
        """APEX + FLOW nodes whose api_name matches the sigs dicts get
        `node["signature"]` populated; unmatched nodes are left alone."""
        tree_root = {
            "kind": "AGENT",
            "api_name": "MyAgent",
            "children": [
                {
                    "kind": "APEX",
                    "api_name": "OrderLookup",
                    "children": [],
                },
                {
                    "kind": "APEX",
                    "api_name": "UnmatchedApex",
                    "children": [],
                },
                {
                    "kind": "FLOW",
                    "api_name": "LookupOrder",
                    "children": [
                        {
                            "kind": "APEX",
                            "api_name": "OrderLookup",
                            "children": [],
                        },
                    ],
                },
            ],
        }
        apex_sigs = {
            "OrderLookup": "public static List<Result> run(List<Request> input)",
        }
        flow_sigs = {
            "LookupOrder": "in: caseId: String | out: result: String",
        }

        main._stamp_signatures(tree_root, apex_sigs, flow_sigs)

        self.assertEqual(
            tree_root["children"][0]["signature"],
            "public static List<Result> run(List<Request> input)",
        )
        # Unmatched Apex stays bare.
        self.assertNotIn("signature", tree_root["children"][1])
        # Flow node gets its signature.
        self.assertEqual(
            tree_root["children"][2]["signature"],
            "in: caseId: String | out: result: String",
        )
        # Apex nested under the flow also stamped.
        self.assertEqual(
            tree_root["children"][2]["children"][0]["signature"],
            "public static List<Result> run(List<Request> input)",
        )
        # Root itself (neither APEX nor FLOW) is untouched.
        self.assertNotIn("signature", tree_root)

    def test_stamp_preserves_shared_utility_across_branches(self):
        """Shared utility flows (e.g. handleFlowFault referenced from N
        places) must get the SAME signature stamped on every occurrence —
        they reference the same FlowDefinition / ApexClass by name."""
        tree_root = {
            "kind": "AGENT",
            "api_name": "Agent",
            "children": [
                {
                    "kind": "FLOW",
                    "api_name": "BranchA",
                    "children": [
                        {
                            "kind": "FLOW",
                            "api_name": "handleFlowFault",
                            "children": [],
                        },
                    ],
                },
                {
                    "kind": "FLOW",
                    "api_name": "BranchB",
                    "children": [
                        {
                            "kind": "FLOW",
                            "api_name": "handleFlowFault",
                            "children": [],
                        },
                    ],
                },
            ],
        }
        flow_sigs = {"handleFlowFault": "in: fault: String"}
        main._stamp_signatures(tree_root, {}, flow_sigs)

        stamp_a = tree_root["children"][0]["children"][0]["signature"]
        stamp_b = tree_root["children"][1]["children"][0]["signature"]
        self.assertEqual(stamp_a, "in: fault: String")
        self.assertEqual(stamp_b, "in: fault: String")
        self.assertEqual(stamp_a, stamp_b)


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