@yegor256/dogent 0.9.1 → 0.11.0

package/src/rules/conditional.js

@@ -0,0 +1,55 @@
+/*
+ * 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');
+
+/**
+ * Conditional.
+ *
+ * Demands that branching never collapse onto one line. A line carrying
+ * more than one condition keyword (if, unless, when, else, otherwise)
+ * spells out a whole branch tree at once, so each case must split into
+ * its own command. Distinct from simple, which weighs clause depth, and
+ * from atomic, which counts instructions; this one targets branching
+ * alone. A lone guard keeps just one keyword and stays clean.
+ */
+class Conditional {
+  constructor() {
+    this.id = 'conditional';
+  }
+  prompt() {
+    return `${this.id}: flag implicit branching that carries no keyword, and split each case into its own command`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = mask(text);
+    const hits = clean.match(/\b(?:if|unless|when|else|otherwise)\b/giu);
+    if (hits === null || hits.length < 2) {
+      return [];
+    }
+    const column = clean.search(/\b(?:if|unless|when|else|otherwise)\b/iu);
+    return [new Violation(
+      this.id,
+      'warning',
+      'multi-branch conditional, split each case into its own command',
+      new Region(uri, line, column + 1)
+    )];
+  }
+}
+
+module.exports = Conditional;

package/src/rules/consistent.js

@@ -20,7 +20,7 @@ class Consistent {
     this.id = 'consistent';
   }
   prompt() {
-    return `${this.id}: flag an instruction that repeats another instruction word for word, or that directly contradicts another instruction in the same file`;
+    return `${this.id}: flag an instruction that repeats another instruction word for word, or that logically contradicts another instruction about the very same subject, where one line orders exactly what another forbids; ignore lines that merely share a theme but govern different concerns, since complementary instructions never clash`;
   }
   violations() {
     return [];

package/src/rules/counter-example.js

@@ -0,0 +1,60 @@
+/*
+ * 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');
+
+/**
+ * CounterExample.
+ *
+ * Rejects "bad example" demonstrations that show the wrong form, since
+ * displaying a mistake can reinforce it. A standalone checker flags a
+ * line that opens a counterexample with an introducer phrase ("bad
+ * example", "wrong example", "for example, do not", "instead of
+ * writing", "avoid writing") and then carries a quoted or backticked
+ * sample of the wrong form. Its prompt hands subtler cases to the AI
+ * oracle, which judges whether an example shows the correct or the
+ * incorrect behavior.
+ */
+class CounterExample {
+  constructor() {
+    this.id = 'counter-example';
+  }
+  prompt() {
+    return `${this.id}: judge whether each example shows the correct behavior, and flag any example that demonstrates the incorrect form`;
+  }
+  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 regex = /bad example|wrong example|for example, do not|instead of writing|avoid writing/iu;
+    const hit = regex.exec(mask(text));
+    if (hit === null) {
+      return [];
+    }
+    const tail = text.slice(hit.index + hit[0].length);
+    if (!/["'`]/u.test(tail)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'counterexample may reinforce the wrong behavior, show the right form',
+      new Region(uri, line, hit.index + 1)
+    )];
+  }
+}
+
+module.exports = CounterExample;

package/src/rules/default.js

