@yegor256/dogent 0.9.1 → 0.11.0

package/src/rules/external-link.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * ExternalLink.
+ *
+ * Flags a bare http(s):// URL sitting in prose or a bullet item, where
+ * the page behind it may rot or inject hidden instructions. Durable
+ * guidance belongs inlined, not fetched at run time. A URL inside
+ * inline code or a fenced snippet is exempt, since those are examples.
+ * Distinct from dead-import, which targets local @path imports; this
+ * one complements untrusted and stale.
+ */
+class ExternalLink {
+  constructor() {
+    this.id = 'external-link';
+  }
+  prompt() {
+    return `${this.id}: judge whether an external link is load-bearing, and flag durable guidance that should be inlined 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 = /(?:https?:\/\/)\S+/giu;
+    const masked = mask(text);
+    let hit = regex.exec(masked);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'warning',
+        'external URL may rot or inject, encode durable guidance instead',
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(masked);
+    }
+    return found;
+  }
+}
+
+module.exports = ExternalLink;

package/src/rules/fence-language.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');
+
+/**
+ * FenceLanguage.
+ *
+ * Demands that every fenced code block declare a language right after
+ * its opening fence. A bare fence of backticks or tildes with no info
+ * string leaves readers and tooling guessing at the snippet's syntax,
+ * so it earns a warning. A fence that names a language stays clean.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class FenceLanguage {
+  constructor() {
+    this.id = 'fence-language';
+    this.fence = /^\s*(?:```|~~~)\s*(?<lang>\S*)/u;
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: () => [],
+      snippet: (content, row) => this.scan(content, row, uri),
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(content, row, uri) {
+    const [first] = content.split('\n');
+    const hit = this.fence.exec(first);
+    if (hit !== null && hit.groups.lang !== '') {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'fenced block has no language tag, declare one',
+      new Region(uri, row, 1)
+    )];
+  }
+}
+
+module.exports = FenceLanguage;

package/src/rules/format.js

