@rudra-js/attested 0.0.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clive Dsouza
+
+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

@@ -1,8 +1,355 @@
 # @rudra-js/attested
 
-This `0.0.0` is a placeholder. npm can only attach a trusted publisher to a
-package that already exists, so this version exists to create the name.
+Checks model-written product copy against the facts a shop stands behind.
 
-Install `0.4.0` or later, which is published from CI with provenance.
+Zero dependencies, no node builtins, no I/O. It is one pure function over text
+and facts, so it runs in Node, in an edge runtime and in a browser, and it drops
+in after anything that writes copy — json-render, the Vercel AI SDK, a raw
+`fetch` to a model, your own template.
 
-See [the repository](https://github.com/clivedsouza1010/rudra-js/tree/main/packages/attested#readme).
+## The guarantee
+
+**When `quantity.supported` is true, every numeral in the text is one you
+supplied — and a numeral the reader cannot read counts as a failure, not a
+pass.**
+
+That is the whole promise, and it is a promise about numerals, not about
+sentences. It does not say the sentence around the number is true: a price you
+supplied can still be written as a sales figure. It says nothing at all about
+`wording.supported`, which is a denylist over an open set and carries
+`strength: 'best-effort'` on every result for that reason.
+
+Everything the guarantee leaves open is listed under
+[What it cannot catch](#what-it-cannot-catch). Nothing there is a bug queued for
+later; it is the shape of what a closed check over digits can promise.
+
+## Install
+
+```sh
+npm install @rudra-js/attested
+```
+
+```ts
+import { verify } from '@rudra-js/attested';
+
+const result = verify('Only 2 left at $39', { values: [39, 'SKU TR-101'] });
+
+result.supported; // false
+result.quantity.findings;
+// [{ layer: 'quantity', token: '2', reason: 'quantity: "2" is not a value the supplied facts carry' }]
+```
+
+## The two layers
+
+They are checked separately and reported separately, because only one of them is
+a proof.
+
+### Layer one — quantities. This is the provable half.
+
+Every run of digits in the text has to be a value you supplied. Not "does this
+read like a bad phrase" but "is this number one the shop stands behind". The set
+of digits in a string is closed and checkable, and it does not care what
+language the sentence is in.
+
+```ts
+verify('Nur noch 2 übrig', { values: [39] }).quantity.supported; // false
+verify('4,8 von 5', { values: [4.8, 5] }).quantity.supported; // true
+```
+
+It is crude on purpose and it errs toward rejection. `"Only 2 left"` is
+unsupported unless you supplied a fact carrying 2, even though 2 is also the
+number of colourways. A false rejection costs a duller sentence; a false
+acceptance costs a fabricated claim.
+
+**What it reads.** Bare integers and decimals, both decimal separators (`4.8`
+and `4,8`), currency symbols attached or detached, percentages, and any Unicode
+decimal digit — Eastern Arabic `٤٫٨`, Devanagari `४.८` and mathematical `𝟰.𝟴`
+all read as 4.8. Grouping is read in the Western (`12,345,678`), Indian
+(`1,29,999`), space (`1 299`, including the no-break and narrow no-break spaces)
+and Swiss (`1'299`) shapes.
+
+**How an ambiguous mark is decided.** One dot or comma with exactly three digits
+behind it is grouping, never a decimal point. `1,299` and `1.299` both read as
+1299 and nothing else, which is why a rating of 4.8 cannot stand behind a
+written `4.800` and a stock count of 12 cannot stand behind `12.000`. Where
+grouping is impossible the decimal reading survives, so `1234,567` is still
+1234.567. Where the two marks differ the last one is the decimal point, so
+`1.299,50` is 1299.5.
+
+**What it refuses to read.** Three things become findings rather than passes:
+
+- A numeric character that is not a decimal digit — `½`, `²`, `②`, `Ⅲ`. These
+  render as numbers and carry a value the reader has no way to check.
+- A magnitude mark glued to a run — `4.8万`, `12M`, `4.8k`. The digits may be
+  yours; the multiplier is not.
+- A run no locale reads as a number — `24.12.2026`, `3.14.15`. These are
+  supported only by a fact written exactly the same way.
+
+Characters that take no room on the page are dropped before any of this, so a
+zero-width space, a soft hyphen, a variation selector, a backspace or a
+combining overline cannot split `213` into a `2` and a `13` that happen to be
+supported separately. That class is every format character, every
+default-ignorable code point, every control character and every mark that hangs
+on the character before it — a rule over the whole of Unicode rather than a list
+someone kept up to date.
+
+A character that does take room still separates two numbers. A tab, a line break
+and a Devanagari matra all leave a gap the shopper can see, so `"Only 2\n3 left"`
+is two numbers and a fact of 23 does not stand behind it.
+
+### Layer two — wording. This is the best-effort half.
+
+Claims with no number in them: "cheap", "bargain", "on sale", "best-selling",
+"selling fast", "in stock", "free delivery". There is no value to check, so
+there is nothing to invert. It stays a denylist, it stays open and
+English-first, and every result it produces says so:
+
+```ts
+verify('Selling fast', { values: [] }).wording;
+// { supported: false, strength: 'best-effort', checked: 81, findings: [...] }
+```
+
+Add your own for your own language, and name the wording you stand behind:
+
+```ts
+verify('Nur noch wenige', { values: [], bannedPhrases: ['nur noch'] });
+verify('In stock, ships today', { values: [], allowedPhrases: ['in stock'] });
+```
+
+`bannedPhrases` is added to the built-in list. `allowedPhrases` works on the
+text, not on the list: **where one of your phrases appears, a banned claim
+sitting wholly inside it is not reported, and the same words elsewhere in the
+copy still are.** So `['back in stock']` clears `"Back in stock"` and still
+catches the `in stock` in `"Only 2 in stock, selling fast"`. `checked` is the
+whole list either way, because nothing leaves it.
+
+Without an allowance a denylist bans the truthful disclosure as hard as the
+fabricated one, and a shop that genuinely offers free shipping cannot say so.
+Three things are worth knowing before you write one:
+
+- **Containment runs one way.** Allowing `in stock` does not clear
+  `back in stock`, which claims a restock on top of it.
+- **Allowances do not compose, and they do not join.**
+  `['sold', 'out']` leaves `sold out` caught, and `['back in', 'stock']` leaves
+  both `in stock` and `back in stock` caught.
+- **An allowance forgives whatever nests inside it, including entries added in a
+  later version.** `['in stock and ready to ship']` forgives nothing extra
+  today; the day `ready to ship` joins the list, that allowance silences it
+  wherever your sentence appears. Keep them tight.
+- **An allowance does not cross a line break.** The denylist reads straight
+  through one, so `"Free\n\nshipping"` is still caught, but an allowance will
+  not bridge it. The model picks where the paragraph breaks fall, and
+  `"We do not offer"` above a horizontal rule, with the free shipping claim
+  below it, is two things a shopper reads apart. The two rules pull opposite
+  ways on purpose: the denylist catches more, the allowance forgives less, and
+  both err toward reporting.
+
+It is also the way around negation. The list matches substrings, so
+`"there is no sale on this product"` reads as a sale claim; allow `no sale` and
+that sentence passes while a `sale` later in the same text still fails.
+
+Matching is case-insensitive. Hyphens become spaces, accents are composed,
+fullwidth forms are folded, characters that take no room are dropped, and a
+handful of Cyrillic and Greek letters that render as Latin ones are folded to
+Latin. Accents are composed before anything is dropped, so `café` keeps its `é`
+while an overline, which composes with nothing, cannot hide `free` from its own
+entry. A line break stays a line break: matching reads through it, and only an
+allowance refuses to cross it. Spaces are dropped from both sides before
+matching, so `送料 無料` still
+reads as `送料無料`. A phrase whose first or last character is an ASCII letter or
+digit will not match glued inside a longer word, so `cheap` misses `cheapskate`,
+but a trailing `s` is allowed, so `discount` catches `discounts`.
+
+## The result
+
+```ts
+interface VerifyResult {
+  supported: boolean; // both layers
+  quantity: LayerReport;
+  wording: LayerReport;
+}
+
+interface LayerReport {
+  supported: boolean;
+  strength: 'proof' | 'best-effort';
+  checked: number; // numerals found, or phrases screened against
+  findings: Finding[]; // one per distinct token that failed
+}
+
+interface Finding {
+  layer: 'quantity' | 'wording';
+  token: string; // the numeral as the text wrote it, or the phrase
+  reason: string; // audit evidence, naming the layer and the token
+}
+```
+
+`checked` says how much the layer actually looked at. `quantity.checked === 0`
+means the text held no numeral and layer one proved nothing about it — which is
+the honest reading of `"Only two left"`, and no assertion you can write on the
+result will turn that into a catch. Layer one counts the numerals it refuses to
+read, so `"Only ② left"` is a finding rather than a silent zero.
+
+## Facts
+
+```ts
+interface Facts {
+  values: readonly (string | number | bigint)[];
+  bannedPhrases?: readonly string[];
+  allowedPhrases?: readonly string[];
+}
+```
+
+`values` is a flat list, not a typed one. Write them however they are written in
+your own system — `39`, `'$1,299.00'`, `'4,8'`, `'ships 13 March'` — and every
+numeral in each one becomes a supported value.
+
+A number is laid out in positional notation first, whatever `String` would have
+made of it, so a fact of `1e21` stands behind
+`'1,000,000,000,000,000,000,000'` and behind neither `1` nor `21`. A string
+whose whole content is a number in exponent notation is laid out the same way:
+`String`, `JSON.stringify`, a spreadsheet export and an API that writes 64-bit
+values as strings all produce one, and none of those is you choosing the digits.
+Any other string is read exactly as you typed it, so `'SKU AX-220e5'` still
+mints 220 and 5.
+
+Past 2^53 a number has lost its exact digits before it ever reaches here —
+`JSON.parse` turns `9007199254740993` into `...92` — so hand a long id over as a
+bigint or as a string. A value that is none of the three stands behind no
+numeral rather than throwing, so one null field does not take the whole call
+down.
+
+Flat rather than typed (money, count, rating, date) because typing only helps if
+the extractor can classify a token in the text, and it cannot. The `2` in
+`"Only 2 left"` and the `2` in `"2 year warranty"` are the same two characters;
+telling them apart means understanding the sentence, in whatever language it was
+written, which is the problem this package exists to stop relying on. Typed
+facts would also need an "unclassified, so skip it" branch, and that branch is a
+hole. A flat set has no hole: every numeral is checked against every value.
+
+The cost is real and it is stated under **What it cannot catch**. Two things
+follow from it that are worth doing:
+
+- **Supply only numbers you are happy to see anywhere.** A SKU of `AT-2199` in
+  `values` makes `"Was $2,199"` a supported sentence. A listing date makes its
+  day number a supported sales figure. If a number in your record is not a fact
+  about the product a shopper would read, leave it out.
+- **`values` is a trust boundary.** On a marketplace the product title is
+  written by the seller, not by you. Putting it in `values` hands the model
+  every number the seller chose to type. Supply fields you author.
+
+## Many fields, one product
+
+```ts
+import { verifyFields } from '@rudra-js/attested';
+
+const result = verifyFields(
+  { headline: 'Yours for $39', badge: 'Only 2 left', body: 'Built for long days' },
+  { values: [39] },
+);
+
+result.supported; // false
+result.fields; // [{ field, result }, ...] in the order the fields were given
+result.acrossFields; // the wording layer over every field read as one
+```
+
+The facts are read once and reused. A card renders its fields next to each
+other, and the model picks the field boundaries, so
+`{ badge: 'Free', delivery: 'delivery on every order' }` is one sentence to a
+shopper while neither field carries it alone. `acrossFields` reads the joined
+text and counts toward `supported`.
+
+## What it cannot catch
+
+This is the honest list.
+
+### Claims with a number in them
+
+- **A number that is real but means something else.** This is the largest hole
+  in the provable half. A flat fact set proves the number came from you, not
+  that the sentence uses it correctly. Supply a price of 39 and `"39 sold in the
+last hour"`, `"Save $39 today"` and `"Under $39"` all pass. Supply a rating
+  scale of 5 and `"Only 5 left"` passes. Supply a rating of 4.8 and a German
+  `"nur 4,80 €"` passes as a price, because 4.80 and 4.8 are one number.
+- **Numbers written as words, in any script.** `"Only two left"` has no digit in
+  it, so layer one never sees it. Neither does `残り二点`, where 二 is a
+  character rather than a digit, nor Arabic `قطعتين`, where "two" is the noun's
+  dual ending and there is no numeral at all. `quantity.checked` is 0 for all
+  three, and that is the only signal you get.
+- **Magnitudes written as words.** `4.8万` and `12M` are caught. `4,8 Millionen`,
+  `4.8 millions`, `4,8 mil`, `4.8 लाख` and `٤٫٨ مليون` are not — a word list is
+  the denylist this package exists to get away from.
+- **The unit on the number.** `￥39.99` against a price of $39.99 passes: the
+  digits are yours and the currency symbol is not a digit. So does
+  `"39,99 Cent"`. Layer one checks the number, never what it is a number of.
+- **A number your facts happen to contain.** A fact of `'2026-09-13'` makes
+  2026, 9 and 13 supported everywhere in the text, including as a stock count.
+- **Where in the text a token was.** A finding names the token, not its offset.
+
+### Claims with no number in them
+
+- **Wording, in general.** Layer two is a denylist over an infinite set. A
+  careful rewording gets past it — `"Half of what it was"` for half price,
+  `"送料は無料"` with a particle dropped in. Entries are added as they are found,
+  and the list will never be finished.
+- **Your language, until you give it one.** Every built-in phrase is English.
+  `"Gratis Versand"`, `"Livraison offerte"` and `"شحن مجاني"` all pass by
+  default. `bannedPhrases` is the answer, and it is your list to keep.
+- **Negation.** The list matches substrings, so `"there is no sale on this
+product"` is caught as a sale claim on its own. There is no rule that reads the
+  `no`; `allowedPhrases: ['no sale']` is the way out, and it is narrow by
+  design — a `sale` elsewhere in the same text still fails.
+- **A character that folds into your allowance.** An allowance is matched
+  against normalised copy, so anything that folds to those words counts as those
+  words. Allow `no sale` and `"№ SALE"` passes, because U+2116 folds to `no`;
+  a superscript `ⁿᵒ` does the same. The shopper reads the numero sign as
+  decoration and the verifier reads it as a word. Keep allowances tight and
+  written the way a shop really writes them.
+- **A letter glued to the end of a phrase.** `"FREE SHIPPINGᵃ see terms"` is not
+  reported. The superscript folds to an `a`, which glues to `shipping`, and the
+  word-gap rule that stops `cheap` matching `cheapskate` then treats the whole
+  thing as a longer word. It holds for every entry on the list, and a footnote
+  marker is exactly how a real shop writes one.
+
+### Preconditions the package cannot check for you
+
+- **The text you check has to be the text you render.** `verify` sees a string.
+  If anything downstream decodes it — an HTML sink turning `½` into ½, or
+  `2` into a 2 — then the string that was checked and the string on the page
+  are different documents, and the guarantee covers the first one.
+- **The font has to agree with Unicode about what renders as nothing.** The
+  layer drops what Unicode marks as taking no room. Where a font gives one of
+  those a visible glyph the two disagree, and U+3164 HANGUL FILLER is the one
+  people really paste as a blank: the layer reads `"1<U+3164>3"` as 13, and a
+  font that widens it shows the shopper `1 3`.
+- **Everything that is not a number or a phrase.** A claim about materials,
+  compatibility, a certification, a warranty condition or a person is entirely
+  out of scope.
+
+## What it over-rejects
+
+The guarantee errs toward rejection, and that has a bill:
+
+- **Every incidental number has to be in `values`.** A VAT rate, a size, a care
+  temperature, a spec number, a support phone number, a founding year, the
+  denominator of a rating scale. None of them are claims, all of them are
+  digits, and copy mentioning one you did not supply is rejected.
+- **A three-digit tail is always grouping.** `1.299 kg` reads as 1299, so a
+  genuine three-decimal number — a weight, or a price in a currency with three
+  decimal places — cannot be written with a dot or a comma. Supply it, and write
+  it, the same way.
+- **Numeric characters that are not digits are refused outright.** `2 m²` and
+  `½ inch` fail, along with the `②` and `Ⅲ` the rule is there to stop.
+- **A magnitude letter glued to a digit is refused.** `4K display` fails.
+  `4 K display` and `1kg` do not, because a letter followed by another letter is
+  a unit, not a multiplier.
+- **A run no locale reads as a number needs its exact spelling.** `24.12.2026`
+  is supported by a fact of `'24.12.2026'` and by nothing else.
+- **Scientific notation in the copy is unsupported by construction.** A fact of
+  `1e-7` is laid out as `0.0000001`, and the text `"1e-7 g"` reads as the two
+  numerals 1 and 7, so the two never meet. `"0.0000001 g"` passes. This is the
+  bill for laying facts out positionally, and a lab or bulk-goods shop that
+  prints the value the way its own data prints it pays it.
+
+## Licence
+
+MIT

package/dist/hidden.d.ts

@@ -0,0 +1,3 @@
+export declare function stripInvisible(text: string): string;
+export declare function stripMarks(text: string): string;
+//# sourceMappingURL=hidden.d.ts.map

package/dist/hidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden.d.ts","sourceRoot":"","sources":["../src/hidden.ts"],"names":[],"mappings":"AAmBA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE/C"}

package/dist/hidden.js

@@ -0,0 +1,22 @@
+// One definition for both layers. It lived in two files, and that is why widening it
+// for the quantity layer left the wording layer open twice running.
+/**
+ * Characters that render as nothing: format characters, default-ignorable code points
+ * and the controls. Cf and Default_Ignorable each hold characters the other does not.
+ */
+const INVISIBLE = /[\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cc}]/gu;
+/** The controls that do take room. Deleting these would read `Only 2\n3 left` as 23. */
+const SPACING = /[\t\n\v\f\r\u0085]/;
+/**
+ * Marks that hang on the character before them instead of taking a column of their own,
+ * so `4<U+0305>9` reads as 49. Spacing marks (Mc) are not here: a Devanagari matra is
+ * a visible gap between two digits and separates them for a reader.
+ */
+const MARKS = /[\p{Mn}\p{Me}]/gu;
+export function stripInvisible(text) {
+    return text.replace(INVISIBLE, (char) => (SPACING.test(char) ? char : ''));
+}
+export function stripMarks(text) {
+    return text.replace(MARKS, '');
+}
+//# sourceMappingURL=hidden.js.map

package/dist/hidden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden.js","sourceRoot":"","sources":["../src/hidden.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,oEAAoE;AAEpE;;;GAGG;AACH,MAAM,SAAS,GAAG,kDAAkD,CAAC;AAErE,wFAAwF;AACxF,MAAM,OAAO,GAAG,oBAAoB,CAAC;AAErC;;;;GAIG;AACH,MAAM,KAAK,GAAG,kBAAkB,CAAC;AAEjC,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { verify, verifyFields, type BatchResult, type Facts, type FieldResult, type Finding, type Layer, type LayerReport, type VerifyResult, } from './verify.js';
+export { BANNED_PHRASES } from './phrases.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,MAAM,EACN,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// @rudra-js/attested — the guarantee that a model cannot lie about a product.
+export { verify, verifyFields, } from './verify.js';
+export { BANNED_PHRASES } from './phrases.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAE9E,OAAO,EACL,MAAM,EACN,YAAY,GAQb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/numerals.d.ts

@@ -0,0 +1,12 @@
+export interface Numeral {
+    /** The run exactly as it appears in the text. */
+    token: string;
+    /** Every reading of that run, canonical. Empty when the layer cannot read the run. */
+    forms: string[];
+    /** `digits` is a run this layer reads. The other two it cannot read at all. */
+    kind: 'digits' | 'magnitude' | 'other-numeral';
+}
+export declare function numeralsIn(text: string): Numeral[];
+/** Every reading of every numeral the host stands behind. */
+export declare function supportedValues(values: readonly (string | number | bigint)[]): Set<string>;
+//# sourceMappingURL=numerals.d.ts.map

package/dist/numerals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"numerals.d.ts","sourceRoot":"","sources":["../src/numerals.ts"],"names":[],"mappings":"AA2BA,MAAM,WAAW,OAAO;IACtB,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,IAAI,EAAE,QAAQ,GAAG,WAAW,GAAG,eAAe,CAAC;CAChD;AAoJD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAIlD;AAmCD,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAQ1F"}

