@tenphi/akno-core 0.1.0

package/dist/config/write-rules.js

@@ -0,0 +1,225 @@
+const HEADER = `{
+  // Rules for this knowledge base. Akno reads this file from the root of the notes,
+  // so the taxonomy travels with the folder rather than living in a machine's config.
+  //
+  // Roles say what a page contributes; management says what automation may do:
+  //   knowledge  canonical claims, eligible for fact derivation
+  //   source     searchable evidence, never mined for facts
+  //   inference  derived interpretation, ranked below authored knowledge
+  //   ignored    not indexed at all
+  //
+  // \`description\` says what belongs in the folder. It is the field a caller reads before
+  // filing a page, so it is worth writing for a reader who has never seen this base.
+  "folders": {
+  }
+}
+`;
+/**
+ * Returns the file's new text with `entry` added to its `folders` block.
+ *
+ * `source` is null when the file does not exist yet, in which case a commented skeleton is
+ * created around the entry — the same explanation a person would otherwise have to go and
+ * find in the docs.
+ *
+ * Throws when the file exists but has no `folders` block to add to, rather than inventing
+ * one at a guess: a file shaped differently than expected is a file somebody meant something
+ * by.
+ */
+export function addFolderRule(source, entry) {
+    const text = source ?? HEADER;
+    const block = findObjectValue(text, 'folders');
+    if (!block) {
+        throw new Error('akno.jsonc has no `folders` block to add a rule to');
+    }
+    const indent = `${indentOfLineAt(text, block.close)}  `;
+    const lines = renderEntry(entry, indent);
+    // The end of the previous rule, or the opening brace when there is none. `{` means the
+    // block is empty and `,` means the previous entry already ends in one; anything else is the
+    // end of a rule and needs a comma before another can follow it.
+    const lastMeaningful = lastMeaningfulOffset(text, block.open + 1, block.close);
+    const needsComma = text[lastMeaningful] !== '{' && text[lastMeaningful] !== ',';
+    const comma = needsComma ? ',' : '';
+    const head = text.slice(0, lastMeaningful + 1);
+    // A closing brace sharing its line with content (`"folders": {}`) has no line of its own to
+    // insert before, so the entry is opened onto one.
+    if (!isFirstOnItsLine(text, block.close)) {
+        return `${head}${comma}\n${lines}\n${indent.slice(2)}${text.slice(block.close)}`;
+    }
+    // Everything between the last rule and the closing brace's line is carried across verbatim:
+    // it is usually a comment about the rule above it, and moving it would silently reattach it
+    // to ours.
+    const between = text.slice(lastMeaningful + 1, startOfLineAt(text, block.close));
+    const rest = text.slice(startOfLineAt(text, block.close));
+    return `${head}${comma}${between}${lines}\n${rest}`;
+}
+/** True when `folders` already has a rule under exactly this glob. */
+export function hasFolderRule(folders, glob) {
+    return folders !== undefined && Object.prototype.hasOwnProperty.call(folders, glob);
+}
+// ─── Rendering ──────────────────────────────────────────────────────────────
+function renderEntry(entry, indent) {
+    const fields = Object.entries(entry.rule)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => `${indent}  ${JSON.stringify(key)}: ${JSON.stringify(value)}`);
+    // A one-line rule reads fine, but `description` is a sentence — every real entry is
+    // multi-line, so they all are, and the file stays uniform.
+    return [`${indent}${JSON.stringify(entry.glob)}: {`, fields.join(',\n'), `${indent}}`].join('\n');
+}
+/**
+ * Finds a key at the root object's own depth and the object it maps to.
+ *
+ * Depth-aware on purpose: a nested `"folders"` under some other key is not the one being
+ * asked for, and a match inside a string or a comment is not a key at all.
+ */
+function findObjectValue(text, key) {
+    const wanted = JSON.stringify(key);
+    let depth = 0;
+    for (let i = 0; i < text.length; i++) {
+        const skipped = skipNonCode(text, i);
+        if (skipped !== i) {
+            i = skipped - 1;
+            continue;
+        }
+        const ch = text[i];
+        if (ch === '{' || ch === '[') {
+            depth++;
+            continue;
+        }
+        if (ch === '}' || ch === ']') {
+            depth--;
+            continue;
+        }
+        if (ch !== '"')
+            continue;
+        // Every string is stepped over, at every depth. A `slug_pattern` of `"^{a}$"` read
+        // character by character would take the depth counter with it.
+        const end = endOfString(text, i);
+        if (depth !== 1 || text.slice(i, end) !== wanted) {
+            i = end - 1;
+            continue;
+        }
+        const colon = nextCode(text, end);
+        if (colon === null || text[colon] !== ':') {
+            i = end - 1;
+            continue;
+        }
+        const open = nextCode(text, colon + 1);
+        if (open === null || text[open] !== '{')
+            return null;
+        const close = matchingBrace(text, open);
+        return close === null ? null : { open, close };
+    }
+    return null;
+}
+/** The offset after any comment or whitespace starting at `i`; `i` itself when there is none. */
+function skipNonCode(text, i) {
+    if (text[i] === '/' && text[i + 1] === '/') {
+        let j = i + 2;
+        while (j < text.length && text[j] !== '\n')
+            j++;
+        return j;
+    }
+    if (text[i] === '/' && text[i + 1] === '*') {
+        let j = i + 2;
+        while (j < text.length - 1 && !(text[j] === '*' && text[j + 1] === '/'))
+            j++;
+        return Math.min(j + 2, text.length);
+    }
+    return i;
+}
+function endOfString(text, quote) {
+    let i = quote + 1;
+    while (i < text.length) {
+        if (text[i] === '\\') {
+            i += 2;
+            continue;
+        }
+        if (text[i] === '"')
+            return i + 1;
+        i++;
+    }
+    return text.length;
+}
+/** The next offset holding something that is not whitespace and not a comment. */
+function nextCode(text, from) {
+    let i = from;
+    while (i < text.length) {
+        if (/\s/.test(text[i])) {
+            i++;
+            continue;
+        }
+        const skipped = skipNonCode(text, i);
+        if (skipped !== i) {
+            i = skipped;
+            continue;
+        }
+        return i;
+    }
+    return null;
+}
+function matchingBrace(text, open) {
+    let depth = 0;
+    for (let i = open; i < text.length; i++) {
+        const skipped = skipNonCode(text, i);
+        if (skipped !== i) {
+            i = skipped - 1;
+            continue;
+        }
+        const ch = text[i];
+        if (ch === '"') {
+            i = endOfString(text, i) - 1;
+            continue;
+        }
+        if (ch === '{')
+            depth++;
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0)
+                return i;
+        }
+    }
+    return null;
+}
+/**
+ * The last offset inside the block that is neither whitespace nor comment — the end of the
+ * previous rule, or the opening brace when there is no previous rule.
+ *
+ * Scanned forwards rather than backwards: a `//` comment can only be recognised from its
+ * start, so reading the file in reverse would mistake the contents of a trailing comment for
+ * code — which is exactly the case that needs handling, a note written under the last rule.
+ */
+function lastMeaningfulOffset(text, from, until) {
+    let last = null;
+    let i = from;
+    while (i < until) {
+        if (/\s/.test(text[i])) {
+            i++;
+            continue;
+        }
+        const skipped = skipNonCode(text, i);
+        if (skipped !== i) {
+            i = skipped;
+            continue;
+        }
+        if (text[i] === '"') {
+            const end = endOfString(text, i);
+            last = end - 1;
+            i = end;
+            continue;
+        }
+        last = i;
+        i++;
+    }
+    return last ?? from - 1;
+}
+function startOfLineAt(text, offset) {
+    return text.lastIndexOf('\n', offset - 1) + 1;
+}
+function isFirstOnItsLine(text, offset) {
+    return text.slice(startOfLineAt(text, offset), offset).trim().length === 0;
+}
+function indentOfLineAt(text, offset) {
+    const line = text.slice(startOfLineAt(text, offset), offset);
+    return /^[ \t]*/.exec(line)[0];
+}
+//# sourceMappingURL=write-rules.js.map