@@ -0,0 +1,68 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Format.
+ *
+ * Demands that a SKILL.md which produces output pin down that output's
+ * shape. Structured-output generation grows far more reliable when the
+ * expected format is declared and shown, while leaving it implicit
+ * produces brittle, drifting output. A standalone checker flags a skill
+ * whose instructions describe producing output (verbs like "produce",
+ * "output", "return", "generate", "write", "emit") yet no section or
+ * snippet declares the output shape. This is distinct from the example
+ * rule: an example shows one case, a format spec defines the contract.
+ * Its prompt asks the AI oracle whether the declared format is concrete
+ * enough to be machine-checkable.
+ */
+class Format {
+  constructor() {
+    this.id = 'format';
+  }
+  prompt() {
+    return `${this.id}: in a SKILL.md, judge whether the declared output format is concrete and machine-checkable, and flag a generating skill that pins down no format`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    if (uri.replace(/^.*\//u, '') !== 'SKILL.md') {
+      return [];
+    }
+    const heading = /^#{1,6}\s+.*\b(?:format|schema|structure|output)\b/iu;
+    const verb = /\b(?:produces?|outputs?|returns?|generates?|writes?|emits?)\b/iu;
+    const signals = document.walk({
+      header: (text) => {
+        if (heading.test(text)) {
+          return ['declared'];
+        }
+        return [];
+      },
+      prose: (text) => {
+        if (verb.test(text)) {
+          return ['generates'];
+        }
+        return [];
+      },
+      snippet: () => ['declared'],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+    if (!signals.includes('generates') || signals.includes('declared')) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'SKILL.md generates output but never declares its format',
+      new Region(uri, 1, 1)
+    )];
+  }
+}
+
+module.exports = Format;

package/src/rules/hidden-char.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');
+
+/**
+ * HiddenChar.
+ *
+ * Demands that every line carry only visible characters, rejecting any
+ * invisible or control codepoint that hides inside the text. Scans every
+ * fragment, including snippets, because a zero-width space, a bidirectional
+ * override, or a variation selector tucked into code is just as dangerous as
+ * one tucked into prose. Flags zero-width characters, bidi controls, and
+ * variation selectors, naming each by its hex codepoint so it can be deleted.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class HiddenChar {
+  constructor() {
+    this.id = 'hidden-char';
+    this.hidden = /[\u200B-\u200D\uFEFF\u202A-\u202E\u2066-\u2069\uFE00-\uFE0F\u{E0100}-\u{E01EF}]/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: (text, line) => this.scan(text, line, uri),
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const found = [];
+    this.hidden.lastIndex = 0;
+    let hit = this.hidden.exec(text);
+    while (hit !== null) {
+      const hex = hit[0].codePointAt(0).toString(16).toUpperCase();
+      const code = hex.padStart(4, '0');
+      found.push(new Violation(
+        this.id,
+        'error',
+        `invisible character U+${code} found, delete it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.hidden.exec(text);
+    }
+    return found;
+  }
+}
+
+module.exports = HiddenChar;

package/src/rules/homoglyph.js

@@ -0,0 +1,82 @@
+/*
+ * 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');
+
+/**
+ * Homoglyph.
+ *
+ * Rejects mixed-script look-alike characters that masquerade as plain
+ * ASCII. A token mixing an ASCII Latin letter with a confusable from
+ * Cyrillic, Greek, or full-width Latin reads as one word yet hides a
+ * foreign codepoint, so it slips past humans while breaking tools. The
+ * check flags every such confusable character at its own column. Inline
+ * code is masked first, so a deliberately quoted example stays clean.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class Homoglyph {
+  constructor() {
+    this.id = 'homoglyph';
+    this.latin = /[A-Za-z]/u;
+    this.confusable = /[Ѐ-ӿͰ-Ͽ＀-￯]/u;
+  }
+  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 clean = mask(text);
+    const result = [];
+    const token = /\S+/gu;
+    let match = token.exec(clean);
+    while (match !== null) {
+      const [word] = match;
+      if (this.latin.test(word) && this.confusable.test(word)) {
+        this.flag(word, match.index).forEach((spot) => {
+          result.push(new Violation(
+            this.id,
+            'error',
+            `mixed-script character "${spot.char}" (U+${spot.point}) found, use plain ASCII`,
+            new Region(uri, line, spot.column)
+          ));
+        });
+      }
+      match = token.exec(clean);
+    }
+    return result;
+  }
+  flag(word, start) {
+    const spots = [];
+    [...word].forEach((char, offset) => {
+      if (!this.confusable.test(char)) {
+        return;
+      }
+      const point = char
+        .codePointAt(0)
+        .toString(16)
+        .toUpperCase()
+        .padStart(4, '0');
+      spots.push({char, point, column: start + offset + 1});
+    });
+    return spots;
+  }
+}
+
+module.exports = Homoglyph;

package/src/rules/index.js

@@ -21,6 +21,7 @@ const NameMatchesDir = require('./name-matches-dir');
 const Polite = require('./polite');
 const Unfinished = require('./unfinished');
 const Crowded = require('./crowded');
+const Budget = require('./budget');
 const DescriptionTriggers = require('./description-triggers');
 const Atomic = require('./atomic');
 const Hedging = require('./hedging');
@@ -29,6 +30,45 @@ const Unique = require('./unique');
 const Consistent = require('./consistent');
 const Simple = require('./simple');
 const SectionLevel = require('./section-level');
+const Format = require('./format');
+const Untrusted = require('./untrusted');
+const Ordered = require('./ordered');
+const Emphasis = require('./emphasis');
+const Persona = require('./persona');
+const Concise = require('./concise');
+const Example = require('./example');
+const Referential = require('./referential');
+const Vague = require('./vague');
+const Positive = require('./positive');
+const Done = require('./done');
+const Terms = require('./terms');
+const Jargon = require('./jargon');
+const PseudoHeading = require('./pseudo-heading');
+const Stale = require('./stale');
+const ToolClarity = require('./tool-clarity');
+const CounterExample = require('./counter-example');
+const Rationale = require('./rationale');
+const SelfContained = require('./self-contained');
+const Quantifier = require('./quantifier');
+const WeakVerb = require('./weak-verb');
+const Default = require('./default');
+const MetaReference = require('./meta-reference');
+const AmbiguousOr = require('./ambiguous-or');
+const ExternalLink = require('./external-link');
+const Conditional = require('./conditional');
+const Transition = require('./transition');
+const Placement = require('./placement');
+const InlineCode = require('./inline-code');
+const Emoji = require('./emoji');
+const Homoglyph = require('./homoglyph');
+const DuplicateSection = require('./duplicate-section');
+const DescriptionVoice = require('./description-voice');
+const ExampleFormat = require('./example-format');
+const DescriptionLength = require('./description-length');
+const Scope = require('./scope');
+const HiddenChar = require('./hidden-char');
+const Units = require('./units');
+const FenceLanguage = require('./fence-language');
 
 module.exports = () => [
   new Grouped(),
@@ -37,6 +77,7 @@ module.exports = () => [
   new SectionLevel(),
   new LineLength(80),
   new TokenCount(4000),
+  new Concise(200),
   new NoArticles(),
   new Command(),
   new Punctuation(),
@@ -44,14 +85,53 @@ module.exports = () => [
   new Redundant(),
   new Consistent(),
   new Simple(),
+  new Referential(),
   new NameMatchesDir(),
   new Polite(),
   new Unfinished(),
   new Crowded(10),
+  new Budget(60),
   new DescriptionTriggers(),
+  new Example(),
+  new Format(),
   new Atomic(),
+  new Ordered(),
   new Hedging(),
+  new Vague(),
+  new ToolClarity(),
   new Passive(),
+  new Untrusted(),
+  new Emphasis(),
+  new Persona(),
+  new Positive(),
+  new Done(),
+  new Terms(),
+  new Jargon(),
+  new PseudoHeading(),
+  new Stale(),
+  new CounterExample(),
+  new Rationale(),
+  new SelfContained(),
+  new Quantifier(),
+  new WeakVerb(),
+  new Default(),
+  new MetaReference(),
+  new AmbiguousOr(),
+  new ExternalLink(),
+  new Conditional(),
+  new Transition(),
+  new Placement(),
+  new InlineCode(),
+  new Emoji(),
+  new Homoglyph(),
+  new DuplicateSection(),
+  new DescriptionVoice(),
+  new ExampleFormat(),
+  new DescriptionLength(),
+  new Scope(),
+  new HiddenChar(),
+  new Units(),
+  new FenceLanguage(),
   new Unique(),
   new Frontmatter(
     'SKILL.md',

package/src/rules/inline-code.js

@@ -0,0 +1,79 @@
+/*
+ * 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');
+
+const PATTERNS = [
+  /\b(?:npm|npx|node|git|eslint|mocha|yarn|pnpm|cd|rm|mkdir|chmod|cat|sed|grep|curl|docker)\s+[\w./-]+/gu,
+  /(?<![\w/.@])[\w-]+(?:\/[\w.-]+)+/gu,
+  /(?<![\w/.@])[\w-]+\.(?:js|ts|jsx|tsx|json|md|ya?ml|sh|py|rb|go|rs|toml|cfg|lock|txt|xml|html|css)\b/gu,
+  /(?<![\w-])(?:--[A-Za-z][\w-]*|-[A-Za-z])(?![\w])/gu
+];
+
+/**
+ * InlineCode.
+ *
+ * When a command, path, filename, or flag sits bare in prose, the model
+ * cannot cleanly tell the literal token from the surrounding words and
+ * may reword or reformat it. Markdown inline code marks such a token as
+ * literal, and consistent code-versus-prose marking measurably lowers
+ * misinterpretation. This standalone check flags a bare literal — a
+ * slashed path, a filename carrying a known extension, a CLI flag, or a
+ * known shell command followed by an argument — once its inline-code
+ * spans are masked away, so an already-backticked literal passes. It
+ * leaves @-imports to the dead-import rule. Its prompt hands borderline
+ * literals to the AI oracle.
+ */
+class InlineCode {
+  constructor() {
+    this.id = 'inline-code';
+  }
+  prompt() {
+    return `${this.id}: flag a bare literal token (command, path, filename, or flag) that should be wrapped in backticks, judging borderline cases`;
+  }
+  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 spans = [];
+    PATTERNS.forEach((pattern) => {
+      let hit = pattern.exec(masked);
+      while (hit !== null) {
+        spans.push({token: hit[0], from: hit.index, to: hit.index + hit[0].length});
+        hit = pattern.exec(masked);
+      }
+    });
+    return InlineCode.prune(spans).map((span) => new Violation(
+      this.id,
+      'warning',
+      `literal "${span.token}" must be wrapped in backticks`,
+      new Region(uri, line, span.from + 1)
+    ));
+  }
+  static prune(spans) {
+    const ordered = spans.slice().sort((one, two) => one.from - two.from || two.to - one.to);
+    const kept = [];
+    ordered.forEach((span) => {
+      if (!kept.some((other) => span.from >= other.from && span.to <= other.to)) {
+        kept.push(span);
+      }
+    });
+    return kept;
+  }
+}
+
+module.exports = InlineCode;

