lambda-watcher 0.1.0__tar.gz → 0.2.0__tar.gz

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lambda-watcher
-Version: 0.1.0
+Version: 0.2.0
 Summary: Watch your Downloads folder for AWS Lambda deployment zips, archive them as versions, analyse them, and diff any two versions.
 Author: Lambda Watcher contributors
 License: Apache-2.0
@@ -45,13 +45,14 @@ to how you work. You keep downloading zips; it does the rest.
 
 ```
 $ lambda-watcher watch
-lambda-watcher 0.1.0 — archiving into ~/.lambda-watcher
+lambda-watcher 0.2.0 — archiving into ~/.lambda-watcher
 watching ~/Downloads. Press Ctrl-C to stop.
                new  order-processor v0001  order-processor.zip — archived a new version
-               new  order-processor v0002  order-processor (1).zip — 2 added, 2 modified, 3 renamed, 52 vendored
+               new  order-processor v0002  order-processor (1).zip — 2 added, 2 modified, 9 renamed, 55 vendored
                     +24/-5 lines · new: 1 env var, 1 AWS service, 3 secrets
                     report: ~/.lambda-watcher/reports/order-processor/v0001-v0002.html
          unchanged  order-processor v0002  order-processor (2).zip — identical to version 2
+done
 ```
 
 That third line is the one that matters: the same code, downloaded again, is
@@ -89,6 +90,14 @@ lw open order-processor                    # the whole archive, in your editor
 lw git order-processor log -p              # or just use git
 ```
 
+`lw diff` hides vendored dependency files and the git mirror keeps them, so the
+two commands report different totals for the same pair of versions — the demo
+below is *2 added, 2 modified, 9 renamed* from `lw diff` and *68 files changed*
+from `lw git order-processor diff --stat v0001 v0002`. Neither is wrong, so each
+one says the other exists: `lw diff --vendor` shows the hidden files, and
+`lw diff --mirror` prints the mirror's own patch for whichever two versions you
+asked for.
+
 ## Why the diffs are actually readable
 
 A raw `diff -r` between two Lambda zips is unusable: thousands of vendored
@@ -100,6 +109,8 @@ answering the questions you actually have, in order:
 | **Your code, separated from theirs** | `node_modules/`, `site-packages/` and friends are classified as vendored and hidden by default. Three changed files, not 3,000. |
 | **Dependencies as versions, not files** | A `boto3` upgrade shows as `boto3 1.34.0 → 1.35.20`, parsed from the `dist-info` actually shipped in the zip — not 400 changed files. |
 | **Config impact, called out** | A new `os.environ["QUEUE_URL"]` is flagged as *"this must exist in the function's environment before you deploy"*. A new `boto3.client("sqs")` is flagged as *"the execution role may need new IAM permissions"*. These are the changes that break a deploy and never show up in a file diff. |
+| **A reindent is not a rewrite** | A file whose only change is indentation, trailing spaces, line endings or blank lines is labelled *whitespace only* instead of being reprinted line by line. One `black` run over the package would otherwise read as a total rewrite of every file it touched. `lw diff --whitespace` shows the hunk anyway. |
+| **Minified bundles are diffed by word** | An 8 KB bundle on one line has no lines to diff, so a changed digit costs you the whole file quoted twice. Instead you get the changed run and the text either side of it: `@ 19  …var t=1 → 2;a=1;a=1…`. Lock files are skipped for the same reason — the dependency row above already says what moved. |
 | **Renames survive edits** | A file that moved *and* changed is shown as one rename with a diff, not an unrelated add plus delete. |
 | **Secrets are diffed too** | An AWS key or Stripe token that appears between v7 and v8 gets its own section. Values are stored redacted; the secret itself never enters the index. |
 
@@ -110,9 +121,10 @@ files and 56 of them are `site-packages/`:
 $ lambda-watcher diff order-processor
 ╭──────────────────────────────────────────────────────────────────────╮
 │ order-processor   v0001 → v0002                                      │
-│ 2 added  2 modified  3 renamed  52 vendored (hidden)  +24 / -5 lines │
+│ 2 added  2 modified  9 renamed  55 vendored (hidden)  +24 / -5 lines │
+│ to see the 55 vendored files: lw diff order-processor --vendor       │
 ╰──────────────────────────────────────────────────────────────────────╯
-  size     8.1 KB → 8.9 KB (+782 B)
+  size     8.3 KB → 9.2 KB (+886 B)
 
 Dependencies                                      
    manager  package   from    to       origin     
@@ -129,21 +141,24 @@ high  aws-access-key-id  config.py:6  AKIA…LE (20 chars)
 high  stripe-key         config.py:7  sk_l…dc (32 chars)  
  low  debug-flag         config.py:8  DEBUG = True        
 
-Files                                                                       
-   path                                                         +  −  size  
-~  lambda_function.py                                           9  2  +322  
-~  requirements.txt                                             2  1   +17  
-+  config.py                                                   10     +235  
-+  helpers/__init__.py                                                      
-→  {db → helpers/db}.py                                         1      +33  
-→  site-packages/boto3-1.{34.0 → 35.20}.dist-info/METADATA      1  1    +1  
-→  site-packages/botocore-1.{34.0 → 35.20}.dist-info/METADATA   1  1    +1
+Files                                                                               
+   path                                                                 +  −  size  
+~  lambda_function.py                                                   9  2  +322  
+~  requirements.txt                                                     2  1   +17  
++  config.py                                                           10     +235  
++  helpers/__init__.py                                                              
+→  {db → helpers/db}.py                                                 1      +33  
+→  site-packages/boto3-1.{34.0 → 35.20}.dist-info/ · 4 files, 1         1  1    +1  
+   edited                                                                           
+→  site-packages/botocore-1.{34.0 → 35.20}.dist-info/ · 4 files, 1      1  1    +1  
+   edited
 ```
 
-The 52 vendored files became three version numbers, `db.py` moving into a
-package is one rename rather than a delete plus an add, and the new environment
-variable, the new AWS service and the three secret findings are changes that a
-file diff cannot express at all.
+The 55 vendored files became three version numbers, `db.py` moving into a
+package is one rename rather than a delete plus an add, each bumped package's
+`dist-info` is one line rather than four, and the new environment variable, the
+new AWS service and the three secret findings are changes that a file diff
+cannot express at all.
 
 That capture is not illustrative — it is the output of
 [`docs/examples/build_demo.py`](docs/examples/build_demo.py), which builds the
@@ -244,7 +259,7 @@ the manual recipes.
 | `ls` | Every function archived so far. |
 | `versions FN` | Every archived version of one function. |
 | `show FN [V]` | Runtime, handler, dependencies, env vars, services and findings for one version. `--files`, `--json`. |
-| `diff FN` | Compare two versions. Defaults to the last two. `--from`/`--to`, `--html`, `--open`, `--vendor`, `--no-patch`, `--json`. |
+| `diff FN` | Compare two versions. Defaults to the last two. `--from`/`--to`, `--html`, `--open`, `--vendor`, `--whitespace`, `--no-patch`, `--json`. |
 | `report FN` | Build a browsable HTML history: an index plus a diff for every step. |
 | `export FN [V]` | Get a version back out as a deployable zip (`--zip`) or a plain folder (`--tree`). |
 | `open FN [V]` | Open the function's mirror in your editor — every version in one folder, with history. Name a version to open just its files. |
@@ -276,11 +291,11 @@ back from the newest.
 └── functions/
     └── order-processor/
         └── versions/
-            ├── 0001-bd9f77c8/
+            ├── 0001-7fc98e0e/
             │   ├── code/           # the extracted tree
             │   ├── manifest.json   # the full analysis
             │   └── package.zip     # the original download
-            └── 0002-73d375ad/
+            └── 0002-7f887035/
 ```
 
 The directories are the source of truth. `index.db` is a cache you can delete

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/README.md

@@ -14,13 +14,14 @@ to how you work. You keep downloading zips; it does the rest.
 
 ```
 $ lambda-watcher watch
