docguard-cli 0.38.0 → 0.40.0

package/cli/shared-source.mjs

@@ -174,7 +174,7 @@ export function resolveSourceRoots(projectDir, config = {}) {
   for (const d of getWorkspaceDirs(projectDir)) add(d);
 
   // 3. conventional roots (only those that exist)
-  const conventional = ['src', 'app', 'lib', 'server', 'api', 'backend/src', 'backend', 'cli'];
+  const conventional = ['src', 'app', 'lib', 'server', 'api', 'functions', 'backend/src', 'backend', 'cli'];
   for (const cr of conventional) add(resolve(projectDir, cr));
 
   // 4. Fall back to the project root ONLY when nothing else resolved. Adding it
@@ -347,50 +347,120 @@ function workerType(param) {
   return type?.type === 'TSTypeReference' && type.typeName?.type === 'Identifier' ? type.typeName.name : '';
 }
 
-/** Static lexical binding analysis; collect declarations before resolving reads. */
+const WORKER_ENTRYPOINTS = new Set(['WorkerEntrypoint', 'DurableObject', 'WorkflowEntrypoint']);
+const WORKER_HANDLER_KEYS = new Set(['fetch', 'scheduled', 'queue', 'email', 'tail', 'trace', 'alarm', 'test']);
+const PAGES_HANDLER_RE = /^onRequest(?:Get|Post|Put|Patch|Delete|Head|Options)?$/;
+
+/**
+ * Static lexical binding analysis; collect declarations before resolving reads.
+ * @implements docguard.language-repository-coverage#FR-006
+ * @implements docguard.language-repository-coverage#FR-007
+ */
 function workerAstBindings(ast, configured) {
-  const root = { parent: null, functionScope: true, env: undefined };
+  const root = { parent: null, functionScope: true, bindings: new Map(), thisEnv: false };
   const reads = [];
-  const bind = (pattern, scope, value = false) => {
+  const exportedHandlers = new Set();
+  const bind = (pattern, scope, value = false, objectSource = null) => {
     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);
+    if (pattern.type === 'Identifier') scope.bindings.set(pattern.name, value);
+    else if (pattern.type === 'AssignmentPattern') bind(pattern.left, scope, value, objectSource);
+    else if (pattern.type === 'RestElement') bind(pattern.argument, scope, value, objectSource);
+    else if (pattern.type === 'ArrayPattern') for (const element of pattern.elements) bind(element, scope, false);
     else if (pattern.type === 'ObjectPattern') {
-      for (const property of pattern.properties) bind(property.type === 'RestElement' ? property.argument : property.value, scope, value);
+      for (const property of pattern.properties) {
+        if (property.type === 'RestElement') bind(property.argument, scope, false);
+        else {
+          const key = property.computed ? property.key?.value : (property.key?.name || property.key?.value);
+          bind(property.value, scope, objectSource === 'pages-context' && key === 'env' ? 'worker-env' : false);
+        }
+      }
+    }
+  };
+  const lookup = (name, scope) => {
+    while (scope) {
+      if (scope.bindings.has(name)) return scope.bindings.get(name);
+      scope = scope.parent;
     }
+    return undefined;
+  };
+  const propertyName = node => node?.computed
+    ? (node.property?.type === 'StringLiteral' ? node.property.value : null)
+    : (node?.property?.name || null);
+  const valueKind = (node, scope) => {
+    if (!node) return false;
+    if (node.type === 'Identifier') return lookup(node.name, scope) || false;
+    if (node.type !== 'MemberExpression' && node.type !== 'OptionalMemberExpression') return false;
+    const property = propertyName(node);
+    if (property !== 'env') return false;
+    if (node.object?.type === 'Identifier' && lookup(node.object.name, scope) === 'pages-context') return 'worker-env';
+    if (node.object?.type === 'ThisExpression' && scope.thisEnv) return 'worker-env';
+    return false;
   };
+
+  // Module imports and direct named exports are instantiated before execution,
+  // so collect their identity before walking source-order declarations.
+  for (const statement of ast.program.body || []) {
+    if (statement.type === 'ImportDeclaration') {
+      const trusted = statement.source?.value === 'cloudflare:workers';
+      for (const specifier of statement.specifiers || []) {
+        const imported = specifier.imported?.name || specifier.imported?.value;
+        const kind = trusted && imported === 'env' ? 'worker-env'
+          : trusted && WORKER_ENTRYPOINTS.has(imported) ? 'worker-entrypoint-class' : false;
+        if (specifier.local?.name) root.bindings.set(specifier.local.name, kind);
+      }
+    }
+    const declaration = statement.type === 'ExportNamedDeclaration' ? statement.declaration : null;
+    if (declaration?.type === 'FunctionDeclaration') exportedHandlers.add(declaration);
+    if (declaration?.type === 'VariableDeclaration') {
+      for (const item of declaration.declarations || []) if (item.init) exportedHandlers.add(item.init);
+    }
+  }
+
   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 };
+      const inheritedThis = node.type === 'ArrowFunctionExpression' ? scope.thisEnv
+        : ['ClassMethod', 'ClassPrivateMethod'].includes(node.type) ? scope.thisEnv : false;
+      scope = { parent: scope, functionScope: true, bindings: new Map(), thisEnv: inheritedThis };
       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) {
+      for (const param of node.params) bind(param, scope, false);
+      if (exportedHandlers.has(node) && PAGES_HANDLER_RE.test(key) && node.params[0]) {
+        const target = node.params[0].type === 'AssignmentPattern' ? node.params[0].left : node.params[0];
+        if (target.type === 'Identifier') bind(target, scope, 'pages-context');
+        else bind(target, scope, false, 'pages-context');
+      } else for (const param of node.params) {
         const target = param.type === 'AssignmentPattern' ? param.left : param;
+        const typed = /^(?:Env|[\w$]*Env|[\w$]*Bindings)$/.test(workerType(target));
         const worker = target.type === 'Identifier' && target.name === 'env' &&
-          /^(?:Env|[\w$]*Env|[\w$]*Bindings)$/.test(workerType(target)) && (configured || (key === 'fetch' && request));
-        bind(param, scope, worker);
+          ((configured && WORKER_HANDLER_KEYS.has(key)) || (typed && (configured || (key === 'fetch' && request))));
+        if (worker) bind(target, scope, 'worker-env');
       }
     } else if (['BlockStatement', 'ForStatement', 'ForOfStatement', 'ForInStatement', 'CatchClause', 'SwitchStatement', 'ClassExpression', 'ClassDeclaration', 'StaticBlock'].includes(node.type)) {
-      scope = { parent: scope, functionScope: node.type === 'StaticBlock', env: undefined };
+      const workerClass = ['ClassExpression', 'ClassDeclaration'].includes(node.type)
+        && node.superClass?.type === 'Identifier' && lookup(node.superClass.name, scope) === 'worker-entrypoint-class';
+      scope = { parent: scope, functionScope: node.type === 'StaticBlock', bindings: new Map(), thisEnv: workerClass || scope.thisEnv };
       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);
