flagcheck 0.2.0a1__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.
- flagcheck/__init__.py +3 -0
- flagcheck/__main__.py +3 -0
- flagcheck/cli.py +108 -0
- flagcheck/scanner.py +447 -0
- flagcheck/schema.py +155 -0
- flagcheck-0.2.0a1.dist-info/METADATA +107 -0
- flagcheck-0.2.0a1.dist-info/RECORD +11 -0
- flagcheck-0.2.0a1.dist-info/WHEEL +5 -0
- flagcheck-0.2.0a1.dist-info/entry_points.txt +2 -0
- flagcheck-0.2.0a1.dist-info/licenses/LICENSE +21 -0
- flagcheck-0.2.0a1.dist-info/top_level.txt +1 -0
flagcheck/__init__.py
ADDED
flagcheck/__main__.py
ADDED
flagcheck/cli.py
ADDED
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import argparse
|
|
4
|
+
from dataclasses import asdict
|
|
5
|
+
import json
|
|
6
|
+
import sys
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
import yaml
|
|
10
|
+
|
|
11
|
+
from flagcheck import __version__
|
|
12
|
+
from flagcheck.schema import extract_argparse, load_schema
|
|
13
|
+
from flagcheck.scanner import ScanStats, file_kind, scan_command, scan_text
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def _targets(paths: list[Path]):
|
|
17
|
+
seen: set[Path] = set()
|
|
18
|
+
for root in paths:
|
|
19
|
+
if not root.exists():
|
|
20
|
+
raise OSError(f"missing input: {root}")
|
|
21
|
+
candidates = sorted(root.rglob("*")) if root.is_dir() else [root]
|
|
22
|
+
for path in candidates:
|
|
23
|
+
if not path.is_file() or path.is_symlink():
|
|
24
|
+
continue
|
|
25
|
+
# Respect explicit files and project roots named e.g. "build".
|
|
26
|
+
# Only ignore generated directories below a recursively scanned root.
|
|
27
|
+
if root.is_dir() and any(p in {".git", ".venv", "venv", "node_modules", "__pycache__", "build", "dist"} for p in path.relative_to(root).parts[:-1]):
|
|
28
|
+
continue
|
|
29
|
+
kind = file_kind(path)
|
|
30
|
+
if kind is None or path.resolve() in seen:
|
|
31
|
+
continue
|
|
32
|
+
seen.add(path.resolve())
|
|
33
|
+
yield path, kind
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def main(argv: list[str] | None = None) -> int:
|
|
37
|
+
parser = argparse.ArgumentParser(prog="flagcheck", allow_abbrev=False)
|
|
38
|
+
parser.add_argument("--version", action="version", version=__version__)
|
|
39
|
+
sub = parser.add_subparsers(dest="operation", required=True)
|
|
40
|
+
scan = sub.add_parser("scan", help="lint files using a reviewed JSON schema", allow_abbrev=False)
|
|
41
|
+
scan.add_argument("--schema", required=True, type=Path)
|
|
42
|
+
scan.add_argument("--format", choices=("text", "json"), default="text")
|
|
43
|
+
scan.add_argument("--fail-on", choices=("warning", "error"), default="warning")
|
|
44
|
+
scan.add_argument("--cmd", help="scan a single command instead of files")
|
|
45
|
+
scan.add_argument("--summary", action="store_true", help="emit partial scan coverage counters as JSON to stderr")
|
|
46
|
+
scan.add_argument("--require-match", action="store_true", help="return status 2 if no configured command was recognized")
|
|
47
|
+
scan.add_argument("paths", nargs="*", type=Path)
|
|
48
|
+
gen = sub.add_parser("schema-from-source", help="extract literal argparse declarations without executing Python", allow_abbrev=False)
|
|
49
|
+
gen.add_argument("source", type=Path)
|
|
50
|
+
gen.add_argument("--command", required=True)
|
|
51
|
+
gen.add_argument("--receiver", action="append", required=True, help="parser or argument-group variable; repeat as needed")
|
|
52
|
+
gen.add_argument("--complete", action="store_true", help="assert that the selected declarations form the entire parser")
|
|
53
|
+
gen.add_argument("--no-abbrev", action="store_true")
|
|
54
|
+
gen.add_argument("--implicit-help", action="store_true", help="confirm -h/--help for an indirect parser constructor")
|
|
55
|
+
gen.add_argument("--action-arity", action="append", default=[], metavar="NAME=N", help="reviewed custom argparse action's number of value tokens; repeat as needed")
|
|
56
|
+
args = parser.parse_args(argv)
|
|
57
|
+
try:
|
|
58
|
+
if args.operation == "schema-from-source":
|
|
59
|
+
overrides = {}
|
|
60
|
+
for entry in args.action_arity:
|
|
61
|
+
key, sep, number = entry.partition("=")
|
|
62
|
+
if not sep or not key or not number.isdecimal():
|
|
63
|
+
raise ValueError("--action-arity must have the form NAME=N (N >= 0)")
|
|
64
|
+
overrides[key] = int(number)
|
|
65
|
+
flags, notes = extract_argparse(args.source.read_text(encoding="utf-8"), set(args.receiver),
|
|
66
|
+
action_arities=overrides, implicit_help=args.implicit_help)
|
|
67
|
+
if not flags:
|
|
68
|
+
raise ValueError("no literal flags found on selected receiver(s)")
|
|
69
|
+
for note in notes:
|
|
70
|
+
print(f"flagcheck: {note}", file=sys.stderr)
|
|
71
|
+
if args.complete and notes:
|
|
72
|
+
raise ValueError("cannot mark extraction complete: unresolved declarations")
|
|
73
|
+
print(json.dumps({args.command: {"complete": args.complete, "allow_abbrev": not args.no_abbrev, "flags": flags}}, indent=2, sort_keys=True))
|
|
74
|
+
return 0
|
|
75
|
+
if args.cmd is not None and args.paths:
|
|
76
|
+
raise ValueError("choose --cmd or file paths, not both")
|
|
77
|
+
schemas = load_schema(args.schema)
|
|
78
|
+
stats = ScanStats()
|
|
79
|
+
files_scanned = 0
|
|
80
|
+
if args.cmd is not None:
|
|
81
|
+
findings = scan_command(args.cmd, schemas, stats=stats)
|
|
82
|
+
elif args.paths:
|
|
83
|
+
targets = list(_targets(args.paths))
|
|
84
|
+
if not targets:
|
|
85
|
+
raise ValueError("no supported input files found")
|
|
86
|
+
findings = []
|
|
87
|
+
for path, kind in targets:
|
|
88
|
+
findings.extend(scan_text(path.read_text(encoding="utf-8"), schemas, kind, str(path), stats=stats))
|
|
89
|
+
files_scanned += 1
|
|
90
|
+
else:
|
|
91
|
+
raise ValueError("provide --cmd or at least one path")
|
|
92
|
+
if args.summary:
|
|
93
|
+
print(json.dumps({"files_scanned": files_scanned, **asdict(stats)}, sort_keys=True), file=sys.stderr)
|
|
94
|
+
if args.require_match and not stats.matched_invocations:
|
|
95
|
+
raise ValueError("no configured command was recognized")
|
|
96
|
+
if args.format == "json":
|
|
97
|
+
print(json.dumps([f.to_dict() for f in findings], indent=2))
|
|
98
|
+
else:
|
|
99
|
+
for finding in findings:
|
|
100
|
+
print(f"{finding.source}:{finding.line}: {finding.severity} {finding.code}: {finding.command} {finding.flag}: {finding.message}")
|
|
101
|
+
return int(any(f.severity == "error" or args.fail_on == "warning" for f in findings))
|
|
102
|
+
except (OSError, ValueError, SyntaxError, yaml.YAMLError) as exc:
|
|
103
|
+
print(f"flagcheck: {exc}", file=sys.stderr)
|
|
104
|
+
return 2
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
if __name__ == "__main__":
|
|
108
|
+
raise SystemExit(main())
|
flagcheck/scanner.py
ADDED
|
@@ -0,0 +1,447 @@
|
|
|
1
|
+
"""Conservative shell scanning. Never executes a scanned command."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from dataclasses import asdict, dataclass
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
|
|
9
|
+
import yaml
|
|
10
|
+
from yaml.nodes import MappingNode, ScalarNode, SequenceNode
|
|
11
|
+
|
|
12
|
+
from flagcheck.schema import Command, Flag
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True)
|
|
16
|
+
class Finding:
|
|
17
|
+
source: str
|
|
18
|
+
line: int
|
|
19
|
+
command: str
|
|
20
|
+
flag: str
|
|
21
|
+
code: str
|
|
22
|
+
severity: str
|
|
23
|
+
message: str
|
|
24
|
+
suggestion: str | None = None
|
|
25
|
+
|
|
26
|
+
def to_dict(self) -> dict:
|
|
27
|
+
return asdict(self)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
@dataclass
|
|
31
|
+
class ScanStats:
|
|
32
|
+
"""Partial coverage counters; unsupported file contexts are not enumerated."""
|
|
33
|
+
logical_commands: int = 0
|
|
34
|
+
matched_invocations: int = 0
|
|
35
|
+
unmatched_segments: int = 0
|
|
36
|
+
checked_long_options: int = 0
|
|
37
|
+
lexer_failures: int = 0
|
|
38
|
+
incomplete_invocations: int = 0
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass(frozen=True)
|
|
42
|
+
class Token:
|
|
43
|
+
value: str
|
|
44
|
+
dynamic: bool = False
|
|
45
|
+
operator: bool = False
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
_ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
|
|
49
|
+
_NEGATIVE = re.compile(r"^-\d+(?:\.\d+)?$")
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
def _lex(text: str) -> list[Token] | None:
|
|
53
|
+
"""Recognize simple shell words, quoted words and control operators.
|
|
54
|
+
|
|
55
|
+
Variable expansions remain opaque; unsupported constructs are skipped.
|
|
56
|
+
"""
|
|
57
|
+
tokens: list[Token] = []
|
|
58
|
+
buf: list[str] = []
|
|
59
|
+
quote = ""
|
|
60
|
+
dynamic = started = False
|
|
61
|
+
i = 0
|
|
62
|
+
|
|
63
|
+
def flush() -> None:
|
|
64
|
+
nonlocal dynamic, started
|
|
65
|
+
if started:
|
|
66
|
+
tokens.append(Token("".join(buf), dynamic))
|
|
67
|
+
buf.clear()
|
|
68
|
+
dynamic = started = False
|
|
69
|
+
|
|
70
|
+
while i < len(text):
|
|
71
|
+
c = text[i]
|
|
72
|
+
if quote == "'":
|
|
73
|
+
if c == "'":
|
|
74
|
+
quote = ""
|
|
75
|
+
else:
|
|
76
|
+
buf.append(c)
|
|
77
|
+
i += 1
|
|
78
|
+
continue
|
|
79
|
+
if c == "\\" and i + 1 < len(text):
|
|
80
|
+
nxt = text[i + 1]
|
|
81
|
+
if not quote or nxt in '\\"$`\n':
|
|
82
|
+
if nxt != "\n":
|
|
83
|
+
buf.append(nxt)
|
|
84
|
+
started = True
|
|
85
|
+
i += 2
|
|
86
|
+
continue
|
|
87
|
+
if c == quote:
|
|
88
|
+
quote = ""
|
|
89
|
+
i += 1
|
|
90
|
+
continue
|
|
91
|
+
if not quote and c in "'\"":
|
|
92
|
+
quote = c
|
|
93
|
+
started = True
|
|
94
|
+
i += 1
|
|
95
|
+
continue
|
|
96
|
+
if c in "$`":
|
|
97
|
+
dynamic = True
|
|
98
|
+
# Keep $(...), ${...} and Make substitutions as a single opaque word.
|
|
99
|
+
if c == "$" and i + 1 < len(text) and text[i + 1] in "({":
|
|
100
|
+
opener = text[i + 1]
|
|
101
|
+
closer = ")" if opener == "(" else "}"
|
|
102
|
+
# This subset intentionally skips nested quotes/parentheses
|
|
103
|
+
# inside complex shell substitutions if they are unbalanced.
|
|
104
|
+
j = i + 2
|
|
105
|
+
depth = 1
|
|
106
|
+
while j < len(text) and depth:
|
|
107
|
+
if text[j] == opener:
|
|
108
|
+
depth += 1
|
|
109
|
+
elif text[j] == closer:
|
|
110
|
+
depth -= 1
|
|
111
|
+
j += 1
|
|
112
|
+
if depth:
|
|
113
|
+
return None
|
|
114
|
+
buf.append(text[i:j])
|
|
115
|
+
started = True
|
|
116
|
+
i = j
|
|
117
|
+
continue
|
|
118
|
+
if c == "`":
|
|
119
|
+
j = text.find("`", i + 1)
|
|
120
|
+
if j < 0:
|
|
121
|
+
return None
|
|
122
|
+
buf.append(text[i:j + 1])
|
|
123
|
+
started = True
|
|
124
|
+
i = j + 1
|
|
125
|
+
continue
|
|
126
|
+
if not quote:
|
|
127
|
+
if c.isspace():
|
|
128
|
+
flush()
|
|
129
|
+
i += 1
|
|
130
|
+
continue
|
|
131
|
+
if c == "#" and not started:
|
|
132
|
+
break
|
|
133
|
+
if c in ";&|<>()":
|
|
134
|
+
flush()
|
|
135
|
+
j = i + 1
|
|
136
|
+
if j < len(text) and text[i:j + 1] in {"&&", "||", ">>", "<<", "|&", ">&", "<&"}:
|
|
137
|
+
j += 1
|
|
138
|
+
tokens.append(Token(text[i:j], operator=True))
|
|
139
|
+
i = j
|
|
140
|
+
continue
|
|
141
|
+
if c in "*?[]~":
|
|
142
|
+
dynamic = True
|
|
143
|
+
started = True
|
|
144
|
+
buf.append(c)
|
|
145
|
+
i += 1
|
|
146
|
+
if quote:
|
|
147
|
+
return None
|
|
148
|
+
flush()
|
|
149
|
+
return tokens
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
def _segments(tokens: list[Token]):
|
|
153
|
+
current: list[Token] = []
|
|
154
|
+
redirected = False
|
|
155
|
+
for token in tokens:
|
|
156
|
+
if token.operator:
|
|
157
|
+
if token.value in {";", "&&", "||", "|", "|&", "&"}:
|
|
158
|
+
if current:
|
|
159
|
+
yield current
|
|
160
|
+
current = []
|
|
161
|
+
redirected = False
|
|
162
|
+
else:
|
|
163
|
+
# Do not guess operands after redirections or compound syntax.
|
|
164
|
+
redirected = True
|
|
165
|
+
elif not redirected:
|
|
166
|
+
current.append(token)
|
|
167
|
+
if current:
|
|
168
|
+
yield current
|
|
169
|
+
|
|
170
|
+
|
|
171
|
+
def _basename(value: str) -> str:
|
|
172
|
+
return value.rsplit("/", 1)[-1]
|
|
173
|
+
|
|
174
|
+
|
|
175
|
+
def _consume(args: list[Token], index: int, spec: Flag, attached: bool) -> int | None:
|
|
176
|
+
if spec.nargs == "?":
|
|
177
|
+
if attached or index + 1 >= len(args):
|
|
178
|
+
return index + 1
|
|
179
|
+
following = args[index + 1]
|
|
180
|
+
if following.dynamic:
|
|
181
|
+
return None
|
|
182
|
+
if following.value.startswith("-") and following.value != "-" and not _NEGATIVE.fullmatch(following.value):
|
|
183
|
+
return index + 1
|
|
184
|
+
return index + 2
|
|
185
|
+
if type(spec.nargs) is not int:
|
|
186
|
+
return None # variadic values cannot be inferred safely
|
|
187
|
+
remaining = max(0, spec.nargs - int(attached))
|
|
188
|
+
return index + remaining + 1
|
|
189
|
+
|
|
190
|
+
|
|
191
|
+
def _inspect(tokens: list[Token], schemas: dict[str, Command], source: str, line: int,
|
|
192
|
+
depth: int, stats: ScanStats | None = None) -> list[Finding]:
|
|
193
|
+
i = 0
|
|
194
|
+
while i < len(tokens) and (_ASSIGN.match(tokens[i].value) or tokens[i].value in {"env", "command", "exec", "time", "sudo", "do", "then", "else"}):
|
|
195
|
+
i += 1
|
|
196
|
+
if i >= len(tokens) or tokens[i].dynamic:
|
|
197
|
+
if stats is not None:
|
|
198
|
+
stats.unmatched_segments += 1
|
|
199
|
+
return []
|
|
200
|
+
command = _basename(tokens[i].value)
|
|
201
|
+
args = tokens[i + 1:]
|
|
202
|
+
# Narrow literal forms of commonly used project runners. Do not attempt to
|
|
203
|
+
# interpret arbitrary runner options or dynamically selected executables.
|
|
204
|
+
if depth < 4 and command in {"pipenv", "uv"} and len(args) >= 2 and args[0].value == "run" and not args[1].dynamic and not args[1].value.startswith("-"):
|
|
205
|
+
return _inspect(args[1:], schemas, source, line, depth + 1, stats)
|
|
206
|
+
if depth < 4 and command == "uvx" and args:
|
|
207
|
+
first = 2 if len(args) >= 3 and args[0].value == "--from" and not args[1].dynamic else 0
|
|
208
|
+
if not args[first].dynamic and not args[first].value.startswith("-"):
|
|
209
|
+
return _inspect(args[first:], schemas, source, line, depth + 1, stats)
|
|
210
|
+
if command in {"python", "python3"} and len(args) >= 2 and args[0].value == "-m" and not args[1].dynamic:
|
|
211
|
+
command = args[1].value
|
|
212
|
+
args = args[2:]
|
|
213
|
+
if command in {"bash", "sh"} and depth < 2 and len(args) >= 2 and re.fullmatch(r"-[a-zA-Z]*c[a-zA-Z]*", args[0].value):
|
|
214
|
+
return scan_command(args[1].value, schemas, source, line, depth + 1, stats=stats)
|
|
215
|
+
spec = schemas.get(command)
|
|
216
|
+
if spec is None:
|
|
217
|
+
if stats is not None:
|
|
218
|
+
stats.unmatched_segments += 1
|
|
219
|
+
return []
|
|
220
|
+
if stats is not None:
|
|
221
|
+
stats.matched_invocations += 1
|
|
222
|
+
incomplete = False
|
|
223
|
+
i = 0
|
|
224
|
+
results: list[Finding] = []
|
|
225
|
+
while i < len(args):
|
|
226
|
+
token = args[i]
|
|
227
|
+
word = token.value
|
|
228
|
+
if word == "--":
|
|
229
|
+
break
|
|
230
|
+
if word.startswith("--"):
|
|
231
|
+
flag, sep, value = word.partition("=")
|
|
232
|
+
if token.dynamic and (not sep or any(c in flag for c in "$`*?[]~")):
|
|
233
|
+
incomplete = True
|
|
234
|
+
break
|
|
235
|
+
known = spec.flags.get(flag)
|
|
236
|
+
if known is not None:
|
|
237
|
+
if stats is not None:
|
|
238
|
+
stats.checked_long_options += 1
|
|
239
|
+
if known.deprecated:
|
|
240
|
+
results.append(Finding(source, line, command, flag, "deprecated", "warning", f"{flag} is deprecated", known.replacement))
|
|
241
|
+
elif not spec.complete:
|
|
242
|
+
incomplete = True
|
|
243
|
+
break
|
|
244
|
+
else:
|
|
245
|
+
if stats is not None:
|
|
246
|
+
stats.checked_long_options += 1
|
|
247
|
+
matches = sorted(f for f in spec.flags if f.startswith(flag) and f.startswith("--"))
|
|
248
|
+
if len(matches) == 1 and spec.allow_abbrev:
|
|
249
|
+
canonical = matches[0]
|
|
250
|
+
known = spec.flags[canonical]
|
|
251
|
+
results.append(Finding(source, line, command, flag, "abbreviation", "warning", f"Use the full option {canonical}", canonical))
|
|
252
|
+
elif len(matches) > 1 and spec.allow_abbrev:
|
|
253
|
+
results.append(Finding(source, line, command, flag, "ambiguous", "error", "Matches " + ", ".join(matches)))
|
|
254
|
+
incomplete = i + 1 < len(args)
|
|
255
|
+
break
|
|
256
|
+
else:
|
|
257
|
+
results.append(Finding(source, line, command, flag, "unknown", "error", f"Unknown option {flag}", matches[0] if len(matches) == 1 else None))
|
|
258
|
+
incomplete = i + 1 < len(args)
|
|
259
|
+
break
|
|
260
|
+
nxt = _consume(args, i, known, bool(sep))
|
|
261
|
+
if nxt is None:
|
|
262
|
+
incomplete = True
|
|
263
|
+
break
|
|
264
|
+
i = nxt
|
|
265
|
+
continue
|
|
266
|
+
if token.dynamic:
|
|
267
|
+
incomplete = True
|
|
268
|
+
break
|
|
269
|
+
if word.startswith("-") and word != "-" and not _NEGATIVE.fullmatch(word):
|
|
270
|
+
# Only long options are linted. Known short options are consumed
|
|
271
|
+
# to avoid interpreting their values as options.
|
|
272
|
+
known = spec.flags.get(word)
|
|
273
|
+
if known is not None:
|
|
274
|
+
nxt = _consume(args, i, known, False)
|
|
275
|
+
if nxt is None:
|
|
276
|
+
incomplete = True
|
|
277
|
+
break
|
|
278
|
+
i = nxt
|
|
279
|
+
continue
|
|
280
|
+
# Argparse-style clusters: exact short spelling takes priority,
|
|
281
|
+
# otherwise consume known switches and any attached final value.
|
|
282
|
+
# We never diagnose an unrecognized short switch.
|
|
283
|
+
nxt = i + 1
|
|
284
|
+
for position, char in enumerate(word[1:], 1):
|
|
285
|
+
short = spec.flags.get("-" + char)
|
|
286
|
+
if short is None:
|
|
287
|
+
nxt = None
|
|
288
|
+
break
|
|
289
|
+
if short.nargs != 0:
|
|
290
|
+
nxt = _consume(args, i, short, position < len(word) - 1)
|
|
291
|
+
break
|
|
292
|
+
if nxt is not None:
|
|
293
|
+
i = nxt
|
|
294
|
+
continue
|
|
295
|
+
incomplete = True
|
|
296
|
+
break
|
|
297
|
+
if spec.subcommands:
|
|
298
|
+
child = spec.subcommands.get(word)
|
|
299
|
+
if child is None:
|
|
300
|
+
incomplete = True
|
|
301
|
+
break
|
|
302
|
+
spec = child
|
|
303
|
+
command += " " + word
|
|
304
|
+
i += 1
|
|
305
|
+
if stats is not None and incomplete:
|
|
306
|
+
stats.incomplete_invocations += 1
|
|
307
|
+
return results
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
def scan_command(text: str, schemas: dict[str, Command], source: str = "<command>",
|
|
311
|
+
line: int = 1, depth: int = 0, *, stats: ScanStats | None = None) -> list[Finding]:
|
|
312
|
+
tokens = _lex(text.strip())
|
|
313
|
+
if tokens is None:
|
|
314
|
+
if stats is not None:
|
|
315
|
+
stats.lexer_failures += 1
|
|
316
|
+
return []
|
|
317
|
+
if tokens and stats is not None:
|
|
318
|
+
stats.logical_commands += 1
|
|
319
|
+
results: list[Finding] = []
|
|
320
|
+
for segment in _segments(tokens):
|
|
321
|
+
results.extend(_inspect(segment, schemas, source, line, depth, stats))
|
|
322
|
+
return results
|
|
323
|
+
|
|
324
|
+
|
|
325
|
+
def _logical_lines(lines):
|
|
326
|
+
parts: list[str] = []
|
|
327
|
+
start = 0
|
|
328
|
+
heredocs: list[tuple[str, bool]] = []
|
|
329
|
+
for number, line in lines:
|
|
330
|
+
if heredocs:
|
|
331
|
+
delimiter, strip_tabs = heredocs[0]
|
|
332
|
+
if (line.lstrip("\t") if strip_tabs else line) == delimiter:
|
|
333
|
+
heredocs.pop(0)
|
|
334
|
+
continue
|
|
335
|
+
if not parts:
|
|
336
|
+
start = number
|
|
337
|
+
trailing = len(line) - len(line.rstrip("\\"))
|
|
338
|
+
if trailing % 2:
|
|
339
|
+
parts.append(line[:-1])
|
|
340
|
+
else:
|
|
341
|
+
parts.append(line)
|
|
342
|
+
logical = "".join(parts)
|
|
343
|
+
yield start, logical
|
|
344
|
+
tokens = _lex(logical) or []
|
|
345
|
+
for index, token in enumerate(tokens[:-1]):
|
|
346
|
+
if token.operator and token.value == "<<":
|
|
347
|
+
following = tokens[index + 1]
|
|
348
|
+
if following.operator:
|
|
349
|
+
continue
|
|
350
|
+
delimiter = following.value
|
|
351
|
+
strip_tabs = delimiter.startswith("-")
|
|
352
|
+
if strip_tabs:
|
|
353
|
+
delimiter = delimiter[1:]
|
|
354
|
+
heredocs.append((delimiter, strip_tabs))
|
|
355
|
+
parts = []
|
|
356
|
+
# An unfinished continuation is not a complete command.
|
|
357
|
+
|
|
358
|
+
|
|
359
|
+
def _make(text: str):
|
|
360
|
+
continuation = False
|
|
361
|
+
for number, line in enumerate(text.splitlines(), 1):
|
|
362
|
+
if not continuation and not line.startswith("\t"):
|
|
363
|
+
continue
|
|
364
|
+
body = line.removeprefix("\t")
|
|
365
|
+
if not continuation:
|
|
366
|
+
body = body.lstrip("@+-")
|
|
367
|
+
# GNU Make's single-dollar automatic variables denote target or
|
|
368
|
+
# prerequisite filenames. Do not rewrite escaped shell variables ($$).
|
|
369
|
+
body = re.sub(r"(?<!\$)\$[@<^+?*%|]", "__MAKE_PATH__", body)
|
|
370
|
+
yield number, body
|
|
371
|
+
continuation = (len(body) - len(body.rstrip("\\"))) % 2 == 1
|
|
372
|
+
|
|
373
|
+
|
|
374
|
+
def _markdown(text: str):
|
|
375
|
+
fence = None
|
|
376
|
+
language = ""
|
|
377
|
+
block: list[tuple[int, str]] = []
|
|
378
|
+
for number, line in enumerate(text.splitlines(), 1):
|
|
379
|
+
m = re.match(r"^\s*(`{3,}|~{3,})(.*)$", line)
|
|
380
|
+
if fence is None and m:
|
|
381
|
+
fence = m[1]
|
|
382
|
+
names = m[2].strip().lower().split()
|
|
383
|
+
language = names[0] if names else ""
|
|
384
|
+
block = []
|
|
385
|
+
elif fence and m and m[1][0] == fence[0] and len(m[1]) >= len(fence) and not m[2].strip():
|
|
386
|
+
if language in {"bash", "sh", "shell", "zsh", "console"}:
|
|
387
|
+
yield from _logical_lines(block)
|
|
388
|
+
fence = None
|
|
389
|
+
elif fence and (language in {"bash", "sh", "shell", "zsh"} or (language == "console" and re.match(r"^\s*\$ ", line))):
|
|
390
|
+
block.append((number, re.sub(r"^\s*\$ ", "", line)))
|
|
391
|
+
|
|
392
|
+
|
|
393
|
+
def _mapping(node, key):
|
|
394
|
+
if isinstance(node, MappingNode):
|
|
395
|
+
return next((v for k, v in node.value if isinstance(k, ScalarNode) and k.value == key), None)
|
|
396
|
+
return None
|
|
397
|
+
|
|
398
|
+
|
|
399
|
+
def _workflow(text: str):
|
|
400
|
+
root = yaml.compose(text, Loader=yaml.SafeLoader)
|
|
401
|
+
jobs = _mapping(root, "jobs")
|
|
402
|
+
if not isinstance(jobs, MappingNode):
|
|
403
|
+
return
|
|
404
|
+
for _, job in jobs.value:
|
|
405
|
+
steps = _mapping(job, "steps")
|
|
406
|
+
if not isinstance(steps, SequenceNode):
|
|
407
|
+
continue
|
|
408
|
+
for step in steps.value:
|
|
409
|
+
run = _mapping(step, "run")
|
|
410
|
+
shell = (_mapping(step, "shell") or _mapping(_mapping(job, "defaults"), "run")
|
|
411
|
+
or _mapping(_mapping(root, "defaults"), "run"))
|
|
412
|
+
if isinstance(shell, MappingNode):
|
|
413
|
+
shell = _mapping(shell, "shell")
|
|
414
|
+
if isinstance(shell, ScalarNode) and shell.value not in {"bash", "sh"}:
|
|
415
|
+
continue
|
|
416
|
+
if shell is None:
|
|
417
|
+
runner = _mapping(job, "runs-on")
|
|
418
|
+
if not isinstance(runner, ScalarNode) or not runner.value.startswith(("ubuntu-", "macos-")):
|
|
419
|
+
continue # default shell depends on the operating system
|
|
420
|
+
if not isinstance(run, ScalarNode) or run.style == ">":
|
|
421
|
+
continue # folded source mapping is intentionally unsupported
|
|
422
|
+
start = run.start_mark.line + (2 if run.style == "|" else 1)
|
|
423
|
+
yield from _logical_lines(enumerate(run.value.splitlines(), start))
|
|
424
|
+
|
|
425
|
+
|
|
426
|
+
def scan_text(text: str, schemas: dict[str, Command], kind: str = "shell", source: str = "<stdin>", *, stats: ScanStats | None = None) -> list[Finding]:
|
|
427
|
+
if kind == "make":
|
|
428
|
+
commands = _logical_lines(_make(text))
|
|
429
|
+
elif kind == "markdown":
|
|
430
|
+
commands = _markdown(text)
|
|
431
|
+
elif kind == "workflow":
|
|
432
|
+
commands = _workflow(text)
|
|
433
|
+
else:
|
|
434
|
+
commands = _logical_lines(enumerate(text.splitlines(), 1))
|
|
435
|
+
return [f for number, command in commands for f in scan_command(command, schemas, source, number, stats=stats)]
|
|
436
|
+
|
|
437
|
+
|
|
438
|
+
def file_kind(path: Path) -> str | None:
|
|
439
|
+
if path.name.lower() in {"makefile", "gnumakefile"} or path.suffix == ".mk":
|
|
440
|
+
return "make"
|
|
441
|
+
if path.suffix.lower() in {".md", ".markdown"}:
|
|
442
|
+
return "markdown"
|
|
443
|
+
if path.suffix.lower() in {".sh", ".bash", ".zsh"}:
|
|
444
|
+
return "shell"
|
|
445
|
+
if path.suffix.lower() in {".yml", ".yaml"} and ".github" in path.parts and "workflows" in path.parts:
|
|
446
|
+
return "workflow"
|
|
447
|
+
return None
|
flagcheck/schema.py
ADDED
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
"""Explicit command schemas and non-executing argparse source extraction."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import ast
|
|
6
|
+
import json
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclass(frozen=True)
|
|
12
|
+
class Flag:
|
|
13
|
+
nargs: int | str = 0
|
|
14
|
+
deprecated: bool = False
|
|
15
|
+
replacement: str | None = None
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(frozen=True)
|
|
19
|
+
class Command:
|
|
20
|
+
flags: dict[str, Flag] = field(default_factory=dict)
|
|
21
|
+
subcommands: dict[str, Command] = field(default_factory=dict)
|
|
22
|
+
complete: bool = False
|
|
23
|
+
allow_abbrev: bool = True
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _command(raw: object) -> Command:
|
|
27
|
+
if not isinstance(raw, dict):
|
|
28
|
+
raise ValueError("command must be an object")
|
|
29
|
+
if set(raw) - {"flags", "subcommands", "complete", "allow_abbrev"}:
|
|
30
|
+
raise ValueError("unrecognized command schema keys")
|
|
31
|
+
flags = raw.get("flags", {})
|
|
32
|
+
children = raw.get("subcommands", {})
|
|
33
|
+
if not isinstance(flags, dict) or not isinstance(children, dict):
|
|
34
|
+
raise ValueError("flags and subcommands must be objects")
|
|
35
|
+
for k in ("complete", "allow_abbrev"):
|
|
36
|
+
if k in raw and type(raw[k]) is not bool:
|
|
37
|
+
raise ValueError(f"{k} must be a boolean")
|
|
38
|
+
result = {}
|
|
39
|
+
for name, value in flags.items():
|
|
40
|
+
if not isinstance(name, str) or not name.startswith("-") or name in {"-", "--"}:
|
|
41
|
+
raise ValueError(f"invalid option name: {name!r}")
|
|
42
|
+
if not isinstance(value, dict) or set(value) - {"nargs", "deprecated", "replacement"}:
|
|
43
|
+
raise ValueError(f"invalid flag metadata for {name}")
|
|
44
|
+
n = value.get("nargs", 0)
|
|
45
|
+
if not ((type(n) is int and n >= 0) or n in ("?", "*", "+", "...")):
|
|
46
|
+
raise ValueError(f"invalid nargs for {name}")
|
|
47
|
+
deprecated = value.get("deprecated", False)
|
|
48
|
+
replacement = value.get("replacement")
|
|
49
|
+
if type(deprecated) is not bool or (replacement is not None and not isinstance(replacement, str)):
|
|
50
|
+
raise ValueError(f"invalid deprecation metadata for {name}")
|
|
51
|
+
result[name] = Flag(n, deprecated, replacement)
|
|
52
|
+
return Command(result, {name: _command(value) for name, value in children.items()},
|
|
53
|
+
raw.get("complete", False), raw.get("allow_abbrev", True))
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def load_schema(path: Path) -> dict[str, Command]:
|
|
57
|
+
raw = json.loads(path.read_text(encoding="utf-8"))
|
|
58
|
+
if not isinstance(raw, dict) or not raw:
|
|
59
|
+
raise ValueError("schema must be a non-empty command-name mapping")
|
|
60
|
+
return {name: _command(spec) for name, spec in raw.items()}
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _literal(node: ast.AST, default: object = None) -> object:
|
|
64
|
+
try:
|
|
65
|
+
return ast.literal_eval(node)
|
|
66
|
+
except (ValueError, TypeError):
|
|
67
|
+
return default
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
def extract_argparse(source: str, receivers: set[str], *,
|
|
71
|
+
action_arities: dict[str, int] | None = None,
|
|
72
|
+
implicit_help: bool = False) -> tuple[dict, list[str]]:
|
|
73
|
+
"""Extract literal add_argument calls on explicitly selected receivers.
|
|
74
|
+
|
|
75
|
+
Does not import or execute source. Dynamic declarations are reported as
|
|
76
|
+
limitations; mutually exclusive runtime branches are a union.
|
|
77
|
+
"""
|
|
78
|
+
tree = ast.parse(source)
|
|
79
|
+
overrides = action_arities or {}
|
|
80
|
+
if any(type(n) is not int or n < 0 for n in overrides.values()):
|
|
81
|
+
raise ValueError("custom action arities must be nonnegative integers")
|
|
82
|
+
flags: dict[str, dict] = {}
|
|
83
|
+
notes: list[str] = []
|
|
84
|
+
no_value = {"store_true", "store_false", "store_const", "append_const", "count", "help", "version"}
|
|
85
|
+
# Direct constructor calls are the only case where we infer implicit help.
|
|
86
|
+
# Indirect factories and wrappers require explicit reviewer confirmation.
|
|
87
|
+
for node in ast.walk(tree):
|
|
88
|
+
if not isinstance(node, (ast.Assign, ast.AnnAssign)):
|
|
89
|
+
continue
|
|
90
|
+
targets = node.targets if isinstance(node, ast.Assign) else [node.target]
|
|
91
|
+
if not any(isinstance(t, ast.Name) and t.id in receivers for t in targets):
|
|
92
|
+
continue
|
|
93
|
+
call = node.value
|
|
94
|
+
if not isinstance(call, ast.Call) or not isinstance(call.func, ast.Attribute):
|
|
95
|
+
continue
|
|
96
|
+
if not (isinstance(call.func.value, ast.Name) and call.func.value.id == "argparse"
|
|
97
|
+
and call.func.attr == "ArgumentParser"):
|
|
98
|
+
continue
|
|
99
|
+
kw = {k.arg: _literal(k.value, "<dynamic>") for k in call.keywords}
|
|
100
|
+
if None in kw:
|
|
101
|
+
notes.append(f"line {node.lineno}: dynamic parser configuration")
|
|
102
|
+
continue
|
|
103
|
+
if kw.get("parents") not in (None, [], ()):
|
|
104
|
+
notes.append(f"line {node.lineno}: inherited parent parser options require review")
|
|
105
|
+
help_enabled = kw.get("add_help", True)
|
|
106
|
+
prefix = kw.get("prefix_chars", "-")
|
|
107
|
+
if help_enabled is True and isinstance(prefix, str) and "-" in prefix:
|
|
108
|
+
implicit_help = True
|
|
109
|
+
elif help_enabled not in (True, False) or prefix == "<dynamic>":
|
|
110
|
+
notes.append(f"line {node.lineno}: unresolved automatic help configuration")
|
|
111
|
+
|
|
112
|
+
if implicit_help:
|
|
113
|
+
flags.update({"-h": {"nargs": 0}, "--help": {"nargs": 0}})
|
|
114
|
+
|
|
115
|
+
for node in ast.walk(tree):
|
|
116
|
+
if not isinstance(node, ast.Call) or not isinstance(node.func, ast.Attribute):
|
|
117
|
+
continue
|
|
118
|
+
if node.func.attr != "add_argument" or not isinstance(node.func.value, ast.Name):
|
|
119
|
+
continue
|
|
120
|
+
if node.func.value.id not in receivers:
|
|
121
|
+
continue
|
|
122
|
+
names = [_literal(x) for x in node.args]
|
|
123
|
+
if not names or not all(isinstance(x, str) for x in names):
|
|
124
|
+
notes.append(f"line {node.lineno}: non-literal option declaration")
|
|
125
|
+
continue
|
|
126
|
+
if not names[0].startswith("-"):
|
|
127
|
+
continue
|
|
128
|
+
if any(kw.arg is None for kw in node.keywords):
|
|
129
|
+
notes.append(f"line {node.lineno}: dynamic keyword arguments")
|
|
130
|
+
continue
|
|
131
|
+
keywords = {kw.arg: _literal(kw.value, "<dynamic>") for kw in node.keywords}
|
|
132
|
+
action = keywords.get("action", "store")
|
|
133
|
+
action_node = next((kw.value for kw in node.keywords if kw.arg == "action"), None)
|
|
134
|
+
if action == "<dynamic>" and isinstance(action_node, (ast.Name, ast.Attribute)):
|
|
135
|
+
action = ast.unparse(action_node)
|
|
136
|
+
if isinstance(action, str) and action in no_value:
|
|
137
|
+
nargs = 0
|
|
138
|
+
elif isinstance(action, str) and action in {"store", "append", "extend"}:
|
|
139
|
+
nargs = keywords.get("nargs", 1)
|
|
140
|
+
elif isinstance(action, str) and action in overrides:
|
|
141
|
+
nargs = overrides[action]
|
|
142
|
+
else:
|
|
143
|
+
notes.append(f"line {node.lineno}: unsupported action {action!r}")
|
|
144
|
+
continue
|
|
145
|
+
if not ((type(nargs) is int and nargs >= 0) or nargs in ("?", "*", "+")):
|
|
146
|
+
notes.append(f"line {node.lineno}: unsupported nargs {nargs!r}")
|
|
147
|
+
continue
|
|
148
|
+
meta = {"nargs": nargs}
|
|
149
|
+
if keywords.get("deprecated") is True:
|
|
150
|
+
meta["deprecated"] = True
|
|
151
|
+
for name in names:
|
|
152
|
+
if name in flags and flags[name] != meta:
|
|
153
|
+
notes.append(f"line {node.lineno}: conflicting declarations for {name}")
|
|
154
|
+
flags[name] = meta
|
|
155
|
+
return flags, notes
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flagcheck
|
|
3
|
+
Version: 0.2.0a1
|
|
4
|
+
Summary: Conservative, schema-driven command-line flag linter
|
|
5
|
+
Author: Parth Agrawal
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Repository, https://github.com/aparth9100/flagcheck
|
|
8
|
+
Project-URL: Issues, https://github.com/aparth9100/flagcheck/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/aparth9100/flagcheck/blob/main/CHANGELOG.md
|
|
10
|
+
Keywords: argparse,cli,lint,makefile,pre-commit
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
License-File: LICENSE
|
|
23
|
+
Requires-Dist: PyYAML>=6
|
|
24
|
+
Dynamic: license-file
|
|
25
|
+
|
|
26
|
+
# Flagcheck — CLI option drift linter
|
|
27
|
+
|
|
28
|
+
**0.2.0a1 — experimental alpha.**
|
|
29
|
+
|
|
30
|
+
Flagcheck detects brittle long-option abbreviations, unknown long options, and explicitly marked deprecated options in static shell commands. It checks against a schema you review, not against a guessed universal list of CLI flags.
|
|
31
|
+
|
|
32
|
+
It is intended for maintainers who control a CLI and want their own Makefile, CI and documentation examples to use stable option names. The scanner never runs a scanned command, imports a target package or makes network requests.
|
|
33
|
+
|
|
34
|
+
## Quick start
|
|
35
|
+
|
|
36
|
+
Python 3.10+ and PyYAML are required. Install from this source directory:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
python -m pip install .
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
After the alpha is available on PyPI, the equivalent registry installation is `python -m pip install --pre flagcheck`.
|
|
43
|
+
|
|
44
|
+
Use the included example schema:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
flagcheck scan --schema examples/schema.json --cmd 'mytool --verb --output result.txt'
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Expected output: a warning suggesting `--verbose`. The command exits with code 1 because the default threshold includes warnings.
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
flagcheck scan --schema examples/schema.json --format json --summary --require-match examples/sample.sh
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Exit codes: 0 = no finding at the selected severity; 1 = finding; 2 = input/configuration error. `--fail-on error` permits warnings without failing CI. An exit code of 0 is **not** proof that all commands are valid.
|
|
57
|
+
|
|
58
|
+
`--summary` writes JSON counters to stderr, keeping findings-only JSON on stdout intact. It reports supported logical commands, recognized invocations, checked long options, lexical failures, unmatched segments and invocations whose scanning stopped early. It is partial coverage, not a measure of all unsupported syntax. `--require-match` returns status 2 when no configured command was recognized; use it on a specific file or path expected to invoke your CLI.
|
|
59
|
+
|
|
60
|
+
## Generate a schema from source
|
|
61
|
+
|
|
62
|
+
```sh
|
|
63
|
+
flagcheck schema-from-source examples/cli_example.py --command mytool --receiver parser --complete
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The command emits JSON to stdout. Save it into a schema file after inspecting it. Repeat `--receiver` for explicitly identified argument groups. The AST extractor recognizes literal `add_argument` declarations, aliases, common actions, value counts and literal deprecation metadata. It never imports the Python file. It recognizes default `-h`/`--help` in a direct `argparse.ArgumentParser` constructor unless disabled; use `--implicit-help` only after verifying an indirect constructor. For a custom action whose arity you have reviewed, specify, for example, `--action-arity NegativeCountAction=0`. For parsers with abbreviation disabled, pass `--no-abbrev`. It cannot infer dynamically constructed arguments, inherited parsers, plugin options or arbitrary runtime behavior. It combines conditional declarations. Only use `--complete` when you have independently verified the parser's complete option inventory; omissions could cause incorrect reports.
|
|
67
|
+
|
|
68
|
+
An example schema:
|
|
69
|
+
|
|
70
|
+
```json
|
|
71
|
+
{
|
|
72
|
+
"mytool": {
|
|
73
|
+
"complete": true,
|
|
74
|
+
"allow_abbrev": true,
|
|
75
|
+
"flags": {
|
|
76
|
+
"--verbose": {"nargs": 0},
|
|
77
|
+
"--output": {"nargs": 1},
|
|
78
|
+
"--legacy": {"nargs": 0, "deprecated": true, "replacement": "--verbose"}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Each command can also specify `subcommands`, a mapping of subcommand names to command-schema objects. A subcommand has its own options, with no implicit inheritance. `complete` defaults to false: incomplete schemas only report explicitly known deprecated flags and stop at unrecognized options. `allow_abbrev` controls whether a unique prefix is a warning or an invalid-option error. `nargs` supports nonnegative integer counts and `?`, `*`, `+`, `...`; optional values are consumed when statically recognizable, and the scanner stops after variadic options rather than guessing their extent.
|
|
85
|
+
|
|
86
|
+
## Supported input
|
|
87
|
+
|
|
88
|
+
- Shell scripts (`.sh`, `.bash`, `.zsh`): simple literal command lines, common wrappers, chains, pipelines and backslash continuations. Limited literal `pipenv run`, `uv run` and `uvx [--from PACKAGE] COMMAND` forms are recognized.
|
|
89
|
+
- Makefiles and `.mk`: tab-prefixed recipes, simple loops, continued lines, literal `bash -c`/`-cx` wrappers, automatic filename variables.
|
|
90
|
+
- GitHub Actions workflows: `jobs.*.steps.*.run` scalar values for explicit `bash`/`sh` or default Ubuntu/macOS runners; literal multiline blocks.
|
|
91
|
+
- Markdown: explicitly shell-tagged fenced snippets; console fences with `$ ` prompts.
|
|
92
|
+
|
|
93
|
+
The scanner intentionally skips unsupported formats, unrecognized commands and ambiguous dynamic arguments. It is not a shell parser, a CLI semantic validator, or a substitute for actual CI. It consumes recognized argparse-style short-option clusters and attached values to avoid false long-option matches, but does not lint short option spellings. It does not support custom Make recipe prefixes, arbitrary Make `$(shell ...)` expansions, folded YAML blocks, PowerShell, fish, shell functions, aliases, dynamically constructed commands or all possible nested shell syntax. A finding's line refers to the beginning of the logical command; it can be the first line of a continuation. Treat results as review prompts, not automatic edits.
|
|
94
|
+
|
|
95
|
+
## Testing
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
python -m unittest discover -s tests -v
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
The test suite uses the standard library `unittest`. The included CI workflow targets Python 3.10–3.13 but has not been run on GitHub. The pre-commit hook is configured but is not publicly installable yet. When a repository and release tag exist, configure the hook with `args: [--schema, path/to/schema.json]`. For now you can invoke the CLI directly or use a local pre-commit hook passing that schema.
|
|
102
|
+
|
|
103
|
+
## Evidence and next milestone
|
|
104
|
+
|
|
105
|
+
See `VALIDATION.md` for the original xml2rfc benchmark and `PHASE2_VALIDATION.md` for validation against PyPA Build, pip-audit and Microsoft MarkItDown. The Phase 2 measurements cover reviewed literal option inventories, original files, deliberate mutations and a Python argparse option-resolution oracle. They are not a general-accuracy claim or independent external adoption evidence. The next milestone is review of a release candidate, check for existing similar tools and distribution-name availability, and decide whether to release. The distribution name is provisional; registry availability is not verified.
|
|
106
|
+
|
|
107
|
+
MIT licensed; source, docs and tests prepared with AI assistance for human review. No publication or external adoption is claimed.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
flagcheck/__init__.py,sha256=tAhX8DkUHgwl3A5STvxI1ZnjH7Migp3ro5ZeyRsKlRI,92
|
|
2
|
+
flagcheck/__main__.py,sha256=lIr50dDFKGVywaDTCTuFeSR0rs7l0mDAfDdr98GdroY,57
|
|
3
|
+
flagcheck/cli.py,sha256=XFsZaAGvl_-SojV4bxWPK2ruaNf9as2nr9OnkG79xvc,5773
|
|
4
|
+
flagcheck/scanner.py,sha256=RCH5ejmf_EKOsylglEFAqu-StaZJns5yPM5qz1zzZgg,16596
|
|
5
|
+
flagcheck/schema.py,sha256=ir5w5BtLGWtjEJQfw5ZtV_l_bn6BuWle091XIr9VPsQ,7101
|
|
6
|
+
flagcheck-0.2.0a1.dist-info/licenses/LICENSE,sha256=BLlMa6K4lwDOqAgLig8dQO7u-Mp6sYgz26Uz5q2SdYo,1140
|
|
7
|
+
flagcheck-0.2.0a1.dist-info/METADATA,sha256=UMuApoKbIpmvzrHExjOu42f8ffB5Z7bOVVQpS2Cr1FE,7428
|
|
8
|
+
flagcheck-0.2.0a1.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
|
|
9
|
+
flagcheck-0.2.0a1.dist-info/entry_points.txt,sha256=uSrnSjgZYLOhX9_s_MxBHpI7UghbMBbr-MvRBFSsSgk,49
|
|
10
|
+
flagcheck-0.2.0a1.dist-info/top_level.txt,sha256=cJ61OwRn3rlOK2qE4qN5JAmRb2bIyClzbCynIq7JcAs,10
|
|
11
|
+
flagcheck-0.2.0a1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Parth Agrawal (aparth9100)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND MERCHANTABILITY AND FITNESS FOR A
|
|
18
|
+
PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
19
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
20
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
21
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
flagcheck
|