package/src/rules/jargon.js

@@ -0,0 +1,115 @@
+/*
+ * 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');
+
+const ALLOWLIST = new Set([
+  'AI',
+  'CI',
+  'CD',
+  'CLI',
+  'API',
+  'URL',
+  'URI',
+  'HTTP',
+  'HTTPS',
+  'JSON',
+  'YAML',
+  'XML',
+  'HTML',
+  'CSS',
+  'SQL',
+  'ID',
+  'OK',
+  'OS',
+  'IO',
+  'NPM',
+  'PR',
+  'MIT',
+  'SARIF',
+  'SKILL',
+  'CLAUDE'
+]);
+
+const initials = (gloss) => (gloss.match(/[A-Za-z]+/gu) || [])
+  .map((word) => word[0].toUpperCase())
+  .join('');
+
+const defined = (masked) => {
+  const found = new Set();
+  const regex = /\b(?<acronym>[A-Z]{2,})\s*\(|\((?<gloss>[^)]+)\)/gu;
+  let hit = regex.exec(masked);
+  while (hit !== null) {
+    if (hit.groups.acronym) {
+      found.add(hit.groups.acronym);
+    } else {
+      found.add(initials(hit.groups.gloss));
+    }
+    hit = regex.exec(masked);
+  }
+  return found;
+};
+
+const undefining = (acronym, scope) => !scope.known.has(acronym) &&
+  !ALLOWLIST.has(acronym);
+
+/**
+ * Jargon.
+ *
+ * Flags an acronym that lands in prose without ever being expanded. An
+ * acronym counts as defined when the document, anywhere, follows it with
+ * a parenthetical gloss, as in "RBAC (role-based access control)", or when
+ * a parenthetical's word initials spell it, as in "AAA pattern
+ * (Arrange-Act-Assert)", so a single expansion licenses every later
+ * mention. Well-known acronyms sit
+ * in a built-in allowlist and pass untouched. Only the first unexpanded
+ * occurrence of each acronym is reported. Its prompt hands non-acronym
+ * domain jargon, the rare nouns a reader cannot parse, to the AI oracle.
+ */
+class Jargon {
+  constructor() {
+    this.id = 'jargon';
+  }
+  prompt() {
+    return `${this.id}: flag non-acronym domain jargon, rare nouns a fresh reader cannot parse, and ask for a plain-word definition on first use`;
+  }
+  violations(document) {
+    const uri = document.uri();
+    const known = defined(mask(document.text()));
+    const seen = new Set();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, {uri, known, seen}),
+      snippet: () => [],
+      bullets: () => [],
+      frontmatter: () => []
+    });
+  }
+  scan(text, line, scope) {
+    const hits = [...mask(text).matchAll(/\b[A-Z]{2,}\b/gu)];
+    return hits.reduce((found, hit) => {
+      const [acronym] = hit;
+      const novel = !scope.seen.has(acronym) && undefining(acronym, scope);
+      scope.seen.add(acronym);
+      return novel
+        ? found.concat(this.flag(acronym, new Region(scope.uri, line, hit.index + 1)))
+        : found;
+    }, []);
+  }
+  flag(acronym, region) {
+    return new Violation(
+      this.id,
+      'warning',
+      `acronym "${acronym}" never expanded, define it on first use`,
+      region
+    );
+  }
+}
+
+module.exports = Jargon;

package/src/rules/meta-reference.js

@@ -0,0 +1,57 @@
+/*
+ * 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');
+
+/**
+ * MetaReference.
+ *
+ * Flags self-referential framing of the model or the document, such as
+ * "as an AI", "you are a model", "this prompt", or "these instructions".
+ * Such framing narrates the setup instead of issuing a command, so it
+ * adds no instruction and earns deletion. Distinct from persona, which
+ * targets role assignment like "Act as a reviewer"; this one targets
+ * the model talking about itself or the document talking about itself.
+ */
+class MetaReference {
+  constructor() {
+    this.id = 'meta-reference';
+    this.phrase = /\b(?:as an ai|as a language model|you are an ai|you are a model|this prompt|these instructions|this manifesto|the system prompt)\b/giu;
+  }
+  prompt() {
+    return `${this.id}: flag self-referential framing of the model or document 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 out = [];
+    let hit = this.phrase.exec(masked);
+    while (hit !== null) {
+      out.push(new Violation(
+        this.id,
+        'warning',
+        `meta self-reference "${hit[0]}" issues no command, delete it`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = this.phrase.exec(masked);
+    }
+    return out;
+  }
+}
+
+module.exports = MetaReference;