cobalto 0.8.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.
cobalto/__init__.py ADDED
@@ -0,0 +1,3 @@
1
+ """Cobalto (CBLT) - portable unit testing for COBOL."""
2
+
3
+ __version__ = "0.8.0"
cobalto/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """python -m cobalto: the same as the cobalto command."""
2
+ import sys
3
+
4
+ from .cli import main
5
+
6
+ sys.exit(main())
cobalto/build.py ADDED
@@ -0,0 +1,164 @@
1
+ """Discovery of the suites and generation of the test programs and the driver."""
2
+ import glob
3
+ import os
4
+ import re
5
+
6
+ from . import coverage as covmod
7
+ from . import inprog
8
+ from .config import copy_dirs_of
9
+ from .driver import driver_source
10
+ from .dsl import DslError, gen_suite, parse_dsl
11
+ from .messages import CobaltoError, warn
12
+ from .model import Generated, SuiteRef
13
+
14
+ PROGRAM_ID = re.compile(r"^\s{6}[\s-]\s*PROGRAM-ID\.\s*([A-Za-z0-9-]+)", re.I | re.M)
15
+
16
+
17
+ def expand(patterns):
18
+ out = []
19
+ for p in patterns:
20
+ out += sorted(glob.glob(p))
21
+ return out
22
+
23
+
24
+ def discover_legacy(files, prefix):
25
+ """[(PROGRAM-ID, file, line)] of the hand-written test programs in files."""
26
+ found = []
27
+ for f in files:
28
+ with open(f, encoding="utf-8", errors="replace") as fh:
29
+ text = fh.read()
30
+ for m in PROGRAM_ID.finditer(text):
31
+ if m.group(1).upper().startswith(prefix.upper()):
32
+ found.append((m.group(1).upper(), f, text.count("\n", 0, m.start(1)) + 1))
33
+ return found
34
+
35
+
36
+ def list_suites(cfg):
37
+ """What the suite files of the project declare, without generating or
38
+ compiling anything: (suites, errors). A file with a syntax error goes to
39
+ errors and does not hide the others."""
40
+ suites, errors, legacy_files = [], [], []
41
+ for f in expand(cfg["tests"]):
42
+ if not f.lower().endswith(".cblt"):
43
+ legacy_files.append(f)
44
+ continue
45
+ try:
46
+ s = parse_dsl(f)
47
+ except DslError as e:
48
+ e.kw["file"] = f
49
+ errors.append({"file": f, "line": e.kw["line"], "code": f"CBLT-{e.code}", "message": e.message})
50
+ continue
51
+ suites.append({"id": s.id, "file": f, "line": s.line, "description": s.desc, "dsl": True,
52
+ "program": s.program,
53
+ "cases": [{"name": c.name, "line": c.line, "ignored": c.ignored} for c in s.cases]})
54
+ dsl_ids = {s["id"] for s in suites}
55
+ for name, f, line in discover_legacy(legacy_files, cfg["test_prefix"]):
56
+ if name not in dsl_ids:
57
+ suites.append({"id": name, "file": f, "line": line, "description": "", "dsl": False,
58
+ "program": None, "cases": []})
59
+ return suites, errors
60
+
61
+
62
+ def resolve_program(spec, cfg, suite_file):
63
+ """PROGRAM name -> searched by PROGRAM-ID or file name in sources;
64
+ PROGRAM "path" -> path relative to the project or to the suite."""
65
+ spec = spec.strip()
66
+ if spec[:1] in "'\"":
67
+ path = spec.strip("'\"")
68
+ for cand in (path, os.path.join(os.path.dirname(suite_file), path)):
69
+ if os.path.isfile(cand):
70
+ return cand
71
+ raise CobaltoError("E400", name=path, file=suite_file, patterns=cfg["sources"])
72
+ name = spec.upper()
73
+ for f in expand(cfg["sources"]):
74
+ if os.path.splitext(os.path.basename(f))[0].upper() == name:
75
+ return f
76
+ with open(f, encoding="utf-8", errors="replace") as fh:
77
+ if any(m.group(1).upper() == name for m in PROGRAM_ID.finditer(fh.read())):
78
+ return f
79
+ raise CobaltoError("E400", name=name, file=suite_file, patterns=cfg["sources"])
80
+
81
+
82
+ def gen_inprogram(s, cfg, coverage, gen):
83
+ """In-program copy of the program under test with the suite injected."""
84
+ prog_path = resolve_program(s.program, cfg, s.file)
85
+ w, plan = inprog.generate(s, prog_path, copy_dirs_of(cfg), with_coverage=coverage)
86
+ gen.inprog[s.id] = os.path.basename(prog_path)
87
+ if plan is not None:
88
+ gen.cov_map.setdefault(plan.name, plan.to_json(prog_path))
89
+ return w
90
+
91
+
92
+ def instrument_sources(cfg, sources, gen):
93
+ """Instrumented copy of each program under test in build/cov/. If a
94
+ source cannot be instrumented (several programs in one file, a missing
95
+ copybook), a warning is shown and the original is compiled."""
96
+ cov_dir = os.path.join(cfg["build"], "cov")
97
+ os.makedirs(cov_dir, exist_ok=True)
98
+ out = []
99
+ for src in sources:
100
+ try:
101
+ w, plan = inprog.generate_coverage(src, copy_dirs_of(cfg))
102
+ except (CobaltoError, ValueError) as e:
103
+ warn("W305", program=src, detail=str(e))
104
+ out.append(src)
105
+ continue
106
+ dst = os.path.join(cov_dir, os.path.basename(src))
107
+ with open(dst, "w") as fh:
108
+ fh.write(w.text())
109
+ gen.linemaps[os.path.normpath(dst)] = w.origin
110
+ gen.cov_map.setdefault(plan.name, plan.to_json(src))
111
+ out.append(dst)
112
+ covmod.save_map(gen.cov_map, os.path.join(cov_dir, "map.json"))
113
+ return out
114
+
115
+
116
+ def generate(cfg, prof, suite_filter=None, coverage=False):
117
+ """Discovers the suites, expands the DSL, instruments the sources when
118
+ coverage is on, and writes the driver. suite_filter keeps only the suites
119
+ whose id contains that text. Returns a Generated."""
120
+ build = cfg["build"]
121
+ os.makedirs(build, exist_ok=True)
122
+ gen = Generated()
123
+ for f in expand(cfg["tests"]):
124
+ if not f.lower().endswith(".cblt"):
125
+ gen.legacy_files.append(f)
126
+ continue
127
+ try:
128
+ s = parse_dsl(f)
129
+ w = gen_inprogram(s, cfg, coverage, gen) if s.program else gen_suite(s)
130
+ except DslError as e:
131
+ e.kw["file"] = f
132
+ raise
133
+ except ValueError as e:
134
+ raise CobaltoError("E200", file=f, line="?", detail=str(e))
135
+ for c in s.cases:
136
+ gen.case_kinds[(s.id, c.name)] = (c.kind, c.reasons)
137
+ out = os.path.join(build, f"{s.id}.cbl")
138
+ with open(out, "w") as fh:
139
+ fh.write(w.text())
140
+ gen.linemaps[os.path.normpath(out)] = w.origin
141
+ gen.gen_files.append(out)
142
+ gen.suites.append(SuiteRef(s.id, f, s.desc))
143
+ # a legacy test whose PROGRAM-ID repeats that of a DSL suite is not
144
+ # compiled: the link would fail on the duplicate symbol
145
+ prefix = cfg["test_prefix"]
146
+ dsl_ids = {s.id for s in gen.suites}
147
+ dup_files = set()
148
+ for name, f, _ in discover_legacy(gen.legacy_files, prefix):
149
+ if name in dsl_ids:
150
+ warn("W302", name=name, file=f)
151
+ dup_files.add(f)
152
+ gen.legacy_files = [f for f in gen.legacy_files if f not in dup_files]
153
+ gen.suites += [SuiteRef(name, f) for name, f, _ in discover_legacy(gen.legacy_files, prefix)]
154
+ if suite_filter:
155
+ gen.suites = [s for s in gen.suites if suite_filter.upper() in s.id]
156
+ if not gen.suites:
157
+ raise CobaltoError("E100", patterns=cfg["tests"])
158
+ gen.sources = expand(cfg["sources"])
159
+ if coverage:
160
+ gen.sources = instrument_sources(cfg, gen.sources, gen)
161
+ gen.driver = os.path.join(build, "CBLTDRV.cbl")
162
+ with open(gen.driver, "w") as fh:
163
+ fh.write(driver_source([s.id for s in gen.suites], prof["results_path"], prof["results_org"], coverage))
164
+ return gen
cobalto/cli.py ADDED
@@ -0,0 +1,148 @@
1
+ """Cobalto (CBLT) - portable unit testing for COBOL. Runner and CLI.
2
+
3
+ cobalto test [--profile P] [--filter SUITE] [--coverage] [--no-run]
4
+ [--generate-only] [--host H] [--remote-dir D] [--json] [--verbose]
5
+ cobalto report --results FILE [--output SCREEN] [--manifest M] [--json]
6
+ cobalto debug --suite SUITE [--profile P]
7
+ cobalto suggest --program PROGRAM [--rounds N] [--backend api|command]
8
+ [--model M] [--dry-run]
9
+ cobalto init [DIR]
10
+ cobalto list [--json]
11
+ cobalto profiles [--json]
12
+ cobalto parse FILE... [--json]
13
+
14
+ Flow: discover the suites (.cblt files in the DSL, or TST*.cbl programs) ->
15
+ expand the DSL to COBOL 85 -> generate the driver -> compile with the
16
+ profile -> run -> read the results file and the output -> console, JUnit
17
+ and results.json. Standard library only: runs on any machine with
18
+ Python 3.9+.
19
+
20
+ Remote profiles ("remote" field): the CLI prepares build/remote/ with the
21
+ sources and the build and run scripts generated from the profile's
22
+ templates, uploads them with "upload", runs each script through "remote" +
23
+ "invoke", brings the results file back with "fetch" and parses it like a
24
+ local profile.
25
+
26
+ report: for hosts without ssh. 'test --generate-only' leaves a manifest
27
+ (cblt-manifest.json) in build/remote/ with the profile, the results format
28
+ and the suites; someone runs the scripts on the host and returns the
29
+ results file and, optionally, the screen output; 'report' parses them with
30
+ that manifest and produces the same console, junit.xml and results.json as
31
+ 'test'.
32
+
33
+ Portable coverage (--coverage, or "coverage": true in the profile): the
34
+ programs in "sources" are compiled from an instrumented copy in build/cov/
35
+ and the in-program copies add counters; the driver dumps the records
36
+ C|program|index|count to the results file, and the CLI reports by
37
+ paragraph and writes build/lcov.info, build/coverage.xml and
38
+ build/sonar-coverage.xml (SonarQube generic format). build/junit.xml,
39
+ build/sonar-tests.xml and build/results.json are written with or without
40
+ coverage, by every run of 'test' or 'report' that reads its results file.
41
+ A run that stops with an error once cblt.json is loaded (exit code 2)
42
+ rewrites junit.xml, sonar-tests.xml and results.json with that error, so
43
+ that none of them is left from an earlier run; with --json it writes the
44
+ same model. The coverage reports are only written by a run with
45
+ coverage, and a run with --no-run or --generate-only that ends without an
46
+ error leaves every report as it was.
47
+
48
+ debug: compiles the suite with the debug profile (-g) and leaves
49
+ .vscode/launch.json ready for the Cobalto VS Code extension (or plain
50
+ lldb-dap), with the line map, the variable map and the data layout.
51
+
52
+ suggest: an AI model proposes a .cblt suite for a program; the CLI runs it
53
+ with coverage and feeds back the errors, the failures and the paragraphs
54
+ that did not run, for N rounds. The best round is saved as a draft in
55
+ tests/<PROGRAM>.ai.cblt for a person to review. See suggest.py.
56
+ """
57
+ import argparse
58
+ import sys
59
+
60
+ from . import messages
61
+ from . import suggest as sugg
62
+ from .commands import (cmd_debug, cmd_init, cmd_list, cmd_parse, cmd_profiles, cmd_report,
63
+ cmd_suggest, cmd_test)
64
+ from .messages import VERSION, CobaltoError
65
+ from .remote import MANIFEST
66
+
67
+ COMMANDS = {"test": cmd_test, "report": cmd_report, "debug": cmd_debug, "suggest": cmd_suggest,
68
+ "init": cmd_init, "list": cmd_list, "profiles": cmd_profiles, "parse": cmd_parse}
69
+
70
+
71
+ def main():
72
+ ap = argparse.ArgumentParser(prog="cobalto")
73
+ ap.add_argument("--version", action="version", version=f"Cobalto {VERSION}")
74
+ ap.add_argument("--config", default="cblt.json")
75
+ sub = ap.add_subparsers(dest="cmd")
76
+ t = sub.add_parser("test", help="compile and run the suites")
77
+ t.add_argument("--profile")
78
+ t.add_argument("--filter", help="only suites whose name contains this text")
79
+ t.add_argument("--coverage", action="store_true",
80
+ help="portable coverage: instruments the programs and reports by paragraph (also LCOV, Cobertura XML and Sonar)")
81
+ t.add_argument("--no-run", action="store_true", help="compile without running")
82
+ t.add_argument("--generate-only", action="store_true",
83
+ help="only generate the suites, the driver and build/remote/ (useful for remote profiles)")
84
+ t.add_argument("--host", help="host of the remote profile (user@machine); overrides the host field")
85
+ t.add_argument("--remote-dir", help="remote directory; overrides the remote_dir field")
86
+ t.add_argument("--json", action="store_true",
87
+ help="write the result as JSON to standard output (the console goes to stderr)")
88
+ t.add_argument("--verbose", "-v", action="store_true")
89
+ r = sub.add_parser("report", help="parse a results file returned by hand from a host without ssh")
90
+ r.add_argument("--results", required=True, help="results file brought back from the host (e.g. CBLT_RESULTS.DAT)")
91
+ r.add_argument("--output", help="screen output of the run, copied to a file (optional)")
92
+ r.add_argument("--manifest", help=f"manifest written by 'test --generate-only' (default build/remote/{MANIFEST})")
93
+ r.add_argument("--json", action="store_true",
94
+ help="write the result as JSON to standard output (the console goes to stderr)")
95
+ r.add_argument("--verbose", "-v", action="store_true")
96
+ i = sub.add_parser("init", help="create a Cobalto project")
97
+ i.add_argument("dir", nargs="?", default=".")
98
+ ls = sub.add_parser("list", help="list the suites and their test cases, without compiling")
99
+ ls.add_argument("--json", action="store_true",
100
+ help="write the result as JSON to standard output (the console goes to stderr)")
101
+ f = sub.add_parser("profiles", help="list the built-in profiles and the project's")
102
+ f.add_argument("--json", action="store_true",
103
+ help="write the result as JSON to standard output (the console goes to stderr)")
104
+ p = sub.add_parser("parse", help="show how the parser sees a COBOL program")
105
+ p.add_argument("files", nargs="+")
106
+ p.add_argument("--json", action="store_true",
107
+ help="write the result as JSON to standard output (the console goes to stderr)")
108
+ d = sub.add_parser("debug", help="compile a suite with -g and prepare .vscode/launch.json (lldb-dap)")
109
+ d.add_argument("--suite", required=True, help="suite id (for example TSTINV)")
110
+ d.add_argument("--profile", help="local profile with -g; default gnucobol-debug")
111
+ d.add_argument("--verbose", "-v", action="store_true")
112
+ g = sub.add_parser("suggest", help="ask an AI model for a suite for a program and validate it by running it")
113
+ g.add_argument("--program", required=True, help="PROGRAM-ID, file name in sources, or path to the .cbl")
114
+ g.add_argument("--rounds", type=int, help=f"rounds of proposal and correction (default {sugg.DEFAULT_ROUNDS})")
115
+ g.add_argument("--max-cases", type=int, help=f"maximum number of test cases per round (default {sugg.DEFAULT_MAX_CASES})")
116
+ g.add_argument("--backend", choices=["api", "command", "auto"], help="api (ANTHROPIC_API_KEY), command (claude -p or another CLI) or auto")
117
+ g.add_argument("--command", help="command of the command backend; it receives the prompt on stdin")
118
+ g.add_argument("--model", help="model (default: the one in the ai field of cblt.json)")
119
+ g.add_argument("--out", help="output file (default tests/<PROGRAM>.ai.cblt)")
120
+ g.add_argument("--profile", help="profile used to run each round")
121
+ g.add_argument("--mode", choices=["auto", "interface", "in-program"],
122
+ help="kind of test case requested: interface (only what goes in and comes out; an internal "
123
+ "case counts as an error of the round), in-program (single paragraphs) or auto (ai.mode field)")
124
+ g.add_argument("--fill-expected", action="store_true",
125
+ help="deterministic characterization: an equality EXPECT that fails is changed to expect the "
126
+ "value the program produces, without spending a round (ai.fill_expected field)")
127
+ g.add_argument("--dry-run", action="store_true", help="build the prompt in build/ai/ without sending it")
128
+ g.add_argument("--verbose", "-v", action="store_true")
129
+ argv = sys.argv[1:]
130
+ if not any(x in COMMANDS or x in ("-h", "--help", "--version") for x in argv):
131
+ argv = ["test"] + argv # 'cobalto --profile X' is the same as 'cobalto test --profile X'
132
+ a = ap.parse_args(argv)
133
+ if getattr(a, "json", False):
134
+ messages.JSON_OUT, sys.stdout = sys.stdout, sys.stderr
135
+ if a.cmd not in COMMANDS:
136
+ ap.print_help()
137
+ return 0
138
+ try:
139
+ return COMMANDS[a.cmd](a)
140
+ except CobaltoError as e:
141
+ print(e, file=sys.stderr)
142
+ # 'test' and 'report' put on the error the model they wrote to results.json
143
+ messages.emit_json(getattr(e, "run", None) or {"error": e.as_json()})
144
+ return 2
145
+
146
+
147
+ if __name__ == "__main__":
148
+ sys.exit(main())
cobalto/cobolgen.py ADDED
@@ -0,0 +1,50 @@
1
+ """Writer for generated fixed-format COBOL that keeps a line map to the source."""
2
+
3
+ AREA_A = " " * 7
4
+ AREA_B = " " * 11
5
+
6
+
7
+ class CobolWriter:
8
+ """Collects fixed-format COBOL lines and remembers which line of the
9
+ test file each one came from (to map compile errors back to it)."""
10
+
11
+ def __init__(self, limit=72):
12
+ self.lines = []
13
+ self.origin = []
14
+ self.limit = limit
15
+
16
+ def a(self, text, origin=None):
17
+ self._emit(AREA_A + text, origin)
18
+
19
+ def b(self, text, origin=None, indent=0):
20
+ self._emit(AREA_B + " " * indent + text, origin)
21
+
22
+ def raw(self, text, origin=None):
23
+ self._emit(text.rstrip("\n"), origin)
24
+
25
+ def comment(self, text):
26
+ self._emit(" * " + text[:64], None)
27
+
28
+ def _emit(self, line, origin):
29
+ if len(line) > self.limit:
30
+ raise ValueError(f"generated line exceeds {self.limit} columns: {line!r}")
31
+ self.lines.append(line)
32
+ self.origin.append(origin)
33
+
34
+ def move_literal(self, text, target, origin=None, indent=0):
35
+ """MOVE of a long literal to a field, split with reference
36
+ modification so that no line goes past column 72."""
37
+ text = text.replace('"', "'")
38
+ if not text:
39
+ self.b(f'MOVE SPACES TO {target}', origin, indent)
40
+ return
41
+ self.b(f'MOVE SPACES TO {target}', origin, indent)
42
+ # 11 of margin + MOVE "..." TO target(pp:nn) has to fit in the width
43
+ pos, chunk = 1, max(10, min(30, self.limit - 29 - len(target) - indent))
44
+ for i in range(0, len(text), chunk):
45
+ part = text[i:i + chunk]
46
+ self.b(f'MOVE "{part}" TO {target}({pos}:{len(part)})', origin, indent)
47
+ pos += len(part)
48
+
49
+ def text(self):
50
+ return "\n".join(self.lines) + "\n"