@base-works/intelligence (0.2.0)
Installation
@base-works:registry=https://git.muddlab.com/api/packages/ahmadsholehin/npm/npm install @base-works/[email protected]"@base-works/intelligence": "0.2.0"About this package
@base-works/intelligence
Transport-independent developer intelligence for BaseWorks derivatives. It resolves the surrounding project, compiles a deterministic catalogue describing what is actually installed, searches that catalogue, and returns exact records for progressive disclosure. It contains no terminal or MCP rendering.
Component reuse level and structural kind are separate. In addition to normal
UI components, manifests may describe map.host, map.layer, map.control
and map.tool roles, supported rendering backends, and the runtime
capabilities a renderer requires. Search indexes those fields and describe
returns them without opening implementation source.
Inputs and ownership
indexProject() reads only declared/local project state:
- copied
*.baseworks.jsonrecords below.base-works/project.json'scatalogue.stackRoots; - compact catalogues declared by directly installed
@base-works/*package manifests throughbaseWorks.catalogue; - declarative co-located
*.meta.tsmanifests and legacy precompiledbaseworks.catalogue.jsonfiles below declaredcatalogue.localRoots.
Stack records become stack-copied; installed L2 and L3 records become
shared-l2 and shared-l3; records from local compiled catalogues become
project-local. Source paths must remain within their owner and resolve in the
installed project. Local TypeScript is parsed statically and must contain only
type-only imports, one JSON-shaped const manifest with unique keys, and its
default export; it is never imported or executed. Duplicate IDs fail indexing
instead of silently overriding an owner and recommend a project-prefixed ID plus
derivedFrom. Lineage must resolve to components and cannot contain cycles.
API
import {
describePattern,
describeCatalogueRecord,
findPatterns,
assessPromotionCandidate,
compareComponents,
indexProject,
searchCatalogue,
} from "@base-works/intelligence";
const indexed = indexProject({ cwd: process.cwd() });
const hits = searchCatalogue(indexed.catalogue, "arrival sequence");
const contract = describeCatalogueRecord(
indexed.catalogue,
"aviation.arrival-sequence-viewer",
);
const patterns = findPatterns(indexed.catalogue, "timeline workspace");
const pattern = describePattern(
indexed.catalogue,
"core.timeline-controlled-workspace",
);
const candidates = findCompatible(indexed.catalogue, {
container: "ui.operations-workspace",
slot: "workspace.left",
});
const result = validateComposition(indexed.catalogue, {
container: "ui.operations-workspace",
placements: [
{ slot: "workspace.primary", component: "project.airspace-map" },
{ slot: "workspace.left", component: "aviation.arrival-sequence-viewer" },
],
});
const sourceIndex = indexSourceGraph({ cwd: process.cwd() });
const implementation = locateImplementation(
sourceIndex.graph,
"ui.time-slider",
);
const usages = findUsages(sourceIndex.graph, "ui.time-slider", { limit: 10 });
const comparison = compareComponents(
sourceIndex.catalogue,
"my-app.replay-control",
"ui.time-slider",
);
const promotionEvidence = assessPromotionCandidate(
sourceIndex.catalogue,
sourceIndex.graph,
"my-app.replay-control",
);
Search returns at most five records by default and ten when explicitly requested. Ranking considers exact IDs/capabilities, domain and purpose terms, availability, level, ownership, and deprecation; ties are deterministic. A relevant project specialization receives a modest preference, followed by the highest suitable shared abstraction, but textual/capability relevance remains dominant.
findPatterns() searches only package-owned known-good compositions, so a
component query and a wiring query do not compete for the same bounded result
set. describePattern() returns compact ordered wiring guidance together with
referenced components, capabilities, semantic slots, canonical examples,
precise source usages, ownership and installed version. Patterns are metadata
over real TSX; they never render React or define an application DSL. Indexing
verifies their package-relative source/example paths and resolves their declared
component, capability and slot references against the installed catalogue.
fits() resolves a concrete slot declaration to its accepted semantic slot
types and intersects them with a component manifest's fits. It never imports
or renders React. findCompatible() applies that rule to the installed
catalogue in deterministic ID order. validateComposition() reports unknown
records/types, incompatible placement, cardinality and missing required slots
as errors; experimental/deprecated status and an available project-local
specialization remain warnings. Applications with additional semantic types
can pass an explicit extended slot registry rather than modifying validation
logic.
Cache
The content fingerprint covers every discovered metadata input and a local
component's resolved source path. A matching index is read from
.base-works/cache/catalogue-v1.json; changed input, missing source, or
refresh: true rebuilds it. The cache is generated, disposable, project-local,
and never authoritative.
Source graph
indexSourceGraph() is the static progressive-disclosure layer over the
authoritative catalogue. It parses TypeScript/TSX below descriptor-declared
Stack and local roots plus src/stories from directly installed BaseWorks
packages. It never imports or executes application code. The derived graph
records declarations, imports, React renders, route renders, hook/store calls,
and curated pattern/component evidence.
locateImplementation() resolves an exact catalogue ID to a symbol or file
line range without returning source text. findUsages() returns at most ten
relationships by default (50 through the API), in deterministic order. Both
return transparent token diagnostics based on UTF-8 bytes divided by four;
these are regression estimates rather than a model-specific tokenizer.
Per-file fingerprints live in the disposable
.base-works/cache/source-graph-v1.json. A warm index reuses every unchanged
analysis; edits reparse only changed/new files and removal drops stale entries.
The graph is syntactic rather than type-checker-complete: dynamic imports,
computed component names, runtime registration and re-export chains may require
one targeted source read after the query.
Promotion assistance
compareComponents() reports exact metadata overlap and differences between two
catalogued component contracts. Its deterministic evidence rank orders review
targets but is not a confidence or promotion decision.
assessPromotionCandidate() accepts only a project-local component and combines
its declared lineage, bounded implementation/usages, installed shared
comparisons, possible package owners, and mandatory review questions. It always
returns human-review-required and never moves source or edits metadata. See
Promotion assistance.
Spectrum L1 guidance
querySpectrumGuidance() preserves the L3/L2-first boundary. Requests labelled
L2 or L3 return a BaseWorks-local decision without invoking the supplied
adapter loader. An explicit L1 request lazily loads a
SpectrumGuidanceAdapter. createAdobeSpectrumAdapter() maps component
questions to Adobe s2-docs and token/design-data questions to Adobe
design-data, through an injected executor owned by the agent host or future
transport package.
Intelligence does not install Adobe tooling, start MCP, fetch remote state, or mirror Spectrum data. See the Spectrum adapter contract.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @base-works/contracts | ^0.2.0 |
| typescript | ^5.9.3 |
Development Dependencies
| ID | Version |
|---|---|
| @types/node | ^24.10.0 |