pineforge-codegen 1.1.0__py3-none-any.whl → 1.2.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.
@@ -6,6 +6,7 @@ from .lexer import Lexer
6
6
  from .parser import Parser
7
7
  from .analyzer import Analyzer
8
8
  from .codegen import CodeGen
9
+ from .diagnostic_codes import diagnostics_catalog, render_diagnostic
9
10
  from .errors import CompileError, Level, Phase
10
11
  from .external_requests import lower_no_data_requests
11
12
  from .builtin_keywords import bind_builtin_keywords
@@ -4414,7 +4414,44 @@ class CodeGen(CallVisitor, ExprVisitor, StmtVisitor, TopLevelEmitter, SecurityEm
4414
4414
  return None
4415
4415
 
4416
4416
  def generate(self) -> str:
4417
- """Generate C++ source from the AnalyzerContext."""
4417
+ """Generate C++ source from the AnalyzerContext.
4418
+
4419
+ An error the settings metadata finds in an input's arguments (emitted
4420
+ in the constructor, ahead of the body: ``checked_settings``) is held
4421
+ until the rest is generated; the error raised is the first in source
4422
+ order, as before that metadata visited the arguments."""
4423
+ self._deferred_settings_errors: list[CompileError] | None = []
4424
+ try:
4425
+ try:
4426
+ cpp = self._generate_cpp()
4427
+ except CompileError as error:
4428
+ first = self._first_settings_error_before(error)
4429
+ if first is None:
4430
+ raise
4431
+ raise first from None
4432
+ if self._deferred_settings_errors:
4433
+ raise self._deferred_settings_errors[0]
4434
+ return cpp
4435
+ finally:
4436
+ self._deferred_settings_errors = None
4437
+
4438
+ def _defer_settings_error(self, error: CompileError) -> None:
4439
+ held = getattr(self, "_deferred_settings_errors", None)
4440
+ if held is None: # outside generate(): nothing holds it
4441
+ raise error
4442
+ held.append(error)
4443
+
4444
+ def _first_settings_error_before(self, error: CompileError) -> CompileError | None:
4445
+ """A held settings error located before ``error``, else None."""
4446
+ def where(err: CompileError):
4447
+ loc = err.diagnostics[0].location if err.diagnostics else None
4448
+ return (loc.line, loc.col) if loc is not None else (float("inf"), 0)
4449
+ held = sorted(self._deferred_settings_errors, key=where)
4450
+ if held and where(held[0]) < where(error):
4451
+ return held[0]
4452
+ return None
4453
+
4454
+ def _generate_cpp(self) -> str:
4418
4455
  # Every input is keyed by its title: refuse a non-constant one first,
4419
4456
  # then flag inputs one override key would reach together.
4420
4457
  self._check_input_titles()
@@ -0,0 +1,186 @@
1
+ """Immutable execution metadata; it does not alter generated computation."""
2
+
3
+ import json
4
+ import math
5
+
6
+ from ..ast_nodes import BoolLiteral, FuncCall, Identifier, MemberAccess, NumberLiteral, StrategyDecl, StringLiteral, UnaryOp, VarDecl
7
+ from ..external_requests import CAPABILITY_UNPINNED_ANNOTATION
8
+ from ..limits import iter_ast_nodes
9
+
10
+
11
+ STRATEGY_PARAMETERS = (
12
+ "title", "shorttitle", "overlay", "format", "precision", "scale", "pyramiding",
13
+ "calc_on_order_fills", "calc_on_every_tick", "max_bars_back",
14
+ "backtest_fill_limits_assumption", "default_qty_type", "default_qty_value",
15
+ "initial_capital", "currency", "slippage", "commission_type", "commission_value",
16
+ "process_orders_on_close", "close_entries_rule", "margin_long", "margin_short",
17
+ "explicit_plot_zorder", "max_lines_count", "max_labels_count", "max_boxes_count",
18
+ "calc_bars_count", "risk_free_rate", "use_bar_magnifier", "fill_orders_on_standard_ohlc",
19
+ "max_polylines_count", "dynamic_requests", "behind_chart", "calc_on_every_history_tick",
20
+ )
21
+
22
+
23
+ DECLARATION_DEFAULTS = {
24
+ "calc_on_every_tick": False,
25
+ "calc_on_order_fills": False,
26
+ "process_orders_on_close": False,
27
+ "use_bar_magnifier": False,
28
+ "fill_orders_on_standard_ohlc": False,
29
+ "backtest_fill_limits_assumption": 0,
30
+ "currency": "currency.NONE",
31
+ "timeframe": "",
32
+ "timeframe_gaps": True,
33
+ "dynamic_requests": True,
34
+ "calc_on_every_history_tick": False,
35
+ }
36
+
37
+
38
+ def _expression(node):
39
+ if isinstance(node, (StringLiteral, NumberLiteral, BoolLiteral)):
40
+ return node.value
41
+ if isinstance(node, Identifier):
42
+ return node.name
43
+ if isinstance(node, MemberAccess):
44
+ return f"{_expression(node.object)}.{node.member}"
45
+ if isinstance(node, FuncCall):
46
+ return f"{_expression(node.callee)}({','.join(str(_expression(arg)) for arg in node.args)})"
47
+ return None
48
+
49
+
50
+ def _literal(node):
51
+ if isinstance(node, (StringLiteral, NumberLiteral, BoolLiteral)):
52
+ return node.value, True
53
+ if isinstance(node, UnaryOp) and node.op in ("+", "-"):
54
+ value, valid = _literal(node.operand)
55
+ if valid and type(value) in (int, float):
56
+ return value if node.op == "+" else -value, True
57
+ if isinstance(node, MemberAccess):
58
+ value = _expression(node)
59
+ if value and value.split(".")[0] in ("currency", "format", "scale", "strategy"):
60
+ return value, True
61
+ return _expression(node), False
62
+
63
+
64
+ def capabilities_document(emitter) -> str:
65
+ declarations = dict(DECLARATION_DEFAULTS)
66
+ unresolved = []
67
+ requests = []
68
+ lower_symbols = {}
69
+ intrabar = False
70
+ recorded = False
71
+ for node, _depth in iter_ast_nodes(emitter.ctx.ast):
72
+ if isinstance(node, StrategyDecl):
73
+ arguments = {STRATEGY_PARAMETERS[index] if index < len(STRATEGY_PARAMETERS)
74
+ else f"strategy() positional argument {index + 1}": argument
75
+ for index, argument in enumerate(node.args)}
76
+ unresolved.extend(arguments.keys() & node.kwargs.keys())
77
+ arguments.update(node.kwargs)
78
+ for name, argument in arguments.items():
79
+ value, valid = _literal(argument)
80
+ default = DECLARATION_DEFAULTS.get(name)
81
+ if name in DECLARATION_DEFAULTS:
82
+ valid &= type(value) is type(default)
83
+ if name == "backtest_fill_limits_assumption":
84
+ valid = (type(value) is int and value >= 0) or (
85
+ type(value) is float and math.isfinite(value) and value >= 0 and value == int(value))
86
+ if valid:
87
+ value = int(value)
88
+ declarations[name] = value
89
+ if not valid or name not in STRATEGY_PARAMETERS and name not in DECLARATION_DEFAULTS:
90
+ unresolved.append(name)
91
+ elif isinstance(node, VarDecl):
92
+ intrabar |= node.is_varip
93
+ elif isinstance(node, FuncCall):
94
+ name, namespace = emitter._resolve_callee(node.callee)
95
+ if namespace == "request" and name == "security_lower_tf":
96
+ expression = node.args[2] if len(node.args) > 2 else node.kwargs.get("expression")
97
+ lower_symbols[id(expression)] = node.args[0] if node.args else node.kwargs.get("symbol")
98
+ parts = (node.annotations or {}).get("pf_recorded_key")
99
+ if parts is not None:
100
+ recorded = True
101
+ requests.append({
102
+ "function": f"{namespace}.{name}",
103
+ "symbol": _expression(node.args[0]) if node.args else None,
104
+ "timeframe": "",
105
+ "lookahead": f"barmerge.lookahead_{parts.get('lookahead', 'off')}",
106
+ "gaps": f"barmerge.gaps_{parts.get('gaps', 'off')}",
107
+ "heikinashi": False,
108
+ "feed": "recorded",
109
+ })
110
+ if isinstance(node, Identifier) and node.name == "timenow":
111
+ unresolved.append("timenow (bar timestamp approximation)")
112
+ if isinstance(node, Identifier) and node.name in ("last_bar_index", "last_bar_time"):
113
+ unresolved.append(f"{node.name} (stream endpoint is not batch-equivalent)")
114
+ if isinstance(node, MemberAccess) and _expression(node) == "barstate.isrealtime":
115
+ unresolved.append("barstate.isrealtime (compiled historical-only approximation)")
116
+ if isinstance(node, MemberAccess) and _expression(node) in (
117
+ "barstate.islast", "barstate.islastconfirmedhistory"):
118
+ unresolved.append(f"{_expression(node)} (stream endpoint is not batch-equivalent)")
119
+
120
+ auxiliary = False
121
+ for site in emitter._security_calls:
122
+ symbol_node = site.get("symbol_node")
123
+ if site.get("is_lower_tf_array"):
124
+ symbol_node = lower_symbols.get(id(site.get("expr_node")), symbol_node)
125
+ if isinstance(symbol_node, FuncCall) and site.get("heikinashi") and symbol_node.args:
126
+ symbol_node = symbol_node.args[0]
127
+ symbol = _expression(symbol_node) if symbol_node is not None else "syminfo.tickerid"
128
+ timeframe = _expression(site.get("tf_node"))
129
+ lookahead = _expression(site.get("lookahead_node")) or "barmerge.lookahead_off"
130
+ gaps = _expression(site.get("gaps_node")) or "barmerge.gaps_off"
131
+ if isinstance(symbol_node, Identifier) and symbol_node.name not in emitter._global_mutable_infos:
132
+ symbol = _expression((getattr(emitter.ctx, "global_expr_map", {}) or {}).get(
133
+ symbol_node.name, symbol_node))
134
+ feed = "chart" if symbol in ("syminfo.tickerid", "syminfo.ticker", "") else "auxiliary"
135
+ auxiliary |= feed == "auxiliary"
136
+ if not isinstance(site.get("tf_node"), StringLiteral) and timeframe != "timeframe.period":
137
+ unresolved.append(f"request.security[{site['sec_id']}].timeframe")
138
+ if lookahead not in ("barmerge.lookahead_off", "barmerge.lookahead_on"):
139
+ unresolved.append(f"request.security[{site['sec_id']}].lookahead")
140
+ requests.append({
141
+ "function": "request.security_lower_tf" if site.get("is_lower_tf_array") else "request.security",
142
+ "symbol": symbol,
143
+ "timeframe": timeframe,
144
+ "lookahead": lookahead,
145
+ "gaps": gaps,
146
+ "heikinashi": bool(site.get("heikinashi")),
147
+ "feed": feed,
148
+ })
149
+ for index, site in enumerate((emitter.ctx.ast.annotations or {}).get(CAPABILITY_UNPINNED_ANNOTATION, ())):
150
+ requests.append({
151
+ "function": site["function"],
152
+ "symbol": _expression(site["symbol_node"]),
153
+ "timeframe": _expression(site["tf_node"]) if site["function"] in (
154
+ "request.security", "request.security_lower_tf") else "",
155
+ "lookahead": _expression(site["lookahead_node"]) or "barmerge.lookahead_off",
156
+ "gaps": _expression(site["gaps_node"]) or "barmerge.gaps_off",
157
+ "heikinashi": False,
158
+ "feed": "unpinned",
159
+ })
160
+ unresolved.append(f"{site['function']}[unpinned:{index}]")
161
+ requirements = {
162
+ "auxiliary_security_feeds": auxiliary,
163
+ "native_security_feeds": False,
164
+ "fx_curve": declarations["currency"] != "currency.NONE",
165
+ "recorded_series": recorded,
166
+ "historical_probe_overrides": False,
167
+ "intrabar_persistence": intrabar,
168
+ }
169
+ return json.dumps({"version": 1, "declarations": declarations, "requests": requests,
170
+ "requirements": requirements, "unresolved": sorted(set(unresolved))},
171
+ sort_keys=True, separators=(",", ":"), allow_nan=False)
172
+
173
+
174
+ def emit_capabilities_exports(emitter, lines: list[str]) -> None:
175
+ literal = json.dumps(capabilities_document(emitter))
176
+ lines.extend([
177
+ "#ifdef PF_SETTINGS_API_VERSION",
178
+ "#ifdef PF_CAPABILITIES_API_VERSION",
179
+ " uint32_t strategy_capabilities_api_version(void) { return PF_CAPABILITIES_API_VERSION; }",
180
+ " int strategy_capabilities_receipt(void* s, char* json, size_t capacity, size_t* required, char* error, size_t error_capacity) {",
181
+ " if (required) *required = 0;",
182
+ " return ::pineforge::checked_settings::boundary(error, error_capacity, [&] {",
183
+ ' ::pineforge::checked_settings::require(s != nullptr, "null strategy");',
184
+ f" ::pineforge::checked_settings::receipt({literal}, json, capacity, required);",
185
+ " });", " }", "#endif", "#endif",
186
+ ])
@@ -1,6 +1,19 @@
1
1
  """Opt-in settings metadata, validation and exception-contained C exports."""
2
2
 
3
3
  from ..ast_nodes import Identifier, MemberAccess
4
+ from ..errors import CompileError
5
+
6
+
7
+ def _visit_setting_arg(emitter, expr) -> str:
8
+ """An input argument's C++ for the settings metadata. The metadata is
9
+ emitted in the constructor, ahead of the script body: an error here is
10
+ held until the body is generated (``CodeGen.generate``), so the script's
11
+ first error in source order is the one raised."""
12
+ try:
13
+ return emitter._visit_expr(expr)
14
+ except CompileError as error:
15
+ emitter._defer_settings_error(error)
16
+ return "0"
4
17
 
5
18
 
6
19
  def emit_settings_members(emitter, lines: list[str], constructor: list[str]) -> None:
@@ -38,7 +51,7 @@ def emit_settings_members(emitter, lines: list[str], constructor: list[str]) ->
38
51
  key = emitter._input_key_literal(name)
39
52
  default = emitter._get_input_default(node)
40
53
  getter = emitter._input_getter_for_call(node, func_name, namespace)
41
- default_cpp = emitter._visit_expr(default) if default is not None else "0"
54
+ default_cpp = _visit_setting_arg(emitter, default) if default is not None else "0"
42
55
  default_cpp = emitter._coerce_string_input_default(getter, default_cpp)
43
56
  value_type = {
44
57
  "get_input_int": "int", "get_input_int64": "int",
@@ -89,7 +102,7 @@ def emit_settings_members(emitter, lines: list[str], constructor: list[str]) ->
89
102
  declared = getattr(arguments.get("options"), "elements", None)
90
103
  if declared:
91
104
  for option in declared:
92
- option_cpp = emitter._visit_expr(option)
105
+ option_cpp = _visit_setting_arg(emitter, option)
93
106
  options.append(option_cpp if getter == "get_input_string" else
94
107
  f'::pineforge::checked_settings::number({option_cpp})')
95
108
  expression = f'{getter}({key}, {default_cpp})'
@@ -98,7 +111,7 @@ def emit_settings_members(emitter, lines: list[str], constructor: list[str]) ->
98
111
  if default_serialized is None:
99
112
  default_serialized = (default_cpp if value_type in ("string", "source") else
100
113
  f'::pineforge::checked_settings::number({default_cpp})')
101
- constraints = [emitter._visit_expr(arguments[name]) if arguments.get(name) is not None
114
+ constraints = [_visit_setting_arg(emitter, arguments[name]) if arguments.get(name) is not None
102
115
  else "std::numeric_limits<double>::quiet_NaN()"
103
116
  for name in ("minval", "maxval", "step")]
104
117
  metadata = (f'{{{key}, "{value_type}", {default_serialized}, '
@@ -1998,6 +1998,8 @@ class TopLevelEmitter:
1998
1998
  lines.append(" }")
1999
1999
  from .checked_settings import emit_settings_exports
2000
2000
  emit_settings_exports(lines)
2001
+ from .capabilities import emit_capabilities_exports
2002
+ emit_capabilities_exports(self, lines)
2001
2003
  if self._declares_bar_magnifier():
2002
2004
  # TradingView runs a script that declares use_bar_magnifier = true
2003
2005
  # on its bar magnifier; the host reads this export to run it on
@@ -282,6 +282,7 @@ CPP_EMITTER_NAMES = frozenset("""
282
282
  configure_security_evaluators snapshot_script_state restore_script_state
283
283
  commit_script_state set_strategy_override set_input
284
284
  set_magnifier_volume_weighted strategy_declares_bar_magnifier fill_report run
285
+ strategy_capabilities_api_version strategy_capabilities_receipt
285
286
  precalculate
286
287
  strategy_entry strategy_close strategy_close_all strategy_exit
287
288
  strategy_exit_cancel_bracket strategy_cancel strategy_cancel_all strategy_order
@@ -0,0 +1,341 @@
1
+ """Stable codes and named arguments for every transpile diagnostic.
2
+
3
+ Every :class:`~pineforge_codegen.errors.Diagnostic` carries a ``code``
4
+ (``PF-E1203`` for an error, ``PF-W0412`` for a warning) and ``args``, the
5
+ named data its English ``message`` and ``hint`` were built from. The codes,
6
+ their severities, English ICU MessageFormat templates and one-line
7
+ explanations live in ``diagnostics_catalog.json`` beside this module, which
8
+ ships with the package and is returned by :func:`diagnostics_catalog`.
9
+
10
+ The emitters keep spelling their English text as they always have, so the
11
+ ``message`` stays byte for byte what it was; a diagnostic is coded by the
12
+ catalog template its text renders from (:func:`classify`). The template's
13
+ literal text must equal the message's around its arguments, so a code is
14
+ never guessed: a text no template renders gets the uncatalogued code of its
15
+ severity (``PF-E0000`` / ``PF-W0000``), which the test suite refuses.
16
+
17
+ The match never backtracks over the text's characters: each literal segment
18
+ of a template goes to its leftmost place after the previous one, the last to
19
+ the text's end, and every argument is the text between its literals -- the
20
+ split a fullmatch of the template with lazy ``(.*?)`` arguments returns. Where
21
+ an argument is named twice (``{receiver}`` in the message and the hint) the
22
+ leftmost split can name it two values; then the later places of a literal are
23
+ tried in order, as the regex's backtracking tries them, within a fixed budget
24
+ of steps. The regex took seconds, then minutes, as a crafted message grew,
25
+ and a user's script spells argument text.
26
+
27
+ Rendering (:func:`render`) is the ICU MessageFormat subset the catalog uses:
28
+ literal text with ICU apostrophe quoting (``''`` is one apostrophe, ``'{'``
29
+ a literal brace) and simple ``{name}`` arguments, a string argument
30
+ inserted as is and a number in plain decimal digits.
31
+ """
32
+
33
+ from __future__ import annotations
34
+
35
+ import json
36
+ import re
37
+ from functools import lru_cache
38
+ from pathlib import Path
39
+ from typing import Any
40
+
41
+ CATALOG_PATH = Path(__file__).with_name("diagnostics_catalog.json")
42
+ CATALOG_SCHEMA = "pineforge-diagnostics-catalog/v1"
43
+ UNCATALOGUED = {"error": "PF-E0000", "warning": "PF-W0000"}
44
+
45
+
46
+ @lru_cache(maxsize=1)
47
+ def _load() -> dict:
48
+ with CATALOG_PATH.open(encoding="utf-8") as handle:
49
+ return json.load(handle)
50
+
51
+
52
+ def diagnostics_catalog() -> dict:
53
+ """The diagnostics catalog: ``{"schema", "codes": {code: entry}}``.
54
+
55
+ Each entry gives ``severity`` (``error`` / ``warning``), ``area``, the
56
+ English ICU MessageFormat ``message`` template, the ``hint`` template or
57
+ ``None``, a one-line ``explanation`` and ``args``: per argument name its
58
+ ``kind`` (``identifier``, ``type``, ``keyword``, ``number``, ``vocab`` or
59
+ ``text``) and, for ``vocab``, its closed set of ``values``. A fresh copy
60
+ is returned on every call.
61
+ """
62
+ return json.loads(json.dumps(_load()))
63
+
64
+
65
+ # ---------------------------------------------------------------------------
66
+ # ICU MessageFormat subset
67
+ # ---------------------------------------------------------------------------
68
+
69
+ _SPECIAL = "{}"
70
+
71
+
72
+ def parse_template(template: str) -> list:
73
+ """Split a catalog template into literal strings and ``(name,)`` argument
74
+ tuples, applying ICU's apostrophe rules (``ApostropheMode.DOUBLE_OPTIONAL``,
75
+ the ICU and FormatJS default)."""
76
+ parts: list = []
77
+ text: list[str] = []
78
+ i, n = 0, len(template)
79
+ while i < n:
80
+ ch = template[i]
81
+ if ch == "'":
82
+ if i + 1 < n and template[i + 1] == "'":
83
+ text.append("'")
84
+ i += 2
85
+ continue
86
+ if i + 1 < n and template[i + 1] in _SPECIAL:
87
+ # A quoted literal runs to the next lone apostrophe.
88
+ i += 1
89
+ while i < n:
90
+ if template[i] == "'":
91
+ if i + 1 < n and template[i + 1] == "'":
92
+ text.append("'")
93
+ i += 2
94
+ continue
95
+ i += 1
96
+ break
97
+ text.append(template[i])
98
+ i += 1
99
+ continue
100
+ text.append("'")
101
+ i += 1
102
+ continue
103
+ if ch == "{":
104
+ end = template.find("}", i)
105
+ if end < 0:
106
+ raise ValueError(f"unclosed argument in template: {template!r}")
107
+ name = template[i + 1:end].strip()
108
+ if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", name):
109
+ raise ValueError(f"unsupported argument {name!r} in template: {template!r}")
110
+ if text:
111
+ parts.append("".join(text))
112
+ text = []
113
+ parts.append((name,))
114
+ i = end + 1
115
+ continue
116
+ if ch == "}":
117
+ raise ValueError(f"unbalanced '}}' in template: {template!r}")
118
+ text.append(ch)
119
+ i += 1
120
+ if text:
121
+ parts.append("".join(text))
122
+ return parts
123
+
124
+
125
+ def escape_literal(text: str) -> str:
126
+ """ICU-escape literal text: every apostrophe doubled, every brace quoted."""
127
+ out: list[str] = []
128
+ for ch in text:
129
+ if ch == "'":
130
+ out.append("''")
131
+ elif ch in _SPECIAL:
132
+ out.append("'" + ch + "'")
133
+ else:
134
+ out.append(ch)
135
+ return "".join(out)
136
+
137
+
138
+ def format_arg(value: Any) -> str:
139
+ """An argument's text: a string as is, a number in plain decimal digits."""
140
+ if isinstance(value, bool):
141
+ raise TypeError("diagnostic arguments are strings or numbers")
142
+ if isinstance(value, int):
143
+ return str(value)
144
+ if isinstance(value, float):
145
+ return repr(value)
146
+ if isinstance(value, str):
147
+ return value
148
+ raise TypeError(f"diagnostic argument of type {type(value).__name__}")
149
+
150
+
151
+ def render(template: str | None, args: dict) -> str | None:
152
+ """Render a catalog template with a diagnostic's ``args``."""
153
+ if template is None:
154
+ return None
155
+ return "".join(
156
+ part if isinstance(part, str) else format_arg(args[part[0]])
157
+ for part in parse_template(template)
158
+ )
159
+
160
+
161
+ def render_diagnostic(code: str, args: dict) -> tuple[str, str | None]:
162
+ """The English ``(message, hint)`` a code renders with ``args``."""
163
+ entry = _load()["codes"][code]
164
+ return render(entry["message"], args), render(entry.get("hint"), args)
165
+
166
+
167
+ # ---------------------------------------------------------------------------
168
+ # Classification
169
+ # ---------------------------------------------------------------------------
170
+
171
+ _CANONICAL_INT = re.compile(r"-?(?:0|[1-9][0-9]*)")
172
+ _CANONICAL_FLOAT = re.compile(r"-?(?:0|[1-9][0-9]*)\.[0-9]+")
173
+
174
+
175
+ def _segments(parts: list) -> tuple[str, tuple[tuple[str, str], ...]]:
176
+ """A parsed template as its leading literal and ``(argument, literal after
177
+ it)`` pairs; the literal after an argument may be empty."""
178
+ head = ""
179
+ pairs: list[list[str]] = []
180
+ for part in parts:
181
+ if isinstance(part, str):
182
+ if pairs:
183
+ pairs[-1][1] += part
184
+ else:
185
+ head += part
186
+ else:
187
+ pairs.append([part[0], ""])
188
+ return head, tuple((name, literal) for name, literal in pairs)
189
+
190
+
191
+ # Literal places a template whose argument is named twice may try, per
192
+ # classification: a script's text never needs more than a few, and a crafted
193
+ # one gets the uncatalogued code instead of a long search.
194
+ _SEARCH_BUDGET = 4096
195
+
196
+
197
+ def _search(segments: list, texts: list[str], repeats: bool) -> dict[str, str] | None:
198
+ """Split ``texts`` (the message, then the hint) by their templates'
199
+ ``segments``: each argument ends at the leftmost place of the literal after
200
+ it, the last argument of a text at its end -- the split a lazy-regex
201
+ fullmatch returns. Without an argument named twice (``repeats``) that split
202
+ succeeds whenever any does, since a leftmost place leaves the rest the most
203
+ room: it is the only one tried, so the work is linear. With one, a split can
204
+ give the name two values; then the later places of a literal are tried in
205
+ order, as the regex backtracks, within ``_SEARCH_BUDGET`` places."""
206
+ starts: list[int] = []
207
+ ends: list[int] = []
208
+ slots: list[tuple[int, str, str, bool]] = [] # text, argument, literal after it, last
209
+ for index, ((head, pairs), text) in enumerate(zip(segments, texts)):
210
+ if not text.startswith(head):
211
+ return None
212
+ if not pairs:
213
+ if len(text) != len(head):
214
+ return None
215
+ starts.append(len(head))
216
+ ends.append(len(head))
217
+ continue
218
+ tail = pairs[-1][1]
219
+ end = len(text) - len(tail)
220
+ if end < len(head) or not text.endswith(tail):
221
+ return None
222
+ starts.append(len(head))
223
+ ends.append(end)
224
+ for at, (name, literal) in enumerate(pairs):
225
+ slots.append((index, name, literal, at == len(pairs) - 1))
226
+ found: dict[str, str] = {}
227
+ budget = [_SEARCH_BUDGET]
228
+
229
+ def step(slot: int, pos: int) -> bool:
230
+ if slot == len(slots):
231
+ return True
232
+ text_index, name, literal, last = slots[slot]
233
+ text, end = texts[text_index], ends[text_index]
234
+ following = slot + 1
235
+ known = found.get(name)
236
+ if last:
237
+ value = text[pos:end]
238
+ resume = (starts[slots[following][0]] if following < len(slots) else end)
239
+ if known is not None:
240
+ return known == value and step(following, resume)
241
+ found[name] = value
242
+ if step(following, resume):
243
+ return True
244
+ del found[name]
245
+ return False
246
+ if known is not None:
247
+ stop = pos + len(known)
248
+ return (text.startswith(known, pos) and stop + len(literal) <= end
249
+ and text.startswith(literal, stop) and step(following, stop + len(literal)))
250
+ at = text.find(literal, pos, end)
251
+ while at >= 0:
252
+ budget[0] -= 1
253
+ if budget[0] < 0:
254
+ return False
255
+ found[name] = text[pos:at]
256
+ if step(following, at + len(literal)):
257
+ return True
258
+ del found[name]
259
+ if not repeats:
260
+ return False
261
+ at = text.find(literal, at + 1, end) if at < end else -1
262
+ return False
263
+
264
+ first = starts[slots[0][0]] if slots else 0
265
+ return found if step(0, first) else None
266
+
267
+
268
+ class _Matcher:
269
+ __slots__ = ("code", "has_hint", "prefix", "suffix", "specificity",
270
+ "_message", "_hint", "_kinds", "_repeats")
271
+
272
+ def __init__(self, code: str, entry: dict):
273
+ self.code = code
274
+ message = parse_template(entry["message"])
275
+ hint = entry.get("hint")
276
+ hint_parts = parse_template(hint) if hint is not None else []
277
+ self.has_hint = hint is not None
278
+ self._message = _segments(message)
279
+ self._hint = _segments(hint_parts) if hint is not None else None
280
+ self.prefix = message[0] if message and isinstance(message[0], str) else ""
281
+ self.suffix = message[-1] if message and isinstance(message[-1], str) else ""
282
+ # The text a template spells itself; the hint's separator counted as one
283
+ # character, as the order of the catalog's codes has always assumed.
284
+ self.specificity = (sum(len(p) for p in message + hint_parts if isinstance(p, str))
285
+ + (1 if hint is not None else 0))
286
+ self._kinds = {name: spec.get("kind") for name, spec in entry.get("args", {}).items()}
287
+ names = [part[0] for part in message + hint_parts if isinstance(part, tuple)]
288
+ self._repeats = len(names) != len(set(names))
289
+
290
+ def match(self, message: str, hint: str | None) -> dict | None:
291
+ segments = [self._message] + ([self._hint] if self._hint is not None else [])
292
+ texts = [message] + ([hint] if self._hint is not None else [])
293
+ found = _search(segments, texts, self._repeats)
294
+ if found is None:
295
+ return None
296
+ args: dict[str, Any] = {}
297
+ for name, value in found.items():
298
+ if self._kinds.get(name) == "number":
299
+ if _CANONICAL_INT.fullmatch(value):
300
+ args[name] = int(value)
301
+ continue
302
+ if _CANONICAL_FLOAT.fullmatch(value) and repr(float(value)) == value:
303
+ args[name] = float(value)
304
+ continue
305
+ args[name] = value
306
+ return args
307
+
308
+
309
+ @lru_cache(maxsize=1)
310
+ def _matchers() -> dict[str, list[_Matcher]]:
311
+ by_severity: dict[str, list[_Matcher]] = {"error": [], "warning": []}
312
+ for code, entry in _load()["codes"].items():
313
+ if code in UNCATALOGUED.values():
314
+ continue
315
+ by_severity[entry["severity"]].append(_Matcher(code, entry))
316
+ for matchers in by_severity.values():
317
+ # The template with the most literal text wins: a message two templates
318
+ # render reads as the more specific one (both render it byte for byte).
319
+ matchers.sort(key=lambda m: (-m.specificity, m.code))
320
+ return by_severity
321
+
322
+
323
+ def classify(severity: str, message: str, hint: str | None = None) -> tuple[str, dict]:
324
+ """The ``(code, args)`` of a diagnostic's English text.
325
+
326
+ ``severity`` is ``"error"`` or ``"warning"``. A text no catalog template
327
+ renders gets ``PF-E0000`` / ``PF-W0000`` with its text as ``args``.
328
+ """
329
+ for matcher in _matchers().get(severity, ()):
330
+ if matcher.has_hint != (hint is not None):
331
+ continue
332
+ if not message.startswith(matcher.prefix) or not message.endswith(matcher.suffix):
333
+ continue
334
+ args = matcher.match(message, hint)
335
+ if args is not None:
336
+ return matcher.code, args
337
+ args = {"message": message}
338
+ if hint is not None:
339
+ args["hint"] = hint
340
+ code = UNCATALOGUED.get(severity, UNCATALOGUED["error"])
341
+ return code, args