-lambda-watcher 0.1.0 — archiving into ~/.lambda-watcher
+lambda-watcher 0.2.0 — archiving into ~/.lambda-watcher
 watching ~/Downloads. Press Ctrl-C to stop.
                new  order-processor v0001  order-processor.zip — archived a new version
-               new  order-processor v0002  order-processor (1).zip — 2 added, 2 modified, 3 renamed, 52 vendored
+               new  order-processor v0002  order-processor (1).zip — 2 added, 2 modified, 9 renamed, 55 vendored
                     +24/-5 lines · new: 1 env var, 1 AWS service, 3 secrets
                     report: ~/.lambda-watcher/reports/order-processor/v0001-v0002.html
          unchanged  order-processor v0002  order-processor (2).zip — identical to version 2
+done
 ```
 
 That third line is the one that matters: the same code, downloaded again, is
@@ -58,6 +59,14 @@ lw open order-processor                    # the whole archive, in your editor
 lw git order-processor log -p              # or just use git
 ```
 
+`lw diff` hides vendored dependency files and the git mirror keeps them, so the
+two commands report different totals for the same pair of versions — the demo
+below is *2 added, 2 modified, 9 renamed* from `lw diff` and *68 files changed*
+from `lw git order-processor diff --stat v0001 v0002`. Neither is wrong, so each
+one says the other exists: `lw diff --vendor` shows the hidden files, and
+`lw diff --mirror` prints the mirror's own patch for whichever two versions you
+asked for.
+
 ## Why the diffs are actually readable
 
 A raw `diff -r` between two Lambda zips is unusable: thousands of vendored
@@ -69,6 +78,8 @@ answering the questions you actually have, in order:
 | **Your code, separated from theirs** | `node_modules/`, `site-packages/` and friends are classified as vendored and hidden by default. Three changed files, not 3,000. |
 | **Dependencies as versions, not files** | A `boto3` upgrade shows as `boto3 1.34.0 → 1.35.20`, parsed from the `dist-info` actually shipped in the zip — not 400 changed files. |
 | **Config impact, called out** | A new `os.environ["QUEUE_URL"]` is flagged as *"this must exist in the function's environment before you deploy"*. A new `boto3.client("sqs")` is flagged as *"the execution role may need new IAM permissions"*. These are the changes that break a deploy and never show up in a file diff. |
+| **A reindent is not a rewrite** | A file whose only change is indentation, trailing spaces, line endings or blank lines is labelled *whitespace only* instead of being reprinted line by line. One `black` run over the package would otherwise read as a total rewrite of every file it touched. `lw diff --whitespace` shows the hunk anyway. |
+| **Minified bundles are diffed by word** | An 8 KB bundle on one line has no lines to diff, so a changed digit costs you the whole file quoted twice. Instead you get the changed run and the text either side of it: `@ 19  …var t=1 → 2;a=1;a=1…`. Lock files are skipped for the same reason — the dependency row above already says what moved. |
 | **Renames survive edits** | A file that moved *and* changed is shown as one rename with a diff, not an unrelated add plus delete. |
 | **Secrets are diffed too** | An AWS key or Stripe token that appears between v7 and v8 gets its own section. Values are stored redacted; the secret itself never enters the index. |
 
@@ -79,9 +90,10 @@ files and 56 of them are `site-packages/`:
 $ lambda-watcher diff order-processor
 ╭──────────────────────────────────────────────────────────────────────╮
 │ order-processor   v0001 → v0002                                      │
-│ 2 added  2 modified  3 renamed  52 vendored (hidden)  +24 / -5 lines │
+│ 2 added  2 modified  9 renamed  55 vendored (hidden)  +24 / -5 lines │
+│ to see the 55 vendored files: lw diff order-processor --vendor       │
 ╰──────────────────────────────────────────────────────────────────────╯
