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 ADDED
@@ -0,0 +1,3 @@
1
+ """Flagcheck: static CLI flag linting against explicit schemas."""
2
+
3
+ __version__ = "0.2.0a1"
flagcheck/__main__.py ADDED
@@ -0,0 +1,3 @@
1
+ from flagcheck.cli import main
2
+
3
+ raise SystemExit(main())
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,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
+ flagcheck = flagcheck.cli:main
@@ -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