@owlmeans/viable-common 0.0.43 → 0.0.45

package/src/convert/census/types.ts

@@ -0,0 +1,181 @@
+import type { DumpKind, EntropyClass, FileClass, SizeClass, WorkspaceKind } from '../consts.js'
+
+/**
+ * The census's file classification: pure, deterministic derivations over the conversion
+ * vocabulary.
+ *
+ * Everything here answers the same way for the same input, in every runtime, forever — which is
+ * what makes the documents a conversion writes byte-stable across two runs, and therefore what
+ * makes the prompt cache prefix they are injected into actually hit. Nothing here reads a file,
+ * calls a model or looks at a clock.
+ */
+export interface CensusHelper {
+  /** Which {@link SizeClass} a byte count falls in. Boundaries are exclusive upper bounds. */
+  sizeClassOf: (bytes: number) => SizeClass
+  /**
+   * What one file of the origin is.
+   *
+   * Location outranks the tail wherever it says more — a `.ts` under `__tests__/` is a test, a
+   * `.json` under `seed/` is data — but only where it says more. The seed/dump rule therefore runs
+   * AFTER the extension table and applies only to {@link DATA_OVERRIDABLE}: asked first, it answered
+   * `Data` for every path merely containing the word (`tests/fixtures/user.ts`, `src/seedUsers.ts`,
+   * `src/exportReport.ts`), which is the census's source budget spent on the wrong files twice over.
+   */
+  fileClassOf: (path: string, ext: string) => FileClass
+  /**
+   * The binary verdict a path already carries, or `null` for a file that has to be probed.
+   *
+   * The three executors that walk a tree — the library-local helper, the publisher and the connector
+   * SDK — must answer the same verdict for the same file, and a probe alone does not: a small `.ico`
+   * with no NUL in its first bytes reads as text, so a census run on a laptop and the same census
+   * run in the slot disagreed about the same repository. The tail is asked first and the probe only
+   * where the tail says nothing, which is also why the probe is affordable at census scale — the
+   * extensions above are the bulk of any repository.
+   *
+   * The extension is taken exactly the way `path.extname` takes it, because two of the three callers
+   * used to: the last dot of the last SEGMENT, and nothing for a name with no dot or for a dotfile.
+   */
+  binaryByExtension: (path: string) => boolean | null
+  /**
+   * How usable a file's head is as evidence.
+   *
+   * The printable ratio over the sampled head, and nothing cleverer: the question is only whether a
+   * model can read it. A minified bundle is printable and useless, so a second rule catches the
+   * shape that gives it away — very long lines with almost no whitespace.
+   */
+  entropyClassOf: (head: string) => EntropyClass
+  /** Whether a path names bulk data — an export, not the application's own data. */
+  isBulkPath: (path: string) => boolean
+  /** Whether a path names seed data — what the application needs in order to make sense. */
+  isSeedPath: (path: string) => boolean
+}
+
+/**
+ * {@link FileStat} is declared in `../../slot/types.js`, not here.
+ *
+ * It is the element of a `statTree` answer, and a slot command's result shape belongs to the slot
+ * vocabulary the publisher and the connector both implement. Redeclaring it beside the census that
+ * consumes it would give the root barrel two `FileStat`s and the two would drift the first time
+ * one end added a field.
+ */
+
+/** One file, as the census classified it. `read` says whether its head was actually opened. */
+export interface FileCensusEntry {
+  path: string
+  bytes: number
+  ext: string
+  cls: FileClass
+  size: SizeClass
+  entropy?: EntropyClass
+  read: boolean
+}
+
+/** A package manifest found in the origin, and what it declares. */
+export interface InventoryPackage {
+  name?: string
+  path: string
+  /** The manifest file itself, root-relative — `package.json`, `pom.xml`, `go.mod`, … */
+  manifest: string
+  /** `member` for a package a workspace root declares; otherwise the workspace kind it declares. */
+  kind: WorkspaceKind | 'member'
+  deps: string[]
+  scripts: Record<string, string>
+  /** Whether something in the tree actually reaches it. See {@link UnlinkedRef}. */
+  linked: boolean
+}
+
+export interface WorkspaceMember {
+  name?: string
+  path: string
+  /** The manifest that declared this member. */
+  declaredBy: string
+  present: boolean
+}
+
+export interface SubmoduleRef {
+  path: string
+  url?: string
+  present: boolean
+}
+
+/**
+ * A directory holding code that nothing in the workspace declares, or a declaration with nothing
+ * behind it.
+ *
+ * Reported rather than silently included: code the build never sees is code the origin does not
+ * run, and converting it produces stories for behaviour the application does not have.
+ */
+export interface UnlinkedRef {
+  path: string
+  reason: 'not-a-member' | 'missing-submodule' | 'declared-not-present'
+}
+
+export interface WorkspaceReport {
+  kind: WorkspaceKind
+  globs: string[]
+  members: WorkspaceMember[]
+  submodules: SubmoduleRef[]
+  unlinked: UnlinkedRef[]
+}
+
+/** A data file the origin carries that is too large, or too generated, to become seed data. */
+export interface DumpRecord {
+  path: string
+  kind: DumpKind
+  bytes: number
+  format: string
+  rows?: number
+  /** At most {@link DUMP_SAMPLE_LINES} lines, read from the head. Never the whole file. */
+  sample: string[]
+  columns?: string[]
+}
+
+/** A small data file the code itself references — the data the application needs to make sense. */
+export interface SeedRecord {
+  name: string
+  path: string
+  bytes: number
+  format: string
+  rows?: number
+  /** The source files that name it. The proof that it is seed rather than an export. */
+  referencedBy: string[]
+  carried: boolean
+  /** Where it was written in the target, once carried. */
+  target?: string
+}
+
+export interface InventorySummary {
+  root: string
+  files: number
+  bytes: number
+  read: number
+  skipped: number
+  /** A census that hit {@link CENSUS_MAX_ENTRIES}. Everything downstream must say so. */
+  truncated: boolean
+  byClass: Record<FileClass, number>
+  bySize: Record<SizeClass, number>
+  extensions: { ext: string, files: number, bytes: number }[]
+  packages: InventoryPackage[]
+  workspace: WorkspaceReport
+  dumps: DumpRecord[]
+  seeds: SeedRecord[]
+  manifests: string[]
+  vcs: { git: boolean, submodules: number }
+  version: number
+  takenAt: string
+}
+
+/** One data file, classified by the model where the path and the size alone were not enough. */
+export interface SeedDetectionItem {
+  path: string
+  name: string
+  /** Whether it is data the application needs rather than an export of what it produced. */
+  seed: boolean
+  /** Whether it should be carried into the target. */
+  carry: boolean
+  reason: string
+}
+
+export interface SeedDetection {
+  items: SeedDetectionItem[]
+}

