jqpm 0.1.0__tar.gz
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.
- jqpm-0.1.0/LICENSE +21 -0
- jqpm-0.1.0/PKG-INFO +243 -0
- jqpm-0.1.0/README.md +225 -0
- jqpm-0.1.0/jqpm.egg-info/PKG-INFO +243 -0
- jqpm-0.1.0/jqpm.egg-info/SOURCES.txt +13 -0
- jqpm-0.1.0/jqpm.egg-info/dependency_links.txt +1 -0
- jqpm-0.1.0/jqpm.egg-info/entry_points.txt +2 -0
- jqpm-0.1.0/jqpm.egg-info/top_level.txt +1 -0
- jqpm-0.1.0/jqpm.py +617 -0
- jqpm-0.1.0/pyproject.toml +33 -0
- jqpm-0.1.0/setup.cfg +4 -0
- jqpm-0.1.0/tests/test_cli.py +197 -0
- jqpm-0.1.0/tests/test_resolve_spec.py +62 -0
- jqpm-0.1.0/tests/test_transitive.py +208 -0
- jqpm-0.1.0/tests/test_unit.py +158 -0
jqpm-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Miguel Ceriani
|
|
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 NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
jqpm-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: jqpm
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal package manager for jq
|
|
5
|
+
Author: Miguel Ceriani
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/miguel76/jqpm
|
|
8
|
+
Project-URL: Issues, https://github.com/miguel76/jqpm/issues
|
|
9
|
+
Keywords: jq,package-manager,json
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Dynamic: license-file
|
|
18
|
+
|
|
19
|
+
# jqpm — a minimal package manager for jq
|
|
20
|
+
|
|
21
|
+
`jqpm` lets you declare, install, and pin `jq` module dependencies from git
|
|
22
|
+
repos (GitHub by default), the same way `npm`/`cargo`/`pip` manage
|
|
23
|
+
dependencies — but radically simpler, because **jq already has a module
|
|
24
|
+
system**. `jqpm` doesn't reinvent that; it just fetches git repos into the
|
|
25
|
+
exact folder layout jq's own `import` resolution already looks for.
|
|
26
|
+
|
|
27
|
+
This means once a package is installed, you use it with **plain, unmodified
|
|
28
|
+
`jq`** — no custom loader, no wrapper required at runtime:
|
|
29
|
+
|
|
30
|
+
```sh
|
|
31
|
+
jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Prior art
|
|
35
|
+
|
|
36
|
+
This is directly inspired by [jqnpm](https://github.com/jqnpm/jqnpm)
|
|
37
|
+
(2014–2021, now archived) — same idea of GitHub-namespaced packages
|
|
38
|
+
(`owner/repo`) and semver git tags. `jqpm` differs mainly in that it doesn't
|
|
39
|
+
wrap `jq` at all at runtime; it leans entirely on jq's native `-L` search
|
|
40
|
+
path and `import "owner/repo"` resolution, so the "package manager" part
|
|
41
|
+
of the system is only responsible for *fetching*, not *loading*.
|
|
42
|
+
|
|
43
|
+
## Install
|
|
44
|
+
|
|
45
|
+
Requires Python 3.9+, `git`, and `jq` (1.6+ recommended for reliable
|
|
46
|
+
`import`) on your `PATH`.
|
|
47
|
+
|
|
48
|
+
The easiest way is from PyPI, which puts a `jqpm` command on your `PATH`:
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
pipx install jqpm # or: uv tool install jqpm
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Alternatively, it's a single file with no dependencies, attached to every
|
|
55
|
+
[GitHub release](https://github.com/miguel76/jqpm/releases):
|
|
56
|
+
|
|
57
|
+
```sh
|
|
58
|
+
curl -fLO https://github.com/miguel76/jqpm/releases/latest/download/jqpm.py
|
|
59
|
+
chmod +x jqpm.py
|
|
60
|
+
# optionally: sudo ln -s $(pwd)/jqpm.py /usr/local/bin/jqpm
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
To pin a specific version, replace `latest/download` with
|
|
64
|
+
`download/v0.1.0` (or any other release tag).
|
|
65
|
+
|
|
66
|
+
## Releasing
|
|
67
|
+
|
|
68
|
+
1. Bump `__version__` in `jqpm.py` and commit.
|
|
69
|
+
2. Create a GitHub release with a matching tag (e.g. `v0.1.0`).
|
|
70
|
+
|
|
71
|
+
The [release workflow](.github/workflows/release.yml) then runs the tests,
|
|
72
|
+
attaches `jqpm.py` to the release, and publishes the package to PyPI.
|
|
73
|
+
|
|
74
|
+
## Package convention
|
|
75
|
+
|
|
76
|
+
A package is just a git repo named `repo`, owned by `owner` on GitHub,
|
|
77
|
+
containing a file `repo.jq` at its root (this matches jq's own module
|
|
78
|
+
naming rules: `import "owner/repo"` looks for `owner/repo.jq` or
|
|
79
|
+
`owner/repo/repo.jq` on the search path — jqpm uses the latter).
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
my-jq-lib/
|
|
83
|
+
my-jq-lib.jq # the entry point, this is what gets imported
|
|
84
|
+
README.md
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Nothing else is required — no manifest inside the package itself. Tag
|
|
88
|
+
releases with semver git tags (`v1.2.0` or `1.2.0`).
|
|
89
|
+
|
|
90
|
+
### Multi-file packages
|
|
91
|
+
|
|
92
|
+
The entry file doesn't have to hold all the code. It can `import`/`include`
|
|
93
|
+
other `.jq`/`.json` files shipped in the same repo, directly or indirectly
|
|
94
|
+
(A imports B, B imports C, ...), exactly like Python or JS:
|
|
95
|
+
|
|
96
|
+
- a spec starting with `./` or `../` is a **local** import — resolved
|
|
97
|
+
relative to the file that contains it, and installed together with the
|
|
98
|
+
package;
|
|
99
|
+
- anything else, e.g. `import "owner/repo" as X;`, is **package-manager-mediated**
|
|
100
|
+
— resolved by jq itself via `-L jq_modules`, same as always.
|
|
101
|
+
|
|
102
|
+
```
|
|
103
|
+
my-jq-lib/
|
|
104
|
+
my-jq-lib.jq # import "./internal/parse" as P; ...
|
|
105
|
+
internal/
|
|
106
|
+
parse.jq # import "./format" as F; ... (reaches a sibling)
|
|
107
|
+
format.jq
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Plain jq resolves `./`-imports relative to the process's current directory,
|
|
111
|
+
not to the file that contains them — which breaks the moment a package
|
|
112
|
+
with local imports is installed under `jq_modules/owner/repo/` and used
|
|
113
|
+
from a different project's directory. jqpm works around this at `jqpm
|
|
114
|
+
install` time by rewriting each local spec into its fully-qualified
|
|
115
|
+
`owner/repo/...` form, still plain jq module names resolved via `-L`, no
|
|
116
|
+
runtime loader involved.
|
|
117
|
+
|
|
118
|
+
### Transitive dependencies
|
|
119
|
+
|
|
120
|
+
A package can depend on other packages too: just ship a `jqpackage.json`
|
|
121
|
+
at its root declaring its own `dependencies`, same format as a project's
|
|
122
|
+
manifest. `jqpm install` walks that graph automatically — every
|
|
123
|
+
dependency of every installed package is fetched and flattened into the
|
|
124
|
+
consuming project's own `jq_modules/`, right alongside its direct
|
|
125
|
+
dependencies:
|
|
126
|
+
|
|
127
|
+
```
|
|
128
|
+
jq_modules/
|
|
129
|
+
acme/
|
|
130
|
+
mid/ # a direct dependency of your project
|
|
131
|
+
mid.jq
|
|
132
|
+
jqpackage.json # declares acme/base as its own dependency
|
|
133
|
+
base/ # fetched automatically because mid depends on it
|
|
134
|
+
base.jq
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
This has to be a flat layout rather than a nested one, because jq's own
|
|
138
|
+
`import` resolution only ever searches a single `-L` path — there's no
|
|
139
|
+
such thing as a package-scoped `jq_modules` the way there is with, say,
|
|
140
|
+
`node_modules`.
|
|
141
|
+
|
|
142
|
+
If two packages require different versions of the same dependency, jqpm
|
|
143
|
+
resolves it like this:
|
|
144
|
+
|
|
145
|
+
- a dependency declared directly in *your* `jqpackage.json` always wins
|
|
146
|
+
over anything merely inferred transitively;
|
|
147
|
+
- between two transitive requirements, the one resolving to the higher
|
|
148
|
+
semver tag wins;
|
|
149
|
+
- a conflict jqpm can't order (e.g. two different explicit git refs) is a
|
|
150
|
+
hard error telling you to add an explicit top-level dependency in your
|
|
151
|
+
own `jqpackage.json` to pin it.
|
|
152
|
+
|
|
153
|
+
`jqpackage-lock.json` covers the whole flattened graph, not just your
|
|
154
|
+
direct dependencies, so `jqpm install` (without `--update`) is reproducible
|
|
155
|
+
end to end; `jqpm list` marks which entries are transitive and shows what
|
|
156
|
+
pulled each one in.
|
|
157
|
+
|
|
158
|
+
## Usage
|
|
159
|
+
|
|
160
|
+
```sh
|
|
161
|
+
# start a new project
|
|
162
|
+
jqpm init
|
|
163
|
+
|
|
164
|
+
# add a dependency (resolves the latest tag satisfying the range,
|
|
165
|
+
# writes it to jqpackage.json, installs it, and records the exact
|
|
166
|
+
# commit in jqpackage-lock.json)
|
|
167
|
+
jqpm add someuser/jq-strings@^1.0.0
|
|
168
|
+
|
|
169
|
+
# install everything from jqpackage.json
|
|
170
|
+
# (reproducible: reuses the exact commit from jqpackage-lock.json
|
|
171
|
+
# if present, so installs are pinned until you explicitly update)
|
|
172
|
+
jqpm install
|
|
173
|
+
|
|
174
|
+
# re-resolve all versions against latest matching tags
|
|
175
|
+
jqpm install --update
|
|
176
|
+
|
|
177
|
+
# see what's installed and at what commit
|
|
178
|
+
jqpm list
|
|
179
|
+
|
|
180
|
+
# remove a dependency
|
|
181
|
+
jqpm remove someuser/jq-strings
|
|
182
|
+
|
|
183
|
+
# run jq with -L jq_modules already set, so imports just work
|
|
184
|
+
jqpm run -n 'import "someuser/jq-strings" as S; "hi" | S::upper'
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
Or skip `jqpm run` entirely and call `jq -L jq_modules ...` yourself —
|
|
188
|
+
that's the whole point of piggybacking on jq's native module resolution.
|
|
189
|
+
|
|
190
|
+
## Version specs
|
|
191
|
+
|
|
192
|
+
Matched against the package repo's git tags:
|
|
193
|
+
|
|
194
|
+
| spec | meaning |
|
|
195
|
+
|--------------|-------------------------------------------------|
|
|
196
|
+
| `1.2.3` | exact tag (`v1.2.3` or `1.2.3`) |
|
|
197
|
+
| `^1.2.3` | latest `1.x.x` >= `1.2.3` |
|
|
198
|
+
| `~1.2.3` | latest `1.2.x` >= `1.2.3` |
|
|
199
|
+
| `*` (default)| latest tag, or default branch `HEAD` if no tags |
|
|
200
|
+
| `#some-ref` | exact git ref: branch name, tag, or commit sha |
|
|
201
|
+
|
|
202
|
+
## Files
|
|
203
|
+
|
|
204
|
+
- `jqpackage.json` — manifest: name, version, dependencies (checked in)
|
|
205
|
+
- `jqpackage-lock.json` — resolved commit per dependency (checked in, for
|
|
206
|
+
reproducible installs — same idea as `package-lock.json`/`Cargo.lock`)
|
|
207
|
+
- `jq_modules/` — installed packages, laid out as `jq_modules/owner/repo/repo.jq`
|
|
208
|
+
(gitignore this, like `node_modules/`)
|
|
209
|
+
|
|
210
|
+
## Testing
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
pip install -r requirements-dev.txt
|
|
214
|
+
pytest
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
The test suite doesn't touch GitHub or the network: it builds throwaway git
|
|
218
|
+
repos on disk (with real tags) and points jqpm at them via `file://` URLs,
|
|
219
|
+
so it exercises the real `git clone`/`ls-remote`/`checkout` codepath end to
|
|
220
|
+
end without any external test fixtures to host or maintain.
|
|
221
|
+
|
|
222
|
+
## What's deliberately left out (v0)
|
|
223
|
+
|
|
224
|
+
This is intentionally minimal. Not included yet, roughly in order of
|
|
225
|
+
likely usefulness:
|
|
226
|
+
|
|
227
|
+
- **A real registry / search.** Right now "the registry" is just "GitHub,
|
|
228
|
+
addressed by `owner/repo`." A `jqpm search` would need a real index
|
|
229
|
+
(could start as a static JSON file in a shared repo, à la early
|
|
230
|
+
Bower/npm-before-npm).
|
|
231
|
+
- **Integrity checking.** The lockfile records a commit sha (which is
|
|
232
|
+
already tamper-evident for that repo's history) but doesn't verify
|
|
233
|
+
signatures or checksums of the fetched tree.
|
|
234
|
+
- **`jqpm publish`.** Publishing today is just "push a git tag." A
|
|
235
|
+
`publish` command could automate tagging/pushing and maybe validate
|
|
236
|
+
that `repo.jq` exists and parses.
|
|
237
|
+
- **A real "private registry" concept**, though any git host already works
|
|
238
|
+
today: `jqpm add https://gitlab.example.com/team/jq-lib.git@^1.0.0`
|
|
239
|
+
installs the same way as a GitHub `owner/repo` dependency.
|
|
240
|
+
|
|
241
|
+
## License
|
|
242
|
+
|
|
243
|
+
Public domain / do whatever you want with it — it's a starting point.
|
jqpm-0.1.0/README.md
ADDED
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
# jqpm — a minimal package manager for jq
|
|
2
|
+
|
|
3
|
+
`jqpm` lets you declare, install, and pin `jq` module dependencies from git
|
|
4
|
+
repos (GitHub by default), the same way `npm`/`cargo`/`pip` manage
|
|
5
|
+
dependencies — but radically simpler, because **jq already has a module
|
|
6
|
+
system**. `jqpm` doesn't reinvent that; it just fetches git repos into the
|
|
7
|
+
exact folder layout jq's own `import` resolution already looks for.
|
|
8
|
+
|
|
9
|
+
This means once a package is installed, you use it with **plain, unmodified
|
|
10
|
+
`jq`** — no custom loader, no wrapper required at runtime:
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
jq -L jq_modules 'import "owner/repo" as X; X::somefunc' input.json
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
## Prior art
|
|
17
|
+
|
|
18
|
+
This is directly inspired by [jqnpm](https://github.com/jqnpm/jqnpm)
|
|
19
|
+
(2014–2021, now archived) — same idea of GitHub-namespaced packages
|
|
20
|
+
(`owner/repo`) and semver git tags. `jqpm` differs mainly in that it doesn't
|
|
21
|
+
wrap `jq` at all at runtime; it leans entirely on jq's native `-L` search
|
|
22
|
+
path and `import "owner/repo"` resolution, so the "package manager" part
|
|
23
|
+
of the system is only responsible for *fetching*, not *loading*.
|
|
24
|
+
|
|
25
|
+
## Install
|
|
26
|
+
|
|
27
|
+
Requires Python 3.9+, `git`, and `jq` (1.6+ recommended for reliable
|
|
28
|
+
`import`) on your `PATH`.
|
|
29
|
+
|
|
30
|
+
The easiest way is from PyPI, which puts a `jqpm` command on your `PATH`:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
pipx install jqpm # or: uv tool install jqpm
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Alternatively, it's a single file with no dependencies, attached to every
|
|
37
|
+
[GitHub release](https://github.com/miguel76/jqpm/releases):
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
curl -fLO https://github.com/miguel76/jqpm/releases/latest/download/jqpm.py
|
|
41
|
+
chmod +x jqpm.py
|
|
42
|
+
# optionally: sudo ln -s $(pwd)/jqpm.py /usr/local/bin/jqpm
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
To pin a specific version, replace `latest/download` with
|
|
46
|
+
`download/v0.1.0` (or any other release tag).
|
|
47
|
+
|
|
48
|
+
## Releasing
|
|
49
|
+
|
|
50
|
+
1. Bump `__version__` in `jqpm.py` and commit.
|
|
51
|
+
2. Create a GitHub release with a matching tag (e.g. `v0.1.0`).
|
|
52
|
+
|
|
53
|
+
The [release workflow](.github/workflows/release.yml) then runs the tests,
|
|
54
|
+
attaches `jqpm.py` to the release, and publishes the package to PyPI.
|
|
55
|
+
|
|
56
|
+
## Package convention
|
|
57
|
+
|
|
58
|
+
A package is just a git repo named `repo`, owned by `owner` on GitHub,
|
|
59
|
+
containing a file `repo.jq` at its root (this matches jq's own module
|
|
60
|
+
naming rules: `import "owner/repo"` looks for `owner/repo.jq` or
|
|
61
|
+
`owner/repo/repo.jq` on the search path — jqpm uses the latter).
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
my-jq-lib/
|
|
65
|
+
my-jq-lib.jq # the entry point, this is what gets imported
|
|
66
|
+
README.md
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Nothing else is required — no manifest inside the package itself. Tag
|
|
70
|
+
releases with semver git tags (`v1.2.0` or `1.2.0`).
|
|
71
|
+
|
|
72
|
+
### Multi-file packages
|
|
73
|
+
|
|
74
|
+
The entry file doesn't have to hold all the code. It can `import`/`include`
|
|
75
|
+
other `.jq`/`.json` files shipped in the same repo, directly or indirectly
|
|
76
|
+
(A imports B, B imports C, ...), exactly like Python or JS:
|
|
77
|
+
|
|
78
|
+
- a spec starting with `./` or `../` is a **local** import — resolved
|
|
79
|
+
relative to the file that contains it, and installed together with the
|
|
80
|
+
package;
|
|
81
|
+
- anything else, e.g. `import "owner/repo" as X;`, is **package-manager-mediated**
|
|
82
|
+
— resolved by jq itself via `-L jq_modules`, same as always.
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
my-jq-lib/
|
|
86
|
+
my-jq-lib.jq # import "./internal/parse" as P; ...
|
|
87
|
+
internal/
|
|
88
|
+
parse.jq # import "./format" as F; ... (reaches a sibling)
|
|
89
|
+
format.jq
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Plain jq resolves `./`-imports relative to the process's current directory,
|
|
93
|
+
not to the file that contains them — which breaks the moment a package
|
|
94
|
+
with local imports is installed under `jq_modules/owner/repo/` and used
|
|
95
|
+
from a different project's directory. jqpm works around this at `jqpm
|
|
96
|
+
install` time by rewriting each local spec into its fully-qualified
|
|
97
|
+
`owner/repo/...` form, still plain jq module names resolved via `-L`, no
|
|
98
|
+
runtime loader involved.
|
|
99
|
+
|
|
100
|
+
### Transitive dependencies
|
|
101
|
+
|
|
102
|
+
A package can depend on other packages too: just ship a `jqpackage.json`
|
|
103
|
+
at its root declaring its own `dependencies`, same format as a project's
|
|
104
|
+
manifest. `jqpm install` walks that graph automatically — every
|
|
105
|
+
dependency of every installed package is fetched and flattened into the
|
|
106
|
+
consuming project's own `jq_modules/`, right alongside its direct
|
|
107
|
+
dependencies:
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
jq_modules/
|
|
111
|
+
acme/
|
|
112
|
+
mid/ # a direct dependency of your project
|
|
113
|
+
mid.jq
|
|
114
|
+
jqpackage.json # declares acme/base as its own dependency
|
|
115
|
+
base/ # fetched automatically because mid depends on it
|
|
116
|
+
base.jq
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
This has to be a flat layout rather than a nested one, because jq's own
|
|
120
|
+
`import` resolution only ever searches a single `-L` path — there's no
|
|
121
|
+
such thing as a package-scoped `jq_modules` the way there is with, say,
|
|
122
|
+
`node_modules`.
|
|
123
|
+
|
|
124
|
+
If two packages require different versions of the same dependency, jqpm
|
|
125
|
+
resolves it like this:
|
|
126
|
+
|
|
127
|
+
- a dependency declared directly in *your* `jqpackage.json` always wins
|
|
128
|
+
over anything merely inferred transitively;
|
|
129
|
+
- between two transitive requirements, the one resolving to the higher
|
|
130
|
+
semver tag wins;
|
|
131
|
+
- a conflict jqpm can't order (e.g. two different explicit git refs) is a
|
|
132
|
+
hard error telling you to add an explicit top-level dependency in your
|
|
133
|
+
own `jqpackage.json` to pin it.
|
|
134
|
+
|
|
135
|
+
`jqpackage-lock.json` covers the whole flattened graph, not just your
|
|
136
|
+
direct dependencies, so `jqpm install` (without `--update`) is reproducible
|
|
137
|
+
end to end; `jqpm list` marks which entries are transitive and shows what
|
|
138
|
+
pulled each one in.
|
|
139
|
+
|
|
140
|
+
## Usage
|
|
141
|
+
|
|
142
|
+
```sh
|
|
143
|
+
# start a new project
|
|
144
|
+
jqpm init
|
|
145
|
+
|
|
146
|
+
# add a dependency (resolves the latest tag satisfying the range,
|
|
147
|
+
# writes it to jqpackage.json, installs it, and records the exact
|
|
148
|
+
# commit in jqpackage-lock.json)
|
|
149
|
+
jqpm add someuser/jq-strings@^1.0.0
|
|
150
|
+
|
|
151
|
+
# install everything from jqpackage.json
|
|
152
|
+
# (reproducible: reuses the exact commit from jqpackage-lock.json
|
|
153
|
+
# if present, so installs are pinned until you explicitly update)
|
|
154
|
+
jqpm install
|
|
155
|
+
|
|
156
|
+
# re-resolve all versions against latest matching tags
|
|
157
|
+
jqpm install --update
|
|
158
|
+
|
|
159
|
+
# see what's installed and at what commit
|
|
160
|
+
jqpm list
|
|
161
|
+
|
|
162
|
+
# remove a dependency
|
|
163
|
+
jqpm remove someuser/jq-strings
|
|
164
|
+
|
|
165
|
+
# run jq with -L jq_modules already set, so imports just work
|
|
166
|
+
jqpm run -n 'import "someuser/jq-strings" as S; "hi" | S::upper'
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
Or skip `jqpm run` entirely and call `jq -L jq_modules ...` yourself —
|
|
170
|
+
that's the whole point of piggybacking on jq's native module resolution.
|
|
171
|
+
|
|
172
|
+
## Version specs
|
|
173
|
+
|
|
174
|
+
Matched against the package repo's git tags:
|
|
175
|
+
|
|
176
|
+
| spec | meaning |
|
|
177
|
+
|--------------|-------------------------------------------------|
|
|
178
|
+
| `1.2.3` | exact tag (`v1.2.3` or `1.2.3`) |
|
|
179
|
+
| `^1.2.3` | latest `1.x.x` >= `1.2.3` |
|
|
180
|
+
| `~1.2.3` | latest `1.2.x` >= `1.2.3` |
|
|
181
|
+
| `*` (default)| latest tag, or default branch `HEAD` if no tags |
|
|
182
|
+
| `#some-ref` | exact git ref: branch name, tag, or commit sha |
|
|
183
|
+
|
|
184
|
+
## Files
|
|
185
|
+
|
|
186
|
+
- `jqpackage.json` — manifest: name, version, dependencies (checked in)
|
|
187
|
+
- `jqpackage-lock.json` — resolved commit per dependency (checked in, for
|
|
188
|
+
reproducible installs — same idea as `package-lock.json`/`Cargo.lock`)
|
|
189
|
+
- `jq_modules/` — installed packages, laid out as `jq_modules/owner/repo/repo.jq`
|
|
190
|
+
(gitignore this, like `node_modules/`)
|
|
191
|
+
|
|
192
|
+
## Testing
|
|
193
|
+
|
|
194
|
+
```sh
|
|
195
|
+
pip install -r requirements-dev.txt
|
|
196
|
+
pytest
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
The test suite doesn't touch GitHub or the network: it builds throwaway git
|
|
200
|
+
repos on disk (with real tags) and points jqpm at them via `file://` URLs,
|
|
201
|
+
so it exercises the real `git clone`/`ls-remote`/`checkout` codepath end to
|
|
202
|
+
end without any external test fixtures to host or maintain.
|
|
203
|
+
|
|
204
|
+
## What's deliberately left out (v0)
|
|
205
|
+
|
|
206
|
+
This is intentionally minimal. Not included yet, roughly in order of
|
|
207
|
+
likely usefulness:
|
|
208
|
+
|
|
209
|
+
- **A real registry / search.** Right now "the registry" is just "GitHub,
|
|
210
|
+
addressed by `owner/repo`." A `jqpm search` would need a real index
|
|
211
|
+
(could start as a static JSON file in a shared repo, à la early
|
|
212
|
+
Bower/npm-before-npm).
|
|
213
|
+
- **Integrity checking.** The lockfile records a commit sha (which is
|
|
214
|
+
already tamper-evident for that repo's history) but doesn't verify
|
|
215
|
+
signatures or checksums of the fetched tree.
|
|
216
|
+
- **`jqpm publish`.** Publishing today is just "push a git tag." A
|
|
217
|
+
`publish` command could automate tagging/pushing and maybe validate
|
|
218
|
+
that `repo.jq` exists and parses.
|
|
219
|
+
- **A real "private registry" concept**, though any git host already works
|
|
220
|
+
today: `jqpm add https://gitlab.example.com/team/jq-lib.git@^1.0.0`
|
|
221
|
+
installs the same way as a GitHub `owner/repo` dependency.
|
|
222
|
+
|
|
223
|
+
## License
|
|
224
|
+
|
|
225
|
+
Public domain / do whatever you want with it — it's a starting point.
|