package/dist/numerals.js

@@ -0,0 +1,205 @@
+// Everything here is string work. No float ever holds a value, so a twenty-digit
+// order number compares exactly.
+import { stripInvisible, stripMarks } from './hidden.js';
+/** A dot or a comma. Either mark is a decimal point in one locale and grouping in another. */
+const AMBIGUOUS = '.,';
+/** The Arabic decimal separator, which is never grouping. */
+const DECIMAL_ONLY = '\u066b';
+/** Marks that are only ever grouping: Arabic thousands, the space family, the apostrophe. */
+const GROUPING_ONLY = '\u066c\u0020\u00a0\u2007\u2008\u2009\u202f\u0027\u2019';
+const SEPARATORS = AMBIGUOUS + DECIMAL_ONLY + GROUPING_ONLY;
+const RUN = `\\p{Nd}+(?:[${SEPARATORS}]\\p{Nd}+)*`;
+/** Marks that multiply the digits in front of them: 万 億 兆, and the k/M/B of English copy. */
+const MAGNITUDE = '(?:[十百千万萬億亿兆]|[kKMB](?!\\p{L}))';
+/** Numeric characters that are not decimal digits: ½ ² ② Ⅲ. */
+const OTHER_NUMERAL = '[\\p{No}\\p{Nl}]+';
+const SCAN = new RegExp(`${RUN}${MAGNITUDE}|${RUN}|${OTHER_NUMERAL}`, 'gu');
+const LOOSE = new RegExp(`[${GROUPING_ONLY}]`, 'u');
+const IS_DIGIT = /^\p{Nd}$/u;
+const STARTS_DIGIT = /^\p{Nd}/u;
+const ENDS_DIGIT = /\p{Nd}$/u;
+const zeros = new Map();
+/**
+ * Unicode writes decimal digits in complete sets of ten, and adjacent sets abut, so
+ * the start of a maximal run of digit code points is a zero and the offset into that
+ * run, modulo ten, is the value. Walking back without that modulo reads every digit
+ * of the second and later sets in the maths block as a nine.
+ */
+function digitValue(char) {
+    const code = char.codePointAt(0) ?? 0;
+    let zero = zeros.get(code);
+    if (zero === undefined) {
+        zero = code;
+        while (zero > 0 && IS_DIGIT.test(String.fromCodePoint(zero - 1)))
+            zero -= 1;
+        zeros.set(code, zero);
+    }
+    return (code - zero) % 10;
+}
+function toAscii(token) {
+    let out = '';
+    for (const char of token) {
+        out += SEPARATORS.includes(char) ? char : String(digitValue(char));
+    }
+    return out;
+}
+/** Strips the zeros that carry no value, so 39.00 and 39 are one string. */
+function canonical(whole, fraction) {
+    let start = 0;
+    while (start < whole.length - 1 && whole[start] === '0')
+        start += 1;
+    let end = fraction.length;
+    while (end > 0 && fraction[end - 1] === '0')
+        end -= 1;
+    const head = whole.slice(start);
+    const tail = fraction.slice(0, end);
+    return tail.length === 0 ? head : `${head}.${tail}`;
+}
+/** Whether these runs read as one grouped whole number: 12,345,678 or 1,29,999. */
+function isGrouping(groups) {
+    if (groups.length === 1)
+        return true;
+    if ((groups[groups.length - 1] ?? '').length !== 3)
+        return false;
+    let three = true;
+    let two = true;
+    for (let index = 1; index < groups.length - 1; index += 1) {
+        const size = (groups[index] ?? '').length;
+        if (size !== 3)
+            three = false;
+        if (size !== 2)
+            two = false;
+    }
+    const lead = (groups[0] ?? '').length;
+    if (three)
+        return lead >= 1 && lead <= 3;
+    // 1,29,999 — the Indian grouping, two digits at a time above the last three.
+    if (two)
+        return lead >= 1 && lead <= 2;
+    return false;
+}
+/** Whether every mark is the same one, and every one of them can be grouping. */
+function allGrouping(separators) {
+    for (const separator of separators) {
+        if (separator !== separators[0])
+            return false;
+        if (DECIMAL_ONLY.includes(separator))
+            return false;
+    }
+    return true;
+}
+/** `1,299` is 1299 in London and in Berlin. `1234,567` is a decimal in both. */
+function formsOf(token) {
+    const ascii = toAscii(token);
+    const groups = [];
+    const separators = [];
+    let current = '';
+    for (const char of ascii) {
+        if (SEPARATORS.includes(char)) {
+            groups.push(current);
+            separators.push(char);
+            current = '';
+        }
+        else {
+            current += char;
+        }
+    }
+    groups.push(current);
+    if (separators.length === 0)
+        return [canonical(groups[0] ?? '', '')];
+    const forms = [];
+    if (allGrouping(separators) && isGrouping(groups))
+        forms.push(canonical(groups.join(''), ''));
+    const whole = groups.slice(0, -1);
+    const leading = separators.slice(0, -1);
+    const point = separators[separators.length - 1] ?? '';
+    const fraction = groups[groups.length - 1] ?? '';
+    // One dot or comma with exactly three digits behind it is grouping wherever it is
+    // written, so `4.800` is four thousand eight hundred and never the rating 4.8.
+    const groupingWins = forms.length > 0 && leading.length === 0 && fraction.length === 3;
+    if (!groupingWins &&
+        !GROUPING_ONLY.includes(point) &&
+        allGrouping(leading) &&
+        leading[0] !== point &&
+        isGrouping(whole)) {
+        forms.push(canonical(whole.join(''), fraction));
+    }
+    return forms;
+}
+function collect(found, token) {
+    if (!STARTS_DIGIT.test(token)) {
+        found.push({ token, forms: [], kind: 'other-numeral' });
+        return;
+    }
+    if (!ENDS_DIGIT.test(token)) {
+        found.push({ token, forms: [], kind: 'magnitude' });
+        return;
+    }
+    const forms = formsOf(token);
+    if (forms.length > 0) {
+        found.push({ token, forms, kind: 'digits' });
+        return;
+    }
+    // `8 10 12` is three numbers, not one badly grouped one.
+    if (LOOSE.test(token)) {
+        for (const part of token.split(LOOSE)) {
+            if (part.length > 0)
+                collect(found, part);
+        }
+        return;
+    }
+    // No locale reads `24.12.2026` as a number, so only a fact written the same way
+    // stands behind it. The raw run carries a mark, and a reading never does, so it
+    // can never be mistaken for one.
+    found.push({ token, forms: [toAscii(token)], kind: 'digits' });
+}
+export function numeralsIn(text) {
+    const found = [];
+    for (const match of stripMarks(stripInvisible(text)).matchAll(SCAN))
+        collect(found, match[0]);
+    return found;
+}
+/** A whole fact in exponent notation and nothing else, so expanding it swallows no prose. */
+const BARE_EXPONENT = /^[+-]?\d+(?:\.\d+)?[eE][+-]?\d+$/;
+/** `String(1e21)` is `1e+21`, which reads as the two numerals 1 and 21. Lay the same digits out in place. */
+function positional(written) {
+    const marker = written.search(/[eE]/);
+    if (marker < 0)
+        return written;
+    const power = Number(written.slice(marker + 1));
+    // The sign never reaches a numeral, so dropping it here mints no digit the host lacks.
+    const body = written.slice(0, marker).replace(/^[+-]/, '');
+    const point = body.indexOf('.');
+    const digits = point < 0 ? body : body.slice(0, point) + body.slice(point + 1);
+    const place = (point < 0 ? body.length : point) + power;
+    if (place <= 0)
+        return `0.${'0'.repeat(-place)}${digits}`;
+    if (place >= digits.length)
+        return `${digits}${'0'.repeat(place - digits.length)}`;
+    return `${digits.slice(0, place)}.${digits.slice(place)}`;
+}
+/**
+ * A string fact is read as the host typed it, except when the whole of it is a number
+ * in exponent notation: `String`, `JSON.stringify`, a CSV export and an API that writes
+ * 64-bit values as strings all produce that, and none of them is the host choosing digits.
+ */
+function digitsOf(value) {
+    if (typeof value === 'number')
+        return positional(String(value));
+    if (typeof value !== 'string')
+        return String(value);
+    const trimmed = value.trim();
+    return BARE_EXPONENT.test(trimmed) ? positional(trimmed) : value;
+}
+/** Every reading of every numeral the host stands behind. */
+export function supportedValues(values) {
+    const supported = new Set();
+    for (const value of values) {
+        for (const numeral of numeralsIn(digitsOf(value))) {
+            for (const form of numeral.forms)
+                supported.add(form);
+        }
+    }
+    return supported;
+}
+//# sourceMappingURL=numerals.js.map