refactor: Ubiquitous Language — MasterDataset → PatternGraph, ProcessStateAPI → PatternGraphAPI#41
Closed
darko-mijic wants to merge 6 commits intomainfrom
Closed
refactor: Ubiquitous Language — MasterDataset → PatternGraph, ProcessStateAPI → PatternGraphAPI#41darko-mijic wants to merge 6 commits intomainfrom
darko-mijic wants to merge 6 commits intomainfrom
Conversation
…lignment Align internal code vocabulary with product terminology per the naming review (ideation docs 04-05). "PatternGraph" communicates structure and content; "MasterDataset" was generic and required translation in every AI session. Tier 1 (core types): - MasterDataset → PatternGraph (type, schema, all references) - RuntimeMasterDataset → RuntimePatternGraph - buildMasterDataset() → buildPatternGraph() - transformToMasterDataset() → transformToPatternGraph() - GeneratorContext.masterDataset → GeneratorContext.patternGraph - @architect-shape master-dataset → @architect-shape pattern-graph Tier 2 (API layer): - ProcessStateAPI → PatternGraphAPI - createProcessStateAPI() → createPatternGraphAPI() File renames: - master-dataset.ts → pattern-graph.ts - process-state.ts → pattern-graph-api.ts - process-state-api test/spec files → pattern-graph-api No logic changes. No backward compatibility. All 8,808 tests pass. 304 files changed across source, tests, specs, and documentation.
…cli rename Wave 2: Renamed ProcessStateAPI implementation layer - ProcessAPICLIImpl → PatternGraphCLIImpl (type + annotations) - ProcessApiReferenceGenerator → CliReferenceGenerator - ProcessStateTypes → PatternGraphAPITypes - process-api.ts → pattern-graph-cli.ts (CLI entry point) - PROCESS-API-REFERENCE.md → CLI-REFERENCE.md (output file) - 14 file renames (source, specs, tests, docs-sources) Wave 3: CLI test infrastructure - All test command strings: "process-api ..." → "pattern-graph-cli ..." - @process-api tags → @pattern-graph-cli - loadFeature() paths updated for renamed test files Wave 4: Documentation and natural language - Stale JSDoc "Master Dataset" → "PatternGraph" in schema - Stale comments in barrel exports and spec text - Broken import path in docs/ARCHITECTURE.md - All remaining "process-api" in CLAUDE.md, specs, docs All 8,808 tests pass. 152 files changed.
|
Important Review skippedToo many files! This PR contains 225 files, which is 75 over the limit of 150. ⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (75)
📒 Files selected for processing (225)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…enames, external agent gaps - Rename MasterPhaseGroup → SchemaPhaseGroup (vestige of old naming in import alias) - Fix "Process API Reference/Recipes" → "CLI Reference/Recipes" in doc index tables - Fix "Process API coverage" → "Pattern Graph CLI coverage" in SESSION-WORKFLOW-GUIDE - Accept external agent fixes: Process State API → Pattern Graph API in comments, ProcessAPILayeredExtraction → PatternGraphLayeredExtraction in specs/tags, generator titles, config paths, and PROCESS-API-RECIPES.md deletion
…d modules Sweep residual stale terminology from two rename waves: - MasterDataset→PatternGraph, ProcessStateAPI→PatternGraphAPI (this PR) - process:query→architect:query, lint-process→architect-guard (prior rebrand) Manual fixes: 7 _claude-md modules, 5 feature specs (with unlock-reason tags for completed specs), AGENTS.md paths, 4 docs/ files, memory files. Regenerated CLAUDE.md and all docs-live/ from updated sources.
- Rename deprecated PROCESS-API.md pointer file to CLI.md - Update all 60+ references across src, specs, stubs, and docs - Fix cli-reference-generator link to point to non-deprecated CLI-RECIPES.md - Update .coderabbit.yaml to exclude all .md files from review (reduces file count below 150-file limit that caused "Review skipped") - Regenerate all docs to propagate rename through pipeline
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Aligns internal code vocabulary with the product's ubiquitous language. Every type, function, file, annotation, test, spec, and documentation reference now speaks the same language as the product, the customer-facing materials, and the engineering team.
The Problem
The codebase used
MasterDatasetfor its core data structure andProcessStateAPIfor its query interface — generic internal names that communicated nothing about the product's domain. Every AI session and every new contributor had to maintain a mental translation layer between what the code said and what the product meant. In a project whose core principle is "code is the single source of truth," the code's vocabulary was contradicting the product's vocabulary.The Principle
Domain-Driven Design's ubiquitous language: code, documentation, and conversation should all use the same vocabulary. When product docs say "pattern graph" but the code says
MasterDataset, every interaction — human or AI — pays a translation tax.What Changed
Core abstraction rename:
MasterDatasetPatternGraphMasterDatasetSchemaPatternGraphSchemaRuntimeMasterDatasetRuntimePatternGraphbuildMasterDataset()buildPatternGraph()transformToMasterDataset()transformToPatternGraph()GeneratorContext.masterDatasetGeneratorContext.patternGraphAPI layer rename:
ProcessStateAPIPatternGraphAPIcreateProcessStateAPI()createPatternGraphAPI()ProcessAPICLIImplPatternGraphCLIImplProcessApiReferenceGeneratorCliReferenceGeneratorFile renames (20 total):
Source files:
validation-schemas/master-dataset.ts→pattern-graph.tsapi/process-state.ts→pattern-graph-api.tscli/process-api.ts→pattern-graph-cli.tsgenerators/built-in/process-api-reference-generator.ts→cli-reference-generator.tsSpec and test files:
process-state-api-*.feature→pattern-graph-api-*.featureprocess-api-*.feature→pattern-graph-cli-*.featureGenerated output:
PROCESS-API-REFERENCE.md→CLI-REFERENCE.mdScope
What Did NOT Change
architect_*)architect)@architect-*)@libar-dev/architect)architect.config.tsformatProcessState(lint module)DeriveProcessState(lint module)Breaking Changes
All consumer repos need updating. The public API exports changed:
PatternGraphAPI(wasProcessStateAPI)createPatternGraphAPI()(wascreateProcessStateAPI())PatternGraph(wasMasterDataset)buildPatternGraph()(wasbuildMasterDataset())pattern-graph.js(wasmaster-dataset.js),pattern-graph-api.js(wasprocess-state.js)No backward-compatibility aliases. No deprecation period.
Design Decisions
"PatternGraph" over "PatternDataset" — The product vocabulary uses "pattern graph" in all customer-facing materials. Structural accuracy ("it's a dataset with optional graph indexes") yields to ubiquitous language alignment ("customers think in terms of a pattern graph").
Single atomic commit per rename wave — No intermediate states with mixed vocabulary.
git blamecost is acceptable for a mechanical rename.CliReferenceGeneratoroverPatternGraphReferenceGenerator— The generator produces CLI documentation, not pattern graph documentation. The name describes what it generates.ProcessStatekept in lint module —ProcessStateinsrc/lint/process-guard/represents the actual delivery process state (files, sessions, FSM). This is a different concept from thePatternGraphAPIquery interface. Renaming it would be semantically wrong.Test Plan
pnpm build— zero TypeScript compilation errorspnpm typecheck— all type references resolvepnpm lint— no unused imports or naming violationspnpm test— 8,808 tests passing (142 test files)pnpm validate:all— 0 errors (anti-pattern + DoD validation)pnpm docs:all— all generated docs use new terminology