@uapkg/diagnostics 1.1.7 → 1.1.9

package/dist/registry/RegistryDiagnostics.js

@@ -0,0 +1,81 @@
+// ---------------------------------------------------------------------------
+// Factory helpers
+// ---------------------------------------------------------------------------
+export function createNetworkErrorDiagnostic(url, reason) {
+    return {
+        level: 'error',
+        code: 'NETWORK_ERROR',
+        message: `Network error for "${url}": ${reason}.`,
+        hint: 'Check your network connection and retry.',
+        data: { url, reason },
+    };
+}
+export function createGitErrorDiagnostic(command, stderr, exitCode) {
+    return {
+        level: 'error',
+        code: 'GIT_ERROR',
+        message: `Git command failed (exit ${exitCode}): ${command}.`,
+        hint: 'Ensure git is installed and the registry URL is reachable.',
+        data: { command, stderr, exitCode },
+    };
+}
+export function createSchemaInvalidDiagnostic(filePath, issues) {
+    return {
+        level: 'error',
+        code: 'SCHEMA_INVALID',
+        message: `Schema validation failed for "${filePath}".`,
+        hint: 'Review the file against the expected schema.',
+        data: { filePath, issues },
+    };
+}
+export function createRegistryNotFoundDiagnostic(registryName) {
+    return {
+        level: 'error',
+        code: 'REGISTRY_NOT_FOUND',
+        message: `Registry "${registryName}" is not defined in configuration.`,
+        hint: `Add the registry. Example:
+  uapkg registry add ${registryName} https://registry.example.com
+
+Or configure manually:
+  uapkg config set registries.${registryName}.url https://registry.example.com
+  uapkg config set registries.${registryName}.ref.type branch
+  uapkg config set registries.${registryName}.ref.value main`,
+        data: { registryName },
+    };
+}
+export function createLockAcquisitionFailedDiagnostic(lockPath, ownerPid) {
+    return {
+        level: 'error',
+        code: 'LOCK_ACQUISITION_FAILED',
+        message: `Could not acquire registry lock at "${lockPath}" (held by PID ${ownerPid}).`,
+        hint: 'Another uapkg process may be updating this registry. Wait or remove the stale lock.',
+        data: { lockPath, ownerPid },
+    };
+}
+export function createCacheReadErrorDiagnostic(cachePath, reason) {
+    return {
+        level: 'error',
+        code: 'CACHE_READ_ERROR',
+        message: `Failed to read registry cache at "${cachePath}": ${reason}.`,
+        hint: 'The cache may be corrupted. Try running `uapkg update` to refresh.',
+        data: { cachePath, reason },
+    };
+}
+export function createRegistryUnreachableDiagnostic(input) {
+    return {
+        level: input.level ?? (input.initialized ? 'warning' : 'error'),
+        code: 'REGISTRY_UNREACHABLE',
+        message: `The "${input.registryName}" registry could not be reached at ${input.url}.`,
+        emitPolicy: 'once',
+        hint: `Verify the registry URL with 'uapkg config get registries.${input.registryName}.url --trace'.
+The registry may also be temporarily unavailable.`,
+        data: {
+            registryName: input.registryName,
+            url: input.url,
+            cause: input.cause,
+            initialized: input.initialized,
+            httpStatus: input.httpStatus,
+        },
+    };
+}
+//# sourceMappingURL=RegistryDiagnostics.js.map

