@kamishibai/sdk 0.1.1

package/src/core/lint-gates.js

@@ -0,0 +1,427 @@
+import { CODES, EXIT, KsbError, ROOT_PATH } from './errors.js'
+
+/**
+ * The `[gates]` layer of `lint` (CONTRACT F7b H1, SPEC §5.4).
+ *
+ * The six retired gates disagreed about numbers, and the disagreement was not a
+ * mistake anybody made: 「body line-height 上限」 is 1.55 in `check.py`, 1.6 in
+ * `render-design-html.md` and 1.70 in book's checklist because those are three
+ * *design languages*, not three opinions about one language. An SDK that serves
+ * all three cannot pick one and be right twice.
+ *
+ * So the threshold moves to where the design language already lives — the
+ * template package's own `manifest.toml`:
+ *
+ * ```toml
+ * [gates]
+ * bodyLineHeightMax = 1.55
+ * allowItalic = false
+ * ```
+ *
+ * Two consequences are load-bearing:
+ *
+ *  - **Undeclared means the rule does not run.** Not "runs with a default": a
+ *    default here would be this file quietly picking one of the three numbers
+ *    after all, and every package that never opted in would start failing for a
+ *    rule its author never agreed to.
+ *  - **An unknown key is refused by name.** A `[gates]` typo that is silently
+ *    ignored leaves a package believing it is gated when nothing is running —
+ *    the worst of the three states, because it is the one nobody checks.
+ *
+ * Dependency direction is unchanged (AGENTS §3.1): this module is pure `core`.
+ * It is *read* by the delivery layer to validate a manifest, and it never reads
+ * a manifest itself — the caller hands it the already-parsed table.
+ */
+
+/** Verbatim CONTRACT constant — the manifest section these rules are declared in. */
+export const GATES_SECTION = 'gates'
+
+const declarationError = (message) =>
+  new KsbError({
+    code: CODES.GATE_DECLARATION_INVALID,
+    message,
+    path: 'doc.meta.template',
+    exitCode: EXIT.VALIDATION,
+  })
+
+const finding = (code, message) => ({ path: ROOT_PATH, code, message })
+
+/** A colour literal, in either of the two spellings CSS actually carries. */
+const HEX_RE = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/
+
+/** `#abc` and `#AABBCC` are the same colour; the blocklist must not care which. */
+const normaliseHex = (hex) => {
+  const body = hex.slice(1).toLowerCase()
+  return body.length === 3 ? `#${body[0]}${body[0]}${body[1]}${body[1]}${body[2]}${body[2]}` : `#${body}`
+}
+
+/**
+ * `line-height: 1.62` — **unitless only**, and deliberately so.
+ *
+ * `1.5rem`, `24px` and `150%` are not comparable to a unitless ratio without
+ * knowing the font-size, and the collected implementation compared them anyway
+ * (`check.py` L160 captures `150` out of `150%` and then tests it against 1.55).
+ * The lookahead is what keeps a unit out: a digit run followed by `r`, `p` or
+ * `%` simply does not match, so a rule that cannot be judged is not judged.
+ */
+const LINE_HEIGHT_RE = /line-height\s*:\s*([0-9]*\.?[0-9]+)\s*(?=[;}!]|$|\s)/gi
+
+/**
+ * A selector that puts a declaration on a heading — `h2`, `.card > h3`, `h1, h2`.
+ * One definition, read by both the heading gate and the body line-height gate:
+ * 「這是不是標題」 answered two slightly different ways is how a body ceiling and
+ * a heading ceiling end up disagreeing about the same block.
+ */
+const HEADING_SELECTOR_RE = /(^|[\s,>+~(])h[1-6]\b/i
+
+/**
+ * The ceiling is a **body** ceiling, so headings are excluded by selector.
+ *
+ * The collected implementation said the same thing with a substring test on the
+ * declaration's own line (`check.py` L720-727 skips a line containing
+ * `headline`, `title` or `display`). Selector-awareness is the same intent
+ * expressed where the fact actually lives: a `line-height` inside `h1 { … }` is
+ * a heading's, whatever the block happens to be named, and a `.headline` class
+ * that is not a heading element no longer buys silence it never earned.
+ *
+ * Reading `cssBlocks` rather than `css` is deliberate and has one visible
+ * consequence: inline `style=` attributes carry no selector, so they are out of
+ * scope. A rule that cannot tell whose line-height it is looking at should not
+ * be calling it 「正文」 in the failure message.
+ */
+const checkLineHeight = (max, regions) => {
+  const over = new Set()
+  for (const { selector, body } of regions.cssBlocks) {
+    if (HEADING_SELECTOR_RE.test(selector)) continue
+    for (const m of body.matchAll(LINE_HEIGHT_RE)) {
+      const value = Number(m[1])
+      if (Number.isFinite(value) && value > max) over.add(value)
+    }
+  }
+  if (over.size === 0) return []
+  const listed = [...over].sort((a, b) => a - b).join('、')
+  return [
+    finding(
+      CODES.GATE_LINE_HEIGHT,
+      `產物的正文 line-height ${listed} 超過模板包宣告的上限 ${max}` +
+        `（\`[gates] bodyLineHeightMax\`）；比較為嚴格大於，等於上限即通過`,
+    ),
+  ]
+}
+
+/** `font-weight: 700`; `bold` is folded to 700, `bolder` is relative and skipped. */
+const FONT_WEIGHT_RE = /font-weight\s*:\s*(\d{3}|bold)\b/gi
+
+const checkHeadingWeight = (max, regions) => {
+  const over = new Set()
+  for (const { selector, body } of regions.cssBlocks) {
+    if (!HEADING_SELECTOR_RE.test(selector)) continue
+    for (const m of body.matchAll(FONT_WEIGHT_RE)) {
+      const weight = m[1].toLowerCase() === 'bold' ? 700 : Number(m[1])
+      if (weight > max) over.add(weight)
+    }
+  }
+  if (over.size === 0) return []
+  const listed = [...over].sort((a, b) => a - b).join('、')
+  return [
+    finding(
+      CODES.GATE_HEADING_WEIGHT,
+      `產物的標題規則 font-weight ${listed} 超過模板包宣告的上限 ${max}` +
+        `（\`[gates] headingWeightMax\`）；\`bold\` 折算 700，相對值 \`bolder\` 無法靜態判定故不判`,
+    ),
+  ]
+}
+
+/** One `box-shadow` declaration's value, up to the `;` or the closing brace. */
+const BOX_SHADOW_RE = /box-shadow\s*:\s*([^;}]+)/gi
+
+/**
+ * A colour function's arguments, removed before lengths are counted.
+ *
+ * `rgba(43, 255, 181, .5)` carries four numbers that are not lengths, and the
+ * first version of this gate counted them. Stripping is safer than a smarter
+ * length pattern: whatever colour syntax arrives next, its digits leave with it.
+ */
+const COLOR_FUNCTION_RE = /[a-z-]+\([^()]*\)/gi
+
+/** `#333333` is six digits that are not a length. Same reason as above. */
+const HEX_COLOR_RE = /#[0-9a-fA-F]{3,8}\b/g
+
+/**
+ * A CSS length: `18px`, `-2px`, `.5px`, and a **unitless `0`**, which is legal
+ * everywhere a length is and is what real stylesheets actually write.
+ * Missing it is what made `0 0 18px rgba(…)` read as「只有一個 length」.
+ */
+const LENGTH_TOKEN_RE = /(-?\d*\.?\d+)(px)?(?=\s|$)/gi
+
+/** Everything in a shadow that is not a length, removed before counting. */
+const lengthsOf = (shadow) =>
+  [
+    ...shadow
+      .replace(COLOR_FUNCTION_RE, ' ')
+      .replace(HEX_COLOR_RE, ' ')
+      .matchAll(LENGTH_TOKEN_RE),
+  ].map((m) => Number(m[1]))
+
+/**
+ * The blur of one shadow, or `undefined` when it cannot be told.
+ *
+ * `undefined` is a real answer here, not a failure to get one: 「判不出來就不判」
+ * is the same clause `var()` already gets, and the alternative — defaulting to
+ * 0 — is precisely the bug this replaces. A two-length shadow (`2px 4px #000`)
+ * therefore goes unjudged even though CSS would give it blur 0; that is a
+ * deliberate under-reach, matching the collected implementation, whose pattern
+ * `(-?\d+px\s+){1,2}(\d+)px` (`check.py` L161) equally requires a third length
+ * before it says anything. Under-reaching is the safe direction for a gate that
+ * runs against artifacts nobody wrote by hand.
+ */
+const blurOf = (shadow) => {
+  if (/var\(/i.test(shadow)) return undefined
+  const lengths = lengthsOf(shadow)
+  if (lengths.length < 3) return undefined
+  // CSS order: offset-x offset-y blur [spread].
+  const [offsetX, offsetY, blur] = lengths
+  // A shadow with no offset is a glow or a ring (`0 0 0 8px` is the focus-ring
+  // idiom), not a drop shadow — and 「無硬陰影」 is a statement about drop
+  // shadows. Judging a ring by a blur floor is a category error, and the
+  // collected implementation never judged one either: its pattern needs the
+  // offsets to carry `px`, which `0 0 …` does not.
+  if (offsetX === 0 && offsetY === 0) return undefined
+  return blur
+}
+
+const checkShadowBlur = (min, regions) => {
+  const under = new Set()
+  for (const m of regions.css.matchAll(BOX_SHADOW_RE)) {
+    const value = m[1]
+    if (/^\s*none\b/i.test(value)) continue
+    // A comma-separated list is *several* shadows. Reading it as one and taking
+    // the third length was how `0 1px 2px #000, 0 4px 16px #000` passed: the
+    // hard 2px edge was invisible behind the soft one that followed it.
+    for (const shadow of value.replace(COLOR_FUNCTION_RE, (c) => c.replace(/,/g, ';')).split(',')) {
+      const blur = blurOf(shadow.replace(/;/g, ','))
+      if (blur !== undefined && blur < min) under.add(blur)
+    }
+  }
+  if (under.size === 0) return []
+  const listed = [...under].sort((a, b) => a - b).join('、')
+  return [
+    finding(
+      CODES.GATE_SHADOW_BLUR,
+      `產物的 box-shadow 模糊半徑 ${listed}px 低於模板包宣告的下限 ${min}px` +
+        `（\`[gates] shadowBlurMinPx\`）；逗號清單逐枚判；零偏移的光暈／描邊環、` +
+        `length 不足三個、含 \`var()\` 者皆無法判定故不判`,
+    ),
+  ]
+}
+
+const ITALIC_RE = /font-style\s*:\s*italic/i
+
+const checkItalic = (allowed, regions) => {
+  if (allowed) return []
+  if (!ITALIC_RE.test(regions.css)) return []
+  return [
+    finding(
+      CODES.GATE_ITALIC,
+      '產物含 `font-style: italic`，但模板包宣告 `[gates] allowItalic = false`',
+    ),
+  ]
+}
+
+const SVG_RGBA_RE = /rgba\s*\(/i
+
+/**
+ * `rgba()` inside a figure — a gate, not a core rule (CONTRACT R10).
+ *
+ * It was collected as core first, on book #7b's reason: the PDF/PPTX export
+ * chain flattens alpha, so what the figure looks like on screen is not what
+ * comes out. That reason is real and it is also **conditional** — it only bites
+ * a product somebody is going to export. The first real skinned product proved
+ * the point: `common-dev/sand-table`'s `x-tacmap` / `x-causal-history` figures
+ * carry seventeen distinct `rgba()` glow and shadow forms ported from the old
+ * Python renderer, and that sand table is consumed as HTML and never exported.
+ * A rule that reds a product the user has already accepted is a rule that is
+ * wrong about its own scope (CONTRACT H4「誤報即規則錯，不是產物錯」).
+ */
+const checkSvgRgba = (_banned, regions) => {
+  if (!SVG_RGBA_RE.test(regions.svg)) return []
+  return [
+    finding(
+      CODES.SVG_RGBA,
+      '產物的 `<svg>` 內含 `rgba()`，但模板包宣告 `[gates] svgRgbaBan = true`' +
+        '；理由是 export pdf/pptx 這條路上圖的 alpha 會被壓平——' +
+        '純 HTML 消費、不走匯出的產物不必宣告這一道',
+    ),
+  ]
+}
+
+const HEX_IN_CSS_RE = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g
+
+const checkBannedHex = (banned, regions) => {
+  const blocked = new Set(banned.map(normaliseHex))
+  const hits = new Set()
+  for (const m of regions.css.matchAll(HEX_IN_CSS_RE)) {
+    const hex = normaliseHex(`#${m[1]}`)
+    if (blocked.has(hex)) hits.add(hex)
+  }
+  if (hits.size === 0) return []
+  return [
+    finding(
+      CODES.GATE_BANNED_HEX,
+      `產物的 CSS 含模板包自列的禁用色 ${[...hits].sort().join('、')}` +
+        '（`[gates] bannedHex`）；色票應走模板包自己的 token，而不是裸色碼',
+    ),
+  ]
+}
+
+/**
+ * Every declarable gate, as data — the single source `lint --rules`, the
+ * manifest validator and the linter all read.
+ *
+ * `off` is what "declared, but this value turns the rule off" means: a boolean
+ * gate set to its permissive value is *declared* (so it is not a typo) and
+ * still runs nothing.
+ */
+export const GATE_SPECS = Object.freeze([
+  Object.freeze({
+    key: 'bodyLineHeightMax',
+    type: 'positiveNumber',
+    code: CODES.GATE_LINE_HEIGHT,
+    scope: 'css',
+    pattern: LINE_HEIGHT_RE.source,
+    note: '正文 line-height 不得超過模板包宣告的上限（嚴格大於才算違規）',
+    check: checkLineHeight,
+  }),
+  Object.freeze({
+    key: 'headingWeightMax',
+    type: 'positiveNumber',
+    code: CODES.GATE_HEADING_WEIGHT,
+    scope: 'css',
+    pattern: FONT_WEIGHT_RE.source,
+    note: '標題選擇器（h1–h6）內的 font-weight 不得超過模板包宣告的上限',
+    check: checkHeadingWeight,
+  }),
+  Object.freeze({
+    key: 'shadowBlurMinPx',
+    type: 'positiveNumber',
+    code: CODES.GATE_SHADOW_BLUR,
+    scope: 'css',
+    pattern: BOX_SHADOW_RE.source,
+    note: 'box-shadow 的模糊半徑不得低於模板包宣告的下限（擋硬陰影）',
+    check: checkShadowBlur,
+  }),
+  Object.freeze({
+    key: 'allowItalic',
+    type: 'boolean',
+    code: CODES.GATE_ITALIC,
+    scope: 'css',
+    pattern: ITALIC_RE.source,
+    note: '宣告 false 時，產物不得含 font-style: italic；宣告 true 等於不跑這條',
+    check: checkItalic,
+    off: (value) => value === true,
+  }),
+  Object.freeze({
+    key: 'svgRgbaBan',
+    type: 'boolean',
+    code: CODES.SVG_RGBA,
+    scope: 'svg',
+    pattern: SVG_RGBA_RE.source,
+    note: '宣告 true 時，`<svg>` 子樹內不得出現 rgba()（匯出會壓平 alpha）；宣告 false 等於不跑這條',
+    check: checkSvgRgba,
+    off: (value) => value === false,
+  }),
+  Object.freeze({
+    key: 'bannedHex',
+    type: 'hexList',
+    code: CODES.GATE_BANNED_HEX,
+    scope: 'css',
+    pattern: HEX_IN_CSS_RE.source,
+    note: '產物 CSS 不得出現模板包自列的禁用色碼（#rgb 與 #rrggbb 視為同色）',
+    check: checkBannedHex,
+    off: (value) => value.length === 0,
+  }),
+])
+
+/** `gates.<key>` — what `lint --rules` prints as a gate rule's declaration site. */
+export const declarationSiteOf = (key) => `${GATES_SECTION}.${key}`
+
+const SPEC_BY_KEY = new Map(GATE_SPECS.map((spec) => [spec.key, spec]))
+
+/** Every gate a manifest may declare, in listing order. */
+export const gateKeys = () => GATE_SPECS.map((spec) => spec.key)
+
+const isTable = (value) => value !== null && typeof value === 'object' && !Array.isArray(value)
+
+const TYPE_CHECK = Object.freeze({
+  positiveNumber: (value) => typeof value === 'number' && Number.isFinite(value) && value > 0,
+  boolean: (value) => typeof value === 'boolean',
+  hexList: (value) => Array.isArray(value) && value.every((v) => typeof v === 'string' && HEX_RE.test(v)),
+})
+
+const TYPE_WORDING = Object.freeze({
+  positiveNumber: '正數',
+  boolean: '布林值（true／false）',
+  hexList: '`#rgb` 或 `#rrggbb` 形色碼的字串陣列',
+})
+
+/**
+ * Validate a manifest's `[gates]` table, loudly (CONTRACT F7b H1).
+ *
+ * @param {unknown} gates the raw `gates` value as the TOML reader produced it
+ * @param {string} where `<namespace>/<name>`, for the message
+ * @returns {Readonly<Record<string, unknown>>} the declared gates, `{}` when absent
+ * @throws {KsbError} KSB_GATE_DECLARATION_INVALID, naming the offending key
+ */
+export function validateGateDeclaration(gates, where) {
+  if (gates === undefined) return Object.freeze({})
+  if (!isTable(gates)) {
+    throw declarationError(
+      `模板包 ${where} 的 \`[${GATES_SECTION}]\` 必須是具名表，得到 ${JSON.stringify(gates)}。`,
+    )
+  }
+  for (const [key, value] of Object.entries(gates)) {
+    const spec = SPEC_BY_KEY.get(key)
+    if (spec === undefined) {
+      throw declarationError(
+        `模板包 ${where} 的 \`[${GATES_SECTION}]\` 宣告了不存在的閘門 \`${key}\`；` +
+          `可宣告的閘門：${gateKeys().join('、')}。` +
+          '未知宣告一律拒收——默默忽略它，包就會以為自己有一道從來沒跑過的閘門。',
+      )
+    }
+    if (!TYPE_CHECK[spec.type](value)) {
+      throw declarationError(
+        `模板包 ${where} 的 \`[${GATES_SECTION}] ${key}\` 必須是${TYPE_WORDING[spec.type]}，` +
+          `得到 ${JSON.stringify(value)}。`,
+      )
+    }
+  }
+  return Object.freeze({ ...gates })
+}
+
+/**
+ * Run every gate the package declared against one artifact's scan regions.
+ *
+ * @param {Record<string, unknown>} gates the validated declaration ({} when none)
+ * @param {{css: string, cssBlocks: Array<{selector: string, body: string}>}} regions
+ * @returns {Array<{path: string, code: string, message: string}>}
+ */
+export function lintGates(gates, regions) {
+  if (!isTable(gates)) return []
+  return GATE_SPECS.flatMap((spec) => {
+    const value = gates[spec.key]
+    if (value === undefined) return []
+    if (spec.off?.(value)) return []
+    return spec.check(value, regions)
+  })
+}
+
+/** The gate rules as `lint --rules` rows, each carrying its declaration site. */
+export function gateRuleListing() {
+  return GATE_SPECS.map((spec) => ({
+    code: spec.code,
+    scope: spec.scope,
+    pattern: spec.pattern,
+    note: spec.note,
+    gate: declarationSiteOf(spec.key),
+  }))
+}