package/src/convert/census.ts

@@ -0,0 +1,95 @@
+import { EntropyClass, FileClass, SizeClass, SIZE_CLASS_BOUNDS } from './consts.js'
+import {
+  BINARY_EXTENSIONS, BULK_HINTS, DATA_AMBIGUOUS_EXT, DATA_OVERRIDABLE, EXT_CLASS, GENERATED_SEGMENTS, LOCK_NAMES,
+  MANIFEST_NAMES, SEED_HINTS, TEST_SEGMENTS, TEXT_EXTENSIONS
+} from './census/consts.local.js'
+import type { CensusHelper } from './census/types.js'
+
+export const createCensusHelper = (): CensusHelper => {
+  const sizeClassOf = (bytes: number): SizeClass => {
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Tiny]) return SizeClass.Tiny
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Small]) return SizeClass.Small
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Medium]) return SizeClass.Medium
+    if (bytes < SIZE_CLASS_BOUNDS[SizeClass.Large]) return SizeClass.Large
+
+    return SizeClass.Huge
+  }
+
+  const segmentsOf = (path: string): string[] => path.split('/').filter(part => part !== '')
+
+  const hasSegment = (path: string, of: string[]): boolean =>
+    segmentsOf(path).some(part => of.includes(part.toLowerCase()))
+
+  const fileClassOf = (path: string, ext: string): FileClass => {
+    const lower = path.toLowerCase()
+    const base = segmentsOf(lower).pop() ?? lower
+    const tail = (ext.startsWith('.') ? ext.slice(1) : ext).toLowerCase()
+
+    if (LOCK_NAMES.includes(base)) return FileClass.Lock
+    if (hasSegment(lower, GENERATED_SEGMENTS)) return FileClass.Generated
+    if (MANIFEST_NAMES.includes(base)) return FileClass.Manifest
+    if (hasSegment(lower, TEST_SEGMENTS) || base.includes('.test.') || base.includes('.spec.')) {
+      return FileClass.Test
+    }
+    if (base.startsWith('.env')) return FileClass.Config
+
+    const byExt = EXT_CLASS[tail] ?? FileClass.Unknown
+    if (
+      (DATA_OVERRIDABLE.includes(byExt) || DATA_AMBIGUOUS_EXT.includes(tail))
+      && (isSeedPath(lower) || isBulkPath(lower))
+    ) {
+      return FileClass.Data
+    }
+
+    return byExt
+  }
+
+  const binaryByExtension = (path: string): boolean | null => {
+    const base = segmentsOf(path).pop() ?? path
+    const dot = base.lastIndexOf('.')
+    if (dot < 1) return null
+    const ext = base.slice(dot).toLowerCase()
+
+    return TEXT_EXTENSIONS.includes(ext) ? false : BINARY_EXTENSIONS.includes(ext) ? true : null
+  }
+
+  const entropyClassOf = (head: string): EntropyClass => {
+    if (head.length < 1) return EntropyClass.Text
+
+    let printable = 0
+    let whitespace = 0
+    for (const char of head) {
+      const code = char.codePointAt(0) ?? 0
+      if (code === 9 || code === 10 || code === 13 || code === 32) {
+        ++whitespace
+        ++printable
+      } else if (code >= 32 && code !== 127) {
+        ++printable
+      }
+    }
+
+    const ratio = printable / head.length
+    if (ratio < 0.85) return EntropyClass.Opaque
+    // Prose, code and markup all break lines and indent. A body that does neither is minified,
+    // encoded or packed — printable, and not something a model can reason over.
+    if (whitespace / head.length < 0.05) return EntropyClass.Dense
+
+    return EntropyClass.Text
+  }
+
+  const matchesHint = (path: string, hints: string[]): boolean => {
+    const lower = path.toLowerCase()
+    if (hasSegment(lower, hints)) return true
+    const base = segmentsOf(lower).pop() ?? lower
+
+    return hints.some(hint => base.includes(hint))
+  }
+
+  const isBulkPath = (path: string): boolean => matchesHint(path, BULK_HINTS)
+
+  const isSeedPath = (path: string): boolean => matchesHint(path, SEED_HINTS)
+
+  return { sizeClassOf, fileClassOf, binaryByExtension, entropyClassOf, isBulkPath, isSeedPath }
+}
+
+export const censusHelper = createCensusHelper()