package/dist/registry/RegistryDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RegistryDiagnostics.js","sourceRoot":"","sources":["../../src/registry/RegistryDiagnostics.ts"],"names":[],"mappings":"AAkFA,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,UAAU,4BAA4B,CAAC,GAAW,EAAE,MAAc;IACtE,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,eAAe;QACrB,OAAO,EAAE,sBAAsB,GAAG,MAAM,MAAM,GAAG;QACjD,IAAI,EAAE,0CAA0C;QAChD,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE;KACtB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe,EAAE,MAAc,EAAE,QAAgB;IACxF,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,4BAA4B,QAAQ,MAAM,OAAO,GAAG;QAC7D,IAAI,EAAE,4DAA4D;QAClE,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE;KACpC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,6BAA6B,CAAC,QAAgB,EAAE,MAAyB;IACvF,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,iCAAiC,QAAQ,IAAI;QACtD,IAAI,EAAE,8CAA8C;QACpD,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE;KAC3B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,YAAoB;IACnE,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,oBAAoB;QAC1B,OAAO,EAAE,aAAa,YAAY,oCAAoC;QACtE,IAAI,EAAE;uBACa,YAAY;;;gCAGH,YAAY;gCACZ,YAAY;gCACZ,YAAY,iBAAiB;QACzD,IAAI,EAAE,EAAE,YAAY,EAAE;KACvB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qCAAqC,CACnD,QAAgB,EAChB,QAAgB;IAEhB,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,uCAAuC,QAAQ,kBAAkB,QAAQ,IAAI;QACtF,IAAI,EAAE,qFAAqF;QAC3F,IAAI,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;KAC7B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,SAAiB,EAAE,MAAc;IAC9E,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,qCAAqC,SAAS,MAAM,MAAM,GAAG;QACtE,IAAI,EAAE,oEAAoE;QAC1E,IAAI,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,KAOnD;IACC,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;QAC/D,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,QAAQ,KAAK,CAAC,YAAY,sCAAsC,KAAK,CAAC,GAAG,GAAG;QACrF,UAAU,EAAE,MAAM;QAClB,IAAI,EAAE,6DAA6D,KAAK,CAAC,YAAY;kDACvC;QAC9C,IAAI,EAAE;YACJ,YAAY,EAAE,KAAK,CAAC,YAAY;YAChC,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU,EAAE,KAAK,CAAC,UAAU;SAC7B;KACF,CAAC;AACJ,CAAC"}

package/dist/resolver/ResolverDiagnostics.d.ts

@@ -0,0 +1,36 @@
+import type { DiagnosticBase } from '../base/Diagnostic.js';
+/** Two or more registries resolve the same package name to different versions (single-version kind). */
+export type VersionConflictDiagnostic = DiagnosticBase<'VERSION_CONFLICT', {
+    readonly packageName: string;
+    readonly versions: readonly string[];
+    readonly registry: string;
+}>;
+/** A dependency cycle was detected. */
+export type CircularDepDiagnostic = DiagnosticBase<'CIRCULAR_DEP', {
+    readonly path: readonly string[];
+}>;
+/** Requested package could not be found in any configured registry. */
+export type PackageNotFoundDiagnostic = DiagnosticBase<'PACKAGE_NOT_FOUND', {
+    readonly packageName: string;
+    readonly registry: string;
+}>;
+/** No published version satisfies the requested range. */
+export type VersionNotFoundDiagnostic = DiagnosticBase<'VERSION_NOT_FOUND', {
+    readonly packageName: string;
+    readonly versionRange: string;
+    readonly registry: string;
+    readonly availableVersions: readonly string[];
+}>;
+/** Same package name required from two different registries. */
+export type RegistryNameCollisionDiagnostic = DiagnosticBase<'REGISTRY_NAME_COLLISION', {
+    readonly packageName: string;
+    readonly registries: readonly string[];
+}>;
+/** Union of all resolver diagnostics. */
+export type ResolverDiagnostic = VersionConflictDiagnostic | CircularDepDiagnostic | PackageNotFoundDiagnostic | VersionNotFoundDiagnostic | RegistryNameCollisionDiagnostic;
+export declare function createVersionConflictDiagnostic(packageName: string, versions: readonly string[], registry: string): VersionConflictDiagnostic;
+export declare function createCircularDepDiagnostic(path: readonly string[]): CircularDepDiagnostic;
+export declare function createPackageNotFoundDiagnostic(packageName: string, registry: string): PackageNotFoundDiagnostic;
+export declare function createVersionNotFoundDiagnostic(packageName: string, versionRange: string, registry: string, availableVersions: readonly string[]): VersionNotFoundDiagnostic;
+export declare function createRegistryNameCollisionDiagnostic(packageName: string, registries: readonly string[]): RegistryNameCollisionDiagnostic;
+//# sourceMappingURL=ResolverDiagnostics.d.ts.map

