#!/usr/bin/env bun

// The GUI extension SDK is learned from editor hovers and the guide, so both are checked. Fails, naming each file and

// line, when in `packages/gui-extensions/src/sdk`:

// - an exported declaration, an interface member, a field of an object type (an option, a result, a union member), or

// a member of an exported object such as `Store.global` has no doc comment;

// - a documented function or method leaves a parameter without `@param`, or names one it does not have.

// It also fails when a code block of the guide (`packages/gui-extensions/README.md`) marked `<!-- source: path -->` (a

// whole file of a shipping extension) or `<!-- source: path#name -->` (a top-level declaration or call named `name`,

// else the first nested match, with the comments directly above it) differs from that source, or when the

// guide or the package's AGENTS.md names a `ctx.<member>` no context declares.

// Usage: bun script/sdk-docs.ts

import path from "node:path"

import { Glob } from "bun"

import ts from "typescript"

const root = path.resolve(import.meta.dir, "..")

const pkg = path.join(root, "packages/gui-extensions")

const sdk = path.join(pkg, "src/sdk")

const problems: string[] = []

const counts = { declarations: 0, members: 0, parameters: 0, blocks: 0 }

const files = [...new Glob("**/*.{ts,tsx}").scanSync(sdk)]

.filter((file) => !/\.(test|typecheck)\.tsx?$/.test(file))

.toSorted()

.map((file) => path.join(sdk, file))

const sources = await Promise.all(files.map(async (file) => parse(file, await Bun.file(file).text())))

sources.forEach((source) => source.statements.forEach((statement) => checkStatement(source, statement)))

await checkGuide()

problems.forEach((problem) => console.log(problem))

console.log(

`sdk-docs: ${counts.declarations} declarations, ${counts.members} members and ${counts.parameters} parameters ` +

`documented in ${files.length} files; ${counts.blocks} guide blocks match their source; ${problems.length} problem(s)`,

)

process.exit(problems.length > 0 ? 1 : 0)

function checkStatement(source: ts.SourceFile, statement: ts.Statement) {

if (!exported(statement)) return

const name = describe(statement)

if (ts.isVariableStatement(statement)) {

documented(source, statement, name, "declarations")

statement.declarationList.declarations.forEach((declaration) => {

if (declaration.type) checkTypes(source, declaration.type, name)

if (declaration.initializer) checkInitializer(source, declaration.initializer, name)

})

return

}

if (name === undefined) return

documented(source, statement, name, "declarations")

if (ts.isFunctionDeclaration(statement)) return checkSignature(source, statement, name)

if (ts.isInterfaceDeclaration(statement)) return checkMembers(source, statement.members, name)

if (ts.isTypeAliasDeclaration(statement)) return checkTypes(source, statement.type, name)

if (ts.isEnumDeclaration(statement))

statement.members.forEach((member) =>

documented(source, member, `${name}.${member.name.getText(source)}`, "members"),

)

}

/** An exported const: the type arguments of its initializer, or each member of an object literal such as `Store`. */

function checkInitializer(source: ts.SourceFile, initializer: ts.Expression, owner: string) {

if (!ts.isObjectLiteralExpression(initializer)) return checkTypes(source, initializer, owner)

initializer.properties.forEach((property) => {

const name = `${owner}.${property.name?.getText(source) ?? "…"}`

documented(source, property, name, "members")

const value = ts.isPropertyAssignment(property) ? property.initializer : property

if (ts.isArrowFunction(value) || ts.isFunctionExpression(value) || ts.isMethodDeclaration(value))

checkSignature(source, value, name, property)

})

}

function checkMembers(source: ts.SourceFile, members: ts.NodeArray<ts.TypeElement>, owner: string) {

members.forEach((member) => {

if (ts.isIndexSignatureDeclaration(member)) return checkTypes(source, member.type, owner)

const name = `${owner}.${member.name?.getText(source) ?? "(call)"}`

documented(source, member, name, "members")

if (ts.isMethodSignature(member) || ts.isCallSignatureDeclaration(member))

return checkSignature(source, member, name)

if (ts.isPropertySignature(member) && member.type) checkTypes(source, member.type, name)

})

}

/** A function or method: a `@param` per parameter, and the object types of its parameters and result. */