package/src/convert/consts.ts

@@ -14,7 +14,6 @@
  * things at each hop.
  */
 
-import type { StoryKind } from '../ba/consts.js'
 import { HISTORY_FILE, METADATA_DIRS } from '../metadata/consts.js'
 
 /**
@@ -359,15 +358,6 @@ export enum EstimateSlice {
   Fixed = 'fixed',
 }
 
-/**
- * What KIND of story a conversion produced.
- *
- * The analysis half of a conversion produces exactly the two kinds an ordinary initialization
- * does; a conversion adds one more — a `coverage` story, written so an area the origin serves but
- * the flow never reaches still has something in it.
- */
-export type ConversionStoryKind = StoryKind | 'coverage'
-
 /**
  * Where the origin's own sources live inside the target's volume.
  *
@@ -454,10 +444,6 @@ export const CONVERSION_SEED_DIR = `${CONVERSION_DIR}/seed`
 /** The carried seed data itself, beside its description. */
 export const CONVERSION_SEED_DATA_DIR = `${CONVERSION_SEED_DIR}/data`
 
-export const conversionStoryDoc = (code: string): string => `${CONVERSION_STORY_DIR}/${code}.md`
-export const conversionSeedDoc = (name: string): string => `${CONVERSION_SEED_DIR}/${name}.md`
-export const conversionSeedData = (name: string, ext: string): string =>
-  `${CONVERSION_SEED_DATA_DIR}/${name}.${ext}`
 
 /**
  * The two agent-memory nodes a conversion writes into the TARGET's own harness.
@@ -670,3 +656,8 @@ export const CONVERSION_INQUIRY = {
   areasMap: 'convert.areas.map',
   originRelocate: 'convert.origin.relocate',
 } as const
+
+/** 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/detection/types.ts

@@ -0,0 +1,74 @@
+import type { TargetLayout } from '../../integrity/consts.js'
+import type {
+  ArchitectureCase, ConvertibilityReason, ConvertibilityVerdict, OriginShape, StackFamily, StackId
+} from '../consts.js'
+
+/** One piece of evidence for a stack, and how much it counts for. */
+export interface StackSignal {
+  id: StackId
+  weight: number
+  evidence: string
+}
+
+/**
+ * What the pure detector concluded, before any model was asked.
+ *
+ * `confirmed` records whether the ONE model confirmation ran and agreed. `confirmedCase` is what
+ * that same call answered about the architecture — asked together because a model that has just
+ * read the manifests to name a framework has already read everything the case follows from, and
+ * two calls over the same evidence is twice the price for one answer.
+ */
+export interface StackDetection {
+  stack: StackId
+  family: StackFamily
+  alternative?: StackId
+  confidence: number
+  confirmed: boolean
+  confirmedCase?: ArchitectureCase
+  signals: StackSignal[]
+  runtime?: string
+  reason?: string
+}
+
+/** The ONE model confirmation of the detected stack, and the case it implies. */
+export interface StackConfirmation {
+  stack: StackId
+  alternative?: StackId
+  case: ArchitectureCase
+  runtime?: string
+  confidence: number
+  reason: string
+}
+
+/**
+ * What the tree IS, as the integrity manifest sees it.
+ *
+ * `violations` is how far a tree is from being a Viable target: zero means it IS one and the
+ * conversion is a repair, a handful means somebody edited a generated project, and a large number
+ * means it is foreign code that happens to be TypeScript.
+ */
+export interface OriginShapeReport {
+  shape: OriginShape
+  layout?: TargetLayout
+  violations: number
+  evidence: string[]
+}
+
+export interface ArchitectureVerdict {
+  case: ArchitectureCase
+  confidence: number
+  reasons: string[]
+  /** Two cases fit equally well; the user is asked which. */
+  ambiguous: boolean
+  /** The origin has no user interface at all — a case the implementation stage must design one for. */
+  uiGap: boolean
+}
+
+export interface ConvertibilityReport {
+  verdict: ConvertibilityVerdict
+  reasons: ConvertibilityReason[]
+  /** What makes the verdict `Refused`, phrased for a person. */
+  blockers: string[]
+  /** What makes it `Limited` — shown before the user pays for anything. */
+  notes: string[]
+}

