appease 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emilio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# appease
+
+
+Make peace in this app.
+
+
+![designing](https://img.shields.io/badge/stability-designing-red.svg)
+[![npm-version](https://img.shields.io/npm/v/appease.svg)](https://npmjs.org/package/appease)
+[![downloads](https://img.shields.io/npm/dm/appease.svg)](https://npmjs.org/package/appease)
+[![build](https://github.com/emilioplatzer/appease/actions/workflows/build-and-test.yml/badge.svg)](https://github.com/emilioplatzer/appease/actions/workflows/build-and-test.yml)
+[![security](https://socket.dev/api/badge/npm/package/appease)](https://socket.dev/npm/package/appease)
+[![qa-control](https://github.com/emilioplatzer/appease/actions/workflows/qa-control.yml/badge.svg)](https://github.com/emilioplatzer/appease/actions/workflows/qa-control.yml)
+
+
+language: ![English](https://raw.githubusercontent.com/codenautas/multilang/master/img/lang-en.png)
+also available in:
+[![Spanish](https://raw.githubusercontent.com/codenautas/multilang/master/img/lang-es.png)](LEEME.md)
+
+A tool to bring order, **once**, to the low-level format of a repository's files (line
+endings, BOM, trailing spaces, final newline, indentation), and to leave the convention
+configured so that keeping it afterwards is free and diffs stay clean and humanly reviewable.
+
+The underlying idea: honoring "the exact format" on every commit is an effort (especially on
+Windows, where line endings get mixed on their own). If instead you normalize once and pin
+the convention with `.gitattributes` + `.editorconfig` + `.vscode/settings.json`, the cost
+disappears.
+
+The name is a play on words between **normalize** and **appease** (to bring to peace).
+
+
+---
+
+## What it normalizes, and where each decision lives
+
+Each format "axis" is controlled from **a single configuration file**, depending on which
+tool is capable of handling it. To answer "what happens to this file on a given axis?" you
+never have to look at two files.
+
+| Axis | Who handles it | Config file |
+|---|---|---|
+| Line ending (EOL) | Git | `.gitattributes` |
+| BOM / charset | editor + appease | `.editorconfig` |
+| Trailing spaces | editor + appease | `.editorconfig` |
+| Final newline | editor + appease | `.editorconfig` |
+| Indentation (convention) | editor | `.editorconfig` |
+| Show whitespace on selection | VSC | `.vscode/settings.json` |
+
+### Line ending (EOL) — handled by Git
+
+It lives in `.gitattributes`, which is **per-repo and overrides Git's global configuration**,
+so there's no need to touch anything in global Git (nor break other repos that rely on its
+behavior).
+
+
+```gitattributes
+# Default: on commit, Git normalizes to LF in the repo (EOL disappears from diffs);
+# on checkout, it delivers the OS-native EOL (CRLF on Windows, LF on Linux).
+* text=auto
+
+# One-off exceptions, one by one:
+path/to/file.crlf   text eol=crlf   # always CRLF, everywhere
+path/to/file.lf     text eol=lf     # always LF, everywhere
+path/to/file.raw    -text           # byte for byte: leave everything as-is (commit and checkout)
+```
+
+Requirement (assumed on purpose): this default yields **native** EOL because each machine
+resolves it via its `core.eol`, whose default value (when unset) is already `native`. appease
+**does not touch Git's configuration** —neither global nor local— so native EOL remains an
+environment requirement: it works as long as `core.eol` is not pinned to `lf`/`crlf`. You can
+verify it, without changing anything, with `git config --get core.eol`.
+
+When adopting or changing `.gitattributes`, already-committed files are not rewritten on
+their own; a one-time pass is needed: `git add --renormalize .`.
+
+### BOM / charset — handled by `.editorconfig`
+
+Git does **not** know how to add or remove the BOM; that's why this axis lives in
+`.editorconfig` (which VSC honors live) and appease applies it.
+
+- Default: **UTF-8 without BOM** (the sane choice for JS/TS/JSON/web).
+- `charset = utf-8-bom` → with a fixed BOM (PowerShell 5.1 with non-ASCII, CSV for Excel, etc.).
+- `charset = unset` → leave the BOM as-is, don't touch it.
+
+### Trailing spaces and final newline — `.editorconfig`
+
+- `trim_trailing_whitespace = true` → trim (default). `= false` → leave them as-is
+  (typical in Markdown, where two trailing spaces are an intentional line break).
+- `insert_final_newline = true` → guarantee exactly one (default). `= false` → leave
+  as-is.
+
+### Indentation — a convention for the editor, **not** a rewrite
+
+For now indentation is treated as a **convention**, not as a mass rewrite (converting
+tab↔spaces is structural, it depends on the language —Makefile *requires* tabs, Go uses tabs—
+and it's exactly the most invasive change).
+
+- `.editorconfig`: `indent_style = space` (to stop adding more tabs), with registered
+  exceptions (`[Makefile] indent_style = tab`, Go, etc.).
+- `.vscode/settings.json`: `editor.renderWhitespace = "selection"`, so that whitespace is
+  shown **only when selecting** text (tabs appear as little arrows on demand; with no
+  selection nothing shows). It's pinned in the repo to guarantee that behavior for the whole
+  team, without depending on each person's VSC default.
+
+
+```json
+{
+  "editor.renderWhitespace": "selection"
+}
+```
+
+The actual conversion of tabs stays **out** of this workflow for now (see `--tabs-*`).
+
+### Example `.editorconfig`
+
+
+```editorconfig
+root = true
+
+# Default for everything
+[*]
+charset = utf-8                  # no BOM
+trim_trailing_whitespace = true
+insert_final_newline = true
+indent_style = space
+
+# Markdown: the two trailing spaces are intentional
+[*.md]
+trim_trailing_whitespace = false
+
+# Examples of one-off exceptions
+[test/fixtures/excel/**]
+charset = utf-8-bom
+
+[test/fixtures/raw/**]
+charset = unset
+trim_trailing_whitespace = false
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab
+```
+
+---
+
+## Modes
+
+Every command prints at the end **which files it created or modified**.
+
+Each command takes the directory to process as an optional positional argument
+(`appease <command> [dir]`; defaults to the current directory).
+
+| Command | Reads | Writes | Destructive |
+|---|---|---|---|
+| `audit` | existing configs (or the defaults it would propose) + the files | nothing, only **reports** what is out of spec | no |
+| `add-config-defaults` | — | the configs with **pure defaults** (without looking at reality) | no (only creates config) |
+| `adapt-configs` | configs + audit | creates or **adapts** the configs to reflect what was found | does not touch source code |
+| `fix-format` | configs | **modifies the files** (BOM, trailing, newline; EOL via Git) honoring the configs | yes (Git reverts) |
+
+### `audit`: report format
+
+`audit` prints canonical JSON with **two** lists. The key point is that conforming files
+**appear in neither**: only the ones that need attention and the ones that couldn't be
+evaluated are listed. A clean repo yields both lists empty:
+
+
+```json
+{
+  "findings": [],
+  "notAnalyzed": []
+}
+```
+
+- **`findings`**: **analyzed files that deviate** from their resolved config. Each entry
+  carries `path`, `deviations` (axes that differ from what the config asks for) and
+  `unresolved` (axes governed by an unrecognized config value: not evaluated, reported as-is).
+- **`notAnalyzed`**: files that were **not analyzed**, with their `reason`
+  (`binary-extension`, `binary-content`, `gitattributes-notext`, `non-utf8`).
+
+This format is **provisional**: today the output is the direct serialization of the
+`AuditResult` type, meant to be easy to parse and test. It may grow if the value justifies it.
+
+### `adapt-configs`: records every deviation as an exception
+
+`adapt-configs` records **every** deviation it finds as an explicit exception, across all
+axes equally (without classifying or guessing intent). This gives a safety invariant: **right
+after `adapt-configs`, a `fix-format` changes nothing**, because the config describes
+reality 100%. Only when you **prune** (delete) exceptions does `fix-format` touch *that and
+only that*.
+
+So, "everything is wrong and I want to fix it all at once" is solved by deleting the block of
+exceptions: everything falls back to the default → `fix-format` rewrites whatever is needed.
+
+Behavior details:
+
+- A deviation can be **multi-axis** in a single file (CRLF + trailing + no final newline +
+  BOM). Its entry covers several properties; deleting it reverts that entire file to the
+  default. To keep a single property (rare) you edit the line instead of deleting it.
+- Each exception lands in the **file that owns the axis**: EOL → `.gitattributes`, the rest →
+  `.editorconfig`. "Select all and delete" is per config file (two places).
+
+### `--tabs-*` (out of scope for now)
+
+Indentation conversion (tab→spaces or vice versa) is left as separate switches, to be defined
+later, since it's structural, risky and language-dependent. In the meantime, tabs are fixed
+by hand.
+
+
+---
+
+## Suggested workflow
+
+0. *(optional)* `add-config-defaults` → **commit**. Versions the "north star" (the pure
+   norm), so that in step 1 deviations stand out in the diff against that norm.
+1. `adapt-configs` → the `git diff` of the configs shows **every added exception = every
+   deviation**. That diff is the real report.
+2. Review those exceptions: keep the ones that were on purpose, **delete** by hand the ones
+   that were junk (if almost everything is wrong, delete the whole block).
+3. `fix-format` → normalizes everything no longer protected by an exception.
+
+Since Git reverts anything, the destructive steps are safe to try.
+
+
+---
+
+## Architecture
+
+Designed to **stand on its own** and to be integrable later as a dependency of another tool.
+
+Text transformation is separated from orchestration (Git, file system, args), so the core is
+pure and testable.
+
+### Pure function (with its tests)
+
+The heart is a side-effect-free function: it receives a file's content (already decoded) and
+the options resolved for that file, and returns the normalized content plus a report of what
+changed. It touches neither disk, nor Git, nor arguments.
+
+
+```
+normalizeText(content: string, options: Options): { content: string; report: Report }
+```
+
+- `Options`: BOM (remove | add | keep), trailing (trim | keep), final newline (ensure | keep).
+  (EOL is Git's responsibility, not this function's.)
+- `Report`: what was modified (so as not to fail silently).
+
+The audit also has its pure core: given a chunk of text, it detects its current state (EOL
+crlf/lf/mixed, BOM yes/no, trailing yes/no, final newline, indentation tabs/spaces/mixed).
+
+Test cases: CRLF↔LF, mixed EOL, trailing, missing/excess final newline, BOM present/absent,
+empty file, and **idempotence** (running twice changes nothing).
+
+Strongly typed, `strict`, no `any`. Errors are handled, not ignored.
+
+
+### `cli.ts`
+
+Maps the commands (`audit`, `add-config-defaults`, `adapt-configs`, `fix-format`) to
+TS calls and orchestrates the effects:
+
+1. Discovers files (`git ls-files`), skips binaries and the ones marked `-text`.
+2. Reads `.gitattributes` and `.editorconfig` to resolve the per-file options.
+3. Depending on the command: only reports, generates/adapts configs, or reads each file, calls
+   the pure function and rewrites if it changed.
+4. Prints the summary of created/modified files.
+
+
+---
+
+## To be defined at implementation time
+
+- Default value for `indent_size` (probably detected per project/language).
+- Exact format of the `audit` report (provisional today, documented above).
+- Binary detection and handling of files in encodings other than UTF-8.
+- Concrete `--tabs-*` switches.
+

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import type { RunOptions } from "./core/types.js";
+/**
+ * Parse argv into resolved RunOptions. cleye is the single source of truth: each RunMode is a
+ * subcommand (`appease <command> [dir]`), so the modes are mutually exclusive by construction and
+ * each gets its own `--help`. cleye prints usage and exits on unknown flags and on `--help`.
+ */
+export declare function parseArgs(argv?: string[]): RunOptions;
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// CLI entry point. Maps switches to the public API and orchestrates the effects.
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { cli, command } from "cleye";
+import { runAppease } from "./index.js";
+/** `--dry-run`, shared by the commands that write to disk (not by `audit`, which never writes). */
+const dryRunFlag = {
+    dryRun: { type: Boolean, description: "Simulate writes; report what would change but touch nothing" },
+};
+/**
+ * Parse argv into resolved RunOptions. cleye is the single source of truth: each RunMode is a
+ * subcommand (`appease <command> [dir]`), so the modes are mutually exclusive by construction and
+ * each gets its own `--help`. cleye prints usage and exits on unknown flags and on `--help`.
+ */
+export function parseArgs(argv) {
+    const parsed = cli({
+        name: "appease",
+        help: { description: "Normalize a repo's text files to its .editorconfig / .gitattributes. One command is required." },
+        commands: [
+            command({ name: "audit", parameters: ["[dir]"], strictFlags: true, help: { description: "Report deviations only (no writes)" } }),
+            command({ name: "add-config-defaults", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Write pure-default configs (only the ones that do not exist yet)" } }),
+            command({ name: "adapt-configs", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Write/adapt configs to reflect the repo's current reality" } }),
+            command({ name: "fix-format", parameters: ["[dir]"], strictFlags: true, flags: dryRunFlag, help: { description: "Normalize files (BOM / EOL / trailing whitespace / final newline)" } }),
+        ],
+    }, undefined, argv);
+    if (parsed.command === undefined) {
+        parsed.showHelp();
+        process.stderr.write("\nSpecify a command: audit | add-config-defaults | adapt-configs | fix-format\n");
+        process.exit(1);
+    }
+    const dir = parsed._.dir;
+    return {
+        mode: parsed.command,
+        cwd: dir !== undefined ? resolve(dir) : process.cwd(),
+        dryRun: parsed.command === "audit" ? false : parsed.flags.dryRun ?? false,
+    };
+}
+/** Drop empty `unresolved` arrays from the audit JSON (an empty list carries no information). */
+function omitEmptyUnresolved(key, value) {
+    return key === "unresolved" && Array.isArray(value) && value.length === 0 ? undefined : value;
+}
+export async function main(argv) {
+    const report = await runAppease(parseArgs(argv));
+    if (report.audit !== undefined)
+        process.stdout.write(`${JSON.stringify(report.audit, omitEmptyUnresolved, 2)}\n`);
+    for (const path of report.created)
+        process.stdout.write(`${report.dryRun ? "would create" : "created"}: ${path}\n`);
+    for (const path of report.modified)
+        process.stdout.write(`${report.dryRun ? "would modify" : "modified"}: ${path}\n`);
+    for (const path of report.unchanged)
+        process.stdout.write(`unchanged: ${path}\n`);
+    return 0;
+}
+// Only run when invoked directly (not when imported by tests).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (err) => {
+        process.stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/core/analyze.d.ts

@@ -0,0 +1,9 @@
+import type { FormatReport } from "./types.js";
+/**
+ * Audit core: detect the current low-level format state of a single file's
+ * already-decoded text. Pure and side-effect free (no disk, no Git, no args).
+ *
+ * Assumes the decoder kept a leading BOM (U+FEFF) in `content` if the file had
+ * one (the orchestration decodes raw, without stripping it).
+ */
+export declare function analyzeContent(content: string): FormatReport;

package/dist/core/analyze.js

@@ -0,0 +1,30 @@
+/**
+ * Audit core: detect the current low-level format state of a single file's
+ * already-decoded text. Pure and side-effect free (no disk, no Git, no args).
+ *
+ * Assumes the decoder kept a leading BOM (U+FEFF) in `content` if the file had
+ * one (the orchestration decodes raw, without stripping it).
+ */
+export function analyzeContent(content) {
+    const empty = content === "";
+    const hasBom = content.charCodeAt(0) === 0xfeff;
+    // Count CRLF, CR and LF separately. Each CRLF contains one CR and one LF, so
+    // the lone-CR / lone-LF counts come out by subtraction.
+    const crlfCount = (content.match(/\r\n/g) ?? []).length;
+    const crCount = (content.match(/\r/g) ?? []).length;
+    const lfCount = (content.match(/\n/g) ?? []).length;
+    const hasCrlf = crlfCount > 0;
+    const hasCr = crCount - crlfCount > 0;
+    const hasLf = lfCount - crlfCount > 0;
+    // Horizontal whitespace right before a line break or at the end of the file.
+    const hasTrailingSpaces = /[ \t]+(?:\r?\n|$)/.test(content);
+    const finalNewline = detectFinalNewline(content);
+    return { empty, hasBom, hasCrlf, hasLf, hasCr, hasTrailingSpaces, finalNewline };
+}
+/** Classify the trailing run of newlines (LF / CRLF only). */
+function detectFinalNewline(content) {
+    if (!/(?:\r\n|\n)$/.test(content))
+        return "missing";
+    return /(?:\r\n|\n){2}$/.test(content) ? "multiple" : "present";
+}
+//# sourceMappingURL=analyze.js.map

package/dist/core/analyze.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze.js","sourceRoot":"","sources":["../../src/core/analyze.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,KAAK,GAAG,OAAO,KAAK,EAAE,CAAC;IAC7B,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC;IAEhD,6EAA6E;IAC7E,wDAAwD;IACxD,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IACxD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IACpD,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;IACpD,MAAM,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,OAAO,GAAG,SAAS,GAAG,CAAC,CAAC;IAEtC,6EAA6E;IAC7E,MAAM,iBAAiB,GAAG,mBAAmB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAE5D,MAAM,YAAY,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAEjD,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,CAAC;AACnF,CAAC;AAED,8DAA8D;AAC9D,SAAS,kBAAkB,CAAC,OAAe;IACzC,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACpD,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC"}

package/dist/core/audit.d.ts

@@ -0,0 +1,14 @@
+import type { FileAudit, FormatReport, ProjectConfig } from "./types.js";
+/**
+ * Evaluate a collection of per-file analyses against the resolved project
+ * config. Pure. Returns one `FileAudit` per file that has any finding
+ * (deviation or unresolved axis); clean files are omitted.
+ *
+ * `nativeEol` is this machine's native line ending (CRLF on Windows, LF
+ * elsewhere); it is how `eol=auto` is evaluated, since under `text=auto` the
+ * working copy is expected to be native. The pure core receives it as input.
+ */
+export declare function audit(reports: {
+    path: string;
+    report: FormatReport;
+}[], config: ProjectConfig, nativeEol: "lf" | "crlf"): FileAudit[];

package/dist/core/audit.js

@@ -0,0 +1,46 @@
+/**
+ * Evaluate a collection of per-file analyses against the resolved project
+ * config. Pure. Returns one `FileAudit` per file that has any finding
+ * (deviation or unresolved axis); clean files are omitted.
+ *
+ * `nativeEol` is this machine's native line ending (CRLF on Windows, LF
+ * elsewhere); it is how `eol=auto` is evaluated, since under `text=auto` the
+ * working copy is expected to be native. The pure core receives it as input.
+ */
+export function audit(reports, config, nativeEol) {
+    const files = [];
+    for (const { path, report } of reports) {
+        const cfg = config.resolve(path);
+        const deviations = fileDeviations(report, cfg, nativeEol);
+        if (deviations.length > 0 || cfg.unresolved.length > 0)
+            files.push({ path, deviations, unresolved: cfg.unresolved });
+    }
+    return files;
+}
+/** Axes where `report` differs from `cfg`, skipping axes the config could not resolve (case 2). */
+function fileDeviations(report, cfg, nativeEol) {
+    const deviations = [];
+    const governs = (axis) => !cfg.unresolved.includes(axis);
+    if (governs("bom")) {
+        if (cfg.bom === "add" && !report.hasBom)
+            deviations.push("bom");
+        else if (cfg.bom === "remove" && report.hasBom)
+            deviations.push("bom");
+    }
+    if (governs("trailing") && cfg.trailing === "trim" && report.hasTrailingSpaces) {
+        deviations.push("trailing");
+    }
+    if (governs("finalNewline") && cfg.finalNewline === "ensure" && report.finalNewline !== "present") {
+        deviations.push("finalNewline");
+    }
+    if (governs("eol")) {
+        const target = cfg.eol === "auto" ? nativeEol : cfg.eol;
+        if (target === "lf" && (report.hasCrlf || report.hasCr))
+            deviations.push("eol");
+        else if (target === "crlf" && (report.hasLf || report.hasCr))
+            deviations.push("eol");
+        // "binary" -> EOL is not evaluated
+    }
+    return deviations;
+}
+//# sourceMappingURL=audit.js.map

package/dist/core/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/core/audit.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,KAAK,CACnB,OAAiD,EACjD,MAAqB,EACrB,SAAwB;IAExB,MAAM,KAAK,GAAgB,EAAE,CAAC;IAC9B,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACjC,MAAM,UAAU,GAAG,cAAc,CAAC,MAAM,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;QAC1D,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC;IACvH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,mGAAmG;AACnG,SAAS,cAAc,CAAC,MAAoB,EAAE,GAAuB,EAAE,SAAwB;IAC7F,MAAM,UAAU,GAAoB,EAAE,CAAC;IACvC,MAAM,OAAO,GAAG,CAAC,IAAmB,EAAW,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEjF,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,IAAI,GAAG,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,CAAC,MAAM;YAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aAC3D,IAAI,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM;YAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC/E,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,CAAC,cAAc,CAAC,IAAI,GAAG,CAAC,YAAY,KAAK,QAAQ,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClG,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnB,MAAM,MAAM,GAAG,GAAG,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;QACxD,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;aAC3E,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrF,mCAAmC;IACrC,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/core/configs.d.ts

@@ -0,0 +1,15 @@
+import type { ProjectConfig, RawConfigs } from "./types.js";
+/**
+ * Interpret the raw contents of the three config sources into a resolver for
+ * per-file options. Pure: takes the already-read contents, touches no disk.
+ *
+ * Each axis is owned by exactly one source (see LEEME.md): EOL -> .gitattributes,
+ * BOM/charset/trailing/final-newline -> .editorconfig, renderWhitespace ->
+ * .vscode/settings.json. Only `.editorconfig` and `.gitattributes` drive
+ * `resolve`; `.vscode/settings.json` only counts towards `present`.
+ */
+export declare function interpretConfigs(raw: RawConfigs): ProjectConfig;
+/** Pure, idempotent defaults for `.editorconfig` (no inspection of the repo's reality). */
+export declare function defaultEditorconfig(): string;
+/** Pure, idempotent defaults for `.gitattributes` (`* text=auto`, ...). */
+export declare function defaultGitattributes(): string;

package/dist/core/configs.js

@@ -0,0 +1,61 @@
+import { parseEditorconfig, resolveEditorconfig } from "./editorconfig.js";
+import { parseGitattributes, resolveGitEol } from "./gitattributes.js";
+/**
+ * Interpret the raw contents of the three config sources into a resolver for
+ * per-file options. Pure: takes the already-read contents, touches no disk.
+ *
+ * Each axis is owned by exactly one source (see LEEME.md): EOL -> .gitattributes,
+ * BOM/charset/trailing/final-newline -> .editorconfig, renderWhitespace ->
+ * .vscode/settings.json. Only `.editorconfig` and `.gitattributes` drive
+ * `resolve`; `.vscode/settings.json` only counts towards `present`.
+ */
+export function interpretConfigs(raw) {
+    const editorconfig = raw.editorconfig !== null ? parseEditorconfig(raw.editorconfig) : { root: false, sections: [] };
+    const gitattributes = raw.gitattributes !== null ? parseGitattributes(raw.gitattributes) : { rules: [] };
+    return {
+        present: {
+            editorconfig: raw.editorconfig !== null,
+            gitattributes: raw.gitattributes !== null,
+            vscodeSettings: raw.vscodeSettings !== null,
+        },
+        resolve: (path) => resolveFile(editorconfig, gitattributes, path),
+    };
+}
+/** Combine the per-source resolutions into the file's resolved config. */
+function resolveFile(editorconfig, gitattributes, path) {
+    const ec = resolveEditorconfig(editorconfig, path);
+    const gitEol = resolveGitEol(gitattributes, path);
+    const unresolved = [...ec.unresolved];
+    if (gitEol === "unresolved")
+        unresolved.push("eol");
+    return {
+        bom: ec.charset === "utf-8-bom" ? "add" : ec.charset === "utf-8" ? "remove" : "keep",
+        eol: gitEol === "unresolved" ? "auto" : gitEol,
+        trailing: ec.trailing,
+        finalNewline: ec.finalNewline,
+        unresolved,
+    };
+}
+/** Pure, idempotent defaults for `.editorconfig` (no inspection of the repo's reality). */
+export function defaultEditorconfig() {
+    return [
+        "root = true",
+        "",
+        "# Defaults for every file",
+        "[*]",
+        "charset = utf-8",
+        "trim_trailing_whitespace = true",
+        "insert_final_newline = true",
+        "indent_style = space",
+        "",
+    ].join("\n");
+}
+/** Pure, idempotent defaults for `.gitattributes` (`* text=auto`, ...). */
+export function defaultGitattributes() {
+    return [
+        "# Normalize to LF in the repo on commit; check out with the OS-native EOL.",
+        "* text=auto",
+        "",
+    ].join("\n");
+}
+//# sourceMappingURL=configs.js.map

package/dist/core/configs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configs.js","sourceRoot":"","sources":["../../src/core/configs.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC9F,OAAO,EAAsB,kBAAkB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3F;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAe;IAC9C,MAAM,YAAY,GAAiB,GAAG,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IACnI,MAAM,aAAa,GAAkB,GAAG,CAAC,aAAa,KAAK,IAAI,CAAC,CAAC,CAAC,kBAAkB,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IACxH,OAAO;QACL,OAAO,EAAE;YACP,YAAY,EAAE,GAAG,CAAC,YAAY,KAAK,IAAI;YACvC,aAAa,EAAE,GAAG,CAAC,aAAa,KAAK,IAAI;YACzC,cAAc,EAAE,GAAG,CAAC,cAAc,KAAK,IAAI;SAC5C;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,YAAY,EAAE,aAAa,EAAE,IAAI,CAAC;KAClE,CAAC;AACJ,CAAC;AAED,0EAA0E;AAC1E,SAAS,WAAW,CAAC,YAA0B,EAAE,aAA4B,EAAE,IAAY;IACzF,MAAM,EAAE,GAAG,mBAAmB,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACnD,MAAM,MAAM,GAAG,aAAa,CAAC,aAAa,EAAE,IAAI,CAAC,CAAC;IAClD,MAAM,UAAU,GAAoB,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,CAAC;IACvD,IAAI,MAAM,KAAK,YAAY;QAAE,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACpD,OAAO;QACL,GAAG,EAAE,EAAE,CAAC,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM;QACpF,GAAG,EAAE,MAAM,KAAK,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM;QAC9C,QAAQ,EAAE,EAAE,CAAC,QAAQ;QACrB,YAAY,EAAE,EAAE,CAAC,YAAY;QAC7B,UAAU;KACX,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,mBAAmB;IACjC,OAAO;QACL,aAAa;QACb,EAAE;QACF,2BAA2B;QAC3B,KAAK;QACL,iBAAiB;QACjB,iCAAiC;QACjC,6BAA6B;QAC7B,sBAAsB;QACtB,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,oBAAoB;IAClC,OAAO;QACL,4EAA4E;QAC5E,aAAa;QACb,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/core/editorconfig.d.ts

@@ -0,0 +1,30 @@
+/** Axes an `.editorconfig` can govern for us; an axis here means "skip + report" (case 2). */
+export type EditorconfigAxis = "bom" | "trailing" | "finalNewline";
+/** Resolved `.editorconfig` stance for a path (only the axes we manage). */
+export interface EditorconfigResolution {
+    /** `keep` = `unset`, `false`-like, or not specified. */
+    charset: "utf-8" | "utf-8-bom" | "keep";
+    trailing: "trim" | "keep";
+    finalNewline: "ensure" | "keep";
+    /** Axes governed by a recognized key with an unrecognized value (case 2). */
+    unresolved: EditorconfigAxis[];
+}
+interface Section {
+    matches: (path: string) => boolean;
+    charset: "utf-8" | "utf-8-bom" | "unset" | "unrecognized" | undefined;
+    trim: boolean | "unset" | "unrecognized" | undefined;
+    finalNewline: boolean | "unset" | "unrecognized" | undefined;
+}
+export interface Editorconfig {
+    root: boolean;
+    sections: Section[];
+}
+/**
+ * Parse `.editorconfig` content into ordered sections. Pure.
+ * Throws on a structurally malformed line (case 3); properties we do not manage
+ * (indent_*, max_line_length, ...) are ignored (case 1).
+ */
+export declare function parseEditorconfig(content: string): Editorconfig;
+/** Resolve the effective stance for `path` (last matching section wins per property). */
+export declare function resolveEditorconfig(ec: Editorconfig, path: string): EditorconfigResolution;
+export {};