packages/engine/unitSummary

Unit summaries for bots and humans: one deterministic, LLM-free, MCP-ready API that answers "what is this thing and is it healthy?" for any unit in the ecosystem (project, feature, layer, file, component, hook, servic...

Engine, v0.8. Source: packages/engine/unitSummary.mjs.

Variables#

DETAILS#

const DETAILS: string[]

Defined in: packages/engine/unitSummary.mjs:16

---

SCHEMA_VERSION#

const SCHEMA_VERSION: 1 = 1

Defined in: packages/engine/unitSummary.mjs:15

---

TOKEN_BUDGETS#

const TOKEN_BUDGETS: object

Defined in: packages/engine/unitSummary.mjs:18

Token budgets per detail level (tokens ~= chars / 4). Brief is designed to fit ~500 tokens.

Type Declaration#

brief

brief: number = 500

full

full: number = 8000

standard

standard: number = 2000

Functions#

listFeatures()#

listFeatures(root, opts?): any

Defined in: packages/engine/unitSummary.mjs:190

Index of features with one-line health each.

Parameters#

root

string

Project root.

opts?

any = {}

Passed on to listUnits and summarizeUnit.

Returns#

any

{ok:true, features:[{name, path, ref, summary, health, completeness}]} (an entry carries error when its summary failed), or {ok:false, error}.

---

listUnits()#

listUnits(root, options?): any

Defined in: packages/engine/unitSummary.mjs:158

List units. With kind: every unit of that kind. Without: an index of kinds (with counts) plus the low-cardinality units (project, feature, layer, route, rule, envelope, generator, package).

Parameters#

root

string

Absolute or relative path of the project root; must exist.

options?

kind?

string

Return every unit of this kind instead of the kind index.

registry?

any = ...

Unit registry to read from (defaults to the built-in one).

Returns#

any

{schemaVersion, ok:true, kind?, kinds?, count, units} or {ok:false, error}: the units (each {kind, id, name, path?, ref}), plus the kind index when kind is omitted; {ok:false} for a missing root (ROOT_NOT_FOUND) or an unknown kind (UNKNOWN_KIND).

Example#

listUnits('.', { kind: 'feature' });
// => { ok: true, kind: 'feature', count: 3, units: [{ kind: 'feature', id: 'plan', ref: 'feature:plan', ... }] }

---

renderUnitMarkdown()#

renderUnitMarkdown(result): string

Defined in: packages/engine/unitSummary.mjs:259

Render any summary/list/error result as Markdown (for humans).

Parameters#

result

any

A summarizeUnit, listUnits or listFeatures result (or an error).

Returns#

string

Markdown for a human reader.

---

resolveUnit()#

resolveUnit(root, ref, opts?): any

Defined in: packages/engine/unitSummary.mjs:135

Resolve a reference to {ok:true, unit:{kind,id}} or a structured ambiguity/not-found error with candidates.

Parameters#

root

any

ref

any

opts?

Returns#

any

---

resolveUnitIn()#

resolveUnitIn(ctx, ref, __namedParameters?): any

Defined in: packages/engine/unitSummary.mjs:125

Resolve a reference against an existing facts context (units/facts.mjs createContext), so a caller resolving many refs pays for the project walk/parse once. Same result shape as resolveUnit.

Parameters#

ctx

any

ref

any

__namedParameters?

registry?

{ get: (name) => any; kinds: () => any[]; names: () => any[]; register: { register(k: any): ...; get: (name: any) => any; kinds: () => any[]; names: () => any[]; }; } = ...

registry.get

(name) => any = ...

registry.kinds

() => any[] = ...

registry.names

() => any[] = ...

registry.register

Returns#

any

---

summarizeFeatureForAgents()#

summarizeFeatureForAgents(root, featureOrRef, opts?): any

Defined in: packages/engine/unitSummary.mjs:203

Feature-first entry point: a feature name, or (route/path) anything else summarizeUnit understands.

Parameters#

root

any

featureOrRef

any

opts?

Returns#

any

---

summarizeUnit()#

summarizeUnit(root, ref, opts?): any

Defined in: packages/engine/unitSummary.mjs:85

Summarize any unit.

Parameters#

root

string

project (or Construct package) root

ref

string

"kind:id", or a bare name/path/route/rule id ("login", "packages/ast", "/login", "PAGE-006")

opts?

include: keep only these sections keys (summary, health, links, next are always kept)

detail?

"standard" | "brief" | "full"

include?

string[]

kind?

string

registry?

any

Returns#

any

{schemaVersion, ok:true, kind, id, ref, name, path, detail, summary, sections, health, links, next, budget} or {schemaVersion, ok:false, error:{code, message, candidates?, hint?}}. Never throws.

---

unitApiManifest()#

unitApiManifest(registry?): any

Defined in: packages/engine/unitSummary.mjs:214

Machine-readable usage note for agents (also served by construct summarize --usage).

Parameters#

registry?

any = ...

Unit registry to describe (defaults to the built-in one).

Returns#

any

The usage note: schema, purpose, recommended call flow, call signatures, CLI, REST routes and the ref grammar.