aontu 0.55.0 → 0.56.0

package/src/hints.ts

@@ -192,6 +192,8 @@ const hints: Record<string, string> = {
   view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
 
   view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
+
+  format_check: 'The formatted text is not the same document, so nothing was written.\nThis is a formatter defect: please report it, with the source.',
   view_style_profile: 'Each profile has ONE way to carry the meaning of a figure\'s marks:\nSGR escapes for text, CSS classes for svg. Asking for the other one is\na usage error rather than a silent no-op. `none` works everywhere.',
   view_style_unknown: 'The styles are none, ansi and css, plus `auto` at the command line,\nwhich the command resolves before the library runs: whether the\ndestination is a terminal is not something a library can see.',
 
@@ -513,6 +515,9 @@ const codeClasses: Record<string, string> = {
   view_profile_unknown: 'reference',
   view_style_profile: 'reference',
   view_style_unknown: 'reference',
+  // The formatter's self-check (docs/design/FMT.0.md): a report-layer
+  // code, class internal -- the formatter, not the document, is wrong.
+  format_check: 'internal',
   view_rows_exceeded: 'budget',
   view_line_break: 'parse',
   view_relation_ambiguous: 'reference',

package/src/jsonschema.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // JSON SCHEMA EXPORT (the review's finding I / SUPPORT.md act 2).
 //
@@ -75,6 +76,11 @@ export type SchemaOptions = {
   // its own directory.
   path?: string
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 
@@ -501,7 +507,7 @@ function fromList(ctx: Ctx, path: string[], v: any): any {
 // The verb. Evaluate, anchor, walk, report.
 export function jsonSchema(src: string, options?: SchemaOptions): SchemaReport {
   const opts = options ?? {}
-  const aontu = new Aontu(null == opts.trust ? {} : { trust: opts.trust })
+  const aontu = new Aontu(includeOpts(opts))
 
   // COLLECT MODE, so a syntax error arrives on the context rather than
   // as a throw -- the same failure Go's `parseEntry` hands back as an

package/src/lang.ts

@@ -1597,6 +1597,14 @@ help isolate the syntax error.`,
 // references, constraints, its own includes. Two extensions, and they
 // are the ones this project owns.
 //
+// `text` — the file's BYTES, as one string scalar. No parser is
+// chosen, so there is nothing for two ports to disagree about and
+// nothing in the file that can mean anything: `notes: @"notes.txt"`
+// is a document loading prose into a string. `.txt` is the only
+// extension here by default; `AontuOptions.textExt` (the CLI's
+// `--text-ext`) adds others, because which name a project keeps its
+// templates under is the project's business, not this table's.
+//
 // A FORMAT NAME — configuration DATA, parsed by that format's own
 // parser into the JSON value it denotes, which then becomes Aontu
 // values like any other data. Every one of these formats maps onto
@@ -1628,8 +1636,43 @@ const INCLUDE_KINDS: { [kind: string]: string } = {
   yaml: 'yaml',
   yml: 'yaml',
   ini: 'ini',
+
+  txt: 'text',
+}
+
+
+// WHAT AN EXTENSION MEANS, for this parse. The table is the fixed
+// part; `textExt` is the per-parse widening, and it wins over nothing
+// -- a host cannot re-read `.toml` as text, because an extension the
+// table already names has a meaning documents rely on. Undefined is
+// the refusal, and it is the ONE place that decides it: the resolver's
+// gate and the processor map both ask here, so a widening cannot reach
+// one and not the other.
+function includeFormat(
+  ext: string, textExt?: string[]): string | undefined {
+  const known = INCLUDE_KINDS[ext]
+  if (undefined !== known) {
+    return known
+  }
+  // NOT EVEN AS TEXT. `.js` is the extension ADR-012 singles out
+  // because multisource's own default EXECUTES it, and an extension
+  // this project refuses on purpose stays refused however a flag is
+  // spelled -- reading it is harmless, but a widening that can reach
+  // the one name the rule names is a widening whose limit nobody can
+  // state. Go's includeFormat holds the same list, and the two CLIs
+  // are diffed on `--text-ext js` because they once disagreed here.
+  if (REFUSED_EXT.has(ext)) {
+    return undefined
+  }
+  return textExt?.includes(ext) ? 'text' : undefined
 }
 
+
+// Extensions no widening may reach. `js` executes under multisource's
+// default processor; `''` is the no-extension fallback, which names no
+// file type at all.
+const REFUSED_EXT = new Set(['js', ''])
+
 // `.csv` IS DELIBERATELY ABSENT, and the reason is ADR-001 rather than
 // taste. The two ports' CSV parsers disagree about what a CSV file IS:
 // one answers header-keyed records with string fields, the other raw
@@ -1754,13 +1797,20 @@ const dataProcessor = (format: string) => (res: any) => {
   res.val = rawToVal(DATA_READERS[format](res.src, res.path))
 }
 
+// TEXT IS NOT PARSED. The bytes multisource read are the value, so
+// this is the one processor with no reader behind it -- which is why
+// a `.txt` include cannot fail on content, only on being unreadable.
+const textProcessor = (res: any) => {
+  res.val = new StringVal({ peg: res.src })
+}
+
 /**
  * The multisource processor map, built FROM the include table so the
  * two cannot drift: every extension the table names gets the reader
  * the table names for it, and the two kinds that are not in the table
  * refuse.
  */
-function includeProcessors(): { [kind: string]: any } {
+function includeProcessors(textExt?: string[]): { [kind: string]: any } {
   const map: { [kind: string]: any } = {
     // multisource's fallback for an extension no entry names, so it is
     // the one that catches whatever the resolver's gate did not.
@@ -1769,9 +1819,23 @@ function includeProcessors(): { [kind: string]: any } {
     js: refuseProcessor,
   }
   const source = makeJsonicProcessor()
+  const forKind = (kind: string) => {
+    const format = includeFormat(kind, textExt)
+    if ('source' === format) return source
+    if ('text' === format) return textProcessor
+    return dataProcessor(format as string)
+  }
   for (const kind of Object.keys(INCLUDE_KINDS)) {
-    const format = INCLUDE_KINDS[kind]
-    map[kind] = 'source' === format ? source : dataProcessor(format)
+    map[kind] = forKind(kind)
+  }
+  // A WIDENING NEVER OVERWRITES. `js` and the empty fallback refuse
+  // above and stay refusing: `--text-ext js` would otherwise turn the
+  // one extension ADR-012 singles out into a readable one, by a flag
+  // whose whole promise is that it chooses no parser.
+  for (const ext of textExt ?? []) {
+    if (undefined === map[ext]) {
+      map[ext] = textProcessor
+    }
   }
   return map
 }
@@ -1893,7 +1957,7 @@ function makeModelResolver(options: any) {
   // module legs do not: both state `kind: 'aon'` because what they
   // serve is Aontu source by construction, not by its spelling.
   const gateExtension = (path: string, full: string): void => {
-    if (undefined === INCLUDE_KINDS[extKindOf(full)]) {
+    if (undefined === includeFormat(extKindOf(full), options.textExt)) {
       refuseExtension(path, full)
     }
   }
@@ -2308,7 +2372,7 @@ class Lang {
         // (BUGS §49b). Its `js` entry EXECUTES the file, which is not
         // something an extension should be able to ask for. And its
         // fallback hands any other file back as TEXT.
-        processor: includeProcessors()
+        processor: includeProcessors(this.opts.textExt)
       })
       .use(AontuJsonic)
   }

package/src/lsp.ts

@@ -21,7 +21,9 @@ import type { Val } from './type'
 import { Aontu, VERSION } from './aontu'
 import { getHint } from './err'
 import { collectNils } from './walk'
-import { collectDeprecations, deprecationMessage } from './utility'
+import { collectDeprecations, deprecationMessage,
+  includeOpts,
+} from './utility'
 import { why } from './query'
 import type { WhyConjunct } from './provenance'
 
@@ -84,13 +86,13 @@ type OutMessage = {
 // functions, syntax errors) produce diagnostics.
 function computeDiagnostics(
   src: string,
-  opts?: { vars?: Record<string, Val>, trust?: any }
+  opts?: { vars?: Record<string, Val>, trust?: any, textExt?: string[] }
 ): Diagnostic[] {
   // The trust profile (G5, docs/trust.md): the LSP is the
   // highest-exposure surface — merely OPENING a hostile .aon file in an
   // editor performs its reads — so the handler confines evaluation to
   // the workspace root and threads the profile through here.
-  const aontu = new Aontu(null == opts?.trust ? {} : { trust: opts.trust })
+  const aontu = new Aontu(includeOpts(opts ?? {}))
 
   let root: any
   let ac: any

package/src/mcp.ts

@@ -459,6 +459,8 @@ const TOOLS: ToolDef[] = [
     name: 'view',
     description:
       'Draw a figure of the document as deterministic text. Kinds: ' +
+      'doc (the shape of the document itself), lattice (the value ' +
+      'lattice, with the document\'s own values placed on it), ' +
       'tree (the dependency tree of a relation), matrix (the ' +
       'dependency matrix, canon or partition order, --closure), graph ' +
       '(node-link, as mermaid, dot or er), layer (the architecture ' +
@@ -474,8 +476,8 @@ const TOOLS: ToolDef[] = [
       kind: {
         type: 'string',
         description:
-          'The figure to draw: tree (the default), matrix, graph, layer, ' +
-          'sets, layers or ladder',
+          'The figure to draw: tree (the default), doc, lattice, matrix, ' +
+          'graph, layer, sets, layers or ladder',
       },
       as: {
         type: 'string',
@@ -565,8 +567,8 @@ const TOOLS: ToolDef[] = [
     required: ['source'],
     docs: ['source'],
     check: (a) => {
-      const kinds = ['doc', 'tree', 'matrix', 'graph', 'layer', 'sets',
-        'layers', 'ladder']
+      const kinds = ['doc', 'lattice', 'tree', 'matrix', 'graph', 'layer',
+        'sets', 'layers', 'ladder']
       if (null != a.kind && !kinds.includes(a.kind)) {
         return `kind must be one of ${kinds.join(', ')}, not ${JSON.stringify(a.kind)}`
       }

package/src/patch.ts

@@ -75,6 +75,12 @@ export type PatchOptions = {
   // The include capability this document evaluates under
   // (G5, docs/trust.md); vet's precedent.
   trust?: TrustOptions
+  // The extensions an include additionally reads as text (the CLI's
+  // --text-ext). It rides WITH the capability, never beside it: this
+  // verb threaded the capability and not the extension, so `set`
+  // refused an include -- and wrote nothing -- under a flag the bare
+  // command honoured.
+  textExt?: string[]
 }
 
 
@@ -578,6 +584,7 @@ export function patch(
   // the caller, "which file" is the whole question.
   const report: VetReport = vet(entrySrc, overlay, {
     trust: options.trust,
+    textExt: options.textExt,
     schemaPath: options.entryPath,
     dataPath: options.overlayPath,
     schemaUrl: options.entryPath,

package/src/query.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // THE QUERY SURFACE (G7 phase 1,
 // docs/capability-review/g7-machine-access.md): select one node of an
@@ -56,6 +57,11 @@ export type QueryOptions = {
   // extension -- but reading is enough.) A server passes
   // `{include:'none'}`.
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 export type QueryReport = {
@@ -271,8 +277,7 @@ export function get(
   const options = opts ?? {}
   const view: QueryView = options.view ?? 'json'
 
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)
@@ -336,8 +341,7 @@ export type WhyReport = {
 export function why(
   src: string, path: string, opts?: QueryOptions): WhyReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const prov = new Provenance()
   const ctx = aontu.ctx({ collect: true, prov })
   const parseOpts = null == options.path ? undefined : { path: options.path }

package/src/reach.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // REACHABILITY OVER THE LINK GRAPH (the review's finding J,
 // use-cases/REVIEW.md): "ship a transitive `reaches(a, b)` check verb".
@@ -60,6 +61,11 @@ export type ReachOptions = {
   // The include capability this document evaluates under (G5,
   // docs/trust.md).
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
   // Follow only edges under this relation. Absent means follow every
   // edge, which is the whole graph and the commoner question.
   relation?: string
@@ -124,8 +130,7 @@ export function reachCheck(
   src: string, from: string, to: string, opts?: ReachOptions
 ): ReachReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)

package/src/relation.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // RELATION GRAPH VERDICTS (RELATIONS.0.md §3.3, replacing the G4
 // phase 5 magic-key pass): acyclicity and inverse consistency over
@@ -70,6 +71,11 @@ export type RelationOptions = {
   // docs/trust.md). vet's precedent: the verb passes the profile the
   // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 
@@ -248,8 +254,7 @@ export function relationErrors(ctx: any, root: any): void {
 export function relationCheck(
   src: string, opts?: RelationOptions): RelationReport {
   const options = opts ?? {}
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == options.path ? undefined : { path: options.path }
   const root: any = aontu.unify(src, parseOpts, ctx)

package/src/std.ts

@@ -87,7 +87,8 @@ view: {
   # it belongs; everything else narrows the drawing, and each option
   # belongs to the kinds that read it.
   Figure: type({
-    kind: doc | tree | matrix | graph | layer | sets | layers | ladder
+    kind: doc | lattice | tree | matrix | graph | layer | sets | layers
+      | ladder
     out: string
 
     # Every kind.

package/src/subsume.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // Subsumption as a first-class query (G3 phases 1-2,
 // docs/capability-review/g3-subsumption-evolution.md): does the GENERAL
@@ -55,6 +56,11 @@ export type SubsumeOptions = {
   // docs/trust.md). vet's precedent: the verb passes the profile the
   // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 export type SubsumeReport = {
@@ -699,8 +705,7 @@ export function subsume(
   }
 
   const load = (src: string, path?: string): any => {
-    const aontu = new Aontu(
-      null == options.trust ? undefined : { trust: options.trust })
+    const aontu = new Aontu(includeOpts(options))
     const ctx = aontu.ctx({ collect: true })
     const v: any = aontu.unify(
       src, null == path ? undefined : { path }, ctx)

package/src/trim.ts

@@ -1,4 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
+import { includeOpts } from './utility'
 
 // The trim reporter (G3 phase 6,
 // docs/capability-review/g3-subsumption-evolution.md): report REDUNDANT
@@ -50,6 +51,11 @@ export type TrimOptions = {
   // docs/trust.md). vet's precedent: the verb passes the profile the
   // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 
@@ -119,8 +125,7 @@ export function deleteAt(root: any, path: string[]): boolean {
 export function evalCanon(
   src: string, opts: TrimOptions, delPath?: string[],
   sink?: { ctx?: any, failed?: any }): string | undefined {
-  const aontu = new Aontu(
-    null == opts.trust ? undefined : { trust: opts.trust })
+  const aontu = new Aontu(includeOpts(opts))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == opts.path ? undefined : { path: opts.path }
   // WHY the run failed, for the one caller that reports it. The

package/src/type.ts

@@ -69,6 +69,14 @@ type AontuOptions = {
   explain?: any[]
   trust?: TrustOptions // Trust profile (G5, docs/trust.md)
 
+  // EXTENSIONS ADDITIONALLY READ AS TEXT, without their dots. `.txt`
+  // is read as text with no option at all; this widens that set for a
+  // host that keeps its prose in `.md`, its queries in `.sql`, or its
+  // templates under some name only it knows. The file's bytes become
+  // one string scalar -- no parser is chosen for it, which is what
+  // makes widening the set safe to offer.
+  textExt?: string[]
+
   // The staged-flip warning window (G5 phase 6, CLI only): under the
   // default 'system' capability the CLI supplies these, and the
   // resolver calls trustWarn for every resolution that escapes

package/src/utility.ts

@@ -2,7 +2,29 @@
 
 
 
-import type { Val } from './type'
+import type { AontuOptions, TrustOptions, Val } from './type'
+
+
+// THE INCLUDE OPTIONS AN ENGINE HANDS ITS Aontu INSTANCE. Every verb
+// engine builds one, and until there were two such options each did it
+// inline -- `null == options.trust ? undefined : { trust: options.trust }`,
+// written out twelve times. That is fine while there is one option and
+// a latent bug the moment there are two: `textExt` had to reach the
+// same twelve places, and the one it missed refused a `.md` include
+// under a flag the bare command honoured. One function now, so a third
+// include option is threaded once.
+type IncludeOptions = {
+  trust?: TrustOptions
+  textExt?: string[]
+}
+
+function includeOpts(options: IncludeOptions): Partial<AontuOptions> {
+  return {
+    ...(null == options.trust ? {} : { trust: options.trust }),
+    ...(null == options.textExt || 0 === options.textExt.length
+      ? {} : { textExt: options.textExt }),
+  }
+}
 
 
 // Default walk() depth limit. High enough that real configs are never
@@ -262,10 +284,13 @@ function items(o: any) {
   else {
     return []
   }
-} /* node:coverage ignore next 18 */
+} /* node:coverage ignore next 20 */
+
 
+export type { IncludeOptions }
 
 export {
+  includeOpts,
   items,
   propagateMarks,
   canonRiders,

package/src/vet.ts

@@ -36,7 +36,9 @@ import { descErr, getHint } from './err'
 import { ConjunctVal } from './val/ConjunctVal'
 import { walkVals, collectNils } from './walk'
 import { sizingResidue } from './val/BagVal'
-import { collectDeprecations, walkBagVals, deprecationMessage } from './utility'
+import { collectDeprecations, walkBagVals, deprecationMessage,
+  includeOpts,
+} from './utility'
 import { subsumeNode, effectiveDefault } from './subsume'
 // The `--at` refusal is the SAME refusal `get` and `why` give for a
 // path that names nothing, down to the "did you mean" -- so it is that
@@ -151,6 +153,11 @@ export type VetOptions = {
   // ADR-012 refuses the extension -- but reading is enough.) A server
   // passes `{include:'none'}`.
   trust?: TrustOptions
+
+  // Extensions additionally read as text (the CLI's `--text-ext`).
+  // Rides beside `trust` because it is the other half of what an
+  // include may read.
+  textExt?: string[]
 }
 
 
@@ -599,8 +606,7 @@ export function vet(
   // ONE instance, two bases: the path rides on each CALL rather than on
   // the constructor, because the schema and the data may live in
   // different directories (Lang.parse takes `opts.path` per parse).
-  const aontu = new Aontu(
-    null == options.trust ? undefined : { trust: options.trust })
+  const aontu = new Aontu(includeOpts(options))
   const schemaOpts = null == options.schemaPath ?
     undefined : { path: options.schemaPath }
   const dataOpts = null == options.dataPath ?