Developer Documentation
Guides

Codebase Analyzer

Suggest Edits

Global Concept

At Flagship, our mission is to help you focus on your code and do your magic.

To help you focus on that purpose, we have created a tool that can analyze your codebase and detect the usage of Flagship flags so that they can be synchronized in our platform.

Distribution

Our Codebase analyzer can be used by downloading our docker image or with the help of our CLI

Prerequisites

The Codebase Analyzer requires the setup of a Client ID and Client Secret for the Remote Control API.
You can find more information here: Remote Control API.

Install

From docker

docker pull flagshipio/code-analyzer

Binary

Download the binary here for your specific system architecture:

https://github.com/flagship-io/codebase-analyzer/releases/latest

Run

With CLI

go build

export FLAGSHIP_CLIENT_ID=FLAGSHIP_MANAGEMENT_API_CLIENT_ID
export FLAGSHIP_CLIENT_SECRET=FLAGSHIP_MANAGEMENT_API_CLIENT_SECRET
export ACCOUNT_ID=FLAGSHIP_ACCOUNT_ID
export ENVIRONMENT_ID=FLAGSHIP_ENVIRONMENT_ID
export REPOSITORY_URL=https://gitlab.com/org/repo
export REPOSITORY_BRANCH=master
export DIRECTORY=./
./codebase-analyzer

With Docker

docker run -v $(pwd)/your_repo:/your_repo -e FLAGSHIP_CLIENT_ID=FLAGSHIP_MANAGEMENT_API_CLIENT_ID -e FLAGSHIP_CLIENT_SECRET=FLAGSHIP_MANAGEMENT_API_CLIENT_SECRET -e ACCOUNT_ID=FLAGSHIP_ACCOUNT_ID -e ENVIRONMENT_ID=your_env_id -e REPOSITORY_URL=https://gitlab.com/org/repo -e REPOSITORY_BRANCH=master -e DIRECTORY=/your_repo flagshipio/code-analyzer

With Homebrew

export FLAGSHIP_CLIENT_ID=FLAGSHIP_MANAGEMENT_API_CLIENT_ID
export FLAGSHIP_CLIENT_SECRET=FLAGSHIP_MANAGEMENT_API_CLIENT_SECRET
export ACCOUNT_ID=FLAGSHIP_ACCOUNT_ID
export ENVIRONMENT_ID=FLAGSHIP_ENVIRONMENT_ID
export REPOSITORY_URL=https://gitlab.com/org/repo
export REPOSITORY_BRANCH=master
export DIRECTORY=./

brew tap flagship-io/flagship
brew install codebase-analyzer

codebase-analyzer

Supported file languages

  • .cs .fs (SDK V4 supported)
  • .dart (SDK V4 supported)
  • .go
  • .java
  • .js .jsx (SDK V4 supported)
  • .kt (Android SDK V4 supported)
  • .m
  • .php (SDK V4 supported)
  • .py
  • .swift (SDK V4 supported)
  • .ts .tsx (SDK V4 supported)
  • .vb

How it Works for V4 SDK

The codebase analyzer scans your codebase for potential usage of Flagship's feature flags, using presets of regexes or custom regexes that match your declarative variable, flag key, and default value with groups, where the first group matches the variable and the second group matches either flag or default value.

Here is an example of how the codebase analyzer scans a codebase where the Flagship JS SDK v4 is used.

  • One regex to match the flag's key and default value
1636

Demonstration of use in the codebase that contains JS SDK v4

  • Two regexes to match the flag's key and default value when they are split
Match declarative variable and flag's key

Match declarative variable and flag's key

Match declarative variable and flag's default value

Match declarative variable and flag's default value

Flagship preset of regexes

The codebase analyzer has a built-in set of regexes that match any feature flags used by Flagship with our SDK. Check supported files.

Custom regexes

The Codebase analyzer allows you to put custom regexes using the variable SearchCustomRegex.

The input data for SearchCustomRegex should follow this structure when the flag's key and default can be matched with one regex

