dw-sdlc 0.4.0 → 0.5.0

package/README.md

@@ -34,6 +34,10 @@ alone, with the same lines, exit codes and document.
 { "scripts": { "check": "dw-sdlc gate" } }
 ```
 
+Under `gate.checks`, a Check the package ships is `true` for its defaults or an object of its options.
+`comment-budget` holds each comment block in the JavaScript, TypeScript and shell (`.sh`) files under
+its `roots` to `maxProseLines` lines of prose, 3 by default.
+
 ## Commands
 
 | command            | what it does                                                                        |

package/config/agentic.config.schema.json

@@ -331,7 +331,7 @@
               "additionalProperties": false
             },
             "comment-budget": {
-              "description": "The comment budget: each comment block in the JavaScript and TypeScript files under `roots` carries at most `maxProseLines` lines of prose, a line with a letter or a digit once the comment markers are off. A block is one `/* … */` comment or a run of `//` comments each alone on consecutive lines; a comment after code on its line is none.",
+              "description": "The comment budget: each comment block in the JavaScript, TypeScript and shell (`.sh`) files under `roots` carries at most `maxProseLines` lines of prose, a line with a letter or a digit once the comment markers are off. A block is one `/* … */` comment or a run of `//` or `#` comments each alone on consecutive lines; a comment after code on its line is none, and so is a shell `#` that does not start a word of code.",
               "type": ["boolean", "object"],
               "properties": {
                 "maxProseLines": {

package/dist/checks/comment-budget.js

@@ -1,9 +1,10 @@
 // `comment-budget`: a comment says what the code cannot, in a few lines. A block, one `/* … */` or a run
-// of `//` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
+// of `//` or shell `#` lines alone on theirs, carries at most `maxProseLines` lines with a letter or a digit.
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, matchesGlob } from "node:path";
 import { matching, treeFiles } from "./tree.js";
 const SOURCE = ["**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"];
+const SHELL = "**/*.sh";
 const REMEDY = "cut it to what the code cannot say, or move the reasoning into a doc and point at it";
 /** The characters after which a `/` opens a regular expression, not a division. */
 const BEFORE_REGEX = new Set("(,=:[!&|?{};+-*%<>~^");
@@ -94,7 +95,170 @@ function commentsOf(text) {
     }
     return comments;
 }
