@preventive/compare 0.0.0-stage → 1.0.1

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nikita Skovoroda
+
+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/compare.d.ts

@@ -0,0 +1,185 @@
+import type { Block } from '@preventive/diff'
+
+// An entry of a tree, in the shape tar has it: what @preventive/archive's
+// unpack returns and Vfs.entries yields are these as they are. `name` is a
+// relative path with no empty, `.` or `..` segment, or `.` for the root
+// directory -- or, under `paths: 'keys'`, any non-empty name. A file is `data`
+// under `mode`, 0o644 if not given: text is kept as text, and stands for its
+// UTF-8. A symlink's or a hard link's target is `linkname`, a hard link's
+// spelled as the name of an entry in the same tree. A directory adds nothing,
+// as git keeps none; what is not given a directory entry is implied. `data`
+// and `linkname` are read only where the type uses them; a mode given is
+// checked on any entry, but only a file's is compared, as only a file's is
+// kept by git. A fifo or a device is refused, as is a name, link target or
+// text that is not well-formed Unicode, since git could hold none of them.
+export interface TreeEntry {
+  name: string
+  type?: 'file' | 'contiguous-file' | 'directory' | 'symlink' | 'hardlink' | 'fifo' | 'character-device' | 'block-device'
+  mode?: number
+  linkname?: string
+  data?: string | Uint8Array
+}
+
+// A file or a link as its tree holds it: what git keeps of one. A hard link
+// is a copy of what it names. `data` is the entry's own, text or bytes, not a
+// copy; text and the bytes of its UTF-8 are the same content.
+export type TreeFile =
+  | { path: string; type: 'file'; mode: number; data: string | Uint8Array }
+  | { path: string; type: 'symlink'; target: string }
+
+// git's statuses, A, D, M, R and T.
+export type Status = 'added' | 'deleted' | 'modified' | 'renamed' | 'type-changed'
+
+// One path that differs, and what became of it. `old` is null for an added
+// file and `new` for a deleted one; a renamed file has both, under their
+// two paths. `similarity` is a rename's, as git's similarity index: the
+// percentage of the new file the old one accounts for, 100 where the content
+// is unchanged; null for anything else.
+export interface FileStatus {
+  status: Status
+  old: TreeFile | null
+  new: TreeFile | null
+  similarity: number | null
+}
+
+// A status with what happened to the content: `blocks`, @preventive/diff's
+// change set from the old side to the new, where a file's content is its data
+// and a link's its target, and a side that is not there is empty. `insertions`
+// and `deletions` count its lines, as --numstat does. Content is text when it
+// is UTF-8 with no NUL; where either side is not, `binary` is true, and there
+// are no blocks and no counts.
+export interface FileChange extends FileStatus {
+  binary: boolean
+  blocks: Block[]
+  insertions: number | null
+  deletions: number | null
+}
+
+// How a change's lines are found, as diff's options: `horizon` is how far a
+// run of lines free to move may go into the lines the two files share at
+// either end -- without limit unless given, as git has it, or 0 to match
+// `diff -U0` and the normal format, the context to match `diff -u` (diff's
+// --horizon-lines); `whitespace` (-w as 'all', -b as 'change', -Z as
+// 'trailing') and `ignoreCase` (-i) say which lines are the same, so that a
+// file changed in nothing else has no blocks.
+export interface LineOptions {
+  horizon?: number
+  whitespace?: 'none' | 'all' | 'change' | 'trailing'
+  ignoreCase?: boolean
+}
+
+// `paths: 'keys'` takes names as keys, as a source map spells them
+// (`webpack://app/a.js`, `../a.js`), and not as paths of a tree that must hold
+// together. `renames` is git's -M: the least similarity, as a percentage
+// above 0, at which a deleted file and an added one are one file renamed;
+// `true` is git's default of 50, `false` finds none, and 100 only those whose
+// content is unchanged. `renameGroup`, given, keeps renames within a group:
+// files are paired only where it gives their paths the same group, a
+// package's for one.
+//
+// `renamesByPath`, unless false, also takes a deleted file and an added one
+// for a rename however little alike, where their paths say so: where they
+// differ only by `lib` for `src` or a TypeScript extension for its JavaScript
+// one (`.ts`, `.mts`, `.cts`, `.tsx` for `.js`, `.mjs`, `.cjs`, `.jsx`), or
+// both, the best scoring of a file's such partners; and, as triage's Compare
+// pairs them, where they share a name less its extension, the extension's
+// family (scripts, `.js` to `.tsx`; styles, `.css` `.scss` `.sass` `.less`)
+// and their directories but for one -- not a package's name under
+// node_modules -- each the other's only such partner. Either gives way only
+// to a candidate that is a rename by itself and scores at least halfway from
+// the pair's score to 100%. git has no such pass, so false is git's own -M.
+//
+// `renameLimit` is git's diff.renameLimit: when more deleted files times added
+// files are left, in a group, after the renames that need no scoring than its
+// square, the rest are not looked for. 1000 unless given; Infinity for no
+// limit. `lines: false` gives statuses alone, their lines found by
+// formatPatch when wanted.
+export interface CompareOptions extends LineOptions {
+  paths?: 'tree' | 'keys'
+  renames?: boolean | number
+  renamesByPath?: boolean
+  renameGroup?: (path: string) => unknown
+  renameLimit?: number
+  lines?: boolean
+}
+
+// Every path the trees do not have the same, in git's order: by path in code
+// point order, a rename at its new one. A file is the same when its content
+// and its mode are, a link when its target is. Throws a CompareError for a
+// tree that does not hold together, naming the path and which tree. A
+// `lines` not known to be true or false types the result as either.
+export function compareTrees(a: Iterable<TreeEntry>, b: Iterable<TreeEntry>, options: CompareOptions & { lines: false }): FileStatus[]
+export function compareTrees(a: Iterable<TreeEntry>, b: Iterable<TreeEntry>, options?: CompareOptions & { lines?: true }): FileChange[]
+export function compareTrees(a: Iterable<TreeEntry>, b: Iterable<TreeEntry>, options?: CompareOptions): FileStatus[] | FileChange[]
+
+// The changes as `git diff` writes them, without its `index` lines, with
+// `context` lines around each change, 3 unless given. A file's mode is
+// written in full, where git would only have 644 or 755. The hunks are each
+// change's own blocks, found under the line options given here, which must
+// carry its old content to its new under them, or @preventive/diff's
+// DiffError is thrown; a change without blocks has them found here.
+export function formatPatch(changes: Iterable<FileStatus | FileChange>, options?: LineOptions & { context?: number }): string
+
+// The ranges `[from, to)` that changed within a removed line and the added
+// line it pairs with, word by word (runs of letters and digits, whitespace,
+// any other character), as the shortest edit script pairLines weighs lines by
+// finds them: every character that changed is in one, and two split by
+// whitespace alone are merged, taking it in. None where the lines are the
+// same; null, no word view, where they are mostly replaced, or past 2000
+// characters or 800 words, so that all of either line is taken as changed.
+export function wordRanges(left: string, right: string): { a: [number, number][]; b: [number, number][] } | null
+
+// A change's removed lines paired with its added lines, in order: two lines
+// pair only where wordRanges gives them ranges (a word in common, at most six
+// in ten of either changed), the most such pairs, and of those the most alike.
+// Where weighing every pair takes too long (many long lines alike), each
+// removed line in turn takes the most alike of the next six added lines.
+// `[i, j]` indices into the two lists; none where either holds more than 200
+// lines.
+export function pairLines(olds: readonly string[], news: readonly string[]): [number, number][]
+
+// Whether diff -w, as `blocks` were found with it, keeps as unchanged a line
+// whose blanks between the same two characters (or before the first or after
+// the last) changed and mix more than one kind, as spaces turned to tabs. True
+// too where `blocks` don't carry `before` to `after` under -w, as such blocks
+// may hide anything.
+export function hidesMixedWhitespace(before: string, after: string, blocks: readonly Pick<Block, 'a0' | 'a1' | 'b0' | 'b1'>[]): boolean
+
+// A rename as `git diff --stat` writes one, in parts for a view to color: the
+// directories both share (`head`), what changed (`from`, `to`), down to the
+// extension where that is all unless `extension` is false, and the rest (`tail`).
+export function renameParts(from: string, to: string, options?: { extension?: boolean }): { head: string; from: string; to: string; tail: string }
+
+// The directory one tree's files sit under in the other: `base: ''` and
+// `other` the directory where the old tree's `a.js` is the new one's
+// `src/a.js`, or the other way round.
+export interface Root { base: string; other: string }
+
+// The root between two trees, or null, and each old path as the new tree lays
+// it out: through the root where the new tree has it there, else as it is where
+// it has that, else through the root clear of every path taken, a `../` further
+// out. A root is taken where it pairs more files than none, and at least half
+// the files of the side without the directory; a tie either way is none.
+export interface Layout { root: Root | null; paths: Map<string, string> }
+export function treeLayout(basePaths: Iterable<string>, otherPaths: Iterable<string>): Layout
+
+// An old module's directory where the layout placed one of its `files` (paths
+// within it), else moved with the root: one outside it a `../` further out for
+// each level of the root, `.` as it is.
+export function layoutDir(layout: Layout, dir: string, files: Iterable<string>): string
+
+// Both trees' package directories by path, either map null, as the new tree
+// lays out its files: the old ones moved with the root, the new ones kept.
+export function layoutPackageDirs(baseDirs: Map<string, string> | null, otherDirs: Map<string, string> | null, layout: Layout): Map<string, string> | null
+
+// A view's directory `prefix` with where the root puts it on each side
+// (`./dir/`, `./src/dir/`); a prefix the root doesn't lead is dropped.
+export function rootLabel(root: Root | null, prefix: string): { prefix: string; from: string | null; to: string | null }
+
+// `path` is the name at fault as its entry spelled it, and `tree` which tree
+// holds it.
+export class CompareError extends Error {
+  constructor(detail: string, path?: string, tree?: 'old' | 'new')
+  path: string | undefined
+  tree: 'old' | 'new' | undefined
+}

