@maxlona/code-refs

Finds where your Maxlona feature flags are used in code and reports each file:line to Maxlona. There, every flag shows where it lives, and the Code References page lists the flags that are ready to clean up: no longer evaluated, fully released, or already removed from code, with one click to archive them.

• No dependencies. Node 18 or later.
• Respects .gitignore inside a git checkout and skips build output, vendored folders, minified files and binaries.
• Works out the repository, branch, commit and link to your code host on GitHub Actions, GitLab CI, Bitbucket Pipelines and Azure Pipelines.
• Needs only a read-only management key. A scan records where flags appear; it never changes a flag.

Quick start

MAXLONA_MANAGEMENT_KEY=mk_... npx @maxlona/code-refs

Try it first without sending anything:

npx @maxlona/code-refs --dry-run

Scanned 1,204 files in acme/web@main (3f9c2e1)
Found 38 references to 12 flags
  new-checkout     9  src/checkout/checkout.ts:42 +8 more
  dark-mode        4  src/theme/theme.service.ts:17 +3 more
Dry run: nothing was sent.

Run it in CI

Scan your main branch after every merge. Each scan replaces the previous one for that branch, so when a flag disappears from the code Maxlona notices and marks it removed from code.

GitHub Actions

on:
  push:
    branches: [main]
jobs:
  code-references:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx @maxlona/code-refs
        env:
          MAXLONA_MANAGEMENT_KEY: ${{ secrets.MAXLONA_MANAGEMENT_KEY }}

Azure Pipelines

trigger: [main]
steps:
  - task: NodeTool@0
    inputs: { versionSpec: '20.x' }
  - script: npx @maxlona/code-refs
    env:
      MAXLONA_MANAGEMENT_KEY: $(MAXLONA_MANAGEMENT_KEY)

GitLab CI

code-references:
  image: node:20
  rules: [{ if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' }]
  script: npx @maxlona/code-refs

Options

| Option | Default | | | --- | --- | --- | | --key <key> | MAXLONA_MANAGEMENT_KEY | Management API key. Read-only is enough. | | --dir <path> | current folder | Folder to scan. | | --repo <name> | from CI or the git remote | Repository name, such as acme/web. | | --branch <name> | from CI or git | Branch being scanned. | | --commit <sha> | from CI or git | Commit being scanned. | | --link <template> | from the remote | Link to a line, with {sha}, {path} and {line}. Must be https. | | --exclude <glob> | none | Skip matching paths. Repeat for more, such as --exclude "**/*.test.ts". | | --base-url <url> | MAXLONA_BASE_URL or https://maxlona.com | Where Maxlona runs. | | --dry-run | | Scan and print without sending. | | --fail-on-archived | | Exit with code 2 when code still uses an archived flag. Useful as a pull request check. | | --json | | Print the result as JSON. |

A key limited to one application only reports that application's flags.

What counts as a reference

A flag key written as a string literal ('new-checkout', "new-checkout" or `new-checkout`) anywhere in a text file. A key that only appears in a comment without quotes, or inside a longer string, is not counted. If you keep flag keys in constants, the constant's definition is the reference.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Scanned (and sent, unless --dry-run). | | 1 | Something went wrong; the message says what. | | 2 | --fail-on-archived found archived flags in code. |