@owlmeans/viable-common 0.0.44 → 0.0.45

package/src/convert/origin.ts

@@ -0,0 +1,33 @@
+import { CONVERTED_ORIGIN_DIR, ORIGIN_CARD_MAX_CHARS } from './consts.js'
+import type { ArchitectureCase } from './consts.js'
+import type { ConversionOriginHelper, OriginCard } from './origin/types.js'
+
+export const createConversionOriginHelper = (): ConversionOriginHelper => {
+  const originCardChars = (card: OriginCard): number => [
+    card.stack as string,
+    card.case as ArchitectureCase as string,
+    card.purpose,
+    ...card.packages,
+    ...card.entities,
+    ...card.flows,
+    ...card.conventions,
+  ].reduce((total, part) => total + (part?.length ?? 0), 0)
+
+  const originCardFits = (card: OriginCard): boolean =>
+    originCardChars(card) <= ORIGIN_CARD_MAX_CHARS
+
+  const isOriginPath = (path: string): boolean =>
+    path === CONVERTED_ORIGIN_DIR || path.startsWith(`${CONVERTED_ORIGIN_DIR}/`)
+
+  const originPath = (relative: string): string => {
+    const path = relative.replace(/^\/+/, '')
+    if (path === '') return CONVERTED_ORIGIN_DIR
+    if (isOriginPath(path)) return path
+
+    return `${CONVERTED_ORIGIN_DIR}/${path}`
+  }
+
+  return { originCardChars, originCardFits, isOriginPath, originPath }
+}
+
+export const conversionOriginHelper = createConversionOriginHelper()

package/src/convert/record/types.ts

@@ -0,0 +1,105 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type { ConnectLlm } from '../../connect/consts.js'
+import type {
+  ArchitectureCase, ConversionStage, ConvertibilityReason, ConvertibilityVerdict, OriginKind, StackFamily,
+  StackId, WorkspaceKind
+} from '../consts.js'
+import type { ConversionEstimate } from '../estimate/types.js'
+
+/**
+ * A question the conversion answered for itself rather than asking.
+ *
+ * The web runs the inquiry policy `default`, so nothing blocks on a person who is not there. Every
+ * defaulted answer is recorded — what was asked, what was assumed and why — and shown, because an
+ * assumption nobody can see is indistinguishable from a fact.
+ */
+export interface ConversionAssumption {
+  id: string
+  question: string
+  assumed: string
+  because: string
+  at: string
+}
+
+/** One asked-and-answered inquiry, as `docs/conversion/inquiries.md` records it. */
+export interface InquiryRecord {
+  id: string
+  question: string
+  kind: string
+  answer?: string | string[]
+  text?: string
+  declined?: boolean
+  at: string
+}
+
+/**
+ * What the LIBRARY knows about a conversion — the state it writes and reads back on the volume.
+ *
+ * Distinct from the platform's conversion record: the library never touches a platform record, and
+ * the platform never keeps the library's working state. This is what survives on the target's own
+ * disk so a resumed or re-entered conversion knows where it was.
+ */
+export interface ConversionSnapshot {
+  stage: ConversionStage
+  originKind: OriginKind
+  stack?: StackId
+  case?: ArchitectureCase
+  verdict?: ConvertibilityVerdict
+  reasons?: ConvertibilityReason[]
+  estimates?: ConversionEstimate[]
+  assumptions?: ConversionAssumption[]
+  originPresent: boolean
+  answers?: Record<string, string | string[]>
+  storyCodes?: string[]
+  lastError?: string
+  updatedAt: string
+}
+
+/** One answer, as the platform carries it into a resume. */
+export interface ConversionAnswer {
+  inquiryId: string
+  value?: string
+  declined?: boolean
+}
+
+/** The stack, as the platform shows it. Display shape — the detection itself stays in the library. */
+export interface ConversionStackRef {
+  id: StackId
+  family: StackFamily
+  label: string
+  language: string
+  framework?: string
+}
+
+/** The census, narrowed to what the platform record keeps and the dialog shows. */
+export interface ConversionInventorySummary {
+  files: number
+  bytes: number
+  packages: number
+  workspace: WorkspaceKind
+  dumps: number
+  seeds: number
+  unlinked: string[]
+  truncated: boolean
+}
+
+/** The area/section/story tree the conversion dialog draws. */
+export interface ConversionStructure {
+  areas: {
+    area: ProjectArea
+    sections: {
+      name: string
+      stories: { code: string, title: string, primary?: boolean }[]
+    }[]
+  }[]
+}
+
+/** Set the profile-wide converter inference mode. */
+export interface ConverterLlmBody {
+  llmMode: ConnectLlm
+}
+
+/** Set the per-project converter inference mode; `null` inherits the profile's. */
+export interface ConverterProjectLlmBody {
+  llmMode: ConnectLlm | null
+}

