git-surface 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- git_surface/__init__.py +4 -0
- git_surface/__main__.py +6 -0
- git_surface/_common.py +314 -0
- git_surface/classify.py +275 -0
- git_surface/surface.py +257 -0
- git_surface-0.1.0.dist-info/METADATA +131 -0
- git_surface-0.1.0.dist-info/RECORD +11 -0
- git_surface-0.1.0.dist-info/WHEEL +5 -0
- git_surface-0.1.0.dist-info/entry_points.txt +2 -0
- git_surface-0.1.0.dist-info/licenses/LICENSE +202 -0
- git_surface-0.1.0.dist-info/top_level.txt +1 -0
git_surface/__init__.py
ADDED
git_surface/__main__.py
ADDED
git_surface/_common.py
ADDED
|
@@ -0,0 +1,314 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""Plumbing for git surface: records, arguments, errors and running git.
|
|
3
|
+
|
|
4
|
+
Everything that crosses a process boundary (stdin, stdout, git's output) is bytes. Text is
|
|
5
|
+
decoded only to build a message for stderr or to look for characters in an added line.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
import errno
|
|
9
|
+
import os
|
|
10
|
+
import re
|
|
11
|
+
import subprocess
|
|
12
|
+
import sys
|
|
13
|
+
|
|
14
|
+
from . import __version__
|
|
15
|
+
|
|
16
|
+
EXIT_NOTHING = 0 # ran, nothing found
|
|
17
|
+
EXIT_FOUND = 1 # ran, something found
|
|
18
|
+
EXIT_ERROR = 2 # error
|
|
19
|
+
|
|
20
|
+
# One object id: 40 hex digits (SHA-1) or 64 (SHA-256). \A and \Z, because $ also matches
|
|
21
|
+
# before a trailing LF.
|
|
22
|
+
OID = re.compile(rb"\A(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
|
|
23
|
+
|
|
24
|
+
_ESCAPES = {0x09: "\\t", 0x0A: "\\n", 0x0D: "\\r", 0x5C: "\\\\"}
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Fail(Exception):
|
|
28
|
+
"""A user-facing error: `run` prints `git-surface: <message>` and exits 2."""
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class PipeClosed(Exception):
|
|
32
|
+
"""The reader of stdout went away; `run` exits 0 quietly."""
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def show(data):
|
|
36
|
+
"""Escape a name for an error message so it stays one line of printable ASCII.
|
|
37
|
+
|
|
38
|
+
Args:
|
|
39
|
+
data: bytes (from a record or git) or str (from the command line).
|
|
40
|
+
|
|
41
|
+
Returns:
|
|
42
|
+
A str: TAB, LF, CR and backslash as backslash escapes, other unprintable bytes as \\xHH.
|
|
43
|
+
"""
|
|
44
|
+
if not isinstance(data, bytes):
|
|
45
|
+
data = os.fsencode(data)
|
|
46
|
+
out = []
|
|
47
|
+
for byte in bytearray(data):
|
|
48
|
+
if byte in _ESCAPES:
|
|
49
|
+
out.append(_ESCAPES[byte])
|
|
50
|
+
elif 0x20 <= byte < 0x7F:
|
|
51
|
+
out.append(chr(byte))
|
|
52
|
+
else:
|
|
53
|
+
out.append("\\x%02x" % byte)
|
|
54
|
+
return "".join(out)
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def parse_args(argv, flags):
|
|
58
|
+
"""Split argv into flags and positionals; anything that is not a known flag is positional.
|
|
59
|
+
|
|
60
|
+
A ref that starts with "-" is therefore a ref. "--" ends option parsing.
|
|
61
|
+
|
|
62
|
+
Args:
|
|
63
|
+
argv: The arguments, without the program name.
|
|
64
|
+
flags: The options the command knows, none of which takes a value.
|
|
65
|
+
|
|
66
|
+
Returns:
|
|
67
|
+
A tuple ({flag: True}, [positionals]).
|
|
68
|
+
"""
|
|
69
|
+
opts = {}
|
|
70
|
+
positionals = []
|
|
71
|
+
for i, arg in enumerate(argv):
|
|
72
|
+
if arg == "--":
|
|
73
|
+
positionals.extend(argv[i + 1:])
|
|
74
|
+
break
|
|
75
|
+
if arg in flags:
|
|
76
|
+
opts[arg] = True
|
|
77
|
+
else:
|
|
78
|
+
positionals.append(arg)
|
|
79
|
+
return opts, positionals
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def read_records(zero):
|
|
83
|
+
"""Read all of stdin and return its non-empty records with their numbers.
|
|
84
|
+
|
|
85
|
+
LF mode splits on LF and removes one trailing CR; -z mode splits on NUL. Numbers count
|
|
86
|
+
every record from 1, skipped empty ones included, like line numbers.
|
|
87
|
+
|
|
88
|
+
Args:
|
|
89
|
+
zero: True for NUL-terminated records.
|
|
90
|
+
|
|
91
|
+
Returns:
|
|
92
|
+
A list of (record number, record bytes).
|
|
93
|
+
|
|
94
|
+
Raises:
|
|
95
|
+
Fail: Standard input is not open.
|
|
96
|
+
"""
|
|
97
|
+
if sys.stdin is None:
|
|
98
|
+
raise Fail("standard input is not open")
|
|
99
|
+
data = sys.stdin.buffer.read()
|
|
100
|
+
parts = data.split(b"\0" if zero else b"\n")
|
|
101
|
+
# A final terminator leaves one empty tail; an unterminated last record is kept.
|
|
102
|
+
if parts and parts[-1] == b"":
|
|
103
|
+
parts.pop()
|
|
104
|
+
records = []
|
|
105
|
+
for number, record in enumerate(parts, 1):
|
|
106
|
+
if not zero and record.endswith(b"\r"):
|
|
107
|
+
record = record[:-1]
|
|
108
|
+
if record:
|
|
109
|
+
records.append((number, record))
|
|
110
|
+
return records
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def check_safe(field, zero, what):
|
|
114
|
+
"""Fail if FIELD cannot be written in an LF record (it holds TAB, LF or CR).
|
|
115
|
+
|
|
116
|
+
Args:
|
|
117
|
+
field: The ref or path, as bytes.
|
|
118
|
+
zero: True in -z mode, where every field is safe.
|
|
119
|
+
what: "ref" or "path", for the message.
|
|
120
|
+
|
|
121
|
+
Raises:
|
|
122
|
+
Fail: The field is unsafe in LF mode; the message names -z.
|
|
123
|
+
"""
|
|
124
|
+
if zero:
|
|
125
|
+
return
|
|
126
|
+
if b"\t" in field or b"\n" in field or b"\r" in field:
|
|
127
|
+
raise Fail("%s contains TAB, LF or CR and cannot be written as a line; use -z: %s"
|
|
128
|
+
% (what, show(field)))
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
def write_stdout(data):
|
|
132
|
+
"""Write bytes to stdout, or flush it when DATA is None.
|
|
133
|
+
|
|
134
|
+
Raises:
|
|
135
|
+
PipeClosed: The reader closed the pipe (EPIPE; EINVAL on Windows).
|
|
136
|
+
"""
|
|
137
|
+
try:
|
|
138
|
+
if data is None:
|
|
139
|
+
sys.stdout.flush()
|
|
140
|
+
else:
|
|
141
|
+
sys.stdout.buffer.write(data)
|
|
142
|
+
except OSError as exc:
|
|
143
|
+
if isinstance(exc, BrokenPipeError) or exc.errno in (errno.EPIPE, errno.EINVAL):
|
|
144
|
+
raise PipeClosed()
|
|
145
|
+
raise
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
_TERMINAL = []
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
def _stdout_is_terminal():
|
|
152
|
+
"""Return True if stdout is a terminal; asked once per process."""
|
|
153
|
+
if not _TERMINAL:
|
|
154
|
+
try:
|
|
155
|
+
_TERMINAL.append(bool(sys.stdout.isatty()))
|
|
156
|
+
except (OSError, ValueError):
|
|
157
|
+
_TERMINAL.append(False)
|
|
158
|
+
return _TERMINAL[0]
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def for_terminal(field):
|
|
162
|
+
"""Return FIELD with every byte a terminal could act on written as an escape.
|
|
163
|
+
|
|
164
|
+
C0 controls, DEL, C1 controls and bytes that are not valid UTF-8 become \\xHH, one per
|
|
165
|
+
byte; a backslash is doubled. Printable UTF-8 passes through.
|
|
166
|
+
|
|
167
|
+
Args:
|
|
168
|
+
field: bytes.
|
|
169
|
+
|
|
170
|
+
Returns:
|
|
171
|
+
bytes.
|
|
172
|
+
"""
|
|
173
|
+
out = []
|
|
174
|
+
for char in field.decode("utf-8", "surrogateescape"):
|
|
175
|
+
code = ord(char)
|
|
176
|
+
if char == "\\":
|
|
177
|
+
out.append("\\\\")
|
|
178
|
+
elif 0xDC80 <= code <= 0xDCFF:
|
|
179
|
+
# surrogateescape maps an invalid byte B to U+DC00 + B.
|
|
180
|
+
out.append("\\x%02x" % (code - 0xDC00))
|
|
181
|
+
elif code < 0x20 or 0x7F <= code <= 0x9F:
|
|
182
|
+
out.extend("\\x%02x" % byte for byte in char.encode("utf-8"))
|
|
183
|
+
else:
|
|
184
|
+
out.append(char)
|
|
185
|
+
return "".join(out).encode("utf-8")
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def write_record(fields, zero):
|
|
189
|
+
"""Write one TAB-separated record ending in LF, or NUL with -z.
|
|
190
|
+
|
|
191
|
+
In LF mode on a terminal each field goes through `for_terminal`; pipes, files and -z
|
|
192
|
+
output carry the raw bytes.
|
|
193
|
+
"""
|
|
194
|
+
if not zero and _stdout_is_terminal():
|
|
195
|
+
fields = [for_terminal(field) for field in fields]
|
|
196
|
+
write_stdout(b"\t".join(fields) + (b"\0" if zero else b"\n"))
|
|
197
|
+
|
|
198
|
+
|
|
199
|
+
def git(args):
|
|
200
|
+
"""Run git with list arguments (never a shell) and LC_ALL=C.
|
|
201
|
+
|
|
202
|
+
Args:
|
|
203
|
+
args: The arguments after "git", str or bytes.
|
|
204
|
+
|
|
205
|
+
Returns:
|
|
206
|
+
(exit code, stdout bytes, stderr bytes).
|
|
207
|
+
|
|
208
|
+
Raises:
|
|
209
|
+
Fail: git cannot be run, or (on Windows) an argument is not valid UTF-8.
|
|
210
|
+
"""
|
|
211
|
+
env = dict(os.environ)
|
|
212
|
+
env["LC_ALL"] = "C"
|
|
213
|
+
argv = ["git"]
|
|
214
|
+
for arg in args:
|
|
215
|
+
if isinstance(arg, bytes):
|
|
216
|
+
try:
|
|
217
|
+
arg = os.fsdecode(arg)
|
|
218
|
+
except UnicodeDecodeError:
|
|
219
|
+
raise Fail("cannot pass a name that is not valid UTF-8 to git on this "
|
|
220
|
+
"platform: %s" % show(arg))
|
|
221
|
+
argv.append(arg)
|
|
222
|
+
try:
|
|
223
|
+
proc = subprocess.run(argv, stdin=subprocess.DEVNULL, stdout=subprocess.PIPE,
|
|
224
|
+
stderr=subprocess.PIPE, env=env)
|
|
225
|
+
except OSError as exc:
|
|
226
|
+
raise Fail("cannot run git: %s" % exc)
|
|
227
|
+
return proc.returncode, proc.stdout, proc.stderr
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
def git_error(stderr, code):
|
|
231
|
+
"""Describe a git failure in one escaped line."""
|
|
232
|
+
lines = stderr.strip().splitlines()
|
|
233
|
+
if lines:
|
|
234
|
+
return show(lines[0])
|
|
235
|
+
return "git exited with status %d" % code
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def resolve(ref):
|
|
239
|
+
"""Return the commit id REF names.
|
|
240
|
+
|
|
241
|
+
`rev-parse --verify` must print exactly one object id (this rejects ranges and "^a"),
|
|
242
|
+
and that id must peel to a commit. --end-of-options keeps a ref starting with "-" a ref.
|
|
243
|
+
|
|
244
|
+
Raises:
|
|
245
|
+
Fail: REF is unknown or not a commit.
|
|
246
|
+
"""
|
|
247
|
+
error = Fail("unknown ref or not a commit: %s" % show(ref))
|
|
248
|
+
code, out, _ = git(["rev-parse", "--verify", "--quiet", "--end-of-options", ref])
|
|
249
|
+
oid = out[:-1] if out.endswith(b"\n") else out
|
|
250
|
+
if code != 0 or not OID.match(oid):
|
|
251
|
+
raise error
|
|
252
|
+
code, out, _ = git(["rev-parse", "--verify", "--quiet", oid + b"^{commit}"])
|
|
253
|
+
sha = out.strip()
|
|
254
|
+
if code != 0 or not OID.match(sha):
|
|
255
|
+
raise error
|
|
256
|
+
return sha
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def usage_and_version(opts, usage):
|
|
260
|
+
"""Print usage for -h or the version for --version; return True if one was handled."""
|
|
261
|
+
if opts.get("-h"):
|
|
262
|
+
write_stdout((usage + "\n").encode("ascii"))
|
|
263
|
+
return True
|
|
264
|
+
if opts.get("--version"):
|
|
265
|
+
write_stdout(("git-surface %s\n" % __version__).encode("ascii"))
|
|
266
|
+
return True
|
|
267
|
+
return False
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def error(message):
|
|
271
|
+
"""Write `git-surface: <message>` to stderr as one line ending in LF."""
|
|
272
|
+
if sys.stderr is None:
|
|
273
|
+
return
|
|
274
|
+
text = "git-surface: %s\n" % str(message).replace("\r", "\\r").replace("\n", "\\n")
|
|
275
|
+
sys.stderr.flush()
|
|
276
|
+
stream = getattr(sys.stderr, "buffer", None)
|
|
277
|
+
if stream is None:
|
|
278
|
+
sys.stderr.write(text)
|
|
279
|
+
sys.stderr.flush()
|
|
280
|
+
return
|
|
281
|
+
stream.write(text.encode(getattr(sys.stderr, "encoding", None) or "utf-8",
|
|
282
|
+
"backslashreplace"))
|
|
283
|
+
stream.flush()
|
|
284
|
+
|
|
285
|
+
|
|
286
|
+
def _discard_stdout():
|
|
287
|
+
"""Point file descriptor 1 at the null device so the exit-time flush cannot fail."""
|
|
288
|
+
devnull = os.open(os.devnull, os.O_WRONLY)
|
|
289
|
+
os.dup2(devnull, sys.stdout.fileno())
|
|
290
|
+
|
|
291
|
+
|
|
292
|
+
def run(body):
|
|
293
|
+
"""Call body() and exit with its code; turn every failure into one line and exit 2.
|
|
294
|
+
|
|
295
|
+
A closed stdout pipe is a quiet exit 0; Ctrl-C is exit 130; never a traceback.
|
|
296
|
+
"""
|
|
297
|
+
if sys.stdout is None:
|
|
298
|
+
error("standard output is not open")
|
|
299
|
+
sys.exit(EXIT_ERROR)
|
|
300
|
+
try:
|
|
301
|
+
code = body()
|
|
302
|
+
write_stdout(None)
|
|
303
|
+
except Fail as exc:
|
|
304
|
+
error(exc)
|
|
305
|
+
code = EXIT_ERROR
|
|
306
|
+
except KeyboardInterrupt:
|
|
307
|
+
code = 128 + 2
|
|
308
|
+
except PipeClosed:
|
|
309
|
+
_discard_stdout()
|
|
310
|
+
code = EXIT_NOTHING
|
|
311
|
+
except Exception as exc: # noqa: BLE001 - one line, never a traceback
|
|
312
|
+
error("internal error: %s" % exc)
|
|
313
|
+
code = EXIT_ERROR
|
|
314
|
+
sys.exit(code)
|
git_surface/classify.py
ADDED
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""The classes git surface reports, as pure functions of paths, modes and content.
|
|
3
|
+
|
|
4
|
+
Nothing here runs git. docs/classes.md lists every rule below in prose; keep them together.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
import re
|
|
9
|
+
|
|
10
|
+
# --- Path rules -------------------------------------------------------------------------
|
|
11
|
+
|
|
12
|
+
# ci: files a CI service runs.
|
|
13
|
+
CI_PREFIXES = (b".github/workflows/", b".github/actions/", b".gitea/workflows/",
|
|
14
|
+
b".forgejo/workflows/", b".gitlab/ci/", b".circleci/", b".buildkite/",
|
|
15
|
+
b".woodpecker/", b".azure-pipelines/")
|
|
16
|
+
CI_ROOT_FILES = {b".gitlab-ci.yml", b".travis.yml", b"azure-pipelines.yml",
|
|
17
|
+
b"azure-pipelines.yaml", b"bitbucket-pipelines.yml", b".drone.yml",
|
|
18
|
+
b".woodpecker.yml", b"appveyor.yml", b".appveyor.yml", b"cloudbuild.yaml",
|
|
19
|
+
b"cloudbuild.yml", b"action.yml", b"action.yaml"}
|
|
20
|
+
CI_NAMES = {b"Jenkinsfile"}
|
|
21
|
+
|
|
22
|
+
# hook: files a git hook manager runs on a developer's machine.
|
|
23
|
+
HOOK_PREFIXES = (b".githooks/", b".husky/")
|
|
24
|
+
HOOK_ROOT_FILES = {b".pre-commit-config.yaml", b".pre-commit-hooks.yaml", b"lefthook.yml",
|
|
25
|
+
b"lefthook.yaml", b".lefthook.yml", b".lefthook.yaml",
|
|
26
|
+
b"lefthook-local.yml"}
|
|
27
|
+
|
|
28
|
+
# install: code that runs when the project is installed or built as a dependency, or when
|
|
29
|
+
# Python starts.
|
|
30
|
+
INSTALL_NAMES = {b"setup.py", b"sitecustomize.py", b"usercustomize.py", b"binding.gyp",
|
|
31
|
+
b"build.rs"}
|
|
32
|
+
INSTALL_SUFFIXES = (b".pth",)
|
|
33
|
+
# npm runs these scripts on install, or when a package is installed from git.
|
|
34
|
+
NPM_LIFECYCLE = ("preinstall", "install", "postinstall", "prepare", "prepack", "postpack",
|
|
35
|
+
"prepublish")
|
|
36
|
+
|
|
37
|
+
# deps: dependency manifests and lockfiles.
|
|
38
|
+
DEPS_NAMES = {b"package.json", b"package-lock.json", b"npm-shrinkwrap.json", b"yarn.lock",
|
|
39
|
+
b"pnpm-lock.yaml", b"bun.lock", b"bun.lockb", b"Pipfile", b"Pipfile.lock",
|
|
40
|
+
b"poetry.lock", b"uv.lock", b"pdm.lock", b"pyproject.toml", b"setup.cfg",
|
|
41
|
+
b"constraints.txt", b"Cargo.toml", b"Cargo.lock", b"go.mod", b"go.sum",
|
|
42
|
+
b"Gemfile", b"Gemfile.lock", b"composer.json", b"composer.lock", b"pom.xml",
|
|
43
|
+
b"build.gradle", b"build.gradle.kts", b"gradle.lockfile",
|
|
44
|
+
b"packages.lock.json"}
|
|
45
|
+
DEPS_SUFFIXES = (b".gemspec",)
|
|
46
|
+
|
|
47
|
+
# exec: build and shell files that run commands.
|
|
48
|
+
EXEC_NAMES = {b"Makefile", b"makefile", b"GNUmakefile", b"Dockerfile", b"Containerfile",
|
|
49
|
+
b"justfile", b"Justfile", b".envrc", b"docker-compose.yml",
|
|
50
|
+
b"docker-compose.yaml", b"compose.yml", b"compose.yaml"}
|
|
51
|
+
EXEC_SUFFIXES = (b".sh", b".bash", b".zsh", b".ps1", b".bat", b".cmd", b".mk", b".dockerfile")
|
|
52
|
+
EXEC_MODE = b"100755"
|
|
53
|
+
|
|
54
|
+
# hidden: Markdown files get the HTML check; every text file gets the character check.
|
|
55
|
+
MARKDOWN_SUFFIXES = (b".md", b".markdown", b".mdx")
|
|
56
|
+
HTML = re.compile(rb"<!--|<\s*/?\s*(img|picture|source|svg|script|style|iframe|object|embed"
|
|
57
|
+
rb"|link|meta|base|form|input|details)(?![A-Za-z0-9-])", re.I)
|
|
58
|
+
|
|
59
|
+
# Invisible and bidirectional characters, as (first, last, label). A range is reported once
|
|
60
|
+
# under its label; a single character under its own code point.
|
|
61
|
+
HIDDEN_CHARS = (
|
|
62
|
+
(0x200B, 0x200F, None), # zero-width space, ZWNJ, ZWJ, LRM, RLM
|
|
63
|
+
(0x2060, 0x2064, None), # word joiner and invisible operators
|
|
64
|
+
(0xFEFF, 0xFEFF, None), # zero-width no-break space (BOM) after the start of a file
|
|
65
|
+
(0x061C, 0x061C, None), # Arabic letter mark
|
|
66
|
+
(0x202A, 0x202E, None), # bidi embeddings and overrides
|
|
67
|
+
(0x2066, 0x2069, None), # bidi isolates
|
|
68
|
+
(0xE0000, 0xE007F, "U+E0000..U+E007F"), # tag characters
|
|
69
|
+
(0xE0100, 0xE01EF, "U+E0100..U+E01EF"), # supplementary variation selectors
|
|
70
|
+
)
|
|
71
|
+
_HIDDEN_RE = re.compile("[%s]" % "".join(
|
|
72
|
+
"\\U%08x-\\U%08x" % (first, last) for first, last, _ in HIDDEN_CHARS))
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _basename(path):
|
|
76
|
+
"""Return the last component of a slash-separated path."""
|
|
77
|
+
return path.rsplit(b"/", 1)[-1]
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def path_classes(path):
|
|
81
|
+
"""Return the set of classes a changed path is in by its name alone.
|
|
82
|
+
|
|
83
|
+
Args:
|
|
84
|
+
path: The path relative to the repository root, bytes.
|
|
85
|
+
|
|
86
|
+
Returns:
|
|
87
|
+
A set drawn from "ci", "hook", "install", "deps", "exec".
|
|
88
|
+
"""
|
|
89
|
+
name = _basename(path)
|
|
90
|
+
lower = name.lower()
|
|
91
|
+
found = set()
|
|
92
|
+
if path.startswith(CI_PREFIXES) or path in CI_ROOT_FILES or name in CI_NAMES:
|
|
93
|
+
found.add("ci")
|
|
94
|
+
if path.startswith(HOOK_PREFIXES) or path in HOOK_ROOT_FILES:
|
|
95
|
+
found.add("hook")
|
|
96
|
+
if name in INSTALL_NAMES or lower.endswith(INSTALL_SUFFIXES):
|
|
97
|
+
found.add("install")
|
|
98
|
+
if (name in DEPS_NAMES or lower.endswith(DEPS_SUFFIXES)
|
|
99
|
+
or (lower.startswith(b"requirements") and lower.endswith(b".txt"))):
|
|
100
|
+
found.add("deps")
|
|
101
|
+
if (name in EXEC_NAMES or name.startswith(b"Dockerfile.")
|
|
102
|
+
or lower.endswith(EXEC_SUFFIXES)):
|
|
103
|
+
found.add("exec")
|
|
104
|
+
return found
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def became_executable(old_mode, new_mode):
|
|
108
|
+
"""Return True if a file's mode is executable now and was not before (or is new)."""
|
|
109
|
+
return new_mode == EXEC_MODE and old_mode != EXEC_MODE
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
def is_markdown(path):
|
|
113
|
+
"""Return True if the path names a Markdown file, by extension, case-insensitively."""
|
|
114
|
+
return path.lower().endswith(MARKDOWN_SUFFIXES)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
# --- Content rules ----------------------------------------------------------------------
|
|
118
|
+
|
|
119
|
+
def hidden_findings(path, added):
|
|
120
|
+
"""Return {kind: first line number} for hidden content on added lines.
|
|
121
|
+
|
|
122
|
+
Args:
|
|
123
|
+
path: The path, bytes; Markdown files also get the HTML check.
|
|
124
|
+
added: [(new line number, line bytes)] in line order.
|
|
125
|
+
|
|
126
|
+
Returns:
|
|
127
|
+
A dict from a kind ("<img", "<!--", "U+202E", or a range label) to the line number
|
|
128
|
+
of its first occurrence.
|
|
129
|
+
"""
|
|
130
|
+
found = {}
|
|
131
|
+
markdown = is_markdown(path)
|
|
132
|
+
for number, line in added:
|
|
133
|
+
if markdown:
|
|
134
|
+
for match in HTML.finditer(line):
|
|
135
|
+
tag = match.group(1)
|
|
136
|
+
kind = "<" + tag.decode("ascii").lower() if tag else "<!--"
|
|
137
|
+
found.setdefault(kind, number)
|
|
138
|
+
text = line.decode("utf-8", "replace")
|
|
139
|
+
for match in _HIDDEN_RE.finditer(text):
|
|
140
|
+
code = ord(match.group(0))
|
|
141
|
+
# A byte-order mark as the very first character of a file is ordinary.
|
|
142
|
+
if code == 0xFEFF and number == 1 and match.start() == 0:
|
|
143
|
+
continue
|
|
144
|
+
found.setdefault(_char_kind(code), number)
|
|
145
|
+
return found
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def _char_kind(code):
|
|
149
|
+
"""Return the report label for a hidden character: its code point or its range."""
|
|
150
|
+
for first, last, label in HIDDEN_CHARS:
|
|
151
|
+
if first <= code <= last and label:
|
|
152
|
+
return label
|
|
153
|
+
return "U+%04X" % code
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def build_system_touched(new_text, added_numbers):
|
|
157
|
+
"""Return True if an added line of pyproject.toml lies in its [build-system] table.
|
|
158
|
+
|
|
159
|
+
Tables are tracked line by line from their `[name]` headers; this is not a TOML parser.
|
|
160
|
+
|
|
161
|
+
Args:
|
|
162
|
+
new_text: The new file content, bytes.
|
|
163
|
+
added_numbers: The set of added line numbers.
|
|
164
|
+
"""
|
|
165
|
+
table = b""
|
|
166
|
+
for number, line in enumerate(new_text.split(b"\n"), 1):
|
|
167
|
+
header = re.match(rb"\s*\[\[?\s*([^\]\s]+)\s*\]", line)
|
|
168
|
+
if header:
|
|
169
|
+
table = header.group(1)
|
|
170
|
+
if number in added_numbers and (table == b"build-system"
|
|
171
|
+
or table.startswith(b"build-system.")):
|
|
172
|
+
return True
|
|
173
|
+
return False
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
# Names and versions printed in a detail field: printable, no spaces, so each stays one word.
|
|
177
|
+
# A name starts with a letter, digit or @, so "-name" (removed) cannot be misread; a version
|
|
178
|
+
# may not contain "->", which separates the old version from the new.
|
|
179
|
+
_SAFE_NAME = re.compile(r"\A[A-Za-z0-9@][A-Za-z0-9@/._~-]*\Z")
|
|
180
|
+
_SAFE_VERSION = re.compile(r"\A(?!.*->)[A-Za-z0-9@/._~^<>=*+:!-]+\Z")
|
|
181
|
+
# One == pin, optionally followed by an environment marker, a line continuation or options
|
|
182
|
+
# such as --hash.
|
|
183
|
+
_PIN = re.compile(r"\A==\s*([^\s,;=\\]+)\s*(?:[;\\].*|--.*)?\Z")
|
|
184
|
+
|
|
185
|
+
|
|
186
|
+
def dependency_changes(old, new):
|
|
187
|
+
"""Return the detail words for two {name: version or None} maps.
|
|
188
|
+
|
|
189
|
+
"+name" for each added name, "-name" for each removed one, then "name old->new" for each
|
|
190
|
+
name whose version changed while both versions are known. Each group is sorted. A name or
|
|
191
|
+
version with characters outside the safe sets is left out.
|
|
192
|
+
"""
|
|
193
|
+
names = sorted(name for name in set(old) | set(new) if _SAFE_NAME.match(name))
|
|
194
|
+
words = ["+" + name for name in names if name not in old]
|
|
195
|
+
words += ["-" + name for name in names if name not in new]
|
|
196
|
+
for name in names:
|
|
197
|
+
before, after = old.get(name), new.get(name)
|
|
198
|
+
if (name in old and name in new and before != after
|
|
199
|
+
and all(isinstance(v, str) and _SAFE_VERSION.match(v) for v in (before, after))):
|
|
200
|
+
words.append("%s %s->%s" % (name, before, after))
|
|
201
|
+
return words
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _load_json(text):
|
|
205
|
+
"""Return the JSON object in TEXT, {} for an absent file, or None if it is not one."""
|
|
206
|
+
if text is None:
|
|
207
|
+
return {}
|
|
208
|
+
try:
|
|
209
|
+
data = json.loads(text.decode("utf-8"))
|
|
210
|
+
except (ValueError, RecursionError):
|
|
211
|
+
return None
|
|
212
|
+
return data if isinstance(data, dict) else None
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def package_json_changes(old_text, new_text):
|
|
216
|
+
"""Compare two versions of a package.json.
|
|
217
|
+
|
|
218
|
+
Args:
|
|
219
|
+
old_text: The old content (bytes), or None if the file is new.
|
|
220
|
+
new_text: The new content (bytes), or None if the file was deleted.
|
|
221
|
+
|
|
222
|
+
Returns:
|
|
223
|
+
(dependency detail words, changed lifecycle script keys), both sorted lists; or
|
|
224
|
+
(None, None) if either side is not a JSON object.
|
|
225
|
+
"""
|
|
226
|
+
old, new = _load_json(old_text), _load_json(new_text)
|
|
227
|
+
if old is None or new is None:
|
|
228
|
+
return None, None
|
|
229
|
+
|
|
230
|
+
def deps(data):
|
|
231
|
+
# A name in several sections takes its version from the first section listing it.
|
|
232
|
+
found = {}
|
|
233
|
+
for key in ("dependencies", "devDependencies", "optionalDependencies",
|
|
234
|
+
"peerDependencies"):
|
|
235
|
+
section = data.get(key)
|
|
236
|
+
if isinstance(section, dict):
|
|
237
|
+
for name, version in section.items():
|
|
238
|
+
found.setdefault(name, version)
|
|
239
|
+
return found
|
|
240
|
+
|
|
241
|
+
def scripts(data):
|
|
242
|
+
section = data.get("scripts")
|
|
243
|
+
return section if isinstance(section, dict) else {}
|
|
244
|
+
|
|
245
|
+
old_scripts, new_scripts = scripts(old), scripts(new)
|
|
246
|
+
changed = [key for key in NPM_LIFECYCLE if old_scripts.get(key) != new_scripts.get(key)]
|
|
247
|
+
return dependency_changes(deps(old), deps(new)), sorted(changed)
|
|
248
|
+
|
|
249
|
+
|
|
250
|
+
def _requirements(text):
|
|
251
|
+
"""Return {normalised project name: == pin or None} for a requirements file.
|
|
252
|
+
|
|
253
|
+
The first line naming a project wins.
|
|
254
|
+
"""
|
|
255
|
+
found = {}
|
|
256
|
+
if text is None:
|
|
257
|
+
return found
|
|
258
|
+
for line in text.decode("utf-8", "replace").splitlines():
|
|
259
|
+
line = line.split("#", 1)[0].strip()
|
|
260
|
+
# Options (-r, -e, --hash, ...) and URLs are not names.
|
|
261
|
+
match = re.match(r"([A-Za-z0-9][A-Za-z0-9._-]*)\s*(\[[^\]]*\])?\s*", line)
|
|
262
|
+
if match and not line.startswith("-") and not re.match(r"[A-Za-z0-9+.-]+://", line):
|
|
263
|
+
# PEP 503 normalisation, so "Foo_Bar" and "foo-bar" are the same project.
|
|
264
|
+
name = re.sub(r"[-_.]+", "-", match.group(1)).lower()
|
|
265
|
+
pin = _PIN.match(line[match.end():])
|
|
266
|
+
found.setdefault(name, pin.group(1) if pin else None)
|
|
267
|
+
return found
|
|
268
|
+
|
|
269
|
+
|
|
270
|
+
def requirements_changes(old_text, new_text):
|
|
271
|
+
"""Return the dependency detail words for two versions of a requirements file.
|
|
272
|
+
|
|
273
|
+
A version change is reported only when both versions pin the project with one `==`.
|
|
274
|
+
"""
|
|
275
|
+
return dependency_changes(_requirements(old_text), _requirements(new_text))
|
git_surface/surface.py
ADDED
|
@@ -0,0 +1,257 @@
|
|
|
1
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
"""git surface BASE: report which refs change what runs or is trusted.
|
|
3
|
+
|
|
4
|
+
Reads refs on stdin (the first field of each record, so `git footprint BASE` output pipes
|
|
5
|
+
straight in), diffs each against its merge base with BASE, and writes
|
|
6
|
+
`ref TAB class TAB detail TAB path` records. It reports; it never blocks anything.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
import sys
|
|
11
|
+
|
|
12
|
+
from . import classify
|
|
13
|
+
from ._common import (EXIT_ERROR, EXIT_FOUND, EXIT_NOTHING, Fail, check_safe, error, git,
|
|
14
|
+
git_error, parse_args, read_records, resolve, run, show,
|
|
15
|
+
usage_and_version, write_record)
|
|
16
|
+
|
|
17
|
+
USAGE = """usage: git surface [-z] BASE < refs
|
|
18
|
+
|
|
19
|
+
For each ref on stdin (the first TAB-separated field of each record), report the changes
|
|
20
|
+
since its merge base with BASE that touch what runs or is trusted:
|
|
21
|
+
ref TAB class TAB detail TAB path
|
|
22
|
+
class: ci, deps, exec, hidden, hook or install
|
|
23
|
+
|
|
24
|
+
Exit status: 0 nothing reported, 1 something reported, 2 error. A ref that shares
|
|
25
|
+
no history with BASE is named on stderr and skipped; the others are still reported.
|
|
26
|
+
|
|
27
|
+
-z records end with NUL instead of LF, on input and output
|
|
28
|
+
-h show this help
|
|
29
|
+
--version show the version"""
|
|
30
|
+
|
|
31
|
+
# Flags shared by both diffs; each overrides a setting that could change what is compared.
|
|
32
|
+
_DIFF_PINS = ["--no-renames", "--no-ext-diff", "--no-textconv", "--no-relative",
|
|
33
|
+
"--ignore-submodules=none"]
|
|
34
|
+
|
|
35
|
+
_NULL_OID = re.compile(rb"\A0+\Z")
|
|
36
|
+
_HUNK = re.compile(rb"@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
|
|
37
|
+
_C_ESCAPES = {ord("a"): 7, ord("b"): 8, ord("t"): 9, ord("n"): 10, ord("v"): 11,
|
|
38
|
+
ord("f"): 12, ord("r"): 13, ord('"'): 34, ord("\\"): 92}
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def merge_base(base_sha, sha, ref):
|
|
42
|
+
"""Return the merge base of BASE and a ref, or None if the two share no history.
|
|
43
|
+
|
|
44
|
+
Raises:
|
|
45
|
+
Fail: git fails.
|
|
46
|
+
"""
|
|
47
|
+
code, out, err = git(["merge-base", base_sha, sha])
|
|
48
|
+
if code == 1 and not out.strip():
|
|
49
|
+
return None
|
|
50
|
+
if code != 0:
|
|
51
|
+
raise Fail("git merge-base failed for %s: %s" % (show(ref), git_error(err, code)))
|
|
52
|
+
return out.split(b"\n")[0].strip()
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def raw_changes(mb, sha):
|
|
56
|
+
"""Return [(old mode, new mode, old oid, new oid, status, path)] from `git diff --raw`.
|
|
57
|
+
|
|
58
|
+
Raises:
|
|
59
|
+
Fail: git fails or prints something that is not raw records.
|
|
60
|
+
"""
|
|
61
|
+
code, out, err = git(["diff", "--raw", "-z", "--no-abbrev"] + _DIFF_PINS + [mb, sha])
|
|
62
|
+
if code != 0:
|
|
63
|
+
raise Fail("git diff failed: %s" % git_error(err, code))
|
|
64
|
+
parts = out.split(b"\0")
|
|
65
|
+
if parts and parts[-1] == b"":
|
|
66
|
+
parts.pop()
|
|
67
|
+
if len(parts) % 2:
|
|
68
|
+
raise Fail("unexpected git diff output")
|
|
69
|
+
changes = []
|
|
70
|
+
for i in range(0, len(parts), 2):
|
|
71
|
+
# ":100644 100755 OLDOID NEWOID M", then the path as its own field.
|
|
72
|
+
fields = parts[i].lstrip(b":").split(b" ")
|
|
73
|
+
if len(fields) != 5:
|
|
74
|
+
raise Fail("unexpected git diff output")
|
|
75
|
+
changes.append(tuple(fields) + (parts[i + 1],))
|
|
76
|
+
return changes
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def _unquote(data, start):
|
|
80
|
+
"""Decode the C-quoted string at data[start] (a '"'); return (bytes, index after it)."""
|
|
81
|
+
out = bytearray()
|
|
82
|
+
i = start + 1
|
|
83
|
+
while i < len(data) and data[i] != 0x22:
|
|
84
|
+
byte = data[i]
|
|
85
|
+
if byte == 0x5C and i + 1 < len(data):
|
|
86
|
+
nxt = data[i + 1]
|
|
87
|
+
if 0x30 <= nxt <= 0x37:
|
|
88
|
+
out.append(int(data[i + 1:i + 4], 8))
|
|
89
|
+
i += 4
|
|
90
|
+
continue
|
|
91
|
+
out.append(_C_ESCAPES.get(nxt, nxt))
|
|
92
|
+
i += 2
|
|
93
|
+
continue
|
|
94
|
+
out.append(byte)
|
|
95
|
+
i += 1
|
|
96
|
+
return bytes(out), i + 1
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def _header_path(line):
|
|
100
|
+
"""Return the path named by a `diff --git a/P b/P` header (no renames: both P equal)."""
|
|
101
|
+
rest = line[len(b"diff --git "):]
|
|
102
|
+
if rest.startswith(b'"'):
|
|
103
|
+
path, _ = _unquote(rest, 0)
|
|
104
|
+
return path[2:]
|
|
105
|
+
# Unquoted: "a/P b/P", so P is half of what remains after the prefixes.
|
|
106
|
+
length = (len(rest) - len(b"a/ b/")) // 2
|
|
107
|
+
return rest[2:2 + length]
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def added_lines(mb, sha):
|
|
111
|
+
"""Return {path: [(new line number, line bytes)]} for every line the diff adds.
|
|
112
|
+
|
|
113
|
+
--text makes git show every file's lines whatever .gitattributes says, so marking a file
|
|
114
|
+
binary or -diff cannot hide its content. A typechange may give a path two sections;
|
|
115
|
+
their lines are combined.
|
|
116
|
+
|
|
117
|
+
Raises:
|
|
118
|
+
Fail: git fails.
|
|
119
|
+
"""
|
|
120
|
+
code, out, err = git(["diff", "-p", "-U0", "--text", "--no-color", "--submodule=short",
|
|
121
|
+
"--src-prefix=a/", "--dst-prefix=b/", "--diff-algorithm=myers",
|
|
122
|
+
"--indent-heuristic", "--inter-hunk-context=0"] + _DIFF_PINS + [mb, sha])
|
|
123
|
+
if code != 0:
|
|
124
|
+
raise Fail("git diff failed: %s" % git_error(err, code))
|
|
125
|
+
result = {}
|
|
126
|
+
lines = None
|
|
127
|
+
number = 0
|
|
128
|
+
in_hunk = False
|
|
129
|
+
for line in out.split(b"\n"):
|
|
130
|
+
if line.startswith(b"diff --git "):
|
|
131
|
+
lines = result.setdefault(_header_path(line), [])
|
|
132
|
+
in_hunk = False
|
|
133
|
+
continue
|
|
134
|
+
if lines is None:
|
|
135
|
+
continue
|
|
136
|
+
hunk = _HUNK.match(line)
|
|
137
|
+
if hunk:
|
|
138
|
+
number = int(hunk.group(1))
|
|
139
|
+
in_hunk = True
|
|
140
|
+
elif in_hunk and line.startswith(b"+"):
|
|
141
|
+
lines.append((number, line[1:]))
|
|
142
|
+
number += 1
|
|
143
|
+
return result
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
def blob(oid, mode):
|
|
147
|
+
"""Return a blob's content, or None for an absent file or a submodule (mode 160000)."""
|
|
148
|
+
if _NULL_OID.match(oid) or mode == b"160000":
|
|
149
|
+
return None
|
|
150
|
+
code, out, err = git(["cat-file", "blob", oid])
|
|
151
|
+
if code != 0:
|
|
152
|
+
raise Fail("git cat-file failed: %s" % git_error(err, code))
|
|
153
|
+
return out
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
def findings(mb, sha, zero):
|
|
157
|
+
"""Return the sorted (class, detail, path) findings for one ref.
|
|
158
|
+
|
|
159
|
+
Raises:
|
|
160
|
+
Fail: git fails, or a path cannot be written in LF mode.
|
|
161
|
+
"""
|
|
162
|
+
added = added_lines(mb, sha)
|
|
163
|
+
found = set()
|
|
164
|
+
for old_mode, new_mode, old_oid, new_oid, status, path in raw_changes(mb, sha):
|
|
165
|
+
check_safe(path, zero, "path")
|
|
166
|
+
status = status.decode("ascii", "replace")
|
|
167
|
+
classes = classify.path_classes(path)
|
|
168
|
+
name = path.rsplit(b"/", 1)[-1]
|
|
169
|
+
lines = added.get(path, [])
|
|
170
|
+
for cls in ("ci", "hook", "install"):
|
|
171
|
+
if cls in classes:
|
|
172
|
+
found.add((cls, status, path))
|
|
173
|
+
if "exec" in classes or classify.became_executable(old_mode, new_mode):
|
|
174
|
+
plus_x = " +x" if classify.became_executable(old_mode, new_mode) else ""
|
|
175
|
+
found.add(("exec", status + plus_x, path))
|
|
176
|
+
deps_detail = status
|
|
177
|
+
if name == b"package.json":
|
|
178
|
+
names, scripts = classify.package_json_changes(blob(old_oid, old_mode),
|
|
179
|
+
blob(new_oid, new_mode))
|
|
180
|
+
if names is None:
|
|
181
|
+
found.add(("install", status + " unparsed", path))
|
|
182
|
+
else:
|
|
183
|
+
deps_detail += "".join(" " + word for word in names)
|
|
184
|
+
if scripts:
|
|
185
|
+
found.add(("install", status + "".join(" scripts." + k for k in scripts),
|
|
186
|
+
path))
|
|
187
|
+
elif name.lower().startswith(b"requirements") and name.lower().endswith(b".txt"):
|
|
188
|
+
words = classify.requirements_changes(blob(old_oid, old_mode),
|
|
189
|
+
blob(new_oid, new_mode))
|
|
190
|
+
deps_detail += "".join(" " + word for word in words)
|
|
191
|
+
elif name == b"pyproject.toml" and lines:
|
|
192
|
+
numbers = set(n for n, _ in lines)
|
|
193
|
+
if classify.build_system_touched(blob(new_oid, new_mode) or b"", numbers):
|
|
194
|
+
found.add(("install", status + " [build-system]", path))
|
|
195
|
+
if "deps" in classes:
|
|
196
|
+
found.add(("deps", deps_detail, path))
|
|
197
|
+
# A NUL byte on an added line marks a binary file: no text checks on it.
|
|
198
|
+
if not any(b"\0" in text for _, text in lines):
|
|
199
|
+
for kind, number in classify.hidden_findings(path, lines).items():
|
|
200
|
+
found.add(("hidden", "%s line %d" % (kind, number), path))
|
|
201
|
+
return sorted(found, key=lambda f: (f[0], f[2], f[1].encode("ascii")))
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def surface(argv):
|
|
205
|
+
"""Run git surface; return the exit code.
|
|
206
|
+
|
|
207
|
+
Raises:
|
|
208
|
+
Fail: A usage error, an unknown BASE or ref, or an unsafe name.
|
|
209
|
+
"""
|
|
210
|
+
opts, positionals = parse_args(argv, ("-z", "-h", "--version"))
|
|
211
|
+
if usage_and_version(opts, USAGE):
|
|
212
|
+
return EXIT_NOTHING
|
|
213
|
+
if len(positionals) != 1:
|
|
214
|
+
raise Fail("expected exactly one BASE argument (see -h)")
|
|
215
|
+
zero = bool(opts.get("-z"))
|
|
216
|
+
base = positionals[0]
|
|
217
|
+
base_sha = resolve(base)
|
|
218
|
+
refs = []
|
|
219
|
+
seen = set()
|
|
220
|
+
for number, record in read_records(zero):
|
|
221
|
+
# The ref is the first field; the rest (a footprint's status and path) is ignored.
|
|
222
|
+
ref = record.split(b"\t", 1)[0]
|
|
223
|
+
if not ref:
|
|
224
|
+
raise Fail("record %d: empty ref" % number)
|
|
225
|
+
if ref in seen:
|
|
226
|
+
continue
|
|
227
|
+
seen.add(ref)
|
|
228
|
+
try:
|
|
229
|
+
check_safe(ref, zero, "ref")
|
|
230
|
+
refs.append((number, ref, resolve(ref)))
|
|
231
|
+
except Fail as exc:
|
|
232
|
+
raise Fail("record %d: %s" % (number, exc))
|
|
233
|
+
code = EXIT_NOTHING
|
|
234
|
+
skipped = False
|
|
235
|
+
for number, ref, sha in refs:
|
|
236
|
+
try:
|
|
237
|
+
mb = merge_base(base_sha, sha, ref)
|
|
238
|
+
if mb is None:
|
|
239
|
+
# Not fatal: name the ref, report the others, and exit 2 at the end.
|
|
240
|
+
error("%s: no merge base with %s" % (show(ref), show(base)))
|
|
241
|
+
skipped = True
|
|
242
|
+
continue
|
|
243
|
+
for cls, detail, path in findings(mb, sha, zero):
|
|
244
|
+
write_record((ref, cls.encode("ascii"), detail.encode("ascii"), path), zero)
|
|
245
|
+
code = EXIT_FOUND
|
|
246
|
+
except Fail as exc:
|
|
247
|
+
raise Fail("record %d: %s" % (number, exc))
|
|
248
|
+
return EXIT_ERROR if skipped else code
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def main():
|
|
252
|
+
"""Console-script entry point."""
|
|
253
|
+
run(lambda: surface(sys.argv[1:]))
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
if __name__ == "__main__":
|
|
257
|
+
main()
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: git-surface
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A git subcommand that reports which branches change what runs or is trusted.
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/jacob-adm/git-surface
|
|
7
|
+
Project-URL: Documentation, https://github.com/jacob-adm/git-surface/tree/main/docs
|
|
8
|
+
Project-URL: Source, https://github.com/jacob-adm/git-surface
|
|
9
|
+
Project-URL: Issues, https://github.com/jacob-adm/git-surface/issues
|
|
10
|
+
Keywords: git,pull-request,code-review,supply-chain,security,cli
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
17
|
+
Requires-Python: >=3.9
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Dynamic: license-file
|
|
21
|
+
|
|
22
|
+
# git-surface
|
|
23
|
+
|
|
24
|
+
git-surface is one git command, `git surface`. Installing it puts `git-surface` on your `PATH`;
|
|
25
|
+
git runs any `git-NAME` program on `PATH` as `git NAME`, so no configuration is needed.
|
|
26
|
+
|
|
27
|
+
When many branches arrive at once, many of them written by coding agents, a reviewer needs to
|
|
28
|
+
know which ones change something that runs or is trusted: a CI workflow, a git hook, an install
|
|
29
|
+
script, a dependency, a build file, or text that hides content from a human reader. Text in an
|
|
30
|
+
issue or pull request can steer an agent into exactly such a change, and malicious packages
|
|
31
|
+
spread through install scripts and new dependencies. `git surface` lists, for each branch, every
|
|
32
|
+
change of that kind, so those branches get a closer look.
|
|
33
|
+
|
|
34
|
+
It only reports. It does not block, score or rewrite anything; what to do with a report is up
|
|
35
|
+
to whoever runs it.
|
|
36
|
+
|
|
37
|
+
## Requirements
|
|
38
|
+
|
|
39
|
+
- Python 3.9 or later, standard library only.
|
|
40
|
+
- git 2.38 or later, as an executable named `git` on `PATH`.
|
|
41
|
+
|
|
42
|
+
## Install
|
|
43
|
+
|
|
44
|
+
From a clone:
|
|
45
|
+
|
|
46
|
+
```
|
|
47
|
+
git clone https://github.com/jacob-adm/git-surface
|
|
48
|
+
cd git-surface
|
|
49
|
+
pip install .
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
pip installs `git-surface` as a console script. Check the install:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
git surface --version
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
git-surface 0.1.0
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Use `-h` for usage: `git surface --help` is answered by git itself, which looks for a manual
|
|
63
|
+
page. Without installing, it also runs from a clone as `python3 -m git_surface`.
|
|
64
|
+
|
|
65
|
+
## How it works
|
|
66
|
+
|
|
67
|
+
1. **List the branches.** Pipe the branch names in, one per line. Only the first TAB-separated
|
|
68
|
+
field of each line is read, so the output of `git footprint BASE` (from git-overlap) pipes
|
|
69
|
+
straight in too.
|
|
70
|
+
2. **Diff each branch against BASE.** For each branch, `git surface BASE` compares the branch
|
|
71
|
+
with its merge base with BASE: the same changes a pull request's "files changed" shows.
|
|
72
|
+
Changes BASE made after the branch left it are not the branch's.
|
|
73
|
+
3. **Classify each changed path.** By its name, a path may be `ci`, `hook`, `install`, `deps` or
|
|
74
|
+
`exec`; a file that becomes executable is `exec` too. `package.json`, `pyproject.toml` and
|
|
75
|
+
`requirements*.txt` are read to name added and removed dependencies, version changes and
|
|
76
|
+
changed install steps.
|
|
77
|
+
4. **Check the added lines.** Only lines the branch adds are read. An HTML tag such as `<img>` or
|
|
78
|
+
`<script>`, or an HTML comment, on an added line of a Markdown file, or an invisible or
|
|
79
|
+
bidirectional Unicode character on an added line of any text file, is `hidden`.
|
|
80
|
+
5. **Read the report.** One line per finding, `ref TAB class TAB detail TAB path`. Like `grep`,
|
|
81
|
+
the command exits 1 when it reports something, 0 when it reports nothing and 2 on an error.
|
|
82
|
+
|
|
83
|
+
The full list of classes and rules is in [Classes](https://github.com/jacob-adm/git-surface/blob/main/docs/classes.md).
|
|
84
|
+
|
|
85
|
+
## Commands
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
git surface [-z] BASE < refs report what each ref changes that runs or is trusted
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
See [Commands](https://github.com/jacob-adm/git-surface/blob/main/docs/commands.md) for the input, output, options and exit status.
|
|
92
|
+
|
|
93
|
+
## Quick start
|
|
94
|
+
|
|
95
|
+
Inside the repository to check, list the branches one per line and pipe them in. Replace `main`
|
|
96
|
+
with the base branch and `refs/heads/agent/` with the refs to check, for example
|
|
97
|
+
`refs/remotes/origin/` for every branch fetched from `origin`.
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
git for-each-ref --format='%(refname:short)' refs/heads/agent/ | git surface main
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
agent/ci ci M .github/workflows/test.yml
|
|
105
|
+
agent/ci exec A +x scripts/release.sh
|
|
106
|
+
agent/deps deps M +left-pad package.json
|
|
107
|
+
agent/deps install M scripts.postinstall package.json
|
|
108
|
+
agent/docs hidden <!-- line 4 README.md
|
|
109
|
+
agent/docs hidden <img line 5 README.md
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`agent/ci` changes a workflow and adds an executable script. `agent/deps` adds the dependency
|
|
113
|
+
`left-pad` and a `postinstall` script. `agent/docs` adds an HTML comment and an image tag to the
|
|
114
|
+
README, neither of which shows when the Markdown is rendered. A fourth branch, `agent/fix`, only
|
|
115
|
+
changes application code, so it has no line.
|
|
116
|
+
|
|
117
|
+
## Documentation
|
|
118
|
+
|
|
119
|
+
- [Commands](https://github.com/jacob-adm/git-surface/blob/main/docs/commands.md): input, output, options, exit status and errors.
|
|
120
|
+
- [Classes](https://github.com/jacob-adm/git-surface/blob/main/docs/classes.md): every class, the paths and content each one covers, and the detail
|
|
121
|
+
field.
|
|
122
|
+
- [Limitations and security](https://github.com/jacob-adm/git-surface/blob/main/docs/limitations-and-security.md): what the command misses, and
|
|
123
|
+
what it reads and runs.
|
|
124
|
+
- [Using it with other tools](https://github.com/jacob-adm/git-surface/blob/main/docs/other-tools.md): tested stacks with
|
|
125
|
+
git-overlap, trust-path, pr-merge-audit and release-drift.
|
|
126
|
+
- [Contributing](https://github.com/jacob-adm/git-surface/blob/main/CONTRIBUTING.md): running the tests and contributing a change.
|
|
127
|
+
- [Reporting a vulnerability](https://github.com/jacob-adm/git-surface/blob/main/SECURITY.md)
|
|
128
|
+
|
|
129
|
+
## License
|
|
130
|
+
|
|
131
|
+
Apache License 2.0; see [LICENSE](https://github.com/jacob-adm/git-surface/blob/main/LICENSE).
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
git_surface/__init__.py,sha256=JMbRUDSSG2qXSIcsLEpBDb00trq60UzOsffn-ZKSl_0,134
|
|
2
|
+
git_surface/__main__.py,sha256=HoXZsOjqVmtMdwe4SNY_GpwgbpExRMIc1alDa0biyjU,124
|
|
3
|
+
git_surface/_common.py,sha256=6wR5hV_JccMI4Bd-cPkFwh1pa2PWhDLIJFKXIQ-qFeU,9640
|
|
4
|
+
git_surface/classify.py,sha256=TaSrUoO7LecgrVBwJRSIrPUr5PNWjJoE4DSeB5LBQLU,11732
|
|
5
|
+
git_surface/surface.py,sha256=fV4Ls3QSFC4MlxDZMXbfGUQpLt0B1BJvQXQWUejgeRY,9935
|
|
6
|
+
git_surface-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
|
|
7
|
+
git_surface-0.1.0.dist-info/METADATA,sha256=GQOXnpbiXXsFMQ9Xc_ScLcrPU6nOd0haT31zW2O5pZA,5875
|
|
8
|
+
git_surface-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
9
|
+
git_surface-0.1.0.dist-info/entry_points.txt,sha256=UbpAM1EbVqaeYxXdmbdanCiqWUiUNyaclHnktBWmYU4,57
|
|
10
|
+
git_surface-0.1.0.dist-info/top_level.txt,sha256=YwzVCaB6CT9tmfh3mwdMS1xUbxSHIDNF5pjYfEf1NGI,12
|
|
11
|
+
git_surface-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
git_surface
|