@yegor256/dogent 0.6.0 → 0.6.2

package/README.md

@@ -29,7 +29,7 @@ In short: `agnix` lints the harness, `dogent` lints the prompt.
 Run it on any manifesto file, no installation required:
 
 ```bash
-npx @yegor256/dogent@0.5.1 CLAUDE.md
+npx @yegor256/dogent@0.6.0 CLAUDE.md
 ```
 
 Lint several files at once:
@@ -90,6 +90,9 @@ It sends the manifesto together with one instruction per rule,
   then prints any violation the model reports for ambiguity,
   weak phrasing, and instructions that only pretend to be commands.
 The model defaults to `gpt-4o-mini`; override it with `OPENAI_MODEL`.
+After the report, `dogent` prints a one-line usage summary to standard error,
+  naming the model, the tokens sent and received, and an estimated cost,
+  for example `OpenAI: gpt-4o-mini, 1234 sent, 567 received, ~$0.0005`.
 
 ```bash
 export OPENAI_API_KEY=...
@@ -150,7 +153,7 @@ Reference `dogent` as a remote hook in `.pre-commit-config.yaml`:
 ```yaml
 repos:
   - repo: https://github.com/yegor256/dogent
-    rev: 0.5.1
+    rev: 0.6.0
     hooks:
       - id: dogent
 ```

package/package.json

@@ -40,5 +40,8 @@
     "lint": "eslint .",
     "test": "mocha 'test/**/*.js' --timeout 60000"
   },
-  "version": "0.6.0"
+  "version": "0.6.2",
+  "dependencies": {
+    "minimist": "^1.2.8"
+  }
 }

package/src/args.js

@@ -5,32 +5,35 @@
 
 'use strict';
 
+const minimist = require('minimist');
+
 /**
  * Args.
  *
- * The command-line arguments handed to dogent. It splits 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.
+ * 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.
  */
 class Args {
-  constructor(argv, flags = ['--sarif', '--offline']) {
-    this.argv = argv;
+  constructor(argv, flags = ['sarif', 'offline']) {
     this.flags = flags;
+    this.parsed = minimist(argv, {boolean: flags, '--': true});
   }
   sarif() {
-    return this.argv.includes('--sarif');
+    return this.parsed.sarif === true;
   }
   offline() {
-    return this.argv.includes('--offline');
+    return this.parsed.offline === true;
   }
   paths() {
-    return this.argv.filter((arg) => !arg.startsWith('-'));
+    return this.parsed._.concat(this.parsed['--']).map(String);
   }
   unknown() {
-    return this.argv.filter(
-      (arg) => arg.startsWith('-') && !this.flags.includes(arg)
-    );
+    return Object.keys(this.parsed)
+      .filter((key) => key !== '_' && key !== '--' && !this.flags.includes(key))
+      .map((key) => `${key.length === 1 ? '-' : '--'}${key}`);
   }
 }
 

package/src/dogent.js

@@ -13,6 +13,7 @@ const Report = require('./report');
 const Sources = require('./sources');
 const Openai = require('./openai');
 const Oracle = require('./oracle');
+const Usage = require('./usage');
 const rules = require('./rules');
 
 const args = new Args(process.argv.slice(2));
@@ -41,27 +42,43 @@ documents.forEach((document) => {
   });
 });
 const key = process.env.OPENAI_API_KEY;
+const audit = async (docs) => {
+  const oracle = new Oracle(
+    rules(),
+    new Openai(
+      key,
+      process.env.OPENAI_MODEL || 'gpt-4o-mini',
+      (url, options) => globalThis.fetch(url, options)
+    )
+  );
+  const replies = await Promise.all(docs.map((doc) => oracle.violations(doc)));
+  return replies.reduce(
+    (acc, reply) => ({
+      extra: acc.extra.concat(reply.found),
+      usage: acc.usage.plus(reply.usage)
+    }),
+    {extra: [], usage: new Usage('', 0, 0)}
+  );
+};
+const finish = (usage) => {
+  const report = new Report('dogent', found);
+  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
+  if (usage !== null) {
+    process.stderr.write(`${usage.text()}\n`);
+  }
+  process.exit(report.count() > 0 ? 1 : 0);
+};
 (async () => {
+  let usage = null;
   if (found.length === 0 && key && !args.offline()) {
     try {
-      const oracle = new Oracle(
-        rules(),
-        new Openai(
-          key,
-          process.env.OPENAI_MODEL || 'gpt-4o-mini',
-          (url, options) => globalThis.fetch(url, options)
-        )
-      );
-      const extra = await Promise.all(
-        documents.map((document) => oracle.violations(document))
-      );
-      extra.forEach((bag) => bag.forEach((violation) => found.push(violation)));
+      const result = await audit(documents);
+      result.extra.forEach((violation) => found.push(violation));
+      ({usage} = result);
     } catch (error) {
       process.stderr.write(`AI verification failed: ${error.message}\n`);
       process.exit(2);
     }
   }
-  const report = new Report('dogent', found);
-  process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
-  process.exit(report.count() > 0 ? 1 : 0);
+  finish(usage);
 })();

package/src/openai.js

@@ -5,11 +5,14 @@
 
 'use strict';
 
+const Usage = require('./usage');
+
 /**
  * Openai.
  *
  * A thin adapter over the OpenAI chat-completions endpoint. Sends one
- * prompt, demands a JSON object back, and returns the assistant text.
+ * prompt, demands a JSON object back, and returns the assistant text
+ * paired with a Usage tally of the model and the tokens it consumed.
  * The transport is injected so the class runs in tests without a socket.
  */
 class Openai {
@@ -38,7 +41,16 @@ class Openai {
     if (!response.ok) {
       throw new Error(`OpenAI request rejected with status ${response.status}`);
     }
-    return (await response.json()).choices[0].message.content;
+    const body = await response.json();
+    const usage = body.usage || {};
+    return {
+      content: body.choices[0].message.content,
+      usage: new Usage(
+        this.model,
+        usage.prompt_tokens || 0,
+        usage.completion_tokens || 0
+      )
+    };
   }
 }
 

package/src/oracle.js

@@ -13,7 +13,8 @@ const Answer = require('./answer');
  *
  * The AI second opinion. Wraps the rules and a chat endpoint, builds one
  * prompt from a document, asks the endpoint, and parses the reply into
- * violations. Mirrors a rule, but consults a model instead of guessing.
+ * violations paired with the token usage the model reported. Mirrors a
+ * rule, but consults a model instead of guessing.
  */
 class Oracle {
   constructor(rules, chat) {
@@ -21,9 +22,11 @@ class Oracle {
     this.chat = chat;
   }
   async violations(document) {
-    return new Answer(
-      await this.chat.answer(new Prompt(this.rules, document).text())
-    ).violations();
+    const reply = await this.chat.answer(new Prompt(this.rules, document).text());
+    return {
+      found: new Answer(reply.content).violations(),
+      usage: reply.usage
+    };
   }
 }
 

package/src/rules/empty.js

@@ -15,13 +15,16 @@ const Region = require('../region');
  * A heading is empty when it is immediately followed by another
  * heading or by end-of-file — no prose, bullets, or snippet sits
  * between them.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class Empty {
   constructor() {
     this.id = 'empty';
   }
   prompt() {
-    return `${this.id}: flag any section heading that carries no instructions beneath it`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/index.js

@@ -15,6 +15,7 @@ const Command = require('./command');
 const Punctuation = require('./punctuation');
 const Frontmatter = require('./frontmatter');
 const DeadImport = require('./dead-import');
+const Redundant = require('./redundant');
 
 module.exports = () => [
   new Grouped(),
@@ -26,6 +27,7 @@ module.exports = () => [
   new Command(),
   new Punctuation(),
   new DeadImport(),
+  new Redundant(),
   new Frontmatter(
     'SKILL.md',
     ['name', 'description'],

package/src/rules/line-length.js

@@ -13,6 +13,9 @@ const Region = require('../region');
  *
  * Demands that every instruction and every heading stay within a
  * maximum width. Code snippets are exempt, since code is not prose.
+ *
+ * The check is standalone and deterministic, so prompt() returns an
+ * empty string and the AI oracle never re-checks this rule.
  */
 class LineLength {
   constructor(max) {
@@ -20,7 +23,7 @@ class LineLength {
     this.max = max;
   }
   prompt() {
-    return `${this.id}: flag any instruction too wordy to grasp in a single read`;
+    return '';
   }
   violations(document) {
     const uri = document.uri();

package/src/rules/redundant.js

@@ -0,0 +1,92 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+const PHRASES = [
+  'be helpful',
+  'be helpful and accurate',
+  'be accurate',
+  'be concise',
+  'be clear',
+  'be polite',
+  'be professional',
+  'write clean code',
+  'write good code',
+  'write readable code',
+  'write maintainable code',
+  'follow best practices',
+  'follow industry best practices',
+  'use best practices',
+  'apply best practices',
+  'use meaningful variable names',
+  'use descriptive variable names',
+  'use good variable names',
+  'handle errors properly',
+  'handle errors gracefully',
+  'handle exceptions properly',
+  'avoid bugs',
+  'avoid mistakes',
+  'think step by step',
+  'do your best',
+  'try your best',
+  'pay attention to detail'
+];
+
+/**
+ * Redundant.
+ *
+ * Flags a line that restates default model behavior, like
+ * "Be helpful and accurate" or "Write clean code". Such filler
+ * burns the context budget and drowns the project-specific
+ * guidance the manifesto exists to carry.
+ *
+ * @todo #15:60min Promote the standalone heuristic into a
+ *  proper AI-oracle check when `OPENAI_API_KEY` is present, so
+ *  redundancy detection covers paraphrases beyond the curated
+ *  blacklist below. The hybrid pattern from `src/rules/command.js`
+ *  is the model: keep the deterministic check as the default,
+ *  let the oracle catch the rest.
+ */
+class Redundant {
+  constructor(phrases = PHRASES) {
+    this.id = 'redundant';
+    this.phrases = phrases;
+  }
+  prompt() {
+    return `${this.id}: flag any line that restates default agent behavior already known to the model, not a project-specific instruction`;
+  }
+  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 = text
+      .replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '')
+      .replace(/[.!?]+\s*$/u, '')
+      .trim()
+      .toLowerCase();
+    if (!this.phrases.includes(clean)) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      'generic instruction, model already knows this',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Redundant;

package/src/usage.js

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Price table.
+ *
+ * United States dollars per one million tokens, sent and received, for
+ * every model dogent knows. An unknown model falls back to zero, so the
+ * summary still prints token counts without inventing a price.
+ */
+const PRICES = {
+  'gpt-4o-mini': {input: 0.15, output: 0.6},
+  'gpt-4o': {input: 2.5, output: 10},
+  'gpt-4.1-nano': {input: 0.1, output: 0.4},
+  'gpt-4.1-mini': {input: 0.4, output: 1.6},
+  'gpt-4.1': {input: 2, output: 8}
+};
+
+/**
+ * Usage.
+ *
+ * One immutable tally of an OpenAI exchange: the model, the tokens sent,
+ * and the tokens received. Sums itself with another tally and renders a
+ * single human summary line, complete with an estimated dollar cost.
+ */
+class Usage {
+  constructor(model, sent, received) {
+    this.model = model;
+    this.sent = sent;
+    this.received = received;
+  }
+  plus(other) {
+    return new Usage(
+      this.model || other.model,
+      this.sent + other.sent,
+      this.received + other.received
+    );
+  }
+  cost() {
+    const price = PRICES[this.model] || {input: 0, output: 0};
+    return this.sent / 1e6 * price.input + this.received / 1e6 * price.output;
+  }
+  text() {
+    return `OpenAI: ${this.model}, ${this.sent} sent, ${this.received} received, ~$${this.cost().toFixed(4)}`;
+  }
+}
+
+module.exports = Usage;