package/src/convert/schemas.ts

@@ -3,16 +3,21 @@ import { ProjectArea } from '../areas/consts.js'
 import { ConnectLlm, CONNECT_INQUIRY_MAX_TEXT } from '../connect/consts.js'
 import { ModelRole } from '../execution/consts.js'
 import {
-  ArchitectureCase, ConversionStage, ConvertibilityReason, ConvertibilityVerdict, EstimateSlice,
-  OriginKind, OriginState, PurposeEvidenceSource, StackFamily, StackId, TaxonomyKind, WorkspaceKind
+  ArchitectureCase, ConversionStage, OriginKind, OriginState, PurposeEvidenceSource, StackFamily, StackId,
+  TaxonomyKind, WorkspaceKind
 } from './consts.js'
 import type {
-  AreaAlignment, ArchitectureVerdict, ConversionAnswer, ConversionEstimate,
-  ConversionInventorySummary, ConversionStackRef, ConversionStructure, ConverterLlmBody,
-  ConverterProjectLlmBody, DesignInference, OriginFlow, OriginFlowList, OriginProof,
-  ProjectOrigin, PurposeInference, SeedDetection, StackConfirmation, StoryEstimateBand, StoryProof,
-  TaxonomyEntry, TaxonomyEntryList, TaxonomyRoleList
-} from './types.js'
+  AreaAlignment, DesignInference, OriginFlow, OriginFlowList, PurposeInference, StoryProof
+} from './analysis/types.js'
+import type { SeedDetection } from './census/types.js'
+import type { ArchitectureVerdict, StackConfirmation } from './detection/types.js'
+import type { ConversionEstimate, StoryEstimateBand } from './estimate/types.js'
+import type {
+  ConversionAnswer, ConversionInventorySummary, ConversionStackRef, ConversionStructure, ConverterLlmBody,
+  ConverterProjectLlmBody
+} from './record/types.js'
+import type { TaxonomyEntry, TaxonomyEntryList, TaxonomyRoleList } from './taxonomy/types.js'
+import type { OriginProof, ProjectOrigin } from './types.js'
 
 /**
  * Two populations of schema live in this file, and they are written differently on purpose.
@@ -659,7 +664,3 @@ export const ConverterProjectLlmBodySchema = {
   additionalProperties: false,
 } as unknown as JSONSchemaType<ConverterProjectLlmBody>
 
-/** The reasons a convertibility verdict can carry, for a consumer building its own enum check. */
-export const ConvertibilityReasonValues = Object.values(ConvertibilityReason)
-export const ConvertibilityVerdictValues = Object.values(ConvertibilityVerdict)
-export const EstimateSliceValues = Object.values(EstimateSlice)

package/src/convert/stage/types.ts

@@ -0,0 +1,27 @@
+import type { ConversionDecision, ConversionStage } from '../consts.js'
+
+/** The conversion's stage ladder: what follows a stage, how to leave it, and what may be entered. */
+export interface ConversionStageHelper {
+  /**
+   * The stage after this one.
+   *
+   * The last stage answers with itself: there is nothing after implementation, and returning
+   * `undefined` would only move the same check to every call site.
+   */
+  stageAfter: (stage: ConversionStage) => ConversionStage
+  /**
+   * The decision that ADVANCES out of a stage.
+   *
+   * Implementation's is {@link ConversionDecision.Leave}, because a finished conversion has nothing
+   * further to run and leaving it as it stands is the ordinary outcome rather than an abandonment.
+   */
+  decisionFor: (stage: ConversionStage) => ConversionDecision
+  /**
+   * Whether a conversion at `from` may enter `to`.
+   *
+   * The same stage is legal — that is a retry. The next one is legal. Nothing else is: every stage
+   * reads the documents the stage before it wrote, so skipping one means running against documents
+   * that were never produced, and going back means overwriting the record a later stage is built on.
+   */
+  canEnter: (from: ConversionStage, to: ConversionStage) => boolean
+}

