@produtype/core 0.68.0 → 0.69.0

package/dist/analyzer/proseLines.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The lines of a Python file that are a docstring rather than code.
+ *
+ * This analyzer has skipped comments since the day it read its own prose about Stripe
+ * as evidence that it takes payments. The rule looks for a line marker — `#`, `//`,
+ * `/*`, `<!--` — and Python's main way of writing prose has none: a docstring is a
+ * string, and its interior lines begin with whatever the author was saying.
+ *
+ * Measured across the corpus: 118 of 1587 citations from Python files land inside
+ * one. `/api/auth/...  registrazione + JWT` was cited as evidence of an
+ * authentication route; `Chi arriva col link (?k=...) si vede posare un cookie` as
+ * evidence about cookies. Sentences describing the code, offered as the code.
+ *
+ * Only a block that stands on its own. `QUERY = """SELECT ..."""` is data assigned to
+ * a name and a hardcoded secret could live in one, so a triple-quoted string on the
+ * right of an assignment stays readable. A docstring is an expression statement and
+ * has nothing before it but indentation.
+ */
+export declare function proseLines(file: string, text: string): Set<number>;

package/dist/analyzer/proseLines.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.proseLines = proseLines;
+/**
+ * The lines of a Python file that are a docstring rather than code.
+ *
+ * This analyzer has skipped comments since the day it read its own prose about Stripe
+ * as evidence that it takes payments. The rule looks for a line marker — `#`, `//`,
+ * `/*`, `<!--` — and Python's main way of writing prose has none: a docstring is a
+ * string, and its interior lines begin with whatever the author was saying.
+ *
+ * Measured across the corpus: 118 of 1587 citations from Python files land inside
+ * one. `/api/auth/...  registrazione + JWT` was cited as evidence of an
+ * authentication route; `Chi arriva col link (?k=...) si vede posare un cookie` as
+ * evidence about cookies. Sentences describing the code, offered as the code.
+ *
+ * Only a block that stands on its own. `QUERY = """SELECT ..."""` is data assigned to
+ * a name and a hardcoded secret could live in one, so a triple-quoted string on the
+ * right of an assignment stays readable. A docstring is an expression statement and
+ * has nothing before it but indentation.
+ */
+function proseLines(file, text) {
+    const prose = new Set();
+    if (!/\.py$/i.test(file))
+        return prose;
+    const lines = text.split(/\r?\n/);
+    let openQuote = null;
+    let openIsProse = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (openQuote) {
+            if (openIsProse)
+                prose.add(i + 1);
+            if (line.includes(openQuote)) {
+                openQuote = null;
+                openIsProse = false;
+            }
+            continue;
+        }
+        const match = /("""|''')/.exec(line);
+        if (!match)
+            continue;
+        const before = line.slice(0, match.index);
+        /** An expression statement: nothing before the quotes but whitespace. */
+        const standsAlone = /^\s*[rRbBuUfF]*$/.test(before);
+        const rest = line.slice(match.index + 3);
+        const closesOnThisLine = rest.includes(match[1]);
+        if (standsAlone)
+            prose.add(i + 1);
+        if (closesOnThisLine)
+            continue;
+        openQuote = match[1];
+        openIsProse = standsAlone;
+    }
+    return prose;
+}

package/dist/utils/textSearch.js

@@ -6,6 +6,7 @@ exports.searchInFiles = searchInFiles;
 exports.anyIncludes = anyIncludes;
 const readTextFileSafe_1 = require("./readTextFileSafe");
 const developmentOnly_1 = require("../analyzer/developmentOnly");
+const proseLines_1 = require("../analyzer/proseLines");
 /**
  * A line that declares a pattern rather than doing anything.
  *
@@ -103,9 +104,11 @@ function matchLines(text, needles, file = '') {
      * fixture of a test asserting the wrong secret is rejected.
      */
     const testOnly = (0, developmentOnly_1.testOnlyLines)(file, text);
+    /** A Python docstring is prose with no line marker to recognise it by. */
+    const prose = (0, proseLines_1.proseLines)(file, text);
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
-        if (testOnly.has(i + 1))
+        if (testOnly.has(i + 1) || prose.has(i + 1))
             continue;
         if (line.length > MAX_CITABLE_LINE)
             continue;
@@ -135,9 +138,10 @@ async function searchInFiles(root, files, needles, limit = 25) {
             continue;
         const lines = text.split(/\r?\n/);
         const testOnly = (0, developmentOnly_1.testOnlyLines)(file, text);
+        const prose = (0, proseLines_1.proseLines)(file, text);
         for (let i = 0; i < lines.length; i++) {
             const line = lines[i];
-            if (testOnly.has(i + 1))
+            if (testOnly.has(i + 1) || prose.has(i + 1))
                 continue;
             if (line.length > MAX_CITABLE_LINE)
                 continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@produtype/core",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Deterministic CLI and library that analyzes a web application repository and reports how far it is from production-ready for the kind of product it is meant to be.",
   "license": "MIT",
   "bin": {