package/dist/resolver/ResolverDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolverDiagnostics.d.ts","sourceRoot":"","sources":["../../src/resolver/ResolverDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,wGAAwG;AACxG,MAAM,MAAM,yBAAyB,GAAG,cAAc,CACpD,kBAAkB,EAClB;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CACF,CAAC;AAEF,uCAAuC;AACvC,MAAM,MAAM,qBAAqB,GAAG,cAAc,CAChD,cAAc,EACd;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC,CACF,CAAC;AAEF,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GAAG,cAAc,CACpD,mBAAmB,EACnB;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,CACF,CAAC;AAEF,0DAA0D;AAC1D,MAAM,MAAM,yBAAyB,GAAG,cAAc,CACpD,mBAAmB,EACnB;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/C,CACF,CAAC;AAEF,gEAAgE;AAChE,MAAM,MAAM,+BAA+B,GAAG,cAAc,CAC1D,yBAAyB,EACzB;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC,CACF,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,kBAAkB,GAC1B,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,GACzB,yBAAyB,GACzB,+BAA+B,CAAC;AAMpC,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,QAAQ,EAAE,MAAM,GACf,yBAAyB,CAQ3B;AAED,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,qBAAqB,CAQ1F;AAED,wBAAgB,+BAA+B,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,yBAAyB,CAQhH;AAED,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,SAAS,MAAM,EAAE,GACnC,yBAAyB,CAQ3B;AAED,wBAAgB,qCAAqC,CACnD,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,SAAS,MAAM,EAAE,GAC5B,+BAA+B,CAQjC"}

package/dist/resolver/ResolverDiagnostics.js

@@ -0,0 +1,49 @@
+// ---------------------------------------------------------------------------
+// Factory helpers
+// ---------------------------------------------------------------------------
+export function createVersionConflictDiagnostic(packageName, versions, registry) {
+    return {
+        level: 'error',
+        code: 'VERSION_CONFLICT',
+        message: `Version conflict for "${packageName}" in registry "${registry}": resolved to [${versions.join(', ')}].`,
+        hint: 'Single-version packages cannot coexist at multiple versions. Pin an explicit version or use overrides.',
+        data: { packageName, versions, registry },
+    };
+}
+export function createCircularDepDiagnostic(path) {
+    return {
+        level: 'error',
+        code: 'CIRCULAR_DEP',
+        message: `Circular dependency detected: ${path.join(' → ')}.`,
+        hint: 'Break the cycle by removing or restructuring the dependency.',
+        data: { path },
+    };
+}
+export function createPackageNotFoundDiagnostic(packageName, registry) {
+    return {
+        level: 'error',
+        code: 'PACKAGE_NOT_FOUND',
+        message: `Package "${packageName}" not found in registry "${registry}".`,
+        hint: 'Verify the package name and ensure the registry is up-to-date.',
+        data: { packageName, registry },
+    };
+}
+export function createVersionNotFoundDiagnostic(packageName, versionRange, registry, availableVersions) {
+    return {
+        level: 'error',
+        code: 'VERSION_NOT_FOUND',
+        message: `No version of "${packageName}" in registry "${registry}" satisfies "${versionRange}".`,
+        hint: `Available versions: ${availableVersions.length > 0 ? availableVersions.join(', ') : '(none)'}.`,
+        data: { packageName, versionRange, registry, availableVersions },
+    };
+}
+export function createRegistryNameCollisionDiagnostic(packageName, registries) {
+    return {
+        level: 'error',
+        code: 'REGISTRY_NAME_COLLISION',
+        message: `Package "${packageName}" is required from multiple registries: [${registries.join(', ')}].`,
+        hint: 'A package name must resolve from a single registry.',
+        data: { packageName, registries },
+    };
+}
+//# sourceMappingURL=ResolverDiagnostics.js.map

