- API sprawl CI check in place.

- Future API doc.

Author: general-kroll-4-life

.github/workflows/build.yml

@@ -141,6 +141,9 @@ jobs:
     - name: Check out code into the Go module directory
       uses: actions/checkout@v2
 
+    - name: API sprawl check
+      run: ./cicd/scripts/hack/check_api_growth.sh
+    
     - name: Setup system dependencies
       run: |
         sudo apt-get update

cicd/scripts/hack/check_api_growth.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "Checking for API sprawl..."
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+echo "TMP_DIR=$TMP_DIR"
+
+echo "Changing to root dir: $ROOT_DIR"
+
+cd "$ROOT_DIR"
+
+# Regenerate current API snapshots
+grep -Rho 'func [A-Z][A-Za-z0-9_]*' --include='*.go' --exclude-dir={vendor,testdata} . \
+  | sort -u > "$TMP_DIR/exported_funcs.txt"
+
+grep -Rnoh '^type [A-Z][A-Za-z0-9_]* interface' --include='*.go' --exclude-dir={vendor,testdata} . \
+  | sed 's/^[^:]*://g' | sort -u > "$TMP_DIR/exported_interfaces.txt"
+
+grep -Rnoh '^type [A-Z][A-Za-z0-9_]* struct' --include='*.go' --exclude-dir={vendor,testdata} . \
+  | sed 's/^[^:]*://g' | sort -u > "$TMP_DIR/exported_structs.txt"
+
+fail=0
+
+check_file() {
+  local baseline="$1"
+  local current="$2"
+  local label="$3"
+
+  if [[ ! -f "$baseline" ]]; then
+    echo "Baseline file missing: $baseline"
+    fail=1
+    return
+  fi
+
+  # Show lines present in current but not in baseline (i.e. additions).
+  local added
+  added="$(comm -13 <(sort "$baseline") <(sort "$current") || true)"
+
+  if [[ -n "$added" ]]; then
+    echo "API growth detected in $label:"
+    echo "$added"
+    echo
+    fail=1
+  fi
+}
+
+
+check_file "cicd/tools/api/exported_funcs.txt"       "$TMP_DIR/exported_funcs.txt"       "exported functions"
+check_file "cicd/tools/api/exported_interfaces.txt"  "$TMP_DIR/exported_interfaces.txt"  "exported interfaces"
+check_file "cicd/tools/api/exported_structs.txt"     "$TMP_DIR/exported_structs.txt"     "exported structs"
+
+if [[ "$fail" -ne 0 ]]; then
+  echo "API sprawl check FAILED: new exported symbols were introduced."
+  echo "If this is intentional, update tools/api/*.txt and FUTURE_API.md in the same PR."
+  exit 1
+fi
+
+echo "API sprawl check PASSED: no new exported symbols."

cicd/tools/api/README.md

@@ -0,0 +1,2 @@
+
+These are reference points for the acceptable bresadth of the API.  In general, it ought to be non-increasing.

cicd/tools/api/exported_funcs.txt

