@gobing-ai/ts-rule-engine 0.4.2 → 0.4.4

package/dist/evaluators/ripgrep-evaluator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ripgrep-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/ripgrep-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAE/B,QAAQ,GAAE,eAA2C;IAIjE,oFAAoF;IAC9E,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA2B5F;AA+ED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACtC,OAAO,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAK/D"}
+{"version":3,"file":"ripgrep-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/ripgrep-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAClF,OAAO,EACH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAGlB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;gBAE/B,QAAQ,GAAE,eAA2C;IAIjE,oFAAoF;IAC9E,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CA8B5F;AAmFD;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CACtC,OAAO,EAAE,MAAM,GAChB;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAK/D"}

package/dist/evaluators/ripgrep-evaluator.js

@@ -44,10 +44,14 @@ export class RipgrepEvaluator {
             rejectOnError: false,
             label: 'rg',
         });
-        // ripgrep exits 0 with matches, 1 when none, 2 on error. Treat 2 (or any non-0/1
-        // with stderr) as a hard failure so a broken pattern or missing `rg` fails loud.
+        // ripgrep exits 0 with matches, 1 when none, 2 on error. A scoped rule whose
+        // positive globs match no files also exits 2 with "No files were searched";
+        // that means "this rule is not applicable in this repo", not a broken
+        // evaluator. Keep all other exit-2 cases loud.
         if (result.exitCode !== 0 && result.exitCode !== 1) {
             const detail = result.stderr.trim();
+            if (isNoFilesSearched(detail))
+                return { findings: [], fixes: [] };
             throw new Error(`rg failed (exit ${result.exitCode})${detail.length > 0 ? `: ${detail}` : ''}`);
         }
         return mode === 'require'
@@ -55,6 +59,9 @@ export class RipgrepEvaluator {
             : { findings: forbidFindings(rule, pattern, result.stdout), fixes: [] };
     }
 }
