@aqaf/cli 0.0.0-stage → 1.1.1

package/vendor/aqaf/documentation.py

@@ -0,0 +1,210 @@
+"""Separate unscored documentation observations; no target execution or certification."""
+from __future__ import annotations
+import ast
+import hashlib
+import re
+import unicodedata
+from pathlib import Path,PurePosixPath
+from urllib.parse import unquote,urlsplit
+from .scope import Scope
+
+
+def markdown_body(text):
+    """Remove fenced/indented samples, comments and inline code before link parsing."""
+    lines=[];fence=None
+    for line in text.splitlines():
+        m=re.match(r'^ {0,3}(`{3,}|~{3,})',line)
+        if m:
+            token=m.group(1)
+            if fence is None:fence=token
+            elif token[0]==fence[0] and len(token)>=len(fence):fence=None
+            lines.append('');continue
+        lines.append('' if fence or line.startswith(('    ','\t')) else line)
+    return re.sub(r'<!--[\s\S]*?-->|(`+).*?\1','', '\n'.join(lines))
+
+
+def links(text):
+    body=markdown_body(text);refs={}
+    for m in re.finditer(r'(?m)^ {0,3}\[([^]\n]+)\]:\s*<?([^\s>]+)>?',body):refs[m.group(1).casefold()]=m.group(2)
+    body=re.sub(r'(?m)^ {0,3}\[[^]\n]+\]:[^\n]*','',body)
+    found=[]
+    # Bounded balanced parentheses allow ordinary paths containing parentheses.
+    for m in re.finditer(r'!?\[([^]\n]*)\]\(\s*(<[^>\n]+>|(?:[^\s()\\]|\\.|\([^()\n]*\)){1,2048})(?:\s+["\'][^\n]*?["\'])?\s*\)',body):
+        found.append((m.group(2).strip('<>'),body.count('\n',0,m.start())+1))
+    for m in re.finditer(r'!?\[([^]\n]+)\](?:\[([^]\n]*)\])?(?![(:])',body):
+        key=(m.group(2) or m.group(1)).casefold()
+        if key in refs:found.append((refs[key],body.count('\n',0,m.start())+1))
+    return sorted(set(found),key=lambda x:(x[1],x[0]))
+
+
+def anchors(text):
+    result=set();counts={}
+    for line in markdown_body(text).splitlines():
+        m=re.match(r'^ {0,3}#{1,6}\s+(.+?)\s*#*$',line)
+        if not m:continue
+        label=re.sub(r'[^\w\- ]','',m.group(1).lower()).replace(' ','-')
+        n=counts.get(label,0);counts[label]=n+1;result.add(label+('-'+str(n) if n else ''))
+    result.update(re.findall(r'\bid=["\']([^"\']+)',text))
+    return result
+
+
+def documented_default(node,flag):
+    """Only JSON scalars; never return credential-shaped literal metadata."""
+    import math
+    if not isinstance(node,ast.Constant):return None,'unknown'
+    value=node.value
+    if type(value) not in {str,int,float,bool,type(None)} or (type(value) is float and not math.isfinite(value)):
+        return None,'unknown'
+    sensitive_name=re.search(r'password|passphrase|secret|token|key|credential|auth',flag,re.I)
+    sensitive_value=isinstance(value,str) and re.search(r'://[^/\s]+@|(?:api[_-]?key|token|password|secret)=[^&\s]+|^Bearer\s+\S+|^(?:sk-|gh[pousr]_|xox[baprs]-|AKIA)',value,re.I)
+    if value is not None and (sensitive_name or sensitive_value):return '[redacted]','redacted'
+    return value,'observed'
+
+
+def interfaces(scope):
+    facts=[];unknown=[];read_bytes=0;attempted=0
+    for r in scope.selected({'production','source','unknown','tooling'}):
+        if r['language']=='other' and r['path'].suffix not in {'.json','.service','.plist'}:continue
+        if attempted>=1000 or read_bytes>=16000000:
+            unknown.append({'reason':'interface_budget','remaining_coverage':'unknown'});break
+        attempted+=1
+        raw=scope.raw(r['path'],min(131072,16000000-read_bytes));read_bytes+=len(raw);text=raw.decode('utf8','replace');sha=hashlib.sha256(raw).hexdigest()
+        base={'path':r['relative'],'sha256':sha,'runtime_verified':False}
+        if r['language']=='python':
+            try:tree=ast.parse(text)
+            except (SyntaxError,ValueError,RecursionError):unknown.append({**base,'reason':'python_syntax_or_truncated'});continue
+            for node in ast.walk(tree):
+                if not isinstance(node,ast.Call):continue
+                name=node.func.attr if isinstance(node.func,ast.Attribute) else ''
+                if name=='add_argument':
+                    flags=[a.value for a in node.args if isinstance(a,ast.Constant) and isinstance(a.value,str) and a.value.startswith('--')]
+                    default_node=next((k.value for k in node.keywords if k.arg=='default'),None)
+                    for flag in flags:
+                        default,default_state=documented_default(default_node,flag)
+                        facts.append({**base,'kind':'cli_flag','name':flag,'default':default,'default_state':default_state,'line':node.lineno,'state':'observed'})
+                    if not flags:unknown.append({**base,'reason':'dynamic_cli_registration','line':node.lineno})
+                if name in {'get','post','put','patch','delete','route'} and node.args and isinstance(node.args[0],ast.Constant) and isinstance(node.args[0].value,str) and node.args[0].value.startswith('/'):
+                    facts.append({**base,'kind':'route_candidate','name':node.args[0].value,'method':name.upper(),'line':node.lineno,'state':'inferred'})
+        elif r['language'] in {'javascript','typescript','shell','powershell','cmd'}:
+            from .adapters import mask_source
+            try:view=mask_source(text,r['language'])[0] if r['language']!='cmd' else text
+            except (ValueError,RecursionError):
+                unknown.append({**base,'reason':'unsupported_or_truncated_syntax'});continue
+            if r['language'] in {'shell','powershell'}:
+                for i,line in enumerate(text.splitlines(),1):
+                    visible=view.splitlines()[i-1] if i<=len(view.splitlines()) else ''
+                    if not re.match(r'^\s*(?:exec\s+)?(?:python[23]?|node|pwsh)\s+',visible):continue
+                    m=re.match(r'^\s*(?:exec\s+)?(python[23]?|node|pwsh)\s+([\w./\\-]+)',line)
+                    if m:facts.append({**base,'kind':'launcher','name':m.group(1),'target':m.group(2),'line':i,'state':'observed','syntax_scope':'literal_launcher_only'})
+            if r['language']=='cmd':
+                for i,line in enumerate(text.splitlines(),1):
+                    if re.match(r'(?i)^\s*@?(?:rem\b|::)',line):continue
+                    m=re.match(r'(?i)^\s*@?(?:call\s+)?(python(?:3|\.exe)?|node(?:\.exe)?|powershell(?:\.exe)?|pwsh|java(?:\.exe)?)\s+([\w./\\-]+)',line)
+                    if m:facts.append({**base,'kind':'launcher','name':m.group(1),'target':m.group(2),'line':i,'state':'observed','syntax_scope':'literal_cmd_launcher_only'})
+            # String-bearing registration requires a call spelling outside strings/comments.
+            for m in re.finditer(r'\.(option|command|get|post|put|delete)\s*\(',view):
+                tail=text[m.end():m.end()+512];literal=re.match(r'\s*["\']([^"\'\n]{1,256})["\']',tail)
+                if literal:
+                    value=literal.group(1);kind='cli_flag' if m.group(1)=='option' else 'route_candidate'
+                    if kind=='cli_flag' and not value.startswith('-'):continue
+                    facts.append({**base,'kind':kind,'name':value.split()[0],'default':None,'state':'inferred','line':text.count('\n',0,m.start())+1})
+                else:unknown.append({**base,'reason':'dynamic_registration'})
+        if r['path'].suffix in {'.service','.plist'}:facts.append({**base,'kind':'service_definition','name':r['path'].name,'state':'observed'})
+        if re.search(r'\b(?:getenv|environ|process\.env)\b',text):unknown.append({**base,'reason':'environment_precedence_requires_review'})
+    return facts,unknown
+
+EXPECTATIONS={
+ 'desktop_ui':('end_user','install|installation','state|storage','reset|troubleshoot'),
+ 'desktop_widget':('end_user','install|installation','state|storage|reset'),
+ 'windows_service':('administrator','privilege|administrator|account','pair|trust|permission'),
+ 'browser_python':('learner','worker|stop|cancel','offline|asset|download'),
+ 'proxy':('operator','auth|token|access','stream','retention|logging'),
+ 'backup':('operator','restore|recovery','dry.run|preview|verify'),
+ 'ocr':('reviewer','evidence|confidence|manual.review','provenance|original|source'),
+ 'pdf_mapping':('content_author','page|mapping','provenance|source|chapter'),
+ 'apps_script':('administrator','permission|scope|oauth','deploy|installation'),
+ 'ide_extension':('developer','install|plugin','model|endpoint|privacy')}
+
+
+def check(root,scope=None,generated_routes=(),audience=None):
+    owned=scope is None;scope=scope or Scope(root).build();root=scope.root
+    try:
+        all_docs=[r for r in scope.records if r['path'].suffix.lower() in {'.md','.markdown'}]
+        docs=all_docs[:2048];budget=16000000;doc_partial=len(docs)<len(all_docs)
+        texts={};hashes={};seen={};duplicates=0;evidence=[];findings=[];finding_keys={}
+        for r in docs:
+            if budget<=0:doc_partial=True;break
+            raw=scope.raw(r['path'],min(262144,budget));budget-=len(raw)
+            if len(raw)!=r['size']:doc_partial=True
+            sha=hashlib.sha256(raw).hexdigest();texts[r['relative']]=raw.decode('utf8','replace')
+            hashes[r['relative']]={'sha256':sha,'bytes':len(raw),'complete_file':len(raw)==r['size']}
+            evidence.append({'path':r['relative'],**hashes[r['relative']],'kind':'documentation','audience':audience or 'unknown'})
+            if sha in seen:duplicates+=1
+            seen[sha]=r['relative']
+        def issue(rule,state,r,message,action,**extra):
+            h=hashes.get(r['relative'])
+            if h is None:
+                raw=scope.raw(r['path'],131072);h={'sha256':hashlib.sha256(raw).hexdigest(),'bytes':len(raw),'complete_file':len(raw)==r['size']}
+            key=(rule,state,h['sha256'],extra.get('target',extra.get('name',action)))
+            if key in finding_keys:
+                finding_keys[key].setdefault('copied_occurrences',[]).append(r['relative']);return
+            item={'rule_id':rule,'state':state,'path':r['relative'],**h,
+                'audience':audience or 'maintainer','consequence':message,'action':action,'priority':'medium' if state=='observed' else 'low',
+                'confirmed':False,'runtime_verified':False,**extra}
+            findings.append(item);finding_keys[key]=item
+        selected={x['relative'] for x in scope.records}
+        for r in docs:
+            if r['relative'] not in texts:continue
+            text=texts[r['relative']]
+            for target,line in links(text):
+                if re.match(r'^[a-z][a-z0-9+.-]*:',target,re.I) or target.startswith('//'):continue
+                parsed=urlsplit(target);link=unquote(parsed.path);fragment=unquote(parsed.fragment)
+                if link.startswith('/'):
+                    if link not in generated_routes:issue('AQD-LINK-003','unknown',r,'Root-relative route has no configured resolution.','Configure the generated route or verify it separately.',target=target,line=line)
+                    continue
+                candidate=r['path'].parent/link if link else r['path']
+                candidate=candidate.resolve()
+                try:rel=candidate.relative_to(root).as_posix()
+                except ValueError:
+                    issue('AQD-LINK-003','unknown',r,'Link leaves the selected root.','Verify the external local dependency separately.',target=target,line=line);continue
+                if rel not in selected and not candidate.is_dir():
+                    portable=[n for n in selected if unicodedata.normalize('NFC',n).casefold()==unicodedata.normalize('NFC',rel).casefold()]
+                    if portable:issue('AQD-LINK-002','observed',r,'Link differs in case or Unicode normalization.','Use the exact portable path spelling.',target=target,line=line)
+                    else:issue('AQD-LINK-001','observed' if not candidate.exists() else 'unknown',r,'Local link target is missing or outside selected scope.','Repair the link or declare its generated/excluded target.',target=target,line=line)
+                elif fragment and candidate in scope.by_path:
+                    if rel not in texts:
+                        issue('AQD-LINK-003','unknown',r,'Anchor target is outside the documentation read budget or supported Markdown scope.','Verify this fragment separately.',target=target,line=line)
+                    elif fragment not in anchors(texts[rel]):issue('AQD-LINK-004','inferred',r,'Heading anchor does not match the supported Markdown convention.','Verify renderer anchor rules and correct the fragment.',target=target,line=line)
+        interface,unknown=interfaces(scope)
+        canonical='\n'.join(t for p,t in texts.items() if not re.search(r'(?i)changelog|release.notes|history',p))
+        documented=set(re.findall(r'--[a-zA-Z][a-zA-Z0-9_-]*',canonical));known={x['name'] for x in interface if x['kind']=='cli_flag'}
+        for fact in interface:
+            if fact['kind']=='route_candidate' and fact['name'] not in canonical:
+                issue('AQD-API-001','inferred',scope.record(root/fact['path']),'A static route-shaped registration has no selected documentation mention.','Check whether this is an exposed route and document its method/authentication contract.',name=fact['name'])
+            if fact['kind']=='cli_flag' and fact['name'] not in documented:
+                r=scope.record(root/fact['path']);issue('AQD-CLI-001','inferred',r,'A static CLI flag is absent from selected current documentation.','Document this flag if it is public.',name=fact['name'])
+            if fact['kind']=='cli_flag' and fact.get('default') is not None and fact['default']!='[redacted]':
+                for line in canonical.splitlines():
+                    if fact['name'] in line:
+                        m=re.search(r'default\s*[:=]\s*[`"\']?([\w./-]+)',line,re.I)
+                        if m and m.group(1)!=str(fact['default']):
+                            issue('AQD-CLI-002','inferred',scope.record(root/fact['path']),'Documented default differs from a static literal.','Check precedence and update the public default.',name=fact['name']);break
+        for flag in sorted(documented-known):
+            if docs:issue('AQD-CLI-003','unknown',docs[0],'Documented flag was not found in supported static registrations.','Check rename, external command or dynamic registration.',name=flag)
+        from .facets import facets
+        capabilities=facets(scope)
+        present={x['facet'] for x in capabilities['facts']}
+        for facet,(reader,*patterns) in EXPECTATIONS.items():
+            if facet not in present:continue
+            for pattern in patterns:
+                if audience and audience!=reader:continue
+                if not re.search(pattern,canonical,re.I) and scope.records:
+                    issue('AQD-PRODUCT-001','inferred',scope.records[0],'Product evidence suggests an undocumented reader need: '+facet+'.','Review and document '+pattern+' for '+reader+'.',product_facet=facet,reader=reader)
+        for index,item in enumerate(findings):item['id']='doc-'+hashlib.sha256((item['rule_id']+item['path']+str(item.get('target',item.get('name',item['action'])))).encode()).hexdigest()[:20]
+        return {'schema_version':1,'kind':'aqaf_documentation_review','root':str(root),'status':'partial' if doc_partial or not scope.selection_complete() or any(x.get('reason') in {'interface_budget','unsupported_or_truncated_syntax','python_syntax_or_truncated'} for x in unknown) else 'complete_within_static_scope',
+            'score_effect':'none','certification':False,'coverage':{'documents_selected':len(all_docs),'documents_read':len(texts),'max_documents':2048,'max_document_bytes':16000000,'max_document_file_bytes':262144},'documents':evidence,'duplicate_documents':duplicates,'interfaces':interface,'interface_unknowns':unknown,
+            'capabilities':capabilities,'findings':findings,'backlog':[{'id':f['id'],'action':f['action'],'evidence':{'path':f['path'],'sha256':f['sha256']},'state':f['state'],'priority':f['priority']} for f in findings],
+            'applicability':[{'facet':facet,'reader':reader,'state':'not_applicable' if audience and audience!=reader else 'inferred' if facet in present else 'unknown'} for facet,(reader,*_) in EXPECTATIONS.items()],
+            'scope':scope.report(),'limitations':['Static bounded registrations only; dynamic interfaces and runtime claims require verification.','Document presence and term matches do not establish correctness or readability.','Renderer-specific anchors and complex Markdown remain reviewable unknowns.']}
+    finally:
+        if owned:scope.cache.close()

