Skip to content

lasp/adamant-skills / adamant-tools

adamant-tools

Verified

FileKindSize
SKILL.mdskill md8.0 KB
adamant_env.shexecutablescript2.5 KB
adamant_inspect.pyscript22.4 KB
adamant_scaffold.pyscript25.3 KB
adamant_style_check.pyexecutablescript12.4 KB
adamant_validate_yaml.pyscript15.8 KB

adamant_inspect.py

View on GitHub
#!/usr/bin/env python3
"""
adamant_inspect.py - Extract and summarize the generated API for an Adamant component.

Parses generated Ada spec files from build/src/ and build/template/ to produce
a concise summary of the component's API: connectors, methods to override,
available helpers, events, data products, commands, parameters, faults, and
data dependencies.

Usage:
    python3 adamant_inspect.py <component_dir>

Example:
    python3 adamant_inspect.py src/components/voltage_monitor

Output is plain text, suitable for pasting into a prompt or reading in a terminal.
"""

import sys
import os
import re
import glob


def find_files(component_dir):
    """Locate generated spec files."""
    build_src = os.path.join(component_dir, "build", "src")
    build_template = os.path.join(component_dir, "build", "template")
    test_build_src = os.path.join(component_dir, "test", "build", "src")
    test_build_template = os.path.join(component_dir, "test", "build", "template")

    result = {
        "base_spec": None,
        "events": None,
        "data_products": None,
        "commands": None,
        "parameters": None,
        "faults": None,
        "data_dependencies": None,
        "tester_spec": None,
        "impl_template": None,
    }

    if not os.path.isdir(build_src):
        return result

    # Component name from directory
    comp_name = os.path.basename(os.path.normpath(component_dir))

    for f in glob.glob(os.path.join(build_src, "*.ads")):
        base = os.path.basename(f)
        if base == f"component-{comp_name}.ads":
            result["base_spec"] = f
        elif base == f"{comp_name}_events.ads":
            result["events"] = f
        elif base == f"{comp_name}_data_products.ads":
            result["data_products"] = f
        elif base == f"{comp_name}_commands.ads":
            result["commands"] = f
        elif base == f"{comp_name}_parameters.ads":
            result["parameters"] = f
        elif base == f"{comp_name}_faults.ads":
            result["faults"] = f
        elif base == f"{comp_name}_data_dependencies.ads":
            result["data_dependencies"] = f

    # Template files
    template = os.path.join(build_template, f"component-{comp_name}-implementation.ads")
    if os.path.isfile(template):
        result["impl_template"] = template

    tester = os.path.join(test_build_template, f"component-{comp_name}-implementation-tester.ads")
    if os.path.isfile(tester):
        result["tester_spec"] = tester

    return result


def extract_sections(text):
    """Split Ada spec into logical sections based on comment headers."""
    sections = []
    current_header = "Header"
    current_lines = []
    for line in text.splitlines():
        # Match section headers like "-- Invokee connector primitives:"
        m = re.match(r"^\s*-+\s*$", line)
        if m:
            # Check if previous line was a comment header
            if current_lines and re.match(r"^\s*--\s+\S", current_lines[-1]):
                header_line = current_lines.pop()
                if current_lines:
                    sections.append((current_header, "\n".join(current_lines)))
                current_header = header_line.strip().lstrip("- ").rstrip(":")
                current_lines = []
                continue
        current_lines.append(line)
    if current_lines:
        sections.append((current_header, "\n".join(current_lines)))
    return sections


def extract_abstract_procedures(text):
    """Extract abstract procedure/function declarations."""
    results = []
    # Multi-line aware: join continuation lines
    joined = re.sub(r"\n\s+", " ", text)
    for m in re.finditer(
        r"(not overriding\s+(?:procedure|function)\s+\w+\s*(?:\([^)]*\))?[^;]*)\s+is\s+abstract",
        joined,
    ):
        sig = m.group(1).strip()
        # Clean up whitespace
        sig = re.sub(r"\s+", " ", sig)
        results.append(sig)
    return results


