@bloodhound-rs/core 0.0.0-stage → 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @bloodhound-rs/core
+
+## 0.1.2
+
+### Patch Changes
+
+- e814af8: Distribute native binaries as separate optional packages selected by operating system, CPU architecture, and Linux libc. Keep the core package limited to the generated loader, type declarations, and schemas.
+
+## 0.1.1
+
+### Patch Changes
+
+- 4c754ee: Release the Rust resource scanning SDK under the MIT license with native binaries for Linux, macOS, and Windows. Fix release artifact extraction on Windows.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Justinidlerz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,184 @@
-# Temporary Holding Version
+# @bloodhound-rs/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Rust SDK for static analysis of browser resources. Rust exports the public methods directly, and napi-rs generates the npm loader and method declarations.
+
+| Component                                                                    | Implementation              |
+| ---------------------------------------------------------------------------- | --------------------------- |
+| JavaScript parsing, scopes, aliases, and bounded evaluation                  | Rust + Oxc                  |
+| HTML extraction and CSS parsing                                              | Rust + html5gum / cssparser |
+| Fetching, import maps, recursive queues, budgets, cancellation, and recovery | Rust                        |
+| Global indexes, report diffs, reports, JSONL, and schema validation          | Rust                        |
+| npm loader and method declarations                                           | Generated by napi-rs        |
+
+Results describe static accesses and potential issues. They do not prove that code executed or modified runtime state. The scanner never executes the code it analyzes.
+
+## Install
+
+```sh
+pnpm add @bloodhound-rs/core
+```
+
+The core package contains the generated loader, type declarations, and schemas. The package manager selects a native binary through optional dependencies using the operating system, CPU architecture, and Linux libc. Keep optional dependencies enabled.
+
+| Platform            | Binary package                        |
+| ------------------- | ------------------------------------- |
+| macOS Apple Silicon | `@bloodhound-rs/core-darwin-arm64`    |
+| macOS Intel         | `@bloodhound-rs/core-darwin-x64`      |
+| Linux glibc ARM64   | `@bloodhound-rs/core-linux-arm64-gnu` |
+| Linux glibc x64     | `@bloodhound-rs/core-linux-x64-gnu`   |
+| Windows x64         | `@bloodhound-rs/core-win32-x64-msvc`  |
+
+The loader uses the architecture of the running Node.js process. Linux musl is not supported. Install dependencies on the target system instead of copying `node_modules` between platforms.
+
+## Build
+
+Requires Node.js 22+, pnpm 10.20.0, Rust 1.97+, and the platform's C/C++ build tools.
+
+```sh
+pnpm install --frozen-lockfile
+pnpm build
+pnpm typecheck
+cargo check --locked
+```
+
+`napi build` generates `dist/index.js`, `dist/index.d.ts`, and a platform-specific `.node` file from the exports in `native/src/lib.rs`. `src/types.ts` defines data structures such as reports and emits only `dist/types.d.ts`, with no runtime code. Loading fails if the native binary is missing.
+
+## Local examples
+
+Run from the repository root:
+
+```sh
+pnpm build
+pnpm example
+pnpm example:html
+```
+
+| Command             | Example                                                                                                                    | Report                             |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
+| `pnpm example`      | Scan JavaScript and query global reads, writes, and potential conflicts                                                    | `outputs/example/report.json`      |
+| `pnpm example:html` | Discover the HTML base URL, import map, inline and external scripts, and styles, then recursively scan module dependencies | `outputs/example-html/report.json` |
+
+The examples import the SDK by package name and read local source files without executing them or making network requests. After building, either example can be run independently.
+
+## SDK
+
+```ts
+import { scanJs, scanHtml, scanResource, GlobalIndex } from '@bloodhound-rs/core';
+
+const report = await scanJs('./dist/app.js', {
+  scriptMode: 'classic',
+  executionEnvironment: 'window',
+  dependencyMode: 'recursive',
+  scopeKey: 'release-page',
+  versions: { scmId: 'artifact-revision' },
+  jsonlPath: './scan.jsonl',
+});
+
+const page = await scanHtml('https://example.com/page.html');
+
+const single = await scanResource(
+  {
+    kind: 'js',
+    source: {
+      type: 'content',
+      resourceUrl: 'https://example.com/app.js',
+      content: 'globalThis.sharedConfig = {};',
+    },
+  },
+  { scriptMode: 'module', executionEnvironment: 'window' },
+);
+
+const index = new GlobalIndex(report);
+for (const target of index.findTargets(['sharedConfig'], 'global-object')) {
+  console.log(index.sources(target.targetId));
+  console.log(index.entryPaths(target.targetId, { limit: 20 }));
+}
+console.log(index.conflicts());
+```
+
+`scan(entries, options)` accepts multiple entry points in one analysis. `scanResource` scans only the specified resource while still recording dependency edges. String inputs represent file paths or HTTP(S) / file URLs. Use `type: 'content'` for source text. Scan CSS with `scanResource({ kind: 'css', source })` or `scan`.
+
+`defaults()` returns a plain object containing the default budgets and version information.
+
+For JavaScript entry points, provide `scriptMode` and `executionEnvironment` explicitly. Missing values remain `unknown` and produce coverage gaps. HTML derives script modes from element attributes and defaults to the Window environment. Workers and iframes use separate scopes.
+
+## HTML discovery and optional context
+
+A typical HTML scan needs only a file path or URL:
+
+```ts
+const report = await scanHtml('./page.html');
+```
+
+The scanner reads `<base href>`, `<script type="importmap">`, script `src` and `type` attributes, stylesheet links, and inline content, then follows module dependencies. Import maps and resource lists already present in the HTML need no additional arguments. The scanner does not execute scripts or discover page state created only at runtime.
+
+Use the following options when the input lacks page context or resources need to be loaded from local files:
+
+| Option                           | Purpose                                                                                                                                                  |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `importMap` / `importMapBaseUrl` | Supply the original page's module mappings and resolution base when scanning JavaScript separately                                                       |
+| `resourceUrl`                    | Supply the original online URL when scanning an offline file                                                                                             |
+| `baseUrl`                        | Supply a document base when the input lacks one. A valid HTML `<base>` is read automatically                                                             |
+| `resourceMappings`               | Map resolved resource URLs to local files or source text, such as build artifacts that have not been deployed. This is separate from the HTML import map |
+
+## Offline pages and local resource mappings
+
+`resourceUrl` is the logical resource address, and `baseUrl` is the document base. External module dependencies resolve against the module URL, while inline module dependencies resolve against the document base. Browser module resolution does not search Node.js package directories or infer file extensions.
+
+```ts
+const report = await scanHtml('./page.html', {
+  resourceUrl: 'https://example.com/page.html',
+  resourceMappings: {
+    'https://example.com/assets/app.js': {
+      type: 'file',
+      path: './artifacts/app.js',
+    },
+  },
+  access: { fileRoots: ['./artifacts', '.'], hosts: ['example.com'] },
+});
+```
+
+HTTP fetching uses Rust's `reqwest`. `requestHeaders` groups headers by destination `host[:port]`. After a redirect, the scanner checks access permissions again and selects headers for the new host. Use `proxy` to configure a proxy. Authentication settings are excluded from reports and checkpoint configuration and must be supplied again when resuming.
+
+## Output and recovery
+
+| API or option                                        | Output                                                                                        |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `Report`                                             | resources, analysisInstances, references, globalTargets, globalAccesses, findings, unresolved |
+| `jsonlPath`                                          | JSONL written by Rust as resources are processed                                              |
+| `reportPath`                                         | A JSON report written by Rust                                                                 |
+| `indexArtifact(report)`                              | A standalone versioned index                                                                  |
+| `adaptReport(report, 'build' / 'page', metadata)`    | A report adapted for build or page integrations                                               |
+| `diffReports(before, after)`                         | Added and removed items, plus changes to items that can be matched uniquely                   |
+| `runtimeCandidates(report, evidence)`                | Static candidate sources, without treating them as confirmed runtime behavior                 |
+| `checkpointPath` / `resumeScan(checkpoint, options)` | Save completed records and the pending queue, then fetch and validate inputs again on resume  |
+
+JSONL records update entities by ID. A reference is emitted again when its target analysis instance completes. `resetAnalysis` indicates an updated cross-module summary: consumers first remove that instance's previous accesses, findings, unresolved items, and outgoing edges, then accept the new records. The final `summary` records scan status and coverage statistics. A file without a `summary` indicates that the scan did not finish normally.
+
+Use `AbortSignal` for cancellation. Rust checks the cancellation flag and stops enqueueing resources, reading downloads, and starting further analysis. Blocking network calls are bounded by `resourceTimeoutMs`. Cancellation is checked after an individual Oxc parse returns. Resuming validates all entry points and context again before reusing results.
+
+Checkpoints preserve access restrictions, resource mappings, and source map settings. Resume options can explicitly override them. Callers must supply authentication headers and proxy settings again. When resuming an older checkpoint that lacks these settings, provide them in the resume options.
+
+```ts
+const controller = new AbortController();
+const pending = scanJs('./app.js', {
+  scriptMode: 'module',
+  executionEnvironment: 'window',
+  signal: controller.signal,
+  checkpointPath: './checkpoint.json',
+});
+// controller.abort();
+const report = await pending;
+```
+
+## Packaging and releases
+
+```sh
+pnpm pack
+```
+
+`pnpm pack` builds the local SDK and packs core without native binaries. For a complete release, CI builds every target in `.github/native-targets.json`, collects the binaries in `dist/`, then runs `pnpm pack:release` to produce six archives in `artifacts/`.
+
+Changesets keeps core and the five binary packages at the same version. The workflow publishes and confirms the binary packages before publishing core with exact optional dependency versions. Run `pnpm changeset` for changes that require a release. See [Releasing](docs/releasing.md) for beta releases, stable releases, and npm authentication.
+
+See [Support](docs/support.md) for capabilities and limitations, [Technical design](docs/technical-design.md) for the design, and [Verification](docs/verification.md) for local validation evidence.

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+/* Generated by napi-rs. Do not edit. */
+import type { ScanEntry, ScanOptions, Source, Checkpoint, Report, Target, GlobalAccess, AnalysisInstance, Resource, Budgets } from './types.js';
+export * from './types.js';
+/**
+ * Which binding artifact the generated loader actually loaded: `'native'` for
+ * a native addon, otherwise the `platformArchABI` of the WASI flavor. Every
+ * flavor napi-rs can build is listed, because `NAPI_RS_NATIVE_LIBRARY_PATH`
+ * can point the loader at a WASI artifact this package does not build itself.
+ */
+export declare const __napiBindingTarget: 'native' | 'wasm32-wasi' | 'wasm32-wasip1'
+
+export declare class GlobalIndex {
+  constructor(report: Report)
+  get report(): Report
+  findTargets(pathSegments: Array<string>, namespace?: string | undefined | null, scopeKey?: string | undefined | null): Target[]
+  sources(targetId: string): { access: GlobalAccess; analysis: AnalysisInstance; resource: Resource }[]
+  accesses(analysisId: string): GlobalAccess[]
+  resourceAccesses(resourceId: string): GlobalAccess[]
+  entryPaths(targetId: string, options?: { limit?: number; offset?: number; maxVisits?: number }): { paths: { entryAnalysisId: string; analysisIds: string[]; referenceIds: string[] }[]; truncated: boolean; nextOffset: number }
+  conflicts(): { targetId: string; accessIds: string[]; analysisIds: string[]; valueTypes: string[]; certainty: 'static-candidate' }[]
+  resolveUnbound(): { targetId: string; candidates: string[]; certainty: 'static-candidate' }[]
+}
+
+export declare function adaptReport(report: Report, type: 'build' | 'page', metadata?: Record<string, unknown>): Record<string, unknown>
+
+export declare function defaults(): { budgets: Budgets; versions: Record<string, string> }
+
+export declare function diffReports(before: Report, after: Report): { added: GlobalAccess[]; removed: GlobalAccess[]; changed: { before: GlobalAccess; after: GlobalAccess }[] }
+
+export declare function engineVersion(): string
+
+export declare function indexArtifact(report: Report, reportId?: string): Pick<Report, 'indexSchemaVersion' | 'scopeKey' | 'entryAnalysisIds' | 'resources' | 'analysisInstances' | 'references' | 'globalTargets' | 'globalAccesses' | 'findings' | 'unresolved'> & { reportId: string }
+
+export declare function resumeScan(checkpoint: Checkpoint, options?: ScanOptions): Promise<Report>
+
+export declare function runtimeCandidates(report: Report, input: { resourceUrl?: string; contentHash?: string; line?: number; column?: number; pathSegments?: string[] }): { accessId: string; attribution: 'static_candidate' }[]
+
+export declare function scan(entries: ScanEntry[], options?: ScanOptions): Promise<Report>
+
+export declare function scanHtml(input: Source | string, options?: ScanOptions): Promise<Report>
+
+export declare function scanJs(input: Source | string, options?: ScanOptions): Promise<Report>
+
+export declare function scanResource(entry: ScanEntry, options?: ScanOptions): Promise<Report>
+
+export declare function validateReport(report: unknown): asserts report is Report