package/vendor/aqaf/evidence.py

@@ -0,0 +1,132 @@
+"""Bounded static evidence helpers. Never import or execute assessed project code."""
+from __future__ import annotations
+import os
+import ast
+from pathlib import Path
+import re
+
+_BLOCK_MARKER = re.compile(r'/\*|\*/')
+
+PACKAGE_MARKERS = ('.git', 'package.json', 'pyproject.toml', 'Cargo.toml', 'Package.swift',
+                   'pom.xml', 'settings.gradle', 'settings.gradle.kts', 'go.mod', 'composer.json')
+
+
+def _metadata_files(root, relative, suffixes):
+    """Known metadata locations only; no symlink traversal or unbounded ancestor walk."""
+    base = root
+    for part in Path(relative).parts:
+        base = base / part
+        if base.is_symlink():
+            return []
+    if base.is_file():
+        return [base] if base.suffix.lower() in suffixes else []
+    if not base.is_dir():
+        return []
+    found = []
+    visited = 0
+    for directory, dirs, names in os.walk(base, followlinks=False):
+        visited += 1
+        if visited > 256:
+            break
+        dirs[:] = sorted(d for d in dirs if not d.startswith('.') and not (Path(directory)/d).is_symlink())
+        for name in sorted(names):
+            path = Path(directory) / name
+            if not path.is_symlink() and path.is_file() and path.suffix.lower() in suffixes:
+                found.append(path)
+                if len(found) == 1000:
+                    return found
+    return found
+
+
+def _unique_paths(paths):
+    # Case-insensitive filesystems can resolve uppercase/lowercase candidates to
+    # one file. Preserve the first valid spelling; keep distinct Linux files.
+    seen = set(); result = []
+    for path in paths:
+        try:
+            info = path.stat(); identity = (info.st_dev, info.st_ino)
+        except OSError:
+            continue
+        if identity not in seen:
+            seen.add(identity); result.append(path)
+    return result
+
+
+def parent_context(root: Path):
+    """Consider only the immediate owner of a conventional source slice.
+
+    An independently marked package/repository never inherits its parent's docs.
+    Evidence is descriptive file presence, not verified architectural compliance.
+    """
+    root = root.resolve()
+    result = {'root': None, 'architecture_files': [], 'migration_files': []}
+    if root.name.lower() not in {'src', 'app', 'lib'} or any((root/name).exists() or (root/name).is_symlink() for name in PACKAGE_MARKERS):
+        return result
+    parent = root.parent
+    documents = []
+    for relative in ('architecture.md', 'ARCHITECTURE.md', 'architecture.rst', 'ARCHITECTURE.rst',
+                     'docs/architecture.md', 'docs/ARCHITECTURE.md', 'docs/architecture', 'docs/adr'):
+        documents.extend(_metadata_files(parent, relative, {'.md', '.rst', '.adoc'}))
+    migrations = []
+    for relative in ('migrations', 'prisma/migrations', 'alembic/versions', 'db/migrate', 'db/migrations'):
+        migrations.extend(_metadata_files(parent, relative, {'.sql', '.py', '.js', '.ts', '.rb', '.php', '.xml', '.json', '.yml', '.yaml'}))
+    documents = _unique_paths(documents)
+    migrations = _unique_paths(migrations)
+    if documents or migrations:
+        result = {'root': str(parent),
+                  'architecture_files': sorted({'../'+p.relative_to(parent).as_posix() for p in documents}),
+                  'migration_files': sorted({'../'+p.relative_to(parent).as_posix() for p in migrations})}
+    return result
+
+
+def code_tokens(text, rust=False):
+    """Mask comments and literals for narrow call/attribute heuristics, not parsing.
+
+    Rust block comments nest; Rust raw-string delimiters are preserved while
+    finding the closing quote. Template strings are masked as a whole.
+    """
+    single = r"'(?:\\.|[^'\\])*'" if not rust else r"'(?:\\[^\n]|[^'\\\n])'"
+    raw = r'(?P<raw>(?:br|r)(?P<hashes>#{0,255})")|' if rust else ''
+    pattern = re.compile(r'//[^\n]*|(?P<block>/\*)|' + raw + r'"(?:\\[\s\S]|[^"\\])*"|' + single + r'|`(?:\\[\s\S]|[^`\\])*`')
+    parts = []; offset = 0
+    while True:
+        match = pattern.search(text, offset)
+        if not match:
+            parts.append(text[offset:]); break
+        parts.append(text[offset:match.start()]); end = match.end()
+        if match.group('block'):
+            depth = 1
+            while depth:
+                marker = _BLOCK_MARKER.search(text, end)
+                if not marker:
+                    end = len(text); break
+                depth += 1 if marker.group() == '/*' else -1
+                end = marker.end()
+        elif rust and match.group('raw'):
+            closing = '"' + match.group('hashes')
+            position = text.find(closing, end)
+            end = len(text) if position < 0 else position + len(closing)
+        parts.append(''.join('\n' if c == '\n' else ' ' for c in text[match.start():end]))
+        offset = end
+    return ''.join(parts)
+
+
+def rust_test_count(text):
+    if not re.search(r'#\s*\[\s*(?:(?:tokio|async_std)\s*::\s*)?test(?:\s*\([^]]*\))?\s*\]', text):
+        return 0
+    tokens = code_tokens(text, rust=True)
+    return len(re.findall(r'#\s*\[\s*(?:(?:tokio|async_std)\s*::\s*)?test(?:\s*\([^]]*\))?\s*\]\s*(?:#\[[^\]]*\]\s*)*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+[A-Za-z_]\w*\s*\(', tokens))
+
+
+def has_warning_call(text, python=False):
+    pattern = r'\b(?:console|logger|log)\s*\.\s*warn(?:ing)?\s*\('
+    if not re.search(pattern, text): return False
+    if python:
+        try:
+            tree = ast.parse(text)
+        except (SyntaxError, RecursionError):
+            return False
+        return any(isinstance(n, ast.Call) and isinstance(n.func, ast.Attribute)
+                   and n.func.attr in {'warn', 'warning'} and isinstance(n.func.value, ast.Name)
+                   and n.func.value.id in {'console', 'logger', 'log'} for n in ast.walk(tree))
+    return bool(re.search(pattern, code_tokens(text)))