def extract_concrete_procedures(text, section_name=""):
    """Extract concrete (non-abstract) procedure/function declarations in private section."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)
    for m in re.finditer(
        r"(not overriding\s+(?:procedure|function)\s+(\w+)\s*(?:\([^)]*\))?(?:\s*return\s+[^;]+)?)",
        joined,
    ):
        full = m.group(1).strip()
        name = m.group(2)
        # Skip abstract ones
        after = joined[m.end():m.end() + 30]
        if "is abstract" in after:
            continue
        full = re.sub(r"\s+", " ", full)
        results.append((name, full))
    return results


def extract_init_params(text):
    """Extract Init procedure parameters."""
    joined = re.sub(r"\n\s+", " ", text)
    m = re.search(
        r"procedure Init\s*\(Self\s*:\s*in out Base_Instance;\s*([^)]+)\)\s*is\s+abstract",
        joined,
    )
    if m:
        params_str = m.group(1)
        params = []
        for p in params_str.split(";"):
            p = p.strip()
            if p:
                params.append(p)
        return params
    return []


def extract_set_id_bases(text):
    """Extract Set_Id_Bases parameters."""
    joined = re.sub(r"\n\s+", " ", text)
    m = re.search(
        r"procedure Set_Id_Bases\s*\(Self\s*:\s*in out Base_Instance;\s*([^)]+)\)",
        joined,
    )
    if m:
        params_str = m.group(1)
        params = []
        for p in params_str.split(";"):
            p = p.strip()
            if p:
                # Just the parameter name and type
                params.append(p)
        return params
    return []


def extract_connector_info(text):
    """Extract connector names, types, and directions from base spec."""
    invokee = []  # recv connectors (to override)
    invoker = []  # send/get/request connectors (to call)

    joined = re.sub(r"\n\s+", " ", text)
    lines = text.splitlines()

    # Find invokee (recv) connectors - look for abstract procedures
    for m in re.finditer(
        r"not overriding procedure (\w+_Recv_(?:Sync|Async))\s*\(Self\s*:\s*in out Base_Instance;\s*Arg\s*:\s*in\s+(\S+)\)\s*is\s+abstract",
        joined,
    ):
        invokee.append({"name": m.group(1), "type": m.group(2), "direction": "recv"})

    # Modify connectors (in out)
    for m in re.finditer(
        r"not overriding procedure (\w+_Modify)\s*\(Self\s*:\s*in out Base_Instance;\s*Arg\s*:\s*in out\s+(\S+)\)\s*is\s+abstract",
        joined,
    ):
        invokee.append({"name": m.group(1), "type": m.group(2), "direction": "modify"})

    # Find invoker (send) connectors - look for Attach_ procedures
    for m in re.finditer(
        r"procedure Attach_(\w+)\s*\(Self\s*:\s*in out Base_Instance",
        joined,
    ):
        name = m.group(1)
        invoker.append({"name": name})

    # Classify invoker connectors
    for inv in invoker:
        name = inv["name"]
        if "_Send" in name:
            inv["direction"] = "send"
        elif "_Get" in name:
            inv["direction"] = "get"
        elif "_Request" in name:
            inv["direction"] = "request"
        else:
            inv["direction"] = "invoke"

    return invokee, invoker


def extract_dropped_handlers(text):
    """Extract *_Dropped abstract procedures."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)
    for m in re.finditer(
        r"not overriding procedure (\w+_Dropped)\s*\(Self\s*:\s*in out Base_Instance;\s*Arg\s*:\s*in\s+(\S+)\)\s*is\s+abstract",
        joined,
    ):
        results.append({"name": m.group(1), "type": m.group(2)})
    return results


def extract_data_dep_helpers(text):
    """Extract private data dependency helper functions (Get_*)."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)
    for m in re.finditer(
        r"not overriding function (Get_\w+)\s*\(Self\s*:\s*in out Base_Instance;\s*([^)]+)\)\s*return\s+(\S+)",
        joined,
    ):
        # Skip abstract ones (Get_Data_Dependency)
        after = joined[m.end():m.end() + 30]
        if "is abstract" in after:
            continue
        results.append({"name": m.group(1), "params": m.group(2).strip(), "returns": m.group(3)})
    return results


def extract_send_helpers(text):
    """Extract private send/get/request helper procedures/functions."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)

    # Send procedures
    for m in re.finditer(
        r"not overriding procedure (\w+_Send(?:_If_Connected)?)\s*\(Self\s*:\s*in out Base_Instance;\s*Arg\s*:\s*in\s+(\S+)",
        joined,
    ):
        results.append({"name": m.group(1), "kind": "procedure", "type": m.group(2)})

    # Get functions (no arg)
    for m in re.finditer(
        r"not overriding function (\w+_Get)\s*\(Self\s*:\s*in Base_Instance\)\s*return\s+(\S+)",
        joined,
    ):
        results.append({"name": m.group(1), "kind": "function", "type": m.group(2)})

    # Request functions (with arg)
    for m in re.finditer(
        r"not overriding function (\w+_Request)\s*\(Self\s*:\s*in Base_Instance;\s*Arg\s*:\s*in\s+(\S+)\)\s*return\s+(\S+)",
        joined,
    ):
        results.append({"name": m.group(1), "kind": "function", "arg_type": m.group(2), "type": m.group(3)})

    # Is_Connected checks
    for m in re.finditer(
        r"not overriding function (Is_\w+_Connected)\s*\(Self\s*:\s*in Base_Instance\)\s*return\s+Boolean",
        joined,
    ):
        results.append({"name": m.group(1), "kind": "function", "type": "Boolean"})

    return results


