mirror of
https://github.com/Effect-TS/effect.git
synced 2026-11-20 01:53:23 +08:00
413 lines
12 KiB
JavaScript
413 lines
12 KiB
JavaScript
#!/usr/bin/env node
|
|
|
|
// Collects exported, non-internal JSDoc descriptions into review chunks.
|
|
// This script deliberately does not judge quality; human/agent reviewers read
|
|
// the chunks and write only the descriptions they flag into the backlog.
|
|
|
|
import * as Fs from "node:fs"
|
|
import * as Path from "node:path"
|
|
import * as Process from "node:process"
|
|
import ts from "typescript"
|
|
|
|
const cwd = Process.cwd()
|
|
const args = Process.argv.slice(2)
|
|
const outputDirectory = getArg("--output-dir") ?? "reports/jsdoc-descriptions"
|
|
const chunkSize = Number(getArg("--chunk-size") ?? 120)
|
|
|
|
const ignoredBasenames = new Set(["Generated.ts", "index.ts"])
|
|
const declarationKinds = new Set([
|
|
ts.SyntaxKind.ClassDeclaration,
|
|
ts.SyntaxKind.EnumDeclaration,
|
|
ts.SyntaxKind.FunctionDeclaration,
|
|
ts.SyntaxKind.InterfaceDeclaration,
|
|
ts.SyntaxKind.ModuleDeclaration,
|
|
ts.SyntaxKind.TypeAliasDeclaration,
|
|
ts.SyntaxKind.VariableStatement
|
|
])
|
|
|
|
const files = listSourceFiles(Path.join(cwd, "packages"))
|
|
const entries = []
|
|
let skippedInternal = 0
|
|
|
|
for (const file of files) {
|
|
const source = Fs.readFileSync(file, "utf8")
|
|
const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true)
|
|
|
|
visitSourceFile(sourceFile, (node, exportPath) => {
|
|
const jsdoc = getLeadingJSDoc(node)
|
|
if (jsdoc === undefined) {
|
|
return
|
|
}
|
|
|
|
const parsed = parseJSDoc(sourceFile, jsdoc)
|
|
if (parsed.tags.includes("internal")) {
|
|
skippedInternal++
|
|
return
|
|
}
|
|
|
|
const declarations = getExportedDeclarations(sourceFile, node)
|
|
for (const declaration of declarations) {
|
|
const position = sourceFile.getLineAndCharacterOfPosition(declaration.position)
|
|
entries.push({
|
|
packageName: getPackageName(file),
|
|
moduleName: getModuleName(file),
|
|
file: normalizePath(Path.relative(cwd, file)),
|
|
line: position.line + 1,
|
|
apiName: [...exportPath, declaration.name].join("."),
|
|
apiKind: declaration.kind,
|
|
description: parsed.description,
|
|
tags: parsed.tags
|
|
})
|
|
}
|
|
})
|
|
}
|
|
|
|
entries.sort((a, b) =>
|
|
a.packageName.localeCompare(b.packageName) ||
|
|
a.moduleName.localeCompare(b.moduleName) ||
|
|
a.line - b.line ||
|
|
a.apiName.localeCompare(b.apiName)
|
|
)
|
|
|
|
writeInventory(entries, {
|
|
files: files.length,
|
|
skippedInternal
|
|
})
|
|
|
|
console.log(`Collected ${entries.length} exported non-internal JSDoc declaration(s) from ${files.length} file(s).`)
|
|
console.log(`Skipped ${skippedInternal} @internal JSDoc declaration(s).`)
|
|
console.log(`Wrote inventory and review chunks to ${outputDirectory}.`)
|
|
|
|
function getArg(name) {
|
|
const direct = args.find((arg) => arg.startsWith(`${name}=`))
|
|
if (direct !== undefined) {
|
|
return direct.slice(name.length + 1)
|
|
}
|
|
const index = args.indexOf(name)
|
|
return index === -1 ? undefined : args[index + 1]
|
|
}
|
|
|
|
function listSourceFiles(root) {
|
|
const out = []
|
|
|
|
function visit(directory) {
|
|
for (const entry of Fs.readdirSync(directory, { withFileTypes: true })) {
|
|
const fullPath = Path.join(directory, entry.name)
|
|
if (entry.isDirectory()) {
|
|
if (
|
|
entry.name === "node_modules" ||
|
|
entry.name === "dist" ||
|
|
entry.name === "docs" ||
|
|
entry.name === "test" ||
|
|
entry.name === "typetest"
|
|
) {
|
|
continue
|
|
}
|
|
visit(fullPath)
|
|
continue
|
|
}
|
|
|
|
if (!entry.isFile() || !entry.name.endsWith(".ts")) {
|
|
continue
|
|
}
|
|
if (
|
|
entry.name.endsWith(".d.ts") ||
|
|
entry.name.endsWith(".test.ts") ||
|
|
entry.name.endsWith(".tst.ts") ||
|
|
ignoredBasenames.has(entry.name)
|
|
) {
|
|
continue
|
|
}
|
|
if (!normalizePath(fullPath).includes("/src/")) {
|
|
continue
|
|
}
|
|
out.push(fullPath)
|
|
}
|
|
}
|
|
|
|
visit(root)
|
|
return out.sort((a, b) => normalizePath(a).localeCompare(normalizePath(b)))
|
|
}
|
|
|
|
function visitSourceFile(sourceFile, onExport) {
|
|
function visit(node, exportPath, exportedNamespaceDepth) {
|
|
if (!declarationKinds.has(node.kind)) {
|
|
ts.forEachChild(node, (child) => visit(child, exportPath, exportedNamespaceDepth))
|
|
return
|
|
}
|
|
|
|
const isExported = hasModifier(node, ts.SyntaxKind.ExportKeyword) || exportedNamespaceDepth > 0
|
|
|
|
if (isExported) {
|
|
onExport(node, exportPath)
|
|
}
|
|
|
|
if (ts.isModuleDeclaration(node) && isExported && node.name !== undefined) {
|
|
const namespaceName = node.name.getText(sourceFile).replaceAll("\"", "")
|
|
if (node.body !== undefined) {
|
|
ts.forEachChild(node.body, (child) => visit(child, [...exportPath, namespaceName], exportedNamespaceDepth + 1))
|
|
}
|
|
return
|
|
}
|
|
|
|
ts.forEachChild(node, (child) => visit(child, exportPath, exportedNamespaceDepth))
|
|
}
|
|
|
|
ts.forEachChild(sourceFile, (node) => visit(node, [], 0))
|
|
}
|
|
|
|
function hasModifier(node, kind) {
|
|
return node.modifiers?.some((modifier) => modifier.kind === kind) === true
|
|
}
|
|
|
|
function getLeadingJSDoc(node) {
|
|
const jsdocs = node.jsDoc
|
|
if (jsdocs === undefined || jsdocs.length === 0) {
|
|
return undefined
|
|
}
|
|
return jsdocs[jsdocs.length - 1]
|
|
}
|
|
|
|
function getExportedDeclarations(sourceFile, node) {
|
|
if (ts.isVariableStatement(node)) {
|
|
return node.declarationList.declarations
|
|
.filter((declaration) => ts.isIdentifier(declaration.name))
|
|
.map((declaration) => ({
|
|
name: declaration.name.text,
|
|
kind: "value",
|
|
position: declaration.name.getStart(sourceFile)
|
|
}))
|
|
}
|
|
|
|
if (
|
|
(ts.isFunctionDeclaration(node) ||
|
|
ts.isClassDeclaration(node) ||
|
|
ts.isInterfaceDeclaration(node) ||
|
|
ts.isTypeAliasDeclaration(node) ||
|
|
ts.isEnumDeclaration(node) ||
|
|
ts.isModuleDeclaration(node)) &&
|
|
node.name !== undefined
|
|
) {
|
|
return [{
|
|
name: node.name.getText(sourceFile),
|
|
kind: getApiKind(node),
|
|
position: node.name.getStart(sourceFile)
|
|
}]
|
|
}
|
|
|
|
return []
|
|
}
|
|
|
|
function getApiKind(node) {
|
|
if (ts.isFunctionDeclaration(node)) {
|
|
return "value"
|
|
}
|
|
if (ts.isClassDeclaration(node)) {
|
|
return "class"
|
|
}
|
|
if (ts.isInterfaceDeclaration(node)) {
|
|
return "interface"
|
|
}
|
|
if (ts.isTypeAliasDeclaration(node)) {
|
|
return "type"
|
|
}
|
|
if (ts.isEnumDeclaration(node)) {
|
|
return "enum"
|
|
}
|
|
if (ts.isModuleDeclaration(node)) {
|
|
return "namespace"
|
|
}
|
|
return "value"
|
|
}
|
|
|
|
function parseJSDoc(sourceFile, jsdoc) {
|
|
const raw = sourceFile.text.slice(jsdoc.pos, jsdoc.end)
|
|
const lines = raw
|
|
.replace(/^\/\*\*/, "")
|
|
.replace(/\*\/$/, "")
|
|
.split(/\r\n|\r|\n/)
|
|
.map((line) => line.replace(/^\s*\* ?/, "").trimEnd())
|
|
|
|
const tags = []
|
|
let inFence = false
|
|
let inExample = false
|
|
const descriptionLines = []
|
|
|
|
for (const line of lines) {
|
|
const trimmed = line.trim()
|
|
if (trimmed.startsWith("```")) {
|
|
inFence = !inFence
|
|
continue
|
|
}
|
|
if (inFence) {
|
|
continue
|
|
}
|
|
|
|
const tag = trimmed.match(/^@([A-Za-z][\w-]*)/)
|
|
if (tag !== null) {
|
|
tags.push(tag[1])
|
|
if (tag[1] === "example") {
|
|
inExample = true
|
|
}
|
|
continue
|
|
}
|
|
|
|
if (/^\*\*Examples?\*\*/i.test(trimmed) || /^#{2,}\s+Examples?/i.test(trimmed)) {
|
|
inExample = true
|
|
continue
|
|
}
|
|
|
|
if (inExample) {
|
|
continue
|
|
}
|
|
|
|
if (trimmed !== "") {
|
|
descriptionLines.push(trimmed)
|
|
}
|
|
}
|
|
|
|
return {
|
|
tags: Array.from(new Set(tags)),
|
|
description: normalizeDescription(descriptionLines.join("\n"))
|
|
}
|
|
}
|
|
|
|
function normalizeDescription(description) {
|
|
return description
|
|
.replaceAll(/\{@link\s+([^}\s]+)(?:\s+[^}]*)?\}/g, "$1")
|
|
.replaceAll(/[ \t]+\n/g, "\n")
|
|
.replaceAll(/\n{3,}/g, "\n\n")
|
|
.trim()
|
|
}
|
|
|
|
function writeInventory(entries, summary) {
|
|
const output = Path.join(cwd, outputDirectory)
|
|
const chunksDirectory = Path.join(output, "chunks")
|
|
const findingsDirectory = Path.join(output, "findings")
|
|
|
|
Fs.mkdirSync(output, { recursive: true })
|
|
Fs.rmSync(chunksDirectory, { recursive: true, force: true })
|
|
Fs.mkdirSync(chunksDirectory, { recursive: true })
|
|
Fs.mkdirSync(findingsDirectory, { recursive: true })
|
|
|
|
Fs.writeFileSync(Path.join(output, "inventory.json"), `${JSON.stringify({
|
|
generatedBy: "node scripts/audit-jsdoc-descriptions.mjs",
|
|
scannedFiles: summary.files,
|
|
skippedInternal: summary.skippedInternal,
|
|
entries
|
|
}, null, 2)}\n`)
|
|
|
|
const chunks = []
|
|
for (let start = 0; start < entries.length; start += chunkSize) {
|
|
const chunkEntries = entries.slice(start, start + chunkSize)
|
|
const chunkNumber = String(chunks.length + 1).padStart(3, "0")
|
|
const chunkPath = Path.join(chunksDirectory, `chunk-${chunkNumber}.md`)
|
|
const chunk = {
|
|
number: chunks.length + 1,
|
|
path: normalizePath(Path.relative(cwd, chunkPath)),
|
|
start: start + 1,
|
|
end: start + chunkEntries.length,
|
|
count: chunkEntries.length
|
|
}
|
|
chunks.push(chunk)
|
|
Fs.writeFileSync(chunkPath, renderChunk(chunk, chunkEntries))
|
|
}
|
|
|
|
const backlogPath = Path.join(output, "review-needed.md")
|
|
if (!Fs.existsSync(backlogPath)) {
|
|
Fs.writeFileSync(backlogPath, renderBacklogSkeleton(entries, chunks, summary))
|
|
}
|
|
}
|
|
|
|
function renderBacklogSkeleton(entries, chunks, summary) {
|
|
return [
|
|
"# JSDoc Description Review Needed",
|
|
"",
|
|
"Generated by `node scripts/audit-jsdoc-descriptions.mjs`.",
|
|
"",
|
|
"This backlog is intentionally empty until reviewers judge the inventory chunks.",
|
|
"The script only detects exported declarations with leading JSDoc blocks that are not tagged `@internal`; it does not decide whether a description is good.",
|
|
"",
|
|
"## Summary",
|
|
"",
|
|
`- Source files scanned: ${summary.files}`,
|
|
`- Exported non-internal JSDoc declarations collected: ${entries.length}`,
|
|
`- @internal JSDoc declarations skipped: ${summary.skippedInternal}`,
|
|
`- Review chunks: ${chunks.length}`,
|
|
"- Review-needed entries remaining: 0",
|
|
"",
|
|
"## Review Chunks",
|
|
"",
|
|
...chunks.map((chunk) => `- [${Path.basename(chunk.path, ".md")}](${chunk.path}) (${chunk.count} entries, ${chunk.start}-${chunk.end})`),
|
|
"",
|
|
"## Entries",
|
|
"",
|
|
"No reviewed findings have been merged yet.",
|
|
""
|
|
].join("\n")
|
|
}
|
|
|
|
function renderChunk(chunk, entries) {
|
|
const lines = [
|
|
`# JSDoc Description Inventory ${String(chunk.number).padStart(3, "0")}`,
|
|
"",
|
|
"This file is reviewer input, not a backlog. Judge each description manually.",
|
|
"Only copy flagged descriptions into `reports/jsdoc-descriptions/review-needed.md` or a worker findings file.",
|
|
"",
|
|
"For each flagged entry, record: severity, issue labels, reason, current description, and suggested replacement.",
|
|
"",
|
|
`Entries: ${chunk.start}-${chunk.end}`,
|
|
""
|
|
]
|
|
|
|
let currentPackage = ""
|
|
let currentModule = ""
|
|
|
|
for (const entry of entries) {
|
|
if (entry.packageName !== currentPackage) {
|
|
currentPackage = entry.packageName
|
|
currentModule = ""
|
|
lines.push("", `## ${entry.packageName}`)
|
|
}
|
|
if (entry.moduleName !== currentModule) {
|
|
currentModule = entry.moduleName
|
|
lines.push("", `### ${entry.moduleName}`)
|
|
}
|
|
|
|
lines.push(
|
|
"",
|
|
`#### ${entry.apiName}`,
|
|
"",
|
|
`- File: \`${entry.file}:${entry.line}\``,
|
|
`- API kind: \`${entry.apiKind}\``,
|
|
`- Tags: ${entry.tags.length === 0 ? "(none)" : entry.tags.map((tag) => `\`${tag}\``).join(", ")}`,
|
|
"- Current description:",
|
|
"",
|
|
"```md",
|
|
entry.description === "" ? "(missing)" : entry.description,
|
|
"```"
|
|
)
|
|
}
|
|
|
|
lines.push("")
|
|
return lines.join("\n")
|
|
}
|
|
|
|
function getPackageName(file) {
|
|
const relative = normalizePath(Path.relative(cwd, file))
|
|
const parts = relative.split("/")
|
|
const srcIndex = parts.indexOf("src")
|
|
return parts.slice(0, srcIndex).join("/")
|
|
}
|
|
|
|
function getModuleName(file) {
|
|
const relative = normalizePath(Path.relative(cwd, file))
|
|
const parts = relative.split("/")
|
|
const srcIndex = parts.indexOf("src")
|
|
return parts.slice(srcIndex + 1).join("/").replace(/\.ts$/, "")
|
|
}
|
|
|
|
function normalizePath(file) {
|
|
return file.split(Path.sep).join("/")
|
|
}
|