-  size     8.1 KB → 8.9 KB (+782 B)
+  size     8.3 KB → 9.2 KB (+886 B)
 
 Dependencies                                      
    manager  package   from    to       origin     
@@ -98,21 +110,24 @@ high  aws-access-key-id  config.py:6  AKIA…LE (20 chars)
 high  stripe-key         config.py:7  sk_l…dc (32 chars)  
  low  debug-flag         config.py:8  DEBUG = True        
 
-Files                                                                       
-   path                                                         +  −  size  
-~  lambda_function.py                                           9  2  +322  
-~  requirements.txt                                             2  1   +17  
-+  config.py                                                   10     +235  
-+  helpers/__init__.py                                                      
-→  {db → helpers/db}.py                                         1      +33  
-→  site-packages/boto3-1.{34.0 → 35.20}.dist-info/METADATA      1  1    +1  
-→  site-packages/botocore-1.{34.0 → 35.20}.dist-info/METADATA   1  1    +1
+Files                                                                               
+   path                                                                 +  −  size  
+~  lambda_function.py                                                   9  2  +322  
+~  requirements.txt                                                     2  1   +17  
++  config.py                                                           10     +235  
++  helpers/__init__.py                                                              
+→  {db → helpers/db}.py                                                 1      +33  
+→  site-packages/boto3-1.{34.0 → 35.20}.dist-info/ · 4 files, 1         1  1    +1  
+   edited                                                                           
+→  site-packages/botocore-1.{34.0 → 35.20}.dist-info/ · 4 files, 1      1  1    +1  
+   edited
 ```
 
-The 52 vendored files became three version numbers, `db.py` moving into a
-package is one rename rather than a delete plus an add, and the new environment
-variable, the new AWS service and the three secret findings are changes that a
-file diff cannot express at all.
+The 55 vendored files became three version numbers, `db.py` moving into a
+package is one rename rather than a delete plus an add, each bumped package's
+`dist-info` is one line rather than four, and the new environment variable, the
+new AWS service and the three secret findings are changes that a file diff
+cannot express at all.
 
 That capture is not illustrative — it is the output of
 [`docs/examples/build_demo.py`](docs/examples/build_demo.py), which builds the
@@ -213,7 +228,7 @@ the manual recipes.
 | `ls` | Every function archived so far. |
 | `versions FN` | Every archived version of one function. |
 | `show FN [V]` | Runtime, handler, dependencies, env vars, services and findings for one version. `--files`, `--json`. |
-| `diff FN` | Compare two versions. Defaults to the last two. `--from`/`--to`, `--html`, `--open`, `--vendor`, `--no-patch`, `--json`. |
+| `diff FN` | Compare two versions. Defaults to the last two. `--from`/`--to`, `--html`, `--open`, `--vendor`, `--whitespace`, `--no-patch`, `--json`. |
 | `report FN` | Build a browsable HTML history: an index plus a diff for every step. |
 | `export FN [V]` | Get a version back out as a deployable zip (`--zip`) or a plain folder (`--tree`). |
 | `open FN [V]` | Open the function's mirror in your editor — every version in one folder, with history. Name a version to open just its files. |
@@ -245,11 +260,11 @@ back from the newest.
 └── functions/
     └── order-processor/
         └── versions/
-            ├── 0001-bd9f77c8/
+            ├── 0001-7fc98e0e/
             │   ├── code/           # the extracted tree
             │   ├── manifest.json   # the full analysis
             │   └── package.zip     # the original download
-            └── 0002-73d375ad/
+            └── 0002-7f887035/
 ```
 
 The directories are the source of truth. `index.db` is a cache you can delete

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "lambda-watcher"
-version = "0.1.0"
+version = "0.2.0"
 description = "Watch your Downloads folder for AWS Lambda deployment zips, archive them as versions, analyse them, and diff any two versions."
 readme = "README.md"
 requires-python = ">=3.10"

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/__init__.py