def extract_feature_items(text, kind):
    """Extract event/data_product/fault/command creation functions from feature spec."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)

    if kind in ("events", "faults"):
        # Functions that create Event.T or Fault.T
        for m in re.finditer(
            r"not overriding function (\w+)\s*\(Self\s*:\s*in Instance;\s*Timestamp\s*:\s*Sys_Time\.T(?:;\s*Param\s*:\s*in\s+(\S+))?\)\s*return\s+(?:Event|Fault)\.T",
            joined,
        ):
            item = {"name": m.group(1)}
            if m.group(2):
                item["param_type"] = m.group(2)
            results.append(item)
    elif kind == "data_products":
        for m in re.finditer(
            r"not overriding function (\w+)\s*\(Self\s*:\s*in Instance;\s*Timestamp\s*:\s*Sys_Time\.T;\s*Item\s*:\s*in\s+(\S+)\)\s*return\s+Data_Product\.T",
            joined,
        ):
            results.append({"name": m.group(1), "type": m.group(2)})
    elif kind == "commands":
        for m in re.finditer(
            r"not overriding function (\w+)\s*\(Self\s*:\s*in Instance(?:;\s*([^)]+))?\)\s*return\s+Command\.T",
            joined,
        ):
            item = {"name": m.group(1)}
            if m.group(2):
                item["params"] = m.group(2).strip()
            results.append(item)

    return results


def extract_local_ids(text):
    """Extract local ID enum values."""
    results = []
    m = re.search(r"type Local_\w+_Id_Type is\s*\(([\s\S]*?)\);", text)
    if m:
        for name in re.findall(r"(\w+_Id)", m.group(1)):
            results.append(name)
    return results


def extract_parameter_info(text):
    """Extract parameter table info from parameters spec."""
    results = []
    joined = re.sub(r"\n\s+", " ", text)

    # Look for Validate_Parameters signature
    validate_sig = None
    m = re.search(
        r"not overriding function Validate_Parameters\s*\(Self\s*:\s*in Instance;\s*([^)]+)\)",
        joined,
    )
    if m:
        validate_sig = m.group(1).strip()

    # Look for parameter record fields
    m = re.search(r"type Parameter_Table_Type is record([\s\S]*?)end record", text)
    if m:
        for fm in re.finditer(r"(\w+)\s*:\s*([^;]+)", m.group(1)):
            results.append({"name": fm.group(1).strip(), "type": fm.group(2).strip()})

    return results, validate_sig


def extract_tester_histories(text):
    """Extract typed history fields from tester spec using section comments."""
    histories = {"connector": [], "event": [], "data_product": [], "fault": [], "command": []}

    section = None
    for line in text.splitlines():
        if "-- Connector histories:" in line:
            section = "connector"
            continue
        elif "-- Event histories:" in line:
            section = "event"
            continue
        elif "-- Data product histories:" in line:
            section = "data_product"
            continue
        elif "-- Fault histories:" in line:
            section = "fault"
            continue
        elif "-- Command histories:" in line:
            section = "command"
            continue
        elif re.match(r"\s+--\s", line) and section:
            # Another comment section header resets
            if "histor" not in line.lower():
                section = None
                continue
        elif "end record" in line:
            section = None
            continue

        if section:
            m = re.match(r"\s+(\w+)\s*:\s*\w+\.Instance", line)
            if m:
                histories[section].append(m.group(1))

    return histories


def extract_tester_overrides(text):
    """Extract override fields from tester (data dep values, return status, etc.)."""
    results = []
    for line in text.splitlines():
        # Look for fields with override-like names
        m = re.match(r"\s+(\w+)\s*:\s*([^;]+?)\s*:=\s*([^;]+);", line)
        if m:
            name = m.group(1).strip()
            typ = m.group(2).strip()
            default = m.group(3).strip()
            # Skip histories and the component instance
            if "History" in name or name == "Component_Instance":
                continue
            results.append({"name": name, "type": typ, "default": default})
    return results


def format_output(component_dir, files):
    """Format the extracted information into readable output."""
    comp_name = os.path.basename(os.path.normpath(component_dir))
    lines = []
    lines.append(f"{'=' * 70}")
    lines.append(f"  GENERATED API: {comp_name}")
    lines.append(f"{'=' * 70}")

    # --- Base spec ---
    if files["base_spec"]:
        with open(files["base_spec"]) as f:
            base_text = f.read()

        # Init params
        init_params = extract_init_params(base_text)
        if init_params:
            lines.append("")
            lines.append("INIT PARAMETERS:")
            for p in init_params:
                lines.append(f"  {p}")

        # Set_Id_Bases
        id_bases = extract_set_id_bases(base_text)
        if id_bases:
            lines.append("")
            lines.append("SET_ID_BASES:")
            for p in id_bases:
                lines.append(f"  {p}")

        # Connectors
        invokee, invoker = extract_connector_info(base_text)
        if invokee:
            lines.append("")
            lines.append("RECV CONNECTORS (override these):")
            for c in invokee:
                lines.append(f"  procedure {c['name']} (Self : in out; Arg : in {c['type']})")

        if invoker:
            lines.append("")
            lines.append("SEND/GET/REQUEST CONNECTORS (call these):")
            send_helpers = extract_send_helpers(base_text)
            for h in send_helpers:
                if h["kind"] == "procedure":
                    lines.append(f"  Self.{h['name']} (Arg)")
                elif "arg_type" in h:
                    lines.append(f"  Result := Self.{h['name']} (Arg)  -- returns {h['type']}")
                elif h["name"].startswith("Is_"):
                    lines.append(f"  Self.{h['name']}  -- returns Boolean")
                else:
                    lines.append(f"  Result := Self.{h['name']}  -- returns {h['type']}")

        # Dropped handlers
        dropped = extract_dropped_handlers(base_text)
        if dropped:
            lines.append("")
            lines.append("DROPPED HANDLERS (must override, usually null):")
            for d in dropped:
                lines.append(f"  procedure {d['name']} (Self : in out; Arg : in {d['type']})")

        # Data dependency helpers
        dep_helpers = extract_data_dep_helpers(base_text)
        if dep_helpers:
            lines.append("")
            lines.append("DATA DEPENDENCY HELPERS (private, call in implementation):")
            for h in dep_helpers:
                lines.append(f"  Status := Self.{h['name']} (...; Value : out ...)  -- returns {h['returns']}")

        # Abstract overrides
        abstracts = extract_abstract_procedures(base_text)
        other_abstracts = [
            a for a in abstracts
            if not any(kw in a for kw in ("Recv_Sync", "Recv_Async", "_Modify", "_Dropped", "Init ", "Get_Data_Dependency", "Invalid_Data_Dependency"))
        ]
        if other_abstracts:
            lines.append("")
            lines.append("OTHER ABSTRACT (must override):")
            for a in other_abstracts:
                sig = a.replace("not overriding ", "")
                lines.append(f"  {sig}")

        # Data dependency abstracts
        dd_abstracts = [a for a in abstracts if "Data_Dependency" in a]
        if dd_abstracts:
            lines.append("")
            lines.append("DATA DEPENDENCY ABSTRACTS (must override):")
            for a in dd_abstracts:
                sig = a.replace("not overriding ", "")
                lines.append(f"  {sig}")

        # Record fields (accessible via Self.*)
        m = re.search(r"type Base_Instance is abstract new.*?with record([\s\S]*?)end record", base_text)
        if m:
            fields = []
            record_body = m.group(1)
            # Parse only actual field declarations (skip comments)
            for line in record_body.splitlines():
                line = line.strip()
                if line.startswith("--") or not line:
                    continue
                fm = re.match(r"(\w+)\s*:\s*([^;]+);", line)
                if fm:
                    fname = fm.group(1).strip()
                    ftype = fm.group(2).strip()
                    if not fname.startswith("Connector_"):
                        fields.append((fname, ftype))
            if fields:
                lines.append("")
                lines.append("INSTANCE FIELDS (access via Self.*):")
                for fname, ftype in fields:
                    lines.append(f"  Self.{fname} : {ftype}")

    # --- Events ---
    if files["events"]:
        with open(files["events"]) as f:
            events_text = f.read()
        items = extract_feature_items(events_text, "events")
        if items:
            lines.append("")
            lines.append("EVENTS (create via Self.Events.*):")
            for item in items:
                param = f", Param => {item['param_type']}" if "param_type" in item else ""
                lines.append(f"  Self.Events.{item['name']} (Timestamp{param})")

    # --- Data Products ---
    if files["data_products"]:
        with open(files["data_products"]) as f:
            dp_text = f.read()
        items = extract_feature_items(dp_text, "data_products")
        if items:
            lines.append("")
            lines.append("DATA PRODUCTS (create via Self.Data_Products.*):")
            for item in items:
                lines.append(f"  Self.Data_Products.{item['name']} (Timestamp, Item => {item['type']})")

    # --- Commands ---
    if files["commands"]:
        with open(files["commands"]) as f:
            cmd_text = f.read()
        items = extract_feature_items(cmd_text, "commands")
        ids = extract_local_ids(cmd_text)
        if items:
            lines.append("")
            lines.append("COMMANDS:")
            lines.append(f"  IDs: {', '.join(ids)}")
            for item in items:
                params = f" ({item['params']})" if "params" in item else ""
                lines.append(f"  Self.Commands.{item['name']}{params}  -- returns Command.T")

    # --- Parameters ---
    if files["parameters"]:
        with open(files["parameters"]) as f:
            param_text = f.read()
        params, validate_sig = extract_parameter_info(param_text)
        if params:
            lines.append("")
            lines.append("PARAMETERS:")
            lines.append("  Table fields (access via Self.Parameters.*):")
            for p in params:
                lines.append(f"    .{p['name']} : {p['type']}")
            if validate_sig:
                lines.append(f"  Validate signature: ({validate_sig})")

    # --- Faults ---
    if files["faults"]:
        with open(files["faults"]) as f:
            faults_text = f.read()
        items = extract_feature_items(faults_text, "faults")
        if items:
            lines.append("")
            lines.append("FAULTS (create via Self.Faults.*):")
            for item in items:
                param = f", Param => {item['param_type']}" if "param_type" in item else ""
                lines.append(f"  Self.Faults.{item['name']} (Timestamp{param})")

    # --- Data Dependencies ---
    if files["data_dependencies"]:
        with open(files["data_dependencies"]) as f:
            dd_text = f.read()
        lines.append("")
        lines.append("DATA DEPENDENCIES:")
        for m in re.finditer(
            r"not overriding function Extract_(\w+)\s*\(Self\s*:\s*in Instance;[^)]*Item\s*:\s*out\s+(\S+?)(?:\)|\s)",
            re.sub(r"\n\s+", " ", dd_text),
        ):
            lines.append(f"  {m.group(1)} -> {m.group(2)}")

    # --- Tester ---
    if files["tester_spec"]:
        with open(files["tester_spec"]) as f:
            tester_text = f.read()

        histories = extract_tester_histories(tester_text)
        overrides = extract_tester_overrides(tester_text)

        lines.append("")
        lines.append("TESTER API:")

        for section, items in histories.items():
            if items:
                lines.append(f"  {section.upper()} HISTORIES:")
                for h in items:
                    lines.append(f"    T.{h}")

        if overrides:
            lines.append("  OVERRIDE FIELDS (set in test to control behavior):")
            for o in overrides:
                lines.append(f"    T.{o['name']} : {o['type']} := {o['default']}")

    lines.append("")
    lines.append(f"{'=' * 70}")
    return "\n".join(lines)


def main():
    if len(sys.argv) < 2:
        print(f"Usage: {sys.argv[0]} <component_dir>", file=sys.stderr)
        print(f"Example: {sys.argv[0]} src/components/voltage_monitor", file=sys.stderr)
        sys.exit(1)

    component_dir = sys.argv[1]
    if not os.path.isdir(component_dir):
        print(f"Error: {component_dir} is not a directory", file=sys.stderr)
        sys.exit(1)

    files = find_files(component_dir)

    if not files["base_spec"]:
        print(f"Error: No generated base spec found in {component_dir}/build/src/", file=sys.stderr)
        print("Run 'redo' first to generate the component.", file=sys.stderr)
        sys.exit(1)

    print(format_output(component_dir, files))


if __name__ == "__main__":
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall