dorksmith 0.1.0__tar.gz

dorksmith-0.1.0/.gitignore

@@ -0,0 +1,55 @@
+# Spec (kept local)
+SPECS.md
+specs.md
+
+# .NET
+bin/
+obj/
+*.user
+*.suo
+.vs/
+TestResults/
+*.trx
+
+# State / data
+state/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Node (test-only, if ever added)
+node_modules/
+playwright-report/
+test-results/
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+
+# Tooling caches
+graft/
+.claude/
+
+# Playwright
+web/tests/node_modules/
+web/tests/playwright-report/
+web/tests/test-results/
+
+# Packages
+packages/dorksmith-js/node_modules/
+packages/dorksmith-js/dist/
+packages/dorksmith-py/dist/
+packages/dorksmith-py/build/
+packages/dorksmith-py/*.egg-info/
+packages/dorksmith-py/src/*.egg-info/
+__pycache__/
+*.pyc
+.pytest_cache/
+.venv/

dorksmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aelena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dorksmith-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.5
+Name: dorksmith
+Version: 0.1.0
+Summary: Deterministic search-dork generator and OSINT/SOCMINT query engine. Catalog-driven, pure Python, no dependencies.
+Project-URL: Homepage, https://github.com/aelena/dorksmith
+Project-URL: Repository, https://github.com/aelena/dorksmith
+Project-URL: Issues, https://github.com/aelena/dorksmith/issues
+Project-URL: Changelog, https://github.com/aelena/dorksmith/commits/main/packages/dorksmith-py
+Author: aelena
+License: MIT License
+        
+        Copyright (c) 2026 aelena
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: deterministic,dork,google-dorks,osint,search-operators,security,socmint
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
+Classifier: Topic :: Security
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# dorksmith (PyPI)
+
+Deterministic search-dork generator and OSINT/SOCMINT query engine as a pure-Python package with no dependencies (Python ≥ 3.10). Same engine and catalogs as the [Dorksmith](https://github.com/aelena/dorksmith) web app and the npm package, conformance-tested against the same golden fixtures.
+
+```bash
+pip install dorksmith
+```
+
+```python
+from dorksmith import generate, expand_handle, validate_query, search_url
+
+result = generate("example.com", "domain", "public-documents",
+                  options={"fileTypes": ["pdf", "docx"], "excludeTerms": ["jobs"], "maxVariants": 3})
+for v in result.variants:
+    print(f"{v.label:<14} {v.query}")
+# Balanced       site:example.com (filetype:pdf OR filetype:docx) -jobs
+# Precise        site:example.com filetype:pdf -jobs
+# Title-focused  site:example.com (filetype:pdf OR filetype:docx) (intitle:report OR intitle:policy OR intitle:presentation OR intitle:"annual report") -jobs
+
+search_url(result.variants[0].query)
+# 'https://www.google.com/search?q=site%3Aexample.com%20%28filetype%3Apdf%20OR%20filetype%3Adocx%29%20-jobs'
+
+handle = expand_handle("@alice42", categories=["developer"], max_platforms=3)
+handle.profiles[0].url, handle.profiles[0].status
+# ('https://github.com/alice42', 'not-checked')
+
+validate_query("cache:example.com site:example.com or filetype:.pdf").warnings
+# ["Lower-case 'or' is treated as an ordinary word; ...", "filetype: values take no leading dot ...", "cache: is deprecated: ..."]
+```
+
+Results are dataclasses; `.to_dict()` gives the same camelCase shape as the HTTP API (`POST /api/v1/dorks/generate`), minus `requestId` and `rateLimit`.
+
+## API
+
+| Function | Purpose |
+|---|---|
+| `generate(input, input_type, intent, *, engine="google", options=None, catalogs=None, limits=DEFAULT_LIMITS)` | Ranked variants with explanation, operators, warnings and rank reason. Raises `InputValidationError` (`.field`, `.unprocessable`). |
+| `validate_query(query, engine="google", catalogs=None)` | Operators used with support state and warnings. Never rewrites the query. |
+| `expand_handle(username, *, categories=None, platform_ids=None, max_platforms=None, catalogs=None)` | Profile URLs (`status` always `not-checked`) and site-scoped queries. |
+| `infer_input_type(text, known_extensions=None)` | Deterministic input-type suggestion. |
+| `search_url(query, engine="google")` | Search-engine URL, percent-encoded locally. |
+| `validate_catalogs(catalogs)` | Structural/cross-reference validation, same rules as the API's readiness check. |
+| `bundled_catalogs()`, `load_catalogs(path)`, `catalog_version()` | Embedded or custom catalogs. |
+| lower-level: `normalize_text`, `try_normalize_domain`, `quote`, `safe_term`, `analyze_query`, `expand_template`, … | Building blocks for custom pipelines. |
+
+`options` keys match the HTTP API: `fileTypes`, `excludeTerms`, `after`, `before`, `site`, `maxVariants`, `organization`, `location`, `role`, `displayName`.
+
+### Bring your own catalogs
+
+```python
+from dorksmith import load_catalogs, validate_catalogs, generate
+catalogs = load_catalogs("path/to/data")      # operators.google.json, intents.json, platforms.json, filetypes.json
+assert validate_catalogs(catalogs) == []
+generate("x", "keyword", "general-discovery", catalogs=catalogs)
+```
+
+## CLI
+
+```bash
+dorksmith generate example.com --intent exposed-config-files --max 3
+dorksmith generate "Alice Smith" --intent person-organization --organization "Example Corp"
+dorksmith handle alice42 --categories developer --json
+dorksmith validate 'cache:example.com site:example.com'
+dorksmith intents
+```
+
+Exit codes: `0` ok, `2` invalid input (or a query with syntax errors for `validate`), `3` valid request that cannot be generated.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python scripts/sync_catalogs.py      # copies ../../data/*.json into src/dorksmith/data
+python -m pytest -q                  # unit tests + the 151 golden fixtures from the monorepo
+python -m build                      # sdist + wheel
+```
+
+Publishing is done by the `py-package` GitHub workflow when a `py-v*` tag is pushed, using PyPI trusted publishing (see the repository README).

dorksmith-0.1.0/README.md

@@ -0,0 +1,78 @@
+# dorksmith (PyPI)
+
+Deterministic search-dork generator and OSINT/SOCMINT query engine as a pure-Python package with no dependencies (Python ≥ 3.10). Same engine and catalogs as the [Dorksmith](https://github.com/aelena/dorksmith) web app and the npm package, conformance-tested against the same golden fixtures.
+
+```bash
+pip install dorksmith
+```
+
+```python
+from dorksmith import generate, expand_handle, validate_query, search_url
+
+result = generate("example.com", "domain", "public-documents",
+                  options={"fileTypes": ["pdf", "docx"], "excludeTerms": ["jobs"], "maxVariants": 3})
+for v in result.variants:
+    print(f"{v.label:<14} {v.query}")
+# Balanced       site:example.com (filetype:pdf OR filetype:docx) -jobs
+# Precise        site:example.com filetype:pdf -jobs
+# Title-focused  site:example.com (filetype:pdf OR filetype:docx) (intitle:report OR intitle:policy OR intitle:presentation OR intitle:"annual report") -jobs
+
+search_url(result.variants[0].query)
+# 'https://www.google.com/search?q=site%3Aexample.com%20%28filetype%3Apdf%20OR%20filetype%3Adocx%29%20-jobs'
+
+handle = expand_handle("@alice42", categories=["developer"], max_platforms=3)
+handle.profiles[0].url, handle.profiles[0].status
+# ('https://github.com/alice42', 'not-checked')
+
+validate_query("cache:example.com site:example.com or filetype:.pdf").warnings
+# ["Lower-case 'or' is treated as an ordinary word; ...", "filetype: values take no leading dot ...", "cache: is deprecated: ..."]
+```
+
+Results are dataclasses; `.to_dict()` gives the same camelCase shape as the HTTP API (`POST /api/v1/dorks/generate`), minus `requestId` and `rateLimit`.
+
+## API
+
+| Function | Purpose |
+|---|---|
+| `generate(input, input_type, intent, *, engine="google", options=None, catalogs=None, limits=DEFAULT_LIMITS)` | Ranked variants with explanation, operators, warnings and rank reason. Raises `InputValidationError` (`.field`, `.unprocessable`). |
+| `validate_query(query, engine="google", catalogs=None)` | Operators used with support state and warnings. Never rewrites the query. |
+| `expand_handle(username, *, categories=None, platform_ids=None, max_platforms=None, catalogs=None)` | Profile URLs (`status` always `not-checked`) and site-scoped queries. |
+| `infer_input_type(text, known_extensions=None)` | Deterministic input-type suggestion. |
+| `search_url(query, engine="google")` | Search-engine URL, percent-encoded locally. |
+| `validate_catalogs(catalogs)` | Structural/cross-reference validation, same rules as the API's readiness check. |
+| `bundled_catalogs()`, `load_catalogs(path)`, `catalog_version()` | Embedded or custom catalogs. |
+| lower-level: `normalize_text`, `try_normalize_domain`, `quote`, `safe_term`, `analyze_query`, `expand_template`, … | Building blocks for custom pipelines. |
+
+`options` keys match the HTTP API: `fileTypes`, `excludeTerms`, `after`, `before`, `site`, `maxVariants`, `organization`, `location`, `role`, `displayName`.
+
+### Bring your own catalogs
+
+```python
+from dorksmith import load_catalogs, validate_catalogs, generate
+catalogs = load_catalogs("path/to/data")      # operators.google.json, intents.json, platforms.json, filetypes.json
+assert validate_catalogs(catalogs) == []
+generate("x", "keyword", "general-discovery", catalogs=catalogs)
+```
+
+## CLI
+
+```bash
+dorksmith generate example.com --intent exposed-config-files --max 3
+dorksmith generate "Alice Smith" --intent person-organization --organization "Example Corp"
+dorksmith handle alice42 --categories developer --json
+dorksmith validate 'cache:example.com site:example.com'
+dorksmith intents
+```
+
+Exit codes: `0` ok, `2` invalid input (or a query with syntax errors for `validate`), `3` valid request that cannot be generated.
+
+## Development
+
+```bash
+python -m pip install -e ".[test]"
+python scripts/sync_catalogs.py      # copies ../../data/*.json into src/dorksmith/data
+python -m pytest -q                  # unit tests + the 151 golden fixtures from the monorepo
+python -m build                      # sdist + wheel
+```
+
+Publishing is done by the `py-package` GitHub workflow when a `py-v*` tag is pushed, using PyPI trusted publishing (see the repository README).

dorksmith-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dorksmith"
+version = "0.1.0"
+description = "Deterministic search-dork generator and OSINT/SOCMINT query engine. Catalog-driven, pure Python, no dependencies."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [{ name = "aelena" }]
+requires-python = ">=3.10"
+keywords = ["osint", "socmint", "google-dorks", "search-operators", "dork", "security", "deterministic"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Information Technology",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+  "Topic :: Internet :: WWW/HTTP :: Indexing/Search",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://github.com/aelena/dorksmith"
+Repository = "https://github.com/aelena/dorksmith"
+Issues = "https://github.com/aelena/dorksmith/issues"
+Changelog = "https://github.com/aelena/dorksmith/commits/main/packages/dorksmith-py"
+
+[project.scripts]
+dorksmith = "dorksmith.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dorksmith"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/dorksmith", "tests", "scripts", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dorksmith-0.1.0/scripts/sync_catalogs.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+"""Copy the repository catalogs (../../data/*.json) into src/dorksmith/data.
+
+`--check` exits non-zero when the embedded copies differ (used in CI).
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+PKG = HERE.parent
+SOURCE = PKG.parent.parent / "data"
+TARGET = PKG / "src" / "dorksmith" / "data"
+
+
+def main() -> int:
+    check = "--check" in sys.argv
+    if not SOURCE.is_dir():
+        print(f"no repository data directory at {SOURCE}; keeping embedded catalogs")
+        return 0
+    TARGET.mkdir(parents=True, exist_ok=True)
+    changed = False
+    files = sorted(SOURCE.glob("*.json"))
+    for src in files:
+        dst = TARGET / src.name
+        data = src.read_bytes()
+        if not dst.exists() or dst.read_bytes() != data:
+            changed = True
+            if not check:
+                dst.write_bytes(data)
+    if check and changed:
+        print("embedded catalogs are out of date; run `python scripts/sync_catalogs.py`", file=sys.stderr)
+        return 1
+    print("embedded catalogs are up to date" if check else f"synced {len(files)} catalog(s)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dorksmith-0.1.0/src/dorksmith/__init__.py

@@ -0,0 +1,56 @@
+"""dorksmith — deterministic search-dork generator and OSINT/SOCMINT query engine.
+
+    from dorksmith import generate, expand_handle, validate_query
+    result = generate("example.com", "domain", "public-documents", options={"fileTypes": ["pdf"]})
+    for v in result.variants:
+        print(v.label, v.query)
+
+The engine is pure: same request + same catalogs = same output. Pass ``catalogs=load_catalogs(path)``
+to run with edited catalogs; the bundled ones are used otherwise.
+"""
+from __future__ import annotations
+
+from urllib.parse import quote as _url_quote
+
+from .analyzer import GOOGLE_WORD_LIMIT, QueryAnalysis, analyze_query
+from .catalogs import Catalogs, bundled_catalog_files, bundled_catalogs, load_catalogs
+from .errors import InputValidationError
+from .generator import (
+    DEFAULT_LIMITS, INPUT_TYPES, GenerateResult, Limits, OperatorUse, ValidateQueryResult, Variant, build_context,
+    expand_template, generate, validate_query,
+)
+from .handles import HANDLE_NOTICE, NOT_CHECKED, HandleExpandResult, HandleQuery, ProfileCandidate, escape_data_string, expand_handle
+from .infer import infer_input_type
+from .normalizer import (
+    canonicalize, domain_label, normalize_text, try_normalize_domain, try_normalize_email, try_normalize_url,
+    try_normalize_username, try_parse_filename, try_parse_iso_date,
+)
+from .placeholders import ALL_PLACEHOLDERS, OPTIONAL_BY_DEFAULT, placeholders_in
+from .quoting import exclusion, looks_like_syntax, operator_value, or_group, quote, safe_term, safe_terms, unquote
+from .validator import validate_catalogs
+
+__version__ = "0.1.0"
+
+
+def catalog_version(catalogs: Catalogs | None = None) -> str:
+    """Version string of the catalogs in use (from intents.json)."""
+    return (catalogs or bundled_catalogs()).catalog_version
+
+
+def search_url(query: str, engine: str = "google", catalogs: Catalogs | None = None) -> str:
+    """Search-engine URL for a query, built locally with percent-encoding."""
+    c = catalogs or bundled_catalogs()
+    template = c.operators.get(engine, {}).get("searchUrlTemplate", "https://www.google.com/search?q={query}")
+    return template.replace("{query}", _url_quote(query, safe="-_.!~*'()"))
+
+
+__all__ = [
+    "__version__", "ALL_PLACEHOLDERS", "Catalogs", "DEFAULT_LIMITS", "GOOGLE_WORD_LIMIT", "GenerateResult", "HANDLE_NOTICE",
+    "HandleExpandResult", "HandleQuery", "INPUT_TYPES", "InputValidationError", "Limits", "NOT_CHECKED", "OPTIONAL_BY_DEFAULT",
+    "OperatorUse", "ProfileCandidate", "QueryAnalysis", "ValidateQueryResult", "Variant", "analyze_query", "build_context",
+    "bundled_catalog_files", "bundled_catalogs", "canonicalize", "catalog_version", "domain_label", "escape_data_string",
+    "exclusion", "expand_handle", "expand_template", "generate", "infer_input_type", "load_catalogs", "looks_like_syntax",
+    "normalize_text", "operator_value", "or_group", "placeholders_in", "quote", "safe_term", "safe_terms", "search_url",
+    "try_normalize_domain", "try_normalize_email", "try_normalize_url", "try_normalize_username", "try_parse_filename",
+    "try_parse_iso_date", "unquote", "validate_catalogs", "validate_query",
+]

dorksmith-0.1.0/src/dorksmith/analyzer.py

@@ -0,0 +1,151 @@
+"""Quote-aware operator scanner with plain-language warnings."""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .catalogs import Json
+from .normalizer import is_letter
+
+GOOGLE_WORD_LIMIT = 32
+
+
+@dataclass(frozen=True)
+class QueryAnalysis:
+    operators: list[str]
+    warnings: list[str]
+    has_errors: bool
+
+
+def _tokenize(query: str) -> list[tuple[str, bool]]:
+    tokens: list[tuple[str, bool]] = []
+    i, n = 0, len(query)
+    while i < n:
+        if query[i].isspace():
+            i += 1
+            continue
+        if query[i] == '"':
+            end = query.find('"', i + 1)
+            if end < 0:
+                end = n - 1
+            tokens.append((query[i + 1: max(i + 1, end)], True))
+            i = end + 1
+            continue
+        start = i
+        while i < n and not query[i].isspace():
+            if query[i] == '"':
+                end = query.find('"', i + 1)
+                i = n if end < 0 else end + 1
+                continue
+            i += 1
+        tokens.append((query[start:i], False))
+    return tokens
+
+
+def analyze_query(query: str, catalog: Json, by_token: dict[str, Json]) -> QueryAnalysis:
+    operators: list[str] = []
+    warnings: list[str] = []
+    has_errors = False
+
+    def use(token: str) -> None:
+        if token not in operators:
+            operators.append(token)
+
+    depth = 0
+    tokens = _tokenize(query)
+    quote_count = query.count('"')
+    if quote_count > 0:
+        use('"')
+    if quote_count % 2 == 1:
+        warnings.append("Unbalanced double quotes: the last phrase will not be treated as exact.")
+        has_errors = True
+
+    for text, quoted in tokens:
+        if quoted:
+            if "*" in text:
+                use("*")
+            continue
+        t = text
+        if not t:
+            continue
+        if t == "OR":
+            use("OR"); continue
+        if t == "AND":
+            use("AND"); continue
+        if t == "|":
+            use("|"); continue
+        if t in ("or", "and"):
+            warnings.append(f"Lower-case '{t}' is treated as an ordinary word; use upper-case {t.upper()} for a boolean operator.")
+            continue
+
+        body = t
+        while body and body[0] == "(":
+            depth += 1; use("("); body = body[1:]
+        closing = 0
+        while body and body[-1] == ")":
+            closing += 1; body = body[:-1]
+        depth -= closing
+
+        if body.startswith("AROUND("):
+            use("AROUND("); continue
+        if len(body) > 1 and body[0] == "-":
+            use("-"); body = body[1:]
+        elif len(body) > 1 and body[0] == "+":
+            use("+"); body = body[1:]
+        elif len(body) > 1 and body[0] == "~":
+            use("~"); body = body[1:]
+        if len(body) > 1 and body[0] == "#":
+            use("#"); continue
+        if len(body) > 1 and body[0] == "@":
+            use("@"); continue
+        if body == "*":
+            use("*"); continue
+        if ".." in body and any(ch.isdigit() for ch in body):
+            use(".."); continue
+        if len(body) > 1 and body[0] == "$" and all(ch.isdigit() or ch in ".," for ch in body[1:]):
+            use("$"); continue
+
+        colon = body.find(":")
+        if colon > 0 and all(is_letter(ch) for ch in body[:colon]):
+            prefix = body[: colon + 1].lower()
+            value = body[colon + 1:]
+            op = by_token.get(prefix)
+            if op:
+                use(prefix)
+                if prefix == "filetype:" and value.startswith("."):
+                    warnings.append("filetype: values take no leading dot (filetype:pdf).")
+                if prefix == "site:" and "://" in value:
+                    warnings.append("site: values take no scheme (site:example.com).")
+                if prefix in ("before:", "after:") and len(value) not in (4, 10):
+                    warnings.append(f"{prefix} expects YYYY-MM-DD or YYYY.")
+                if op.get("takesValue") and not value:
+                    warnings.append(f"{prefix} has no value.")
+                    has_errors = True
+            elif len(body[:colon]) <= 15 and "://" not in body:
+                warnings.append(f"'{prefix}' is not a known {catalog.get('engineName', '')} operator and will be searched as plain text.")
+
+    if depth != 0:
+        warnings.append("Unbalanced parentheses.")
+        has_errors = True
+
+    for token in operators:
+        op = by_token.get(token)
+        if not op:
+            continue
+        support = op.get("support")
+        caveats = op.get("caveats") or []
+        if support == "deprecated":
+            warnings.append(f"{op['token']} is deprecated: {caveats[0] if caveats else 'it no longer works.'}")
+        elif support == "unreliable":
+            warnings.append(f"{op['token']} is unreliable: {caveats[0] if caveats else 'results are inconsistent.'}")
+        elif support == "unknown":
+            warnings.append(f"{op['token']} has unknown support status.")
+
+    word_count = sum(1 for text, _ in tokens if text)
+    if word_count > GOOGLE_WORD_LIMIT:
+        warnings.append(f"Query has {word_count} terms; Google ignores everything after the first {GOOGLE_WORD_LIMIT}.")
+
+    return QueryAnalysis(operators, warnings, has_errors)
+
+
+_ = re  # keep re available for callers that extend the analyzer

dorksmith-0.1.0/src/dorksmith/catalogs.py

@@ -0,0 +1,73 @@
+"""Catalog loading. Catalogs are plain dicts mirroring the JSON files in the repository's data/ directory."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+Json = dict[str, Any]
+
+
+@dataclass(frozen=True)
+class Catalogs:
+    """The four catalogs the engine consumes. ``operators`` is keyed by engine id."""
+
+    operators: dict[str, Json]
+    intents: Json
+    platforms: Json
+    file_types: Json
+    _operator_index: dict[str, dict[str, Json]] = field(default_factory=dict, repr=False, compare=False)
+
+    @property
+    def catalog_version(self) -> str:
+        return str(self.intents.get("catalogVersion", ""))
+
+    def operator_index(self, engine: str) -> dict[str, Json]:
+        """token -> operator definition for an engine (cached)."""
+        if engine not in self._operator_index:
+            index: dict[str, Json] = {}
+            for op in self.operators[engine].get("operators", []):
+                index.setdefault(op["token"], op)
+            self._operator_index[engine] = index
+        return self._operator_index[engine]
+
+    def intent(self, intent_id: str) -> Json | None:
+        for i in self.intents.get("intents", []):
+            if i.get("id") == intent_id:
+                return i
+        return None
+
+
+def _assemble(files: dict[str, Json]) -> Catalogs:
+    operators = {v["engine"]: v for k, v in files.items() if k.startswith("operators.")}
+    return Catalogs(operators=operators, intents=files["intents.json"], platforms=files["platforms.json"], file_types=files["filetypes.json"])
+
+
+def load_catalogs(directory: str | Path) -> Catalogs:
+    """Load catalogs from a directory containing operators.<engine>.json, intents.json, platforms.json, filetypes.json."""
+    d = Path(directory)
+    files = {p.name: json.loads(p.read_text(encoding="utf-8")) for p in sorted(d.glob("*.json"))}
+    return _assemble(files)
+
+
+def bundled_catalog_files() -> dict[str, Json]:
+    """The raw catalog files embedded in the package, keyed by file name."""
+    root = resources.files("dorksmith") / "data"
+    out: dict[str, Json] = {}
+    for entry in sorted(root.iterdir(), key=lambda e: e.name):
+        if entry.name.endswith(".json"):
+            out[entry.name] = json.loads(entry.read_text(encoding="utf-8"))
+    return out
+
+
+_bundled: Catalogs | None = None
+
+
+def bundled_catalogs() -> Catalogs:
+    """The catalogs embedded in this package (loaded once)."""
+    global _bundled
+    if _bundled is None:
+        _bundled = _assemble(bundled_catalog_files())
+    return _bundled