0
# Query & Analysis
1

2
Commands for querying information about projects, tasks, and the build pipeline to analyze workspace structure and understand changes.
3

4
## Capabilities
5

6
### Inspect Hash Contents
7

8
Examine the contents and inputs that contributed to a generated hash for debugging cache behavior.
9

10
```bash { .api }
11
moon query hash <hash> [--json]
12
```
13

14
**Arguments:**
15
- `hash` (required) - The hash identifier to inspect
16

17
**Options:**
18
- `--json` - Output the hash manifest in JSON format
19

20
**Usage Examples:**
21

22
```bash
23
# Inspect a specific hash
24
moon query hash abc123def456
25

26
# Get hash details as JSON
27
moon query hash abc123def456 --json
28
```
29

30
**Sample Output:**
31
```
32
Hash: abc123def456
33
Target: my-app:build
34
Inputs:
35
  - src/index.ts (hash: def789)
36
  - package.json (hash: ghi012)
37
  - tsconfig.json (hash: jkl345)
38
Environment:
39
  NODE_ENV: production
40
  BUILD_MODE: release
41
Created: 2024-01-15 14:30:25 UTC
42
```
43

44
### Compare Hash Differences
45

46
Compare two hashes to understand what changed between builds or cache entries.
47

48
```bash { .api }
49
moon query hash-diff <left> <right> [--json]
50
```
51

52
**Arguments:**
53
- `left` (required) - Base hash to compare against
54
- `right` (required) - Target hash to compare with
55

56
**Options:**
57
- `--json` - Output the difference information in JSON format
58

59
**Usage Examples:**
60

61
```bash
62
# Compare two hashes
63
moon query hash-diff abc123 def456
64

65
# Get diff as JSON
66
moon query hash-diff abc123 def456 --json
67
```
68

69
**Sample Output:**
70
```
71
Hash Diff: abc123 -> def456
72

73
Changed Files:
74
  + src/utils.ts (new file)
75
  ~ src/index.ts (modified)
76
  - src/legacy.ts (deleted)
77

78
Environment Changes:
79
  NODE_ENV: development -> production
80
  + BUILD_TARGET: es2022
81

82
Dependencies:
83
  ~ shared-utils:build (hash changed)
84
```
85

86
### Query Projects
87

88
Search and filter projects within the workspace based on various criteria.
89

90
```bash { .api }
91
moon query projects [query] [--alias <ALIAS>] [--affected] [--downstream <SCOPE>] [--id <ID>] [--json] [--language <LANG>] [--layer <LAYER>] [--source <SOURCE>] [--stack <STACK>] [--tags <TAGS>] [--tasks <TASKS>] [--upstream <SCOPE>]
92
```
93

94
**Arguments:**
95
- `query` (optional) - Filter projects using a query expression
96

97
**Options:**
98
- `--alias <ALIAS>` - Filter projects matching this alias pattern
99
- `--affected` - Filter projects affected by touched files
100
- `--downstream <SCOPE>` - Include downstream dependents (direct|all)
101
- `--id <ID>` - Filter projects matching this ID pattern
102
- `--json` - Output project list in JSON format
103
- `--language <LANG>` - Filter projects by programming language
104
- `--layer <LAYER>` - Filter projects by architectural layer
105
- `--source <SOURCE>` - Filter projects by source path pattern
106
- `--stack <STACK>` - Filter projects by technology stack
107
- `--tags <TAGS>` - Filter projects with specific tags (comma-separated)
108
- `--tasks <TASKS>` - Filter projects that have specific tasks
109
- `--upstream <SCOPE>` - Include upstream dependencies (direct|all)
110

111
**Usage Examples:**
112

113
```bash
114
# List all projects
115
moon query projects
116

117
# Find projects by language
118
moon query projects --language typescript
119

120
# Find affected projects
121
moon query projects --affected
122

123
# Find projects with specific tags
124
moon query projects --tags "frontend,react"
125

126
# Find projects with specific tasks
127
moon query projects --tasks "build,test"
128

129
# Complex query with multiple filters
130
moon query projects --language typescript --stack node --affected
131

132
# Include downstream dependents
133
moon query projects --id my-app --downstream all
134

135
# Get results as JSON
136
moon query projects --json
137
```
138

139
### Query Tasks
140

141
List and filter tasks across the workspace based on various criteria.
142

143
```bash { .api }
144
moon query tasks [query] [--affected] [--command <COMMAND>] [--downstream <SCOPE>] [--id <ID>] [--json] [--project <PROJECT>] [--script <SCRIPT>] [--toolchain <TOOLCHAIN>] [--type <TYPE>] [--upstream <SCOPE>]
145
```
146

