pbiplint 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,9 @@
 # pbiplint
 
 Best-practice linter for Power BI semantic models. Point it at a `.SemanticModel` folder, a PBIP
-folder, or one `.tmdl` file and get ranked findings with a link to a fix page for each rule.
-Nothing is uploaded: it reads the files you name and writes to your terminal. Node 20 or later.
+folder, a `definition` folder, or one `.tmdl` file and get ranked findings with a link to a fix
+page for each rule. Nothing is uploaded: it reads the files you name and writes to your terminal.
+Node 20 or later.
 
 ```bash
 npx pbiplint path/to/Model.SemanticModel
@@ -10,12 +11,15 @@ npx pbiplint --sample                                       # a bundled model wi
 npx pbiplint path/to/model --format sarif --output pbiplint.sarif
 npx pbiplint path/to/model --format markdown
 npx pbiplint rules                                          # every rule with status and severity
+npx pbiplint --help                                         # every option, in one screen
+npx pbiplint --version
 ```
 
 Formats: `text` (default), `json`, `sarif` (for GitHub code scanning and editors), `markdown`.
 
-Exit codes: `0` no findings at or above `--fail-on` (default `error`), `1` findings, `2` usage or
-input error. `--fail-on warning` tightens the gate; `--fail-on none` always exits 0.
+Exit codes: `0` no findings at or above `--fail-on`, `1` findings, `2` usage or input error.
+`--fail-on error` is the default; `--fail-on warning` and `--fail-on info` tighten the gate;
+`--fail-on none` always exits 0.
 
 ## Configuration
 

package/dist/pbiplint.mjs

@@ -5,7 +5,7 @@ import { mkdirSync, writeFileSync } from "node:fs";
 import { basename as basename2, dirname as dirname4, relative as relative2, resolve as resolve3 } from "node:path";
 
 // ../core/src/version.ts