+      for (const declaration of node.declarations) {
+        const kind = valueKind(declaration.init, scope);
+        bind(declaration.id, declarationScope, kind, kind);
+      }
+    }
+    if (node.type === 'ImportDeclaration') {
+      for (const spec of node.specifiers) if (!scope.bindings.has(spec.local?.name)) bind(spec.local, scope);
     }
-    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 });
+    if (node.type === 'MemberExpression' || node.type === 'OptionalMemberExpression') {
+      const name = propertyName(node);
+      if (name) reads.push({ scope, name, object: node.object });
     }
     for (const [key, child] of Object.entries(node)) {
       if (['loc', 'start', 'end', 'extra', 'comments', 'tokens'].includes(key)) continue;
@@ -399,13 +469,7 @@ function workerAstBindings(ast, configured) {
     }
   }
   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;
+  return new Set(reads.filter(read => valueKind(read.object, read.scope) === 'worker-env').map(read => read.name));
 }
 
 /** Optional parser argument makes the absent/failed-parser contract testable. */
@@ -419,7 +483,13 @@ export function extractWorkerEnvBindings(content, filename = 'file.ts', configur
       return workerAstBindings(ast, configured);
     } catch { /* Failed parsing retains conservative lexical evidence. */ }
   }
-  return workerEnvUsageFallback(content, classifyChars(content, extname(filename)), configured);
+  const result = workerEnvUsageFallback(content, classifyChars(content, extname(filename)), configured);
+  const fallbackOnly = [];
+  if (/cloudflare:workers/.test(content) && /\bimport\s*\{[^}]*\benv\b/.test(content)) fallbackOnly.push('worker-imported-env-needs-ast');
+  if (/\bonRequest(?:Get|Post|Put|Patch|Delete|Head|Options)?\b/.test(content) && /\bcontext\s*\.\s*env\b/.test(content)) fallbackOnly.push('pages-context-needs-ast');
+  if (/\bextends\s+(?:WorkerEntrypoint|DurableObject|WorkflowEntrypoint)\b/.test(content) && /\bthis\s*\.\s*env\b/.test(content)) fallbackOnly.push('worker-class-env-needs-ast');
+  result.limitations = fallbackOnly;
+  return result;
 }
 
 // Resolve binding positions in simple lexical patterns, not property names.