package/src/convert/docs/types.ts

@@ -0,0 +1,151 @@
+import type { ProjectArea } from '../../areas/consts.js'
+import type {
+  ArchitectureCase, ConversionStage, ConvertibilityVerdict, OriginKind, PurposeEvidenceSource, StackFamily, StackId
+} from '../consts.js'
+
+/** Where the per-story and per-seed conversion documents live in a target. */
+export interface ConversionDocHelper {
+  /** The restored story document of one story code. */
+  conversionStoryDoc: (code: string) => string
+  /** The description document of one carried seed. */
+  conversionSeedDoc: (name: string) => string
+  /** The carried seed data file itself. */
+  conversionSeedData: (name: string, ext: string) => string
+}
+
+export interface ConversionDocMeta {
+  version: number
+  stage: ConversionStage
+  updatedAt: string
+}
+
+export interface ConversionIndexMeta extends ConversionDocMeta {
+  origin: string
+  originKind: OriginKind
+  stack: StackId
+  case: ArchitectureCase
+  verdict: ConvertibilityVerdict
+  purged: boolean
+}
+
+export interface InventoryDocMeta extends ConversionDocMeta {
+  files: number
+  bytes: number
+  packages: number
+  dumps: number
+  seeds: number
+  truncated: boolean
+}
+
+export interface StackDocMeta extends ConversionDocMeta {
+  stack: StackId
+  family: StackFamily
+  alternative?: StackId
+  confidence: number
+  confirmed: boolean
+}
+
+export interface ArchitectureDocMeta extends ConversionDocMeta {
+  case: ArchitectureCase
+  confidence: number
+  ambiguous: boolean
+  uiGap: boolean
+}
+
+export interface HarnessDocMeta extends ConversionDocMeta {
+  docs: number
+  hasReadme: boolean
+  hasAgents: boolean
+  openapi: boolean
+}
+
+export interface TaxonomyDocMeta extends ConversionDocMeta {
+  case: ArchitectureCase
+  packages: number
+  counts: Record<string, number>
+  deviations: number
+}
+
+export interface PurposeDocMeta extends ConversionDocMeta {
+  source: PurposeEvidenceSource
+  confidence: number
+}
+
+export interface AnalysisDocMeta extends ConversionDocMeta {
+  name: string
+  language: string
+  entities: string[]
+  flowSteps: number
+}
+
+export interface StoryListDocMeta extends ConversionDocMeta {
+  total: number
+  flow: number
+  connective: number
+  coverage: number
+}
+
+export interface StoryProofDocMeta extends ConversionDocMeta {
+  code: string
+  area: ProjectArea
+  origin: string[]
+  complexity: number
+}
+
+export interface EstimateDocMeta extends ConversionDocMeta {
+  stages: ConversionStage[]
+  inputTokens: number
+  outputTokens: number
+}
+
+export interface AssumptionsDocMeta extends ConversionDocMeta {
+  count: number
+}
+
+export interface InquiriesDocMeta extends ConversionDocMeta {
+  asked: number
+  answered: number
+  declined: number
+}
+
+export interface DumpsDocMeta extends ConversionDocMeta {
+  dumps: number
+  bytes: number
+  sampled: number
+}
+
+export interface SeedDocMeta extends ConversionDocMeta {
+  name: string
+  format: string
+  bytes: number
+  rows?: number
+  carried: boolean
+}
+
+export interface AreasDocMeta extends ConversionDocMeta {
+  areas: ProjectArea[]
+  roles: number
+  permissions: number
+}
+
+export interface StructureDocMeta extends ConversionDocMeta {
+  nodes: number
+  edges: number
+}
+
+export interface OriginCardDocMeta extends ConversionDocMeta {
+  chars: number
+  stack: StackId
+  case: ArchitectureCase
+}
+
+/** The frontmatter of the target's own `.agents/memory/conversion.md` node. */
+export interface ConversionMemoryMeta {
+  version: number
+  stage: ConversionStage
+  case: ArchitectureCase
+  stack: StackId
+  origin: string
+  purged: boolean
+  updatedAt: string
+}