package/vendor/aqaf/facets.py

@@ -0,0 +1,63 @@
+"""Unscored product facets from bounded static evidence, separate from profiles."""
+import re
+import hashlib
+
+# Spelling evidence is an inferred capability, never proof of complete behavior.
+PATTERNS={
+ 'browser_python':r'\b(?:loadPyodide|runPythonAsync|pyodide)\b',
+ 'pseudocode':r'\b(?:parsePseudocode|PseudocodeParser|executePseudocode)\b',
+ 'ocr':r'\b(?:pytesseract|Tesseract|recognizeText|VNRecognizeTextRequest|OCRResult|OcrResult|ocr|ocr_[A-Za-z0-9_]+)\b',
+ 'grading':r'\b(?:grade_submission|evaluate_submission|EvaluationResult|criterion_scores)\b',
+ 'desktop_ui':r'\b(?:QApplication|NSApplication|Tk|WindowGroup|ApplicationWindow|QMainWindow)\b',
+ 'desktop_widget':r'\b(?:WidgetKit|WidgetConfiguration|AppWidgetProvider)\b',
+ 'windows_service':r'\b(?:ServiceBase|AddWindowsService|UseWindowsService|ServiceFramework)\b',
+ 'proxy':r'\b(?:StreamingResponse|ReverseProxy|ProxyPass|proxy_pass|http_proxy)\b',
+ 'authentication':r'\b(?:OAuth2PasswordBearer|AuthenticationMiddleware|AddAuthentication|login_required|verify_oauth2_token|verify_id_token|OAuth2AuthorizationCodeBearer)\b',
+ 'backup':r'\b(?:CreateBackup|create_backup|backup_source|BackupFlow|PortBackupSource)\b',
+ 'pdf_mapping':r'\b(?:page_map|page_mapping|chapter_manifest|build_book_packs)\b',
+ 'browser_worker':r'\b(?:Worker|postMessage|terminate)\b',
+ 'apps_script':r'\b(?:SpreadsheetApp|ScriptApp|DocumentApp)\b',
+ 'ide_extension':r'\b(?:ToolWindowFactory|AnAction|IntelliJPlatform|ProjectActivity)\b',
+ 'infrastructure':r'\b(?:subprocess|ProcessBuilder|StartProcess|Popen)\b',
+}
+
+def facets(scope,max_files=128,max_bytes=2000000,owner=None):
+    from .discovery import code_view,load_engine
+    engine=load_engine();facts=[];diagnostics=[];used=0;attempted=0
+    records=[r for r in scope.selected({'production','source','unknown','tooling'}) if owner is None or r['owner']==owner]
+    for record in records:
+        if record['language']=='other':continue
+        if attempted>=max_files or used>=max_bytes:break
+        raw=scope.raw(record['path'],min(32768,max_bytes-used));used+=len(raw);attempted+=1
+        text=raw.decode('utf8','replace')
+        try:view=code_view(text,record['language'],engine)
+        except (ValueError,RecursionError,SyntaxError):
+            diagnostics.append({'path':record['relative'],'reason':'unsupported_or_truncated_syntax'});continue
+        for facet,pattern in PATTERNS.items():
+            match=re.search(pattern,view)
+            if match:facts.append({'facet':facet,'state':'inferred','path':record['relative'],
+                'sha256':hashlib.sha256(raw).hexdigest(),'line':view.count('\n',0,match.start())+1,
+                'read_bytes':len(raw),'complete_file':len(raw)==record['size'],
+                'confirmed':False,'runtime_verified':False})
+    present={f['facet'] for f in facts}
+    delivery=sorted({kind for facet,kind in [('desktop_ui','desktop'),('browser_python','browser'),('browser_worker','browser'),('desktop_widget','desktop'),('windows_service','service'),('ide_extension','ide_plugin'),('apps_script','cloud_script')] if facet in present})
+    return {'delivery':delivery,'runtimes':sorted({r['language'] for r in records if r['language']!='other'}),'source_evidence_state':'bounded_source_sample' if attempted else 'metadata_only_or_unread','platform_constraints':['windows'] if 'windows_service' in present else ['apple'] if 'desktop_widget' in present and any(r['language']=='swift' for r in records) else ['unknown'],
+            'diagnostics':diagnostics[:200],'schema_version':1,'facts':facts,'attempted':attempted,'bytes':used,
+            'partial':bool(diagnostics) or attempted<sum(r['language']!='other' for r in records) or any(not f['complete_file'] for f in facts),
+            'interpretation':'Static capability spellings; absence from bounded evidence means unknown.'}
+
+
+def classification(scope):
+    """Existing profile IDs, shared selected roots, masked source-only text cues."""
+    from .discovery import code_view,load_engine
+    from .registry import Registry
+    engine=load_engine();records=[r for r in scope.records if r['owner']=='root']
+    code=[r['path'] for r in records if r['language']!='other']
+    def reader(path,limit=65536):
+        text=scope.text(path,limit);lang=scope.record(path).get('language')
+        if lang and lang!='other':
+            try:return code_view(text,lang,engine)
+            except (ValueError,RecursionError):return ''
+        return text
+    ident,evidence,confidence,alternatives=Registry().detect([r['path'] for r in records],scope.root,code,reader=reader)
+    return {'profile':ident,'evidence':evidence,'confidence':confidence,'alternatives':alternatives,'kind':'static_heuristic','confirmed':False}

