paperlint 14.0.0 → 14.2.0

package/skills/build-label-page/scripts/fixtures/blocks-items.json

@@ -0,0 +1,214 @@
+{
+  "study": "demo-review",
+  "kind": "labels",
+  "title": "Review comments",
+  "intro": "Each card shows one guideline, one changed line and one question about that line.",
+  "seed": 5,
+  "groups": { "all": "Review comments" },
+  "labels": {
+    "place": "Comment {n} of {total}",
+    "body": "Guideline",
+    "repeat": "Comment {index} of {of} on this guideline",
+    "practice_example": "Another case: "
+  },
+  "questions": [
+    {
+      "id": "applies",
+      "text": "Does the guideline cover this line?",
+      "short": "covered?",
+      "options": [
+        {
+          "value": "yes",
+          "label": "Yes",
+          "icon": "✅",
+          "example": "«No string-built SQL» and an f-string query"
+        },
+        {
+          "value": "no",
+          "label": "No",
+          "icon": "🚫",
+          "example": "«No string-built SQL» and a log message"
+        },
+        {
+          "value": "unclear",
+          "label": "Unclear",
+          "icon": "↔️",
+          "example": "«Short functions» and a 40-line function",
+          "ask_why": "What makes it unclear?"
+        }
+      ]
+    }
+  ],
+  "practice": [
+    {
+      "body": "Every query is parameterised",
+      "situation": {
+        "summary": "One reviewer asked for a change at {line}; the other approved it.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/orders.py",
+        "lines": [
+          { "n": 41, "text": "def total(order_id):", "mark": false },
+          {
+            "n": 42,
+            "text": "    sql = f\"SELECT * FROM o WHERE id={order_id}\"",
+            "mark": true
+          }
+        ],
+        "caption": "Reviewer A wrote: build this query with parameters."
+      },
+      "expected": { "applies": "yes" },
+      "why": "The value goes into the query text."
+    },
+    {
+      "body": "Every query is parameterised",
+      "situation": {
+        "summary": "One reviewer flagged {line}; the other did not.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/log.py",
+        "lines": [
+          {
+            "n": 7,
+            "text": "log.info(f\"order {order_id} paid\")",
+            "mark": true
+          }
+        ]
+      },
+      "expected": { "applies": "no" },
+      "why": "A log line is not a query."
+    },
+    {
+      "body": "Functions stay short",
+      "situation": {
+        "summary": "One reviewer asked to split the function; the other did not.",
+        "question": "Does «Functions stay short» cover this function?"
+      },
+      "excerpt": {
+        "file": "app/cart.py",
+        "lines": [
+          { "n": 1, "text": "def checkout(cart):", "mark": true },
+          { "n": 2, "text": "    ...", "mark": false }
+        ],
+        "caption": "The function is 40 lines long."
+      },
+      "expected": { "applies": "unclear" },
+      "why": "«Short» has no number."
+    }
+  ],
+  "items": [
+    {
+      "source_id": "review-sql-1",
+      "group": "all",
+      "body": "Every query is parameterised",
+      "repeat": { "group": "guide-sql", "index": 1, "of": 2 },
+      "situation": {
+        "summary": "Reviewer A asked for a change at {line}; reviewer B approved it.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/report.py",
+        "url": "https://example.com/shop/blob/0000000/app/report.py#L12",
+        "lines": [
+          { "n": 11, "text": "def monthly(month):", "mark": false },
+          {
+            "n": 12,
+            "text": "    rows = db.raw(\"SELECT * FROM sales WHERE m=\" + month)",
+            "mark": true
+          },
+          { "n": 13, "text": "", "mark": false },
+          { "n": 14, "text": "    return rows", "mark": false }
+        ],
+        "caption": "Reviewer A wrote: concatenated SQL.",
+        "mark_label": "◀ the line in question"
+      },
+      "references": {
+        "summary": "What the guideline says",
+        "entries": [
+          {
+            "label": "Guideline",
+            "title": "Security guide `SQL-1`",
+            "fields": [
+              { "text": "Build every query with parameters, never by joining strings." },
+              {
+                "label": "Why",
+                "text": "A query built from strings lets input become part of the query, and a value a user typed can then change what the query does: read other rows, change data, or drop a table. Parameters keep data and query apart in every driver the shop uses."
+              },
+              { "style": "note", "text": "The examples below are the guide's own." },
+              {
+                "label": "Not like this",
+                "style": "code",
+                "text": "db.raw(\"SELECT * FROM t WHERE id=\" + id)"
+              },
+              {
+                "label": "Like this",
+                "style": "code",
+                "text": "db.raw(\"SELECT * FROM t WHERE id=%s\", [id])"
+              }
+            ],
+            "url": "https://example.com/guide#sql-1",
+            "url_label": "Security guide"
+          }
+        ]
+      },
+      "more": {
+        "summary": "3 more lines like this",
+        "items": ["`app/export.py`", "`app/admin.py`"],
+        "rest": "and 1 more"
+      },
+      "table": {
+        "summary": "What each reviewer wrote",
+        "note": "Reviewer A asked for the change; reviewer B approved.",
+        "rows": [
+          {
+            "label": "A only · Comment",
+            "value": "use parameters",
+            "plain": "asks for a parameterised query",
+            "mark": { "tone": "yes", "text": "✓ about this line" }
+          },
+          {
+            "label": "B only · Approval",
+            "value": "LGTM",
+            "mark": { "tone": "no", "text": "✗ says nothing about this line" }
+          }
+        ]
+      }
+    },
+    {
+      "source_id": "review-sql-2",
+      "group": "all",
+      "body": "Every query is parameterised",
+      "repeat": { "group": "guide-sql", "index": 2, "of": 2 },
+      "situation": {
+        "summary": "Only one reviewer commented on {line}.",
+        "question": "Does «Every query is parameterised» cover {line}?"
+      },
+      "excerpt": {
+        "file": "app/search.py",
+        "lines": [
+          {
+            "n": 30,
+            "text": "    q = `SELECT * FROM items WHERE name LIKE '${term}'`",
+            "mark": true
+          }
+        ]
+      }
+    },
+    {
+      "source_id": "review-short-1",
+      "group": "all",
+      "body": "Functions stay short",
+      "situation": {
+        "summary": "One reviewer asked to split the function, the other did not.",
+        "question": "Does «Functions stay short» cover this function?"
+      },
+      "excerpt": {
+        "lines": [
+          { "n": 1, "text": "def import_orders(path):", "mark": true }
+        ]
+      }
+    }
+  ]
+}