package/dist/resolver/ResolverDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResolverDiagnostics.js","sourceRoot":"","sources":["../../src/resolver/ResolverDiagnostics.ts"],"names":[],"mappings":"AA6DA,8EAA8E;AAC9E,kBAAkB;AAClB,8EAA8E;AAE9E,MAAM,UAAU,+BAA+B,CAC7C,WAAmB,EACnB,QAA2B,EAC3B,QAAgB;IAEhB,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,yBAAyB,WAAW,kBAAkB,QAAQ,mBAAmB,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACjH,IAAI,EAAE,wGAAwG;QAC9G,IAAI,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE;KAC1C,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,IAAuB;IACjE,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,iCAAiC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG;QAC7D,IAAI,EAAE,8DAA8D;QACpE,IAAI,EAAE,EAAE,IAAI,EAAE;KACf,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,WAAmB,EAAE,QAAgB;IACnF,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,YAAY,WAAW,4BAA4B,QAAQ,IAAI;QACxE,IAAI,EAAE,gEAAgE;QACtE,IAAI,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE;KAChC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,WAAmB,EACnB,YAAoB,EACpB,QAAgB,EAChB,iBAAoC;IAEpC,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,mBAAmB;QACzB,OAAO,EAAE,kBAAkB,WAAW,kBAAkB,QAAQ,gBAAgB,YAAY,IAAI;QAChG,IAAI,EAAE,uBAAuB,iBAAiB,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,GAAG;QACtG,IAAI,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,iBAAiB,EAAE;KACjE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,qCAAqC,CACnD,WAAmB,EACnB,UAA6B;IAE7B,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,yBAAyB;QAC/B,OAAO,EAAE,YAAY,WAAW,4CAA4C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QACrG,IAAI,EAAE,qDAAqD;QAC3D,IAAI,EAAE,EAAE,WAAW,EAAE,UAAU,EAAE;KAClC,CAAC;AACJ,CAAC"}

package/dist/safety/SafetyDiagnostics.d.ts

@@ -0,0 +1,31 @@
+import type { DiagnosticBase } from '../base/Diagnostic.js';
+/**
+ * A target install directory exists but has no `uapkg.json` inside.
+ * The installer refuses to overwrite because the directory's identity is
+ * unknown. Use `--force` to override.
+ */
+export type SafetyTargetExistsNoManifestDiagnostic = DiagnosticBase<'SAFETY_TARGET_EXISTS_NO_MANIFEST', {
+    readonly packageName: string;
+    readonly path: string;
+}>;
+/**
+ * A plugin-kind manifest declared a custom install `path` for one of its
+ * dependencies. Only project-kind manifests may override paths; plugins fall
+ * back to the default install location and this warning is emitted.
+ */
+export type SafetyPathNotProjectManifestDiagnostic = DiagnosticBase<'SAFETY_PATH_NOT_PROJECT_MANIFEST', {
+    readonly pluginName: string;
+    readonly dependencyName: string;
+    readonly requestedPath: string;
+    readonly fallbackPath: string;
+}>;
+/** Informational: a safety check was bypassed because --force was passed. */
+export type SafetyOverriddenByForceDiagnostic = DiagnosticBase<'SAFETY_OVERRIDDEN_BY_FORCE', {
+    readonly packageName: string;
+    readonly policy: string;
+}>;
+export type SafetyDiagnostic = SafetyTargetExistsNoManifestDiagnostic | SafetyPathNotProjectManifestDiagnostic | SafetyOverriddenByForceDiagnostic;
+export declare function createSafetyTargetExistsNoManifestDiagnostic(packageName: string, path: string): SafetyTargetExistsNoManifestDiagnostic;
+export declare function createSafetyPathNotProjectManifestDiagnostic(pluginName: string, dependencyName: string, requestedPath: string, fallbackPath: string): SafetyPathNotProjectManifestDiagnostic;
+export declare function createSafetyOverriddenByForceDiagnostic(packageName: string, policy: string): SafetyOverriddenByForceDiagnostic;
+//# sourceMappingURL=SafetyDiagnostics.d.ts.map

