@yegor256/dogent 0.9.1 → 0.11.0

package/src/rules/terms.js

@@ -0,0 +1,77 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Terms.
+ *
+ * Flags synonym drift: one concept named several ways across a file.
+ * Where consistent hunts word-for-word duplicates and contradictions,
+ * this rule catches the same idea wearing different labels, which makes
+ * the agent guess whether two names mean two things. A small built-in
+ * map of synonym groups seeds the deterministic check; the broader,
+ * fuzzier judgement is handed to the AI oracle through prompt().
+ */
+class Terms {
+  constructor() {
+    this.id = 'terms';
+    this.groups = [
+      ['agent', 'assistant', 'bot'],
+      ['directory', 'folder'],
+      ['parameter', 'argument', 'param', 'arg'],
+      ['function', 'method', 'routine']
+    ];
+  }
+  prompt() {
+    return `${this.id}: flag any pair of words used interchangeably for one concept, and demand a single canonical term across the whole file`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const seen = this.groups.map(() => new Map());
+    document.walk({
+      header: () => [],
+      prose: (text, line) => this.collect(text, line, seen),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    return this.report(seen, uri);
+  }
+  collect(text, line, seen) {
+    const masked = mask(text);
+    this.groups.forEach((group, index) => {
+      group.forEach((word) => {
+        const regex = new RegExp(`\\b${word}\\b`, 'iu');
+        if (regex.test(masked) && !seen[index].has(word)) {
+          seen[index].set(word, line);
+        }
+      });
+    });
+    return [];
+  }
+  report(seen, uri) {
+    const found = [];
+    seen.forEach((members) => {
+      if (members.size >= 2) {
+        const names = Array.from(members.keys());
+        const lines = Array.from(members.values());
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `concept named two ways ("${names[0]}"/"${names[1]}"), pick one term`,
+          new Region(uri, lines[1], 1)
+        ));
+      }
+    });
+    return found;
+  }
+}
+
+module.exports = Terms;