function checkSignature(source: ts.SourceFile, signature: ts.SignatureDeclaration, name: string, host?: ts.Node) {

checkParameters(source, signature, name, host)

signature.parameters.forEach((parameter) => parameter.type && checkTypes(source, parameter.type, name))

if (signature.type) checkTypes(source, signature.type, name)

}

/**

* Every object type within a type: option objects, results and union members. A conditional type's `extends` clause is

* a pattern, not a shape anyone writes, and a function's body is implementation.

*/

function checkTypes(source: ts.SourceFile, node: ts.Node, owner: string) {

if (ts.isTypeLiteralNode(node)) return checkMembers(source, node.members, owner)

if (ts.isConditionalTypeNode(node))

return [node.checkType, node.trueType, node.falseType].forEach((type) => checkTypes(source, type, owner))

if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {

node.parameters.forEach((parameter) => parameter.type && checkTypes(source, parameter.type, owner))

if (node.type) checkTypes(source, node.type, owner)

return

}

ts.forEachChild(node, (child) => checkTypes(source, child, owner))

}

/** Each parameter has a `@param`, and no `@param` names a parameter the signature lacks. */

function checkParameters(source: ts.SourceFile, signature: ts.SignatureDeclaration, name: string, host?: ts.Node) {

const names = signature.parameters.map((parameter) => parameter.name.getText(source))

const tags = docs(host ?? signature).flatMap((doc) => (doc.tags ?? []).filter(ts.isJSDocParameterTag))

signature.parameters.forEach((parameter, index) => {

if (tags.some((tag) => tag.name.getText(source) === names[index])) return void counts.parameters++

report(source, parameter, `${name}: parameter \`${names[index]}\` has no @param`)

})

tags.forEach((tag) => {

if (!names.includes(tag.name.getText(source)))

report(source, tag, `${name}: @param \`${tag.name.getText(source)}\` names no parameter`)

})

}

function documented(source: ts.SourceFile, node: ts.Node, name: string, kind: "declarations" | "members") {

const described = docs(node).some((doc) => !!ts.getTextOfJSDocComment(doc.comment)?.trim())

if (described) return void counts[kind]++

report(source, node, `${name} has no doc comment`)

}

function docs(node: ts.Node) {

return ts.getJSDocCommentsAndTags(node).filter(ts.isJSDoc)

}

function exported(statement: ts.Statement) {

return (

ts.canHaveModifiers(statement) &&

!!ts.getModifiers(statement)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword)

)

}

/** The declared name, or undefined for a statement that declares nothing, such as `export * from`. */

function describe(statement: ts.Statement) {

if (ts.isVariableStatement(statement))

return statement.declarationList.declarations.map((declaration) => declaration.name.getText()).join(", ")

if (

ts.isFunctionDeclaration(statement) ||

ts.isClassDeclaration(statement) ||

ts.isInterfaceDeclaration(statement) ||

ts.isTypeAliasDeclaration(statement) ||

ts.isEnumDeclaration(statement)

)

return statement.name?.getText() ?? "default"

return undefined

}

function report(source: ts.SourceFile, node: ts.Node, message: string) {

const position = source.getLineAndCharacterOfPosition(node.getStart(source))

problems.push(`${relative(source.fileName)}:${position.line + 1}:${position.character + 1} ${message}`)

}

function relative(file: string) {

return path.relative(root, file).replaceAll(path.sep, "/")

}

/** The guide's marked code blocks match their source, and every `ctx.*` the guide and AGENTS.md name exists. */

