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.
@@ -0,0 +1,4 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """git surface: report which branches change what runs or is trusted."""
3
+
4
+ __version__ = "0.1.0"
@@ -0,0 +1,6 @@
1
+ # SPDX-License-Identifier: Apache-2.0
2
+ """Run git surface as `python3 -m git_surface`."""
3
+
4
+ from .surface import main
5
+
6
+ main()
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)
@@ -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,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.2.1)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ git-surface = git_surface.surface:main
@@ -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