module.workspace
Workspace discovery and management module
@lssm-tech/module.workspacebun add @lssm-tech/module.workspaceManifest declarations describe the current workspace; they do not verify registry publication or runtime execution.
Package guide
Website: https://contractspec.io
Workspace discovery, static analysis, and graph-building module.
What It Provides
- Layer: module.
- Generative Core role: owns pure static analyzers that turn scanned specs, package files, imports/exports, docs, tests, implementation links, and generated outputs into deterministic graph input.
- Consumers: bundles (contractspec-studio), apps (cli-contractspec).
- Related ContractSpec packages include
@lssm-tech/lib.contracts-integrations,@lssm-tech/lib.contracts-spec,@lssm-tech/lib.schema,@lssm-tech/tool.bun,@lssm-tech/tool.typescript. - Related ContractSpec packages include
@lssm-tech/lib.contracts-integrations,@lssm-tech/lib.contracts-spec,@lssm-tech/lib.schema,@lssm-tech/tool.bun,@lssm-tech/tool.typescript.
Installation
npm install @lssm-tech/module.workspace
or
bun add @lssm-tech/module.workspace
Usage
Import the root entrypoint from @lssm-tech/module.workspace, or choose a documented subpath when you only need one part of the package surface.
Source scanning, authoring path conventions, structure validation, spec types, and Markdown/DocBlock rendering forward to their canonical implementations in @lssm-tech/lib.cli-runtime/workspace/analysis, /workspace/types, and /workspace/formatters. Existing workspace exports preserve function identity and behavior. Lower runtime consumers can use those CLI runtime leaves directly. Semantic diff, snapshot, impact classification, and static DocBlock extraction use the same compatible forwards.
Static DocBlock extraction (extractModuleDocData, analyzePackageDocBlocks, buildPackageDocManifest) parses through the typescript runtime port of @lssm-tech/lib.cli-runtime. @lssm-tech/bundle.workspace binds it when its root entry is imported and when it creates a CLI program. Other callers bind it first, or the call throws CliRuntimePortError (code: 'missingHostBinding'):
import { bindCliRuntimePorts } from '@lssm-tech/lib.cli-runtime/ports/runtime';
import * as typescript from '@lssm-tech/lib.typescript-runtime';
bindCliRuntimePorts({ typescript });Self-maintaining APIs
@lssm-tech/module.workspace/maintenance exposes provider-neutral contracts and pure orchestration for source ingestion, cross-language usage analysis, candidate patch planning, approval, CI validation, draft change requests, rollback, leasing, and merged-outcome observation.
The continuous worker is fail-closed: source refs must bind explicit base/head roles, approvals expire, leases fence concurrent workers, validation failure rolls back the candidate branch, and completion requires the repository adapter to observe a merged change request. Infrastructure and GitHub calls remain behind ports and are supplied by a bundle or host application.
GovernedChangeAutomationCoordinator is a separate additive V2 coordinator. It binds the maintenance case, patch receipt, exact base/head revisions, low-risk decision, and passing checks before it can mark a PR ready or schedule native auto-merge. Medium, high, unknown, stale, or failed-check changes remain blocked for human review. The original draft-only lifecycle is unchanged.
Architecture
src/aiis part of the package's public or composition surface.src/analysisis part of the package's public or composition surface.src/formatter.tsis part of the package's public or composition surface.src/formattersis part of the package's public or composition surface.src/index.tsis the root public barrel and package entrypoint.src/maintenanceowns the provider-neutral self-maintaining API lifecycle.src/templatesis part of the package's public or composition surface.src/typesis part of the package's public or composition surface.
Generative Core Analyzer Scope
- Contract graph extraction covers authored operations, events, presentations, forms, workflows, knowledge, policies, integrations, jobs, translations, docs, tests, and generated-artifact refs.
- Codebase graph extraction covers packages, files, imports, exports, tests, docs, generated targets, implementation links, and confidence diagnostics.
- Visual scenarios are discovered from
defineVisualScenario(...)declarations and the.visual-scenario.ts/visual-scenarios/conventions. - The module stays pure: persistence, Connect policy, CLI rendering, and apply/repair orchestration remain in bundle/app layers.
Public Entry Points
- Export
.resolves through./src/index.ts. - Export
./maintenanceresolves through./src/maintenance/index.ts.
Local Commands
bun run dev— contractspec-bun-build devbun run build— contractspec-bun-build buildbun run test— bun testbun run lint— bun lint:fixbun run lint:check— biome check .bun run lint:fix— biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .bun run typecheck— tsgo --noEmitbun run publish:pkg— bun publish --tolerate-republish --ignore-scripts --verbosebun run publish:pkg:canary— bun publish:pkg --tag canarybun run clean— rimraf dist .turbobun run build:bundle— contractspec-bun-build transpilebun run build:types— contractspec-bun-build typesbun run prebuild— contractspec-bun-build prebuild
Recent Updates
- Replace eslint+prettier by biomejs to optimize speed.
- Stability.
- Add changesets and apply pending fixes.
- Add ai-native messaging channel runtime.
- Add the leased, approval-gated, provider-neutral self-maintaining API worker.
Notes
- Uses
ts-morphfor AST analysis andcompare-versionsfor semver checks -- version bumps may affect parsing behavior. - Workspace detection is file-system-dependent; always use the provided abstractions, never raw
fscalls. - Changes here affect CLI and studio workspace initialization flows.
Data-view structure validation accepts both legacy defineDataView(spec) and translation-bound defineDataView(messages, spec), inspecting the spec argument rather than the translation catalog.
The root build targets Node-compatible server execution (including Bun). It requires filesystem, process, or native compiler facilities and does not advertise a browser export condition. Browser applications should use the relevant browser-safe contracts or UI entry points instead of importing this server root.
Relationships
Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.
12 declarations
@lssm-tech/lib.contracts-runtime-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.orchestration-specworkspace:^
Read the package manual ↗@lssm-tech/lib.typescript-runtimeworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-integrationsworkspace:^
Read the package manual ↗@lssm-tech/lib.contracts-spec-coreworkspace:^
Read the package manual ↗@lssm-tech/lib.schemaworkspace:^
Read the package manual ↗
Declared capabilities
Workspace discovery and management module
Scripts
publish:pkgbun publish --tolerate-republish --ignore-scripts --verbosepublish:pkg:canarybun publish:pkg --tag canarybuildcontractspec-bun-build buildbuild:bundlecontractspec-bun-build transpilebuild:typescontractspec-bun-build typesdevcontractspec-bun-build devcleanrimraf dist .turbolintbun lint:fixlint:fixnode ../../../../scripts/biome.cjs check --write --unsafe --only=nursery/useSortedClasses . && node ../../../../scripts/biome.cjs check --write .lint:checknode ../../../../scripts/biome.cjs check .testbun testprebuildcontractspec-bun-build prebuildtypechecktsgo --noEmit