LAMS is a style guide and linter for Looker's LookML data modeling language. It is designed to help a team of developers to produce more maintainable LookML projects.

• The style guide alone can help your project, even without enforcement by the linter.
• The linter can be configured to enforce rules from the style guide for all commits to your master branch.
• The linter also allows you to conveniently specify custom rules to enforce.
• In addition to enforcing rules, the linter also produces markdown files to help developers navigate the project.

Interested? See a video of LAMS in action!

• Functionality & Features
  • Predefined Linter Rules
  • Rule Exemptions
  • Generated Markdown Output
  • Custom Rules
• Deployment Examples
• Configuration
• About

The linter currently enforces rules K1-4, F1-4, E1-2, and T1-10 from the style guide.

It currently does not resolve extends references, so if you are complying with a rule via extension, use a rule exemption as noted below.

You can opt-out of rules either globally or granularly using rule_exemptions.

The rule exemption syntax encourages developers to document the reason for each such exemption:

view: rollup {
  derived_table: {
    sql_trigger_value: SELECT CURRENT_DATE() ;;
    # LAMS
    # rule_exemptions: {
    #  T1: "2018-11-12 - I can't use datagroups for this super special reason and Bob said it's ok"
    # }
    sql: SELECT ...

Note: For large projects with many exemptions, we suggest starting the reasons with the Y-M-D formatted date on which they were added, for easier review in your issue report.

If you want to entirely opt-out of checking a particular rule, you can specify the exemptions in your project's manifest.lkml file. See customizing LAMS for additional details.

One of the primary ways that LAMS gives developers feedback, in addition to any integrations with your CI workflow, is by adding its findings to markdown files in your project, so that they can be viewed in Looker's IDE. Here is an example of a resulting markdown file as displayed in Looker:

In addition to linting against its style guide, LAMS also lets you specify your own rules. See Customizing LAMS.

Although LAMS can be deployed in many ways to fit your specific CI flow, we have put together a few examples and resources to get you up and running quicker. (If you'd like to contribute your configuration, get in touch!)

• Local Interactive Usage - To use LAMS with the least overhead for simple interactive local use and testing:

npm install -g @looker/look-at-me-sideways
cd <your-lookml-project>
lams

• Github Action - This option is very quick to get started if you're using Github, and offers a compromise between convenience of setup and per-commit run performance.
• Dockerized Jenkins Server - We have provided a Docker image with an end-to-end configuration including a Jenkins server, LAMS, and Github protected branches & status checks configuration.
• GitLab CI - A community-contributed configuration for GitLab, which offers similarly low overhead as our dockerized Jenkins configuration
• CircleCI - A community-contributed configuration for CircleCI (external link)

• reporting - Required. One of yes, no, save-yes, or save-no. See PRIVACY.md for details.
• report-user - An email address to use in reporting. See PRIVACY.md for details.
• report-license-key - A Looker license key to use in reporting. See PRIVACY.md for details.
• cwd - A path for LAMS to use as its current working directory. Useful if you are not invoking lams from your LookML repo directory via the globally installed lams command.
• source - A glob specifying which files to read. Defaults to **/{*.model,*.explore,*.view,manifest}.lkml.
• project-name - An optional name for the project, used to generate links back to the project in mardown output. Specifying this in manifest.lkml is preferred.
• allow-custom-rules - Experimental option. DO NOT USE TO RUN UNTRUSTED CODE. Pass a value to allow running of externally defined JS for custom rules.
• jenkins - Set to indicate that LAMS is being run by Jenkins and to include the build URL from ENV variables in the markdown output.
• output-to-cli - Primarily intended for debugging. Setting it will output a verbose listing of errors and warnings to stdout. Set to a numerical value to determine the maximum number of entries to output for each of errors & warnings.
• on-parser-error - Set to "fail" to indicate that LookML parsing errors should fail the linter. By default, parsing errors are logged and ignored.
• date-output - Set to "none" to skip printing the date at the top of the issues.md file.

If your LookML project doesn't have a manifest.lkml file, you may want to consider adding one! LAMS uses the following information from your project's mainfest.lkml file:

• name - Recommended. A name for the project, used to generate links back to the project in mardown output. If the native LookML validator complains about an unnecessary project name, you can use a conditional #LAMS comment to specify it.
• rule_exemptions - Optional. Used to entirely opt out of rules. See customizing LAMS
• rule: rule_name - Optional. Used to specify custom rules. See customizing LAMS

LAMS respects user privacy. See PRIVACY.md for details.

LAMS is Copyright (c) 2018 Looker Data Sciences, Inc. and is licensed under the MIT License. See LICENSE.txt for license details.

LAMS is NOT officially supported by Looker. Please do not contact Looker support for issues with LAMS. Issues may be reported via the Issues tracker, but no SLA or warranty exists that they will be resolved.

LAMS has primarily been developed by Joseph Axisa and Fabio Beltramini. See all contributors

Bug reports and pull requests are welcome on GitHub at https://github.com/looker-open-source/look-at-me-sideways.

Trying to install LAMS for development?

git clone [email protected]:looker-open-source/look-at-me-sideways.git
cd look-at-me-sideways
mv npm-shrinkwrap.dev.json npm-shrinkwrap.json 
npm install

Publishing an update? The following hooks will run:

npm version {minor|major|patch}
> Pre-verion: npm run lint-fix
> Pre-verion: npm run test

npm publish
> Pre-publish: npm shrinkwrap
> Pre-publish: mv npm-shrinkwrap.json npm-shrinkwrap.dev.json
> Pre-publish: npm prune --prod
> Pre-publish: npm shrinkwrap

This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributer Covenant Code of Conduct. Concerns or incidents may be reported confidentially to [email protected].

>_>