-/** The comments as blocks: a run of `//` lines alone on consecutive lines is one; a comment after code is none. */
+/** The characters that end a shell word, so a `#` after one opens a comment. */
+const WORD_BREAK = new Set(" \t\n;&|()<>");
+/** Where the line that holds `index` ends: at its newline, or at the end of `text`. */
+function lineEnd(text, index) {
+    const newline = text.indexOf("\n", index);
+    return newline === -1 ? text.length : newline;
+}
+/** Where a span that `closer` ends, read from `start`, stops, past the closer; `\` escapes a character when `escapes`. */
+function spanEnd(text, start, closer, escapes) {
+    for (let index = start; index < text.length; index += 1) {
+        if (escapes && text.charAt(index) === "\\") {
+            index += 1;
+        }
+        else if (text.charAt(index) === closer) {
+            return index + 1;
+        }
+    }
+    return text.length;
+}
+/** The heredoc whose `<<` is at `start`, its delimiter's quotes off, and where the delimiter's word ends. */
+function heredocAt(text, start) {
+    const strip = text.charAt(start + 2) === "-";
+    let index = start + (strip ? 3 : 2);
+    while (text.charAt(index) === " " || text.charAt(index) === "\t") {
+        index += 1;
+    }
+    let end = index;
+    while (end < text.length && !WORD_BREAK.has(text.charAt(end))) {
+        const char = text.charAt(end);
+        end = char === "'" || char === '"' ? spanEnd(text, end + 1, char, false) : end + (char === "\\" ? 2 : 1);
+    }
+    return { delimiter: text.slice(index, end).replace(/["'\\]/g, ""), strip, end };
+}
+/** Where the heredoc body that starts at `start` ends: past the line that is its delimiter. */
+function heredocEnd(text, start, { delimiter, strip }) {
+    for (let index = start; index < text.length;) {
+        const end = lineEnd(text, index);
+        const line = text.slice(index, end);
+        index = end + 1;
+        if ((strip ? line.replace(/^\t+/, "") : line) === delimiter) {
+            return index;
+        }
+    }
+    return text.length;
+}
+/** The character that opens a nesting inside each frame and the one that closes it; a double quote has none. */
+const NESTING = {
+    code: ["(", ")"],
+    arithmetic: ["(", ")"],
+    expansion: ["{", "}"],
+    double: []
+};
+/**
+ * Every `#` comment in shell `text`: a `#` that starts a word of code, never one in a quote, an
+ * expansion, an arithmetic `((…))` or a heredoc body, nor the shebang on line 1.
+ */
+function shellCommentsOf(text) {
+    const comments = [];
+    const newlines = [...text.matchAll(/\n/g)].map((match) => match.index);
+    const outer = [];
+    let frame = { kind: "code", depth: 0 };
+    const heredocs = [];
+    let wordStart = true;
+    let index = text.startsWith("#!") ? lineEnd(text, 0) : 0;
+    const open = (kind, length) => {
+        outer.push(frame);
+        frame = { kind, depth: 0 };
+        index += length;
+        wordStart = true;
+    };
+    const close = (length) => {
+        frame = outer.pop() ?? frame;
+        index += length;
+        wordStart = false;
+    };
+    const skipTo = (end) => {
+        index = end;
+        wordStart = false;
+    };
+    while (index < text.length) {
+        const char = text.charAt(index);
+        const next = text.charAt(index + 1);
+        const { kind } = frame;
+        const [opener, closer] = NESTING[kind];
+        if (char === "\\" && next === "\n") {
+            index += 2;
+        }
+        else if (char === "\\") {
+            skipTo(index + 2);
+        }
+        else if (kind === "double" && char === '"') {
+            close(1);
+        }
+        else if (char === "$" && text.startsWith("((", index + 1)) {
+            open("arithmetic", 3);
+        }
+        else if (char === "$" && next === "(") {
+            open("code", 2);
+        }
+        else if (char === "$" && next === "{") {
+            open("expansion", 2);
+        }
+        else if (char === "`") {
+            skipTo(spanEnd(text, index + 1, "`", true));
+        }
+        else if (kind === "double") {
+            index += 1;
+        }
+        else if (char === "$" && next === "'") {
+            skipTo(spanEnd(text, index + 2, "'", true));
+        }
+        else if (char === "'") {
+            skipTo(spanEnd(text, index + 1, "'", false));
+        }
+        else if (char === '"') {
+            open("double", 1);
+        }
+        else if (kind === "code" && char === "#" && wordStart) {
+            const end = lineEnd(text, index);
+            const line = newlines.filter((newline) => newline < index).length + 1;
+            const alone = text.slice(text.lastIndexOf("\n", index - 1) + 1, index).trim() === "";
+            comments.push({ kind: alone ? "line" : "trailing", start: line, end: line, text: text.slice(index, end) });
+            index = end;
+        }
+        else if (kind === "code" && char === "\n") {
+            index += 1;
+            for (const heredoc of heredocs.splice(0)) {
+                index = heredocEnd(text, index, heredoc);
+            }
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<<", index)) {
+            index += 3;
+            wordStart = true;
+        }
+        else if (kind === "code" && text.startsWith("<<", index)) {
+            const { end, ...heredoc } = heredocAt(text, index);
+            heredocs.push(heredoc);
+            skipTo(end);
+        }
+        else if (kind === "code" && text.startsWith("((", index)) {
+            open("arithmetic", 2);
+        }
+        else if (char === opener) {
+            frame.depth += 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && frame.depth > 0) {
+            frame.depth -= 1;
+            index += 1;
+            wordStart = true;
+        }
+        else if (char === closer && outer.length > 0) {
+            close(kind === "arithmetic" && next === ")" ? 2 : 1);
+        }
+        else {
+            wordStart = WORD_BREAK.has(char);
+            index += 1;
+        }
+    }
+    return comments;
+}
+/** The comments as blocks: a run of `//` or `#` lines alone on consecutive lines is one; a comment after code is none. */
 function blocksOf(comments) {
     const blocks = [];
     for (const comment of comments) {
@@ -123,8 +287,9 @@ function proseLines(block) {
 }
 function run(root, { maxProseLines, roots }) {
     const findings = [];
-    for (const file of matching(root, treeFiles(root, roots), SOURCE)) {
-        for (const block of blocksOf(commentsOf(readFileSync(join(root, file), "utf8")))) {
+    for (const file of matching(root, treeFiles(root, roots), [...SOURCE, SHELL])) {
+        const text = readFileSync(join(root, file), "utf8");
+        for (const block of blocksOf(matchesGlob(file, SHELL) ? shellCommentsOf(text) : commentsOf(text))) {
             const prose = proseLines(block.text);
             if (prose > maxProseLines) {
                 const message = `a comment block of ${prose} prose lines, over the ${maxProseLines}-line budget`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dw-sdlc",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "The Gate and the agentic config of a repository: the dw-sdlc bin with the Gate, the setup, the doctor, the config check, and the Sync and setup of References; the resolver of the config's layers, its JSON Schema and the validator that reads it.",
   "license": "MIT",
   "repository": {