package/src/convert/docs.ts

@@ -0,0 +1,15 @@
+import { CONVERSION_SEED_DATA_DIR, CONVERSION_SEED_DIR, CONVERSION_STORY_DIR } from './consts.js'
+import type { ConversionDocHelper } from './docs/types.js'
+
+export const createConversionDocHelper = (): ConversionDocHelper => {
+  const conversionStoryDoc = (code: string): string => `${CONVERSION_STORY_DIR}/${code}.md`
+
+  const conversionSeedDoc = (name: string): string => `${CONVERSION_SEED_DIR}/${name}.md`
+
+  const conversionSeedData = (name: string, ext: string): string =>
+    `${CONVERSION_SEED_DATA_DIR}/${name}.${ext}`
+
+  return { conversionStoryDoc, conversionSeedDoc, conversionSeedData }
+}
+
+export const conversionDocHelper = createConversionDocHelper()

package/src/convert/estimate/types.ts

@@ -0,0 +1,75 @@
+import type { ModelRole } from '../../execution/consts.js'
+import type { ConversionStage, EstimateSlice } from '../consts.js'
+
+/**
+ * One row of a stage's role plan — what the estimator believes a step will spend.
+ *
+ * Data rather than a measurement: the plan says which slices of the origin a step reads, how many
+ * calls it makes and what it writes back, and the estimator projects tokens from the census. A
+ * step that is per-story is multiplied by the story count instead of run once.
+ */
+export interface RolePlanEntry {
+  step: string
+  role: ModelRole
+  slices: EstimateSlice[]
+  /** What share of the named slices this step actually reads. */
+  factor: number
+  calls: number
+  /** Fixed input tokens per call — the persona, the framing, the schema. */
+  overhead: number
+  /** Expected output tokens per call. */
+  output: number
+  perStory?: boolean
+}
+
+export interface RoleEstimate {
+  role: ModelRole
+  calls: number
+  inputTokens: number
+  outputTokens: number
+  steps: string[]
+}
+
+/**
+ * What one stage is expected to cost, as the platform stores it on the conversion record.
+ *
+ * Priced on the agent, where the model presets and the run mode are: a DELEGATED conversion runs
+ * its model calls on the parent agent and costs the platform nothing, so `usd` is zero and
+ * `delegated` says why. `basis` is kept so a user can see what the number was projected from
+ * rather than being handed a figure with no provenance.
+ */
+export interface ConversionEstimate {
+  stage: ConversionStage
+  version: number
+  roles: RoleEstimate[]
+  inputTokens: number
+  outputTokens: number
+  usd: number
+  /** @deprecated Credits are USD at the reference rate now — read `usd`. Kept for records stored before the change. */
+  credits?: number
+  delegated: boolean
+  basis: {
+    files: number
+    bytes: number
+    storyCount?: number
+    sampleRatio: number
+    retryFactor: number
+  }
+  computedAt: string
+}
+
+/**
+ * The per-story band shown before the implementation stage.
+ *
+ * A range, because a story's cost is set by how much code it turns out to need — which is exactly
+ * what nothing knows before it is written. Shown with the disclaimer that says so.
+ */
+export interface StoryEstimateBand {
+  minUsd: number
+  maxUsd: number
+  /** @deprecated Credits are USD at the reference rate now — read `minUsd`. Kept for records stored before the change. */
+  minCredits?: number
+  /** @deprecated Credits are USD at the reference rate now — read `maxUsd`. Kept for records stored before the change. */
+  maxCredits?: number
+  perStory: { code: string, complexity: number, minUsd: number, maxUsd: number }[]
+}

package/src/convert/estimate.ts

@@ -0,0 +1,19 @@
+import type { StoryProof } from './analysis/types.js'
+
+/**
+ * How much work re-implementing a story is, as a multiplier on the per-story price band.
+ *
+ * Derived from what the extraction found, never asked of a model: a story backed by a handful of
+ * proofs and no algorithm is ordinary CRUD, one that carries described algorithms is business
+ * logic somebody has to reproduce. Two runs over the same extraction therefore price identically,
+ * which is the point — a band that moved between two viewings of the same screen would be noise.
+ */
+export const storyComplexity = (proof: Pick<StoryProof, 'proofs' | 'algorithms'>): number => {
+  const proofs = proof.proofs?.length ?? 0
+  const algorithms = proof.algorithms?.length ?? 0
+
+  if (algorithms > 1 || proofs > 8) return 2
+  if (algorithms > 0 || proofs > 3) return 1.5
+
+  return 1
+}