ballerina-platform/ballerina-library/generating-connectors

Setup → Sanitize → Client → Tests → Examples → Docs

# Check environment (bal, PyYAML) — run first in setup, after PYTHON_CMD is resolved
<PYTHON_CMD> scripts/check_environment.py
 
# Find OpenAPI spec candidates in CWD — use before prompting for spec path
<PYTHON_CMD> scripts/find_spec_files.py
 
# Find an existing Ballerina.toml nested below CWD — use before prompting for output dir
<PYTHON_CMD> scripts/find_ballerina_toml.py
 
# Initialise a Ballerina package in the output dir (bal new . + remove main.bal)
<PYTHON_CMD> scripts/init_ballerina_package.py "<output-dir>"
 
# Validate spec file (YAML/JSON validity + required fields)
<PYTHON_CMD> scripts/validate_spec.py "<spec-path>"
 
# Extract structured spec metadata — the only spec representation in LLM context
<PYTHON_CMD> scripts/parse_openapi_spec.py "<spec-path>"
 
# Convert YAML spec to JSON — writes <same-name>.json, prints output path
<PYTHON_CMD> scripts/convert_yaml_to_json.py "<spec.yaml>"
 
# Locate aligned/flattened spec output in a spec directory
<PYTHON_CMD> scripts/find_spec_output.py "<spec-dir>"
 
# Read Ballerina.toml package fields → JSON {org, name, version, distribution, keywords, description}
<PYTHON_CMD> scripts/parse_ballerina_toml.py "<Ballerina.toml>"
 
# Write/replace the keywords array in Ballerina.toml's [package] section
<PYTHON_CMD> scripts/write_ballerina_keywords.py "<Ballerina.toml>" "<keyword1>" "<keyword2>" ...
 
# Generate/merge sanitations.md from a structural diff of original vs aligned spec
<PYTHON_CMD> scripts/generate_sanitations.py "<original-spec>" "<aligned-spec>" "<out.md>" --template "<template>" --module-name "<PC>" --cli-command "<cmd>"
 
# Analyse client.bal → JSON {apiCount, numExamples, configType, methods:[...]}
<PYTHON_CMD> scripts/analyze_client.py "<client.bal>"
 
# Generate service stub from spec → tests/mock_service.bal
# 3rd/4th args optional (empty string when unset): operation filter + license header
<PYTHON_CMD> scripts/generate_mock_stub.py "<aligned-spec>" "<output-dir>" "<SELECTED_OPERATIONS>" "<LICENSE_PATH>"
 
# Run any bal command in a working directory — prints stderr to a temp file and its path on failure
<PYTHON_CMD> scripts/run_bal_command.py --cwd "<working-dir>" <command> [<argument>...]
 
# Parse compilation errors from bal build stderr → JSON error array
<PYTHON_CMD> scripts/parse_errors.py "<stderr-file-or-stdin>"
 
# Reuse and persist stable AI operation-ID decisions across regeneration runs
<PYTHON_CMD> scripts/operation_id_mappings.py prepare "<aligned-spec>" "<ai-mappings.json>" "<candidate.json>"
<PYTHON_CMD> scripts/operation_id_mappings.py apply "<aligned-spec>" "<candidate.json>" "<decisions.json>" "<ai-mappings.json>"
 
# Scan an aligned spec for duplicate operationIds — non-fatal warnings
<PYTHON_CMD> scripts/check_duplicate_operation_ids.py "<aligned-spec>"
 
# Reuse and persist stable AI schema-name decisions; schema-less specs are supported
<PYTHON_CMD> scripts/schema_mappings.py prepare "<aligned-spec>" "<ai-mappings.json>" "<candidate.json>"
<PYTHON_CMD> scripts/schema_mappings.py apply "<aligned-spec>" "<candidate.json>" "<decisions.json>" "<ai-mappings.json>"
 
# Collect/apply missing request-body and API-key descriptions
<PYTHON_CMD> scripts/spec_descriptions.py prepare "<aligned-spec>" "<requests.json>"
<PYTHON_CMD> scripts/spec_descriptions.py apply "<aligned-spec>" "<requests.json>" "<decisions.json>"
 
# Normalize and resolve a unique snake_case example name
<PYTHON_CMD> scripts/example_names.py resolve "<examples-dir>" "<suggested-name>" "<fallback-name>"
 
# Capture and compare client/types source snapshots for semantic-version advice
<PYTHON_CMD> scripts/client_version_summary.py capture "<ballerina-dir>" "<baseline.json>"
<PYTHON_CMD> scripts/client_version_summary.py diff "<ballerina-dir>" "<baseline.json>"
 
# Scan or safely clean generated example packages only
<PYTHON_CMD> scripts/manage_examples.py <scan|cleanup> "<examples-dir>"