@pathmx/core 0.5.1 → 0.5.2

package/README.md

@@ -55,6 +55,10 @@ const app = await createApp({
 })
 ```
 
+Routes and Source identities are file-based. A Source-level frontmatter `id`
+is ignored and reported as a non-failing `pmx lint` warning. Block-level ids
+remain authorable for stable local targets.
+
 Official packages follow the CLI's release channel:
 
 ```sh

package/cli/lint.ts

@@ -19,7 +19,13 @@ export type InvalidSourceIssue = Readonly<{
   message: string
 }>
 
-export type LintIssue = UnresolvedLinkIssue | InvalidSourceIssue
+export type SourceWarning = Readonly<{
+  type: "source.warning"
+  source: string
+  message: string
+}>
+
+export type LintIssue = UnresolvedLinkIssue | InvalidSourceIssue | SourceWarning
 
 export function collectUnresolved(app: Engine) {
   const issues: UnresolvedLinkIssue[] = []
@@ -37,9 +43,16 @@ export function collectUnresolved(app: Engine) {
 }
 
 function issueKey(issue: LintIssue) {
-  return issue.type === "link.unresolved"
-    ? `${issue.type}\0${issue.source}\0${issue.href}\0${issue.label ?? ""}`
-    : `${issue.type}\0${issue.source}\0${issue.plugin}\0${issue.message}`
+  switch (issue.type) {
+    case "link.unresolved":
+      return `${issue.type}\0${issue.source}\0${issue.href}\0${issue.label ?? ""}`
+    case "source.invalid":
+      return `${issue.type}\0${issue.source}\0${issue.plugin}\0${issue.message}`
+    case "source.warning":
+      return `${issue.type}\0${issue.source}\0${issue.message}`
+    default:
+      return issue satisfies never
+  }
 }
 
 function compareIssues(a: LintIssue, b: LintIssue) {
@@ -60,6 +73,7 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
 
   const links: UnresolvedLinkIssue[] = []
   const authoring: InvalidSourceIssue[] = []
+  const warnings: SourceWarning[] = []
   for (const issue of issues) {
     switch (issue.type) {
       case "link.unresolved":
@@ -68,6 +82,9 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
       case "source.invalid":
         authoring.push(issue)
         break
+      case "source.warning":
+        warnings.push(issue)
+        break
       default:
         issue satisfies never
     }
@@ -89,9 +106,24 @@ export function formatLintIssues(issues: readonly LintIssue[]) {
       ].join("\n"),
     )
   }
+  if (warnings.length) {
+    sections.push(
+      [
+        pc.bold(`Warnings (${warnings.length})`),
+        ...warnings.map((issue) => `${issue.source}: ${issue.message}`),
+      ].join("\n"),
+    )
+  }
 
-  const noun = issues.length === 1 ? "issue" : "issues"
-  sections.push(pc.red(`${issues.length} ${noun} found`))
+  const failureCount = links.length + authoring.length
+  if (failureCount) {
+    const noun = failureCount === 1 ? "issue" : "issues"
+    sections.push(pc.red(`${failureCount} ${noun} found`))
+  }
+  if (warnings.length) {
+    const noun = warnings.length === 1 ? "warning" : "warnings"
+    sections.push(pc.yellow(`${warnings.length} ${noun} found`))
+  }
   return sections.join("\n\n")
 }
 
@@ -114,6 +146,15 @@ export async function collectLintIssues(app: Engine) {
     addDiagnostic(diagnostic)
   }
   for (const source of app.repo.all()) {
+    if (Object.hasOwn(source.data, "id")) {
+      const warning: SourceWarning = {
+        type: "source.warning",
+        source: source.path,
+        message:
+          'Source frontmatter "id" is ignored; Source ids are derived from file paths. Remove this field.',
+      }
+      issues.set(issueKey(warning), warning)
+    }
     if (!app.isPage(source)) continue
     try {
       await app.compilePage(source)
@@ -155,8 +196,9 @@ export function registerLint(program: Command) {
         })
         const issues = await collectLintIssues(app)
         console.log(formatLintIssues(issues))
-        if (!issues.length) return
-        process.exitCode = 1
+        if (issues.some((issue) => issue.type !== "source.warning")) {
+          process.exitCode = 1
+        }
       } catch (error) {
         fail(error)
       }

