Merge branch 'master' into fabble/explore-rules-2023q3

README.md

@@ -53,9 +53,13 @@ As of LAMS v3, you must opt-in via your `manifest.lkml` file to use the built-in
 #rule: W1{} # Block indentation
 ```
 
+### Custom Rules
+
+In addition to linting against its [style guide](https://looker-open-source.github.io/look-at-me-sideways/rules.html), LAMS also lets you specify your own rules. See [Customizing LAMS](https://looker-open-source.github.io/look-at-me-sideways/customizing-lams).
+
 ### Rule Exemptions
 
-You can opt-out of rules granularly using `rule_exemptions`.
+You can opt-out of rules granularly by locally specifying `rule_exemptions`.
 
 The rule exemption syntax encourages developers to document the reason for each such exemption:
 
@@ -71,9 +75,15 @@ view: rollup {
   ...
 ```
 
-### Custom Rules
+(BETA) You can also opt-out of rules granularly from a centrally maintained `lams-exemptions.ndjson` file. Simply specify the rule name and location to exempt in a series of newline-terminated JSON objects:
 
-In addition to linting against its [style guide](https://looker-open-source.github.io/look-at-me-sideways/rules.html), LAMS also lets you specify your own rules. See [Customizing LAMS](https://looker-open-source.github.io/look-at-me-sideways/customizing-lams).
+```js
+{"rule":"K3","location":"model:my_model/view:rollup"}
+{"rule":"K3","location":"model:my_other_model/view:foo"}
+
+```
+
+You may also apply rule_exemptions globally in your project.manifest, but this is generally unnecessary as of LAMS v3.
 
 ### Output
 
@@ -116,7 +126,7 @@ The following examples were prepared for v1 of LAMS, though updating them for v2
 - **reporting** - Required. One of `yes`, `no`, `save-yes`, or `save-no`. See [PRIVACY.md](https://github.com/looker-open-source/look-at-me-sideways/blob/master/PRIVACY.md) for details.
 - **report-user** - An email address to use in reporting. See [PRIVACY.md](https://github.com/looker-open-source/look-at-me-sideways/blob/master/PRIVACY.md) for details.
 - **report-license-key** - A Looker license key to use in reporting. See [PRIVACY.md](https://github.com/looker-open-source/look-at-me-sideways/blob/master/PRIVACY.md) for details.
-- **output** - A comma-separated string of output modes from among: `lines` (default), `markdown`, `markdown-developer`, `jenkins`, `legacy-cli`
+- **output** - A comma-separated string of output modes from among: `lines` (default), `markdown`, `markdown-developer`, `jenkins`, `legacy-cli`, or (BETA) `add-exemptions`
 - **source** - A glob specifying which files to read. Defaults to `**/{*.model,*.explore,*.view,manifest}.lkml`.
 - **cwd** - A path for LAMS to use as its current working directory. Useful if you are not invoking lams from your LookML repo directory.
 - **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.

__tests__/dummy-projects/27-output-add-exemptions/.gitignore

@@ -0,0 +1 @@
+lams-exemptions.ndjson

__tests__/dummy-projects/27-output-add-exemptions/index.test.js

@@ -0,0 +1,90 @@
+const lams = require('../../../index.js')
+const mocks = require('../../../lib/mocks.js')
+const path= require('path')
+const defaultTestingOptions = {reporting:"no", cwd:__dirname}
+require('../../../lib/expect-to-contain-message');
+const log = x=>console.log(x)
+const testProjectName = __dirname.split(path.sep).slice(-1)[0];
+const fs = require("node:fs/promises")
+const expectedOutput = '{"rule":"K1","location":"model:test/view:bad"}\n';
+describe('Projects', () => {
+	describe(testProjectName, () => {
+		let {spies, process, console} = mocks()
+		let messages1, messages2, output1, output2
+		beforeAll( async () => {
+			const options = {
+				...defaultTestingOptions,
+				output: "add-exemptions"
+			}
+			const outputPath = path.resolve(__dirname,"lams-exemptions.ndjson")
+			try{await fs.rm(outputPath, {force:true})}catch(e){}
+			messages1 = {messages: await lams(options,{process, console})}
+			output1 = await fs.readFile(outputPath,{encoding:"utf8"})
+			messages2 = {messages: await lams(options,{process, console})}
+			output2 = await fs.readFile(outputPath,{encoding:"utf8"})
+		})
+		it("should not error out", ()=> {
+			expect(console.error).not.toHaveBeenCalled()
+		});
+		it("it should not contain any unexpected parser (P0) errors", ()=> {
+			expect(messages1).not.toContainMessage({
+				rule: "P0",
+				level: "error"
+			});
+			expect(messages2).not.toContainMessage({
+				rule: "P0",
+				level: "error"
+			});
+		});
+		it("it should not contain any parser syntax (P1) errors", ()=> {
+			expect(messages1).not.toContainMessage({
+				rule: "P1",
+				level: "error"
+			});
+			expect(messages2).not.toContainMessage({
+				rule: "P1",
+				level: "error"
+			});
+		});
+
+		it("run 1 should match K1 (1 match, 0 exempt, 1 error)", ()=> {
+			expect(messages1).toContainMessage({
+				rule: "K1",
+				level: "info",
+				description: "Rule K1 summary: 1 matches, 0 matches exempt, and 1 errors"
+			});
+		});
+
+		it("run 1 should error on K1", ()=> {
+			expect(messages1).toContainMessage({
+				rule: "K1",
+				level: "error"
+			});
+		});
+
+		it("run 1 should output the expected ndjson", ()=> {
+			expect(output1).toEqual(expectedOutput);
+		});
+
+		it("run 2 should match K1 (1 match, 1 exempt, 0 errors)", ()=> {
+			expect(messages2).toContainMessage({
+				rule: "K1",
+				level: "info",
+				description: "Rule K1 summary: 1 matches, 1 matches exempt, and 0 errors"
+			});
+		});
+
+		it("run 2 not should error on K1", ()=> {
+			expect(messages2).not.toContainMessage({
+				rule: "K1",
+				level: "error"
+			});
+		});
+
+		it("run 2 should output the (same) expected ndjson", ()=> {
+			expect(output2).toEqual(expectedOutput);
+		});
+
+
+	});
+});

__tests__/dummy-projects/27-output-add-exemptions/manifest.lkml

@@ -0,0 +1,2 @@
+#LAMS
+#rule: K1 {}

__tests__/dummy-projects/27-output-add-exemptions/test.model.lkml

@@ -0,0 +1,7 @@
+
+explore: bad {}
+
+view: bad {
+	sql_table_name: foo ;;
+	dimension: not_a_pk {}
+}

__tests__/template-functions.test.js

@@ -1,5 +1,5 @@
 /* Copyright (c) 2018 Looker Data Sciences, Inc. See https://github.com/looker-open-source/look-at-me-sideways/blob/master/LICENSE.txt */
-const {groupBy} = require('../lib/template-functions.js');
+const {groupBy} = require('../lib/outputters/templating/template-functions.js');
 
 describe('Template Functions', () => {
 	describe('groupBy', () => {

docs/github-action.md

@@ -3,14 +3,14 @@ favicon: img/logo.png
 ---
 # Running LAMS via Github Actions
 
-This example shows how to run LAMS with Github Actions.
+- Inside your Github-connected LookML repo, you can specify [Github Actions](https://docs.github.com/en/actions) in `.github/workflows/main.yml`
+- Populate the parameters within the "Run LAMS" step (see `XXXXX` placeholders below)
+- Note: This configuration is helpful alongside pull requests. [Set "Pull Requests Required" within Looker](https://cloud.google.com/looker/docs/git-options#integrating_pull_requests_for_your_project).
+- Note: This configuration is helpful alongside Github's [protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) feature
 
-Note: As compared to our dockerized Jenkins configuration, Github Actions is a quicker way to get set up, but may be slower since the former does not require as much set-up per run (Node.js installation, LAMS installation), and can run on a dedicated instance. 
+# Standard configuration
 
-## Instructions
-
-- Inside your Github-connected LookML repo, add the following file at `.github/workflows/main.yml`
-- Populate the parameters within the "Run LAMS" step & uncomment
+This configuration is useful alongside
 
 <!-- {% raw %} -->
 ```yaml
@@ -33,6 +33,10 @@ jobs:
       run: npm install -g @looker/look-at-me-sideways@3
     - name: Run LAMS
       # See [PRIVACY.md](https://github.com/looker-open-source/look-at-me-sideways/blob/master/PRIVACY.md)
-      run: lams --reporting=... --report-license-key=... --report-user=...
+      run: lams --reporting=XXXXX --report-license-key=XXXXX --report-user=XXXXX
 ```
 <!-- {% endraw %}) -->
+
+# ([BETA](https://github.com/looker-open-source/look-at-me-sideways/issues/142)) Incremental configuration
+
+If at any point (for example, manually, or upon merging a set of changes), you wish to exempt all current errors in future runs, you can run LAMS with  `--output=add-exemptions` and add the resulting/updated `lams-exemptions.ndjson` file to your repo.

docs/release-notes/v3.md

@@ -56,3 +56,13 @@ For any error not detailed below, please submit an issue!
 	- You may wish to update the view to comply with the style guide, or apply exemptions for the relevant rule(s)
 - If you have opted out of rules T2-T10
 	- These rules are now all bundled under rule T2. For a global exemption, you may simply omit rule T2 from your manifest. For local exemptions, or exemptions to the subrules, you may still exempt these individually, although the ID's of the rules have been updated. (For example, rule "T3" is now "T2.1")
+
+# v3.1
+
+This update introduces, as beta features, centrally managed exemptions, and an `add-exemptions` output mode. Together, these features serve to enable incremental linting use cases.
+
+Feedback on these beta features and the overall incremental linting use case is welcome in [issue #142](https://github.com/looker-open-source/look-at-me-sideways/issues/142).
+
+- **Centrally-managed exemptions**: (BETA) In addition to locally specified exemptions, LAMS can now also use exemptions in `lams-exemptions.ndjson` in a newline-delimited JSON format.
+	- If you wish to source this file from another location, you can pass the `` argument.
+- **Add exemptions as output**: (BETA) `output=add-exemptions` can append any errors from the current run as new exemptions in the `lams-exemptions.ndjson` file.