Pine/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity

Gate JSDoc completeness on every package export

Browse Source 
New doc-sync gate verify-export-jsdoc walks every module-level exported
name under packages/*/*/src and requires description prose everywhere,
plus @param per parameter and @returns on non-void annotated returns for
function-like exports, public class methods, properties, and accessors.
The parsing + check helpers move out of gen-cordis-catalog.ts into a
shared scripts/jsdoc.ts so 'documented' means one thing on both gated
surfaces.

Deliberate exemptions (documented in the RFC): heritage-declared class
members (the seam declaration is the doc's one home — the one checker
query in an otherwise pure-AST walk), cordis plugin-protocol slots
(name/inject/reusable/Config/apply, top-level and static), constructors,
overload implementations, declare-module augmentation bodies, and
re-export statements (checked at the defining module).

The 203 under-documented exports the gate found at adoption are filled
in this change, so the gate lands green; generated catalogs/graphs are
regenerated for the shifted line pointers.

RFC: docs/rfc/implemented/process/2026-07-06-export-surface-jsdoc-gate.md
This commit is contained in:
Tianyi Cui
2026-07-06 22:09:30 +08:00
parent 1c999804d8
commit cd9737d569
92 changed files with 1802 additions and 289 deletions
Download Patch File Download Diff File Expand all files Collapse all files
scripts/gen-cordis-catalog.ts
+14 -177
View File
@@ -40,7 +40,9 @@
* a stale `@param` naming no real parameter errors. Violations aggregate into
* ONE error listing every offender. The tags are enforcement-only: parseJsDoc
* stops prose at the first block tag, so they never change the rendered
* catalog. The INHERITED
* catalog. The parsing + check helpers live in `scripts/jsdoc.ts`, shared with
* the whole-export-surface gate (`scripts/verify-export-jsdoc.ts`) so
* "documented" means the same thing on both surfaces. The INHERITED
* tier (cordis core + loader/hmr/timer) is pinned vendor source a plugin author
* also sees; it is rendered tersely (name + one-line + source pointer) from a
* curated table in this script, NOT elevated to the harness tier's prominence.
@@ -53,6 +55,7 @@
import { globSync, readFileSync, writeFileSync } from 'node:fs'
import { resolve } from 'node:path'
import ts from 'typescript'
import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
const root = resolve(import.meta.dirname, '..')
const OUT_EVENTS = 'docs/cordis-catalog/events.md'
@@ -62,9 +65,6 @@ const OUT_SERVICES = 'docs/cordis-catalog/services.md'
* doc-typecheck, since a bare signature fragment is not standalone-compilable). */
const FENCE = 'ts cordis-catalog'
/** A dispatch mode, rendered as the badge after an event name. */
type Mode = 'emit' | 'waterfall' | 'parallel' | 'serial'
/**
* Cross-link map: a type name that appears in a signature → the
* core-data-structures page that documents it (path relative to the catalogs'
@@ -146,132 +146,6 @@ interface InheritedEntry {
source: string
}
/** Repo-relative source pointer `file:line` for a node's first character. */
function pointer(rel: string, sf: ts.SourceFile, node: ts.Node): string {
const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
return `${rel}:${line + 1}`
}
/** The raw `/** … *​/` JSDoc block immediately preceding a node, or '' if none. */
function rawJsDoc(text: string, node: ts.Node): string {
const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []
const jsdoc = ranges.filter(r => text.slice(r.pos, r.pos + 3) === '/**').at(-1)
return jsdoc ? text.slice(jsdoc.pos, jsdoc.end) : ''
}
/**
* Parse a raw JSDoc block into description prose + the `@mode` tag (when
* present). Output obeys the repo's markdown conventions so the generated file
* passes verify-md-wrap: each prose paragraph collapses to ONE physical line,
* and a `-` bullet list is preserved with each item on its own single line
* (continuation lines folded in). `{@link Foo}` unwraps to `Foo`. Description
* prose ends at the FIRST block tag (standard JSDoc semantics): tag lines and
* their continuation lines are never prose, so `@param`/`@returns` blocks are
* invisible to the rendered catalog.
*/
function parseJsDoc(raw: string): { doc: string; mode: Mode | null } {
const inner = raw
.replace(/^\/\*\*/, '')
.replace(/\*\/$/, '')
.split('\n')
.map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
let mode: Mode | null = null
let inTags = false
const blocks: string[] = []
let para: string[] = []
let list: string[] = []
let item: string[] = []
const join = (parts: string[]): string => parts.join(' ').replace(/\s+/g, ' ').trim()
const flushItem = (): void => {
if (item.length) list.push(join(item))
item = []
}
const flushList = (): void => {
flushItem()
if (list.length) blocks.push(list.join('\n')) // one block, items on own lines
list = []
}
const flushPara = (): void => {
flushList()
if (para.length) blocks.push(join(para))
para = []
}
for (const line of inner) {
const m = /^@mode\s+(emit|waterfall|parallel|serial)\s*$/.exec(line)
if (m) { mode = m[1] as Mode; flushPara(); inTags = true; continue }
if (line.startsWith('@')) { flushPara(); inTags = true; continue }
if (inTags) continue // block-tag territory: continuations are never prose
if (line.trim() === '') { flushPara(); continue }
if (/^-\s+/.test(line)) {
// A list item starts: a pending paragraph (e.g. an intro line directly
// above the list, no blank between) flushes FIRST so it renders above.
flushItem()
if (para.length) { blocks.push(join(para)); para = [] }
item.push(line)
continue
}
if (item.length) { item.push(line); continue } // continuation of current item
para.push(line)
}
flushPara()
const doc = blocks.join('\n\n').replace(/\{@link\s+([^}]+)\}/g, '$1').trim()
return { doc, mode }
}
/**
* Parse the block tags of a raw JSDoc comment for the completeness checks:
* every `@param name — description` entry plus the `@returns` description.
* Standard JSDoc block-tag semantics — a tag's description runs across
* continuation lines until the next tag or a blank line, and the `-`/`—`
* separator after a param name is optional. `[name]` optional-brackets unwrap
* to `name`. Rendering never sees these: parseJsDoc stops prose at the first
* block tag.
*/
function parseTags(raw: string): { params: Map<string, string>; returns: string | null } {
const inner = raw
.replace(/^\/\*\*/, '')
.replace(/\*\/$/, '')
.split('\n')
.map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
const params = new Map<string, string>()
let returns: string | null = null
let sink: ((text: string) => void) | null = null
for (const line of inner) {
const param = /^@param\s+(\[?[\w$]+\]?)\s*(?:[-—–]\s*)?(.*)$/.exec(line)
if (param) {
const name = (param[1] ?? '').replace(/^\[|\]$/g, '')
let acc = param[2] ?? ''
params.set(name, acc)
sink = (t) => { acc = acc ? `${acc} ${t}` : t; params.set(name, acc) }
continue
}
const ret = /^@returns?(?:\s+[-—–]?\s*(.*))?$/.exec(line)
if (ret) {
let acc = ret[1] ?? ''
returns = acc
sink = (t) => { acc = acc ? `${acc} ${t}` : t; returns = acc }
continue
}
if (line.startsWith('@') || line.trim() === '') { sink = null; continue }
sink?.(line.trim())
}
return { params, returns }
}
/**
* Throw one aggregate error for every completeness violation a walk collected.
* Aggregation (vs the fail-fast the @mode check used to do) is deliberate: a
* remediation pass sees the whole list at once instead of replaying the gate
* once per offender.
*/
function reportViolations(violations: string[]): void {
if (violations.length === 0) return
throw new Error(
`gen-cordis-catalog: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):\n`
+ violations.map(v => ` ${v}`).join('\n'),
)
}
/** Find the `declare module 'cordis'` body in a source file, or null. */
function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
for (const stmt of sf.statements) {
@@ -334,27 +208,13 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
// (mode machinery, documented once by @mode semantics). Documenting an
// exempt parameter anyway is allowed — only absence is checked.
const { params } = parseTags(raw)
for (const p of member.parameters) {
if (!ts.isIdentifier(p.name)) {
violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the event surface needs simple identifier parameters so @param can name them.`)
continue
}
const pname = p.name.text
if (pname === 'this' || (hasNext && p === last)) continue
const desc = params.get(pname)
if (desc === undefined) violations.push(`${where} is missing @param ${pname}.`)
else if (!desc.trim()) violations.push(`${where}: @param ${pname} has an empty description.`)
}
for (const tag of params.keys()) {
if (!member.parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
}
}
checkParams(where, 'event', member.parameters, params, sf,
p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, mode, doc, source: src })
}
}
}
reportViolations(violations)
reportViolations('gen-cordis-catalog', violations)
return entries
}
@@ -415,35 +275,12 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
const { params, returns } = parseTags(raw)
// Every parameter needs a non-empty @param; a `this` receiver
// annotation is not payload and is exempt.
for (const p of member.parameters) {
if (!ts.isIdentifier(p.name)) {
violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the service surface needs simple identifier parameters so @param can name them.`)
continue
}
const pname = p.name.text
if (pname === 'this') continue
const desc = params.get(pname)
if (desc === undefined) violations.push(`${where} is missing @param ${pname}.`)
else if (!desc.trim()) violations.push(`${where}: @param ${pname} has an empty description.`)
}
for (const tag of params.keys()) {
if (!member.parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
}
}
// A non-void result needs a non-empty @returns. The return type must be
// ANNOTATED: a pure-AST walk cannot classify an inferred return. On a
// `void`/`Promise<void>` method @returns stays optional (resolution
// timing can be worth documenting), never required.
const rt = member.type?.getText(sf).replace(/\s+/g, ' ')
if (rt === undefined) {
violations.push(`${where} has no return type annotation; annotate it explicitly so the gate can classify the result.`)
} else if (!/^(void|Promise<void>)$/.test(rt)) {
if (returns === null) violations.push(`${where} is missing @returns (return type: ${rt}).`)
else if (!returns.trim()) violations.push(`${where}: @returns has an empty description.`)
}
// Every parameter needs a non-empty @param (`this` receiver exempt),
// and a non-void ANNOTATED result needs a non-empty @returns — the
// shared checkers carry the exact contract.
checkParams(where, 'service', member.parameters, params, sf,
p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
checkReturns(where, member.type, returns, sf, violations)
}
entries.push({
key,
@@ -455,7 +292,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
})
}
}
reportViolations(violations)
reportViolations('gen-cordis-catalog', violations)
return entries.sort((a, b) => a.key.localeCompare(b.key))
}