@aqaf/cli 0.0.0-stage → 1.1.0

package/vendor/aqaf/data/source_registry.json

@@ -0,0 +1,302 @@
+[
+  {
+    "id": "B01",
+    "type": "book",
+    "title": "Software Architecture in Practice, 4e",
+    "authors_or_owner": "Bass; Clements; Kazman",
+    "edition_or_date": "2021",
+    "url": "https://www.oreilly.com/library/view/software-architecture-in/9780136885979/",
+    "relevant_for": "Quality attributes; architecture evaluation; tactics",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B02",
+    "type": "book",
+    "title": "Fundamentals of Software Architecture",
+    "authors_or_owner": "Richards; Ford",
+    "edition_or_date": "2020",
+    "url": "https://www.oreilly.com/library/view/fundamentals-of-software/9781492043447/",
+    "relevant_for": "Style trade-offs; architectural characteristics",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B03",
+    "type": "book",
+    "title": "Building Evolutionary Architectures, 2e",
+    "authors_or_owner": "Ford; Parsons; Kua; Sadalage",
+    "edition_or_date": "2022",
+    "url": "https://www.oreilly.com/library/view/building-evolutionary-architectures/9781492097532/",
+    "relevant_for": "Fitness functions and incremental governance",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B04",
+    "type": "book",
+    "title": "Designing Data-Intensive Applications",
+    "authors_or_owner": "Kleppmann",
+    "edition_or_date": "2017",
+    "url": "https://www.oreilly.com/library/view/designing-data-intensive-applications/9781491903063/",
+    "relevant_for": "Data consistency, storage, transactions, distributed systems",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B05",
+    "type": "book",
+    "title": "Domain-Driven Design",
+    "authors_or_owner": "Evans",
+    "edition_or_date": "2003",
+    "url": "https://www.pearson.de/domain-driven-design-tackling-complexity-in-the-heart-of-software-9780321125217",
+    "relevant_for": "Bounded contexts and domain language",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B06",
+    "type": "book",
+    "title": "Working Effectively with Legacy Code",
+    "authors_or_owner": "Feathers",
+    "edition_or_date": "2004",
+    "url": "https://www.oreilly.com/library/view/working-effectively-with/0131177052/",
+    "relevant_for": "Characterization tests and safe seams",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B07",
+    "type": "book",
+    "title": "Accelerate",
+    "authors_or_owner": "Forsgren; Humble; Kim",
+    "edition_or_date": "2018",
+    "url": "https://dl.acm.org/doi/10.5555/3235404",
+    "relevant_for": "Measuring delivery capabilities; not a code architecture score",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B08",
+    "type": "book",
+    "title": "Team Topologies, 2e",
+    "authors_or_owner": "Skelton; Pais",
+    "edition_or_date": "2025",
+    "url": "https://teamtopologies.com/books",
+    "relevant_for": "Architecture/team boundaries and cognitive load",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B09",
+    "type": "book",
+    "title": "Clean Architecture",
+    "authors_or_owner": "Robert C. Martin",
+    "edition_or_date": "2017",
+    "url": "https://www.oreilly.com/library/view/clean-architecture-a/9780134494272/",
+    "relevant_for": "Dependency direction; one design approach, not universal law",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B10",
+    "type": "book",
+    "title": "Monolith to Microservices",
+    "authors_or_owner": "Sam Newman",
+    "edition_or_date": "2019",
+    "url": "https://samnewman.io/books/monolith-to-microservices/",
+    "relevant_for": "Incremental extraction trade-offs",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B11",
+    "type": "book",
+    "title": "Software Architecture: The Hard Parts",
+    "authors_or_owner": "Ford; Richards; Sadalage; Dehghani",
+    "edition_or_date": "2021",
+    "url": "https://www.oreilly.com/library/view/software-architecture-the/9781492086888/",
+    "relevant_for": "Trade-off analysis and distribution costs",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B12",
+    "type": "book",
+    "title": "Release It!, 2e",
+    "authors_or_owner": "Michael Nygard",
+    "edition_or_date": "2018",
+    "url": "https://www.pragmatic.org/titles/mnee2/release-it-second-edition/",
+    "relevant_for": "Runtime resilience, stability and production operations",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B13",
+    "type": "book",
+    "title": "A Philosophy of Software Design, 2e",
+    "authors_or_owner": "John Ousterhout",
+    "edition_or_date": "2021",
+    "url": "https://www.web.stanford.edu/~ouster/cgi-bin/aposd.php",
+    "relevant_for": "Managing complexity; deep modules vs unnecessary layers",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B14",
+    "type": "book",
+    "title": "Patterns of Enterprise Application Architecture",
+    "authors_or_owner": "Martin Fowler",
+    "edition_or_date": "2002",
+    "url": "https://martinfowler.com/books/eaa.html",
+    "relevant_for": "Domain and data mapping patterns",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "B15",
+    "type": "book",
+    "title": "Understanding Software Dynamics",
+    "authors_or_owner": "Richard L. Sites",
+    "edition_or_date": "2021",
+    "url": "https://www.oreilly.com/library/view/understanding-software-dynamics/9780137589692/",
+    "relevant_for": "Evidence-based performance measurement",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S01",
+    "type": "official",
+    "title": "Codex Agents and AGENTS.md",
+    "authors_or_owner": "OpenAI",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://developers.openai.com/codex/guides/agents-md",
+    "relevant_for": "Agent repository instructions",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S02",
+    "type": "official",
+    "title": "OpenAI Agent Skills",
+    "authors_or_owner": "OpenAI",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://developers.openai.com/api/docs/guides/tools-skills",
+    "relevant_for": "Skill structure and versioning",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S03",
+    "type": "official",
+    "title": "Codex skills and prompt guidance update",
+    "authors_or_owner": "OpenAI",
+    "edition_or_date": "2026",
+    "url": "https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra",
+    "relevant_for": "Keep instructions concise, contextual",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S04",
+    "type": "official",
+    "title": "GitHub Actions Marketplace publishing",
+    "authors_or_owner": "GitHub",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://docs.github.com/en/actions/how-tos/create-and-publish-actions/publish-in-github-marketplace",
+    "relevant_for": "Separate action repository and root metadata",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S05",
+    "type": "official",
+    "title": "GitHub SARIF 2.1.0 support",
+    "authors_or_owner": "GitHub",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://docs.github.com/en/code-security/concepts/code-scanning/sarif-files",
+    "relevant_for": "Static analysis interchange format",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S06",
+    "type": "standard",
+    "title": "OWASP ASVS 5.0.0",
+    "authors_or_owner": "OWASP",
+    "edition_or_date": "2025",
+    "url": "https://asvs.owasp.org/",
+    "relevant_for": "Security requirements for web apps, separate from architecture fitness",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S07",
+    "type": "standard",
+    "title": "OpenSSF Scorecard",
+    "authors_or_owner": "OpenSSF",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://openssf.org/projects/scorecard/",
+    "relevant_for": "Open-source supply-chain hygiene",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S08",
+    "type": "official",
+    "title": "Swift Package Manager",
+    "authors_or_owner": "Swift project",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/",
+    "relevant_for": "Swift modularity and packages",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S09",
+    "type": "official",
+    "title": "Swift API Design Guidelines",
+    "authors_or_owner": "Swift project",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://www.swift.org/documentation/api-design-guidelines/",
+    "relevant_for": "Swift API consistency",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S10",
+    "type": "official",
+    "title": "The Cargo Book: workspaces",
+    "authors_or_owner": "Rust project",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://doc.rust-lang.org/cargo/reference/workspaces.html",
+    "relevant_for": "Rust crate/workspace separation",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S11",
+    "type": "official",
+    "title": "Rust Clippy",
+    "authors_or_owner": "Rust project",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://doc.rust-lang.org/clippy/",
+    "relevant_for": "Rust lint rules",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S12",
+    "type": "community",
+    "title": "ArchUnit",
+    "authors_or_owner": "ArchUnit",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://www.archunit.org/",
+    "relevant_for": "JVM architecture rule testing",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S13",
+    "type": "community",
+    "title": "dependency-cruiser",
+    "authors_or_owner": "dependency-cruiser",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://github.com/sverweij/dependency-cruiser",
+    "relevant_for": "JS/TS module dependencies",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S14",
+    "type": "official",
+    "title": "Android modularization guidance",
+    "authors_or_owner": "Android Developers",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://developer.android.com/topic/modularization",
+    "relevant_for": "Android module design",
+    "aqaf_independent_interpretation": true
+  },
+  {
+    "id": "S15",
+    "type": "official",
+    "title": "WordPress Plugin Handbook",
+    "authors_or_owner": "WordPress",
+    "edition_or_date": "accessed 2026-11-07",
+    "url": "https://developer.wordpress.org/plugins/",
+    "relevant_for": "Plugin structure and hooks",
+    "aqaf_independent_interpretation": true
+  }
+]

