crewly 1.8.9 → 1.8.12

package/dist/backend/backend/src/services/wiki/wiki-cleanup.service.js

@@ -0,0 +1,399 @@
+/**
+ * WikiCleanupService — detect + remove low-quality pages from a wiki vault.
+ *
+ * Origin: the 2026-05-27 migration dumped every agent's `memory.json`
+ * roleKnowledge entries as their own wiki page (~3,277 pages across 6
+ * project vaults). Many are stream-of-consciousness daily memory rather
+ * than team-level patterns. Symptom: each project vault has 500+ pages
+ * under `patterns/`, most low-quality (confidence < 0.5, verbatim memory
+ * dump shape). Karpathy's wiki spec says "frequently-read distilled
+ * knowledge" — 500 stream-of-consciousness pages violates that.
+ *
+ * Detection is **rule-based + mechanical** (OSS does this). The actual
+ * keep/delete decision can be deferred to an agent via the bridge —
+ * this service exposes both `scan(rules)` (mechanical candidate list)
+ * and `apply(pages)` (executes the explicit page list provided).
+ *
+ * Design rules (mirror WikiMigrateService):
+ *  - Default DRY-RUN. Caller must pass `{ apply: true }` to delete.
+ *  - Idempotent + reversible. Every deleted page body + frontmatter is
+ *    archived to `<vault>/.wiki-cleanup-archive.json` BEFORE the file
+ *    is removed. Re-running with the same input is a no-op.
+ *  - Migrate manifest is updated so the SAME source entry is not
+ *    re-imported by the next `wiki-migrate --apply` (would defeat the
+ *    cleanup).
+ *  - LEGACY FILES (`memory.json`, `.crewly/knowledge/*`) are NEVER
+ *    touched. The cleanup ONLY removes pages from the wiki vault.
+ *  - Frozen folders (`memory/`, `sop/`, `sop-overrides/`, `okr/`,
+ *    `decisions/manual/`) are never scanned.
+ *
+ * @module services/wiki/wiki-cleanup.service
+ */
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { existsSync } from 'fs';
+import { LoggerService } from '../core/logger.service.js';
+import { atomicWriteJson, safeReadJson, ensureDir } from '../../utils/file-io.utils.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const WIKI_CLEANUP_ARCHIVE_FILENAME = '.wiki-cleanup-archive.json';
+export const WIKI_CLEANUP_ARCHIVE_VERSION = 1;
+/** Folders we never scan — managed by OSS code path, not LLM-editable. */
+const FROZEN_FOLDERS = new Set([
+    'memory',
+    'sop',
+    'sop-overrides',
+    'okr',
+]);
+/** Folder under the vault where llm-curated pages live. */
+const LLM_CURATED_DIR = 'llm-curated';
+/** Hard cap on candidates returned per scan — defensive (prevents OOM on a
+ *  corrupted vault with 100k+ files). */
+const SCAN_HARD_CAP = 5_000;
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+export class WikiCleanupService {
+    static instance = null;
+    logger;
+    constructor() {
+        this.logger = LoggerService.getInstance().createComponentLogger('WikiCleanup');
+    }
+    static getInstance() {
+        if (!this.instance)
+            this.instance = new WikiCleanupService();
+        return this.instance;
+    }
+    /** Test-only reset. */
+    static resetInstance() {
+        this.instance = null;
+    }
+    /**
+     * Walk the vault's `llm-curated/` tree, parse frontmatter, return all
+     * pages matching at least one cleanup rule. Pure read — no writes.
+     */
+    async scan(input) {
+        const validation = this.validateVault(input.vaultPath);
+        if (!validation.ok)
+            return validation;
+        const rules = {
+            minConfidence: input.rules?.minConfidence ?? 0.5,
+            dropAgentMemoryDumps: input.rules?.dropAgentMemoryDumps ?? true,
+            maxPerAgent: input.rules?.maxPerAgent ?? 0,
+        };
+        const llmCuratedRoot = path.join(input.vaultPath, LLM_CURATED_DIR);
+        const allPages = [];
+        let truncated = false;
+        if (existsSync(llmCuratedRoot)) {
+            truncated = await this.walkPages(llmCuratedRoot, input.vaultPath, allPages, SCAN_HARD_CAP);
+        }
+        const flagged = new Map();
+        const summary = { lowConfidence: 0, agentMemoryDump: 0, perAgentCapped: 0 };
+        for (const page of allPages) {
+            const fm = page.frontmatter;
+            const reasons = [];
+            const conf = parseConfidence(fm['confidence']);
+            if (conf !== null && conf < rules.minConfidence) {
+                reasons.push(`confidence ${conf} < ${rules.minConfidence}`);
+                summary.lowConfidence++;
+            }
+            const migratedFrom = typeof fm['migrated_from'] === 'string' ? fm['migrated_from'] : null;
+            if (rules.dropAgentMemoryDumps && migratedFrom?.startsWith('agent/') && migratedFrom.endsWith('/memory.json')) {
+                reasons.push('migrated from agent memory.json');
+                summary.agentMemoryDump++;
+            }
+            if (reasons.length > 0) {
+                flagged.set(page.relPath, {
+                    reasons,
+                    meta: {
+                        confidence: conf,
+                        originalAuthor: typeof fm['original_author'] === 'string' ? fm['original_author'] : null,
+                        originalDate: typeof fm['original_date'] === 'string' ? fm['original_date'] : null,
+                    },
+                });
+            }
+        }
+        // Second pass — per-agent cap. Only considers pages NOT already flagged
+        // by other rules (so a low-confidence page doesn't take a "cap slot").
+        if (rules.maxPerAgent > 0) {
+            const byAuthor = new Map();
+            for (const page of allPages) {
+                if (flagged.has(page.relPath))
+                    continue;
+                const fm = page.frontmatter;
+                const author = typeof fm['original_author'] === 'string' ? fm['original_author'] : null;
+                if (!author)
+                    continue;
+                const conf = parseConfidence(fm['confidence']) ?? 0;
+                const date = typeof fm['original_date'] === 'string' ? fm['original_date'] : '';
+                const arr = byAuthor.get(author) ?? [];
+                arr.push({ relPath: page.relPath, confidence: conf, date });
+                byAuthor.set(author, arr);
+            }
+            for (const [author, arr] of byAuthor) {
+                if (arr.length <= rules.maxPerAgent)
+                    continue;
+                // Keep top-N by confidence desc, then date desc.
+                arr.sort((a, b) => (b.confidence - a.confidence) || b.date.localeCompare(a.date));
+                for (const overflow of arr.slice(rules.maxPerAgent)) {
+                    const existing = flagged.get(overflow.relPath);
+                    if (existing) {
+                        existing.reasons.push(`per-agent cap (${author}: keep ${rules.maxPerAgent})`);
+                    }
+                    else {
+                        flagged.set(overflow.relPath, {
+                            reasons: [`per-agent cap (${author}: keep ${rules.maxPerAgent})`],
+                            meta: { confidence: overflow.confidence, originalAuthor: author, originalDate: overflow.date },
+                        });
+                    }
+                    summary.perAgentCapped++;
+                }
+            }
+        }
+        const candidates = [];
+        for (const page of allPages) {
+            const flag = flagged.get(page.relPath);
+            if (!flag)
+                continue;
+            const fm = page.frontmatter;
+            candidates.push({
+                relPath: page.relPath,
+                reasons: flag.reasons,
+                confidence: flag.meta.confidence,
+                originalAuthor: flag.meta.originalAuthor,
+                migratedFrom: typeof fm['migrated_from'] === 'string' ? fm['migrated_from'] : null,
+                originalId: typeof fm['original_id'] === 'string' ? fm['original_id'] : null,
+                bytes: page.bytes,
+            });
+            if (candidates.length >= SCAN_HARD_CAP) {
+                truncated = true;
+                break;
+            }
+        }
+        this.logger.info('Wiki cleanup scan complete', {
+            vaultPath: input.vaultPath,
+            scannedCount: allPages.length,
+            candidateCount: candidates.length,
+            truncated,
+            summary,
+        });
+        return {
+            ok: true,
+            vaultPath: input.vaultPath,
+            candidates,
+            scannedCount: allPages.length,
+            truncated,
+            summary,
+        };
+    }
+    /**
+     * Delete the listed pages from the vault, archive each one (body +
+     * frontmatter) to `.wiki-cleanup-archive.json`, and invalidate the
+     * corresponding entry in the migrate manifest so the same source can't
+     * resurrect the page on the next `wiki-migrate --apply`.
+     */
+    async apply(input) {
+        const validation = this.validateVault(input.vaultPath);
+        if (!validation.ok)
+            return validation;
+        if (!Array.isArray(input.pages) || input.pages.length === 0) {
+            return { ok: false, reason: 'invalid_input', message: 'pages must be a non-empty array' };
+        }
+        const archivePath = path.join(input.vaultPath, WIKI_CLEANUP_ARCHIVE_FILENAME);
+        const archive = await safeReadJson(archivePath, { version: WIKI_CLEANUP_ARCHIVE_VERSION, entries: [] }, this.logger);
+        if (archive.version !== WIKI_CLEANUP_ARCHIVE_VERSION) {
+            // Migrate-style: don't trust an unknown version, just start fresh.
+            archive.version = WIKI_CLEANUP_ARCHIVE_VERSION;
+            archive.entries = [];
+        }
+        const deleted = [];
+        const skipped = [];
+        for (const relPath of input.pages) {
+            const safe = this.normalizeRelPath(relPath);
+            if (!safe) {
+                skipped.push({ relPath, reason: 'outside_vault' });
+                continue;
+            }
+            // Defence: even if the caller passes a frozen-folder path, refuse.
+            // The top-level segment is the folder name (`memory/secret.md` →
+            // `memory`); pages directly under the vault root are never frozen.
+            const segments = safe.split('/');
+            if (segments.length >= 2 && FROZEN_FOLDERS.has(segments[0])) {
+                skipped.push({ relPath, reason: 'frozen' });
+                continue;
+            }
+            const abs = path.join(input.vaultPath, safe);
+            if (!existsSync(abs)) {
+                skipped.push({ relPath, reason: 'not_found' });
+                continue;
+            }
+            // Read + parse before delete so we can archive shape.
+            const raw = await fs.readFile(abs, 'utf8');
+            const { frontmatter, body } = parseFrontmatter(raw);
+            archive.entries.push({
+                relPath: safe,
+                archivedAt: new Date().toISOString(),
+                reasons: ['apply-list'],
+                body,
+                frontmatter,
+            });
+            await fs.unlink(abs);
+            deleted.push(safe);
+        }
+        // Persist archive — the rollback source of truth.
+        //
+        // **Manifest is deliberately NOT modified** (2026-05-28 fix). Earlier
+        // versions removed the matching entries from `.migration-state.json`
+        // on the theory "now nothing pins the page in place." That was
+        // exactly backwards: the migrate manifest is what makes
+        // `wiki-migrate --apply` IDEMPOTENT. With the entry present + hash
+        // match, migrate sees "already migrated" → skips. With the entry
+        // removed, migrate sees "new content" → re-imports → the
+        // just-deleted page reappears on the next bridge tick. Symptom seen
+        // 2026-05-28 ~05:30: 20 pages deleted, then 20 re-imported by the
+        // next migrate tick, candidate count never dropped. The page on
+        // disk is gone; that is sufficient. Manifest stays intact.
+        await ensureDir(input.vaultPath);
+        await atomicWriteJson(archivePath, archive);
+        this.logger.info('Wiki cleanup apply complete', {
+            vaultPath: input.vaultPath,
+            requested: input.pages.length,
+            deleted: deleted.length,
+            skipped: skipped.length,
+            archivePath,
+        });
+        return {
+            ok: true,
+            vaultPath: input.vaultPath,
+            deleted,
+            skipped,
+            archivePath,
+            manifestEntriesInvalidated: 0,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    validateVault(vaultPath) {
+        if (!vaultPath || !path.isAbsolute(vaultPath)) {
+            return { ok: false, reason: 'invalid_input', message: 'vaultPath must be an absolute path' };
+        }
+        if (!existsSync(vaultPath)) {
+            return { ok: false, reason: 'vault_missing', message: `vault not found: ${vaultPath}` };
+        }
+        return { ok: true };
+    }
+    /**
+     * Best-effort safe-rel normalisation. Returns null if the path would
+     * resolve outside the vault (`..` traversal etc).
+     */
+    normalizeRelPath(rel) {
+        const normalised = path.posix.normalize(rel.replace(/\\/g, '/'));
+        if (normalised.startsWith('..') || path.isAbsolute(normalised))
+            return null;
+        return normalised;
+    }
+    /**
+     * Walk the vault tree, parsing frontmatter on each `.md` file. Skips
+     * frozen folders + non-md files. Returns true if the scan was truncated
+     * by the hard cap.
+     */
+    async walkPages(dir, vaultPath, accumulator, cap) {
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        for (const entry of entries) {
+            if (accumulator.length >= cap)
+                return true;
+            // Skip frozen folders only at the vault-root level (`llm-curated/`
+            // sits next to them, so we never recurse INTO sibling frozen dirs
+            // — but defence-in-depth this check covers anyone who calls
+            // `walkPages` with the vault root directly).
+            if (entry.isDirectory()) {
+                const relParent = path.relative(vaultPath, path.join(dir, entry.name));
+                const topLevel = relParent.split(path.sep)[0];
+                if (FROZEN_FOLDERS.has(topLevel))
+                    continue;
+                const truncated = await this.walkPages(path.join(dir, entry.name), vaultPath, accumulator, cap);
+                if (truncated)
+                    return true;
+                continue;
+            }
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            const abs = path.join(dir, entry.name);
+            try {
+                const stat = await fs.stat(abs);
+                const raw = await fs.readFile(abs, 'utf8');
+                const { frontmatter } = parseFrontmatter(raw);
+                accumulator.push({
+                    relPath: path.relative(vaultPath, abs).split(path.sep).join('/'),
+                    frontmatter,
+                    bytes: stat.size,
+                });
+            }
+            catch (err) {
+                this.logger.debug('walkPages: skipping unreadable file', {
+                    path: abs,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers (module-private, exported for tests)
+// ---------------------------------------------------------------------------
+/**
+ * Parse `confidence` from frontmatter into a number, or null if absent /
+ * unparseable. Accepts both numeric (`0.3`) and string (`"0.3"`) shapes
+ * because YAML quoting is inconsistent across older migrated pages.
+ */
+export function parseConfidence(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return raw;
+    if (typeof raw === 'string') {
+        const parsed = parseFloat(raw);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return null;
+}
+/**
+ * Minimal YAML frontmatter parser. Handles the shapes our migrate service
+ * emits — `key: value` lines, with optional quotes around values. NOT a
+ * general YAML parser. Returns `{}` when no frontmatter is present.
+ */
+export function parseFrontmatter(raw) {
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+    if (!match)
+        return { frontmatter: {}, body: raw };
+    const fm = {};
+    for (const line of match[1].split('\n')) {
+        const lineMatch = line.match(/^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/);
+        if (!lineMatch)
+            continue;
+        let value = lineMatch[2].trim();
+        // Strip wrapping quotes.
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Coerce a few common scalar shapes.
+        if (value === 'true')
+            fm[lineMatch[1]] = true;
+        else if (value === 'false')
+            fm[lineMatch[1]] = false;
+        else if (/^-?\d+(\.\d+)?$/.test(value))
+            fm[lineMatch[1]] = parseFloat(value);
+        else
+            fm[lineMatch[1]] = value;
+    }
+    return { frontmatter: fm, body: match[2] };
+}
+//# sourceMappingURL=wiki-cleanup.service.js.map

package/dist/backend/backend/src/services/wiki/wiki-cleanup.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-cleanup.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-cleanup.service.ts"],"names":[],"mappings":"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"}

package/dist/backend/backend/src/services/wiki/wiki-lint.service.d.ts

@@ -0,0 +1,182 @@
+/**
+ * WikiLintService — deterministic validation pass over a vault.
+ *
+ * Per v2.1 spec §3, the third Phase 1 skill (alongside `wiki-ingest` and
+ * `wiki-query`). Unlike `wiki-bookkeep` (vault HEALTH metrics — counts,
+ * recent activity, duplicate clusters), lint focuses on CORRECTNESS:
+ *
+ *   - **frozenPathRespected** — no markdown content in folders flagged
+ *     `frozen: true` in SCHEMA.md (other than the SCHEMA.md itself /
+ *     legitimate frozen content). Lint refuses to alter frozen paths.
+ *   - **missingEntities** — `[[wikilinks]]` that don't resolve to any
+ *     page in the vault. Either the target was renamed, deleted, or the
+ *     wikilink was made up. The lint flags them; the agent decides.
+ *   - **orphanPages** — pages with zero incoming wikilinks, excluding
+ *     seed pages (log.md, index.md, README*). These are candidates for
+ *     either deletion or new linking.
+ *   - **staleClaims** — files un-touched for `staleDays` (default 90).
+ *   - **restructureProposals** — heuristics for llm-curated/ only: large
+ *     un-indexed folders, near-duplicate filenames.
+ *
+ * The service never writes. The agent's LLM reads the report and decides
+ * whether to ingest a consolidation, archive stale pages, etc.
+ *
+ * @module services/wiki/wiki-lint.service
+ */
+/** Default age threshold (days) for marking a page stale. */
+export declare const WIKI_LINT_DEFAULT_STALE_DAYS = 90;
+/** Folder size threshold above which lint proposes an `index.md` rollup. */
+export declare const WIKI_LINT_ROLLUP_THRESHOLD = 20;
+/** Max number of pages walked per lint pass. */
+export declare const WIKI_LINT_MAX_PAGES = 1000;
+/** Cap per category to keep the payload bounded. */
+export declare const WIKI_LINT_MAX_ROWS_PER_SECTION = 50;
+/** Pages with these basenames never count as "orphans". */
+export declare const WIKI_LINT_SEED_BASENAMES: Set<string>;
+/**
+ * A `[[wikilink]]` target is "concept-shaped" (vs a dangling typo) when
+ * it appears at least this many times across the vault. Below this, the
+ * unresolved target is just noise; at or above this, the concept is
+ * load-bearing and deserves its own page.
+ */
+export declare const WIKI_LINT_MISSING_CONCEPT_THRESHOLD = 3;
+export interface WikiLintInput {
+    vaultPath: string;
+    staleDays?: number;
+}
+export interface WikiLintFrozenViolation {
+    /** Relative path of the offending file. */
+    path: string;
+    /** The frozen folder it lives in. */
+    frozenFolder: string;
+}
+export interface WikiLintMissingEntity {
+    /** Page that contains the dangling wikilink. */
+    sourcePath: string;
+    /** The unresolved wikilink target. */
+    target: string;
+    /** Line number in the source page (1-based). */
+    lineNumber: number;
+}
+export interface WikiLintRestructureProposal {
+    /** Plain-English description of the proposal, e.g. "folder X has 31 pages without an index.md — propose llm-curated/X/index.md". */
+    description: string;
+    /** Optional related path (folder or page). */
+    path?: string;
+}
+/**
+ * A wikilink target that appears repeatedly across the vault but has no
+ * dedicated page. Karpathy's lint contract names this explicitly:
+ * *"important concepts mentioned but lacking their own page."* Different
+ * from `missingEntities` (which is one-off dangling refs / typos):
+ * `missingConcepts` is **frequency-weighted** signal that the team keeps
+ * mentioning a thing → write a page for it.
+ */
+export interface WikiLintMissingConcept {
+    /** The wikilink target referenced (e.g. `verify-output`). */
+    target: string;
+    /** How many distinct wikilink occurrences resolved to nothing. */
+    referenceCount: number;
+    /** Sample sources (capped) that reference this concept. */
+    sources: string[];
+}
+export interface WikiLintReport {
+    vault: {
+        scope: string;
+        id: string;
+        path: string;
+    };
+    generatedAt: string;
+    staleDays: number;
+    frozenPathRespected: boolean;
+    frozenViolations: WikiLintFrozenViolation[];
+    missingEntities: WikiLintMissingEntity[];
+    /** New 2026-05-26: frequency-weighted "missing concept" signals. */
+    missingConcepts: WikiLintMissingConcept[];
+    orphanPages: string[];
+    staleClaims: string[];
+    restructureProposals: WikiLintRestructureProposal[];
+    truncated: boolean;
+}
+export type WikiLintOutcome = {
+    ok: true;
+    report: WikiLintReport;
+} | {
+    ok: false;
+    reason: 'vault_missing' | 'schema_missing' | 'invalid_input';
+    message: string;
+};
+/**
+ * Singleton lint service. Stateless — pattern mirrors the other wiki
+ * services so the controller wiring is uniform.
+ */
+export declare class WikiLintService {
+    private static instance;
+    private readonly logger;
+    private readonly schemaLoader;
+    private constructor();
+    static getInstance(): WikiLintService;
+    static resetInstance(): void;
+    /**
+     * Generate a lint report for the given vault.
+     */
+    generate(input: WikiLintInput): Promise<WikiLintOutcome>;
+    /**
+     * Recursive walk collecting `.md` files. Honors `WIKI_LINT_MAX_PAGES`.
+     */
+    private collectFiles;
+    /**
+     * Find `.md` files that live inside any frozen folder. SCHEMA.md and
+     * legitimate sibling files inside frozen dirs (e.g. `sop/<role>.md`)
+     * are excluded — frozen folders ARE allowed to contain content; what's
+     * NOT allowed is `wiki-ingest` writing INTO them. That's a runtime
+     * check elsewhere. Lint surfaces files only when they look like they
+     * were created by ingest patterns (timestamp-prefixed slugs).
+     */
+    private detectFrozenViolations;
+    /**
+     * One read pass per file: pulls `[[wikilink]]` references, builds the
+     * inverse "incoming" map for orphan detection, and emits missing-entity
+     * rows for any link that resolves to nothing.
+     */
+    private scanWikilinks;
+    /**
+     * A page is an orphan when no other page wikilinks to it AND it is
+     * not a seed page (log.md / index.md / README.md / SCHEMA.md).
+     */
+    private detectOrphans;
+    /**
+     * Find load-bearing concepts referenced repeatedly across the vault
+     * but lacking a dedicated page. Karpathy's lint contract names this:
+     * *"important concepts mentioned but lacking their own page."*
+     *
+     * Frequency-filtered (`WIKI_LINT_MISSING_CONCEPT_THRESHOLD`, default 3)
+     * so we ignore typos and inline-code-style `[[X]]` brackets that aren't
+     * meant as wikilinks. Distinct from `missingEntities`, which flags every
+     * dangling ref individually.
+     *
+     * Results sort by referenceCount desc — highest-leverage concepts first.
+     */
+    private detectMissingConcepts;
+    /**
+     * Files whose content is older than `staleDays`.
+     *
+     * Migrated pages may have an `original_date` frontmatter field
+     * (e.g. the legacy decision was made 2026-02-01 but we wrote the
+     * markdown TODAY). Stale detection should respect the original date
+     * when present — otherwise every freshly-migrated old page would look
+     * "new" by mtime alone. Falls back to mtime when frontmatter is absent.
+     */
+    private detectStale;
+    /**
+     * Heuristic restructure proposals — only for `llm-curated/` since
+     * frozen folders cannot be restructured.
+     *
+     * (1) A subfolder with > WIKI_LINT_ROLLUP_THRESHOLD pages and NO `index.md`
+     *     gets an "add an index.md rollup" proposal.
+     * (2) Near-duplicate filename prefixes (e.g. `pricing-v1.md`, `pricing-v2.md`)
+     *     get a "consider merging" proposal.
+     */
+    private proposeRestructures;
+}
+//# sourceMappingURL=wiki-lint.service.d.ts.map

package/dist/backend/backend/src/services/wiki/wiki-lint.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-lint.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-lint.service.ts"],"names":[],"mappings":"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"}