@codefast/cli 0.5.0 → 0.6.0

package/dist/audit/domain/audit-file.js

@@ -20,7 +20,7 @@ export function hasRtlCompanion(fileTokens, expectedValue) {
     });
 }
 /**
- * Detect physical-direction Tailwind classes that should be logical or rtl:-paired.
+ * Detects physical-direction Tailwind classes that should be logical or rtl:-paired.
  *
  * @since 1.0.0-canary.7
  */

package/dist/audit/domain/comment-content.js

@@ -0,0 +1,178 @@
+/**
+ * Recognises comment content the repo bans outright: repo-document pointers and JSDoc type syntax.
+ */
+// "see <anything>.md" — a pointer at a repo document. A bare .md mention is allowed: code that
+// generates a markdown file legitimately names its own output.
+const docPointerPattern = /\bsee\b[^\n]*?[\w./-]+\.md\b/i;
+// The classic JSDoc `{type}` payload TSDoc drops — TS already declares the type.
+const jsdocTypePattern = /@(?:param|returns?|type|prop(?:erty)?)\s*\{/;
+// TSDoc separates the name from its description with a hyphen.
+const paramNoHyphenPattern = /^\s*\*\s*@(?:param|typeParam)\s+[\w.$[\]]+\s+(?!-\s)\S/;
+const blockTagPattern = /^\s*\*\s*@[a-z]/i;
+const sinceTagPattern = /^\s*\*\s*@since\b/;
+const lineCommentPattern = /^[ \t]*\/\//;
+const blockLinePattern = /^[ \t]*(?:\/\*|\*)/;
+const docBlockClosePattern = /^[ \t]*(?:\*.*)?\*\/[ \t]*$/;
+const paramTagPattern = /^\s*\*\s*@param\s+([\w.$]+)/;
+const declarationPattern = /^[ \t]*(?:export|const|let|var|function|class|interface|type|enum|async|declare)\b/;
+// A divider or a tooling directive above a doc block is not a stacked note.
+const dividerLinePattern = /^[ \t]*\/\/[ \t]*[-=─_*~#]{2,}/;
+const directiveLinePattern = /^[ \t]*\/\/[ \t]*(?:oxlint-|eslint-|@ts-|prettier-)/;
+/**
+ * Scans a source file's comments for banned content, in source order.
+ *
+ * @since 0.6.0
+ */
+export function scanCommentContent(content, language) {
+    const findings = [];
+    const lines = content.split(/\r?\n/);
+    let insideBlock = false;
+    let pendingSinceLine = 0;
+    let documentedParams = [];
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const trimmed = line.trim();
+        // Only a line-leading `/*` opens a block — a marker inside code or a string literal does not.
+        const opensBlock = trimmed.startsWith("/*") && !trimmed.includes("*/");
+        // A `//` run stacked directly above a doc block reads as a second doc — it belongs inside.
+        if (language === "js" && !insideBlock && trimmed.startsWith("/**")) {
+            let runStart = index;
+            while (runStart > 0 &&
+                lineCommentPattern.test(lines[runStart - 1]) &&
+                !dividerLinePattern.test(lines[runStart - 1]) &&
+                !directiveLinePattern.test(lines[runStart - 1])) {
+                runStart--;
+            }
+            if (runStart < index) {
+                findings.push({ line: runStart + 1, raw: lines[runStart].trim().slice(0, 80), defect: "stacked-doc" });
+            }
+        }
+        const isComment = insideBlock ||
+            opensBlock ||
+            (language === "js" ? lineCommentPattern.test(line) || blockLinePattern.test(line) : trimmed.startsWith("/*"));
+        if (opensBlock) {
+            insideBlock = true;
+        }
+        if (insideBlock && trimmed.includes("*/")) {
+            insideBlock = false;
+            pendingSinceLine = 0;
+        }
+        if (!isComment) {
+            continue;
+        }
+        const pointer = docPointerPattern.exec(line);
+        if (pointer !== null) {
+            findings.push({ line: index + 1, raw: pointer[0].trim(), defect: "doc-pointer" });
+        }
+        if (jsdocTypePattern.test(line)) {
+            findings.push({ line: index + 1, raw: trimmed.slice(0, 80), defect: "jsdoc-type" });
+        }
+        if (paramNoHyphenPattern.test(line)) {
+            findings.push({ line: index + 1, raw: trimmed.slice(0, 80), defect: "param-hyphen" });
+        }
+        // `@since` is stamped at release and stays the block's last tag; any tag after it is misplaced.
+        if (insideBlock && sinceTagPattern.test(line)) {
+            pendingSinceLine = index + 1;
+        }
+        else if (pendingSinceLine > 0 && blockTagPattern.test(line)) {
+            findings.push({ line: pendingSinceLine, raw: trimmed.slice(0, 80), defect: "since-order" });
+            pendingSinceLine = 0;
+        }
+        const paramTag = paramTagPattern.exec(line);
+        if (insideBlock && paramTag !== null) {
+            documentedParams.push(paramTag[1].split(".", 1)[0]);
+        }
+        // A `//` run between a doc block and its declaration detaches the block from the symbol.
+        if (language === "js" && docBlockClosePattern.test(line) && index + 1 < lines.length) {
+            let cursor = index + 1;
+            while (cursor < lines.length && lineCommentPattern.test(lines[cursor])) {
+                cursor++;
+            }
+            if (cursor > index + 1 && cursor < lines.length && declarationPattern.test(lines[cursor])) {
+                findings.push({ line: index + 2, raw: lines[index + 1].trim().slice(0, 80), defect: "detached-doc" });
+            }
+            if (documentedParams.length > 0) {
+                const missing = missingSignatureParams(lines, index + 1, documentedParams);
+                if (missing.length > 0) {
+                    findings.push({ line: index + 1, raw: `@param missing: ${missing.join(", ")}`, defect: "param-coverage" });
+                }
+            }
+            documentedParams = [];
+        }
+    }
+    return findings;
+}
+// A partial list reads as a complete one, so a block naming any parameter must name them all.
+function missingSignatureParams(lines, startIndex, documented) {
+    // gather the declaration text up to a balanced top-level `(...)` group
+    let text = "";
+    let sawOpen = false;
+    let depth = 0;
+    for (let index = startIndex; index < Math.min(lines.length, startIndex + 40); index++) {
+        for (const ch of lines[index]) {
+            if (ch === "(") {
+                depth++;
+                sawOpen = true;
+                if (depth === 1) {
+                    continue;
+                }
+            }
+            else if (ch === ")") {
+                depth--;
+            }
+            if (sawOpen && depth > 0) {
+                text += ch;
+            }
+            if (sawOpen && depth === 0) {
+                return compareParams(text, documented);
+            }
+        }
+        if (sawOpen) {
+            text += "\n";
+        }
+    }
+    return [];
+}
+function compareParams(parameterListText, documented) {
+    const entries = [];
+    let depth = 0;
+    let current = "";
+    for (const ch of parameterListText) {
+        if ("([{<".includes(ch)) {
+            depth++;
+        }
+        else if (")]}>".includes(ch)) {
+            depth--;
+        }
+        if (ch === "," && depth === 0) {
+            entries.push(current);
+            current = "";
+        }
+        else {
+            current += ch;
+        }
+    }
+    if (current.trim().length > 0) {
+        entries.push(current);
+    }
+    const missing = [];
+    for (const entry of entries) {
+        const cleaned = entry.trim().replace(/^\.{3}/, "");
+        // A wrapper call or a destructured parameter cannot be matched by name — skip, never guess.
+        if (cleaned.startsWith("(")) {
+            return [];
+        }
+        if (cleaned.startsWith("{") || cleaned.startsWith("[")) {
+            continue;
+        }
+        const name = /^(?:readonly\s+)?([\w$]+)/.exec(cleaned)?.[1];
+        if (name === undefined || name === "this") {
+            continue;
+        }
+        if (!documented.includes(name)) {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+//# sourceMappingURL=comment-content.js.map

package/dist/audit/domain/comment-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-content.js","sourceRoot":"","sources":["../../../src/audit/domain/comment-content.ts"],"names":[],"mappings":"AAAA;;GAEG;AA4BH,+FAA+F;AAC/F,+DAA+D;AAC/D,MAAM,iBAAiB,GAAG,+BAA+B,CAAC;AAC1D,iFAAiF;AACjF,MAAM,gBAAgB,GAAG,6CAA6C,CAAC;AACvE,+DAA+D;AAC/D,MAAM,oBAAoB,GAAG,wDAAwD,CAAC;AACtF,MAAM,eAAe,GAAG,kBAAkB,CAAC;AAC3C,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAC5C,MAAM,kBAAkB,GAAG,aAAa,CAAC;AACzC,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAC9C,MAAM,oBAAoB,GAAG,6BAA6B,CAAC;AAC3D,MAAM,eAAe,GAAG,6BAA6B,CAAC;AACtD,MAAM,kBAAkB,GAAG,oFAAoF,CAAC;AAChH,4EAA4E;AAC5E,MAAM,kBAAkB,GAAG,gCAAgC,CAAC;AAC5D,MAAM,oBAAoB,GAAG,qDAAqD,CAAC;AAEnF;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,QAAsB;IACxE,MAAM,QAAQ,GAAiC,EAAE,CAAC;IAClD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,IAAI,WAAW,GAAG,KAAK,CAAC;IACxB,IAAI,gBAAgB,GAAG,CAAC,CAAC;IACzB,IAAI,gBAAgB,GAAkB,EAAE,CAAC;IAEzC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,8FAA8F;QAC9F,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACvE,2FAA2F;QAC3F,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,WAAW,IAAI,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YACnE,IAAI,QAAQ,GAAG,KAAK,CAAC;YACrB,OACE,QAAQ,GAAG,CAAC;gBACZ,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAE,CAAC;gBAC7C,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAE,CAAC;gBAC9C,CAAC,oBAAoB,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAE,CAAC,EAChD,CAAC;gBACD,QAAQ,EAAE,CAAC;YACb,CAAC;YACD,IAAI,QAAQ,GAAG,KAAK,EAAE,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,QAAQ,CAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;YAC1G,CAAC;QACH,CAAC;QACD,MAAM,SAAS,GACb,WAAW;YACX,UAAU;YACV,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAChH,IAAI,UAAU,EAAE,CAAC;YACf,WAAW,GAAG,IAAI,CAAC;QACrB,CAAC;QACD,IAAI,WAAW,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC1C,WAAW,GAAG,KAAK,CAAC;YACpB,gBAAgB,GAAG,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,CAAC,SAAS,EAAE,CAAC;YACf,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAG,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;YACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,IAAI,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC;QACtF,CAAC;QACD,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,gGAAgG;QAChG,IAAI,WAAW,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,gBAAgB,GAAG,KAAK,GAAG,CAAC,CAAC;QAC/B,CAAC;aAAM,IAAI,gBAAgB,GAAG,CAAC,IAAI,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,GAAG,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;YAC5F,gBAAgB,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,WAAW,IAAI,QAAQ,KAAK,IAAI,EAAE,CAAC;YACrC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;QACxD,CAAC;QAED,yFAAyF;QACzF,IAAI,QAAQ,KAAK,IAAI,IAAI,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;YACrF,IAAI,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;YACvB,OAAO,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAE,CAAC,EAAE,CAAC;gBACxE,MAAM,EAAE,CAAC;YACX,CAAC;YACD,IAAI,MAAM,GAAG,KAAK,GAAG,CAAC,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,IAAI,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAE,CAAC,EAAE,CAAC;gBAC3F,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC,CAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC;YACzG,CAAC;YACD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAChC,MAAM,OAAO,GAAG,sBAAsB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,EAAE,gBAAgB,CAAC,CAAC;gBAC3E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,mBAAmB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBAC7G,CAAC;YACH,CAAC;YACD,gBAAgB,GAAG,EAAE,CAAC;QACxB,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,8FAA8F;AAC9F,SAAS,sBAAsB,CAAC,KAAoB,EAAE,UAAkB,EAAE,UAAyB;IACjG,uEAAuE;IACvE,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,KAAK,GAAG,UAAU,EAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACtF,KAAK,MAAM,EAAE,IAAI,KAAK,CAAC,KAAK,CAAE,EAAE,CAAC;YAC/B,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,KAAK,EAAE,CAAC;gBACR,OAAO,GAAG,IAAI,CAAC;gBACf,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;oBAChB,SAAS;gBACX,CAAC;YACH,CAAC;iBAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACtB,KAAK,EAAE,CAAC;YACV,CAAC;YACD,IAAI,OAAO,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACzB,IAAI,IAAI,EAAE,CAAC;YACb,CAAC;YACD,IAAI,OAAO,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAC3B,OAAO,aAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QACD,IAAI,OAAO,EAAE,CAAC;YACZ,IAAI,IAAI,IAAI,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,aAAa,CAAC,iBAAyB,EAAE,UAAyB;IACzE,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,KAAK,MAAM,EAAE,IAAI,iBAAiB,EAAE,CAAC;QACnC,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YACxB,KAAK,EAAE,CAAC;QACV,CAAC;aAAM,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC/B,KAAK,EAAE,CAAC;QACV,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC;QACf,CAAC;aAAM,CAAC;YACN,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;IAED,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACnD,4FAA4F;QAC5F,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACvD,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,2BAA2B,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5D,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1C,SAAS;QACX,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/audit/domain/comment-dividers.js

@@ -0,0 +1,146 @@
+/**
+ * Recognises section dividers in source text and renders them in the one form the repo allows.
+ */
+/**
+ * The column every divider's rule ends at — `oxfmt`'s `printWidth`, indentation included.
+ *
+ * @since 0.6.0
+ */
+export const DIVIDER_COLUMN = 120;
+const RULE_GLYPH = "─";
+const LEAD_GLYPHS = "──";
+/** Every glyph a divider has historically been drawn with, so legacy forms are recognised too. */
+const RULE_CHARACTER_CLASS = String.raw `[-=─_*~#]`;
+const ruleOnlyLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*|\*)[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*(?:\*\/)?[ \t]*$`);
+const titledLinePattern = new RegExp(String.raw `^(?<indent>[ \t]*)(?:\/\/|\/\*)[ \t]*${RULE_CHARACTER_CLASS}{2,}[ \t]+(?<title>.*?)[ \t]+${RULE_CHARACTER_CLASS}{2,}[ \t]*(?:\*\/)?[ \t]*$`);
+const commentLinePattern = /^[ \t]*(?:\/\/|\/\*|\*)/;
+const bareRuleClosePattern = new RegExp(String.raw `^[ \t]*${RULE_CHARACTER_CLASS}{4,}[ \t]*\*\/[ \t]*$`);
+const rulesOnlyPattern = new RegExp(String.raw `^(?:${RULE_CHARACTER_CLASS}|[ \t])*$`);
+const commentPrefixPattern = /^[ \t]*(?:\/\/|\/\*|\*)[ \t]?/;
+const commentSuffixPattern = /[ \t]*\*\/[ \t]*$/;
+/** A banner spanning more lines than this is prose that happens to start with a rule, not a divider. */
+const MAX_BANNER_SPAN = 16;
+/** Past this a banner's lone line is a sentence the writer wanted kept, not a section name. */
+const MAX_TITLE_LENGTH = 60;
+/**
+ * Renders a divider in the canonical form.
+ *
+ * @param indent - leading whitespace copied from the site, counted toward the column
+ * @param title - the section name, already trimmed
+ * @param language - which comment syntax to draw the divider in
+ *
+ * @since 0.6.0
+ */
+export function renderDivider(indent, title, language) {
+    if (language === "css") {
+        const head = `${indent}/* ${LEAD_GLYPHS} ${title} `;
+        return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length - 3))} */`;
+    }
+    const head = `${indent}// ${LEAD_GLYPHS} ${title} `;
+    return `${head}${RULE_GLYPH.repeat(Math.max(2, DIVIDER_COLUMN - head.length))}`;
+}
+/**
+ * Every section divider in a file, canonical ones included, in source order.
+ *
+ * @remarks A rule-framed comment that carries prose is a doc block, not a divider, and never
+ * appears here — the two are different things and only one of them has a fixed form.
+ *
+ * @since 0.6.0
+ */
+export function scanCommentDividers(content, language) {
+    const lines = content.split(/\r?\n/);
+    const regions = [];
+    for (let index = 0; index < lines.length; index++) {
+        const region = readRegionAt(lines, index, language);
+        if (region === null) {
+            continue;
+        }
+        regions.push(region);
+        index = region.endLine - 1;
+    }
+    return regions;
+}
+/**
+ * Rewrites every off-convention divider into the canonical form.
+ *
+ * @since 0.6.0
+ */
+export function applyCommentDividerFixes(content, language) {
+    const regions = scanCommentDividers(content, language).filter((region) => region.defect !== null);
+    if (regions.length === 0) {
+        return { content, fixedCount: 0 };
+    }
+    const newline = content.includes("\r\n") ? "\r\n" : "\n";
+    const lines = content.split(/\r?\n/);
+    // Descending, so an earlier region's replacement cannot shift a later region's line numbers.
+    for (const region of [...regions].toReversed()) {
+        lines.splice(region.startLine - 1, region.endLine - region.startLine + 1, renderDivider(region.indent, region.title, language));
+    }
+    return { content: lines.join(newline), fixedCount: regions.length };
+}
+function readRegionAt(lines, index, language) {
+    const line = lines[index];
+    const titled = titledLinePattern.exec(line);
+    const title = titled?.groups?.title?.trim();
+    if (titled !== null && title !== undefined && title.length > 0 && !rulesOnlyPattern.test(title)) {
+        const indent = titled.groups?.indent ?? "";
+        const canonical = renderDivider(indent, title, language);
+        return {
+            startLine: index + 1,
+            endLine: index + 1,
+            indent,
+            title,
+            raw: line.trim(),
+            defect: line === canonical ? null : usesCanonicalGlyphs(line) ? "bad-width" : "legacy-form",
+        };
+    }
+    const ruleOnly = ruleOnlyLinePattern.exec(line);
+    if (ruleOnly === null) {
+        return null;
+    }
+    return readBannerAt(lines, index, ruleOnly.groups?.indent ?? "");
+}
+function readBannerAt(lines, index, indent) {
+    const line = lines[index];
+    // An unterminated `/*` opens a block whose body needs no per-line marker, so the run ends at `*/`.
+    const insideBlock = line.trimStart().startsWith("/*") && !line.includes("*/");
+    const body = [];
+    let cursor = index + 1;
+    while (cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && !isBannerClose(lines[cursor], insideBlock)) {
+        if (!insideBlock && !commentLinePattern.test(lines[cursor])) {
+            break;
+        }
+        body.push(stripCommentPrefix(lines[cursor]));
+        cursor++;
+    }
+    const closed = cursor < lines.length && cursor - index <= MAX_BANNER_SPAN && isBannerClose(lines[cursor], insideBlock);
+    const meaningful = body.filter((entry) => entry.length > 0);
+    // A frame around prose is a doc block, and an unclosed rule is prose formatting inside one.
+    if (!closed || meaningful.length !== 1 || !looksLikeTitle(meaningful[0])) {
+        return null;
+    }
+    return {
+        startLine: index + 1,
+        endLine: cursor + 1,
+        indent,
+        title: meaningful[0],
+        raw: line.trim(),
+        defect: "legacy-form",
+    };
+}
+function looksLikeTitle(text) {
+    return text.length <= MAX_TITLE_LENGTH && !text.endsWith(".");
+}
+function isBannerClose(line, insideBlock) {
+    if (ruleOnlyLinePattern.test(line)) {
+        return true;
+    }
+    return insideBlock && bareRuleClosePattern.test(line);
+}
+function usesCanonicalGlyphs(line) {
+    return line.trimStart().startsWith(`// ${LEAD_GLYPHS} `) || line.trimStart().startsWith(`/* ${LEAD_GLYPHS} `);
+}
+function stripCommentPrefix(line) {
+    return line.replace(commentPrefixPattern, "").replace(commentSuffixPattern, "").trim();
+}
+//# sourceMappingURL=comment-dividers.js.map

package/dist/audit/domain/comment-dividers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment-dividers.js","sourceRoot":"","sources":["../../../src/audit/domain/comment-dividers.ts"],"names":[],"mappings":"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"}

package/dist/audit/domain/link-references.js

@@ -0,0 +1,64 @@
+/**
+ * Resolves `{@link}` references against the scanned tree, so a rename that orphans one is caught.
+ */
+const linkPattern = /\{@link\s+([^}|\s]+)/g;
+const commentLinePattern = /^[ \t]*(?:\/\/|\/\*|\*)/;
+/**
+ * Every `{@link}` target in a file's comments, in source order.
+ *
+ * @since 0.6.0
+ */
+export function scanLinkReferences(content) {
+    const references = [];
+    const lines = content.split(/\r?\n/);
+    for (let index = 0; index < lines.length; index++) {
+        if (!commentLinePattern.test(lines[index])) {
+            continue;
+        }
+        for (const match of lines[index].matchAll(linkPattern)) {
+            references.push({ line: index + 1, target: match[1] });
+        }
+    }
+    return references;
+}
+/**
+ * The identifier a declaration-style target must resolve through — `Foo.bar` resolves via `Foo`.
+ *
+ * @since 0.6.0
+ */
+export function linkTargetHead(target) {
+    return target.split(/[.#]/, 1)[0];
+}
+/**
+ * Whether a target names a file or URL rather than a declaration.
+ *
+ * @since 0.6.0
+ */
+export function isPathLinkTarget(target) {
+    return (target.startsWith("http://") || target.startsWith("https://") || target.startsWith("./") || target.startsWith("../"));
+}
+/**
+ * Counts word-boundary occurrences of each head across a body of source text.
+ *
+ * @remarks A `{@link X}` occurrence itself mentions `X` once, so a target is orphaned when its
+ * total mentions do not exceed its link occurrences — a rename removes every real mention.
+ *
+ * @since 0.6.0
+ */
+export function countHeadMentions(contents, heads) {
+    const counts = new Map();
+    for (const head of heads) {
+        counts.set(head, 0);
+    }
+    const wordPattern = /[A-Za-z_$][\w$]*/g;
+    for (const content of contents) {
+        for (const match of content.matchAll(wordPattern)) {
+            const found = counts.get(match[0]);
+            if (found !== undefined) {
+                counts.set(match[0], found + 1);
+            }
+        }
+    }
+    return counts;
+}
+//# sourceMappingURL=link-references.js.map

package/dist/audit/domain/link-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link-references.js","sourceRoot":"","sources":["../../../src/audit/domain/link-references.ts"],"names":[],"mappings":"AAAA;;GAEG;AAaH,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAC5C,MAAM,kBAAkB,GAAG,yBAAyB,CAAC;AAErD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAe;IAChD,MAAM,UAAU,GAAyB,EAAE,CAAC;IAC5C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QAClD,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAE,CAAC,EAAE,CAAC;YAC5C,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,KAAK,CAAE,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YACxD,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC,CAAE,EAAE,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC;AACrC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,CACL,MAAM,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CACrH,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAA0B,EAAE,KAA0B;IACtF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtB,CAAC;IACD,MAAM,WAAW,GAAG,mBAAmB,CAAC;IACxC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAClD,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/audit/domain/markdown-links.js

@@ -0,0 +1,76 @@
+/**
+ * Extracts the two things a markdown cross-reference can get wrong: where it points and what it lands on.
+ */
+// Anything with a scheme, a protocol-relative host, or a bare mail address is somebody else's to check.
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i;
+/**
+ * The anchor ids a rendered document exposes: explicit `<a id>` targets plus every heading's slug.
+ *
+ * @remarks Slugging matches GitHub's — lowercase, drop everything that is not a letter, number, space
+ * or hyphen, then hyphenate spaces. Duplicate headings get a `-1` suffix there; this returns the base
+ * only, so a link to the second copy reads as dangling rather than being silently accepted.
+ *
+ * @since 0.5.0
+ */
+export function collectMarkdownAnchors(content) {
+    const anchors = new Set();
+    for (const match of content.matchAll(/<a\s+id="([^"]+)"\s*><\/a>/g)) {
+        anchors.add(match[1]);
+    }
+    for (const match of content.matchAll(/^#{1,6}\s+(.+?)\s*$/gm)) {
+        anchors.add(match[1]
+            .toLowerCase()
+            .replaceAll(/[^\p{L}\p{N} -]/gu, "")
+            .trim()
+            .replaceAll(/\s+/g, "-"));
+    }
+    return anchors;
+}
+/**
+ * Every repo-local link a document makes, with the anchors it offers.
+ *
+ * @remarks Fenced code is stripped first: a fence showing a link is an example, not a reference, and
+ * checking it would make the audit fail on documentation that is doing its job.
+ *
+ * @since 0.5.0
+ */
+export function scanMarkdownLinks(content) {
+    const withoutFences = content.replaceAll(/^```[\s\S]*?^```/gm, (block) => block.replaceAll(/[^\n]/g, " "));
+    const references = [];
+    for (const match of withoutFences.matchAll(/\[[^\]]*]\(\s*([^)\s]+?)\s*\)/g)) {
+        const raw = match[1];
+        if (EXTERNAL.test(raw)) {
+            continue;
+        }
+        const hashAt = raw.indexOf("#");
+        const targetPath = hashAt === -1 ? raw : raw.slice(0, hashAt);
+        const anchor = hashAt === -1 ? null : raw.slice(hashAt + 1);
+        if (targetPath === "" && anchor === null) {
+            continue;
+        }
+        references.push({
+            line: lineNumberAt(withoutFences, match.index),
+            targetPath: decodeTarget(targetPath),
+            anchor: anchor === null || anchor === "" ? null : decodeTarget(anchor),
+        });
+    }
+    return { references, anchors: collectMarkdownAnchors(content) };
+}
+function decodeTarget(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+function lineNumberAt(content, index) {
+    let line = 1;
+    for (let position = 0; position < index; position++) {
+        if (content.charCodeAt(position) === 10) {
+            line++;
+        }
+    }
+    return line;
+}
+//# sourceMappingURL=markdown-links.js.map

package/dist/audit/domain/markdown-links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-links.js","sourceRoot":"","sources":["../../../src/audit/domain/markdown-links.ts"],"names":[],"mappings":"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"}

package/dist/audit/domain/tokenize.js

@@ -1,5 +1,5 @@
 /**
- * Split a class token into [variant, value, modifier], colon/slash-aware of
+ * Splits a class token into [variant, value, modifier], colon/slash-aware of
  * brackets and parens (arbitrary values like data-[side=left] or calc(...)).
  *
  * @since 1.0.0-canary.7
@@ -48,7 +48,7 @@ export function splitClassName(token) {
     return [variant, value, modifier];
 }
 /**
- * Extract string/template literal contents with their line numbers.
+ * Extracts string/template literal contents with their line numbers.
  *
  * @since 1.0.0-canary.7
  */

package/dist/audit/domain/tsdoc-syntax.js

@@ -0,0 +1,33 @@
+import { TSDocConfiguration, TSDocParser, TSDocTagDefinition, TSDocTagSyntaxKind } from "@microsoft/tsdoc";
+const configuration = new TSDocConfiguration();
+// The repo's one custom tag, stamped at release by `codefast tag`.
+configuration.addTagDefinition(new TSDocTagDefinition({ tagName: "@since", syntaxKind: TSDocTagSyntaxKind.BlockTag }));
+configuration.setSupportForTags(configuration.tagDefinitions, true);
+const parser = new TSDocParser(configuration);
+// Only a line-leading `/**` opens a doc block — one inside code or a string literal does not.
+const docBlockPattern = /^[ \t]*\/\*\*[\s\S]*?\*\//gm;
+/**
+ * Every TSDoc grammar diagnostic in a file's doc blocks, in source order.
+ *
+ * @since 0.6.0
+ */
+export function scanTsdocSyntax(content) {
+    const findings = [];
+    for (const match of content.matchAll(docBlockPattern)) {
+        const context = parser.parseString(match[0]);
+        if (context.log.messages.length === 0) {
+            continue;
+        }
+        const blockLine = content.slice(0, match.index).split("\n").length;
+        for (const message of context.log.messages) {
+            const offsetInBlock = match[0].slice(0, message.textRange.pos).split("\n").length - 1;
+            findings.push({
+                line: blockLine + offsetInBlock,
+                raw: message.messageId,
+                reason: message.unformattedText,
+            });
+        }
+    }
+    return findings;
+}
+//# sourceMappingURL=tsdoc-syntax.js.map

package/dist/audit/domain/tsdoc-syntax.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tsdoc-syntax.js","sourceRoot":"","sources":["../../../src/audit/domain/tsdoc-syntax.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAkB3G,MAAM,aAAa,GAAG,IAAI,kBAAkB,EAAE,CAAC;AAC/C,mEAAmE;AACnE,aAAa,CAAC,gBAAgB,CAAC,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,kBAAkB,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;AACvH,aAAa,CAAC,iBAAiB,CAAC,aAAa,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;AACpE,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,aAAa,CAAC,CAAC;AAE9C,8FAA8F;AAC9F,MAAM,eAAe,GAAG,6BAA6B,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,MAAM,QAAQ,GAA8B,EAAE,CAAC;IAC/C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC;QACtD,MAAM,OAAO,GAAG,MAAM,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtC,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;QACnE,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC;YAC3C,MAAM,aAAa,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;YACtF,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,SAAS,GAAG,aAAa;gBAC/B,GAAG,EAAE,OAAO,CAAC,SAAS;gBACtB,MAAM,EAAE,OAAO,CAAC,eAAe;aAChC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/audit/output.js

@@ -41,4 +41,92 @@ export function formatRtlAuditJsonOutput(result, rootDir) {
         result,
     });
 }
+/**
+ * Exit `1` when any non-allowlisted broken link remains.
+ *
+ * @since 0.5.0
+ */
+export function exitCodeForLinkAuditResult(result) {
+    return result.breakageCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Human-readable link audit report.
+ *
+ * @since 0.5.0
+ */
+export function presentLinkAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.breakages) {
+            logger.out(`  ${line}: ${raw} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.breakageCount > 0) {
+        logger.out(`\n✖ ${result.breakageCount} broken link(s)${allowlistSuffix}`);
+    }
+    else {
+        logger.out(`✓ ${result.linkCount} repo-local link(s) across ${result.scannedFileCount} document(s) all resolve${allowlistSuffix}`);
+    }
+}
+/**
+ * Machine-readable link audit summary for `--json`.
+ *
+ * @since 0.5.0
+ */
+export function formatLinkAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.breakageCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}
+/**
+ * Exit `1` when any non-allowlisted divider still breaks the convention.
+ *
+ * @since 0.6.0
+ */
+export function exitCodeForCommentAuditResult(result) {
+    return result.breakageCount > 0 ? CLI_EXIT_GENERAL_ERROR : CLI_EXIT_SUCCESS;
+}
+/**
+ * Human-readable comment-divider report.
+ *
+ * @since 0.6.0
+ */
+export function presentCommentAuditResult(result) {
+    for (const file of result.files) {
+        logger.out(`\n${file.relativePath}`);
+        for (const { line, raw, reason } of file.breakages) {
+            logger.out(`  ${line}: ${truncate(raw)} → ${reason}`);
+        }
+    }
+    const allowlistSuffix = result.allowlistedCount > 0 ? ` (${result.allowlistedCount} allowlisted)` : "";
+    if (result.fixedCount > 0) {
+        logger.out(`\n✎ Rewrote ${result.fixedCount} divider(s)`);
+    }
+    if (result.breakageCount > 0) {
+        logger.out(`\n✖ ${result.breakageCount} comment issue(s)${allowlistSuffix} — --fix rewrites divider forms`);
+    }
+    else {
+        logger.out(`✓ ${result.dividerCount} divider(s) across ${result.scannedFileCount} file(s), no banned comment content${allowlistSuffix}`);
+    }
+}
+/**
+ * Machine-readable comment-divider summary for `--json`.
+ *
+ * @since 0.6.0
+ */
+export function formatCommentAuditJsonOutput(result, rootDir) {
+    return JSON.stringify({
+        schemaVersion: 1,
+        ok: result.breakageCount === 0,
+        cwd: rootDir,
+        result,
+    });
+}
+function truncate(raw) {
+    return raw.length <= 60 ? raw : `${raw.slice(0, 57)}…`;
+}
 //# sourceMappingURL=output.js.map