[
    {
        "file_extension": "<YOUR_FILE_EXTENSION>",
        "regexes": [
						"YOUR_REGEX" // for v4
        ]
    }
]

When the flag's key and default value can't be matched with one regex you can use the property split, seach_flag and search_default_value.

[
    {
        "file_extension": "<YOUR_FILE_EXTENSION>",
        "regexes": [
						"REGEX TO MATCH DECLARATIVE VARIABLE AND FLAG'S KEY" // for v4
        ],
        "split": true,
      	"search_flag": true
    }
]

[
    {
        "file_extension": "<YOUR_FILE_EXTENSION>",
        "regexes": [
						"REGEX TO MATCH DECLARATIVE VARIABLE AND FLAG'S DEFAULT VALUE" // for v4
        ],
        "split": true,
      	"search_default_value": true
    }
]

❗️

The variable SearchCustomRegex is a string

Make sure to escape special characters in your regex and format JSON without spaces, line breaks, tabulation etc...

For example for JS SDK v4:

  • When the flag's key and default value can be matched with one regex:
[
    {
        "file_extension": ".ts?",
        "regexes": [
            "getFlag[(](?:(?:\\s*[\\\"'](\w*)[\\\"']\\s*[)]\\s*.getValue[(]([\\\"']\\w*\\s*[^\\\"]*[\\\"']|[^)]*))\\s*[)])?"
        ]
    }
]

This JSON should be transformed to this string.

[{\"file_extension\":\".ts?\",\"regexes\":[\"getFlag[(](?:(?:\s*[\\\"\\\\'](\\\\w*)[\\\"\\\\']\\\\s*[)]\\\\s*.getValue[(]([\\\"\\\\']\\\\w*\\\\s*[^\\\"]*[\\\"\\\\']|[^)]*))\\\\s*[)])?\"]}]

When the flag's key and default value are split

  • To match the declarative variable and the flag's key
[
    {
        "file_extension": ".ts?",
        "regexes": [
            "(?:(\\w+)\\s*[?]?\\s*[:]?\\s*(?:number|string|boolean|any|void| never|null|undefined|bigint|symbol|object|IFSFlag|FSFlag)?)\\s*[=]\\s*(?:.*)getFlag[(](?:(?:\\s*[\\\"'](\\w*)[\\\"']\\s*[)]\\s*))[^\\.]"
        ],
      	"split": true,
      	"search_flag": true
      	
    }
]
  • To match the declarative variable and the flag's default value
[
    {
        "file_extension": ".ts?",
        "regexes": [
            "\\s*(\\w*)[\\.]getValue[(]([\\\\"']?\\w*[\\\\"']?)[)]"
        ],
      	"split": true,
      	"search_default_value": true
      	
    }
]

How it Works for V3 SDK

The codebase analyzer scans your codebase for potential usage of Flagship's feature flags, using presets of regexes or custom regexes that match the flag key and default value with groups, where the first group matches the key and the second group matches the default value.

Here an example on how the codebase analyzer scans a codebase where the Flagship JS SDK v3 is used.

1636

Demonstration of use in codebase that contains JS SDK v3

Flagship preset of regexes

The codebase analyzer has a built-in set of regexes that match any feature flags used by Flagship with our SDK. Check supported files.

Custom regexes

The Codebase analyzer allows you to put custom regexes using the variable SearchCustomRegex.

The input data for SearchCustomRegex should follow this structure

[
    {
        "file_extension": "<YOUR_FILE_EXTENSION>",
        "regexes": [
            "YOUR_REGEX", // for v1
						"YOUR_REGEX" // for v2
        ]
    }
]

❗️

The variable SearchCustomRegex is a string

Make sure to escape special characters in your regex and format JSON without spaces, line breaks, tabulation etc...

For example: 

[
    {
        "file_extension": ".go?",
        "regexes": [
            "(?:Bool|String|Float64)Variation[(](?:\\s*[\\\"'](.*)[\\\"']\\s*,\\s*([\\\"'].*\\s*[^\\\"]*[\\\"']|[^)]*))\\s*[)]"
        ]
    }
]

