@exodus/stasis-core 1.0.0-beta.2 → 1.0.0-beta.4

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/src/util.js CHANGED
@@ -1,84 +1,44 @@
1
+ import { isUtf8 } from 'node:buffer'
1
2
  import * as fs from 'node:fs'
2
- import { basename, isAbsolute, join, posix, relative } from 'node:path'
3
-
4
- // Snapshot realpathSync at module-eval, BEFORE `stasis run --fs` patches fs.realpathSync.
5
- // The patch + syncBuiltinESMExports() repoint a LIVE `import { realpathSync }` binding to the
6
- // bundle-serving wrapper, which (by design, for user code) does NOT throw ENOENT for a
7
- // recorded-but-absent path -- which would silently defeat assertRealPathWithinBase's reliance
8
- // on that throw (see its comment). Stasis's own reads must stay on the genuine builtin, so we
9
- // snapshot here exactly like state.js / state-util.js / fs.js do for the other patched readers.
10
- const { realpathSync } = fs
11
-
12
- const sep = '/'
13
-
14
- // The full, finite universe of `format` strings stasis knows. Lockfile and bundle
15
- // parsers reject any value outside this set so a tampered or forward-incompatible
16
- // artifact fails closed at the schema boundary, not at a later string compare.
17
- // Categories:
18
- // Executable by Node's loader — module, commonjs, json, *-typescript
19
- // Source languages (analysis-only, not runnable by Node) — solidity, php, bash, rust
20
- // Resources (asset payloads) — resource (raw UTF-8), resource:base64 (binary)
21
- // Filesystem captures (`stasis run --fs`) — directory (a JSON-serialized,
22
- // sorted `fs.readdirSync` listing; a resource-like raw-UTF-8 payload), and the
23
- // payload-free stat records stat:file / stat:directory (an `fs.lstatSync`/
24
- // `fs.statSync` capture: attests only that the path existed with that KIND —
25
- // no bytes, no hash, no module-files entry — so isFile()/isDirectory() answer
26
- // from the bundle at load; see isStatFormat below)
27
- // Adding a new format is a deliberate schema change: list it here AND extend
28
- // hooks.js's executable allowlist if Node should serve it from a bundle.
29
- export const KNOWN_FORMATS = new Set([
30
- 'module',
31
- 'commonjs',
32
- 'json',
33
- 'module-typescript',
34
- 'commonjs-typescript',
35
- 'solidity',
36
- 'php',
37
- 'bash',
38
- 'rust',
39
- 'resource',
40
- 'resource:base64',
41
- 'directory',
42
- 'stat:file',
43
- 'stat:directory',
3
+ import { basename, isAbsolute, join, relative } from 'node:path'
4
+ import { parseArgs } from 'node:util'
5
+
6
+ import { NODE_FORMATS } from './artifact-util.js'
7
+
8
+ // The Node-side half of the util split: byte/name classification for the capture walks, fs/execute-bit
9
+ // observation and CLI parsing. The pure artifact data model (formats universe, keys, merges,
10
+ // executable-set rules, converters) lives in artifact-util.js; re-exported here so
11
+ // `@exodus/stasis-core/util` keeps serving the full set.
12
+ export * from './artifact-util.js'
13
+
14
+ // Snapshot before `stasis run --fs` patches fs: the patched realpathSync doesn't throw ENOENT (which
15
+ // assertRealPathWithinBase relies on) and patched statSync answers with synthetic Stats modes.
16
+ const { realpathSync, statSync } = fs
17
+
18
+ // JS_UNRESOLVED_EXTS (.js/.ts type/syntax-dependent, .jsx/.tsx transformed) classify as null, not a format.
19
+ const NODE_EXT_FORMATS = new Map([
20
+ ['mjs', 'module'], ['cjs', 'commonjs'], ['json', 'json'],
21
+ ['mts', 'module-typescript'], ['cts', 'commonjs-typescript'],
44
22
  ])
23
+ const JS_UNRESOLVED_EXTS = new Set(['js', 'ts', 'jsx', 'tsx'])
24
+ export const CODE_EXTENSIONS = new Set([...NODE_EXT_FORMATS.keys(), ...JS_UNRESOLVED_EXTS])
45
25
 
46
- // File extensions whose bytes are JS-shaped code -- Node's loader and the
47
- // lockfile/bundle format machinery can attest them (module/commonjs/json/
48
- // *-typescript) and `bundle=load` can round-trip them as modules. This is the
49
- // SINGLE source of truth for "is this a code file", shared so the two capture
50
- // paths can't disagree: bundler plugins classify module-graph imports against it
51
- // (classifyExtension), parseResourcesOption refuses to admit any of these into a
52
- // `resources` allowlist (a code file is never an asset payload), and State both
53
- // classifies `--fs` reads and guards `resource:true` against it. Dot-less +
54
- // lowercase, matching pathExt. Drift here was the root of a lockfile/bundle
55
- // desync: `.jsx`/`.tsx` were code to the plugins but missing from the fs-capture's
56
- // own set, so an fs-read tagged a `.jsx` 'resource' while the import tagged it code.
57
- export const CODE_EXTENSIONS = new Set(['js', 'mjs', 'cjs', 'ts', 'jsx', 'tsx', 'json', 'mts', 'cts'])
58
-
59
- // The payload-free stat-record formats (`stasis run --fs` lstatSync/statSync captures).
60
- // A stat record attests a path's KIND (file vs directory) without any content, so it
61
- // lives ONLY in the `formats` maps — never in a module's hashed `files`, never as a
62
- // bundle payload. It is deliberately WEAK: real content recorded for the same path (a
63
- // read, a readdir listing, an import) supersedes it — see State's addFile/addFsDir
64
- // stale-record drop and #mergedFormats' upgrade rule.
65
- export const isStatFormat = (format) => format === 'stat:file' || format === 'stat:directory'
66
-
67
- // Lowercased, dot-less extension of a path, or '' if none.
68
26
  export function pathExt(filePath) {
69
27
  const m = /\.([^./\\]+)$/.exec(filePath)
70
28
  return m ? m[1].toLowerCase() : ''
71
29
  }
72
30
 
73
- // Validates + normalizes a `resources` allowlist (plugin option, --resources flag,
74
- // EXODUS_STASIS_RESOURCES, or stasis.config.json) into a Set of lowercase entries. Each
75
- // entry is either a bare extension (`png`, `.png`) or an extensionless filename
76
- // (`LICENSE`, `Makefile`, `license-mit`); classifyExtension matches a file by its
77
- // extension, falling back to its basename when it has none. A dotted entry like
78
- // `data.bin` is rejected -- a file that HAS an extension is keyed by it, so the entry
79
- // would never match; declare the extension (`bin`) instead. Code extensions are rejected
80
- // too (always tracked). Throwing here surfaces misconfigurations immediately rather than
81
- // as silent capture drift. `resources` may be an array (option / config) or undefined.
31
+ // A native path as the '/'-joined form every artifact key uses (a no-op off Windows).
32
+ export const toPosix = (path) => path.split(/[\\/]/u).join('/')
33
+
34
+ // Both rules are needed: pathExt('.env.local') is 'local', and the extension rule alone misses `.env.*`.
35
+ export function isDotEnvFile(name) {
36
+ const base = basename(name).toLowerCase()
37
+ return base === '.env' || base.startsWith('.env.') || pathExt(base) === 'env'
38
+ }
39
+
40
+ // Entries are a bare extension (`png`) or extensionless filename (`LICENSE`); a dotted entry
41
+ // (`data.bin`) is rejected because a file with an extension is keyed by it and would never match.
82
42
  export function parseResourcesOption(label, resources) {
83
43
  if (resources === undefined) return new Set()
84
44
  if (!Array.isArray(resources)) {
@@ -103,10 +63,7 @@ export function parseResourcesOption(label, resources) {
103
63
 
104
64
  export const isBrotliQuality = (n) => Number.isInteger(n) && n >= 0 && n <= 11
105
65
 
106
- // Parse an EXODUS_STASIS_BROTLI_QUALITY / --brotli-quality string into a brotli quality
107
- // (integer 0..11). `${n}` must round-trip back to the input, so Number()-coercible
108
- // non-canonical forms ('5.0', '05', ' 5 ', whitespace -> 0) throw instead of silently
109
- // selecting an unintended quality. The single parser for the env var and both CLIs.
66
+ // `${n}` must round-trip to the input, so non-canonical forms ('5.0', '05', ' 5 ') throw.
110
67
  export function parseBrotliQuality(name, value) {
111
68
  const n = Number(value)
112
69
  if (`${n}` !== value || !isBrotliQuality(n)) {
@@ -115,126 +72,290 @@ export function parseBrotliQuality(name, value) {
115
72
  return n
116
73
  }
117
74
 
118
- // Classifies a file against the code set + a parsed resources allowlist. Returns 'code'
119
- // (track with its loader format), 'resource' (track with a 'resource'/'resource:base64'
120
- // format -- the encoding is chosen from content), or 'unknown' (caller must reject). A
121
- // file is keyed by its extension, or -- when it has none (LICENSE, Makefile, a dotless
122
- // name) -- by its basename, so a resources entry can be an extension or an extensionless
123
- // filename. The 'unknown' path forces every non-JS asset to be declared explicitly -- no
124
- // silent attestation widening. The SINGLE classifier for both capture paths: bundler
125
- // plugins run it on module-graph imports, State runs it on `--fs` reads, so the two
126
- // can't drift.
75
+ // Shifts the leading option tokens off `argv`, stopping at the first positional so `run`'s forwarded
76
+ // child argv survives. `valueFlags` lists options whose separate-token value (`-o dir`) isn't the positional.
77
+ export function parseLeadingOptions(argv, options, { valueFlags = [], onError } = {}) {
78
+ const takesValue = new Set(valueFlags)
79
+ const flags = []
80
+ while (argv.length > 0 && (argv[0].startsWith('-') || takesValue.has(flags.at(-1)))) {
81
+ flags.push(argv.shift())
82
+ }
83
+ try {
84
+ return parseArgs({ args: flags, options }).values
85
+ } catch (cause) {
86
+ onError(`Error: ${cause.message}`) // usage(), which exits
87
+ return undefined
88
+ }
89
+ }
90
+
91
+ // The JS-graph bundlers' policy view over classifyFormat: only JS-family code (null or a NODE_FORMAT)
92
+ // counts as 'code'; native/source formats don't. Otherwise 'resource' if allowlisted, else 'unknown'.
127
93
  export function classifyExtension(filePath, resources) {
128
- const ext = pathExt(filePath)
129
- if (CODE_EXTENSIONS.has(ext)) return 'code'
130
- if (resources.has(ext || basename(filePath).toLowerCase())) return 'resource'
94
+ const format = classifyFormat(filePath)
95
+ if (format === null || NODE_FORMATS.has(format)) return 'code'
96
+ if (resources.has(pathExt(filePath) || basename(filePath).toLowerCase())) return 'resource'
131
97
  return 'unknown'
132
98
  }
133
99
 
134
- // Set-equality for parsed resources allowlists (lowercase extension/filename sets).
135
- // Coordinates a plugin's `resources` option against an active preload's, and the env
136
- // var against an explicit option in Config.
137
- export function extSetsEqual(a, b) {
138
- if (a.size !== b.size) return false
139
- for (const ext of a) if (!b.has(ext)) return false
140
- return true
100
+ // Compiled/prebuilt artifacts, non-deterministic across installs, so the native capture skips them
101
+ // entirely. Matched on a file OR directory name (an Apple `*.framework`/`*.xcodeproj` bundle dir).
102
+ const NATIVE_ARTIFACT_EXTS = new Set([
103
+ 'a', 'so', 'o', 'obj', 'dylib', 'lib', 'dll', 'exe', 'pdb',
104
+ 'aar', 'jar', 'class', 'dex',
105
+ 'node',
106
+ 'framework', 'xcframework', 'dsym',
107
+ 'xcodeproj', 'xcworkspace',
108
+ 'zip', 'tar', 'gz', 'tgz', 'bz2', 'xz', '7z',
109
+ ])
110
+ export function isNativeArtifact(name) {
111
+ return NATIVE_ARTIFACT_EXTS.has(pathExt(name))
141
112
  }
142
113
 
143
- // Flat project-relative key for the file `rel` inside module dir `dir`, inverse of
144
- // the bucketing State/Bundle apply. The `rel === ''` branch is reached only by a
145
- // `directory` capture whose path IS a module root (e.g. `fs.readdirSync` of a
146
- // package dir, or of the project root): the listing is keyed at the bucket itself,
147
- // so the flat key is the dir — never `${dir}/`, which a trailing-slash join would
148
- // wrongly produce and break the round-trip. The workspace root keys at '.' (the
149
- // '.' bucket's own dir), NOT '': join('.', '') === '.' is what lockfile re-absorb
150
- // derives, so a '' key would be written but never found again on load. For every
151
- // ordinary file `rel` is a real basename, so this matches the historical
152
- // `dir === '.' ? rel : `${dir}/${rel}`` exactly.
153
- export function moduleFileKey(dir, rel) {
154
- if (rel === '') return dir
155
- return dir === '.' ? rel : `${dir}/${rel}`
156
- }
157
-
158
- // Resolve `baseDir/relPath` through symlinks and confirm the real target stays
159
- // within `realBase` (the caller-resolved real path of baseDir). Throws on a
160
- // symlink that escapes the bundle root: a crafted in-tree symlink
161
- // (`link.sh -> /etc/passwd`, or a symlinked directory) must not pull an
162
- // external file into a self-contained, attestable bundle. The textual path
163
- // guards elsewhere don't catch this because they never resolve symlinks.
164
- // realpathSync surfaces ENOENT for a missing path, which the loaders' disk
165
- // walks already handle as "missing".
166
- export function assertRealPathWithinBase(realBase, baseDir, relPath) {
167
- const real = realpathSync(join(baseDir, relPath))
168
- const rel = relative(realBase, real).split(/[\\/]/u).join('/')
169
- if (rel.startsWith('..') || isAbsolute(rel)) {
170
- throw new Error(`Refusing to follow symlink escaping bundle root: ${relPath} -> ${real}`)
171
- }
114
+ // An extensionless non-UTF-8 file is a compiled tool (Hermes' `hermesc`), never source -- skipped.
115
+ function isExtensionlessBinary(name, content) {
116
+ return pathExt(name) === '' && Buffer.isBuffer(content) && !isUtf8(content)
172
117
  }
173
118
 
174
- export function assert(condition, msg) {
175
- if (!condition) throw new Error(msg)
119
+ // A binary plist is a real build input, but its bytes can't ride the text-only 'xml' format
120
+ // classifyFormat gives a `.plist`. Callers treat it as NOT code, so it needs `.plist` in `resources`.
121
+ export function isBinaryPlist(name, content) {
122
+ return pathExt(name) === 'plist' && Buffer.isBuffer(content) && !isUtf8(content)
176
123
  }
177
124
 
178
- export function sortPaths(a, b) {
179
- const [al, bl] = [a.split(sep), b.split(sep)]
180
- while (al.length > 0 && al[0] === bl[0]) {
181
- al.shift()
182
- bl.shift()
183
- }
184
- if (al.length === 0 && bl.length === 0) return 0
125
+ // Discovered by name: RN scatters podspecs in subdirs `react-native config` misses.
126
+ export function isPodspec(name) {
127
+ return name.endsWith('.podspec') || name.endsWith('.podspec.json')
128
+ }
185
129
 
186
- // First process each file in dir, then subdirs
187
- if (al.length < 2) return bl.length < 2 && al > bl ? 1 : -1
188
- if (bl.length < 2) return 1
130
+ // Non-JS code formats by extension. Every value must be in KNOWN_FORMATS.
131
+ const CODE_EXT_FORMATS = new Map([
132
+ ['sol', 'solidity'],
133
+ ['php', 'php'],
134
+ ['sh', 'shell'], ['bash', 'shell'],
135
+ ['rs', 'rust'],
136
+ ['patch', 'patch'],
137
+ ['java', 'java'],
138
+ ['kt', 'kotlin'],
139
+ ['kts', 'kotlin'],
140
+ ['gradle', 'gradle'],
141
+ ['m', 'objc'],
142
+ ['mm', 'objcpp'],
143
+ ['swift', 'swift'],
144
+ ['c', 'c'],
145
+ ['cc', 'cpp'], ['cxx', 'cpp'], ['cpp', 'cpp'], ['c++', 'cpp'],
146
+ ['h', 'c-header'],
147
+ ['hh', 'cpp-header'], ['hxx', 'cpp-header'], ['hpp', 'cpp-header'], ['h++', 'cpp-header'],
148
+ ['rb', 'ruby'],
149
+ ['cmake', 'cmake'],
150
+ ['podspec', 'podspec'],
151
+ ['template', 'template'],
152
+ ['xml', 'xml'],
153
+ ['plist', 'xml'],
154
+ ['xcprivacy', 'xml'],
155
+ ['xcscheme', 'xml'],
156
+ ['storyboard', 'xml'],
157
+ ['entitlements', 'xml'],
158
+ ['env', 'env'],
159
+ ['pbxproj', 'pbxproj'],
160
+ ['xcworkspacedata', 'xml'],
161
+ ])
189
162
 
190
- // * comes first
191
- if (al[0] === '*') return -1
192
- if (bl[0] === '*') return 1
163
+ // Code formats by exact (lowercased) basename, for names whose extension is too generic to key
164
+ // (Podfile.lock's `.lock`, CMakeLists.txt's `.txt`).
165
+ const CODE_NAME_FORMATS = new Map([
166
+ ['podfile', 'podfile'],
167
+ ['podfile.lock', 'podfile-lock'],
168
+ ['cmakelists.txt', 'cmake'],
169
+ ['gradlew', 'shell'],
170
+ ['appfile', 'fastlane'],
171
+ ['fastfile', 'fastlane'],
172
+ ['apple-app-site-association', 'json'],
173
+ ])
193
174
 
194
- // node_modules comes last
195
- if (al[0] === 'node_modules') return 1
196
- if (bl[0] === 'node_modules') return -1
175
+ const SHELL_SHEBANG = /^#![^\n]*\b(?:bash|sh)\b/u
176
+ function isShellShebang(content) {
177
+ if (!Buffer.isBuffer(content) || !isUtf8(content)) return false
178
+ const head = content.subarray(0, 256).toString('utf8')
179
+ const nl = head.indexOf('\n')
180
+ return SHELL_SHEBANG.test(nl === -1 ? head : head.slice(0, nl))
181
+ }
197
182
 
198
- // Prefer example/ over example-something/
199
- const [an, bn] = [al, bl].map((list) => list.join(String.fromCodePoint(0)))
200
- if (an < bn) return -1
201
- if (an > bn) return 1
202
- throw new Error('Unreachable')
183
+ // Files a native package ships that are NOT build inputs (docs/legal, editor/lint/CI config, logs,
184
+ // sidecars), excluded from the Metro native capture. `flow` covers the `*.js.flow` sidecars.
185
+ const NATIVE_EXCLUDE_EXTS = new Set(['md', 'log', 'map', 'flow', 'swiftdoc'])
186
+ const NATIVE_EXCLUDE_NAMES = new Set([
187
+ 'license', 'licence', 'third-party-licenses',
188
+ '.prettierrc', '.prettierignore', '.prettierrc.js', '.gitattributes', '.flowconfig', '.eslintignore',
189
+ '.releaserc', '.clang-format', '.buckconfig', '.watchmanconfig', '.editorconfig', 'circle.yml', '.swiftlint.yml',
190
+ 'documentation.yml', // documentation.js config
191
+ 'yarn.lock',
192
+ '.project', // Eclipse IDE metadata
193
+ 'gradle-wrapper.properties', // the APP's wrapper drives the build, not a module's own
194
+ ])
195
+ export function isExcludedNativeFile(name, { win32 = process.platform === 'win32' } = {}) {
196
+ const base = basename(name).toLowerCase()
197
+ if (NATIVE_EXCLUDE_NAMES.has(base)) return true
198
+ const ext = pathExt(name)
199
+ if (NATIVE_EXCLUDE_EXTS.has(ext)) return true
200
+ return !win32 && ext === 'bat'
203
201
  }
204
202
 
205
- export const isPlainObject = (x) => x && [null, Object.prototype].includes(Object.getPrototypeOf(x))
203
+ export function isExcludedNativeDir(name, { win32 = process.platform === 'win32' } = {}) {
204
+ return !win32 && name === 'windows'
205
+ }
206
206
 
207
- export const fromEntries = (entries) => Object.setPrototypeOf(Object.fromEntries(entries), null)
207
+ // An Apple prebuilt-slice dir (`ios-arm64`, `tvos-arm64_x86_64-simulator`): compiled output, not source,
208
+ // at ANY depth. The PLATFORM segment is deliberately loose -- the required ARCH segment is the precision.
209
+ const APPLE_ARCH = String.raw`(?:arm64e|arm64_32|arm64|armv7k|armv7s|armv7|x86_64|i386)`
210
+ const APPLE_SLICE_DIR = new RegExp(
211
+ String.raw`^[a-z0-9]+-${APPLE_ARCH}(?:_${APPLE_ARCH})*(?:-(?:simulator|maccatalyst))?$`,
212
+ 'u'
213
+ )
214
+ export function isAppleSliceDir(name) {
215
+ return APPLE_SLICE_DIR.test(name)
216
+ }
208
217
 
209
- export const fileSetToObject = (set) => [...set].toSorted((a, b) => sortPaths(a, b))
218
+ // Types only, never a runtime module: the resolvers must refuse to land on one and fall through to the
219
+ // real `.js`. Keyed by compound suffix -- pathExt only sees the trailing `ts`.
220
+ const TYPE_DECLARATION_SUFFIXES = ['.d.ts', '.d.mts', '.d.cts']
221
+ export function isTypeDeclaration(name) {
222
+ const base = basename(name).toLowerCase()
223
+ return TYPE_DECLARATION_SUFFIXES.some((suffix) => base.endsWith(suffix))
224
+ }
210
225
 
211
- export const fileMapToObject = (map) => fromEntries(
212
- [...map]
213
- .toSorted((a, b) => sortPaths(a[0], b[0]))
214
- .map(([k, v]) => [k, v instanceof Map ? fileMapToObject(v) : v])
215
- )
226
+ export function stripTypeDeclaration(name) {
227
+ const lower = name.toLowerCase()
228
+ const suffix = TYPE_DECLARATION_SUFFIXES.find((s) => lower.endsWith(s))
229
+ return suffix === undefined ? name : name.slice(0, -suffix.length)
230
+ }
216
231
 
217
- export const objectToMaps = (obj) => new Map(
218
- Object.entries(obj).map(([k, v]) => [k, isPlainObject(v) ? objectToMaps(v) : v])
219
- )
232
+ // stasis's own outputs (`stasis.lock.json`, a `*stasis*.br`): absent on a first run but present on a
233
+ // later one, so a listing (`--fs` readdir) or a sweep (`add .`) that records one diverges between runs
234
+ // and the later capture conflicts.
235
+ export function isStasisArtifactName(name) {
236
+ const base = basename(name).toLowerCase()
237
+ return base === 'stasis.lock.json' || (base.includes('stasis') && base.endsWith('.br'))
238
+ }
220
239
 
221
- // True when a POSIX, project-relative path escapes the root once normalized:
222
- // a leading `..`, an absolute path, or a mid-path `..` that pops above the
223
- // root (`a/../../x`). Plain `startsWith('..')` only catches the leading case,
224
- // so it's not enough for paths that later get resolved against the root.
225
- export function posixPathEscapes(path) {
226
- const normalized = posix.normalize(path)
227
- return normalized === '..' || normalized.startsWith('../') || posix.isAbsolute(normalized)
228
- }
229
-
230
- export function splitNodeModulesPath(path) {
231
- const marker = 'node_modules/'
232
- const idx = path.lastIndexOf(marker)
233
- if (idx === -1) return null
234
- const after = idx + marker.length
235
- const parts = path.slice(after).split('/')
236
- const pkgLen = parts[0].startsWith('@') ? 2 : 1
237
- if (parts.length <= pkgLen || parts.slice(0, pkgLen).some((p) => !p)) return null
238
- const name = parts.slice(0, pkgLen).join('/')
239
- return { dir: path.slice(0, after) + name, rel: parts.slice(pkgLen).join('/'), name }
240
+ // Dirs no walk descends into: VCS/CI/IDE metadata, sample apps, test scaffolding -- none of it is the
241
+ // code being shipped -- plus the Apple prebuilt slice dirs. `name` is a BARE dir name (a dirent name
242
+ // or path segment), matched at any depth, so every walk agrees on what "not source" means.
243
+ const AUTO_EXCLUDED_DIRS = new Set([
244
+ '.git', '.github', '.settings', // VCS / CI / IDE metadata
245
+ 'example', 'examples', // sample apps -- they import the package, they aren't it
246
+ '__tests__', '__mocks__', 'jest', // test scaffolding
247
+ ])
248
+ export function isAutoExcludedDir(name) {
249
+ const base = name.toLowerCase()
250
+ return AUTO_EXCLUDED_DIRS.has(base) || isAppleSliceDir(base)
251
+ }
252
+
253
+ // Dirs the NATIVE walks (Metro plugin + the static --metro bundler) skip, on top of the shared set:
254
+ // nested packages (attested separately) and regenerated build output -- none is a build input.
255
+ const NATIVE_BUILD_OUTPUT_DIRS = new Set(['node_modules', 'build', '.gradle', '.cxx', 'Pods', 'DerivedData'])
256
+ export function isSkippedNativeWalkDir(name) {
257
+ return NATIVE_BUILD_OUTPUT_DIRS.has(name) || isAutoExcludedDir(name) || isNativeArtifact(name)
258
+ }
259
+
260
+ // Files a sweep drops: type declarations (types only, erased at runtime), the `.env` family (secrets),
261
+ // stasis's own outputs (they'd attest themselves), and everything the native capture excludes as
262
+ // non-build-input noise (docs/legal, editor/lint/CI config, `*.map`/`*.js.flow` sidecars, logs).
263
+ // A path can only reach this via a glob -- an EXPLICITLY named one is added as asked (`add .env` still
264
+ // captures), which is also the only way to attest a file this set covers.
265
+ export function isAutoExcludedFile(name) {
266
+ return isTypeDeclaration(name) || isDotEnvFile(name) || isStasisArtifactName(name) || isExcludedNativeFile(name)
267
+ }
268
+
269
+ // The single name->format classifier every capture path is a policy view of. Returns a concrete format
270
+ // when the name determines one; null for a JS-family file (.js/.ts/.jsx/.tsx); undefined if unrecognized.
271
+ export function classifyFormat(name, { content } = {}) {
272
+ const base = basename(name).toLowerCase()
273
+ // Before the extension rules, so a `*.podspec.json` isn't shadowed.
274
+ if (base === 'package.json' || base.endsWith('.podspec.json')) return 'json'
275
+ // Compound suffix: pathExt only sees the trailing `in`.
276
+ if (base.endsWith('.cmake.in')) return 'cmake'
277
+ const byName = CODE_NAME_FORMATS.get(base)
278
+ if (byName !== undefined) return byName
279
+ const ext = pathExt(name)
280
+ if (JS_UNRESOLVED_EXTS.has(ext)) return null
281
+ const byExt = NODE_EXT_FORMATS.get(ext) ?? CODE_EXT_FORMATS.get(ext)
282
+ if (byExt !== undefined) return byExt
283
+ if (ext === '' && isShellShebang(content)) return 'shell'
284
+ return undefined
285
+ }
286
+
287
+ // The Metro native capture's policy view. Returns { action, format }: 'code' (a native build input),
288
+ // 'skip' (excluded noise, or a JS-family file matched BY EXTENSION -- Metro owns those), else 'resource'.
289
+ export function classifyNativeCapture(name, { win32 = process.platform === 'win32', content } = {}) {
290
+ if (isExcludedNativeFile(name, { win32 })) return { action: 'skip' }
291
+ // `.env` files carry secrets: an automated capture must never sweep them in.
292
+ if (isDotEnvFile(name)) return { action: 'skip' }
293
+ const base = basename(name).toLowerCase()
294
+ // Name-matched code is always a native build input, even when its tag is a Node format the JS
295
+ // graph would otherwise own.
296
+ if (base === 'package.json' || base.endsWith('.podspec.json')) return { action: 'code', format: 'json' }
297
+ const byName = CODE_NAME_FORMATS.get(base)
298
+ if (byName !== undefined) return { action: 'code', format: byName }
299
+ if (CODE_EXTENSIONS.has(pathExt(name))) return { action: 'skip' }
300
+ const format = classifyFormat(name, { content })
301
+ if (format !== undefined) return { action: 'code', format }
302
+ return { action: 'resource' }
303
+ }
304
+
305
+ // The byte-level half of the native classification, refining what classifyNativeCapture derived from the
306
+ // NAME. Both rules only ever demote. A 'resource' carries no format: storage derives base64 from bytes.
307
+ export function refineNativeCapture(classified, name, content, resources = new Set()) {
308
+ if (isExtensionlessBinary(name, content)) return { action: 'skip' }
309
+ if (isBinaryPlist(name, content)) return { action: resources.has('plist') ? 'resource' : 'skip' }
310
+ return classified
311
+ }
312
+
313
+ // Files `pod install` reads while loading podspecs (Ruby helpers, package.json) -- NOT the native
314
+ // source those podspecs compile.
315
+ export function isNativeManifest(name) {
316
+ return isPodspec(name) || pathExt(name) === 'rb' || name === 'package.json'
317
+ }
318
+
319
+ // RN core build scripts the native walk would defer to Metro as `.js`, but Metro never sees them (RN's
320
+ // podspecs invoke them at pod-install). Project-relative, so react-native's `exports` can't hide them.
321
+ export const RN_CORE_INCLUDE_FILES = ['sdks/hermes-engine/utils/replace_hermes_version.js']
322
+
323
+ export function extSetsEqual(a, b) {
324
+ if (a.size !== b.size) return false
325
+ for (const ext of a) if (!b.has(ext)) return false
326
+ return true
327
+ }
328
+
329
+ export const EXECUTE_BITS = 0o111
330
+
331
+ export const isExecutableMode = (stats) => stats.isFile() && (stats.mode & EXECUTE_BITS) !== 0
332
+
333
+ // Tri-state: `undefined` means the mode could NOT be observed (gone mid-run, EACCES, ELOOP, a synthetic
334
+ // bundle entry). Callers must not read that as "not executable" -- failing to look is not evidence.
335
+ export function observeExecutable(abs) {
336
+ let stats
337
+ try {
338
+ stats = statSync(abs, { throwIfNoEntry: false })
339
+ } catch {
340
+ return undefined
341
+ }
342
+ if (stats === undefined) return undefined
343
+ return isExecutableMode(stats)
344
+ }
345
+
346
+ // Boolean view for callers with nothing to refute (recording a fresh set from scratch).
347
+ export const isExecutableFile = (abs) => observeExecutable(abs) === true
348
+
349
+ // Windows reports no POSIX execute bits, so a capture there records none and must NOT read "no bit" as
350
+ // "the bit was removed" and strip what a POSIX capture attested.
351
+ export const canObserveExecuteBits = ({ win32 = process.platform === 'win32' } = {}) => !win32
352
+
353
+ // Throws on a symlink escaping the bundle root: a crafted `link.sh -> /etc/passwd` must not pull an
354
+ // external file into an attestable bundle. realpathSync surfaces ENOENT, which loaders treat as "missing".
355
+ export function assertRealPathWithinBase(realBase, baseDir, relPath) {
356
+ const real = realpathSync(join(baseDir, relPath))
357
+ const rel = toPosix(relative(realBase, real))
358
+ if (rel.startsWith('..') || isAbsolute(rel)) {
359
+ throw new Error(`Refusing to follow symlink escaping bundle root: ${relPath} -> ${real}`)
360
+ }
240
361
  }