@produtype/core 0.68.0 → 0.70.0

package/dist/analyzer/blockComments.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The lines of a C-family file that sit inside a block comment.
+ *
+ * The comment rule reads one line at a time and looks for a marker at its start:
+ * a double slash, a slash-star, a lone star. A block comment written without a
+ * leading star on every line has no marker to find, and neither does code that
+ * somebody commented out by wrapping the whole thing. In AsteroidsJS a wrapped
+ * `localStorage.setItem('highScores', ...)` was cited as evidence that the game
+ * saves progress; the function it belongs to is switched off.
+ *
+ * It is the same defect the Python docstrings had, in the languages where the marker
+ * usually is there and sometimes is not.
+ *
+ * Counting the delimiters is not enough, and measuring that was the point. A first
+ * pass said 135 citations across the corpus, and the second example it offered was
+ * live code: a glob like star-star-slash-star-dot-ts, and a slash-star inside a
+ * shader string, both look like an opening. So this walks the file properly —
+ * through single quotes, double quotes, template literals and line comments — and
+ * only then decides.
+ */
+export declare function blockCommentLines(file: string, text: string): Set<number>;

package/dist/analyzer/blockComments.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * The lines of a C-family file that sit inside a block comment.
+ *
+ * The comment rule reads one line at a time and looks for a marker at its start:
+ * a double slash, a slash-star, a lone star. A block comment written without a
+ * leading star on every line has no marker to find, and neither does code that
+ * somebody commented out by wrapping the whole thing. In AsteroidsJS a wrapped
+ * `localStorage.setItem('highScores', ...)` was cited as evidence that the game
+ * saves progress; the function it belongs to is switched off.
+ *
+ * It is the same defect the Python docstrings had, in the languages where the marker
+ * usually is there and sometimes is not.
+ *
+ * Counting the delimiters is not enough, and measuring that was the point. A first
+ * pass said 135 citations across the corpus, and the second example it offered was
+ * live code: a glob like star-star-slash-star-dot-ts, and a slash-star inside a
+ * shader string, both look like an opening. So this walks the file properly —
+ * through single quotes, double quotes, template literals and line comments — and
+ * only then decides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockCommentLines = blockCommentLines;
+const C_FAMILY = /\.(ts|tsx|js|jsx|mjs|cjs|go|java|cs|rs|php|scala|kt|swift|c|cc|cpp|h)$/i;
+function blockCommentLines(file, text) {
+    const inside = new Set();
+    if (!C_FAMILY.test(file))
+        return inside;
+    if (!text.includes('/*'))
+        return inside;
+    let line = 1;
+    let state = 'code';
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const character = text[i];
+        const next = text[i + 1];
+        if (character === '\n') {
+            line++;
+            if (state === 'line-comment')
+                state = 'code';
+            if (state === 'single' || state === 'double')
+                state = 'code';
+            if (state === 'block-comment')
+                inside.add(line);
+            escaped = false;
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        switch (state) {
+            case 'code':
+                if (character === '/' && next === '/') {
+                    state = 'line-comment';
+                    i++;
+                }
+                else if (character === '/' && next === '*') {
+                    state = 'block-comment';
+                    i++;
+                }
+                else if (character === "'")
+                    state = 'single';
+                else if (character === '"')
+                    state = 'double';
+                else if (character === '`')
+                    state = 'template';
+                break;
+            case 'block-comment':
+                if (character === '*' && next === '/') {
+                    state = 'code';
+                    i++;
+                }
+                break;
+            case 'single':
+            case 'double':
+            case 'template':
+                if (character === '\\')
+                    escaped = true;
+                else if ((state === 'single' && character === "'")
+                    || (state === 'double' && character === '"')
+                    || (state === 'template' && character === '`')) {
+                    state = 'code';
+                }
+                break;
+            default:
+                break;
+        }
+    }
+    return inside;
+}

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,8 @@ exports.searchInFiles = searchInFiles;
 exports.anyIncludes = anyIncludes;
 const readTextFileSafe_1 = require("./readTextFileSafe");
 const developmentOnly_1 = require("../analyzer/developmentOnly");
+const proseLines_1 = require("../analyzer/proseLines");
+const blockComments_1 = require("../analyzer/blockComments");
 /**
  * A line that declares a pattern rather than doing anything.
  *
@@ -103,9 +105,13 @@ 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);
+    /** Code somebody switched off by wrapping it, which has no marker on its lines. */
+    const commented = (0, blockComments_1.blockCommentLines)(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) || commented.has(i + 1))
             continue;
         if (line.length > MAX_CITABLE_LINE)
             continue;
@@ -135,9 +141,11 @@ 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);
+        const commented = (0, blockComments_1.blockCommentLines)(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) || commented.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.70.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": {