package/dist/safety/SafetyDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SafetyDiagnostics.d.ts","sourceRoot":"","sources":["../../src/safety/SafetyDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D;;;;GAIG;AACH,MAAM,MAAM,sCAAsC,GAAG,cAAc,CACjE,kCAAkC,EAClC;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,sCAAsC,GAAG,cAAc,CACjE,kCAAkC,EAClC;IACE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B,CACF,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,iCAAiC,GAAG,cAAc,CAC5D,4BAA4B,EAC5B;IACE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CACF,CAAC;AAEF,MAAM,MAAM,gBAAgB,GACxB,sCAAsC,GACtC,sCAAsC,GACtC,iCAAiC,CAAC;AAMtC,wBAAgB,4CAA4C,CAC1D,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,GACX,sCAAsC,CAQxC;AAED,wBAAgB,4CAA4C,CAC1D,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,sCAAsC,CAQxC;AAED,wBAAgB,uCAAuC,CACrD,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,iCAAiC,CAOnC"}

package/dist/safety/SafetyDiagnostics.js

@@ -0,0 +1,30 @@
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+export function createSafetyTargetExistsNoManifestDiagnostic(packageName, path) {
+    return {
+        level: 'error',
+        code: 'SAFETY_TARGET_EXISTS_NO_MANIFEST',
+        message: `Refusing to overwrite "${path}" (no uapkg.json found) for package "${packageName}".`,
+        hint: 'Remove the directory or re-run with --force to overwrite.',
+        data: { packageName, path },
+    };
+}
+export function createSafetyPathNotProjectManifestDiagnostic(pluginName, dependencyName, requestedPath, fallbackPath) {
+    return {
+        level: 'warning',
+        code: 'SAFETY_PATH_NOT_PROJECT_MANIFEST',
+        message: `Plugin "${pluginName}" requested install path "${requestedPath}" for "${dependencyName}"; using default "${fallbackPath}" instead.`,
+        hint: 'Only project-kind manifests may dictate install paths. Move the override to your project manifest.',
+        data: { pluginName, dependencyName, requestedPath, fallbackPath },
+    };
+}
+export function createSafetyOverriddenByForceDiagnostic(packageName, policy) {
+    return {
+        level: 'info',
+        code: 'SAFETY_OVERRIDDEN_BY_FORCE',
+        message: `Safety policy "${policy}" bypassed for "${packageName}" (--force).`,
+        data: { packageName, policy },
+    };
+}
+//# sourceMappingURL=SafetyDiagnostics.js.map

package/dist/safety/SafetyDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SafetyDiagnostics.js","sourceRoot":"","sources":["../../src/safety/SafetyDiagnostics.ts"],"names":[],"mappings":"AAgDA,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,UAAU,4CAA4C,CAC1D,WAAmB,EACnB,IAAY;IAEZ,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,kCAAkC;QACxC,OAAO,EAAE,0BAA0B,IAAI,wCAAwC,WAAW,IAAI;QAC9F,IAAI,EAAE,2DAA2D;QACjE,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE;KAC5B,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,4CAA4C,CAC1D,UAAkB,EAClB,cAAsB,EACtB,aAAqB,EACrB,YAAoB;IAEpB,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,kCAAkC;QACxC,OAAO,EAAE,WAAW,UAAU,6BAA6B,aAAa,UAAU,cAAc,qBAAqB,YAAY,YAAY;QAC7I,IAAI,EAAE,oGAAoG;QAC1G,IAAI,EAAE,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,EAAE;KAClE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uCAAuC,CACrD,WAAmB,EACnB,MAAc;IAEd,OAAO;QACL,KAAK,EAAE,MAAM;QACb,IAAI,EAAE,4BAA4B;QAClC,OAAO,EAAE,kBAAkB,MAAM,mBAAmB,WAAW,cAAc;QAC7E,IAAI,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE;KAC9B,CAAC;AACJ,CAAC"}