package/vendor/aqaf/registry.py

@@ -0,0 +1,124 @@
+"""Strictly data-only architecture profiles and packs. Does not import or execute extension code."""
+from __future__ import annotations
+import json
+import re
+from pathlib import Path
+from importlib import resources
+
+IDENT = re.compile(r'^[a-z][a-z0-9_]{1,63}$')
+SIGNALS = {'file','extension','path','text','json_key'}
+
+class ProfileError(ValueError):
+    pass
+
+
+def validate(doc, category):
+    if not isinstance(doc, dict) or doc.get('schema_version') != 1 or not IDENT.fullmatch(str(doc.get('id',''))):
+        raise ProfileError('Expected schema_version=1 and lowercase snake_case id')
+    if category == 'profile':
+        for key in ('name','product_type','target_architecture','status'):
+            if not isinstance(doc.get(key),str) or not doc[key].strip():
+                raise ProfileError(f'Profile {doc["id"]}: missing {key}')
+        if not isinstance(doc.get('packs'),list) or not all(IDENT.fullmatch(str(x)) for x in doc['packs']):
+            raise ProfileError(f'Profile {doc["id"]}: invalid packs')
+        if not isinstance(doc.get('detection'),list): raise ProfileError('detection must be a list')
+        for item in doc['detection']:
+            if not isinstance(item,dict) or item.get('kind') not in SIGNALS or not isinstance(item.get('value'),str) or not 0 <= item.get('weight',-1) <= 150:
+                raise ProfileError(f'Invalid declarative detection in {doc["id"]}')
+            if len(item['value']) > 200 or '..' in item['value']:
+                raise ProfileError('Unsafe/oversized detection value')
+    elif category == 'pack':
+        if not isinstance(doc.get('name'),str) or not isinstance(doc.get('profiles'),list):
+            raise ProfileError(f'Pack {doc["id"]}: invalid fields')
+        if not all(IDENT.fullmatch(str(p)) for p in doc['profiles']):
+            raise ProfileError('Invalid profile ID in pack')
+    return doc
+
+
+def read_doc(path: Path, category):
+    if path.is_symlink() or not path.is_file() or path.stat().st_size > 65536:
+        raise ProfileError(f'Invalid or oversized manifest: {path}')
+    try: return validate(json.loads(path.read_text(encoding='utf-8')), category)
+    except (OSError, ValueError) as e: raise ProfileError(f'{path}: {e}') from e
+
+
+class Registry:
+    def __init__(self, extra_dirs=(), extra_pack_dirs=()):
+        self.profiles = {}
+        self.packs = {}
+        pkg = resources.files('aqaf').joinpath('data')
+        for category, name, store in [('profile','profiles',self.profiles),('pack','packs',self.packs)]:
+            for item in sorted(pkg.joinpath(name).iterdir(), key=lambda p:p.name):
+                if item.name.endswith('.json'):
+                    value = validate(json.loads(item.read_text(encoding='utf-8')),category)
+                    if value['id'] in store: raise ProfileError('Duplicate built-in ID')
+                    store[value['id']] = value
+        for folder in extra_dirs:
+            path=Path(folder)
+            if not path.is_dir(): raise ProfileError(f'Profile directory not found: {path}')
+            for item in sorted(path.glob('*.json')):
+                value=read_doc(item,'profile')
+                if value['id'] in self.profiles:
+                    raise ProfileError(f'External profile may not override built-in ID {value["id"]}')
+                self.profiles[value['id']] = value
+        for folder in extra_pack_dirs:
+            path=Path(folder)
+            if not path.is_dir(): raise ProfileError(f'Pack directory not found: {path}')
+            for item in sorted(path.glob('*.json')):
+                value=read_doc(item,'pack')
+                if value['id'] in self.packs:
+                    raise ProfileError(f'External pack may not override built-in ID {value["id"]}')
+                self.packs[value['id']] = value
+        for pack in self.packs.values():
+            for p in pack['profiles']:
+                if p not in self.profiles: raise ProfileError(f'Pack {pack["id"]}: unknown profile {p}')
+
+    def get_profile(self, id):
+        if id not in self.profiles: raise ProfileError(f'Unknown product profile {id}; run aqaf profiles list')
+        return self.profiles[id]
+
+    def get_pack(self,id):
+        if id not in self.packs: raise ProfileError(f'Unknown pack {id}; run aqaf packs list')
+        return self.packs[id]
+
+    def detect(self, files, root, code, pack='auto'):
+        if pack!='auto': allowed=set(self.get_pack(pack)['profiles']) | {pid for pid,p in self.profiles.items() if pack in p['packs']}
+        else: allowed=set(self.profiles)
+        filenames={p.name.lower() for p in files}
+        extensions={p.suffix.lower() for p in code}
+        paths='\n'.join(str(p.relative_to(root)).replace('\\','/').lower() for p in files)
+        # Text signal sampling is bounded; this detector never executes target files.
+        snippets='\n'.join(_read_small(p)[:1500].lower() for p in code[:350])
+        candidates=[]
+        for id,profile in self.profiles.items():
+            if id not in allowed or id=='unknown_or_general_app': continue
+            evidence=[]; total=0
+            for s in profile['detection']:
+                kind=s['kind']; val=s['value']; weight=s['weight']; matched=False
+                if kind=='file': matched=val.lower() in filenames
+                elif kind=='extension': matched=val.lower() in extensions
+                elif kind=='path': matched=val.lower() in paths
+                elif kind=='text': matched=val.lower() in snippets
+                elif kind=='json_key':
+                    file_name,key=val.split(':',1) if ':' in val else ('','')
+                    for p in files:
+                        if p.name.lower()==file_name.lower():
+                            try:
+                                d=json.loads(_read_small(p,65536)); matched= key in d if isinstance(d,dict) else False
+                            except (ValueError,UnicodeError): pass
+                            if matched: break
+                if matched: total+=weight; evidence.append(kind+':'+val)
+            if evidence: candidates.append((total,id,evidence))
+        if not candidates: return 'unknown_or_general_app',[], 'low', []
+        candidates.sort(key=lambda x:(-x[0],x[1]))
+        best=candidates[0]
+        # Don't treat weak, generic evidence as an authoritative classification.
+        confidence='medium' if best[0]>=60 and (len(candidates)==1 or best[0]-candidates[1][0]>=20) else 'low'
+        summary=[{'profile':id,'signal_score':score,'signals':evidence} for score,id,evidence in candidates[:5]]
+        return best[1], best[2],confidence,summary
+
+
+def _read_small(p,limit=65536):
+    try:
+        with p.open('rb') as handle: return handle.read(limit).decode('utf-8','replace')
+    except OSError: return ''