Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -125,8 +125,10 @@ What each rule reports and why is in [`RULES.md`](RULES.md). Report false positi

Some rules come from the Effect rules of [`dmmulroy/anti-slop`](https://github.com/dmmulroy/anti-slop), MIT-licensed: see [`LICENSE.anti-slop`](LICENSE.anti-slop).

- Imported: [`anti-slop-no-manual-effect-error-tag`](RULES.md#anti-slop-no-manual-effect-error-tag), [`anti-slop-no-service-constructor-imports`](RULES.md#anti-slop-no-service-constructor-imports), [`anti-slop-prefer-effect-match`](RULES.md#anti-slop-prefer-effect-match).
- Superseded: `no-manual-tag-comparison` by [`no-manual-discriminant-comparison`](RULES.md#no-manual-discriminant-comparison), `no-manual-tagged-construction` by [`no-manual-discriminant-construction`](RULES.md#no-manual-discriminant-construction).
| Status | Rules |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Imported | [`anti-slop-no-manual-effect-error-tag`](RULES.md#anti-slop-no-manual-effect-error-tag), [`anti-slop-no-service-constructor-imports`](RULES.md#anti-slop-no-service-constructor-imports), [`anti-slop-prefer-effect-match`](RULES.md#anti-slop-prefer-effect-match) |
| Superseded | `no-manual-tag-comparison` → [`no-manual-discriminant-comparison`](RULES.md#no-manual-discriminant-comparison), `no-manual-tagged-construction` → [`no-manual-discriminant-construction`](RULES.md#no-manual-discriminant-construction) |

## Default configuration

Expand Down
9 changes: 5 additions & 4 deletions website/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -3,21 +3,23 @@ import starlight from "@astrojs/starlight"
import { defineConfig } from "astro/config"

import { publishedSite } from "./src/site-content/publishedSite.ts"
import { rulesOverviewId } from "./src/site-content/readmeMdSource.ts"
import { readSiteSources } from "./src/site-content/readSiteSources.ts"
import { sitePages } from "./src/site-content/sitePages.ts"

// Starlight's autogenerated sidebar needs entries backed by files, which loader pages are not
const pages = sitePages(await readSiteSources(new URL(".", import.meta.url)), publishedSite)
const rulePages = pages.filter((page) => page.kind === "rule")
const guidePages = pages.filter((page) => page.kind === "guide" && page.id !== "rules-overview")
const referencePages = pages.filter((page) => page.kind === "reference" && page.id !== "rules")
const guidePages = pages.filter((page) => page.kind === "guide" && page.id !== rulesOverviewId)
const referencePages = pages.filter((page) => page.kind === "reference")

export default defineConfig({
site: "https://doubleloop-io.github.io",
base: publishedSite.base,
integrations: [
starlight({
title: "oxlint-plugin-effect",
tableOfContents: false,
social: [
{
icon: "github",
Expand Down Expand Up @@ -47,8 +49,7 @@ export default defineConfig({
{
label: "Rules",
items: [
{ slug: "rules-overview" },
{ slug: "rules" },
{ slug: rulesOverviewId },
...Object.entries(Object.groupBy(rulePages, ({ group }) => group)).map(
([group, groupPages = []]) => ({
label: group,
Expand Down
10 changes: 7 additions & 3 deletions website/src/site-content/readmeMdAlignment.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ const expectedHref = (href: string) => {
if (/^https?:/u.test(href)) return href
const link = /^(?<file>[\w.-]+)?(?:#(?<anchor>[\w-]+))?$/u.exec(href)?.groups
if (link?.file === "RULES.md") {
return `${base}/${link.anchor === undefined ? "rules/" : expectedRulesMdRoute(link.anchor)}`
return `${base}/${link.anchor === undefined ? "rules-overview/" : expectedRulesMdRoute(link.anchor)}`
}
if (link?.file !== undefined) return `${repositoryUrl}/blob/main/${href}`
return `${base}/${sectionRoutes.get(link?.anchor ?? "") ?? "not-a-readme-section/"}`
Expand All @@ -62,8 +62,12 @@ test("the real README introduction is the landing page with its text, links poin

const landing = pages.find(({ kind }) => kind === "landing")

assert.equal(landing?.title, title.replace(/^# /u, ""))
assert.equal(pageText(landing?.body ?? ""), sourceText(sourceSection(title)))
const [tagline, ...rest] = sourceText(sourceSection(title)).split("\n\n")
assert.ok(landing?.kind === "landing")
assert.equal(landing.title, title.replace(/^# /u, ""))
assert.equal(`${landing.scope ?? ""}${landing.name}`, landing.title)
assert.equal(landing.tagline, tagline)
assert.equal(pageText(landing.body), rest.join("\n\n"))
})

for (const heading of publishedHeadings) {
Expand Down
10 changes: 10 additions & 0 deletions website/src/site-content/readmeMdSource.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -63,3 +63,13 @@ test("the Development section and its subsections are on no page", () => {
assert.ok(!pages.some(({ id }) => id === "development"))
assert.ok(!pages.some(({ body }) => body.includes("pnpm format") || body.includes("Releasing")))
})

test("an unscoped package name is the whole landing title, and an introduction of one paragraph leaves an empty body", () => {
const page = pageById(readmeMarkdown(), "index")

assert.ok(page?.kind === "landing")
assert.equal(page.scope, undefined)
assert.equal(page.name, "the-plugin")
assert.equal(page.tagline, "A plugin.")
assert.equal(page.body, "")
})
29 changes: 18 additions & 11 deletions website/src/site-content/readmeMdSource.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { headingAnchor } from "./internalLinks.ts"
import { markdownLines } from "./markdownLines.ts"
import type { SourcePage } from "./sitePages.ts"
import type { SitePage, SourcePage } from "./sitePages.ts"

type Section = { level: "#" | "##"; heading: string; subheadings: string[]; lines: string[] }

Expand All @@ -12,17 +12,17 @@ const subsectionHeading = /^### (?<title>.+)$/u
// Addressed to the plugin maintainers, not to its users
export const maintainerSections = new Set(["Development"])

// `rules` is the rules index from RULES.md
export const renamedSections = new Map([
["Rules", { id: "rules-overview", title: "Rules overview" }],
])
export const rulesOverviewId = "rules-overview"

// `rules/` is the parent route of the rule pages
export const renamedSections = new Map([["Rules", { id: rulesOverviewId, title: "Rules overview" }]])

const guidePage = (heading: string) =>
renamedSections.get(heading) ?? { id: headingAnchor(heading), title: heading }

const landingActions = [
{ text: "Installation", link: "#installation" },
{ text: "Rules index", link: "RULES.md" },
{ text: "Rules overview", link: "RULES.md" },
]

export const readmeMdSource = (markdown: string) => {
Expand All @@ -33,21 +33,28 @@ export const readmeMdSource = (markdown: string) => {
return { sourcePages, routes: linkRoutes(readmeSections) }
}

const packageName = /^(?<scope>@[^/]+\/)?(?<name>.+)$/u

const readmeMdPage = ({ level, heading, lines }: Section): SourcePage => {
const body = `${lines.join("\n").trim()}\n`
return level === "#"
? {
page: { kind: "landing", id: "index", title: heading, body, actions: landingActions },
file,
location: "introduction",
}
? { page: landingPage(heading, body), file, location: "introduction" }
: {
page: { kind: "guide", ...guidePage(heading), body },
file,
location: `section \`${heading}\``,
}
}

// The heading is the package name, split so the scope can sit above the name;
// the first paragraph is the tagline under it, so the body starts after it
const landingPage = (heading: string, introduction: string): SitePage => {
const { scope, name = heading } = packageName.exec(heading)?.groups ?? {}
const [tagline = "", ...rest] = introduction.split("\n\n")
const body = rest.length === 0 ? "" : `${rest.join("\n\n").trim()}\n`
return { kind: "landing", id: "index", title: heading, scope, name, tagline: tagline.trim(), body, actions: landingActions }
}

const linkRoutes = (readmeSections: Section[]) =>
new Map(
readmeSections
Expand Down
2 changes: 1 addition & 1 deletion website/src/site-content/realRulesMd.ts
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ const firstRuleOfGroup = new Map(
)

const referencePageRoutes = new Map([
["rules-index", "rules/"],
["rules-index", "rules-overview/"],
["common-limits", "common-limits/"],
["shared-settings", "shared-settings/"],
])
Expand Down
2 changes: 1 addition & 1 deletion website/src/site-content/rulesMdAlignment.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ test("every block of a real RULES.md rule section is on its page, links pointing
}
})

for (const heading of ["Rules index", "Common limits", "Shared settings"]) {
for (const heading of ["Common limits", "Shared settings"]) {
test(`${heading} is a page with the text of its real RULES.md section, links pointing to the page of their anchor`, () => {
const source = sourceSection(`## ${heading}`).replace(`## ${heading}\n`, "").trim()

Expand Down
11 changes: 3 additions & 8 deletions website/src/site-content/rulesMdSource.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,19 +174,14 @@ test("Shared settings and Common limits each become a page with the body of thei
])
})

test("the rules index becomes the page at the root of the rules", () => {
test("the rules index has no page, as the rules overview lists every rule", () => {
const markdown = [
"# Rules\n",
"## Rules index\n\n| Group | Rule |\n| --- | --- |\n\nAll at `warn`.\n",
group("Error channel", ruleSection("no-effect-promise")),
].join("\n")

const page = pageById(markdown, "rules")
const pages = rulesMdSource(markdown).sourcePages

assert.deepEqual(page, {
kind: "reference",
id: "rules",
title: "Rules index",
body: "| Group | Rule |\n| --- | --- |\n\nAll at `warn`.\n",
})
assert.ok(pages.every(({ page }) => page.title !== "Rules index"))
})
8 changes: 6 additions & 2 deletions website/src/site-content/rulesMdSource.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { headingAnchor } from "./internalLinks.ts"
import { isCodeFence, markdownLines } from "./markdownLines.ts"
import { rulesOverviewId } from "./readmeMdSource.ts"
import type { SitePage, SourcePage } from "./sitePages.ts"

type Section = {
Expand All @@ -13,7 +14,6 @@ type RuleSection = Section & { name: string }
const file = "RULES.md"

const referencePageIds = new Map([
["Rules index", "rules"],
["Common limits", "common-limits"],
["Shared settings", "shared-settings"],
])
Expand Down Expand Up @@ -50,10 +50,14 @@ const rulesMdPage = (section: Section): RulesMdPage[] => {
return [{ page, file, heading, location: `section \`${heading}\`` }]
}

// The README Rules section lists every rule, so it stands in for the rules index, which has no page
const rulesIndexRoute = `${rulesOverviewId}/`

// A group has no page: its anchor leads to its first rule, as its heading does in RULES.md
const linkRoutes = (allSections: Section[], sourcePages: RulesMdPage[]) =>
new Map([
[file, "rules/"],
[file, rulesIndexRoute],
[`${file}#rules-index`, rulesIndexRoute],
...allSections.flatMap(({ heading }): [string, string][] => {
const target =
sourcePages.find((source) => source.heading === heading)?.page ??
Expand Down
25 changes: 14 additions & 11 deletions website/src/site-content/sitePages.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -49,23 +49,24 @@ test("a link to Shared settings or Common limits points to its page", () => {

test("a link to a group points to the first rule of that group", () => {
const markdown = rulesMarkdown(
"## Shared settings\n\nUsed by [Error channel](#error-channel).\n",
group("Error channel", ruleSection("no-effect-promise"), ruleSection("try-object-form")),
).replace("| --- | --- |\n", "| --- | --- |\n| [Error channel](#error-channel) | |\n")
)

const page = pageById({ rulesMd: markdown }, "rules")
const page = pageById({ rulesMd: markdown }, "shared-settings")

assert.ok(page?.body.includes("[Error channel](/site/rules/no-effect-promise/)"))
})

test("a link to the rules index points to the rules index page", () => {
test("a link to the rules index points to the rules overview", () => {
const markdown = rulesMarkdown(
"## Shared settings\n\nListed in the [rules index](#rules-index).\n",
group("Error channel", ruleSection("no-effect-promise")),
)

const page = pageById({ rulesMd: markdown }, "shared-settings")

assert.ok(page?.body.includes("[rules index](/site/rules/)"))
assert.ok(page?.body.includes("[rules index](/site/rules-overview/)"))
})

test("a RULES.md link to a section that has no site page fails, naming the link and the rule", () => {
Expand All @@ -82,7 +83,7 @@ test("a RULES.md link to a section that has no site page fails, naming the link
})
})

test("the landing page links to installation and to the rules index", () => {
test("the landing page shows the package scope above its name, the first paragraph as tagline, and links to installation and the rules overview", () => {
const readmeMd = [
"# @owner/the-plugin\n\nAn oxlint plugin.\n\nIt complements [tsgo](#alongside-effecttsgo).\n",
"## Installation\n\n```bash\npnpm add -D the-plugin\n```\n",
Expand All @@ -95,10 +96,13 @@ test("the landing page links to installation and to the rules index", () => {
kind: "landing",
id: "index",
title: "@owner/the-plugin",
body: "An oxlint plugin.\n\nIt complements [tsgo](/site/configuration/#alongside-effecttsgo).\n",
scope: "@owner/",
name: "the-plugin",
tagline: "An oxlint plugin.",
body: "It complements [tsgo](/site/configuration/#alongside-effecttsgo).\n",
actions: [
{ text: "Installation", link: "/site/installation/" },
{ text: "Rules index", link: "/site/rules/" },
{ text: "Rules overview", link: "/site/rules-overview/" },
],
})
})
Expand All @@ -117,7 +121,7 @@ test("a link to a README section points to its page, a link to a subsection to i
)
})

test("a link to the Rules section points to the rules overview, apart from the rules index page", () => {
test("a link to the Rules section points to the rules overview", () => {
const readmeMd = readmeMarkdown(
"## Rules\n\n| Topic | Rules |\n\n### Absorbed from anti-slop\n\nSome rules.\n",
"## Versioning\n\nSee the [overview](#rules) and [provenance](#absorbed-from-anti-slop).\n",
Expand All @@ -129,10 +133,9 @@ test("a link to the Rules section points to the rules overview, apart from the r
pages.find(({ id }) => id === "versioning")?.body,
"See the [overview](/site/rules-overview/) and [provenance](/site/rules-overview/#absorbed-from-anti-slop).\n",
)
assert.equal(pages.find(({ id }) => id === "rules")?.title, "Rules index")
})

test("a link from the README to RULES.md points to the rules index, a link to a rule in it to the rule page", () => {
test("a link from the README to RULES.md points to the rules overview, a link to a rule in it to the rule page", () => {
const readmeMd = readmeMarkdown(
"## Versioning\n\nIn [`RULES.md`](RULES.md), such as [this](RULES.md#no-effect-promise).\n",
)
Expand All @@ -141,7 +144,7 @@ test("a link from the README to RULES.md points to the rules index, a link to a

assert.equal(
page?.body,
"In [`RULES.md`](/site/rules/), such as [this](/site/rules/no-effect-promise/).\n",
"In [`RULES.md`](/site/rules-overview/), such as [this](/site/rules/no-effect-promise/).\n",
)
})

Expand Down
11 changes: 10 additions & 1 deletion website/src/site-content/sitePages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,16 @@ export type SitePage =
| { kind: "rule"; id: string; title: string; group: string; body: string }
| { kind: "reference"; id: string; title: string; body: string }
| { kind: "guide"; id: string; title: string; body: string }
| { kind: "landing"; id: string; title: string; body: string; actions: LandingAction[] }
| {
kind: "landing"
id: string
title: string
scope: string | undefined
name: string
tagline: string
body: string
actions: LandingAction[]
}

type LandingAction = { text: string; link: string }

Expand Down
16 changes: 14 additions & 2 deletions website/src/site-content/sitePagesLoader.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,18 @@ import type { Loader } from "astro/loaders"

import { publishedSite } from "./publishedSite.ts"
import { readSiteSources } from "./readSiteSources.ts"
import { sitePages } from "./sitePages.ts"
import { type SitePage, sitePages } from "./sitePages.ts"

export const sitePagesLoader = (): Loader => ({
name: "site-pages",
load: async ({ config, store, parseData, renderMarkdown }) => {
const sources = await readSiteSources(config.root)
store.clear()
for (const page of sitePages(sources, { ...publishedSite, base: config.base })) {
const hero = page.kind === "landing" ? { actions: page.actions } : undefined
const hero =
page.kind === "landing"
? { title: heroTitle(page), tagline: escapeHtml(page.tagline), actions: page.actions }
: undefined
const data = await parseData({ id: page.id, data: { title: page.title, hero } })
store.set({
id: page.id,
Expand All @@ -21,3 +24,12 @@ export const sitePagesLoader = (): Loader => ({
}
},
})

type LandingPage = Extract<SitePage, { kind: "landing" }>

// Starlight renders the hero title and tagline as HTML
const heroTitle = ({ scope, name }: LandingPage) =>
[scope === undefined ? "" : `<span class="hero-scope">${escapeHtml(scope)}</span>`, escapeHtml(name)].join("")

const escapeHtml = (text: string) =>
text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;")
Loading
Loading