package/dist/spec/SpecDiagnostics.d.ts

@@ -0,0 +1,21 @@
+import type { DiagnosticBase } from '../base/Diagnostic.js';
+/** The raw CLI specifier could not be parsed into `(@org/)?name(@range)?`. */
+export type InvalidPackageSpecDiagnostic = DiagnosticBase<'INVALID_PACKAGE_SPEC', {
+    readonly input: string;
+    readonly reason: string;
+}>;
+/** Organization portion of a package spec was not a valid OrgName. */
+export type InvalidOrgNameDiagnostic = DiagnosticBase<'INVALID_ORG_NAME', {
+    readonly input: string;
+    readonly org: string;
+}>;
+/** Version range portion of a package spec was not a valid semver range. */
+export type InvalidVersionRangeDiagnostic = DiagnosticBase<'INVALID_VERSION_RANGE', {
+    readonly input: string;
+    readonly range: string;
+}>;
+export type SpecParseDiagnostic = InvalidPackageSpecDiagnostic | InvalidOrgNameDiagnostic | InvalidVersionRangeDiagnostic;
+export declare function createInvalidPackageSpecDiagnostic(input: string, reason: string): InvalidPackageSpecDiagnostic;
+export declare function createInvalidOrgNameDiagnostic(input: string, org: string): InvalidOrgNameDiagnostic;
+export declare function createInvalidVersionRangeDiagnostic(input: string, range: string): InvalidVersionRangeDiagnostic;
+//# sourceMappingURL=SpecDiagnostics.d.ts.map

package/dist/spec/SpecDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecDiagnostics.d.ts","sourceRoot":"","sources":["../../src/spec/SpecDiagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAM5D,8EAA8E;AAC9E,MAAM,MAAM,4BAA4B,GAAG,cAAc,CACvD,sBAAsB,EACtB;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CACF,CAAC;AAEF,sEAAsE;AACtE,MAAM,MAAM,wBAAwB,GAAG,cAAc,CACnD,kBAAkB,EAClB;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB,CACF,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,6BAA6B,GAAG,cAAc,CACxD,uBAAuB,EACvB;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CACF,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAC3B,4BAA4B,GAC5B,wBAAwB,GACxB,6BAA6B,CAAC;AAMlC,wBAAgB,kCAAkC,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,4BAA4B,CAQ9G;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,wBAAwB,CAQnG;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,6BAA6B,CAQ/G"}

package/dist/spec/SpecDiagnostics.js

@@ -0,0 +1,31 @@
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+export function createInvalidPackageSpecDiagnostic(input, reason) {
+    return {
+        level: 'error',
+        code: 'INVALID_PACKAGE_SPEC',
+        message: `Invalid package specifier "${input}": ${reason}.`,
+        hint: 'Use the form "(@org/)?name(@range)?" — e.g. "@myorg/my-pkg@^1.0.0".',
+        data: { input, reason },
+    };
+}
+export function createInvalidOrgNameDiagnostic(input, org) {
+    return {
+        level: 'error',
+        code: 'INVALID_ORG_NAME',
+        message: `Invalid organization name "${org}" in specifier "${input}".`,
+        hint: 'Organization names must be lowercase alphanumeric with hyphens or underscores.',
+        data: { input, org },
+    };
+}
+export function createInvalidVersionRangeDiagnostic(input, range) {
+    return {
+        level: 'error',
+        code: 'INVALID_VERSION_RANGE',
+        message: `Invalid semver range "${range}" in specifier "${input}".`,
+        hint: 'Use a valid semver range like "^1.0.0", "~2.3.4", or ">=1.0.0 <2.0.0".',
+        data: { input, range },
+    };
+}
+//# sourceMappingURL=SpecDiagnostics.js.map