package/cli/update.ts

@@ -35,15 +35,52 @@ export async function availableRelease(
 }
 
 async function installRelease(spec: string) {
-  const child = Bun.spawn([process.execPath, "add", "--global", spec], {
+  const child = Bun.spawn(
+    [process.execPath, "add", "--global", "--exact", spec],
+    {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+    },
+  )
+  return child.exited
+}
+
+export function globalPackageVersion(output: string, packageName: string) {
+  const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
+  return output.match(new RegExp(`${escaped}@([^\\s]+)`))?.[1]
+}
+
+async function installedGlobalVersion() {
+  const child = Bun.spawn([process.execPath, "pm", "ls", "--global"], {
     stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
+    stdout: "pipe",
+    stderr: "pipe",
   })
-  const exitCode = await child.exited
+  const [stdout, exitCode] = await Promise.all([
+    new Response(child.stdout).text(),
+    child.exited,
+  ])
+  if (exitCode !== 0) return
+  return globalPackageVersion(stdout, release.package)
+}
+
+type InstallRelease = (spec: string) => Promise<number>
+type InstalledVersion = () => Promise<string | undefined>
+
+export async function installCheckedRelease(
+  spec: string,
+  expected: string,
+  install: InstallRelease = installRelease,
+  installed: InstalledVersion = installedGlobalVersion,
+) {
+  const exitCode = await install(spec)
   if (exitCode !== 0) {
+    if ((await installed()) === expected)
+      return { type: "installed-with-warning" as const, exitCode }
     throw new Error(`Bun could not install ${spec} (exit ${exitCode}).`)
   }
+  return { type: "installed" as const }
 }
 
 export function registerUpdate(program: Command) {
@@ -70,7 +107,12 @@ export function registerUpdate(program: Command) {
       console.log(
         `Updating ${release.package} ${release.version} → ${available}`,
       )
-      await installRelease(releaseSpec())
+      const result = await installCheckedRelease(releaseSpec(), available)
+      if (result.type === "installed-with-warning") {
+        console.warn(
+          `warning: Bun exited with ${result.exitCode}, but ${release.package}@${available} was installed. Check your Bun global package manifest for an unrelated invalid dependency.`,
+        )
+      }
       console.log(
         `PathMX ${available} installed. Run \`pathmx --version\` to verify.`,
       )

package/environments/bun.ts

@@ -15,6 +15,7 @@ import type {
   HtmlRewrite,
   PathMXEnvironment,
 } from "../environment.ts"
+import { isAuthoredStoragePath } from "../storage-path.ts"
 
 export { publishToDirectory, writePublication } from "./bun-publish.ts"
 
@@ -201,9 +202,10 @@ export const bunEnvironment: PathMXEnvironment = {
     stringify: (value) => YAML.stringify(value, null, 2),
   },
   storage: {
-    list: (root) => [
-      ...new Bun.Glob("**/*").scanSync({ cwd: root, onlyFiles: true }),
-    ],
+    list: (root) =>
+      [
+        ...new Bun.Glob("**/*").scanSync({ cwd: root, onlyFiles: true }),
+      ].filter(isAuthoredStoragePath),
     readText: (path) => Bun.file(path).text(),
     readBlob: (path) => Bun.file(path),
     writeText: async (path, content) => {

package/host/engine.ts

@@ -434,6 +434,13 @@ export class Engine {
       "index.source",
       () => {
         this.forgetNode(source.path)
+        if (Object.hasOwn(source.data, "id")) {
+          this.log.warn("source.id.ignored", {
+            source: source.path,
+            message:
+              'Source frontmatter "id" is ignored; Source ids are derived from file paths.',
+          })
+        }
         this.compiler.indexSource(source)
         this.authorityErrors.delete(source.id)
         const capture = (error: unknown) => {

package/ops/href.ts

@@ -23,16 +23,6 @@ export function isRelativeHref(pathname: string) {
   )
 }
 
-export function authoredId(source: Source) {
-  const id = source.data.id
-  return typeof id === "string" && id.trim() ? id.trim() : undefined
-}
-
-export function isAuthoredIdHref(pathname: string, source: Source) {
-  const id = authoredId(source)
-  return Boolean(id && (pathname === id || pathname === `/${id}`))
-}
-
 export function relativeHref(
   fromPath: string,
   targetPath: string,
@@ -75,7 +65,6 @@ export function retargetHref(
 ): string | undefined {
   const { pathname, query, fragment } = splitHref(href)
   if (!pathname) return
-  if (isAuthoredIdHref(pathname, oldSource)) return
 
   const explicitMd = pathname.endsWith(".md")
   const target = explicitMd ? newSource.path : publicPath(newSource)

package/ops/move-source.ts

@@ -3,7 +3,6 @@ import { posixPath } from "../path.ts"
 import { isIndexSource, publicPath } from "../server/router.ts"
 import { createSource, rewriteLinks, type Source } from "../source/index.ts"
 import {
-  authoredId,
   isRelativeHref,
   rebaseRelativeHref,
   retargetHref,
@@ -104,9 +103,12 @@ export async function moveSource(
       `Moving index source ${source.path} changes the directory route ${publicPath(source)}`,
     )
   }
-  if (!authoredId(source) && source.id !== preview.id) {
+  if (
+    !isIndexSource(source) &&
+    publicPath(source) !== publicPath(preview)
+  ) {
     plan.warnings.push(
-      `Moving ${source.path} changes its public URL from ${source.id} to ${preview.id}`,
+      `Moving ${source.path} changes its public URL from ${publicPath(source)} to ${publicPath(preview)}`,
     )
   }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pathmx/core",
   "description": "A minimal, plugin-first framework for Paths and learning applications.",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "license": "SEE LICENSE IN LICENSE.md",
   "repository": {
     "type": "git",

package/server/watch.ts

@@ -3,6 +3,7 @@ import { realpathSync } from "node:fs"
 import { relative } from "node:path"
 import type { Engine } from "../host/engine.ts"
 import { SourceDiagnosticError } from "../source-diagnostic.ts"
+import { isAuthoredStoragePath } from "../storage-path.ts"
 import { CssImportIndex } from "./css-imports.ts"
 
 type UnresolvedLink = {
@@ -91,7 +92,13 @@ export function watchPaths(app: Engine, root: string) {
         const changedStyles = new Set<string>()
         for (const event of events) {
           const rel = relative(base, event.path)
-          if (!rel || rel.startsWith("..")) continue
+          if (
+            !rel ||
+            rel.startsWith("..") ||
+            !isAuthoredStoragePath(rel)
+          ) {
+            continue
+          }
           app.log.debug("watch", { file: rel, type: event.type })
           if (rel.endsWith(".md")) await app.syncFromStorage(rel)
           else if (rel.endsWith(".css")) {

package/source/source.ts

@@ -49,7 +49,6 @@ export function sourceIdFromPath(path: string, type = DEFAULT_SOURCE_TYPE) {
 }
 
 export function resolveSourceId(path: string, data: Topmatter) {
-  if (typeof data.id === "string" && data.id.trim()) return data.id.trim()
   const type =
     typeof data.type === "string" && data.type.trim()
       ? data.type.trim()

package/storage-path.ts

@@ -0,0 +1,8 @@
+const CONTROL_DIRECTORIES = new Set([".git", ".pathmx", "node_modules"])
+
+/** True when a storage-relative path belongs to authored project content. */
+export function isAuthoredStoragePath(path: string) {
+  return path
+    .split(/[\\/]/)
+    .every((segment) => !CONTROL_DIRECTORIES.has(segment))
+}