@mortice/mapwright 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,161 @@
+# Changelog
+
+## 0.8.0
+
+Mortice Mapwright **v0.8.0** — change intelligence.
+
+- **Renamed from Code Atlas to Mapwright (`@mortice/mapwright`) before first public distribution.** CLI binary is now `mapwright`, MCP binary is `mapwright-mcp`, default catalogue directory is `.mapwright`, config file is `mapwright.config.json`, and MCP resources use the `mapwright://` namespace. Cryptographic identity/comparison namespace strings inherited from the pre-release Code Atlas era (`code-atlas-identity`, `code-atlas-fingerprint`, `code-atlas-comparison`, `code-atlas-change`) are intentionally frozen for ID stability. Catalogues with generator name `code-atlas` continue to load.
+- **Toolkit namespace corrected from Mortise to Mortice (`@mortice/mapwright`) immediately before first public npm distribution** because the `@mortise` npm scope was unavailable. Mapwright's own runtime identity (CLI, MCP, generator name, catalogue directory, config file, `mapwright://` resources) and repository (`andrewmuir/Mapwright`) were not affected. Earlier qualification evidence retains the original `@mortise` scope and Mortise-branded package spelling under which it was produced; see [docs/naming.md](docs/naming.md) and [docs/release/v0.8-qualification.md](docs/release/v0.8-qualification.md).
+- Comparison schema: **1**; change contract: **"1"**; compatibility rules: **"1"**; identity scheme: **comparison-sha256-v1**
+- Deterministic catalogue-pair comparison with added/removed/modified/unchanged classification, signature-versus-implementation facets, and conservative move/rename candidates
+- Public API compatibility findings (`breaking`, `potentially_breaking`, `non_breaking`, `documentation_only`, `unknown`, `not_applicable`) with severity aggregation
+- Dependant-directed direct and transitive change impact with base/head and impact-delta reporting, bounded by depth/node/edge/path budgets
+- Deterministic source-free comparison artefacts with full identity, ordering, hash, and referential validation on load; rollback-safe replacement; path and lock-file security
+- CLI `diff`, `changes`, `compatibility`, `change-impact`, `drift`; MCP comparison tools and resources
+- Explicit read-only catalogue drift detection (in-memory indexing, no writes, no Git execution)
+- Mixed generator-version comparison (e.g. v0.7.0 base against v0.8.0 head)
+- Windows and Docker Linux qualification of one frozen tarball with matching cross-platform semantic artefact hashes
+
+Not tagged / not published until separately authorised.
+
+## 0.8.0-rc.3
+
+### Fixed
+
+- Loaded comparison artefacts recompute and verify comparison, change, candidate, and compatibility-finding identities; reject duplicate IDs, unsupported vocabularies, wrong deterministic ordering, and lock/manifest identity disagreement
+- Catalogue referential integrity covers authoritative Schema 2 forward references across public APIs, symbols, capabilities, tests, examples, relationships, and diagnostics (derived membership backlinks may warn)
+- Production comparison drift no longer executes Git or exposes filesystem/Git observation options
+- Comparison artefact directory replacement is transactional/rollback-safe (backup → install → cleanup) rather than delete-then-rename
+
+### Tests
+
+- Artefact semantic validation with content rewrite + lock rehash
+- Referential integrity failures across domains
+- Injectable filesystem failure injection for transactional replace
+- Packed/source guard that drift contains no Git subprocess invocation
+
+RC.1 and RC.2 remain historical evidence and were not rewritten.
+
+## 0.8.0-rc.2
+
+### Fixed
+
+- Impact traversal now follows **dependants** (reverse dependency edges), not outgoing dependency targets
+- Impact sections report truthful `total` / pagination (`offset`, `limit`, `truncated`) within bounded work budgets
+- Declaration `range` and relationship evidence line fields no longer create semantic modifications
+- Transition candidates require stronger fingerprint/structural evidence; global ambiguity resolution; budget exhaustion warnings
+- Console-script additions are `non_breaking`; removals/renames/target changes classified granularly
+- Stability transitions use an explicit matrix (not documentation-only for all stability facets)
+- `--fail-on any-public-change` ignores internal-only changes
+- Referential integrity validation before comparison (`comparison_referential_integrity_failed`)
+- Comparison artefact lock allowlist, path containment, size limits, atomic directory replace, and full load validation
+- Drift returns separate `driftClass` and `regenerationRecommendation`; filesystem observation for no-write verification
+
+### Tests
+
+- Expanded focused comparison suites (projections, compatibility, candidates, impact, store, CLI, security, validation, drift)
+
+RC.1 remains historical evidence and was not promoted.
+
+## 0.8.0-rc.1
+
+Release-candidate packaging of the v0.8 change-intelligence line. Same feature surface as `0.8.0-dev.0`; intended for packed Windows and Docker Linux qualification before final `0.8.0`.
+
+## 0.8.0-dev.0
+
+### Added
+
+- Gate 0 contracts and scenario freeze for deterministic catalogue comparison (`comparisonSchemaVersion: 1`, `changeContractVersion: "1"`, `compatibilityRuleVersion: "1"`, `comparison-sha256-v1`)
+- Deterministic catalogue comparison core (`src/comparison/`) with directional comparison IDs, domain projections, facets, and Model A artefact store
+- Public API compatibility analysis with severity aggregation and Schema 2 signature feasibility fallbacks
+- Move/rename transition candidates (public surface, declarations, files) under bounded work budgets
+- Bounded base/head change impact from persisted graph indexes
+- CLI: `diff`, `changes`, `compatibility`, `change-impact`, `drift`
+- MCP: `compare_catalogues`, `load_comparison`, `get_change_summary`, `list_changes`, `get_change`, `get_compatibility_report`, `get_change_impact`, `check_catalogue_drift`
+- MCP resources: `code-atlas://comparison/summary|changes|compatibility`
+- Docs: `docs/change-intelligence.md`, `docs/compatibility-analysis.md`, `docs/change-impact.md`, `docs/comparison-artefacts.md`, `docs/release-v0.8.md`
+## 0.7.0
+
+Code Atlas **v0.7.0**.
+
+- Catalogue `schemaVersion`: **2**
+- Required `identityScheme`: **stable-sha256-v1**
+- Includes corrective canonicalisation (Category A + Category B module topology), ranking, bounded MCP resources, and RC.2 qualification fixes
+- Final tarball `code-atlas-mcp-0.7.0.tgz` SHA-256 `ac7f0455be53e7b29d6c4e491aeda57e76c6d7d46443b98baeabca0590fecf86` (host/Windows/Docker/Pass A/security qualified)
+
+Not tagged / not published until separately authorised.
+
+## 0.7.0-rc.2
+
+### Fixed
+
+- Source/generated canonicalisation now requires Category A declaration equivalence **and** Category B module topology mapping (`src` ↔ `dist`/`build`/`out` or colocated `.ts`/`.d.ts`). Package/name/kind alone no longer collapses declarations.
+- Provenance semantics: collapsed generated records use `generated_declaration` (not `generated_only`); inconsistent provenance is validated.
+- Relationship remapping merges duplicate semantic edges and evidence ranges after canonicalisation.
+- Identity collision checks register canonical preimages for packages, symbols, public APIs, tests, relationships, capabilities, examples, and diagnostics.
+
+### Tests
+
+- Added dedicated canonicalisation and indexing-level identity collision coverage.
+- Requalified Windows + Docker Linux packed MCP installs, StyleFrameWork Pass A, and security boundaries against tarball `0bbf3e516d44213cee339e39d67c5979a9cb47f475277082acfa332dc7d01abc`.
+
+## 0.7.0-rc.1
+
+Release-candidate packaging of the v0.7 retrieval-quality work. Same feature surface as `0.7.0-dev.0` development line; intended for packed Windows and Docker Linux qualification before final `0.7.0`.
+
+## 0.7.0-dev.0
+
+### Breaking
+
+- Catalogue `schemaVersion` is now **2**. Schema 1 catalogues fail with `catalogue_upgrade_required` and must be regenerated.
+- Required catalogue field `identityScheme: "stable-sha256-v1"`.
+- Stable IDs no longer embed source line numbers. Package, declaration, public export, test, and relationship identities use fixed SHA-256 digests.
+- Public API IDs are independent of declaration location (package + consumer import path + exported name + kind).
+- MCP search tools return ranked paginated envelopes; collection resources are bounded with list-tool continuation.
+
+### Added
+
+- Canonical identity encoder (`stable-sha256-v1`) with NFC + JSON-array preimages
+- Source/generated canonicalisation (Category A + B mapping evidence)
+- Deterministic ranking with hard filters, query-specific policies, and per-result `matchReasons`
+- Bounded `list_*` tools and windowed MCP resources with semantic ordering
+- Conservative `resolved_direct_import` / `resolved_direct_usage` linkage
+- Stronger Python public surface (`__all__`, `__init__` re-exports, `project.scripts`, import package fields)
+- Opt-in bounded `editingContext` on context tools
+- Read-only `recommend_config` MCP tool and CLI command
+
+### Changed
+
+- Package identity always includes ecosystem + name/unnamed + package root
+- Relationship semantic endpoints use canonical symbol IDs
+- Generator/package version set to `0.7.0-dev.0` for schema-2 development
+
+## 0.6.0
+
+### Added
+
+- MCP `load_committed_catalogue` for consuming committed snapshots without source indexing
+- Deterministic committed-catalogue compatibility checks and error codes
+- Shared `catalogue_not_loaded` helper/message for MCP tools and resources
+- Fail-closed source-preview path and binary exclusions
+- Cross-repository generalisation dogfooding evidence
+- Cross-platform packed-install qualification (Windows host + Docker Linux)
+- Release documentation for installation, MCP configuration, and catalogue compatibility
+
+### Changed
+
+- Public API import paths prefer package-root/subpath guidance when export-reachable
+- Package manifest names take precedence over earlier markdown/path seeds
+- `typescript` is a runtime dependency for packed MCP installs
+- MCP resources serve the loaded snapshot only
+- Package version set to `0.6.0`
+
+### Fixed
+
+- Windows MCP server entrypoint startup using `fileURLToPath`
+- Packed installation failure caused by missing runtime TypeScript dependency
+- Workspace path boundary checks for source preview escapes
+
+## 0.6.0-rc.1
+
+Release-candidate packaging and generalisation baseline retained as historical evidence.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mortice Mapwright contributors
+
+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,262 @@
+# Mortice Mapwright
+
+Mortice Mapwright is a standalone MCP server and CLI that builds an agent-facing catalogue of repository capabilities, public APIs, symbols, files, tests, and diagnostics.
+
+## Relationship to Mortice
+
+Mapwright is a standalone deterministic repository catalogue and change-intelligence
+tool within the Mortice toolkit. It remains usable independently and does not depend
+on Mortice workflow orchestration.
+
+## What problem this solves
+Coding agents need a reliable way to discover and reuse existing code before creating new code. Mortice Mapwright provides a structured catalogue layer over a repository so agents can query capabilities, public APIs, symbols, tests, and diagnostics without defaulting to raw source reads.
+
+## What v0.1 does
+- Indexes a workspace with deterministic output in .mapwright.
+- Extracts metadata from TypeScript or JavaScript JSDoc and Python docstrings.
+- Parses CATALOGUE.md package or capability metadata.
+- Produces relationships and diagnostics for docs and reference quality.
+- Serves catalogue data through CLI commands and MCP tools.
+
+## What v0.2 adds
+- Import and export relationship extraction for TypeScript, JavaScript, and Python.
+- Conservative package boundary modeling from manifests, docs, and directory layout.
+- Dependency neighborhood querying through MCP.
+- Improved public API import-path metadata where entrypoints are detectable.
+- Evidence text in relationship records is bounded and metadata-first.
+- Package IDs are path-aware so nested packages do not collide.
+
+## What v0.3 starts
+- Richer authored CATALOGUE.md parsing for package and capability reuse context.
+- First-class example records with metadata-only references.
+- Rich capability and public API context bundles through query/MCP surfaces.
+- Deterministic metadata-only reuse candidate search with explainable reasons.
+- Diagnostics for missing or broken authored reuse documentation.
+
+## What v0.4 focuses on
+- Adoption tooling for retrofitting Mortice Mapwright documentation into real repositories.
+- Deterministic audit outputs that highlight missing package, capability, and public API docs.
+- Grouped adoption plans ordered by deterministic priority tiers.
+- Static conservative documentation templates for package and API metadata authoring.
+
+## What v0.5 focuses on
+- Dogfooding and quality calibration on realistic repositories.
+- Compact evaluation reports that summarize diagnostics and adoption gaps.
+- Clear methodology for deciding whether findings are bugs or expected limitations.
+- Practical guidance for maintainer-facing review and next-step decisions.
+
+## What v0.7 focuses on
+- Stable package, declaration, public-export, test, and relationship identities (`stable-sha256-v1`).
+- Schema 2 clean break; schema 1 requires regeneration (`catalogue_upgrade_required`).
+- Deterministic search ranking with hard filters and per-result `matchReasons`.
+- Bounded MCP collection resources and explicit `list_*` continuation.
+- Conservative provenanced import/usage linkage and stronger Python public surfaces.
+- Opt-in bounded editing context and read-only configuration recommendations.
+
+## What v0.6 focuses on
+- Cross-repository generalisation beyond StyleFrameWork.
+- Committed-catalogue MCP consumption without eager source indexing.
+- Packed-package installation and catalogue compatibility for v0.6.0.
+- Package-root/subpath import guidance and clearer empty-state MCP errors.
+
+## What v0.8 adds
+- Deterministic comparison of two committed catalogues with stable comparison IDs (`comparison-sha256-v1`).
+- Added/removed/modified/unchanged change records with signature-versus-implementation facets.
+- Conservative move and rename transition candidates with explicit ambiguity handling.
+- Public API compatibility findings and severity aggregation (breaking → not-applicable).
+- Dependant-directed direct and transitive change impact with truthful pagination and bounded work budgets.
+- Source-free comparison artefacts validated on load (identities, ordering, hashes, references) and replaced rollback-safely.
+- CLI `diff`, `changes`, `compatibility`, `change-impact`, and `drift`; matching MCP tools and resources.
+- Explicit read-only drift detection: indexes the workspace in memory, writes nothing, executes no Git.
+- Renamed from Code Atlas to Mapwright (`@mortice/mapwright`) before first public distribution. Frozen identity/comparison namespace strings from the pre-release Code Atlas era are preserved for ID stability; catalogues that still carry a `code-atlas` generator name continue to load. The toolkit namespace was corrected from Mortise to Mortice immediately before first public npm distribution; see [docs/naming.md](docs/naming.md).
+
+## Version metadata
+- `schemaVersion` identifies the catalogue JSON schema compatibility level (v0.7 → **2**).
+- `identityScheme` identifies the persisted identity encoding (`stable-sha256-v1`).
+- `generator.version` identifies the Mapwright package version that produced the snapshot.
+- `rankingContractVersion` is emitted by the running query implementation (not catalogue truth).
+
+## Install
+
+```bash
+npm install -g @mortice/mapwright
+```
+
+```bash
+npx -y @mortice/mapwright
+```
+
+Local development:
+
+```bash
+npm install
+npm run build
+```
+
+See [docs/installation.md](docs/installation.md).
+
+## Build
+```bash
+npm run build
+```
+
+## Test
+```bash
+npm test
+```
+
+## CLI usage
+```bash
+mapwright index --workspace .
+mapwright validate --workspace .
+mapwright check --workspace . --fail-on warning
+mapwright schema
+mapwright audit-docs --workspace .
+mapwright adoption-plan --workspace .
+mapwright template package-catalogue
+mapwright template --list
+mapwright dogfood --workspace .
+```
+
+Equivalent local runs without global install:
+```bash
+npm run cli -- index --workspace .
+npm run cli -- validate --workspace .
+npm run cli -- schema
+npm run cli -- audit-docs --workspace .
+npm run cli -- adoption-plan --workspace .
+npm run cli -- template package-catalogue
+npm run cli -- template --list
+npm run cli -- dogfood --workspace .
+```
+
+## v0.4 adoption examples
+
+Audit-docs command returns a stable envelope with summary, gaps, and recommendations:
+
+```json
+{
+	"ok": true,
+	"data": {
+		"summary": {
+			"gapsTotal": 12,
+			"gapsReturned": 12,
+			"gapsTruncated": false
+		},
+		"gaps": [],
+		"recommendations": []
+	},
+	"warnings": [],
+	"provenance": {
+		"source": "mapwright"
+	}
+}
+```
+
+Adoption-plan command groups recommendations by deterministic priority order:
+
+```json
+{
+	"ok": true,
+	"data": {
+		"groupedRecommendations": [
+			{ "priority": "high", "recommendations": [] },
+			{ "priority": "medium", "recommendations": [] },
+			{ "priority": "low", "recommendations": [] }
+		]
+	},
+	"warnings": [],
+	"provenance": {
+		"source": "mapwright"
+	}
+}
+```
+
+Template command returns metadata plus static content, and templates always include TODO placeholders:
+
+```json
+{
+	"ok": true,
+	"data": {
+		"templateId": "package-catalogue",
+		"title": "Package CATALOGUE scaffold",
+		"description": "Markdown scaffold for package metadata and one initial capability section.",
+		"surface": "markdown",
+		"content": "# Catalogue\n... TODO ..."
+	},
+	"warnings": [],
+	"provenance": {
+		"source": "mapwright"
+	}
+}
+```
+
+## Run MCP server
+```bash
+npm run mcp
+# or from a packed install:
+npx -y @mortice/mapwright
+# or the MCP executable directly:
+mapwright-mcp
+```
+
+Preferred agent load path: `load_committed_catalogue` then `get_workspace_overview` / `mapwright://packages`.
+
+If no catalogue is loaded, tools return: `Run load_committed_catalogue or index_workspace first.`
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "mapwright": {
+      "command": "npx",
+      "args": ["-y", "@mortice/mapwright"]
+    }
+  }
+}
+```
+
+Where the MCP executable is invoked directly:
+
+```json
+{
+  "mcpServers": {
+    "mapwright": {
+      "command": "mapwright-mcp"
+    }
+  }
+}
+```
+
+See [docs/mcp-configuration.md](docs/mcp-configuration.md).
+
+## Docs
+- [docs/installation.md](docs/installation.md)
+- [docs/mcp-configuration.md](docs/mcp-configuration.md)
+- [docs/catalogue-compatibility.md](docs/catalogue-compatibility.md)
+- [docs/release-v0.6.md](docs/release-v0.6.md)
+- [docs/dogfooding/cross-repository-generalisation-v0.6.md](docs/dogfooding/cross-repository-generalisation-v0.6.md)
+- [docs/Code-Atlas-v0.1-Spec.md](docs/Code-Atlas-v0.1-Spec.md)
+- [docs/architecture.md](docs/architecture.md)
+- [docs/reuse-context.md](docs/reuse-context.md)
+- [docs/v0.1-current-state.md](docs/v0.1-current-state.md)
+- [docs/v0.2-roadmap.md](docs/v0.2-roadmap.md)
+- [docs/v0.3-roadmap.md](docs/v0.3-roadmap.md)
+- [docs/v0.4-roadmap.md](docs/v0.4-roadmap.md)
+- [docs/v0.5-roadmap.md](docs/v0.5-roadmap.md)
+- [docs/adoption.md](docs/adoption.md)
+- [docs/dogfooding.md](docs/dogfooding.md)
+- [docs/naming.md](docs/naming.md)
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [skills/](skills/)
+
+## Naming quick reference
+- Product: Mortice Mapwright
+- Package: @mortice/mapwright
+- CLI: mapwright
+- MCP binary: mapwright-mcp
+- Config: mapwright.config.json
+- Catalogue output dir: .mapwright
+- MCP resource namespace: mapwright://
+- Pre-release history: Code Atlas (frozen identity/comparison namespace strings only; see [docs/naming.md](docs/naming.md))

package/dist/catalogue/canonicalisation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Symbol canonicalisation for schema 2.
+ *
+ * Collapses a generated declaration onto an authored source only when both
+ * Category A (declaration equivalence beyond package/name/kind alone) and
+ * Category B (actual source↔output module mapping) hold.
+ */
+import type { DiagnosticRecord, SymbolRecord } from "./schema.js";
+export type SymbolProvenanceKind = "authored_source" | "generated_declaration" | "generated_only";
+/** Path is under a build output tree (dist/build/out). */
+export declare function isBuildOutputPath(filePath: string): boolean;
+/**
+ * A symbol is treated as generated when its file is a build artefact, is a
+ * declaration file, or its provenance already marks it as generated.
+ */
+export declare function isGeneratedSymbol(symbol: SymbolRecord): boolean;
+/**
+ * Strip a single source or generated root segment and the file extension so
+ * relative module topology can be compared (e.g. src/a/b.ts ↔ dist/a/b.d.ts).
+ */
+export declare function moduleTopologyKey(filePath: string): string;
+/** Category B: authored and generated files share module topology after src↔emit transform. */
+export declare function hasSourceOutputMapping(authored: SymbolRecord, generated: SymbolRecord): boolean;
+/**
+ * Category A: declaration equivalence stronger than package+name+kind alone.
+ * Requires matching qualified declaration identity (container + name) and kind,
+ * plus compatible signature fingerprint when both are present.
+ */
+export declare function categoryACompatible(a: SymbolRecord, b: SymbolRecord): boolean;
+export declare function validateSymbolProvenance(symbol: SymbolRecord): string | undefined;
+/**
+ * Assign canonical identities to symbols in place.
+ *
+ * Returns a map from collapsed duplicate symbol id to its canonical symbol id.
+ */
+export declare function canonicaliseSymbols(symbols: SymbolRecord[], diagnostics: DiagnosticRecord[]): Map<string, string>;