@whenlabs/core - npm Package Compare versions

Comparing version 0.1.0 to 1.0.0

dist/index.d.ts

 /**
  * @whenlabs/core — shared types for the @whenlabs developer toolkit.
  *
- * v0.1 surface (additive-only until v1.0):
+ * v1.0 surface (stable contract — breaking changes require a 2.0 bump):
  *   - schemaVersion
@@ -116,3 +116,27 @@ *   - ProjectContext
 }
+/**
+ * Minimal shape the kit uses to detect "this came from a newer core than I
+ * understand." Anything stamped with a `schemaVersion` other than {@link schemaVersion}
+ * is a candidate for translation. Kept as `unknown`-ish on purpose — by design
+ * we don't know the v2 shape yet.
+ */
+interface VersionedResult {
+    schemaVersion: number;
+    [key: string]: unknown;
+}
+/**
+ * Forward-compat seam for when `schemaVersion` is bumped to 2 in a future
+ * breaking release. Consumers should call this before narrowing a result to
+ * {@link ScanResult} so the kit has a single place to land v2→v1 adapters.
+ *
+ * **Status (v1.0):** no-op. There is no v2 yet, so the only legal input is a
+ * v1 result, which is returned as-is. When v2 lands, this function becomes the
+ * canonical place to translate `{schemaVersion: 2, ...}` payloads down to v1
+ * for older consumers (or vice versa for newer ones).
+ *
+ * Throws if handed a schemaVersion the installed core doesn't understand,
+ * so the kit fails loud instead of silently mis-parsing.
+ */
+declare function translateScanResult(input: VersionedResult): ScanResult;
 
-export { type Finding, type Location, type Patch, type ProjectContext, type ScanOptions, type ScanResult, type ScanSummary, type ScanTiming, type Severity, type SuggestionRule, type Tool, type TriggerContext, schemaVersion };
+export { type Finding, type Location, type Patch, type ProjectContext, type ScanOptions, type ScanResult, type ScanSummary, type ScanTiming, type Severity, type SuggestionRule, type Tool, type TriggerContext, type VersionedResult, schemaVersion, translateScanResult };

dist/index.js

 // src/index.ts
 var schemaVersion = 1;
+function translateScanResult(input) {
+  if (input.schemaVersion === schemaVersion) {
+    return input;
+  }
+  throw new Error(
+    `@whenlabs/core: unsupported schemaVersion ${input.schemaVersion} (this build understands ${schemaVersion}). Upgrade @whenlabs/core to consume newer tool output, or downgrade the tool.`
+  );
+}
 export {
-  schemaVersion
+  schemaVersion,
+  translateScanResult
 };

package.json

 {
   "name": "@whenlabs/core",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "Shared types for the @whenlabs developer toolkit",
@@ -5,0 +5,0 @@ "type": "module",

README.md

@@ -17,15 +17,15 @@ # @whenlabs/core
 - **`SuggestionRule`** — the trigger/emit rule shape used by the kit's post-invocation suggestion layer.
+- **`translateScanResult(input)`** — forward-compat seam for future `schemaVersion` bumps. No-op in v1.0; returns v1 results as-is and throws on any other `schemaVersion`.
 
-Supporting types also exported: `Severity`, `Location`, `ScanOptions`, `ScanTiming`, `ScanSummary`, `Patch`, `TriggerContext`.
+Supporting types also exported: `Severity`, `Location`, `ScanOptions`, `ScanTiming`, `ScanSummary`, `Patch`, `TriggerContext`, `VersionedResult`.
 
-## Discipline: additive-only until v1.0
+## Stability: v1.0 contract
 
-The whole point of pinning this to `0.1.x` is stability. Until v1.0:
+As of v1.0 the contract is **stable**. The additive-only pre-v1.0 discipline has ended — every exported type, field, and constant is now locked.
 
-- **Never rename** an exported type, field, or constant.
-- **Never remove** an exported type, field, or constant.
-- **Never tighten** a type (e.g. widening `string` → `'a' | 'b'`, making optional → required).
-- **Adding** a new optional field, a new exported type, or a new enum variant on a union typed as `string` is allowed.
+- **Any breaking change requires a 2.0 major bump.** Renames, removals, tightenings (widening `string` → `'a' | 'b'`, optional → required) all qualify.
+- **Additive changes remain safe in 1.x.** A new optional field, a new exported type, or a new variant on a union typed as `string` can ship in a minor release.
+- **`schemaVersion` is the long-lived signal.** It stays at `1` for the entire 1.x line. A 2.0 core bumps it to `2` and ships a translator via `translateScanResult()` so 1.x consumers have a migration path.
 
-Breaking changes wait for v1.0. Red-flag items from Phase 2 (closed `detectedStack` enum, `inspect()` method, streaming) are deliberately deferred.
+Red-flag items previously deferred (closed `detectedStack` enum, `inspect()` method, streaming `scan()`) are now 2.0 candidates — they cannot land in 1.x without breaking the contract.
 
@@ -32,0 +32,0 @@ ## Known limitations (v0.1)

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Improved metrics

Total package byte prevSize

11739

20.87%

Lines of code

154

27.27%

Number of low quality alerts

2

-33.33%

No dependency changes