147
**Arguments:**
148
- `query` (optional) - Filter tasks using a query expression
149

150
**Options:**
151
- `--affected` - Filter tasks affected by touched files
152
- `--command <COMMAND>` - Filter tasks with specific command pattern
153
- `--downstream <SCOPE>` - Include downstream dependents (direct|all)
154
- `--id <ID>` - Filter tasks matching this ID pattern
155
- `--json` - Output task list in JSON format
156
- `--project <PROJECT>` - Filter tasks belonging to specific project
157
- `--script <SCRIPT>` - Filter tasks with specific script pattern
158
- `--toolchain <TOOLCHAIN>` - Filter tasks by toolchain (node, rust, etc.)
159
- `--type <TYPE>` - Filter tasks by type (build, test, lint, etc.)
160
- `--upstream <SCOPE>` - Include upstream dependencies (direct|all)
161

162
**Usage Examples:**
163

164
```bash
165
# List all tasks
166
moon query tasks
167

168
# Find build tasks
169
moon query tasks --type build
170

171
# Find tasks in specific project
172
moon query tasks --project my-app
173

174
# Find affected tasks
175
moon query tasks --affected
176

177
# Find tasks by command pattern
178
moon query tasks --command "*webpack*"
179

180
# Find Node.js tasks
181
moon query tasks --toolchain node
182

183
# Include task dependencies
184
moon query tasks --id build --upstream all
185

186
# Complex filtering
187
moon query tasks --type test --affected --json
188
```
189

190
### Query Touched Files
191

192
Identify files that have changed between Git revisions for affected project detection.
193

194
```bash { .api }
195
moon query touched-files [--base <REF>] [--default-branch] [--head <REF>] [--json] [--local] [--remote] [--status <STATUS>]
196
```
197

198
**Options:**
199
- `--base <REF>` - Base branch, commit, or revision to compare against
200
- `--default-branch` - When on default branch, compare against previous revision
201
- `--head <REF>` - Current branch, commit, or revision to compare with
202
- `--json` - Output file list in JSON format
203
- `--local` - Use local Git state instead of remote
204
- `--remote` - Use remote Git state instead of local
205
- `--status <STATUS>` - Filter files by status (added, modified, deleted, renamed)
206

207
**Usage Examples:**
208

209
```bash
210
# Show touched files since main branch
211
moon query touched-files --base main
212

213
# Compare specific commits
214
moon query touched-files --base abc123 --head def456
215

216
# Show only modified files
217
moon query touched-files --status modified
218

219
# Use local changes only
220
moon query touched-files --local
221

222
# Get output as JSON
223
moon query touched-files --json
224

225
# Compare against previous commit on default branch
226
moon query touched-files --default-branch
227
```
228

229
## Query Expressions
230

231
Moon supports advanced query expressions for filtering:
232

233
```bash
234
# Language-based queries
235
moon query projects --language="typescript || javascript"
236

237
# Tag-based queries  
238
moon query projects --tags="frontend && !legacy"
239

240
# Path-based queries
241
moon query projects --source="apps/** || packages/ui-*"
242

243
# Complex task queries
244
moon query tasks "type=build && project~apps/*"
245
```
246

247
## Output Formats
248

249
### JSON Output
250
All query commands support `--json` for programmatic use:
251

252
```bash
253
moon query projects --json | jq '.[] | select(.language == "typescript")'
254
```
255

256
### Formatted Output
257
Default output is human-readable:
258

259
```
260
Projects (3 found):
261
  my-app              apps/my-app              typescript  application
262
  shared-utils        packages/shared-utils    typescript  library  
263
  ui-components       packages/ui-components   typescript  library
264
```
265

266
## Integration with Other Commands
267

268
Query results can be used with other moon commands:
269

270
```bash
271
# Run tasks for affected projects
272
AFFECTED=$(moon query projects --affected --json | jq -r '.[].id')
273
moon run $AFFECTED:build
274

275
# Check specific language projects
276
moon query projects --language rust | xargs moon check
277

278
# Run tests for touched projects
279
moon query projects --affected | xargs -I {} moon run {}:test
280
```
281

282
## Performance Analysis
283

284
Use queries to analyze workspace performance:
285

286
```bash
287
# Find slow tasks
288
moon query tasks --json | jq 'sort_by(.avgDuration) | reverse | .[0:10]'
289

290
# Analyze cache hit rates
291
moon query hash --json | jq '.cacheStats'
292

293
# Find dependency bottlenecks
294
moon query projects --downstream all --json | jq 'group_by(.dependents | length)'
295
```