@idfkit/language 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Samuel Letellier-Duchesne
+
+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,47 @@
+# @idfkit/language
+
+The opt-in language service for IDF text: what completes here, what this means,
+what this points at, and where a finding sits in the characters the reader is
+looking at.
+
+Peer-depends on [`@idfkit/core`](../core) and on nothing else. Everything
+exported here is synchronous and free of I/O, so it runs unchanged in Node, a
+browser, a worker, or behind an editor server.
+
+**[Documentation](https://js.idfkit.com/)** ·
+[API reference](https://js.idfkit.com/reference/language/)
+
+```bash
+npm install @idfkit/language
+```
+
+## Reaching it from the shared name
+
+A project that installs `idfkit` reaches this package through a subpath:
+
+```ts
+import { completionsAt } from 'idfkit/language';
+```
+
+The subpath stays in the export map whether or not this package is installed.
+Importing it without this package names the install to run rather than failing
+with a bare module-resolution error, which is why the service costs a reader who
+never asks for it zero bytes on disk and zero bytes in a bundle.
+
+## No protocol
+
+This package imports, depends on, and names nothing from any editor protocol
+library. It answers in its own vocabulary and a consumer translates: `envelop`
+to its own editor's shape, `idfkit-lsp` to the Language Server Protocol. The
+regions it reports never cross a line boundary, because no editor token encoding
+can express one that does, so the translation stays a rename rather than
+arithmetic.
+
+## Versioning
+
+This package joins the repository's release lockstep. `@idfkit/core`,
+`@idfkit/schemas`, `@idfkit/weather` and this package are versioned and released
+together, and the dependency on `@idfkit/core` is an exact peer range rather than
+a caret one. A service paired with a syntax layer it disagrees with would put
+findings on the wrong characters, silently; the lockstep is what makes that
+install unsupported rather than merely unlikely.

package/dist/complete.d.ts

@@ -0,0 +1,93 @@
+import { type IdfDocument, type ProsePool, type Region, type Schema } from '@idfkit/core';
+/**
+ * One thing that may go where the cursor is.
+ *
+ * Everything a consumer needs to render the offer and to apply it, so that a list can be shown and
+ * accepted without a second call and without the consumer measuring anything itself.
+ */
+export interface Offer {
+    /** The text to insert. */
+    readonly value: string;
+    /**
+     * The region this offer would replace.
+     *
+     * Carried rather than left to the consumer (FR-048), and this is not optional politeness. An
+     * editor's own word rules break on both halves of this format: type names contain colons, so
+     * `BuildingSurface:Detailed` is two words to most of them, and values contain spaces, so
+     * `Office Zone 1` is three. A consumer left to derive the replaced span would get it wrong on
+     * the majority of real completions. Working it out needs the format's rules, which live here.
+     *
+     * The region is empty where nothing has been written yet, which is an insertion at that point.
+     */
+    readonly replaces: Region;
+    /** What kind of thing this is. */
+    readonly kind: 'objectType' | 'enumValue' | 'referenceTarget';
+    /** Whether the schema marks the field required. Undefined for object types. */
+    readonly required: boolean | undefined;
+    /**
+     * The schema's own prose, when the caller supplied the pool.
+     *
+     * The type's memo for a type-name offer and the field's note for a value offer, because those
+     * are the two things the pool holds. It carries no sentence about an individual permitted value
+     * and neither does this: deriving one from the value's spelling is the one thing FR-022 forbids
+     * by name.
+     */
+    readonly prose: string | undefined;
+}
+/**
+ * What completes here, or why nothing does.
+ *
+ * A discriminated union rather than a list that is sometimes empty, because "the schema permits
+ * anything here" and "I could not consult a schema" are different states and an editor that
+ * rendered them identically would teach the reader that the tool is broken in the first case and
+ * silently wrong in the second (FR-020, FR-031). A consumer that only wants the happy path matches
+ * `'ok'` and ignores the rest; a consumer that wants to tell a reader why there is nothing has the
+ * reason.
+ *
+ * `'ok'` with no offers is a legitimate state and a different one from all four below: it says the
+ * schema constrains this field to names the model has not declared yet.
+ */
+export type CompletionResult = {
+    readonly status: 'ok';
+    readonly offers: readonly Offer[];
+} | {
+    readonly status: 'unconstrained';
+} | {
+    readonly status: 'noSchema';
+} | {
+    readonly status: 'unknownType';
+    readonly typeName: string;
+} | {
+    readonly status: 'notApplicable';
+};
+/** What a caller can supply beyond the text, the offset and the schema. */
+export interface CompletionOptions {
+    /** Supplies candidate names for reference fields. Omit and none are offered. */
+    readonly document?: IdfDocument;
+    /** Supplies prose for the offers. Omit and offers carry none. */
+    readonly prose?: ProsePool;
+}
+/**
+ * What may be written where the cursor is.
+ *
+ * Bounded local work: the cursor is placed by {@link contextAt}, which scans one statement, and
+ * the answer then comes from the schema, whose cost is the type rather than the file. The one
+ * exception is a reference field, whose candidates are the names other objects declare, which is a
+ * whole-document question by nature; it is answered from the document the caller already holds and
+ * never by parsing one (research R9). A service that quietly parsed a document when the argument
+ * was omitted would make one function on the keystroke path eighty milliseconds slower depending
+ * on an argument nobody passed, which is the worst failure mode available.
+ *
+ * The whole schema's type list is offered where a statement begins, unfiltered by what has been
+ * typed so far. Filtering is the consumer's, and it has what it needs to do it: `replaces` says
+ * exactly which characters the offer stands in for, which is the span an editor's own word rules
+ * get wrong on this format.
+ *
+ * `schema` is written as possibly absent rather than required, because `'noSchema'` is a state
+ * FR-031 requires this to report and a signature that forbade the input would make it unreachable
+ * from typed code.
+ *
+ * Nothing throws, for any input.
+ */
+export declare function completionsAt(text: string, offset: number, schema: Schema | undefined, options?: CompletionOptions): CompletionResult;
+//# sourceMappingURL=complete.d.ts.map

package/dist/complete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"complete.d.ts","sourceRoot":"","sources":["../src/complete.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,MAAM,EACX,KAAK,MAAM,EAGZ,MAAM,cAAc,CAAC;AAItB;;;;;GAKG;AACH,MAAM,WAAW,KAAK;IACpB,0BAA0B;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,WAAW,GAAG,iBAAiB,CAAC;IAC9D,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;IACvC;;;;;;;OAOG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GACpC;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CAAE,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC;IAChC,iEAAiE;IACjE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAqElB"}

package/dist/complete.js

@@ -0,0 +1,225 @@
+import { describeObjectType, } from '@idfkit/core';
+import { contextAt, fieldNameAt } from './cursor.js';
+const NOT_APPLICABLE = { status: 'notApplicable' };
+const NO_SCHEMA = { status: 'noSchema' };
+const UNCONSTRAINED = { status: 'unconstrained' };
+/**
+ * What may be written where the cursor is.
+ *
+ * Bounded local work: the cursor is placed by {@link contextAt}, which scans one statement, and
+ * the answer then comes from the schema, whose cost is the type rather than the file. The one
+ * exception is a reference field, whose candidates are the names other objects declare, which is a
+ * whole-document question by nature; it is answered from the document the caller already holds and
+ * never by parsing one (research R9). A service that quietly parsed a document when the argument
+ * was omitted would make one function on the keystroke path eighty milliseconds slower depending
+ * on an argument nobody passed, which is the worst failure mode available.
+ *
+ * The whole schema's type list is offered where a statement begins, unfiltered by what has been
+ * typed so far. Filtering is the consumer's, and it has what it needs to do it: `replaces` says
+ * exactly which characters the offer stands in for, which is the span an editor's own word rules
+ * get wrong on this format.
+ *
+ * `schema` is written as possibly absent rather than required, because `'noSchema'` is a state
+ * FR-031 requires this to report and a signature that forbade the input would make it unreachable
+ * from typed code.
+ *
+ * Nothing throws, for any input.
+ */
+export function completionsAt(text, offset, schema, options = {}) {
+    const context = contextAt(text, offset, schema);
+    // Inside a comment nothing completes, with a schema or without one. Reporting `'noSchema'` here
+    // would send a caller off to load one that would change this answer not at all.
+    if (context.at === 'comment')
+        return NOT_APPLICABLE;
+    if (schema === undefined)
+        return NO_SCHEMA;
+    // `'typeName'` and `'betweenStatements'` are the two states that carry no field index, and both
+    // are a statement beginning: half a type name written, or nothing written yet.
+    if (context.fieldIndex === undefined) {
+        return { status: 'ok', offers: typeNameOffers(schema, context, options.prose) };
+    }
+    const typeName = context.typeName;
+    if (typeName === undefined) {
+        return { status: 'unknownType', typeName: context.statement.typeNameText };
+    }
+    const type = schema.get(typeName);
+    if (type === undefined)
+        return { status: 'unknownType', typeName };
+    const facts = fieldFactsAt(schema, typeName, type, context.fieldIndex, options.prose);
+    // Past the type's last field, with no extensible group to repeat. The schema constrains a field
+    // it does not define in no way at all; that the field should not be there is a finding, and
+    // saying so is that finding's job rather than this one's.
+    if (facts === undefined)
+        return UNCONSTRAINED;
+    const written = context.statement.fields[context.fieldIndex];
+    // A field index is counted from the separators of this same statement, so it always names a
+    // written field. An insertion at the statement's end is the harmless answer if that ever stops
+    // being true; replacing the statement's whole region would not be.
+    const replaces = written ?? {
+        start: context.statement.region.end,
+        end: context.statement.region.end,
+    };
+    if (facts.values !== undefined && facts.values.length > 0) {
+        return {
+            status: 'ok',
+            offers: facts.values.map((value) => ({
+                // Numeric on the handful of fields that express a choice numerically, and the offer is
+                // text to insert, so it is spelled the way it would be written.
+                value: String(value),
+                replaces,
+                kind: 'enumValue',
+                required: facts.required,
+                prose: facts.prose,
+            })),
+        };
+    }
+    if (facts.objectList !== undefined && facts.objectList.length > 0) {
+        const document = options.document;
+        // No document, so no candidates can exist. Saying so is the point: an empty `'ok'` list here
+        // would be indistinguishable from a model that has declared nothing yet.
+        if (document === undefined)
+            return NOT_APPLICABLE;
+        return {
+            status: 'ok',
+            offers: declaredNames(document, schema, facts.objectList).map((value) => ({
+                value,
+                replaces,
+                kind: 'referenceTarget',
+                required: facts.required,
+                prose: facts.prose,
+            })),
+        };
+    }
+    return UNCONSTRAINED;
+}
+/**
+ * Every object type the schema defines, as offers replacing the type name as written.
+ *
+ * The replaced region is the statement's type name, which is empty where nothing has been typed
+ * yet, so accepting an offer between two statements inserts and accepting one over a half-written
+ * name replaces the whole of it, colons included.
+ */
+function typeNameOffers(schema, context, prose) {
+    const replaces = context.statement.typeName;
+    return schema.typeNames.map((value) => ({
+        value,
+        replaces,
+        kind: 'objectType',
+        // A type is not required or optional; only a field is.
+        required: undefined,
+        prose: memoOf(schema, value, prose),
+    }));
+}
+/**
+ * The names objects in this document declare into any of `lists`.
+ *
+ * A walk of the document the caller handed in, which is a document cost rather than a text cost:
+ * nothing is parsed, nothing is scanned, and a document a keystroke behind the text is the correct
+ * input rather than a stale one, because the statement being typed is incomplete by definition and
+ * names harvested from it would be garbage (research R9).
+ *
+ * A name reaches a list two ways, and both are read here so that no third way to resolve a name is
+ * invented (FR-029): the object's own name, when its type's `nref` contributes to the list, and an
+ * ordinary field's value, when that field's `ref` does. The second is how anonymous types such as
+ * `FluidProperties:Name` carry their identity, and treating those as nameless would offer nothing
+ * where the model plainly declares something.
+ */
+function declaredNames(document, schema, lists) {
+    const wanted = new Set(lists);
+    const seen = new Set();
+    const names = [];
+    const keep = (value) => {
+        if (value === undefined || value === '')
+            return;
+        // Deduplicated case-insensitively, the way EnergyPlus resolves a name, but offered in the
+        // casing the model wrote it in, which is what a reader expects to see inserted.
+        const key = value.toLowerCase();
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        names.push(value);
+    };
+    for (const object of document.objects()) {
+        const type = schema.get(object.typeName);
+        if (type === undefined)
+            continue;
+        if (contributes(type.nref, wanted))
+            keep(object.name);
+        for (const [field, definition] of Object.entries(type.p)) {
+            if (!contributes(definition.ref, wanted))
+                continue;
+            const value = object.get(field);
+            if (typeof value === 'string')
+                keep(value);
+        }
+    }
+    return names;
+}
+/** Whether any list this record contributes to is one the field points into. */
+function contributes(declared, wanted) {
+    if (declared === undefined)
+        return false;
+    return declared.some((list) => wanted.has(list));
+}
+/**
+ * What the schema says about the field at a positional index.
+ *
+ * Taken from `describeObjectType`, which is the one place a field's facts are read (FR-029), so
+ * that a completion offers what the reference page documents rather than a second opinion about
+ * the same bundle.
+ *
+ * With one hole, and it is worth naming rather than hiding. `describeObjectType` drops the type's
+ * positional first field, because Python's `get_field_names` drops it on the assumption that it is
+ * always the name. On a named type it is, and the name is free text, so `'unconstrained'` is the
+ * right answer there anyway. On the 164 anonymous types it is a real field, and 41 of those are
+ * choice fields: `GlobalGeometryRules.starting_vertex_position` is one an author edits by hand.
+ * Reporting nothing for those would be silently wrong, so this reads that one field's record
+ * directly. Closing the hole properly means changing `describeObjectType` in `@idfkit/core`, which
+ * this package does not own.
+ */
+function fieldFactsAt(schema, typeName, type, index, prose) {
+    const name = fieldNameAt(type, index);
+    if (name === undefined)
+        return undefined;
+    const described = describeObjectType(schema, typeName, prose).fields.find((field) => field.name === name);
+    if (described !== undefined) {
+        return {
+            values: described.enumValues,
+            objectList: described.objectList,
+            required: described.required,
+            prose: described.note,
+        };
+    }
+    const definition = type.p[name] ?? type.x?.p[name];
+    if (definition === undefined)
+        return undefined;
+    return {
+        values: permittedValues(definition),
+        objectList: definition.ol,
+        required: (type.r ?? []).includes(name),
+        prose: definition.n === undefined ? undefined : prose?.[definition.n],
+    };
+}
+/**
+ * The values a field accepts, for the one field `describeObjectType` cannot describe.
+ *
+ * Reproduces that function's `acceptedValues` exactly, and only exists because it is not reachable
+ * from here. `se`, the collapsed `anyOf` string branch, carries the sizing sentinels and wins when
+ * it is present; `e`, the choice list, has had the empty string filtered out by the bundle because
+ * `e` is what validation checks against, and `eb` records that it was there.
+ */
+function permittedValues(field) {
+    if (field.se !== undefined)
+        return [...field.se];
+    if (field.e === undefined)
+        return undefined;
+    return field.eb === 1 ? ['', ...field.e] : [...field.e];
+}
+/** A type's own prose, resolved against the pool. Nothing is hydrated when no pool was supplied. */
+function memoOf(schema, typeName, prose) {
+    if (prose === undefined)
+        return undefined;
+    const memo = schema.get(typeName)?.m;
+    return memo === undefined ? undefined : prose[memo];
+}
+//# sourceMappingURL=complete.js.map

package/dist/complete.js.map

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

package/dist/cursor.d.ts

@@ -0,0 +1,59 @@
+import type { Schema, Statement } from '@idfkit/core';
+/**
+ * Which statement an offset falls in, which field, and which part.
+ *
+ * Everything a cursor answer needs, and nothing a whole file would have to be read to know.
+ * `statement` is the one statement the offset sits in, scanned locally; `at` says which part of it
+ * the offset is on; `fieldIndex` positions that part; and `typeName` and `fieldName` are what the
+ * schema calls them, when a schema was supplied and knows.
+ */
+export interface CursorContext {
+    /** The statement the offset falls in, scanned locally. */
+    readonly statement: Statement;
+    /** Where in the statement the offset is. */
+    readonly at: 'typeName' | 'field' | 'comment' | 'betweenStatements';
+    /**
+     * Positional index of the field, when `at` is `'field'`.
+     *
+     * Counted the same way `Statement.fields` is indexed, so it maps onto schema field order
+     * directly: index 0 is the first field after the type name, which on a named type is the name.
+     */
+    readonly fieldIndex: number | undefined;
+    /** The canonical type name, when the schema defines it. */
+    readonly typeName: string | undefined;
+    /** The schema field name, when the type is known and the index is in range. */
+    readonly fieldName: string | undefined;
+}
+/**
+ * Where the cursor is, found by scanning outwards from it.
+ *
+ * **This never builds or consults a `SyntaxLayer`, and it must not start.** Building a layer to
+ * answer a cursor is the reparse the whole design exists to avoid: it costs the file, on a
+ * keystroke, for an answer that concerns one statement. The committed measurement asks the same
+ * question of a large model and of a file a hundredth its size and requires the two to come out
+ * within a small factor, which is a check a reparse cannot pass on any machine.
+ *
+ * The method is a backward scan to the nearest semicolon that is not inside a comment, then a
+ * forward scan over that one statement. Both halves are sound only because of what this grammar
+ * lacks: IDF has no nesting, no string literals and no escape sequences, so a semicolon terminates
+ * a statement unconditionally unless a comment swallowed it, and a comment is an exclamation mark
+ * running to the end of its line. Deciding whether a candidate semicolon is real therefore costs
+ * the length of its line, and finding the statement costs the distance back to the previous real
+ * terminator. Neither number grows with the file. Almost no other grammar would permit this, and
+ * a language that gained a string literal would break it silently, so the property is stated here
+ * rather than left for a reader to rediscover.
+ *
+ * The honest bound is the distance back to the previous real terminator rather than the length of
+ * the statement. Those are the same number in ordinary files and differ in one real case: a cursor
+ * in the first statement of a file that opens with a large comment header scans back through the
+ * header. Headers are small, and the case is still linear with a tiny constant.
+ *
+ * Nothing throws, for any input. An offset outside `[0, text.length]` is clamped into range rather
+ * than refused (FR-032): a cursor arrives from an editor that may be a keystroke ahead of the text
+ * it was measured against, and answering about the nearest character beats answering nothing.
+ *
+ * The schema is optional. Without one the context still reports the statement, the part, and the
+ * field index, which is what positions a finding about a type no schema defines.
+ */
+export declare function contextAt(text: string, offset: number, schema?: Schema): CursorContext;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../src/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAU,MAAM,EAAY,SAAS,EAAE,MAAM,cAAc,CAAC;AAExE;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,EAAE,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,mBAAmB,CAAC;IACpE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,aAAa,CActF"}