From 6a3ad116f3d1348de6b9353e35ba6d4dceeb65c0 Mon Sep 17 00:00:00 2001 From: "otoneko." Date: Wed, 14 Oct 2026 15:59:46 +0900 Subject: [PATCH] feat: add lint rules and an ignore option to lintInput New rules: duplicate ids, future dates, relative URLs in content, enclosure type/length, overlong or HTML titles, and a paging suggestion past 100 items. Every rule has an id, and lintInput accepts { ignore, now }. --- README.ja.md | 4 +- README.md | 4 +- base/README.base.md | 11 ++- src/index.ts | 1 + src/lint.test.ts | 94 +++++++++++++++++++++++++ src/lint.ts | 168 +++++++++++++++++++++++++++++++++++++++----- 6 files changed, 262 insertions(+), 20 deletions(-) diff --git a/README.ja.md b/README.ja.md index 07b9a47..7e0ce1b 100644 --- a/README.ja.md +++ b/README.ja.md @@ -742,7 +742,7 @@ const xml = toAtom({ options, items }, { baseUrl: 'https://example.com' }) ## リント -`validateInput` が検証するのは、ドキュメントを壊すものだけです (タイトルがない、Atom の author がない、など)。`lintInput` はさらに踏み込み、仕様上は省略可能でも、実際のリーダーやディレクトリが期待している項目を指摘します。たとえばフィードの `description` / `language` / `image` がない、記事に `id`、`author`、日付がない、`podcast` を設定したのにポッドキャストのメタデータが不完全、などです。例外は投げず、警告の `string[]` を返します (問題がなければ空)。`serveFeed` はこれを呼ばないので、テストや CI 向けの機能で、配信の経路では使いません。 +`validateInput` が検証するのは、ドキュメントを壊すものだけです (タイトルがない、Atom の author がない、など)。`lintInput` はさらに踏み込み、仕様上は省略可能でも、実際のリーダーやディレクトリが期待している項目を指摘します。たとえばフィードの `description` / `language` / `image` がない、記事に `id`、`author`、日付がない、`podcast` を設定したのにポッドキャストのメタデータが不完全、などです。よくあるミスも検出します。記事の `id` の重複、未来の日付 (多くはタイムゾーンの取り違え)、`content` / `description` に残った相対 URL (リーダーが解決できません)、`type` や `length` がない enclosure、長すぎる、または HTML が混ざったタイトル、100 件を超えるのに `paging` がないフィード、などです。例外は投げず、警告の `string[]` を返します (問題がなければ空)。`serveFeed` はこれを呼ばないので、テストや CI 向けの機能で、配信の経路では使いません。 ```ts import { lintInput } from 'hono-feed' @@ -751,6 +751,8 @@ const warnings = lintInput({ options, items }, 'rss') // e.g. expect(lintInput({ options, items }, 'rss')).toEqual([]) in a CI check ``` +すべてのルールに ID (`LintRuleId`) があり、許容するルールだけ無効にできます。たとえば `lintInput(input, 'rss', { ignore: ['feed-language', 'item-count'] })` のように指定します。`future-date` ルールは現在時刻と比較するので、テストを決定的にしたい場合は `now` を渡してください。 + ## コントリビュート コントリビュートを歓迎します。次のような形で参加できます。 diff --git a/README.md b/README.md index ce5d298..37459de 100644 --- a/README.md +++ b/README.md @@ -742,7 +742,7 @@ const xml = toAtom({ options, items }, { baseUrl: 'https://example.com' }) ## Linting -`validateInput` only enforces what breaks the document (a missing title, a missing Atom author, …). `lintInput` goes further: it flags fields that are optional per spec but expected by real readers and directories — a missing feed `description`/`language`/`image`, an item with no `id`, `author`, or date, incomplete Podcast metadata once `podcast` is set, and so on. It never throws and returns a plain `string[]` of warnings (empty when clean), and `serveFeed` never calls it — it's for tests and CI, not the serve path: +`validateInput` only enforces what breaks the document (a missing title, a missing Atom author, …). `lintInput` goes further: it flags fields that are optional per spec but expected by real readers and directories — a missing feed `description`/`language`/`image`, an item with no `id`, `author`, or date, incomplete Podcast metadata once `podcast` is set, and so on. It also catches common mistakes: duplicate item ids, a date in the future (usually a timezone mix-up), relative URLs left in `content`/`description` (readers can't resolve them), an enclosure with no `type` or `length`, an overlong or HTML-laden title, and a feed of more than 100 items with no `paging`. It never throws and returns a plain `string[]` of warnings (empty when clean), and `serveFeed` never calls it — it's for tests and CI, not the serve path: ```ts import { lintInput } from 'hono-feed' @@ -751,6 +751,8 @@ const warnings = lintInput({ options, items }, 'rss') // e.g. expect(lintInput({ options, items }, 'rss')).toEqual([]) in a CI check ``` +Every rule has an id (`LintRuleId`), so you can silence the ones you accept: `lintInput(input, 'rss', { ignore: ['feed-language', 'item-count'] })`. The `future-date` rule compares against the current time; pass `now` for a deterministic test. + ## Contributing Contributions Welcome! You can contribute in the following ways. diff --git a/base/README.base.md b/base/README.base.md index 2b2d2d1..fe9d79d 100644 --- a/base/README.base.md +++ b/base/README.base.md @@ -1093,12 +1093,12 @@ const xml = toAtom({ options, items }, { baseUrl: 'https://example.com' }) :::kiritan{locale=en} ## Linting -`validateInput` only enforces what breaks the document (a missing title, a missing Atom author, …). `lintInput` goes further: it flags fields that are optional per spec but expected by real readers and directories — a missing feed `description`/`language`/`image`, an item with no `id`, `author`, or date, incomplete Podcast metadata once `podcast` is set, and so on. It never throws and returns a plain `string[]` of warnings (empty when clean), and `serveFeed` never calls it — it's for tests and CI, not the serve path: +`validateInput` only enforces what breaks the document (a missing title, a missing Atom author, …). `lintInput` goes further: it flags fields that are optional per spec but expected by real readers and directories — a missing feed `description`/`language`/`image`, an item with no `id`, `author`, or date, incomplete Podcast metadata once `podcast` is set, and so on. It also catches common mistakes: duplicate item ids, a date in the future (usually a timezone mix-up), relative URLs left in `content`/`description` (readers can't resolve them), an enclosure with no `type` or `length`, an overlong or HTML-laden title, and a feed of more than 100 items with no `paging`. It never throws and returns a plain `string[]` of warnings (empty when clean), and `serveFeed` never calls it — it's for tests and CI, not the serve path: ::: :::kiritan{locale=ja} ## リント -`validateInput` が検証するのは、ドキュメントを壊すものだけです (タイトルがない、Atom の author がない、など)。`lintInput` はさらに踏み込み、仕様上は省略可能でも、実際のリーダーやディレクトリが期待している項目を指摘します。たとえばフィードの `description` / `language` / `image` がない、記事に `id`、`author`、日付がない、`podcast` を設定したのにポッドキャストのメタデータが不完全、などです。例外は投げず、警告の `string[]` を返します (問題がなければ空)。`serveFeed` はこれを呼ばないので、テストや CI 向けの機能で、配信の経路では使いません。 +`validateInput` が検証するのは、ドキュメントを壊すものだけです (タイトルがない、Atom の author がない、など)。`lintInput` はさらに踏み込み、仕様上は省略可能でも、実際のリーダーやディレクトリが期待している項目を指摘します。たとえばフィードの `description` / `language` / `image` がない、記事に `id`、`author`、日付がない、`podcast` を設定したのにポッドキャストのメタデータが不完全、などです。よくあるミスも検出します。記事の `id` の重複、未来の日付 (多くはタイムゾーンの取り違え)、`content` / `description` に残った相対 URL (リーダーが解決できません)、`type` や `length` がない enclosure、長すぎる、または HTML が混ざったタイトル、100 件を超えるのに `paging` がないフィード、などです。例外は投げず、警告の `string[]` を返します (問題がなければ空)。`serveFeed` はこれを呼ばないので、テストや CI 向けの機能で、配信の経路では使いません。 ::: ```ts @@ -1108,6 +1108,13 @@ const warnings = lintInput({ options, items }, 'rss') // e.g. expect(lintInput({ options, items }, 'rss')).toEqual([]) in a CI check ``` +:::kiritan{locale=en} +Every rule has an id (`LintRuleId`), so you can silence the ones you accept: `lintInput(input, 'rss', { ignore: ['feed-language', 'item-count'] })`. The `future-date` rule compares against the current time; pass `now` for a deterministic test. +::: +:::kiritan{locale=ja} +すべてのルールに ID (`LintRuleId`) があり、許容するルールだけ無効にできます。たとえば `lintInput(input, 'rss', { ignore: ['feed-language', 'item-count'] })` のように指定します。`future-date` ルールは現在時刻と比較するので、テストを決定的にしたい場合は `now` を渡してください。 +::: + :::kiritan{locale=en} ## Contributing diff --git a/src/index.ts b/src/index.ts index 9d90d37..5966670 100644 --- a/src/index.ts +++ b/src/index.ts @@ -1,5 +1,6 @@ export { Feed } from './feed' export { toAtom, toJSONFeed, toRSS } from './formats' +export type { LintOptions, LintRuleId } from './lint' export { lintInput } from './lint' export type { FeedMiddlewareEnv, ServeFeedFn } from './middleware' export { feed as feedMiddleware } from './middleware' diff --git a/src/lint.test.ts b/src/lint.test.ts index cbdb44f..9458920 100644 --- a/src/lint.test.ts +++ b/src/lint.test.ts @@ -176,3 +176,97 @@ describe('lintInput', () => { expect(() => lintInput(empty, 'atom')).not.toThrow() }) }) + +describe('lintInput rules', () => { + const withItem = (patch: Partial): FeedInput => ({ + ...clean, + items: [{ ...clean.items[0], ...patch }], + }) + const now = new Date('2026-07-01T00:00:00Z') + + it('flags items that share an id (or fall back to the same link)', () => { + const dup: FeedInput = { ...clean, items: [clean.items[0], { ...clean.items[0] }] } + expect(lintInput(dup, 'rss')).toEqual([expect.stringMatching(/item\[1\].*item\[0\]/)]) + const byLink: FeedInput = { + ...clean, + items: [ + { ...clean.items[0], id: undefined }, + { ...clean.items[0], id: undefined }, + ], + } + expect(lintInput(byLink, 'rss', { ignore: ['item-id'] })).toEqual([ + expect.stringMatching(/same id\/link/), + ]) + }) + + it('flags a date more than a day in the future, but not a small skew', () => { + const future = withItem({ published: new Date('2026-07-03T00:00:00Z') }) + expect(lintInput(future, 'rss', { now })).toEqual([ + expect.stringMatching(/"published" is in the future/), + ]) + expect( + lintInput(withItem({ updated: new Date('2026-07-01T05:00:00Z') }), 'rss', { now }), + ).toEqual([]) + }) + + it('flags relative URLs in content and description, not absolute, fragment or mailto ones', () => { + const relative = withItem({ content: 'x' }) + expect(lintInput(relative, 'atom')).toEqual([ + expect.stringMatching(/"content" has 2 relative URL\(s\), e\.g\. "\/a\.png"/), + ]) + expect(lintInput(withItem({ description: "" }), 'rss')).toEqual([ + expect.stringMatching(/"description"/), + ]) + const fine = withItem({ + content: + 'abcd', + }) + expect(lintInput(fine, 'atom')).toEqual([]) + }) + + it('flags an enclosure with no type or a zero length', () => { + const noLength = withItem({ enclosure: { url: 'https://a.test/a.mp3', type: 'audio/mpeg' } }) + expect(lintInput(noLength, 'rss')).toEqual([expect.stringMatching(/no "length"/)]) + const noType = withItem({ enclosure: { url: 'https://a.test/a.mp3', type: '', length: 5 } }) + expect(lintInput(noType, 'rss')).toEqual([expect.stringMatching(/no "type"/)]) + const ok = withItem({ + enclosure: { url: 'https://a.test/a.mp3', type: 'audio/mpeg', length: 5 }, + }) + expect(lintInput(ok, 'rss')).toEqual([]) + }) + + it('flags an overlong title and a title containing HTML', () => { + expect(lintInput(withItem({ title: 'x'.repeat(151) }), 'rss')).toEqual([ + expect.stringMatching(/151 characters/), + ]) + expect(lintInput(withItem({ title: 'a bold move' }), 'rss')).toEqual([ + expect.stringMatching(/HTML markup/), + ]) + expect(lintInput(withItem({ title: '1 < 2 and 3 > 2' }), 'rss')).toEqual([]) + }) + + it('suggests paging for a feed over 100 items, unless paging is set', () => { + const many: FeedInput = { + ...clean, + items: Array.from({ length: 101 }, (_, i) => ({ + ...clean.items[0], + id: `https://example.com/${i}`, + link: `https://example.com/${i}`, + })), + } + expect(lintInput(many, 'rss')).toEqual([expect.stringMatching(/101 items.*paging/)]) + const paged: FeedInput = { + ...many, + options: { ...many.options, paging: { next: 'https://example.com/?p=2' } }, + } + expect(lintInput(paged, 'rss')).toEqual([]) + }) + + it('skips ignored rules, including the pre-existing ones', () => { + const bare: FeedInput = { options: { title: 't' }, items: [{ title: 'a' }] } + const all = lintInput(bare, 'rss') + const filtered = lintInput(bare, 'rss', { ignore: ['feed-description', 'item-author'] }) + expect(all.length - filtered.length).toBe(2) + expect(filtered.join('\n')).not.toMatch(/"description"|"author"/) + }) +}) diff --git a/src/lint.ts b/src/lint.ts index d54fe65..feba1f0 100644 --- a/src/lint.ts +++ b/src/lint.ts @@ -1,53 +1,106 @@ import type { FeedFormat, FeedInput, FeedItem, FeedOptions } from './types' import { firstAuthor } from './utils/author' +import { enclosureList } from './utils/enclosure' + +/** Stable identifier of a lint rule, for `LintOptions.ignore`. */ +export type LintRuleId = + | 'feed-description' + | 'feed-language' + | 'feed-image' + | 'atom-feed-id' + | 'atom-feed-link' + | 'paging-archive-current' + | 'podcast-incomplete' + | 'item-id' + | 'item-date' + | 'item-author' + | 'duplicate-id' + | 'future-date' + | 'relative-url' + | 'enclosure' + | 'title' + | 'item-count' + +export interface LintOptions { + /** Rules to skip, by id. */ + ignore?: LintRuleId[] + /** The "current time" for the `future-date` rule. Defaults to `new Date()`; set it for deterministic tests. */ + now?: Date +} + +type Report = (rule: LintRuleId, message: string) => void + +// Dates a little ahead of the clock are normal (timezone rounding, clock skew); anything beyond a day is almost always a timezone mix-up. +const FUTURE_TOLERANCE_MS = 24 * 60 * 60 * 1000 +const LONG_TITLE_LENGTH = 150 +const PAGING_SUGGESTION_ITEM_COUNT = 100 /** * Report recommended-but-missing fields — the "valid, but…" tier that `validateInput` doesn't cover. `validateInput` enforces hard spec requirements (missing → broken document); `lintInput` surfaces what feed validators warn about and directories/readers penalize. - * Returns a list of human-readable warnings (empty = clean); it never throws and `serveFeed` never calls it, so it can't slow the serve path. Meant for tests/CI — `expect(lintInput(input, 'rss')).toEqual([])` — and for tightening a feed before shipping. + * Returns a list of human-readable warnings (empty = clean); it never throws and `serveFeed` never calls it, so it can't slow the serve path. Meant for tests/CI — `expect(lintInput(input, 'rss')).toEqual([])` — and for tightening a feed before shipping. Pass `{ ignore: [...] }` to silence individual rules by id. */ -export function lintInput(input: FeedInput, format: FeedFormat): string[] { +export function lintInput( + input: FeedInput, + format: FeedFormat, + lintOptions: LintOptions = {}, +): string[] { const { options, items } = input const warnings: string[] = [] + const ignored = new Set(lintOptions.ignore) + const report: Report = (rule, message) => { + if (!ignored.has(rule)) warnings.push(message) + } - lintFeed(options, format, warnings) + lintFeed(options, items.length, format, report) items.forEach((item, i) => { - lintItem(item, i, format, warnings) + lintItem(item, i, format, lintOptions.now ?? new Date(), report) }) + lintDuplicateIds(items, report) return warnings } -function lintFeed(options: FeedOptions, format: FeedFormat, warnings: string[]): void { +function lintFeed(options: FeedOptions, itemCount: number, format: FeedFormat, warn: Report): void { if (!options.description) { - warnings.push( + warn( + 'feed-description', format === 'rss' ? 'feed: no "description" — RSS requires ; an empty one is emitted' : 'feed: no "description" — readers show it as the feed subtitle/summary', ) } if (!options.language) { - warnings.push('feed: no "language" — readers and directories use it for filtering and display') + warn( + 'feed-language', + 'feed: no "language" — readers and directories use it for filtering and display', + ) } if (!options.image && !options.favicon) { - warnings.push('feed: no "image" or "favicon" — directories and readers display placeholder art') + warn( + 'feed-image', + 'feed: no "image" or "favicon" — directories and readers display placeholder art', + ) } // Atom's falls back to link, then to the request URL at serve time; the latter changes with the host, so the feed's identity isn't stable across environments. if (format === 'atom' && !options.id && !options.link && !options.feedUrl) { - warnings.push( + warn( + 'atom-feed-id', 'feed: no "id" (or "link"/"feedUrl") — Atom id falls back to the request URL, so the feed identity is unstable across hosts', ) } // RFC 4287 §4.1.1: an Atom feed SHOULD carry a rel="alternate" link to a human-readable page. if (format === 'atom' && !options.link) { - warnings.push( + warn( + 'atom-feed-link', 'feed: no "link" — Atom SHOULD have a rel="alternate" link to a human-readable page (RFC 4287 §4.1.1)', ) } // RFC 5005 §4: an archive page SHOULD carry rel="current" back to the always-up-to-date document. Only RSS/Atom emit fh:archive/rel="current" at all — JSON Feed has no mapping. if (format !== 'json' && options.paging?.archive && !options.paging?.current) { - warnings.push( + warn( + 'paging-archive-current', 'feed.paging: "archive" is set without "current" — RFC 5005 §4 recommends pointing archive pages at the current document', ) } @@ -60,26 +113,109 @@ function lintFeed(options: FeedOptions, format: FeedFormat, warnings: string[]): if (!p.category?.length) missing.push('category') if (p.explicit === undefined) missing.push('explicit') if (missing.length) { - warnings.push( + warn( + 'podcast-incomplete', `feed.podcast: no ${missing.map((f) => `"${f}"`).join('/')} — Apple Podcasts requires ${missing.join('/')} to list a show`, ) } } + if (itemCount > PAGING_SUGGESTION_ITEM_COUNT && !options.paging) { + warn( + 'item-count', + `feed: ${itemCount} items in one document — consider "paging" (see paginate()) so readers don't download the whole archive on every poll`, + ) + } } -function lintItem(item: FeedItem, i: number, format: FeedFormat, warnings: string[]): void { +function lintItem(item: FeedItem, i: number, format: FeedFormat, now: Date, warn: Report): void { if (!item.id) { - warnings.push( + warn( + 'item-id', `item[${i}]: no "id" — the ${format === 'atom' ? 'atom:id' : format === 'json' ? 'json id' : 'guid'} falls back to the link, which breaks readers if the URL changes`, ) } if (!item.published && !item.updated) { - warnings.push( + warn( + 'item-date', `item[${i}]: no "published"/"updated" date — readers sort undated items unpredictably`, ) } // A name-only author still surfaces (Atom/JSON author, RSS dc:creator); a missing one doesn't. if (!firstAuthor(item.author)) { - warnings.push(`item[${i}]: no "author" — readers can't attribute the item`) + warn('item-author', `item[${i}]: no "author" — readers can't attribute the item`) + } + + for (const field of ['published', 'updated'] as const) { + const date = item[field] + if (date && date.getTime() > now.getTime() + FUTURE_TOLERANCE_MS) { + warn( + 'future-date', + `item[${i}]: "${field}" is in the future (${date.toISOString()}) — usually a timezone mix-up`, + ) + } + } + + for (const field of ['content', 'description'] as const) { + const relative = relativeUrlsIn(item[field]) + if (relative.length) { + warn( + 'relative-url', + `item[${i}]: "${field}" has ${relative.length} relative URL(s), e.g. "${relative[0]}" — feed readers can't resolve them against your site; use absolute URLs`, + ) + } + } + + for (const enclosure of enclosureList(item.enclosure)) { + if (!enclosure.type) { + warn('enclosure', `item[${i}]: enclosure "${enclosure.url}" has no "type" (MIME type)`) + } + if (!enclosure.length) { + warn( + 'enclosure', + `item[${i}]: enclosure "${enclosure.url}" has no "length" — it is emitted as 0, and some podcast clients and validators reject that`, + ) + } + } + + if (item.title.length > LONG_TITLE_LENGTH) { + warn( + 'title', + `item[${i}]: "title" is ${item.title.length} characters — readers truncate long titles`, + ) + } + if (/<\/?[a-z][^>]*>/i.test(item.title)) { + warn( + 'title', + `item[${i}]: "title" contains HTML markup — titles are plain text and the tags would be escaped`, + ) + } +} + +function lintDuplicateIds(items: FeedItem[], warn: Report): void { + const seen = new Map() + items.forEach((item, i) => { + const key = item.id ?? item.link + if (!key) return + const first = seen.get(key) + if (first === undefined) seen.set(key, i) + else + warn( + 'duplicate-id', + `item[${i}]: same id/link as item[${first}] ("${key}") — readers will merge or drop one of them`, + ) + }) +} + +// Attribute values that are neither absolute (`scheme:`), protocol-relative, nor a fragment. +const URL_ATTRIBUTE = /\b(?:src|href|poster)\s*=\s*(["'])(.*?)\1/gi +const NOT_RELATIVE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i + +function relativeUrlsIn(html: string | undefined): string[] { + if (!html) return [] + const found: string[] = [] + for (const match of html.matchAll(URL_ATTRIBUTE)) { + const url = match[2].trim() + if (url && !NOT_RELATIVE.test(url)) found.push(url) } + return found }