package/vendor/aqaf/ignore.py

@@ -0,0 +1,109 @@
+"""Bounded .gitignore matching without Git, shell execution, or index access.
+
+Patterns apply to scanned files regardless of tracked status. Only ignore files
+inside the authorized root are loaded; global Git config is never consulted.
+"""
+from __future__ import annotations
+from dataclasses import dataclass
+import fnmatch
+import hashlib
+from pathlib import PurePosixPath
+
+MAX_IGNORE_BYTES = 131072
+MAX_RULES = 4096
+MAX_PATTERN = 512
+
+
+def _unescape(pattern):
+    out=[];i=0
+    while i<len(pattern):
+        if pattern[i]=='\\' and i+1<len(pattern):
+            i+=1;c=pattern[i];out.append({'*':'[*]','?':'[?]','[':'[[]'}.get(c,c))
+        elif pattern.startswith('[^',i):
+            # Git accepts both ! and ^ to negate a character class.
+            out.append('[!');i+=2;continue
+        else:out.append(pattern[i])
+        i+=1
+    return ''.join(out)
+
+
+def _components_match(pattern, parts):
+    # DP rather than a recursive/backtracking ** regex over an entire path.
+    states={0}
+    for index,component in enumerate(pattern):
+        next_states=set()
+        for pos in states:
+            if component=='**':
+                # A trailing '/**' matches descendants, never the parent itself.
+                minimum=1 if index==len(pattern)-1 and len(pattern)>1 else 0
+                next_states.update(range(pos+minimum,len(parts)+1))
+            elif pos<len(parts) and fnmatch.fnmatchcase(parts[pos],component):next_states.add(pos+1)
+        states=next_states
+        if not states:return False
+    return len(parts) in states
+
+
+@dataclass(frozen=True)
+class IgnoreRule:
+    base: tuple
+    pattern: tuple
+    basename: bool
+    directory_only: bool
+    negate: bool
+    source: str
+    line: int
+
+    def matches(self, relative, is_dir):
+        parts=PurePosixPath(relative).parts
+        if parts[:len(self.base)]!=self.base:return False
+        parts=parts[len(self.base):]
+        if not parts:return False
+        if self.basename:
+            return any(fnmatch.fnmatchcase(part,self.pattern[0]) and (not self.directory_only or i<len(parts)-1 or is_dir) for i,part in enumerate(parts))
+        # A matched directory also excludes descendants. The walker prunes
+        # excluded parents, so a later child negation cannot rescue them.
+        for end in range(1,len(parts)+1):
+            if self.directory_only and end==len(parts) and not is_dir:continue
+            if _components_match(self.pattern,parts[:end]):return True
+        return False
+
+
+def parse_ignore(raw, source='.gitignore'):
+    """Return rules plus an explicit diagnostic for unsupported/oversized input."""
+    if len(raw)>MAX_IGNORE_BYTES:return [],'oversized_gitignore'
+    try:text=raw.decode('utf-8-sig')
+    except UnicodeError:return [],'invalid_gitignore_encoding'
+    base=PurePosixPath(source).parent.parts
+    rules=[];diagnostic=None
+    for line_no,line in enumerate(text.splitlines(),1):
+        while line.endswith(' '):
+            preceding=len(line[:-1])-len(line[:-1].rstrip('\\'))
+            if preceding%2:break
+            line=line[:-1]
+        if not line or line.startswith('#'):continue
+        negate=line.startswith('!')
+        if negate:line=line[1:]
+        if not line:continue
+        directory=line.endswith('/')
+        if directory:line=line[:-1]
+        anchored=line.startswith('/')
+        if anchored:line=line[1:]
+        if not line:continue
+        if len(line)>MAX_PATTERN or len(line.split('/'))>64 or line.count('*')+line.count('?')>32 or '\x00' in line or '[[:' in line:
+            diagnostic='unsupported_gitignore_pattern';continue
+        basename='/' not in line and not anchored
+        pattern=tuple(_unescape(x) for x in line.split('/'))
+        rules.append(IgnoreRule(base,pattern,basename,directory,negate,source,line_no))
+        if len(rules)>=MAX_RULES:diagnostic='gitignore_rule_limit';break
+    return rules,diagnostic
+
+
+def ignore_decision(relative,is_dir,rules):
+    ignored=False;last=None
+    for rule in rules:
+        if rule.matches(relative,is_dir):ignored=not rule.negate;last=rule
+    return ignored,({'path':last.source,'line':last.line} if ignored and last else None)
+
+
+def ignore_evidence(raw, relative):
+    return {'path':relative,'sha256':hashlib.sha256(raw).hexdigest()}