This JSON should be transformed to this string.

[{\"file_extension\":\".go?\",\"regexes\":[\"(?:Bool|String|Float64)Variation[(](?:\\\\s*[\\\"\\\\'](.*)[\\\"\\\\']\\\\s*,\\\\s*([\\\"\\\\'].*\\\\s*[^\\\"]*[\\\"\\\\']|[^)]*))\\\\s*[)]\"]}]


[
    {
        "file_extension": ".ts?",
        "regexes": [
            "\\s*(\\w*)[\\.]getValue[(]([\\\\"']?\\w*[\\\\"']?)[)]"
        ],
      	"split": true,
      	"search_default_value": true
      	
    }
]

Environment variables

Flagship client ID (required)

This environment variable contains the Flagship client id necessary to authenticate requests and send flag infos to the Flagship Platform

  • example: FLAGSHIP_CLIENT_ID=FLAGSHIP_MANAGEMENT_API_CLIENT_ID

Flagship client secret (required)

This environment variable contains the Flagship client secret necessary to authenticate requests and send flag infos to the Flagship Platform

  • example: FLAGSHIP_CLIENT_SECRET=FLAGSHIP_MANAGEMENT_API_CLIENT_SECRET

You can retrieve these data from the platform or follow these instructions

Account ID (required)

This environment variable contains the Flagship account ID to synchronize flag usage for the matching environment

example: ACCOUNT_ID=your_flagship_account_id

Environment ID (required)

This environment variable contains the Flagship environment ID to synchronize flag usage for the matching environment

  • example: ENVIRONMENT_ID=your_flagship_env_id

Repository URL (required)

This environment variable should be set to the root URL of your repository and is used to track the links of the files where your flags are used

  • example: REPOSITORY_URL=https://gitlab.com/org/repo
  • default value: ""

Repository branch (required)

This environment variable should be set to the branch of the code you want to analyze and is used to track the links of the files where your flags are used

  • example: REPOSITORY_BRANCH=master
  • default value: ""

Files to exclude (optional)

This environment variable should contain a comma-separated list of globs to exclude

  • example: FILES_TO_EXCLUDE=".git/*,go.mod,go.sum,main.go,internal/*,example/*"
  • default value: ""

Directory to analyze (optional)

This environment variable should contain the directory you want to analyze

  • example: DIRECTORY="."
  • default value: "."

Custom regex to apply (optional)

This environment variable should contain the regex for the pattern you want to analyze

  • example: CUSTOM_REGEX_JSON="[{\"file_extension\":\".go?\",\"regexes\":[\"(?:Bool|String|Float64)Variation[(](?:\\\\s*[\\\"\\\\'](.*)[\\\"\\\\']\\\\s*,\\\\s*([\\\"\\\\'].*\\\\s*[^\\\"]*[\\\"\\\\']|[^)]*))\\\\s*[)]\"]}]"
  • default value: ""

Use with Gitlab CI

You can use the Codebase analyzer to push flag references to your Flagship environment when code is pushed to a specific branch or tag

analyze_flag_references:
  image: flagshipio/code-analyzer:master
  stage: analyze
  variables:
    REPOSITORY_URL: $CI_PROJECT_URL
    REPOSITORY_BRANCH: $CI_COMMIT_BRANCH
    FLAGSHIP_CLIENT_ID: FLAGSHIP_MANAGEMENT_API_CLIENT_ID
    FLAGSHIP_CLIENT_SECRET: FLAGSHIP_MANAGEMENT_API_CLIENT_SECRET
    ACCOUNT_ID: YOUR_ACCOUNT_ID
    ENVIRONMENT_ID: YOUR_ENVIRONMENT_ID
  script:
    - /root/code-analyser
  only:
    - master

Contribute

The Codebase Analyzer is an open-source software.
See the GitHub link for the contribution guide: https://github.com/flagship-io/codebase-analyzer

Any feedback? We would be happy to have a quick chat!

Updated 2 months ago