package/dist/spec/SpecDiagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpecDiagnostics.js","sourceRoot":"","sources":["../../src/spec/SpecDiagnostics.ts"],"names":[],"mappings":"AAsCA,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,UAAU,kCAAkC,CAAC,KAAa,EAAE,MAAc;IAC9E,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,sBAAsB;QAC5B,OAAO,EAAE,8BAA8B,KAAK,MAAM,MAAM,GAAG;QAC3D,IAAI,EAAE,qEAAqE;QAC3E,IAAI,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE;KACxB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAa,EAAE,GAAW;IACvE,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,8BAA8B,GAAG,mBAAmB,KAAK,IAAI;QACtE,IAAI,EAAE,gFAAgF;QACtF,IAAI,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE;KACrB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,KAAa,EAAE,KAAa;IAC9E,OAAO;QACL,KAAK,EAAE,OAAO;QACd,IAAI,EAAE,uBAAuB;QAC7B,OAAO,EAAE,yBAAyB,KAAK,mBAAmB,KAAK,IAAI;QACnE,IAAI,EAAE,wEAAwE;QAC9E,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;KACvB,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+import type { ConfigDiagnostic } from './config/ConfigDiagnostics.js';
+import type { GeneralDiagnostic } from './general/GeneralDiagnostics.js';
+import type { InstallerDiagnostic } from './installer/InstallerDiagnostics.js';
+import type { ManifestDiagnostic } from './manifest/ManifestDiagnostics.js';
+import type { PackDiagnostic } from './pack/PackDiagnostics.js';
+import type { PostinstallDiagnostic } from './postinstall/PostinstallDiagnostics.js';
+import type { RegistryDiagnostic } from './registry/RegistryDiagnostics.js';
+import type { ResolverDiagnostic } from './resolver/ResolverDiagnostics.js';
+import type { SafetyDiagnostic } from './safety/SafetyDiagnostics.js';
+import type { SpecParseDiagnostic } from './spec/SpecDiagnostics.js';
+/**
+ * The unified Diagnostic type — a discriminated union of every known
+ * diagnostic, keyed on `code`.
+ *
+ * To add a new diagnostic:
+ *   1. Create its type in the appropriate family file.
+ *   2. Add it to that family's union.
+ *   3. It is automatically part of `Diagnostic` through this re-export.
+ */
+export type Diagnostic = ResolverDiagnostic | ConfigDiagnostic | RegistryDiagnostic | ManifestDiagnostic | PackDiagnostic | GeneralDiagnostic | InstallerDiagnostic | PostinstallDiagnostic | SafetyDiagnostic | SpecParseDiagnostic;
+/**
+ * Extract a specific diagnostic by code.
+ *
+ * @example
+ * type VC = DiagnosticByCode<'VERSION_CONFLICT'>;
+ */
+export type DiagnosticByCode<C extends Diagnostic['code']> = Extract<Diagnostic, {
+    code: C;
+}>;
+/** All known diagnostic codes. */
+export type DiagnosticCode = Diagnostic['code'];
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yCAAyC,CAAC;AACrF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE;;;;;;;;GAQG;AACH,MAAM,MAAM,UAAU,GAClB,kBAAkB,GAClB,gBAAgB,GAChB,kBAAkB,GAClB,kBAAkB,GAClB,cAAc,GACd,iBAAiB,GACjB,mBAAmB,GACnB,qBAAqB,GACrB,gBAAgB,GAChB,mBAAmB,CAAC;AAExB;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAE9F,kCAAkC;AAClC,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uapkg/diagnostics",
-  "version": "1.1.7",
+  "version": "1.1.9",
   "type": "module",
   "sideEffects": false,
   "files": [