patch-manager 0.0.11__tar.gz → 0.1.0__tar.gz

{patch_manager-0.0.11 → patch_manager-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patch-manager
-Version: 0.0.11
+Version: 0.1.0
 Summary: Create, check and email patch series, with Patchwork integration
 Author-email: Simon Glass <sjg@chromium.org>
 License-Expression: GPL-2.0-or-later

{patch_manager-0.0.11 → patch_manager-0.1.0}/patch_manager.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: patch-manager
-Version: 0.0.11
+Version: 0.1.0
 Summary: Create, check and email patch series, with Patchwork integration
 Author-email: Simon Glass <sjg@chromium.org>
 License-Expression: GPL-2.0-or-later

{patch_manager-0.0.11 → patch_manager-0.1.0}/patch_manager.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ patman/checkpatch.py
 patman/cmdline.py
 patman/commit.py
 patman/control.py
+patman/coverity.py
 patman/cser_helper.py
 patman/cseries.py
 patman/database.py

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/__main__.py

@@ -40,6 +40,7 @@ def run_patman():
         from patman import func_test
         from patman import test_checkpatch
         from patman import test_cseries
+        from patman import test_settings
         from u_boot_pylib import test_command
 
         to_run = args.testname if args.testname not in [None, 'test'] else None
@@ -48,7 +49,7 @@ def run_patman():
             args.test_preserve_dirs, None, to_run, None,
             [test_checkpatch.TestPatch, func_test.TestFunctional,
              'patman.settings', test_cseries.TestCseries,
-             test_command.TestRunInteractive])
+             test_settings.TestSettings, test_command.TestRunInteractive])
         sys.exit(0 if result.wasSuccessful() else 1)
 
     # Process commits, produce patches files, check them, email them

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/cmdline.py

@@ -342,6 +342,16 @@ def add_series_subparser(subparsers):
     ren = series_subparsers.add_parser('rename')
     ren.add_argument('-N', '--new-name', help='New name for the series')
 
+    rev = series_subparsers.add_parser(
+        'review', help='AI-review the series and store the result')
+    rev.add_argument('-f', '--force', action='store_true',
+                     help='Re-review even if reviews are already stored')
+    rev.add_argument('--spelling', type=str, default='British',
+                     help='Spelling convention for review comments')
+    rev.add_argument('-c', '--context', type=str, default=None,
+                     help="Extra context for the review agent, or '@path' "
+                          'to read it from a file')
+
     series_subparsers.add_parser('rm')
 
     snotes = series_subparsers.add_parser('save-notes')
@@ -587,6 +597,10 @@ def add_review_subparser(subparsers):
     review.add_argument(
         '-d', '--create-drafts', action='store_true',
         help='Create Gmail draft emails for each review')
+    review.add_argument(
+        '--redraft', action='store_true',
+        help='Recreate Gmail drafts from the stored reviews even when a '
+             'draft already exists, to recover after an error')
     review.add_argument(
         '--gmail-account', type=str, default=None,
         help='Gmail account to create drafts in (e.g. user@gmail.com)')
@@ -607,6 +621,14 @@ def add_review_subparser(subparsers):
     review.add_argument(
         '--apply-only', action='store_true',
         help='Only download and apply patches, skip AI review')
+    review.add_argument(
+        '--coverity', action='store_true',
+        help='Run Coverity on the base and the series, and feed the new '
+             'defects into the review (needs the cov-* tools on PATH)')
+    review.add_argument(
+        '--coverity-defconfig', type=str, default=None,
+        help='Board defconfig to build for --coverity '
+             '(default: sandbox_defconfig)')
     review.add_argument(
         '--signoff', type=str, default='',
         help="Sign-off for reviews with comments (from .patman settings)")
@@ -627,9 +649,26 @@ def add_review_subparser(subparsers):
         '--sync', action='store_true',
         help='Check if review drafts have been sent and record the '
              'final email content')