package/src/rules/tool-clarity.js

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * ToolClarity.
+ *
+ * Demands the exact name of a tool or command, never a bare generic
+ * noun. An action verb such as "run", "use", or "invoke" pointed at
+ * "the script" or "a command" leaves the agent guessing which one. The
+ * mask blanks backticked spans first, so "run `npm test`" passes while
+ * "run the script" gets flagged. Its prompt defers subtler vague
+ * references to the AI oracle.
+ */
+class ToolClarity {
+  constructor() {
+    this.id = 'tool-clarity';
+  }
+  prompt() {
+    return `${this.id}: flag any vague reference to a tool or command beyond the fixed list, and demand the exact name, path, or invocation instead`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const found = [];
+    const regex = new RegExp(
+      '\\b(?:run|use|call|invoke|execute|open)\\s+(?:the|a|an)\\s+' +
+      '(?:script|tool|command|api|file|function)\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `name the exact tool or command, not "${hit[0]}"`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = ToolClarity;

package/src/rules/transition.js

@@ -0,0 +1,59 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Transition.
+ *
+ * Flags a discourse connector that opens an instruction, like
+ * "furthermore", "in summary", or "however". A leading connector
+ * chains prose without adding a command, so it earns one violation.
+ * The check stays disjoint from the polite rule: it lists no courtesy
+ * word such as "please" or "make sure to". Its prompt hands looser
+ * connective filler to the AI oracle for deletion.
+ */
+class Transition {
+  constructor() {
+    this.id = 'transition';
+  }
+  prompt() {
+    return `${this.id}: flag connective filler beyond the fixed list, and delete it`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const [lead] = masked.match(/^\s*(?:[-*+]|\d+\.)?\s*/u);
+    const rest = masked.slice(lead.length);
+    const regex = /^(?:furthermore|moreover|additionally|in summary|in conclusion|in other words|as you can see|of course|basically|essentially|that said|however)\b/iu;
+    const hit = regex.exec(rest);
+    if (hit === null) {
+      return [];
+    }
+    return [
+      new Violation(
+        this.id,
+        'warning',
+        `discourse transition "${hit[0]}" adds no instruction, delete it`,
+        new Region(uri, line, lead.length + 1)
+      )
+    ];
+  }
+}
+
+module.exports = Transition;

package/src/rules/units.js

@@ -0,0 +1,81 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Units.
+ *
+ * Demands that every magnitude carry a unit so the reader knows what
+ * the number measures. A bare cardinal like "under 80" leaves the
+ * scale implicit; "under 80 symbols" states it. The checker masks
+ * inline code first, then scans each run of digits and flags one that
+ * names no unit, skipping percentages, units already present, decimals
+ * and versions, and leading list ordinals. Distinct from quantifier,
+ * which targets vague amount words like "several"; here the number is
+ * exact but its unit is missing.
+ */
+class Units {
+  constructor() {
+    this.id = 'units';
+    this.unit = new RegExp(
+      '^ ?(?:ms|s|sec|secs|second|seconds|min|mins|minute|minutes|' +
+      'h|hr|hrs|hour|hours|d|day|days|week|weeks|month|months|' +
+      'year|years|b|kb|mb|gb|tb|byte|bytes|bit|bits|char|chars|' +
+      'character|characters|symbol|symbols|line|lines|word|words|' +
+      'token|tokens|px|em|rem|pt|time|times|x)\\b',
+      'u'
+    );
+  }
+  prompt() {
+    return `${this.id}: flag a magnitude whose unit is implicit even in context, and state what it measures`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const clean = mask(text);
+    const found = [];
+    const digits = /\d+/gu;
+    let hit = digits.exec(clean);
+    while (hit !== null) {
+      if (!this.skip(clean, hit)) {
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `number "${hit[0]}" has no unit, state what it measures`,
+          new Region(uri, line, hit.index + 1)
+        ));
+      }
+      hit = digits.exec(clean);
+    }
+    return found;
+  }
+  skip(clean, hit) {
+    const after = clean.slice(hit.index + hit[0].length);
+    if (after.startsWith('%') || this.unit.test(after)) {
+      return true;
+    }
+    const before = clean.charAt(hit.index - 1);
+    if (/[.v@\d]/u.test(before) || /^\.\d/u.test(after)) {
+      return true;
+    }
+    const lead = /^\s*(?<num>\d+)\.\s/u.exec(clean);
+    return lead !== null && lead.index + lead[0].indexOf(lead.groups.num) === hit.index;
+  }
+}
+
+module.exports = Units;

package/src/rules/untrusted.js

@@ -0,0 +1,59 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Untrusted.
+ *
+ * Guards against indirect prompt injection. When a line tells the agent
+ * to act on external content — a verb like "read", "fetch", "open",
+ * "follow", or "execute" applied to a "page", "url", "link", "email",
+ * "file", "issue", "output", or "comment" — that content can carry
+ * hidden instructions the agent then obeys. A standalone checker flags
+ * such a line when it lacks a data-only guard ("as data", "do not
+ * follow", "treat as untrusted", "inside delimiters"). Its prompt hands
+ * the deeper judgement of source trust and guard sufficiency to the AI
+ * oracle.
+ */
+class Untrusted {
+  constructor() {
+    this.id = 'untrusted';
+  }
+  prompt() {
+    return `${this.id}: judge whether a consumed source is genuinely untrusted external input and whether its data-only guard is sufficient against prompt injection`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const verb = /\b(?:read|fetch|open|follow|execute)\b/iu;
+    const source = /\b(?:page|url|link|email|file|issue|output|comment)\b/iu;
+    const guard = /\b(?:as data|do not follow|treat as untrusted|inside delimiters|untrusted)\b/iu;
+    if (!verb.test(masked) || !source.test(masked) || guard.test(masked)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'untrusted input consumed without a data-only guard',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Untrusted;

package/src/rules/vague.js

@@ -0,0 +1,63 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Vague.
+ *
+ * Flags subjective, unmeasurable qualifiers that pretend to be precise:
+ * "properly", "good", "clean", "fast", "robust", and the like. Each
+ * leaves the agent to guess a criterion that varies run to run, so a
+ * vague qualifier is a non-instruction in disguise. The list is kept
+ * apart from the hedging words so the two rules never double-report. Its
+ * prompt hands subjective adjectives outside the fixed list to the AI
+ * oracle, asking it to suggest a concrete, checkable threshold.
+ */
+class Vague {
+  constructor() {
+    this.id = 'vague';
+  }
+  prompt() {
+    return `${this.id}: flag any subjective or unmeasurable qualifier beyond the fixed list, and propose a concrete, checkable threshold to replace it`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const found = [];
+    const regex = new RegExp(
+      '\\b(?:properly|correctly|appropriately|good|clean|fast|slow|' +
+      'large|small|robust|reasonable|efficient|as much as possible|' +
+      'if needed)\\b',
+      'giu'
+    );
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `vague qualifier "${hit[0]}" carries no measurable criterion`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Vague;

package/src/rules/weak-verb.js

@@ -0,0 +1,62 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+const mask = require('../mask');
+
+/**
+ * Weak verb.
+ *
+ * Flags a leading imperative that names no concrete action: "handle",
+ * "manage", "process", "support", "ensure", "maintain", "deal with",
+ * "take care of", "work on". Each tells the agent to do something
+ * unspecified, so the line carries no real instruction. The check fires
+ * only on the first word of the line, leaving the same verb mid-sentence
+ * alone, and stays apart from "vague" (adjectives) and "command"
+ * (imperative form). Its prompt hands subtler catch-all verbs outside
+ * the fixed list to the AI oracle.
+ */
+class WeakVerb {
+  constructor() {
+    this.id = 'weak-verb';
+  }
+  prompt() {
+    return `${this.id}: flag a leading imperative verb that names no concrete action beyond the fixed list, and propose a precise action verb`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const regex = new RegExp(
+      '^(?<lead>\\s*(?:[-*+]|\\d+\\.)?\\s*)' +
+      '(?<verb>handle|manage|process|support|ensure|maintain|' +
+      'deal with|take care of|work on)\\b',
+      'iu'
+    );
+    const hit = regex.exec(masked);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `weak verb "${hit.groups.verb}" names no concrete action, use a precise verb`,
+      new Region(uri, line, hit.groups.lead.length + 1)
+    )];
+  }
+}
+
+module.exports = WeakVerb;

package/src/version.js

@@ -9,8 +9,8 @@
  * Version.
  *
  * The current release of dogent, replaced on every release by rultor.
- * The default `0.9.1` marks an unreleased build straight from source.
+ * The default `0.11.0` marks an unreleased build straight from source.
  */
-const version = '0.9.1';
+const version = '0.11.0';
 
 module.exports = version;