@@ -0,0 +1,274 @@
+func CallFromSignature
+func CartesianProduct
+func ClientProtocolTypeFromString
+func DecompressToPath
+func DefaultLinkHeaderTransformer
+func Execute
+func ExtractHTTPElement
+func ExtractParameterisedURL
+func ExtractProviderDesignation
+func FilePathJoin
+func FindLatest
+func FindLatestStable
+func Gcd
+func Get
+func GetAccessToken
+func GetAuthCtx
+func GetAwsEc2ListMultiResponseReader
+func GetAwsEc2ListSingleResponseReader
+func GetContrivedPagesResponseReader
+func GetControlAttributes
+func GetCurrentAuthUser
+func GetDB
+func GetDBMSInternalCfg
+func GetDescribeHeader
+func GetFilePathFromRepositoryRoot
+func GetFilePathUnescapedFromRepositoryRoot
+func GetForwardSlashFilePathFromRepositoryRoot
+func GetGCCfg
+func GetGoogleFoldersListResponseReader
+func GetHTTPClient
+func GetK8SNodesListMultiResponseReader
+func GetKStoreCfg
+func GetLogger
+func GetMockLocalRegistry
+func GetMockRegistry
+func GetMonitorRequest
+func GetNamespaceCfg
+func GetPrefixPrefix
+func GetProviderDocBytes
+func GetRequestMediaType
+func GetResourcesHeader
+func GetResourcesRegisterDocBytes
+func GetResponseMediaType
+func GetRoundTripper
+func GetSQLBackendCfg
+func GetSQLEngineSetupDDL
+func GetServiceDocBytes
+func GetServicesHeader
+func GetSubObjFromNode
+func GetSubObjTyped
+func GetTabulation
+func GetTestingView
+func GetTxnCoordinatorCfgCfg
+func InterfaceToBytes
+func InterfaceToSQLType
+func IsAcceptableMediaType
+func IsJSONSynonym
+func IsNil
+func IsXMLSynonym
+func Lcm
+func LcmMultiple
+func LoadProviderAndServiceFromPaths
+func LoadProviderByName
+func LoadProviderDocFromBytes
+func LoadProviderDocFromFile
+func LoadResourcesShallow
+func LoadServiceDocFromBytes
+func LoadServiceDocFromFile
+func LoadServiceSubsetDocFromBytes
+func MakeSuffixMapFromParameterMap
+func MarshalXMLUserInput
+func NewAddressSpaceAnalysisPassManager
+func NewAddressSpaceFormulator
+func NewAddressSpaceGrammar
+func NewAliasMap
+func NewAnalyzerCfg
+func NewAnySdkArgList
+func NewAnySdkClientConfigurator
+func NewAnySdkOpStoreDesignation
+func NewAuthUtility
+func NewAwsSignTransport
+func NewBasicDiscoveryAdapter
+func NewBrickMap
+func NewColumnDescriptor
+func NewDataFlowCfg
+func NewDefaultCredentialAzureTokenSource
+func NewDropDoubleUnderscoreParamsTranslator
+func NewEmptyOperationStore
+func NewEmptyProviderService
+func NewEmptyResource
+func NewExecContext
+func NewExecPayload
+func NewFileValidator
+func NewFuzzyPair
+func NewGetQueryToPostFormEncodedTranslator
+func NewHTTPArmoury
+func NewHTTPArmouryParameters
+func NewHTTPElement
+func NewHTTPPreparator
+func NewHTTPPreparatorConfig
+func NewHttpClientConfiguratorInput
+func NewHttpParameters
+func NewHttpPreparatorStream
+func NewInterrogator
+func NewJSONPathResolver
+func NewLocalTemplateExecutor
+func NewMethodAnalysisInput
+func NewMethodAnalyzer
+func NewNaiveBodyTranslator
+func NewNilTranslator
+func NewNopMapStream
+func NewOperationSelector
+func NewOptionalAddressableRequestBodyProperty
+func NewParameter
+func NewParameterBinding
+func NewParameterSuffixMap
+func NewParameterTranslator
+func NewParameters
+func NewPrefixedTranslator
+func NewProvider
+func NewProviderServiceResourceAnalyzer
+func NewProvidersList
+func NewQueryTransposer
+func NewRadixTree
+func NewRegexpShorthand
+func NewRegexpStringMetcher
+func NewRegistry
+func NewRequestTranslator
+func NewRequiredAddressableRequestBodyProperty
+func NewResourceAddressSpaceExpander
+func NewResourceRegister
+func NewResponse
+func NewRouter
+func NewSQLEngine
+func NewSQLPersistenceSystem
+func NewService
+func NewServiceLevelStaticAnalyzer
+func NewSessionContext
+func NewSimpleMockRegistryRoundTripper
+func NewSimpleProjectionMapStream
+func NewStandardAddressSpaceExpansionConfig
+func NewStandardBrickMapConfig
+func NewStandardGQLReader
+func NewStandardMapStream
+func NewStandardMapStreamCollection
+func NewStandardOutputPacket
+func NewStandardParamInputStrem
+func NewStandardStaticAnalyzerFactoryFactory
+func NewStandardTransformerLocator
+func NewStaticAnalyzer
+func NewStreamTransformerFactory
+func NewStringSchema
+func NewTTLDiscoveryStore
+func NewTemplateStreamTransformer
+func NewTestSchema
+func NewTransport
+func NewTxnCounterManager
+func NewViewNameMangler
+func NewViewNameUnmangler
+func NewXMLShorthand
+func NewXMLStringShorthand
+func NewXPathResolver
+func NewwHTTPAnySdkArgList
+func NormaliseMediaType
+func OAuthToGoogle
+func ObtainServerURLsFromServers
+func ParseURLHost
+func ProviderTypeConditionIsValid
+func ReadService
+func RenderTemplateFromSerializable
+func ResourceConditionIsValid
+func ResourceKeyExists
+func RevokeGoogleAuth
+func SanitiseServerURL
+func ServiceConditionIsValid
+func ServiceKeyExists
+func Set
+func SetLogger
+func SplitSearchPath
+func TestAliasedAddressSpaceGoogleCurrent
+func TestAwareListVolumesMulti
+func TestBasicAddressSpaceAWSCurrent
+func TestBasicAddressSpaceGoogleCurrent
+func TestBestEffortXMLStreamTransform
+func TestConfigDrivenAliasedAddressSpaceGoogleCurrent
+func TestDeepDiscoveryGoogleCurrent
+func TestDiscovery01
+func TestDiscoveryAWS
+func TestFatConfigDrivenAliasedAddressSpaceGoogleCurrent
+func TestFragmentedResourcesFile
+func TestGet
+func TestGetControlAttributes
+func TestGetLogger
+func TestGetStruct
+func TestHeavyAliasedAddressSpaceAWSCurrent
+func TestHeavyAliasedAddressSpaceGoogleCurrent
+func TestIndirectGoogleComputeResourcesJsonRead
+func TestIndirectGoogleComputeServiceSubsetAccess
+func TestIndirectGoogleComputeServiceSubsetJsonRead
+func TestIntelligentAliasedAddressSpaceGoogleCurrent
+func TestJSONPathHandle
+func TestJSONPathHandleEnforcedResponseMediaType
+func TestJSONRequestBody
+func TestListProviderVersionsRegistry
+func TestListProvidersRegistry
+func TestLocalExec
+func TestLocalRegistryIndirectGoogleComputeServiceSubsetAccess
+func TestLocalTemplateClient
+func TestLocalTemplatedCompositeServiceFile
+func TestLocalValidateAndParseValidProviderFile
+func TestMeaningfulStreamTransform
+func TestMeaningfulXMLStreamTransform
+func TestMethodLevelVariableHostRoutingFutureProofed
+func TestMonolithicCompositeServiceFile
+func TestNewAddressSpace
+func TestNoFallbackViewApi
+func TestOpensslCertTextStreamTransform
+func TestPersistence01
+func TestPersistenceSetup
+func TestPlaceholder
+func TestProviderPull
+func TestProviderPullAndPersist
+func TestRegistryArrayTopLevelResponse
+func TestRegistryCanHandlePolymorphismAllOf
+func TestRegistryCanHandleUnspecifiedResponseWithDefaults
+func TestRegistryIndirectGoogleComputeResourcesJsonRead
+func TestRegistryIndirectGoogleComputeServiceMethodResolutionSeparateDocs
+func TestRegistryIndirectGoogleComputeServiceSubsetAccess
+func TestRegistryLocalTemplated
+func TestRegistryProviderLatestVersion
+func TestRegistrySimpleOktaApplicationServiceRead
+func TestRenderEnvTemplate
+func TestRenderEnvTemplateExotic
+func TestRenderEnvURLTemplateExotic
+func TestRenderErroneousTemplateFromSerializable
+func TestRenderNilURLTemplateFromSerializable
+func TestRenderTemplate
+func TestRenderTemplateFromSerializable
+func TestRenderURLTemplateFromSerializable
+func TestSearchAliasedAddressSpaceGoogleCurrent
+func TestSet
+func TestSetDollar
+func TestSetLogger
+func TestSetStruct
+func TestSetStructAll
+func TestShallowDiscoveryGoogleCurrent
+func TestShallowDiscoveryGoogleLegacy
+func TestSimpleAWSec2ServiceJsonReadAndDumpString
+func TestSimpleGoogleComputeResourcesJsonRead
+func TestSimpleGoogleComputeServiceJsonReadAndDumpString
+func TestSimpleOktaApplicationServiceJsonReadAndDumpString
+func TestSimpleOktaApplicationServiceRead
+func TestSimpleOktaApplicationServiceReadAndDump
+func TestSimpleOktaApplicationServiceReadAndDumpString
+func TestSimpleStreamTransform
+func TestSimpleTextXMLStreamTransform
+func TestSimpleViewApi
+func TestSplitCompositeServiceFile
+func TestSplitPath
+func TestSplitPathLong
+func TestStandardControlAttributes
+func TestStaticHostRouting
+func TestTransformedXMLHTTPHandle
+func TestValidateAndParseGoogleProviderFile
+func TestValidateAndParse_ValidJSON
+func TestVariableHostRouting
+func TestVariableHostRoutingFutureProofed
+func TestXMLMArshal
+func TestXMLRequestBody
+func TestXMLSchemaInterrogation
+func TestXPathHandle
+func TranslateServiceKeyGenericProviderToIql
+func TrimSelectItemsKey
+func ValidateAndParse