module.workspace

@lssm-tech/module.workspace

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, vscode-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/ai is part of the package's public or composition surface.
• src/analysis is part of the package's public or composition surface.
• src/formatter.ts is part of the package's public or composition surface.
• src/formatters is part of the package's public or composition surface.
• src/index.ts is the root public barrel and package entrypoint.
• src/maintenance owns the provider-neutral self-maintaining API lifecycle.
• src/templates is part of the package's public or composition surface.
• src/types is 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 ./maintenance resolves through ./src/maintenance/index.ts.

Local Commands

• bun run dev — contractspec-bun-build dev
• bun run build — contractspec-bun-build build
• bun run test — bun test
• bun run lint — bun lint:fix
• bun run lint:check — biome check .
• bun run lint:fix — biome check --write --unsafe --only=nursery/useSortedClasses . && biome check --write .
• bun run typecheck — tsgo --noEmit
• bun run publish:pkg — bun publish --tolerate-republish --ignore-scripts --verbose
• bun run publish:pkg:canary — bun publish:pkg --tag canary
• bun run clean — rimraf dist .turbo
• bun run build:bundle — contractspec-bun-build transpile
• bun run build:types — contractspec-bun-build types
• bun 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-morph for AST analysis and compare-versions for semver checks -- version bumps may affect parsing behavior.
• Workspace detection is file-system-dependent; always use the provided abstractions, never raw fs calls.
• Changes here affect CLI, VSCode extension, 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.