package/compare.js

@@ -0,0 +1,29 @@
+// Two file trees compared the way `git diff -M` compares two commits, built
+// on @preventive/diff for what changed inside each file and @exodus/bytes for
+// UTF-8. Nothing here reads a disk.
+
+// The trees in, every file that differs out, with what became of it --
+// added, deleted, modified, renamed, or changed in type -- and its line
+// change set. A tree is tar's entries, as @preventive/archive unpacks them
+// or a Vfs yields them, or names taken as keys.
+export { compareTrees } from './src/changes.js'
+
+// Those changes as the patch git writes, for git apply or patch to carry out.
+export { formatPatch } from './src/patch.js'
+
+// Changed lines read word by word: what changed within a line and which removed
+// line was edited into which added one; and whether diff -w hides blanks of
+// more than one kind changing.
+export { pairLines } from './src/pairs.js'
+export { wordRanges } from './src/words.js'
+export { hidesMixedWhitespace } from './src/whitespace.js'
+
+// A rename written as `git diff --stat` writes one.
+export { renameParts } from './src/paths.js'
+
+// Two trees taken from different roots lined up: the root between them and
+// each old path, directory and package directory as the new tree lays it out.
+export { layoutDir, layoutPackageDirs, rootLabel, treeLayout } from './src/layout.js'
+
+// What a tree that does not hold together is refused with.
+export { CompareError } from './src/error.js'