@@ -537,6 +607,7 @@ function workerEnvUsageFallback(content, kind, configured) {
 
 export function grepEnvUsage(projectDir, config = {}) {
   const names = new Set();
+  names.limitations = [];
   const roots = resolveSourceRoots(projectDir, config);
   const seen = new Set();
 
@@ -579,7 +650,9 @@ export function grepEnvUsage(projectDir, config = {}) {
     // 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);
+      const workerBindings = extractWorkerEnvBindings(content, filePath, workerConfigForFile(projectDir, filePath));
+      for (const name of workerBindings) names.add(name);
+      for (const limitation of workerBindings.limitations || []) names.limitations.push({ code: limitation, file: rel.replace(/\\/g, '/') });
     }
     // 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.

package/cli/validators/architecture.mjs

@@ -20,6 +20,8 @@ import { resolve, join, extname, relative, dirname, basename } from 'node:path';
 import { shouldIgnore, isNonProductPath, walkFiles as sharedWalkFiles } from '../shared-ignore.mjs';
 import { mkFinding, resultFromFindings } from '../findings.mjs';
 import { resolveDocRole } from '../shared-doc-roles.mjs';
+import { getWorkspaceDirs } from '../shared-source.mjs';
+import { extractPythonFiles } from '../scanners/py-ast.mjs';
 
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.next', 'dist', 'build',
@@ -27,7 +29,7 @@ const IGNORE_DIRS = new Set([
   'templates', 'configs', 'Research', 'docs-canonical', 'docs-implementation',
 ]);
 
-const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
+const JS_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
 
 // v0.29: migrated to structured findings (ARC001–ARC003). Messages are
 // byte-identical to the legacy strings — resultFromFindings derives the
@@ -35,7 +37,7 @@ const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.mjs', '.cjs', '.jsx']);
 // helpers below mutate in place.
 export function validateArchitecture(projectDir, config = {}) {
   const acc = { findings: [], passed: 0, total: 0 };
-  let applicability = { status: 'checked', reason: 'JS/TS static import graph inspected; arbitrary runtime dependencies are not resolved' };
+  let applicability = { status: 'checked', reason: 'Repository-local JS/TS and Python static import graphs inspected; runtime dependency resolution is outside scope' };
   const compose = () => ({
     name: 'architecture',
     applicability,
@@ -50,16 +52,20 @@ export function validateArchitecture(projectDir, config = {}) {
 
   // ── 2. Auto-detect import graph ──
   const importGraph = buildImportGraph(projectDir, config);
-  if (importGraph.unsupportedFiles.length > 0) {
+  if (importGraph.limitations.length > 0) {
     applicability = {
       status: importGraph.files.length > 0 ? 'partial' : 'unsupported',
-      reason: 'Python import graph analysis is unsupported: relative imports, package paths, src-layout resolution and dynamic imports are not verified; JS/TS findings, when present, are retained',
+      reason: `Static import findings are retained; incomplete evidence: ${summarizeLimitations(importGraph.limitations)}`,
     };
   } else if (importGraph.files.length === 0) {
-    applicability = { status: 'not-applicable', reason: 'No supported JS/TS source files found for import graph analysis' };
+    applicability = { status: 'not-applicable', reason: 'No supported JS/TS or Python source files found for import graph analysis' };
   }
   if (importGraph.files.length === 0) return compose();
 
+  if (layers && Object.keys(layers).length > 0) {
+    validatePythonConfigLayers(importGraph, layers, acc);
+  }
+
   // ── 3. Detect circular dependencies ──
   const circles = detectCircularDeps(importGraph);
   for (const circle of circles) {
@@ -122,7 +128,7 @@ function validateConfigLayers(projectDir, config, layers, acc) {
 
     const files = getFilesRecursive(layerDir, config, projectDir);
     for (const file of files) {
-      if (!CODE_EXTENSIONS.has(extname(file))) continue;
+      if (!JS_EXTENSIONS.has(extname(file))) continue;
 
       const content = readFileSync(file, 'utf-8');
       const relPath = relative(projectDir, file);
@@ -155,20 +161,25 @@ function validateConfigLayers(projectDir, config, layers, acc) {
 // ── Import Graph Builder ────────────────────────────────────────────────────
 
 /**
- * Build the project's JS/TS import graph. Exported for reuse by `impact`
+ * Build the project's repository-local JS/TS and Python static import graph.
+ * Exported for reuse by `impact`
  * (indirect code→doc analysis walks this graph's reverse edges) — one graph
  * builder, not two.
  *
- * @returns {{files: string[], edges: {from,to,dynamic}[], fileMap: Map<string,string[]>}}
+ * @implements docguard.language-repository-coverage#FR-002
+ * @implements docguard.language-repository-coverage#FR-003
+ * @implements docguard.language-repository-coverage#FR-004
+ * @implements docguard.language-repository-coverage#FR-005
+ * @returns {{files: string[], edges: {from,to,dynamic,language}[], fileMap: Map<string,string[]>, unsupportedFiles: string[], limitations: object[]}}
  */
 export function buildImportGraph(projectDir, config) {
-  const graph = { files: [], edges: [], fileMap: new Map(), unsupportedFiles: [] };
+  const graph = { files: [], edges: [], fileMap: new Map(), unsupportedFiles: [], limitations: [] };
 
   const allFiles = getFilesRecursive(projectDir, config, projectDir);
-  graph.unsupportedFiles = allFiles
+  const pythonFiles = allFiles
     .filter(f => extname(f) === '.py' && !isNonProductPath(relative(projectDir, f).replace(/\\/g, '/'), config))
-    .map(f => relative(projectDir, f));
-  const codeFiles = allFiles.filter(f => CODE_EXTENSIONS.has(extname(f)));
+    .filter(f => !(config && shouldIgnore(relative(projectDir, f), config)));
+  const codeFiles = allFiles.filter(f => JS_EXTENSIONS.has(extname(f)));
 
   for (const file of codeFiles) {
     const relPath = relative(projectDir, file);
@@ -190,7 +201,7 @@ export function buildImportGraph(projectDir, config) {
         const fromDir = dirname(file);
         const resolved = resolveImport(fromDir, imp.spec, projectDir);
         if (resolved) {
-          graph.edges.push({ from: relPath, to: resolved, dynamic: imp.dynamic });
+          graph.edges.push({ from: relPath, to: resolved, dynamic: imp.dynamic, language: 'javascript' });
           // v0.28 (field report #2): a dynamic `await import()` does NOT create a
           // load-time edge — it's the canonical way to BREAK an import cycle. So
           // it's excluded from the cycle-detection adjacency (fileMap) while still
@@ -204,9 +215,171 @@ export function buildImportGraph(projectDir, config) {
     } catch { /* skip binary or unreadable files */ }
   }
 
+  addPythonImportGraph(projectDir, config || {}, pythonFiles, graph);
+
   return graph;
 }
 
+function posixPath(path) {
+  return path.replace(/\\/g, '/');
+}
+
+function summarizeLimitations(limitations) {
+  const labels = {
+    'python-interpreter-unavailable': 'Python interpreter unavailable',
+    'python-parse-failed': 'Python parse failure',
+    'python-dynamic-import': 'dynamic Python import',
+    'python-path-mutation': 'runtime sys.path mutation',
+    'python-relative-outside-package': 'relative import outside a resolvable package',
+    'python-ambiguous-module': 'ambiguous Python module across import roots',
+  };
+  const counts = new Map();
+  for (const item of limitations) counts.set(item.code, (counts.get(item.code) || 0) + 1);
+  return [...counts].map(([code, count]) => `${labels[code] || code}${count > 1 ? ` (${count})` : ''}`).join('; ');
+}
+
+function pythonImportRoots(projectDir, config, pythonFiles) {
+  const candidates = [];
+  const add = (path, priority) => {
+    const absolute = resolve(path);
+    if (!existsSync(absolute) || candidates.some(item => item.path === absolute)) return;
+    if (!pythonFiles.some(file => file === absolute || !relative(absolute, file).startsWith('..'))) return;
+    candidates.push({ path: absolute, priority });
+  };
+  const configured = config.sourceRoot ? (Array.isArray(config.sourceRoot) ? config.sourceRoot : [config.sourceRoot]) : [];
+  for (const root of configured) {
+    const absolute = resolve(projectDir, root);
+    if (existsSync(join(absolute, 'src'))) add(join(absolute, 'src'), 0);
+    add(absolute, 1);
+    if (existsSync(join(absolute, '__init__.py'))) add(dirname(absolute), 2);
+  }
+  for (const workspace of getWorkspaceDirs(projectDir)) {
+    if (existsSync(join(workspace, 'src'))) add(join(workspace, 'src'), 3);
+    add(workspace, 4);
+  }
+  if (existsSync(join(projectDir, 'src'))) add(join(projectDir, 'src'), 5);
+  add(projectDir, 6);
+  return candidates.sort((a, b) => a.priority - b.priority || b.path.length - a.path.length);
+}
+
+function pythonModuleForFile(file, roots) {
+  const containing = roots.filter(root => {
+    const rel = relative(root.path, file);
+    return rel !== '' && !rel.startsWith('..') && !rel.startsWith('/');
+  });
+  if (containing.length === 0) return null;
+  const selected = containing[0];
+  const rel = posixPath(relative(selected.path, file));
+  const parts = rel.replace(/\.py$/, '').split('/');
+  const isPackage = parts.at(-1) === '__init__';
+  if (isPackage) parts.pop();
+  if (parts.length === 0) return null;
+  let cursor = selected.path;
+  let namespace = false;
+  const packageParts = isPackage ? parts : parts.slice(0, -1);
+  for (const part of packageParts) {
+    cursor = join(cursor, part);
+    if (!existsSync(join(cursor, '__init__.py'))) namespace = true;
+  }
+  return { name: parts.join('.'), packageName: (isPackage ? parts : parts.slice(0, -1)).join('.'), namespace, root: selected.path };
+}
+
+function pythonImportCandidates(imp, owner) {
+  let base = imp.module || '';
+  if (imp.level > 0) {
+    const pkg = owner.packageName ? owner.packageName.split('.') : [];
+    const remove = imp.level - 1;
+    if (remove >= pkg.length && !(remove === 0 && pkg.length > 0)) return { candidates: [], outside: true };
+    const prefix = pkg.slice(0, pkg.length - remove);
+    base = [...prefix, ...(base ? base.split('.') : [])].join('.');
+  }
+  if (imp.kind === 'import') return { candidates: base ? [base] : [], outside: false };
+  const names = Array.isArray(imp.names) ? imp.names.filter(name => name && name !== '*') : [];
+  if (names.length === 0) return { candidates: base ? [base] : [], outside: false };
+  return { candidates: names.map(name => [base, name].filter(Boolean).join('.')), fallback: base || null, outside: false };
+}
+
+function addPythonImportGraph(projectDir, config, pythonFiles, graph) {
+  if (pythonFiles.length === 0) return;
+  const extracted = extractPythonFiles(pythonFiles);
+  if (extracted === null) {
+    graph.unsupportedFiles.push(...pythonFiles.map(file => posixPath(relative(projectDir, file))));
+    graph.limitations.push({ code: 'python-interpreter-unavailable', files: graph.unsupportedFiles.length });
+    return;
+  }
+  const roots = pythonImportRoots(projectDir, config, pythonFiles);
+  const moduleByFile = new Map();
+  const modules = new Map();
+  for (const file of pythonFiles) {
+    const owner = pythonModuleForFile(file, roots);
+    if (!owner) continue;
+    moduleByFile.set(file, owner);
+    if (!modules.has(owner.name)) modules.set(owner.name, []);
+    modules.get(owner.name).push({ file, ...owner });
+  }
+
+  for (const file of pythonFiles) {
+    const relPath = posixPath(relative(projectDir, file));
+    const parsed = extracted[file];
+    const owner = moduleByFile.get(file);
+    if (!parsed?.ok || !owner) {
+      graph.unsupportedFiles.push(relPath);
+      graph.limitations.push({ code: 'python-parse-failed', file: relPath });
+      continue;
+    }
+    graph.files.push(relPath);
+    const resolvedImports = [];
+    if (parsed.dynamicImports) graph.limitations.push({ code: 'python-dynamic-import', file: relPath });
+    if (parsed.pathMutation) graph.limitations.push({ code: 'python-path-mutation', file: relPath });
+    for (const imp of parsed.imports || []) {
+      const request = pythonImportCandidates(imp, owner);
+      if (request.outside) {
+        graph.limitations.push({ code: 'python-relative-outside-package', file: relPath });
+        continue;
+      }
+      const selected = [];
+      for (const candidate of request.candidates) {
+        const matches = modules.get(candidate) || [];
+        if (matches.length > 1) {
+          graph.limitations.push({ code: 'python-ambiguous-module', file: relPath, module: candidate });
+        } else if (matches.length === 1) {
+          selected.push(matches[0]);
+        }
+      }
+      if (selected.length === 0 && request.fallback) {
+        const matches = modules.get(request.fallback) || [];
+        if (matches.length > 1) graph.limitations.push({ code: 'python-ambiguous-module', file: relPath, module: request.fallback });
+        else if (matches.length === 1) selected.push(matches[0]);
+      }
+      for (const target of selected) {
+        const to = posixPath(relative(projectDir, target.file));
+        if (to === relPath || resolvedImports.includes(to)) continue;
+        graph.edges.push({ from: relPath, to, dynamic: false, language: 'python' });
+        resolvedImports.push(to);
+      }
+    }
+    graph.fileMap.set(relPath, resolvedImports);
+  }
+}
+
+function validatePythonConfigLayers(graph, layers, acc) {
+  const layerEntries = Object.entries(layers)
+    .filter(([, value]) => value?.dir && Array.isArray(value.canImport))
+    .map(([name, value]) => ({ name, dir: posixPath(value.dir).replace(/\/$/, ''), canImport: value.canImport }));
+  for (const edge of graph.edges.filter(item => item.language === 'python')) {
+    const from = layerEntries.find(layer => edge.from === layer.dir || edge.from.startsWith(`${layer.dir}/`));
+    const to = layerEntries.find(layer => edge.to === layer.dir || edge.to.startsWith(`${layer.dir}/`));
+    if (!from || !to || from.name === to.name || from.canImport.includes(to.name)) continue;
+    acc.total++;
+    acc.findings.push(mkFinding({
+      code: 'ARC001', validator: 'architecture', severity: 'error',
+      message: `${edge.from}: ${from.name} layer imports from forbidden layer (${to.dir})`,
+      location: edge.from,
+      suggestion: { kind: 'fix', text: 'Remove the import or route it through an allowed layer (see the layers config in .docguard.json)' },
+    }));
+  }
+}
+
 /**
  * Extract a file's imports as `{ spec, dynamic }`. `dynamic:true` marks a
  * runtime `import('…')` — which does NOT create a load-time dependency edge and

package/cli/validators/environment.mjs

@@ -1,3 +1,8 @@
+/**
+ * @implements docguard.language-repository-coverage#FR-006
+ * @implements docguard.language-repository-coverage#FR-007
+ * @implements docguard.language-repository-coverage#FR-008
+ */
 import { docRolePath, resolveDocRole } from '../shared-doc-roles.mjs';
 /**
  * Environment Validator — Checks ENVIRONMENT.md docs and .env.example
@@ -18,6 +23,7 @@ export function validateEnvironment(projectDir, config) {
   const findings = [];
   let passed = 0;
   let total = 0;
+  let applicability = null;
   const ptc = config.projectTypeConfig || {};
 
   const envDoc = docRolePath(config, 'environment');
@@ -113,6 +119,13 @@ export function validateEnvironment(projectDir, config) {
     }
 
     const codeUsed = grepEnvUsage(projectDir, config);
+    if (codeUsed.limitations?.length) {
+      const forms = [...new Set(codeUsed.limitations.map(item => item.code))].join(', ');
+      applicability = {
+        status: 'partial',
+        reason: `Environment findings are retained; the parser fallback cannot verify these Worker forms: ${forms}`,
+      };
+    }
 
     // Only assess when code actually reads env vars — otherwise the check is
     // vacuous (always passes) and would just inflate the count.
@@ -180,5 +193,5 @@ export function validateEnvironment(projectDir, config) {
     passed++;
   }
 
-  return { name: 'environment', ...resultFromFindings(findings, { passed, total }) };
+  return { name: 'environment', ...(applicability ? { applicability } : {}), ...resultFromFindings(findings, { passed, total }) };
 }

package/cli/validators/evidence.mjs

@@ -0,0 +1,52 @@
+/**
+ * Guard adapter for evidence-scoped verification.
+ * @implements docguard.evidence-scoped-verification#FR-010
+ */
+
+import { evaluateEvidence } from '../evidence/evaluate.mjs';
+import { mkFinding, resultFromFindings } from '../findings.mjs';
+
+const stateFinding = {
+  contradicted: {
+    code: 'EVD002', severity: 'error',
+    suggestion: { kind: 'review', text: 'Review approved intent and the current source, then correct the regressed side.' },
+  },
+  stale: {
+    code: 'EVD003', severity: 'warn',
+    suggestion: { kind: 'fix', text: 'Regenerate the saved upstream report and refresh its declared input hashes.', command: 'docguard verify --evidence' },
+  },
+  inconclusive: {
+    code: 'EVD004', severity: 'warn',
+    suggestion: { kind: 'fix', text: 'Restore safe, unique evidence or narrow the declaration.', command: 'docguard verify --evidence' },
+  },
+  unsupported: {
+    code: 'EVD005', severity: 'warn',
+    suggestion: { kind: 'report', text: 'Contribute a synthetic failing fixture and neighboring valid control before expanding the adapter.' },
+  },
+};
+
+export function validateEvidence(projectDir, config = {}) {
+  const evaluation = evaluateEvidence(projectDir, config);
+  if (!evaluation.exists) return { ...resultFromFindings([], { applicable: false }), evidence: evaluation };
+  const findings = [];
+  for (const error of evaluation.errors) {
+    findings.push(mkFinding({
+      code: 'EVD001', validator: 'evidence', severity: 'error', confidence: 'high',
+      message: error.declarationId ? `${error.declarationId}: ${error.message}` : error.message,
+      location: '.docguard-evidence.json',
+      suggestion: { kind: 'fix', text: 'Repair the strict manifest contract, then rerun evidence verification.', command: 'docguard verify --evidence' },
+      reportable: false,
+    }));
+  }
+  for (const result of evaluation.results) {
+    const contract = stateFinding[result.state];
+    if (!contract) continue;
+    findings.push(mkFinding({
+      ...contract, validator: 'evidence', confidence: 'high',
+      message: `${result.declarationId}: ${result.message} (${result.reasonCode})`,
+      location: result.location, reportable: false,
+    }));
+  }
+  const passed = evaluation.summary['verified-within-scope'] || 0;
+  return { ...resultFromFindings(findings, { passed, total: passed + findings.length, applicable: true }), evidence: evaluation };
+}

package/cli/validators/security.mjs

@@ -3,6 +3,7 @@
  *
  * Respects config.securityIgnore (glob patterns) and config.ignore (global).
  * Uses shared-ignore.mjs for consistent filtering (Constitution IV, v1.1.0).
+ * @implements docguard.precision-evidence-loop#FR-003
  */
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
@@ -35,10 +36,10 @@ const IGNORE_DIRS = new Set([
 
 // Patterns that might indicate hardcoded secrets
 const SECRET_PATTERNS = [
-  { pattern: /(?:password|passwd|pwd)\s*[:=]\s*['"][^'"]{8,}['"]/gi, label: 'hardcoded password' },
-  { pattern: /(?:api[_-]?key|apikey)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded API key' },
-  { pattern: /(?:secret[_-]?key|secretkey)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded secret key' },
-  { pattern: /(?:access[_-]?token|accesstoken)\s*[:=]\s*['"][^'"]{16,}['"]/gi, label: 'hardcoded access token' },
+  { pattern: /(?:password|passwd|pwd)\??\s*(?:=\s*|:\s*(?:[^'";=\n]+?=\s*)?)['"][^'"]{8,}['"]/gi, label: 'hardcoded password' },
+  { pattern: /(?:api[_-]?key|apikey)\??\s*(?:=\s*|:\s*(?:[^'";=\n]+?=\s*)?)['"][^'"]{16,}['"]/gi, label: 'hardcoded API key' },
+  { pattern: /(?:secret[_-]?key|secretkey)\??\s*(?:=\s*|:\s*(?:[^'";=\n]+?=\s*)?)['"][^'"]{16,}['"]/gi, label: 'hardcoded secret key' },
+  { pattern: /(?:access[_-]?token|accesstoken)\??\s*(?:=\s*|:\s*(?:[^'";=\n]+?=\s*)?)['"][^'"]{16,}['"]/gi, label: 'hardcoded access token' },
   { pattern: /AKIA[0-9A-Z]{16}/g, label: 'AWS Access Key ID' },
   { pattern: /(?:sk-|sk_live_|sk_test_)[a-zA-Z0-9]{20,}/g, label: 'API secret key (Stripe/OpenAI pattern)' },
 ];

package/cli/validators/todo-tracking.mjs

@@ -119,9 +119,10 @@ function skippedCalls(content, filename) {
 // Parser failure/unavailability cannot turn an unexplained skip into a pass.
 function fallbackSkippedCalls(content) {
   const lines = content.split('\n');
+  const codeLines = maskJsNonCode(content).split('\n');
   const calls = [];
-  for (let i = 0; i < lines.length; i++) {
-    if (!SKIP_PATTERNS.some(p => p.test(lines[i]))) continue;
+  for (let i = 0; i < codeLines.length; i++) {
+    if (!SKIP_PATTERNS.some(p => p.test(codeLines[i]))) continue;
     // Only a directly preceding comment is unambiguous without a parser.
     const previous = lines[i - 1] || '';
     calls.push({ line: i + 1, hasReason: /^\s*\/\//.test(previous) &&
@@ -130,6 +131,48 @@ function fallbackSkippedCalls(content) {
   return calls;
 }
 
+/**
+ * Preserve line structure while hiding comments and string/template literals.
+ * This keeps the parser-failure fallback from treating fixture text such as
+ * `"test.skip()"` as executable code. Template interpolation is intentionally
+ * masked with the surrounding template: on malformed input it is safer to miss
+ * that uncommon form than to report prose as a real skipped test.
+ */
+function maskJsNonCode(content) {
+  let state = 'code';
+  let escaped = false;
+  let out = '';
+  for (let i = 0; i < content.length; i++) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (state === 'code') {
+      if (ch === '/' && next === '/') { out += '  '; i++; state = 'line-comment'; continue; }
+      if (ch === '/' && next === '*') { out += '  '; i++; state = 'block-comment'; continue; }
+      if (ch === "'") { out += ' '; state = 'single'; escaped = false; continue; }
+      if (ch === '"') { out += ' '; state = 'double'; escaped = false; continue; }
+      if (ch === '`') { out += ' '; state = 'template'; escaped = false; continue; }
+      out += ch;
+      continue;
+    }
+    if (ch === '\n') {
+      out += '\n';
+      if (state === 'line-comment') state = 'code';
+      if (state === 'single' || state === 'double') escaped = false;
+      continue;
+    }
+    if (state === 'block-comment' && ch === '*' && next === '/') {
+      out += '  '; i++; state = 'code'; continue;
+    }
+    if (state === 'line-comment' || state === 'block-comment') { out += ' '; continue; }
+    const quote = state === 'single' ? "'" : state === 'double' ? '"' : '`';
+    if (!escaped && ch === quote) { out += ' '; state = 'code'; continue; }
+    if (!escaped && ch === '\\') { escaped = true; out += ' '; continue; }
+    escaped = false;
+    out += ' ';
+  }
+  return out;
+}
+
 /**
  * Main validator — checks for untracked TODOs and unexplained test skips.
  *