docgrity 0.1.3 → 0.1.4

package/README.md

@@ -17,13 +17,20 @@ Part of the Docgrity family:
 ```yaml
 - uses: ujjavala/docgrity-vscode/action@main
   env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}   # for issue creation
   with:
-    provider: github-models   # free — uses GITHUB_TOKEN, no API key
+    provider: anthropic       # or openai / gemini / ollama
+    api_key: ${{ secrets.DOCGRITY_API_KEY }}
     create_issues: 'true'     # opt-in; default false
     max_new_issues: 5
 ```
 
+> **Note:** GitHub Models (`provider: github-models`) is being retired by GitHub —
+> runs may fail with HTTP 410 (`github_models_retirement`). Use a BYO-key provider
+> (`anthropic` / `openai` / `gemini`) or `ollama` instead. Copilot models are **not**
+> available here: Copilot has no API outside the editor — only the VS Code extension
+> can use it.
+
 Full example with weekly schedule, PR trigger and Pages report publishing:
 [examples/docgrity.yml](examples/docgrity.yml).
 
@@ -43,9 +50,29 @@ What it does per run:
 
 | provider | key | cost |
 |---|---|---|
-| `github-models` (default in CI) | none — uses `GITHUB_TOKEN` with `models: read` | free (being retired by GitHub — prefer a BYO provider) |
-| `gemini` / `openai` / `anthropic` | `api_key` input (use a repo secret) | your key |
-| `ollama` | none — local or tunnelled endpoint | free, fully private |
+| `anthropic` / `openai` / `gemini` | `api_key` input (use a repo secret) — defaults: `claude-3-5-haiku-latest`, `gpt-4o-mini`, `gemini-flash` | your key |
+| `ollama` (CLI default) | none — local or tunnelled endpoint | free, fully private |
+| `none` (no-agent mode) | none — zero LLM calls | free, instant, fully offline |
+| `github-models` | none — uses `GITHUB_TOKEN` with `models: read` | **being retired by GitHub** (HTTP 410) — switch to a provider above |
+
+### No-agent mode (`provider: none`)
+
+Pure algorithms, no model, no keys, no network:
+
+| Check | How | Notes |
+|---|---|---|
+| **Duplicates** | verbatim shared-block detection + TF-IDF similarity | catches copy-paste duplication; paraphrased duplication needs AI |
+| **Open questions** | explicit markers (`TODO`, `TBD`, `FIXME`, `???`, "open question"…) | deterministic — high confidence; subtle unanswered questions need AI |
+| **Contradictions** | ❌ **requires AI intelligence** (semantic understanding) — skipped, and the report says so | never guessed at heuristically |
+
+Confidence is *measured*, not guessed: duplicate confidence comes from the
+actual verbatim-overlap ratio; marker-based open questions score 0.85–0.95.
+Tuned for precision — paraphrased text, shared code samples and boilerplate
+headings never fire. Evidence is verbatim by construction. Findings carry
+`method: heuristic`, and issue drafts use a deterministic template.
+
+Great as a zero-setup PR pre-check (heuristics on every PR, full AI scan weekly)
+or when no key/model is available.
 
 ## Local CLI (read-only)
 
@@ -73,7 +100,8 @@ Usage: docgrity scan [options]
   --max-pairs <n>         Max document pairs (default: 25)
   --threshold-duplicate / --threshold-contradiction / --threshold-open-question <0..1>
 