async function checkGuide() {

const guide = path.join(pkg, "README.md")

const lines = (await read(guide)).split("\n")

const blocks = lines.flatMap((line, index) => {

const marker = /^<!-- source: ([^#\s]+)(?:#([\w$]+))? -->$/.exec(line.trim())

if (!marker?.[1]) return []

const fence = lines.findIndex((candidate, next) => next > index && candidate.startsWith("```"))

const close = lines.findIndex((candidate, next) => next > fence && candidate.trim() === "```")

const at = `${relative(guide)}:${index + 1}`

if (fence === -1 || close === -1 || lines.slice(index + 1, fence).some((between) => between.trim() !== "")) {

problems.push(`${at} the source marker is not followed by a code block`)

return []

}

return [{ at, file: path.join(pkg, marker[1]), name: marker[2], code: lines.slice(fence + 1, close) }]

})

await Promise.all(

blocks.map(async (block) => {

const label = `${relative(block.file)}${block.name ? `#${block.name}` : ""}`

const text = await Bun.file(block.file)

.text()

.catch(() => undefined)

if (text === undefined) return void problems.push(`${block.at} ${label}: no such file`)

const expected = excerpt(block.file, text.replaceAll("\r\n", "\n"), block.name)

if (!expected) return void problems.push(`${block.at} ${label}: nothing by that name`)

const row = Array.from({ length: Math.max(expected.length, block.code.length) }, (_, row) => row).find(

(row) => expected[row] !== block.code[row],

)

if (row === undefined) return void counts.blocks++

problems.push(`${block.at} the code block differs from ${label} at its line ${row + 1}`)

}),

)

const members = contextMembers()

await Promise.all(

[guide, path.join(pkg, "AGENTS.md")].map(async (doc) =>

(await read(doc)).split("\n").forEach((line, index) =>

[...line.matchAll(/\bctx\.([A-Za-z]+)/g)].forEach((match) => {

if (match[1] && !members.has(match[1]))

problems.push(`${relative(doc)}:${index + 1} \`ctx.${match[1]}\` is not a context member`)

}),

),

),

)

}

async function read(file: string) {

return (await Bun.file(file).text()).replaceAll("\r\n", "\n")

}

/**

* The file's lines, or, for a name, the lines of its top-level match (else the first nested match), with the comment

* lines directly above it, dedented.

*/

function excerpt(file: string, text: string, name: string | undefined) {

const lines = text.replace(/\n$/, "").split("\n")

if (!name) return lines

const source = parse(file, text)

const node = named(source, name)

if (!node) return undefined

const first = source.getLineAndCharacterOfPosition(node.getStart(source)).line

const last = source.getLineAndCharacterOfPosition(node.getEnd()).line

const above = lines.slice(0, first).findLastIndex((line) => !/^\s*(\/\/|\/\*|\*)/.test(line)) + 1

const picked = lines.slice(above, last + 1)

const indent = Math.min(...picked.filter((line) => line.trim()).map((line) => /^\s*/.exec(line)?.[0].length ?? 0))

return picked.map((line) => line.slice(indent))

}

/** Top-level matches win; otherwise find the first nested declaration, property or call in source order. */

function named(node: ts.Node, name: string): ts.Node | undefined {

if (ts.isSourceFile(node)) {

const top = node.statements.find((statement) => matches(statement, name))

if (top) return top

}

if (matches(node, name)) return node

return ts.forEachChild(node, (child) => named(child, name))

}

function matches(node: ts.Node, name: string) {

if (ts.isVariableStatement(node)) {

return node.declarationList.declarations.some((declaration) => declaration.name.getText() === name)

}

if (

(ts.isFunctionDeclaration(node) ||

ts.isClassDeclaration(node) ||

ts.isInterfaceDeclaration(node) ||

ts.isTypeAliasDeclaration(node) ||

ts.isPropertyAssignment(node) ||

ts.isMethodDeclaration(node)) &&

node.name?.getText() === name

)

return true

if (

ts.isExpressionStatement(node) &&

ts.isCallExpression(node.expression) &&

node.expression.expression.getText() === name

)

return true

return false

}

function parse(file: string, text: string) {

return ts.createSourceFile(

file,

text,

ts.ScriptTarget.Latest,

true,

file.endsWith(".tsx") ? ts.ScriptKind.TSX : ts.ScriptKind.TS,

)

}

/** Every member a window or main context exposes: `BaseContext`, `Context`, `SetupContext` and `MainContext`. */

function contextMembers() {

const names = new Set(["BaseContext", "Context", "SetupContext", "MainContext"])

return new Set(

sources.flatMap((source) =>

source.statements.flatMap((statement) =>

ts.isInterfaceDeclaration(statement) && names.has(statement.name.text)

? statement.members.flatMap((member) => (member.name ? [member.name.getText(source)] : []))

: [],

),

),

)

}