@wildshard/upload 0.0.0 → 0.4.0
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.
- package/package.json +26 -8
- package/src/cli/account/account.ts +199 -0
- package/src/cli/account/command.ts +193 -0
- package/src/cli/account/key.ts +154 -0
- package/src/cli/args.ts +100 -0
- package/src/cli/audio/audio.ts +39 -0
- package/src/cli/delete/delete.ts +258 -0
- package/src/cli/hero/hero.ts +163 -0
- package/src/cli/hero/scene-card.ts +46 -0
- package/src/cli/hero/stamp.ts +300 -0
- package/src/cli/report.ts +20 -0
- package/src/cli/shardfile/command.ts +49 -0
- package/src/cli/shardfile/shardfile.ts +192 -0
- package/src/cli/upload/api.ts +286 -0
- package/src/cli/upload/command.ts +239 -0
- package/src/cli/upload/completion.ts +80 -0
- package/src/cli/upload/compress.ts +55 -0
- package/src/cli/upload/hero-gate.ts +208 -0
- package/src/cli/upload/hero.ts +62 -0
- package/src/cli/upload/image-size.ts +89 -0
- package/src/cli/upload/placement.ts +132 -0
- package/src/cli/upload/provenance.ts +204 -0
- package/src/cli/upload/signature.ts +39 -0
- package/src/cli/upload/status-body.ts +41 -0
- package/src/cli/upload/status.ts +176 -0
- package/src/cli/upload/upload.ts +298 -0
- package/src/cli/upload/validate.ts +92 -0
- package/src/cli/upload/wire.ts +189 -0
- package/src/sharddev/draft.ts +11 -0
- package/src/sharddev/refusals.ts +329 -0
- package/src/sharddev/shardSource.ts +75 -0
- package/README.md +0 -3
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
import { installFormatHook } from '@wildshard/format/formatHook'
|
|
2
|
+
import {
|
|
3
|
+
array,
|
|
4
|
+
intersect,
|
|
5
|
+
literal,
|
|
6
|
+
nullable,
|
|
7
|
+
number,
|
|
8
|
+
object,
|
|
9
|
+
optional,
|
|
10
|
+
picklist,
|
|
11
|
+
string,
|
|
12
|
+
tuple,
|
|
13
|
+
unknown,
|
|
14
|
+
variant,
|
|
15
|
+
} from 'valibot'
|
|
16
|
+
|
|
17
|
+
import type { UploadResult } from '@wildshard/format/uploadWire'
|
|
18
|
+
import type { GenericSchema } from 'valibot'
|
|
19
|
+
|
|
20
|
+
// The replies `sharddev upload` reads from api-server (J61, J96), from
|
|
21
|
+
// format, which both depend on (J27). A wire change reaches both through a
|
|
22
|
+
// tag, and the upload fails on the parse rather than guess. Format ships raw
|
|
23
|
+
// .ts, so it loads here, behind the hook, and not by a static import.
|
|
24
|
+
|
|
25
|
+
installFormatHook()
|
|
26
|
+
|
|
27
|
+
const wire = await import('@wildshard/format/uploadWire')
|
|
28
|
+
|
|
29
|
+
const {
|
|
30
|
+
ErrorBodySchema,
|
|
31
|
+
ShardfileListSchema,
|
|
32
|
+
UploadResultSchema,
|
|
33
|
+
DirectUploadTicketSchema,
|
|
34
|
+
} = wire
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* SA30's `placement` (meta SHARD-AUTHORING, J314): the cell a new shard
|
|
38
|
+
* got and the channels whose grid now has it, or why it got none. Absent
|
|
39
|
+
* while api-server's `GRID_AUTOPLACE` is off, and for a shard not new.
|
|
40
|
+
*/
|
|
41
|
+
type Placement =
|
|
42
|
+
| Readonly<{
|
|
43
|
+
placed: true
|
|
44
|
+
cell: readonly [number, number]
|
|
45
|
+
channels: readonly string[]
|
|
46
|
+
}>
|
|
47
|
+
| Readonly<{ placed: false; reason: string }>
|
|
48
|
+
|
|
49
|
+
const CellSchema = tuple([number(), number()])
|
|
50
|
+
|
|
51
|
+
const PlacedSchema = object({
|
|
52
|
+
placed: literal(true),
|
|
53
|
+
cell: CellSchema,
|
|
54
|
+
channels: array(string()),
|
|
55
|
+
})
|
|
56
|
+
|
|
57
|
+
const NotPlacedSchema = object({ placed: literal(false), reason: string() })
|
|
58
|
+
|
|
59
|
+
const PlacementSchema: GenericSchema<Placement> = variant('placed', [
|
|
60
|
+
PlacedSchema,
|
|
61
|
+
NotPlacedSchema,
|
|
62
|
+
])
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* The J275 commit's answer (API-CLOUDFLARE AC6, AC16): format's
|
|
66
|
+
* `UploadResult` plus the shard version, the API's format version and the
|
|
67
|
+
* migrations that ran. Format's wire predates them, so sharddev reads the
|
|
68
|
+
* three itself until a format tag carries them.
|
|
69
|
+
*/
|
|
70
|
+
const UploadStateSchema = picklist([
|
|
71
|
+
'checked',
|
|
72
|
+
'cooking',
|
|
73
|
+
'staged',
|
|
74
|
+
'live',
|
|
75
|
+
'refused',
|
|
76
|
+
'stalled',
|
|
77
|
+
])
|
|
78
|
+
type UploadState = (typeof UploadStateSchema.options)[number]
|
|
79
|
+
|
|
80
|
+
interface CommitAnswer extends UploadResult {
|
|
81
|
+
readonly uploadId?: string | undefined
|
|
82
|
+
readonly status?: UploadState | undefined
|
|
83
|
+
readonly version: string
|
|
84
|
+
readonly formatVersion: string
|
|
85
|
+
readonly migrations: readonly unknown[]
|
|
86
|
+
/** UP2's echo of the channel and the versions; absent before it. */
|
|
87
|
+
readonly channel?: string | null | undefined
|
|
88
|
+
readonly engine?: string | null | undefined
|
|
89
|
+
readonly sharddev?: string | null | undefined
|
|
90
|
+
readonly shardFormat?: string | null | undefined
|
|
91
|
+
/**
|
|
92
|
+
* SA30's grid step, read by placement.ts against `PlacementSchema`: the
|
|
93
|
+
* commit is recorded by now, so a shape the CLI can't read never fails
|
|
94
|
+
* the upload. Absent while placement is off.
|
|
95
|
+
*/
|
|
96
|
+
readonly placement?: unknown
|
|
97
|
+
/** DEL7: true when the commit brought a deleted shard back (preview only). */
|
|
98
|
+
readonly revived?: unknown
|
|
99
|
+
/** Why no pointer moves on the upload's channel yet (meta STAGING-BUGBASH SB35): a format above the channel's. */
|
|
100
|
+
readonly held?: string | undefined
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
const MigrationsSchema = array(unknown())
|
|
104
|
+
|
|
105
|
+
/** A string the API may leave out, or send as null. */
|
|
106
|
+
const EchoSchema = optional(nullable(string()))
|
|
107
|
+
|
|
108
|
+
const CommitFieldsSchema = object({
|
|
109
|
+
uploadId: optional(string()),
|
|
110
|
+
status: optional(UploadStateSchema),
|
|
111
|
+
version: string(),
|
|
112
|
+
formatVersion: string(),
|
|
113
|
+
migrations: MigrationsSchema,
|
|
114
|
+
channel: EchoSchema,
|
|
115
|
+
engine: EchoSchema,
|
|
116
|
+
sharddev: EchoSchema,
|
|
117
|
+
shardFormat: EchoSchema,
|
|
118
|
+
placement: optional(unknown()),
|
|
119
|
+
revived: optional(unknown()),
|
|
120
|
+
held: optional(string()),
|
|
121
|
+
})
|
|
122
|
+
|
|
123
|
+
const CommitAnswerSchema: GenericSchema<CommitAnswer> = intersect([
|
|
124
|
+
UploadResultSchema,
|
|
125
|
+
CommitFieldsSchema,
|
|
126
|
+
])
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* `GET /api/catalogue`, as far as the hero pre-check reads it: each slug's
|
|
130
|
+
* newest version and, once UP4 is live, its hero digest.
|
|
131
|
+
*/
|
|
132
|
+
interface CatalogueShard {
|
|
133
|
+
readonly slug: string
|
|
134
|
+
readonly version?: string | null | undefined
|
|
135
|
+
readonly heroHash?: string | null | undefined
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const CatalogueShardSchema = object({
|
|
139
|
+
slug: string(),
|
|
140
|
+
version: EchoSchema,
|
|
141
|
+
heroHash: EchoSchema,
|
|
142
|
+
})
|
|
143
|
+
|
|
144
|
+
const CatalogueSchema: GenericSchema<{
|
|
145
|
+
readonly shards: readonly CatalogueShard[]
|
|
146
|
+
}> = object({ shards: array(CatalogueShardSchema) })
|
|
147
|
+
|
|
148
|
+
interface UploadStatus {
|
|
149
|
+
readonly uploadId: string
|
|
150
|
+
readonly hash: string
|
|
151
|
+
readonly status: UploadState
|
|
152
|
+
readonly createdAt: number
|
|
153
|
+
readonly updatedAt: number
|
|
154
|
+
readonly report?: unknown
|
|
155
|
+
readonly build?: string | undefined
|
|
156
|
+
readonly placement?: unknown
|
|
157
|
+
}
|
|
158
|
+
const UploadStatusSchema: GenericSchema<UploadStatus> = object({
|
|
159
|
+
uploadId: string(),
|
|
160
|
+
hash: string(),
|
|
161
|
+
status: UploadStateSchema,
|
|
162
|
+
createdAt: number(),
|
|
163
|
+
updatedAt: number(),
|
|
164
|
+
report: optional(unknown()),
|
|
165
|
+
build: optional(string()),
|
|
166
|
+
placement: optional(unknown()),
|
|
167
|
+
})
|
|
168
|
+
|
|
169
|
+
export {
|
|
170
|
+
type CatalogueShard,
|
|
171
|
+
type CommitAnswer,
|
|
172
|
+
type Placement,
|
|
173
|
+
type UploadStatus,
|
|
174
|
+
type UploadState,
|
|
175
|
+
UploadStatusSchema,
|
|
176
|
+
CatalogueSchema,
|
|
177
|
+
PlacementSchema,
|
|
178
|
+
CommitAnswerSchema,
|
|
179
|
+
DirectUploadTicketSchema,
|
|
180
|
+
ErrorBodySchema,
|
|
181
|
+
ShardfileListSchema,
|
|
182
|
+
UploadResultSchema,
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export type {
|
|
186
|
+
DirectUploadTicket,
|
|
187
|
+
ShardfileSummary,
|
|
188
|
+
UploadResult,
|
|
189
|
+
} from '@wildshard/format/uploadWire'
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
// QA-FEEDBACK 11-13 row 2 (J198, J259): `wildshard build` writes a draft shard file, `sdk: "0.2"`. Only `wildshard prepare`
|
|
2
|
+
// (J198, scripts/prepare-product.mjs) makes it `"0.3"`, and api-server refuses a draft at commit (422). So build and check
|
|
3
|
+
// warn, and upload refuses a draft before a byte is sent (rule `shardfile-draft` in refusals.ts).
|
|
4
|
+
|
|
5
|
+
/** The `sdk` marker of an unprepared draft; a prepared shard file says `0.3`. */
|
|
6
|
+
export const DRAFT_SDK = '0.2';
|
|
7
|
+
|
|
8
|
+
/** The words build and check warn with and upload refuses with. */
|
|
9
|
+
export function draftMessage(slug: string): string {
|
|
10
|
+
return `${slug} is an unprepared draft (sdk 0.2): api-server refuses a draft at commit, so prepare its folder and build it again before upload`;
|
|
11
|
+
}
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
// SHARD-AUTHORING SA21 (J317, "the first ten minutes"): every refusal an author can hit in `wildshard` (lint, build,
|
|
2
|
+
// validate, prove, the report card, new, the shard file build writes (and `pack`, its deprecated alias, SA3) and upload's
|
|
3
|
+
// local checks) names a stable rule id, a one-line fix and a
|
|
4
|
+
// GUIDE.md section. This file is the one table. GUIDE.md (SA13) writes one heading per anchor below, so
|
|
5
|
+
// `GUIDE.md#<anchor>` lands on it; refusals.test.ts fails a row with no fix or anchor and a wildshard lint rule with no
|
|
6
|
+
// row. Rule ids are stable: rename one only together with its GUIDE.md heading.
|
|
7
|
+
//
|
|
8
|
+
// SA41: shard-format's refusals carry a stable code (its `issue-codes.ts`, docs/VALIDATION-CODES.md): a validator's
|
|
9
|
+
// `error.code`, `PerformanceIssue.code`, `AudioFinding.code`. A coded refusal takes the row that lists its code, from any
|
|
10
|
+
// step; every one of shard-format's codes has a row (refusals.test.ts fails a new code with none). Words are the fallback
|
|
11
|
+
// for refusals with no code (sharddev's own, and shard-format's admitted-with-warning lines): a message takes the first
|
|
12
|
+
// row (in table order) for its step whose pattern matches, else its step's catch-all (the row with neither pattern nor
|
|
13
|
+
// codes), wherever that sits.
|
|
14
|
+
//
|
|
15
|
+
// Messages stay as the refusing code (and shard-format) words them: a row matches them, it never rewrites them.
|
|
16
|
+
import type { IssueCode } from '@wildshard/format/issue-codes';
|
|
17
|
+
|
|
18
|
+
/** The engine check's failure code (its `ShardfileCheckFailure['code']`, a plain string); named here so this table,
|
|
19
|
+
* which upload ships, never imports the engine (SDK-SPLIT SP2a). */
|
|
20
|
+
type CheckFailureCode = string;
|
|
21
|
+
|
|
22
|
+
/** Where a refusal came from: `check`'s five steps, then the other verbs. `shardfile` is the shard file build writes (SA3). */
|
|
23
|
+
export type RefusalStep = 'lint' | 'build' | 'validate' | 'prove' | 'report' | 'new' | 'update' | 'shardfile' | 'pack' | 'upload' | 'account' | 'delete';
|
|
24
|
+
/** One rule: its id, its GUIDE.md anchor, the fix, the shard-format codes it names (from any step) and the refusal
|
|
25
|
+
* messages it names in `steps` (neither: the step's catch-all). */
|
|
26
|
+
export interface RefusalRule {
|
|
27
|
+
readonly id: string;
|
|
28
|
+
readonly anchor: string;
|
|
29
|
+
readonly fix: string;
|
|
30
|
+
readonly steps: readonly RefusalStep[] | 'any';
|
|
31
|
+
readonly codes?: readonly (IssueCode | CheckFailureCode)[];
|
|
32
|
+
readonly match?: RegExp;
|
|
33
|
+
}
|
|
34
|
+
/** What a refusal carries besides its words: oxlint's code and help, or shard-format's issue code. */
|
|
35
|
+
export interface RefusalSource { readonly lint?: { readonly code: string | null; readonly help: string | null } | undefined; readonly code?: string | undefined }
|
|
36
|
+
/** What a printed refusal carries besides its message. `guide` is `GUIDE.md#<anchor>`. */
|
|
37
|
+
export interface RefusalNote { readonly rule: string; readonly fix: string; readonly guide: string }
|
|
38
|
+
|
|
39
|
+
/** The author's manual: shipped in the package and written into a project by `wildshard new` (SA13). */
|
|
40
|
+
export const GUIDE_FILE = 'GUIDE.md';
|
|
41
|
+
|
|
42
|
+
/** The refusals that are not lint rules, most specific first; each step has one catch-all (no `match`). */
|
|
43
|
+
export const REFUSAL_RULES: readonly RefusalRule[] = [
|
|
44
|
+
{ id: 'three-version', anchor: 'three-version', steps: 'any', match: /^\[three-version\] /,
|
|
45
|
+
fix: 'Install the three the sdk pins: pnpm add three@<the version named> --save-exact.' },
|
|
46
|
+
{ id: 'usage', anchor: 'usage', steps: 'any', match: /^usage: |^unknown (?:wildshard command|build flag|command)|unknown or incomplete build map flag|^Unknown schema root|accepts no pointer|^dev port must be|^invalid --port\b|^(?:validate|prove) requires a format-2 shard\.json or (?:shard source|author project)/u,
|
|
47
|
+
fix: 'Run `wildshard --help` and give the verb the arguments and flags it lists.' },
|
|
48
|
+
// new
|
|
49
|
+
{ id: 'new-target', anchor: 'new-target', steps: ['new'], match: /new requires a fresh directory and kebab-case slug/u,
|
|
50
|
+
fix: 'Name a folder that does not exist yet and a kebab-case slug: `wildshard new my-isle`.' },
|
|
51
|
+
{ id: 'new-template', anchor: 'new-template', steps: ['new'], match: /^new: (?:unknown template |--template blender is retired)/u,
|
|
52
|
+
fix: 'Leave out --template (sdk is the only one). blender is retired: write three.js scene source; Blender makes models.' },
|
|
53
|
+
{ id: 'new-refused', anchor: 'new-refused', steps: ['new'],
|
|
54
|
+
fix: 'Reinstall @wildshard/sdk (`pnpm install`); `new` copies the reference world shipped with it.' },
|
|
55
|
+
// update (SA28)
|
|
56
|
+
{ id: 'update-target', anchor: 'update-target', steps: ['update'], match: /^update: .* is not a shard repo/u,
|
|
57
|
+
fix: 'Run `wildshard update` in the repo `wildshard new` made, or name it: `wildshard update my-isle`.' },
|
|
58
|
+
{ id: 'update-pins-no-git', anchor: 'update-pins-no-git', steps: ['update'], match: /^update --pins: .* is not in a git repo with its package\.json committed/u,
|
|
59
|
+
fix: 'Put the shard repo in git and commit it (`git init`, `git add .`, `git commit`), then run `wildshard update --pins` again.' },
|
|
60
|
+
{ id: 'update-pins-dirty', anchor: 'update-pins-dirty', steps: ['update'], match: /^update --pins: .* has uncommitted changes/u,
|
|
61
|
+
fix: 'Commit or stash your changes, then run `wildshard update --pins` again.' },
|
|
62
|
+
{ id: 'update-pins', anchor: 'update-pins', steps: ['update'], match: /^update --pins: /u,
|
|
63
|
+
fix: 'Read the line above and the GUIDE.md heading for its case, fix that, then run `wildshard update --pins` again.' },
|
|
64
|
+
{ id: 'update-refused', anchor: 'update-refused', steps: ['update'],
|
|
65
|
+
fix: 'Reinstall @wildshard/sdk (`pnpm install`); `update` copies GUIDE.md and the skills shipped with it.' },
|
|
66
|
+
// build
|
|
67
|
+
{ id: 'source-file-missing', anchor: 'source-file-missing', steps: ['build', 'validate', 'prove'], match: /ENOENT: no such file or directory|Cannot resolve entry module/u,
|
|
68
|
+
fix: 'Check the path shown: the shard source or shard file folder, or a file it names, is not there.' },
|
|
69
|
+
{ id: 'source-import-missing', anchor: 'source-import-missing', steps: ['build'], match: /Could not resolve|Cannot find (?:module|package)|Failed to resolve import/u,
|
|
70
|
+
fix: 'Fix the import path, or add the package to package.json and run `pnpm install`.' },
|
|
71
|
+
{ id: 'json-syntax', anchor: 'json-syntax', steps: ['build'], match: /builtin:vite-json|while parsing|is not valid JSON|in JSON at position/u,
|
|
72
|
+
fix: 'Fix the JSON at the line and column shown: usually a missing comma, bracket or quote.' },
|
|
73
|
+
{ id: 'source-syntax', anchor: 'source-syntax', steps: ['build'], match: /builtin:vite-transform|SyntaxError|Unexpected token|Expected .* but found/u,
|
|
74
|
+
fix: 'Fix the syntax error at the file and line shown; your editor\'s TypeScript check marks it too.' },
|
|
75
|
+
{ id: 'config-default-export', anchor: 'config-default-export', steps: ['build'], match: /config has no default export|config generate export must be a build function|Author module has no exports/u,
|
|
76
|
+
fix: 'shard.config.ts must `export default generate;`, the function `wildshard new` wrote there.' },
|
|
77
|
+
{ id: 'config-file-access', anchor: 'config-file-access', steps: ['build'], match: /must use injected build capabilities for file access/u,
|
|
78
|
+
fix: 'Read files through the build context (`ctx.cached`), not node:fs, in code shard.config.ts imports.' },
|
|
79
|
+
{ id: 'project-folder-slug', anchor: 'project-folder-slug', steps: ['build'], match: /Manifest identity differs from its folder/u,
|
|
80
|
+
fix: 'Name the shard source folder after the shard\'s slug (data/identity.json), or change the slug to the folder\'s name.' },
|
|
81
|
+
{ id: 'source-schema', anchor: 'source-schema', steps: ['build'], match: /(?:^|: |; )Invalid [a-z]+: /u,
|
|
82
|
+
fix: 'Give the field at the path shown the value it expects; `wildshard schema shardfile <pointer>` prints its shape.' },
|
|
83
|
+
{ id: 'build-refused', anchor: 'build-refused', steps: ['build'],
|
|
84
|
+
fix: 'Fix what the message names (a file, field or generator) and run `wildshard check` again.' },
|
|
85
|
+
{ id: 'spawn-aware-radius', anchor: 'spawn-aware-radius', steps: 'any', codes: ['spawn-aware-radius'],
|
|
86
|
+
fix: 'Move the creature or player spawn farther apart, or reduce the brain awareRadius; an intentional arrival encounter can keep this warning.' },
|
|
87
|
+
// validate
|
|
88
|
+
{ id: 'validate-refused', anchor: 'validate-refused', steps: ['validate'],
|
|
89
|
+
fix: 'Rebuild with `wildshard check`; if a fresh build of unedited output still fails, report it with this message.' },
|
|
90
|
+
// prove
|
|
91
|
+
{ id: 'proof-tape-invalid', anchor: 'proof-tape-invalid', steps: ['prove'], match: /^[^\s/]+\.json: /u,
|
|
92
|
+
fix: 'Fix the proof tape (proof.json) where the message says; GUIDE.md "Proof tapes" and wildshard prove --help show its shape.' },
|
|
93
|
+
{ id: 'proof-failed', anchor: 'proof-failed', steps: ['prove'],
|
|
94
|
+
fix: 'Walk the quest in `wildshard dev`, then fix the data or the tape step that did not happen.' },
|
|
95
|
+
// the report card (budgets, J303): shard-format's PerformanceIssue codes
|
|
96
|
+
{ id: 'budget-unmeasured', anchor: 'budget-unmeasured', steps: 'any',
|
|
97
|
+
codes: ['perf-native-view-unmeasured', 'perf-native-resident-unmeasured', 'perf-script-sample-invalid', 'perf-script-samples-missing'],
|
|
98
|
+
fix: 'Run the shard long enough to measure: `wildshard check` measures it headlessly; native gameplay needs a browser proof.' },
|
|
99
|
+
{ id: 'budget-download', anchor: 'budget-download', steps: 'any',
|
|
100
|
+
codes: ['perf-library-download-budget', 'perf-critical-download-budget', 'perf-library-download', 'perf-critical-download', 'perf-tile-download', 'perf-far-download'],
|
|
101
|
+
fix: 'Shrink or drop assets on the named download tier, or move them to a later tier.' },
|
|
102
|
+
{ id: 'budget-draws', anchor: 'budget-draws', steps: 'any', codes: ['perf-tile-draws', 'perf-far-draws'],
|
|
103
|
+
fix: 'Merge meshes that share a material, or cut objects from the named view.' },
|
|
104
|
+
{ id: 'budget-triangles', anchor: 'budget-triangles', steps: 'any', codes: ['perf-tile-triangles', 'perf-far-triangles'],
|
|
105
|
+
fix: 'Lower the mesh detail (LODs, fewer props) in the named view.' },
|
|
106
|
+
{ id: 'budget-memory', anchor: 'budget-memory', steps: 'any', codes: ['perf-memory-target', 'perf-playing-memory', 'perf-loading-memory'],
|
|
107
|
+
fix: 'Cut texture size or count and mesh bytes until the named total fits.' },
|
|
108
|
+
{ id: 'budget-script-cpu', anchor: 'budget-script-cpu', steps: 'any', codes: ['perf-script-cpu'],
|
|
109
|
+
fix: 'Do less work per tick in behaviour scripts: spread it over ticks or run it on events.' },
|
|
110
|
+
{ id: 'budget-script-fuel', anchor: 'budget-script-fuel', steps: 'any', codes: ['perf-script-fuel'],
|
|
111
|
+
fix: 'Shorten the hottest behaviour script loops; fuel counts instructions per tick.' },
|
|
112
|
+
// TC-NE6: report's warnings, each a provisional or report-only cap over its limit; nothing refuses them yet.
|
|
113
|
+
{ id: 'budget-report-only', anchor: 'budget-report-only', steps: ['report'], match: /\(a report-only cap: upload still takes it\)$/u,
|
|
114
|
+
fix: 'Nothing blocks: a report-only cap warns until it is measured on devices. Bring the number under it if you can (GUIDE.md says which caps these are).' },
|
|
115
|
+
{ id: 'check-execution', anchor: 'check-execution', steps: 'any', codes: ['check-execution'],
|
|
116
|
+
fix: 'Fix the simulation or entry route named in the report, then run `wildshard check` again.' },
|
|
117
|
+
{ id: 'check-infrastructure', anchor: 'check-infrastructure', steps: 'any', codes: ['check-infrastructure'],
|
|
118
|
+
fix: 'Restore the missing runtime dependency or resource named in the report, then retry the check.' },
|
|
119
|
+
{ id: 'budget-over', anchor: 'budget-over', steps: ['report'],
|
|
120
|
+
fix: 'Run `wildshard check`: its report step names each budget over its limit and the row here for each.' },
|
|
121
|
+
// `Performance report refused` is sharddev's own words (cli.ts); the two codes are shard-format's preflight of the same.
|
|
122
|
+
{ id: 'budget-refused', anchor: 'budget-refused', steps: ['build', 'validate'], codes: ['declared-costs', 'performance-targets'], match: /Performance report refused/u,
|
|
123
|
+
fix: 'Run `wildshard check`: its report step names each budget over its limit and the row here for each.' },
|
|
124
|
+
// the shard file build writes (SA3; `pack` is its deprecated alias) and upload, before a byte is sent. `shardfile-draft` is
|
|
125
|
+
// a warning from build and check and a refusal from upload (draft.ts).
|
|
126
|
+
{ id: 'hero-stale', anchor: 'hero-stale', steps: ['shardfile', 'pack', 'upload'], match: /the hero (?:of .* is older than its content|of .* has no .* stamp)|the hero files of .* are not the ones stamped/u,
|
|
127
|
+
fix: 'Capture the hero again from a served build: `wildshard hero src/shards/<name> --base <url>`.' },
|
|
128
|
+
{ id: 'hero-not-in-product', anchor: 'hero-not-in-product', steps: ['shardfile', 'pack', 'upload'], match: /does not carry the captured hero/u,
|
|
129
|
+
fix: 'Build again after the hero capture: `wildshard build` writes a shard file that carries it.' },
|
|
130
|
+
{ id: 'hero-unchanged', anchor: 'hero-unchanged', steps: ['upload'], match: /the hero is unchanged since/u,
|
|
131
|
+
fix: 'Capture a new hero (`wildshard hero`), then build and upload again.' },
|
|
132
|
+
// HERO-GATE HG2 (Jake, 2026-11-17): upload, and api-server's commit, refuse a zone with no real hero
|
|
133
|
+
{ id: 'hero-missing', anchor: 'hero-missing', steps: ['upload'], match: /\[hero-(?:missing|generated)\]/u,
|
|
134
|
+
fix: 'Capture the hero from a served build: run `wildshard dev .`, then `wildshard hero <shard> --base <url>`, build and upload again.' },
|
|
135
|
+
{ id: 'hero-size', anchor: 'hero-size', steps: ['upload'], match: /\[hero-(?:image|size)\]/u,
|
|
136
|
+
fix: 'The hero is thumb 640x360, portrait 804x1626 and landscape 1600x900 PNG, JPEG or WebP: capture it again with `wildshard hero <shard> --base <url>`.' },
|
|
137
|
+
// the audio rules (AU5): `audio-refused` is upload's refusal of a red report; the rest are its findings, which build
|
|
138
|
+
// prints with their rows (red or amber, a build never refuses on them)
|
|
139
|
+
{ id: 'audio-refused', anchor: 'audio-refused', steps: 'any', codes: ['audio-refused'],
|
|
140
|
+
fix: 'Fix each red audio finding listed, or waive it in the shard\'s audio-waiver.json.' },
|
|
141
|
+
{ id: 'audio-unreadable', anchor: 'audio-unreadable', steps: 'any', codes: ['audio-unreadable'],
|
|
142
|
+
fix: 'Export the recording again as AAC-LC 48 kHz, mono or stereo, in an .m4a file: this one does not read as that.' },
|
|
143
|
+
{ id: 'audio-container', anchor: 'audio-container', steps: 'any', codes: ['audio-container'],
|
|
144
|
+
fix: 'Export the recording again as AAC-LC 48 kHz in an .m4a file, not WAV: its bytes are FLAC, AIFF, Ogg, MP3, WebM, CAF or unknown.' },
|
|
145
|
+
{ id: 'audio-encoding', anchor: 'audio-encoding', steps: 'any', codes: ['audio-strict-index', 'audio-wav', 'audio-sample-rate'],
|
|
146
|
+
fix: 'Encode the recording as AAC-LC at 48 kHz in an .m4a file; it plays as it is, but ships larger or less safely.' },
|
|
147
|
+
{ id: 'audio-duration', anchor: 'audio-duration', steps: 'any', codes: ['audio-duration'],
|
|
148
|
+
fix: 'Cut the recording under the maximum length the message gives, or split it in two.' },
|
|
149
|
+
{ id: 'audio-bitrate', anchor: 'audio-bitrate', steps: 'any', codes: ['audio-bitrate'],
|
|
150
|
+
fix: 'Encode the recording at a lower bitrate: the message gives the cap for its role and channels.' },
|
|
151
|
+
{ id: 'audio-budget', anchor: 'audio-budget', steps: 'any', codes: ['audio-budget-amber', 'audio-budget-red', 'audio-budget-waived'],
|
|
152
|
+
fix: 'Cut, shorten or re-encode recordings until the shard\'s own audio fits, or add a dated audio-waiver.json.' },
|
|
153
|
+
{ id: 'audio-waiver', anchor: 'audio-waiver', steps: 'any', codes: ['audio-waiver-invalid'],
|
|
154
|
+
fix: 'Fix audio-waiver.json: this shard\'s slug, a date not yet past, and at least the bytes its audio holds.' },
|
|
155
|
+
{ id: 'shardfile-draft', anchor: 'shardfile-draft', steps: ['shardfile', 'upload'], match: /is an unprepared draft \(sdk 0\.2\)/u,
|
|
156
|
+
fix: 'Run `wildshard prepare <folder>`, then `wildshard build <folder>`; a shard repo\'s `pack:shards` does both (WILDSHARD_PREPARATION_URL).' },
|
|
157
|
+
{ id: 'shardfile-link', anchor: 'shardfile-link', steps: ['shardfile', 'pack'], match: /not a regular file|link is refused/u,
|
|
158
|
+
fix: 'Replace links in the shard file folder with real files, then build again.' },
|
|
159
|
+
{ id: 'shardfile-folder-missing', anchor: 'shardfile-folder-missing', steps: ['shardfile', 'pack'], match: /(?:build|pack) needs a shard file folder|ENOENT/u,
|
|
160
|
+
fix: 'Build the shard source: `wildshard build <source>` writes public/shardfiles/<slug>.shardfile.' },
|
|
161
|
+
// shard-format's validator refusals (SA41's validate and stream codes), from validate, the shard file step or upload
|
|
162
|
+
{ id: 'shardfile-invalid', anchor: 'shardfile-invalid', steps: 'any', codes: ['archive-invalid'],
|
|
163
|
+
fix: 'Upload the shard file `wildshard build` wrote, unedited: the format checks refuse this one.' },
|
|
164
|
+
{ id: 'shardfile-index', anchor: 'shardfile-index', steps: 'any', codes: ['index-invalid'],
|
|
165
|
+
fix: 'Build again so shard.json is written for you; a hand-written shard.json must parse and fit the index schema.' },
|
|
166
|
+
{ id: 'shardfile-files', anchor: 'shardfile-files', steps: 'any', codes: ['file-mismatch', 'unlisted-file', 'source-hash', 'pack-invalid'],
|
|
167
|
+
fix: 'Build again: the folder\'s files differ from the ones shard.json lists, so never edit a built folder by hand.' },
|
|
168
|
+
{ id: 'shardfile-section', anchor: 'shardfile-section', steps: 'any', codes: ['section-invalid', 'shard-schema'],
|
|
169
|
+
fix: 'Give the field at the path shown the value it expects; `wildshard schema shardfile <pointer>` prints its shape.' },
|
|
170
|
+
{ id: 'shardfile-assets', anchor: 'shardfile-assets', steps: 'any',
|
|
171
|
+
codes: ['blob-invalid', 'server-file-invalid', 'ktx2-costs', 'asset-admission', 'cook-invalid', 'runtime-files'],
|
|
172
|
+
fix: 'Export the asset the message names again and build: its bytes do not match what the shard file declares.' },
|
|
173
|
+
{ id: 'shardfile-scripts', anchor: 'shardfile-scripts', steps: 'any', codes: ['script-side', 'script-admission'],
|
|
174
|
+
fix: 'Run each behaviour script only on the side its declaration allows, then build again.' },
|
|
175
|
+
{ id: 'shardfile-targets', anchor: 'shardfile-targets', steps: 'any', codes: ['world-targets'],
|
|
176
|
+
fix: 'Declare the item or quest the message names, or take it out of the world targets.' },
|
|
177
|
+
{ id: 'shardfile-stream', anchor: 'shardfile-stream', steps: 'any', codes: ['stream-cap', 'stream-miss', 'stream-changed'],
|
|
178
|
+
fix: 'Shrink the file or pack the message names under the streaming cap; if the file changed mid-read, upload again.' },
|
|
179
|
+
{ id: 'shardfile-refused', anchor: 'shardfile-refused', steps: ['shardfile', 'pack'],
|
|
180
|
+
fix: 'Build the shard source again with `wildshard build`: it writes and checks the shard file.' },
|
|
181
|
+
{ id: 'upload-shardfile-missing', anchor: 'upload-shardfile-missing', steps: ['upload'], match: /upload needs a shard ?file|ENOENT/u,
|
|
182
|
+
fix: 'Pass the shard file `wildshard build` wrote: `wildshard upload public/shardfiles/<slug>.shardfile --channel staging`.' },
|
|
183
|
+
{ id: 'upload-channel', anchor: 'upload-channel', steps: ['upload'], match: /upload needs --channel/u,
|
|
184
|
+
fix: 'Add `--channel staging` (try it there first) or `--channel prod`.' },
|
|
185
|
+
{ id: 'upload-credentials', anchor: 'upload-credentials', steps: ['upload'], match: /upload needs --server/u,
|
|
186
|
+
fix: 'Set WILDSHARD_API_URL in your shell, or pass --server.' },
|
|
187
|
+
// the account key (meta SHARD-DELETE DEL6): upload sends it on the ticket and the commit; account and whoami
|
|
188
|
+
{ id: 'account-key-missing', anchor: 'account-key-missing', steps: ['upload', 'account', 'delete'], match: /needs an account key|^no account key/u,
|
|
189
|
+
fix: 'Run `wildshard account <email>` once, or set WILDSHARD_API_KEY to your account key.' },
|
|
190
|
+
{ id: 'account-exists', anchor: 'account-exists', steps: ['account'], match: /already has an account/u,
|
|
191
|
+
fix: 'Use the key you saved for this email; a lost key needs an operator reset by the Wildshard team.' },
|
|
192
|
+
{ id: 'account-key-file', anchor: 'account-key-file', steps: ['account'], match: /already holds a key/u,
|
|
193
|
+
fix: 'Keep the key you have, or pass `--force` to replace the file; the old key keeps working.' },
|
|
194
|
+
{ id: 'account-refused', anchor: 'account-refused', steps: ['account'],
|
|
195
|
+
fix: 'Read the reason: a bad email is 400, and 429 means wait a minute and try again.' },
|
|
196
|
+
// delete (meta SHARD-DELETE DEL10): start, the typed slug, finalize; account-key-missing above covers no key
|
|
197
|
+
{ id: 'delete-not-confirmed', anchor: 'delete-not-confirmed', steps: ['delete'], match: /not confirmed: you typed/u,
|
|
198
|
+
fix: 'Nothing was deleted. Run `wildshard delete <slug>` again and type the slug exactly, or pass `--yes`.' },
|
|
199
|
+
{ id: 'delete-expired', anchor: 'delete-expired', steps: ['delete'], match: /waits for this confirm token/u,
|
|
200
|
+
fix: 'Nothing was deleted: run `wildshard delete <slug>` again and confirm within 10 minutes.' },
|
|
201
|
+
{ id: 'delete-not-owner', anchor: 'delete-not-owner', steps: ['delete'], match: /belongs to another account|only the admin token can delete|(?:start|finalize) answered 401:/u,
|
|
202
|
+
fix: 'Delete with the account key that first uploaded the shard; `wildshard whoami` shows which key you send.' },
|
|
203
|
+
{ id: 'delete-unknown', anchor: 'delete-unknown', steps: ['delete'], match: /(?:start|finalize) answered 40[04]:/u,
|
|
204
|
+
fix: 'Check the slug: the API has no shard by that name (the catalogue lists every live one).' },
|
|
205
|
+
{ id: 'delete-refused', anchor: 'delete-refused', steps: ['delete'],
|
|
206
|
+
fix: 'Read the reason: the API answered with what it wants, or the server is not https.' },
|
|
207
|
+
{ id: 'upload-level', anchor: 'upload-level', steps: ['upload'], match: /^invalid --level/u,
|
|
208
|
+
fix: 'Pass `--level` 0 to 11, or leave it out for the default.' },
|
|
209
|
+
{ id: 'upload-version', anchor: 'upload-version', steps: ['upload'], match: /pass --version X\.Y\.Z|^--version \S+ is not X\.Y\.Z/u,
|
|
210
|
+
fix: 'Set `version` (X.Y.Z) in the shard source\'s package.json, or pass `--version X.Y.Z`.' },
|
|
211
|
+
{ id: 'upload-commit', anchor: 'upload-commit', steps: ['upload'], match: /is not a git checkout|^--commit \S+ is not a full 40-hex sha/u,
|
|
212
|
+
fix: 'Upload from the shard repo\'s git checkout, or pass `--commit <sha>` (40 hex) of the bytes\' commit.' },
|
|
213
|
+
{ id: 'upload-uncommitted', anchor: 'upload-uncommitted', steps: ['upload'], match: /has uncommitted changes/u,
|
|
214
|
+
fix: 'Commit your changes, build again, then upload: the commit names the bytes.' },
|
|
215
|
+
{ id: 'upload-sdk-missing', anchor: 'upload-sdk-missing', steps: ['upload'], match: /is not installed at or above|\(.*package\.json\) is not X\.Y\.Z/u,
|
|
216
|
+
fix: 'Run `pnpm install` in the shard repo.' },
|
|
217
|
+
{ id: 'upload-refused', anchor: 'upload-refused', steps: ['upload'],
|
|
218
|
+
fix: 'Read the reason: a format refusal means build again (`wildshard build`); a server refusal names what it wants.' },
|
|
219
|
+
// lint, besides the rules below
|
|
220
|
+
{ id: 'lint-not-run', anchor: 'lint-not-run', steps: ['lint'], match: /^oxlint (?:did not run|exited|report has no)/u,
|
|
221
|
+
fix: 'Reinstall (`pnpm install`): the author lint runs the repo\'s oxlint, or the one that ships with @wildshard/sdk.' },
|
|
222
|
+
{ id: 'lint-refused', anchor: 'lint-refused', steps: ['lint'],
|
|
223
|
+
fix: 'Fix what the message names at the file and line shown.' },
|
|
224
|
+
];
|
|
225
|
+
|
|
226
|
+
/** Wildshard's lint rules an author's source can hit (`.oxlintrc.author.json`), with the fix for each. */
|
|
227
|
+
const LINT_FIXES: Readonly<Record<string, string>> = {
|
|
228
|
+
'wildshard-sdk/generator-imports': 'Import Wildshard code only through @wildshard/sdk\'s exports; copy what another shard has instead of importing it.',
|
|
229
|
+
'wildshard-sdk/no-hand-graph': 'Write the graph in TSL with graph() from @wildshard/sdk/materials; it compiles to the graph IR.',
|
|
230
|
+
'wildshard/engine-internal': 'Use the shard-facing SDK export instead of the game-only engine export.',
|
|
231
|
+
'wildshard/engine-sides': 'Keep client, server and shared code apart: import the shared module, not the other side\'s.',
|
|
232
|
+
'wildshard/engine-words': 'Move Wildshard words (shard and game names) out of engine code into content data.',
|
|
233
|
+
'wildshard/exec-max-buffer': 'Pass an explicit `maxBuffer` to the exec call that captures output.',
|
|
234
|
+
'wildshard/layer': 'Import downward through the public index; a shard never imports another shard.',
|
|
235
|
+
'wildshard/no-active-chunk': 'Read current content through the game layer, not the active chunk.',
|
|
236
|
+
'wildshard/no-active-singleton': 'Take the service from your context instead of the active singleton.',
|
|
237
|
+
'wildshard/no-authored-html': 'Set text with `textContent`, never HTML.',
|
|
238
|
+
'wildshard/no-base64': 'Keep binary content binary: ship the bytes as an asset, never base64.',
|
|
239
|
+
'wildshard/no-build-time-import': 'Runtime code must not import build-time code: move the shared part to a runtime module.',
|
|
240
|
+
'wildshard/no-client-plan-reflection': 'Pass data to the client feature; do not reflect into shard TypeScript.',
|
|
241
|
+
'wildshard/no-generated-import': 'Call the authoring function or read the built shard file folder, not a generated file.',
|
|
242
|
+
'wildshard/no-generated-json-import': 'Read generated JSON as data at build time, not with an import.',
|
|
243
|
+
'wildshard/no-global-listener-patch': 'Register listeners through your scope, not on globals.',
|
|
244
|
+
'wildshard/no-hook-chain': 'Subscribe to the typed event instead of chaining hooks.',
|
|
245
|
+
'wildshard/no-inline-ui-string': 'Put player-facing text in the shard\'s string table (data/text.json).',
|
|
246
|
+
'wildshard/no-level-identity': 'Move level and style choices into content data instead of branching on identity.',
|
|
247
|
+
'wildshard/no-module-mock': 'Test through a seam (pass the dependency in) instead of a module mock.',
|
|
248
|
+
'wildshard/no-production-test-import': 'Move what production needs out of the test module.',
|
|
249
|
+
'wildshard/no-raw-animation-mixer': 'Use the engine\'s animation API instead of a raw three.js mixer.',
|
|
250
|
+
'wildshard/no-raw-hud': 'Mount HUD through the numbered HUD slots your scope owns.',
|
|
251
|
+
'wildshard/no-raw-input': 'Read input through the input service, not DOM listeners.',
|
|
252
|
+
'wildshard/no-raw-random-time': 'Use the engine\'s seeded random and clock, not Math.random or Date.',
|
|
253
|
+
'wildshard/no-raw-save': 'Save through the saves service, not localStorage.',
|
|
254
|
+
'wildshard/no-raw-shader-patch': 'Patch shaders through the shader registry.',
|
|
255
|
+
'wildshard/no-reexport': 'Import from the module that defines the name; do not re-export it.',
|
|
256
|
+
'wildshard/no-renderer-type': 'Keep renderer types inside rendering code; pass plain data out.',
|
|
257
|
+
'wildshard/no-runtime-generator': 'Import generators only from shard.config.ts, bakers and other generators.',
|
|
258
|
+
'wildshard/no-runtime-in-build': 'Build code must not import runtime code: share a plain data module instead.',
|
|
259
|
+
'wildshard/no-shard-branch': 'Move the shard-specific choice into the shard\'s data or plugin.',
|
|
260
|
+
'wildshard/no-shard-host-callback': 'Give host APIs data, not TypeScript callbacks.',
|
|
261
|
+
'wildshard/no-shard-runtime': 'Keep the shard to authoring and declarations: gameplay goes in behaviour/ scripts.',
|
|
262
|
+
'wildshard/no-url-switch': 'Drop the URL query switch; read settings from the shard\'s data.',
|
|
263
|
+
'wildshard/public-index': 'Import the package by its public export, not a file path inside it.',
|
|
264
|
+
'wildshard/runtime-commons': 'Runtime code must not import build-time commons; use the runtime export.',
|
|
265
|
+
'wildshard/runtime-performance': 'Bound the work: no per-frame allocation, raw rendering, DOM, timers or fetch.',
|
|
266
|
+
'wildshard/runtime-standalone': 'Runtime code must stand alone: import only the runtime surface.',
|
|
267
|
+
'wildshard/sdk-no-facade': 'Import the SDK\'s own export; do not alias a game or engine binding.',
|
|
268
|
+
'wildshard/shard-engine-imports': 'Import @wildshard/sdk, not engine internals, from shard source.',
|
|
269
|
+
'wildshard/shard-game-imports': 'Import @wildshard/sdk, not the game, from shard source.',
|
|
270
|
+
'wildshard/shard-game-plugins': 'Import only the game plugin exports that define your runtime.',
|
|
271
|
+
'wildshard/shard-names': 'Name no particular shard outside its own folder.',
|
|
272
|
+
'wildshard/shard-sandbox': 'Keep services, globals, settings and assets inside the shard\'s context.',
|
|
273
|
+
'wildshard/shard-services': 'Get engine services from ShardContext.',
|
|
274
|
+
'wildshard/sim-no-render': 'Keep rendering out of code the headless simulation imports.',
|
|
275
|
+
};
|
|
276
|
+
|
|
277
|
+
/** Every wildshard lint rule as a row: id is the config's `plugin/rule`, anchor `lint-<rule>`. */
|
|
278
|
+
export const LINT_RULES: readonly RefusalRule[] = Object.entries(LINT_FIXES).map(([id, fix]) => ({ id, fix, steps: ['lint'], anchor: `lint-${id.slice(id.indexOf('/') + 1)}` }));
|
|
279
|
+
/** Any other lint rule (oxlint's own, by its code): oxlint's help when it gives one. */
|
|
280
|
+
export const LINT_OTHER: RefusalRule = { id: 'lint-other', anchor: 'lint-rules', steps: ['lint'],
|
|
281
|
+
fix: 'Fix what the rule names at the file and line shown; `oxlint --rules` lists it.' };
|
|
282
|
+
|
|
283
|
+
/** Every anchor GUIDE.md must have a heading for (SA13). */
|
|
284
|
+
export const REFUSAL_ANCHORS: readonly string[] = [...REFUSAL_RULES, ...LINT_RULES, LINT_OTHER].map(rule => rule.anchor);
|
|
285
|
+
|
|
286
|
+
const note = (rule: RefusalRule, id = rule.id, fix = rule.fix): RefusalNote => ({ rule: id, fix, guide: `${GUIDE_FILE}#${rule.anchor}` });
|
|
287
|
+
const appliesTo = (rule: RefusalRule, step: RefusalStep): boolean => rule.steps === 'any' || rule.steps.includes(step);
|
|
288
|
+
const LINT_BY_ID = new Map(LINT_RULES.map(rule => [rule.id, rule]));
|
|
289
|
+
|
|
290
|
+
/** oxlint's code (`wildshard(no-raw-save)`) as the config spells the rule (`wildshard/no-raw-save`). */
|
|
291
|
+
export function lintRuleId(code: string): string {
|
|
292
|
+
const match = /^([\w-]+)\(([\w/-]+)\)$/u.exec(code);
|
|
293
|
+
return match === null ? code : `${match[1] ?? ''}/${match[2] ?? ''}`;
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
/** shard-format's codes, each to the row that names it. */
|
|
297
|
+
const RULE_BY_CODE: ReadonlyMap<string, RefusalRule> = new Map(REFUSAL_RULES.flatMap(row => (row.codes ?? []).map(code => [code, row] as const)));
|
|
298
|
+
|
|
299
|
+
/** The shard-format code a refusal carries (SA41): on the error or, when sharddev wrapped it, on a cause beneath it. */
|
|
300
|
+
export function refusalCode(error: unknown): string | undefined {
|
|
301
|
+
for (let at = error, depth = 0; typeof at === 'object' && at !== null && depth < 8; depth += 1) {
|
|
302
|
+
const code: unknown = 'code' in at ? at.code : undefined;
|
|
303
|
+
if (typeof code === 'string' && RULE_BY_CODE.has(code)) return code;
|
|
304
|
+
at = 'cause' in at ? at.cause : undefined;
|
|
305
|
+
}
|
|
306
|
+
return undefined;
|
|
307
|
+
}
|
|
308
|
+
|
|
309
|
+
/** The rule, fix and guide link for a refusal message from `step`. A known lint rule's code wins over the message, and
|
|
310
|
+
* so does a shard-format code (SA41); the message's words are the fallback. */
|
|
311
|
+
export function refusalNote(step: RefusalStep, message: string, source: RefusalSource = {}): RefusalNote {
|
|
312
|
+
const { lint, code } = source;
|
|
313
|
+
if (lint?.code !== undefined && lint.code !== null) {
|
|
314
|
+
const id = lintRuleId(lint.code), known = LINT_BY_ID.get(id);
|
|
315
|
+
const help = lint.help?.split('\n')[0]?.trim() ?? '';
|
|
316
|
+
return known === undefined ? note(LINT_OTHER, id, help === '' ? LINT_OTHER.fix : help) : note(known);
|
|
317
|
+
}
|
|
318
|
+
const coded = code === undefined ? undefined : RULE_BY_CODE.get(code);
|
|
319
|
+
if (coded !== undefined) return note(coded);
|
|
320
|
+
const rule = REFUSAL_RULES.find(row => appliesTo(row, step) && row.match?.test(message) === true)
|
|
321
|
+
?? REFUSAL_RULES.find(row => appliesTo(row, step) && row.match === undefined && row.codes === undefined);
|
|
322
|
+
if (rule === undefined) throw new Error(`no refusal rule for step ${step}`);
|
|
323
|
+
return note(rule);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
/** The line printed under a refusal: `[rule] fix: ... (GUIDE.md#anchor)`. */
|
|
327
|
+
export function refusalHint(refusal: RefusalNote): string {
|
|
328
|
+
return `[${refusal.rule}] fix: ${refusal.fix} (${refusal.guide})`;
|
|
329
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- The CLI finds a shard source on disk from the path it was given.
|
|
2
|
+
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
|
3
|
+
// oxlint-disable-next-line import/no-nodejs-modules -- Resolve the shard source beneath the given repo path.
|
|
4
|
+
import { basename, dirname, resolve } from 'node:path';
|
|
5
|
+
|
|
6
|
+
/** The build entry that marks a folder as a shard source. */
|
|
7
|
+
export const SHARD_CONFIG = 'shard.config.ts';
|
|
8
|
+
/** A hand-written shard source (`new --template blender`, J314) is a shard file folder held by hand: its index. */
|
|
9
|
+
export const SHARD_INDEX = 'shard.json';
|
|
10
|
+
|
|
11
|
+
/** A hand-written shard source: a shard file folder (`shard.json`) a person edits, with no `shard.config.ts` to build. */
|
|
12
|
+
export function isHandwrittenSource(source: string): boolean {
|
|
13
|
+
return existsSync(resolve(source, SHARD_INDEX)) && !existsSync(resolve(source, SHARD_CONFIG));
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* SA16 (J317): the shard source a path names. A folder with `shard.config.ts` is one; a single-shard repo keeps its
|
|
18
|
+
* source at `src/` (or a hand-written shard file folder there, `--template blender`); a multi-shard repo keeps `src/shards/<slug>/`, so its repo root names one only when it holds exactly
|
|
19
|
+
* one. Any other path comes back unchanged, so the verb refuses it as it always has.
|
|
20
|
+
*/
|
|
21
|
+
export function findShardSource(path: string): string {
|
|
22
|
+
const given = resolve(path);
|
|
23
|
+
if (existsSync(resolve(given, SHARD_CONFIG))) return given;
|
|
24
|
+
if (existsSync(resolve(given, 'src', SHARD_CONFIG)) || isHandwrittenSource(resolve(given, 'src'))) return resolve(given, 'src');
|
|
25
|
+
const shards = resolve(given, 'src/shards');
|
|
26
|
+
if (!existsSync(shards)) return given;
|
|
27
|
+
const found = readdirSync(shards, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(resolve(shards, entry.name, SHARD_CONFIG)));
|
|
28
|
+
return found.length === 1 && found[0] !== undefined ? resolve(shards, found[0].name) : given;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** A shard source at a single-shard repo's `src/` (J317), rather than its own folder or `src/shards/<slug>/`. */
|
|
32
|
+
export function isRepoSource(source: string): boolean {
|
|
33
|
+
return basename(source) === 'src' && (existsSync(resolve(source, SHARD_CONFIG)) || isHandwrittenSource(source));
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* SA44: the repo a shard source sits in, where its `public/` and `out/` are. The two layouts name it: a single-shard
|
|
38
|
+
* repo's `src/` is one folder below it and a multi-shard repo's `src/shards/<slug>/` three. Any other source takes the
|
|
39
|
+
* nearest folder above it with a `package.json` or `.git`, else its own parent. Layout comes first, so a fixture under
|
|
40
|
+
* some repo's `tmp/` is its own repo, as it always was.
|
|
41
|
+
*/
|
|
42
|
+
export function shardRepoRoot(source: string): string {
|
|
43
|
+
const given = resolve(source), parent = dirname(given);
|
|
44
|
+
if (isRepoSource(given)) return parent;
|
|
45
|
+
if (basename(parent) === 'shards' && basename(dirname(parent)) === 'src') return dirname(dirname(parent));
|
|
46
|
+
for (let at = given; ; at = dirname(at)) {
|
|
47
|
+
if (existsSync(resolve(at, 'package.json')) || existsSync(resolve(at, '.git'))) return at;
|
|
48
|
+
if (dirname(at) === at) return given;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Where build output lands for a shard source: the repo root for `src/`, the source folder itself otherwise. */
|
|
53
|
+
export function shardOutputRoot(source: string): string {
|
|
54
|
+
return isRepoSource(source) ? dirname(source) : source;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* The folder name build checks a manifest's slug against (`project-folder-slug`). A `src/` source names no slug by its
|
|
59
|
+
* folder, so its `manifest.json` slug is the folder; any other source is named by its folder, as before.
|
|
60
|
+
*/
|
|
61
|
+
export function shardFolderName(source: string): string {
|
|
62
|
+
if (!isRepoSource(source)) return basename(source);
|
|
63
|
+
const index = resolve(source, SHARD_INDEX);
|
|
64
|
+
if (isHandwrittenSource(source)) {
|
|
65
|
+
const parsed: unknown = JSON.parse(readFileSync(index, 'utf8'));
|
|
66
|
+
if (typeof parsed === 'object' && parsed !== null && 'identity' in parsed && typeof parsed.identity === 'object' && parsed.identity !== null
|
|
67
|
+
&& 'slug' in parsed.identity && typeof parsed.identity.slug === 'string') return parsed.identity.slug;
|
|
68
|
+
}
|
|
69
|
+
const manifest = resolve(source, 'manifest.json');
|
|
70
|
+
if (existsSync(manifest)) {
|
|
71
|
+
const parsed: unknown = JSON.parse(readFileSync(manifest, 'utf8'));
|
|
72
|
+
if (typeof parsed === 'object' && parsed !== null && 'slug' in parsed && typeof parsed.slug === 'string') return parsed.slug;
|
|
73
|
+
}
|
|
74
|
+
return basename(dirname(source));
|
|
75
|
+
}
|
package/README.md
DELETED