@sarj/eslint-plugin 2.9.0 → 2.10.0

package/dist/index.cjs

@@ -287,12 +287,115 @@ function isProse(text) {
   }
   return false;
 }
-function isRedundantNarration(body) {
+var NARRATION_MAX_WORDS = 6;
+var NARRATION_MIN_CONTENT = 1;
+var TOKEN_PLURAL_MIN = 4;
+var RESTATABLE_STATEMENTS = /* @__PURE__ */ new Set([
+  import_utils3.AST_NODE_TYPES.ExpressionStatement,
+  import_utils3.AST_NODE_TYPES.ReturnStatement,
+  import_utils3.AST_NODE_TYPES.ThrowStatement,
+  import_utils3.AST_NODE_TYPES.VariableDeclaration
+]);
+var NARRATION_VERB_RE = /^(?:add|append|assign|build|calculate|call|check|clear|close|compute|convert|copy|count|create|declare|decrement|define|delete|extract|fetch|filter|find|format|generate|get|handle|increment|init|initialise|initialize|insert|iterate|join|load|log|loop|make|map|merge|open|parse|print|process|push|read|remove|render|reset|return|save|send|set|setup|sort|split|start|stop|store|update|validate|wrap|write)(?:s|es|d|ed|ing)?$/i;
+var NARRATION_STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "all",
+  "an",
+  "and",
+  "any",
+  "are",
+  "as",
+  "at",
+  "back",
+  "be",
+  "both",
+  "by",
+  "each",
+  "for",
+  "from",
+  "here",
+  "if",
+  "in",
+  "into",
+  "is",
+  "it",
+  "its",
+  "just",
+  "new",
+  "of",
+  "on",
+  "one",
+  "onto",
+  "or",
+  "our",
+  "out",
+  "over",
+  "so",
+  "that",
+  "the",
+  "then",
+  "this",
+  "to",
+  "up",
+  "us",
+  "we",
+  "when",
+  "with"
+]);
+function normalizeToken(word) {
+  const lower = word.toLowerCase();
+  return lower.length > TOKEN_PLURAL_MIN && lower.endsWith("s") && !lower.endsWith("ss") ? lower.slice(0, -1) : lower;
+}
+function codeTokens(source) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const identifier of source.match(/[A-Za-z_$][\w$]*/g) ?? []) {
+    tokens.add(normalizeToken(identifier));
+    for (const part of identifier.split(/[_$]+|(?<=[a-z0-9])(?=[A-Z])/)) {
+      if (part.length > 0) tokens.add(normalizeToken(part));
+    }
+  }
+  return tokens;
+}
+function isTrivialInitializer(node) {
+  return node.declarations.every((declarator) => {
+    const init = declarator.init;
+    if (init == null || init.type === import_utils3.AST_NODE_TYPES.Literal) return true;
+    return init.type === import_utils3.AST_NODE_TYPES.ArrayExpression && init.elements.length === 0 || init.type === import_utils3.AST_NODE_TYPES.ObjectExpression && init.properties.length === 0;
+  });
+}
+function restatableStatementBelow(comment, sourceCode) {
+  const token = sourceCode.getTokenAfter(comment, { includeComments: false });
+  if (token === null || token.loc.start.line !== comment.loc.end.line + 1) return null;
+  for (let node = sourceCode.getNodeByRangeIndex(token.range[0]); node != null && node.type !== import_utils3.AST_NODE_TYPES.Program; node = node.parent) {
+    if (!RESTATABLE_STATEMENTS.has(node.type)) continue;
+    if (node.loc.start.line !== token.loc.start.line || node.loc.end.line !== node.loc.start.line) {
+      return null;
+    }
+    if (node.type === import_utils3.AST_NODE_TYPES.VariableDeclaration && isTrivialInitializer(node)) {
+      return null;
+    }
+    return sourceCode.getText(node);
+  }
+  return null;
+}
+function restatesNextLine(body, statement) {
+  if (statement === null) return false;
+  const words = body.match(/[A-Za-z][\w$]*/g) ?? [];
+  const opener = words[0];
+  if (opener === void 0 || words.length > NARRATION_MAX_WORDS) return false;
+  if (!NARRATION_VERB_RE.test(opener)) return false;
+  const content = words.slice(1).map(normalizeToken).filter((word) => !NARRATION_STOPWORDS.has(word));
+  if (content.length < NARRATION_MIN_CONTENT) return false;
+  const head = statement.split("(")[0] ?? statement;
+  const code = codeTokens(head);
+  return content.every((word) => code.has(word));
+}
+function isRedundantNarration(body, statementBelow) {
   const t = body.trim();
   if (!t || looksLikeCode(t) || hasPseudocode(t)) return false;
   if (STEP_NARRATION_RE.test(t)) return true;
   if (META_COMMENTARY_RE.test(t)) return true;
-  return false;
+  return restatesNextLine(t, statementBelow);
 }
 function hasCommentedOutCode(texts, precedingProse) {
   for (let i = 0; i < texts.length; i++) {
@@ -377,7 +480,8 @@ var no_comment_cruft_default = import_utils3.ESLintUtils.RuleCreator(
           }
           if (comment.type === "Line" && texts.length === 1) {
             const body = texts[0];
-            if (body !== void 0 && isRedundantNarration(body)) {
+            const statement = restatableStatementBelow(comment, sourceCode);
+            if (body !== void 0 && isRedundantNarration(body, statement)) {
               context.report({ node: comment, messageId: "redundantNarration" });
             }
           }
@@ -3638,6 +3742,10 @@ function isSecretName(identifier, innocuous = INNOCUOUS_WORDS) {
   if (last !== void 0 && innocuous.has(last)) {
     return false;
   }
+  const first = leadingWord(identifier);
+  if (first !== void 0 && FLAG_PREFIXES.has(first)) {
+    return false;
+  }
   if (tokens.some((tok) => SECRET_WORDS.has(tok))) {
     return true;
   }
@@ -3648,10 +3756,6 @@ function isAuthSecretName(identifier) {
     return false;
   }
   const tokens = tokenize(identifier);
-  const first = leadingWord(identifier);
-  if (first !== void 0 && FLAG_PREFIXES.has(first)) {
-    return false;
-  }
   const last = tokens.at(-1);
   if (last !== void 0 && DESCRIPTOR_WORDS.has(last)) {
     return false;
@@ -3728,6 +3832,49 @@ function isRawSecretValue(prop) {
   }
   return prop.value.type === "Identifier" || prop.value.type === "MemberExpression";
 }
+var RAW_BLOB_WORDS = /* @__PURE__ */ new Set([
+  "body",
+  "bodies",
+  "payload",
+  "payloads",
+  "params"
+]);
+var RAW_BLOB_IDENTIFIERS = /* @__PURE__ */ new Set(["formdata"]);
+var BLOB_REDACTION_RE = /redact|sanit|scrub|mask|truncat|anonym|filtered|preview|summar/i;
+var BLOB_REDACTION_TOKENS = /* @__PURE__ */ new Set([
+  "safe",
+  "clean",
+  "shape",
+  "keys",
+  "public"
+]);
+function isRawBlobName(name) {
+  if (REDACTION_RE.test(name) || BLOB_REDACTION_RE.test(name)) {
+    return false;
+  }
+  const tokens = tokenize(name);
+  if (tokens.some((tok) => BLOB_REDACTION_TOKENS.has(tok))) {
+    return false;
+  }
+  const first = leadingWord(name);
+  if (first !== void 0 && FLAG_PREFIXES.has(first)) {
+    return false;
+  }
+  if (RAW_BLOB_IDENTIFIERS.has(name.toLowerCase())) {
+    return true;
+  }
+  const last = tokens.at(-1);
+  return last !== void 0 && RAW_BLOB_WORDS.has(last);
+}
+function rawBlobValueName(value) {
+  if (value.type === "Identifier") {
+    return isRawBlobName(value.name) ? value.name : null;
+  }
+  if (value.type === "MemberExpression" && !value.computed && value.property.type === "Identifier") {
+    return isRawBlobName(value.property.name) ? value.property.name : null;
+  }
+  return null;
+}
 function propertyKeyName2(prop) {
   if (prop.computed) {
     return null;
@@ -3747,7 +3894,7 @@ var no_secret_in_log_default = import_utils28.ESLintUtils.RuleCreator(
   meta: {
     type: "problem",
     docs: {
-      description: "Disallow passing a secret-named value to a logging call; it leaks to log sinks. Redact or omit it."
+      description: "Disallow passing a secret-named value or a raw request/response blob to a logging call; both leak to log sinks. Redact or omit."
     },
     schema: [
       {
@@ -3757,52 +3904,58 @@ var no_secret_in_log_default = import_utils28.ESLintUtils.RuleCreator(
       }
     ],
     messages: {
-      noSecretInLog: "Secret `{{name}}` passed to a logging call leaks it to log sinks. Redact (e.g. `{{name}}Prefix: {{name}}.slice(0, 6)`) or omit it."
+      noSecretInLog: "Secret `{{name}}` passed to a logging call leaks it to log sinks. Redact (e.g. `{{name}}Prefix: {{name}}.slice(0, 6)`) or omit it.",
+      noRawBodyInLog: "Raw `{{name}}` passed to a logging call. Request/response blobs carry PII and often echo credentials back, and log sinks have no retention policy. Log a derived value instead (a status, `{{name}}.id`, a length, a truncated issue list) or pass it through a redactor (`redact({{name}})`)."
     }
   },
   defaultOptions: [{}],
   create(context, [loggingOptions]) {
     const matcher = createLogMatcher(loggingOptions);
+    const blobArmApplies = !isTestFile(context.filename);
+    function reportSecretArgument(arg) {
+      const name = arg.type === "Identifier" ? arg.name : arg.type === "MemberExpression" && !arg.computed && arg.property.type === "Identifier" ? arg.property.name : null;
+      if (name === null || !isSecretKeyword(name)) {
+        return false;
+      }
+      context.report({ node: arg, messageId: "noSecretInLog", data: { name } });
+      return true;
+    }
+    function reportSecretProperty(prop) {
+      const keyName2 = propertyKeyName2(prop);
+      if (keyName2 === null || !isSecretKeyword(keyName2) || !isRawSecretValue(prop)) {
+        return false;
+      }
+      context.report({ node: prop, messageId: "noSecretInLog", data: { name: keyName2 } });
+      return true;
+    }
+    function reportRawBlob(node, value) {
+      if (!blobArmApplies) {
+        return;
+      }
+      const name = rawBlobValueName(value);
+      if (name !== null) {
+        context.report({ node, messageId: "noRawBodyInLog", data: { name } });
+      }
+    }
     return {
       CallExpression(node) {
         if (!matcher.isLoggingCall(node)) {
           return;
         }
         for (const arg of node.arguments) {
-          if (arg.type === "Identifier") {
-            if (isSecretKeyword(arg.name)) {
-              context.report({
-                node: arg,
-                messageId: "noSecretInLog",
-                data: { name: arg.name }
-              });
-            }
-            continue;
-          }
-          if (arg.type === "MemberExpression") {
-            if (!arg.computed && arg.property.type === "Identifier" && isSecretKeyword(arg.property.name)) {
-              context.report({
-                node: arg,
-                messageId: "noSecretInLog",
-                data: { name: arg.property.name }
-              });
-            }
-            continue;
-          }
           if (arg.type === "ObjectExpression") {
             for (const prop of arg.properties) {
               if (prop.type !== "Property") {
                 continue;
               }
-              const keyName2 = propertyKeyName2(prop);
-              if (keyName2 !== null && isSecretKeyword(keyName2) && isRawSecretValue(prop)) {
-                context.report({
-                  node: prop,
-                  messageId: "noSecretInLog",
-                  data: { name: keyName2 }
-                });
+              if (!reportSecretProperty(prop)) {
+                reportRawBlob(prop, prop.value);
               }
             }
+            continue;
+          }
+          if (!reportSecretArgument(arg)) {
+            reportRawBlob(arg, arg);
           }
         }
       }
@@ -4577,7 +4730,7 @@ function functionName(node) {
   }
   return null;
 }
-function isExported(node) {
+function isInlineExported(node) {
   for (let current = node; current != null; current = current.parent) {
     const parent = current.parent;
     if (parent?.type === import_utils35.AST_NODE_TYPES.ExportNamedDeclaration || parent?.type === import_utils35.AST_NODE_TYPES.ExportDefaultDeclaration) {
@@ -4586,6 +4739,58 @@ function isExported(node) {
   }
   return false;
 }
+function moduleScopeBindingName(node) {
+  let current = node;
+  let child = node;
+  while (current.parent != null && current.parent.type !== import_utils35.AST_NODE_TYPES.Program) {
+    child = current;
+    current = current.parent;
+  }
+  if (current.parent?.type !== import_utils35.AST_NODE_TYPES.Program) {
+    return null;
+  }
+  if (current.type === import_utils35.AST_NODE_TYPES.FunctionDeclaration || current.type === import_utils35.AST_NODE_TYPES.ClassDeclaration) {
+    return current.id?.name ?? null;
+  }
+  if (current.type === import_utils35.AST_NODE_TYPES.VariableDeclaration) {
+    if (child.type !== import_utils35.AST_NODE_TYPES.VariableDeclarator || child.id.type !== import_utils35.AST_NODE_TYPES.Identifier) {
+      return null;
+    }
+    return child.id.name;
+  }
+  return null;
+}
+function specifierExportedNames(program) {
+  const names = /* @__PURE__ */ new Set();
+  for (const statement of program.body) {
+    if (statement.type === import_utils35.AST_NODE_TYPES.ExportNamedDeclaration && statement.declaration == null && statement.source == null && statement.exportKind !== "type") {
+      for (const specifier of statement.specifiers) {
+        if (specifier.exportKind !== "type" && specifier.local.type === import_utils35.AST_NODE_TYPES.Identifier) {
+          names.add(specifier.local.name);
+        }
+      }
+      continue;
+    }
+    if (statement.type === import_utils35.AST_NODE_TYPES.ExportDefaultDeclaration && statement.declaration.type === import_utils35.AST_NODE_TYPES.Identifier) {
+      names.add(statement.declaration.name);
+      continue;
+    }
+    if (statement.type === import_utils35.AST_NODE_TYPES.TSExportAssignment && statement.expression.type === import_utils35.AST_NODE_TYPES.Identifier) {
+      names.add(statement.expression.name);
+    }
+  }
+  return names;
+}
+function isExported(node, specifierExports) {
+  if (isInlineExported(node)) {
+    return true;
+  }
+  if (specifierExports.size === 0) {
+    return false;
+  }
+  const binding = moduleScopeBindingName(node);
+  return binding !== null && specifierExports.has(binding);
+}
 var no_positional_tuple_return_default = import_utils35.ESLintUtils.RuleCreator(
   (name) => `https://github.com/sarj-ai/standards/blob/main/packages/typescript/src/rules/${name}.ts`
 )({
@@ -4602,6 +4807,7 @@ var no_positional_tuple_return_default = import_utils35.ESLintUtils.RuleCreator(
   },
   defaultOptions: [],
   create(context) {
+    const specifierExports = specifierExportedNames(context.sourceCode.ast);
     const check = (node) => {
       const annotation = node.returnType?.typeAnnotation;
       if (annotation === void 0) {
@@ -4615,7 +4821,7 @@ var no_positional_tuple_return_default = import_utils35.ESLintUtils.RuleCreator(
       if (name === null || name.startsWith("_") || /^use[A-Z]/.test(name)) {
         return;
       }
-      if (!isExported(node)) {
+      if (!isExported(node, specifierExports)) {
         return;
       }
       context.report({
@@ -5847,7 +6053,7 @@ var rules = {
 var plugin = {
   meta: {
     name: "@sarj/eslint-plugin",
-    version: "2.9.0"
+    version: "2.10.0"
   },
   rules,
   configs: {