package/skills/build-label-page/scripts/fixtures/linter-config-witness-items.json

@@ -0,0 +1,448 @@
+{
+  "study": "demo-witness",
+  "preset": "linter-config-witness",
+  "kind": "labels",
+  "title": "Witness cards",
+  "intro": "Each card shows one requirement, one piece of real code and one question about that code. The linter settings behind the card are under «Settings behind this card»; you do not need them to answer.",
+  "seed": 11,
+  "groups": {
+    "all": "Witness cards"
+  },
+  "questions": [
+    {
+      "id": "witness",
+      "text": "Does the requirement forbid this line, or apply to this file?",
+      "short": "answer",
+      "options": [
+        {
+          "value": "covers",
+          "label": "Yes",
+          "icon": "✅",
+          "example": "«Use `===`» and the line `a == b`: yes, the requirement forbids it"
+        },
+        {
+          "value": "excludes",
+          "label": "No",
+          "icon": "🚫",
+          "example": "«No `console` in shipped code» and a test file: no, tests are not shipped"
+        },
+        {
+          "value": "open",
+          "label": "Unclear: the wording could be read either way",
+          "icon": "↔️",
+          "example": "«Use `===`» and the line `x == null`: unclear, a common exception the wording neither allows nor forbids"
+        },
+        {
+          "value": "unsure",
+          "label": "I can't judge (tell me why)",
+          "icon": "❔",
+          "example": "the code is in a language you cannot read: say so in the box",
+          "ask_why": "Why can't you judge it?"
+        }
+      ]
+    }
+  ],
+  "practice": [
+    {
+      "body": "Functions take at most 3 parameters",
+      "situation": {
+        "summary": "One setting allows up to 5 parameters, the other up to 3.",
+        "question": "Does «Functions take at most 3 parameters» forbid {line}?"
+      },
+      "example": {
+        "file": "src/orders/create.ts",
+        "lines": [
+          {
+            "n": 11,
+            "text": "",
+            "mark": false
+          },
+          {
+            "n": 12,
+            "text": "export function createOrder(id, items, user, coupon) {",
+            "mark": true
+          },
+          {
+            "n": 13,
+            "text": "  return { id, items, user, coupon };",
+            "mark": false
+          }
+        ],
+        "message": "Function 'createOrder' has too many parameters (4). Maximum allowed is 3.",
+        "caught_by": "a"
+      },
+      "details": {
+        "a": [
+          {
+            "key": "option:max",
+            "raw": "3",
+            "plain": "at most 3 parameters",
+            "matches_example": true
+          }
+        ],
+        "b": [
+          {
+            "key": "option:max",
+            "raw": "5",
+            "plain": "at most 5 parameters",
+            "matches_example": false
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "eslint",
+          "id": "max-params",
+          "explanation": {
+            "source": "eslint docs",
+            "what": "Enforce a maximum number of parameters in function definitions.",
+            "example_bad": "function foo (bar, baz, qux, qxx) {}",
+            "example_good": "function foo (bar, baz, qux) {}",
+            "url": "https://eslint.org/docs/latest/rules/max-params"
+          }
+        }
+      ],
+      "expected": {
+        "witness": "covers"
+      },
+      "why": "The words fix the number 3, and the marked line has 4 parameters."
+    },
+    {
+      "body": "Use `===`, never `==`",
+      "situation": {
+        "summary": "One setting allows `== null`, the other forbids every `==`.",
+        "question": "Does «Use `===`, never `==`» forbid {line}?"
+      },
+      "example": {
+        "file": "src/cache/lookup.ts",
+        "lines": [
+          {
+            "n": 41,
+            "text": "  const entry = store.get(key);",
+            "mark": false
+          },
+          {
+            "n": 42,
+            "text": "  if (entry == null) return undefined;",
+            "mark": true
+          }
+        ],
+        "message": "Expected '===' and instead saw '=='.",
+        "caught_by": "b"
+      },
+      "details": {
+        "a": [
+          {
+            "key": "option:null",
+            "raw": "\"ignore\"",
+            "plain": "allows `== null` and `!= null`",
+            "matches_example": false
+          }
+        ],
+        "b": [
+          {
+            "key": "rule",
+            "raw": "\"always\"",
+            "plain": "every `==` and `!=`",
+            "matches_example": true
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "eslint",
+          "id": "eqeqeq",
+          "explanation": {
+            "source": "none"
+          }
+        }
+      ],
+      "expected": {
+        "witness": "covers"
+      },
+      "why": "«never `==`» names no exception, so `== null` is forbidden too."
+    },
+    {
+      "body": "No `console` calls in shipped code",
+      "situation": {
+        "summary": "One setting checks test files, the other leaves them out.",
+        "question": "Should this requirement apply to test files?"
+      },
+      "example": {
+        "file": "test/report.test.ts",
+        "lines": [
+          {
+            "n": 7,
+            "text": "  console.log(result);",
+            "mark": true
+          }
+        ],
+        "message": "Unexpected console statement.",
+        "caught_by": "a"
+      },
+      "details": {
+        "a": [
+          {
+            "key": "files",
+            "raw": "**/*.ts",
+            "plain": "every TypeScript file",
+            "matches_example": true
+          }
+        ],
+        "b": [
+          {
+            "key": "files",
+            "raw": "**/*.ts",
+            "plain": "every TypeScript file",
+            "matches_example": true
+          },
+          {
+            "key": "ignores",
+            "raw": "test/**",
+            "plain": "except the files under test/",
+            "matches_example": true
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "eslint",
+          "id": "no-console",
+          "explanation": {
+            "source": "none"
+          }
+        }
+      ],
+      "expected": {
+        "witness": "excludes"
+      },
+      "why": "Test files are not shipped, so the words do not reach them."
+    }
+  ],
+  "items": [
+    {
+      "source_id": "req-logging:tests",
+      "group": "all",
+      "body": "Never log with `print`; use the `logging` module",
+      "situation": {
+        "summary": "One setting checks the scripts/ folder, the other leaves it out.",
+        "question": "Should this requirement apply to the scripts/ folder?"
+      },
+      "example": {
+        "file": "scripts/seed_db.py",
+        "url": "https://example.com/demo-shop/blob/0000000/scripts/seed_db.py#L18",
+        "lines": [
+          {
+            "n": 16,
+            "text": "for row in rows:",
+            "mark": false
+          },
+          {
+            "n": 17,
+            "text": "    db.insert(row)",
+            "mark": false
+          },
+          {
+            "n": 18,
+            "text": "print(f\"seeded {len(rows)} rows\")",
+            "mark": true
+          }
+        ],
+        "message": "`print` found",
+        "caught_by": "b"
+      },
+      "more_like_this": {
+        "count": 3,
+        "files": [
+          "scripts/migrate.py",
+          "scripts/backfill_prices.py"
+        ]
+      },
+      "details": {
+        "a": [
+          {
+            "key": "rule",
+            "raw": "T201",
+            "plain": "flags every call to `print`",
+            "matches_example": null
+          },
+          {
+            "key": "ignores",
+            "raw": "scripts/**",
+            "plain": "except the files under scripts/",
+            "matches_example": true
+          }
+        ],
+        "b": [
+          {
+            "key": "rule",
+            "raw": "T201",
+            "plain": "flags every call to `print`",
+            "matches_example": null
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "ruff",
+          "id": "T201",
+          "explanation": {
+            "source": "ruff rule",
+            "what": "Checks for `print` statements.",
+            "why": "`print` statements used for debugging should be omitted from production code. They can lead to the accidental inclusion of sensitive information in logs, and are not configurable by clients, unlike `logging` statements.",
+            "example_bad": "def sum_less_than_four(a, b):\n    print(f\"Calling with {a} and {b}\")\n    return a + b < 4",
+            "example_good": "import logging\n\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(__name__)\n\n\ndef sum_less_than_four(a, b):\n    logger.debug(\"Calling with %s and %s\", a, b)\n    return a + b < 4",
+            "url": "https://docs.astral.sh/ruff/rules/print/"
+          }
+        }
+      ],
+      "repeat": {
+        "group": "req-logging",
+        "index": 1,
+        "of": 2
+      }
+    },
+    {
+      "source_id": "req-logging:debug-flag",
+      "group": "all",
+      "body": "Never log with `print`; use the `logging` module",
+      "situation": {
+        "summary": "One setting allows `print` behind a debug flag, the other forbids every `print`.",
+        "question": "Does «Never log with `print`; use the `logging` module» forbid {line}?"
+      },
+      "example": {
+        "file": "shop/cart.py",
+        "lines": [
+          {
+            "n": 30,
+            "text": "    if DEBUG:",
+            "mark": false
+          },
+          {
+            "n": 31,
+            "text": "        print(\"cart\", cart.id, cart.total)",
+            "mark": true
+          }
+        ],
+        "message": "`print` found",
+        "caught_by": "a"
+      },
+      "details": {
+        "a": [
+          {
+            "key": "rule",
+            "raw": "T201",
+            "plain": "flags every call to `print`",
+            "matches_example": null
+          }
+        ],
+        "b": [
+          {
+            "key": "rule",
+            "raw": "T201",
+            "plain": "flags every call to `print`",
+            "matches_example": null
+          },
+          {
+            "key": "option:allow-debug",
+            "raw": "true",
+            "plain": "allows `print` inside `if DEBUG:`",
+            "matches_example": true
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "ruff",
+          "id": "T201",
+          "explanation": {
+            "source": "none"
+          }
+        }
+      ],
+      "repeat": {
+        "group": "req-logging",
+        "index": 2,
+        "of": 2
+      }
+    },
+    {
+      "source_id": "req-imports:barrel",
+      "group": "all",
+      "body": "Import from a package's public entry point, never from its internals",
+      "situation": {
+        "summary": "One setting forbids any path below a package's folder, the other only paths into src/internal/.",
+        "question": "Does «Import from a package's public entry point, never from its internals» forbid {line}?"
+      },
+      "example": {
+        "file": "apps/web/src/checkout/total.ts",
+        "lines": [
+          {
+            "n": 1,
+            "text": "import { money } from \"@demo/format\";",
+            "mark": false
+          },
+          {
+            "n": 2,
+            "text": "import { round } from \"@demo/format/src/round\";",
+            "mark": true
+          },
+          {
+            "n": 3,
+            "text": "",
+            "mark": false
+          }
+        ],
+        "message": "'@demo/format/src/round' import is restricted from being used by a pattern. Import from the package's entry point.",
+        "caught_by": "a"
+      },
+      "more_like_this": {
+        "count": 1,
+        "files": [
+          "apps/admin/src/report/sum.ts"
+        ]
+      },
+      "details": {
+        "a": [
+          {
+            "key": "option:patterns",
+            "raw": "[{\"group\": [\"@demo/*/*\"], \"message\": \"Import from the package's entry point.\"}]",
+            "plain": "forbids any import path one or more folders below a `@demo/` package",
+            "matches_example": true
+          },
+          {
+            "key": "files",
+            "raw": "apps/**/*.ts",
+            "plain": "the TypeScript files under apps/",
+            "matches_example": true
+          }
+        ],
+        "b": [
+          {
+            "key": "option:patterns",
+            "raw": "[{\"group\": [\"@demo/*/src/internal/**\"]}]",
+            "plain": "forbids only import paths into a package's src/internal/ folder",
+            "matches_example": false
+          },
+          {
+            "key": "files",
+            "raw": "apps/**/*.ts",
+            "plain": "the TypeScript files under apps/",
+            "matches_example": true
+          }
+        ]
+      },
+      "rules": [
+        {
+          "linter": "eslint",
+          "id": "no-restricted-imports",
+          "explanation": {
+            "source": "config message",
+            "what": "Import from the package's entry point.",
+            "url": "https://eslint.org/docs/latest/rules/no-restricted-imports"
+          }
+        }
+      ]
+    }
+  ]
+}