docguard-cli 0.35.0 → 0.36.0

package/cli/scanners/semantic-claims.mjs

@@ -1,3 +1,4 @@
+import { docRolePath } from '../shared-doc-roles.mjs';
 /**
  * Semantic claim extractor (LLM field report #5).
  *
@@ -21,10 +22,12 @@
  * Zero npm dependencies — pure Node.js built-ins.
  */
 
-import { existsSync, readFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { lstatSync, realpathSync, readdirSync, openSync, readSync, fstatSync, closeSync, constants } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { resolve, relative, isAbsolute, sep } from 'node:path';
 import { loadIgnorePatterns } from '../shared.mjs';
-import { listCanonicalDocs } from '../shared-ignore.mjs';
+
 
 // Numbers are only claims when adjacent to a recognized unit.
 const NUMBER_PATTERNS = [
@@ -44,28 +47,169 @@ const NUMBER_PATTERNS = [
 const ENUM_LIST_RE = /\b[A-Z][A-Z0-9_]{2,}(?:\s*(?:\/|,|\||\bor\b)\s*[A-Z][A-Z0-9_]{2,}){1,}\b/g;
 const ENUM_CONTEXT_RE = /\b(status|state|enum|values?|one of|phase|stage|transitions?)\b/i;
 
-// A code path mentioned in or near the claim — the agent's starting point.
-const CITED_CODE_RE = /`?([\w./-]+\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json))`?(?::(\d+))?/;
+export const SEMANTIC_COVERAGE_LIMITATION = 'Semantic claim discovery is limited to docs-canonical/**/*.md, explicitly mapped Markdown document roles, README.md, and AGENTS.md, subject to ignores, safety checks, and scan budgets. Other resolved documentation homes are unscanned/unsupported by this extractor; guard coverage labels do not extend this scope. Hashes cover only captured document and cited-source inputs, not all documentation or factual correctness.';
 
 const MAX_CLAIMS = 80;
+const MAX_EVIDENCE_FILE_BYTES = 1024 * 1024;
+const MAX_EVIDENCE_BYTES = 8 * MAX_EVIDENCE_FILE_BYTES;
+const MAX_EVIDENCE_FILES = 128;
+const MAX_CITED_SOURCES = 8;
+
+export function contentHash(content) {
+  return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
+
+function unknownFile(path, reason) {
+  return { path: path || null, status: 'unknown', hash: null, reason };
+}
+
+function privateSegment(part) {
+  return part.toLowerCase() === '.local' || /^\.env(?:\.|$)/i.test(part);
+}
 
-/** Canonical docs + the root docs where limits/counts commonly live. */
-function claimSourceDocs(projectDir) {
-  // Honor .docguardignore: a doc the user explicitly excluded from validation
-  // (e.g. a historical audit full of point-in-time counts) must not feed the
-  // "unverified claims" pool either — it inflated the count and buried the
-  // claims that ARE actionable (bug-212).
-  const isIgnored = loadIgnorePatterns(projectDir);
-  // Recursive — nested canonical docs make claims too. The ignore predicate is
-  // applied per-doc inside the helper against the full relative path, so a
-  // pattern like `docs-canonical/99-archive/**` still excludes a subtree.
-  const docs = listCanonicalDocs(projectDir, { isIgnored }).map(d => d.rel);
-  for (const root of ['README.md', 'AGENTS.md']) {
-    if (existsSync(resolve(projectDir, root)) && !isIgnored(root)) docs.push(root);
+/** Per-run bounded cache. Never follows symlinks, reads secrets, or leaves root. */
+export function createEvidenceReader(projectDir) {
+  let root;
+  try { root = realpathSync(projectDir); } catch { /* unknown root */ }
+  const cache = new Map();
+  let bytes = 0;
+  return (citation) => {
+    const path = typeof citation === 'string' ? citation.replace(/:\d+(?:-\d+)?$/, '') : null;
+    if (!path) return { evidence: unknownFile(path, 'not-cited'), content: null };
+    if (cache.has(path)) return cache.get(path);
+    const fail = (reason) => ({ evidence: unknownFile(path, reason), content: null });
+    if (!root || isAbsolute(path) || /[\\:\0]/.test(path) || path.split('/').some(p => p === '..' || privateSegment(p))) {
+      return fail('unsafe-path');
+    }
+    if (cache.size >= MAX_EVIDENCE_FILES) return fail('file-budget');
+    let result;
+    let fd;
+    try {
+      let full = root;
+      let inspected;
+      for (const part of path.split('/').filter(p => p && p !== '.')) {
+        full = resolve(full, part);
+        inspected = lstatSync(full);
+        if (inspected.isSymbolicLink()) throw new Error('symlink');
+      }
+      const actual = realpathSync(full);
+      const rel = relative(root, actual);
+      if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel) || rel.split(sep).some(privateSegment)) {
+        throw new Error('unsafe-path');
+      }
+      fd = openSync(actual, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      const stat = fstatSync(fd);
+      if (!stat.isFile()) throw new Error('not-file');
+      if (stat.dev !== inspected?.dev || stat.ino !== inspected?.ino) throw new Error('changed-during-read');
+      if (stat.size > MAX_EVIDENCE_FILE_BYTES) throw new Error('file-too-large');
+      if (bytes + stat.size > MAX_EVIDENCE_BYTES) throw new Error('byte-budget');
+      const buffer = Buffer.alloc(stat.size);
+      let offset = 0;
+      while (offset < buffer.length) {
+        const n = readSync(fd, buffer, offset, buffer.length - offset, offset);
+        if (!n) break;
+        offset += n;
+      }
+      bytes += offset;
+      const after = fstatSync(fd);
+      if (offset !== stat.size || after.size !== stat.size || after.mtimeMs !== stat.mtimeMs || after.ctimeMs !== stat.ctimeMs) {
+        throw new Error('changed-during-read');
+      }
+      result = { evidence: { path, status: 'snapshot', hash: contentHash(buffer) }, content: buffer.toString('utf8') };
+    } catch (err) {
+      const reasons = ['symlink', 'unsafe-path', 'not-file', 'file-too-large', 'byte-budget', 'changed-during-read'];
+      result = fail(reasons.includes(err.message) ? err.message : 'unavailable');
+    } finally {
+      if (fd !== undefined) closeSync(fd);
+    }
+    cache.set(path, result);
+    return result;
+  };
+}
+
+/** Candidate paths only; the reader decides whether they can be used safely. */
+export function citedSources(text, limit = MAX_CITED_SOURCES) {
+  const paths = [];
+  for (const match of String(text || '').slice(0, 32768).matchAll(/`([^`\n]+)`|([^\s`]+)/g)) {
+    const candidate = match[1] || match[2].replace(/^[(["']+|[)\],;.!"']+$/g, '');
+    if (!/(?:\.(?:ts|tsx|js|mjs|cjs|jsx|py|go|rs|java|kt|rb|php|sql|yaml|yml|json)|(?:^|\/)\.env(?:\.[\w.-]+)?)(?::\d+(?:-\d+)?)?$/.test(candidate)) continue;
+    if (!paths.includes(candidate)) paths.push(candidate);
+    if (paths.length >= limit) break;
+  }
+  return paths;
+}
+
+/** Stable identity excludes line numbers, discovery order, and content hashes. */
+export function semanticClaimId(claim) {
+  return `claim.${contentHash(JSON.stringify([
+    claim.doc, claim.section, claim.kind, claim.subkind, claim.value, claim.unit,
+    String(claim.text || '').replace(/\s+/g, ' ').trim(),
+    (claim.citedCode || '').replace(/:\d+(?:-\d+)?$/, ''),
+  ])).slice(7)}`;
+}
+
+/** Hashes bind a snapshot to its inputs; they are never evidence of review. */
+export function taskEvidence(read, doc, citations = [], taskContent = '') {
+  const document = read(doc).evidence;
+  const citedSourceFiles = [...new Set(citations)].slice(0, MAX_CITED_SOURCES).map(p => read(p).evidence);
+  const snapshot = { document, citedSources: citedSourceFiles, taskContentHash: contentHash(taskContent) };
+  return {
+    kind: 'snapshot', verification: 'unverified', factualAccuracy: 'unknown',
+    limitation: SEMANTIC_COVERAGE_LIMITATION,
+    ...snapshot,
+    sourceCoverage: citedSourceFiles.length && citedSourceFiles.every(s => s.status === 'snapshot') ? 'cited-only' : 'unknown',
+    snapshotHash: contentHash(JSON.stringify(snapshot)),
+  };
+}
+
+/** Two bounded read-only Git queries per artifact, never per task. */
+export function gitEvidence(projectDir) {
+  const result = { revision: null, dirty: null, status: 'unknown' };
+  const options = { cwd: projectDir, encoding: 'utf8', timeout: 1500, maxBuffer: 65536,
+    stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } };
+  try {
+    const revision = execFileSync('git', ['rev-parse', '--verify', 'HEAD'], options).trim();
+    if (/^[a-f0-9]{40,64}$/.test(revision)) result.revision = revision;
+  } catch { /* missing Git/revision stays unknown */ }
+  try {
+    result.dirty = execFileSync('git', ['status', '--porcelain', '--untracked-files=normal'], options).length > 0;
+  } catch { /* dirty state unknown */ }
+  if (result.revision !== null && result.dirty !== null) result.status = 'snapshot';
+  return result;
+}
+
+/** Bounded canonical inventory that does not traverse private or symlink dirs. */
+export function evidenceDocs(projectDir, config = {}) {
+  const docs = [];
+  let directories = 0;
+  const walk = (rel) => {
+    if (++directories > MAX_EVIDENCE_FILES || docs.length >= MAX_EVIDENCE_FILES) return;
+    try {
+      if (lstatSync(resolve(projectDir, rel)).isSymbolicLink()) return;
+      for (const entry of readdirSync(resolve(projectDir, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (docs.length >= MAX_EVIDENCE_FILES) break;
+        if (entry.isSymbolicLink() || privateSegment(entry.name)) continue;
+        const path = `${rel}/${entry.name}`;
+        if (entry.isDirectory() && !entry.name.startsWith('.')) walk(path);
+        else if (entry.isFile() && /\.md$/i.test(entry.name)) docs.push(path);
+      }
+    } catch { /* inventory is heuristic, not proof of coverage */ }
+  };
+  walk('docs-canonical');
+  for (const role of Object.keys(config.docs?.roles || {})) {
+    const path = docRolePath(config, role);
+    if (/\.md$/i.test(path) && !docs.includes(path)) docs.push(path);
   }
   return docs;
 }
 
+/** Canonical docs + root docs, honoring the existing ignore contract. */
+function claimSourceDocs(projectDir, read, config) {
+  // The legacy matcher reads its file itself; never call it for an unsafe file.
+  const isIgnored = read('.docguardignore').content === null ? () => false : loadIgnorePatterns(projectDir);
+  return [...evidenceDocs(projectDir, config), 'README.md', 'AGENTS.md'].filter(doc => !isIgnored(doc));
+}
+
 /** True if a line is inside a fenced code block (toggled by the caller). */
 function findCitedCode(lines, idx) {
   // Search the claim line first, then the immediately adjacent lines. A tight
@@ -74,8 +218,8 @@ function findCitedCode(lines, idx) {
   for (let d = 0; d <= 1; d++) {
     for (const j of d === 0 ? [idx] : [idx - d, idx + d]) {
       if (j < 0 || j >= lines.length) continue;
-      const m = CITED_CODE_RE.exec(lines[j]);
-      if (m) return m[2] ? `${m[1]}:${m[2]}` : m[1];
+      const cited = citedSources(lines[j], 1)[0];
+      if (cited) return cited;
     }
   }
   return null;
@@ -85,13 +229,13 @@ function findCitedCode(lines, idx) {
  * Extract semantic claims from a project's canonical docs.
  * @returns {Array<{ doc, line, section, kind, subkind, value, unit, text, citedCode }>}
  */
-export function extractSemanticClaims(projectDir, config = {}) {
+export function extractSemanticClaims(projectDir, config = {}, read = createEvidenceReader(projectDir)) {
   const claims = [];
   const seen = new Set();
 
-  for (const doc of claimSourceDocs(projectDir)) {
-    let content;
-    try { content = readFileSync(resolve(projectDir, doc), 'utf-8'); } catch { continue; }
+  for (const doc of claimSourceDocs(projectDir, read, config)) {
+    const { content } = read(doc);
+    if (content === null) continue;
     const lines = content.split('\n');
     let section = '';
     let inFence = false;
@@ -108,7 +252,11 @@ export function extractSemanticClaims(projectDir, config = {}) {
         const key = `${doc}:${lineNo}:${claim.kind}:${claim.value}:${claim.unit || ''}`;
         if (seen.has(key)) return;
         seen.add(key);
-        claims.push({ doc, line: lineNo, section, citedCode: findCitedCode(lines, i), text: line.trim().slice(0, 200), ...claim });
+        if (claims.length >= MAX_CLAIMS) return;
+        const candidate = { doc, line: lineNo, section, citedCode: findCitedCode(lines, i), text: line.trim().slice(0, 200), ...claim };
+        candidate.stableId = semanticClaimId({ ...candidate, text: line.trim() });
+        candidate.evidence = taskEvidence(read, doc, candidate.citedCode ? [candidate.citedCode] : [], line.trim());
+        claims.push(candidate);
       };
 
       for (const { kind, re } of NUMBER_PATTERNS) {
@@ -147,6 +295,8 @@ export function buildSemanticVerifyTasks(claims) {
       : `the ${c.subkind} value ${c.value}${c.unit ? ` ${c.unit}` : ''}`;
     return {
       id: `verify.semantic.${i + 1}`,
+      stableId: c.stableId || semanticClaimId(c),
+      evidence: c.evidence || taskEvidence(path => ({ evidence: unknownFile(path, 'not-captured') }), c.doc, c.citedCode ? [c.citedCode] : []),
       doc: c.doc,
       line: c.line,
       section: c.section,
@@ -155,7 +305,7 @@ export function buildSemanticVerifyTasks(claims) {
       unit: c.unit,
       citedCode: c.citedCode,
       claim: c.text,
-      instruction: `Verify ${what} documented in ${c.doc}:${c.line}${c.section ? ` (section "${c.section}")` : ''} against the code.${where} If the code disagrees, the doc (or the code) is wrong — report the mismatch with both values.`,
+      instruction: `Verify ${what} documented in ${c.doc}:${c.line}${c.section ? ` (section "${c.section}")` : ''} against the code.${where} If the code disagrees, the doc (or the code) is wrong — report the mismatch with both values. Attached hashes capture an unverified snapshot; guard does not verify this claim.`,
       confidence: 'requires-human',
     };
   });

package/cli/shared-diff.mjs

@@ -169,7 +169,7 @@ export function activityLabeledDiff(fileDiff) {
 }
 
 /**
- * Tokens that LEFT the code in this file diff — union over every '-' line
+ * Old-side tokens absent from additions, plus removed declaration names, from every '-' line
  * (both pure deletes and the "old" side of replaces). This is the
  * `deleted ∪ replaceOld` span the outdated-comment research keys on: a doc
  * that still talks about these tokens is a drift suspect.
@@ -181,6 +181,27 @@ export function removedTokens(fileDiff, opts) {
       if (ln.op === '-') for (const t of tokenize(ln.text, opts)) set.add(t);
     }
   }
+  // Reformatting or movement into another hunk does not remove a token.
+  for (const token of addedTokens(fileDiff, opts)) set.delete(token);
+  // A retained call is not a retained declaration. Preserve name evidence when
+  // declarations disappear, even if additions still reference those names.
+  const declarationNames = op => {
+    const text = (fileDiff.hunks || []).flatMap(h => h.lines)
+      .filter(line => line.op === op).map(line => line.text).join('\n');
+    const names = new Map();
+    const pattern = /\b(?:function\s*\*?\s*|def\s+|class\s+|(?:const|let|var)\s+)([A-Za-z_$][\w$]*)/g;
+    for (const match of text.matchAll(pattern)) {
+      names.set(match[1], (names.get(match[1]) || 0) + 1);
+    }
+    return names;
+  };
+  const declarationsAdded = declarationNames('+');
+  for (const [name, count] of declarationNames('-')) {
+    if (count > (declarationsAdded.get(name) || 0)) {
+      for (const token of tokenize(name, opts)) set.add(token);
+    }
+  }
+
   return set;
 }
 

package/cli/shared-doc-roles.mjs

@@ -0,0 +1,59 @@
+/** Explicit document roles let existing repository layouts serve as canonical input. */
+import { lstatSync } from 'node:fs';
+import { resolve, isAbsolute, join } from 'node:path';
+export const DOC_ROLES = Object.freeze({
+  architecture: 'docs-canonical/ARCHITECTURE.md', dataModel: 'docs-canonical/DATA-MODEL.md',
+  security: 'docs-canonical/SECURITY.md', testSpec: 'docs-canonical/TEST-SPEC.md',
+  environment: 'docs-canonical/ENVIRONMENT.md', apiReference: 'docs-canonical/API-REFERENCE.md',
+  requirements: 'docs-canonical/REQUIREMENTS.md',
+});
+export function docRolePath(config = {}, role) {
+  if (!Object.hasOwn(DOC_ROLES, role)) throw new Error('Unknown document role: ' + role);
+  const value = config.docs?.roles?.[role] ?? DOC_ROLES[role];
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0')) throw new Error('Invalid document path for role: ' + role);
+  const path = value.replace(/\\/g, '/');
+  if (config.docs?.roles?.[role] !== undefined && !path.toLowerCase().endsWith('.md')) throw new Error('Mapped document roles currently require Markdown (.md): ' + role);
+  if (isAbsolute(path) || /^[A-Za-z]:/.test(path) || path.split('/').some(p => p === '..' || p.toLowerCase() === '.local' || p.toLowerCase() === '.git')) throw new Error('Document role path must stay within the project: ' + role);
+  return path.startsWith('./') ? path.slice(2) : path;
+}
+export function resolveDocRole(projectDir, config, role) {
+  const rel = docRolePath(config, role);
+  // Opt-in mappings must not follow links into another repository/private data.
+  if (config.docs?.roles?.[role] !== undefined) {
+    let current = resolve(projectDir);
+    for (const part of rel.split('/')) {
+      current = join(current, part);
+      try { if (lstatSync(current).isSymbolicLink()) throw new Error('Document role path contains a symlink: ' + role); }
+      catch (e) { if (e.code !== 'ENOENT') throw e; }
+    }
+  }
+  return resolve(projectDir, rel);
+}
+export function applyDocRoles(projectDir, config) {
+  const roles = config.docs?.roles;
+  if (roles === undefined) return config;
+  if (!roles || typeof roles !== 'object' || Array.isArray(roles)) throw new Error('docs.roles must be an object');
+  const replacements = new Map();
+  for (const role of Object.keys(roles)) {
+    resolveDocRole(projectDir, config, role);
+    replacements.set(DOC_ROLES[role], docRolePath(config, role));
+  }
+  const requiredFiles = { ...config.requiredFiles, canonical: [...new Set([...(config.requiredFiles?.canonical || []).map(p => replacements.get(p) || p), ...replacements.values()])] };
+  const documentTypes = { ...config.documentTypes };
+  for (const [oldPath, newPath] of replacements) {
+    const old = documentTypes[oldPath] || {};
+    if (oldPath !== newPath) delete documentTypes[oldPath];
+    documentTypes[newPath] = { ...old, ...documentTypes[newPath], required: true, category: 'canonical' };
+  }
+  return { ...config, requiredFiles, documentTypes };
+}
+export function remapDocPath(config, path) {
+  const role = Object.keys(DOC_ROLES).find(key => DOC_ROLES[key] === path);
+  return role ? docRolePath(config, role) : path;
+}
+
+export function assertDefaultDocWrites(config) {
+  if (Object.entries(config.docs?.roles || {}).some(([role, path]) => path !== DOC_ROLES[role])) {
+    throw new Error('Custom docs.roles currently support validation and read-only planning. Automatic document generation/repair is unavailable for mapped layouts; review and edit the existing documents directly.');
+  }
+}

package/cli/shared-ignore.mjs

@@ -1,3 +1,4 @@
+import { resolveDocRole } from './shared-doc-roles.mjs';
 /**
  * Shared Ignore Utility — Unified file filtering for all validators.
  *
@@ -384,11 +385,11 @@ export function walkFiles(dir, callback, opts = {}) {
 export function listCanonicalDocs(projectDir, opts = {}) {
   const { dirName = 'docs-canonical', isIgnored = null } = opts;
   const root = resolvePath(projectDir, dirName);
-  if (!existsSync(root)) return [];
+  // An explicit role may live outside the conventional canonical directory.
 
   const isMarkdown = (name) => name.toLowerCase().endsWith('.md');
   const out = [];
-  walkFiles(root, (abs) => {
+  if (existsSync(root)) walkFiles(root, (abs) => {
     if (!isMarkdown(abs)) return;
     const rel = relPosix(projectDir, abs);
     if (isIgnored && isIgnored(rel)) return;
@@ -399,6 +400,18 @@ export function listCanonicalDocs(projectDir, opts = {}) {
     keepDot: isMarkdown,
   });
 
+  let roleConfig = opts.config;
+  if (!roleConfig) {
+    const configFile = resolvePath(projectDir, '.docguard.json');
+    try { if (existsSync(configFile)) roleConfig = JSON.parse(readFileSync(configFile, 'utf-8')); }
+    catch { /* loadConfig owns malformed configuration errors */ }
+  }
+  for (const role of Object.keys(roleConfig?.docs?.roles || {})) {
+    const abs = resolveDocRole(projectDir, roleConfig, role);
+    const rel = relPosix(projectDir, abs);
+    if (!existsSync(abs) || !isMarkdown(abs) || (isIgnored && isIgnored(rel))) continue;
+    if (!out.some(doc => doc.abs === abs)) out.push({ abs, rel });
+  }
   out.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
   return out;
 }

package/cli/shared-source.mjs

@@ -10,9 +10,11 @@
  *   - pnpm-workspace.yaml          (packages:)
  *   - turbo.json                   (presence → trust package.json workspaces)
  *
- * Zero NPM dependencies — pure Node.js built-ins only.
+ * Source discovery uses Node.js built-ins; Worker binding analysis optionally
+ * loads the existing @babel/parser dependency, with a lexical fallback.
  */
 
+import { createRequire } from 'node:module';
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { resolve, join, dirname, relative, extname } from 'node:path';
 import { shouldIgnore, isNonProductDir, isNonProductPath } from './shared-ignore.mjs';
@@ -316,6 +318,223 @@ export function isRunnerEnvVar(name) {
   return RUNNER_ENV_PREFIXES.some((p) => name.startsWith(p));
 }
 
+
+/** Wrangler is static evidence only: never load or execute project config. */
+export function hasWorkerConfig(dir) {
+  return ['wrangler.toml', 'wrangler.json', 'wrangler.jsonc'].some(name => {
+    try { return statSync(join(dir, name)).isFile(); } catch { return false; }
+  });
+}
+
+function workerConfigForFile(projectDir, file) {
+  const root = resolve(projectDir);
+  let dir = dirname(file);
+  while (dir === root || (!relative(root, dir).startsWith('..') && !relative(root, dir).startsWith('/'))) {
+    if (hasWorkerConfig(dir)) return true;
+    if (dir === root) break;
+    dir = dirname(dir);
+  }
+  return false;
+}
+
+// Optional-load the existing parser directly: shared helpers must not depend
+// on the scanner layer. No project modules or configuration are executed.
+let workerParse = null;
+try { workerParse = createRequire(import.meta.url)('@babel/parser').parse; } catch { /* lexical fallback */ }
+
+function workerType(param) {
+  const type = param?.typeAnnotation?.typeAnnotation;
+  return type?.type === 'TSTypeReference' && type.typeName?.type === 'Identifier' ? type.typeName.name : '';
+}
+
+/** Static lexical binding analysis; collect declarations before resolving reads. */
+function workerAstBindings(ast, configured) {
+  const root = { parent: null, functionScope: true, env: undefined };
+  const reads = [];
+  const bind = (pattern, scope, value = false) => {
+    if (!pattern) return;
+    if (pattern.type === 'Identifier' && pattern.name === 'env') scope.env = value;
+    else if (pattern.type === 'AssignmentPattern') bind(pattern.left, scope, value);
+    else if (pattern.type === 'RestElement') bind(pattern.argument, scope, value);
+    else if (pattern.type === 'ArrayPattern') for (const element of pattern.elements) bind(element, scope, value);
+    else if (pattern.type === 'ObjectPattern') {
+      for (const property of pattern.properties) bind(property.type === 'RestElement' ? property.argument : property.value, scope, value);
+    }
+  };
+  const functionTypes = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression', 'ObjectMethod', 'ClassMethod', 'ClassPrivateMethod']);
+  function visit(node, scope, parent) {
+    if (!node || typeof node.type !== 'string') return;
+    if (node.type === 'FunctionDeclaration' || node.type === 'ClassDeclaration') bind(node.id, scope);
+    if (functionTypes.has(node.type)) {
+      scope = { parent: scope, functionScope: true, env: undefined };
+      if (node.type === 'FunctionExpression') bind(node.id, scope);
+      const key = node.key?.name || node.key?.value || node.id?.name ||
+        (parent?.type === 'ObjectProperty' ? parent.key?.name || parent.key?.value : parent?.type === 'VariableDeclarator' ? parent.id?.name : '');
+      const request = workerType(node.params[0]) === 'Request';
+      for (const param of node.params) {
+        const target = param.type === 'AssignmentPattern' ? param.left : param;
+        const worker = target.type === 'Identifier' && target.name === 'env' &&
+          /^(?:Env|[\w$]*Env|[\w$]*Bindings)$/.test(workerType(target)) && (configured || (key === 'fetch' && request));
+        bind(param, scope, worker);
+      }
+    } else if (['BlockStatement', 'ForStatement', 'ForOfStatement', 'ForInStatement', 'CatchClause', 'SwitchStatement', 'ClassExpression', 'ClassDeclaration', 'StaticBlock'].includes(node.type)) {
+      scope = { parent: scope, functionScope: node.type === 'StaticBlock', env: undefined };
+      if (node.type === 'CatchClause') bind(node.param, scope);
+      if (node.type === 'ClassExpression' || node.type === 'ClassDeclaration') bind(node.id, scope);
+    }
+    if (node.type === 'VariableDeclaration') {
+      let declarationScope = scope;
+      if (node.kind === 'var') while (!declarationScope.functionScope && declarationScope.parent) declarationScope = declarationScope.parent;
+      for (const declaration of node.declarations) bind(declaration.id, declarationScope);
+    }
+    if (node.type === 'ImportDeclaration') for (const spec of node.specifiers) bind(spec.local, scope);
+    if ((node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') && node.object?.type === 'Identifier' && node.object.name === 'env') {
+      const name = node.computed ? (node.property.type === 'StringLiteral' ? node.property.value : null) : node.property.name;
+      if (name) reads.push({ scope, name });
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (['loc', 'start', 'end', 'extra', 'comments', 'tokens'].includes(key)) continue;
+      if (Array.isArray(child)) for (const item of child) visit(item, scope, node);
+      else if (child && typeof child === 'object') visit(child, scope, node);
+    }
+  }
+  visit(ast.program, root, null);
+  const names = new Set();
+  for (const read of reads) {
+    let scope = read.scope;
+    while (scope && scope.env === undefined) scope = scope.parent;
+    if (scope?.env === true) names.add(read.name);
+  }
+  return names;
+}
+
+/** Optional parser argument makes the absent/failed-parser contract testable. */
+export function extractWorkerEnvBindings(content, filename = 'file.ts', configured = false, parse = workerParse) {
+  if (parse) {
+    try {
+      const plugins = ['decorators-legacy', 'classProperties', 'topLevelAwait'];
+      if (/\.[cm]?tsx?$/.test(filename)) plugins.push('typescript');
+      if (/\.[jt]sx?$/.test(filename) && !filename.endsWith('.ts')) plugins.push('jsx');
+      const ast = parse(content, { sourceType: 'unambiguous', allowReturnOutsideFunction: true, plugins });
+      return workerAstBindings(ast, configured);
+    } catch { /* Failed parsing retains conservative lexical evidence. */ }
+  }
+  return workerEnvUsageFallback(content, classifyChars(content, extname(filename)), configured);
+}
+
+// Resolve binding positions in simple lexical patterns, not property names.
+// Defaults may refer to env without introducing a new local env binding.
+function lexicalEnvBinding(pattern) {
+  const split = (text, delimiter) => {
+    const parts = []; let depth = 0, start = 0;
+    for (let i = 0; i < text.length; i++) {
+      if ('([{'.includes(text[i])) depth++;
+      else if (')]}'.includes(text[i])) depth--;
+      else if (text[i] === delimiter && depth === 0) { parts.push(text.slice(start, i)); start = i + 1; }
+    }
+    return [...parts, text.slice(start)];
+  };
+  const binding = text => {
+    text = split(text.trim().replace(/^\.\.\./, ''), '=')[0].trim();
+    if (text.startsWith('{') && text.endsWith('}')) {
+      return split(text.slice(1, -1), ',').some(property => {
+        const pair = split(property, ':');
+        return binding(pair.length > 1 ? pair.slice(1).join(':') : property);
+      });
+    }
+    if (text.startsWith('[') && text.endsWith(']')) return split(text.slice(1, -1), ',').some(binding);
+    return /^env\s*(?::[^]*)?$/.test(text);
+  };
+  return split(pattern, ',').some(binding);
+}
+
+/** Conservative, parser-independent support for ordinary typed function bodies. */
+function workerEnvUsageFallback(content, kind, configured) {
+  // Mask regex literals where an expression may start. Division remains code.
+  for (let i = 0; i < content.length; i++) {
+    if (kind[i] || content[i] !== '/') continue;
+    const prefix = content.slice(0, i).trimEnd();
+    if (prefix && !/[=(:,[!&|?{};]$/.test(prefix) && !/(?:\b(?:return|throw|yield|case)|=>)$/.test(prefix)) continue;
+    let end = i + 1, bracket = false;
+    for (; end < content.length && content[end] !== '\n'; end++) {
+      if (content[end] === '\\') { end++; continue; }
+      if (content[end] === '[') bracket = true;
+      if (content[end] === ']') bracket = false;
+      if (content[end] === '/' && !bracket) break;
+    }
+    if (content[end] === '/') { kind.fill(1, i, end + 1); i = end; }
+  }
+  const code = content.split('').map((ch, i) => kind[i] === 0 ? ch : (ch === '\n' ? '\n' : ' ')).join('');
+  const braces = new Map(), parens = new Map();
+  const stack = [], parentheses = [];
+  for (let i = 0; i < code.length; i++) {
+    if (code[i] === '{') stack.push(i);
+    else if (code[i] === '}' && stack.length) braces.set(stack.pop(), i);
+    else if (code[i] === '(') parentheses.push(i);
+    else if (code[i] === ')' && parentheses.length) parens.set(parentheses.pop(), i);
+  }
+  const scopes = [], functionScopes = [], loops = [];
+  const functions = /\(([^()]*)\)\s*(?::\s*[\w$.[\]<>| ,]+)?\s*(?:=>\s*)?\{/g;
+  for (const match of code.matchAll(functions)) {
+    const prefix = code.slice(Math.max(0, match.index - 80), match.index);
+    if (/\b(?:if|for|while|switch|with)\s*$/.test(prefix)) continue;
+    const start = match.index + match[0].length - 1, end = braces.get(start);
+    if (end === undefined) continue;
+    const scope = { start, end };
+    if (!/\bcatch\s*$/.test(prefix)) functionScopes.push(scope);
+    const params = match[1];
+    if (!lexicalEnvBinding(params)) continue;
+    const typed = /(?:^|,)\s*env\s*:\s*(?:Env|[\w$]*Env|[\w$]*Bindings)\s*(?=,|$)/.test(params);
+    const fetch = /\bfetch\s*(?::|=)?\s*$/.test(prefix);
+    const request = /^\s*[\w$]+\s*:\s*Request\s*,/.test(params);
+    scopes.push({ ...scope, binding: typed && (configured || (fetch && request)) });
+  }
+  for (const match of code.matchAll(/(?:\(\s*env\s*\)|\benv)\s*=>\s*/g)) {
+    const start = match.index + match[0].length;
+    let end = braces.get(start);
+    if (end === undefined) {
+      end = start; let depth = 0;
+      for (; end < code.length; end++) {
+        const ch = code[end];
+        if (depth === 0 && /[,;\n)}\]]/.test(ch)) break;
+        if ('({['.includes(ch)) depth++;
+        else if (')}]'.includes(ch)) depth--;
+      }
+    }
+    scopes.push({ start: start - 1, end, binding: false });
+  }
+  for (const match of code.matchAll(/\bfor\s*(?:await\s*)?\(/g)) {
+    const open = match.index + match[0].length - 1, close = parens.get(open);
+    if (close === undefined) continue;
+    let body = close + 1;
+    while (/\s/.test(code[body] || '') && body < code.length) body++;
+    const end = braces.get(body) ?? code.indexOf(';', body);
+    if (end >= 0) loops.push({ start: match.index, end, headerEnd: close });
+  }
+  for (const match of code.matchAll(/\b(const|let|var)\s+(env\b|\{[^;]*?\}|\[[^;]*?\])/g)) {
+    if (!lexicalEnvBinding(match[2])) continue;
+    let scope;
+    if (match[1] === 'var') {
+      scope = functionScopes.filter(s => s.start < match.index && match.index < s.end).sort((a, b) => b.start - a.start)[0];
+    } else {
+      scope = loops.find(s => s.start < match.index && match.index < s.headerEnd);
+      if (!scope) scope = [...braces].filter(([start, end]) => start < match.index && match.index < end)
+        .sort(([a], [b]) => b - a).map(([start, end]) => ({ start, end }))[0];
+    }
+    scopes.push({ ...(scope || { start: -1, end: code.length }), binding: false });
+  }
+  const names = new Set();
+  const access = /\benv\s*(?:(?:\?\.|\.)\s*([A-Za-z_$][\w$]*)|(?:\?\.)?\s*\[\s*['"]([A-Za-z_$][\w$]*)['"]\s*\])/g;
+  for (const match of content.matchAll(access)) {
+    if (kind[match.index] !== 0) continue;
+    if (/[\w$]$/.test(code.slice(0, match.index)) || /[.?]$/.test(code.slice(0, match.index).trimEnd())) continue;
+    const scope = scopes.filter(s => s.start < match.index && match.index < s.end)
+      .sort((a, b) => b.start - a.start || Number(a.binding) - Number(b.binding))[0];
+    if (scope?.binding) names.add(match[1] || match[2]);
+  }
+  return names;
+}
+
 export function grepEnvUsage(projectDir, config = {}) {
   const names = new Set();
   const roots = resolveSourceRoots(projectDir, config);
@@ -359,6 +578,9 @@ export function grepEnvUsage(projectDir, config = {}) {
     // the access KEYWORD (process/os/import) — for a real read the keyword is
     // code while only the argument 'X' is a string, so the name is still caught.
     const kind = classifyChars(content, extname(filePath));
+    if (['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'].includes(extname(filePath))) {
+      for (const name of extractWorkerEnvBindings(content, filePath, workerConfigForFile(projectDir, filePath))) names.add(name);
+    }
     // patterns[2] is the import.meta.env one — its matches are Vite-injected
     // when the name is an intrinsic, and must not be reported as user env vars.
     for (let i = 0; i < patterns.length; i++) {