pm-ops 2026.7.29 → 2026.8.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 2026.8.1 - 2026-08-01
+
+### Added
+
+- Docstring coverage gate: a lexer-backed, fail-closed documentation gate the fleet can share ([ops-073p](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/features/ops-073p.toon))
+
+### Fixed
+
+- Brace-ending initializers consume following ASI declarations and members ([ops-cqyv](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-cqyv.toon))
+- Prevent symlink cycles during docstring source traversal ([ops-hkxb](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-hkxb.toon))
+- Semicolon-free exported variables consume following declarations ([ops-aun4](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-aun4.toon))
+- Sanitize Node test-runner context before release verification ([ops-hq5u](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-hq5u.toon))
+- The docstrings command writes JSON on the failure path under the default toon format ([ops-k6wq](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-k6wq.toon))
+- Semicolon-free class fields bypass docstring evaluation ([ops-6wen](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-6wen.toon))
+- The docstring gate is fail-open for exported bindings it cannot decompose ([ops-f25k](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/issues/ops-f25k.toon))
+
+## 2026.7.31 - 2026-07-31
+
+### Other
+
+- Expose the analyzer as a pm ops subcommand and a package subpath export ([ops-qvbu](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-qvbu.toon))
+- Build the lexer-backed docstring analyzer and its negative controls ([ops-w8n4](https://github.com/unbraind/pm-ops/blob/main/.agents/pm/tasks/ops-w8n4.toon))
+
 ## 2026.7.29 - 2026-07-29
 
 ### Added

package/dist/docstrings.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @file Lexer-backed docstring coverage analyzer.
+ *
+ * The fleet mandate requires every source declaration to carry a real
+ * docstring, enforced by a gate that cannot be cheated. A naive implementation
+ * is worse than none: a green check that proves nothing is active cover for
+ * missing documentation. This module is the replacement for a prior regex-based
+ * attempt, rebuilt on the one source of truth that distinguishes real syntax
+ * from text that merely looks syntactic: the TypeScript token stream.
+ *
+ * ## Why a lexer, not a regex or the compiler
+ *
+ * TypeScript 7 removed the stable compiler API (`createSourceFile`,
+ * `forEachChild`, …), so there is no AST to walk: `import ts from "typescript"`
+ * yields only `{ version }` at run time. What the `typescript/unstable/ast`
+ * surface still exposes is the lexer — `createScanner` — which emits exactly
+ * the punctuation and keywords that exist in the file. A brace inside a string,
+ * template literal, regex, or comment is never a `OpenBraceToken`; a declaration
+ * written inside a comment produces no tokens at all. That is precisely the
+ * property a brace-counting regex lacks, and it is what makes the rules below
+ * trustworthy.
+ *
+ * The scanner needs two corrections the unstable surface does not apply
+ * automatically, both handled in {@link tokenize}:
+ *
+ * 1. A template substitution `${ … }` emits a `CloseBraceToken` for the `}`
+ *    without a matching `OpenBraceToken` (the `${` is folded into the
+ *    `TemplateHead`). Plain brace counting is corrupted by it, exactly as the
+ *    regex version was corrupted by braces in strings. The fix is to track a
+ *    frame stack and, only when a `}` closes a substitution frame, call
+ *    `reScanTemplateToken` so it becomes a `TemplateMiddle` / `TemplateTail`
+ *    and never reaches the brace counter.
+ *
+ * 2. The scanner does not decide regex versus division on its own: a `/` is
+ *    always a `SlashToken`, and `reScanSlashToken` scans a regex
+ *    unconditionally — which swallows a division operator and everything after
+ *    it as one unterminated regular expression. The fix is to rescan `/` as a
+ *    regex only when the previous significant token cannot end an expression,
+ *    matching the heuristic every JavaScript lexer uses.
+ *
+ * After that, the token array contains only real, balanced braces, and group
+ * matching over it is exact.
+ *
+ * ## Docstring recovery
+ *
+ * `getLeadingCommentRanges(text, tokenFullStart)` returns only the comments in
+ * the contiguous trivia immediately preceding a token, so a JSDoc block that
+ * lives inside a string literal, a template, or a commented-out line is
+ * invisible to it — the four classic cheats. JSDoc is a block comment (`kind`
+ * `3`) beginning with `/**`; a `//` line comment is `kind` `2` and does not
+ * count.
+ *
+ * ## Rules
+ *
+ * The documented surface — every symbol {@link judge} evaluates — is:
+ *
+ * - every exported declaration (`function`, `class`, `interface`, `type`,
+ *   `const` / `let` / `var`, including `export default function|class`);
+ * - every non-`private`, non-`protected`, non-`#` member of an exported class
+ *   (methods, properties, and `get` / `set` accessors);
+ * - every non-exported `function` whose body spans more than
+ *   {@link INTERNAL_BODY_LINES} lines, implemented (unlike the prior attempt's
+ *   declared-but-never-read constant).
+ *
+ * A passing docstring must carry at least {@link MIN_DOC_WORDS} meaningful words
+ * after filler removal and contribute at least {@link MIN_NOVEL_WORDS} terms the
+ * identifier did not already carry, so a `Gets the name.` JSDoc on `getName`
+ * fails.
+ *
+ * ## Fail-closed
+ *
+ * A declaration keyword the finder cannot classify is a violation with reason
+ * `unrecognized declaration form`, never a silent skip. The silent skip is the
+ * cheat this gate exists to prevent.
+ *
+ * ## Out of scope (structural, not configurable)
+ *
+ * `.d.ts` ambient declarations, `test/`, `dist/`, and `node_modules` are skipped
+ * by hard-coded directory rules; imports and re-export statements (`export { … }
+ * from`, `export * from`) declare nothing; `export default <expression>`,
+ * overload signatures, constructors, index signatures, computed-name members,
+ * `private` / `protected` / `#` members, and anonymous function/arrow
+ * expressions carry no stable identifier and are therefore not in the documented
+ * surface. There is deliberately no ignore list: an exemption must be a
+ * documented rule with a reason, not a configuration entry.
+ */
+/**
+ * Minimum number of meaningful words a docstring must contain after filler
+ * removal. Below this the comment is too thin to document anything.
+ */
+export declare const MIN_DOC_WORDS = 4;
+/**
+ * Minimum number of meaningful words a docstring must contribute that the
+ * identifier itself does not already carry. This is what rejects a comment that
+ * merely restates the name.
+ */
+export declare const MIN_NOVEL_WORDS = 2;
+/**
+ * Number of source lines a non-exported function body must span before it joins
+ * the documented surface. Short private helpers stay undocumented; substantial
+ * ones must explain themselves.
+ */
+export declare const INTERNAL_BODY_LINES = 4;
+/** A single documentation violation found in one source file. */
+export interface DocstringViolation {
+    /** Path of the file, relative to the scanned root. */
+    readonly file: string;
+    /** 1-based line of the declaration that failed. */
+    readonly line: number;
+    /** Symbol that failed, e.g. `parseFoo` or `Widget.render`. */
+    readonly symbol: string;
+    /** Actionable reason naming the rule that failed. */
+    readonly reason: string;
+}
+/** Aggregate result of scanning one tree. */
+export interface DocstringReport {
+    /** Number of `.ts` files analyzed. */
+    readonly files_scanned: number;
+    /** Number of declarations evaluated against the rules. */
+    readonly declarations_checked: number;
+    /** Every violation, in source order. */
+    readonly violations: readonly DocstringViolation[];
+}
+/**
+ * Result of analyzing a single source text via {@link analyzeSource}: the
+ * violations it produced and how many declarations were evaluated.
+ */
+export interface SourceAnalysis {
+    /** Violations found in this source. */
+    readonly violations: readonly DocstringViolation[];
+    /** Declarations evaluated against the rules. */
+    readonly declarations: number;
+}
+/**
+ * Analyze one already-read TypeScript source text and report the docstring
+ * violations it contains plus how many declarations were evaluated.
+ */
+export declare function analyzeSource(text: string, file: string): SourceAnalysis;
+/**
+ * Walk a directory tree and analyze every authored `.ts` source beneath it,
+ * skipping `.d.ts` files and the structural non-source directories. Scanning
+ * zero files fails by throwing rather than passing vacuously.
+ */
+export declare function analyzeDocstringCoverage(options: {
+    root: string;
+    sourceDirs?: readonly string[];
+}): DocstringReport;
+//# sourceMappingURL=docstrings.d.ts.map

package/dist/docstrings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docstrings.d.ts","sourceRoot":"","sources":["../docstrings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AAOH;;;GAGG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B;;;;GAIG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC,iEAAiE;AACjE,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6CAA6C;AAC7C,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,wCAAwC;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACpD;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,QAAQ,CAAC,UAAU,EAAE,SAAS,kBAAkB,EAAE,CAAC;IACnD,gDAAgD;IAChD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AA2lCD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,cAAc,CAKxE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAAG,eAAe,CAoBnH"}