pre-commit-bigfix 2.0.1__py3-none-any.whl

pre_commit_bigfix/bes_relevance_lint.py

@@ -0,0 +1,402 @@
+#!/usr/bin/env python3
+"""Pre-commit hook: lint the relevance inside BES files.
+
+Every other hook in this repo treats relevance as opaque -- `{...}` is a lexer
+state mechanically identical to a string literal, and the most any check proves
+about a condition is that it starts with a brace. This hook is where that stops:
+it hands each relevance statement to `bigfix-relevance-analyzer`, which parses
+it, binds `it`, resolves every inspector against the dumps, type-checks the
+result, and scores what it costs to evaluate.
+
+Every relevance site the analyzer's extractor recognizes is checked -- <Relevance>
+bodies, <SuccessCriteria Option="CustomRelevance"> bodies, Analysis <Property>
+bodies, and the `{...}` substitutions inside <ActionScript> -- so a defect in a
+substitution is reported at the line it lives on, not at the top of the file.
+
+Checks:
+    E600  the statement could not be parsed
+    E601  the statement contains text that could not be lexed
+    E602  `it` is used where there is no context to bind it to
+    E603  the type checker reported a problem beyond an unbound `it`
+    E604  the complexity score is above the ceiling (raise with --max-score)
+    E605  the evaluation cost is above the ceiling (raise with
+          --max-evaluation-cost)
+    E606  a directory tree was deeper than the walk's limit, so it was not
+          fully scanned. Only reachable when auto-discovering -- pre-commit
+          always passes filenames
+    E607  a path given to the linter does not exist, could not be read, or
+          is not a file type the analyzer's extractor recognizes (under
+          pre-commit the hook's `files:` pattern keeps those away)
+    E608  the value does not fit the kind of site it was extracted from -- a
+          non-boolean <Relevance>, or an `if`/`elseif`/`continue if`
+          condition that is not a boolean or string
+    E609  inspectors exclusive to client relevance and to session relevance in
+          one statement, which no engine can answer
+    E610  an ActionScript command word used as a relevance name -- usually an
+          ActionScript line pasted or doubled into relevance
+    E611  a plural operand where the engine requires a single value, which it
+          refuses before evaluating anything. Split out of E603; where the
+          analyzer can work out `unique value of` or the singular spelling of
+          an aggregate, it is printed as a suggested fix
+    E612  an ActionScript `{` with anything after it on its line and no `}` to
+          close it there, which fails the action
+    E613  a `<?Relevance` with no closing `?>`, so its relevance was not linted
+    E614  a BES file that is not well-formed XML, so nothing in it was linted.
+          Off by default -- bes-schema-validate owns file validity -- and
+          switched back on with --enable E614
+    W600  a name no inspector dump defines. A warning rather than an error
+          because a repo running a newer client than the analyzer's snapshot
+          legitimately uses names it has never heard of
+    W601  a property written singular over an object that may be plural.
+          Disabled by default in .pre-commit-hooks.yaml: it fires ~6 times per
+          file across real content, which drowns everything else. Enable it
+          deliberately with --enable W601
+    W602  a singular spelling mid-chain -- under a `whose` filter, or where a
+          plural is built from it -- where the plural reads safer
+    W603  two version-looking strings compared as strings, not as versions
+    W604  a version comparison that truncates to the shorter operand's
+          components
+    W605  an ordinary ActionScript `{...}` substitution (in a `run`, `wait`,
+          `parameter`, ...) whose value is an opaque object with no text form
+          -- a `bes *`, `dmi *`, `smbios *`, `xml dom *`, `active directory *`
+          or `sqlite *` object, or a bare `registry`, `process`, `wmi
+          object`, ... -- so there is nothing to embed in the command line.
+          A warning rather than an E608 error because which types cannot
+          render is the analyzer's curated inference, not a confirmed engine
+          fact
+    W606  an ordinary ActionScript `{...}` substitution whose value may be
+          more than one value. The client joins a plural with no separator,
+          so the action runs but probably not as meant; use
+          `concatenation "<sep>" of (...)` or a tighter filter
+    W607  a relevance-tagged markdown code fence that is never closed, so its
+          relevance was not linted (markdown only; never from a BES file)
+
+E-codes fail the hook; warnings fail only under --strict.
+
+Unparsable XML is skipped, not reported (E614 is off by default) --
+bes-schema-validate owns file validity, and this hook must not duplicate its
+findings. That does mean a
+truncated file passes here: a clean run says the relevance the extractor could
+see is sound, not that the file parses.
+
+A file opts out of every check here with `pre-commit-skip: bes-relevance-lint`
+anywhere in it, the same marker the sibling hooks honor. There is no per-rule
+marker: --disable takes the code repo-wide, and a single file that legitimately
+needs relevance this complex is what --max-score is for.
+
+There is no auto-fix: files are never rewritten. Where the analyzer can work
+out a safe rewrite of a whole statement (today, the singular spellings behind
+W602 and the `unique value of` / singular-aggregate rewrites behind E611), the fixed statement is printed once under that statement's first
+finding as `suggested fix: ...`, for a human to copy in. Everything else needs
+a human to decide what the relevance was meant to say.
+
+Usage:
+    bes-relevance-lint [--strict] [--disable E604] [--enable W601] [FILES...]
+
+Exit status:
+    0  no E-code findings (and, without --strict, no warnings either), or the
+       interpreter is older than 3.11, where the analyzer cannot be installed
+       and the hook skips with a notice rather than failing a build that has
+       no way to go green
+    1  an E-code fired, a warning fired under --strict, or the analyzer is
+       missing on a 3.11+ interpreter, where it should have been installed
+"""
+
+import argparse
+import sys
+
+try:
+    from bigfix_relevance_analyzer import (
+        LintConfig,
+        Severity,
+        lint_directory,
+        lint_paths,
+    )
+
+    IMPORT_ERROR = None
+except ImportError as exc:  # pragma: no cover - exercised only on an old Python
+    LintConfig = lint_directory = lint_paths = Severity = None
+    IMPORT_ERROR = exc
+
+__all__ = ["main"]
+
+# Every rule the analyzer can report, mapped to this repo's code vocabulary.
+# Two spellings exist because a repo configures hooks by E-code (--disable E604,
+# same as every sibling hook) while the analyzer names its rules in prose; the
+# analyzer's own name is printed in the message tail so either one greps to the
+# same line.
+#
+# tests/test_bes_relevance_lint.py fails if a key of the analyzer's RULES is
+# missing here -- that is what turns "the library added a rule" from a silent
+# dropped finding into a red build.
+CODES = {
+    "parse-error": "E600",
+    "error-token": "E601",
+    "unbound-it": "E602",
+    "type-error": "E603",
+    "complexity": "E604",
+    "evaluation-cost": "E605",
+    "max-depth-exceeded": "E606",
+    "file-error": "E607",
+    "site-type-mismatch": "E608",
+    "mixed-dialect": "E609",
+    "actionscript-keyword": "E610",
+    "singular-required": "E611",
+    "unterminated-substitution": "E612",
+    "unterminated-processing-instruction": "E613",
+    "xml-parse-error": "E614",
+    "unknown-inspector": "W600",
+    "non-unique-risk": "W601",
+    "plural-preferred": "W602",
+    "version-like-string-compare": "W603",
+    "version-truncating-compare": "W604",
+    "non-renderable-substitution": "W605",
+    "plural-substitution": "W606",
+    "unterminated-code-fence": "W607",
+}
+
+KNOWN_CODES = frozenset(CODES.values())
+
+# The reverse direction, for --disable/--enable: a repo names an E-code, the
+# analyzer's LintConfig wants its own.
+ANALYZER_CODES = {code: name for name, code in CODES.items()}
+
+# Off unless a repo names them in --enable. E614 is a BES file that is not
+# well-formed XML: bes-schema-validate already reports that, and this hook must
+# not duplicate its findings, so unparsable XML stays skipped here.
+DEFAULT_DISABLED = frozenset({"E614"})
+
+
+MIN_ANALYZER_PYTHON = (3, 11)
+
+
+def _analyzer_unavailable():
+    """Explain the missing analyzer and return the exit status to use.
+
+    The two cases are not the same failure. Below 3.11 the dependency cannot
+    be installed at all -- setup.cfg holds it back with an environment marker
+    on purpose, because this package still supports 3.8 -- so nothing the repo
+    writes in its config makes the hook run, and failing would leave it a
+    permanently red build with no fix available. There the hook skips: it
+    prints why and exits 0. On 3.11+ the analyzer is a hard dependency, so a
+    missing one is a broken install and stays a failure.
+    """
+    running = f"{sys.version_info[0]}.{sys.version_info[1]}"
+    if sys.version_info < MIN_ANALYZER_PYTHON:
+        print(
+            "bes-relevance-lint: skipped. It requires bigfix-relevance-analyzer, "
+            f"which needs Python 3.11 or newer; this interpreter is {running}. "
+            "To actually run this hook, point pre-commit at a 3.11+ interpreter "
+            "with `default_language_version` in your .pre-commit-config.yaml. "
+            f"({IMPORT_ERROR})"
+        )
+        return 0
+    print(
+        "bes-relevance-lint requires bigfix-relevance-analyzer, which is not "
+        f"importable on this Python {running} interpreter even though it is new "
+        "enough for it. Reinstall this package's dependencies (pip install "
+        "--upgrade pre-commit-bigfix), or drop this hook from your config. "
+        f"({IMPORT_ERROR})"
+    )
+    return 1
+
+
+def _split_codes(raw):
+    """Parse a comma-separated --disable/--enable value into a set of E-codes."""
+    return {code.strip().upper() for code in raw.split(",") if code.strip()}
+
+
+def _severities(disabled, enabled):
+    """Per-code overrides for LintConfig, in the analyzer's own vocabulary."""
+    severities = {}
+    for code in disabled:
+        severities[ANALYZER_CODES[code]] = Severity.IGNORE
+    for code in enabled:
+        # Restore the analyzer's own default rather than forcing a severity:
+        # --enable exists to undo a default --disable from the hook
+        # declaration, not to promote a warning into an error. --strict is
+        # what does that, for every warning at once.
+        severities.pop(ANALYZER_CODES[code], None)
+    return severities
+
+
+SKIP_MARKER = "pre-commit-skip: bes-relevance-lint"
+
+
+def _opted_out(path):
+    """Whether this file carries the marker that skips this hook entirely.
+
+    Read as bytes and matched against bytes: this runs before the analyzer
+    touches the file, so it must not care whether the file decodes cleanly.
+    An unreadable file is not opted out -- it simply yields no findings once
+    the extractor reaches it.
+    """
+    try:
+        with open(path, "rb") as handle:
+            return SKIP_MARKER.encode("utf-8") in handle.read()
+    except OSError:
+        return False
+
+
+def _report(findings):
+    """Print each finding in this repo's format.
+
+    Returns (errors, warnings).
+    """
+    errors = warnings = 0
+    # Every fixable finding from one statement carries the same whole-statement
+    # rewrite, so print it once per statement rather than once per finding.
+    suggested = set()
+    for finding in findings:
+        code = CODES[finding.code]
+        where = f"{finding.path}:{finding.line}"
+        label = "warning: " if finding.severity is Severity.WARNING else ""
+        print(f"{where}: [{code}] {label}{finding.message} ({finding.code})")
+        fix = getattr(finding, "autofix", None)
+        if fix is not None:
+            site_line = finding.site.line if finding.site is not None else None
+            key = (str(finding.path), site_line, fix.original)
+            if key not in suggested:
+                suggested.add(key)
+                print(f"    suggested fix: {fix.fixed}")
+        if finding.severity is Severity.WARNING:
+            warnings += 1
+        else:
+            errors += 1
+    return errors, warnings
+
+
+def main(argv=None):
+    """Execution starts here.
+
+    argv defaults to None so this works both as a console_scripts entry point
+    (pre-commit calls it with no arguments; argparse then reads sys.argv) and
+    when called directly as `main(sys.argv[1:])`.
+    """
+    if IMPORT_ERROR is not None:
+        return _analyzer_unavailable()
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="treat warnings as failures (non-zero exit); default: advisory",
+    )
+    parser.add_argument(
+        "--disable",
+        default="",
+        metavar="CODES",
+        help="comma-separated check IDs to skip entirely, e.g. --disable E604",
+    )
+    parser.add_argument(
+        "--enable",
+        default="",
+        metavar="CODES",
+        help=(
+            "comma-separated check IDs to switch back on, undoing a --disable "
+            "this hook declares by default, e.g. --enable W601"
+        ),
+    )
+    parser.add_argument(
+        "--max-score",
+        type=float,
+        default=None,
+        help=(
+            "raise E604's complexity ceiling above the analyzer's default; "
+            "content that legitimately needs to be this complex should raise "
+            "this rather than disable the check"
+        ),
+    )
+    parser.add_argument(
+        "--max-evaluation-cost",
+        type=float,
+        default=None,
+        help="raise E605's evaluation-cost ceiling above the analyzer's default",
+    )
+    parser.add_argument(
+        "--dialect",
+        choices=["client", "session"],
+        default=None,
+        help="force the dialect instead of trusting what extraction says",
+    )
+    parser.add_argument(
+        "--platform",
+        default=None,
+        help="narrow client inspector lookups to one platform, e.g. windows",
+    )
+    parser.add_argument(
+        "--max-depth",
+        type=int,
+        default=6,
+        help=(
+            "how many directory levels to walk when auto-discovering "
+            "(no effect when files are given, which is always the case under "
+            "pre-commit)"
+        ),
+    )
+    parser.add_argument(
+        "files",
+        nargs="*",
+        help=(
+            "files to check; a named file the analyzer's extractor does not "
+            "recognize is reported as E607. If omitted, the current folder and "
+            "below is walked"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    disabled = _split_codes(args.disable)
+    enabled = _split_codes(args.enable)
+    unknown = (disabled | enabled) - KNOWN_CODES
+    if unknown:
+        print(
+            "warning: ignoring unknown --disable/--enable code(s): {}".format(
+                ", ".join(sorted(unknown))
+            )
+        )
+    disabled -= unknown
+    enabled -= unknown
+    disabled |= DEFAULT_DISABLED - enabled
+
+    config_kwargs = {"severities": _severities(disabled, enabled)}
+    # The analyzer's ceilings are on by default and these only raise them, so a
+    # None here means "keep the built-in default", not "no limit".
+    if args.max_score is not None:
+        config_kwargs["max_score"] = args.max_score
+    if args.max_evaluation_cost is not None:
+        config_kwargs["max_evaluation_cost"] = args.max_evaluation_cost
+    if args.platform is not None:
+        config_kwargs["platform"] = args.platform
+    if args.dialect is not None:
+        from bigfix_relevance_analyzer.dialect import Dialect
+
+        config_kwargs["dialect"] = Dialect(args.dialect)
+
+    config = LintConfig(**config_kwargs)
+
+    if args.files:
+        findings = lint_paths(
+            [path for path in args.files if not _opted_out(path)], config
+        )
+    else:
+        # Filter after the walk rather than before it: the analyzer owns
+        # discovery, and re-walking here to drop opted-out files first would
+        # mean two definitions of what counts as a file to check.
+        findings = [
+            finding
+            for finding in lint_directory(".", config, max_depth=args.max_depth)
+            if not _opted_out(finding.path)
+        ]
+
+    error_count, warning_count = _report(findings)
+
+    if warning_count:
+        print(f"{warning_count} warning(s).")
+    if error_count:
+        print(f"{error_count} issue(s).")
+    # E-codes always fail; warnings fail only under --strict
+    return 1 if (error_count or (warning_count and args.strict)) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

pre_commit_bigfix/bes_schema_validate.py

@@ -0,0 +1,84 @@
+"""A pre-commit hook to validate BigFix XML files against their schemas.
+
+Covers BES and OJO files, Git External Custom Site files (siteConfig.xml,
+site.xml, digest.xml) and BigFix Inventory signatures (Signatures/*.xml).
+Only the schemas bundled with validate_bes_xml are used, never a *.xsd in the
+current folder. Each error is printed as `path:line: message`; files that
+pass print nothing. A .xml file whose root has no bundled schema (a sitemap
+or a Maven site descriptor named site.xml, say) is not a BigFix file and is
+skipped; a .bes or .ojo file with no schema fails.
+"""
+
+import argparse
+import os
+import sys
+
+import validate_bes_xml
+
+if __package__ in (None, ""):  # run directly as a script, not as a module
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from pre_commit_bigfix import bes_common
+
+
+def build_argument_parser():
+    """Build and return the argument parser."""
+
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("filenames", nargs="*", help="Filenames to check.")
+
+    return parser
+
+
+def check_file(filename, schemas):
+    """Validate one file; print its errors and return True if it failed."""
+
+    result = validate_bes_xml.validate_bes(path=filename, schema_pathnames=schemas)
+    if result:
+        return False
+    # compare against the value: every Status member is a non-empty str
+    if result.status == "no_schema":
+        if filename.lower().endswith(".xml"):
+            return False  # not a BigFix file
+        # inferred_schema is left out: it is cut short for namespaced roots
+        print(f"{filename}: no schema to validate this file against")
+        return True
+    for line, message in result.errors:
+        if line is None:
+            print(f"{filename}: {message}")
+        else:
+            print(f"{filename}:{line}: {message}")
+    if not result.errors:  # never expected, but a failure must say something
+        print(f"{filename}: {result.status.value}")
+    return True
+
+
+def main(argv=None):
+    """Main process."""
+
+    # Parse command line arguments.
+    argparser = build_argument_parser()
+    args = argparser.parse_args(argv)
+
+    if not args.filenames:
+        return 0
+
+    schemas = bes_common._bundled_schemas(  # pylint: disable=protected-access
+        validate_bes_xml
+    )
+    if not schemas:
+        # an empty list would make validate_bes_xml fall back to the cwd schemas
+        print(
+            "bes-schema-validate: validate_bes_xml has no bundled schemas; "
+            'reinstall "validate_bes_xml>=2.4.1,<3"',
+            file=sys.stderr,
+        )
+        return len(args.filenames)
+
+    return sum(check_file(filename, schemas) for filename in args.filenames)
+
+
+if __name__ == "__main__":
+    sys.exit(main())