package/names.d.ts

@@ -0,0 +1,42 @@
+import type { Block } from '@preventive/diff'
+
+// How each text is parsed, by the extension of the file it is: `mjs` a
+// module, `cjs` a CommonJS module, any other (`js` unless given) a module
+// where it says so (`import`, `export`) and a script where not.
+// `otherExtension` is the new text's, the old one's unless given.
+export interface RenameOptions {
+  extension?: string
+  otherExtension?: string
+}
+
+// Why a text keeps its own names: it does not parse, or oxc's semantic check
+// finds an error in it (`unparsed`); it reads a name by its spelling (`eval`,
+// `with`: `dynamic`); it holds JSX (`jsx`); outside strict code it declares a
+// function in a block, which there sets its function's variable of that name
+// too (`block-function`); or the names found would not bind as the old ones
+// did, or a check that should never fail did, or anything else went wrong
+// (`unverified`, what failed among the warnings).
+export type RenameReason = 'unparsed' | 'dynamic' | 'jsx' | 'block-function' | 'unverified'
+
+// The diff of two JavaScript files minified on both sides with renamed names
+// set aside. The old side is given the new side's names wherever a minifier
+// renamed a variable alike throughout (a declared variable's short ASCII name,
+// not a script's top level, an export's or import's by its own name, or a
+// shorthand property's), checked to bind every name as before by this
+// package's scope analysis and again by oxc's minifier; formatted again where
+// that changes its layout alone and still binds alike; diffed as diff -U0 has
+// it; and the blocks checked to take `before` to the new side (thrown should
+// they not). `reason` says why no names were given; `reads` the properties
+// either text reads names through (`name`, `toString`, `stack`, `callee`,
+// `caller`), sorted, as code reading its names may act otherwise renamed;
+// `marks` the plain diff's blocks that differ in renamed names alone; and
+// `warnings` what a check that should never fail found.
+export function renamedDiff(before: string, after: string, options?: RenameOptions & { whitespace?: 'none' | 'all' | 'change' | 'trailing' }): Promise<{
+  before: string
+  blocks: Pick<Block, 'a0' | 'a1' | 'b0' | 'b1'>[]
+  reason: RenameReason | null
+  reads: string[]
+  marks: Pick<Block, 'a0' | 'a1' | 'b0' | 'b1'>[]
+  warnings: string[]
+}>
+