-  --provider <p>          ollama | gemini | openai | anthropic | github-models
+  --provider <p>          none | ollama | gemini | openai | anthropic | github-models
+                          (none = no-agent mode: algorithms only, contradictions skipped)
   --model <m>             Model name
   --endpoint <url>        Ollama endpoint (default http://localhost:11434)
 
@@ -82,11 +110,13 @@ Usage: docgrity scan [options]
 ```
 
 Provider auto-detection: `DOCGRITY_API_KEY` set → `gemini`; else `GITHUB_TOKEN` →
-`github-models`; else → `ollama` (local, fully private — nothing leaves your machine).
+`github-models` (retiring — pass `--provider` explicitly); else → `ollama` (local,
+fully private — nothing leaves your machine).
 
 Examples:
 
 ```bash
+docgrity scan --provider none --open                      # no-agent: no model, no keys
 docgrity scan --checks contradictions                     # one check only
 docgrity scan --checks duplicates,open-questions --max-pairs 10
 docgrity scan --provider ollama --model llama3.1:8b       # fully local

package/action.yml

@@ -8,7 +8,10 @@ branding:
   color: 'blue'
 inputs:
   provider:
-    description: 'LLM provider: github-models (default, uses GITHUB_TOKEN), gemini, openai, anthropic'
+    description: >-
+      LLM provider: anthropic, openai, gemini (api_key required), ollama, github-models
+      (retiring), or "none" for no-agent mode — heuristic duplicates + open questions
+      only; contradiction detection requires an AI model and is skipped.
     default: 'github-models'
   api_key:
     description: 'API key for gemini/openai/anthropic (pass a repo secret). Not needed for github-models.'

package/bin/action.js

@@ -18,13 +18,19 @@ const slug = process.env.GITHUB_REPOSITORY ?? '';
 const branch = (process.env.GITHUB_REF_NAME ?? 'main').replace(/^refs\/heads\//, '');
 
 try {
-  const client = makeClient({
-    provider: input('provider', 'github-models'),
-    apiKey: input('api_key'),
-    githubToken: token,
-  });
+  const provider = input('provider', 'github-models');
+  // provider: none → no-agent mode: heuristic duplicates + open questions,
+  // contradictions skipped (they need AI), template-drafted issues.
+  const client =
+    provider === 'none'
+      ? null
+      : makeClient({
+          provider,
+          apiKey: input('api_key'),
+          githubToken: token,
+        });
 
-  console.log(`Docgrity scan on ${slug} (${branch})`);
+  console.log(`Docgrity scan on ${slug} (${branch})${provider === 'none' ? ' — no-agent (heuristic) mode' : ''}`);
   const { findings, stats } = await runScan(root, { client, log: (m) => console.log(m) });
 
   // Opt-in issue sync (deduped by fingerprint, capped, auto-close resolved).

package/bin/docgrity.js

@@ -54,8 +54,12 @@ Options:
   --threshold-contradiction <0..1>   Min confidence, contradictions (default: 0.7)
   --threshold-open-question <0..1>   Min confidence, open questions (default: 0.6)
 
-  --provider <p>          ollama | gemini | openai | anthropic | github-models
+  --provider <p>          none | ollama | gemini | openai | anthropic | github-models
                           (default: auto — see below)
+                          none = no-agent mode: pure algorithms, zero LLM calls.
+                          Detects duplicates (verbatim shared blocks + TF-IDF)
+                          and open questions (TODO/TBD/FIXME/???… markers).
+                          Contradictions REQUIRE an AI model and are skipped.
   --model <m>             Model name (provider-specific default otherwise)
   --endpoint <url>        Ollama endpoint (default: http://localhost:11434,
                           or DOCGRITY_OLLAMA_URL; supports tunnelled remotes)
@@ -74,6 +78,7 @@ Provider auto-detection (when --provider is omitted):
 
 Examples:
   docgrity scan --open
+  docgrity scan --provider none              # no-agent: no model, no keys, instant
   docgrity scan --checks contradictions
   docgrity scan --checks duplicates,open-questions --max-pairs 10
   docgrity scan --provider ollama --model llama3.1:8b
@@ -148,16 +153,22 @@ const provider =
 const checks = parseChecks(args.checks);
 
 try {
-  const client = makeClient({
-    provider,
-    apiKey: process.env.DOCGRITY_API_KEY,
-    githubToken: process.env.GITHUB_TOKEN || process.env.GH_TOKEN,
-    model: args.model,
-    endpoint: args.endpoint,
-  });
+  const client =
+    provider === 'none'
+      ? null
+      : makeClient({
+          provider,
+          apiKey: process.env.DOCGRITY_API_KEY,
+          githubToken: process.env.GITHUB_TOKEN || process.env.GH_TOKEN,
+          model: args.model,
+          endpoint: args.endpoint,
+        });
 
   const enabled = Object.entries(checks).filter(([, on]) => on).map(([k]) => k).join(', ');
-  console.log(`Docgrity local scan (read-only) — provider: ${provider}; checks: ${enabled}`);
+  console.log(`Docgrity local scan (read-only) — provider: ${provider}${provider === 'none' ? ' (no-agent, heuristics only)' : ''}; checks: ${enabled}`);
+  if (provider === 'none' && checks.contradictions) {
+    console.log('  Note: contradiction detection needs AI intelligence — it will be skipped. Use an LLM provider to enable it.');
+  }
   const { findings, stats } = await runScan(root, {
     client,
     checks,
@@ -181,6 +192,9 @@ try {
   await writeFile(path.join(outDir, 'findings.json'), JSON.stringify({ findings, stats }, null, 2));
 
   console.log(`\n${findings.length} finding(s) across ${stats.docs} docs.`);
+  for (const f of findings) {
+    console.log(`  [${f.severity}] ${f.type} — ${(f.confidence * 100).toFixed(0)}% confidence — ${f.files.join(' + ')}`);
+  }
   console.log(`Report: ${reportPath}`);
   console.log('Note: local scans are read-only — review owners and evidence in the report; issues are only raised by CI (opt-in).');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docgrity",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Docgrity doc-integrity scans for CI and local use: contradictions, duplicates and open questions across repository markdown docs. Read-only CLI — generates an HTML report; never posts anything.",
   "type": "module",
   "bin": { "docgrity": "bin/docgrity.js" },

package/src/heuristics.js

@@ -0,0 +1,146 @@
+/**
+ * No-agent (heuristic) checks — pure algorithms, zero LLM calls.
+ *
+ * What works without a model:
+ *   - duplicates: TF-IDF similarity + verbatim shared-block detection
+ *   - open questions: explicit unresolved markers (TODO/TBD/FIXME/???/…)
+ * What does NOT work without a model:
+ *   - contradictions: require semantic understanding — explicitly skipped,
+ *     and the report says so, rather than emitting noisy guesses.
+ *
+ * Evidence is verbatim by construction (extracted from the source text), so
+ * the same hallucination guard in scan.js passes trivially. Confidence for
+ * duplicates is derived from measured overlap; for open questions the
+ * markers are deterministic, so confidence is fixed high per marker class.
+ */
+
+const stripFences = (text) => text.replace(/```[\s\S]*?```/g, (m) => m.replace(/[^\n]/g, ''));
+
+const normLine = (s) => s.replace(/\s+/g, ' ').trim();
+
+/** Lines substantive enough to count as shared content (not markdown noise). */
+const substantive = (line) => {
+  const l = normLine(line);
+  if (l.length < 40) return false;
+  if (/^[#>\-*|=\s`~[\]().\d]+$/.test(l)) return false; // pure punctuation/structure
+  return true;
+};
+
+/**
+ * Find consecutive runs of lines from A that also appear (normalized) in B.
+ * Returns blocks sorted by length desc.
+ */
+export function sharedBlocks(textA, textB) {
+  const linesA = stripFences(textA).split('\n');
+  const setB = new Set(stripFences(textB).split('\n').map(normLine).filter((l) => l.length >= 20));
+  const blocks = [];
+  let current = [];
+  for (const raw of linesA) {
+    const l = normLine(raw);
+    if (l.length >= 20 && setB.has(l)) {
+      current.push(raw.trim());
+    } else if (l.length > 0) {
+      if (current.length) blocks.push(current), (current = []);
+    }
+    // blank lines don't break a block
+  }
+  if (current.length) blocks.push(current);
+  return blocks
+    .map((lines) => ({ lines, text: lines.join('\n'), chars: lines.join(' ').length }))
+    .filter((b) => b.lines.some(substantive))
+    .sort((x, y) => y.chars - x.chars);
+}
+
+/**
+ * Heuristic duplicate assessment. `similarity` is the TF-IDF cosine from
+ * candidate selection. Flags only when there is *verbatim* shared content —
+ * vocabulary similarity alone is not enough (false-positive guard).
+ */
+export function heuristicDuplicate(a, b, similarity = 0) {
+  const blocks = sharedBlocks(a.text, b.text);
+  const sharedChars = blocks.reduce((n, bl) => n + bl.chars, 0);
+  const minLen = Math.max(1, Math.min(a.text.length, b.text.length));
+  const sharedRatio = Math.min(1, sharedChars / minLen);
+
+  // Require a meaningful verbatim block; similarity alone never fires.
+  const hasBlock = blocks.length > 0 && blocks[0].chars >= 120;
+  const is_duplicate = hasBlock && (sharedRatio >= 0.2 || similarity >= 0.6);
+
+  // Confidence is measured, not guessed: verbatim overlap dominates.
+  const confidence = is_duplicate
+    ? Math.min(0.99, Math.round((0.55 * Math.min(1, sharedRatio * 2) + 0.45 * similarity) * 100) / 100)
+    : Math.round(Math.max(sharedRatio, similarity) * 100) / 100;
+
+  return {
+    output: {
+      is_duplicate,
+      confidence,
+      summary: is_duplicate
+        ? `Verbatim duplicated content between "${a.relPath}" and "${b.relPath}" — ${blocks.length} shared block(s), ~${Math.round(sharedRatio * 100)}% of the smaller doc (TF-IDF similarity ${similarity.toFixed(2)}).`
+        : 'No verbatim duplication detected.',
+      recommended_action: 'CONSOLIDATE',
+      evidence: blocks.slice(0, 3).map((bl) => ({ page: 'A', excerpt: bl.text.slice(0, 1000) })),
+    },
+    model: 'heuristic (tf-idf + shared blocks)',
+    promptVersion: 'heuristic-v1',
+  };
+}
+
+/** Explicit unresolved-marker classes — deterministic, hence high confidence. */
+const OQ_MARKERS = [
+  { re: /\b(TODO|FIXME)\b(?!\s*:?\s*none)/, label: 'TODO/FIXME marker', confidence: 0.95, severity: 'MEDIUM' },
+  { re: /\b(TBD|TBC)\b|\bto be (decided|determined|confirmed|announced)\b/i, label: 'TBD marker', confidence: 0.95, severity: 'MEDIUM' },
+  { re: /\?{3,}|\[\?\]/, label: 'placeholder question marks', confidence: 0.9, severity: 'MEDIUM' },
+  // Affirmative context required ("remains unresolved"), so negations like
+  // "nothing unresolved" don't fire (false-positive guard).
+  { re: /\bopen question\b|\b(is|are|remains?|still|left)\s+(unresolved|undecided)\b|\bnot (yet )?(decided|determined|finali[sz]ed)\b/i, label: 'explicit open-question language', confidence: 0.85, severity: 'MEDIUM' },
+];
+
+/**
+ * Heuristic open-question detection. Scans prose only (fenced code stripped —
+ * TODOs inside code samples are code concerns, not doc integrity), one
+ * finding per line, deduplicated.
+ */
+export function heuristicOpenQuestions(doc) {
+  const lines = stripFences(doc.text).split('\n');
+  const questions = [];
+  const seen = new Set();
+  for (const raw of lines) {
+    const line = normLine(raw);
+    if (!line || seen.has(line)) continue;
+    for (const m of OQ_MARKERS) {
+      if (m.re.test(line)) {
+        seen.add(line);
+        questions.push({
+          question: `Unresolved ${m.label}: "${line.slice(0, 200)}"`,
+          excerpt: raw.trim().slice(0, 1000),
+          confidence: m.confidence,
+          severity: m.severity,
+        });
+        break; // one finding per line even if several markers match
+      }
+    }
+  }
+  return {
+    output: { questions },
+    model: 'heuristic (signal markers)',
+    promptVersion: 'heuristic-v1',
+  };
+}
+
+/** Template-based issue draft — used when no LLM client is available. */
+export function templateIssue(finding) {
+  const title = `[docgrity] ${finding.type.replace('_', ' ')}: ${finding.summary.slice(0, 140)}`;
+  const body = [
+    `**Type:** ${finding.type}  `,
+    `**Severity:** ${finding.severity} · **Confidence:** ${(finding.confidence * 100).toFixed(0)}%  `,
+    `**Docs:** ${finding.files.map((f) => `\`${f}\``).join(', ')}  `,
+    `**Potential owner(s):** ${finding.potentialOwners.join(', ') || 'unknown'} *(from git history — potential, not asserted)*`,
+    '',
+    '### Evidence',
+    ...finding.evidence.map((e) => `> ${e.excerpt.replace(/\n/g, '\n> ')}\n> — \`${e.sourceLabel}\``),
+    '',
+    `_Detected by Docgrity in no-agent (heuristic) mode — evidence is verbatim from the docs._`,
+  ].join('\n');
+  return { title: title.slice(0, 200), body: body.slice(0, 20000) };
+}

package/src/issues.js

@@ -7,6 +7,7 @@
  * Only runs when create_issues is explicitly enabled (opt-in guard).
  */
 import { draftIssue } from './llm.js';
+import { templateIssue } from './heuristics.js';
 
 const MARKER = (fp) => `<!-- docgrity:fingerprint:${fp} -->`;
 const LABEL = 'docgrity';
@@ -71,7 +72,9 @@ export async function syncIssues({ client, token, slug, findings, maxNewIssues =
       result.skipped++;
       continue;
     }
-    const draft = await draftIssue(client, f);
+    // No LLM client (no-agent mode) → deterministic template draft; evidence is
+    // already verbatim, so nothing is lost except prose polish.
+    const draft = client ? await draftIssue(client, f) : templateIssue(f);
     const body = `${draft.body}
 
 ---

package/src/report.js

@@ -154,7 +154,8 @@ export function renderReport({ findings, stats, repoSlug, branch }) {
 <div class="wrap">
   <div class="hero">
     <h1>Docgrity — documentation-integrity report</h1>
-    <div class="meta">${esc(repoSlug ?? 'local scan')} · scanned ${esc(stats.scannedAt)} · ${stats.docs} markdown docs · ${stats.pairs} pairs assessed</div>
+    <div class="meta">${esc(repoSlug ?? 'local scan')} · scanned ${esc(stats.scannedAt)} · ${stats.docs} markdown docs · ${stats.pairs} pairs assessed${stats.mode === 'heuristic' ? ' · no-agent (heuristic) mode' : ''}</div>
+    ${(stats.notes ?? []).map((n) => `<div class="meta" style="margin-top:6px">⚠ ${esc(n)}</div>`).join('')}
   </div>
   <div class="stats">
     <button class="stat" data-target="all"><div><div class="label">Open findings</div><div class="num">${findings.length}</div><div class="sub">view all</div></div><div class="badge ${findings.length ? 'findings' : 'ok'}">${icon(findings.length ? 'findings' : 'check')}</div></button>

package/src/scan.js

@@ -6,6 +6,7 @@
 import crypto from 'crypto';
 import { collectCorpus, selectCandidatePairs, potentialOwner } from './corpus.js';
 import { assessContradiction, assessDuplicate, assessOpenQuestions } from './llm.js';
+import { heuristicDuplicate, heuristicOpenQuestions } from './heuristics.js';
 
 const norm = (s) => s.replace(/\s+/g, ' ').trim().toLowerCase();
 
@@ -37,9 +38,17 @@ export async function runScan(root, opts = {}) {
   } = opts;
 
   const docs = await collectCorpus(root, { maxFiles });
+  // No-agent (heuristic) mode when no LLM client is provided.
+  const heuristic = !client;
+  const notes = [];
+  if (heuristic && checks.contradictions) {
+    notes.push('Contradiction detection requires an AI model (semantic understanding) — skipped in no-agent mode.');
+    log('Note: contradictions need AI — skipped (no-agent mode).');
+  }
   // Pair selection is only needed for the pairwise checks.
-  const pairs = checks.duplicates || checks.contradictions ? selectCandidatePairs(docs, maxPairs) : [];
-  log(`Corpus: ${docs.length} markdown docs; assessing ${pairs.length} candidate pairs`);
+  const pairwise = checks.duplicates || (checks.contradictions && !heuristic);
+  const pairs = pairwise ? selectCandidatePairs(docs, maxPairs) : [];
+  log(`Corpus: ${docs.length} markdown docs; assessing ${pairs.length} candidate pairs${heuristic ? ' (heuristic, no LLM)' : ''}`);
   const findings = [];
   const now = new Date().toISOString();
 
@@ -53,10 +62,14 @@ export async function runScan(root, opts = {}) {
   };
 
   let i = 0;
-  for (const { a, b } of pairs) {
+  for (const { a, b, similarity } of pairs) {
     i++;
     log(`Pair ${i}/${pairs.length}: ${a.relPath} <-> ${b.relPath}`);
-    const dup = checks.duplicates ? await assessDuplicate(client, a, b) : null;
+    const dup = checks.duplicates
+      ? heuristic
+        ? heuristicDuplicate(a, b, similarity)
+        : await assessDuplicate(client, a, b)
+      : null;
     if (
       dup &&
       dup.output.is_duplicate &&
@@ -79,11 +92,12 @@ export async function runScan(root, opts = {}) {
         potentialOwners: await owners([a, b]),
         model: dup.model,
         promptVersion: dup.promptVersion,
+        method: heuristic ? 'heuristic' : 'llm',
         createdAt: now,
       });
     }
 
-    const con = checks.contradictions ? await assessContradiction(client, a, b) : null;
+    const con = checks.contradictions && !heuristic ? await assessContradiction(client, a, b) : null;
     if (
       con &&
       con.output.is_contradiction &&
@@ -106,6 +120,7 @@ export async function runScan(root, opts = {}) {
         potentialOwners: await owners([a, b]),
         model: con.model,
         promptVersion: con.promptVersion,
+        method: 'llm',
         createdAt: now,
       });
     }
@@ -116,7 +131,7 @@ export async function runScan(root, opts = {}) {
   for (const doc of oqDocs) {
     j++;
     log(`Open questions ${j}/${oqDocs.length}: ${doc.relPath}`);
-    const oq = await assessOpenQuestions(client, doc);
+    const oq = heuristic ? heuristicOpenQuestions(doc) : await assessOpenQuestions(client, doc);
     const kept = oq.output.questions.filter(
       (q) => q.confidence >= thresholds.openQuestion && verifyExcerpts([q], [doc])
     );
@@ -133,10 +148,20 @@ export async function runScan(root, opts = {}) {
         potentialOwners: await owners([doc]),
         model: oq.model,
         promptVersion: oq.promptVersion,
+        method: heuristic ? 'heuristic' : 'llm',
         createdAt: now,
       });
     }
   }
 
-  return { findings, stats: { docs: docs.length, pairs: pairs.length, scannedAt: now } };
+  return {
+    findings,
+    stats: {
+      docs: docs.length,
+      pairs: pairs.length,
+      scannedAt: now,
+      mode: heuristic ? 'heuristic' : 'llm',
+      ...(notes.length ? { notes } : {}),
+    },
+  };
 }