package/src/convert/stage.ts

@@ -0,0 +1,31 @@
+import { ConversionDecision, ConversionStage, CONVERSION_STAGE_ORDER } from './consts.js'
+import type { ConversionStageHelper } from './stage/types.js'
+
+export const createConversionStageHelper = (): ConversionStageHelper => {
+  const stageAfter = (stage: ConversionStage): ConversionStage => {
+    const at = CONVERSION_STAGE_ORDER.indexOf(stage)
+
+    return CONVERSION_STAGE_ORDER[at + 1] ?? stage
+  }
+
+  const decisionFor = (stage: ConversionStage): ConversionDecision => {
+    switch (stage) {
+      case ConversionStage.Intake: return ConversionDecision.Analyze
+      case ConversionStage.Analysis: return ConversionDecision.Extract
+      case ConversionStage.Extraction: return ConversionDecision.Implement
+      default: return ConversionDecision.Leave
+    }
+  }
+
+  const canEnter = (from: ConversionStage, to: ConversionStage): boolean => {
+    const at = CONVERSION_STAGE_ORDER.indexOf(from)
+    const next = CONVERSION_STAGE_ORDER.indexOf(to)
+    if (at < 0 || next < 0) return false
+
+    return next === at || next === at + 1
+  }
+
+  return { stageAfter, decisionFor, canEnter }
+}
+
+export const conversionStageHelper = createConversionStageHelper()

package/src/convert/taxonomy/types.ts

@@ -0,0 +1,74 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type { ArchitectureCase, TaxonomyKind } from '../consts.js'
+import type { OriginProof } from '../types.js'
+
+/** What the origin says about itself in prose — the cheapest and best evidence there is. */
+export interface HarnessDigest {
+  readme?: string
+  agents?: string
+  docs: { path: string, title: string, chars: number }[]
+  openapi: string[]
+  migrations: string[]
+  env: string[]
+  scripts: Record<string, string>
+  summary: string
+}
+
+export interface TaxonomyEntry {
+  name: string
+  path: string
+  kind: TaxonomyKind
+  symbol?: string
+  entity?: string
+  refs?: string[]
+  note?: string
+  proofs?: OriginProof[]
+}
+
+export interface TaxonomyPackage {
+  name: string
+  path: string
+  /** What this package does in the origin's own terms — `api`, `web`, `worker`, `db`, … */
+  role: string
+  entries: Partial<Record<TaxonomyKind, TaxonomyEntry[]>>
+}
+
+/** A role the origin's own access model names, mapped onto the area whose audience holds it. */
+export interface TaxonomyRole {
+  name: string
+  area: ProjectArea
+  evidence: OriginProof[]
+}
+
+export interface TaxonomyPermission {
+  name: string
+  roles: string[]
+  /** The origin's own guards, middlewares or decorators that enforce it. */
+  guards: string[]
+  evidence: OriginProof[]
+}
+
+export interface TaxonomySummary {
+  case: ArchitectureCase
+  packages: TaxonomyPackage[]
+  areas: ProjectArea[]
+  roles: TaxonomyRole[]
+  permissions: TaxonomyPermission[]
+  counts: Record<TaxonomyKind, number>
+  /** Where the origin does something its own stack's conventions do not explain. */
+  deviations: string[]
+  /** What a whole taxonomy would have needed and the origin does not carry. */
+  missingHarness: string[]
+  version: number
+}
+
+/** What one taxonomy layer's model call answers with. */
+export interface TaxonomyEntryList {
+  entries: TaxonomyEntry[]
+}
+
+/** What the access-model pass answers with — the roles and the permissions in one call. */
+export interface TaxonomyRoleList {
+  roles: TaxonomyRole[]
+  permissions: TaxonomyPermission[]
+}