package/dist/config/write-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-rules.js","sourceRoot":"","sources":["../../src/config/write-rules.ts"],"names":[],"mappings":"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"}

package/dist/config/write-setup.d.ts

@@ -0,0 +1,42 @@
+import type { ConfigDoc } from './schema.ts';
+export interface SetupConfigTargetOptions {
+    stateDir?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Test seam; undefined discovers the checkout, while null models an installed package. */
+    repoRoot?: string | null;
+}
+export interface SetupConfigChange {
+    path: string;
+    action: 'add' | 'replace';
+}
+export interface SetupConfigWriteOptions {
+    /** Object paths owned as a unit by a preset instead of recursively merged. */
+    replacePaths?: string[];
+}
+/**
+ * The write plan deliberately keeps document bytes internal to the config layer. CLI output receives
+ * only changed paths, so an existing provider header can never become part of a setup diff.
+ */
+export interface SetupConfigWritePlan {
+    targetPath: string;
+    existed: boolean;
+    changed: boolean;
+    changes: SetupConfigChange[];
+    document: ConfigDoc;
+    beforeFingerprint: string | null;
+    after: string;
+}
+export interface SetupConfigWriteResult {
+    targetPath: string;
+    created: boolean;
+    changed: boolean;
+}
+/** Resolve the same writable layer that normal commands will read. */
+export declare function setupConfigTarget(options?: SetupConfigTargetOptions): string;
+export declare function planSetupConfigWrite(targetPath: string, overlay: ConfigDoc, options?: SetupConfigWriteOptions): SetupConfigWritePlan;
+/**
+ * Fsync a sibling temporary file and rename it over the target. The fingerprint check turns an
+ * editor save between preview and apply into a visible conflict instead of a lost update.
+ */
+export declare function applySetupConfigWrite(plan: SetupConfigWritePlan): Promise<SetupConfigWriteResult>;
+//# sourceMappingURL=write-setup.d.ts.map

