@yegor256/dogent 0.7.8 → 0.9.0

package/README.md

@@ -64,6 +64,7 @@ The command exits with a non-zero status when problems are found,
 - Every line must be an instruction.
 - Instructions must be grouped in sections.
 - Section names must be short, 1-3 words.
+- Every section must be a level-2 (`##`) heading, below the lone `#` title.
 - Every line must be no longer than 80 symbols.
 - The whole file must stay under 4000 tokens.
 - Every line must sound like a command.

package/package.json

@@ -40,7 +40,7 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.7.8",
+  "version": "0.9.0",
   "dependencies": {
     "minimist": "^1.2.8"
   }

package/src/args.js

@@ -13,13 +13,15 @@ const minimist = require('minimist');
  * The command-line arguments handed to dogent. It leans on minimist to split
  * the raw argv into recognized options and the manifesto paths that remain.
  * The `--sarif` flag switches the report to SARIF, while `--offline` forbids
- * any talk to the LLM even when a token sits in the environment. Everything
- * after a `--` separator counts as a path, never as an option.
+ * any talk to the LLM even when a token sits in the environment. The `--help`
+ * flag, also spelled `-h`, asks for the usage banner. The `--version` flag
+ * asks for the release number. Everything after a `--` separator counts as a
+ * path, never as an option.
  */
 class Args {
-  constructor(argv, flags = ['sarif', 'offline']) {
+  constructor(argv, flags = ['sarif', 'offline', 'help', 'version']) {
     this.flags = flags;
-    this.parsed = minimist(argv, {boolean: flags, '--': true});
+    this.parsed = minimist(argv, {boolean: flags, alias: {help: 'h'}, '--': true});
   }
   sarif() {
     return this.parsed.sarif === true;
@@ -27,12 +29,18 @@ class Args {
   offline() {
     return this.parsed.offline === true;
   }
+  help() {
+    return this.parsed.help === true;
+  }
+  version() {
+    return this.parsed.version === true;
+  }
   paths() {
     return this.parsed._.concat(this.parsed['--']).map(String);
   }
   unknown() {
     return Object.keys(this.parsed)
-      .filter((key) => key !== '_' && key !== '--' && !this.flags.includes(key))
+      .filter((key) => key !== '_' && key !== '--' && key !== 'h' && !this.flags.includes(key))
       .map((key) => `${key.length === 1 ? '-' : '--'}${key}`);
   }
 }

package/src/dogent.js

@@ -14,19 +14,37 @@ const Sources = require('./sources');
 const Openai = require('./openai');
 const Oracle = require('./oracle');
 const Usage = require('./usage');
+const version = require('./version');
 const rules = require('./rules');
 
 const args = new Args(process.argv.slice(2));
 const sarif = args.sarif();
+const banner = 'Usage: dogent [--sarif] [--offline] <file.md|dir>...';
+if (args.version()) {
+  process.stdout.write(`${version}\n`);
+  process.exit(0);
+}
+if (args.help()) {
+  process.stdout.write(
+    `${banner}\n\n` +
+    'Lint agentic manifesto files like SKILL.md and CLAUDE.md.\n\n' +
+    'Options:\n' +
+    '  --sarif    render the report as SARIF JSON\n' +
+    '  --offline  never call the LLM, even when a token exists\n' +
+    '  --version  show the version and exit\n' +
+    '  --help     show this help and exit\n'
+  );
+  process.exit(0);
+}
 const unknown = args.unknown();
 if (unknown.length > 0) {
   process.stderr.write(`Unknown option: ${unknown[0]}\n`);
-  process.stderr.write('Usage: dogent [--sarif] [--offline] <file.md|dir>...\n');
+  process.stderr.write(`${banner}\n`);
   process.exit(2);
 }
 const paths = args.paths();
 if (paths.length === 0) {
-  process.stderr.write('Usage: dogent [--sarif] [--offline] <file.md|dir>...\n');
+  process.stderr.write(`${banner}\n`);
   process.exit(2);
 }
 const scanned = new Sources(paths).files();

package/src/rules/atomic.js

@@ -39,7 +39,8 @@ class Atomic {
   }
   judge(text, line, uri) {
     const clean = text.replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '').trimEnd();
-    if (!/[.!?]\s+\S/u.test(clean) && !/;/u.test(clean)) {
+    const masked = clean.replace(/\b(?:e\.g|i\.e|etc)\./giu, (match) => match.replace(/\./gu, ' '));
+    if (!/[.!?]\s+\S/u.test(masked) && !/;/u.test(masked)) {
       return [];
     }
     return [new Violation(

package/src/rules/index.js

@@ -28,11 +28,13 @@ const Passive = require('./passive');
 const Unique = require('./unique');
 const Consistent = require('./consistent');
 const Simple = require('./simple');
+const SectionLevel = require('./section-level');
 
 module.exports = () => [
   new Grouped(),
   new Empty(),
   new ShortSections(),
+  new SectionLevel(),
   new LineLength(80),
   new TokenCount(4000),
   new NoArticles(),

package/src/rules/section-level.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');
+
+/**
+ * SectionLevel.
+ *
+ * Demands that every section sit at the second level, marked by two
+ * hashes. A lone top-level title may open the file, but any later
+ * first-level heading or any deeper sub-heading breaks the flat shape
+ * a manifesto must keep.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
+ */
+class SectionLevel {
+  constructor() {
+    this.id = 'section-level';
+  }
+  prompt() {
+    return '';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document
+      .walk({
+        header: (text, line, depth) => [{line, depth}],
+        prose: () => [],
+        snippet: () => [],
+        bullets: () => [],
+        frontmatter: () => []
+      })
+      .map((header, index) => this.leveled(header, index, uri))
+      .flat();
+  }
+  leveled(header, index, uri) {
+    if (header.depth === 2 || header.depth === 1 && index === 0) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `section must be a level-2 heading, found ${header.depth}`,
+      new Region(uri, header.line, 1)
+    )];
+  }
+}
+
+module.exports = SectionLevel;

package/src/rules/simple.js

@@ -8,12 +8,31 @@
 const Violation = require('../violation');
 const Region = require('../region');
 
+/**
+ * Counts the commas that sit inside a coordinated `A, B, or C` list run,
+ * so an enumeration can be discounted before clause commas are weighed.
+ * @param {string} text The line to scan
+ * @return {number} The number of commas belonging to coordinated lists
+ */
+const listCommas = function listCommas(text) {
+  const runs = text.match(/(?:[^,]+,\s*)+(?:or|and)\b/giu);
+  if (runs === null) {
+    return 0;
+  }
+  return runs.reduce((sum, run) => {
+    const inner = run.match(/,/gu);
+    return sum + (inner === null ? 0 : inner.length);
+  }, 0);
+};
+
 /**
  * Simple.
  *
  * Demands simple grammar over ambiguity. A standalone checker can only
  * guess: it counts commas and conjunctions to flag lines that pile up
- * clauses. Its prompt hands the subtler tangle judgement to the oracle,
+ * clauses. Commas inside a coordinated `A, B, or C` list are discounted
+ * first, so a lone enumeration sitting in one clause does not read as
+ * tangled. Its prompt hands the subtler tangle judgement to the oracle,
  * which weighs true clause depth rather than counting punctuation.
  */
 class Simple {
@@ -36,8 +55,9 @@ class Simple {
   judge(text, line, uri) {
     const commas = text.match(/,/gu);
     const commaCount = commas === null ? 0 : commas.length;
+    const clauseCommas = commaCount - listCommas(text);
     const hasConjunction = /\b(?:if|when|unless|because|although|while)\b/iu.test(text);
-    const tangled = hasConjunction && commaCount >= 2;
+    const tangled = hasConjunction && clauseCommas >= 2;
     if (!tangled) {
       return [];
     }

package/src/usage.js

@@ -45,7 +45,7 @@ class Usage {
     return this.sent / 1e6 * price.input + this.received / 1e6 * price.output;
   }
   text() {
-    return `OpenAI: ${this.model}, ${this.sent} sent, ${this.received} received, ~${(this.cost() * 100).toFixed(2)}¢`;
+    return `OpenAI: ${this.model}, ${this.sent}+${this.received} tokens, ${(this.cost() * 100).toFixed(2)}¢`;
   }
 }
 

package/src/version.js

@@ -0,0 +1,16 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Version.
+ *
+ * The current release of dogent, replaced on every release by rultor.
+ * The default `0.9.0` marks an unreleased build straight from source.
+ */
+const version = '0.9.0';
+
+module.exports = version;