package/names.js

@@ -0,0 +1,9 @@
+// JavaScript minified on both sides, its renamed names told apart from its
+// changes: the old side given the new side's names wherever a minifier
+// renamed a variable alike throughout, so that the two then diff as they are.
+// Built on oxc-parser and oxc-minify, and oxfmt for renamedDiff, optional
+// peers: on Node loaded on first use, elsewhere oxc with this module.
+// compare.js loads none. Typed and described in names.d.ts.
+
+// The diff of two such files with renamed names set aside, checked to hide no change.
+export { renamedDiff } from './src/names/diff.js'

package/package.json

@@ -1,6 +1,133 @@
 {
   "name": "@preventive/compare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Two file trees compared as git diff compares them, with their line change sets and the patch git writes; and minified JavaScript compared with its layout and its renamed names set aside, each step checked to hide no change",
+  "type": "module",
+  "main": "./compare.js",
+  "types": "./compare.d.ts",
+  "exports": {
+    ".": {
+      "types": "./compare.d.ts",
+      "default": "./compare.js"
+    },
+    "./compare.js": {
+      "types": "./compare.d.ts",
+      "default": "./compare.js"
+    },
+    "./names.js": {
+      "types": "./names.d.ts",
+      "default": "./names.js"
+    },
+    "./pretty.js": {
+      "types": "./pretty.d.ts",
+      "default": "./pretty.js"
+    }
+  },
+  "imports": {
+    "#same-bytes": {
+      "node": "./src/same-bytes.node.js",
+      "default": "./src/same-bytes.js"
+    },
+    "#oxc": {
+      "node": "./src/oxc.node.js",
+      "default": "./src/oxc.js"
+    }
+  },
+  "files": [
+    "LICENSE-APACHE",
+    "LICENSE-MIT",
+    "compare.d.ts",
+    "compare.js",
+    "names.d.ts",
+    "names.js",
+    "pretty.d.ts",
+    "pretty.js",
+    "src/blocks.js",
+    "src/changes.js",
+    "src/css.js",
+    "src/error.js",
+    "src/layout.js",
+    "src/marked.js",
+    "src/names/analyze.js",
+    "src/names/binds.js",
+    "src/names/check.js",
+    "src/names/diff.js",
+    "src/names/misread.js",
+    "src/names/pairing.js",
+    "src/names/rename.js",
+    "src/names/syntax.js",
+    "src/oxc.js",
+    "src/oxc.node.js",
+    "src/patch.js",
+    "src/pairs.js",
+    "src/paths.js",
+    "src/peers.js",
+    "src/pretty.js",
+    "src/quote.js",
+    "src/renames.js",
+    "src/same-bytes.js",
+    "src/same-bytes.node.js",
+    "src/script.js",
+    "src/similarity.js",
+    "src/text.js",
+    "src/tree.js",
+    "src/whitespace.js",
+    "src/words.js"
+  ],
+  "engines": {
+    "node": ">=24.14.0"
+  },
+  "scripts": {
+    "test": "node --test ./tests/*.test.js"
+  },
+  "license": "MIT OR Apache-2.0",
+  "author": {
+    "name": "Nikita Skovoroda",
+    "email": "chalkerx@gmail.com",
+    "url": "https://github.com/ChALkeR"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PreventiveMeasures/libraries.git",
+    "directory": "compare"
+  },
+  "bugs": {
+    "url": "https://github.com/PreventiveMeasures/libraries/issues"
+  },
+  "homepage": "https://github.com/PreventiveMeasures/libraries/tree/main/compare",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@exodus/bytes": "^1.16.0",
+    "@preventive/diff": "^1.0.2"
+  },
+  "peerDependencies": {
+    "css-tree": ">=3.2.1",
+    "oxc-minify": ">=0.152.0",
+    "oxc-parser": ">=0.152.0",
+    "oxfmt": ">=0.72.0"
+  },
+  "peerDependenciesMeta": {
+    "css-tree": {
+      "optional": true
+    },
+    "oxc-minify": {
+      "optional": true
+    },
+    "oxc-parser": {
+      "optional": true
+    },
+    "oxfmt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@preventive/archive": "workspace:*",
+    "@preventive/vfs": "workspace:*",
+    "css-tree": "^3.2.1",
+    "oxc-minify": "^0.152.0",
+    "oxc-parser": "^0.152.0",
+    "oxfmt": "^0.72.0"
+  }
+}

