mirror of
https://github.com/norandom/OpenUltraSAST.git
synced 2026-10-18 12:39:28 +00:00
pre-push(17.2): name every skipped check in plain words
One terminal line per distinct coverage reason (push/explain.py): hex-encoded paths decoded, per-question sha256 tokens dropped and counted, unknown reasons still printed; the JSON artifact keeps the raw values. A changed language with no engine frontend and no quick rules is recorded and printed as "language not covered: <lang> (...)", in pre-push and in `ousast scan`. The scan report renders the eight degradations cli.py recorded but never showed, and any reason without a sentence. The hook forwards OUSAST_COMPARISON_BASE. Requirement 9.2. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo
This commit is contained in:
Marius Ciepluch
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
bf07cd4d1d
commit
f555dee640
@@ -0,0 +1,176 @@
|
||||
"""Plain-language lines for pre-push coverage reasons (Requirement 9.2).
|
||||
|
||||
The artifact keeps every raw reason exactly as recorded. The terminal gets one line per distinct
|
||||
kind of skip, in words a first-time user can act on: hex-encoded repository paths are decoded,
|
||||
per-question sha256 tokens are dropped and counted, and a reason this table does not know is
|
||||
still printed rather than hidden.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import re
|
||||
from collections.abc import Sequence
|
||||
|
||||
_HEX_PATH = re.compile(r"^((?:[0-9a-f]{2})+):(.+)$")
|
||||
_TOKEN = re.compile(r"^(.+?):(?:[a-z][a-z0-9-]*:)?[0-9a-f]{64}$")
|
||||
|
||||
# Reasons that summarise others; printing them would only repeat a line already shown.
|
||||
_SUMMARY = frozenset({"analysis_incomplete"})
|
||||
|
||||
_ENGINE_MISSING = (
|
||||
"engine did not run: the code graph could not be built (is Joern installed? 'joern-parse' must be on PATH, "
|
||||
"or run the hook through ops/ousast-docker)"
|
||||
)
|
||||
_NOVELTY = "whether this push introduced some engine findings could not be established ({detail})"
|
||||
|
||||
GLOSSARY: dict[str, str] = {
|
||||
"cpg_build_failed": _ENGINE_MISSING,
|
||||
"cpg_unavailable": _ENGINE_MISSING,
|
||||
"cpg_empty": "engine read no code: the code graph came back empty",
|
||||
"frontend_unsupported": "engine has no frontend for at least one language in this push",
|
||||
"deadline_exhausted": (
|
||||
"engine did not finish within the {deadline} s deadline; rerun with a longer --deadline, "
|
||||
"or set OUSAST_PUSH_ENGINE=background to finish it after the push"
|
||||
),
|
||||
"change_context_deadline_exhausted": "the deadline ran out while relating the change to the code",
|
||||
"report_deadline_exhausted": "the deadline ran out while saving the details",
|
||||
"base_comparison_unavailable": "no base revision was analysed, so no engine finding can be called new or worsened",
|
||||
"base_counterpart_unresolved": "the changed code has no counterpart in the base revision to compare against",
|
||||
"base_unavailable": "the base revision is unavailable",
|
||||
"declaration_paths_unavailable": "project declaration files could not be listed",
|
||||
"ambiguous_line_correspondence": "changed lines could not be matched one-to-one to base lines in {paths}",
|
||||
"line_correspondence_unavailable": "changed lines could not be mapped to the base in {paths}",
|
||||
"ambiguous_path_rename_correspondence": "a renamed file could not be matched to one base file: {paths}",
|
||||
"unmatched_added_deleted_path_correspondence": (
|
||||
"files were both added and deleted, so a moved file cannot be told apart from a new one"
|
||||
),
|
||||
"capability_unavailable": ("engine findings are not qualified as alerts yet: no capability has passed independent evaluation"),
|
||||
"capability_disabled": "an engine capability is declared but disabled",
|
||||
"capability_unevaluated": "an engine capability has not passed its evaluation",
|
||||
"capability_ambiguous": "more than one capability declaration matches a finding",
|
||||
"eligibility": "the capability registry does not match this build ({detail}), so no capability can be used",
|
||||
"comparison_unknown": _NOVELTY,
|
||||
"dynamic_external_or_depth_context_unresolved": ("{n} engine check(s) depend on dynamic or external code the engine cannot follow"),
|
||||
"query_failed": "an engine query failed, so some regions were not decided",
|
||||
"query_budget_reserved": "some engine questions were not asked, to keep time for the ones that were",
|
||||
"query_too_expensive": "some engine questions were too expensive to answer",
|
||||
"regions_truncated": "only the highest-ranked regions were examined (--max-regions)",
|
||||
"files_unparsed": "some files could not be parsed by the engine",
|
||||
"cross_partition_semantics_unresolved": "flows between languages in this repository are not followed",
|
||||
"resolution": "the pushed ref could not be resolved ({detail})",
|
||||
"push_input_failed": "the push input could not be read ({detail})",
|
||||
"snapshot": "some files could not be materialised for analysis ({detail})",
|
||||
"dependency_unresolved": "{n} engine finding(s) depend on code the comparison could not resolve",
|
||||
"change_unsupported": "{n} engine finding(s) have no supported relationship to the change",
|
||||
}
|
||||
|
||||
# Comparison outcomes recorded per finding; each means novelty was not established.
|
||||
_NOVELTY_REASONS = frozenset(
|
||||
{
|
||||
"base_incomplete",
|
||||
"head_context_incomplete",
|
||||
"witness_identity_unresolved",
|
||||
"semantics_mismatch",
|
||||
"change_context_unresolved",
|
||||
"operation_correspondence_unresolved",
|
||||
"base_reachability_bounded",
|
||||
"base_operation_inventory_unavailable",
|
||||
"base_enumeration_scope_reachability_derived",
|
||||
"operation_present_in_base_without_traced_flow",
|
||||
"operation_moved_within_change",
|
||||
"source_correspondence_unresolved",
|
||||
}
|
||||
)
|
||||
|
||||
_RESOLUTION = {
|
||||
"missing_base": (
|
||||
"new branch: the remote has no base to compare against, so the engine comparison did not run "
|
||||
"(OUSAST_COMPARISON_BASE=<local branch> compares against a local branch instead)"
|
||||
),
|
||||
"unsupported_base": "the remote's current commit is not available locally, so there is no base to compare against",
|
||||
"no_merge_base": "the pushed commit shares no history with the remote branch",
|
||||
"ambiguous_base": "more than one base could apply to the pushed ref",
|
||||
"missing_target": "the pushed commit could not be found locally",
|
||||
"unsupported_target": "the pushed object is not a commit",
|
||||
"resolution_error": "the pushed ref could not be resolved",
|
||||
}
|
||||
|
||||
|
||||
def _words(value: str) -> str:
|
||||
return value.replace("_", " ").replace(":", ": ")
|
||||
|
||||
|
||||
def _decode(path_hex: str) -> str | None:
|
||||
try:
|
||||
text = os.fsdecode(bytes.fromhex(path_hex))
|
||||
except ValueError:
|
||||
return None
|
||||
return text if text and text.isprintable() else None
|
||||
|
||||
|
||||
def _split(reason: str) -> tuple[str, str, str | None]:
|
||||
"""(key, detail, decoded path) for one raw reason."""
|
||||
path = None
|
||||
match = _HEX_PATH.match(reason)
|
||||
if match and (decoded := _decode(match.group(1))) is not None:
|
||||
path, reason = decoded, match.group(2)
|
||||
token = _TOKEN.match(reason)
|
||||
if token:
|
||||
reason = token.group(1)
|
||||
if reason in GLOSSARY or reason in _NOVELTY_REASONS or reason in _SUMMARY:
|
||||
return reason, "", path
|
||||
head, _, rest = reason.partition(":")
|
||||
if head not in GLOSSARY and head.endswith("_failed") and rest:
|
||||
return "stage_failed", f"{head[: -len('_failed')]}:{rest}", path
|
||||
return head, rest, path
|
||||
|
||||
|
||||
def language_reason(language: str, changed: int, total: int) -> str:
|
||||
"""The raw reason recorded when a language has no engine frontend and no quick rules."""
|
||||
return f"language_not_covered:{language}:{changed}:{total}"
|
||||
|
||||
|
||||
def explain(reasons: Sequence[str], *, deadline: float | None = None) -> list[str]:
|
||||
"""One plain line per distinct kind of skipped or incomplete check, in first-seen order."""
|
||||
groups: dict[tuple[str, str], list[str | None]] = {}
|
||||
for reason in reasons:
|
||||
key, detail, path = _split(str(reason))
|
||||
if key in _SUMMARY:
|
||||
continue
|
||||
if key in _NOVELTY_REASONS:
|
||||
key, detail = "comparison_unknown", _words(key)
|
||||
groups.setdefault((key, detail), []).append(path)
|
||||
novelty_details = [detail for (key, detail) in groups if key == "comparison_unknown" and detail]
|
||||
lines: list[str] = []
|
||||
for (key, detail), paths in groups.items():
|
||||
if key == "comparison_unknown":
|
||||
if detail or not novelty_details:
|
||||
lines.append(_NOVELTY.format(detail=detail or "see the details file"))
|
||||
continue
|
||||
named = sorted({p for p in paths if p})
|
||||
shown = ", ".join(named[:3]) + (f" and {len(named) - 3} more" if len(named) > 3 else "")
|
||||
if key == "language_not_covered":
|
||||
language, _, counts = detail.partition(":")
|
||||
changed, _, total = counts.partition(":")
|
||||
lines.append(
|
||||
f"language not covered: {language} ({changed} changed file(s), {total} in the repository): "
|
||||
"no engine frontend and no quick rules, so silence here is not a clean result"
|
||||
)
|
||||
elif key == "resolution":
|
||||
lines.append(_RESOLUTION.get(detail, GLOSSARY["resolution"].format(detail=_words(detail))))
|
||||
elif key == "stage_failed":
|
||||
stage, _, error = detail.partition(":")
|
||||
lines.append(f"the {_words(stage)} step failed ({error})")
|
||||
elif key in GLOSSARY:
|
||||
text = GLOSSARY[key].format(
|
||||
n=len(paths),
|
||||
paths=shown or "some files",
|
||||
detail=_words(detail),
|
||||
deadline=f"{deadline:g}" if deadline is not None else "configured",
|
||||
)
|
||||
lines.append(text)
|
||||
else:
|
||||
suffix = f" in {shown}" if shown else ""
|
||||
lines.append(f"{_words(key if not detail else key + ':' + detail)}{suffix} (see the details file)")
|
||||
return lines
|
||||
@@ -18,6 +18,7 @@ from typing import Literal
|
||||
from openultrasast.model.contracts import ChangeContext, ExecutionBudget
|
||||
from openultrasast.model.scan import ModelScanResult
|
||||
from openultrasast.push.contracts import PushComparison, PushResolution, PushResult, SnapshotManifest
|
||||
from openultrasast.push.explain import explain
|
||||
from openultrasast.push.policy import AdmissionResult, _context_boundaries
|
||||
from openultrasast.redaction import redact_secrets
|
||||
|
||||
@@ -187,6 +188,10 @@ def _save(report: PushReport, target: Path, budget: ExecutionBudget) -> str | No
|
||||
process.close()
|
||||
|
||||
|
||||
# Distinct skip kinds shown in the terminal; the artifact keeps every reason.
|
||||
_SKIP_LINES = 12
|
||||
|
||||
|
||||
def _short(value: str, limit: int = 180) -> str:
|
||||
# Bound before escaping: repository-controlled names/witnesses cannot add lines
|
||||
# or terminal escapes. Full spelling and every witness remain in the artifact.
|
||||
@@ -260,8 +265,14 @@ def render_report(report: PushReport, *, artifact: Path | None, error: str | Non
|
||||
notices = []
|
||||
if report.result.coverage_status in ("incomplete", "unavailable"):
|
||||
reasons = report.admission.coverage_reasons
|
||||
# One plain line per distinct skipped check (Requirement 9.2); the artifact keeps the raw values.
|
||||
deadline = report.timings.get("deadline_seconds")
|
||||
for skipped in explain(reasons, deadline=float(deadline) if deadline is not None else None)[:_SKIP_LINES]:
|
||||
lines.append("Skipped: " + _short(skipped, 400))
|
||||
if any("deadline" in reason for reason in reasons):
|
||||
notices.append("Analysis did not finish. Rerun with a longer analysis deadline.")
|
||||
elif any(reason in ("cpg_build_failed", "cpg_unavailable") for reason in reasons):
|
||||
notices.append("Engine checks did not run. Install Joern, or run the hook through ops/ousast-docker. Review the details.")
|
||||
elif any("capability" in reason for reason in reasons):
|
||||
notices.append("Some checks are not enabled for normal alerts. Review capability coverage in the details.")
|
||||
else:
|
||||
|
||||
@@ -9,6 +9,7 @@ import os
|
||||
import pickle
|
||||
import selectors
|
||||
import time
|
||||
from collections import Counter
|
||||
from collections.abc import Callable, Sequence
|
||||
from contextlib import nullcontext
|
||||
from dataclasses import asdict, replace
|
||||
@@ -28,6 +29,7 @@ from openultrasast.preprocess import build_file_target, enumerate_source_files
|
||||
from openultrasast.push.cache import ArtifactCache, SemanticKeys
|
||||
from openultrasast.push.contracts import ComparisonAnalysis, PushComparison, PushResult, SnapshotManifest
|
||||
from openultrasast.push.eligibility import fingerprint, load_registry
|
||||
from openultrasast.push.explain import language_reason
|
||||
from openultrasast.push.policy import (
|
||||
ActionableDefect,
|
||||
AdmissionCandidate,
|
||||
@@ -206,6 +208,30 @@ def _record(
|
||||
return report.to_payload()
|
||||
|
||||
|
||||
def _uncovered_languages(manifest: SnapshotManifest, context: ChangeContext) -> list[str]:
|
||||
"""`language_not_covered` reasons for changed languages with no engine frontend and no quick rules.
|
||||
|
||||
Only a language this push changes is named: a Go helper nobody touched is not this push's gap.
|
||||
"""
|
||||
from openultrasast.findings import PATTERN_RULES
|
||||
from openultrasast.model.partitions import FRONTENDS
|
||||
from openultrasast.preprocess import LANGUAGE_BY_EXTENSION
|
||||
|
||||
covered = set(FRONTENDS) | {language for rule in PATTERN_RULES if rule.status != "disabled" for language in rule.languages}
|
||||
if any(not rule.languages for rule in PATTERN_RULES if rule.status != "disabled"):
|
||||
return []
|
||||
|
||||
def language(path: str) -> str | None:
|
||||
return LANGUAGE_BY_EXTENSION.get(os.path.splitext(path)[1].lower())
|
||||
|
||||
totals = Counter(language(os.fsdecode(bytes.fromhex(item.path_hex))) for item in manifest.files)
|
||||
changed = Counter(language(context.decode_path(path)) for path in context.changed_paths if path not in context.deleted_paths)
|
||||
return [
|
||||
language_reason(name, count, totals.get(name, 0))
|
||||
for name, count in sorted((k, v) for k, v in changed.items() if k is not None and k not in covered)
|
||||
]
|
||||
|
||||
|
||||
def _discovery_identity() -> str:
|
||||
root = Path(__file__).resolve().parents[1]
|
||||
# Discovery invokes the shipped mapper, preprocessing, layout and family specs.
|
||||
@@ -347,6 +373,7 @@ def _analyze(
|
||||
context = adapter.compare(comparison, declaration_paths=tuple(set(head_declarations + base_declarations)), budget=budget)
|
||||
context = replace(context, unresolved_boundaries=tuple(dict.fromkeys((*context.unresolved_boundaries, *reasons))))
|
||||
reasons.extend(context.unresolved_boundaries)
|
||||
reasons.extend(_uncovered_languages(tip.manifest, context))
|
||||
stage_started = _stage(timings, stage, stage_started)
|
||||
stage = "head"
|
||||
head_scan = scan_repository(
|
||||
|
||||
Reference in New Issue
Block a user