+function isNoFilesSearched(stderr) {
+    return stderr.includes('No files were searched');
+}
 /** Build the ripgrep argument list for the given mode and scope. */
 function buildArgs(pattern, mode, multiline, include, exclude) {
     const args = [];

package/dist/evaluators/tsdoc-export-evaluator.js

@@ -42,8 +42,8 @@ export class TsdocExportEvaluator {
         for (const { file, content } of files) {
             const lines = content.split('\n');
             for (const site of findExports(lines, requested)) {
-                if (!precededByJsdoc(lines, site.line)) {
-                    findings.push(createFinding(rule, `Exported ${site.kind} "${site.name}" is missing a JSDoc comment`, file, {
+                if (!precededByDoc(lines, site.line)) {
+                    findings.push(createFinding(rule, `Exported ${site.kind} "${site.name}" is missing a doc comment`, file, {
                         line: site.line,
                         code: 'tsdoc:missing',
                     }));
@@ -71,17 +71,19 @@ function findExports(lines, requested) {
     return sites;
 }
 /**
- * True when a JSDoc block precedes a declaration.
+ * True when a documentation comment precedes a declaration.
  *
- * Walks backward from the line before the declaration, skipping blank lines,
- * JSDoc body lines (`* …`), and decorator / JSDoc-tag lines (`@…`), then
- * checks whether the nearest meaningful line closes (or is) a JSDoc comment.
+ * Accepts both JSDoc blocks (`/** … *\/`) and line comments (`// …`) as valid
+ * preceding documentation. Walks backward from the line before the declaration,
+ * skipping blank lines, JSDoc body lines (`* …`), decorator / JSDoc-tag lines
+ * (`@…`), and contiguous `//` comment lines, then checks whether the nearest
+ * meaningful line is a JSDoc fence, a `//` comment, or the start of a `//` block.
  */
-function precededByJsdoc(lines, declarationLine) {
+function precededByDoc(lines, declarationLine) {
     let cursor = declarationLine - 2; // zero-based line above the declaration
     while (cursor >= 0) {
         const prev = lines[cursor]?.trim() ?? '';
-        // Blank line between JSDoc closing fence and declaration — keep walking.
+        // Blank line between comment and declaration — keep walking.
         if (prev === '') {
             cursor -= 1;
             continue;
@@ -90,13 +92,17 @@ function precededByJsdoc(lines, declarationLine) {
         if (prev.endsWith('*/') || prev.startsWith('/**')) {
             return true;
         }
+        // Line comment (// …) — accepted as documentation.
+        if (prev.startsWith('//')) {
+            return true;
+        }
         // JSDoc body line (* …) or decorator / tag (@…).  Check after the
-        // fence so `*/` is never misidentified as a body line.
+        // fences so `*/` is never misidentified as a body line.
         if (prev.startsWith('*') || prev.startsWith('@')) {
             cursor -= 1;
             continue;
         }
-        // Non-JSDoc, non-decorator line — no JSDoc precedes this declaration.
+        // Non-comment, non-decorator line — no documentation precedes this declaration.
         return false;
     }
     return false;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.4.2",
+    "version": "0.4.4",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -49,10 +49,10 @@
         "release": "echo 'Manual publish is disabled. Releases go through GitHub Actions via Trusted Publishing — push a tag: git tag @gobing-ai/ts-rule-engine-v<version> && git push --tags' && exit 1"
     },
     "dependencies": {
-        "@gobing-ai/ts-ai-runner": "^0.4.2",
-        "@gobing-ai/ts-infra": "^0.4.2",
-        "@gobing-ai/ts-runtime": "^0.4.2",
-        "@gobing-ai/ts-db": "^0.4.2",
+        "@gobing-ai/ts-ai-runner": "^0.4.4",
+        "@gobing-ai/ts-infra": "^0.4.4",
+        "@gobing-ai/ts-runtime": "^0.4.4",
+        "@gobing-ai/ts-db": "^0.4.4",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/rules/quality/tsdoc-exports.yaml

@@ -1,7 +1,7 @@
-# TSDoc export rules — every public export must carry a JSDoc comment.
+# TSDoc export rules — every public export must carry a doc comment (JSDoc `/** */` or line `//`).
 rules:
   - id: every-export-has-tsdoc
-    description: "Every export (function, class, interface, type, const, enum) must have a /** ... */ JSDoc comment describing what it is and why."
+    description: "Every export (function, class, interface, type, const, enum) must have a preceding doc comment — either a JSDoc block (`/** ... */`) or a line comment (`// ...`) describing what it is and why."
     severity: error
     evaluator:
       type: tsdoc-export

package/src/evaluators/ripgrep-evaluator.ts

@@ -55,10 +55,13 @@ export class RipgrepEvaluator implements RuleEvaluator {
             label: 'rg',
         });
 
-        // ripgrep exits 0 with matches, 1 when none, 2 on error. Treat 2 (or any non-0/1
-        // with stderr) as a hard failure so a broken pattern or missing `rg` fails loud.
+        // ripgrep exits 0 with matches, 1 when none, 2 on error. A scoped rule whose
+        // positive globs match no files also exits 2 with "No files were searched";
+        // that means "this rule is not applicable in this repo", not a broken
+        // evaluator. Keep all other exit-2 cases loud.
         if (result.exitCode !== 0 && result.exitCode !== 1) {
             const detail = result.stderr.trim();
+            if (isNoFilesSearched(detail)) return { findings: [], fixes: [] };
             throw new Error(`rg failed (exit ${result.exitCode})${detail.length > 0 ? `: ${detail}` : ''}`);
         }
 
@@ -68,6 +71,10 @@ export class RipgrepEvaluator implements RuleEvaluator {
     }
 }
 
+function isNoFilesSearched(stderr: string): boolean {
+    return stderr.includes('No files were searched');
+}
+
 /** Build the ripgrep argument list for the given mode and scope. */
 function buildArgs(pattern: string, mode: string, multiline: boolean, include: string[], exclude: string[]): string[] {
     const args: string[] = [];

package/src/evaluators/tsdoc-export-evaluator.ts

@@ -62,9 +62,9 @@ export class TsdocExportEvaluator implements RuleEvaluator {
         for (const { file, content } of files) {
             const lines = content.split('\n');
             for (const site of findExports(lines, requested)) {
-                if (!precededByJsdoc(lines, site.line)) {
+                if (!precededByDoc(lines, site.line)) {
                     findings.push(
-                        createFinding(rule, `Exported ${site.kind} "${site.name}" is missing a JSDoc comment`, file, {
+                        createFinding(rule, `Exported ${site.kind} "${site.name}" is missing a doc comment`, file, {
                             line: site.line,
                             code: 'tsdoc:missing',
                         }),
@@ -94,17 +94,19 @@ function findExports(lines: string[], requested: ReadonlySet<ExportKind>): Expor
 }
 
 /**
- * True when a JSDoc block precedes a declaration.
+ * True when a documentation comment precedes a declaration.
  *
- * Walks backward from the line before the declaration, skipping blank lines,
- * JSDoc body lines (`* …`), and decorator / JSDoc-tag lines (`@…`), then
- * checks whether the nearest meaningful line closes (or is) a JSDoc comment.
+ * Accepts both JSDoc blocks (`/** … *\/`) and line comments (`// …`) as valid
+ * preceding documentation. Walks backward from the line before the declaration,
+ * skipping blank lines, JSDoc body lines (`* …`), decorator / JSDoc-tag lines
+ * (`@…`), and contiguous `//` comment lines, then checks whether the nearest
+ * meaningful line is a JSDoc fence, a `//` comment, or the start of a `//` block.
  */
-function precededByJsdoc(lines: string[], declarationLine: number): boolean {
+function precededByDoc(lines: string[], declarationLine: number): boolean {
     let cursor = declarationLine - 2; // zero-based line above the declaration
     while (cursor >= 0) {
         const prev = lines[cursor]?.trim() ?? '';
-        // Blank line between JSDoc closing fence and declaration — keep walking.
+        // Blank line between comment and declaration — keep walking.
         if (prev === '') {
             cursor -= 1;
             continue;
@@ -113,13 +115,17 @@ function precededByJsdoc(lines: string[], declarationLine: number): boolean {
         if (prev.endsWith('*/') || prev.startsWith('/**')) {
             return true;
         }
+        // Line comment (// …) — accepted as documentation.
+        if (prev.startsWith('//')) {
+            return true;
+        }
         // JSDoc body line (* …) or decorator / tag (@…).  Check after the
-        // fence so `*/` is never misidentified as a body line.
+        // fences so `*/` is never misidentified as a body line.
         if (prev.startsWith('*') || prev.startsWith('@')) {
             cursor -= 1;
             continue;
         }
-        // Non-JSDoc, non-decorator line — no JSDoc precedes this declaration.
+        // Non-comment, non-decorator line — no documentation precedes this declaration.
         return false;
     }
     return false;