@memoarchitect/tools 0.6.7 → 0.7.2

package/packages/tools/lib/model/project-conversion.d.ts

@@ -0,0 +1,226 @@
+/** One file the conversion relocates, rewrites, or both. */
+export interface ConversionFileChange {
+    /** Path relative to the project root, before conversion. */
+    from: string;
+    /** Path relative to the project root, after conversion. */
+    to: string;
+    /** Declared SysML package before conversion, when the file declares one. */
+    fromPackage?: string;
+    /** Declared SysML package after conversion. */
+    toPackage?: string;
+    /** Full file text after conversion. Undefined for binary payloads. */
+    content?: string;
+    /** Why this file changed, for the diff header. */
+    reasons: string[];
+}
+/** A file the conversion creates that had no pre-conversion counterpart. */
+export interface ConversionNewFile {
+    path: string;
+    content: string;
+    reason: string;
+}
+/**
+ * A refusal. A plan carrying collisions is never applied.
+ *
+ * Collisions are reported as a complete list rather than thrown one at a time:
+ * a user converting a real project wants to see every clash in one pass, not to
+ * discover the second one after fixing the first.
+ */
+export interface ConversionCollision {
+    code: 'destination-conflict' | 'package-name-conflict' | 'destination-occupied' | 'no-project-prefix' | 'referenced-superseded-entrypoint' | 'unparsed-package';
+    message: string;
+    files: string[];
+}
+export interface ConversionWarning {
+    code: 'package-not-mirroring' | 'unclassified-view' | 'vendored-reusable-package' | 'legacy-settings-file' | 'superseded-entrypoint' | 'unresolved-import';
+    message: string;
+    file?: string;
+}
+export interface ConversionPlan {
+    projectRoot: string;
+    /** Package-name prefix every project package shares, e.g. `memo_examples_gpca_pump`. */
+    projectPrefix: string;
+    /** True when the project is already in the target layout: applying is a no-op. */
+    alreadyConverted: boolean;
+    changes: ConversionFileChange[];
+    newFiles: ConversionNewFile[];
+    /** Legacy semantic settings files the conversion consumes and deletes. */
+    removals: string[];
+    /** old package name → new package name, for every renamed package. */
+    packageRenames: Map<string, string>;
+    collisions: ConversionCollision[];
+    warnings: ConversionWarning[];
+}
+/**
+ * The package a file declares, and the constructs it holds.
+ *
+ * This is deliberately a light regex read rather than a Langium parse. The
+ * converter's job is textual — move a file, rename a package, follow the
+ * references — and it must work on files that do not fully parse, which is
+ * exactly the state a stale pre-conversion project is in. Anything that needs
+ * real semantics (which viewpoint a view belongs to) is read as a declaration,
+ * not evaluated.
+ */
+interface SourceFacts {
+    packageName?: string;
+    /** `view <name> : <Type>` usages declared in the file. */
+    viewUsages: string[];
+    /** `viewpoint <name>` usages declared in the file. */
+    viewpointUsages: string[];
+    /** Name bound by `part :>> viewpointDefinition = <name>;`. */
+    viewpointDefinition?: string;
+    /** Package names this file imports. */
+    imports: string[];
+    /**
+     * True when the package body holds imports and nothing else — a re-export
+     * wrapper rather than model content.
+     */
+    declaresOnlyImports: boolean;
+}
+export declare function readSourceFacts(text: string): SourceFacts;
+/**
+ * Longest `_`-separated prefix shared by every project package.
+ *
+ * Derived rather than configured, because the prefix is already a fact about
+ * the project's source: whatever the packages agree on is the project's
+ * namespace. Trailing structural segments are dropped so that a project whose
+ * packages are all called `x_model_catalog_*` yields `x`, not `x_model_catalog`
+ * — those segments describe where files sit, and the whole point of the
+ * conversion is that the directory tree carries that instead.
+ */
+export declare function deriveProjectPrefix(packageNames: string[], sharedDirSegments?: string[]): string | undefined;
+/**
+ * The package name a file at `catalogRelPath` should declare.
+ *
+ * Namespace mirroring, mechanically: prefix, then the directory chain, then the
+ * basename — except where the basename only restates the directory it sits in.
+ */
+export declare function derivePackageName(prefix: string, catalogRelPath: string): string;
+/**
+ * Whether an in-place file's declared package already mirrors its location.
+ *
+ * Two forms are accepted: the canonical one `derivePackageName` emits, and the
+ * same name with the trailing basename segment dropped. Both place the package
+ * at or under its directory's namespace, which is what mirroring means. The
+ * short form is accepted rather than "corrected" because rewriting a package
+ * name is a real edit to a user's model, and MEMO's own hand-authored catalog
+ * uses it — a converter that churned those files would fail its own
+ * idempotence test for a purely cosmetic reason.
+ */
+export declare function isMirroringPackageName(name: string, prefix: string, catalogRelPath: string): boolean;
+export type FileRole = 'catalog' | 'view' | 'viewpoint' | 'entrypoint' | 'vendored-reusable' | 'legacy-entrypoint';
+/**
+ * Where a source file belongs after conversion.
+ *
+ * The classification is structural — a file's current directory and the
+ * constructs it declares — and never guesses at ontology layer. Deciding that
+ * `gpca_risk.sysml` "is" safety/risk content would mean the converter forming
+ * an opinion about model semantics, and getting that wrong silently relocates a
+ * user's model into a namespace they did not choose. Files already inside the
+ * catalog therefore keep their place; only files outside it, whose location is
+ * unambiguously wrong under section 6.2, are moved.
+ */
+export declare function classifyFile(relPath: string, facts: SourceFacts, viewpointGroup: (viewpointUsage: string) => string): {
+    role: FileRole;
+    to: string;
+};
+/**
+ * Directory name for the viewpoint a view is governed by.
+ *
+ * Prefers the directory the reusable viewpoint's own source sits in, so a
+ * project's `viewpoints/risk/` lines up with the ontology's
+ * `src/viewpoints/risk/`. Falls back to the usage name with its `Viewpoint`
+ * suffix removed.
+ */
+export declare function viewpointGroupName(usageName: string, declaringFileByUsage: Map<string, string>): string;
+/**
+ * Rewrite package references in `text` according to `renames`.
+ *
+ * Word-boundary anchored and applied longest-name-first, because package names
+ * nest: renaming `a_b` before `a_b_c` would corrupt every reference to the
+ * longer name. Comments and doc strings are rewritten too — deliberately, since
+ * a stale package name in a comment is a documentation defect the conversion
+ * would otherwise create.
+ */
+export declare function rewritePackageReferences(text: string, renames: Map<string, string>): string;
+/**
+ * Rewrite the file's own `package <name>` declaration.
+ *
+ * Separate from reference rewriting because a file's declaration is renamed
+ * even when nothing else refers to it, and because the declaration is the one
+ * occurrence that must change exactly once.
+ */
+export declare function rewritePackageDeclaration(text: string, toPackage: string): string;
+/**
+ * Rewrite model-owned payload URIs to follow their payload files.
+ *
+ * Artifact identities carry a project-relative URI (`imageUri`, `uri`,
+ * `payloadUri`, `sourceUri`). When the payload moves, an unrewritten URI leaves
+ * the artifact pointing at nothing, and the hash check that would have caught
+ * it passes vacuously because the file is simply absent. This is the quietest
+ * failure the conversion could produce, so it is handled explicitly rather than
+ * left to the package-reference pass.
+ */
+export declare function rewriteArtifactUris(text: string, moves: Map<string, string>): string;
+export interface PlanOptions {
+    /**
+     * Viewpoint usage name → file that declares it, across the resolved
+     * reusable closure. Supplied by the command, which has already resolved the
+     * project; the planner stays free of resolution so it can be tested on a
+     * directory alone.
+     */
+    viewpointDeclarations?: Map<string, string>;
+    /** Package name → the reusable package that declares that viewpoint usage. */
+    viewpointPackages?: Map<string, string>;
+    /**
+     * Also rename packages of files that do not move but whose declared name
+     * does not mirror their location.
+     *
+     * Off by default. Renaming a package a user chose is a real edit to their
+     * model with no functional payoff — the file already sits where it belongs,
+     * and only the spelling of its namespace is off. Reporting it as a warning
+     * lets the owner decide. MEMO's own corpus turns it on, because a shipped
+     * example whose packages still spell `…_model_catalog_…` is demonstrating
+     * the layout the catalog replaced.
+     */
+    normalizeNames?: boolean;
+}
+/**
+ * Describe, without writing anything, the conversion of `projectRoot`.
+ *
+ * Every disk write in this module happens in `applyConversion`. That split is
+ * what makes `--dry-run` trustworthy: dry-run is not a flag threaded through
+ * the write path that might be missed on one branch, it is the absence of a
+ * call to the only function that writes.
+ */
+export declare function planConversion(projectRoot: string, options?: PlanOptions): ConversionPlan;
+/**
+ * A human-readable description of the plan.
+ *
+ * Deliberately not a unified content diff by default: the conversion's changes
+ * are overwhelmingly moves and one-token renames, and a line-level diff of
+ * twenty relocated files buries the two facts a reviewer needs — what moved,
+ * and what got renamed. `--diff` adds the content hunks on top of this.
+ */
+export declare function renderPlan(plan: ConversionPlan, options?: {
+    diff?: boolean;
+}): string;
+export interface ApplyResult {
+    written: string[];
+    moved: string[];
+    created: string[];
+    removed: string[];
+}
+/**
+ * The only function in this module that writes.
+ *
+ * It refuses a plan carrying collisions, and it refuses to duplicate: a move
+ * writes the destination and removes the source, so a half-applied conversion
+ * leaves one copy of each file rather than two divergent ones. Directories left
+ * empty by the moves are pruned, because an empty `model/views/` beside
+ * `model/catalog/viewpoints/` is exactly the superseded layout the conversion
+ * exists to eliminate.
+ */
+export declare function applyConversion(plan: ConversionPlan): ApplyResult;
+export {};
+//# sourceMappingURL=project-conversion.d.ts.map

package/packages/tools/lib/model/project-conversion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-conversion.d.ts","sourceRoot":"","sources":["../../src/model/project-conversion.ts"],"names":[],"mappings":"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"}