@gobing-ai/ts-rule-engine 0.5.29 → 0.5.32

package/README.md

@@ -372,6 +372,26 @@ Built-in fixer providers (`RegexFixerProvider`, `PathFixerProvider`, `TestStubFi
 | `test-location` | Enforce test placement and matching source/test pairs. | Uses named test-path resolvers. |
 | `schema-artifact` | Validate JSON schema artifact structure. | Checks existence, JSON validity, title, properties, defs, required array. |
 | `sg` | Run an ast-grep pattern. | Requires the `sg` CLI in the execution environment. |
+| `hedge-phrases` | Flag uncertainty phrasing ("it may", "presumably") in scoped files. | Literal phrases, one finding per file per phrase with its first matching line; `caseSensitive` (default false) and `wholeWord` (default true). |
+
+Hedge phrases (a claim that hedges states nothing verifiable):
+
+```yaml
+rules:
+  - id: no-hedged-claims
+    severity: warning
+    include: ["docs/tasks*/**/*.md"]
+    evaluator:
+      type: hedge-phrases
+      config:
+        phrases: ["it may", "presumably"]
+        # wholeWord: true      # default: "it may" does not match inside "it maybe"
+        # caseSensitive: false # default
+```
+
+A finding reads `uncertainty phrases detected: it may` and carries the first matching line.
+Enable it only where evidence prose must stay factual — design docs may legitimately hedge.
+Bundled as `rules/quality/no-hedged-claims.yaml` (shipped disabled).
 
 ### Common Evaluator Examples
 

package/dist/evaluators/hedge-phrases-evaluator.d.ts

@@ -0,0 +1,28 @@
+import { type ConstraintRule, type RuleContext, type RuleEvaluationResult, type RuleEvaluator } from '../types';
+/**
+ * Flags uncertainty / hedge phrasing in the files a rule scopes in: a claim that
+ * hedges ("it may", "presumably") states no verifiable fact, so it reads as evidence
+ * while pinning nothing.
+ *
+ * Config (`evaluator.config`):
+ * - `phrases`: non-empty list of literal phrases to flag (required; a phrase is text,
+ *   never a pattern)
+ * - `caseSensitive`: default `false` — "It May" is the same hedge as "it may"
+ * - `wholeWord`: default `true` — `it may` does not match inside `it maybe`
+ *
+ * One finding per file per phrase, carrying the first matching line, with the message
+ * `uncertainty phrases detected: <phrase>`. Scope comes from the rule's `include` /
+ * `exclude` (anchored globs), so the plane is the rule author's choice rather than a
+ * built-in assumption.
+ */
+export declare class HedgePhrasesEvaluator implements RuleEvaluator {
+    /**
+     * No collaborators: scope and filesystem come from the rule and the context. Explicit rather
+     * than implicit because Bun's coverage counts an implicit class constructor as uncovered, which
+     * would keep this file under the per-file function threshold for no real gap.
+     */
+    constructor();
+    /** Scan the scoped files for each configured phrase. */
+    evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult>;
+}
+//# sourceMappingURL=hedge-phrases-evaluator.d.ts.map

package/dist/evaluators/hedge-phrases-evaluator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedge-phrases-evaluator.d.ts","sourceRoot":"","sources":["../../src/evaluators/hedge-phrases-evaluator.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACrB,MAAM,UAAU,CAAC;AAWlB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACvD;;;;OAIG;;IAGH,wDAAwD;IAClD,QAAQ,CAAC,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;CAiC5F"}

package/dist/evaluators/hedge-phrases-evaluator.js

@@ -0,0 +1,70 @@
+import { createFinding, } from '../types.js';
+import { stringArray } from './config-access.js';
+import { scanFiles } from './file-discovery.js';
+/**
+ * Flags uncertainty / hedge phrasing in the files a rule scopes in: a claim that
+ * hedges ("it may", "presumably") states no verifiable fact, so it reads as evidence
+ * while pinning nothing.
+ *
+ * Config (`evaluator.config`):
+ * - `phrases`: non-empty list of literal phrases to flag (required; a phrase is text,
+ *   never a pattern)
+ * - `caseSensitive`: default `false` — "It May" is the same hedge as "it may"
+ * - `wholeWord`: default `true` — `it may` does not match inside `it maybe`
+ *
+ * One finding per file per phrase, carrying the first matching line, with the message
+ * `uncertainty phrases detected: <phrase>`. Scope comes from the rule's `include` /
+ * `exclude` (anchored globs), so the plane is the rule author's choice rather than a
+ * built-in assumption.
+ */
+export class HedgePhrasesEvaluator {
+    /**
+     * No collaborators: scope and filesystem come from the rule and the context. Explicit rather
+     * than implicit because Bun's coverage counts an implicit class constructor as uncovered, which
+     * would keep this file under the per-file function threshold for no real gap.
+     */
+    constructor() { }
+    /** Scan the scoped files for each configured phrase. */
+    async evaluate(rule, context) {
+        const config = (rule.evaluator.config ?? {});
+        const phrases = stringArray(config.phrases) ?? [];
+        if (phrases.length === 0) {
+            throw new Error('hedge-phrases evaluator requires a non-empty "phrases" config');
+        }
+        const caseSensitive = config.caseSensitive === true;
+        const wholeWord = config.wholeWord !== false;
+        const matchers = phrases.map((phrase) => ({ phrase, pattern: toPattern(phrase, caseSensitive, wholeWord) }));
+        const files = await scanFiles({
+            workdir: context.workdir,
+            include: rule.include,
+            exclude: rule.exclude,
+            matchMode: 'glob',
+            ...(context.fileSystem !== undefined ? { fs: context.fileSystem } : {}),
+        });
+        const findings = [];
+        for (const { file, content } of files) {
+            const lines = content.split('\n');
+            for (const { phrase, pattern } of matchers) {
+                const index = lines.findIndex((line) => pattern.test(line));
+                if (index < 0)
+                    continue;
+                findings.push(createFinding(rule, `uncertainty phrases detected: ${phrase}`, file, {
+                    line: index + 1,
+                    code: 'hedge-phrases:matched',
+                }));
+            }
+        }
+        return { findings, fixes: [] };
+    }
+}
+/**
+ * Compile one phrase as literal text, optionally whole-word and case-insensitive. The
+ * word boundary is applied only at an edge that is a word character, so a phrase like
+ * `(b) may?` still matches — a trailing `\\b` after `?` could never be satisfied.
+ */
+function toPattern(phrase, caseSensitive, wholeWord) {
+    const body = phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const lead = wholeWord && /^\w/.test(body) ? '\\b' : '';
+    const tail = wholeWord && /\w$/.test(body) ? '\\b' : '';
+    return new RegExp(`${lead}${body}${tail}`, caseSensitive ? 'u' : 'iu');
+}

package/dist/host/builtins.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/host/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAsB7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAwBvF"}
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/host/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAuB7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,IAAI,CAyBvF"}

package/dist/host/builtins.js

@@ -2,6 +2,7 @@ import { AgentDetectionEvaluator } from '../evaluators/agent-detection-evaluator
 import { CoverageGateEvaluator } from '../evaluators/coverage-gate-evaluator.js';
 import { ExitCodeEvaluator } from '../evaluators/exit-code-evaluator.js';
 import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluator.js';
+import { HedgePhrasesEvaluator } from '../evaluators/hedge-phrases-evaluator.js';
 import { ImportBoundaryEvaluator } from '../evaluators/import-boundary-evaluator.js';
 import { PathEvaluator } from '../evaluators/path-evaluator.js';
 import { RegexEvaluator } from '../evaluators/regex-evaluator.js';
@@ -37,6 +38,7 @@ export function registerBuiltins(host, executor) {
     host.evaluators.register('sg', new SgEvaluator(executor), 'builtin');
     host.evaluators.register('schema-artifact', new SchemaArtifactEvaluator(), 'builtin');
     host.evaluators.register('import-boundary', new ImportBoundaryEvaluator(), 'builtin');
+    host.evaluators.register('hedge-phrases', new HedgePhrasesEvaluator(), 'builtin');
     host.formatters.register('text', new TextFormatter(), 'builtin');
     host.formatters.register('json', new JsonFormatter(), 'builtin');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/ts-rule-engine",
-    "version": "0.5.29",
+    "version": "0.5.32",
     "description": "@gobing-ai/ts-rule-engine — Constraint rule schemas, loading, evaluation, and result formatting.",
     "keywords": [
         "typescript",
@@ -51,10 +51,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.5.29",
-        "@gobing-ai/ts-infra": "^0.5.29",
-        "@gobing-ai/ts-runtime": "^0.5.29",
-        "@gobing-ai/ts-db": "^0.5.29",
+        "@gobing-ai/ts-ai-runner": "^0.5.32",
+        "@gobing-ai/ts-infra": "^0.5.32",
+        "@gobing-ai/ts-runtime": "^0.5.32",
+        "@gobing-ai/ts-db": "^0.5.32",
         "yaml": "^2.7.0",
         "zod": "^4.1.0"
     },

package/rules/quality/no-hedged-claims.yaml

@@ -0,0 +1,32 @@
+# Uncertainty-phrase gate — a claim that hedges states nothing a reader can verify.
+#
+# SHIPPED DISABLED. Hedging is style, not a correctness contract for every consumer, and the
+# scope below is this project's task-file plane: enable it per project (and adjust `include`)
+# where evidence prose must stay factual. A runner whose engine predates `hedge-phrases` reports
+# `Unknown evaluator: hedge-phrases` as an error finding, so keep it disabled there.
+#
+# Plane: task files carry the evidence a reviewer trusts, so a hedged claim there ("it may be
+# stale") reads as proof while pinning nothing. Prose in design docs may legitimately hedge.
+include:
+  - "docs/tasks*/**/*.md"
+
+rules:
+  - id: no-hedged-claims
+    description: "Task evidence must state what was observed; an uncertainty phrase (\"it may\") is reported instead of read as proof."
+    severity: warning
+    enabled: false
+    evaluator:
+      type: hedge-phrases
+      config:
+        phrases:
+          - "it may"
+          - "it might"
+          - "might be"
+          - "may be"
+          - "possibly"
+          - "presumably"
+          - "probably"
+          - "seems to"
+          - "appears to"
+        wholeWord: true
+        caseSensitive: false

package/src/evaluators/hedge-phrases-evaluator.ts

@@ -0,0 +1,89 @@
+import {
+    type ConstraintFinding,
+    type ConstraintRule,
+    createFinding,
+    type RuleContext,
+    type RuleEvaluationResult,
+    type RuleEvaluator,
+} from '../types';
+import { stringArray } from './config-access';
+import { scanFiles } from './file-discovery';
+
+/** Evaluator config shape extracted from `rule.evaluator.config`. */
+interface HedgePhrasesConfig {
+    phrases?: unknown;
+    caseSensitive?: unknown;
+    wholeWord?: unknown;
+}
+
+/**
+ * Flags uncertainty / hedge phrasing in the files a rule scopes in: a claim that
+ * hedges ("it may", "presumably") states no verifiable fact, so it reads as evidence
+ * while pinning nothing.
+ *
+ * Config (`evaluator.config`):
+ * - `phrases`: non-empty list of literal phrases to flag (required; a phrase is text,
+ *   never a pattern)
+ * - `caseSensitive`: default `false` — "It May" is the same hedge as "it may"
+ * - `wholeWord`: default `true` — `it may` does not match inside `it maybe`
+ *
+ * One finding per file per phrase, carrying the first matching line, with the message
+ * `uncertainty phrases detected: <phrase>`. Scope comes from the rule's `include` /
+ * `exclude` (anchored globs), so the plane is the rule author's choice rather than a
+ * built-in assumption.
+ */
+export class HedgePhrasesEvaluator implements RuleEvaluator {
+    /**
+     * No collaborators: scope and filesystem come from the rule and the context. Explicit rather
+     * than implicit because Bun's coverage counts an implicit class constructor as uncovered, which
+     * would keep this file under the per-file function threshold for no real gap.
+     */
+    constructor() {}
+
+    /** Scan the scoped files for each configured phrase. */
+    async evaluate(rule: ConstraintRule, context: RuleContext): Promise<RuleEvaluationResult> {
+        const config = (rule.evaluator.config ?? {}) as HedgePhrasesConfig;
+        const phrases = stringArray(config.phrases) ?? [];
+        if (phrases.length === 0) {
+            throw new Error('hedge-phrases evaluator requires a non-empty "phrases" config');
+        }
+        const caseSensitive = config.caseSensitive === true;
+        const wholeWord = config.wholeWord !== false;
+        const matchers = phrases.map((phrase) => ({ phrase, pattern: toPattern(phrase, caseSensitive, wholeWord) }));
+        const files = await scanFiles({
+            workdir: context.workdir,
+            include: rule.include,
+            exclude: rule.exclude,
+            matchMode: 'glob',
+            ...(context.fileSystem !== undefined ? { fs: context.fileSystem } : {}),
+        });
+
+        const findings: ConstraintFinding[] = [];
+        for (const { file, content } of files) {
+            const lines = content.split('\n');
+            for (const { phrase, pattern } of matchers) {
+                const index = lines.findIndex((line) => pattern.test(line));
+                if (index < 0) continue;
+                findings.push(
+                    createFinding(rule, `uncertainty phrases detected: ${phrase}`, file, {
+                        line: index + 1,
+                        code: 'hedge-phrases:matched',
+                    }),
+                );
+            }
+        }
+        return { findings, fixes: [] };
+    }
+}
+
+/**
+ * Compile one phrase as literal text, optionally whole-word and case-insensitive. The
+ * word boundary is applied only at an edge that is a word character, so a phrase like
+ * `(b) may?` still matches — a trailing `\\b` after `?` could never be satisfied.
+ */
+function toPattern(phrase: string, caseSensitive: boolean, wholeWord: boolean): RegExp {
+    const body = phrase.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const lead = wholeWord && /^\w/.test(body) ? '\\b' : '';
+    const tail = wholeWord && /\w$/.test(body) ? '\\b' : '';
+    return new RegExp(`${lead}${body}${tail}`, caseSensitive ? 'u' : 'iu');
+}

package/src/host/builtins.ts

@@ -3,6 +3,7 @@ import { AgentDetectionEvaluator } from '../evaluators/agent-detection-evaluator
 import { CoverageGateEvaluator } from '../evaluators/coverage-gate-evaluator';
 import { ExitCodeEvaluator } from '../evaluators/exit-code-evaluator';
 import { ForbiddenImportEvaluator } from '../evaluators/forbidden-import-evaluator';
+import { HedgePhrasesEvaluator } from '../evaluators/hedge-phrases-evaluator';
 import { ImportBoundaryEvaluator } from '../evaluators/import-boundary-evaluator';
 import { PathEvaluator } from '../evaluators/path-evaluator';
 import { RegexEvaluator } from '../evaluators/regex-evaluator';
@@ -45,6 +46,7 @@ export function registerBuiltins(host: RuleEngineHost, executor?: ProcessExecuto
     host.evaluators.register('sg', new SgEvaluator(executor), 'builtin');
     host.evaluators.register('schema-artifact', new SchemaArtifactEvaluator(), 'builtin');
     host.evaluators.register('import-boundary', new ImportBoundaryEvaluator(), 'builtin');
+    host.evaluators.register('hedge-phrases', new HedgePhrasesEvaluator(), 'builtin');
     host.formatters.register('text', new TextFormatter(), 'builtin');
     host.formatters.register('json', new JsonFormatter(), 'builtin');
 }