-var VERSION = "0.1.0";
+var VERSION = "0.1.2";
 
 // ../core/src/engine/config.ts
 var ConfigError = class extends Error {
@@ -36,6 +36,8 @@ function resolveConfig(raw = {}) {
   for (const k of Object.keys(raw))
     if (k !== "rules" && k !== "failOn" && k !== "$schema")
       throw new ConfigError(`pbiplint.config.json: unknown key "${k}"`);
+  if (raw.$schema !== void 0 && typeof raw.$schema !== "string")
+    throw new ConfigError('pbiplint.config.json: "$schema" must be a string');
   const out = { disabled: /* @__PURE__ */ new Set(), severity: /* @__PURE__ */ new Map(), failOn: 3 };
   if (raw.rules !== void 0) {
     if (!isRecord(raw.rules))
@@ -2320,34 +2322,31 @@ function parseTmdl(file, text) {
   const roots = [];
   const issues = [];
   const stack = [];
-  let pendingDescription = [];
-  let descriptionLine = 0;
-  let descriptionText = "";
+  let pendingDescription = null;
+  const orphanDescription = (pending) => {
+    issues.push({
+      file,
+      line: pending.line,
+      text: pending.text,
+      reason: "description is not followed by a declaration"
+    });
+    pendingDescription = null;
+  };
   let i = 0;
   while (i < lines.length) {
     const raw = lines[i];
     const lineNo = i + 1;
     if (raw.trim() === "") {
-      if (pendingDescription.length) {
-        issues.push({
-          file,
-          line: descriptionLine,
-          text: descriptionText,
-          reason: "description is not followed by a declaration"
-        });
-        pendingDescription = [];
-      }
+      if (pendingDescription) orphanDescription(pendingDescription);
       i++;
       continue;
     }
     const indent = tabIndent(raw);
     const content = raw.slice(indent);
     if (content.startsWith("///")) {
-      if (!pendingDescription.length) {
-        descriptionLine = lineNo;
-        descriptionText = raw;
-      }
-      pendingDescription.push(content.replace(/^\/\/\/ ?/, ""));
+      const line = content.replace(/^\/\/\/ ?/, "");
+      if (pendingDescription) pendingDescription.lines.push(line);
+      else pendingDescription = { line: lineNo, text: raw, lines: [line] };
       i++;
       continue;
     }
@@ -2390,7 +2389,7 @@ function parseTmdl(file, text) {
         j++;
       }
       if (j >= lines.length)
-        issues.push({ file, line: lineNo, text: raw, reason: "unterminated ``` fence" });
+        issues.push({ file, line: lineNo, text: raw, reason: "unterminated code fence" });
       const boundary = j < lines.length ? leadingWs(lines[j]) : 0;
       i = j;
       return out.map((l) => l.slice(Math.min(boundary, leadingWs(l)))).join("\n");
@@ -2424,9 +2423,9 @@ function parseTmdl(file, text) {
         node = { ...base, kind: "flag", type: h.type.toLowerCase() };
       }
     }
-    if (pendingDescription.length) {
-      node.description = pendingDescription.join("\n");
-      pendingDescription = [];
+    if (pendingDescription) {
+      node.description = pendingDescription.lines.join("\n");
+      pendingDescription = null;
     }
     stack.length = indent;
     const parent = indent > 0 ? stack[indent - 1] : void 0;
@@ -2445,6 +2444,7 @@ function parseTmdl(file, text) {
     stack[indent] = node;
     i++;
   }
+  if (pendingDescription) orphanDescription(pendingDescription);
   return { file, roots, issues, lineCount: lines.length };
 }
 
@@ -2490,7 +2490,7 @@ function rank(findings, rules, config) {
     g.findings.push(f);
   }
   return [...groups.values()].sort(
-    (a, b) => b.rule.severity - a.rule.severity || CATEGORY_ORDER.indexOf(a.rule.category) - CATEGORY_ORDER.indexOf(b.rule.category) || b.findings.length - a.findings.length || a.rule.id.localeCompare(b.rule.id)
+    (a, b) => b.rule.severity - a.rule.severity || CATEGORY_ORDER.indexOf(a.rule.category) - CATEGORY_ORDER.indexOf(b.rule.category) || b.findings.length - a.findings.length || a.rule.id.localeCompare(b.rule.id, "en")
   );
 }
 
@@ -3132,15 +3132,15 @@ Read more: https://pbiplint.com/rules/large-tables-should-be-partitioned`,
     markdown: "### Why it matters\n\nWith a default summarization, dragging the column onto a visual produces an implicit sum, and it is easy to sum something that should never be summed: a year, a unit price, a percentage, a key. The implicit measure also bypasses the format string and the logic of the real measures, so two visuals of the same thing disagree. With summarization off, the column lands on a visual as a category and the author reaches for a measure.\n\n### How to fix it\n\nIn Power BI Desktop, select the column and set Summarization to Don't summarize under Column tools. In the TMDL file the property is `summarizeBy: none`. Create explicit measures for the aggregations reports need.\n\n### Quirks\n\n- A column with no summarizeBy property is treated as Default, which is not None, so it is flagged.\n\nRead more: https://pbiplint.com/rules/numeric-column-summarize-by"
   },
   OBJECTS_SHOULD_NOT_START_OR_END_WITH_A_SPACE: {
-    text: 'Why it matters\n\nA leading or trailing space is invisible on screen but is part of the name, so "Sales " and "Sales" are two different objects to the engine. That is enough to break a DAX reference, a report visual binding, or a deployment that expects the trimmed name, and the error you get back will name an object that looks perfectly correct. Stray spaces almost always arrive by accident, pasted in or inherited from a source column name, so trimming them is safe and rarely breaks anything downstream. TRIM_OBJECT_NAMES makes the same check across more object types at a lower severity, so every finding here appears there as well.\n\nHow to fix it\n\nRename the object without the space in Power BI Desktop, which updates the visuals and DAX that reference it, or edit the name in the TMDL file.\n\nQuirks\n\n- Narrower scope than TRIM_OBJECT_NAMES: levels, roles, expressions, calculation items, calculated tables, and calculated table columns are not checked here.\n\nRead more: https://pbiplint.com/rules/objects-should-not-start-or-end-with-a-space',
-    markdown: '### Why it matters\n\nA leading or trailing space is invisible on screen but is part of the name, so "Sales " and "Sales" are two different objects to the engine. That is enough to break a DAX reference, a report visual binding, or a deployment that expects the trimmed name, and the error you get back will name an object that looks perfectly correct. Stray spaces almost always arrive by accident, pasted in or inherited from a source column name, so trimming them is safe and rarely breaks anything downstream. `TRIM_OBJECT_NAMES` makes the same check across more object types at a lower severity, so every finding here appears there as well.\n\n### How to fix it\n\nRename the object without the space in Power BI Desktop, which updates the visuals and DAX that reference it, or edit the name in the TMDL file.\n\n### Quirks\n\n- Narrower scope than `TRIM_OBJECT_NAMES`: levels, roles, expressions, calculation items, calculated tables, and calculated table columns are not checked here.\n\nRead more: https://pbiplint.com/rules/objects-should-not-start-or-end-with-a-space'
+    text: 'Why it matters\n\nA leading or trailing space is invisible on screen but is part of the name, so "Sales " and "Sales" are two different objects to the engine. That is enough to break a DAX reference, a report visual binding, or a deployment that expects the trimmed name, and the error you get back will name an object that looks perfectly correct. Stray spaces almost always arrive by accident, pasted in or inherited from a source column name, so trimming them is safe and rarely breaks anything downstream. TRIM_OBJECT_NAMES makes the same check across more object types at a lower severity, so every finding here appears there as well.\n\nHow to fix it\n\nRename the object without the space in Power BI Desktop, which updates the visuals and DAX that reference it, or edit the name in the TMDL file.\n\nQuirks\n\n- Narrower scope than TRIM_OBJECT_NAMES: levels, roles, expressions, calculation items, calculated tables, and calculated table columns are not checked here.\n- In the browser, the "Choose a folder" button in Chrome and Edge does not list a file whose name begins or ends with a space, so a table file named that way is never read on that route and its findings are missing. Drag the folder onto the page, or use the command line, to read it.\n\nRead more: https://pbiplint.com/rules/objects-should-not-start-or-end-with-a-space',
+    markdown: '### Why it matters\n\nA leading or trailing space is invisible on screen but is part of the name, so "Sales " and "Sales" are two different objects to the engine. That is enough to break a DAX reference, a report visual binding, or a deployment that expects the trimmed name, and the error you get back will name an object that looks perfectly correct. Stray spaces almost always arrive by accident, pasted in or inherited from a source column name, so trimming them is safe and rarely breaks anything downstream. `TRIM_OBJECT_NAMES` makes the same check across more object types at a lower severity, so every finding here appears there as well.\n\n### How to fix it\n\nRename the object without the space in Power BI Desktop, which updates the visuals and DAX that reference it, or edit the name in the TMDL file.\n\n### Quirks\n\n- Narrower scope than `TRIM_OBJECT_NAMES`: levels, roles, expressions, calculation items, calculated tables, and calculated table columns are not checked here.\n- In the browser, the "Choose a folder" button in Chrome and Edge does not list a file whose name begins or ends with a space, so a table file named that way is never read on that route and its findings are missing. Drag the folder onto the page, or use the command line, to read it.\n\nRead more: https://pbiplint.com/rules/objects-should-not-start-or-end-with-a-space'
   },
   OBJECTS_WITH_NO_DESCRIPTION: {
     text: "Why it matters\n\nThe description is the tooltip a report author sees when hovering a field in the field list, and it is the only place in the model to say what a measure counts, which currency a column is in, or which of two similar fields to use. Without it, every author works that out from the name, and gets it wrong at about the same rate. Descriptions also feed documentation tools, so the same sentence pays off twice.\n\nHow to fix it\n\nIn Power BI Desktop, open Model view, select the object, and type the Description in the Properties pane. In the TMDL file a description is one or more /// lines directly above the object. With hundreds of objects, Tabular Editor can paste descriptions into many objects at once; the TMDL comment lines need no other tool.\n\nQuirks\n\n- Visibility is the object's own isHidden flag: a visible column inside a hidden table is still reported.\n- A calculation group table is reported once, as a calculation group.\n\nRead more: https://pbiplint.com/rules/objects-with-no-description",
     markdown: "### Why it matters\n\nThe description is the tooltip a report author sees when hovering a field in the field list, and it is the only place in the model to say what a measure counts, which currency a column is in, or which of two similar fields to use. Without it, every author works that out from the name, and gets it wrong at about the same rate. Descriptions also feed documentation tools, so the same sentence pays off twice.\n\n### How to fix it\n\nIn Power BI Desktop, open Model view, select the object, and type the Description in the Properties pane. In the TMDL file a description is one or more `///` lines directly above the object. With hundreds of objects, Tabular Editor can paste descriptions into many objects at once; the TMDL comment lines need no other tool.\n\n### Quirks\n\n- Visibility is the object's own isHidden flag: a visible column inside a hidden table is still reported.\n- A calculation group table is reported once, as a calculation group.\n\nRead more: https://pbiplint.com/rules/objects-with-no-description"
   },
   PARSE_ISSUE: {
-    text: "Why it matters\n\nThe parser skipped the line, so whatever it declared, a column, a property, a measure, is missing from the model the rules see. Findings on that object and on anything that references it may be missing or wrong, and a result that looks clean may not be. The orphaned description is the mild case: no declaration is lost, only the description, which stops at the blank line instead of reaching the object below it, so that object is read as having none. Tabular Editor's TMDL reader is stricter and refuses to open a file that puts a blank line after a /// line at all.\n\nHow to fix it\n\nOpen the file at the reported line. TMDL is indented with tabs, and expression blocks open and close with  on their own lines. A /// description must sit directly above its declaration, with no blank line between them. Power BI Desktop writes valid TMDL, so a parse issue usually means a hand edit or a merge conflict marker.\n\nRead more: https://pbiplint.com/rules/parse-issue",
+    text: "Why it matters\n\nThe parser skipped the line, so whatever it declared, a column, a property, a measure, is missing from the model the rules see. Findings on that object and on anything that references it may be missing or wrong, and a result that looks clean may not be. The orphaned description is the mild case: no declaration is lost, only the description, which stops at the blank line instead of reaching the object below it, so that object is read as having none. Tabular Editor's TMDL reader is stricter and refuses to open a file that puts a blank line after a /// line at all.\n\nHow to fix it\n\nOpen the file at the reported line. TMDL is indented with tabs, and expression blocks open and close with ``` on their own lines. A /// description must sit directly above its declaration, with no blank line between them. Power BI Desktop writes valid TMDL, so a parse issue usually means a hand edit or a merge conflict marker.\n\nRead more: https://pbiplint.com/rules/parse-issue",
     markdown: "### Why it matters\n\nThe parser skipped the line, so whatever it declared, a column, a property, a measure, is missing from the model the rules see. Findings on that object and on anything that references it may be missing or wrong, and a result that looks clean may not be. The orphaned description is the mild case: no declaration is lost, only the description, which stops at the blank line instead of reaching the object below it, so that object is read as having none. Tabular Editor's TMDL reader is stricter and refuses to open a file that puts a blank line after a `///` line at all.\n\n### How to fix it\n\nOpen the file at the reported line. TMDL is indented with tabs, and expression blocks open and close with ``` on their own lines. A `///` description must sit directly above its declaration, with no blank line between them. Power BI Desktop writes valid TMDL, so a parse issue usually means a hand edit or a merge conflict marker.\n\nRead more: https://pbiplint.com/rules/parse-issue"
   },
   PARTITION_NAME_SHOULD_MATCH_TABLE_NAME_FOR_SINGLE_PARTITION_TABLES: {
@@ -3247,7 +3247,7 @@ import { basename, dirname as dirname3, join as join3, relative, resolve as reso
 var toPosix = (p) => p.split("\\").join("/");
 function readTmdlFiles(root, dir, out) {
   for (const entry of readdirSync(dir, { withFileTypes: true }).sort(
-    (a, b) => a.name.localeCompare(b.name)
+    (a, b) => a.name.localeCompare(b.name, "en")
   )) {
     const p = join3(dir, entry.name);
     if (entry.isDirectory()) readTmdlFiles(root, p, out);
@@ -3288,7 +3288,7 @@ function resolveModel(input) {
 }
 
 // src/main.ts
-var VERSION2 = true ? "0.1.0" : "0.0.0-dev";
+var VERSION2 = true ? "0.1.2" : "0.0.0-dev";
 function listRules() {
   const width = Math.max(...defaultRules.map((r) => r.id.length));
   return defaultRules.map(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pbiplint",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Lint Power BI semantic models (TMDL) for best-practice violations, with text, JSON, SARIF, and Markdown output. Nothing is uploaded.",
   "keywords": [
     "power-bi",
@@ -43,6 +43,6 @@
     "test:bundle": "node dist/pbiplint.mjs --sample --format json > /dev/null; test $? -eq 1"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || >=22.12.0"
   }
 }