@@ -0,0 +1,60 @@
+/*
+ * 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');
+
+/**
+ * Default.
+ *
+ * Demands that optional behavior names its default. A line marking work
+ * as optional through "optionally", "you may", or "feel free to" leaves
+ * the agent guessing what happens when it declines, so the line must
+ * state a default. A line that already declares one through "by
+ * default", "defaults to", or "otherwise" passes untouched. Its prompt
+ * hands subtler optionality with no stated default to the AI oracle.
+ */
+class Default {
+  constructor() {
+    this.id = 'default';
+  }
+  prompt() {
+    return `${this.id}: flag optionality that names no default even without a listed marker, and state the default`;
+  }
+  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);
+    if ((/\b(?:by default|default to|defaults to|otherwise)\b/iu).test(masked)) {
+      return [];
+    }
+    const found = [];
+    const regex = /\b(?:optionally|you may|you can|if you want|feel free to|as an option)\b/giu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        `optional behavior "${hit[0]}" has no default, state it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = Default;

package/src/rules/description-length.js

@@ -0,0 +1,64 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionLength.
+ *
+ * Demands that a SKILL.md description stay within a sane size. The
+ * loader keeps every description in context, so an overgrown one wastes
+ * the budget that the instructions need. Flags a value longer than the
+ * ceiling and a value that is empty, leaving the wording itself to
+ * sibling rules.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class DescriptionLength {
+  constructor() {
+    this.id = 'description-length';
+    this.ceiling = 1024;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const {value} = pair;
+    if (value.trim() === '') {
+      return [this.flag('description is empty, write a concise capability statement', pair.row, uri)];
+    }
+    if (value.length > this.ceiling) {
+      return [this.flag(`description is ${value.length} chars, keep it under ${this.ceiling}`, pair.row, uri)];
+    }
+    return [];
+  }
+  flag(message, row, uri) {
+    return new Violation(this.id, 'warning', message, new Region(uri, row, 1));
+  }
+}
+
+module.exports = DescriptionLength;

package/src/rules/description-voice.js

@@ -0,0 +1,67 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * DescriptionVoice.
+ *
+ * Demands that a SKILL.md description stay in the third person, reading
+ * as a capability statement like "Extracts tables ..." rather than a
+ * first- or second-person sentence like "I extract ..." or "You can
+ * use ...". A standalone checker flags first- and second-person
+ * pronouns as whole words, after dropping the trigger clause that opens
+ * with "Use when" so a legitimate "Use when ..." phrase stays clean.
+ * Distinct from description-triggers, which checks that a "when" clause
+ * exists, and from description-length, which checks the size; this one
+ * checks the grammatical voice. Its prompt hands subtler voice
+ * judgement to the AI oracle.
+ */
+class DescriptionVoice {
+  constructor() {
+    this.id = 'description-voice';
+    this.pronoun = /\b(?:I|we|you|your|my|our)\b/giu;
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, flag a description written in first or second person and demand a third-person capability statement`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const pairs = document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: (keys) => keys
+    });
+    const found = pairs.filter((pair) => pair.key === 'description');
+    if (found.length === 0) {
+      return [];
+    }
+    return this.judge(found[0], uri);
+  }
+  judge(pair, uri) {
+    const text = pair.value.replace(/use when.*$/isu, '');
+    this.pronoun.lastIndex = 0;
+    const hit = this.pronoun.exec(text);
+    if (hit === null) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      `description must be third person, not "${hit[0]}"`,
+      new Region(uri, pair.row, 1)
+    )];
+  }
+}
+
+module.exports = DescriptionVoice;

package/src/rules/done.js

