@astryxdesign/cli 0.6.3-canary.c82ebb8 → 0.6.3-canary.ca632c6

package/README.md

@@ -189,6 +189,8 @@ if (isError(result)) {
 | `ERR_UNKNOWN_FEATURE`             | An unrecognized `--features` value was passed to init.                                                                                                   |
 | `ERR_UNKNOWN_CODEMOD`             | A `--codemod` value did not match any registered codemod (upgrade).                                                                                      |
 | `ERR_CODEMOD_FAILED`              | One or more codemods failed during an upgrade run.                                                                                                       |
+| `ERR_CODEMOD_PROTECTED`           | A required codemod change remains blocked by a protected consumer file.                                                                                  |
+| `ERR_CODEMOD_PROTECTION_SOURCE`   | A working-tree protection declaration could not be read or parsed.                                                                                       |
 | `ERR_NOT_FOUND`                   | A generic discover/lookup query matched nothing in any package.                                                                                          |
 | `ERR_NO_DOC`                      | A component exists but has no typed `.doc.mjs` file.                                                                                                     |
 | `ERR_NO_SHOWCASE`                 | No showcase exists for the requested component.                                                                                                          |

package/api/docs/detail/section/section.mjs

@@ -4,9 +4,9 @@
  * @file docs.detail.section leaf — load a single section of a topic.
  *
  * @input A topic name, a section query, and optional {lang, zh, dense}. Resolves
- *   the topic via the shared adapter, finds the section in its lowered compiled
- *   node by its stable key, then by exact title, then by a title that contains
- *   the query, and links only that section.
+ *   the topic via the shared adapter, keeps the 0.6.x first title-substring
+ *   match, then falls back to a stable key or normalized title key, and links
+ *   only that section.
  * @output { type: 'docs.detail.section', data: ReferenceSection } with any
  *   token-ref blocks inlined — matching `astryx --json docs <topic> <section>`.
  *   Throws ERR_UNKNOWN_SECTION when nothing matches, or when the query matches
@@ -17,10 +17,7 @@
 
 import {AstryxError} from '../../../error.mjs';
 import {ERROR_CODES} from '../../../../foundation/response/error-codes.mjs';
-import {
-  findDocSection,
-  sectionKey,
-} from '../../../../foundation/discovery/docs-section-key.mjs';
+import {findDocSection} from '../../../../foundation/discovery/docs-section-key.mjs';
 import {linkReferenceSection} from '../../../../foundation/doc-compiler/compile.mjs';
 import {
   readerSections,
@@ -52,16 +49,13 @@ export async function section(topic, sectionName, options = {}) {
 
   const {catalog, node, lang} = await resolveTopicDocs(topic, options);
   const sections = readerSections(node);
-  const {section: match, candidates} = findDocSection(sections, sectionName);
+  const {section: match} = findDocSection(sections, sectionName);
   if (!match) {
-    const ambiguous = candidates.length > 1;
     throw new AstryxError(
-      ambiguous
-        ? `Section "${sectionName}" matches ${candidates.length} sections in "${topic}". Read one by its key.`
-        : `Section "${sectionName}" not found in "${topic}"`,
-      (ambiguous ? candidates : sections).map(s => ({
-        name: sectionKey(s),
-        reason: s.title,
+      `Section "${sectionName}" not found in "${topic}"`,
+      sections.map(s => ({
+        name: s.title,
+        reason: 'available section',
       })),
       ERROR_CODES.ERR_UNKNOWN_SECTION,
     );

package/api/docs/detail/section/section.test.mjs

@@ -30,6 +30,17 @@ describe('docs.detail.section leaf', () => {
     }
     expect(err).toBeInstanceOf(AstryxError);
     expect(err.code).toBe('ERR_UNKNOWN_SECTION');
+    expect(err.suggestions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          name: expect.any(String),
+          reason: 'available section',
+        }),
+      ]),
+    );
+    expect(err.suggestions.some(suggestion => /\s/u.test(suggestion.name))).toBe(
+      true,
+    );
   }, SLOW);
 
   it('does not return the first section for an empty section name', async () => {
@@ -50,12 +61,10 @@ describe('docs.detail.section leaf', () => {
     expect(res.data.id).toBe(target.id);
   }, SLOW);
 
-  it('refuses a query that matches more than one section', async () => {
-    const err = await section('theme', 'e').catch(e => e);
-    expect(err).toBeInstanceOf(AstryxError);
-    expect(err.code).toBe('ERR_UNKNOWN_SECTION');
-    expect(err.message).toMatch(/matches \d+ sections/);
-    expect(err.suggestions.length).toBeGreaterThan(1);
+  it('keeps a previously accepted ambiguous query on its first match', async () => {
+    const res = await section('theme', 'e');
+    expect(res.type).toBe('docs.detail.section');
+    expect(res.data).toBeDefined();
   }, SLOW);
 
   it.each([null, 'zh', 'dense'])(

package/api/doctor/doctor.mjs

@@ -994,7 +994,7 @@ export async function checkDocsProgressiveDisclosure(ctx) {
     return {
       id,
       label,
-      status: 'fail',
+      status: 'warn',
       message: joinProblems(problems),
       fix: 'Fix the doc each problem names; split a section that is too large into smaller ones, each with its own key.',
     };

package/api/doctor/doctor.test.mjs

@@ -391,7 +391,7 @@ describe('checkDocsProgressiveDisclosure', () => {
     expect(c.message).toMatch(/^\d+ topics: /);
   }, SLOW);
 
-  it('fails on an invalid doc an integration contributed', async () => {
+  it('warns on an invalid doc an integration contributed', async () => {
     const c = await checkDocsProgressiveDisclosure({
       docsCatalogIssues: [
         {
@@ -402,13 +402,13 @@ describe('checkDocsProgressiveDisclosure', () => {
         },
       ],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toBe('@acme/widgets: bad.doc.mjs exports no doc');
   });
 
-  it('fails when the docs catalog cannot be built', async () => {
+  it('warns when the docs catalog cannot be built', async () => {
     const c = await checkDocsProgressiveDisclosure({docsCatalogError: 'boom'});
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toContain('boom');
   });
 
@@ -436,7 +436,7 @@ describe('checkDocsProgressiveDisclosure', () => {
       }),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toMatch(/^2 problems: /);
     expect(c.message).toContain('huge everything: 41 KB, over the 32 KB one read may return');
     expect(c.message).toContain('broken: ');
@@ -812,7 +812,7 @@ describe('checkDocsProgressiveDisclosure languages', () => {
       docsCatalog: DocsCatalog.fromBuiltins({deploying: path.join(dir, 'deploying.doc.mjs')}),
       docsCatalogIssues: [],
     });
-    expect(c.status).toBe('fail');
+    expect(c.status).toBe('warn');
     expect(c.message).toContain('deploying [zh]: zh overlay broken');
     expect(c.message).toContain('deploying [dense] overview: 41 KB');
     expect(c.message).not.toMatch(/deploying overview:/);

package/api/upgrade/_adapter.d.mts

@@ -104,19 +104,27 @@ export function ensureCodemodDeps({ installDeps }?: {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
-export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root }: {
+export function runCoreCodemods(versionManifests: CoreVersionManifest[], { apply, path: srcPath, codemod, skipCodemods, root, protection, silent }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
     root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
     totalValidationBlocked: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;
@@ -180,20 +188,30 @@ export function selectIntegrationCodemodsFor(integrations: Array<import("../../f
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
 export function runIntegrationCodemodsStep(versionGroups: Array<{
     version: string;
     codemods: import("../../authoring/codemod/type").CodemodEntry[];
-}>, { apply, path: srcPath, codemod, skipCodemods }: {
+}>, { apply, path: srcPath, codemod, skipCodemods, root, protection, contents, silent, }: {
     apply: boolean;
     path: string;
     codemod?: string;
     skipCodemods: Set<string>;
+    root?: string;
+    protection?: {
+        root: string;
+        classify: (file: string) => import("../../foundation/fs/file-protection.mjs").FileProtection[];
+    };
+    contents?: Map<string, string>;
+    silent?: boolean;
 }): Promise<{
     totalFilesChanged: number;
     totalTransformsApplied: number;
+    changedFiles: string[];
     writtenFiles: string[];
+    stagedContents: Map<string, string>;
+    protectedFiles: import("../../authoring/codemod/type").CodemodRunResult["protectedFiles"];
     errors: Array<{
         file: string;
         codemod: string;

package/api/upgrade/_adapter.mjs

@@ -329,19 +329,20 @@ export async function ensureCodemodDeps({installDeps} = {}) {
  * Run the CORE registry codemods. Runs BEFORE the config is loaded so a core
  * CONFIG codemod can repair a config the strict loader would otherwise reject.
  * @param {CoreVersionManifest[]} versionManifests
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, silent?: boolean}} options
  */
 export async function runCoreCodemods(
   versionManifests,
-  {apply, path: srcPath, codemod, skipCodemods, root},
+  {apply, path: srcPath, codemod, skipCodemods, root, protection, silent},
 ) {
   return runCodemods(versionManifests, {
     apply,
     path: srcPath,
     codemod,
     skipCodemods,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
     root,
+    protection,
   });
 }
 
@@ -479,11 +480,20 @@ export async function selectIntegrationCodemodsFor(integrations, from, to) {
 /**
  * Run the file-based INTEGRATION codemods (config codemods first, then code).
  * @param {Array<{version: string, codemods: import('../../authoring/codemod/type').CodemodEntry[]}>} versionGroups
- * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>}} options
+ * @param {{apply: boolean, path: string, codemod?: string, skipCodemods: Set<string>, root?: string, protection?: {root: string, classify: (file: string) => import('../../foundation/fs/file-protection.mjs').FileProtection[]}, contents?: Map<string, string>, silent?: boolean}} options
  */
 export async function runIntegrationCodemodsStep(
   versionGroups,
-  {apply, path: srcPath, codemod, skipCodemods},
+  {
+    apply,
+    path: srcPath,
+    codemod,
+    skipCodemods,
+    root,
+    protection,
+    contents,
+    silent,
+  },
 ) {
   const jscodeshift = (await import('jscodeshift')).default;
   return runIntegrationCodemods(versionGroups, {
@@ -492,6 +502,9 @@ export async function runIntegrationCodemodsStep(
     codemod,
     skipCodemods,
     jscodeshift,
-    silent: logger.silent,
+    silent: silent ?? logger.silent,
+    root,
+    protection,
+    contents,
   });
 }