package/vendor/aqaf/knowledge.py

@@ -0,0 +1,110 @@
+"""Optional, data-only book-informed review questions. Never scored detectors."""
+from __future__ import annotations
+import hashlib
+from importlib import resources
+import json
+import re
+from urllib.parse import urlsplit
+from pathlib import Path
+
+
+def load_knowledge():
+    data=json.loads(resources.files('aqaf').joinpath('data/book_review_knowledge.json').read_text(encoding='utf8'))
+    return validate_knowledge(data)
+
+
+def validate_knowledge(data):
+    if data.get('schema_version')!=1:raise ValueError('Unsupported review knowledge version')
+    books={b['id']:b for b in data['books']}
+    if len(books)!=len(data['books']):raise ValueError('Duplicate knowledge book')
+    routes=set()
+    for b in books.values():
+        if not b.get('edition') or not b.get('review_summary') or not b.get('review_contribution') or not b.get('reading_references'):
+            raise ValueError('Missing book reading metadata')
+        expected='/books/'+b['id']+'/'
+        if b.get('website_path')!=expected or not re.fullmatch(r'/books/[a-z0-9-]+/',expected):raise ValueError('Invalid book page')
+        for ref in b['reading_references']:
+            if ref.get('kind') not in {'chapter','topic','pattern'} or not ref.get('title') or ref.get('edition')!=b['edition']:
+                raise ValueError('Invalid reading reference')
+            if ref.get('number') is not None and not re.fullmatch(r'[1-9][0-9]*',str(ref['number'])):raise ValueError('Invalid reference number')
+            url=ref.get('source_url','');parsed=urlsplit(url)
+            if parsed.scheme!='https' or not parsed.hostname or parsed.username is not None or parsed.password is not None or any(c.isspace() or c=='\\' for c in url):raise ValueError('Invalid reference URL')
+            if ref.get('verification_status')!='verified_primary' or not re.fullmatch(r'\d{4}-\d{2}-\d{2}',ref.get('verified_on','')) or not ref.get('verification_basis'):
+                raise ValueError('Unverified reading reference')
+    ids=set()
+    for card in data['principles']:
+        if card['id'] in ids or not card['book_ids'] or not set(card['book_ids'])<=set(books):raise ValueError('Invalid knowledge references')
+        route=card.get('website_path','')
+        if not re.fullmatch(r'/learn/[a-z0-9-]+/',route) or route in routes:raise ValueError('Invalid guide page')
+        routes.add(route)
+        if not all(card.get(k) for k in ('explanation','example','counterexample','editorial_basis','example_basis')):raise ValueError('Incomplete guide')
+        ids.add(card['id'])
+        if set(card['applies_when'])!={'profiles','facets','languages'}:raise ValueError('Invalid knowledge applicability')
+    return data
+
+
+def review_agenda(scope,profile,paths=None):
+    """Ask context-sensitive questions, without interpreting absence as failure."""
+    from .facets import facets
+    allowed=set(Path(p) for p in paths) if paths is not None else set(scope.files)
+    records=[r for r in scope.records if r['path'] in allowed]
+    owners={r['owner'] for r in records}
+    context=facets(scope,owner=next(iter(owners)) if len(owners)==1 else None) if records else {'facts':[],'partial':False}
+    relative={r['relative'] for r in records}
+    facts=[f for f in context['facts'] if f['path'] in relative]
+    present={f['facet'] for f in facts};languages={r['language'] for r in records if r['language']!='other'}
+    # Evidence is deliberately bounded, contains no source bodies or default values.
+    samples=[]
+    for role in ({'production','source','unknown','tooling'},{'docs'},{'tests'}):
+        candidates=[r for r in records if r['role'] in role]
+        for r in candidates[:2]:
+            raw=scope.raw(r['path'],8192)
+            samples.append({'path':r['relative'],'role':r['role'],'sha256':hashlib.sha256(raw).hexdigest(),
+                            'bytes':len(raw),'complete_file':len(raw)==r['size'],'state':'observed_inventory_only'})
+    data=load_knowledge();books={b['id']:b for b in data['books']};questions=[]
+    for card in data['principles']:
+        when=card['applies_when'];basis=[]
+        if not any(when.values()):basis.append({'kind':'general_review','claim':'Applicability and adequacy require a reviewer; not a missing-feature finding.'})
+        if profile in when['profiles']:basis.append({'kind':'profile_hint','profile':profile,'confirmed':False})
+        for lang in sorted(languages & set(when['languages'])):basis.append({'kind':'language_presence','language':lang})
+        for f in facts:
+            if f['facet'] in when['facets']:basis.append({'kind':'inferred_static_facet',**f})
+        if not basis:continue
+        questions.append({k:card[k] for k in ('id','title','question','required_evidence','verification','limitations','explanation')} | {
+            'kind':'manual_verification','state':'unknown','confirmed':False,'runtime_verified':False,'mandatory':False,
+            'guide_url':'https://aqaf.focsd.com'+card['website_path'],
+            'applicability_basis':basis,'sources':[{'source_id':books[b]['source_id'],'book_id':b,'title':books[b]['title'],
+                'url':books[b]['primary_url'],'book_url':'https://aqaf.focsd.com'+books[b]['website_path'],
+                'edition':books[b]['edition'],'contribution':books[b]['review_contribution'],
+                'reading_references':books[b]['reading_references'],'basis':'secondary_application_notes','notes_path':books[b]['notes_path'],
+                'notes_sha256':books[b]['notes_sha256'],'full_book_reviewed':False} for b in card['book_ids']],
+            'completion_record':{'reviewer':None,'date':None,'evidence':[],'result':'unknown','not_applicable_reason':None}})
+    return {'schema_version':1,'knowledge_version':data['knowledge_version'],'kind':'book_informed_review_agenda','score_effect':'none',
+            'profile_hint':profile,'languages':sorted(languages),'questions':questions,'inventory_evidence':samples,
+            'context_sampling_partial':context.get('partial',False),'target_code_executed':False,
+            'limitations':data['limitations']+['Profile/facet hints select questions; they do not establish a product contract or a defect.',
+                'No repository commands, Git history, tests, network checks or hardware actions are executed.',
+                'Receiver validation, authentication, runtime behavior and architecture conformance need independent evidence.']}
+
+
+def markdown_agenda(agenda):
+    """Render current and earlier additive agenda records without online lookups."""
+    lines=['## Book-informed review agenda','','Optional human verification questions; unknown until reviewed. No score effect. Application guidance uses secondary notes; selected reading-reference facts were independently checked. These references do not validate detectors.','']
+    for q in agenda['questions']:
+        lines.extend(['### '+q['id']+' — '+q['title'],q['question']])
+        if q.get('explanation'):lines.extend(['',q['explanation']])
+        if q.get('guide_url'):lines.extend(['','[Why this matters and how to review it]('+q['guide_url']+')'])
+        lines.extend(['','- Evidence to request: '+q['required_evidence'],
+            '- Suggested verification (not executed): '+q['verification'],'- Limit: '+q['limitations'],
+            '- State: unknown; assign a reviewer and date or explain why not applicable.','', 'Further reading:'])
+        for source in q['sources']:
+            edition=' — '+source['edition'] if source.get('edition') else ''
+            contribution='. '+source['contribution'] if source.get('contribution') else ''
+            lines.extend(['- ['+source['title']+']('+source.get('book_url',source['url'])+')'+edition+contribution,
+                          '  Primary resource: ['+source['title']+']('+source['url']+').'])
+            for ref in source.get('reading_references',[]):
+                label=ref['kind'].capitalize()+(' '+ref['number'] if ref['number'] is not None else '')+': '+ref['title']
+                lines.append('  - ['+label+']('+ref['source_url']+') — '+ref['edition']+'; verified '+ref['verified_on']+' (title/number/edition only).')
+            lines.append('  Source ID: '+source['source_id']+'. Full book not reviewed.')
+        lines.append('')
+    return lines