@shrkcrft/inspector 0.1.0-alpha.1

package/dist/onboarding-drafts-merge.js

@@ -0,0 +1,174 @@
+/**
+ * Three-way merge for onboarding drafts.
+ *
+ * When `shrk onboard --write-drafts` re-runs against a project that has
+ * hand-edited drafts, the safe behaviour is to merge the new proposal
+ * against the user's current file and the snapshot we wrote last time:
+ *
+ *   - base    : `.sharkcraft/onboarding-drafts-snapshots/<file>` (what we
+ *               wrote last). When absent, the merge degrades to a strict
+ *               "matches proposal → no-op, otherwise conflict" rule.
+ *   - ours    : the current `sharkcraft/onboarding/<file>` content.
+ *   - theirs  : the freshly rendered proposal we are about to write.
+ *
+ * The merge always returns an intended `body`. The caller decides whether
+ * to write it (e.g. `abortOnConflict` keeps the file unchanged).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export var DraftMergeStatus;
+(function (DraftMergeStatus) {
+    /** File did not exist; the proposal was written verbatim. */
+    DraftMergeStatus["Created"] = "created";
+    /** Current file already matches the proposal — nothing to do. */
+    DraftMergeStatus["Unchanged"] = "unchanged";
+    /** Current file matches the snapshot; the proposal was applied. */
+    DraftMergeStatus["CleanUpdate"] = "clean-update";
+    /** Proposal matches the snapshot; the user's edits were kept. */
+    DraftMergeStatus["UserKept"] = "user-kept";
+    /** Disjoint single-region edits on both sides; auto-merged. */
+    DraftMergeStatus["AutoMerged"] = "auto-merged";
+    /** Both sides changed the same region — conflict markers emitted. */
+    DraftMergeStatus["Conflict"] = "conflict";
+    /** Both sides changed but `abortOnConflict` was set — file untouched. */
+    DraftMergeStatus["Aborted"] = "aborted";
+})(DraftMergeStatus || (DraftMergeStatus = {}));
+/**
+ * Resolve the snapshot path for a given draft file.
+ *
+ * @param projectRoot Absolute repo root.
+ * @param draftPath   Absolute path of the draft file.
+ */
+export function snapshotPathFor(projectRoot, draftPath) {
+    const rel = nodePath.relative(nodePath.join(projectRoot, 'sharkcraft', 'onboarding'), draftPath);
+    return nodePath.join(projectRoot, '.sharkcraft', 'onboarding-drafts-snapshots', rel);
+}
+export function readSnapshot(snapshotPath) {
+    if (!existsSync(snapshotPath))
+        return null;
+    try {
+        return readFileSync(snapshotPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSnapshot(snapshotPath, body) {
+    mkdirSync(nodePath.dirname(snapshotPath), { recursive: true });
+    writeFileSync(snapshotPath, body, 'utf8');
+}
+/**
+ * Three-way merge a single draft file.
+ *
+ * Truth table:
+ *   - !exists(ours)           → Created (body = theirs)
+ *   - ours === theirs         → Unchanged
+ *   - base === null:
+ *       - ours === theirs     → Unchanged
+ *       - otherwise           → Conflict (or Aborted)
+ *   - ours === base           → CleanUpdate (body = theirs)
+ *   - theirs === base         → UserKept (body = ours)
+ *   - otherwise               → diff3Lines → AutoMerged | Conflict | Aborted
+ */
+export function threeWayMergeDraft(base, ours, theirs, options = {}) {
+    if (ours === null) {
+        return { status: DraftMergeStatus.Created, body: theirs, conflictRegions: 0 };
+    }
+    if (ours === theirs) {
+        return { status: DraftMergeStatus.Unchanged, body: ours, conflictRegions: 0 };
+    }
+    if (base === null) {
+        return wholeFileConflict(ours, theirs, options);
+    }
+    if (ours === base) {
+        return { status: DraftMergeStatus.CleanUpdate, body: theirs, conflictRegions: 0 };
+    }
+    if (theirs === base) {
+        return { status: DraftMergeStatus.UserKept, body: ours, conflictRegions: 0 };
+    }
+    return diff3Lines(base, ours, theirs, options);
+}
+/**
+ * Coarse-grained line-level three-way merge.
+ *
+ * Strips the common prefix and suffix lines, then inspects the centre:
+ *   - centre(ours) === centre(base)   → take theirs
+ *   - centre(theirs) === centre(base) → take ours
+ *   - centre(ours) === centre(theirs) → take either
+ *   - otherwise                       → emit conflict markers around the centre
+ *
+ * Multiple disjoint edit regions fall through to conflict; that's a
+ * deliberate trade-off — anything subtler than a single contiguous edit
+ * is exactly the case a human should review.
+ */
+function diff3Lines(base, ours, theirs, options) {
+    const baseLines = base.split('\n');
+    const oursLines = ours.split('\n');
+    const theirsLines = theirs.split('\n');
+    let prefix = 0;
+    const maxPrefix = Math.min(baseLines.length, oursLines.length, theirsLines.length);
+    while (prefix < maxPrefix &&
+        baseLines[prefix] === oursLines[prefix] &&
+        baseLines[prefix] === theirsLines[prefix]) {
+        prefix += 1;
+    }
+    let suffix = 0;
+    const maxSuffix = Math.min(baseLines.length, oursLines.length, theirsLines.length) - prefix;
+    while (suffix < maxSuffix &&
+        baseLines[baseLines.length - 1 - suffix] === oursLines[oursLines.length - 1 - suffix] &&
+        baseLines[baseLines.length - 1 - suffix] === theirsLines[theirsLines.length - 1 - suffix]) {
+        suffix += 1;
+    }
+    const baseCentre = baseLines.slice(prefix, baseLines.length - suffix).join('\n');
+    const oursCentre = oursLines.slice(prefix, oursLines.length - suffix).join('\n');
+    const theirsCentre = theirsLines.slice(prefix, theirsLines.length - suffix).join('\n');
+    const headLines = oursLines.slice(0, prefix);
+    const tailLines = oursLines.slice(oursLines.length - suffix);
+    if (oursCentre === baseCentre) {
+        // Only theirs diverged.
+        const merged = [...headLines, ...theirsLines.slice(prefix, theirsLines.length - suffix), ...tailLines].join('\n');
+        return { status: DraftMergeStatus.AutoMerged, body: merged, conflictRegions: 0 };
+    }
+    if (theirsCentre === baseCentre) {
+        // Only ours diverged.
+        return { status: DraftMergeStatus.UserKept, body: ours, conflictRegions: 0 };
+    }
+    if (oursCentre === theirsCentre) {
+        // Both sides made identical changes.
+        const merged = [...headLines, ...oursLines.slice(prefix, oursLines.length - suffix), ...tailLines].join('\n');
+        return { status: DraftMergeStatus.AutoMerged, body: merged, conflictRegions: 0 };
+    }
+    if (options.abortOnConflict) {
+        return { status: DraftMergeStatus.Aborted, body: ours, conflictRegions: 1 };
+    }
+    const oursLabel = options.oursLabel ?? 'ours';
+    const theirsLabel = options.theirsLabel ?? 'incoming proposal';
+    const markerOpen = `<<<<<<< ${oursLabel}`;
+    const markerMid = '=======';
+    const markerClose = `>>>>>>> ${theirsLabel}`;
+    const conflictBlock = [
+        markerOpen,
+        oursCentre,
+        markerMid,
+        theirsCentre,
+        markerClose,
+    ];
+    const body = [...headLines, ...conflictBlock, ...tailLines].join('\n');
+    return { status: DraftMergeStatus.Conflict, body, conflictRegions: 1 };
+}
+function wholeFileConflict(ours, theirs, options) {
+    if (options.abortOnConflict) {
+        return { status: DraftMergeStatus.Aborted, body: ours, conflictRegions: 1 };
+    }
+    const oursLabel = options.oursLabel ?? 'ours';
+    const theirsLabel = options.theirsLabel ?? 'incoming proposal';
+    const body = [
+        `<<<<<<< ${oursLabel}`,
+        ours.replace(/\n$/, ''),
+        '=======',
+        theirs.replace(/\n$/, ''),
+        `>>>>>>> ${theirsLabel}`,
+        '',
+    ].join('\n');
+    return { status: DraftMergeStatus.Conflict, body, conflictRegions: 1 };
+}

package/dist/onboarding-drafts.d.ts

@@ -0,0 +1,42 @@
+import type { IOnboardingPlan } from './onboarding.js';
+import type { IImportedAgentRulesBundle } from './onboarding-agent-import.js';
+import { DraftMergeStatus } from './onboarding-drafts-merge.js';
+export interface IWrittenDraft {
+    path: string;
+    bytes: number;
+    /** Three-way merge status for this draft. */
+    mergeStatus: DraftMergeStatus;
+    /** Number of conflict regions emitted into `path` (0 unless status=Conflict). */
+    conflictRegions: number;
+}
+export interface IWriteOnboardingDraftsOptions {
+    projectRoot: string;
+    /** Override the output directory. Default: `<projectRoot>/sharkcraft/onboarding`. */
+    outDir?: string;
+    /**
+     * When provided, write an additional `imported-agent-rules.draft.ts` file
+     * containing the entries parsed from AGENTS.md / CLAUDE.md / .cursor/rules.
+     * The file is still under the onboarding/ subdir — never written to rules.ts.
+     */
+    importedAgentRules?: IImportedAgentRulesBundle;
+    /**
+     * When true, conflicts leave the existing file unchanged and report status
+     * via the result. Useful for CI gates.
+     */
+    abortOnConflict?: boolean;
+}
+export interface IWriteOnboardingDraftsResult {
+    outDir: string;
+    files: IWrittenDraft[];
+    /** Total number of draft files that ended in a Conflict status. */
+    conflicts: number;
+    /** Total number of draft files left untouched because abortOnConflict was set. */
+    aborted: number;
+}
+/**
+ * Write onboarding drafts under sharkcraft/onboarding/. This function NEVER
+ * writes outside that subdirectory (the caller can override the location, but
+ * the function refuses any path that escapes the resolved outDir).
+ */
+export declare function writeOnboardingDrafts(plan: IOnboardingPlan, options: IWriteOnboardingDraftsOptions): IWriteOnboardingDraftsResult;
+//# sourceMappingURL=onboarding-drafts.d.ts.map

package/dist/onboarding-drafts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-drafts.d.ts","sourceRoot":"","sources":["../src/onboarding-drafts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAA8B,MAAM,iBAAiB,CAAC;AAEnF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,8BAA8B,CAAC;AAC9E,OAAO,EACL,gBAAgB,EAMjB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,6CAA6C;IAC7C,WAAW,EAAE,gBAAgB,CAAC;IAC9B,iFAAiF;IACjF,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,6BAA6B;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,yBAAyB,CAAC;IAC/C;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,OAAO,EAAE,6BAA6B,GACrC,4BAA4B,CA+C9B"}

package/dist/onboarding-drafts.js

@@ -0,0 +1,268 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { renderOnboardingReport } from "./onboarding-report.js";
+import { DraftMergeStatus, readSnapshot, snapshotPathFor, threeWayMergeDraft, writeSnapshot, } from "./onboarding-drafts-merge.js";
+/**
+ * Write onboarding drafts under sharkcraft/onboarding/. This function NEVER
+ * writes outside that subdirectory (the caller can override the location, but
+ * the function refuses any path that escapes the resolved outDir).
+ */
+export function writeOnboardingDrafts(plan, options) {
+    const outDir = nodePath.resolve(options.outDir ??
+        nodePath.join(options.projectRoot, 'sharkcraft', 'onboarding'));
+    ensureDir(outDir);
+    const files = [];
+    const write = (name, proposal) => {
+        const full = nodePath.join(outDir, name);
+        // Belt-and-braces: refuse anything that escapes outDir.
+        if (!full.startsWith(outDir + nodePath.sep)) {
+            throw new Error(`draft path escapes outDir: ${name}`);
+        }
+        const merge = mergeDraft(options.projectRoot, full, proposal, options);
+        if (merge.status !== DraftMergeStatus.Aborted) {
+            writeFileSync(full, merge.body, 'utf8');
+            // Snapshot what we just wrote so the next run has a fresh `base`.
+            writeSnapshot(snapshotPathFor(options.projectRoot, full), merge.body);
+        }
+        files.push({
+            path: full,
+            bytes: Buffer.byteLength(merge.body, 'utf8'),
+            mergeStatus: merge.status,
+            conflictRegions: merge.conflictRegions,
+        });
+    };
+    write('onboarding-report.md', renderOnboardingReport(plan));
+    write('inferred-rules.draft.ts', renderInferredRulesDraft(plan));
+    write('inferred-paths.draft.ts', renderInferredPathsDraft(plan));
+    write('inferred-templates.draft.ts', renderInferredTemplatesDraft(plan));
+    write('inferred-boundaries.draft.ts', renderInferredBoundariesDraft(plan));
+    write('inferred-pipelines.draft.ts', renderInferredPipelinesDraft(plan));
+    if (options.importedAgentRules && options.importedAgentRules.entries.length > 0) {
+        write('imported-agent-rules.draft.ts', renderImportedAgentRulesDraft(options.importedAgentRules));
+    }
+    let conflicts = 0;
+    let aborted = 0;
+    for (const f of files) {
+        if (f.mergeStatus === DraftMergeStatus.Conflict)
+            conflicts += 1;
+        else if (f.mergeStatus === DraftMergeStatus.Aborted)
+            aborted += 1;
+    }
+    return { outDir, files, conflicts, aborted };
+}
+function mergeDraft(projectRoot, draftPath, proposal, options) {
+    const ours = existsSync(draftPath) ? safeRead(draftPath) : null;
+    const base = readSnapshot(snapshotPathFor(projectRoot, draftPath));
+    return threeWayMergeDraft(base, ours, proposal, {
+        abortOnConflict: options.abortOnConflict ?? false,
+    });
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Renderers ───────────────────────────────────────────────────────────────
+function renderInferredRulesDraft(plan) {
+    const lines = [];
+    lines.push(`// Inferred rules draft — generated by \`shrk onboard\`. Review before adopting.`);
+    lines.push(`// Move keepers into sharkcraft/rules.ts.`);
+    lines.push(`export default [`);
+    for (const r of plan.inferredRules) {
+        lines.push(`  {`);
+        lines.push(`    id: ${literal(r.id)},`);
+        lines.push(`    type: 'rule',`);
+        lines.push(`    title: ${literal(r.title)},`);
+        lines.push(`    priority: ${literal(r.priority)},`);
+        lines.push(`    content: ${literal(r.content)},`);
+        lines.push(`    tags: ${literal(['inferred', r.source])},`);
+        lines.push(`    // reason: ${escapeSingleLineComment(r.reason)}`);
+        lines.push(`  },`);
+    }
+    lines.push(`];`);
+    return lines.join('\n') + '\n';
+}
+function renderInferredPathsDraft(plan) {
+    const lines = [];
+    lines.push(`// Inferred path conventions draft — generated by \`shrk onboard\`. Review before adopting.`);
+    lines.push(`// Move keepers into sharkcraft/paths.ts.`);
+    lines.push(`export default [`);
+    for (const p of plan.inferredPathConventions) {
+        lines.push(`  {`);
+        lines.push(`    id: ${literal(p.id)},`);
+        lines.push(`    type: 'path',`);
+        lines.push(`    title: ${literal(p.title)},`);
+        lines.push(`    content: ${literal(p.content)},`);
+        lines.push(`    patterns: ${literal(p.patterns)},`);
+        lines.push(`    tags: ${literal(['inferred', 'path'])},`);
+        lines.push(`    // reason: ${escapeSingleLineComment(p.reason)}`);
+        lines.push(`  },`);
+    }
+    lines.push(`];`);
+    return lines.join('\n') + '\n';
+}
+function renderInferredTemplatesDraft(plan) {
+    const lines = [];
+    const anyScaffolded = plan.inferredTemplateCandidates.some((t) => t.scaffold);
+    lines.push(`// Inferred template candidates — generated by \`shrk onboard\`.`);
+    if (anyScaffolded) {
+        lines.push(`// Entries with \`runnable: true\` ship a draft body with placeholder variables.`);
+        lines.push(`// Review carefully (especially low-confidence entries) before moving to sharkcraft/templates.ts.`);
+    }
+    else {
+        lines.push(`// NOT runnable until you fill in targetPath + content. Re-run with \`--scaffold-templates\` to draft bodies.`);
+    }
+    lines.push(`export default [`);
+    for (const t of plan.inferredTemplateCandidates) {
+        renderTemplateCandidate(lines, t);
+    }
+    lines.push(`];`);
+    return lines.join('\n') + '\n';
+}
+function renderTemplateCandidate(lines, t) {
+    lines.push(`  {`);
+    lines.push(`    id: ${literal(t.id)},`);
+    lines.push(`    name: ${literal(t.name)},`);
+    lines.push(`    description: ${literal(t.description)},`);
+    lines.push(`    confidence: ${literal(t.confidence)},`);
+    if (t.targetPathHint) {
+        lines.push(`    // targetPath hint: ${escapeSingleLineComment(t.targetPathHint)}`);
+    }
+    if (t.sample) {
+        lines.push(`    // sample: ${escapeSingleLineComment(t.sample)}`);
+    }
+    lines.push(`    // reason: ${escapeSingleLineComment(t.reason)}`);
+    if (t.scaffold) {
+        lines.push(`    runnable: true,`);
+        lines.push(`    scaffold: {`);
+        lines.push(`      id: ${literal(t.scaffold.id)},`);
+        lines.push(`      name: ${literal(t.scaffold.name)},`);
+        lines.push(`      description: ${literal(t.scaffold.description)},`);
+        lines.push(`      targetPath: ${literal(t.scaffold.targetPath)},`);
+        lines.push(`      variables: [`);
+        for (const v of t.scaffold.variables) {
+            lines.push(`        {`);
+            lines.push(`          name: ${literal(v.name)},`);
+            lines.push(`          description: ${literal(v.description)},`);
+            if (typeof v.default === 'string') {
+                lines.push(`          default: ${literal(v.default)},`);
+            }
+            lines.push(`        },`);
+        }
+        lines.push(`      ],`);
+        lines.push(`      content: ${renderMultilineTemplateLiteral(t.scaffold.content)},`);
+        if (t.scaffold.warnings.length > 0) {
+            lines.push(`      // warnings:`);
+            for (const w of t.scaffold.warnings) {
+                lines.push(`      //   - ${escapeSingleLineComment(w)}`);
+            }
+        }
+        lines.push(`    },`);
+    }
+    lines.push(`  },`);
+}
+function renderMultilineTemplateLiteral(content) {
+    // Use a tagged template literal-safe form. Backticks and ${ must be escaped.
+    const escaped = content.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${');
+    return '`' + escaped + '`';
+}
+function renderInferredBoundariesDraft(plan) {
+    const lines = [];
+    lines.push(`// Inferred boundary rules draft — generated by \`shrk onboard\`. Review before adopting.`);
+    lines.push(`// Drop into sharkcraft/boundaries.ts (and register via sharkcraft.config.ts boundaryFiles).`);
+    lines.push(`export default [`);
+    for (const b of plan.inferredBoundaryRules) {
+        lines.push(`  {`);
+        lines.push(`    id: ${literal(b.id)},`);
+        lines.push(`    title: ${literal(b.title)},`);
+        lines.push(`    severity: ${literal(b.severity)},`);
+        lines.push(`    from: ${literal(b.from)},`);
+        if (b.forbiddenImports) {
+            lines.push(`    forbiddenImports: ${literal(b.forbiddenImports)},`);
+        }
+        if (b.allowedImports) {
+            lines.push(`    allowedImports: ${literal(b.allowedImports)},`);
+        }
+        lines.push(`    suggestedFix: ${literal(b.suggestedFix)},`);
+        lines.push(`    // reason: ${escapeSingleLineComment(b.reason)}`);
+        lines.push(`  },`);
+    }
+    lines.push(`];`);
+    return lines.join('\n') + '\n';
+}
+function renderInferredPipelinesDraft(plan) {
+    const lines = [];
+    lines.push(`// Inferred pipelines draft — generated by \`shrk onboard\`. Review before adopting.`);
+    lines.push(`// Move keepers into sharkcraft/pipelines.ts.`);
+    lines.push(`export default [`);
+    for (const p of plan.inferredPipelines) {
+        lines.push(`  {`);
+        lines.push(`    id: ${literal(p.id)},`);
+        lines.push(`    title: ${literal(p.title)},`);
+        lines.push(`    description: ${literal(p.description)},`);
+        lines.push(`    steps: ${renderSteps(p.steps)},`);
+        lines.push(`    // reason: ${escapeSingleLineComment(p.reason)}`);
+        lines.push(`  },`);
+    }
+    lines.push(`];`);
+    return lines.join('\n') + '\n';
+}
+function renderSteps(steps) {
+    const items = steps.map((id) => `      { id: ${literal(id)}, title: ${literal(id)} }`);
+    return `[\n${items.join(',\n')}\n    ]`;
+}
+// ─── Util ────────────────────────────────────────────────────────────────────
+function literal(v) {
+    if (Array.isArray(v)) {
+        return `[${v.map((x) => literal(x)).join(', ')}]`;
+    }
+    if (typeof v === 'string') {
+        // Use JSON.stringify for safe escaping.
+        return JSON.stringify(v);
+    }
+    return JSON.stringify(v);
+}
+function escapeSingleLineComment(s) {
+    return s.replace(/\r?\n/g, ' ').replace(/\*\//g, '*​/');
+}
+function ensureDir(dir) {
+    if (existsSync(dir))
+        return;
+    mkdirSync(dir, { recursive: true });
+}
+function renderImportedAgentRulesDraft(bundle) {
+    const lines = [];
+    lines.push(`// Imported agent rules draft — generated by \`shrk onboard --import-agents\`.`);
+    lines.push(`// Source files: ${bundle.sourceFiles.map((s) => escapeSingleLineComment(s)).join(', ') || '(none)'}`);
+    lines.push(`// Review before adopting; entries flagged "ambiguous" may need a manual rewrite.`);
+    lines.push(`export default [`);
+    for (const e of bundle.entries) {
+        lines.push(`  {`);
+        lines.push(`    id: ${literal(e.id)},`);
+        lines.push(`    type: ${literal(e.type)},`);
+        lines.push(`    title: ${literal(e.title)},`);
+        lines.push(`    content: ${literal(e.content)},`);
+        lines.push(`    tags: ${literal(e.tags)},`);
+        if (e.scope?.length)
+            lines.push(`    scope: ${literal(e.scope)},`);
+        if (e.source?.origin) {
+            lines.push(`    // origin: ${escapeSingleLineComment(e.source.origin)}`);
+        }
+        if (e.flaggedAmbiguous) {
+            lines.push(`    // ambiguous: please review the wording before adopting`);
+        }
+        lines.push(`  },`);
+    }
+    lines.push(`];`);
+    if (bundle.warnings.length > 0) {
+        lines.push('');
+        lines.push('// Warnings:');
+        for (const w of bundle.warnings) {
+            lines.push(`//   - ${escapeSingleLineComment(w)}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/onboarding-report.d.ts

@@ -0,0 +1,8 @@
+import type { IOnboardingPlan } from './onboarding.js';
+/**
+ * Render an onboarding plan as a Markdown report. The output is intentionally
+ * stable and human-readable: it is the artifact a user reads when deciding
+ * whether to adopt SharkCraft drafts.
+ */
+export declare function renderOnboardingReport(plan: IOnboardingPlan): string;
+//# sourceMappingURL=onboarding-report.d.ts.map

package/dist/onboarding-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"onboarding-report.d.ts","sourceRoot":"","sources":["../src/onboarding-report.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CA0PpE"}