karni-cli 0.3.1__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.
- karni_cli/__init__.py +3 -0
- karni_cli/_agent/__init__.py +82 -0
- karni_cli/_agent/__main__.py +44 -0
- karni_cli/_agent/check.py +658 -0
- karni_cli/_agent/history.py +328 -0
- karni_cli/_agent/history_chronicle.py +246 -0
- karni_cli/_agent/overrides.py +194 -0
- karni_cli/_agent/rules.py +673 -0
- karni_cli/_changelog/0.2.0.toml +304 -0
- karni_cli/_changelog/0.3.0.toml +25 -0
- karni_cli/_changelog/__init__.py +248 -0
- karni_cli/_errorcodes/__init__.py +1171 -0
- karni_cli/_errorcodes/__main__.py +34 -0
- karni_cli/_errorcodes/links.py +217 -0
- karni_cli/_templates/project/cookiecutter.json +8 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/.dockerignore +7 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/.env.example +85 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/.gitignore +10 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/Caddyfile +22 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/Dockerfile +53 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/Makefile +52 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/README.md +169 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/__init__.py +16 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/asgi.py +14 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/celery.py +17 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/settings.py +28 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/urls.py +31 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/config/wsgi.py +14 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/docker-compose.yml +126 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/.dockerignore +2 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/.jscpd.json +9 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/.npmrc +7 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/Dockerfile.dev +17 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/eslint.config.js +32 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/index.html +14 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/package.json +43 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/postcss.config.js +6 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/public/favicon.svg +6 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/App.tsx +18 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/api/health.ts +21 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/index.css +11 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/layout.tsx +51 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/main.tsx +11 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/pages/home.tsx +28 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/routes.tsx +24 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/src/vite-env.d.ts +1 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/tailwind.config.ts +13 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/tsconfig.json +19 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/frontend/vite.config.ts +18 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/manage.py +23 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/pyproject.toml +31 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/tests/__init__.py +0 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/tests/test_api_schema.py +17 -0
- karni_cli/_templates/project/{{cookiecutter.project_slug}}/tests/test_smoke.py +11 -0
- karni_cli/adapters.py +373 -0
- karni_cli/agent_adapters.toml +160 -0
- karni_cli/agent_data.py +260 -0
- karni_cli/brand.py +55 -0
- karni_cli/clidoc.py +254 -0
- karni_cli/commands/__init__.py +0 -0
- karni_cli/commands/add.py +144 -0
- karni_cli/commands/beat.py +36 -0
- karni_cli/commands/check.py +101 -0
- karni_cli/commands/config.py +81 -0
- karni_cli/commands/context.py +171 -0
- karni_cli/commands/createsuperuser.py +28 -0
- karni_cli/commands/doctor.py +136 -0
- karni_cli/commands/explain.py +60 -0
- karni_cli/commands/make.py +55 -0
- karni_cli/commands/manage_passthrough.py +28 -0
- karni_cli/commands/mcp.py +20 -0
- karni_cli/commands/migrate.py +23 -0
- karni_cli/commands/new.py +106 -0
- karni_cli/commands/routes.py +20 -0
- karni_cli/commands/rules.py +139 -0
- karni_cli/commands/run_tests.py +38 -0
- karni_cli/commands/schedule.py +40 -0
- karni_cli/commands/seed.py +34 -0
- karni_cli/commands/serve.py +50 -0
- karni_cli/commands/shell.py +28 -0
- karni_cli/commands/sync_roles.py +32 -0
- karni_cli/commands/types.py +72 -0
- karni_cli/commands/upgrade.py +231 -0
- karni_cli/commands/worker.py +63 -0
- karni_cli/config.py +142 -0
- karni_cli/environment.py +29 -0
- karni_cli/errorcodes.py +377 -0
- karni_cli/errordoc.py +227 -0
- karni_cli/generators/__init__.py +67 -0
- karni_cli/generators/apitest.py +206 -0
- karni_cli/generators/app.py +103 -0
- karni_cli/generators/command.py +98 -0
- karni_cli/generators/component.py +115 -0
- karni_cli/generators/core.py +319 -0
- karni_cli/generators/event.py +57 -0
- karni_cli/generators/factory.py +88 -0
- karni_cli/generators/fields.py +343 -0
- karni_cli/generators/introspect.py +263 -0
- karni_cli/generators/listener.py +168 -0
- karni_cli/generators/middleware.py +95 -0
- karni_cli/generators/migration.py +82 -0
- karni_cli/generators/model.py +235 -0
- karni_cli/generators/module.py +255 -0
- karni_cli/generators/naming.py +100 -0
- karni_cli/generators/page.py +373 -0
- karni_cli/generators/pysource.py +304 -0
- karni_cli/generators/schedule.py +174 -0
- karni_cli/generators/seeder.py +86 -0
- karni_cli/generators/serializer.py +165 -0
- karni_cli/generators/service.py +68 -0
- karni_cli/generators/task.py +84 -0
- karni_cli/generators/viewset.py +179 -0
- karni_cli/history.py +59 -0
- karni_cli/local_state.py +73 -0
- karni_cli/main.py +104 -0
- karni_cli/mcp_server.py +103 -0
- karni_cli/project.py +248 -0
- karni_cli/rules_render.py +86 -0
- karni_cli/scaffold.py +197 -0
- karni_cli/settings_edit.py +128 -0
- karni_cli/tips.py +53 -0
- karni_cli/typegen.py +101 -0
- karni_cli/upgrades/__init__.py +28 -0
- karni_cli/upgrades/changelog.py +123 -0
- karni_cli/upgrades/codemod.py +125 -0
- karni_cli/upgrades/engine.py +224 -0
- karni_cli/upgrades/legacy_agent_files.py +138 -0
- karni_cli/upgrades/python.py +670 -0
- karni_cli/upgrades/transforms/rename-export.cjs +96 -0
- karni_cli/upgrades/typescript.py +160 -0
- karni_cli/upgrades/v0_2/__init__.py +1 -0
- karni_cli/upgrades/v0_2/agent_guidance.py +269 -0
- karni_cli/upgrades/v1_0/__init__.py +5 -0
- karni_cli/upgrades/v1_0/all_objects_to_without.py +18 -0
- karni_cli/upgrades/v1_0/all_with_deleted_to_without.py +13 -0
- karni_cli/upgrades/v1_0/deleted_only_to_without_dead.py +13 -0
- karni_cli/upgrades/v1_0/object_permission_classes_to_access.py +16 -0
- karni_cli/upgrades/v1_0/related_lookups_to_optimize.py +15 -0
- karni_cli/upgrades/v1_0/scoped_related_lookups_to_optimize.py +15 -0
- karni_cli/upgrades/v1_0/soft_delete_manager_mixin_to_scoped.py +14 -0
- karni_cli-0.3.1.dist-info/METADATA +191 -0
- karni_cli-0.3.1.dist-info/RECORD +145 -0
- karni_cli-0.3.1.dist-info/WHEEL +4 -0
- karni_cli-0.3.1.dist-info/entry_points.txt +2 -0
- karni_cli-0.3.1.dist-info/licenses/LICENSE +201 -0
karni_cli/errorcodes.py
ADDED
|
@@ -0,0 +1,377 @@
|
|
|
1
|
+
"""Error codes: the CLI's own (``C``), and lookup across every registry for ``karni explain``.
|
|
2
|
+
|
|
3
|
+
Every :class:`~karni_cli.project.CliError` carries a ``C`` code (or passes
|
|
4
|
+
through a Karni code such as ``E704``). :func:`lookup` finds any code offline:
|
|
5
|
+
|
|
6
|
+
- ``E``/``W`` codes: Karni's registry (``karni.errorcodes``), read from the
|
|
7
|
+
monorepo source or the copy bundled into this wheel (``karni_cli/_errorcodes``)
|
|
8
|
+
— no Django, no project needed;
|
|
9
|
+
- ``C`` codes: :data:`CODES` below;
|
|
10
|
+
- module codes (``PAY001``): ``karni.errorcodes`` entry points installed next to
|
|
11
|
+
karni-cli, else the project interpreter (``python -m karni.errorcodes``);
|
|
12
|
+
- ``K`` codes: the agent rules (``karni rules --explain``).
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import importlib.util
|
|
18
|
+
import json
|
|
19
|
+
import subprocess
|
|
20
|
+
import sys
|
|
21
|
+
from importlib import resources
|
|
22
|
+
from importlib.metadata import entry_points
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
from types import ModuleType
|
|
25
|
+
from typing import Any, Final, NamedTuple
|
|
26
|
+
|
|
27
|
+
__all__ = ["CODES", "CliCode", "core_module", "docs_url", "lookup"]
|
|
28
|
+
|
|
29
|
+
_MODULE_NAME = "karni_cli._bundled_karni_errorcodes"
|
|
30
|
+
_FALLBACK_BASE = "https://cbsshekhawat18-lab.github.io/karni/"
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
class CliCode(NamedTuple):
|
|
34
|
+
code: str
|
|
35
|
+
title: str
|
|
36
|
+
why: str
|
|
37
|
+
fix: str
|
|
38
|
+
source: str
|
|
39
|
+
kind: str = "cli"
|
|
40
|
+
|
|
41
|
+
def as_dict(self) -> dict[str, str]:
|
|
42
|
+
return {**self._asdict(), "url": docs_url(self.code)}
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _c(code: str, title: str, source: str, why: str, fix: str) -> CliCode:
|
|
46
|
+
return CliCode(code=code, title=title, why=why, fix=fix, source=source)
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
CODES: Final[tuple[CliCode, ...]] = (
|
|
50
|
+
# C0xx project and environment
|
|
51
|
+
_c(
|
|
52
|
+
"C001",
|
|
53
|
+
"Not inside a Karni project",
|
|
54
|
+
"karni_cli.project.require_project and every project command",
|
|
55
|
+
"Project commands find the project by walking up to the directory with manage.py "
|
|
56
|
+
"(and config/settings.py).",
|
|
57
|
+
"cd into the project (or a directory below it), or create one: karni new <name>.",
|
|
58
|
+
),
|
|
59
|
+
_c(
|
|
60
|
+
"C002",
|
|
61
|
+
"No way to run the project's Python",
|
|
62
|
+
"karni_cli.project (runners: serve, migrate, test, shell, seed, ...)",
|
|
63
|
+
"Project commands run in the project's own interpreter: its .venv, else the "
|
|
64
|
+
"active virtualenv (VIRTUAL_ENV), else the running docker compose stack.",
|
|
65
|
+
"Create the venv (python -m venv .venv && .venv/bin/pip install -e .), activate "
|
|
66
|
+
"one that has the project's dependencies, or start the stack (docker compose up "
|
|
67
|
+
"-d). The message says which one the command looked for.",
|
|
68
|
+
),
|
|
69
|
+
_c(
|
|
70
|
+
"C003",
|
|
71
|
+
"Docker is not installed",
|
|
72
|
+
"karni_cli.project",
|
|
73
|
+
"Without --local, karni runs the project through docker compose.",
|
|
74
|
+
"Install Docker with the compose plugin, or run on the host: karni serve --local "
|
|
75
|
+
"(with a .venv).",
|
|
76
|
+
),
|
|
77
|
+
_c(
|
|
78
|
+
"C004",
|
|
79
|
+
"These options cannot be combined",
|
|
80
|
+
"karni serve, karni make model/page/schedule",
|
|
81
|
+
"Some options only apply in a particular mode (for example --host needs --local).",
|
|
82
|
+
"Drop one of the options as the message says, or add the option it needs.",
|
|
83
|
+
),
|
|
84
|
+
_c(
|
|
85
|
+
"C005",
|
|
86
|
+
"This karni-cli install is incomplete",
|
|
87
|
+
"karni_cli (bundled templates, agent rules, changelog, error codes)",
|
|
88
|
+
"The wheel bundles the project template, agent rules, changelog and error codes; "
|
|
89
|
+
"one is missing, so the install is broken.",
|
|
90
|
+
"Reinstall karni-cli (pipx reinstall karni-cli, or pip install --force-reinstall "
|
|
91
|
+
"karni-cli).",
|
|
92
|
+
),
|
|
93
|
+
_c(
|
|
94
|
+
"C006",
|
|
95
|
+
"An optional tool is not installed",
|
|
96
|
+
"karni mcp, karni types",
|
|
97
|
+
"Some commands need extra tools: the MCP SDK for karni mcp, Node and "
|
|
98
|
+
"openapi-typescript for karni types.",
|
|
99
|
+
"Install what the message names, e.g. pip install 'karni-cli[mcp]', or add "
|
|
100
|
+
"openapi-typescript to frontend devDependencies (Node 20+).",
|
|
101
|
+
),
|
|
102
|
+
_c(
|
|
103
|
+
"C007",
|
|
104
|
+
"A configuration value is invalid",
|
|
105
|
+
"karni config, KARNI_AGENT_SOURCE, KARNI_TEMPLATES, KARNI_UI_SRC",
|
|
106
|
+
"karni reads its settings from karni config files and a few environment variables.",
|
|
107
|
+
"Use a value the message lists (karni config shows the known settings), or unset "
|
|
108
|
+
"the environment variable.",
|
|
109
|
+
),
|
|
110
|
+
_c(
|
|
111
|
+
"C008",
|
|
112
|
+
"A file cannot be written",
|
|
113
|
+
"karni config",
|
|
114
|
+
"The file or its directory is not writable.",
|
|
115
|
+
"Check the path's permissions, or set the value per project instead of --global.",
|
|
116
|
+
),
|
|
117
|
+
_c(
|
|
118
|
+
"C009",
|
|
119
|
+
"A command in the project failed",
|
|
120
|
+
"karni context, karni upgrade, karni rules (project interpreter)",
|
|
121
|
+
"karni ran manage.py or Python in the project and it exited with an error.",
|
|
122
|
+
"Read the project's error in the message (often a settings or import error), fix "
|
|
123
|
+
"it, and re-run. `karni doctor` checks the environment.",
|
|
124
|
+
),
|
|
125
|
+
_c(
|
|
126
|
+
"C010",
|
|
127
|
+
"The path is not a file inside the project",
|
|
128
|
+
"karni rules --check, karni context --with-history",
|
|
129
|
+
"These commands read files of the current project only.",
|
|
130
|
+
"Pass an existing file path inside the project.",
|
|
131
|
+
),
|
|
132
|
+
_c(
|
|
133
|
+
"C011",
|
|
134
|
+
"pytest is not installed in the project interpreter",
|
|
135
|
+
"karni test",
|
|
136
|
+
"karni test runs `python -m pytest` through the project's interpreter (its .venv, the "
|
|
137
|
+
"active virtualenv, or the compose service); pytest and pytest-django are in the "
|
|
138
|
+
"project's dev dependency group, not in karni.",
|
|
139
|
+
"Install them there: pip install pytest pytest-django (or `uv sync` for the dev "
|
|
140
|
+
"group), then run karni test again.",
|
|
141
|
+
),
|
|
142
|
+
# C1xx karni make
|
|
143
|
+
_c(
|
|
144
|
+
"C101",
|
|
145
|
+
"The file karni make would write already exists",
|
|
146
|
+
"karni make (every generator)",
|
|
147
|
+
"Generators never overwrite your code silently.",
|
|
148
|
+
"Pass --force to overwrite (or, for multi-file generators, to create only the "
|
|
149
|
+
"missing files), or remove the file first.",
|
|
150
|
+
),
|
|
151
|
+
_c(
|
|
152
|
+
"C102",
|
|
153
|
+
"Which app? (none, unknown, or several)",
|
|
154
|
+
"karni make (generators that write into an app)",
|
|
155
|
+
"Generators write into a local app listed in the `# karni:apps` block of "
|
|
156
|
+
"config/settings.py.",
|
|
157
|
+
"Create one (karni make app <name>), or choose one with --app <label>.",
|
|
158
|
+
),
|
|
159
|
+
_c(
|
|
160
|
+
"C103",
|
|
161
|
+
"The name is not valid here",
|
|
162
|
+
"karni make, karni new",
|
|
163
|
+
"Names become Python modules, classes, URLs or task names, each with its own rules, "
|
|
164
|
+
"and must not shadow existing modules or Django/Karni commands.",
|
|
165
|
+
"Use the form the message shows (snake_case module, CamelCase model, kebab-case "
|
|
166
|
+
"module or route) and a name nothing else uses.",
|
|
167
|
+
),
|
|
168
|
+
_c(
|
|
169
|
+
"C104",
|
|
170
|
+
"A field spec is invalid",
|
|
171
|
+
"karni make model (name:type[:arg][?] fields)",
|
|
172
|
+
"Fields are written as name:type[:arg][?], e.g. title:str:200 or "
|
|
173
|
+
"starts_at:datetime?; relations name their target model.",
|
|
174
|
+
"Fix the field the message names; `karni make model --help` lists the types.",
|
|
175
|
+
),
|
|
176
|
+
_c(
|
|
177
|
+
"C105",
|
|
178
|
+
"Something the generator builds on does not exist yet",
|
|
179
|
+
"karni make (viewset, test, serializer, listener, schedule, ...)",
|
|
180
|
+
"Generators wire new code into existing code: a viewset needs its model, a test its "
|
|
181
|
+
"viewset, a listener its event.",
|
|
182
|
+
"Run the karni make command the message names first, then re-run this one.",
|
|
183
|
+
),
|
|
184
|
+
_c(
|
|
185
|
+
"C106",
|
|
186
|
+
"An option value is invalid",
|
|
187
|
+
"karni make, karni types",
|
|
188
|
+
"The option accepts specific values (the message lists them).",
|
|
189
|
+
"Use one of the values shown, e.g. --access owned:organizer or --every 15m.",
|
|
190
|
+
),
|
|
191
|
+
_c(
|
|
192
|
+
"C107",
|
|
193
|
+
"The new code would clash with existing code",
|
|
194
|
+
"karni make (component, viewset, schedule, page, service)",
|
|
195
|
+
"Two components claiming one role, two viewsets for one model, or two schedules "
|
|
196
|
+
"or routes with one name would shadow each other.",
|
|
197
|
+
"Extend or edit the existing code the message names, or choose another name.",
|
|
198
|
+
),
|
|
199
|
+
_c(
|
|
200
|
+
"C108",
|
|
201
|
+
"A karni marker is missing from a project file",
|
|
202
|
+
"karni make, karni add (settings.py and routes.tsx markers)",
|
|
203
|
+
"Generators insert code at `# karni:` / `// karni:` markers that karni new writes; "
|
|
204
|
+
"older or hand-edited projects may lack them.",
|
|
205
|
+
"Add the change by hand as the message shows, or restore the marker from a fresh "
|
|
206
|
+
"karni new project.",
|
|
207
|
+
),
|
|
208
|
+
_c(
|
|
209
|
+
"C109",
|
|
210
|
+
"An explicit serializer needs a reason",
|
|
211
|
+
"karni make serializer",
|
|
212
|
+
"BaseViewSet generates the serializer from the model (rule K106); a hand-written one "
|
|
213
|
+
"must say why it exists.",
|
|
214
|
+
'Pass --reason "<why>", or tune the generated serializer with APIMeta instead.',
|
|
215
|
+
),
|
|
216
|
+
_c(
|
|
217
|
+
"C110",
|
|
218
|
+
"A project file cannot be parsed",
|
|
219
|
+
"karni make (reads your Python before editing it)",
|
|
220
|
+
"karni make edits your files structurally and stops rather than guess.",
|
|
221
|
+
"Fix the syntax error at the file and line in the message, then re-run.",
|
|
222
|
+
),
|
|
223
|
+
_c(
|
|
224
|
+
"C199",
|
|
225
|
+
"Internal error in karni",
|
|
226
|
+
"karni make, karni upgrade",
|
|
227
|
+
"A generator or codemod hit a case it does not handle; nothing was written.",
|
|
228
|
+
"Report it with the command and the file it stopped on. Meanwhile, make the change "
|
|
229
|
+
"by hand.",
|
|
230
|
+
),
|
|
231
|
+
# C2xx upgrade, rules, types, add
|
|
232
|
+
_c(
|
|
233
|
+
"C201",
|
|
234
|
+
"karni upgrade needs a clean git work tree",
|
|
235
|
+
"karni upgrade",
|
|
236
|
+
"Codemods rewrite many files; a clean tree lets you review and undo them with git.",
|
|
237
|
+
"Commit or stash first, preview with --dry-run, or pass --allow-dirty to write anyway.",
|
|
238
|
+
),
|
|
239
|
+
_c(
|
|
240
|
+
"C202",
|
|
241
|
+
"karni upgrade does not downgrade",
|
|
242
|
+
"karni upgrade",
|
|
243
|
+
"Codemods only move code forward.",
|
|
244
|
+
"Pass a --to version newer than the project's karni, or check --from.",
|
|
245
|
+
),
|
|
246
|
+
_c(
|
|
247
|
+
"C203",
|
|
248
|
+
"That is not a version number",
|
|
249
|
+
"karni upgrade (--to / --from)",
|
|
250
|
+
"Versions are MAJOR.MINOR[.PATCH].",
|
|
251
|
+
"Write e.g. --to 0.2 or --to 0.2.0.",
|
|
252
|
+
),
|
|
253
|
+
_c(
|
|
254
|
+
"C204",
|
|
255
|
+
"No such rule or procedure",
|
|
256
|
+
"karni rules, karni explain",
|
|
257
|
+
"Rules (K codes) and procedures are listed by karni rules.",
|
|
258
|
+
"Run `karni rules` for the codes and procedures, then use one of them.",
|
|
259
|
+
),
|
|
260
|
+
_c(
|
|
261
|
+
"C205",
|
|
262
|
+
"The agent adapter configuration is invalid",
|
|
263
|
+
"karni rules sync (karni.rules.py ADAPTERS)",
|
|
264
|
+
"Adapters are the generated agent guidance files; each has an id and a line cap.",
|
|
265
|
+
"Use the adapter ids the message lists, and shorten project rules feeding an adapter "
|
|
266
|
+
"that exceeds its cap.",
|
|
267
|
+
),
|
|
268
|
+
_c(
|
|
269
|
+
"C206",
|
|
270
|
+
"The OpenAPI schema cannot be turned into types",
|
|
271
|
+
"karni types",
|
|
272
|
+
"karni types reads the backend's schema (x-karni-resource operations) to generate "
|
|
273
|
+
"typed hooks.",
|
|
274
|
+
"Make sure the backend serves Karni viewsets (karni routes) and the schema uses only "
|
|
275
|
+
"local $refs.",
|
|
276
|
+
),
|
|
277
|
+
_c(
|
|
278
|
+
"C207",
|
|
279
|
+
"karni add cannot edit pyproject.toml",
|
|
280
|
+
"karni add",
|
|
281
|
+
"karni add manages the [project].dependencies table of the project's pyproject.toml.",
|
|
282
|
+
"Add the table (or the dependency) by hand, then re-run.",
|
|
283
|
+
),
|
|
284
|
+
)
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
def core_source_dir() -> Path | None:
|
|
288
|
+
"""``karni/errorcodes``: the monorepo source, else the wheel's bundled copy."""
|
|
289
|
+
for parent in Path(__file__).resolve().parents:
|
|
290
|
+
candidate = parent / "packages" / "karni" / "karni" / "errorcodes"
|
|
291
|
+
if (candidate / "__init__.py").is_file():
|
|
292
|
+
return candidate
|
|
293
|
+
packaged = resources.files("karni_cli") / "_errorcodes"
|
|
294
|
+
with resources.as_file(packaged) as path:
|
|
295
|
+
if (path / "__init__.py").is_file():
|
|
296
|
+
return path
|
|
297
|
+
return None
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
def core_module() -> ModuleType | None:
|
|
301
|
+
"""``karni.errorcodes`` loaded by path under a private name (no Django needed)."""
|
|
302
|
+
if _MODULE_NAME in sys.modules:
|
|
303
|
+
return sys.modules[_MODULE_NAME]
|
|
304
|
+
directory = core_source_dir()
|
|
305
|
+
if directory is None:
|
|
306
|
+
return None
|
|
307
|
+
spec = importlib.util.spec_from_file_location(_MODULE_NAME, directory / "__init__.py")
|
|
308
|
+
if spec is None or spec.loader is None: # pragma: no cover - importlib contract
|
|
309
|
+
return None
|
|
310
|
+
loaded = importlib.util.module_from_spec(spec)
|
|
311
|
+
sys.modules[_MODULE_NAME] = loaded
|
|
312
|
+
try:
|
|
313
|
+
spec.loader.exec_module(loaded)
|
|
314
|
+
except Exception:
|
|
315
|
+
del sys.modules[_MODULE_NAME]
|
|
316
|
+
raise
|
|
317
|
+
return loaded
|
|
318
|
+
|
|
319
|
+
|
|
320
|
+
def docs_url(code: str) -> str:
|
|
321
|
+
"""The docs link for any code (Karni's single DOCS_BASE_URL)."""
|
|
322
|
+
core = core_module()
|
|
323
|
+
if core is not None:
|
|
324
|
+
return str(core.docs_url(code))
|
|
325
|
+
return f"{_FALLBACK_BASE}errors/#{code.lower()}"
|
|
326
|
+
|
|
327
|
+
|
|
328
|
+
def _module_entries() -> list[Any]:
|
|
329
|
+
found: list[Any] = []
|
|
330
|
+
for entry_point in entry_points(group="karni.errorcodes"):
|
|
331
|
+
try:
|
|
332
|
+
found.extend(entry_point.load())
|
|
333
|
+
except Exception: # noqa: BLE001, S112 - a broken module must not break explain
|
|
334
|
+
continue
|
|
335
|
+
return found
|
|
336
|
+
|
|
337
|
+
|
|
338
|
+
def _from_project(code: str) -> dict[str, str] | None:
|
|
339
|
+
"""Ask the project interpreter (it has the project's modules installed)."""
|
|
340
|
+
from karni_cli import project as project_mod
|
|
341
|
+
|
|
342
|
+
project = project_mod.find_project()
|
|
343
|
+
python = project_mod.venv_python(project) if project is not None else None
|
|
344
|
+
if python is None:
|
|
345
|
+
return None
|
|
346
|
+
try:
|
|
347
|
+
proc = subprocess.run(
|
|
348
|
+
[str(python), "-m", "karni.errorcodes", code, "--json"],
|
|
349
|
+
capture_output=True,
|
|
350
|
+
text=True,
|
|
351
|
+
timeout=30,
|
|
352
|
+
check=False,
|
|
353
|
+
cwd=project,
|
|
354
|
+
)
|
|
355
|
+
except (OSError, subprocess.SubprocessError):
|
|
356
|
+
return None
|
|
357
|
+
if proc.returncode != 0:
|
|
358
|
+
return None
|
|
359
|
+
data = json.loads(proc.stdout)
|
|
360
|
+
return data if isinstance(data, dict) else None
|
|
361
|
+
|
|
362
|
+
|
|
363
|
+
def lookup(code: str) -> dict[str, str] | None:
|
|
364
|
+
"""The entry for ``code`` as a dict (code, title, kind, why, fix, source, url), or None.
|
|
365
|
+
|
|
366
|
+
``K`` codes are not handled here (``karni explain`` renders the rule).
|
|
367
|
+
"""
|
|
368
|
+
wanted = code.strip().upper()
|
|
369
|
+
for cli in CODES:
|
|
370
|
+
if cli.code == wanted:
|
|
371
|
+
return cli.as_dict()
|
|
372
|
+
core = core_module()
|
|
373
|
+
if core is not None:
|
|
374
|
+
for entry in (*core.CODES, *_module_entries()):
|
|
375
|
+
if entry.code == wanted:
|
|
376
|
+
return dict(entry.as_dict())
|
|
377
|
+
return _from_project(wanted)
|
karni_cli/errordoc.py
ADDED
|
@@ -0,0 +1,227 @@
|
|
|
1
|
+
"""Render docs/errors.md from every registry — codes and their docs cannot drift.
|
|
2
|
+
|
|
3
|
+
python -m karni_cli.errordoc > docs/errors.md
|
|
4
|
+
|
|
5
|
+
Sources: Karni's registry (``karni.errorcodes``), installed modules'
|
|
6
|
+
``karni.errorcodes`` entry points (karni-payments), the CLI's ``C`` codes
|
|
7
|
+
(:mod:`karni_cli.errorcodes`), the agent rules (``K`` codes) and the ESLint
|
|
8
|
+
plugin's ``rules.json``. ``tests/test_errordoc.py`` fails when the committed
|
|
9
|
+
page differs from :func:`render`.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import json
|
|
15
|
+
from collections.abc import Iterable, Mapping
|
|
16
|
+
from pathlib import Path
|
|
17
|
+
from typing import Any
|
|
18
|
+
|
|
19
|
+
from karni_cli import agent_data
|
|
20
|
+
from karni_cli.errorcodes import CODES as CLI_CODES
|
|
21
|
+
from karni_cli.errorcodes import _module_entries, core_module
|
|
22
|
+
|
|
23
|
+
#: Karni's ranges, in page order: (first code, heading).
|
|
24
|
+
RANGES: tuple[tuple[str, str], ...] = (
|
|
25
|
+
("000", "Models, managers and scopes"),
|
|
26
|
+
("100", "API: access, viewsets, serializers, pagination, budgets, expand"),
|
|
27
|
+
("200", "Accounts"),
|
|
28
|
+
("300", "Admin"),
|
|
29
|
+
("400", "Events, listeners, schedules and Celery"),
|
|
30
|
+
("500", "Settings and optional dependencies"),
|
|
31
|
+
("600", "Testing and seeding"),
|
|
32
|
+
("700", "Agent tooling: karni check, karni.rules.py, changelog"),
|
|
33
|
+
)
|
|
34
|
+
|
|
35
|
+
INTRO = """\
|
|
36
|
+
---
|
|
37
|
+
description: Every Karni error code with why it happens and how to fix it, the page each error message links to.
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
# Error codes
|
|
41
|
+
|
|
42
|
+
<!-- Generated by `python -m karni_cli.errordoc > docs/errors.md`; never edit by hand. -->
|
|
43
|
+
|
|
44
|
+
Every error Karni raises starts with a code and ends with a link to its entry
|
|
45
|
+
on this page:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
E104: EventViewSet: Owned('organiser') does not lead from Event to the user model
|
|
49
|
+
(Event has no field 'organiser'). Name a relation path ending at the user, e.g.
|
|
50
|
+
Owned("organizer") or Owned("event__organizer"). See …/errors/#e104
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The message names *your* class, field or setting. The entry below says why
|
|
54
|
+
Karni objects and how to fix it in general. Offline, without a browser:
|
|
55
|
+
|
|
56
|
+
```sh
|
|
57
|
+
karni explain E104 # any code on this page: E, W, C, PAY, K
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Codes are permanent: a code never changes meaning and is never reused, so
|
|
61
|
+
match on the code, not on the wording, which improves between releases.
|
|
62
|
+
|
|
63
|
+
| Prefix | Comes from |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `E` / `W` | Karni itself: exceptions, system checks (`W` = warning), API errors, test failures |
|
|
66
|
+
| `PAY` | the karni-payments module (each module has its own prefix) |
|
|
67
|
+
| `C` | the `karni` command |
|
|
68
|
+
| `K` | agent rules, enforced by `karni check` and the architecture tests |
|
|
69
|
+
| `karni/…` | the ESLint plugin shipped with @karni/ui |
|
|
70
|
+
|
|
71
|
+
System checks run on `runserver`, `migrate`, `check` and every management
|
|
72
|
+
command, so problems surface on boot rather than on the first request. Their
|
|
73
|
+
ids are `karni.<code>` (silence a warning on purpose with
|
|
74
|
+
`SILENCED_SYSTEM_CHECKS = ["karni.W001"]`).
|
|
75
|
+
|
|
76
|
+
End-user outcomes are not on this page: wrong credentials, expired or used
|
|
77
|
+
tokens, an invalid 2FA code, a declined payment, a 404 for a row outside your
|
|
78
|
+
`access`. Those are ordinary API responses (see [accounts](accounts.md) and
|
|
79
|
+
[api](api.md)), not mistakes in your code.
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
KIND_LABEL: Mapping[str, str] = {
|
|
83
|
+
"exception": "exception",
|
|
84
|
+
"check": "system check (error)",
|
|
85
|
+
"warning": "system check (warning)",
|
|
86
|
+
"api": "API 400 response",
|
|
87
|
+
"test": "test failure",
|
|
88
|
+
"cli": "karni command",
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _entry(entry: Mapping[str, str]) -> str:
|
|
93
|
+
code = entry["code"]
|
|
94
|
+
return "\n".join(
|
|
95
|
+
[
|
|
96
|
+
f'<a id="{code.lower()}"></a>',
|
|
97
|
+
"",
|
|
98
|
+
f"### {code} — {entry['title']}",
|
|
99
|
+
"",
|
|
100
|
+
f"*{KIND_LABEL.get(entry['kind'], entry['kind'])}* · from `{entry['source']}`",
|
|
101
|
+
"",
|
|
102
|
+
f"**Why Karni objects.** {entry['why']}",
|
|
103
|
+
"",
|
|
104
|
+
f"**Fix.** {entry['fix']}",
|
|
105
|
+
"",
|
|
106
|
+
]
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def _section(title: str, entries: Iterable[Mapping[str, str]], level: str = "##") -> str:
|
|
111
|
+
body = "\n".join(_entry(entry) for entry in entries)
|
|
112
|
+
return f"{level} {title}\n\n{body}"
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def _core_sections(core: Any) -> list[str]:
|
|
116
|
+
entries = sorted((entry.as_dict() for entry in core.CODES), key=lambda e: e["code"][1:])
|
|
117
|
+
sections = ["## Karni (`E`, `W`)\n"]
|
|
118
|
+
for index, (start, title) in enumerate(RANGES):
|
|
119
|
+
end = RANGES[index + 1][0] if index + 1 < len(RANGES) else "999"
|
|
120
|
+
inside = [e for e in entries if start <= e["code"][1:] < end]
|
|
121
|
+
if inside:
|
|
122
|
+
sections.append(_section(f"{start[0]}xx · {title}", inside, level="###"))
|
|
123
|
+
# Within a range the headings are ### too; demote entries to ####.
|
|
124
|
+
return [
|
|
125
|
+
section.replace("\n### E", "\n#### E").replace("\n### W", "\n#### W")
|
|
126
|
+
for section in sections
|
|
127
|
+
]
|
|
128
|
+
|
|
129
|
+
|
|
130
|
+
def _module_sections() -> list[str]:
|
|
131
|
+
by_prefix: dict[str, list[dict[str, str]]] = {}
|
|
132
|
+
for entry in _module_entries():
|
|
133
|
+
prefix = "".join(ch for ch in entry.code if ch.isalpha())
|
|
134
|
+
by_prefix.setdefault(prefix, []).append(dict(entry.as_dict()))
|
|
135
|
+
names = {"PAY": "karni-payments"}
|
|
136
|
+
return [
|
|
137
|
+
_section(
|
|
138
|
+
f"{names.get(prefix, prefix)} (`{prefix}`)", sorted(items, key=lambda e: e["code"])
|
|
139
|
+
)
|
|
140
|
+
for prefix, items in sorted(by_prefix.items())
|
|
141
|
+
]
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
def _rule_section() -> str:
|
|
145
|
+
rules = sorted(agent_data.load(None).rules, key=lambda rule: str(rule["code"]))
|
|
146
|
+
blocks = [
|
|
147
|
+
"\n".join(
|
|
148
|
+
[
|
|
149
|
+
f'<a id="{str(rule["code"]).lower()}"></a>',
|
|
150
|
+
"",
|
|
151
|
+
f"### {rule['code']} — {rule['summary']}",
|
|
152
|
+
"",
|
|
153
|
+
f"*agent rule, {rule['severity']}* · enforced by "
|
|
154
|
+
+ ", ".join(f"`{name}`" for name in rule.get("enforced_by") or ["review"]),
|
|
155
|
+
"",
|
|
156
|
+
f"**Rule.** {rule['rule']}",
|
|
157
|
+
"",
|
|
158
|
+
f"**Why Karni objects.** {rule['rationale']}",
|
|
159
|
+
"",
|
|
160
|
+
f"**Fix.** {rule['fix']}",
|
|
161
|
+
"",
|
|
162
|
+
]
|
|
163
|
+
)
|
|
164
|
+
for rule in rules
|
|
165
|
+
]
|
|
166
|
+
return (
|
|
167
|
+
"## Agent rules (`K`)\n\n"
|
|
168
|
+
+ (
|
|
169
|
+
"`karni rules` lists them in one screen; `karni check` and the architecture tests "
|
|
170
|
+
"(`pytest --pyargs karni.testing.architecture`) enforce them.\n\n"
|
|
171
|
+
)
|
|
172
|
+
+ "\n".join(blocks)
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def _eslint_manifest() -> list[dict[str, str]]:
|
|
177
|
+
for parent in Path(__file__).resolve().parents:
|
|
178
|
+
candidate = parent / "packages" / "karni-ui" / "eslint-plugin" / "rules.json"
|
|
179
|
+
if candidate.is_file():
|
|
180
|
+
data = json.loads(candidate.read_text(encoding="utf-8"))
|
|
181
|
+
return [dict(item) for item in data]
|
|
182
|
+
return []
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def _eslint_section() -> str:
|
|
186
|
+
blocks = [
|
|
187
|
+
"\n".join(
|
|
188
|
+
[
|
|
189
|
+
f'<a id="{item["id"].replace("/", "-")}"></a>',
|
|
190
|
+
"",
|
|
191
|
+
f"### `{item['id']}` — {item['title']}",
|
|
192
|
+
"",
|
|
193
|
+
f"**Why Karni objects.** {item['why']}",
|
|
194
|
+
"",
|
|
195
|
+
f"**Fix.** {item['fix']}",
|
|
196
|
+
"",
|
|
197
|
+
]
|
|
198
|
+
)
|
|
199
|
+
for item in _eslint_manifest()
|
|
200
|
+
]
|
|
201
|
+
return (
|
|
202
|
+
"## ESLint rules (`@karni/ui/eslint-plugin`)\n\n"
|
|
203
|
+
+ (
|
|
204
|
+
"Every rule is an error in `karni.configs.recommended`; an opt-out needs an "
|
|
205
|
+
"`eslint-disable` comment with a `-- reason`.\n\n"
|
|
206
|
+
)
|
|
207
|
+
+ "\n".join(blocks)
|
|
208
|
+
)
|
|
209
|
+
|
|
210
|
+
|
|
211
|
+
def render() -> str:
|
|
212
|
+
core = core_module()
|
|
213
|
+
if core is None: # pragma: no cover - the monorepo always has the source
|
|
214
|
+
raise SystemExit("karni/errorcodes not found")
|
|
215
|
+
parts = [
|
|
216
|
+
INTRO,
|
|
217
|
+
*_core_sections(core),
|
|
218
|
+
*_module_sections(),
|
|
219
|
+
_section("The karni command (`C`)", [code.as_dict() for code in CLI_CODES]),
|
|
220
|
+
_rule_section(),
|
|
221
|
+
_eslint_section(),
|
|
222
|
+
]
|
|
223
|
+
return "\n".join(part.rstrip("\n") + "\n" for part in parts)
|
|
224
|
+
|
|
225
|
+
|
|
226
|
+
if __name__ == "__main__":
|
|
227
|
+
print(render(), end="")
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""``karni make`` generators — one module per generator, registered here.
|
|
2
|
+
|
|
3
|
+
Each generator module exposes ``NAME``, ``SUMMARY``, a ``plan(...)`` that
|
|
4
|
+
works against a :class:`~karni_cli.generators.core.Workspace`, and a typer
|
|
5
|
+
``command``. :data:`GENERATORS` is the single list ``karni make``,
|
|
6
|
+
``karni make --list``, the hidden ``make:<type>`` aliases and docs/cli.md
|
|
7
|
+
are built from.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from collections.abc import Callable
|
|
13
|
+
from dataclasses import dataclass
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
from karni_cli.generators import (
|
|
17
|
+
apitest,
|
|
18
|
+
app,
|
|
19
|
+
command,
|
|
20
|
+
component,
|
|
21
|
+
event,
|
|
22
|
+
factory,
|
|
23
|
+
listener,
|
|
24
|
+
middleware,
|
|
25
|
+
migration,
|
|
26
|
+
model,
|
|
27
|
+
module,
|
|
28
|
+
page,
|
|
29
|
+
schedule,
|
|
30
|
+
seeder,
|
|
31
|
+
serializer,
|
|
32
|
+
service,
|
|
33
|
+
task,
|
|
34
|
+
viewset,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
@dataclass(frozen=True)
|
|
39
|
+
class Generator:
|
|
40
|
+
name: str
|
|
41
|
+
summary: str
|
|
42
|
+
command: Callable[..., Any]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
GENERATORS: tuple[Generator, ...] = tuple(
|
|
46
|
+
Generator(mod.NAME, mod.SUMMARY, mod.command)
|
|
47
|
+
for mod in (
|
|
48
|
+
app,
|
|
49
|
+
model,
|
|
50
|
+
viewset,
|
|
51
|
+
serializer,
|
|
52
|
+
migration,
|
|
53
|
+
apitest,
|
|
54
|
+
factory,
|
|
55
|
+
seeder,
|
|
56
|
+
task,
|
|
57
|
+
schedule,
|
|
58
|
+
event,
|
|
59
|
+
listener,
|
|
60
|
+
command,
|
|
61
|
+
service,
|
|
62
|
+
middleware,
|
|
63
|
+
page,
|
|
64
|
+
component,
|
|
65
|
+
module,
|
|
66
|
+
)
|
|
67
|
+
)
|