package/dist/config/write-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-setup.d.ts","sourceRoot":"","sources":["../../src/config/write-setup.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAK7C,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,KAAK,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,QAAQ,EAAE,SAAS,CAAC;IACpB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,sEAAsE;AACtE,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,MAAM,CAYhF;AAED,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,SAAS,EAClB,OAAO,GAAE,uBAA4B,GACpC,oBAAoB,CA0BtB;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA8BvG"}

package/dist/config/write-setup.js

@@ -0,0 +1,358 @@
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { parseJsonc, readJsoncFile } from "./jsonc.js";
+import { findRepoRoot, resolveUserPath } from "./paths.js";
+import { sha256 } from "../store/ids.js";
+/** Resolve the same writable layer that normal commands will read. */
+export function setupConfigTarget(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.AKNO_CONFIG)
+        return resolveUserPath(env.AKNO_CONFIG);
+    const repoRoot = options.repoRoot === undefined ? findRepoRoot() : options.repoRoot;
+    if (repoRoot)
+        return path.join(repoRoot, 'config', 'local.jsonc');
+    const stateDir = resolveUserPath(options.stateDir ?? env.AKNO_STATE_DIR ?? '~/.akno');
+    const json = path.join(stateDir, 'config.json');
+    const jsonc = path.join(stateDir, 'config.jsonc');
+    if (fs.existsSync(json))
+        return json;
+    return fs.existsSync(jsonc) ? jsonc : json;
+}
+export function planSetupConfigWrite(targetPath, overlay, options = {}) {
+    const before = readFileIfPresent(targetPath);
+    const raw = before === null ? {} : readJsoncFile(targetPath);
+    if (!isPlainObject(raw)) {
+        throw new Error(`${targetPath} must contain one JSON object`);
+    }
+    const overlayRecord = overlay;
+    const replacePaths = new Set(options.replacePaths ?? []);
+    const document = mergeObjects(raw, overlayRecord, replacePaths);
+    const changes = collectChanges(raw, overlayRecord, replacePaths);
+    const after = renderMergedConfig(before, overlayRecord, replacePaths, document);
+    const plan = {
+        targetPath,
+        existed: before !== null,
+        changed: changes.length > 0,
+        changes,
+    };
+    // These are intentionally non-enumerable. A plan is useful in CLI and plugin code, and an
+    // accidental JSON.stringify must expose only the path-only diff, never an existing header.
+    Object.defineProperties(plan, {
+        document: { value: document, enumerable: false },
+        beforeFingerprint: { value: before === null ? null : sha256(before), enumerable: false },
+        after: { value: after, enumerable: false },
+    });
+    return plan;
+}
+/**
+ * Fsync a sibling temporary file and rename it over the target. The fingerprint check turns an
+ * editor save between preview and apply into a visible conflict instead of a lost update.
+ */
+export async function applySetupConfigWrite(plan) {
+    const current = readFileIfPresent(plan.targetPath);
+    const currentFingerprint = current === null ? null : sha256(current);
+    if (currentFingerprint !== plan.beforeFingerprint) {
+        throw new Error(`configuration changed while setup was preparing its write: ${plan.targetPath}`);
+    }
+    if (!plan.changed) {
+        return { targetPath: plan.targetPath, created: false, changed: false };
+    }
+    await fsp.mkdir(path.dirname(plan.targetPath), { recursive: true });
+    const existingMode = await fileMode(plan.targetPath);
+    const temporary = `${plan.targetPath}.${process.pid}.${Math.random().toString(16).slice(2)}.akno.tmp`;
+    const handle = await fsp.open(temporary, 'wx', existingMode ?? 0o600);
+    try {
+        await handle.writeFile(plan.after, 'utf8');
+        await handle.sync();
+    }
+    catch (error) {
+        await handle.close();
+        await fsp.rm(temporary, { force: true });
+        throw error;
+    }
+    await handle.close();
+    try {
+        await fsp.rename(temporary, plan.targetPath);
+    }
+    catch (error) {
+        await fsp.rm(temporary, { force: true });
+        throw error;
+    }
+    return { targetPath: plan.targetPath, created: !plan.existed, changed: true };
+}
+function readFileIfPresent(targetPath) {
+    try {
+        return fs.readFileSync(targetPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+async function fileMode(targetPath) {
+    try {
+        return (await fsp.stat(targetPath)).mode & 0o777;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function mergeObjects(base, overlay, replacePaths, prefix = '') {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value === undefined)
+            continue;
+        const target = prefix ? `${prefix}.${key}` : key;
+        const existing = result[key];
+        result[key] =
+            !replacePaths.has(target) && isPlainObject(existing) && isPlainObject(value)
+                ? mergeObjects(existing, value, replacePaths, target)
+                : value;
+    }
+    return result;
+}
+function collectChanges(base, overlay, replacePaths, prefix = '') {
+    const changes = [];
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value === undefined)
+            continue;
+        const target = prefix ? `${prefix}.${key}` : key;
+        const exists = Object.hasOwn(base, key);
+        const existing = base[key];
+        if (!replacePaths.has(target) && isPlainObject(existing) && isPlainObject(value)) {
+            changes.push(...collectChanges(existing, value, replacePaths, target));
+        }
+        else if (!exists || !sameDocument(existing, value)) {
+            changes.push({ path: target, action: exists ? 'replace' : 'add' });
+        }
+    }
+    return changes;
+}
+function sameValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+/** Preserve comments and unrelated formatting while changing only overlay-owned values. */
+function renderMergedConfig(before, overlay, replacePaths, document) {
+    if (before === null)
+        return `${JSON.stringify(document, null, 2)}\n`;
+    const patched = patchJsoncObject(before, overlay, replacePaths);
+    const parsed = parseJsonc(patched, '<planned setup config>');
+    if (!sameDocument(parsed, document)) {
+        throw new Error('planned setup config did not preserve the merged document');
+    }
+    return patched.endsWith('\n') ? patched : `${patched}\n`;
+}
+function patchJsoncObject(input, overlay, replacePaths, prefix = '') {
+    const object = scanJsoncObject(input);
+    const byKey = new Map(object.properties.map((property) => [property.key, property]));
+    const edits = [];
+    const missing = [];
+    for (const [key, value] of Object.entries(overlay)) {
+        if (value === undefined)
+            continue;
+        const target = prefix ? `${prefix}.${key}` : key;
+        const property = byKey.get(key);
+        if (!property) {
+            missing.push([key, value]);
+            continue;
+        }
+        const current = parseJsonc(input.slice(property.valueStart, property.valueEnd));
+        if (sameDocument(current, value))
+            continue;
+        const replacement = !replacePaths.has(target) && isPlainObject(current) && isPlainObject(value)
+            ? patchJsoncObject(input.slice(property.valueStart, property.valueEnd), value, replacePaths, target)
+            : formatJsonValue(value, propertyIndent(input, property.keyStart));
+        edits.push({ start: property.valueStart, end: property.valueEnd, text: replacement });
+    }
+    if (missing.length > 0) {
+        const objectIndent = propertyIndent(input, object.openBrace);
+        const keyIndent = object.properties[0]
+            ? propertyIndent(input, object.properties[0].keyStart)
+            : `${objectIndent}  `;
+        const additions = missing
+            .map(([key, value]) => `${keyIndent}${JSON.stringify(key)}: ${formatJsonValue(value, keyIndent)}`)
+            .join(',\n');
+        const beforeClose = input.slice(0, object.closeBrace);
+        const leadingNewline = beforeClose.endsWith('\n') ? '' : '\n';
+        edits.push({
+            start: object.closeBrace,
+            end: object.closeBrace,
+            text: `${leadingNewline}${additions}\n${objectIndent}`,
+        });
+        const last = object.properties.at(-1);
+        if (last && !hasCommaAfter(input, last.valueEnd, object.closeBrace)) {
+            edits.push({ start: last.valueEnd, end: last.valueEnd, text: ',' });
+        }
+    }
+    return applyTextEdits(input, edits);
+}
+function scanJsoncObject(input) {
+    let cursor = skipTrivia(input, 0);
+    if (input[cursor] !== '{')
+        throw new Error('setup can merge only JSON objects');
+    const openBrace = cursor++;
+    const properties = [];
+    while (cursor < input.length) {
+        cursor = skipTrivia(input, cursor);
+        if (input[cursor] === '}')
+            return { openBrace, closeBrace: cursor, properties };
+        if (input[cursor] !== '"')
+            throw new Error('setup config contains an invalid object key');
+        const keyStart = cursor;
+        const keyEnd = scanString(input, cursor);
+        const key = JSON.parse(input.slice(keyStart, keyEnd));
+        cursor = skipTrivia(input, keyEnd);
+        if (input[cursor] !== ':')
+            throw new Error(`setup config key ${key} has no value`);
+        cursor = skipTrivia(input, cursor + 1);
+        const valueStart = cursor;
+        const valueEnd = scanValue(input, cursor);
+        properties.push({ key, keyStart, valueStart, valueEnd });
+        cursor = skipTrivia(input, valueEnd);
+        if (input[cursor] === ',') {
+            cursor++;
+            continue;
+        }
+        if (input[cursor] === '}')
+            return { openBrace, closeBrace: cursor, properties };
+        throw new Error(`setup config property ${key} is not followed by a comma or closing brace`);
+    }
+    throw new Error('setup config object is not closed');
+}
+function scanValue(input, start) {
+    const first = input[start];
+    if (first === '"')
+        return scanString(input, start);
+    if (first === '{' || first === '[')
+        return scanContainer(input, start);
+    let cursor = start;
+    while (cursor < input.length) {
+        const char = input[cursor];
+        if (char === ',' || char === '}' || char === ']' || /\s/.test(char ?? ''))
+            break;
+        if (char === '/' && (input[cursor + 1] === '/' || input[cursor + 1] === '*'))
+            break;
+        cursor++;
+    }
+    if (cursor === start)
+        throw new Error('setup config contains an empty value');
+    return cursor;
+}
+function scanContainer(input, start) {
+    const stack = [input[start]];
+    let cursor = start + 1;
+    while (cursor < input.length && stack.length > 0) {
+        const char = input[cursor];
+        const next = input[cursor + 1];
+        if (char === '"') {
+            cursor = scanString(input, cursor);
+            continue;
+        }
+        if (char === '/' && next === '/') {
+            cursor = skipLineComment(input, cursor + 2);
+            continue;
+        }
+        if (char === '/' && next === '*') {
+            cursor = skipBlockComment(input, cursor + 2);
+            continue;
+        }
+        if (char === '{' || char === '[')
+            stack.push(char);
+        else if (char === '}' || char === ']') {
+            const expected = char === '}' ? '{' : '[';
+            if (stack.pop() !== expected)
+                throw new Error('setup config contains mismatched brackets');
+        }
+        cursor++;
+    }
+    if (stack.length > 0)
+        throw new Error('setup config contains an unclosed value');
+    return cursor;
+}
+function scanString(input, start) {
+    let cursor = start + 1;
+    while (cursor < input.length) {
+        if (input[cursor] === '\\') {
+            cursor += 2;
+            continue;
+        }
+        if (input[cursor] === '"')
+            return cursor + 1;
+        cursor++;
+    }
+    throw new Error('setup config contains an unclosed string');
+}
+function skipTrivia(input, start) {
+    let cursor = start;
+    while (cursor < input.length) {
+        if (/\s/.test(input[cursor] ?? '')) {
+            cursor++;
+            continue;
+        }
+        if (input[cursor] === '/' && input[cursor + 1] === '/') {
+            cursor = skipLineComment(input, cursor + 2);
+            continue;
+        }
+        if (input[cursor] === '/' && input[cursor + 1] === '*') {
+            cursor = skipBlockComment(input, cursor + 2);
+            continue;
+        }
+        break;
+    }
+    return cursor;
+}
+function skipLineComment(input, start) {
+    let cursor = start;
+    while (cursor < input.length && input[cursor] !== '\n')
+        cursor++;
+    return cursor;
+}
+function skipBlockComment(input, start) {
+    const end = input.indexOf('*/', start);
+    if (end === -1)
+        throw new Error('setup config contains an unclosed block comment');
+    return end + 2;
+}
+function propertyIndent(input, position) {
+    const lineStart = input.lastIndexOf('\n', position - 1) + 1;
+    const prefix = input.slice(lineStart, position);
+    return /^\s*$/.test(prefix) ? prefix : '  ';
+}
+function formatJsonValue(value, indent) {
+    return JSON.stringify(value, null, 2).replace(/\n/g, `\n${indent}`);
+}
+function hasCommaAfter(input, valueEnd, closeBrace) {
+    const cursor = skipTrivia(input, valueEnd);
+    return cursor < closeBrace && input[cursor] === ',';
+}
+function applyTextEdits(input, edits) {
+    let result = input;
+    for (const edit of edits.sort((left, right) => right.start - left.start)) {
+        result = `${result.slice(0, edit.start)}${edit.text}${result.slice(edit.end)}`;
+    }
+    return result;
+}
+function sameDocument(left, right) {
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return (Array.isArray(left) &&
+            Array.isArray(right) &&
+            left.length === right.length &&
+            left.every((value, index) => sameDocument(value, right[index])));
+    }
+    if (isPlainObject(left) || isPlainObject(right)) {
+        if (!isPlainObject(left) || !isPlainObject(right))
+            return false;
+        const leftKeys = Object.keys(left).sort();
+        const rightKeys = Object.keys(right).sort();
+        return sameValue(leftKeys, rightKeys) && leftKeys.every((key) => sameDocument(left[key], right[key]));
+    }
+    return Object.is(left, right);
+}
+//# sourceMappingURL=write-setup.js.map