@@ -1,4 +1,4 @@
 """Watch a downloads folder for AWS Lambda deployment packages and version them."""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = ["__version__"]

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/analysis/__init__.py

@@ -46,26 +46,57 @@ class Analysis:
 
     @property
     def primary_handler(self) -> str | None:
+        """The handler AWS would most likely invoke, or None if none was found.
+
+        :func:`~.handler.detect_handlers` returns its candidates best-first, so this
+        is simply the top one — something like ``lambda_function.lambda_handler``.
+        """
         return self.handlers[0].handler if self.handlers else None
 
     @property
     def vendor_file_count(self) -> int:
+        """How many files came from ``node_modules``, ``site-packages`` and friends.
+
+        Usually most of the package. Reported separately so a diff can say "1 file
+        you wrote changed, 4,812 vendored files came along with it" instead of
+        burying the first number in the second.
+        """
         return sum(1 for f in self.inventory.files if f.is_vendor)
 
     @property
     def vendor_size(self) -> int:
+        """Total bytes of vendored files, the companion to :attr:`vendor_file_count`."""
         return sum(f.size for f in self.inventory.files if f.is_vendor)
 
     def unique_env_vars(self, include_reserved: bool = False) -> list[str]:
+        """The distinct environment variable names the code reads, sorted.
+
+        Collapses the per-reference list, which can name the same variable from a
+        dozen lines. Runtime-provided names (``AWS_REGION``, ``PATH``) are left out
+        unless ``include_reserved`` is set, because they are the same in every
+        package and only ever add noise to a diff.
+        """
         names = {
             ref.name for ref in self.env_vars if include_reserved or not ref.is_reserved
         }
         return sorted(names)
 
     def unique_services(self) -> list[str]:
+        """The distinct AWS service ids the code talks to, sorted.
+
+        ``["dynamodb", "s3", "sqs"]`` — one entry per service no matter how many
+        call sites mention it.
+        """
         return sorted({ref.service for ref in self.services})
 
     def totals(self) -> dict[str, int]:
