@agentxm/registry-protocol 0.28.4-bootstrap.0

package/dist/src/unstable/lint/context.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Rule-context types and narrow accessors.
+ *
+ * Each rule-context type bundles a caller-decoded `subject` with a narrow
+ * caller-bound accessor and a `displayRoot` used for path rendering. Rules
+ * consume accessors as ordinary property access (no Layer wiring); tests pass
+ * literal fakes.
+ *
+ * Phase 2 pins the context shapes and accessor interfaces. Phases 3a, 3b, and
+ * 3c land the concrete `subject` decoders and VFT-/platform-backed accessor
+ * implementations.
+ *
+ * Accessor surfaces are intentionally minimal — rules SHALL see only the
+ * methods the v1 catalog requires. Extending a surface is a Phase 3a/3b/3c
+ * action with a documented rule consumer, not a free action.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import type * as Effect from "effect/Effect";
+import type { KnowledgeInspection } from "../knowledge/okf.js";
+/**
+ * Tagged error surfaced by `SkillFileAccessor` / `PackFileAccessor` when a
+ * read fails for reasons other than "file not found" (which is represented
+ * by `exists -> false`).
+ *
+ * Concrete implementations live in Phases 3a/3b; this interface fixes the
+ * error shape rules can rely on.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface FileAccessError {
+    readonly _tag: "FileAccessError";
+    /** Accessor-relative posix path that failed. */
+    readonly path: string;
+    /** Machine-readable reason. */
+    readonly reason: "path-escape" | "read-error" | "io-error";
+    /** Human-readable detail; no rendered display path. */
+    readonly message: string;
+}
+/**
+ * Narrow skill-rooted file accessor.
+ *
+ * Root is the directory containing `SKILL.md`. Paths are posix and relative
+ * to the root; implementations MUST reject path-traversal attempts (`..`,
+ * absolute paths, symlink escapes) by returning `false` from `exists` or
+ * failing `readBytes` with `FileAccessError { reason: "path-escape" }`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+/**
+ * Narrow pack-rooted file accessor.
+ *
+ * Root is the directory containing `pack.json`. Same traversal
+ * constraints as `SkillFileAccessor`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface PackFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+export interface SubagentFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+export interface McpServerFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+export interface HookFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+export interface RuleFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+export interface KnowledgeFileAccessor {
+    readonly exists: (path: string) => Effect.Effect<boolean>;
+    readonly readBytes: (path: string) => Effect.Effect<Uint8Array, FileAccessError>;
+}
+/**
+ * Context passed to `skill/*` rules.
+ *
+ * `subject` is the caller-decoded skill content (SKILL.md frontmatter +
+ * optional skill.json). Phase 3a refines the `subject` type to the concrete
+ * `SkillContent` shape; Phase 2 leaves it structurally open so the rule
+ * primitives don't need a circular dependency on the skill module.
+ *
+ * `displayRoot` is posix and relative; `""` means the accessor root is the
+ * rendering base. See `./compose-path.ts` for the four documented cases.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillRuleContext<S = SkillContent> {
+    readonly subject: S;
+    /**
+     * Content-root accessor. Rooted at the directory containing `SKILL.md`.
+     * For native (registry-installed) skills this is the `src/` sub-directory
+     * of the package; for non-native skills it is the skill's own
+     * directory. Rules validating skill content (`skill-md-present`,
+     * `frontmatter-parseable`, and any future rule evaluating files that
+     * render into agent directories) read through this accessor.
+     */
+    readonly files: SkillFileAccessor;
+    /**
+     * Package-root accessor. Rooted at the skill's package root —
+     * the directory containing `skill.json` for native skills. For non-native
+     * skills that have no package/content split, this MAY alias `files`.
+     * Rules validating package-shape concerns (`manifest-present` and any
+     * future rule inspecting files at or above the content root) read through
+     * this accessor.
+     */
+    readonly packageFiles: SkillFileAccessor;
+    readonly displayRoot: string;
+}
+/**
+ * Concrete subject shape passed to `skill/*` rules.
+ *
+ * Rules read `SKILL.md` bytes through `context.files` (the authoritative
+ * source shared across publish and `axm lint`). The `subject` carries only
+ * what rules can't efficiently re-derive from bytes:
+ *
+ * - `isNative` — whether the caller expects this skill to carry a
+ *   `skill.json` manifest. Native (registry-installed) skills set this to
+ *   `true`; non-native (managed external) skills set it to `false`. Rules
+ *   that depend on `skill.json` (`skill/manifest-present`,
+ *   `skill/manifest-schema-valid`, `skill/manifest-keys-recognized`)
+ *   early-return `[]` when `isNative === false`, so the same catalog covers
+ *   both.
+ * - `skillJson` — the already-decoded `skill.json` contents when present
+ *   (caller decodes once, rules don't re-read + re-parse). `undefined` when
+ *   the file is absent. Schema-valid rules pipe this into
+ *   `Schema.decodeUnknownResult(SkillManifestSchema)`; keys-recognized
+ *   enumerates top-level keys after narrowing to `Record<string, unknown>`.
+ *
+ * Workspace consumers build `SkillContent` via `buildSkillRuleContexts`
+ * against the lint workspace view; publish builds one `SkillContent` per
+ * incoming archive.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillContent {
+    readonly isNative: boolean;
+    readonly skillJson: unknown;
+    /** Agent-facing skill directory name used for the standard name-match check. */
+    readonly expectedName?: string;
+}
+/**
+ * Context passed to `pack/*` rules.
+ *
+ * `subject` is the caller-decoded pack content — concrete `PackContent` shape
+ * defined below. Packs are registry-only at v1 (no non-native arm), so the
+ * subject carries only the already-decoded manifest and rules read
+ * `pack.json` bytes through `context.files` as needed.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface PackRuleContext<S = PackContent> {
+    readonly subject: S;
+    readonly files: PackFileAccessor;
+    readonly displayRoot: string;
+}
+/**
+ * Concrete subject shape passed to `pack/*` rules.
+ *
+ * Rules read `pack.json` bytes through `context.files` (the
+ * authoritative source shared across publish and `axm lint`). The `subject`
+ * carries only what rules can't efficiently re-derive from bytes:
+ *
+ * - `packJson` — the already-decoded `pack.json` contents when
+ *   present (caller decodes once, rules don't re-read + re-parse).
+ *   `undefined` when the file is absent. Schema-valid rules pipe this into
+ *   `Schema.decodeUnknownResult(PackManifestSchema)`;
+ *   keys-recognized enumerates top-level keys after narrowing to
+ *   `Record<string, unknown>`.
+ *
+ * Unlike `SkillContent`, there is no `isNative` discriminator — packs are
+ * registry-only and every pack context is expected to expose a manifest.
+ * The presence rule (`pack/manifest-present`) owns the absence arm.
+ *
+ * Workspace consumers build `PackContent` via `buildPackRuleContexts`
+ * against the lint workspace view; publish builds one `PackContent` per
+ * incoming archive.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface PackContent {
+    readonly packJson: unknown;
+}
+export interface SubagentRuleContext<S = SubagentContent> {
+    readonly subject: S;
+    readonly files: SubagentFileAccessor;
+    readonly displayRoot: string;
+}
+export interface SubagentContent {
+    readonly subagentJson: unknown;
+}
+export interface McpServerRuleContext<S = McpServerContent> {
+    readonly subject: S;
+    readonly files: McpServerFileAccessor;
+    readonly displayRoot: string;
+}
+export interface McpServerContent {
+    readonly mcpServerJson: unknown;
+}
+export interface HookRuleContext<S = HookContent> {
+    readonly subject: S;
+    readonly files: HookFileAccessor;
+    readonly displayRoot: string;
+}
+export interface HookContent {
+    readonly hookJson: unknown;
+}
+/**
+ * Context passed to `rule/*` rules.
+ *
+ * The doubled word is unavoidable: `rule` is an extension type and `rule` is
+ * also the lint primitive, so the context for the `rule` extension type is a
+ * `RuleRuleContext`. Every other name here follows `<Type>RuleContext`.
+ */
+export interface RuleRuleContext<S = RuleContent> {
+    readonly subject: S;
+    readonly files: RuleFileAccessor;
+    readonly displayRoot: string;
+}
+export interface RuleContent {
+    readonly ruleJson: unknown;
+}
+export interface KnowledgeRuleContext<S = KnowledgeContent> {
+    readonly subject: S;
+    readonly files: KnowledgeFileAccessor;
+    readonly displayRoot: string;
+    /** Absolute package root used once while constructing the cached inspection. */
+    readonly packageRoot?: string;
+}
+export interface KnowledgeContent {
+    readonly knowledgeJson: unknown;
+    readonly inspection?: KnowledgeInspection;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/src/unstable/lint/context.js

@@ -0,0 +1,21 @@
+/**
+ * Rule-context types and narrow accessors.
+ *
+ * Each rule-context type bundles a caller-decoded `subject` with a narrow
+ * caller-bound accessor and a `displayRoot` used for path rendering. Rules
+ * consume accessors as ordinary property access (no Layer wiring); tests pass
+ * literal fakes.
+ *
+ * Phase 2 pins the context shapes and accessor interfaces. Phases 3a, 3b, and
+ * 3c land the concrete `subject` decoders and VFT-/platform-backed accessor
+ * implementations.
+ *
+ * Accessor surfaces are intentionally minimal — rules SHALL see only the
+ * methods the v1 catalog requires. Extending a surface is a Phase 3a/3b/3c
+ * action with a documented rule consumer, not a free action.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=context.js.map

package/dist/src/unstable/lint/describe-document.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The one place lint turns a document filename into the human label that opens
+ * a finding message ("Skill manifest has unrecognized top-level field ...").
+ *
+ * Three copies of this switch used to exist — one in `issues-to-findings.ts`,
+ * one in `catalog/shared/schema-rule.ts`, one in
+ * `catalog/shared/manifest-json.ts` — and they had drifted: only one knew
+ * `hook.json`, none knew `rule.json` or `knowledge.json`, and the parse-failure
+ * copy defaulted to "Manifest" where the others defaulted to "Document".
+ *
+ * The manifest labels are derived from `MANIFEST_FILENAME_BY_TYPE` and
+ * `extensionTypeSentenceLabels`, both of which are total over `ExtensionType`,
+ * so a new extension type gets a label the moment its row lands in
+ * `EXTENSION_TYPE_TABLE`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+/** Label used when a filename matches no known document. */
+export declare const UNKNOWN_DOCUMENT_LABEL = "Document";
+/**
+ * Describe the document at `file` for use as the subject of a finding message.
+ *
+ * Keyed by basename, so both bare accessor-relative filenames (`hook.json`,
+ * as the per-extension rules pass) and workspace-relative paths
+ * (`axm.json`, as `issues-to-findings` passes) resolve.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const describeSchemaDocument: (file: string) => string;
+//# sourceMappingURL=describe-document.d.ts.map

package/dist/src/unstable/lint/describe-document.js

@@ -0,0 +1,50 @@
+/**
+ * The one place lint turns a document filename into the human label that opens
+ * a finding message ("Skill manifest has unrecognized top-level field ...").
+ *
+ * Three copies of this switch used to exist — one in `issues-to-findings.ts`,
+ * one in `catalog/shared/schema-rule.ts`, one in
+ * `catalog/shared/manifest-json.ts` — and they had drifted: only one knew
+ * `hook.json`, none knew `rule.json` or `knowledge.json`, and the parse-failure
+ * copy defaulted to "Manifest" where the others defaulted to "Document".
+ *
+ * The manifest labels are derived from `MANIFEST_FILENAME_BY_TYPE` and
+ * `extensionTypeSentenceLabels`, both of which are total over `ExtensionType`,
+ * so a new extension type gets a label the moment its row lands in
+ * `EXTENSION_TYPE_TABLE`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import { extensionTypeSentenceLabels, extensionTypes, } from "@agentxm/extension-model/unstable/extensions/common";
+import { LOCKFILE_NAME } from "@agentxm/extension-model/unstable/workspace-files";
+import { MANIFEST_FILENAME_BY_TYPE } from "../publish/manifest-policy.js";
+import { SETTINGS_FILENAME } from "@agentxm/extension-model/unstable/workspace-files";
+/** Label used when a filename matches no known document. */
+export const UNKNOWN_DOCUMENT_LABEL = "Document";
+const capitalizeFirst = (value) => value.length === 0 ? value : `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+// eslint-disable-next-line no-restricted-syntax -- Immutable lookup over the closed manifest filename vocabulary.
+const documentLabels = new Map([
+    ...extensionTypes.map((type) => [
+        MANIFEST_FILENAME_BY_TYPE[type],
+        `${capitalizeFirst(extensionTypeSentenceLabels[type])} manifest`,
+    ]),
+    [SETTINGS_FILENAME, "Workspace settings"],
+    [LOCKFILE_NAME, "Lockfile"],
+]);
+const basename = (file) => {
+    const normalized = file.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    return parts[parts.length - 1] ?? normalized;
+};
+/**
+ * Describe the document at `file` for use as the subject of a finding message.
+ *
+ * Keyed by basename, so both bare accessor-relative filenames (`hook.json`,
+ * as the per-extension rules pass) and workspace-relative paths
+ * (`axm.json`, as `issues-to-findings` passes) resolve.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const describeSchemaDocument = (file) => documentLabels.get(basename(file)) ?? UNKNOWN_DOCUMENT_LABEL;
+//# sourceMappingURL=describe-document.js.map

package/dist/src/unstable/lint/evaluate.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Pure evaluator for the lint engine.
+ *
+ * `evaluateContexts(rules, contexts, config)` pairs each rule with each context,
+ * invokes `rule.check`, applies permitted severity overrides from
+ * `config.rules`, and drops warning findings configured `"off"`.
+ *
+ * Both functions are plain `Effect` values; neither requires a Layer or an
+ * ambient service. See the `lint-engine` design doc §3 for the rationale
+ * behind library primitives over a central engine service.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+import type { LintConfig } from "./config.js";
+import type { LintFinding, LintRule } from "./rule.js";
+/**
+ * One `(rule, context, findings)` evaluation result.
+ *
+ * `findings` is emitted after severity overrides from `config.rules` have been
+ * applied; rule-level severity is the platform default, finding-level severity
+ * is the effective post-override severity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface Evaluated<C> {
+    readonly rule: LintRule<C>;
+    readonly context: C;
+    readonly findings: ReadonlyArray<LintFinding>;
+}
+/**
+ * Pair each rule with each context, run `rule.check`, apply severity overrides
+ * from `config.rules`, and return one `Evaluated<C>` per pair.
+ *
+ * Findings whose configured severity is `"off"` are suppressed entirely; the
+ * `Evaluated` entry still ships (with an empty `findings` array) so consumers
+ * that group by rule still see the rule ran.
+ *
+ * Rules are evaluated in catalog order; contexts are evaluated in caller
+ * order. Rule-context invocation is sequential within a single
+ * `evaluateContexts` call so tests can observe deterministic ordering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const evaluateContexts: <C>(rules: ReadonlyArray<LintRule<C>>, contexts: ReadonlyArray<C>, config: LintConfig) => Effect.Effect<ReadonlyArray<Evaluated<C>>>;
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/src/unstable/lint/evaluate.js

@@ -0,0 +1,82 @@
+/**
+ * Pure evaluator for the lint engine.
+ *
+ * `evaluateContexts(rules, contexts, config)` pairs each rule with each context,
+ * invokes `rule.check`, applies permitted severity overrides from
+ * `config.rules`, and drops warning findings configured `"off"`.
+ *
+ * Both functions are plain `Effect` values; neither requires a Layer or an
+ * ambient service. See the `lint-engine` design doc §3 for the rationale
+ * behind library primitives over a central engine service.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Effect from "effect/Effect";
+// -----------------------------------------------------------------------------
+// Severity override
+// -----------------------------------------------------------------------------
+/**
+ * Translate a `LintRuleSeverity` config value into an effective `Severity`
+ * or the `"off"` sentinel. `"warn"` maps to `"warning"` so downstream code
+ * sees the canonical three-severity alphabet.
+ *
+ * `config.rules` keys are exact rule ids with no wildcard / glob support in v1;
+ * see `./config.ts` for the schema.
+ */
+const translateConfigValue = (value) => {
+    switch (value) {
+        case "warn":
+            return "warning";
+        case "off":
+        case "info":
+        case "error":
+            return value;
+    }
+};
+const applyOverride = (defaultSeverity, override) => {
+    if (defaultSeverity === "error") {
+        return "error";
+    }
+    if (override === undefined) {
+        return defaultSeverity;
+    }
+    const translated = translateConfigValue(override);
+    return defaultSeverity === "warning" && translated === "info" ? "warning" : translated;
+};
+const withSeverity = (finding, severity) => ({
+    ...finding,
+    severity,
+});
+// -----------------------------------------------------------------------------
+// evaluateContexts
+// -----------------------------------------------------------------------------
+/**
+ * Pair each rule with each context, run `rule.check`, apply severity overrides
+ * from `config.rules`, and return one `Evaluated<C>` per pair.
+ *
+ * Findings whose configured severity is `"off"` are suppressed entirely; the
+ * `Evaluated` entry still ships (with an empty `findings` array) so consumers
+ * that group by rule still see the rule ran.
+ *
+ * Rules are evaluated in catalog order; contexts are evaluated in caller
+ * order. Rule-context invocation is sequential within a single
+ * `evaluateContexts` call so tests can observe deterministic ordering.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const evaluateContexts = (rules, contexts, config) => Effect.forEach(rules.flatMap((rule) => contexts.map((context) => ({ rule, context }))), ({ rule, context }) => evaluateOne(rule, context, config), { concurrency: 1 });
+const evaluateOne = (rule, context, config) => Effect.map(rule.check(context), (rawFindings) => ({
+    rule,
+    context,
+    findings: applySeverityConfig(rule, rawFindings, config),
+}));
+const applySeverityConfig = (rule, findings, config) => {
+    const override = config.rules?.[rule.id];
+    const effective = applyOverride(rule.severity, override);
+    if (effective === "off") {
+        return [];
+    }
+    return findings.map((finding) => withSeverity(finding, effective));
+};
+//# sourceMappingURL=evaluate.js.map

package/dist/src/unstable/lint/issues-to-findings.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `issuesToFindings` — shared schema-delegation helper.
+ *
+ * `-schema-valid` rules delegate their `check` to Effect Schema via
+ * `Schema.decodeUnknownResult(schema, { onExcessProperty: "ignore" })` (or the
+ * Effect/Exit equivalents) and map the resulting `Issue` tree 1:1 to
+ * `AdvisoryFinding`s through this helper. Rules never re-implement schema
+ * checks inline; the paired `-keys-recognized` rule owns unknown-key hygiene
+ * at warning severity.
+ *
+ * The helper walks the recursive `SchemaIssue.Issue` tree, accumulating a
+ * path at each `Pointer` node and emitting one finding per leaf issue.
+ * Composite nodes recurse into their children. Each finding's `message`
+ * is branch-specific and guide-conformant: invariant failure first, raw
+ * schema detail second when needed, remediation last. `location.file` is the
+ * caller-supplied file (the manifest file); v1 does not parse byte positions
+ * out of `Issue` values.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as SchemaIssue from "effect/SchemaIssue";
+import type { AdvisoryFinding, Severity } from "./rule.js";
+/**
+ * Walk an `Issue` tree and produce one finding per leaf issue.
+ *
+ * @param ruleId    - `<namespace>/<name>` id of the calling rule.
+ * @param severity  - Severity to stamp on each emitted finding.
+ * @param file      - Accessor-relative file path to stamp on `location.file`.
+ * @param issue     - Root `Issue` produced by `Schema.decodeUnknown*`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const issuesToFindings: (ruleId: string, severity: Severity, file: string, issue: SchemaIssue.Issue) => ReadonlyArray<AdvisoryFinding>;
+//# sourceMappingURL=issues-to-findings.d.ts.map

package/dist/src/unstable/lint/issues-to-findings.js

@@ -0,0 +1,149 @@
+/**
+ * `issuesToFindings` — shared schema-delegation helper.
+ *
+ * `-schema-valid` rules delegate their `check` to Effect Schema via
+ * `Schema.decodeUnknownResult(schema, { onExcessProperty: "ignore" })` (or the
+ * Effect/Exit equivalents) and map the resulting `Issue` tree 1:1 to
+ * `AdvisoryFinding`s through this helper. Rules never re-implement schema
+ * checks inline; the paired `-keys-recognized` rule owns unknown-key hygiene
+ * at warning severity.
+ *
+ * The helper walks the recursive `SchemaIssue.Issue` tree, accumulating a
+ * path at each `Pointer` node and emitting one finding per leaf issue.
+ * Composite nodes recurse into their children. Each finding's `message`
+ * is branch-specific and guide-conformant: invariant failure first, raw
+ * schema detail second when needed, remediation last. `location.file` is the
+ * caller-supplied file (the manifest file); v1 does not parse byte positions
+ * out of `Issue` values.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as SchemaIssue from "effect/SchemaIssue";
+import { describeSchemaDocument } from "./describe-document.js";
+// -----------------------------------------------------------------------------
+// Public helper
+// -----------------------------------------------------------------------------
+/**
+ * Walk an `Issue` tree and produce one finding per leaf issue.
+ *
+ * @param ruleId    - `<namespace>/<name>` id of the calling rule.
+ * @param severity  - Severity to stamp on each emitted finding.
+ * @param file      - Accessor-relative file path to stamp on `location.file`.
+ * @param issue     - Root `Issue` produced by `Schema.decodeUnknown*`.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export const issuesToFindings = (ruleId, severity, file, issue) => {
+    const findings = [];
+    walkIssue(issue, [], (leaf, path) => {
+        findings.push(toFinding(ruleId, severity, file, leaf, path));
+    });
+    return findings;
+};
+const walkIssue = (issue, path, visit) => {
+    switch (issue._tag) {
+        case "Pointer": {
+            walkIssue(issue.issue, [...path, ...issue.path], visit);
+            return;
+        }
+        case "Composite":
+        case "AnyOf": {
+            if (issue.issues.length === 0) {
+                // No union member matched / no nested issues — treat as a leaf so
+                // the caller sees at least one finding for the covering diagnostic.
+                visit(issue, path);
+                return;
+            }
+            for (const child of issue.issues) {
+                walkIssue(child, path, visit);
+            }
+            return;
+        }
+        case "Filter":
+        case "Encoding": {
+            walkIssue(issue.issue, path, visit);
+            return;
+        }
+        case "InvalidType":
+        case "InvalidValue":
+        case "MissingKey":
+        case "UnexpectedKey":
+        case "Forbidden":
+        case "OneOf": {
+            visit(issue, path);
+            return;
+        }
+    }
+};
+const toFinding = (ruleId, severity, file, issue, path) => {
+    return {
+        kind: "advisory",
+        ruleId,
+        severity,
+        message: formatIssueMessage(describeSchemaDocument(file), file, issue, path),
+        location: { file },
+    };
+};
+const formatIssueMessage = (documentLabel, file, issue, path) => {
+    const pathStr = formatPath(path);
+    const valueRef = describeValueReference(documentLabel, pathStr);
+    switch (issue._tag) {
+        case "MissingKey":
+            return formatMissingKeyMessage(documentLabel, file, path, pathStr);
+        case "UnexpectedKey":
+            return formatUnexpectedKeyMessage(documentLabel, file, pathStr);
+        case "InvalidType":
+            return `${valueRef} has the wrong type. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "replace it with a value of the expected type")}`;
+        case "InvalidValue":
+            return `${valueRef} is invalid. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "update it so it satisfies the schema constraint")}`;
+        case "Forbidden":
+            return `${valueRef} uses a value or operation the schema does not allow. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "update it so the document satisfies the schema")}`;
+        case "OneOf":
+            return `${valueRef} matches more than one allowed shape. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "rewrite it so exactly one allowed shape matches")}`;
+        case "AnyOf":
+            return `${valueRef} does not match any allowed shape. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "rewrite it so it matches one of the allowed shapes")}`;
+        case "Filter":
+            return `${valueRef} fails a schema constraint. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "update it so it satisfies the constraint")}`;
+        case "Encoding":
+            return `${valueRef} cannot be encoded or decoded as required by the schema. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "update it to the shape the schema expects")}`;
+        case "Pointer":
+            return `${documentLabel} has a schema problem${pathStr === "" ? "" : ` at ${pathStr}`}. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "fix the value at that path so the document satisfies the schema")}`;
+        case "Composite":
+            return `${valueRef} has multiple schema problems. Detail: ${formatSchemaIssue(issue)}. ${formatRemediation(file, "fix the referenced values so the document satisfies the schema")}`;
+    }
+};
+const formatSchemaIssue = SchemaIssue.makeFormatterDefault();
+const formatMissingKeyMessage = (documentLabel, file, path, pathStr) => {
+    const lastSegment = path[path.length - 1];
+    const parentPath = formatPath(path.slice(0, -1));
+    if (typeof lastSegment === "string" && pathStr !== "") {
+        return parentPath === ""
+            ? `${documentLabel} is missing required field \`${pathStr}\`. ${formatRemediation(file, `add \`${lastSegment}\``)}`
+            : `${documentLabel} is missing required field \`${pathStr}\`. ${formatRemediation(file, `add \`${lastSegment}\` under \`${parentPath}\``)}`;
+    }
+    if (lastSegment !== undefined && pathStr !== "") {
+        return `${documentLabel} is missing a required item at \`${pathStr}\`. ${formatRemediation(file, "add the missing item at that path")}`;
+    }
+    return `${documentLabel} is missing a required value. ${formatRemediation(file, "add the required value")}`;
+};
+const formatUnexpectedKeyMessage = (documentLabel, file, pathStr) => pathStr === ""
+    ? `${documentLabel} has an unrecognized field. ${formatRemediation(file, "remove it or rename it to the intended field name")}`
+    : `${documentLabel} has unrecognized field \`${pathStr}\`. ${formatRemediation(file, "remove it or rename it to the intended field name")}`;
+const describeValueReference = (documentLabel, pathStr) => pathStr === "" ? documentLabel : `${documentLabel} field \`${pathStr}\``;
+const formatRemediation = (file, manualAction) => isLockfile(file)
+    ? "Regenerate the workspace lockfile from workspace settings by reinstalling the declared extensions."
+    : `Edit \`${file}\` and ${manualAction}.`;
+const formatPath = (path) => path.reduce((acc, segment) => {
+    if (typeof segment === "number") {
+        return `${acc}[${String(segment)}]`;
+    }
+    return acc === "" ? String(segment) : `${acc}.${String(segment)}`;
+}, "");
+const basename = (file) => {
+    const normalized = file.replace(/\\/g, "/");
+    const parts = normalized.split("/");
+    return parts[parts.length - 1] ?? normalized;
+};
+const isLockfile = (file) => basename(file) === "axm-lock.yaml";
+//# sourceMappingURL=issues-to-findings.js.map