+    review.add_argument(
+        '--scan', action='store_true',
+        help='Scan patchwork for new versions of already-reviewed series '
+             'and review the latest version once it has fully appeared')
+    review.add_argument(
+        '--relink', action='store_true',
+        help='Repair the database by merging review series that were split '
+             'across versions, so follow-up reviews see earlier feedback')
+    review.add_argument(
+        '-j', '--jobs', type=int, default=4,
+        help='Number of series to review in parallel with --scan '
+             '(default: 4)')
     review.add_argument(
         '-f', '--force', action='store_true',
         help='Force re-review even if the series was already reviewed')
+    review.add_argument(
+        '--any-state', action='store_true',
+        help='Review the series even if no patch is in an active state '
+             '(new, RFC, under-review, changes-requested or '
+             'needs-review-ack)')
     review.add_argument(
         '-c', '--context', type=str, default=None,
         help="Extra context for the review agent — e.g. 'this is RFC, "

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/control.py

@@ -245,6 +245,9 @@ def do_series(args, test_db=None, pwork=None, cser=None):
             cser.show_notes(args.series)
         elif args.subcmd == 'rename':
             cser.rename(args.series, args.new_name, dry_run=args.dry_run)
+        elif args.subcmd == 'review':
+            cser.review(args.series, args.version, force=args.force,
+                        spelling=args.spelling, context=args.context)
         elif args.subcmd == 'set-upstream':
             cser.set_upstream(args.series, args.upstream_name,
                               dry_run=args.dry_run)
@@ -433,7 +436,8 @@ def do_review(args, test_db=None, pwork=None, cser=None):
         cser.open_database()
 
         # Resolve patchwork URL
-        if not pwork and not args.learn_voice and not args.sync:
+        if not pwork and not args.learn_voice and not args.sync \
+                and not args.relink:
             ups = args.upstream
             if not ups:
                 ups = cser.db.upstream_get_default()

patch_manager-0.1.0/patman/coverity.py

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: GPL-2.0+
+#
+# Copyright 2026 Simon Glass <sjg@chromium.org>
+#
+"""Run Coverity static analysis on a series and find new defects
+
+Coverity works on a whole build rather than a diff, so to find the
+defects a series introduces we analyse the base tree and the patched
+tree separately and compare. Each Coverity defect carries a stable
+'mergeKey' that identifies the same defect across builds, so the new
+defects are those whose mergeKey is not present in the base.
+
+The cov-build, cov-analyze and cov-format-errors tools must be on the
+PATH; they are part of a (commercial) Coverity installation.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+
+from u_boot_pylib import tout
+
+# Default board config to build for analysis (host build, no toolchain)
+DEFAULT_DEFCONFIG = 'sandbox_defconfig'
+
+
+def check_available():
+    """Check whether the Coverity command-line tools are installed
+
+    Returns:
+        bool: True if cov-build, cov-analyze and cov-format-errors are all
+            on the PATH
+    """
+    return all(shutil.which(tool) for tool in
+               ('cov-build', 'cov-analyze', 'cov-format-errors'))
+
+
+def _run(cmd, cwd):
+    """Run a command, raising on failure
+
+    Args:
+        cmd (list of str): Command and arguments
+        cwd (str): Directory to run in
+
+    Raises:
+        subprocess.CalledProcessError: if the command fails
+    """
+    subprocess.run(cmd, cwd=cwd, check=True, stdout=subprocess.PIPE,
+                   stderr=subprocess.STDOUT, text=True)
+
+
+def analyze(repo_path, defconfig, emit_dir):
+    """Build and analyse a tree, returning its Coverity defects
+
+    Configures the given defconfig, builds it under cov-build, runs
+    cov-analyze and reads the defects back as JSON.
+
+    Args:
+        repo_path (str): Worktree to configure and build in
+        defconfig (str): Board defconfig to build, e.g. 'sandbox_defconfig'
+        emit_dir (str): Coverity intermediate directory to write
+
+    Returns:
+        list of dict: Defect records, each with at least 'mergeKey'
+
+    Raises:
+        subprocess.CalledProcessError: if a build or analysis step fails
+    """
+    jobs = str(os.cpu_count() or 1)
+    _run(['make', defconfig], repo_path)
+    _run(['cov-build', '--dir', emit_dir, 'make', '-j', jobs], repo_path)
+    _run(['cov-analyze', '--dir', emit_dir], repo_path)
+    out_json = os.path.join(emit_dir, 'defects.json')
+    _run(['cov-format-errors', '--dir', emit_dir, '--json-output-v7',
+          out_json], repo_path)
+    with open(out_json, encoding='utf-8') as fd:
+        data = json.load(fd)
+    return data.get('issues', [])
+
+
+def find_new_defects(base, patched):
+    """Find defects present in the patched tree but not the base
+
+    Args:
+        base (list of dict): Defects from the base tree
+        patched (list of dict): Defects from the patched tree
+
+    Returns:
+        list of dict: Defects whose mergeKey is not in the base
+    """
+    base_keys = {defect.get('mergeKey') for defect in base}
+    return [defect for defect in patched
+            if defect.get('mergeKey') not in base_keys]
+
+
+def format_defect(defect):
+    """Format a single defect as a one-line summary
+
+    Args:
+        defect (dict): Coverity defect record
+
+    Returns:
+        str: Summary like 'RESOURCE_LEAK: drivers/foo.c:42 (probe): ...'
+    """
+    checker = defect.get('checkerName', '?')
+    path = defect.get('mainEventFilePathname', '?')
+    line = defect.get('mainEventLineNumber', '?')
+    func = defect.get('functionDisplayName', '')
+    desc = (defect.get('subcategoryLongDescription') or
+            defect.get('subcategoryShortDescription') or '')
+    loc = f'{path}:{line}'
+    if func:
+        loc += f' ({func})'
+    return f'{checker}: {loc}: {desc}'.rstrip(': ')
+
+
+def format_defects(defects):
+    """Format a list of defects as a bullet list, most useful first
+
+    Args:
+        defects (list of dict): Defects to format
+
+    Returns:
+        str: One '- <summary>' line per defect, or '' if there are none
+    """
+    return '\n'.join(f'- {format_defect(defect)}' for defect in defects)

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/cseries.py

@@ -1507,6 +1507,49 @@ class Cseries(cser_helper.CseriesHelper):
                 self.rollback()
                 tout.info('Dry run completed')
 
+    def review(self, series, version, force=False, spelling='British',
+               context=None):
+        """AI-review the series and store the result in the database
+
+        Reviews the commits on the series branch with the review agent and
+        stores the findings, keyed by version, so they can be viewed later
+        with 'patman series info -r'. The series must already have been
+        added with 'patman series add'.
+
+        Args:
+            series (str): Name of series, or None to use the current branch
+            version (int): Version number, or None to detect from the branch
+            force (bool): Re-review even if reviews are already stored
+            spelling (str): Spelling convention for review comments
+            context (str or None): Extra context for the review agent, or
+                '@path' to read it from a file
+        """
+        from patman import review
+
+        ser, version = self._parse_series_and_version(series, version)
+        self._ensure_in_db(ser)
+        self._ensure_version(ser, version)
+        svid = self.get_ser_ver(ser.idnum, version).idnum
+
+        existing = self.db.review_get_for_version(svid)
+        if existing and not force:
+            raise ValueError(
+                f"Series '{ser.name}' v{version} already has "
+                f"{len(existing)} stored review(s); view with 'patman "
+                "series info -r' or use -f to re-review")
+        if existing:
+            self.db.review_delete_for_version(svid)
+
+        name = self._get_branch_name(ser.name, version)
+        if not gitutil.check_branch(name, git_dir=self.gitdir):
+            raise ValueError(f"No branch named '{name}'")
+        count = gitutil.count_commits_to_branch(name, self.gitdir)
+        series_obj = patchstream.get_metadata(name, 0, count,
+                                              git_dir=self.gitdir)
+
+        review.review_series(self, ser.idnum, svid, version, name,
+                             series_obj, spelling=spelling, context=context)
+
     def gather_all(self, pwork, show_comments, show_cover_comments,
                    sync_all_versions, gather_tags, dry_run=False):
         to_fetch, missing = self._get_fetch_dict(sync_all_versions)

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/database.py

@@ -830,6 +830,29 @@ class Database:  # pylint:disable=R0904
             return SerVer(*recs[0])
         return [SerVer(*x) for x in recs]
 
+    def ser_ver_get_svids(self, series_idnum):
+        """Get all ser_ver IDs for a series
+
+        Args:
+            series_idnum (int): Series ID
+
+        Return:
+            list of int: svids of every version of the series
+        """
+        res = self.execute('SELECT id FROM ser_ver WHERE series_id = ?',
+                           (series_idnum,))
+        return [row[0] for row in res.fetchall()]
+
+    def ser_ver_set_series(self, svid, series_idnum):
+        """Move a ser_ver record to a different series
+
+        Args:
+            svid (int): ser_ver ID to move
+            series_idnum (int): Series ID to attach it to
+        """
+        self.execute('UPDATE ser_ver SET series_id = ? WHERE id = ?',
+                     (series_idnum, svid))
+
     def ser_ver_get_ids_for_series(self, series_idnum, version=None):
         """Get a list of ser_ver records for a given series ID
 
@@ -1431,25 +1454,28 @@ class Database:  # pylint:disable=R0904
         return [Review(*row) for row in res.fetchall()]
 
     def review_get_previous(self, series_id, version):
-        """Get reviews from the previous version of a series
+        """Get reviews from the most recent earlier version of a series
 
-        Looks up the ser_ver for version-1 and returns its reviews, so
-        they can be provided as context when reviewing a new version.
+        Returns the reviews of the highest version below the current one
+        that actually has reviews, so they can be provided as context when
+        reviewing a new version. Skipping over versions with no reviews
+        means a gap (e.g. an intermediate version that was never reviewed)
+        still yields the earlier feedback rather than nothing.
 
         Args:
             series_id (int): Series ID
             version (int): Current version being reviewed
 
         Return:
-            list of Review: Reviews from version-1, or empty list
+            list of Review: Reviews from the latest earlier reviewed
+                version, or empty list
         """
-        prev_version = version - 1
-        if prev_version < 1:
-            return []
         res = self.execute(
             'SELECT sv.id FROM ser_ver sv '
-            'WHERE sv.series_id = ? AND sv.version = ?',
-            (series_id, prev_version))
+            'JOIN review r ON r.svid = sv.id '
+            'WHERE sv.series_id = ? AND sv.version < ? '
+            'ORDER BY sv.version DESC LIMIT 1',
+            (series_id, version))
         row = res.fetchone()
         if not row:
             return []

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/gmail.py

@@ -324,6 +324,24 @@ def create_draft(service, to, subject, body,
     return draft
 
 
+def delete_draft(service, draft_id):
+    """Delete a Gmail draft
+
+    A draft that no longer exists (already sent or deleted by hand) is
+    ignored rather than raising.
+
+    Args:
+        service (googleapiclient.discovery.Resource): Gmail API service
+        draft_id (str): ID of the draft to delete
+    """
+    from googleapiclient.errors import HttpError
+    try:
+        service.users().drafts().delete(userId='me', id=draft_id).execute()
+    except HttpError as exc:
+        if exc.resp.status != 404:
+            raise
+
+
 def _build_cc(headers, list_email):
     """Build a CC list from the original patch headers
 

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/patchwork.py

@@ -452,6 +452,19 @@ class Patchwork:
         """
         return await self._request(client, f'series/{link}/')
 
+    async def get_series_patch_states(self, client, link):
+        """Get the patchwork state of each patch in a series
+
+        Args:
+            client (aiohttp.ClientSession): Session to use
+            link (str): Patchwork series ID
+
+        Returns:
+            list of str: State slug for each patch, e.g. ['new', 'rfc']
+        """
+        res = await self._request(client, f'patches/?series={link}')
+        return [patch.get('state') for patch in res]
+
     async def get_series_mbox(self, client, link):
         """Download the raw mbox file for a series.
 

{patch_manager-0.0.11 → patch_manager-0.1.0}/patman/patman.rst

@@ -121,6 +121,31 @@ possible to override the `project` settings variable or anything else
 in a project-specific way. The values of this "local" configuration
 file take precedence over those of the "global" one.
 
+Config is read from three files, each overriding the previous one on a
+per-key basis (lowest to highest priority):
+
+1. ``.patman-defaults`` at the root of the git repository. This is
+   tracked in git and shipped by the project to provide sensible
+   defaults (such as the patchwork URL or the get_maintainer.pl
+   invocation). Because it is the lowest layer, anyone can override it,
+   so it never takes control away from the user. In a tree whose
+   ``.gitignore`` ignores dot-files (as U-Boot's does), force-add it
+   with ``git add -f .patman-defaults``.
+2. ``~/.patman``, the user's global config.
+3. ``.patman`` at the root of the git repository, the user's per-repo
+   override (not tracked).
+
+Command-line arguments override all three. A project shipping
+``.patman-defaults`` might contain::
+
+    [settings]
+    patchwork_url: https://patchwork.ozlabs.org
+    get_maintainer_script: scripts/get_maintainer.pl --norolestats
+
+A user who sets ``patchwork_url`` in their own ``~/.patman`` (or passes
+``-P``) overrides it; anything they leave unset falls back to these
+defaults.
+
 Aliases are recursive.
 
 If the project provides a checkpatch.pl (in its 'scripts/' or 'tools/'
@@ -1289,6 +1314,15 @@ To create Gmail drafts threaded under the original emails::
 Use ``-n`` with ``-d`` for a dry run that shows what would be created
 without calling the Gmail API.
 
+If a draft failed to create or was lost, ``--redraft`` recreates the
+Gmail drafts from the stored reviews, even when the series has already
+been reviewed and the drafts already exist::
+
+    patman review -s 497923 --redraft --gmail-account your@email
+
+Any existing draft is deleted first, so it is not left as a duplicate
+in the thread.
+
 Use ``--apply-only`` to download and apply patches without running the
 AI review -- useful for checking that patches apply cleanly.
 
@@ -1310,10 +1344,48 @@ again::
 
     patman review -s 497923 -U us -f --reviewer 'Your Name <your@email>'
 
+With ``-d``, the Gmail drafts from the previous review are deleted too,
+so the re-review does not leave duplicates in the thread.
+
 If the reviewer email (from ``--reviewer`` or git config) differs from
 the ``--gmail-account``, patman sets the From header on the draft so
 the email is sent with the correct identity.
 
+Reviewing your own series before sending
+----------------------------------------
+
+To get an AI review of your own series before sending it, add the
+series with ``patman series add`` and then run::
+
+    patman series review
+
+This reviews the commits on the current branch (or ``-s <name>``) with
+the same agent, along with the cover letter (stored as patch 0), and
+saves the findings in the database, keyed by version. Because the
+review is expensive, it is saved so you can read it later without
+re-running::
+
+    patman series info -r          # show the stored review
+    patman series info -r 2 3      # just patches 2 and 3
+
+Re-running is refused when a review is already stored; pass ``-f`` to
+review again, replacing the stored one. Unlike ``patman review``, this
+needs no patchwork link and creates no drafts -- it is purely a local
+pre-send check. Reviews from the previous version are used as context,
+so a follow-up review focuses on what changed.
+
+Active series only
+------------------
+
+By default patman only reviews a series when at least one of its
+patches is in an active patchwork state: new, RFC, under-review,
+changes-requested or needs-review-ack. Reviewing a series
+that patchwork has finished with (accepted, superseded, rejected and so
+on) fails with a message naming the override. Use ``--any-state`` to
+review regardless::
+
+    patman review -s 497923 --any-state
+
 How the review works
 --------------------
 
@@ -1331,9 +1403,21 @@ over the drafts to tighten the language, remove cross-patch duplicates
 and check voice consistency. Approved reviews without comments are
 excluded from refinement to preserve their quoted commit messages.
 
+If the agent has nothing to say about a patch -- no comments and not an
+approval -- no review is produced for it, rather than an empty
+greeting-only reply.
+
+Comments on the commit message are placed before comments on the code,
+matching the usual reply order.
+
 A mechanical cleanup step also runs to remove backticks and fix function
 quoting style (e.g. ``malloc()`` not ```malloc```).
 
+Only one review of a given series runs at a time. If a review for the
+same series is already in progress -- from another patman invocation or
+a scan -- the second is refused rather than corrupting the shared
+review worktree and database records.
+
 Apply step
 ~~~~~~~~~~
 
@@ -1342,12 +1426,37 @@ changes -- including untracked files -- so build artefacts on the
 current branch don't leak into the review. The original branch and
 stash are restored at the end of the run, including on failure.
 
-If the apply agent finishes but the resulting branch holds fewer
-commits than the series cover letter advertises, patman aborts with a
-message of the form ``Only N of M patches applied to <branch>;
-aborting. Fix the conflicts manually and retry.`` The database row
-for the new version is rolled back so a retry starts from a clean
-state.
+If the apply agent applies some but not all of the patches -- for
+example one depends on a prerequisite series that is not yet upstream
+-- patman warns (``Only N of M patches applied to <branch>; reviewing
+what is there``) and reviews the patches that did apply. Only when
+nothing applies at all does it fail and roll back the new version's
+database row.
+
+Each review is matched to its patchwork patch by subject, not by
+position, so a patch that failed to apply does not shift the remaining
+reviews onto the wrong patches.
+
+Coverity static analysis
+------------------------
+
+With ``--coverity``, patman runs Coverity on the series and feeds the
+new defects into the review. Coverity analyses a whole build rather
+than a diff, so patman builds and analyses the base branch and the
+patched branch separately and reports only the defects the series
+introduces (matched by Coverity's mergeKey)::
+
+    patman review -s 497923 -U us --coverity \
+        --reviewer 'Your Name <your@email>'
+
+This needs the ``cov-build``, ``cov-analyze`` and ``cov-format-errors``
+tools on your PATH; if they are missing the check is skipped with a
+warning. The build uses ``sandbox_defconfig`` by default; use
+``--coverity-defconfig`` to pick another board. Building twice makes
+this much slower than a normal review.
+
+The new defects are passed to the review agent as context, so it can
+raise the ones that fall in the code each patch changes.
 
 Patchwork subcommands
 ---------------------
@@ -1423,6 +1532,34 @@ This:
 - Generates response drafts when appropriate (e.g. answering
   questions, pushing back on objections, or conceding gracefully)
 
+Scanning for new versions
+-------------------------
+
+Rather than reviewing one series at a time, ``--scan`` looks on
+patchwork for new versions of series you have already reviewed and
+reviews them::
+
+    patman review --scan -U us --reviewer 'Your Name <your@email>'
+
+For each reviewed series it takes the highest version on patchwork
+above the latest one reviewed. A version is reviewed only once it has
+fully appeared on patchwork; if the newest version is still arriving,
+the series is left to wait rather than reviewing an older, now
+superseded one. Inactive series (see `Active series only`_) are
+skipped.
+
+Reviews run in parallel, each in its own child process and review
+worktree, up to ``--jobs`` (``-j``) at a time (default 4).
+
+Each review's output is buffered and printed as one block when it
+finishes, prefixed with a ``[done/total]`` counter and ending with a
+summary line::
+
+    Scanned: 3 new, 1 reviewed, 1 waiting, 1 skipped, 0 failed
+
+Use ``-n`` / ``--dry-run`` to see which series would be reviewed,
+waiting or skipped, without launching any reviews.
+
 Review lifecycle
 ----------------
 
@@ -1435,8 +1572,17 @@ Each review goes through these states:
 - **replied**: Author or another reviewer has replied to our review
 
 When reviewing a new version of a previously reviewed series, patman
-loads the previous review as context for the AI, so it can check
-whether earlier issues have been addressed.
+loads the most recent earlier version that has reviews as context for
+the AI, so it can check whether earlier issues were addressed and avoid
+raising fresh points the earlier versions did not. Versions are linked
+by their cleaned cover-letter title.
+
+An older database may have stored each version as a separate, unlinked
+record, leaving follow-up reviews without this context. Repair it by
+merging the split records, which backs up the database (to
+``<db>.bak``) first::
+
+    patman review --relink
 
 Aliases
 -------