+        """The headline counts for this package, as a flat dict.
+
+        The numbers a summary line is built from: how many files, how many bytes,
+        and how much of each is first-party code rather than vendored dependency.
+        Kept as one dict because it goes straight into the manifest and into the
+        index as a row.
+        """
         return {
             "file_count": self.inventory.file_count,
             "total_size": self.inventory.total_size,
@@ -77,6 +108,17 @@ class Analysis:
         }
 
     def to_manifest(self, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Render this analysis as the ``manifest.json`` written beside the version.
+
+        The manifest is the source of truth on disk: the SQLite index is rebuilt
+        from these files by :mod:`~lambda_watcher.reindex`, so anything the index
+        needs has to be here. ``extra`` carries the fields only the ingest knows —
+        the function name, the sequence number, the originating zip — which are
+        merged in over the top.
+
+        Bumping the shape of what this returns means bumping ``MANIFEST_SCHEMA``,
+        and old manifests still have to reindex.
+        """
         manifest: dict[str, Any] = {
             "schema": MANIFEST_SCHEMA,
             "tree_hash": self.inventory.tree_hash,

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/analysis/deps.py

@@ -32,6 +32,14 @@ except ModuleNotFoundError:  # pragma: no cover
 
 @dataclass(frozen=True)
 class Dependency:
+    """One dependency, either declared in a manifest or installed in the zip.
+
+    ``is_declared`` is the important flag. A declared entry came from
+    ``requirements.txt`` and may be a range (``boto3>=1.34``); an installed
+    entry came from ``site-packages`` and is an exact version that really
+    shipped (``boto3 1.34.0``). Frozen so it can go in a set.
+    """
+
     manager: str      # pip | npm | go | maven | gem
     name: str
     version: str | None
@@ -39,9 +47,16 @@ class Dependency:
     is_declared: bool  # False => vendored/installed
 
     def key(self) -> tuple[str, str]:
+        """Identity across versions: ``(manager, lowercased name)``.
+
+        Deliberately excludes the version, because this is what a diff groups on to
+        notice that ``boto3`` went from 1.34.0 to 1.35.20 rather than reporting one
+        package removed and a different one added.
+        """
         return (self.manager, self.name.lower())
 
     def as_dict(self) -> dict:
+        """This dependency as plain JSON-ready data, for the manifest."""
         return {
             "manager": self.manager,
             "name": self.name,
@@ -58,6 +73,16 @@ _REQ_LINE = re.compile(
 
 
 def _parse_requirements(text: str, source: str) -> list[Dependency]:
+    """Parse a ``requirements.txt`` into declared pip dependencies.
+
+    Handles the ordinary ``boto3==1.34.0`` form plus extras (``requests[security]``),
+    direct URLs and ``git+`` references (the trailing path segment becomes the
+    name), and PEP 508 ``name @ url`` entries. Comments and the flag lines that
+    start with ``-`` (``-r base.txt``, ``-e .``, ``--index-url``) are skipped.
+
+    A bare ``boto3`` with no comparison operator records a None version — the
+    file asked for the package but not for any particular release.
+    """
     deps: list[Dependency] = []
     for raw in text.splitlines():
         line = raw.split("#", 1)[0].strip()
@@ -80,6 +105,16 @@ def _parse_requirements(text: str, source: str) -> list[Dependency]:
 
 
 def _parse_pyproject(text: str, source: str) -> list[Dependency]:
+    """Parse a ``pyproject.toml`` into declared pip dependencies.
+
+    Reads both the standard ``[project] dependencies`` list and Poetry's
+    ``[tool.poetry.dependencies]`` table, whose values may be a bare version
+    string or a table with a ``version`` key. Poetry's ``python`` entry is
+    dropped: it constrains the interpreter, not the package set.
+
+    Returns nothing if TOML cannot be parsed — on Python 3.10 ``tomli`` may be
+    absent, and a malformed file is not worth failing an ingest over.
+    """
     if tomllib is None:
         return []
     try:
@@ -108,6 +143,15 @@ def _parse_pyproject(text: str, source: str) -> list[Dependency]:
 
 
 def _parse_package_json(text: str, source: str, declared: bool = True) -> list[Dependency]:
+    """Parse a ``package.json``, either as a manifest or as an installed package.
+
+    The same filename means two different things depending on where it sits.
+    At the package root it is a manifest, and ``declared=True`` reads the
+    ``dependencies``/``devDependencies``/``optionalDependencies`` tables, whose
+    values are ranges like ``^4.17.21``. Inside ``node_modules/<pkg>/`` it
+    describes one installed package, and ``declared=False`` takes the file's own
+    ``name`` and ``version`` — the exact release that shipped.
+    """
     try:
         data = json.loads(text)
     except json.JSONDecodeError:
@@ -129,6 +173,13 @@ def _parse_package_json(text: str, source: str, declared: bool = True) -> list[D
 
 
 def _parse_package_lock(text: str, source: str) -> list[Dependency]:
+    """Parse a ``package-lock.json`` into installed npm dependencies.
+
+    Supports both lockfile layouts: v2/v3 keep a flat ``packages`` map keyed by
+    path, where the name has to be recovered from the key when the entry omits
+    it, while v1 keeps a ``dependencies`` map keyed by name. Both give resolved
+    versions, so entries are recorded as installed rather than declared.
+    """
     try:
         data = json.loads(text)
     except json.JSONDecodeError:
@@ -154,6 +205,12 @@ _YARN_ENTRY = re.compile(r'^"?([^@\s"][^@\s"]*)@[^\n:]*:\s*$\n(?:.*\n)*?\s+versi
 
 
 def _parse_yarn_lock(text: str, source: str) -> list[Dependency]:
+    """Parse a ``yarn.lock`` into installed npm dependencies.
+
+    Yarn's format is not JSON, so this matches each ``name@range:`` header
+    against the indented ``version "1.2.3"`` line that follows it and takes the
+    resolved version.
+    """
     deps: list[Dependency] = []
     for match in _YARN_ENTRY.finditer(text):
         deps.append(Dependency("npm", match.group(1), match.group(2), source, False))
@@ -165,6 +222,11 @@ _GO_REQUIRE_LINE = re.compile(r"^\s*([^\s/]+\S*)\s+(v\S+)", re.MULTILINE)
 
 
 def _parse_go_mod(text: str, source: str) -> list[Dependency]:
+    """Parse a ``go.mod`` into declared Go dependencies.
+
+    Covers both spellings: the grouped ``require ( ... )`` block and the
+    single-line ``require example.com/mod v1.2.3`` form.
+    """
     deps: list[Dependency] = []
     for block in _GO_REQUIRE_BLOCK.findall(text):
         for name, version in _GO_REQUIRE_LINE.findall(block):
@@ -179,6 +241,16 @@ def _parse_go_mod(text: str, source: str) -> list[Dependency]:
 
 
 def _parse_pom(text: str, source: str) -> list[Dependency]:
+    """Parse a Maven ``pom.xml`` into declared Java dependencies.
+
+    Each ``<dependency>`` becomes one entry named ``groupId:artifactId``, the
+    coordinate Maven itself uses. A ``<version>`` that is a property reference
+    (``${aws.sdk.version}``) is recorded verbatim, since resolving it would mean
+    evaluating the build.
+
+    Regex rather than an XML parser because this only needs the common shape and
+    must not fail an ingest over an unusual document.
+    """
     deps: list[Dependency] = []
     for block in re.findall(r"<dependency>(.*?)</dependency>", text, re.DOTALL):
         group = re.search(r"<groupId>(.*?)</groupId>", block, re.DOTALL)
@@ -196,6 +268,11 @@ _GEMFILE_LOCK = re.compile(r"^\s{4}([a-zA-Z0-9_-]+)\s+\(([^)]+)\)", re.MULTILINE
 
 
 def _parse_gemfile_lock(text: str, source: str) -> list[Dependency]:
+    """Parse a ``Gemfile.lock`` into installed Ruby gems.
+
+    The four-space-indented ``name (1.2.3)`` lines under ``specs:`` are the
+    resolved versions, which is why these are recorded as installed.
+    """
     return [
         Dependency("gem", name, version, source, False)
         for name, version in _GEMFILE_LOCK.findall(text)

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/analysis/envvars.py

@@ -39,18 +39,43 @@ _SCANNABLE = {"python", "javascript", "typescript", "java", "ruby", "csharp", "g
 
 @dataclass
 class EnvVarRef:
+    """One place in the code where an environment variable is read.
+
+    The same variable read from three files is three refs; collapse them with
+    :meth:`~lambda_watcher.analysis.Analysis.unique_env_vars` when you want the
+    set of names rather than the call sites.
+    """
+
     name: str
     path: str
     line: int
     is_reserved: bool = False
 
     def as_dict(self) -> dict:
+        """This reference as plain JSON-ready data, for the manifest."""
         return {"name": self.name, "path": self.path, "line": self.line, "is_reserved": self.is_reserved}
 
 
 def detect_env_vars(
     root: Path, inventory: Inventory, include_vendor: bool = False, max_files: int = 2000
 ) -> list[EnvVarRef]:
+    """Find every environment variable the code reads, across languages.
+
+    Scans each text file line by line for the idioms that read configuration —
+    ``os.environ["X"]`` and ``os.getenv("X")`` in Python, ``process.env.X`` in
+    JavaScript, ``System.getenv("X")`` in Java, and the Ruby and C# equivalents
+    — and records the name, file and line of each hit.
+
+    Vendored dependencies are skipped by default: they read hundreds of
+    variables that have nothing to do with this function. ``max_files`` caps how
+    many files are opened so a package with an enormous tree cannot make an
+    ingest crawl. Results are deduplicated by ``(name, path, line)`` and sorted,
+    so re-analysing an unchanged tree produces an identical list.
+
+    This is textual pattern matching, not parsing: a name built at runtime
+    (``os.environ[prefix + "_URL"]``) is invisible to it, and one inside a
+    comment still counts.
+    """
     refs: list[EnvVarRef] = []
     seen: set[tuple[str, str, int]] = set()
     entries = inventory.files if include_vendor else inventory.code_files

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/analysis/handler.py

@@ -31,16 +31,30 @@ _PREFERRED = (
 
 @dataclass
 class HandlerCandidate:
+    """One possible Lambda entry point, with a score saying how likely it is.
+
+    ``handler`` is the string you would actually paste into the AWS console —
+    ``lambda_function.lambda_handler`` — assembled from the file's module path
+    and the function's name.
+    """
+
     path: str
     symbol: str
     handler: str  # "module.function", the value you paste into the console
     score: int
 
     def as_dict(self) -> dict:
+        """This candidate as plain JSON-ready data, for the manifest."""
         return {"path": self.path, "symbol": self.symbol, "handler": self.handler, "score": self.score}
 
 
 def _module_name(path: str) -> str:
+    """Turn a file path into the dotted module path AWS expects.
+
+    ``src/app/handler.py`` -> ``src.app.handler``. The extension is dropped and
+    every directory separator becomes a dot, which is the form the handler
+    setting takes.
+    """
     pure = PurePosixPath(path)
     stem = pure.stem
     parts = list(pure.parts[:-1]) + [stem]

{lambda_watcher-0.1.0 → lambda_watcher-0.2.0}/src/lambda_watcher/analysis/inventory.py

@@ -10,6 +10,14 @@ from ..utils import count_lines, is_probably_text, language_for, matches_any, sh
 
 @dataclass
 class FileEntry:
+    """One file inside an extracted package, hashed and classified.
+
+    ``path`` is always posix-style and relative to the package root, so the same
+    tree hashes identically on Windows and Linux. ``is_vendor`` is the flag most
+    of the tool keys off: it separates the handful of files somebody wrote from
+    the thousands that came out of ``pip install``.
+    """
+
     path: str          # posix relative path
     size: int
     sha256: str
@@ -20,6 +28,7 @@ class FileEntry:
     lines: int
 
     def as_dict(self) -> dict:
+        """This entry as plain JSON-ready data, for the manifest."""
         return {
             "path": self.path,
             "size": self.size,
@@ -34,6 +43,14 @@ class FileEntry:
 
 @dataclass
 class Inventory:
+    """Every file in one extracted package, plus the totals worth caching.
+
+    ``tree_hash`` is the identity of the whole tree and what decides whether an
+    ingest has found a new version. The size and line counts are accumulated
+    during the walk rather than recomputed, since they are wanted on every
+    summary screen.
+    """
+
     files: list[FileEntry] = field(default_factory=list)
     tree_hash: str = ""
     total_size: int = 0
@@ -42,6 +59,7 @@ class Inventory:
 
     @property
     def file_count(self) -> int:
+        """How many files the package contains, vendored ones included."""
         return len(self.files)
 
     @property
@@ -51,12 +69,24 @@ class Inventory:
 
     @property
     def code_file_count(self) -> int:
+        """How many first-party files there are — the length of :attr:`code_files`."""
         return len(self.code_files)
 
     def by_path(self) -> dict[str, FileEntry]:
+        """The files as a ``{path: entry}`` lookup.
+
+        Diffing two versions means asking "was this path in the other one too?"
+        thousands of times, which wants a dict rather than a scan of the list.
+        """
         return {f.path: f for f in self.files}
 
     def language_breakdown(self) -> dict[str, int]:
+        """Count first-party files per language, most common first.
+
+        ``{"python": 12, "json": 3, "markdown": 1}``. Vendored files are excluded
+        deliberately — counting them would report the language of the dependencies
+        rather than of the function.
+        """
         counts: dict[str, int] = {}
         for f in self.code_files:
             counts[f.lang] = counts.get(f.lang, 0) + 1