package/pretty.d.ts

@@ -0,0 +1,14 @@
+// `text` formatted by oxfmt as a file with `extension`, changing what is written
+// no more than layout needs (keys keep their quotes, no trailing commas or arrow
+// parentheses are added, template literals stay), the copy used only where checks
+// of oxfmt's output, apart from oxfmt, find it changes the layout alone:
+// - a script's (`js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, `tsx`) syntax tree as
+//   oxc parses it, its comments and its text;
+// - a style sheet's (`css`) tree as css-tree, an optional peer, parses it, but for
+//   the case of what CSS reads in any case and zeros in a number that change neither
+//   its value nor its type (`.50` as `0.5`, but not `1.0` as `1`, an integer);
+// - JSON's strings and comments as written.
+// Otherwise an error: no check for the kind of file (`unsupported`, CSS without
+// css-tree), it does not parse (`unformattable`) or would change more
+// (`pretty-mismatch`). Rejects only where the optional oxfmt peer is missing.
+export function format(text: string, extension: string): Promise<{ code: string } | { error: 'unsupported' | 'unformattable' | 'pretty-mismatch' }>

package/pretty.js

@@ -0,0 +1,4 @@
+// Minified code formatted for reading, its copy checked to differ from the
+// file in layout alone. oxfmt formats, oxc-parser and css-tree check: optional
+// peers loaded on first use. Typed and described in pretty.d.ts.
+export { format } from './src/pretty.js'