@@ -0,0 +1,53 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Done.
+ *
+ * Demands that a SKILL.md state a verifiable completion check, symmetric
+ * to the description trigger requirement. A standalone checker can only
+ * approximate: it scans headings and prose for a verification signal. Its
+ * prompt hands the deeper judgement to the AI oracle, which weighs whether
+ * the stated check is truly pass/fail testable rather than vague.
+ */
+class Done {
+  constructor() {
+    this.id = 'done';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether the stated completion check is actually pass/fail testable rather than a vague gesture toward being finished`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const signals = document.walk({
+      header: (text) => [/\b(?:verify|done|check|validation|acceptance)\b/iu.test(text)],
+      prose: (text) => [/\b(?:confirm|assert|verify|the test passes|tests pass|exit code|pass\/fail)\b/iu.test(text)],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (signals.some((signal) => signal)) {
+      return [];
+    }
+    return [
+      new Violation(
+        this.id,
+        'warning',
+        'SKILL.md never says how to verify completion',
+        new Region(uri, 1, 1)
+      )
+    ];
+  }
+}
+
+module.exports = Done;

package/src/rules/duplicate-section.js

@@ -0,0 +1,65 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const bare = (text) => text.replace(/^#{1,6}\s*/u, '').trim();
+
+const normalize = (text) => bare(text).toLowerCase().replace(/\s+/gu, ' ');
+
+/**
+ * DuplicateSection.
+ *
+ * Rejects two headings that carry the same name, so each section owns
+ * a distinct title. It collects every heading in order, normalizes it
+ * by case and whitespace, then flags the second and any later twin
+ * while leaving the first occurrence clean. Distinct from unique,
+ * which targets repeated prose instructions, and from short-sections,
+ * which targets heading length; this one targets repeated heading
+ * names. Its prompt stays empty since the check is fully
+ * deterministic.
+ */
+class DuplicateSection {
+  constructor() {
+    this.id = 'duplicate-section';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    const headers = document.walk({
+      header: (text, row) => [{text, row}],
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    return this.repeats(uri, headers);
+  }
+  repeats(uri, headers) {
+    const seen = new Set();
+    const found = [];
+    headers.forEach((header) => {
+      const norm = normalize(header.text);
+      if (seen.has(norm)) {
+        found.push(new Violation(
+          this.id,
+          'warning',
+          `duplicate section "${bare(header.text)}", give each section a distinct name`,
+          new Region(uri, header.row, 1)
+        ));
+      } else {
+        seen.add(norm);
+      }
+    });
+    return found;
+  }
+}
+
+module.exports = DuplicateSection;

package/src/rules/emoji.js

@@ -0,0 +1,60 @@
+/*
+ * 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');
+
+/**
+ * Emoji.
+ *
+ * Flags any emoji or decorative pictographic symbol that adds token
+ * noise without instruction. Inline code is masked first, so a fenced
+ * or inline example may keep a needed glyph. Distinct from homoglyph,
+ * which targets letters borrowed from other scripts; this one stays to
+ * pictographs, symbols, and dingbats only and never flags a foreign
+ * letter.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Emoji {
+  constructor() {
+    this.id = 'emoji';
+    this.glyph = /[\p{Extended_Pictographic}\u{2190}-\u{21FF}\u{2300}-\u{27BF}\u{2B00}-\u{2BFF}]/gu;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.scan(text, line, uri),
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const masked = mask(text);
+    const result = [];
+    let hit = this.glyph.exec(masked);
+    while (hit !== null) {
+      result.push(new Violation(
+        this.id,
+        'warning',
+        `decorative character "${hit[0]}" adds token noise, use plain text`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.glyph.exec(masked);
+    }
+    return result;
+  }
+}
+
+module.exports = Emoji;

package/src/rules/emphasis.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');
+
+/**
+ * Emphasis.
+ *
+ * Flags shouting that tries to force compliance through volume rather
+ * than clarity: a curated all-caps word like "IMPORTANT" or "NEVER", a
+ * run of two or more consecutive all-caps words, and repeated marks like
+ * "!!" or "!?". The model gains nothing from volume, so the emphasis is
+ * pure noise. A lone short acronym such as "JSON" or "AI" is left alone.
+ * Its prompt hands the borderline emphasis and reward framing the
+ * patterns miss to the AI oracle.
+ */
+class Emphasis {
+  constructor() {
+    this.id = 'emphasis';
+    this.shout = new Set(['IMPORTANT', 'ALWAYS', 'NEVER', 'MUST', 'CRITICAL', 'REQUIRED']);
+  }
+  prompt() {
+    return `${this.id}: flag emphatic shouting the patterns miss, including borderline all-caps and reward framing, since emphasis adds no instruction`;
+  }
+  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);
+    return this.punctuation(masked, line, uri).concat(this.shouting(masked, line, uri));
+  }
+  punctuation(masked, line, uri) {
+    const found = [];
+    const regex = /!{2,}|!\?|\?!/gu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(this.flag(hit[0], line, hit.index, uri));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+  shouting(masked, line, uri) {
+    const found = [];
+    const regex = /[A-Z]{2,}(?:\s+[A-Z]{2,})*/gu;
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      const tokens = hit[0].split(/\s+/u);
+      const loud = tokens.length > 1
+        ? tokens.some((token) => token.length >= 5 || this.shout.has(token))
+        : this.shout.has(tokens[0]);
+      if (loud) {
+        found.push(this.flag(hit[0], line, hit.index, uri));
+      }
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+  flag(marker, line, index, uri) {
+    return new Violation(
+      this.id,
+      'warning',
+      `emphasis marker "${marker}" adds no instruction, state it plainly`,
+      new Region(uri, line, index + 1)
+    );
+  }
+}
+
+module.exports = Emphasis;

package/src/rules/example-format.js

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Example format.
+ *
+ * A few-shot demonstration regulates the shape of the output more
+ * strongly than any prose, so an example that disagrees with the
+ * declared format teaches the agent the wrong shape. This rule ties the
+ * `example` and `format` rules together by checking their consistency:
+ * when one SKILL.md both shows an example and declares an output format,
+ * the two must agree. The mismatch hides between two distant fragments,
+ * so this check is pure judgement: prompt() hands the comparison to the
+ * AI oracle and violations() finds nothing on its own.
+ */
+class ExampleFormat {
+  constructor() {
+    this.id = 'example-format';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md that both shows an example and declares an output format, judge whether the example conforms to the declared format and flag any mismatch`;
+  }
+  violations() {
+    return [];
+  }
+}
+
+module.exports = ExampleFormat;

package/src/rules/example.js

@@ -0,0 +1,60 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Example.
+ *
+ * Demands that a SKILL.md demonstrate, not only describe. A skill that
+ * states rules in prose alone leaves the agent to infer the exact shape
+ * of correct output, while a single worked example is one of the most
+ * reliable levers in prompt engineering. A standalone checker passes the
+ * skill that carries at least one fenced code block or an explicit
+ * "Example" section heading, and flags the one that has neither. Its
+ * prompt hands the deeper judgement to the AI oracle, which weighs
+ * whether a present code block is truly illustrative.
+ */
+class Example {
+  constructor() {
+    this.id = 'example';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether a present code block is a genuine worked example rather than a stray snippet, and flag a skill that only describes without demonstrating`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const hints = document.walk({
+      header: (text) => this.heading(text),
+      prose: () => [],
+      snippet: () => ['snippet'],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (hints.length > 0) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'SKILL.md has no example, add a worked input/output sample',
+      new Region(uri, 1, 1)
+    )];
+  }
+  heading(text) {
+    if (/^#{1,6}\s+examples?\b/iu.test(text)) {
+      return [this.id];
+    }
+    return [];
+  }
+}
+
+module.exports = Example;